Upgrade & compatibility

ADR (Early Access): Peer REST is the stable interoperability contract. Chaincode may evolve behind it; clients should not bind to ledger transaction internals.

Decision

Choice	Status
Account-model fungible-token v2.0 wallet API (multi-token; replaces v1 for new deploys)	Current public token surface
F1 — in-place chaincode sequence upgrade	Supported playbook (v1 → v2 on existing peers; default token keeps legacy keys)
F2 — Panurus migration	Deferred — not required for current integrators
REST paths + error envelope	Stable across F1 upgrades
Public token gateway (/token-gateway/*)	Current SaaS-builder surface (same REST shapes behind the gateway)

Current contract

• Tokens: account-model wallet ops documented in Tokens
• Assets: sync / query / get as in Assets
• Errors: { error: { code, message } } per Errors
• Auth: VPC + optional X-Api-Key per Authentication

OpenAPI on this portal tracks that public slice. Admin-only token routes may change without a partner notice window.

F1 — chaincode upgrade

Playbook: upgrade the installed chaincode version/sequence on the channel while keeping Peer REST routes and request/response shapes.

1. Build and approve the new chaincode package (e.g. fungible-token:2.0 for multi-token).
2. Roll peers with sequence upgrade (Chain Deploy lifecycle).
3. Verify /health/ready and a smoke call (GET /api/tokens/stats, small asset sync).
4. Watch SLIs (error%, p95) for regressions.

Multi-token (v2.0): the default token continues to use legacy state keys (token-network, wallet:{walletId}), so single-token networks remain byte-compatible with v1 and can roll back safely. Additional tokenIds use prefixed keys and are invisible to v1 (expected — v1 had no multi-token concept).

Clients that only call documented REST routes should not need code changes for a compatible F1 upgrade. SaaS builders on the public token gateway should prefer explicit /tokens/{tokenId}/… paths going forward.

F2 — Panurus migration (deferred)

Panurus is a future ledger / runtime migration path. It is out of scope for current Early Access integrators.

• No public timeline in these docs.
• When F2 is scheduled, expect a dedicated migration playbook (dual-write or cutover), not a silent REST break.
• Until then, do not block product work on Panurus readiness.

Compatibility rules

1. REST is the contract — not chaincode function names, endorsement policy, or private data collections.
2. Additive OpenAPI fields are non-breaking; removals or semantic changes to public routes require notice.
3. Admin routes (X-Admin-Api-Key) are exempt from the partner stability promise.
4. Prefer feature detection via documented error codes over probing ledger internals.