Best practices

The page explains operational recommendations for AMP2 issuer integrations in production.

Operational recommendations for running AMP2 issuer integrations in production.

The SDK packages (@blockstream/cryptic, @blockstream/amp-registry, @blockstream/ecs-registry) and your private keys (RSA, ECDSA) must never be exposed in browser code, mobile apps, or any client facing environment. All AMP2 operations should run from a trusted backend service.

Rotate keys regularly

Use POST /auth/change-keys to rotate RSA and ECDSA key pairs on a regular schedule (e.g., quarterly, or after any personnel change). Test rotation on testnet first. See Key Management.

Separate environments completely

Use different key pairs for testnet and mainnet.
Use different invite data and server URLs.
Never share credentials, keys, or configuration between environments.
Use environment variables or a secret manager. Never hardcode keys in source.

Reliability

Implement idempotency for PSET pipelines

The PSET flow (request → sign → cosign → broadcast) is a multi step pipeline. If a step fails mid way:

Do not retry the original PSET: UTXO state may have changed.
Request a new PSET and start the pipeline fresh.
Broadcasting is safe to retry: the Liquid Network rejects duplicate transactions.
Track pipeline state in your application (e.g., pset_requested, signed, cosigned, broadcast, confirmed).

Persist mapping tables

Maintain local records of:

Data	Why
Asset IDs	Map to your internal asset catalog
Wallet IDs (WIDs)	Map to investor identities in your CRM
Restriction group IDs	Track policy history for audit
Transaction IDs	Reconcile with on chain state

Handle transient failures

Use retry with exponential backoff for network errors.
Distinguish between transient errors (network timeout, 503) and permanent errors (403 forbidden, policy violation).
Set timeouts on SDK calls. COSE encryption adds processing overhead.

Compliance and audit

Log everything

AMP2 does not provide a built in audit log. Build one in your issuer systems:

Record every API call with timestamp, operator, parameters, and result.
Log restriction changes (create, delete) with the old and new policy state.
Log lock/unlock operations with the reason and authorizing operator.
Log all PSET pipeline state transitions.

Reconcile regularly

Compare AMP2 asset balances with your internal accounting on a regular schedule.
Compare AMP2 wallet state with on chain data from Esplora/Waterfalls.

Error handling catalog

Error pattern	Typical cause	Recommended action
`401 Unauthorized`	Expired or invalid bearer token	Refresh token and retry
`403 Forbidden`	Asset permission check failed	Verify you own the asset
`404 Not Found`	Asset or wallet does not exist	Check IDs
PSET cosign refused	Restriction policy violation	Check whitelist and lock states
Broadcast rejected	UTXO already spent (race condition)	Request a new PSET
Network timeout	Connectivity issue	Retry with backoff

Next steps

Monitoring: endpoint reference for operational tracking