Solana bundle

A Solana transaction can run several program instructions in a fixed order and commit them atomically. Aomi calls that instruction set a Solana bundle. It compiles the bundle into one legacy or v0 VersionedTransaction, simulates the complete transaction, then routes signing and submission according to the wallet’s policy. On this page, bundle means the instructions inside one Solana transaction. It does not mean a Jito bundle of several independent transactions. Every instruction in an Aomi Solana bundle succeeds together or the transaction fails without committing any of them.

​

Bundle anatomy

A bundle combines the user’s connected wallet with one cluster and an ordered instruction list. The transaction format determines whether address lookup tables can be used. Compute-budget settings and a recent blockhash complete the transaction before it reaches a signer. The payer and cluster must remain consistent across every staged instruction. Aomi also preserves the original instruction order through assembly, simulation, and signing. It rejects a mixed payer or mixed cluster before producing transaction bytes.

​

Two build paths

Aomi supports an instruction path and a venue-transaction path. Both produce a single VersionedTransaction, but they differ in who supplies the transaction structure. Choose the path that matches the output of your App’s build tool. The instruction path uses svm_stage_ix, svm_simulate_ix, and svm_commit_ix. Staging gives each instruction a stable id. Simulation and commit resolve the same ids in the same order before compiling one transaction. The venue path uses svm_stage_tx, svm_simulate_tx, and svm_commit_tx. Aomi treats the staged VersionedTransaction as authoritative. It does not reconstruct the message from a simplified description or silently change the venue’s lookup tables and compute-budget instructions.

​

Execution lifecycle

The App stages either instructions or transaction bytes, then asks Aomi to simulate the complete transaction. At commit time, Aomi checks the wallet’s current signing policy and the App’s configured submission route. The selected signer authorizes the exact transaction bytes prepared for that route. The wallet route combines the signer and submitter in one wallet operation. The venue route separates them so an App can pass signed bytes to a protocol’s submission endpoint. The Aomi route requires delegated signing because the runtime cannot submit for a wallet that still requires an interactive prompt.

​

Instruction bundles

The instruction path works well when your App can identify each program call. You can stage raw instruction data or use supported semantic encoders. Aomi records the program id, account metadata, instruction data, payer, and cluster before assigning ids to the staged instructions. At simulation or commit time, you select legacy or v0 format and provide any address lookup tables. You can also set a compute-unit limit and priority price. If the instruction list already contains matching compute-budget instructions, Aomi preserves them instead of adding duplicates.

​

Venue-built transactions

Some protocol APIs return a complete serialized transaction rather than an instruction list. Aomi decodes that transaction and verifies that its fee payer matches the connected wallet. It preserves the message version, lookup tables, instruction order, and any compute-budget settings supplied by the venue. Venue-built transactions can keep their original blockhash when the protocol requires byte-stable signing and submission. A wallet-handoff flow may instead allow a refresh before approval. A pre-signed transaction must keep its original message because changing the blockhash would invalidate its signature.

​

Simulation

Aomi simulates the assembled transaction without submitting it to the cluster. The normal path uses LiteSVM with current program and account data. When a program loader is not supported locally, Aomi can use the configured cluster simulator. A program failure remains a failure and does not trigger a different simulator to search for a passing result. The result reports success or failure along with program logs and compute use. It can also return selected account state when the App requests it. These details help the App explain a failure and choose an appropriate compute budget before asking for a signature.

​

Signing authority

The connected wallet must be linked to the current Aomi account before a hosted commit can proceed. Aomi checks the wallet’s policy at commit time. A read-only thread, a locked wallet, an unbound address, or an address owned by another account produces no signature. Manual and client-held signing routes can surface additional signer addresses required by the transaction. The wallet client must collect those signatures alongside the payer signature. Delegated automatic signing currently supports only the common single-signer transaction because the provider grant controls the payer key alone.

​

Submission routes

The App declares which submission routes it permits and provides a default. The model forwards that decision when it stages or assembles the transaction. Aomi then reconciles the route with the wallet’s signing policy instead of letting the model choose a more permissive path. An automatic signer has no interactive wallet available, so a wallet route uses Aomi submission instead. A manual wallet cannot use the aomi route today. It must submit through the wallet or return signed bytes to the venue.

​

Blockhash and confirmation

An instruction bundle receives a fresh blockhash when it is committed. A venue-built transaction follows the preservation rule recorded when it was staged. This keeps byte-sensitive protocol flows intact while allowing a refreshable transaction to use a longer validity window. For Aomi submission, the runtime sends the signed bytes and monitors the transaction signature. The default target is confirmed, while an App can request processed or finalized. Aomi resubmits the same bytes while the blockhash remains valid because Solana identifies those attempts by the same signature. If a refreshable transaction expires, Aomi rechecks the delegated grant before attaching a new blockhash and requesting a new signature. A transaction whose bytes must be preserved cannot be rewritten after expiry. It ends with an expired status so the App can rebuild it from the original intent.

​

Guards

The instruction path exposes each program id and instruction discriminator to the App’s guard policy. This allows a guarded App to restrict writes to an approved cluster and a known set of program operations. Anything the guard cannot decode fails closed before signing. An opaque venue transaction cannot be inspected with the same instruction-level policy guarantees. A guarded App should use the instruction path when it needs program and discriminator allowlists. This gives up the convenience of a ready-made transaction in exchange for an auditable instruction bundle.

​

Current boundaries

A Solana bundle is atomic only inside one transaction. If an action requires several transactions, Aomi processes them separately and Solana confirms each one independently. A later failure cannot roll back a transaction that already confirmed. The connected wallet remains the fee payer, so this path does not currently provide separate Solana gas sponsorship. Delegated signing supports one required signature. A transaction that needs additional signers requires an interactive or key-holding client that can collect them. Interactive wallets must also submit through the wallet or venue route rather than handing signed bytes to Aomi for broadcast.

​

Related concepts