Tokens, keys, and the chain — the decisions you don't get a second attempt at

The token registry

docs/TOKEN_REGISTRY.md is not design documentation — it is the platform's living operational record of every NAQD deployment: the mint addresses that exist, the account that holds each authority, and where the keys controlling them physically live. It contains no secrets; it records where things live and who holds them, never key material itself. It is meant to be edited the same day something changes, not "eventually" — a registry that lags reality is worse than no registry, because it actively misleads whoever reads it next during an incident.

Current state — reproduced from docs/TOKEN_REGISTRY.md §1

As of this page's generation date, zero mints exist anywhere. The devnet treasury below is a signer, not a mint — it's the keypair that will become the devnet mint/freeze authority the moment naqd-token create runs.

What gets written to §1, and when, follows directly from the two meanings of "minting": the registry tracks token creation events (one row per chain, ever), not the recurring issuance operations that stablecoin-service posts to the ledger millions of times over. Concretely:

1. The moment naqd-token create succeeds. Record the mint address, decimals, token program, and both authorities in §1 — the command prints all of them on success.
2. The moment an authority moves. spl-token authorize (see Operating & rotating) changes who can sign for mint or freeze — the new authority and who approved the change belong in the same row.
3. The moment a key is rotated or a keypair file is regenerated, even if the on-chain authority hasn't moved yet — §2's custody table should never describe a file that no longer exists.
4. The moment a compromise is even suspected. Don't wait for confirmation — see the incident ordering in Operating & rotating.

Key custody model

Three keys show up across this platform's NAQD path, and they have genuinely different blast radii — worth being exact about which is which, since the most common mistake is treating them as interchangeable "the crypto key."

How the service actually loads and decrypts keys

Treasury private keys for both live chains are AES-256-GCM encrypted at rest. The easy mistake is assuming CHAIN_ENV is somehow part of key derivation — it isn't. It only selects which ChainClient implementation gets constructed:

func NewRegistryFromConfig(cfg *config.Config) (*Registry, error) {
    mode := strings.ToLower(strings.TrimSpace(os.Getenv("CHAIN_ENV")))
    if mode == "" { mode = ChainEnvSandbox }

    switch mode {
    case ChainEnvLive:
        solanaC, err := newSolanaChain(cfg)   // hard-fails if keys/addresses unset
        polygonC, err := newPolygonChain(cfg) // same — never silently falls back
        return NewRegistry([]ChainClient{solanaC, polygonC}, "solana")
    case ChainEnvSandbox:
        return NewRegistry([]ChainClient{NewSandboxChain("solana"), NewSandboxChain("polygon")}, "solana")
    }
}

CHAIN_ENV=live hard-fails construction at startup if either chain's keys or addresses are missing — it deliberately never degrades to sandbox quietly, because a live deployment must not end up minting into an in-memory map without anyone noticing.

func deriveAESKey(passphrase string) []byte {
    sum := sha256.Sum256([]byte(passphrase))
    return sum[:] // ENCRYPTION_KEY, whatever length an operator sets, becomes exactly 32 bytes
}

func decryptTreasuryKey(passphrase, ciphertextB64 string) (string, error) {
    key := deriveAESKey(passphrase)
    raw, _ := base64.StdEncoding.DecodeString(ciphertextB64)
    block, _ := aes.NewCipher(key)
    gcm, _ := cipher.NewGCM(block)
    nonce, ciphertext := raw[:gcm.NonceSize()], raw[gcm.NonceSize():]
    plaintext, err := gcm.Open(nil, nonce, ciphertext, nil)
    return string(plaintext), err
}

Called as decryptTreasuryKey(cfg.Security.EncryptionKey, encrypted) — identically for SOLANA_WALLET_PRIVATE_KEY and POLYGON_WALLET_PRIVATE_KEY inside newSolanaChain/newPolygonChain — the same ENCRYPTION_KEY that also wraps card PANs (Security → Key management). In CHAIN_ENV=sandbox none of this runs at all; no keys are needed. Custody address = treasury address in both live implementations — there is no separate "mint authority" identity distinct from the treasury signer anywhere in this codebase today; that separation only exists once a multisig becomes the mint authority (§chain-choice does not change this — it's orthogonal to which chain is primary).

The .gitignore protections, and what a leak actually means

# --- Chain keypairs: NEVER commit these (they are mint authorities) ---
*treasury*.json
*keypair*.json
!package*.json

The negation on the last line matters: without it, the two globs above would also swallow every package.json/package-lock.json in the admin dashboard and mobile tooling, which is not the intent.

SPL Token vs. Token-2022

The single irreversible decision that has to happen before any mainnet mint exists. A Solana mint is created under exactly one token program and cannot be migrated to the other afterwards; Token-2022's extensions can only be enabled at mint creation, never bolted on later. Getting this wrong doesn't mean a config change — it means creating a second mint and migrating every holder's balance to it.

Why cmd/tools/naqd-token deliberately doesn't implement this

The CLI documented on this platform creates mints under the original SPL Token program only — on purpose, not as an oversight:

// This tool creates a mint under the ORIGINAL SPL Token program. That is a
// permanent choice: a mint cannot be migrated to Token-2022 afterwards, and
// Token-2022 extensions (permanent delegate / clawback, confidential
// transfers, transfer hooks for KYC gating) can only be enabled at creation.
// solana-go ships no instruction bindings for those extensions, and
// hand-rolling TLV encoding for a one-time irreversible mainnet action is a
// bad trade — use the official `spl-token` CLI if you want them.
// See docs/TOKEN_REGISTRY.md § "SPL Token vs Token-2022".

Concretely: solana-go (the Go SDK naqd-token is built on) ships the Token-2022 program ID as a constant, and full instruction-builder bindings for the original token program — which is what cmdCreate actually calls, via token.NewInitializeMint2InstructionBuilder — but no equivalent builders for Token-2022's extension instructions. Enabling permanent delegate or a transfer hook means hand-encoding TLV (type-length-value) extension data by hand against the raw program, with no library to check the encoding against. That's a reasonable thing to build and test carefully for a feature you'll exercise repeatedly; it's the wrong thing to trust for a mainnet mint creation you get to run exactly once. The official Rust-based spl-token CLI has first-class, tested support for every Token-2022 extension — use it instead.

# freeze authority only (the conservative, recommended default)
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  create-token --decimals 6 --enable-freeze

# add clawback as well — only once the policy question above is actually decided
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  create-token --decimals 6 --enable-freeze --enable-permanent-delegate

Decimals must stay ≥ 4 — the platform's NAQD settlement exponent (Ledger → On rounding) — or ledger amounts become unrepresentable on chain. 6 is the recommended value and what naqd-token's defaultDecimals constant and every worked example on this site assume, matching USDC's convention.

Why Solana, and when you'd choose otherwise

MyNEX is custodial and ledger-first: a user's NAQD balance is a row in the ledger, not a wallet UTXO or account, until they explicitly withdraw on-chain (NAQD → Custodial-first design). Every mint, burn, and transfer inside the platform posts to the ledger first and calls the chain second (NAQD Minting → Mint lifecycle) — which means the chain is not this product's hot path. It's a settlement/proof/self-custody-exit rail: it exists so circulating supply is publicly checkable against the reserve, and so a user can leave custodial holding entirely by withdrawing to an address only they control. That materially lowers the stakes of which chain is primary compared to a wallet-native token where every user interaction touches the chain directly — and it's exactly why ChainClient (NAQD Minting → Custody & the ChainClient interface) is an interface with three interchangeable implementations rather than Solana-specific code sprinkled through stablecoin-service.

What would change this answer: if MyNEX's center of gravity shifted from "store of value plus a self-custody exit" toward "payments/remittance rail as the primary use case" — NAQD moving through corridors like Malaysia more than it sits in a wallet as saved value — Stellar's remittance-native issuance and MoneyGram/Circle integrations would deserve a serious, product-led re-evaluation, not just a technical one. Separately, a major Solana outage or a client-diversity regression would have been a real reason to hesitate as recently as late 2025, before Firedancer shipped; that specific risk is materially smaller now. Polygon's position is worth naming plainly: it's still the platform's declared secondary chain in configuration, but polygon.Client.DeployERC20Token is a literal not-implemented stub today (NAQD Minting → The two meanings of "minting") — the gap between "declared secondary chain" and "chain with any working deployment path" is real, not a rounding error.

Operating & rotating

cmd/tools/naqd-token is the operational surface for token creation, inspection, and break-glass issuance — not the platform's normal issuance path.

Every command except info refuses to touch mainnet without --yes-really-mainnet, checked in netFlags.endpoint() — a deliberate second confirmation on top of whatever shell history or muscle memory got the operator there.

Authority rotation

Incident response — suspected key compromise, in order

1. Rotate the mint authority first. spl-token authorize <mint> mint <new-authority> — minutes matter here, since a compromised authority can issue unbacked supply for as long as it stays valid. Do this before investigating, not after.
2. Freeze suspicious accounts, if a freeze authority exists and holder accounts look affected — a mitigation, not a fix, for the underlying key exposure.
3. Audit naqd_operations against on-chain supply. Every legitimate mint has a corresponding completed NAQDOperation row; anything minted through the compromised key directly (bypassing stablecoin-service, same mechanism as CLI issuance above) will not.
4. Reconcile the ledger's naqd_reserve account against both figures — the full procedure is documented at Reconciliation → NAQD reserve accounting.

Which key is compromised changes what's actually at risk — cross-reference against the blast-radius column in the custody diagram above before deciding how urgently to escalate.