From 38c7241c94eda9178dd2ad1f7e83216f760bb886 Mon Sep 17 00:00:00 2001 From: Fabian Schuh Date: Fri, 30 Oct 2026 18:30:12 +0100 Subject: [PATCH 1/5] fix(js): resume interrupted creates when the metadata PDA holds a pre-allocated buffer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The write flow decided between create and update solely on whether an account exists at the metadata PDA. A create that is interrupted between the buffer writes and the initialize instruction leaves a pre-allocated buffer (discriminator: Buffer) at that PDA, which decoded as an existing metadata account and routed every subsequent write into the update flow. The update flow then planned a fresh keypair buffer, a full set of chunk writes and a final set_data that fails on-chain with 'instruction requires an initialized account' — after the buffer transactions had already been sent, leaking rent-exempt buffers on every retry. Route on the account discriminator instead: - absent account -> create (unchanged) - initialized metadata account -> update (unchanged) - pre-allocated buffer -> resume: initialize the account in place, rewriting the data (and growing the buffer) when it differs, and rejecting data smaller than the buffer since buffer accounts cannot shrink --- clients/js/src/createMetadata.ts | 100 ++++++++++++++++ clients/js/src/writeMetadata.ts | 33 +++++- clients/js/test/writeMetadata.test.ts | 164 ++++++++++++++++++++++++++ 3 files changed, 292 insertions(+), 5 deletions(-) diff --git a/clients/js/src/createMetadata.ts b/clients/js/src/createMetadata.ts index f317add..99a837d 100644 --- a/clients/js/src/createMetadata.ts +++ b/clients/js/src/createMetadata.ts @@ -24,6 +24,7 @@ import { getInitializeInstruction, getWriteInstruction, InitializeInput, + Metadata, PROGRAM_METADATA_PROGRAM_ADDRESS, } from './generated'; import { getCloseDestination, isValidInstructionPlan } from './internals'; @@ -94,6 +95,105 @@ export async function getCreateMetadataInstructionPlan( : await getCreateMetadataInstructionPlanUsingNewBuffer(client, { ...input, data }); } +/** + * Resumes an interrupted create when the metadata account PDA already holds a + * pre-allocated buffer. + * + * The create flow allocates the metadata account PDA as a buffer, writes the + * data into it and finally initializes it as a metadata account. If a run is + * interrupted before the `initialize` instruction executes, the PDA is left + * holding a fully written buffer that the update flow cannot handle — its + * `set_data` instruction requires an initialized metadata account. + * + * When the desired data is already present, the plan consists of a single + * `initialize` instruction. Otherwise the buffer is grown (if needed) and the + * data rewritten before initializing. Buffer accounts cannot shrink, so a + * pre-allocated buffer larger than the desired data is rejected with guidance. + */ +export async function getResumeMetadataInstructionPlan( + client: ClientWithGetMinimumBalance, + input: Omit & { + buffer?: Account; + closeBuffer?: Address | HasAddress | boolean; + data?: ReadonlyUint8Array; + metadata: Account; + payer: TransactionSigner; + singleExtendPerTransaction?: boolean; + }, +): Promise { + const currentData = input.metadata.data.data as ReadonlyUint8Array; + const desiredData = input.data ?? input.buffer?.data.data; + if (desiredData === undefined) { + throw new Error('Either `data` or `buffer` must be provided to resume a pre-allocated metadata buffer.'); + } + if (desiredData.length < currentData.length) { + throw new Error( + `The metadata account at ${input.metadata.address} holds a pre-allocated buffer of ${currentData.length} ` + + `bytes which is larger than the ${desiredData.length} bytes to store, and buffer accounts cannot be ` + + `trimmed. Close it (eg. \`close-buffer ${input.metadata.address}\`) and retry to create the metadata ` + + `account from scratch.`, + ); + } + const growth = desiredData.length - currentData.length; + return sequentialInstructionPlan([ + ...(growth > 0 + ? [ + getTransferSolInstruction({ + source: input.payer, + destination: input.metadata.address, + amount: await client.getMinimumBalance(growth), + }), + getExtendInstructionPlan({ + account: input.metadata.address, + authority: input.authority, + extraLength: growth, + program: input.program, + programData: input.programData, + singleExtendPerTransaction: input.singleExtendPerTransaction, + }), + ] + : []), + ...(!dataEquals(currentData, desiredData) + ? [ + input.data + ? parallelInstructionPlan([ + getWriteInstructionPlan({ + buffer: input.metadata.address, + authority: input.authority, + data: input.data, + }), + ]) + : getWriteInstruction({ + buffer: input.metadata.address, + authority: input.authority, + sourceBuffer: input.buffer!.address, + offset: 0, + }), + ] + : []), + getInitializeInstruction({ + ...input, + metadata: input.metadata.address, + system: PROGRAM_METADATA_PROGRAM_ADDRESS, + data: undefined, + }), + ...(input.buffer && input.closeBuffer + ? [ + getCloseInstruction({ + account: input.buffer.address, + authority: input.authority, + destination: getCloseDestination(input.closeBuffer, input.payer.address), + }), + ] + : []), + ]); +} + +function dataEquals(a: ReadonlyUint8Array, b: ReadonlyUint8Array): boolean { + if (a.length !== b.length) return false; + return a.every((byte, index) => byte === b[index]); +} + export async function getCreateMetadataInstructionPlanUsingInstructionData( client: ClientWithGetMinimumBalance, input: Omit & { diff --git a/clients/js/src/writeMetadata.ts b/clients/js/src/writeMetadata.ts index e1b75df..c482efa 100644 --- a/clients/js/src/writeMetadata.ts +++ b/clients/js/src/writeMetadata.ts @@ -14,8 +14,16 @@ import { TransactionSigner, } from '@solana/kit'; -import { getCreateMetadataInstructionPlan } from './createMetadata'; -import { Buffer, fetchBuffer, fetchMaybeMetadata, InitializeInput, Metadata, SetDataInput } from './generated'; +import { getCreateMetadataInstructionPlan, getResumeMetadataInstructionPlan } from './createMetadata'; +import { + AccountDiscriminator, + Buffer, + fetchBuffer, + fetchMaybeMetadata, + InitializeInput, + Metadata, + SetDataInput, +} from './generated'; import { getUpdateMetadataInstructionPlan } from './updateMetadata'; import { MetadataInput, resolveMetadataPda } from './utils'; @@ -60,7 +68,22 @@ export async function getWriteMetadataInstructionPlan( singleExtendPerTransaction?: boolean; }, ): Promise { - return input.metadata.exists - ? await getUpdateMetadataInstructionPlan(client, { ...input, metadata: input.metadata }) - : await getCreateMetadataInstructionPlan(client, { ...input, metadata: input.metadata.address }); + if (!input.metadata.exists) { + return await getCreateMetadataInstructionPlan(client, { ...input, metadata: input.metadata.address }); + } + switch (input.metadata.data.discriminator) { + case AccountDiscriminator.Metadata: + return await getUpdateMetadataInstructionPlan(client, { ...input, metadata: input.metadata }); + // A pre-allocated buffer at the metadata PDA means a previous create + // was interrupted before initializing the account — resume it instead + // of updating, which would fail since `set_data` requires an + // initialized metadata account. + case AccountDiscriminator.Buffer: + return await getResumeMetadataInstructionPlan(client, { ...input, metadata: input.metadata }); + default: + throw new Error( + `The account at ${input.metadata.address} has an unexpected discriminator ` + + `(${input.metadata.data.discriminator}); expected a metadata account or a pre-allocated buffer.`, + ); + } } diff --git a/clients/js/test/writeMetadata.test.ts b/clients/js/test/writeMetadata.test.ts index 4aabcae..27d08bd 100644 --- a/clients/js/test/writeMetadata.test.ts +++ b/clients/js/test/writeMetadata.test.ts @@ -98,3 +98,167 @@ it('updates a metadata account if it exists', async () => { data: newData, }); }); + +it('initializes a pre-allocated buffer left at the metadata PDA by an interrupted create', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a fully written pre-allocated buffer + // at the canonical metadata PDA, never initialized as a metadata account. + const seed = 'idl'; + const data = getUtf8Encoder().encode('Interrupted create'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, dataLength: data.length }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + await client.programMetadata.instructions.write({ buffer: metadata, authority, offset: 0, data }).sendTransaction(); + + // When we upload the metadata account with the same data. + await client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the pre-allocated buffer is initialized as the metadata account. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + program, + authority: none(), + mutable: true, + canonical: true, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + dataLength: data.length, + data, + }); +}); + +it('rewrites a pre-allocated buffer at the metadata PDA when the data changed', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a pre-allocated buffer with stale + // data of the same length at the canonical metadata PDA. + const seed = 'idl'; + const staleData = getUtf8Encoder().encode('STALE DATA'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, dataLength: staleData.length }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + await client.programMetadata.instructions + .write({ buffer: metadata, authority, offset: 0, data: staleData }) + .sendTransaction(); + + // When we upload the metadata account with new data of the same length. + const data = getUtf8Encoder().encode('FRESH DATA'); + await client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the pre-allocated buffer is rewritten and initialized as metadata. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); +}); + +it('extends a pre-allocated buffer at the metadata PDA when the new data is larger', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a small pre-allocated buffer at the + // canonical metadata PDA. + const seed = 'idl'; + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, dataLength: 4 }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + await client.programMetadata.instructions + .write({ buffer: metadata, authority, offset: 0, data: getUtf8Encoder().encode('TINY') }) + .sendTransaction(); + + // When we upload the metadata account with larger data. + const data = getUtf8Encoder().encode('MUCH LARGER DATA'); + await client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the pre-allocated buffer is grown, rewritten and initialized. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); +}); + +it('rejects writes smaller than a pre-allocated buffer at the metadata PDA', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a large fully written pre-allocated + // buffer at the canonical metadata PDA. + const seed = 'idl'; + const staleData = getUtf8Encoder().encode('THIRTY-TWO BYTES OF STALE DATA'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, dataLength: staleData.length }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + await client.programMetadata.instructions + .write({ buffer: metadata, authority, offset: 0, data: staleData }) + .sendTransaction(); + + // When we upload the metadata account with smaller data, then it fails with + // an actionable error instead of misreporting the account's data length. + const data = getUtf8Encoder().encode('small'); + await expect( + client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }), + ).rejects.toThrow(/close-buffer/u); +}); From 5137005e265e577343e6ba0efb0057f65d1d7db5 Mon Sep 17 00:00:00 2001 From: Fabian Schuh Date: Fri, 30 Oct 2026 19:39:25 +0100 Subject: [PATCH 2/5] fix(js): harden resume plan per PR review feedback - Reject `buffer` == metadata PDA with an explicit error instead of initializing the account only to close it right after - Prefer `buffer` over `data`, matching the create and update flows - Fund extends with `withoutHeader: true` so the existing account header is not paid for twice (~0.0009 SOL stranded per extend) - Use Kit's `bytesEqual` instead of the local `dataEquals` helper - Document the resume path in `writeMetadata`'s docblock New tests: buffer==PDA guard throws, source buffer preferred over conflicting inline data, non-canonical PDA resume. Suite: 131 passed; oxlint, oxffmt and tsc clean. --- clients/js/src/createMetadata.ts | 36 +++---- clients/js/src/writeMetadata.ts | 7 +- clients/js/test/writeMetadata.test.ts | 137 +++++++++++++++++++++++++- 3 files changed, 157 insertions(+), 23 deletions(-) diff --git a/clients/js/src/createMetadata.ts b/clients/js/src/createMetadata.ts index 99a837d..ee96654 100644 --- a/clients/js/src/createMetadata.ts +++ b/clients/js/src/createMetadata.ts @@ -2,6 +2,7 @@ import { getTransferSolInstruction } from '@solana-program/system'; import { Account, Address, + bytesEqual, ClientWithGetMinimumBalance, ClientWithRpc, ClientWithTransactionPlanning, @@ -121,8 +122,12 @@ export async function getResumeMetadataInstructionPlan( singleExtendPerTransaction?: boolean; }, ): Promise { + if (input.buffer?.address === input.metadata.address) { + throw new Error('`buffer` must not be the metadata account itself when resuming a pre-allocated buffer.'); + } const currentData = input.metadata.data.data as ReadonlyUint8Array; - const desiredData = input.data ?? input.buffer?.data.data; + // Prefer `buffer` over `data`, matching the create and update flows. + const desiredData = input.buffer?.data.data ?? input.data; if (desiredData === undefined) { throw new Error('Either `data` or `buffer` must be provided to resume a pre-allocated metadata buffer.'); } @@ -141,7 +146,7 @@ export async function getResumeMetadataInstructionPlan( getTransferSolInstruction({ source: input.payer, destination: input.metadata.address, - amount: await client.getMinimumBalance(growth), + amount: await client.getMinimumBalance(growth, { withoutHeader: true }), }), getExtendInstructionPlan({ account: input.metadata.address, @@ -153,22 +158,22 @@ export async function getResumeMetadataInstructionPlan( }), ] : []), - ...(!dataEquals(currentData, desiredData) + ...(!bytesEqual(currentData, desiredData) ? [ - input.data - ? parallelInstructionPlan([ + input.buffer + ? getWriteInstruction({ + buffer: input.metadata.address, + authority: input.authority, + sourceBuffer: input.buffer.address, + offset: 0, + }) + : parallelInstructionPlan([ getWriteInstructionPlan({ buffer: input.metadata.address, authority: input.authority, - data: input.data, + data: desiredData, }), - ]) - : getWriteInstruction({ - buffer: input.metadata.address, - authority: input.authority, - sourceBuffer: input.buffer!.address, - offset: 0, - }), + ]), ] : []), getInitializeInstruction({ @@ -189,11 +194,6 @@ export async function getResumeMetadataInstructionPlan( ]); } -function dataEquals(a: ReadonlyUint8Array, b: ReadonlyUint8Array): boolean { - if (a.length !== b.length) return false; - return a.every((byte, index) => byte === b[index]); -} - export async function getCreateMetadataInstructionPlanUsingInstructionData( client: ClientWithGetMinimumBalance, input: Omit & { diff --git a/clients/js/src/writeMetadata.ts b/clients/js/src/writeMetadata.ts index c482efa..efbe8da 100644 --- a/clients/js/src/writeMetadata.ts +++ b/clients/js/src/writeMetadata.ts @@ -38,9 +38,10 @@ type WriteMetadataClient = ClientWithGetMinimumBalance & * When `input.metadata` is omitted, the PDA is derived from `program`, `seed` * and — for non-canonical metadata accounts — `authority`. The metadata * account is fetched to determine whether it already exists; if so, the - * operation is an update, otherwise it is a create. When `input.buffer` is - * provided as an address, the buffer account is fetched to determine its data - * length. + * operation is an update, otherwise it is a create. A pre-allocated buffer at + * the metadata PDA — the remnant of an interrupted create — resumes the + * create instead. When `input.buffer` is provided as an address, the buffer + * account is fetched to determine its data length. */ export async function writeMetadata(client: WriteMetadataClient, input: MetadataInput): Promise { const metadata = await resolveMetadataPda(input); diff --git a/clients/js/test/writeMetadata.test.ts b/clients/js/test/writeMetadata.test.ts index 27d08bd..299ac33 100644 --- a/clients/js/test/writeMetadata.test.ts +++ b/clients/js/test/writeMetadata.test.ts @@ -1,7 +1,16 @@ -import { getUtf8Encoder, none } from '@solana/kit'; +import { address, generateKeyPairSigner, getUtf8Encoder, none, some } from '@solana/kit'; import { expect, it } from 'vitest'; -import { AccountDiscriminator, Compression, DataSource, Encoding, findCanonicalPda, Format, Metadata } from '../src'; +import { + AccountDiscriminator, + Compression, + DataSource, + Encoding, + findCanonicalPda, + findNonCanonicalPda, + Format, + Metadata, +} from '../src'; import { createDeployedProgram, createTestClient, generateKeyPairSignerWithSol } from './_setup'; it('creates a new metadata account if it does not exist', async () => { @@ -262,3 +271,127 @@ it('rejects writes smaller than a pre-allocated buffer at the metadata PDA', asy }), ).rejects.toThrow(/close-buffer/u); }); + +it('rejects a resume that passes the metadata PDA itself as the buffer', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a fully written pre-allocated buffer + // at the canonical metadata PDA. + const seed = 'idl'; + const data = getUtf8Encoder().encode('Interrupted create'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, dataLength: data.length }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + await client.programMetadata.instructions.write({ buffer: metadata, authority, offset: 0, data }).sendTransaction(); + + // When we resume using the metadata PDA itself as the source buffer, then + // it fails instead of initializing the account only to close it. + await expect( + client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed, + buffer: metadata, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }), + ).rejects.toThrow(/`buffer` must not be the metadata account/u); +}); + +it('resumes a pre-allocated buffer from a source buffer, preferring it over inline data', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a pre-allocated buffer with stale + // data at the canonical metadata PDA. + const seed = 'idl'; + const staleData = getUtf8Encoder().encode('STALE DATA!'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, dataLength: staleData.length }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + await client.programMetadata.instructions + .write({ buffer: metadata, authority, offset: 0, data: staleData }) + .sendTransaction(); + + // And given a source buffer holding the desired data. + const desiredData = getUtf8Encoder().encode('FRESH DATA!'); + const sourceBuffer = await generateKeyPairSigner(); + await client.programMetadata.instructions + .createBuffer({ newBuffer: sourceBuffer, authority: sourceBuffer, data: desiredData }) + .sendTransaction(); + + // When we resume the create providing both the source buffer and inline + // data of the same length. + await client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed, + buffer: sourceBuffer, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('INLINE DATA'), + }); + + // Then the metadata account is initialized with the source buffer's data, + // matching the precedence of the create and update flows. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: desiredData.length, + data: desiredData, + }); +}); + +it('initializes a pre-allocated buffer left at a non-canonical metadata PDA', async () => { + // Given the following authority. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const program = address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'); + + // And given an interrupted create left a fully written pre-allocated buffer + // at the non-canonical metadata PDA. + const seed = 'idl'; + const data = getUtf8Encoder().encode('Interrupted create'); + await client.programMetadata.instructions + .createNonCanonicalBuffer({ authority, program, seed, data }) + .sendTransaction(); + const [metadata] = await findNonCanonicalPda({ program, authority: authority.address, seed }); + + // When we upload the metadata account with the same data. + await client.programMetadata.writeMetadata({ + authority, + program, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the pre-allocated buffer is initialized as the metadata account. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + program, + authority: some(authority.address), + canonical: false, + seed, + dataLength: data.length, + data, + }); +}); From bd561389db97759de16d66cb8fce0eeb4c3fd2e2 Mon Sep 17 00:00:00 2001 From: Loris Leiva Date: Mon, 2 Nov 2026 15:07:07 +0000 Subject: [PATCH 3/5] fix(js): resume interrupted creates and batch metadata fetches Fold the resume logic into the buffer-based create factories, which now inspect the state of the metadata PDA and skip the steps an interrupted create already completed (rent, allocate, extend, write). Callers pass the fetched account straight through, so `createMetadata`, `writeMetadata` and the CLI no longer duplicate the "already exists" check. Reject updates on a pre-allocated buffer before sending any transaction, and fetch the metadata and source buffer accounts using a single `getMultipleAccounts` request. --- clients/js/src/cli/commands/create-buffer.ts | 7 +- clients/js/src/cli/commands/create.ts | 21 +- clients/js/src/cli/commands/update-buffer.ts | 7 +- clients/js/src/cli/commands/update.ts | 10 +- clients/js/src/cli/commands/write.ts | 18 +- clients/js/src/cli/utils.ts | 32 +- clients/js/src/createMetadata.ts | 379 ++++++++++--------- clients/js/src/internals.ts | 118 +++++- clients/js/src/updateMetadata.ts | 28 +- clients/js/src/writeMetadata.ts | 58 ++- clients/js/test/createMetadata.test.ts | 186 ++++++++- clients/js/test/updateMetadata.test.ts | 43 ++- clients/js/test/writeMetadata.test.ts | 279 +++++++++++++- 13 files changed, 914 insertions(+), 272 deletions(-) diff --git a/clients/js/src/cli/commands/create-buffer.ts b/clients/js/src/cli/commands/create-buffer.ts index dcef53f..33a9e8e 100644 --- a/clients/js/src/cli/commands/create-buffer.ts +++ b/clients/js/src/cli/commands/create-buffer.ts @@ -1,5 +1,6 @@ import { generateKeyPairSigner } from '@solana/kit'; +import { fetchBuffer } from '../../generated'; import { fileArgument } from '../arguments'; import { logCommand } from '../logs'; import { GlobalOptions, setWriteOptions, WriteOptions } from '../options'; @@ -18,7 +19,11 @@ type Options = WriteOptions; export async function doCreateBuffer(file: string | undefined, _: Options, cmd: CustomCommand) { const options = cmd.optsWithGlobals() as GlobalOptions & Options; const client = await getClient(options); - const [buffer, writeInput] = await Promise.all([generateKeyPairSigner(), getWriteInput(client, file, options)]); + const [buffer, sourceBuffer] = await Promise.all([ + generateKeyPairSigner(), + options.buffer ? fetchBuffer(client.rpc, options.buffer) : Promise.resolve(undefined), + ]); + const writeInput = getWriteInput(file, options, sourceBuffer); logCommand(`Creating new buffer and setting authority...`, { buffer: buffer.address, diff --git a/clients/js/src/cli/commands/create.ts b/clients/js/src/cli/commands/create.ts index 7852dec..2caf0f6 100644 --- a/clients/js/src/cli/commands/create.ts +++ b/clients/js/src/cli/commands/create.ts @@ -1,10 +1,10 @@ import { Address } from '@solana/kit'; -import picocolors from 'picocolors'; import { getCreateMetadataInstructionPlan } from '../../createMetadata'; -import { fetchMaybeMetadata, Seed } from '../../generated'; +import { Seed } from '../../generated'; +import { decodeMaybeMetadataOrBuffer, fetchMetadataAndBuffer, isPreAllocatedBuffer } from '../../internals'; import { fileArgument, programArgument, seedArgument } from '../arguments'; -import { logCommand, logErrorAndExit } from '../logs'; +import { logCommand, logWarning } from '../logs'; import { GlobalOptions, nonCanonicalWriteOption, @@ -12,7 +12,7 @@ import { setWriteOptions, WriteOptions, } from '../options'; -import { CustomCommand, getClient, getPdaDetailsForWriting, getWriteInput } from '../utils'; +import { CustomCommand, getClient, getPdaDetailsForWriting, getWriteInput, INTERRUPTED_CREATE_WARNING } from '../utils'; export function setCreateCommand(program: CustomCommand): void { program @@ -39,13 +39,12 @@ export async function doCreate(seed: Seed, program: Address, file: string | unde authority: client.identity.address, }); - const [metadataAccount, writeInput] = await Promise.all([ - fetchMaybeMetadata(client.rpc, metadata), - getWriteInput(client, file, options), - ]); + const [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, options.buffer); + const metadataAccount = decodeMaybeMetadataOrBuffer(encodedMetadata); + const writeInput = getWriteInput(file, options, buffer); - if (metadataAccount.exists) { - logErrorAndExit(`Metadata account ${picocolors.bold(metadataAccount.address)} already exists.`); + if (isPreAllocatedBuffer(metadataAccount)) { + logWarning(INTERRUPTED_CREATE_WARNING); } await client.runOrExport( @@ -56,7 +55,7 @@ export async function doCreate(seed: Seed, program: Address, file: string | unde program, programData, seed, - metadata, + metadata: metadataAccount, singleExtendPerTransaction: options.singleExtendPerTx, }), ); diff --git a/clients/js/src/cli/commands/update-buffer.ts b/clients/js/src/cli/commands/update-buffer.ts index 4d5941e..4abd095 100644 --- a/clients/js/src/cli/commands/update-buffer.ts +++ b/clients/js/src/cli/commands/update-buffer.ts @@ -1,6 +1,6 @@ import { Address } from '@solana/kit'; -import { fetchMaybeBuffer } from '../../generated'; +import { fetchBuffer, fetchMaybeBuffer } from '../../generated'; import { bufferArgument, fileArgument } from '../arguments'; import { logCommand, logErrorAndExit } from '../logs'; import { GlobalOptions, setWriteOptions, WriteOptions } from '../options'; @@ -22,10 +22,11 @@ export async function doUpdateBuffer(buffer: Address, file: string | undefined, const client = await getClient(options); logCommand(`Updating buffer...`, { buffer }); - const [writeInput, bufferAccount] = await Promise.all([ - getWriteInput(client, file, options), + const [bufferAccount, sourceBuffer] = await Promise.all([ fetchMaybeBuffer(client.rpc, buffer), + options.buffer ? fetchBuffer(client.rpc, options.buffer) : Promise.resolve(undefined), ]); + const writeInput = getWriteInput(file, options, sourceBuffer); if (!bufferAccount.exists) { logErrorAndExit(`Buffer account not found: "${buffer}"`); diff --git a/clients/js/src/cli/commands/update.ts b/clients/js/src/cli/commands/update.ts index e717985..027d119 100644 --- a/clients/js/src/cli/commands/update.ts +++ b/clients/js/src/cli/commands/update.ts @@ -1,7 +1,8 @@ import { Address } from '@solana/kit'; import picocolors from 'picocolors'; -import { fetchMaybeMetadata, Seed } from '../../generated'; +import { decodeMetadata, Seed } from '../../generated'; +import { fetchMetadataAndBuffer } from '../../internals'; import { getUpdateMetadataInstructionPlan } from '../../updateMetadata'; import { fileArgument, programArgument, seedArgument } from '../arguments'; import { logCommand, logErrorAndExit } from '../logs'; @@ -39,10 +40,9 @@ export async function doWrite(seed: Seed, program: Address, file: string | undef authority: client.identity.address, }); - const [metadataAccount, writeInput] = await Promise.all([ - fetchMaybeMetadata(client.rpc, metadata), - getWriteInput(client, file, options), - ]); + const [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, options.buffer); + const metadataAccount = decodeMetadata(encodedMetadata); + const writeInput = getWriteInput(file, options, buffer); if (!metadataAccount.exists) { logErrorAndExit(`Metadata account ${picocolors.bold(metadataAccount.address)} does not exist.`); diff --git a/clients/js/src/cli/commands/write.ts b/clients/js/src/cli/commands/write.ts index ffe5940..bba320d 100644 --- a/clients/js/src/cli/commands/write.ts +++ b/clients/js/src/cli/commands/write.ts @@ -1,9 +1,10 @@ import { Address } from '@solana/kit'; -import { fetchMaybeMetadata, Seed } from '../../generated'; +import { Seed } from '../../generated'; +import { decodeMaybeMetadataOrBuffer, fetchMetadataAndBuffer, isPreAllocatedBuffer } from '../../internals'; import { getWriteMetadataInstructionPlan } from '../../writeMetadata'; import { fileArgument, programArgument, seedArgument } from '../arguments'; -import { logCommand } from '../logs'; +import { logCommand, logWarning } from '../logs'; import { GlobalOptions, nonCanonicalWriteOption, @@ -11,7 +12,7 @@ import { setWriteOptions, WriteOptions, } from '../options'; -import { CustomCommand, getClient, getPdaDetailsForWriting, getWriteInput } from '../utils'; +import { CustomCommand, getClient, getPdaDetailsForWriting, getWriteInput, INTERRUPTED_CREATE_WARNING } from '../utils'; export function setWriteCommand(program: CustomCommand): void { program @@ -38,10 +39,13 @@ export async function doWrite(seed: Seed, program: Address, file: string | undef authority: client.identity.address, }); - const [metadataAccount, writeInput] = await Promise.all([ - fetchMaybeMetadata(client.rpc, metadata), - getWriteInput(client, file, options), - ]); + const [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, options.buffer); + const metadataAccount = decodeMaybeMetadataOrBuffer(encodedMetadata); + const writeInput = getWriteInput(file, options, buffer); + + if (isPreAllocatedBuffer(metadataAccount)) { + logWarning(INTERRUPTED_CREATE_WARNING); + } await client.runOrExport( getWriteMetadataInstructionPlan(client, { diff --git a/clients/js/src/cli/utils.ts b/clients/js/src/cli/utils.ts index b4096c4..41fa1c6 100644 --- a/clients/js/src/cli/utils.ts +++ b/clients/js/src/cli/utils.ts @@ -53,7 +53,6 @@ import { DataSource, decodeMetadata, Encoding, - fetchBuffer, findMetadataPda, Format, SeedArgs, @@ -445,18 +444,29 @@ async function getCanonicalPdaDetailsUnchecked( return { isAuthorized: storedAuthority === identity, metadata, programData }; } -export async function getWriteInput( - client: Client, +/** + * Warning shown by the `create` and `write` commands when the metadata PDA + * holds a pre-allocated buffer left by an interrupted create, which they + * resume instead of starting over. + */ +export const INTERRUPTED_CREATE_WARNING = + 'The metadata account holds a pre-allocated buffer left by an interrupted create. Resuming that create...'; + +/** + * Builds the write input shared by commands writing data from the CLI + * arguments and options. When the `--buffer` option is used, the fetched + * buffer account must be provided so commands can batch its fetch with other + * accounts. + */ +export function getWriteInput( file: string | undefined, options: WriteOptions, -): Promise< - PackedData & { - buffer?: Account; - format: Format; - closeBuffer?: Address | boolean; - } -> { - const buffer = options.buffer ? await fetchBuffer(client.rpc, options.buffer) : undefined; + buffer: Account | undefined, +): PackedData & { + buffer?: Account; + format: Format; + closeBuffer?: Address | boolean; +} { return { ...getPackedData(file, options), format: options.format ?? getFormatFromFile(file), diff --git a/clients/js/src/createMetadata.ts b/clients/js/src/createMetadata.ts index ee96654..4f1d7d7 100644 --- a/clients/js/src/createMetadata.ts +++ b/clients/js/src/createMetadata.ts @@ -7,19 +7,21 @@ import { ClientWithRpc, ClientWithTransactionPlanning, ClientWithTransactionSending, - GetAccountInfoApi, + GetMultipleAccountsApi, HasAddress, InstructionPlan, + MaybeAccount, parallelInstructionPlan, ReadonlyUint8Array, sequentialInstructionPlan, TransactionPlanResult, TransactionSigner, } from '@solana/kit'; +import { getAddressFromResolvedInstructionAccount } from '@solana/kit/program-client-core'; import { + AccountDiscriminator, Buffer, - fetchBuffer, getAllocateInstruction, getCloseInstruction, getInitializeInstruction, @@ -28,46 +30,78 @@ import { Metadata, PROGRAM_METADATA_PROGRAM_ADDRESS, } from './generated'; -import { getCloseDestination, isValidInstructionPlan } from './internals'; import { + decodeMaybeMetadataOrBuffer, + fetchMetadataAndBuffer, + getCloseDestination, + getDecodedAccountDiscriminator, + isValidInstructionPlan, +} from './internals'; +import { + ACCOUNT_HEADER_LENGTH, getAccountSize, getExtendInstructionPlan, getWriteInstructionPlan, MetadataInput, - needsExtend, + REALLOC_LIMIT, resolveMetadataPda, } from './utils'; type CreateMetadataClient = ClientWithGetMinimumBalance & - ClientWithRpc & + ClientWithRpc & ClientWithTransactionPlanning & ClientWithTransactionSending; +/** + * The metadata account to create. Either its address or the account fetched + * at that address — see {@link decodeMaybeMetadataOrBuffer}. + * + * Providing the fetched account allows the create to resume from a + * pre-allocated buffer left at the metadata PDA by an interrupted create. + */ +export type CreateMetadataTarget = Account | InitializeInput['metadata'] | MaybeAccount; + /** * Creates a new metadata account for the given program. * * When `input.metadata` is omitted, the PDA is derived from `program`, `seed` - * and — for non-canonical metadata accounts — `authority`. When `input.buffer` - * is provided as an address, the buffer account is fetched to determine its - * data length. + * and — for non-canonical metadata accounts — `authority`. The metadata + * account is fetched so that a pre-allocated buffer left at the PDA by an + * interrupted create is resumed rather than allocated again. When + * `input.buffer` is provided as an address, the buffer account is fetched + * alongside it to determine its data length. + * + * @throws If the metadata account already exists. */ export async function createMetadata( client: CreateMetadataClient, input: MetadataInput, ): Promise { - const [metadata, buffer] = await Promise.all([ - resolveMetadataPda(input), - input.buffer ? fetchBuffer(client.rpc, input.buffer) : Promise.resolve(undefined), - ]); - const plan = await getCreateMetadataInstructionPlan(client, { ...input, buffer, metadata }); + const metadata = await resolveMetadataPda(input); + const [metadataAccount, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, input.buffer); + const plan = await getCreateMetadataInstructionPlan(client, { + ...input, + buffer, + metadata: decodeMaybeMetadataOrBuffer(metadataAccount), + }); return await client.sendTransactions(plan); } +/** + * Builds a plan that creates a new metadata account. + * + * When `input.metadata` is the account fetched at the metadata PDA and holds a + * pre-allocated buffer — the remnant of a create interrupted before its final + * `initialize` instruction — only the missing steps of the create are planned. + * + * @throws If `input.metadata` is an existing metadata account. + */ export async function getCreateMetadataInstructionPlan( client: ClientWithGetMinimumBalance & ClientWithTransactionPlanning, - input: Omit & { + input: Omit & { buffer?: Account; data?: ReadonlyUint8Array; + metadata: CreateMetadataTarget; payer: TransactionSigner; closeBuffer?: Address | HasAddress | boolean; singleExtendPerTransaction?: boolean; @@ -76,6 +110,7 @@ export async function getCreateMetadataInstructionPlan( if (!input.buffer && !input.data) { throw new Error('Either `buffer` or `data` must be provided to create a new metadata account.'); } + const pda = getMetadataPdaState(input.metadata); if (input.buffer) { return await getCreateMetadataInstructionPlanUsingExistingBuffer(client, { @@ -86,8 +121,13 @@ export async function getCreateMetadataInstructionPlan( } const data = input.data as ReadonlyUint8Array; + if (pda.allocated) { + return await getCreateMetadataInstructionPlanUsingNewBuffer(client, { ...input, data }); + } + const usingInstructionDataPlan = await getCreateMetadataInstructionPlanUsingInstructionData(client, { ...input, + metadata: pda.address, data, }); const validPlan = await isValidInstructionPlan(usingInstructionDataPlan, client); @@ -96,104 +136,6 @@ export async function getCreateMetadataInstructionPlan( : await getCreateMetadataInstructionPlanUsingNewBuffer(client, { ...input, data }); } -/** - * Resumes an interrupted create when the metadata account PDA already holds a - * pre-allocated buffer. - * - * The create flow allocates the metadata account PDA as a buffer, writes the - * data into it and finally initializes it as a metadata account. If a run is - * interrupted before the `initialize` instruction executes, the PDA is left - * holding a fully written buffer that the update flow cannot handle — its - * `set_data` instruction requires an initialized metadata account. - * - * When the desired data is already present, the plan consists of a single - * `initialize` instruction. Otherwise the buffer is grown (if needed) and the - * data rewritten before initializing. Buffer accounts cannot shrink, so a - * pre-allocated buffer larger than the desired data is rejected with guidance. - */ -export async function getResumeMetadataInstructionPlan( - client: ClientWithGetMinimumBalance, - input: Omit & { - buffer?: Account; - closeBuffer?: Address | HasAddress | boolean; - data?: ReadonlyUint8Array; - metadata: Account; - payer: TransactionSigner; - singleExtendPerTransaction?: boolean; - }, -): Promise { - if (input.buffer?.address === input.metadata.address) { - throw new Error('`buffer` must not be the metadata account itself when resuming a pre-allocated buffer.'); - } - const currentData = input.metadata.data.data as ReadonlyUint8Array; - // Prefer `buffer` over `data`, matching the create and update flows. - const desiredData = input.buffer?.data.data ?? input.data; - if (desiredData === undefined) { - throw new Error('Either `data` or `buffer` must be provided to resume a pre-allocated metadata buffer.'); - } - if (desiredData.length < currentData.length) { - throw new Error( - `The metadata account at ${input.metadata.address} holds a pre-allocated buffer of ${currentData.length} ` + - `bytes which is larger than the ${desiredData.length} bytes to store, and buffer accounts cannot be ` + - `trimmed. Close it (eg. \`close-buffer ${input.metadata.address}\`) and retry to create the metadata ` + - `account from scratch.`, - ); - } - const growth = desiredData.length - currentData.length; - return sequentialInstructionPlan([ - ...(growth > 0 - ? [ - getTransferSolInstruction({ - source: input.payer, - destination: input.metadata.address, - amount: await client.getMinimumBalance(growth, { withoutHeader: true }), - }), - getExtendInstructionPlan({ - account: input.metadata.address, - authority: input.authority, - extraLength: growth, - program: input.program, - programData: input.programData, - singleExtendPerTransaction: input.singleExtendPerTransaction, - }), - ] - : []), - ...(!bytesEqual(currentData, desiredData) - ? [ - input.buffer - ? getWriteInstruction({ - buffer: input.metadata.address, - authority: input.authority, - sourceBuffer: input.buffer.address, - offset: 0, - }) - : parallelInstructionPlan([ - getWriteInstructionPlan({ - buffer: input.metadata.address, - authority: input.authority, - data: desiredData, - }), - ]), - ] - : []), - getInitializeInstruction({ - ...input, - metadata: input.metadata.address, - system: PROGRAM_METADATA_PROGRAM_ADDRESS, - data: undefined, - }), - ...(input.buffer && input.closeBuffer - ? [ - getCloseInstruction({ - account: input.buffer.address, - authority: input.authority, - destination: getCloseDestination(input.closeBuffer, input.payer.address), - }), - ] - : []), - ]); -} - export async function getCreateMetadataInstructionPlanUsingInstructionData( client: ClientWithGetMinimumBalance, input: Omit & { @@ -213,110 +155,181 @@ export async function getCreateMetadataInstructionPlanUsingInstructionData( ]); } +/** + * Builds a plan that allocates the metadata PDA as a buffer, writes `data` + * into it in chunks and initializes it as a metadata account. + * + * When `input.metadata` holds a pre-allocated buffer, the allocation is + * skipped and so is the write if the buffer already holds `data`. + */ export async function getCreateMetadataInstructionPlanUsingNewBuffer( client: ClientWithGetMinimumBalance, - input: Omit & { + input: Omit & { data: ReadonlyUint8Array; + metadata: CreateMetadataTarget; payer: TransactionSigner; singleExtendPerTransaction?: boolean; }, ) { - const rent = await client.getMinimumBalance(Number(getAccountSize(input.data.length))); - return sequentialInstructionPlan([ - getTransferSolInstruction({ - source: input.payer, - destination: input.metadata, - amount: rent, - }), - getAllocateInstruction({ - buffer: input.metadata, - authority: input.authority, - program: input.program, - programData: input.programData, - seed: input.seed, - }), - ...(needsExtend(input.data.length) - ? [ - getExtendInstructionPlan({ - account: input.metadata, - authority: input.authority, - extraLength: input.data.length, - program: input.program, - programData: input.programData, - singleExtendPerTransaction: input.singleExtendPerTransaction, - }), - ] - : []), - parallelInstructionPlan([ - getWriteInstructionPlan({ - buffer: input.metadata, - authority: input.authority, - data: input.data, - }), - ]), - getInitializeInstruction({ - ...input, - system: PROGRAM_METADATA_PROGRAM_ADDRESS, - data: undefined, - }), - ]); + const pda = getMetadataPdaState(input.metadata); + return await getCreateMetadataInstructionPlanUsingPdaBuffer(client, { + ...input, + pda, + dataLength: input.data.length, + write: + pda.allocated && bytesEqual(pda.data, input.data) + ? undefined + : parallelInstructionPlan([ + getWriteInstructionPlan({ buffer: pda.address, authority: input.authority, data: input.data }), + ]), + }); } +/** + * Builds a plan that allocates the metadata PDA as a buffer, copies the data + * of an existing `buffer` into it and initializes it as a metadata account, + * optionally closing `buffer` afterwards. + * + * When `input.metadata` holds a pre-allocated buffer, the allocation is + * skipped. + */ export async function getCreateMetadataInstructionPlanUsingExistingBuffer( client: ClientWithGetMinimumBalance, - input: Omit & { + input: Omit & { buffer: Address | HasAddress; dataLength: number; + metadata: CreateMetadataTarget; payer: TransactionSigner; closeBuffer?: Address | HasAddress | boolean; singleExtendPerTransaction?: boolean; }, ) { - const rent = await client.getMinimumBalance(Number(getAccountSize(input.dataLength))); - return sequentialInstructionPlan([ - getTransferSolInstruction({ - source: input.payer, - destination: input.metadata, - amount: rent, - }), - getAllocateInstruction({ - buffer: input.metadata, + const pda = getMetadataPdaState(input.metadata); + const buffer = getAddressFromResolvedInstructionAccount('buffer', input.buffer); + if (buffer === pda.address) { + throw new Error('`buffer` must not be the metadata account itself.'); + } + return await getCreateMetadataInstructionPlanUsingPdaBuffer(client, { + ...input, + pda, + write: getWriteInstruction({ + buffer: pda.address, authority: input.authority, - program: input.program, - programData: input.programData, - seed: input.seed, + sourceBuffer: buffer, + offset: 0, }), - ...(needsExtend(input.dataLength) + close: input.closeBuffer + ? getCloseInstruction({ + account: buffer, + authority: input.authority, + destination: getCloseDestination(input.closeBuffer, input.payer.address), + }) + : undefined, + }); +} + +/** + * The state of the metadata PDA before creating the metadata account: either + * not allocated yet or holding a pre-allocated buffer. + */ +type MetadataPdaState = { + address: Address; + allocated: boolean; + data: ReadonlyUint8Array; + lamports: bigint; +}; + +function getMetadataPdaState(metadata: CreateMetadataTarget): MetadataPdaState { + const discriminator = getDecodedAccountDiscriminator(metadata); + if (discriminator === undefined) { + const address = getAddressFromResolvedInstructionAccount('metadata', metadata as InitializeInput['metadata']); + return { address, allocated: false, data: new Uint8Array(0), lamports: 0n }; + } + const account = metadata as Account; + switch (discriminator) { + case AccountDiscriminator.Buffer: + return { address: account.address, allocated: true, data: account.data.data, lamports: account.lamports }; + case AccountDiscriminator.Metadata: + throw new Error(`Metadata account ${account.address} already exists.`); + default: + throw new Error( + `The account at ${account.address} has an unexpected discriminator (${discriminator}); ` + + 'expected a metadata account or a pre-allocated buffer.', + ); + } +} + +/** + * Shared steps of the buffer-based create flows. Each step that an + * interrupted create already completed on the metadata PDA is skipped: rent + * the account holds is not transferred again, an allocated account is not + * allocated again and the account is only extended by the growth left. + */ +async function getCreateMetadataInstructionPlanUsingPdaBuffer( + client: ClientWithGetMinimumBalance, + input: Omit & { + close?: ReturnType; + dataLength: number; + payer: TransactionSigner; + pda: MetadataPdaState; + singleExtendPerTransaction?: boolean; + write?: InstructionPlan | ReturnType; + }, +) { + const { pda } = input; + + // Buffer accounts cannot shrink and `initialize` derives the data length + // from the account size. + if (input.dataLength < pda.data.length) { + throw new Error( + `The metadata account at ${pda.address} holds a pre-allocated buffer of ${pda.data.length} ` + + `bytes which is larger than the ${input.dataLength} bytes to store, and buffer accounts cannot be ` + + `trimmed. Close it (eg. \`close-buffer ${pda.address}\`) and retry to create the metadata ` + + `account from scratch.`, + ); + } + + const requiredRent = await client.getMinimumBalance(Number(getAccountSize(input.dataLength))); + const missingRent = requiredRent - pda.lamports; + const extraLength = input.dataLength - pda.data.length; + // The header allocated by `allocate` counts towards the realloc limit of + // the transaction too, see `needsExtend`. + const growth = (pda.allocated ? 0 : ACCOUNT_HEADER_LENGTH) + extraLength; + + return sequentialInstructionPlan([ + ...(missingRent > 0n + ? [getTransferSolInstruction({ source: input.payer, destination: pda.address, amount: missingRent })] + : []), + ...(pda.allocated + ? [] + : [ + getAllocateInstruction({ + buffer: pda.address, + authority: input.authority, + program: input.program, + programData: input.programData, + seed: input.seed, + }), + ]), + ...(growth > REALLOC_LIMIT ? [ getExtendInstructionPlan({ - account: input.metadata, + account: pda.address, authority: input.authority, - extraLength: input.dataLength, + extraLength, program: input.program, programData: input.programData, singleExtendPerTransaction: input.singleExtendPerTransaction, }), ] : []), - getWriteInstruction({ - buffer: input.metadata, - authority: input.authority, - sourceBuffer: input.buffer, - offset: 0, - }), + ...(input.write ? [input.write] : []), getInitializeInstruction({ ...input, + metadata: pda.address, system: PROGRAM_METADATA_PROGRAM_ADDRESS, data: undefined, }), - ...(input.closeBuffer - ? [ - getCloseInstruction({ - account: input.buffer, - authority: input.authority, - destination: getCloseDestination(input.closeBuffer, input.payer.address), - }), - ] - : []), + ...(input.close ? [input.close] : []), ]); } diff --git a/clients/js/src/internals.ts b/clients/js/src/internals.ts index 81ddd05..5f369a6 100644 --- a/clients/js/src/internals.ts +++ b/clients/js/src/internals.ts @@ -1,4 +1,84 @@ -import { Address, ClientWithTransactionPlanning, HasAddress, InstructionPlan } from '@solana/kit'; +import { SYSTEM_PROGRAM_ADDRESS } from '@solana-program/system'; +import { + Account, + Address, + assertAccountExists, + ClientWithTransactionPlanning, + fetchEncodedAccounts, + GetMultipleAccountsApi, + HasAddress, + InstructionPlan, + MaybeAccount, + MaybeEncodedAccount, + Rpc, +} from '@solana/kit'; + +import { + AccountDiscriminator, + Buffer, + decodeBuffer, + decodeMetadata, + Metadata, + PROGRAM_METADATA_PROGRAM_ADDRESS, +} from './generated'; + +/** + * Fetches the account at a metadata PDA and, optionally, a source buffer + * account using a single `getMultipleAccounts` RPC call. + * + * The metadata account is returned encoded so callers can decode it according + * to the operation, e.g. via {@link decodeMaybeMetadataOrBuffer}. The buffer + * account, when requested, must exist and is decoded as a {@link Buffer}. + */ +export async function fetchMetadataAndBuffer( + rpc: Rpc, + metadata: Address, + buffer?: Address | HasAddress, +): Promise<[MaybeEncodedAccount, Account | undefined]> { + const addresses = buffer ? [metadata, toAddress(buffer)] : [metadata]; + const [metadataAccount, bufferAccount] = await fetchEncodedAccounts(rpc, addresses); + if (!bufferAccount) return [metadataAccount, undefined]; + assertAccountExists(bufferAccount); + return [metadataAccount, decodeBuffer(bufferAccount)]; +} + +/** + * Decodes the account at a metadata PDA according to its discriminator. + * + * Besides an initialized metadata account, the PDA may hold a pre-allocated + * buffer — the remnant of a create that was interrupted before its final + * `initialize` instruction — which is returned as a decoded {@link Buffer} + * account so callers can resume the create. + * + * A system-owned account without data — i.e. a PDA that was only funded — is + * reported as missing since the create flow supports pre-funded accounts. + * + * @throws If the account is owned by another program or holds an unexpected + * discriminator. + */ +export function decodeMaybeMetadataOrBuffer(account: MaybeEncodedAccount): Account | MaybeAccount { + if (!account.exists) return account; + if (account.data.length === 0 && account.programAddress === SYSTEM_PROGRAM_ADDRESS) { + return { address: account.address, exists: false }; + } + if (account.programAddress !== PROGRAM_METADATA_PROGRAM_ADDRESS) { + throw new Error( + `The account at ${account.address} is owned by ${account.programAddress}; ` + + `expected a metadata account owned by ${PROGRAM_METADATA_PROGRAM_ADDRESS}.`, + ); + } + switch (account.data[0]) { + case AccountDiscriminator.Metadata: + return decodeMetadata(account as MaybeEncodedAccount); + case AccountDiscriminator.Buffer: + return decodeBuffer(account); + default: + throw new Error( + `The account at ${account.address} has an unexpected discriminator (${account.data[0]}); ` + + 'expected a metadata account or a pre-allocated buffer.', + ); + } +} /** * Returns `true` if the given instruction plan can be planned by the client's @@ -30,3 +110,39 @@ export function toAddress(input: Address | Ha export function getCloseDestination(closeBuffer: Address | HasAddress | true, fallback: Address): Address { return closeBuffer === true ? fallback : toAddress(closeBuffer); } + +/** + * Returns the discriminator of a decoded metadata or buffer account, or + * `undefined` if the input is not an existing decoded account — e.g. an + * address or a missing `MaybeAccount`. + * + * Both account types share the same header layout, so accounts decoded with + * either decoder are supported. + */ +export function getDecodedAccountDiscriminator(input: unknown): AccountDiscriminator | undefined { + if (typeof input !== 'object' || input === null || !('data' in input) || !('lamports' in input)) { + return undefined; + } + const { data } = input as { data: unknown }; + if (typeof data !== 'object' || data === null || !('discriminator' in data)) { + return undefined; + } + return (data as { discriminator: AccountDiscriminator }).discriminator; +} + +/** + * Returns `true` if the given input is a decoded account holding a + * pre-allocated buffer, e.g. a metadata PDA left behind by an interrupted + * create. + */ +export function isPreAllocatedBuffer(input: unknown): input is Account { + return getDecodedAccountDiscriminator(input) === AccountDiscriminator.Buffer; +} + +/** + * Returns `true` if the given input is a decoded, initialized metadata + * account. + */ +export function isInitializedMetadata(input: unknown): input is Account { + return getDecodedAccountDiscriminator(input) === AccountDiscriminator.Metadata; +} diff --git a/clients/js/src/updateMetadata.ts b/clients/js/src/updateMetadata.ts index beaf54f..063487e 100644 --- a/clients/js/src/updateMetadata.ts +++ b/clients/js/src/updateMetadata.ts @@ -2,12 +2,13 @@ import { getTransferSolInstruction } from '@solana-program/system'; import { Account, Address, + assertAccountExists, ClientWithGetMinimumBalance, ClientWithRpc, ClientWithTransactionPlanning, ClientWithTransactionSending, generateKeyPairSigner, - GetAccountInfoApi, + GetMultipleAccountsApi, HasAddress, InstructionPlan, lamports, @@ -21,19 +22,18 @@ import { import { getCreateBufferInstructionPlan } from './createBuffer'; import { Buffer, - fetchBuffer, - fetchMetadata, + decodeMetadata, getCloseInstruction, getSetDataInstruction, getTrimInstruction, Metadata, SetDataInput, } from './generated'; -import { getCloseDestination, isValidInstructionPlan } from './internals'; +import { fetchMetadataAndBuffer, getCloseDestination, isPreAllocatedBuffer, isValidInstructionPlan } from './internals'; import { getExtendInstructionPlan, MetadataInput, REALLOC_LIMIT, resolveMetadataPda } from './utils'; type UpdateMetadataClient = ClientWithGetMinimumBalance & - ClientWithRpc & + ClientWithRpc & ClientWithTransactionPlanning & ClientWithTransactionSending; @@ -44,20 +44,18 @@ type UpdateMetadataClient = ClientWithGetMinimumBalance & * and — for non-canonical metadata accounts — `authority`. The current * metadata account is fetched to compute the size difference. When * `input.buffer` is provided as an address, the buffer account is fetched - * to determine its data length. + * alongside it to determine its data length. */ export async function updateMetadata( client: UpdateMetadataClient, input: MetadataInput, ): Promise { const metadata = await resolveMetadataPda(input); - const [metadataAccount, buffer] = await Promise.all([ - fetchMetadata(client.rpc, metadata), - input.buffer ? fetchBuffer(client.rpc, input.buffer) : Promise.resolve(undefined), - ]); + const [metadataAccount, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, input.buffer); + assertAccountExists(metadataAccount); const plan = await getUpdateMetadataInstructionPlan(client, { ...input, - metadata: metadataAccount, + metadata: decodeMetadata(metadataAccount), buffer, }); return await client.sendTransactions(plan); @@ -77,6 +75,14 @@ export async function getUpdateMetadataInstructionPlan( if (!input.buffer && !input.data) { throw new Error('Either `buffer` or `data` must be provided to update a metadata account.'); } + if (isPreAllocatedBuffer(input.metadata)) { + // The `set_data` instruction requires an initialized metadata account, + // so fail before planning any buffer transactions. + throw new Error( + `The metadata account at ${input.metadata.address} holds a pre-allocated buffer left by an ` + + 'interrupted create. Write or create the metadata account instead to resume that create.', + ); + } if (!input.metadata.data.mutable) { throw new Error('Metadata account is immutable'); } diff --git a/clients/js/src/writeMetadata.ts b/clients/js/src/writeMetadata.ts index efbe8da..0628cd0 100644 --- a/clients/js/src/writeMetadata.ts +++ b/clients/js/src/writeMetadata.ts @@ -5,7 +5,7 @@ import { ClientWithRpc, ClientWithTransactionPlanning, ClientWithTransactionSending, - GetAccountInfoApi, + GetMultipleAccountsApi, HasAddress, InstructionPlan, MaybeAccount, @@ -14,21 +14,14 @@ import { TransactionSigner, } from '@solana/kit'; -import { getCreateMetadataInstructionPlan, getResumeMetadataInstructionPlan } from './createMetadata'; -import { - AccountDiscriminator, - Buffer, - fetchBuffer, - fetchMaybeMetadata, - InitializeInput, - Metadata, - SetDataInput, -} from './generated'; +import { getCreateMetadataInstructionPlan } from './createMetadata'; +import { Buffer, InitializeInput, Metadata, SetDataInput } from './generated'; +import { decodeMaybeMetadataOrBuffer, fetchMetadataAndBuffer, isInitializedMetadata } from './internals'; import { getUpdateMetadataInstructionPlan } from './updateMetadata'; import { MetadataInput, resolveMetadataPda } from './utils'; type WriteMetadataClient = ClientWithGetMinimumBalance & - ClientWithRpc & + ClientWithRpc & ClientWithTransactionPlanning & ClientWithTransactionSending; @@ -41,22 +34,28 @@ type WriteMetadataClient = ClientWithGetMinimumBalance & * operation is an update, otherwise it is a create. A pre-allocated buffer at * the metadata PDA — the remnant of an interrupted create — resumes the * create instead. When `input.buffer` is provided as an address, the buffer - * account is fetched to determine its data length. + * account is fetched alongside it to determine its data length. */ export async function writeMetadata(client: WriteMetadataClient, input: MetadataInput): Promise { const metadata = await resolveMetadataPda(input); - const [metadataAccount, buffer] = await Promise.all([ - fetchMaybeMetadata(client.rpc, metadata), - input.buffer ? fetchBuffer(client.rpc, input.buffer) : Promise.resolve(undefined), - ]); + const [metadataAccount, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, input.buffer); const plan = await getWriteMetadataInstructionPlan(client, { ...input, - metadata: metadataAccount, + metadata: decodeMaybeMetadataOrBuffer(metadataAccount), buffer, }); return await client.sendTransactions(plan); } +/** + * Builds a plan that creates or updates a metadata account depending on the + * state of `input.metadata`: + * + * - a missing account is created, + * - a pre-allocated buffer — the remnant of a create interrupted before its + * final `initialize` instruction — resumes that create, + * - an initialized metadata account is updated. + */ export async function getWriteMetadataInstructionPlan( client: ClientWithGetMinimumBalance & ClientWithTransactionPlanning, input: Omit & @@ -64,27 +63,14 @@ export async function getWriteMetadataInstructionPlan( buffer?: Account; closeBuffer?: Address | HasAddress | boolean; data?: ReadonlyUint8Array; - metadata: MaybeAccount; + metadata: Account | MaybeAccount; payer: TransactionSigner; singleExtendPerTransaction?: boolean; }, ): Promise { - if (!input.metadata.exists) { - return await getCreateMetadataInstructionPlan(client, { ...input, metadata: input.metadata.address }); - } - switch (input.metadata.data.discriminator) { - case AccountDiscriminator.Metadata: - return await getUpdateMetadataInstructionPlan(client, { ...input, metadata: input.metadata }); - // A pre-allocated buffer at the metadata PDA means a previous create - // was interrupted before initializing the account — resume it instead - // of updating, which would fail since `set_data` requires an - // initialized metadata account. - case AccountDiscriminator.Buffer: - return await getResumeMetadataInstructionPlan(client, { ...input, metadata: input.metadata }); - default: - throw new Error( - `The account at ${input.metadata.address} has an unexpected discriminator ` + - `(${input.metadata.data.discriminator}); expected a metadata account or a pre-allocated buffer.`, - ); + const { metadata } = input; + if (!isInitializedMetadata(metadata)) { + return await getCreateMetadataInstructionPlan(client, { ...input, metadata }); } + return await getUpdateMetadataInstructionPlan(client, { ...input, metadata }); } diff --git a/clients/js/test/createMetadata.test.ts b/clients/js/test/createMetadata.test.ts index cca2dfc..c01cd9e 100644 --- a/clients/js/test/createMetadata.test.ts +++ b/clients/js/test/createMetadata.test.ts @@ -1,4 +1,4 @@ -import { address, generateKeyPairSigner, getUtf8Encoder, none, some } from '@solana/kit'; +import { address, generateKeyPairSigner, getUtf8Encoder, none, ReadonlyUint8Array, some } from '@solana/kit'; import { expect, it } from 'vitest'; import { @@ -9,6 +9,8 @@ import { findCanonicalPda, findNonCanonicalPda, Format, + getAccountSize, + getCreateMetadataInstructionPlan, Metadata, } from '../src'; import { @@ -455,3 +457,185 @@ it('accepts address wrappers for the program, program data, metadata, buffer and expect(bufferAccount.exists).toBe(false); expect(await getBalance(client, recipient)).toBe(bufferLamports); }); + +it('resumes an interrupted create that left a pre-allocated buffer at the metadata PDA', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a fully written pre-allocated buffer + // at the canonical metadata PDA, never initialized as a metadata account. + const data = getUtf8Encoder().encode('{"standard":"dummyIdl"}'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed: 'idl', data }) + .sendTransaction(); + + // When we create the canonical metadata account with the same data. + await client.programMetadata.createMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the pre-allocated buffer is initialized as the metadata account. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + program, + authority: none(), + canonical: true, + seed: 'idl', + dataLength: data.length, + data, + }); +}); + +it('only transfers the missing rent when resuming an interrupted create', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create funded the canonical metadata PDA for its + // final size and allocated it as a buffer, but never wrote any data to it. + const data = getUtf8Encoder().encode('{"standard":"dummyIdl"}'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed: 'idl', dataLength: data.length }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const rent = client.svm.minimumBalanceForRentExemption(BigInt(getAccountSize(data.length))); + expect(await getBalance(client, metadata)).toBe(rent); + + // When we create the canonical metadata account. + await client.programMetadata.createMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the metadata account is initialized with the data. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); + + // And it holds exactly the rent it needs since no extra rent was transferred. + expect(await getBalance(client, metadata)).toBe(rent); +}); + +it('extends a pre-allocated buffer by more than the realloc limit when resuming an interrupted create', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create only allocated an empty buffer at the + // canonical metadata PDA. + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed: 'idl' }) + .sendTransaction(); + + // And given a source buffer holding data larger than the realloc limit, + // which a single `write` instruction cannot copy without a prior `extend`. + const data: ReadonlyUint8Array = new Uint8Array(REALLOC_LIMIT * 2 + 100).fill(42); + const sourceBuffer = await generateKeyPairSigner(); + await client.programMetadata.instructions + .createBuffer({ newBuffer: sourceBuffer, authority: sourceBuffer, data }) + .sendTransactions(); + + // When we create the canonical metadata account from the source buffer. + await client.programMetadata.createMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.None, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.None, + buffer: sourceBuffer.address, + }); + + // Then the pre-allocated buffer is extended, written and initialized. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); + expect(await getBalance(client, metadata)).toBe( + client.svm.minimumBalanceForRentExemption(BigInt(getAccountSize(data.length))), + ); +}); + +it('cannot create a metadata account that already exists', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the following existing canonical metadata account. + const input = { + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('{"standard":"dummyIdl"}'), + }; + await client.programMetadata.createMetadata(input); + + // When we try to create it again, then we expect an error. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + await expect(client.programMetadata.createMetadata(input)).rejects.toThrow( + `Metadata account ${metadata} already exists.`, + ); +}); + +it('cannot plan the creation of a metadata account that already exists', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the following existing canonical metadata account. + const input = { + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('{"standard":"dummyIdl"}'), + }; + await client.programMetadata.createMetadata(input); + + // When we plan its creation from the fetched account, then we expect an error. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const metadataAccount = await client.programMetadata.accounts.metadata.fetchMaybe(metadata); + await expect( + getCreateMetadataInstructionPlan(client, { ...input, payer: client.payer, metadata: metadataAccount }), + ).rejects.toThrow(`Metadata account ${metadata} already exists.`); +}); diff --git a/clients/js/test/updateMetadata.test.ts b/clients/js/test/updateMetadata.test.ts index 84ac39d..c936838 100644 --- a/clients/js/test/updateMetadata.test.ts +++ b/clients/js/test/updateMetadata.test.ts @@ -11,7 +11,13 @@ import { Format, Metadata, } from '../src'; -import { createDeployedProgram, createTestClient, generateKeyPairSignerWithSol, REALLOC_LIMIT } from './_setup'; +import { + createDeployedProgram, + createTestClient, + generateKeyPairSignerWithSol, + getBalance, + REALLOC_LIMIT, +} from './_setup'; it('updates a canonical metadata account', async () => { // Given the following authority and deployed program. @@ -527,3 +533,38 @@ it('can close an existing buffer after using it to update a new metadata account const bufferAccount = await client.programMetadata.accounts.buffer.fetchMaybe(buffer.address); expect(bufferAccount.exists).toBe(false); }); + +it('cannot update a pre-allocated buffer left by an interrupted create', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a fully written pre-allocated buffer + // at the canonical metadata PDA. + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed: 'idl', data: getUtf8Encoder().encode('OLD') }) + .sendTransaction(); + const balanceBefore = await getBalance(client, client.payer.address); + + // When we try to update it, then we expect an error. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + await expect( + client.programMetadata.updateMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: new Uint8Array(REALLOC_LIMIT).fill(42), + }), + ).rejects.toThrow( + `The metadata account at ${metadata} holds a pre-allocated buffer left by an interrupted create.`, + ); + + // And no transaction was sent, so no new buffer was paid for. + expect(await getBalance(client, client.payer.address)).toBe(balanceBefore); +}); diff --git a/clients/js/test/writeMetadata.test.ts b/clients/js/test/writeMetadata.test.ts index 299ac33..8e267f3 100644 --- a/clients/js/test/writeMetadata.test.ts +++ b/clients/js/test/writeMetadata.test.ts @@ -1,4 +1,16 @@ -import { address, generateKeyPairSigner, getUtf8Encoder, none, some } from '@solana/kit'; +import { SYSTEM_PROGRAM_ADDRESS } from '@solana-program/system'; +import { + address, + flattenInstructionPlan, + generateKeyPairSigner, + getUtf8Encoder, + isSolanaError, + lamports, + none, + SingleInstructionPlan, + SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND, + some, +} from '@solana/kit'; import { expect, it } from 'vitest'; import { @@ -9,7 +21,12 @@ import { findCanonicalPda, findNonCanonicalPda, Format, + getWriteMetadataInstructionPlan, + identifyProgramMetadataInstruction, Metadata, + PROGRAM_METADATA_PROGRAM_ADDRESS, + ProgramMetadataInstruction, + writeMetadata, } from '../src'; import { createDeployedProgram, createTestClient, generateKeyPairSignerWithSol } from './_setup'; @@ -395,3 +412,263 @@ it('initializes a pre-allocated buffer left at a non-canonical metadata PDA', as data, }); }); + +it('resumes an interrupted create when the pre-allocated buffer was decoded as a metadata account', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a fully written pre-allocated buffer + // at the canonical metadata PDA. + const seed = 'idl'; + const data = getUtf8Encoder().encode('Interrupted create'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, data }) + .sendTransaction(); + + // And given that account was fetched using the metadata decoder. + const [metadata] = await findCanonicalPda({ program, seed }); + const metadataAccount = await client.programMetadata.accounts.metadata.fetchMaybe(metadata); + + // When we plan and send a write using that account. + const plan = await getWriteMetadataInstructionPlan(client, { + payer: client.payer, + authority, + program, + programData, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + metadata: metadataAccount, + }); + await client.sendTransactions(plan); + + // Then the pre-allocated buffer is initialized as the metadata account. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); +}); + +it('creates a metadata account at a PDA that was only funded', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the canonical metadata PDA was funded but never allocated. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + client.svm.setAccount({ + address: metadata, + data: new Uint8Array(0), + executable: false, + lamports: lamports(1_000_000n), + programAddress: SYSTEM_PROGRAM_ADDRESS, + space: 0n, + }); + + // When we upload the canonical metadata account. + const data = getUtf8Encoder().encode('Some data'); + await client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then we expect the metadata account to be created. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); +}); + +it('rejects a metadata PDA holding an unexpected discriminator', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the canonical metadata PDA holds a zeroed program-owned account. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + client.svm.setAccount({ + address: metadata, + data: new Uint8Array(96), + executable: false, + lamports: lamports(client.svm.minimumBalanceForRentExemption(96n)), + programAddress: PROGRAM_METADATA_PROGRAM_ADDRESS, + space: 96n, + }); + + // When we upload the canonical metadata account, then we expect an error. + await expect( + client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('Some data'), + }), + ).rejects.toThrow(`The account at ${metadata} has an unexpected discriminator (0)`); +}); + +it('only plans an initialize instruction when the pre-allocated buffer already holds the data', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create left a fully written and funded + // pre-allocated buffer at the canonical metadata PDA. + const seed = 'idl'; + const data = getUtf8Encoder().encode('Interrupted create'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed, data }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed }); + const metadataAccount = await client.programMetadata.accounts.buffer.fetch(metadata); + + // When we plan a write with the same data. + const plan = await getWriteMetadataInstructionPlan(client, { + payer: client.payer, + authority, + program, + programData, + seed, + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + metadata: metadataAccount, + }); + + // Then the plan only consists of the `initialize` instruction. + const leaves = flattenInstructionPlan(plan); + expect(leaves).toHaveLength(1); + expect(leaves[0]).toMatchObject({ kind: 'single' }); + const [leaf] = leaves as [SingleInstructionPlan]; + expect(identifyProgramMetadataInstruction(leaf.instruction.data!)).toBe(ProgramMetadataInstruction.Initialize); +}); + +it('fetches the metadata and buffer accounts using a single RPC request', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given a source buffer holding the data to write. + const data = getUtf8Encoder().encode('Some data'); + const sourceBuffer = await generateKeyPairSigner(); + await client.programMetadata.instructions + .createBuffer({ newBuffer: sourceBuffer, authority: sourceBuffer, data }) + .sendTransaction(); + + // And given an RPC that records the methods it is called with. + const calledMethods: string[] = []; + const rpc = new Proxy(client.rpc, { + get(target, property, receiver) { + calledMethods.push(String(property)); + return Reflect.get(target, property, receiver) as unknown; + }, + }); + + // When we write the metadata account from the source buffer. + await writeMetadata( + { ...client, rpc }, + { + payer: client.payer, + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + buffer: sourceBuffer.address, + }, + ); + + // Then both accounts were fetched using a single `getMultipleAccounts` request. + expect(calledMethods).toEqual(['getMultipleAccounts']); + + // And the metadata account was created from the source buffer. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ dataLength: data.length, data }); +}); + +it('cannot write a metadata account from a buffer that does not exist', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // When we write the metadata account from a missing buffer, then we expect an error. + const missingBuffer = await generateKeyPairSigner(); + await expect( + client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + buffer: missingBuffer.address, + }), + ).rejects.toSatisfy(error => isSolanaError(error, SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND)); +}); + +it('rejects a metadata PDA owned by another program', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the canonical metadata PDA holds an account owned by another program. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const owner = address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'); + client.svm.setAccount({ + address: metadata, + data: new Uint8Array(96), + executable: false, + lamports: lamports(client.svm.minimumBalanceForRentExemption(96n)), + programAddress: owner, + space: 96n, + }); + + // When we upload the canonical metadata account, then we expect an error. + await expect( + client.programMetadata.writeMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('Some data'), + }), + ).rejects.toThrow(`The account at ${metadata} is owned by ${owner}`); +}); From 043cebac360b941b340ad337fcd331629635ae2b Mon Sep 17 00:00:00 2001 From: Loris Leiva Date: Mon, 2 Nov 2026 15:52:02 +0000 Subject: [PATCH 4/5] fix(js): validate the metadata account owner and discriminator on update --- clients/js/src/cli/commands/update.ts | 6 +-- clients/js/src/createMetadata.ts | 8 +-- clients/js/src/internals.ts | 6 ++- clients/js/src/updateMetadata.ts | 31 +++++++----- clients/js/test/updateMetadata.test.ts | 67 +++++++++++++++++++++++++- 5 files changed, 96 insertions(+), 22 deletions(-) diff --git a/clients/js/src/cli/commands/update.ts b/clients/js/src/cli/commands/update.ts index 027d119..6d4dedd 100644 --- a/clients/js/src/cli/commands/update.ts +++ b/clients/js/src/cli/commands/update.ts @@ -1,8 +1,8 @@ import { Address } from '@solana/kit'; import picocolors from 'picocolors'; -import { decodeMetadata, Seed } from '../../generated'; -import { fetchMetadataAndBuffer } from '../../internals'; +import { Seed } from '../../generated'; +import { decodeMaybeMetadataOrBuffer, fetchMetadataAndBuffer } from '../../internals'; import { getUpdateMetadataInstructionPlan } from '../../updateMetadata'; import { fileArgument, programArgument, seedArgument } from '../arguments'; import { logCommand, logErrorAndExit } from '../logs'; @@ -41,7 +41,7 @@ export async function doWrite(seed: Seed, program: Address, file: string | undef }); const [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, options.buffer); - const metadataAccount = decodeMetadata(encodedMetadata); + const metadataAccount = decodeMaybeMetadataOrBuffer(encodedMetadata); const writeInput = getWriteInput(file, options, buffer); if (!metadataAccount.exists) { diff --git a/clients/js/src/createMetadata.ts b/clients/js/src/createMetadata.ts index 4f1d7d7..2c31b05 100644 --- a/clients/js/src/createMetadata.ts +++ b/clients/js/src/createMetadata.ts @@ -260,10 +260,10 @@ function getMetadataPdaState(metadata: CreateMetadataTarget): MetadataPdaState { } /** - * Shared steps of the buffer-based create flows. Each step that an - * interrupted create already completed on the metadata PDA is skipped: rent - * the account holds is not transferred again, an allocated account is not - * allocated again and the account is only extended by the growth left. + * Shared steps of the buffer-based create flows. When the metadata PDA holds + * a pre-allocated buffer, each step that an interrupted create already + * completed is skipped: rent the buffer holds is not transferred again, the + * account is not allocated again and it is only extended by the growth left. */ async function getCreateMetadataInstructionPlanUsingPdaBuffer( client: ClientWithGetMinimumBalance, diff --git a/clients/js/src/internals.ts b/clients/js/src/internals.ts index 5f369a6..6b140e8 100644 --- a/clients/js/src/internals.ts +++ b/clients/js/src/internals.ts @@ -56,7 +56,9 @@ export async function fetchMetadataAndBuffer( * @throws If the account is owned by another program or holds an unexpected * discriminator. */ -export function decodeMaybeMetadataOrBuffer(account: MaybeEncodedAccount): Account | MaybeAccount { +export function decodeMaybeMetadataOrBuffer( + account: MaybeEncodedAccount, +): MaybeAccount | (MaybeAccount & { exists: true }) { if (!account.exists) return account; if (account.data.length === 0 && account.programAddress === SYSTEM_PROGRAM_ADDRESS) { return { address: account.address, exists: false }; @@ -71,7 +73,7 @@ export function decodeMaybeMetadataOrBuffer(account: MaybeEncodedAccount): Accou case AccountDiscriminator.Metadata: return decodeMetadata(account as MaybeEncodedAccount); case AccountDiscriminator.Buffer: - return decodeBuffer(account); + return decodeBuffer(account as MaybeEncodedAccount) as MaybeAccount & { exists: true }; default: throw new Error( `The account at ${account.address} has an unexpected discriminator (${account.data[0]}); ` + diff --git a/clients/js/src/updateMetadata.ts b/clients/js/src/updateMetadata.ts index 063487e..3f1e82f 100644 --- a/clients/js/src/updateMetadata.ts +++ b/clients/js/src/updateMetadata.ts @@ -22,14 +22,19 @@ import { import { getCreateBufferInstructionPlan } from './createBuffer'; import { Buffer, - decodeMetadata, getCloseInstruction, getSetDataInstruction, getTrimInstruction, Metadata, SetDataInput, } from './generated'; -import { fetchMetadataAndBuffer, getCloseDestination, isPreAllocatedBuffer, isValidInstructionPlan } from './internals'; +import { + decodeMaybeMetadataOrBuffer, + fetchMetadataAndBuffer, + getCloseDestination, + isPreAllocatedBuffer, + isValidInstructionPlan, +} from './internals'; import { getExtendInstructionPlan, MetadataInput, REALLOC_LIMIT, resolveMetadataPda } from './utils'; type UpdateMetadataClient = ClientWithGetMinimumBalance & @@ -51,11 +56,12 @@ export async function updateMetadata( input: MetadataInput, ): Promise { const metadata = await resolveMetadataPda(input); - const [metadataAccount, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, input.buffer); - assertAccountExists(metadataAccount); + const [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, input.buffer); + const metadataAccount = decodeMaybeMetadataOrBuffer(encodedMetadata); + assertAccountExists(metadataAccount); const plan = await getUpdateMetadataInstructionPlan(client, { ...input, - metadata: decodeMetadata(metadataAccount), + metadata: metadataAccount, buffer, }); return await client.sendTransactions(plan); @@ -64,7 +70,7 @@ export async function updateMetadata( export async function getUpdateMetadataInstructionPlan( client: ClientWithGetMinimumBalance & ClientWithTransactionPlanning, input: Omit & { - metadata: Account; + metadata: Account | Account; buffer?: Account; data?: ReadonlyUint8Array; payer: TransactionSigner; @@ -75,15 +81,16 @@ export async function getUpdateMetadataInstructionPlan( if (!input.buffer && !input.data) { throw new Error('Either `buffer` or `data` must be provided to update a metadata account.'); } - if (isPreAllocatedBuffer(input.metadata)) { + const { metadata } = input; + if (isPreAllocatedBuffer(metadata)) { // The `set_data` instruction requires an initialized metadata account, // so fail before planning any buffer transactions. throw new Error( - `The metadata account at ${input.metadata.address} holds a pre-allocated buffer left by an ` + + `The metadata account at ${metadata.address} holds a pre-allocated buffer left by an ` + 'interrupted create. Write or create the metadata account instead to resume that create.', ); } - if (!input.metadata.data.mutable) { + if (!metadata.data.mutable) { throw new Error('Metadata account is immutable'); } @@ -92,7 +99,7 @@ export async function getUpdateMetadataInstructionPlan( ...input, buffer: input.buffer.address, dataLength: input.buffer.data.data.length, - metadata: input.metadata, + metadata, }); } @@ -100,7 +107,7 @@ export async function getUpdateMetadataInstructionPlan( const usingInstructionDataPlan = await getUpdateMetadataInstructionPlanUsingInstructionData(client, { ...input, data, - metadata: input.metadata, + metadata, }); const validPlan = await isValidInstructionPlan(usingInstructionDataPlan, client); if (validPlan) return usingInstructionDataPlan; @@ -110,7 +117,7 @@ export async function getUpdateMetadataInstructionPlan( ...input, buffer: newBuffer, data, - metadata: input.metadata, + metadata, }); } diff --git a/clients/js/test/updateMetadata.test.ts b/clients/js/test/updateMetadata.test.ts index c936838..39a150f 100644 --- a/clients/js/test/updateMetadata.test.ts +++ b/clients/js/test/updateMetadata.test.ts @@ -1,4 +1,13 @@ -import { address, generateKeyPairSigner, getUtf8Encoder, none, some } from '@solana/kit'; +import { + address, + generateKeyPairSigner, + getUtf8Encoder, + isSolanaError, + lamports, + none, + SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND, + some, +} from '@solana/kit'; import { expect, it } from 'vitest'; import { @@ -568,3 +577,59 @@ it('cannot update a pre-allocated buffer left by an interrupted create', async ( // And no transaction was sent, so no new buffer was paid for. expect(await getBalance(client, client.payer.address)).toBe(balanceBefore); }); + +it('cannot update a metadata PDA owned by another program', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the canonical metadata PDA holds an account owned by another program. + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const owner = address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'); + client.svm.setAccount({ + address: metadata, + data: new Uint8Array(96), + executable: false, + lamports: lamports(client.svm.minimumBalanceForRentExemption(96n)), + programAddress: owner, + space: 96n, + }); + + // When we try to update it, then we expect an error. + await expect( + client.programMetadata.updateMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('NEW'), + }), + ).rejects.toThrow(`The account at ${metadata} is owned by ${owner}`); +}); + +it('cannot update a metadata account that does not exist', async () => { + // Given the following authority and deployed program without metadata. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // When we try to update its canonical metadata account, then we expect an error. + await expect( + client.programMetadata.updateMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data: getUtf8Encoder().encode('NEW'), + }), + ).rejects.toSatisfy(error => isSolanaError(error, SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND)); +}); From 0dd532649f3ef8ccbce8f4809b4507074bb4a009 Mon Sep 17 00:00:00 2001 From: Fabian Schuh Date: Fri, 6 Nov 2026 09:25:21 +0100 Subject: [PATCH 5/5] fix(js): only transfer the missing rent and skip redundant buffer rewrites - Carry the lamports of a funded, empty metadata PDA through `decodeMaybeMetadataOrBuffer` so the create flow transfers only the rent that is missing - Accept `existingLamports` in the instruction-data plan, which had the same full-rent transfer - Skip the source-buffer `write` when the PDA already holds its bytes, mirroring the data path's `bytesEqual` short-circuit Optional polish from the review round; plan shapes stay compatible. Tests: pre-funded PDA keeps its exact balance, buffer-source resume plans a single `initialize`. Suite: 148 passed. --- clients/js/src/createMetadata.ts | 41 +++++++++++------ clients/js/src/internals.ts | 7 +-- clients/js/test/createMetadata.test.ts | 42 +++++++++++++++++ clients/js/test/extendInstructionPlan.test.ts | 45 +++++++++++++++++++ 4 files changed, 118 insertions(+), 17 deletions(-) diff --git a/clients/js/src/createMetadata.ts b/clients/js/src/createMetadata.ts index 2c31b05..e500782 100644 --- a/clients/js/src/createMetadata.ts +++ b/clients/js/src/createMetadata.ts @@ -117,6 +117,7 @@ export async function getCreateMetadataInstructionPlan( ...input, buffer: input.buffer.address, dataLength: input.buffer.data.data.length, + sourceData: input.buffer.data.data, }); } @@ -129,6 +130,7 @@ export async function getCreateMetadataInstructionPlan( ...input, metadata: pda.address, data, + existingLamports: pda.lamports, }); const validPlan = await isValidInstructionPlan(usingInstructionDataPlan, client); return validPlan @@ -139,18 +141,24 @@ export async function getCreateMetadataInstructionPlan( export async function getCreateMetadataInstructionPlanUsingInstructionData( client: ClientWithGetMinimumBalance, input: Omit & { + existingLamports?: bigint; data?: ReadonlyUint8Array; payer: TransactionSigner; }, ) { const dataLength = input.data?.length ?? 0; const rent = await client.getMinimumBalance(Number(getAccountSize(dataLength))); + const missingRent = rent - (input.existingLamports ?? 0n); return sequentialInstructionPlan([ - getTransferSolInstruction({ - source: input.payer, - destination: input.metadata, - amount: rent, - }), + ...(missingRent > 0n + ? [ + getTransferSolInstruction({ + source: input.payer, + destination: input.metadata, + amount: missingRent, + }), + ] + : []), getInitializeInstruction(input), ]); } @@ -191,7 +199,7 @@ export async function getCreateMetadataInstructionPlanUsingNewBuffer( * optionally closing `buffer` afterwards. * * When `input.metadata` holds a pre-allocated buffer, the allocation is - * skipped. + * skipped and so is the write if the buffer already holds `sourceData`. */ export async function getCreateMetadataInstructionPlanUsingExistingBuffer( client: ClientWithGetMinimumBalance, @@ -202,6 +210,7 @@ export async function getCreateMetadataInstructionPlanUsingExistingBuffer( payer: TransactionSigner; closeBuffer?: Address | HasAddress | boolean; singleExtendPerTransaction?: boolean; + sourceData?: ReadonlyUint8Array; }, ) { const pda = getMetadataPdaState(input.metadata); @@ -212,12 +221,15 @@ export async function getCreateMetadataInstructionPlanUsingExistingBuffer( return await getCreateMetadataInstructionPlanUsingPdaBuffer(client, { ...input, pda, - write: getWriteInstruction({ - buffer: pda.address, - authority: input.authority, - sourceBuffer: buffer, - offset: 0, - }), + write: + input.sourceData && pda.allocated && bytesEqual(pda.data, input.sourceData) + ? undefined + : getWriteInstruction({ + buffer: pda.address, + authority: input.authority, + sourceBuffer: buffer, + offset: 0, + }), close: input.closeBuffer ? getCloseInstruction({ account: buffer, @@ -243,7 +255,8 @@ function getMetadataPdaState(metadata: CreateMetadataTarget): MetadataPdaState { const discriminator = getDecodedAccountDiscriminator(metadata); if (discriminator === undefined) { const address = getAddressFromResolvedInstructionAccount('metadata', metadata as InitializeInput['metadata']); - return { address, allocated: false, data: new Uint8Array(0), lamports: 0n }; + const lamports = typeof metadata === 'object' && 'lamports' in metadata ? (metadata.lamports ?? 0n) : 0n; + return { address, allocated: false, data: new Uint8Array(0), lamports }; } const account = metadata as Account; switch (discriminator) { @@ -262,7 +275,7 @@ function getMetadataPdaState(metadata: CreateMetadataTarget): MetadataPdaState { /** * Shared steps of the buffer-based create flows. When the metadata PDA holds * a pre-allocated buffer, each step that an interrupted create already - * completed is skipped: rent the buffer holds is not transferred again, the + * completed is skipped: rent the account holds is not transferred again, the * account is not allocated again and it is only extended by the growth left. */ async function getCreateMetadataInstructionPlanUsingPdaBuffer( diff --git a/clients/js/src/internals.ts b/clients/js/src/internals.ts index 6b140e8..ab1e7a6 100644 --- a/clients/js/src/internals.ts +++ b/clients/js/src/internals.ts @@ -51,17 +51,18 @@ export async function fetchMetadataAndBuffer( * account so callers can resume the create. * * A system-owned account without data — i.e. a PDA that was only funded — is - * reported as missing since the create flow supports pre-funded accounts. + * reported as missing with its lamports, since the create flow supports + * pre-funded accounts. * * @throws If the account is owned by another program or holds an unexpected * discriminator. */ export function decodeMaybeMetadataOrBuffer( account: MaybeEncodedAccount, -): MaybeAccount | (MaybeAccount & { exists: true }) { +): (MaybeAccount & { lamports?: bigint }) | (MaybeAccount & { exists: true }) { if (!account.exists) return account; if (account.data.length === 0 && account.programAddress === SYSTEM_PROGRAM_ADDRESS) { - return { address: account.address, exists: false }; + return { address: account.address, exists: false, lamports: account.lamports }; } if (account.programAddress !== PROGRAM_METADATA_PROGRAM_ADDRESS) { throw new Error( diff --git a/clients/js/test/createMetadata.test.ts b/clients/js/test/createMetadata.test.ts index c01cd9e..9754eef 100644 --- a/clients/js/test/createMetadata.test.ts +++ b/clients/js/test/createMetadata.test.ts @@ -1,3 +1,4 @@ +import { getTransferSolInstruction } from '@solana-program/system'; import { address, generateKeyPairSigner, getUtf8Encoder, none, ReadonlyUint8Array, some } from '@solana/kit'; import { expect, it } from 'vitest'; @@ -539,6 +540,47 @@ it('only transfers the missing rent when resuming an interrupted create', async expect(await getBalance(client, metadata)).toBe(rent); }); +it('does not transfer rent again for a pre-funded metadata PDA', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given the canonical metadata PDA was funded with its full rent but + // never allocated as a buffer. + const data = getUtf8Encoder().encode('{"standard":"dummyIdl"}'); + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + const rent = client.svm.minimumBalanceForRentExemption(BigInt(getAccountSize(data.length))); + await client.sendTransaction([ + getTransferSolInstruction({ source: authority, destination: metadata, amount: rent }), + ]); + + // When we create the canonical metadata account. + await client.programMetadata.createMetadata({ + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + data, + }); + + // Then the metadata account is initialized with the data. + const account = await client.programMetadata.accounts.metadata.fetch(metadata); + expect(account.data).toMatchObject({ + discriminator: AccountDiscriminator.Metadata, + dataLength: data.length, + data, + }); + + // And it holds exactly the rent it needs since the rent it held was not + // transferred again. + expect(await getBalance(client, metadata)).toBe(rent); +}); + it('extends a pre-allocated buffer by more than the realloc limit when resuming an interrupted create', async () => { // Given the following authority and deployed program. const client = await createTestClient(); diff --git a/clients/js/test/extendInstructionPlan.test.ts b/clients/js/test/extendInstructionPlan.test.ts index 3180519..9865dc7 100644 --- a/clients/js/test/extendInstructionPlan.test.ts +++ b/clients/js/test/extendInstructionPlan.test.ts @@ -16,6 +16,7 @@ import { Encoding, findCanonicalPda, Format, + getCreateMetadataInstructionPlan, getCreateMetadataInstructionPlanUsingExistingBuffer, getCreateMetadataInstructionPlanUsingNewBuffer, getExtendInstructionPlan, @@ -23,6 +24,7 @@ import { PROGRAM_METADATA_PROGRAM_ADDRESS, ProgramMetadataInstruction, } from '../src'; +import { decodeMaybeMetadataOrBuffer, fetchMetadataAndBuffer } from '../src/internals'; import { createDeployedProgram, createTestClient, @@ -302,6 +304,49 @@ it('adds a single extend instruction when the data alone fits within the realloc expect(getExtendLengths(messages[0], metadata)).toEqual([REALLOC_LIMIT]); }); +it('skips the write when the pre-allocated buffer already holds the source data', async () => { + // Given the following authority and deployed program. + const client = await createTestClient(); + const authority = await generateKeyPairSignerWithSol(client); + const [program, programData] = await createDeployedProgram(client, authority); + + // And given an interrupted create wrote data into the canonical metadata + // PDA, which was never initialized. + const data = getUtf8Encoder().encode('{"standard":"dummyIdl"}'); + await client.programMetadata.instructions + .createCanonicalBuffer({ authority, program, programData, seed: 'idl', dataLength: data.length, data }) + .sendTransaction(); + const [metadata] = await findCanonicalPda({ program, seed: 'idl' }); + + // And given a source buffer holding the same data. + const sourceBuffer = await generateKeyPairSigner(); + await client.programMetadata.instructions + .createBuffer({ newBuffer: sourceBuffer, authority: sourceBuffer, data }) + .sendTransaction(); + + // When we plan the create from the fetched PDA account and source buffer. + const [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, sourceBuffer); + const plan = await getCreateMetadataInstructionPlan(client, { + authority, + program, + programData, + seed: 'idl', + encoding: Encoding.Utf8, + compression: Compression.None, + dataSource: DataSource.Direct, + format: Format.Json, + buffer, + metadata: decodeMaybeMetadataOrBuffer(encodedMetadata), + payer: authority, + }); + const messages = await planMessages(client, plan); + + // Then the plan only initializes the account, since the source data is + // already in the buffer. + expect(messages).toHaveLength(1); + expect(getInstructionTypes(messages[0], metadata)).toEqual([ProgramMetadataInstruction.Initialize]); +}); + async function planMessages(client: TestClient, plan: InstructionPlan): Promise { const transactionPlan = await client.planTransactions(plan); return flattenTransactionPlan(transactionPlan).map(single => single.message);