Composing programs in practice
Suggest an editWhen 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.
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.
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 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.