1. Asset registry
Approved chains, contracts or mints, standards, decimals, authorities, capabilities, metadata rules, and confirmation policy.
Documentation map
Build from responsibilities, not endpoints alone.
2. Operation model
Idempotency, normalized intent, immutable request fields, states, failure codes, transaction evidence, and audit history.
3. Policy engine
Tenant access, recipient rules, supply and batch limits, business uniqueness, approvals, and emergency disablement.
4. Signing boundary
Decoded transaction allowlists, key custody, independent authorization, per-key limits, and break-glass controls.
5. Chain adapters
EVM nonces and receipts; Solana accounts, blockhashes, and commitment; NFT IDs and metadata evidence.
6. Delivery
Polling, signed webhooks, event deduplication, reconciliation, support views, and corrective state transitions.
Minimal implementation sequence
Start with one asset and one complete path.
A thin vertical slice should use production-like configuration and signing even when it runs on a development network.
- Verify the deployed contract, program, or mint account.
- Register immutable identity and reviewed capabilities.
- Implement create and retrieve operation resources.
- Add idempotency and business uniqueness constraints.
- Integrate a constrained signer and one chain adapter.
- Confirm, reconcile, and deliver signed events.
# 1. Create one approved asset configuration
asset_id: rewards-usd-v1
network: solana-devnet
standard: spl
mint: 9xQe...WmA
program: token-program
# 2. POST a mint operation with an idempotency key
# 3. Store the returned operation ID
# 4. Poll GET /v1/mints/{id} or verify signed webhooks
# 5. Reconcile chain evidence before fulfilling downstream workArchitecture quickstart. Replace example values and apply your own authentication, authorization, and signing policy.
Core resources
Keep public objects small and durable.
Asset
A reviewed token definition: network, standard, contract or mint, decimals, authority policy, capabilities, metadata model, and status.
Asset fields →Mint operation
The immutable business intent, operational state, transaction evidence, reconciliation result, and timestamps for one logical issuance.
Operation fields →Webhook event
A signed, deduplicable delivery of an operation state transition with a stable event ID and timestamp.
Webhook fields →Status semantics
Publish what the service knows.
| Status | Meaning | External side effect |
|---|---|---|
accepted | The request and idempotency mapping are durable. | No signature or transaction is implied. |
signing | Policy passed and a restricted signing request is in progress. | A transaction may not yet exist. |
submitted | A transaction identity is recorded and broadcast was attempted. | The network outcome can still be unknown. |
confirmed | The configured network evidence is present. | Reconciliation may be complete or represented separately. |
failed | Evidence proves the operation cannot produce the intended effect. | A new request may be allowed only under policy. |
needs_review | The result is ambiguous or reconciliation does not match intent. | Automatic reminting is blocked. |
Test contract
Prove recovery, not only success.
Test concurrent idempotent requests, worker crashes after every stage, provider timeouts, signer denial, transaction replacement or expiry, reorganization, metadata mismatch, and webhook replay.
Build from explicit contracts
Use the reference architecture as a starting point.
Define assets, authorities, idempotency, confirmation, and reconciliation before connecting a production signer.