diff --git a/.vitepress/config.mts b/.vitepress/config.mts index a532785..88ceb77 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -225,6 +225,16 @@ function sidebarHome() { collapsed: true, items: [ { text: 'Overview', link: '/developers/overview ' }, + + { + text: 'Token Walkthroughs', + collapsed: true, + items: [ + { text: 'Getting Started', link: '/developers/token/walkthrough' }, + { text: 'Advanced', link: '/developers/token/walkthrough-advanced' } + ] + }, + { text: 'Testnet', collapsed: true, diff --git a/developers/token/walkthrough-advanced.md b/developers/token/walkthrough-advanced.md new file mode 100644 index 0000000..1eec70c --- /dev/null +++ b/developers/token/walkthrough-advanced.md @@ -0,0 +1,313 @@ +### APL Token Walkthrough — Level 2: Advanced Operations + +This guide builds on the Level 1 walkthrough and covers advanced token scenarios using `arch-cli`. You’ll learn authority management, freezing/thawing, delegate approvals, “checked” operations, batch jobs, multisig, account lifecycle, and useful listing/formatting utilities. + +Prereqs: +- Completed Level 1 and have a running environment (`orchestrate start`) pointing at your profile +- Have `MINT` and at least one token account from Level 1 + +Tip: `--profile` is a global flag and must be placed before subcommands, or set `ARCH_PROFILE` env var. + +--- + +## 0) Quick setup (reuse Level 1 values) + +If you didn’t keep these env vars around, re-export them now with your own values: + +```bash +# Example formats only; paste your own from Level 1 output +export MINT= +export ATA= +``` + +Optional keys/env from Level 1 for examples below: + +```bash +mkdir -p ~/DEMO_KEYS +openssl rand -out ~/DEMO_KEYS/freeze_authority.key 32 # if you want to demo freeze/thaw +openssl rand -out ~/DEMO_KEYS/new_mint_authority.key 32 # for authority handoff demos +# If not already created in Level 1 +# openssl rand -out ~/DEMO_KEYS/recipient.key 32 # recipient wallet + +# If you created a recipient ATA in Level 1, reuse it: +# export RECIPIENT_ATA= +``` + +--- + +## 1) Authority management (mint/freeze/account owner/close account) + +Why: Use authorities to harden supply, reduce custody risk, and separate duties. Common patterns include: disabling minting after distribution to cap supply, removing freeze authority for immutability, delegating account ownership for custodial flows, and designating who can close dormant accounts to reclaim rent. + +Disable future minting (burn-only mint): + +```bash +arch-cli token set-authority "$MINT" \ + --authority-type mint \ + --new-authority none \ + --current-authority ~/DEMO_KEYS/mint_authority.key +``` + +Transfer mint authority to a new authority address: + +```bash +arch-cli token set-authority "$MINT" \ + --authority-type mint \ + --new-authority \ + --current-authority ~/DEMO_KEYS/mint_authority.key + +Note: Replace `` with the base58 public key (32-byte) of the new authority. If you only have a key file, you can run an airdrop once using that key to print its public key, then use that base58 value here. +``` + +Remove freeze authority (cannot freeze accounts anymore): + +```bash +arch-cli token set-authority "$MINT" \ + --authority-type freeze \ + --new-authority none \ + --current-authority ~/DEMO_KEYS/mint_authority.key +``` + +Change token account owner (handoff custody of a specific account): + +```bash +arch-cli token set-authority "$ATA" \ + --authority-type account_owner \ + --new-authority \ + --current-authority ~/DEMO_KEYS/mint_authority.key +``` + +Enable someone to close an account to reclaim rent-exemption back to a destination: + +```bash +arch-cli token set-authority "$ATA" \ + --authority-type close_account \ + --new-authority \ + --current-authority ~/DEMO_KEYS/mint_authority.key +``` + +--- + +## 2) Freeze and thaw token accounts + +Why: Freezing lets you respond to emergencies (compromised keys, suspected fraud, regulatory holds) without impacting the mint itself. Thawing restores normal operations once the incident is resolved. If you never want this power, remove the freeze authority from the mint for stronger guarantees. + +Freeze a token account (requires freeze authority on mint): + +```bash +arch-cli token freeze-account "$ATA" \ + --authority ~/DEMO_KEYS/freeze_authority.key +``` + +Thaw a frozen token account: + +```bash +arch-cli token thaw-account "$ATA" \ + --authority ~/DEMO_KEYS/freeze_authority.key +``` + +Check state with: + +```bash +arch-cli token balance "$ATA" +``` + +--- + +## 3) Delegate approvals (approve/revoke) + +Why: Delegations enable spend allowances without handing over full ownership. Typical uses include exchange hot wallets, automated market maker bots, and time-bound spend limits. Revoking an allowance is a fast way to cut access without moving funds. + +Approve a delegate to spend from an account up to an allowance: + +```bash +export DELEGATE=$(xxd -p -c 64 ~/DEMO_KEYS/recipient.key) +arch-cli token approve "$ATA" "$DELEGATE" 420000 \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +Revoke the delegate (removes allowance): + +```bash +arch-cli token revoke "$ATA" \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +--- + +## 4) Checked operations (decimals-verified) + +Why: Checked ops provide defense-in-depth by verifying the mint’s decimals on-chain. This prevents wrong-scale mistakes (e.g., treating 6-decimal assets as 9-decimal) and mitigates spoofing where a mismatched mint could otherwise accept transfers. + +Use these when you want the instruction to also verify the expected decimals on-chain. Replace `6` with your mint’s decimals. + +Transfer checked (to recipient’s ATA): + +```bash +arch-cli token transfer-checked "$ATA" "$RECIPIENT_ATA" 1000 6 \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +Mint to checked (to a specific account): + +```bash +arch-cli token mint-to-checked "$MINT" "$ATA" 100000 6 \ + --authority ~/DEMO_KEYS/mint_authority.key +``` + +Burn checked: + +```bash +arch-cli token burn-checked "$ATA" 50000 6 \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +--- + +## 5) Batch operations + +Why: Batch jobs are ideal for airdrops, vesting schedules, or periodic distributions. Capture a single source of truth in JSON and execute consistently, making it easy to review, audit, and re-run if needed. + +Prepare a JSON file describing transfers: + +```json +[ + { + "source_account": "", + "destination_account": "", + "amount": 12345, + "owner_keypair_path": "~/DEMO_KEYS/mint_authority.key" + } +] +``` + +Run the batch transfer (batch uses default decimals=9 internally; amounts are raw units): + +```bash +arch-cli token batch-transfer ./transfers.json \ + --keypair-path ~/DEMO_KEYS/payer.key +``` + +Prepare a JSON file describing mints: + +```json +[ + { + "mint_address": "", + "account_address": "", + "amount": 1000000, + "authority_keypair_path": "~/DEMO_KEYS/mint_authority.key" + } +] +``` + +Run the batch mint (batch uses default decimals=9 internally; amounts are raw units): + +```bash +arch-cli token batch-mint ./mints.json \ + --keypair-path ~/DEMO_KEYS/payer.key +``` + +--- + +## 6) Multisig (advanced/experimental) + +Why: Multisig reduces single-key risk for high-value authorities (mint/freeze). Require M-of-N signers to approve sensitive changes, align with governance policies, and keep keys distributed across stakeholders and devices. + +Create a multisig authority requiring 2-of-3 signers: + +```bash +arch-cli token create-multisig 2 \ + --signers ~/DEMO_KEYS/mint_authority.key,~/DEMO_KEYS/new_mint_authority.key,~/DEMO_KEYS/freeze_authority.key \ + --keypair-path ~/DEMO_KEYS/payer.key +``` + +Show multisig account details: + +```bash +arch-cli token multisig-show +``` + +Make the multisig the new mint authority: + +```bash +arch-cli token set-authority "$MINT" \ + --authority-type mint \ + --new-authority \ + --current-authority ~/DEMO_KEYS/mint_authority.key +``` + +Note: Multisig sign/execute flows are currently developer-focused and may evolve. + +--- + +## 7) Account lifecycle: create ATA, list, close + +Why: Manually creating ATAs helps with onboarding recipients ahead of distributions. Listing accounts gives operational visibility (balances, freezes, delegates). Closing idle accounts reclaims rent to keep state lean and costs low. + +Manual account creation for a recipient (Associated Token Account): + +```bash +arch-cli token create-account \ + --mint "$MINT" \ + --owner ~/DEMO_KEYS/recipient.key \ + --keypair-path ~/DEMO_KEYS/payer.key +``` + +List all accounts for a mint and see balances/states: + +```bash +arch-cli token accounts "$MINT" +``` + +Close a token account (reclaim rent to a destination address): + +```bash +arch-cli token close-account "$ATA" \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +--- + +## 8) Utilities: supply, mints, balances, amount formatting + +Why: These commands are your day-to-day observability and formatting toolkit. Confirm supply caps, scan all mints in the network, inspect account holders, and convert amounts precisely for UI or accounting. + +Supply and mint details: + +```bash +arch-cli token supply "$MINT" +``` + +List all mints on the network: + +```bash +arch-cli token mints +``` + +Account balance (with UI formatting): + +```bash +arch-cli token balance "$ATA" +``` + +Convert amounts with mint decimals: + +```bash +arch-cli token amount-to-ui "$MINT" 1000000 +arch-cli token ui-to-amount "$MINT" 1.000000 +``` + +--- + +## 9) Suggested hardening patterns + +- Disable mint authority when distribution is complete (`--new-authority none`). +- Remove freeze authority for immutable mints. +- Use checked ops (`*-checked`) in critical flows to enforce decimals. +- Use multisig for high-value authorities. +- Keep separate keys for fee payer, mint authority, freeze authority, and custodians. + +--- + +That’s it—Level 2 equips you with operational controls for production-grade tokens. Continue to iterate with batch jobs, multisig authorities, and authority life-cycle management. diff --git a/developers/token/walkthrough.md b/developers/token/walkthrough.md new file mode 100644 index 0000000..55868c4 --- /dev/null +++ b/developers/token/walkthrough.md @@ -0,0 +1,257 @@ +### Create Your Own APL Token: End-to-End Walkthrough + +This guide walks you through creating an APL token from scratch using the Arch CLI, starting local services, generating keys, minting tokens (with automatic ATA creation), and verifying balances. + +We’ll create a fun demo token called “STARBURST” with 6 decimals, mint a supply to your wallet, and inspect the results. + +Prereqs: +- arch-cli installed and on PATH +- Docker with the docker compose plugin +- Local Arch dev tools checked out (we’ll point orchestrate to your local source) + +Tip: All commands below are copy/paste ready. Replace placeholders as needed. + +--- + +## 1) Create a configuration profile + +First, create a profile named `demo-testnet` pointing to a remote Bitcoin node and your local Arch node: + +```bash +arch-cli config create-profile demo-testnet \ + --bitcoin-node-endpoint http://bitcoin-node.test.aws.archnetwork.xyz:49332 \ + --bitcoin-node-username bitcoin \ + --bitcoin-node-password uU1taFBTUvae96UCtA8YxAepYTFszYvYVSXK8xgzBs0 \ + --bitcoin-network testnet \ + --arch-node-url http://localhost:9002 +``` + +Optionally set this as your default profile so you don’t need to pass `--profile` each time: + +```bash +arch-cli config set-default-profile demo-testnet +``` + +You can confirm your profiles with: + +```bash +arch-cli config list-profiles +``` + +--- + +## 2) Start the local environment (no bitcoind) + +We’ll run the orchestrated stack using your local Arch source and skip running a local bitcoind. Titan will connect to the Bitcoin RPC specified in your `demo-testnet` profile. + +From your arch-network repo root: + +```bash +# Use --profile as a top-level flag (must come before subcommands) +arch-cli --profile demo-testnet orchestrate start --local "$(pwd)" --no-bitcoind + +# Alternatively, use the environment variable for the profile +ARCH_PROFILE=demo-testnet arch-cli orchestrate start --local "$(pwd)" --no-bitcoind +``` + +What this does: +- Starts Titan and the local_validator +- Uses your profile’s Bitcoin RPC endpoint and credentials (no local bitcoind needed) +- Exposes the Arch RPC at `http://localhost:9002` + +Notes: +- `--profile` is a global flag and must be placed before subcommands like `orchestrate start`. +- You can also set the profile via the `ARCH_PROFILE` environment variable. +- If you set `demo-testnet` as the default profile, you can omit `--profile demo-testnet` entirely. + +--- + +## 3) Create demo keys + +For this walkthrough, we’ll generate simple 32-byte secp256k1 secret keys for the payer and the mint authority. Keep these safe in a dedicated folder. + +```bash +mkdir -p ~/DEMO_KEYS + +# Generate 32-byte secrets for payer and mint authority +openssl rand -out ~/DEMO_KEYS/payer.key 32 +openssl rand -out ~/DEMO_KEYS/mint_authority.key 32 + +# (If using SPL-style Option A) Generate a dedicated mint account keypair +openssl rand -out ~/DEMO_KEYS/mint.key 32 + +# (Optional) Freeze authority if you want to retain freeze control +# openssl rand -out ~/DEMO_KEYS/freeze_authority.key 32 +``` + +Notes: +- Files contain raw 32-byte secp256k1 private keys. Do not share them. +- For a quick demo, the same key can be used for multiple roles, but using separate keys is safer. + +### 3.1) Fund the mint authority (fee payer) + +The mint authority will act as the fee payer for account creation and mint transactions. Fund it once via the faucet: + +```bash +arch-cli --profile demo-testnet account airdrop \ + --keypair-path ~/DEMO_KEYS/mint_authority.key +``` + +Keep the printed public key handy; you’ll compare it with the mint’s authority in the next step. + +--- + +## 4) Create the STARBURST mint + +We’ll create a mint with 6 decimals (common for UI-friendly tokens). The “name” is off-chain branding; the chain stores mint config and authorities. We’ll refer to it as STARBURST throughout. + +```bash +# Create a new token mint with 6 decimals (SPL-style) +# Option A: Provide a mint keypair file +arch-cli token create-mint \ + --decimals 6 \ + --mint-authority ~/DEMO_KEYS/mint_authority.key \ + --mint-keypair-path ~/DEMO_KEYS/mint.key \ + --keypair-path ~/DEMO_KEYS/payer.key + +# Option B: Let the CLI generate a fresh mint keypair in-memory +# (address printed; key not saved by default) +# arch-cli token create-mint \ +# --decimals 6 \ +# --mint-authority ~/DEMO_KEYS/mint_authority.key \ +# --keypair-path ~/DEMO_KEYS/payer.key +``` + +This will: +- Derive a deterministic mint address (printed to the console) +- Create and initialize the mint account on-chain + + + +Capture the printed mint address into an environment variable `MINT` for convenience: + +```bash +# Replace with the address printed by the previous command +export MINT= + +# Example format: base58 public key (32-byte) +# export MINT=3N5Sx5Q1z3kVw8Yx3Pqv8i8dPZv2oJv1kz2N9UQG6o4w +``` + +Verify the mint: + +```bash +arch-cli token show-mint "$MINT" +``` + +You should see fields like Decimals, Supply (initially 0), and Authorities. + +--- + +## 5) Mint tokens with automatic ATA creation + +Now let’s mint some STARBURST into your wallet. We’ll use `--auto-create-ata` so the CLI derives and creates the Associated Token Account (ATA) automatically if needed. + +We’ll mint 1,000,000 raw units, which with 6 decimals equals 1.000000 STARBURST. + +```bash +arch-cli token mint "$MINT" 1000000 \ + --authority ~/DEMO_KEYS/mint_authority.key \ + --auto-create-ata +``` + +What happens: +- The CLI derives the ATA for the mint authority’s wallet +- If it doesn’t exist, it creates it (and waits for it to be visible) +- Mints 1,000,000 raw units to that account +- Prints the token account address it minted to + +Copy that printed token account address and set it as `ATA`: + +```bash +# Replace with the token account address printed by the mint command +export ATA= +``` + +--- + +## 6) Confirm balances and details + +Check the mint state: + +```bash +arch-cli token show-mint "$MINT" +``` + +Check your token account state and balance: + +```bash +arch-cli token show-account "$ATA" +``` + +You should see: +- Mint: your `MINT` +- Owner: your wallet (the mint authority’s public key) +- Balance: `1000000` (raw units) + +With 6 decimals, raw 1000000 equals 1.000000 STARBURST. + +--- + +### 6.1) Create a recipient and its ATA (for transfers) + +To demonstrate transfers, create a second wallet and its Associated Token Account for this mint. + +```bash +# Generate a second owner key (recipient) +openssl rand -out ~/DEMO_KEYS/recipient.key 32 + +# Manually create the recipient's ATA for this mint +arch-cli --profile demo-testnet token create-account \ + --mint "$MINT" \ + --owner ~/DEMO_KEYS/recipient.key \ + --keypair-path ~/DEMO_KEYS/payer.key + +# Capture the printed ATA address +export RECIPIENT_ATA= +``` + +You can verify it with: + +```bash +arch-cli --profile demo-testnet token show-account "$RECIPIENT_ATA" +``` + +--- + +## 7) Optional: transfer or burn + +Transfer some STARBURST from your account to another account (replace addresses): + +```bash +arch-cli --profile demo-testnet token transfer "$ATA" "$RECIPIENT_ATA" 420000 \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +Burn tokens from your account: + +```bash +arch-cli token burn "$ATA" 100000 \ + --owner ~/DEMO_KEYS/mint_authority.key +``` + +Re-run `show-account` and `show-mint` to confirm balances and supply. + +--- + +## Tips, gotchas, and customization + +- Profiles: You can pass `--profile demo-testnet` on any command if you didn’t make it default. +- Decimals: Common choices are 6 or 9. Pick the right precision for your UI. +- Authorities: Use a distinct freeze authority if you want the ability to freeze accounts; otherwise omit it for a freer token. +- Naming: “STARBURST” is our friendly name here. Metadata (name/symbol/logo) can be layered on via off-chain services or future metadata programs. +- Logs: If a command fails, rerun with `-v` (verbose) or review logs printed by `orchestrate start`. + +That’s it—your STARBURST APL token is live, funded, and visible. Happy building! + +Next: Continue with Level 2 advanced scenarios (authority management, freeze/thaw, delegates, checked ops, batch jobs, multisig, account lifecycle) in `APL_TOKEN_WALKTHROUGH_LEVEL_2.md`.