Skip to main content

Pi Topics

These sections cover many of the unique or special tools that the Pi App Platform offers to developers. Also covered are the blockchain topics that a developer should be familiar with.

Pi Mainnet vs Pi Testnet​

Pi Mainnet​

The Pi Mainnet is a blockchain developed by Pi Network in which Pi is the native cryptocurrency. The mining mechanism that widely distributes the Pi cryptocurrency requires Pioneers to make many diverse forms of contributions to the network’s growth, security, utilities creation, decentralization, stability, and longevity, by which Pi is first deposited in the Pioneers’ mobile Pi accounts. The migration of these Pioneers’ Pi balances from their mobile Pi account to their Mainnet wallet started in June 2022 when the network passed one million KYC-verified Pioneers. KYC authentication of a Pioneer through a native, decentralized Pi KYC app precedes their balance migration to the Mainnet. In order to allow for sufficient time for millions of Pioneers to successfully complete their KYC verification and the subsequent Mainnet migration, create utilities in the Pi ecosystem, and the network’s continued efforts to iterate on the Pi ecosystem design, the Mainnet phase of the Roadmap has two periods as summarized below. For more details, please refer to the updated Roadmap chapter draft linked here

Firewalled Mainnet (i.e., the Enclosed Network), Open Mainnet (i.e., the Open Network).

Enclosed Network Period​

This period began on December 28, 2021 when the Pi Mainnet blockchain launched. The Enclosed Network period means that the Mainnet is live but with a firewall that prevents any unwanted external connectivity. KYC’ed Pioneers will be able to use their Pi on the Mainnet freely in an enclosed environment within Pi Network. Pi apps will be able to switch from Testnet to Mainnet—to production mode for real Pi transactions. However, this period will not allow connectivity between the Pi blockchain and other blockchains.

The Enclosed Network allows the Mainnet to run with production data and real Pi, which differs from Testnet. Data gathered during the Enclosed Network will help calibrate and tweak any configurations and formulae, if necessary, to ensure a stable and successful Open Network.

Restrictions in the Enclosed Network Period​

While transactions between Pi apps and Pioneers, and Pioneer-to-Pioneer, are allowed within Pi Network, the Enclosed Network will have in place the restrictions as listed below. These restrictions at this stage help enforce the enclosed nature of the network:

There will be no connectivity between Pi and other blockchains or crypto exchanges. Mainnet can only be accessed through the Pi Wallet and Pi apps on the Pi Browser. The Mainnet blockchain will be accessible to any computer on the internet but only through a firewall to enforce the above rules. There will only be Core Team Nodes on the Mainnet to ensure that the firewall is in place at all times.

The Enclosed Network will support the growth of the Pi ecosystem. Thus, Pioneer-to-Pioneer transactions are possible through the Pi Wallet as KYC’ed Pioneers will be able to use the Pi Wallet to transact in Pi. Pioneers can also spend Pi in Pi apps on the Pi Browser, which can access the Mainnet through the Pi Apps SDK and the Pi Blockchain API. During the Enclosed Network period, an app on the Pi Browser can only use the Pi blockchain APIs whitelisted by the firewall to interact with the Mainnet.

The following uses of Pioneer-to-Pioneer, Pioneer-to-App, and App-to-Pioneer transactions will be allowed:

  • Exchange of Pi for goods and services through Pi Apps
  • Transfer of Pi between Pioneers for goods and services

The following uses will be prohibited:

  • Exchange of Pi for fiat currency
  • Exchange of Pi for other cryptocurrencies
  • Transfer for Pi for a future promise of fiat or other cryptocurrencies

We will enforce the above restrictions by adding a firewall to the Mainnet and by exclusively running the Mainnet Nodes for this interim period. Community Nodes will continue to run on the Testnet in the Enclosed Network period. We will continue to implement interface and other changes to the Nodes in preparation for the Open Network period where the Community Nodes will be able to run on the Mainnet. The restrictions of the Network to keep it enclosed will be relaxed as it reaches the next period—Open Network.

Open Network Period​

The launch of the Open Network Period depends on the maturity of the Enclosed Network ecosystem and the progress of KYC. The Open Network period means that the firewall in the Enclosed Network period will be removed, allowing any external connectivity, e.g., to other networks, wallets, and anyone who wants to connect to Pi Mainnet. API calls will not be firewalled, and Pioneers will be able to run their own Pi Nodes and API services. Pioneers will have connectivity with other blockchains. Community Nodes can also run the Mainnet.

Pi Testnet​

Pi Testnet allows for the testing of connectivity, performance, security, and scalability of the blockchain, and allows Pi app developers to develop the Pi apps before they deploy their app on the Pi Mainnet. Blockchain transactions are irreversible and cannot be refunded; therefore, it is important to have a place for developers and Pioneers to test transactions in a risk-free environment. The Pi Testnet is meant to mimic but is not a fork of the Pi Mainnet and the two blockchains may not be identical at a given point in time.

The Pi Testnet uses Test Pi (or test-π), which is NOT REAL Pi. Test Pi is solely for the purpose of testing transactions on the Pi Testnet and contains NO VALUE. There is a faucet on the Pi Testnet that distributes Test Pi. If your wallet is running low on Test Pi, more can be requested. The Test-Pi balance in the wallet may be reset because Testnet will be periodically reset as part of the testing.

Sandbox (Local Environment)​

The Sandbox is a local testing environment that utilizes the Pi Testnet and a local instance of your app. This is for testing purposes only and should only be used during development. In order to use this feature, you must have a URL registered within the Developer Portal page of your app.

To learn how to utilize the Sandbox and get it set up, go to the Pi SDK page and see the section titled “The Sandbox Flag.”

Pi Wallet​

The Pi Wallet can be utilized on both the Pi Mainnet and Pi Testnet. See the Pi Wallet page to learn more about the wallet. Instructions to switch between networks within the Pi Wallet are available on this page.

Access Token​

The access token is a long random string that uniquely identifies a Pioneer within an app. The Access Token is the identifier that Applications use to communicate with the Pi Servers about a Pioneer. The Access Token is designed to protect the Pioneer’s information from unapproved access. This page assumes that you’ve read the Pi SDK page and have an understanding of how the Pi SDK and the Authenticate function work.

Obtaining the Access Token​

The Access Token is received by calling the Authenticate function of the Pi SDK. No specific scope is required to obtain Access Token as it will come included in all calls to the Authenticate Function.

The authenticate() Function call will return an Access Token as a promise object in the format below:

  AuthResults{
    accessToken: string,
    user: {
      uid: string,
    }
  }

Security Note: Do not save or use the accessToken or uid obtained in the Authentication call for purposes other than for display purposes because a malicious actor could pass a forged or corrupt access token. Instead pass the accessToken to your server side and verify it with the /me endpoint of the Pi App Platform APIs. Calling that API will be detailed later on.

The Access Token is a dynamic string and will change at preset time intervals. Apps should not use the access token to create records or store information about a Pioneer. Instead, Apps should verify the access token which returns the correct uid of the Pioneer. To authenticate an access token, the App should pass the access token from its Frontend to its server side, and then call the Pi API /me endpoint.

The uid is a static string which uniquely identifies a Pioneer to an app. The uid that comes with the Authenticate function is unverified and should be treated as not valid. Only the uid received from the /me endpoint of the Pi Platform APIs should be considered valid.

Verifying the Access Token​

Once the App has the Access token in its backend, then it should call the /me endpoint of the Platform APIs. This call will return the UserDTO with the uid and the username. If the access token is not valid for any reason, the call will return a 401 error.

The first step to call the Pi API is to create the Authorization Header that is needed. A Bearer header is combined with the Access Token to validate the call.

Authorization: Bearer <Pioneer's access token obtained from App Frontend>

The /me endpoint will return either the UserDTO, if the Access Token was valid, or a 401 Error Code if the token was fake or invalid. The returned UserDTO will look as follows:

Object{
  user: {
    uid: string,
    username: string ,
  }
}

The returned uid is static, and since it comes from the /me endpoint, it is the correct uid for the Pioneer and your App. Check out the next section for potential uses of the uid.

Using The uid Within Your App​

Create Unique Database Records​

Using the verified uid which is obtained from the /me Pi Platform API endpoint, the app can create a unique record for each Pioneer within its DB. The uid is static and will not change; however, it is important to not use the uid that is returned by the Pi Platform SDK Authenticate function because it is not verified. Once the record is created using the uid, then it can be used to store any usage information such as purchases, progress within a game, etc.

No Pioneer Sign-In Required​

Everytime a Pioneer visits the app, the Pi Platform SDK Authenticate function will be called. This will return the Access Token, which needs to be verified. Once that token is verified the uid can be used to locate the Pioneer’s record within the app’s Database, which enables the app to personalize the Pioneer’s experience.

For example, you have an app that offers videos that require purchase. Upon visiting the site within the Pi Browser, the Pioneer is first presented with a loading screen. Within a few seconds, when the app has received and verified the access token, then the homepage can load. Using the uid, the app now displays to the Pioneer all of the videos that they’ve purchased in the past. Included the uid is the username that can be displayed in a custom header on the app homepage so the Pioneer knows they are accessing their account. In addition, the app could use the Pioneer’s purchase history to recommend new videos. This is all done without the Pioneer signing in or remembering any passwords, making for a seamless user experience.

Pi Net​

Is a platform that allows anyone to browse, view and share select Pi Apps on any browser of their choice and on any device, bridging the gap between the Web2 and Web3 world and improving accessibility to the Pi ecosystem for Pioneers and non-Pioneers alike.

What Is PiNet​

For developers, share and show your app through PiNet to onboard non-Pioneer users to your app. Nearly any Mainnet Ecosystem app found on the Pi Browser now has the potential to be accessible on Chrome, Safari, Brave, and any other conventional internet browser that conforms to the standard http protocol.

PiNet achieves this by giving Pi applications a unique URL which can be accessed by anyone through PiNet in the Browser of their choice.

To Create a PiNet URL​

There are a few steps that need completed in order to register for and allow users to start using your application through a PiNet URL.

To be eligible to register for a PiNet URL the application must be listed in the Ecosystem App.

  1. The application needs to register for a PiNet subdomain within the Developer Portal.

  2. On the Application Checklist in the Developer Portal there is a step for adding a “PiNet Subdomain”

    • Complete this field with the subdomain that is desired by the application for Pioneers to access the application.
    • Use a subdomain of the previously Verified App Domain
    • A random 4-5 digit number will be added to the URL in order to prevent Domain Squatting. In the future, it may be possible to drop the numbers * Example:
    • Subdomain - AppExample.com
    • PiNet URL - AppExample12345.pinet.com * All URLs must comply with the Pi Trademark Guidelines

  3. At this stage the application is ready to start sharing its PiNet URL with users.

PiNet User Flow​

While the PiNet user may view Pi apps without logging into their Pi account, the user will be blocked from the application at the point in the application where the Pi SDK is required for interaction. This means that once the application invokes Pi.authenticate the user’s experience will end. They will need to either access the application from the Pi Browser and, if they don’t already have an account, they will need to create one, in order to continue experiencing the application.

  • For example, when designing Fireside Forum, the application was built so that those visiting from the PiNet URL can click on and view posts and comments. A user, however, is required to use the Pi-Browser if they want to create a post or add any fire. These actions require the user to log into the Fireside Forum application and submit a transaction.
  • Other examples are:
    • Marketplace apps could allow PiNet URLs to view offerings but require Pi Account to make a purchase
    • Games could allow a user to complete a tutorial, to see the game, prior to requiring the user to authenticate.
  • Applications that invoke the Pi.Authenticate method of the Pi SDK, when a user first visits the app, will need to restructure their applications’ user flow to allow for users to visit without initially requiring Pi account authentication
    • Applications that utilize a landing page which blocks access to the app from outside of the Pi Browser will be unable to use PiNet until this landing page is removed or refactored.

Chat Rooms for Community Apps​

One goal of Pi is to create a seamless experience for users and developers. Developers need a way to connect with Pioneers and chat with them to get valuable feedback, learn what their users want, and grow app use. As a response to Developers’ requests and to support this need, Developers of approved applications have the ability to connect with Pioneers by opening a Public Chat Room in the Pi Chats.

What Are They​

For ease of use, each app-specific chat room will look and feel like a more general Pi Chat Room. However the moderation of these chat rooms will be executed by the Application Team themselves. In addition all chat rooms will be publicly searchable so Pioneers can find your chat room easily.

Eligibility​

To be eligible to open a chat room, an application must meet certain key requirements.

The application must:

  • Be listed in the Ecosystem Application (Testnet or Mainnet)
  • Abide by the developers Terms of Service
  • Maintain active moderation that adheres to the Pi Terms of Service.

Moderation​

To accommodate the app-specific chat rooms, Community Apps will establish application teams themselves to maintain the moderation within their Pi Chat Room.

While the Pi Core Team will support the developers in their chat rooms with some moderation tools, all messages and moderation must adhere to the following guidelines:

As chat rooms within Pi Network, we expect developers to maintain the standards of their community chat rooms, while applying their personal leadership and knowledge to maintain and support their users.

In addition to their own work, developer moderators will be supported with Pi Networks’ Auto-Moderation Tools, which will be enabled on all channels. These tools will automatically delete messages that contain certain banned words and unapproved links.

These Auto-Moderation tools are designed to help developer moderators be more efficient and more confident in running their channels free from spam, scams and abuse.

Creating a Chat Room​

Once an application is listed in the Ecosystem, the eligible app will receive a button “Create Chat Room” on the Developer Portal App Dashboard. Clicking on this button will begin the process to create your app’s chat room.

Next complete the required onboarding steps:

  • Create a New Chat Room: The conversation name, the visibility of the app (Public), and the number of mining sessions a user must have completed in order to post in the conversation. This information is currently pre-filled with the possibility that it becomes editable in the future.
  • Moderation Tools: This is a general overview of the Pi Core Team provided auto-moderation tools
  • Permission Settings: This step will allow you to add members to your team to help moderate the content in the chat room. After chat room creation, permissions can only be changed from within the chat room itself.
  • Terms of Service: Read and agree to the Terms and Service

After Initial Chat Room Creation​

  • Add a Representative: chat room creators can go to the PiChat app, have your Representative post a message, and then tap and hold on their message to change their permissions.
  • Remove a Representative: Chat room creators have a “Manage Chat Representatives” feature, accessed by clicking on the settings icon, on the feature page a chat room creator can see all of the current representative and remove representatives.

Cost​

With these chat rooms, developers will be better able to interface directly with users, creating their own environments to better deliver and improve utilities for Pioneers around the world.

We’re currently offering this feature as a free room for developers to connect with their community of users. Future iterations may include Pi payments to help developers create preferential chat rooms and balance system costs.

Pi Payments​

This section covers all the relevant topics on creating, receiving, and sending payments of various types utilizing the Pi SDK. Pioneers utilize the Pi Wallet within Pi Browser and all documentation is related to the functionality associated with the Pi Wallet. Currently, Pioneer-to-App is the only payment method supported by the Pi SDK. Coming soon will be App-to-Pioneer payments and Pioneer-to-Pioneer payments initiated by an App.