🪙 Pi Network Token Minting Guide & Automation Toolkit

A complete, production-ready guide and automation script suite to create, mint, and list custom tokens on the Pi Network (Testnet & Mainnet).

---

📋 Table of Contents

• Overview
• How Tokens Work on Pi Network
• Prerequisites
• Project Setup
• Environment Configuration (.env)
• Step-by-Step Minting Workflow
  • Step 1: Install Dependencies
  • Step 2: Mint Tokens
  • Step 3: Verify Balances
  • Step 4: Set Home Domain (For Pi Wallet Listing)
  • Step 5: Host pi.toml Metadata
• Testnet vs Mainnet Comparison
• Security & Production Best Practices
• Troubleshooting & FAQs

---

💡 Overview

Pi Network's blockchain is built upon the Stellar Consensus Protocol (SCP). Unlike EVM blockchains (which use smart contracts like ERC-20), Pi Network tokens are native custom assets created through cryptographic trustlines and direct payment operations.

This repository provides ready-to-use scripts to:

1. Automatically establish a Trustline on the Distributor wallet.
2. Mint tokens by executing a payment operation from the Issuer to the Distributor wallet.
3. Link your official Home Domain to the Issuer account on-chain.
4. Provide standard pi.toml metadata templates for official Pi Wallet listing.

---

⚙️ How Tokens Work on Pi Network

sequenceDiagram
    autonumber
    actor Dev as Developer / Admin
    participant Dist as Distributor Wallet
    participant PiBC as Pi Blockchain (Horizon)
    participant Iss as Issuer Wallet
    participant Web as Web Server (Domain)

    Dev->>Dist: 1. Sign & Submit ChangeTrust Tx (Establish Trustline)
    Dist->>PiBC: Register Trustline for Asset (e.g. RB)
    PiBC-->>Dist: Asset registered on-chain
    
    Dev->>Iss: 2. Sign & Submit Payment Tx (Mint Amount)
    Iss->>PiBC: Send custom tokens to Distributor
    PiBC-->>Dist: Tokens Minted & Credited to Distributor Balance
    
    Dev->>Iss: 3. Set Home Domain (e.g. token.rushbox.in)
    Iss->>PiBC: Update Account Home Domain
    
    PiBC->>Web: 4. Pi Server crawls /.well-known/pi.toml
    Web-->>PiBC: Returns validated token metadata & logo
    Note over PiBC,Web: Token is now verified in Pi Wallet UI!

Loading

1. Trustline Requirement: On Pi Network, a wallet cannot receive a custom asset unless it explicitly "trusts" it. The first wallet to establish a trustline becomes the Distributor.
2. Minting via Payment: When the Issuer Account sends the custom token to the Distributor, the tokens are dynamically created (minted) on-chain.

---

📦 Prerequisites

Before starting, ensure you have:

1. Node.js (v18 or newer) installed on your machine.
2. Two Pi Wallets:
   • Issuer Wallet: Creates and issues the token.
   • Distributor Wallet: Receives, holds, and distributes the initial token supply.
   • Both wallets must be activated and have enough Pi (Test-Pi on Testnet or Real Pi on Mainnet) to cover minimum ledger reserves and network fees.
3. Secret Keys (S... format) for both wallets (accessible in Pi Wallet > Settings).
4. (Optional for Pi Wallet UI listing): A domain with HTTPS access (e.g., token.rushbox.in).

---

🛠️ Project Setup

Clone this repository and navigate into the token_guide directory:

git clone <YOUR_REPO_URL>
cd token_guide

Copy the .env.example file to .env:

cp .env.example .env

---

🔐 Environment Configuration (.env)

Open .env in your code editor and fill in your values:

# ==============================================================================
# 1. NETWORK SELECTION (TESTNET or MAINNET)
# ==============================================================================
PI_NETWORK=TESTNET

# ==============================================================================
# 2. WALLET SECRET KEYS (Private Keys starting with S...)
# ==============================================================================
ISSUER_SECRET_KEY=SDUMMYISSUERKEYXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DISTRIBUTOR_SECRET_KEY=SDUMMYDISTRIBUTORKEYXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# ==============================================================================
# 3. TOKEN CONFIGURATION
# ==============================================================================
TOKEN_CODE=RB
MINT_AMOUNT=1000000

# ==============================================================================
# 4. HOME DOMAIN (For Pi Wallet UI Verification)
# ==============================================================================
HOME_DOMAIN=token.rushbox.in

Configuration Options:

Variable	Description	Allowed Values / Example
PI_NETWORK	Target Pi Network environment	TESTNET (Default) or MAINNET
ISSUER_SECRET_KEY	Secret Key of the Issuing Account	Starts with S... (56 characters)
DISTRIBUTOR_SECRET_KEY	Secret Key of the Distributor Account	Starts with S... (56 characters)
TOKEN_CODE	Token identifier (Alphanumeric, max 12 chars)	RB, GAME, COIN, etc.
MINT_AMOUNT	Total tokens to mint initially	e.g. 1000000 (1 Million)
HOME_DOMAIN	Domain for metadata verification	token.rushbox.in (No https://)
HORIZON_URL	(Optional) Custom Horizon Server URL	Auto-selected based on PI_NETWORK
NETWORK_PASSPHRASE	(Optional) Custom Network Passphrase	Auto-selected based on PI_NETWORK

---

🚀 Step-by-Step Minting Workflow

Step 1: Install Dependencies

Install @stellar/stellar-sdk and dotenv:

npm install

---

Step 2: Mint Tokens

Run the automated minting script:

node mint.js

What this script does:

1. Loads the specified network configuration (TESTNET or MAINNET).
2. Checks if a trustline for TOKEN_CODE already exists on the Distributor account. If not, creates and submits the changeTrust transaction.
3. Submits a payment transaction from the Issuer to the Distributor, effectively minting MINT_AMOUNT tokens.
4. Outputs transaction hashes and the updated balances.

---

Step 3: Verify Balances

Check the balances and trustlines of both Issuer and Distributor wallets:

node check_balance.js

---

Step 4: Set Home Domain (For Pi Wallet Listing)

To link your domain on-chain:

node set_domain.js

This submits a setOptions transaction on the Issuer account setting homeDomain = <YOUR_DOMAIN>.

---

Step 5: Host pi.toml Metadata

Create and host a file at https://<YOUR_DOMAIN>/.well-known/pi.toml with Content-Type: text/plain and HTTPS enabled.

# /.well-known/pi.toml

[[CURRENCIES]]
code="RB"
issuer="<YOUR_ISSUER_PUBLIC_KEY>"
name="RushBox"
desc="Official utility token for the Rush Box gaming ecosystem."
image="https://token.rushbox.in/assets/logo.png"

Verification Requirements:

• code: Must match your TOKEN_CODE exactly (case-sensitive).
• issuer: Must match your ISSUER_PUBLIC_KEY (G...).
• image: A direct HTTPS link to a square PNG/JPG logo.
• Served with header: Content-Type: text/plain and Access-Control-Allow-Origin: *.

---

🌐 Testnet vs Mainnet Comparison

Feature	Testnet (PI_NETWORK=TESTNET)	Mainnet (PI_NETWORK=MAINNET)
Purpose	Development, Testing & Staging	Real Ecosystem & Production Use
Horizon API	https://api.testnet.minepi.com	https://api.mainnet.minepi.com
Network Passphrase	Pi Testnet	Pi Network
Token Cost	Free (Obtained via Testnet Faucet)	Real Pi Coin Fees
Risk	Zero financial risk	Irreversible on-chain actions

---

🔒 Security & Production Best Practices

1. Locking Issuer Account (Fixing Total Supply):
   • On Pi/Stellar, as long as the Issuer secret key exists and has signers, more tokens can technically be minted.
   • To make your total supply permanently fixed (capped), you can lock the issuing account by setting its master key weight to 0.
2. Never Expose Private Keys:
   • Ensure .env is listed in your .gitignore.
   • Never commit private keys to GitHub or public repositories.
3. Use Dedicated Wallets:
   • Do NOT use personal wallets holding mainnet funds as your testnet issuer.
4. Cache & CDN for pi.toml:
   • Host pi.toml behind Cloudflare Pages / Workers with edge caching enabled to prevent crawler downtime delisting.

---

❓ Troubleshooting & FAQs

1. Account not found (404)

• Cause: The wallet account has not been activated on the target network.
• Fix: On Testnet, fund the wallet with Test-Pi from the Pi Wallet faucet. On Mainnet, send at least 1 Pi to activate the account.

2. op_underfunded or tx_insufficient_fee

• Cause: Not enough Pi in the wallet to pay transaction fees or maintain the base reserve (each trustline requires a 0.5 Pi reserve).
• Fix: Add more Pi to the wallet.

3. op_no_trust

• Cause: The destination wallet does not have an active trustline for the token.
• Fix: Run mint.js which automatically creates the trustline first.

---

📄 License

MIT License. Built for the Pi Network Community.