docs: improve IDL documentation and add allocate test

clients/js/src/generated/instructions/allocate.ts

@@ -52,9 +52,16 @@ export type AllocateInstruction<
         ]
     >;
 
-export type AllocateInstructionData = { discriminator: number; space: bigint };
+export type AllocateInstructionData = {
+    discriminator: number;
+    /** The number of bytes to allocate */
+    space: bigint;
+};
 
-export type AllocateInstructionDataArgs = { space: number | bigint };
+export type AllocateInstructionDataArgs = {
+    /** The number of bytes to allocate */
+    space: number | bigint;
+};
 
 export function getAllocateInstructionDataEncoder(): FixedSizeEncoder<AllocateInstructionDataArgs> {
     return transformEncoder(
@@ -81,6 +88,7 @@ export function getAllocateInstructionDataCodec(): FixedSizeCodec<
 }
 
 export type AllocateInput<TAccountNewAccount extends string = string> = {
+    /** The account to allocate space for */
     newAccount: TransactionSigner<TAccountNewAccount>;
     space: AllocateInstructionDataArgs['space'];
 };
@@ -116,6 +124,7 @@ export type ParsedAllocateInstruction<
 > = {
     programAddress: Address<TProgram>;
     accounts: {
+        /** The account to allocate space for */
         newAccount: TAccountMetas[0];
     };
     data: AllocateInstructionData;

clients/js/src/generated/instructions/createAccount.ts

@@ -61,14 +61,20 @@ export type CreateAccountInstruction<
 
 export type CreateAccountInstructionData = {
     discriminator: number;
+    /** The amount of lamports to transfer to the new account */
     lamports: bigint;
+    /** The number of bytes to allocate for the new account */
     space: bigint;
+    /** The address of the program that will own the new account */
     programAddress: Address;
 };
 
 export type CreateAccountInstructionDataArgs = {
+    /** The amount of lamports to transfer to the new account */
     lamports: number | bigint;
+    /** The number of bytes to allocate for the new account */
     space: number | bigint;
+    /** The address of the program that will own the new account */
     programAddress: Address;
 };
 
@@ -101,7 +107,9 @@ export function getCreateAccountInstructionDataCodec(): FixedSizeCodec<
 }
 
 export type CreateAccountInput<TAccountPayer extends string = string, TAccountNewAccount extends string = string> = {
+    /** The account that will pay for the new account */
     payer: TransactionSigner<TAccountPayer>;
+    /** The account to create */
     newAccount: TransactionSigner<TAccountNewAccount>;
     lamports: CreateAccountInstructionDataArgs['lamports'];
     space: CreateAccountInstructionDataArgs['space'];
@@ -147,7 +155,9 @@ export type ParsedCreateAccountInstruction<
 > = {
     programAddress: Address<TProgram>;
     accounts: {
+        /** The account that will pay for the new account */
         payer: TAccountMetas[0];
+        /** The account to create */
         newAccount: TAccountMetas[1];
     };
     data: CreateAccountInstructionData;

clients/js/src/generated/instructions/transferSol.ts

@@ -55,9 +55,16 @@ export type TransferSolInstruction<
         ]
     >;
 
-export type TransferSolInstructionData = { discriminator: number; amount: bigint };
+export type TransferSolInstructionData = {
+    discriminator: number;
+    /** The amount of lamports to transfer */
+    amount: bigint;
+};
 
-export type TransferSolInstructionDataArgs = { amount: number | bigint };
+export type TransferSolInstructionDataArgs = {
+    /** The amount of lamports to transfer */
+    amount: number | bigint;
+};
 
 export function getTransferSolInstructionDataEncoder(): FixedSizeEncoder<TransferSolInstructionDataArgs> {
     return transformEncoder(
@@ -84,7 +91,9 @@ export function getTransferSolInstructionDataCodec(): FixedSizeCodec<
 }
 
 export type TransferSolInput<TAccountSource extends string = string, TAccountDestination extends string = string> = {
+    /** The account referencing the source of the transfer */
     source: TransactionSigner<TAccountSource>;
+    /** The account referencing the destination of the transfer */
     destination: Address<TAccountDestination>;
     amount: TransferSolInstructionDataArgs['amount'];
 };
@@ -124,7 +133,9 @@ export type ParsedTransferSolInstruction<
 > = {
     programAddress: Address<TProgram>;
     accounts: {
+        /** The account referencing the source of the transfer */
         source: TAccountMetas[0];
+        /** The account referencing the destination of the transfer */
         destination: TAccountMetas[1];
     };
     data: TransferSolInstructionData;

clients/js/test/allocate.test.ts

@@ -0,0 +1,60 @@
+import {
+    appendTransactionMessageInstruction,
+    fetchEncodedAccount,
+    generateKeyPairSigner,
+    pipe,
+    airdropFactory,
+    lamports,
+} from '@solana/kit';
+import { it, expect } from 'vitest';
+import { getAllocateInstruction } from '../src';
+import {
+    createDefaultSolanaClient,
+    createDefaultTransaction,
+    generateKeyPairSignerWithSol,
+    signAndSendTransaction,
+} from './_setup';
+
+it('allocates space for an account', async () => {
+    // 1. Setup client and payer.
+    const client = createDefaultSolanaClient();
+    const [payer, accountToAllocate] = await Promise.all([
+        generateKeyPairSignerWithSol(client),
+        generateKeyPairSigner(),
+    ]);
+
+    // 2. Airdrop lamports to the account so it exists (system owned, 0 data).
+    await airdropFactory(client)({
+        recipientAddress: accountToAllocate.address,
+        lamports: lamports(await client.rpc.getMinimumBalanceForRentExemption(100n).send()),
+        commitment: 'confirmed',
+    });
+
+    // Verify initial state
+    let fetchedAccount = await fetchEncodedAccount(client.rpc, accountToAllocate.address);
+    expect(fetchedAccount.exists).toBe(true);
+    if (fetchedAccount.exists) {
+        expect(fetchedAccount.data.length).toBe(0);
+    }
+
+    // 3. Use getAllocateInstruction to allocate 100 bytes.
+    const newSpace = 100n;
+    const allocate = getAllocateInstruction({
+        newAccount: accountToAllocate,
+        space: newSpace,
+    });
+
+    // 4. Send transaction
+    await pipe(
+        await createDefaultTransaction(client, payer),
+        tx => appendTransactionMessageInstruction(allocate, tx),
+        tx => signAndSendTransaction(client, tx),
+    );
+
+    // 5. Verify the account's data length is exactly 100 bytes.
+    fetchedAccount = await fetchEncodedAccount(client.rpc, accountToAllocate.address);
+    expect(fetchedAccount.exists).toBe(true);
+    if (fetchedAccount.exists) {
+        expect(fetchedAccount.data.length).toBe(100);
+    }
+});