Architecture

Two-program model, CPI boundaries, and PDA derivation.

Two-Program Model

Sovereign Liquidity Protocol is split into two on-chain programs that communicate via cross-program invocation (CPI):

Users / Clients
       │
       ▼
sovereign-liquidity   (authority + lifecycle)
       │ CPI
       ▼
sovereign-engine-v3   (pool math + swaps + bins)

Program	Responsibilities
sovereign-liquidity	Protocol config, sovereign creation, deposit/withdraw, governance, unwind, emergency, NFT positions & listings
sovereign-engine-v3	Pool creation, bin array lifecycle, swap buy/sell, fee accounting, pause/drain/close

CPI Boundary

The liquidity program is the sole authority over the engine. All cross-program calls flow one direction — from sovereign-liquidity into sovereign-engine-v3:

▸Create and finalize pools
▸LP and creator fee claims
▸Pause, unpause, and drain operations
▸Fee parameter updates
▸Reconciliation and account close flows

PDA Model

Both programs derive accounts using Program Derived Addresses (PDAs) with deterministic seeds.

Sovereign Liquidity PDAs

Seeds defined in constants.rs:

protocol_statesovereigndeposit_recordproposalvote_recordnft_positionnft_listingsol_vaulttoken_vaulttoken_mint

Engine PDAs

Account	Seeds
EnginePool	['engine_pool', sovereign]
BinArray	['bin_array', sovereign, page_index]
EngineLpClaim	['engine_lp_claim', pool, depositor]
engine_gor_vault	['engine_gor_vault', sovereign]

BinArray Allocation Flow

Bin arrays are allocated incrementally due to Solana account size constraints. The extend_bin_array instruction grows the account by up to 10,240 bytes per call.

prepare_bin_array  →  extend_bin_array (repeat)  →  allocate_bin_page

Sovereign Types

TokenLaunch

Protocol creates a Token-2022 mint. Full lifecycle from bonding through active trading.

BYOToken

Creator supplies an existing mint and token deposit. Advisory flags surface warnings for active mint/freeze authority.