Mainnet Readiness

This document describes requirements for operating a production mainnet deployment. The 1.0.1 standard and SDK release supports explicit mainnet configuration for all four native profiles. Publishing the SDK does not certify a deployment, provide its storage/signing infrastructure, or enable the hosted Testnet demo on mainnet. Operators must satisfy the requirements below for their actual topology; these are not a requirement to ship a bundled backend.

The 1.0.1 native payment surface includes:

• exact with kaspa-exact-v2 (standard-native by default, optional KIP-10 additive head profile);
• optional hash-chain-additive exact with kaspa-hash-chain-exact-v1 and kaspa-x402-hash-chain-head-v2; and
• batch-settlement with kaspa-escrow-v3 and kaspa-x402-escrow-v5.

Reference signing defaults to ALL. See the signature policy and 1.0.1 validation record. Funded Testnet qualification does not certify an operator's mainnet deployment.

kaspa:testnet-10 remains the funded validation target. 1.0.1 does not provide compatibility or state migration for pre-RC runtimes. Mainnet remains opt-in and disabled by default. Operators must close the gates below before enabling their production deployment.

SDK Network Verification

Run npm run proof:mainnet-network from protocol/ for repeatable network-binding and policy-selected evidence checks over real loopback WebSocket transport. npm run proof:release-artifacts additionally builds and installs the four public tarballs in a fresh consumer. Its receipt records standard-native, additive, hash-chain-additive and batch flows on both networks, with retry, successor application and private-grant restart checks. The publisher requires that complete installed profile matrix. These proofs use controlled chain facts and do not establish operator independence, production durability or funded mainnet correctness.

Reference PNN clients accept network and allowMainnet; omitted configuration remains Testnet-10. Every RPC read/submission checks the node's reported network. Mainnet policy selection requires independently declared administrative domains; single-source and mixed-network configurations are rejected. Mainnet native address codecs and generic verified adapters require explicit opt-in. Private grant issuers also require allowMainnet on each reopen. PNN receipts carry their network; legacy receipts are Testnet-10 and cannot recover a mainnet payment. The legacy REST adapter and the funded Testnet proof runner remain Testnet-only. Use one ScriptAddressBook per network: its first record or adapter binds the book, and later cross-network use is rejected before cache writes or RPC calls. Durable evidence stores must persist a mainnet checkpoint's network tag and filter findPnnCheckpointBefore(daaScore, network) by that network. Untagged legacy checkpoints belong to Testnet-10; mainnet rejects an unscoped/foreign checkpoint instead of forwarding it to a node. Testnet-only store adapters can keep their existing method signatures and untagged checkpoint records. Generic mainnet verifiers require a matching network identity on their chain client/view; missing metadata cannot relabel legacy Testnet reads. Read and broadcast providers must share one network. Exact settlement attempts persist their network, while untagged legacy attempts remain Testnet-only on recovery. For a mainnet hash-chain view, configure new HashChainExactTransactionVerifier(view, 10000000n, 8, { network: "kaspa:mainnet", allowMainnet: true }) and expose the same immutable view.network identity.

For a read-only deployment preflight, create a private JSON configuration:

{
  "network": "kaspa:mainnet",
  "allowMainnet": true,
  "requiredAuthorities": 2,
  "submissionEndpoints": ["wss://submission.example/wrpc/json"],
  "authorities": [
    {"trustDomain": "operator_a", "endpoints": ["wss://node-a.example/wrpc/json"]},
    {"trustDomain": "operator_b", "endpoints": ["wss://node-b.example/wrpc/json"]}
  ],
  "addresses": []
}

Run npm run check:chain-authorities -- --config /private/authorities.json. This checks submission identity and corroborated health/UTXO reads without keys or broadcasts. Replace placeholders with genuinely independent operators; names and distinct URLs do not prove independence. Retain outage/disagreement, selected-chain recovery and funded evidence for the actual deployment separately.

Required Gates

Independent Audit

Audit scope must include:

• transaction signature scope selection, per-signature digest verification, and protection of unsigned fields by other signatures and covenant guards;

• exact transaction verification, replay protection, and finality policy;

• hash-chain grant confidentiality and assignment, one-time key exposure, abandoned grants, accepted owner rotation, and reorg recovery;

• singleton KIP-20 genesis, stable covenant-id derivation, current-outpoint tracking, and pruning-safe genesis evidence;

• batch voucher, claim, top-up, and refund paths, including A/S/T/V/R invariants, signed-int64 limits, and claim fee topology;

• payment-identifier, channel state, concurrency, and crash-safe transition attempts;

• client funding-source policy, facilitator capability intersection, live adapter recovery, operator key handling, transport resource budgets, and distributed admission controls.

Audit output must include explicit pass/fail status for exact and batch-settlement. A Testnet-10-only pass is not sufficient for mainnet.

Consensus Cross-Validation

The transaction-v1 vectors for batch genesis, claim, top-up, and refund must be cross-validated against the configured Kaspa consensus checkout:

KASPA_X402_KASPA_CONSENSUS_ROOT=<rusty-kaspa-checkout> npm run validate:tx-v1-consensus

Cross-validation must prove the singleton transition shapes:

• genesis creates exactly one transaction output, the expected covenant;
• claim consumes one same-ID input and creates one same-ID successor;
• top-up consumes one same-ID input and creates one same-ID successor; and
• refund consumes one same-ID input and creates no same-ID successor.

The recorded validation level must be refreshed whenever consensus code, transaction serialization assumptions, covenant state, fixture scripts, fee policy, or compute-budget assumptions change.

Recorded offline validation (2026-09-30): Rusty-Kaspa 2.1.0 at 01b532e8b553523216471682649693af92f0fd16, using a clean checkout and the committed consensus harness lockfile. The full TransactionValidator accepted all five batch tx-v1 vectors, exact standard-native and additive profiles, KIP-10 continuation, and the hash-chain genesis, borrow, rotation, recovery, top-up, and sweep paths. The batch guard matrix rejected ten signed invalid transitions and accepted its three controls; the existing exact and hash-chain negative cases also passed. Regenerated batch, exact, and hash-chain vectors changed only source provenance, preserving transaction bytes, IDs, covenant IDs, fees, mass, and compute-budget evidence.

Harness JSON reports the actual checkout commit and consensus package version, plus whether the source has local or hidden changes. The default launcher requires the exact clean pin; --allow-different-source is an explicit experimental override. Fresh funded Testnet-10 validation and the remaining mainnet gates are separate requirements.

Independent Chain Evidence

Mainnet must not trust one node, endpoint, RPC provider, or commonly operated endpoint set for acceptance, UTXO, permanent-absence, or selected-chain lineage decisions. The deployment must use independently corroborated evidence or another audited Byzantine-resilient design, document source independence and disagreement policy, and fail closed whenever required sources are unavailable or disagree. Endpoint failover alone does not close this gate.

Durable State

Production deployments must use durable transactional server and client stores. The server store must satisfy docs/server-store-contract.md, and servers must use a shared lock manager satisfying docs/server-runtime-lock-contract.md. In-memory stores are not acceptable for mainnet.

The store must preserve stable covenantId, current outpoint, A/S/T/V state, voucher evidence, and unresolved transition attempts across process loss. KIP-20 does not provide covenant-id reverse lookup, so genesis and every accepted successor must be recorded from verified transaction evidence.

It must also preserve the immutable source/compiler/bytecode/ABI launch manifest, append-only accepted and removed lineage events, and selected-chain checkpoint. The current head must be derived atomically from those records. Recovery must process removals before additions and fail closed across pruning, missing predecessors, branches, or wrong covenant bindings. The current Testnet-10 reference threshold is 30 confirmations; choosing and validating a mainnet threshold remains an explicit independent-audit and operations gate.

The client ChannelStore must durably reserve the exact signed refund and its deterministic transaction id before broadcast. A send exception or broadcast-only result must block another refund until a trusted RefundReconciler proves that exact transaction accepted or confirmed. Accepted application must atomically compare the captured head and mark both the channel refunded and the attempt applied; unknown, mismatched, or stale evidence fails closed without rebroadcast.

Distributed Admission And Resource Bounds

Every production topology must enforce active-attempt, byte, and per-payer limits across all processes and Worker isolates that share a trust domain. Process-local counters are insufficient. The reference Worker uses renewable leases from its single named GatewayState Durable Object; other hosts need an equivalent transactional admission service. The chosen topology must be tested under concurrent cross-instance load before mainnet enablement.

Facilitator bodies and remote chain reads must have whole-operation resource budgets. These include streamed byte and JSON-structure limits, finite body deadlines and caller aborts, plus cumulative selected-chain byte, block, page, and remote-operation bounds. Limit breaches, disagreement, and partial or non-converging lineage must fail closed.

Operational Recovery

Operators need tested recovery procedures for:

• standard-native exact conflicts and additive-head advancement conflicts;
• singleton batch genesis verification before pruning or history loss;
• concurrent or uncertain claim, top-up, and refund broadcasts;
• node/indexer outage handling and current-outpoint lineage reconstruction; and
• adapter crash recovery without reopening a spent head or double-executing protected work.

Live Evidence

Before any mainnet release candidate, a fresh funded kaspa:testnet-10 run must pass:

npm run proof:live:check -- --live --write-report

The sanitized report in docs/live-testnet-report.md must show tiny and normal standard-native exact settlement, additive exact-delta head advancement, multiple heads, one-winner conflict with unresolved losers held pending, exact replay and invalid-signature rejection, post-broadcast recovery, and trusted external reconciliation.

For batch settlement it must show verified singleton genesis, multiple lifetime vouchers across at least one outpoint rotation, claim fee accounting, top-up, concurrent-transition rejection, crash recovery, replay rejection, and terminal timeout refund. Every successor must preserve the expected stable covenantId and state, while the durable current outpoint advances.

Release Controls

Mainnet enablement requires explicit configuration and the deployment-specific audit, durable stores, live evidence and recovery procedures above. The SDK release and its Testnet evidence do not certify those operator choices. Hosted demo services remain Testnet-only; publishing the SDK does not deploy them.

Source: /docs/mainnet-readiness.md