add-chain-integration

# Adding a chain / family / token to PipRail

This is the canonical, do-it-every-time procedure — the reusable **"how"** for adding any
new chain, family, EVM preset, or token. Read it end-to-end before you start.

> The whole product is *immaculate simplicity* — `npm install`, name a chain,
> add a wallet, get paid. Every integration must preserve that. If a change
> makes PipRail heavier, you're doing it wrong.

---

## 0. The iron rules (violate none of these)

1. **Every token address is verified on-chain before it ships.** Read `symbol()`
   + `decimals()` (or the chain's metadata call) from a live mainnet RPC. Re-derive
   from the **issuer** (Circle / Tether / Ripple), never from a blog or aggregator.
   This rule has already caught real errors (testnet issuers posing as mainnet,
   third-party bridges posing as native). No exceptions.
2. **The native coin AND a stablecoin are BOTH mandatory — no chain ships without native.**
   Every integrated chain (a preset *or* a new family) MUST support, and be **live-proven on
   mainnet**, two payment assets. This is non-negotiable and has no exception:
   - **The chain's native coin** (`token: 'native'`) — fully wired through `resolveToken`,
     `describeAsset`, `pay`, `verify`, `estimateCost`, `balanceOf`, and `recipientReady`
     (for native: `balanceOf` reads the native coin, `recipientReady` → `'n/a'`), end-to-end. Native is the
     **zero-setup, always-available rail** (no token contract, no trustline / ATA / storage
     to receive), so it **must work 100% of the time**. If you think native "can't" be done
     on a chain, you're wrong: it is **digest-bound** wherever the tx can't carry a memo
     (EVM, Solana, Sui, Tron, NEAR — verified by the tx digest + a recency window + the
     gate's single-use set) and **memo/tag-bound** where it can (TON, Stellar, XRPL). Tron
     and NEAR were **retrofitted** with native in 1.1.0 *specifically to close this gap* —
     never reintroduce a "token-only" chain. Native is a valid payment asset on **every**
     family shipped today; keep it that way.
   - **At least one canonical stablecoin** — Circle-native **USDC** or Tether-native **USD₮**
     (issuer-native, per rule 3). Ship every one the chain has; a chain with **neither** earns
     **no preset** (it's documented byo-only — see §1).
   Both assets are verified on-chain (§2) **and** exercised by a real mainnet payment from the
   chain's test wallet before the chain is "done", and the family's `describe-asset` test MUST
   assert **native and ≥1 stablecoin**. A PR that adds a chain without a working `token:'native'`
   path is incomplete — send it back.
3. **Ship only ISSUER-NATIVE stablecoins.** "Issuer-native" = minted directly by
   Circle/Tether/Ripple on that chain (e.g. Sei's "USDT" is USDT0/LayerZero, *not*
   Tether-native → omitted). Bridged/wrapped tokens are **not** built in (callers can still
   pass them as a custom token). Document any omission inline, like TON's "native USDC doesn't
   exist here". *(This rule is about a stablecoin's provenance; the chain's own coin is rule 2 —
   don't confuse the two senses of "native".)*
4. **The protocol layer stays chain-agnostic.** `server.ts`, `client.ts`, `x402.ts`,
   `errors.ts` import **only** `drivers/types.ts`. Never add `viem`, `@solana/*`,
   `@ton/*`, or any chain lib to those files.
5. **Drivers mirror each other, file-for-file.** A family is `chains · wallet · pay ·
   verify · index`, functions are family-suffixed (`payEvm`/`paySolana`/`payTon`,
   `verifyEvm`/…). A new family copies the closest existing one.
6. **Optional chain libs are lazy.** Anything beyond `viem` (the one hard peer dep) is
   an **optional peer dep**, dynamically imported on first use. A pure-EVM install must
   never download `@solana/*`, `@ton/*` or `@stellar/*`. After `npm run build`, the main
   entry must have **zero static imports** of those libs (they live only in code-split
   `<family>-*` chunks) — verify with the dist grep in the §5 runbook, and keep it that way.
7. **Tests are the contract — change them first.** Behaviour change ⇒ test changes
   first, then code. `sdk/test/` (Vitest) is canonical.
8. **The site is part of "done."** A chain isn't shipped until it's on piprail.com with
   its real logo SVG. See §6 — this is the step that's easiest to forget and the user
   has flagged it as a hard requirement.
9. **No backend, no database, no auth, no dashboard, no fee, no hosted facilitator.**
   If an integration seems to need one, stop — it's the wrong design.
10. **Never publish.** Do not `npm publish` or touch the npm registry. Publishing is
    manual and owner-only.
11. **Every chain needs a test wallet — create one if it's missing.** Before building a
    family, check `.secrets/wallets/`. If there's no wallet for that chain, **generate a
    full one** (address + mnemonic/seed + public & private key — whatever that chain needs
    to sign and recover) with the chain's own keygen, write it to
    `.secrets/wallets/<family>-wallet.json` (`chmod 600`), and use it for the live smoke
    test. `.secrets/` is gitignored — **never commit a wallet, and never paste a private
    key/seed into code, logs, the transcript, or anywhere outside that file.** Generating a
    keypair is offline and free; *funding* it (native coin for fees + any
    trustline/account-creation) is a separate manual step the owner does — tell them what's
    needed. See §2.

---

## 1. First — classify the work (this decides everything)

| You are adding… | Driver work | Files you touch | Effort |
|---|---|---|---|
| **A token on a chain we already support** (e.g. EURC on Base) | none | that chain's `tokens` map in `drivers/<family>/chains.ts`; tests; README; **site** (token badge + maybe a `tokens/<sym>.svg`) | minutes |
| **A new EVM chain** (any L1/L2 viem can reach — incl. "native EVM" chains like Sei, Injective) | **none — reuse the EVM driver** | one row in `drivers/evm/chains.ts`; tests; README; CLAUDE.