chore(js): Add plugin & instruction planner defaults

clients/js/src/createMint.ts

@@ -24,7 +24,7 @@ export type CreateMintInstructionPlanInput = {
     mintAccountLamports?: number;
 };
 
-type CreateMintInstructionPlanConfig = {
+export type CreateMintInstructionPlanConfig = {
     systemProgram?: Address;
     tokenProgram?: Address;
 };

clients/js/src/mintToATA.ts

@@ -5,6 +5,7 @@ import {
     getMintToCheckedInstruction,
     TOKEN_PROGRAM_ADDRESS,
 } from './generated';
+import { MakeOptional } from './types';
 
 export type MintToATAInstructionPlanInput = {
     /** Funding account (must be a system account). */
@@ -28,7 +29,7 @@ export type MintToATAInstructionPlanInput = {
     multiSigners?: Array<TransactionSigner>;
 };
 
-type MintToATAInstructionPlanConfig = {
+export type MintToATAInstructionPlanConfig = {
     systemProgram?: Address;
     tokenProgram?: Address;
     associatedTokenProgram?: Address;
@@ -69,21 +70,25 @@ export function getMintToATAInstructionPlan(
     ]);
 }
 
-type MintToATAInstructionPlanAsyncInput = Omit<MintToATAInstructionPlanInput, 'ata'>;
+export type MintToATAInstructionPlanAsyncInput = MakeOptional<MintToATAInstructionPlanInput, 'ata'>;
 
 export async function getMintToATAInstructionPlanAsync(
     input: MintToATAInstructionPlanAsyncInput,
     config?: MintToATAInstructionPlanConfig,
 ): Promise<InstructionPlan> {
-    const [ataAddress] = await findAssociatedTokenPda({
-        owner: input.owner,
-        tokenProgram: config?.tokenProgram ?? TOKEN_PROGRAM_ADDRESS,
-        mint: input.mint,
-    });
+    const tokenProgram = config?.tokenProgram ?? TOKEN_PROGRAM_ADDRESS;
+    let ata = input.ata;
+    if (!ata) {
+        [ata] = await findAssociatedTokenPda({
+            owner: input.owner,
+            tokenProgram,
+            mint: input.mint,
+        });
+    }
     return getMintToATAInstructionPlan(
         {
             ...input,
-            ata: ataAddress,
+            ata,
         },
         config,
     );

clients/js/src/plugin.ts

@@ -1,30 +1,49 @@
 import { ClientWithPayer, pipe } from '@solana/kit';
 import { addSelfPlanAndSendFunctions, SelfPlanAndSendFunctions } from '@solana/kit/program-client-core';
 
-import { CreateMintInstructionPlanInput, getCreateMintInstructionPlan } from './createMint';
+import {
+    CreateMintInstructionPlanConfig,
+    CreateMintInstructionPlanInput,
+    getCreateMintInstructionPlan,
+} from './createMint';
 import {
     TokenPlugin as GeneratedTokenPlugin,
     TokenPluginInstructions as GeneratedTokenPluginInstructions,
     TokenPluginRequirements as GeneratedTokenPluginRequirements,
     tokenProgram as generatedTokenProgram,
 } from './generated';
-import { getMintToATAInstructionPlan, MintToATAInstructionPlanInput } from './mintToATA';
-import { getTransferToATAInstructionPlan, TransferToATAInstructionPlanInput } from './transferToATA';
+import {
+    getMintToATAInstructionPlanAsync,
+    MintToATAInstructionPlanAsyncInput,
+    MintToATAInstructionPlanConfig,
+} from './mintToATA';
+import {
+    getTransferToATAInstructionPlanAsync,
+    TransferToATAInstructionPlanAsyncInput,
+    TransferToATAInstructionPlanConfig,
+} from './transferToATA';
+import { MakeOptional } from './types';
 
 export type TokenPluginRequirements = GeneratedTokenPluginRequirements & ClientWithPayer;
 
 export type TokenPlugin = Omit<GeneratedTokenPlugin, 'instructions'> & { instructions: TokenPluginInstructions };
 
 export type TokenPluginInstructions = GeneratedTokenPluginInstructions & {
+    /** Create a new token mint. */
     createMint: (
-        input: MakeOptional<CreateMintInstructionPlanInput, 'payer'>,
+        input: MakeOptional<CreateMintInstructionPlanInput, 'payer' | 'mintAuthority'>,
+        config?: CreateMintInstructionPlanConfig,
     ) => ReturnType<typeof getCreateMintInstructionPlan> & SelfPlanAndSendFunctions;
+    /** Mint tokens to an owner's ATA (created if needed). */
     mintToATA: (
-        input: MakeOptional<MintToATAInstructionPlanInput, 'payer'>,
-    ) => ReturnType<typeof getMintToATAInstructionPlan> & SelfPlanAndSendFunctions;
+        input: MakeOptional<MintToATAInstructionPlanAsyncInput, 'payer' | 'mintAuthority'>,
+        config?: MintToATAInstructionPlanConfig,
+    ) => Promise<Awaited<ReturnType<typeof getMintToATAInstructionPlanAsync>>> & SelfPlanAndSendFunctions;
+    /** Transfer tokens to a recipient's ATA (created if needed). */
     transferToATA: (
-        input: MakeOptional<TransferToATAInstructionPlanInput, 'payer'>,
-    ) => ReturnType<typeof getTransferToATAInstructionPlan> & SelfPlanAndSendFunctions;
+        input: MakeOptional<TransferToATAInstructionPlanAsyncInput, 'payer' | 'authority'>,
+        config?: TransferToATAInstructionPlanConfig,
+    ) => Promise<Awaited<ReturnType<typeof getTransferToATAInstructionPlanAsync>>> & SelfPlanAndSendFunctions;
 };
 
 export function tokenProgram() {
@@ -35,25 +54,44 @@ export function tokenProgram() {
                 ...c.token,
                 instructions: {
                     ...c.token.instructions,
-                    createMint: input =>
+                    createMint: (input, config) =>
                         addSelfPlanAndSendFunctions(
                             client,
-                            getCreateMintInstructionPlan({ ...input, payer: input.payer ?? client.payer }),
+                            getCreateMintInstructionPlan(
+                                {
+                                    ...input,
+                                    payer: input.payer ?? client.payer,
+                                    mintAuthority: input.mintAuthority ?? client.payer.address,
+                                },
+                                config,
+                            ),
                         ),
-                    mintToATA: input =>
+                    mintToATA: (input, config) =>
                         addSelfPlanAndSendFunctions(
                             client,
-                            getMintToATAInstructionPlan({ ...input, payer: input.payer ?? client.payer }),
+                            getMintToATAInstructionPlanAsync(
+                                {
+                                    ...input,
+                                    payer: input.payer ?? client.payer,
+                                    mintAuthority: input.mintAuthority ?? client.payer,
+                                },
+                                config,
+                            ),
                         ),
-                    transferToATA: input =>
+                    transferToATA: (input, config) =>
                         addSelfPlanAndSendFunctions(
                             client,
-                            getTransferToATAInstructionPlan({ ...input, payer: input.payer ?? client.payer }),
+                            getTransferToATAInstructionPlanAsync(
+                                {
+                                    ...input,
+                                    payer: input.payer ?? client.payer,
+                                    authority: input.authority ?? client.payer,
+                                },
+                                config,
+                            ),
                         ),
                 },
             },
         }));
     };
 }
-
-type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

clients/js/src/transferToATA.ts

@@ -5,6 +5,7 @@ import {
     getTransferCheckedInstruction,
     TOKEN_PROGRAM_ADDRESS,
 } from './generated';
+import { MakeOptional } from './types';
 
 export type TransferToATAInstructionPlanInput = {
     /** Funding account (must be a system account). */
@@ -30,7 +31,7 @@ export type TransferToATAInstructionPlanInput = {
     multiSigners?: Array<TransactionSigner>;
 };
 
-type TransferToATAInstructionPlanConfig = {
+export type TransferToATAInstructionPlanConfig = {
     systemProgram?: Address;
     tokenProgram?: Address;
     associatedTokenProgram?: Address;
@@ -71,21 +72,44 @@ export function getTransferToATAInstructionPlan(
     ]);
 }
 
-type TransferToATAInstructionPlanAsyncInput = Omit<TransferToATAInstructionPlanInput, 'destination'>;
+export type TransferToATAInstructionPlanAsyncInput = MakeOptional<
+    TransferToATAInstructionPlanInput,
+    'source' | 'destination'
+>;
 
 export async function getTransferToATAInstructionPlanAsync(
     input: TransferToATAInstructionPlanAsyncInput,
     config?: TransferToATAInstructionPlanConfig,
 ): Promise<InstructionPlan> {
-    const [ataAddress] = await findAssociatedTokenPda({
-        owner: input.recipient,
-        tokenProgram: config?.tokenProgram ?? TOKEN_PROGRAM_ADDRESS,
-        mint: input.mint,
-    });
+    const tokenProgram = config?.tokenProgram ?? TOKEN_PROGRAM_ADDRESS;
+
+    const destinationAta =
+        input.destination ??
+        (
+            await findAssociatedTokenPda({
+                owner: input.recipient,
+                tokenProgram,
+                mint: input.mint,
+            })
+        )[0];
+
+    let source = input.source;
+    if (!source) {
+        const authorityAddress: Address =
+            typeof input.authority === 'string' ? input.authority : input.authority.address;
+        const [sourceAta] = await findAssociatedTokenPda({
+            owner: authorityAddress,
+            tokenProgram,
+            mint: input.mint,
+        });
+        source = sourceAta;
+    }
+
     return getTransferToATAInstructionPlan(
         {
             ...input,
-            destination: ataAddress,
+            source,
+            destination: destinationAta,
         },
         config,
     );

clients/js/src/types.ts

@@ -0,0 +1 @@
+export type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

clients/js/test/mintToATA.test.ts

@@ -1,4 +1,11 @@
-import { Account, generateKeyPairSigner, none } from '@solana/kit';
+import {
+    Account,
+    Address,
+    generateKeyPairSigner,
+    none,
+    type SingleInstructionPlan,
+    type SequentialInstructionPlan,
+} from '@solana/kit';
 import test from 'ava';
 import {
     AccountState,
@@ -16,6 +23,14 @@ import {
     generateKeyPairSignerWithSol,
 } from './_setup';
 
+// Extract the account addresses from a sequential instruction plan's instructions.
+function getInstructionAccounts(plan: SequentialInstructionPlan): Address[][] {
+    return plan.plans.map(p => {
+        const single = p as SingleInstructionPlan;
+        return (single.instruction.accounts ?? []).map(a => a.address);
+    });
+}
+
 test('it creates a new associated token account with an initial balance', async t => {
     // Given a mint account, its mint authority, a token owner and the ATA.
     const client = createDefaultSolanaClient();
@@ -170,3 +185,69 @@ test('it also mints to an existing associated token account', async t => {
         },
     });
 });
+
+// --- Offline tests: verify derived addresses in instruction plans ---
+
+test('async variant auto-derives ATA from owner + mint', async t => {
+    // Given an owner and mint.
+    const payer = await generateKeyPairSigner();
+    const mintAuthority = await generateKeyPairSigner();
+    const owner = (await generateKeyPairSigner()).address;
+    const mint = (await generateKeyPairSigner()).address;
+
+    const [expectedAta] = await findAssociatedTokenPda({
+        owner,
+        mint,
+        tokenProgram: TOKEN_PROGRAM_ADDRESS,
+    });
+
+    // When building a plan without an explicit ATA.
+    const plan = await getMintToATAInstructionPlanAsync({
+        payer,
+        mint,
+        owner,
+        mintAuthority,
+        amount: 500n,
+        decimals: 6,
+    });
+
+    // Then the plan should contain the derived ATA.
+    const seqPlan = plan as SequentialInstructionPlan;
+    t.is(seqPlan.kind, 'sequential');
+    t.is(seqPlan.plans.length, 2);
+
+    const accounts = getInstructionAccounts(seqPlan);
+
+    // createAssociatedTokenIdempotent — ata at index 1
+    t.is(accounts[0][1], expectedAta);
+
+    // mintToChecked — token at index 1
+    t.is(accounts[1][1], expectedAta);
+});
+
+test('async variant uses explicit ATA when provided', async t => {
+    // Given an explicit ATA address.
+    const payer = await generateKeyPairSigner();
+    const mintAuthority = await generateKeyPairSigner();
+    const owner = (await generateKeyPairSigner()).address;
+    const mint = (await generateKeyPairSigner()).address;
+    const explicitAta = (await generateKeyPairSigner()).address;
+
+    // When building a plan with the explicit ATA.
+    const plan = await getMintToATAInstructionPlanAsync({
+        payer,
+        mint,
+        owner,
+        mintAuthority,
+        ata: explicitAta,
+        amount: 500n,
+        decimals: 6,
+    });
+
+    // Then the plan should use the explicit ATA, not a derived one.
+    const seqPlan = plan as SequentialInstructionPlan;
+    const accounts = getInstructionAccounts(seqPlan);
+
+    t.is(accounts[0][1], explicitAta);
+    t.is(accounts[1][1], explicitAta);
+});