Crypto payments & custody
Crypto stays available when its independent readiness gates are healthy. New direct deposits and x402 can be stopped separately without disabling receipt reconciliation, customer billing reads, or sweep reconciliation.
Production gate
Section titled “Production gate”Run the structured report before enabling or restoring either path:
frameworks crypto readiness --output jsonAfter deploying Gateway/Commodore changes, also verify that public wallet onboarding is not behind an authentication or payment wall:
frameworks crypto smoke --base-url https://bridge.frameworks.network --output jsonThe smoke command checks published wallet/x402 metadata and issues an expiring challenge for a fixed non-customer address. It does not sign or consume the challenge, create an account, use a customer wallet, or move funds.
Production eligibility requires the HD watch-only xpub, configured finalized heads and healthy scanner cursors, the embedded x402 v2 exact facilitator, complete supplier identity/registration/country configuration, effective VAT rates, non-zero treasury addresses, and dedicated gas-only relayers. The live report also proves the x402 and sweep-relayer accounts can fund at least one transaction at the current bounded fee ceiling.
An absent gate keeps the affected method hidden/fail-closed. It is not a warning that operators may ignore.
Emergency controls
Section titled “Emergency controls”CRYPTO_DEPOSITS_ENABLED=falsestops new direct-deposit addresses.X402_PAYMENTS_ENABLED=falsestops new x402 quotes and settlement.
Keep the scanner and reconcilers running. A provider/RPC timeout is an unknown outcome, never proof that settlement failed; retries use the persisted quote, authorization nonce, provider transaction, and mutation-result records.
Operator review queues
Section titled “Operator review queues”purser.crypto_accounting_anomalies holds conditions that cannot be repaired
safely from RPC state alone, including a consumed USDC authorization without a
recoverable transaction hash and a late settlement with no matching ledger
reversal. Readiness reports
the unresolved count. Never “resolve” an item by editing a balance or settlement
row; use an audited compensating operation backed by canonical evidence.
Reorg behavior
Section titled “Reorg behavior”Credits are issued only after consensus-labelled finality and a canonical block hash check. Allocated deposits continue to be rechecked. A later canonical mismatch reverses prepaid credit, reopens/claws back invoice allocation, creates a linked credit note where a customer document exists, and lets ordinary prepaid admission block on the resulting balance. There is no paid-request bypass.
Customer records and retention
Section titled “Customer records and retention”Authenticated document downloads are available through
/v1/billing/documents. Purser tenant-scopes every invoice, simplified invoice,
confirmed-payment receipt, and credit note, renders only persisted evidence, and
returns an integrity hash. Database deletion guards retain these source records
for at least ten years. Confirmed top-up is the VAT tax point; each document
records the effective rate source and customer location. New instructions retain
an immutable exclusive-crypto-advance-v3 assessment with the supplier/customer
identity, accepted treatment, location evidence, and the VIES proof actually
used. Gross payment and net service credit are distinct; a EUR 100 net advance
with 21% VAT collects EUR 121. Effective rates are retained at the tax point.
Changing a billing profile, supplier configuration or
VIES availability cannot erase an already-received payment’s document.
New instructions require a billing country and a personal/business classification (a submitted VAT claim also identifies a business claim). Personal profiles need no company name or VAT number. Business profiles and payments over EUR 100 require a full invoice identity. Older quotes settle under their versioned legacy rules; non-EU legacy treatment is explicitly marked for review, not reused to authorize new quotes.
Late receipts retain their accepted payment and tax evidence; missing or
unusable proof is retained for review rather than silently changing the claim.
Expired or revoked evidence is marked
CRYPTO_TAX_REVIEW_REQUIRED in the financial audit. The original quote assessment
and confirmation evidence remain available for correction review.
The Dutch supplier service policy charges Dutch VAT to Dutch customers and EU consumers. EU business reverse charge requires validated VAT evidence. Non-EU services state that Dutch VAT is outside scope. National numbers and Greek GR/EL prefixes are normalized before validation. Invalid claims or unavailable verification are returned before a new purchase is accepted. The recurring collection fallback and operator review workflow are described in Billing financial evidence. These checks supplement the global crypto readiness report.
Custody and sweeping
Section titled “Custody and sweeping”Purser is watch-only. Automatic hot-wallet sweeping is deliberately out of scope. Operators use:
frameworks crypto sweep plan --network base --out manifest.json --persistframeworks crypto sweep sign --manifest manifest.json --out signed.json \ --treasury-allowlist treasuries.json --secret-fd 3 \ --max-fee-gwei 5 --max-priority-fee-gwei 2frameworks crypto sweep broadcast --bundle signed.json --execute --ack <checksum>frameworks crypto sweep reconcile --batch-id <batch-id>frameworks crypto sweep release --batch-id <batch-id> --reason "expired ceremony"Signing is performed offline with an xprv supplied through a file descriptor and independent operator-selected fee ceilings. Broadcast rechecks chain, token, treasury, balance, nonce/authorization state, and fee bounds. Repeating broadcast replays the persisted transaction intent; it does not allocate another relayer nonce.
Release is dry-run by default. Execute only with --execute --ack <manifest-checksum> from the dry-run output. Canonically safe claims become
replannable; unresolved signed/broadcast claims are quarantined, never blindly
released.
To rotate the generated-address key, create a new account-external xpub offline, then run:
frameworks crypto wallet rotate --xpub-file new-deposit.xpub --network mainnetOnly future addresses use the new key. Historical addresses retain their original xpub and are planned in separate signing-key batches. Keep every retired xprv offline until no remaining sweep manifest uses it.
For the two-person evidence checklist, failure recovery, and incident-specific
procedures, use the repository runbooks docs/operations/sweep-ceremony.md and
docs/operations/crypto-incidents.md shipped with the same release.