State Versioning#
Seesaw uses a drain-by-cadence policy for account layout changes. Most market state is short-lived: markets have bounded durations, a bounded expiration window, and a close path that reclaims market-scoped rent after liabilities drain. That means not every layout change needs an in-place migration framework.
Account Classes#
| Class | Examples | Versioning policy |
|---|---|---|
| Global long-lived | ConfigAccount | Requires explicit migration or backward-compatible reserved fields |
| User/referral long-lived | ReferralAccount, ReferrerEarningsAccount | Requires explicit migration or new account family |
| Catalog/asset long-lived | Asset/catalog metadata when present | Requires explicit migration or new account family |
| Market-scoped | MarketAccount, orderbook, trader ledger, vault-adjacent metadata, YES/NO mints and escrows | New layout applies to newly-created markets only unless a specific rescue migration is approved |
| Per-user-per-market | Positions and market-local trader-ledger seats | Drains with the parent market; new layout applies to newly-created markets only |
Policy#
Market-scoped account layout changes should ship as new-markets-only changes by default. Existing markets continue with their original layout until they resolve, settle, and close. Frontends, SDKs, and indexers must support all live market layouts during the overlap window, but the overlap is bounded by cadence and close latency.
Only long-lived account families need standing migration paths. Today that means the config account and referral/accounting families. If an asset/catalog account family becomes long-lived, it joins this set.
Use an in-place migration instruction for market-scoped accounts only when all of these are true:
- a live-account bug cannot wait for natural market drain;
- the migration preserves user liabilities and settlement eligibility;
- historical fixtures cover every deployed layout that may be touched;
- old and new instruction behavior is pinned before activation;
- the governance proposal names why new-markets-only rollout is insufficient.
Operational Consequence#
Launch changes to market shape should prefer:
- add new account fields in reserved space when already present;
- create only new markets with the new layout;
- stop first-party creation of old-layout markets;
- let old markets drain and close;
- remove old-layout support only after indexer/API evidence shows no live accounts remain.
This keeps migration work proportional to genuinely long-lived state instead of turning every market experiment into a broad migration framework.