Account for the header when deciding whether to extend a new account

Under CPI, the `allocate` and the first write share a transaction, so an account holding between 10,144 and 10,240 bytes of data would grow by more than the realloc limit despite `--single-extend-per-tx`, since no extend plan was emitted for it. Creation paths now gate the extend plan on `ACCOUNT_HEADER_LENGTH + dataLength` via a new `needsExtend` helper. The gate is unconditional: in dense mode it only adds one extend instruction to the same transaction for that 96-byte window.

Author: lorisleiva

clients/js/src/createBuffer.ts

@@ -20,7 +20,7 @@ import {
     PROGRAM_METADATA_PROGRAM_ADDRESS,
     SeedArgs,
 } from './generated';
-import { getAccountSize, getExtendInstructionPlan, getWriteInstructionPlan, REALLOC_LIMIT } from './utils';
+import { getAccountSize, getExtendInstructionPlan, getWriteInstructionPlan, needsExtend } from './utils';
 
 /**
  * Builds a plan that creates a brand new buffer account owned by a fresh
@@ -196,7 +196,7 @@ async function getPdaBufferInstructionPlan(
             programData: input.programData,
             seed: input.seed,
         }),
-        ...(dataLength > REALLOC_LIMIT
+        ...(needsExtend(dataLength)
             ? [
                   getExtendInstructionPlan({
                       account: input.buffer,

clients/js/src/createMetadata.ts

@@ -31,7 +31,7 @@ import {
     getExtendInstructionPlan,
     getWriteInstructionPlan,
     MetadataInput,
-    REALLOC_LIMIT,
+    needsExtend,
     resolveMetadataPda,
 } from './utils';
 
@@ -134,7 +134,7 @@ export async function getCreateMetadataInstructionPlanUsingNewBuffer(
             programData: input.programData,
             seed: input.seed,
         }),
-        ...(input.data.length > REALLOC_LIMIT
+        ...(needsExtend(input.data.length)
             ? [
                   getExtendInstructionPlan({
                       account: input.metadata,
@@ -185,7 +185,7 @@ export async function getCreateMetadataInstructionPlanUsingExistingBuffer(
             programData: input.programData,
             seed: input.seed,
         }),
-        ...(input.dataLength > REALLOC_LIMIT
+        ...(needsExtend(input.dataLength)
             ? [
                   getExtendInstructionPlan({
                       account: input.metadata,

clients/js/src/utils.ts

@@ -112,6 +112,20 @@ export function getAccountSize(dataLength: bigint | number) {
     return BigInt(ACCOUNT_HEADER_LENGTH) + BigInt(dataLength);
 }
 
+/**
+ * Whether an account created via `allocate` needs explicit `extend`
+ * instructions to hold `dataLength` bytes of data.
+ *
+ * The account grows from nothing to the header length when allocated and to
+ * `ACCOUNT_HEADER_LENGTH + dataLength` once written, so the header must be
+ * counted towards the realloc limit. Doing so keeps the creation valid when
+ * the transactions are executed through a CPI, where the limit applies to the
+ * whole transaction rather than to each instruction.
+ */
+export function needsExtend(dataLength: number): boolean {
+    return ACCOUNT_HEADER_LENGTH + dataLength > REALLOC_LIMIT;
+}
+
 /**
  * Resolves the metadata PDA address for the given input.
  *

clients/js/test/createMetadata.test.ts

@@ -182,6 +182,58 @@ it('creates a canonical metadata account using an existing buffer', async () =>
     });
 });
 
+it.each([
+    { singleExtendPerTransaction: false, label: 'densely packed extend instructions' },
+    { singleExtendPerTransaction: true, label: 'a single extend instruction per transaction' },
+])(
+    'creates a canonical metadata account using an existing buffer as large as the realloc limit using $label',
+    async ({ singleExtendPerTransaction }) => {
+        // Given the following authority and deployed program.
+        const client = await createTestClient();
+        const authority = await generateKeyPairSignerWithSol(client);
+        const [program, programData] = await createDeployedProgram(client, authority);
+
+        // And an existing buffer holding exactly one realloc limit of data.
+        const data = getUtf8Encoder().encode('x'.repeat(REALLOC_LIMIT));
+        const buffer = await generateKeyPairSigner();
+        await client.programMetadata.instructions
+            .createBuffer({ newBuffer: buffer, authority: buffer, data })
+            .sendTransactions();
+
+        // When we create a canonical metadata account using the existing buffer.
+        await client.programMetadata.createMetadata({
+            authority,
+            program,
+            programData,
+            seed: 'idl',
+            encoding: Encoding.Utf8,
+            compression: Compression.None,
+            dataSource: DataSource.Direct,
+            format: Format.Json,
+            buffer: buffer.address,
+            singleExtendPerTransaction,
+        });
+
+        // Then we expect the following metadata account to be created.
+        const [metadata] = await findCanonicalPda({ program, seed: 'idl' });
+        const account = await client.programMetadata.accounts.metadata.fetch(metadata);
+        expect(account.data).toMatchObject(<Metadata>{
+            discriminator: AccountDiscriminator.Metadata,
+            program,
+            authority: none(),
+            mutable: true,
+            canonical: true,
+            seed: 'idl',
+            encoding: Encoding.Utf8,
+            compression: Compression.None,
+            format: Format.Json,
+            dataSource: DataSource.Direct,
+            dataLength: data.length,
+            data,
+        });
+    },
+);
+
 it('creates a non-canonical metadata account', async () => {
     // Given the following authority and deployed program.
     const client = await createTestClient();

clients/js/test/extendInstructionPlan.test.ts

@@ -1,5 +1,12 @@
 import { SYSTEM_PROGRAM_ADDRESS } from '@solana-program/system';
-import { Address, flattenTransactionPlan, getUtf8Encoder, InstructionPlan, TransactionMessage } from '@solana/kit';
+import {
+    Address,
+    flattenTransactionPlan,
+    generateKeyPairSigner,
+    getUtf8Encoder,
+    InstructionPlan,
+    TransactionMessage,
+} from '@solana/kit';
 import { expect, it } from 'vitest';
 
 import {
@@ -9,6 +16,7 @@ import {
     Encoding,
     findCanonicalPda,
     Format,
+    getCreateMetadataInstructionPlanUsingExistingBuffer,
     getCreateMetadataInstructionPlanUsingNewBuffer,
     getExtendInstructionPlan,
     parseProgramMetadataInstruction,
@@ -163,6 +171,85 @@ it('packs the extend instructions densely when creating metadata by default', as
     expect(getExtendLengths(messages[0], metadata)).toEqual([REALLOC_LIMIT, REALLOC_LIMIT, 25_000 - 2 * REALLOC_LIMIT]);
 });
 
+it('accounts for the header when the data alone fits within the realloc limit', async () => {
+    // Given a deployed program and an existing buffer holding exactly one realloc limit of data,
+    // which together with the account header exceeds the limit.
+    const client = await createTestClient();
+    const authority = await generateKeyPairSignerWithSol(client);
+    const [program, programData] = await createDeployedProgram(client, authority);
+    const [metadata] = await findCanonicalPda({ program, seed: 'idl' });
+    const buffer = await generateKeyPairSigner();
+
+    // When we plan the metadata creation from that buffer with a single extend instruction per transaction.
+    const plan = await getCreateMetadataInstructionPlanUsingExistingBuffer(client, {
+        authority,
+        buffer: buffer.address,
+        dataLength: REALLOC_LIMIT,
+        metadata,
+        payer: authority,
+        program,
+        programData,
+        seed: 'idl',
+        encoding: Encoding.Utf8,
+        compression: Compression.None,
+        dataSource: DataSource.Direct,
+        format: Format.Json,
+        singleExtendPerTransaction: true,
+    });
+    const messages = await planMessages(client, plan);
+
+    // Then the allocation and a header-adjusted extend share the first transaction,
+    // and the remaining bytes are extended before the write in the second one.
+    expect(getInstructionTypes(messages[0], metadata)).toEqual([
+        ProgramMetadataInstruction.Allocate,
+        ProgramMetadataInstruction.Extend,
+    ]);
+    expect(getExtendLengths(messages[0], metadata)).toEqual([REALLOC_LIMIT - ACCOUNT_HEADER_LENGTH]);
+    expect(getInstructionTypes(messages[1], metadata)).toEqual([
+        ProgramMetadataInstruction.Extend,
+        ProgramMetadataInstruction.Write,
+        ProgramMetadataInstruction.Initialize,
+    ]);
+    expect(getExtendLengths(messages[1], metadata)).toEqual([ACCOUNT_HEADER_LENGTH]);
+    expect(messages.every(message => getGrowth(message, metadata) <= REALLOC_LIMIT)).toBe(true);
+});
+
+it('adds a single extend instruction when the data alone fits within the realloc limit by default', async () => {
+    // Given a deployed program and an existing buffer holding exactly one realloc limit of data.
+    const client = await createTestClient();
+    const authority = await generateKeyPairSignerWithSol(client);
+    const [program, programData] = await createDeployedProgram(client, authority);
+    const [metadata] = await findCanonicalPda({ program, seed: 'idl' });
+    const buffer = await generateKeyPairSigner();
+
+    // When we plan the metadata creation from that buffer without constraining the extend instructions.
+    const plan = await getCreateMetadataInstructionPlanUsingExistingBuffer(client, {
+        authority,
+        buffer: buffer.address,
+        dataLength: REALLOC_LIMIT,
+        metadata,
+        payer: authority,
+        program,
+        programData,
+        seed: 'idl',
+        encoding: Encoding.Utf8,
+        compression: Compression.None,
+        dataSource: DataSource.Direct,
+        format: Format.Json,
+    });
+    const messages = await planMessages(client, plan);
+
+    // Then everything fits in a single transaction with one full extend instruction.
+    expect(messages).toHaveLength(1);
+    expect(getInstructionTypes(messages[0], metadata)).toEqual([
+        ProgramMetadataInstruction.Allocate,
+        ProgramMetadataInstruction.Extend,
+        ProgramMetadataInstruction.Write,
+        ProgramMetadataInstruction.Initialize,
+    ]);
+    expect(getExtendLengths(messages[0], metadata)).toEqual([REALLOC_LIMIT]);
+});
+
 async function planMessages(client: TestClient, plan: InstructionPlan): Promise<TransactionMessage[]> {
     const transactionPlan = await client.planTransactions(plan);
     return flattenTransactionPlan(transactionPlan).map(single => single.message);