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..6d4dedd 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 { Seed } from '../../generated'; +import { decodeMaybeMetadataOrBuffer, 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 = decodeMaybeMetadataOrBuffer(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 f317add..e500782 100644 --- a/clients/js/src/createMetadata.ts +++ b/clients/js/src/createMetadata.ts @@ -2,70 +2,106 @@ import { getTransferSolInstruction } from '@solana-program/system'; import { Account, Address, + bytesEqual, ClientWithGetMinimumBalance, 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, getWriteInstruction, InitializeInput, + 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; @@ -74,19 +110,27 @@ 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, { ...input, buffer: input.buffer.address, dataLength: input.buffer.data.data.length, + sourceData: input.buffer.data.data, }); } 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, + existingLamports: pda.lamports, }); const validPlan = await isValidInstructionPlan(usingInstructionDataPlan, client); return validPlan @@ -97,126 +141,208 @@ 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), ]); } +/** + * 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 and so is the write if the buffer already holds `sourceData`. + */ 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; + sourceData?: ReadonlyUint8Array; + }, +) { + 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: + 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, + 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']); + 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) { + 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. When the metadata PDA holds + * a pre-allocated buffer, each step that an interrupted create already + * 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( + client: ClientWithGetMinimumBalance, + input: Omit & { + close?: ReturnType; + dataLength: number; + payer: TransactionSigner; + pda: MetadataPdaState; + singleExtendPerTransaction?: boolean; + write?: InstructionPlan | ReturnType; }, ) { - const rent = await client.getMinimumBalance(Number(getAccountSize(input.dataLength))); + 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([ - 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.dataLength) + ...(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..ab1e7a6 100644 --- a/clients/js/src/internals.ts +++ b/clients/js/src/internals.ts @@ -1,4 +1,87 @@ -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 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 & { 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, lamports: account.lamports }; + } + 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 as MaybeEncodedAccount) as MaybeAccount & { exists: true }; + 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 +113,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..3f1e82f 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,23 @@ import { import { getCreateBufferInstructionPlan } from './createBuffer'; import { Buffer, - fetchBuffer, - fetchMetadata, getCloseInstruction, getSetDataInstruction, getTrimInstruction, Metadata, SetDataInput, } from './generated'; -import { getCloseDestination, isValidInstructionPlan } from './internals'; +import { + decodeMaybeMetadataOrBuffer, + fetchMetadataAndBuffer, + getCloseDestination, + isPreAllocatedBuffer, + isValidInstructionPlan, +} from './internals'; import { getExtendInstructionPlan, MetadataInput, REALLOC_LIMIT, resolveMetadataPda } from './utils'; type UpdateMetadataClient = ClientWithGetMinimumBalance & - ClientWithRpc & + ClientWithRpc & ClientWithTransactionPlanning & ClientWithTransactionSending; @@ -44,17 +49,16 @@ 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 [encodedMetadata, buffer] = await fetchMetadataAndBuffer(client.rpc, metadata, input.buffer); + const metadataAccount = decodeMaybeMetadataOrBuffer(encodedMetadata); + assertAccountExists(metadataAccount); const plan = await getUpdateMetadataInstructionPlan(client, { ...input, metadata: metadataAccount, @@ -66,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; @@ -77,7 +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 (!input.metadata.data.mutable) { + 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 ${metadata.address} holds a pre-allocated buffer left by an ` + + 'interrupted create. Write or create the metadata account instead to resume that create.', + ); + } + if (!metadata.data.mutable) { throw new Error('Metadata account is immutable'); } @@ -86,7 +99,7 @@ export async function getUpdateMetadataInstructionPlan( ...input, buffer: input.buffer.address, dataLength: input.buffer.data.data.length, - metadata: input.metadata, + metadata, }); } @@ -94,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; @@ -104,7 +117,7 @@ export async function getUpdateMetadataInstructionPlan( ...input, buffer: newBuffer, data, - metadata: input.metadata, + metadata, }); } diff --git a/clients/js/src/writeMetadata.ts b/clients/js/src/writeMetadata.ts index e1b75df..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, @@ -15,12 +15,13 @@ import { } from '@solana/kit'; import { getCreateMetadataInstructionPlan } from './createMetadata'; -import { Buffer, fetchBuffer, fetchMaybeMetadata, InitializeInput, Metadata, SetDataInput } from './generated'; +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; @@ -30,24 +31,31 @@ 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 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 & @@ -55,12 +63,14 @@ export async function getWriteMetadataInstructionPlan( buffer?: Account; closeBuffer?: Address | HasAddress | boolean; data?: ReadonlyUint8Array; - metadata: MaybeAccount; + metadata: Account | MaybeAccount; payer: TransactionSigner; singleExtendPerTransaction?: boolean; }, ): Promise { - return input.metadata.exists - ? await getUpdateMetadataInstructionPlan(client, { ...input, metadata: input.metadata }) - : await getCreateMetadataInstructionPlan(client, { ...input, metadata: input.metadata.address }); + 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..9754eef 100644 --- a/clients/js/test/createMetadata.test.ts +++ b/clients/js/test/createMetadata.test.ts @@ -1,4 +1,5 @@ -import { address, generateKeyPairSigner, getUtf8Encoder, none, some } from '@solana/kit'; +import { getTransferSolInstruction } from '@solana-program/system'; +import { address, generateKeyPairSigner, getUtf8Encoder, none, ReadonlyUint8Array, some } from '@solana/kit'; import { expect, it } from 'vitest'; import { @@ -9,6 +10,8 @@ import { findCanonicalPda, findNonCanonicalPda, Format, + getAccountSize, + getCreateMetadataInstructionPlan, Metadata, } from '../src'; import { @@ -455,3 +458,226 @@ 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('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(); + 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/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); diff --git a/clients/js/test/updateMetadata.test.ts b/clients/js/test/updateMetadata.test.ts index 84ac39d..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 { @@ -11,7 +20,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 +542,94 @@ 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); +}); + +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)); +}); diff --git a/clients/js/test/writeMetadata.test.ts b/clients/js/test/writeMetadata.test.ts index 4aabcae..8e267f3 100644 --- a/clients/js/test/writeMetadata.test.ts +++ b/clients/js/test/writeMetadata.test.ts @@ -1,7 +1,33 @@ -import { getUtf8Encoder, none } 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 { AccountDiscriminator, Compression, DataSource, Encoding, findCanonicalPda, Format, Metadata } from '../src'; +import { + AccountDiscriminator, + Compression, + DataSource, + Encoding, + findCanonicalPda, + findNonCanonicalPda, + Format, + getWriteMetadataInstructionPlan, + identifyProgramMetadataInstruction, + Metadata, + PROGRAM_METADATA_PROGRAM_ADDRESS, + ProgramMetadataInstruction, + writeMetadata, +} from '../src'; import { createDeployedProgram, createTestClient, generateKeyPairSignerWithSol } from './_setup'; it('creates a new metadata account if it does not exist', async () => { @@ -98,3 +124,551 @@ 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); +}); + +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, + }); +}); + +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}`); +});