Add an instruction plan to transfer to an ATA

clients/js/src/createMint.ts

@@ -39,7 +39,7 @@ type CreateMintInstructionPlanConfig = {
   tokenProgram?: Address;
 };
 
-export function createMintInstructionPlan(
+export function getCreateMintInstructionPlan(
   input: CreateMintInstructionPlanInput,
   config?: CreateMintInstructionPlanConfig
 ): InstructionPlan {

clients/js/src/index.ts

@@ -1,3 +1,4 @@
 export * from './generated';
 export * from './createMint';
 export * from './mintToATA';
+export * from './transferToATA';

clients/js/src/mintToATA.ts

@@ -16,7 +16,7 @@ type MintToATAInstructionPlanInput = {
   payer: TransactionSigner;
   /** Associated token account address to mint to.
    * Will be created if it does not already exist.
-   * Note: Use {@link mintToATAInstructionPlanAsync} instead to derive this automatically.
+   * Note: Use {@link getMintToATAInstructionPlanAsync} instead to derive this automatically.
    * Note: Use {@link findAssociatedTokenPda} to derive the associated token account address.
    */
   ata: Address;
@@ -39,7 +39,7 @@ type MintToATAInstructionPlanConfig = {
   associatedTokenProgram?: Address;
 };
 
-export function mintToATAInstructionPlan(
+export function getMintToATAInstructionPlan(
   input: MintToATAInstructionPlanInput,
   config?: MintToATAInstructionPlanConfig
 ): InstructionPlan {
@@ -79,7 +79,7 @@ type MintToATAInstructionPlanAsyncInput = Omit<
   'ata'
 >;
 
-export async function mintToATAInstructionPlanAsync(
+export async function getMintToATAInstructionPlanAsync(
   input: MintToATAInstructionPlanAsyncInput,
   config?: MintToATAInstructionPlanConfig
 ): Promise<InstructionPlan> {
@@ -88,7 +88,7 @@ export async function mintToATAInstructionPlanAsync(
     tokenProgram: config?.tokenProgram ?? TOKEN_PROGRAM_ADDRESS,
     mint: input.mint,
   });
-  return mintToATAInstructionPlan(
+  return getMintToATAInstructionPlan(
     {
       ...input,
       ata: ataAddress,

clients/js/src/transferToATA.ts

@@ -0,0 +1,100 @@
+import {
+  InstructionPlan,
+  sequentialInstructionPlan,
+  Address,
+  TransactionSigner,
+} from '@solana/kit';
+import {
+  findAssociatedTokenPda,
+  getCreateAssociatedTokenIdempotentInstruction,
+  getTransferCheckedInstruction,
+  TOKEN_PROGRAM_ADDRESS,
+} from './generated';
+
+type TransferToATAInstructionPlanInput = {
+  /** Funding account (must be a system account). */
+  payer: TransactionSigner;
+  /** The token mint to transfer. */
+  mint: Address;
+  /** The source account for the transfer. */
+  source: Address;
+  /** The source account's owner/delegate or its multisignature account. */
+  authority: Address | TransactionSigner;
+  /** Associated token account address to transfer to.
+   * Will be created if it does not already exist.
+   * Note: Use {@link getTransferToATAInstructionPlanAsync} instead to derive this automatically.
+   * Note: Use {@link findAssociatedTokenPda} to derive the associated token account address.
+   */
+  destination: Address;
+  /** Wallet address for the destination. */
+  recipient: Address;
+  /** The amount of tokens to transfer. */
+  amount: number | bigint;
+  /** Expected number of base 10 digits to the right of the decimal place. */
+  decimals: number;
+  multiSigners?: Array<TransactionSigner>;
+};
+
+type TransferToATAInstructionPlanConfig = {
+  systemProgram?: Address;
+  tokenProgram?: Address;
+  associatedTokenProgram?: Address;
+};
+
+export function getTransferToATAInstructionPlan(
+  input: TransferToATAInstructionPlanInput,
+  config?: TransferToATAInstructionPlanConfig
+): InstructionPlan {
+  return sequentialInstructionPlan([
+    getCreateAssociatedTokenIdempotentInstruction(
+      {
+        payer: input.payer,
+        ata: input.destination,
+        owner: input.recipient,
+        mint: input.mint,
+        systemProgram: config?.systemProgram,
+        tokenProgram: config?.tokenProgram,
+      },
+      {
+        programAddress: config?.associatedTokenProgram,
+      }
+    ),
+    getTransferCheckedInstruction(
+      {
+        source: input.source,
+        mint: input.mint,
+        destination: input.destination,
+        authority: input.authority,
+        amount: input.amount,
+        decimals: input.decimals,
+        multiSigners: input.multiSigners,
+      },
+      {
+        programAddress: config?.tokenProgram,
+      }
+    ),
+  ]);
+}
+
+type TransferToATAInstructionPlanAsyncInput = Omit<
+  TransferToATAInstructionPlanInput,
+  '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,
+  });
+  return getTransferToATAInstructionPlan(
+    {
+      ...input,
+      destination: ataAddress,
+    },
+    config
+  );
+}

clients/js/test/_setup.ts

@@ -9,7 +9,8 @@ import {
   SolanaRpcSubscriptionsApi,
   TransactionMessageWithBlockhashLifetime,
   TransactionMessageWithFeePayer,
-  TransactionPlanExecutor,
+  TransactionPlan,
+  TransactionPlanResult,
   TransactionPlanner,
   TransactionSigner,
   airdropFactory,
@@ -32,22 +33,47 @@ import {
 } from '@solana/kit';
 import {
   TOKEN_PROGRAM_ADDRESS,
+  findAssociatedTokenPda,
   getInitializeAccountInstruction,
   getInitializeMintInstruction,
   getMintSize,
+  getMintToATAInstructionPlan,
   getMintToInstruction,
   getTokenSize,
 } from '../src';
 
 type Client = {
   rpc: Rpc<SolanaRpcApi>;
   rpcSubscriptions: RpcSubscriptions<SolanaRpcSubscriptionsApi>;
+  sendTransactionPlan: (
+    transactionPlan: TransactionPlan
+  ) => Promise<TransactionPlanResult>;
 };
 
 export const createDefaultSolanaClient = (): Client => {
   const rpc = createSolanaRpc('http://127.0.0.1:8899');
   const rpcSubscriptions = createSolanaRpcSubscriptions('ws://127.0.0.1:8900');
-  return { rpc, rpcSubscriptions };
+
+  const sendAndConfirm = sendAndConfirmTransactionFactory({
+    rpc,
+    rpcSubscriptions,
+  });
+  const transactionPlanExecutor = createTransactionPlanExecutor({
+    executeTransactionMessage: async (transactionMessage) => {
+      const signedTransaction =
+        await signTransactionMessageWithSigners(transactionMessage);
+      assertIsSendableTransaction(signedTransaction);
+      assertIsTransactionWithBlockhashLifetime(signedTransaction);
+      await sendAndConfirm(signedTransaction, { commitment: 'confirmed' });
+      return { transaction: signedTransaction };
+    },
+  });
+
+  const sendTransactionPlan = async (transactionPlan: TransactionPlan) => {
+    return transactionPlanExecutor(transactionPlan);
+  };
+
+  return { rpc, rpcSubscriptions, sendTransactionPlan };
 };
 
 export const generateKeyPairSignerWithSol = async (
@@ -114,24 +140,6 @@ export const createDefaultTransactionPlanner = (
   });
 };
 
-export const createDefaultTransactionPlanExecutor = (
-  client: Client,
-  commitment: Commitment = 'confirmed'
-): TransactionPlanExecutor => {
-  return createTransactionPlanExecutor({
-    executeTransactionMessage: async (transactionMessage) => {
-      const signedTransaction =
-        await signTransactionMessageWithSigners(transactionMessage);
-      assertIsSendableTransaction(signedTransaction);
-      assertIsTransactionWithBlockhashLifetime(signedTransaction);
-      await sendAndConfirmTransactionFactory(client)(signedTransaction, {
-        commitment,
-      });
-      return { transaction: signedTransaction };
-    },
-  });
-};
-
 export const getBalance = async (client: Client, address: Address) =>
   (await client.rpc.getBalance(address, { commitment: 'confirmed' }).send())
     .value;
@@ -235,3 +243,37 @@ export const createTokenWithAmount = async (
 
   return token.address;
 };
+
+export const createTokenPdaWithAmount = async (
+  client: Client,
+  payer: TransactionSigner,
+  mintAuthority: TransactionSigner,
+  mint: Address,
+  owner: Address,
+  amount: bigint,
+  decimals: number
+): Promise<Address> => {
+  const [token] = await findAssociatedTokenPda({
+    owner,
+    mint,
+    tokenProgram: TOKEN_PROGRAM_ADDRESS,
+  });
+
+  const transactionPlan = await createDefaultTransactionPlanner(
+    client,
+    payer
+  )(
+    getMintToATAInstructionPlan({
+      payer,
+      ata: token,
+      owner,
+      mint,
+      mintAuthority,
+      amount,
+      decimals,
+    })
+  );
+
+  await client.sendTransactionPlan(transactionPlan);
+  return token;
+};

clients/js/test/createMint.test.ts

@@ -1,11 +1,10 @@
 import { generateKeyPairSigner, Account, some, none } from '@solana/kit';
 import test from 'ava';
-import { fetchMint, Mint, createMintInstructionPlan } from '../src';
+import { fetchMint, Mint, getCreateMintInstructionPlan } from '../src';
 import {
   createDefaultSolanaClient,
   generateKeyPairSignerWithSol,
   createDefaultTransactionPlanner,
-  createDefaultTransactionPlanExecutor,
 } from './_setup';
 
 test('it creates and initializes a new mint account', async (t) => {
@@ -15,7 +14,7 @@ test('it creates and initializes a new mint account', async (t) => {
   const mint = await generateKeyPairSigner();
 
   // When we create and initialize a mint account at this address.
-  const instructionPlan = createMintInstructionPlan({
+  const instructionPlan = getCreateMintInstructionPlan({
     payer: authority,
     newMint: mint,
     decimals: 2,
@@ -24,8 +23,7 @@ test('it creates and initializes a new mint account', async (t) => {
 
   const transactionPlanner = createDefaultTransactionPlanner(client, authority);
   const transactionPlan = await transactionPlanner(instructionPlan);
-  const transactionPlanExecutor = createDefaultTransactionPlanExecutor(client);
-  await transactionPlanExecutor(transactionPlan);
+  await client.sendTransactionPlan(transactionPlan);
 
   // Then we expect the mint account to exist and have the following data.
   const mintAccount = await fetchMint(client.rpc, mint.address);
@@ -52,7 +50,7 @@ test('it creates a new mint account with a freeze authority', async (t) => {
   ]);
 
   // When we create and initialize a mint account at this address.
-  const instructionPlan = createMintInstructionPlan({
+  const instructionPlan = getCreateMintInstructionPlan({
     payer: payer,
     newMint: mint,
     decimals: 2,
@@ -62,8 +60,7 @@ test('it creates a new mint account with a freeze authority', async (t) => {
 
   const transactionPlanner = createDefaultTransactionPlanner(client, payer);
   const transactionPlan = await transactionPlanner(instructionPlan);
-  const transactionPlanExecutor = createDefaultTransactionPlanExecutor(client);
-  await transactionPlanExecutor(transactionPlan);
+  await client.sendTransactionPlan(transactionPlan);
 
   // Then we expect the mint account to exist and have the following data.
   const mintAccount = await fetchMint(client.rpc, mint.address);