State Machine

9-state sovereign lifecycle with transitions, failure branches, and terminal states.

State Diagram

Bonding ──→ Finalizing ──→ Recovery ──→ Active
  │                           │            │
  ▼                           └──→ Unwinding ←┘
 Failed                              │   ↑
                                     ▼   │ (threshold met)
                                   Unwound ──→ Retired

 Any* ──emergency_unlock──→ Halted ──→ Retired

 * except Halted or Unwound

All states are encoded in SovereignStatus.

States

#	State	Description
1	Bonding	Collecting SOL deposits, creator escrow, and token setup.
2	Finalizing	Bond target met. Pool creation in progress.
3	Recovery	Post-launch. 100% of swap fees go to LPs until principal recovered.
4	Active	Normal operations. Fees split between LPs and creator.
5	Unwinding	Governance or emergency unwind initiated. Pool draining.
6	Unwound	Pool drained. LPs can claim their share of GOR.
7	Failed	Bond did not reach target within deadline.
8	Halted	Emergency halt by protocol authority. Terminal — can only transition to Retired.
9	Retired	Terminal state. All claims processed. Sovereign is closed.

Phase Behavior

Each phase gates a specific set of operations. Derived from on-chain constraints.

Bonding

▸LPs deposit or withdraw SOL toward the bond target
▸Creator posts escrow and configures token parameters
▸Transitions to Finalizing when target met, or Failed on deadline
✕No NFTs, governance, or swaps — engine pool does not exist yet

Finalizing → Recovery

▸Engine pool created and wired via CPI
▸Bin arrays allocated and populated
▸Liquidity permanently locked — no LP withdrawal from pool
▸Transitions directly to Recovery

Recovery

The sovereign is fully operational — swaps, NFTs, and governance are all live. The only difference from Active is fee routing: LPs receive 100% of swap fee revenue until their principal is recovered.

▸Fees: 100% of swap fees flow to LPs after bin share — creator receives zero revenue
▸Swaps: Buy and sell are live — engine pool is in Trading status
▸NFTs: LP positions can be minted as NFTs, listed, and traded on the marketplace
▸Governance: Unwind proposals can be created, voted on, and finalized
▸Transitions to Active when LP recovery threshold met, or to Unwinding if governance vote passes

Active

Identical to Recovery in terms of allowed operations. The only change is how fee revenue is split.

▸Fees: Revenue split between LPs and creator per the configured creator share
▸Swaps: Buy and sell continue as normal
▸NFTs: Mint, list, buy, delist, burn — full marketplace
▸Governance: Unwind proposals, voting, and finalization
▸Transitions to Unwinding if governance vote passes

Unwinding

Governance vote passed. Engine enters an observation period to determine if the unwind proceeds.

▸Voting: Existing proposals can still be voted on and finalized during observation
▸Fee claims: LP and creator fee claims remain available
▸NFT burns: Holders can convert NFTs back to deposit records
✕No new governance proposals
✕No new NFT mints or listings
▸If observation volume threshold is met → reverts to Active (unwind cancelled)
▸Otherwise → engine pool drained, GOR returned to vault → Unwound

Unwound

Engine pool is drained. How the returned GOR is distributed depends on the sovereign type.

▸LPs claim their pro-rata share of returned GOR minus unwind fee in both types
▸NFT holders can still burn back to deposit records to claim

TokenLaunch

▸Any GOR surplus above LP principal goes to a token redemption pool
▸External token holders can redeem tokens for their pro-rata share of that pool within 30 days
▸Unsold tokens in the vault are returned to the creator
▸Creator receives zero surplus GOR — it all goes to token holders

BYO Token

▸Any GOR surplus above LP principal goes to the creator
▸No token redemption pool — external token holders cannot redeem
▸Remaining tokens in the vault are returned to the creator
▸BYO tokens are assumed to trade on external markets — the design assumes holders have other liquidity options

Unwound → Retired is terminal — all accounts can be closed.

Failed / Halted / Retired

▸Failed: bond deadline expired without reaching target. Deposits refunded.
▸Halted: emergency halt by protocol authority. NFT burns still available so holders can reclaim deposit records.
▸Retired: terminal. All rent-bearing accounts can be closed and recovered.
▸All three are terminal — only path out is Retired (or Halted via emergency unlock for Failed)

Halted — TokenLaunch

Token holders can still redeem tokens for GOR via the emergency redemption path, same pro-rata formula as governance unwind.

Halted — BYO Token

No token redemption. Creator claims remaining tokens and any surplus GOR once LPs have claimed their principal via the emergency withdrawal path.