Add a single-extend-per-transaction option for exported transactions

This PR adds a `--single-extend-per-tx` CLI option (and a matching `singleExtendPerTransaction` input on the JS client's plan builders) for transactions that are exported and later executed through a CPI, e.g. by a Squads multisig. In that setting the Solana runtime applies the 10,240-byte realloc limit to the whole top-level instruction rather than to each inner instruction, so the extend instructions the client packs into a single transaction to grow a metadata or buffer account beyond 10KB fail with `InvalidRealloc`.

When the option is set, a dedicated message packer ensures an account never grows by more than the realloc limit within a single transaction. It sizes each `extend` from the growth budget the candidate transaction has left, accounting for program-metadata instructions already present in it, so the first extend shares its transaction with the rent transfer and the `allocate` that creates the 96-byte header, every following extend gets its own transaction, and the rest of the plan (writes, `initialize` or `setData`) follows the last one. The option only applies to exported transactions and errors out without `--export`, since transactions run by the CLI directly execute top-level and are not affected.

The default (dense) packing now computes the extend chunk sizes locally instead of relying on Kit's `getReallocMessagePackerInstructionPlan`, which emits a final 0-byte extend when the total is an exact multiple of 10,240 and leaves the account one chunk short. This is a stopgap until the upstream fix ships. `REALLOC_LIMIT` is now exported from the client and reused by the tests instead of being redeclared.

Tests cover both packing modes at the planning level (per-transaction growth, exact-multiple chunking, the allocate header adjustment) and end to end with 25KB payloads through the create and update-from-buffer paths, which previously had no coverage above the realloc limit. The README documents the new option and when the Squads workflow needs it.

Author: lorisleiva

README.md

@@ -120,7 +120,8 @@ Using a buffer account you can split the metadata update into the uploading of t
 - `--priority-fees <number>`: Priority fees in micro-lamports per compute unit (default: 100000)
 - `--rpc <string>`: Custom RPC URL
 - `--export [address]`: Export transactions instead of running them. Optionally specify an override authority address.
-- `--export-encoding <encoding>`: How to encode exported transactions. Choices: none, utf8, base58, base64 (default: base64)
+- `--export-encoding <encoding>`: How to encode exported transactions. Choices: none, utf8, base58, base64, instruction-list (default: base64)
+- `--single-extend-per-tx`: Never grow an account by more than 10KB within a single exported transaction. Required when the exported transactions are executed through a CPI, e.g. by a multisig such as Squads. Requires `--export`.
 - `--tx-version <version>`: Transaction version to build. Choices: legacy, 0 (default: 0)
 - `-h, --help`: Show help for command
 
@@ -150,7 +151,13 @@ Squads v3 only accepts legacy transactions. If your multisig is on Squads v3, ad
 npx @solana-program/program-metadata@latest write idl <program-address> --buffer <buffer-address> --export <multisig-address> --export-encoding base58 --close-buffer <your-address-to-get-the-buffer-rent-back> --tx-version legacy
 ```
 
-4. Sign the transaction in your multisig and send it
+If the metadata account needs to grow by more than 10KB — because it is being created with more than 10KB of data, or updated with more than 10KB of additional data — add `--single-extend-per-tx`. Multisigs execute the exported transactions through a CPI, where the Solana runtime caps the growth of an account at 10KB per transaction rather than per instruction. This option spreads the growth over several transactions accordingly, so expect more than one transaction to import:
+
+```bash
+npx @solana-program/program-metadata@latest write idl <program-address> --buffer <buffer-address> --export <multisig-address> --export-encoding base58 --close-buffer <your-address-to-get-the-buffer-rent-back> --single-extend-per-tx
+```
+
+4. Sign the transaction(s) in your multisig and send them in order
 
 ### Examples
 

clients/js/src/cli/commands/create.ts

@@ -57,6 +57,7 @@ export async function doCreate(seed: Seed, program: Address, file: string | unde
             programData,
             seed,
             metadata,
+            singleExtendPerTransaction: options.singleExtendPerTx,
         }),
     );
 }

clients/js/src/cli/commands/update-buffer.ts

@@ -43,6 +43,7 @@ export async function doUpdateBuffer(buffer: Address, file: string | undefined,
             sourceBuffer: writeInput.buffer,
             closeSourceBuffer: writeInput.closeBuffer,
             data: newData,
+            singleExtendPerTransaction: options.singleExtendPerTx,
         }),
     );
 }

clients/js/src/cli/commands/update.ts

@@ -56,6 +56,7 @@ export async function doWrite(seed: Seed, program: Address, file: string | undef
             program,
             programData,
             metadata: metadataAccount,
+            singleExtendPerTransaction: options.singleExtendPerTx,
         }),
     );
 }

clients/js/src/cli/commands/write.ts

@@ -52,6 +52,7 @@ export async function doWrite(seed: Seed, program: Address, file: string | undef
             programData,
             seed,
             metadata: metadataAccount,
+            singleExtendPerTransaction: options.singleExtendPerTx,
         }),
     );
 }

clients/js/src/cli/options.ts

@@ -12,6 +12,7 @@ export type GlobalOptions = KeypairOption &
     RpcOption &
     ExportOption &
     ExportEncodingOption &
+    SingleExtendPerTxOption &
     TransactionVersionOption;
 
 export function setGlobalOptions(command: CustomCommand) {
@@ -22,6 +23,7 @@ export function setGlobalOptions(command: CustomCommand) {
         .addOption(rpcOption)
         .addOption(exportOption)
         .addOption(exportEncodingOption)
+        .addOption(singleExtendPerTxOption)
         .addOption(transactionVersionOption);
 }
 
@@ -68,6 +70,14 @@ export const exportEncodingOption = new Option(
         (value: string): ExportEncoding => (value === 'instruction-list' ? 'instruction-list' : encodingParser(value)),
     );
 
+export type SingleExtendPerTxOption = { singleExtendPerTx: boolean };
+export const singleExtendPerTxOption = new Option(
+    '--single-extend-per-tx',
+    'Never grow an account by more than 10KB within a single exported transaction (at most one "extend" instruction per transaction). ' +
+        'Required when the exported transactions are executed through a CPI, e.g. by a multisig program such as Squads, ' +
+        'as the runtime then applies the 10KB realloc limit per transaction instead of per instruction. Requires "--export".',
+).default(false);
+
 export type TransactionVersion = 'legacy' | 0;
 export type TransactionVersionOption = { txVersion: TransactionVersion };
 export const transactionVersionOption = new Option(

clients/js/src/cli/utils.ts

@@ -58,6 +58,7 @@ import {
     NonCanonicalWriteOption,
     PayerOption,
     RpcOption,
+    SingleExtendPerTxOption,
     WriteOptions,
 } from './options';
 import { createRetryingSolanaRpc, RetryingRpcConfig } from './rpc';
@@ -85,6 +86,7 @@ export class CustomCommand extends Command {
 export type Client = Awaited<ReturnType<typeof getClient>>;
 
 export async function getClient(options: GlobalOptions) {
+    assertValidExportOptions(options);
     const configs = getSolanaConfigs();
     const rpcUrl = getRpcUrl(options, configs);
     const rpcSubscriptionsUrl = getRpcSubscriptionsUrl(rpcUrl, configs);
@@ -111,6 +113,17 @@ export async function getClient(options: GlobalOptions) {
         .use(cliRunOrExport(options));
 }
 
+/**
+ * Rejects option combinations that only make sense when exporting
+ * transactions. When transactions are executed directly by the CLI they run
+ * top-level, so `--single-extend-per-tx` would only add needless transactions.
+ */
+function assertValidExportOptions(options: ExportOption & SingleExtendPerTxOption): void {
+    if (options.singleExtendPerTx && !options.export) {
+        logErrorAndExit('The `--single-extend-per-tx` option can only be used together with `--export`.');
+    }
+}
+
 /**
  * Shared configuration for the CLI's retrying RPC. Surfaces a warning whenever a
  * request is rate limited and retried, so a paused command does not appear to

clients/js/src/createBuffer.ts

@@ -20,8 +20,7 @@ import {
     PROGRAM_METADATA_PROGRAM_ADDRESS,
     SeedArgs,
 } from './generated';
-import { REALLOC_LIMIT } from './internals';
-import { getAccountSize, getExtendInstructionPlan, getWriteInstructionPlan } from './utils';
+import { getAccountSize, getExtendInstructionPlan, getWriteInstructionPlan, REALLOC_LIMIT } from './utils';
 
 /**
  * Builds a plan that creates a brand new buffer account owned by a fresh
@@ -120,6 +119,7 @@ export async function getCreateCanonicalBufferInstructionPlan(
         program: Address;
         programData: Address;
         seed: SeedArgs;
+        singleExtendPerTransaction?: boolean;
     },
 ) {
     const buffer = input.buffer ?? (await findCanonicalPda({ program: input.program, seed: input.seed }))[0];
@@ -151,6 +151,7 @@ export async function getCreateNonCanonicalBufferInstructionPlan(
         payer: TransactionSigner;
         program: Address;
         seed: SeedArgs;
+        singleExtendPerTransaction?: boolean;
     },
 ) {
     const buffer =
@@ -177,6 +178,7 @@ async function getPdaBufferInstructionPlan(
         program: Address;
         programData?: Address;
         seed: SeedArgs;
+        singleExtendPerTransaction?: boolean;
     },
 ) {
     const dataLength = input.dataLength ?? input.data?.length ?? 0;
@@ -202,6 +204,7 @@ async function getPdaBufferInstructionPlan(
                       extraLength: dataLength,
                       program: input.program,
                       programData: input.programData,
+                      singleExtendPerTransaction: input.singleExtendPerTransaction,
                   }),
               ]
             : []),

clients/js/src/createMetadata.ts

@@ -25,12 +25,13 @@ import {
     InitializeInput,
     PROGRAM_METADATA_PROGRAM_ADDRESS,
 } from './generated';
-import { isValidInstructionPlan, REALLOC_LIMIT } from './internals';
+import { isValidInstructionPlan } from './internals';
 import {
     getAccountSize,
     getExtendInstructionPlan,
     getWriteInstructionPlan,
     MetadataInput,
+    REALLOC_LIMIT,
     resolveMetadataPda,
 } from './utils';
 
@@ -66,6 +67,7 @@ export async function getCreateMetadataInstructionPlan(
         data?: ReadonlyUint8Array;
         payer: TransactionSigner;
         closeBuffer?: Address | boolean;
+        singleExtendPerTransaction?: boolean;
     },
 ): Promise<InstructionPlan> {
     if (!input.buffer && !input.data) {
@@ -115,6 +117,7 @@ export async function getCreateMetadataInstructionPlanUsingNewBuffer(
     input: Omit<InitializeInput, 'data'> & {
         data: ReadonlyUint8Array;
         payer: TransactionSigner;
+        singleExtendPerTransaction?: boolean;
     },
 ) {
     const rent = await client.getMinimumBalance(Number(getAccountSize(input.data.length)));
@@ -139,6 +142,7 @@ export async function getCreateMetadataInstructionPlanUsingNewBuffer(
                       extraLength: input.data.length,
                       program: input.program,
                       programData: input.programData,
+                      singleExtendPerTransaction: input.singleExtendPerTransaction,
                   }),
               ]
             : []),
@@ -164,6 +168,7 @@ export async function getCreateMetadataInstructionPlanUsingExistingBuffer(
         dataLength: number;
         payer: TransactionSigner;
         closeBuffer?: Address | boolean;
+        singleExtendPerTransaction?: boolean;
     },
 ) {
     const rent = await client.getMinimumBalance(Number(getAccountSize(input.dataLength)));
@@ -188,6 +193,7 @@ export async function getCreateMetadataInstructionPlanUsingExistingBuffer(
                       extraLength: input.dataLength,
                       program: input.program,
                       programData: input.programData,
+                      singleExtendPerTransaction: input.singleExtendPerTransaction,
                   }),
               ]
             : []),

clients/js/src/internals.ts

@@ -1,7 +1,5 @@
 import { ClientWithTransactionPlanning, InstructionPlan } from '@solana/kit';
 
-export const REALLOC_LIMIT = 10_240;
-
 /**
  * Returns `true` if the given instruction plan can be planned by the client's
  * transaction planner without throwing — i.e. it fits within a single