Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Going to production · Boson Protocol
Skip to content

Going to production

You've built a thing on staging. Before you flip configId from staging-* to production-*, walk this list.

Security

  • Private keys in a managed signer (KMS, Vault, Fireblocks, Privy, Turnkey). Never in env vars on a long-running host.
  • Smart account for sellers, ideally with a session key for the assistant role.
  • Restricted RPC API keys — at least to your server's IP range.
  • Per-environment ConfigId — process.env-gated, not hardcoded.
  • HMAC-signed webhook payloads for your fulfillment endpoints.
  • CSP allowlist for widget embeds (script-src https://widgets.bosonprotocol.io).

On-chain hygiene

  • Verify contract addresses against the official Contract addresses table before any integration.
  • Read protocol.pausedRegions() before a call. Treat a paused region as a transient failure.
  • Subscribe to facet upgrade events. Subscribe to the Diamond's DiamondCut event so you know when the protocol is upgraded under you.
  • Pin SDK and contract ABI versions to the same release tag.
  • Monitor your wallet's gas balance. Drain alerts at 0.5×, 0.2×, 0.1× the expected daily burn.

Operational

  • Idempotent writes. Every state-changing call keyed on (exchangeId, target state) or a request ID.
  • Subgraph lag handled. waitForGraphNodeIndexing on every read-after-write path. See Eventing & indexing.
  • Reorg handling. 2–3 confirmations on L2s, 12+ on Mainnet, before treating a state change as final.
  • Rate-limit Biconomy / facilitator calls. Have a fallback for when the relayer is down.
  • Persist webhook events with (txHash, logIndex) as the dedupe key.
  • Health-check the subgraph. Alert if its head-block falls more than ~20 behind chain head.

Money

  • Withdrawals are not automatic. Schedule a job to call withdraw_funds periodically or on a balance threshold.
  • Test the full state machine on a real exchange before flipping to production. Including a dispute path.
  • Document who has admin keys for the seller and how to rotate them. This is a real fire drill.
  • Calculate effective fee, gas, and FX exposure per exchange. Use Networks → Supported tokens for fee tables.

Observability

  • Log every tool call with an exchangeId. Indexable, searchable, replayable.
  • Dashboards: open exchanges, redemption rate, dispute rate, time-to-completion, gas spent.
  • Alerts: dispute raised, exchange disputed > 1 day, wallet balance low, subgraph stale.
  • Tracing across SDK → RPC → relayer → chain → subgraph for one canonical request.

Code

  • No console.log of private keys, signatures, or full transaction objects. Easier to leak than you think.
  • Catch and surface tx revert reasons. Use sdk.parseError() or decode against the merged ABI.
  • Type-check SDK + MCP call sites (Twoslash in docs is your friend during integration).
  • End-to-end smoke test that runs against production every release, using a known test offer.

When something breaks