Transaction Builder

The Transaction Builder lets you create custom transactions and populate them with arbitrary instructions, enabling direct interaction with any program on Solana from your Squad. Use it for operations that don’t have a dedicated feature in the Squads app, such as interacting with custom Anchor programs, executing native Solana program instructions, or managing validators and stake pools.

​

What you can do with it

Most things a Solana transaction can do, as long as the Squad vault (plus any ephemeral signers) signs. The Squads program itself cannot be called from the Transaction Builder. Some common uses: A single draft can combine several instructions, from different programs, into one transaction that executes all of them together. For operations you repeat, enable Keep draft after initiation to reuse the draft. To inspect or reuse the instructions in other tools, select Export as base58. The export is the unsigned inner transaction, not the Squad proposal, so it cannot be executed on the vault’s behalf elsewhere.

​

How the Transaction Builder works

The Transaction Builder creates transaction drafts that you populate with one or more instructions before initiating. Each draft can contain multiple instructions targeting different programs, all executed as a single transaction. When you create a draft, you choose how to add instructions: through an Anchor program IDL, by specifying raw Solana program accounts and data, by importing a base58- or base64-encoded transaction, or by using a predefined template. Once your instructions are assembled, simulate the transaction to verify correctness, then initiate it for Squad approval.

​

Signers in Transaction Builder instructions

When building instructions that will execute from your Squad, the signer for your inner instructions must be the vault PDA (the vault address executing the transaction), not the multisig address. The Squads program signs on behalf of the vault during execution. Setting the multisig PDA as a signer will cause simulation to pass but execution to fail or hang indefinitely. The multisig PDA is a data account owned by the Squads program and cannot sign or pay for anything. If your instruction requires an additional signer beyond the vault (for example, a second keypair), use ephemeral signers. Ephemeral signers allow a derived keypair to be used for a specific transaction. To use one, mark the account as Ephemeral in the instruction form. Its address is computed at initiation. Alternatively, restructure your instruction so that only the vault needs to sign. You cannot have a random keypair sign a wrapped Squad transaction unless that keypair also signs during execution.

​

Create a transaction draft

​

Adding instructions: Anchor programs

1. Select Add instruction and select Custom transaction
2. In the Anchor tab, enter the Program ID and select Load IDL, or select Import local IDL to load the program’s IDL file (JSON, up to 3 MB)
3. Select the desired instruction from the list
4. Fill in the required accounts and parameters
5. Select Add instruction to add the instruction

​

Adding instructions: native Solana programs

1. Select Add instruction and select Custom transaction
2. Switch to the Solana tab (for programs written in native Rust without an Anchor IDL)
3. Enter the Program ID
4. Enter the account information (mark each account as Signer, Writable, or Ephemeral as needed) and select the data format (Buffer or Raw)
5. Select Add instruction to add the instruction

​

Adding instructions: base58 or base64 import

1. Select Add instruction and select Base58 / base64 import
2. Paste the base58- or base64-encoded transaction and select Decode
3. Review the decoded instructions and any address lookup tables
4. Select the Add instruction(s) button, which shows the number of decoded instructions, to add them to your draft

The import accepts legacy, v0, and v1 transactions in base58 or base64, so no conversion is needed. For a versioned transaction, the address lookup tables it references are fetched and added to the draft with the instructions.

​

Using predefined templates

Select a template when creating your draft to get a preconfigured instruction format:

• Token program: Transfer tokens and close token accounts
• Stake program: Authorize, delegate, split, merge, deactivate, withdraw, and move stake
• Vote program: Change withdraw authority, withdraw stake rewards, change validator commission, and change the block revenue or inflation rewards collector
• Stake Pool program: Set manager, staker, fees, and funding authority of stake pools

Fill in the required fields for the selected template and select Add instruction.

​

Simulate and initiate

1. Review your assembled instructions in the draft view
2. (Optional) Add Address lookup tables to reduce transaction size for complex instructions
3. Select Simulate to verify the transaction will execute correctly
4. Select Initiate transaction to submit the transaction for Squad approval. The draft’s Description is submitted as the note
5. Once the transaction reaches the threshold and is executed, the onchain interaction completes

You can enable Keep draft after initiation to preserve the draft for future reuse, or select Export as base58 to copy the transaction to your clipboard and share it externally.

​

Best practices

• Simulate before initiating. Simulations catch incorrect accounts, missing signers, and other instruction errors before the transaction enters the approval flow.
• Use Address Lookup Tables for complex transactions. Transactions with many accounts can exceed Solana’s size limits. Adding lookup tables compresses the transaction.
• Save reusable drafts. Enable Keep draft after initiation for transactions you expect to repeat, such as periodic validator operations.
• Verify program addresses. Confirm the program ID matches the official deployment before adding instructions. Interacting with the wrong program can result in lost funds.
• Use the vault PDA as the signer, not the multisig address, for all inner instruction accounts that require a signer.
• Account for Squads wrapping overhead when estimating transaction size. Keep inner transaction messages under approximately 1,000 bytes to avoid size errors.

Troubleshooting

Issue	Solution
Simulation fails	Incorrect accounts or parameters. Review instruction data and verify all account addresses are correct
Transaction too large	Too many accounts or too much instruction data. See Resolving transaction size errors below
Transaction too large (with Fee Relayer)	Fee Relayer adds extra bytes to the transaction. Disable the Fee Relayer, fund your SquadsX pubkey with SOL, and retry
IDL not loading	Program doesn’t publish an onchain IDL. Use Import local IDL to load the IDL file manually, or switch to the Solana tab for raw instruction input
Draft won’t initiate	No instructions added. Add at least one instruction before initiating
Simulation succeeds but execution fails (hangs at confirming)	Imported transaction had extra signatures that were stripped on import. Use ephemeral signers for instructions requiring a second signer, or restructure so only the vault signs
Simulation succeeds but execution fails (privilege escalation error)	Wrong keypair or address used as signer in instruction accounts. Ensure the vault PDA is used as the signer in inner instructions, not the multisig PDA or a random keypair. The multisig PDA cannot sign transactions
Simulation succeeds but execution fails (general)	Program state changed between simulation and execution. Re-simulate with current state and initiate a new transaction
”BPFLoaderUpgradeable not supported by inner instructions”	While Solana supports CPI calls to BPFLoaderUpgradeable for many operations (including Upgrade and ExtendProgram), the Transaction Builder may not handle all of them. Try using the Squads CLI or SDK to craft the transaction programmatically, or contact support

​

Resolving transaction size errors

Legacy and v0 Solana transactions are limited to 1,232 bytes. Squads wraps your inner instructions into a multisig transaction, adding approximately 150 to 200 bytes of overhead. This means your inner transaction message should stay under approximately 1,000 bytes. A transaction that works from a regular wallet may exceed the limit when executed through Squads. Wallets that support the larger Solana v1 transaction format, such as Solflare or Jupiter, can propose and execute transactions of up to 4,096 bytes. Hardware wallets do not support it. If the TX Builder reports that the transaction is too large for your wallet’s transaction format, propose it with a wallet that supports v1, or reduce its size. To resolve size errors:

• Use Address Lookup Tables to reference accounts by a 1-byte index instead of a full 32-byte public key, saving 31 bytes per account. Signers and program IDs must still appear inline.
• Split instructions across multiple transactions. Import your base58-encoded transaction, keep only the first group of instructions (such as token account creation), execute it, then re-import and repeat with the next group.
• Reduce the number of accounts in a single instruction where possible.
• Disable the Fee Relayer if enabled, as it adds extra bytes. Fund your SquadsX pubkey with SOL to pay fees instead.