@solana-program/token-wrap 2.3.0 → 2.5.0

package/src/index.ts

@@ -0,0 +1,23 @@
+export * from './generated';
+
+export { createMint, type CreateMintArgs, type CreateMintResult } from './create-mint';
+export {
+    singleSignerWrap,
+    type SingleSignerWrapArgs,
+    type SingleSignerWrapResult,
+    multisigOfflineSignWrap,
+    type MultiSignerWrapIxBuilderArgs,
+} from './wrap';
+export {
+    singleSignerUnwrap,
+    type SingleSignerUnwrapArgs,
+    type SingleSignerUnwrapResult,
+    multisigOfflineSignUnwrap,
+} from './unwrap';
+export {
+    createEscrowAccount,
+    type CreateEscrowAccountArgs,
+    type CreateEscrowAccountResult,
+    combinedMultisigTx,
+    type MultiSigCombineArgs,
+} from './utilities';

package/src/unwrap.ts

@@ -0,0 +1,208 @@
+import { findAssociatedTokenPda, getTokenDecoder } from '@solana-program/token-2022';
+import {
+    Address,
+    appendTransactionMessageInstructions,
+    Blockhash,
+    createTransactionMessage,
+    fetchEncodedAccount,
+    GetAccountInfoApi,
+    Instruction,
+    pipe,
+    Rpc,
+    setTransactionMessageFeePayerSigner,
+    setTransactionMessageLifetimeUsingBlockhash,
+    TransactionMessage,
+    TransactionMessageWithBlockhashLifetime,
+    TransactionMessageWithFeePayerSigner,
+    TransactionSigner,
+} from '@solana/kit';
+import { findWrappedMintAuthorityPda, getUnwrapInstruction, UnwrapInput } from './generated';
+import { getMintFromTokenAccount, getOwnerFromAccount } from './utilities';
+
+export interface SingleSignerUnwrapArgs {
+    rpc: Rpc<GetAccountInfoApi>;
+    payer: TransactionSigner; // Fee payer and default transfer authority
+    wrappedTokenAccount: Address;
+    amount: bigint | number;
+    recipientUnwrappedToken: Address;
+    // Optional arguments below (will be derived/defaulted if not provided)
+    transferAuthority?: Address | TransactionSigner; // Defaults to payer
+    unwrappedMint?: Address; // Will derive from unwrappedEscrow if not provided
+    wrappedTokenProgram?: Address; // Will derive from wrappedTokenAccount if not provided
+    unwrappedTokenProgram?: Address; // Will derive from unwrappedEscrow if not provided
+}
+
+async function resolveUnwrapAddrs({
+    rpc,
+    payer,
+    wrappedTokenAccount,
+    recipientUnwrappedToken,
+    inputUnwrappedMint,
+    inputTransferAuthority,
+    inputWrappedTokenProgram,
+    inputUnwrappedTokenProgram,
+}: {
+    rpc: Rpc<GetAccountInfoApi>;
+    payer: TransactionSigner;
+    wrappedTokenAccount: Address;
+    recipientUnwrappedToken: Address;
+    inputUnwrappedMint?: Address;
+    inputTransferAuthority?: Address | TransactionSigner;
+    inputWrappedTokenProgram?: Address;
+    inputUnwrappedTokenProgram?: Address;
+}) {
+    const wrappedTokenProgram = inputWrappedTokenProgram ?? (await getOwnerFromAccount(rpc, wrappedTokenAccount));
+    const unwrappedTokenProgram =
+        inputUnwrappedTokenProgram ?? (await getOwnerFromAccount(rpc, recipientUnwrappedToken));
+    const unwrappedMint = inputUnwrappedMint ?? (await getMintFromTokenAccount(rpc, recipientUnwrappedToken));
+
+    // Get wrapped mint from the token account being burned
+    const wrappedAccountInfo = await fetchEncodedAccount(rpc, wrappedTokenAccount);
+    if (!wrappedAccountInfo.exists) {
+        throw new Error(`Wrapped token account ${wrappedTokenAccount} not found.`);
+    }
+    const wrappedMint = getTokenDecoder().decode(wrappedAccountInfo.data).mint;
+
+    const [wrappedMintAuthority] = await findWrappedMintAuthorityPda({ wrappedMint });
+
+    // Default transfer authority to payer if not provided
+    const transferAuthority = inputTransferAuthority ?? payer;
+
+    return {
+        unwrappedMint,
+        wrappedMint,
+        wrappedMintAuthority,
+        transferAuthority,
+        wrappedTokenProgram,
+        unwrappedTokenProgram,
+    };
+}
+
+interface UnwrapTxBuilderArgs {
+    wrappedTokenAccount: Address;
+    amount: bigint | number;
+    wrappedMint: Address;
+    wrappedMintAuthority: Address;
+    unwrappedMint: Address;
+    recipientUnwrappedToken: Address;
+    unwrappedTokenProgram: Address;
+    wrappedTokenProgram: Address;
+    transferAuthority: Address | TransactionSigner;
+    multiSigners?: TransactionSigner[];
+}
+
+async function buildUnwrapTransaction({
+    recipientUnwrappedToken,
+    wrappedMintAuthority,
+    unwrappedMint,
+    wrappedTokenProgram,
+    unwrappedTokenProgram,
+    wrappedTokenAccount,
+    wrappedMint,
+    transferAuthority,
+    amount,
+    multiSigners = [],
+}: UnwrapTxBuilderArgs): Promise<Instruction> {
+    const [unwrappedEscrow] = await findAssociatedTokenPda({
+        owner: wrappedMintAuthority,
+        mint: unwrappedMint,
+        tokenProgram: unwrappedTokenProgram,
+    });
+
+    const unwrapInstructionInput: UnwrapInput = {
+        unwrappedEscrow,
+        recipientUnwrappedToken,
+        wrappedMintAuthority,
+        unwrappedMint,
+        wrappedTokenProgram,
+        unwrappedTokenProgram,
+        wrappedTokenAccount,
+        wrappedMint,
+        transferAuthority,
+        amount: BigInt(amount),
+        multiSigners,
+    };
+
+    return getUnwrapInstruction(unwrapInstructionInput);
+}
+
+export interface SingleSignerUnwrapResult {
+    ixs: Instruction[];
+    recipientUnwrappedToken: Address;
+    amount: bigint;
+}
+
+/**
+ * Creates, signs (single signer or default authority), and sends an unwrap transaction.
+ * Derives necessary PDAs and default accounts if not provided.
+ */
+export async function singleSignerUnwrap({
+    rpc,
+    payer,
+    wrappedTokenAccount,
+    amount,
+    recipientUnwrappedToken,
+    transferAuthority: inputTransferAuthority,
+    unwrappedMint: inputUnwrappedMint,
+    wrappedTokenProgram: inputWrappedTokenProgram,
+    unwrappedTokenProgram: inputUnwrappedTokenProgram,
+}: SingleSignerUnwrapArgs): Promise<SingleSignerUnwrapResult> {
+    const {
+        wrappedMint,
+        wrappedMintAuthority,
+        transferAuthority,
+        unwrappedTokenProgram,
+        unwrappedMint,
+        wrappedTokenProgram,
+    } = await resolveUnwrapAddrs({
+        rpc,
+        payer,
+        wrappedTokenAccount,
+        recipientUnwrappedToken,
+        inputUnwrappedMint,
+        inputTransferAuthority,
+        inputWrappedTokenProgram,
+        inputUnwrappedTokenProgram,
+    });
+
+    const ix = await buildUnwrapTransaction({
+        recipientUnwrappedToken,
+        wrappedMintAuthority,
+        unwrappedMint,
+        wrappedTokenProgram,
+        unwrappedTokenProgram,
+        wrappedTokenAccount,
+        wrappedMint,
+        transferAuthority,
+        amount,
+    });
+
+    return {
+        recipientUnwrappedToken,
+        amount: BigInt(amount),
+        ixs: [ix],
+    };
+}
+
+export interface MultiSignerUnWrapTxBuilderArgs extends UnwrapTxBuilderArgs {
+    payer: TransactionSigner;
+    blockhash: {
+        blockhash: Blockhash;
+        lastValidBlockHeight: bigint;
+    };
+    multiSigners: TransactionSigner[];
+}
+
+// Used to collect signatures
+export async function multisigOfflineSignUnwrap(
+    args: MultiSignerUnWrapTxBuilderArgs,
+): Promise<TransactionMessage & TransactionMessageWithBlockhashLifetime & TransactionMessageWithFeePayerSigner> {
+    const unwrapIx = await buildUnwrapTransaction(args);
+
+    return pipe(
+        createTransactionMessage({ version: 0 }),
+        tx => setTransactionMessageFeePayerSigner(args.payer, tx),
+        tx => setTransactionMessageLifetimeUsingBlockhash(args.blockhash, tx),
+        tx => appendTransactionMessageInstructions([unwrapIx], tx),
+    );
+}

package/src/utilities.ts

@@ -0,0 +1,234 @@
+import { getCreateAccountInstruction } from '@solana-program/system';
+import { getInitializeAccountInstruction as initializeToken, TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
+import {
+    fetchMaybeToken,
+    findAssociatedTokenPda,
+    getCreateAssociatedTokenInstruction,
+    getTokenDecoder,
+    InitializeAccountInput,
+    getInitializeAccountInstruction as initializeToken2022,
+    Token,
+    TOKEN_2022_PROGRAM_ADDRESS,
+} from '@solana-program/token-2022';
+import {
+    Account,
+    Address,
+    assertIsFullySignedTransaction,
+    assertIsSendableTransaction,
+    Blockhash,
+    containsBytes,
+    fetchEncodedAccount,
+    FullySignedTransaction,
+    generateKeyPairSigner,
+    GetAccountInfoApi,
+    GetMinimumBalanceForRentExemptionApi,
+    Instruction,
+    KeyPairSigner,
+    Rpc,
+    SignatureBytes,
+    Transaction,
+    TransactionWithBlockhashLifetime,
+    TransactionWithinSizeLimit,
+} from '@solana/kit';
+import { findWrappedMintAuthorityPda, findWrappedMintPda } from './generated';
+
+function getInitializeTokenFn(tokenProgram: Address): (input: InitializeAccountInput) => Instruction {
+    if (tokenProgram === TOKEN_PROGRAM_ADDRESS) return initializeToken;
+    if (tokenProgram === TOKEN_2022_PROGRAM_ADDRESS) return initializeToken2022;
+    throw new Error(`${tokenProgram} is not a valid token program.`);
+}
+
+export async function createTokenAccount({
+    rpc,
+    payer,
+    mint,
+    owner,
+    tokenProgram,
+}: {
+    rpc: Rpc<GetMinimumBalanceForRentExemptionApi>;
+    payer: KeyPairSigner;
+    mint: Address;
+    owner: Address;
+    tokenProgram: Address;
+}): Promise<{ ixs: Instruction[]; keyPair: KeyPairSigner }> {
+    const [keyPair, lamports] = await Promise.all([
+        generateKeyPairSigner(),
+        rpc.getMinimumBalanceForRentExemption(165n).send(),
+    ]);
+
+    const createAccountIx = getCreateAccountInstruction({
+        payer,
+        newAccount: keyPair,
+        lamports,
+        space: 165,
+        programAddress: tokenProgram,
+    });
+
+    const initializeAccountIx = getInitializeTokenFn(tokenProgram)({
+        account: keyPair.address,
+        mint,
+        owner,
+    });
+
+    return {
+        ixs: [createAccountIx, initializeAccountIx],
+        keyPair,
+    };
+}
+
+export interface CreateEscrowAccountArgs {
+    rpc: Rpc<GetAccountInfoApi & GetMinimumBalanceForRentExemptionApi>;
+    payer: KeyPairSigner;
+    unwrappedMint: Address;
+    wrappedTokenProgram: Address;
+}
+
+export type CreateEscrowAccountResult =
+    | { kind: 'already_exists'; account: Account<Token> }
+    | {
+          kind: 'instructions_to_create';
+          address: Address;
+          ixs: Instruction[];
+      };
+
+export async function createEscrowAccount({
+    rpc,
+    payer,
+    unwrappedMint,
+    wrappedTokenProgram,
+}: CreateEscrowAccountArgs): Promise<CreateEscrowAccountResult> {
+    const [wrappedMint] = await findWrappedMintPda({ unwrappedMint, wrappedTokenProgram });
+    const [wrappedMintAuthority] = await findWrappedMintAuthorityPda({ wrappedMint });
+    const unwrappedTokenProgram = await getOwnerFromAccount(rpc, unwrappedMint);
+
+    const [escrowAta] = await findAssociatedTokenPda({
+        owner: wrappedMintAuthority,
+        mint: unwrappedMint,
+        tokenProgram: unwrappedTokenProgram,
+    });
+
+    const escrowResult = await fetchMaybeToken(rpc, escrowAta);
+    if (escrowResult.exists) {
+        return { kind: 'already_exists', account: escrowResult };
+    }
+
+    const ix = getCreateAssociatedTokenInstruction({
+        payer,
+        owner: wrappedMintAuthority,
+        mint: unwrappedMint,
+        ata: escrowAta,
+        tokenProgram: unwrappedTokenProgram,
+    }) as Instruction;
+
+    return { address: escrowAta, ixs: [ix], kind: 'instructions_to_create' };
+}
+
+export async function getOwnerFromAccount(rpc: Rpc<GetAccountInfoApi>, accountAddress: Address): Promise<Address> {
+    const accountInfo = await rpc.getAccountInfo(accountAddress, { encoding: 'base64' }).send();
+    if (!accountInfo.value) {
+        throw new Error(`Account ${accountAddress} not found.`);
+    }
+    return accountInfo.value.owner;
+}
+
+export async function getMintFromTokenAccount(
+    rpc: Rpc<GetAccountInfoApi>,
+    tokenAccountAddress: Address,
+): Promise<Address> {
+    const account = await fetchEncodedAccount(rpc, tokenAccountAddress);
+    if (!account.exists) {
+        throw new Error(`Unwrapped token account ${tokenAccountAddress} not found.`);
+    }
+    return getTokenDecoder().decode(account.data).mint;
+}
+
+function messageBytesEqual(results: (Transaction & TransactionWithBlockhashLifetime)[]): boolean {
+    // If array has only one element, return true
+    if (results.length === 1) {
+        return true;
+    }
+
+    // Use the first result as reference
+    const reference = results[0];
+    if (!reference) throw new Error('No transactions in input');
+
+    // Compare each result with the reference
+    return results.every(
+        c =>
+            reference.messageBytes.length === c.messageBytes.length &&
+            containsBytes(reference.messageBytes, c.messageBytes, 0),
+    );
+}
+
+function combineSignatures(
+    signedTxs: (Transaction & TransactionWithBlockhashLifetime)[],
+): Record<string, SignatureBytes> {
+    // Step 1: Determine the canonical signer order from the first signed transaction.
+    //         Insertion order is the way to re-create this. Without it, verification will fail.
+    const firstSignedTx = signedTxs[0];
+    if (!firstSignedTx) {
+        throw new Error('No signed transactions provided');
+    }
+
+    const allSignatures: Record<string, SignatureBytes | null> = {};
+
+    // Step 1: Insert a null signature for each signer, maintaining the order of the signatures from the first signed transaction
+    for (const pubkey of Object.keys(firstSignedTx.signatures)) {
+        allSignatures[pubkey] = null;
+    }
+
+    // Step 2: Gather all signatures from all transactions
+    for (const signedTx of signedTxs) {
+        for (const [address, signature] of Object.entries(signedTx.signatures)) {
+            if (signature) {
+                // only store non-null signers
+                allSignatures[address] = signature;
+            }
+        }
+    }
+
+    // Step 3: Assert all signatures are set
+    const missingSigners: string[] = [];
+    for (const [pubkey, signature] of Object.entries(allSignatures)) {
+        if (signature === null) {
+            missingSigners.push(pubkey);
+        }
+    }
+    if (missingSigners.length > 0) {
+        throw new Error(`Missing signatures for: ${missingSigners.join(', ')}`);
+    }
+
+    return allSignatures as Record<string, SignatureBytes>;
+}
+
+export interface MultiSigCombineArgs {
+    signedTxs: (Transaction & TransactionWithBlockhashLifetime)[];
+    blockhash: {
+        blockhash: Blockhash;
+        lastValidBlockHeight: bigint;
+    };
+}
+
+// Combines, validates, and broadcasts outputs of multisig offline partially signed txs
+export function combinedMultisigTx({
+    signedTxs,
+    blockhash,
+}: MultiSigCombineArgs): Transaction &
+    FullySignedTransaction &
+    TransactionWithBlockhashLifetime &
+    TransactionWithinSizeLimit {
+    const messagesEqual = messageBytesEqual(signedTxs);
+    if (!messagesEqual) throw new Error('Messages are not all the same');
+    if (!signedTxs[0]) throw new Error('No signed transactions provided');
+
+    const tx = {
+        messageBytes: signedTxs[0].messageBytes,
+        signatures: combineSignatures(signedTxs),
+        lifetimeConstraint: blockhash,
+    };
+
+    assertIsFullySignedTransaction(tx);
+    assertIsSendableTransaction(tx);
+
+    return tx;
+}

package/src/wrap.ts

@@ -0,0 +1,211 @@
+import { findAssociatedTokenPda } from '@solana-program/token-2022';
+import {
+    Address,
+    appendTransactionMessageInstructions,
+    Blockhash,
+    createTransactionMessage,
+    GetAccountInfoApi,
+    Instruction,
+    pipe,
+    Rpc,
+    setTransactionMessageFeePayerSigner,
+    setTransactionMessageLifetimeUsingBlockhash,
+    TransactionMessage,
+    TransactionMessageWithBlockhashLifetime,
+    TransactionMessageWithFeePayerSigner,
+    TransactionSigner,
+} from '@solana/kit';
+import { findWrappedMintAuthorityPda, findWrappedMintPda, getWrapInstruction, WrapInput } from './generated';
+import { getMintFromTokenAccount, getOwnerFromAccount } from './utilities';
+
+interface IxBuilderArgs {
+    unwrappedTokenAccount: Address;
+    wrappedTokenProgram: Address;
+    amount: bigint | number;
+    wrappedMint: Address;
+    wrappedMintAuthority: Address;
+    transferAuthority: Address | TransactionSigner;
+    unwrappedMint: Address;
+    recipientWrappedTokenAccount: Address;
+    unwrappedTokenProgram: Address;
+    multiSigners?: TransactionSigner[];
+}
+
+export interface MultiSignerWrapIxBuilderArgs extends IxBuilderArgs {
+    payer: TransactionSigner;
+    blockhash: {
+        blockhash: Blockhash;
+        lastValidBlockHeight: bigint;
+    };
+    multiSigners: TransactionSigner[];
+}
+
+// Used to collect signatures
+export async function multisigOfflineSignWrap(
+    args: MultiSignerWrapIxBuilderArgs,
+): Promise<TransactionMessage & TransactionMessageWithBlockhashLifetime & TransactionMessageWithFeePayerSigner> {
+    const wrapIx = await buildWrapIx(args);
+
+    return pipe(
+        createTransactionMessage({ version: 0 }),
+        tx => setTransactionMessageFeePayerSigner(args.payer, tx),
+        tx => setTransactionMessageLifetimeUsingBlockhash(args.blockhash, tx),
+        tx => appendTransactionMessageInstructions([wrapIx], tx),
+    );
+}
+
+export interface SingleSignerWrapArgs {
+    rpc: Rpc<GetAccountInfoApi>;
+    payer: TransactionSigner; // Fee payer and default transfer authority
+    unwrappedTokenAccount: Address;
+    wrappedTokenProgram: Address;
+    amount: bigint | number;
+    transferAuthority?: Address | TransactionSigner; // Defaults to payer if not provided
+    unwrappedMint?: Address; // Will fetch from unwrappedTokenAccount if not provided
+    recipientWrappedTokenAccount?: Address; // Defaults to payer's ATA if not provided
+    unwrappedTokenProgram?: Address; // Will fetch from unwrappedTokenAccount owner if not provided
+}
+
+export interface SingleSignerWrapResult {
+    ixs: Instruction[];
+    recipientWrappedTokenAccount: Address;
+    escrowAccount: Address;
+    amount: bigint;
+}
+
+export async function singleSignerWrap({
+    rpc,
+    payer,
+    unwrappedTokenAccount,
+    wrappedTokenProgram,
+    amount,
+    transferAuthority: inputTransferAuthority,
+    unwrappedMint: inputUnwrappedMint,
+    recipientWrappedTokenAccount: inputRecipientTokenAccount,
+    unwrappedTokenProgram: inputUnwrappedTokenProgram,
+}: SingleSignerWrapArgs): Promise<SingleSignerWrapResult> {
+    const {
+        unwrappedMint,
+        unwrappedTokenProgram,
+        wrappedMint,
+        wrappedMintAuthority,
+        recipientWrappedTokenAccount,
+        transferAuthority,
+        unwrappedEscrow,
+    } = await resolveAddrs({
+        rpc,
+        payer,
+        inputTransferAuthority,
+        inputUnwrappedMint,
+        unwrappedTokenAccount,
+        inputUnwrappedTokenProgram,
+        wrappedTokenProgram,
+        inputRecipientTokenAccount,
+    });
+
+    const ix = await buildWrapIx({
+        unwrappedTokenAccount,
+        wrappedTokenProgram,
+        amount,
+        transferAuthority,
+        unwrappedMint,
+        wrappedMint,
+        wrappedMintAuthority,
+        recipientWrappedTokenAccount,
+        unwrappedTokenProgram,
+    });
+
+    return {
+        ixs: [ix],
+        recipientWrappedTokenAccount,
+        escrowAccount: unwrappedEscrow,
+        amount: BigInt(amount),
+    };
+}
+
+// Meant to handle all of the potential default values
+async function resolveAddrs({
+    rpc,
+    payer,
+    unwrappedTokenAccount,
+    wrappedTokenProgram,
+    inputTransferAuthority,
+    inputUnwrappedMint,
+    inputRecipientTokenAccount,
+    inputUnwrappedTokenProgram,
+}: {
+    rpc: Rpc<GetAccountInfoApi>;
+    payer: TransactionSigner;
+    unwrappedTokenAccount: Address;
+    wrappedTokenProgram: Address;
+    inputTransferAuthority?: Address | TransactionSigner;
+    inputUnwrappedMint?: Address;
+    inputRecipientTokenAccount?: Address;
+    inputUnwrappedTokenProgram?: Address;
+}) {
+    const unwrappedMint = inputUnwrappedMint ?? (await getMintFromTokenAccount(rpc, unwrappedTokenAccount));
+    const unwrappedTokenProgram = inputUnwrappedTokenProgram ?? (await getOwnerFromAccount(rpc, unwrappedTokenAccount));
+    const [wrappedMint] = await findWrappedMintPda({ unwrappedMint, wrappedTokenProgram });
+    const [wrappedMintAuthority] = await findWrappedMintAuthorityPda({ wrappedMint });
+    const recipientWrappedTokenAccount =
+        inputRecipientTokenAccount ??
+        (
+            await findAssociatedTokenPda({
+                owner: payer.address,
+                mint: wrappedMint,
+                tokenProgram: wrappedTokenProgram,
+            })
+        )[0];
+    const [unwrappedEscrow] = await findAssociatedTokenPda({
+        owner: wrappedMintAuthority,
+        mint: unwrappedMint,
+        tokenProgram: unwrappedTokenProgram,
+    });
+
+    const transferAuthority = inputTransferAuthority ?? payer;
+
+    return {
+        unwrappedEscrow,
+        transferAuthority,
+        unwrappedMint,
+        unwrappedTokenProgram,
+        wrappedMint,
+        wrappedMintAuthority,
+        recipientWrappedTokenAccount,
+    };
+}
+
+async function buildWrapIx({
+    unwrappedTokenAccount,
+    wrappedTokenProgram,
+    amount,
+    transferAuthority,
+    unwrappedMint,
+    recipientWrappedTokenAccount,
+    unwrappedTokenProgram,
+    wrappedMint,
+    wrappedMintAuthority,
+    multiSigners = [],
+}: IxBuilderArgs): Promise<Instruction> {
+    const [unwrappedEscrow] = await findAssociatedTokenPda({
+        owner: wrappedMintAuthority,
+        mint: unwrappedMint,
+        tokenProgram: unwrappedTokenProgram,
+    });
+
+    const wrapInstructionInput: WrapInput = {
+        recipientWrappedTokenAccount,
+        wrappedMint,
+        wrappedMintAuthority,
+        unwrappedTokenProgram,
+        wrappedTokenProgram,
+        unwrappedTokenAccount,
+        unwrappedMint,
+        unwrappedEscrow,
+        transferAuthority,
+        amount: BigInt(amount),
+        multiSigners,
+    };
+
+    return getWrapInstruction(wrapInstructionInput);
+}