Module virtual_state 

Account Virtualization.

Virtual state lets protocols model logical state that spans multiple Solana accounts. Use cases:

• Protocol state larger than the 10 MiB account limit
• Sharded systems (order books, AMM pools, registries)
• Multi-account logical entities (e.g. a “Market” = OrderBook + Pool + Config)

How It Works

A VirtualState maps N logical slots to physical accounts in the instruction’s account array. At runtime it provides unified typed access across all constituent accounts.

+--------------+  +--------------+  +--------------+
|  Account 0   |  |  Account 1   |  |  Account 2   |
|  MarketCore  |  |  OrderBook   |  |  PoolState   |
+------+-------+  +------+-------+  +------+-------+
       |                 |                 |
       +-----------------+-----------------+
                         |
               +---------v---------+
               |  VirtualState     |
               |  "Market"         |
               |  - core: 0        |
               |  - orders: 1      |
               |  - pool: 2        |
               +-------------------+

Usage

// Define the virtual mapping
let vstate = VirtualState::<3>::new()
    .map(0, CORE_IDX)     // slot 0 -> account CORE_IDX
    .map(1, ORDERS_IDX)   // slot 1 -> account ORDERS_IDX
    .map(2, POOL_IDX);    // slot 2 -> account POOL_IDX

// Read from any slot through the virtual view
let core = vstate.overlay::<MarketCore>(accounts, 0)?;
let book = vstate.overlay::<OrderBook>(accounts, 1)?;

Structs

ShardedAccess

A sharded collection that distributes entries across multiple accounts.

VirtualSlot

A mapping from virtual slot index to account index.

VirtualState

A virtual state assembly mapping N slots to accounts.