Upgrade & compatibility

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

Decision

Choice	Status
Account-model fungible-token v0.1 wallet API	Current public token surface
F1 — in-place chaincode sequence upgrade	Supported playbook
F2 — Panurus migration	Deferred — not required for v0.1 integrators
REST paths + error envelope	Stable across F1 upgrades

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.
2. Roll peers with sequence upgrade (Chain Deploy / Fabric lifecycle).
3. Verify /health/ready and a smoke call (GET /api/tokens/stats, small asset sync).
4. Watch SLIs (error%, p95) for regressions.

Clients that only call documented REST routes should not need code changes for a compatible F1 upgrade.

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 Fabric internals.