---

name: icpay-roadmap description: What ICPay has shipped, what is next, and what was deliberately refused. Read before proposing or building a feature, so work lands in phase order and rejected ideas are not re-proposed.

ICPay roadmap

Source of truth: docs/roadmap/roadmap.md. This is a summary — read that file before planning real work, and treat it as authoritative if the two disagree.

Shipped

Phase 0 — Custody foundation. Per-user subaccounts derived from the caller principal. Strict API→Service→Repository→Storage layering. 24-test suite.

Phase 1 — Username as the address. Free claim for 5–8 characters; paid purchase for 1–4 (10 / 5 / 2 / 1 ICP by length). Usernames are permanent, with aliases. Send by username, principal, account, or account-ID. Public profiles. Unauthenticated directory search.

Phase 2 — Multi-token visibility. Discovers every SNS token from SNS-W plus five chain-key ledgers (ckBTC, ckETH, ckUSDC, ckUSDT, ICP), showing balances via icrc1_balance_of. Read-only at the time this phase closed — sending arrived in Phase 3.

Also shipped outside the phase numbering: 10-language UI, fiat display, avatar profile links, settings drawer with theme switching.

Phase 3 — Multi-token transfers. LedgerService.mo takes a ledgerId on every call, so one path serves any ICRC-1. Fees read live via icrc1_fee, never cached. A storage allowlist gates which ledgers can be sent to.

Phase 4 — Token creation. launchToken charges 5 ICP, creates a canister, installs the sealed reference ledger wasm and hands off control. Three things differ from what the roadmap originally specified, and the deviations are deliberate — do not "fix" them back:

• ICPay pays the cycles, not the creator. Requiring the creator to supply cycles would put dfx back in the flow.
• Nobody is the controller — every launch sets controllers = [], so the ledger can never be upgraded by anyone, creator included. The freezing threshold is a year to compensate, since there is no reinstall after deletion.
• Decimals (8) and transfer fee (10 000 e8s) are fixed, not form fields.

TOKEN_MINTING_PRINCIPAL = "aaaaa-aa" (Config.mo:36) is what makes a launched token's supply genuinely fixed: the management canister has no caller, and in ICRC-1 a transfer from the minting account is what mints. ICPAY itself launched before that fix, so its supply is still mintable and its ledger cannot be upgraded to change it — never claim ICPAY has a fixed supply.

Next

Phase 5 — Liquidity and trading. ICRC-2 approve + transfer_from, swap quotes with slippage, LP positions. The roadmap's recommendation is to integrate an existing DEX (ICPSwap, Sonic, KongSwap) rather than build an AMM. Do not propose building one. This is the next thing to build — prefer it over starting a later phase.

Phase 6 — Decentralizing custody. Move the controller to an SNS- or NNS-controlled canister. Reproducible Docker builds, third-party audit, SECURITY.md with a private disclosure channel, published incident policy. Partially mitigated already: both canisters now have redundant recovery controllers, so key loss no longer means losing the canister. Key theft is still unmitigated — that is what this phase is for. See docs/security/guide.md.

Phase 7 — Merchants and payments. Merchant accounts with a verification badge; signed, expiring, single-use payment requests; checkout page; webhook API; refunds as a first-class operation; settlement reports. Depends on Phase 3 for stablecoins and Phase 6 for security.

Phase 8 — Shopping. Merchant directory, product listings, order history, optional escrow with a dispute window. The most speculative item on the list.

Deliberately refused

Do not propose these. Each was considered and rejected with a reason:

| Not doing | Why | |---|---| | Non-custodial mode | A different product. Retrofitting means rebuilding every flow. | | Native mobile apps | The PWA covers it. | | Cross-chain bridges | Chain-key tokens make them redundant, and bridges are the most-exploited component in the industry. | | NFTs | No connection to sending money by username. | | Fiat on-ramp | Needs a licensed partner. Revisit alongside Phase 7 compliance work. |

Continuous concerns

Performance. getById, completeTx, and failTx scan the global transaction list linearly. Fine at current volume, quadratic at scale — a known future problem, not a bug to fix opportunistically.

Cycles. Watch npm run ci cycles:balance. At zero the canister is deleted.

Tests. 33 files. Every new endpoint adds a test in the same commit.

Docs. docs/command/README.md is the operations reference and is meant to stay true. Update it when a command changes.

Where things are documented

| Path | Contents | |---|---| | docs/roadmap/roadmap.md | The authoritative roadmap | | docs/command/README.md | Operations reference — every npm run ci command | | docs/workflow.md | Branch workflow | | docs/architecture/meramaid/ | Mermaid diagrams: system, backend, frontend, flows, data | | docs/costing/here.md | Cycle cost and burn analysis | | docs/language/add/readme.md | How to add a locale | | docs/launch/guide.md | Launch playbook | | docs/demo/ | Screenshots used by the README |