Sign in

Composing programs in practice

Suggest an edit

When a program calls a program that calls another program, every account any of them touches has to be listed in the one transaction the client sends. The list grows with each layer and each pool, and the whole transaction has to fit in 1,232 bytes.

The outer transaction lists the accounts of every layer

Take an aggregator program that calls a swap program, which in turn calls the Token Program.

Aggregator calls Swap calls Token Program: three CPI layers, 10 accountsThree stacked layers show Aggregator calling Swap via CPI, and Swap calling the Token Program via CPI. Each layer lists its handler and accounts, with a running total that reaches 10 distinct accounts needed in the outer transaction. A worked example: Aggregator → Swap → Token Program Layer 1: Your Aggregator program (the outermost call) handler: aggregate_swap(amount, route) accounts it needs: user (Signer), aggregator_state, fee_account + everything the inner Swap needs (passed through) running total: 3 of its own, more to come CPI to Swap Layer 2: Swap program (called via CPI) handler: swap(amount_in, min_out) accounts it needs: pool_state, pool_authority (PDA), user_in_ata, user_out_ata, pool_in_ata, pool_out_ata running total: 3 + 6 = 9 accounts CPI to Token Program Layer 3: Token Program (does the actual transfers) two transfers: in (user→pool) and out (pool→user) accounts: the four token accounts above + Token Program ID itself running total: 9 + 1 (Token Program) = 10 accounts Three nested calls. Ten distinct accounts that all must appear in the outer transaction.

When the user signs a transaction calling your aggregator's aggregate_swap handler, they have to supply every account the call will touch. In practice this work is done by the user's frontend constructing the transaction, but the principle is the same: every account that any layer of the call will read or write has to be in the outer transaction's accounts list.

The aggregator needs three accounts of its own: the user's wallet as signer, the aggregator's state, and its fee account. The swap needs six more: the pool state, the pool authority PDA, the user's ATAs for the input and output tokens, and the pool's two ATAs. The Token Program moves tokens between the four token accounts already on the list and adds one entry, its own program ID. Those are the ten accounts in the diagram, and the frontend has to know all ten before it sends anything.

Your aggregator handler receives all of these in its own ctx.accounts. It picks out the ones the swap needs and assembles them into a CpiContext for the swap CPI. The swap handler receives them, validates them with its own constraints, picks out the four token accounts plus the pool authority, and assembles its own CpiContext for the Token Program CPI. The Token Program receives a strict subset, executes the transfer, and returns.

None of the inner programs ever requests accounts dynamically. They expect specific accounts in specific positions, and the caller supplies them, so the outermost caller has to know them all. That's the trade Solana made for determinism and parallelism: every account is named explicitly up front, so the runtime can schedule transactions safely without surprise dependencies.

A two-DEX route needs 27 accounts, and about 35 fit

Three layers and ten accounts is a toy example. Consider a user who swaps USDC for BONK through SOL, with the aggregator sending half of the trade through Raydium and half through Orca to get better pricing.

Aggregator swap of USDC to BONK via Raydium and Orca: 27 accountsA user swaps USDC for BONK routed through SOL, split half through Raydium and half through Orca. Listing every user, aggregator, pool, mint, and program account needed gives 27 accounts, close to the roughly 35-account cap for legacy transactions. A real aggregator transaction: the accounts list balloons scenario: user wants to swap USDC for BONK, routed through SOL aggregator splits the trade across two AMMs: half through Raydium, half through Orca two pools, three tokens, two-hop routing per leg the accounts the transaction has to carry user-side: 1. user wallet (Signer) 2. user USDC ATA 3. user SOL account 4. user BONK ATA aggregator: 5. aggregator program 6. aggregator state PDA 7. aggregator fee account Raydium leg: 8. raydium program 9. pool USDC/SOL state 10. pool USDC vault 11. pool SOL vault 12. pool authority PDA 13. pool SOL/BONK state 14. pool SOL vault (2nd) Orca leg: 15. orca program 16. pool USDC/SOL state 17. pool USDC vault 18. pool SOL vault 19. pool authority PDA 20. pool SOL/BONK state 21. pool BONK vault tokens involved: 22. USDC mint 23. wSOL mint 24. BONK mint required programs: 25. SPL Token Program 26. Associated Token Program 27. System Program 27 accounts. Legacy transactions cap at around 35 accounts due to a 1232-byte total size limit. Add one more hop or one more pool, and the transaction stops fitting. This is the wall that versioned transactions and ALTs were designed to break.

The list has four accounts on the user's side, three for the aggregator, seven for each DEX leg (the DEX program, the pool states, the pool vaults, and the pool authority PDA), three mints, and three shared programs: 4 + 3 + 7 + 7 + 3 + 3 = 27. Twenty-seven accounts is the conservative count for a relatively simple two-leg aggregator route. Real Jupiter-style routes that pass through three or four DEXes on the way to an exotic token easily exceed forty distinct accounts.

Each transaction has to encode every account address, each one 32 bytes, plus the instruction data, plus signatures, plus the message header. The 27 addresses of this route take 864 bytes. A transaction is capped at 1,232 bytes for the entire payload. In the original (legacy) format, where every address is written out in full, that works out to about 35 accounts in the best case, less when the instruction data is anything other than trivial.

For a long time, this ceiling shaped what protocols could release. Aggregators had to split routes across multiple transactions. Composite operations that should logically happen atomically got broken into pieces with intermediate state. Anything that wanted to compose more than two or three layers of programs could not fit in a single transaction.

Versioned transactions with address lookup tables raise the ceiling without any change to programs: a transaction refers to an account by a 1-byte index into a table stored on chain instead of its 32-byte address. The next lesson covers the format in detail.

The layers also share a compute budget and a depth limit, and any of them can be upgraded

The CU limit belongs to the transaction, and every operation in every layer is counted against it (transaction fees and compute units). If the aggregator, the swaps on both DEXes, and the Token Program transfers together pass the limit, the whole transaction reverts, whichever layer was running at that moment.

The depth of a call chain is limited to four levels (CPI lesson). Aggregator, swap, and Token Program already use three.

Each layer is also code that someone else can replace. A program keeps its address when its upgrade authority deploys new bytecode, so the swap your aggregator calls today can run different code tomorrow, with the signers and writable accounts your handler forwards to it. The program upgrades lesson covers who can do that and how to check.

Every account your instruction requires costs your integrators 32 bytes

If other programs will call yours, your instruction's accounts list becomes part of their callers' transactions, next to the accounts of every other program on the route. The 27-account route above leaves room for about eight more addresses in a legacy transaction at best, and for fewer once instruction data is counted, so an instruction that brings fifteen new accounts cannot be added to it. A lookup table shortens an address to one byte only if someone has put that address into a table ahead of time.

Before you publish an instruction that other programs will call, count the accounts it requires and ask of each one whether the instruction can work without it.