@thru/token-program 0.2.1

package/src/accounts.ts

@@ -0,0 +1,72 @@
+import { encodeAddress } from '@thru/helpers';
+import type { Account } from '@thru/thru-sdk';
+import { Pubkey as AbiPubkey } from './abi/thru/common/primitives/types';
+import {
+  TickerField,
+  TokenAccount,
+  TokenMintAccount,
+} from './abi/thru/program/token/types';
+import type { MintAccountInfo, TokenAccountInfo } from './types';
+
+const TEXT_DECODER = new TextDecoder();
+
+export function parseMintAccountData(account: Account): MintAccountInfo {
+  const data = account.data?.data;
+  if (!data) {
+    throw new Error('Mint account data is missing');
+  }
+
+  const parsed = TokenMintAccount.from_array(data);
+  if (!parsed) {
+    throw new Error('Mint account data is malformed');
+  }
+
+  const hasFreezeAuthority = parsed.get_has_freeze_authority() === 1;
+  const freezeAuthority = hasFreezeAuthority
+    ? encodeAddress(pubkeyToBytes(parsed.get_freeze_authority()))
+    : null;
+
+  return {
+    decimals: parsed.get_decimals(),
+    supply: parsed.get_supply(),
+    creator: encodeAddress(pubkeyToBytes(parsed.get_creator())),
+    mintAuthority: encodeAddress(pubkeyToBytes(parsed.get_mint_authority())),
+    freezeAuthority,
+    hasFreezeAuthority,
+    ticker: decodeTicker(parsed.get_ticker()),
+  };
+}
+
+export function parseTokenAccountData(account: Account): TokenAccountInfo {
+  const data = account.data?.data;
+  if (!data) {
+    throw new Error('Token account data is missing');
+  }
+
+  const parsed = TokenAccount.from_array(data);
+  if (!parsed) {
+    throw new Error('Token account data is malformed');
+  }
+
+  return {
+    mint: encodeAddress(pubkeyToBytes(parsed.get_mint())),
+    owner: encodeAddress(pubkeyToBytes(parsed.get_owner())),
+    amount: parsed.get_amount(),
+    isFrozen: parsed.get_is_frozen() === 1,
+  };
+}
+
+export function isAccountNotFoundError(err: unknown): boolean {
+  if (!err) return false;
+  return (err as { code?: number }).code === 5;
+}
+
+function pubkeyToBytes(pubkey: AbiPubkey): Uint8Array {
+  return Uint8Array.from(pubkey.bytes);
+}
+
+function decodeTicker(field: TickerField): string {
+  const length = field.get_length();
+  const bytes = Uint8Array.from(field.get_bytes()).slice(0, length);
+  return TEXT_DECODER.decode(bytes).replace(/\0+$/, '');
+}

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const PUBKEY_LENGTH = 32;
+export const TICKER_MAX_LENGTH = 8;
+export const ZERO_PUBKEY = new Uint8Array(PUBKEY_LENGTH);

package/src/derivation.ts

@@ -0,0 +1,74 @@
+import { deriveAddress, deriveProgramAddress, Pubkey } from '@thru/thru-sdk';
+import { PUBKEY_LENGTH } from './constants';
+
+const TOKEN_ACCOUNT_DEFAULT_SEED = new Uint8Array(PUBKEY_LENGTH);
+
+export function deriveMintAddress(
+  mintAuthorityAddress: string,
+  seed: string,
+  tokenProgramAddress: string
+): { address: string; bytes: Uint8Array; derivedSeed: Uint8Array } {
+  const mintAuthorityBytes = Pubkey.from(mintAuthorityAddress).toBytes();
+  const seedBytes = hexToBytes(seed);
+  if (seedBytes.length !== 32) throw new Error('Seed must be 32 bytes (64 hex characters)');
+
+  const { bytes: derivedSeed } = deriveAddress([mintAuthorityBytes, seedBytes]);
+
+  const result = deriveProgramAddress({
+    programAddress: tokenProgramAddress,
+    seed: derivedSeed,
+    ephemeral: false,
+  });
+
+  return {
+    address: result.address,
+    bytes: result.bytes,
+    derivedSeed,
+  };
+}
+
+export function deriveTokenAccountAddress(
+  ownerAddress: string,
+  mintAddress: string,
+  tokenProgramAddress: string,
+  seed: Uint8Array = TOKEN_ACCOUNT_DEFAULT_SEED
+): { address: string; bytes: Uint8Array; derivedSeed: Uint8Array } {
+  if (seed.length !== PUBKEY_LENGTH) throw new Error('Token account seed must be 32 bytes');
+
+  const ownerBytes = Pubkey.from(ownerAddress).toBytes();
+  const mintBytes = Pubkey.from(mintAddress).toBytes();
+
+  const { bytes: derivedSeed } = deriveAddress([ownerBytes, mintBytes, seed]);
+
+  const result = deriveProgramAddress({
+    programAddress: tokenProgramAddress,
+    seed: derivedSeed,
+    ephemeral: false,
+  });
+
+  return {
+    address: result.address,
+    bytes: result.bytes,
+    derivedSeed,
+  };
+}
+
+export function deriveWalletSeed(
+  walletAddress: string,
+  extraSeeds: Uint8Array[] = []
+): Uint8Array {
+  const walletBytes = Pubkey.from(walletAddress).toBytes();
+  return deriveAddress([walletBytes, ...extraSeeds]).bytes;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const normalized = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (normalized.length % 2 !== 0) {
+    throw new Error('Hex string must have even number of characters');
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let i = 0; i < normalized.length; i += 2) {
+    bytes[i / 2] = parseInt(normalized.substring(i, i + 2), 16);
+  }
+  return bytes;
+}

package/src/format.ts

@@ -0,0 +1,24 @@
+export function formatRawAmount(amount: bigint, decimals: number): string {
+  if (decimals === 0) return amount.toString();
+  const scale = BigInt(10) ** BigInt(decimals);
+  const whole = amount / scale;
+  const fraction = amount % scale;
+  const fractionStr = fraction.toString().padStart(decimals, '0').replace(/0+$/, '');
+  return fractionStr ? `${whole.toString()}.${fractionStr}` : whole.toString();
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const normalized = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (normalized.length % 2 !== 0) {
+    throw new Error('Hex string must have even number of characters');
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let i = 0; i < normalized.length; i += 2) {
+    bytes[i / 2] = parseInt(normalized.substring(i, i + 2), 16);
+  }
+  return bytes;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Types
+export type {
+  AccountLookupContext,
+  InstructionData,
+  MintAccountInfo,
+  TokenAccountInfo,
+  InitializeMintArgs,
+  InitializeAccountArgs,
+  MintToArgs,
+  TransferArgs,
+} from './types';
+
+// Constants
+export { PUBKEY_LENGTH, TICKER_MAX_LENGTH, ZERO_PUBKEY } from './constants';
+
+// Instructions
+export {
+  createInitializeMintInstruction,
+  createInitializeAccountInstruction,
+  createMintToInstruction,
+  createTransferInstruction,
+  buildTokenInstructionBytes,
+} from './instructions/index';
+
+// Derivation
+export { deriveMintAddress, deriveTokenAccountAddress, deriveWalletSeed } from './derivation';
+
+// Account parsing
+export { parseMintAccountData, parseTokenAccountData, isAccountNotFoundError } from './accounts';
+
+// Formatting
+export { formatRawAmount, bytesToHex, hexToBytes } from './format';

package/src/instructions/index.ts

@@ -0,0 +1,5 @@
+export { createInitializeMintInstruction } from './initialize-mint';
+export { createInitializeAccountInstruction } from './initialize-account';
+export { createMintToInstruction } from './mint-to';
+export { createTransferInstruction } from './transfer';
+export { buildTokenInstructionBytes } from './shared';

package/src/instructions/initialize-account.ts

@@ -0,0 +1,27 @@
+import { InitializeAccountInstructionBuilder } from '../abi/thru/program/token/types';
+import type { AccountLookupContext, InitializeAccountArgs, InstructionData } from '../types';
+import { buildTokenInstructionBytes } from './shared';
+
+export function createInitializeAccountInstruction(
+  args: InitializeAccountArgs
+): InstructionData {
+  if (args.seedBytes.length !== 32) {
+    throw new Error('Token account seed must be 32 bytes');
+  }
+
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    const tokenAccountIndex = context.getAccountIndex(args.tokenAccountBytes);
+    const mintAccountIndex = context.getAccountIndex(args.mintAccountBytes);
+    const ownerAccountIndex = context.getAccountIndex(args.ownerAccountBytes);
+
+    const payload = new InitializeAccountInstructionBuilder()
+      .set_token_account_index(tokenAccountIndex)
+      .set_mint_account_index(mintAccountIndex)
+      .set_owner_account_index(ownerAccountIndex)
+      .set_new_account_seed(args.seedBytes)
+      .set_state_proof(args.stateProof)
+      .build();
+
+    return buildTokenInstructionBytes('initialize_account', payload);
+  };
+}

package/src/instructions/initialize-mint.ts

@@ -0,0 +1,76 @@
+import {
+  InitializeMintInstructionBuilder,
+  TickerFieldBuilder,
+} from '../abi/thru/program/token/types';
+import { TICKER_MAX_LENGTH, ZERO_PUBKEY } from '../constants';
+import type { AccountLookupContext, InitializeMintArgs, InstructionData } from '../types';
+import { buildTokenInstructionBytes } from './shared';
+
+const TEXT_ENCODER = new TextEncoder();
+
+export function hexToBytes(hex: string): Uint8Array {
+  const normalized = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (normalized.length % 2 !== 0) {
+    throw new Error('Hex string must have even number of characters');
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let i = 0; i < normalized.length; i += 2) {
+    bytes[i / 2] = parseInt(normalized.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+export function createInitializeMintInstruction({
+  mintAccountBytes,
+  decimals,
+  mintAuthorityBytes,
+  freezeAuthorityBytes,
+  ticker,
+  seedHex,
+  stateProof,
+  creatorBytes,
+}: InitializeMintArgs): InstructionData {
+  const hasFreezeAuthority = freezeAuthorityBytes ? 1 : 0;
+  const seedBytes = hexToBytes(seedHex);
+  if (seedBytes.length !== 32) {
+    throw new Error('Seed must be 32 bytes (64 hex characters)');
+  }
+  const tickerFieldBytes = buildTickerFieldBytes(ticker);
+  const creator = creatorBytes ?? mintAuthorityBytes;
+
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    const mintAccountIndex = context.getAccountIndex(mintAccountBytes);
+    const mintAuthority = mintAuthorityBytes;
+    const freezeAuthority = freezeAuthorityBytes ?? ZERO_PUBKEY;
+
+    const payload = new InitializeMintInstructionBuilder()
+      .set_mint_account_index(mintAccountIndex)
+      .set_decimals(decimals)
+      .set_creator(creator)
+      .set_mint_authority(mintAuthority)
+      .set_freeze_authority(freezeAuthority)
+      .set_has_freeze_authority(hasFreezeAuthority)
+      .set_ticker(tickerFieldBytes)
+      .set_seed(seedBytes)
+      .set_state_proof(stateProof)
+      .build();
+
+    return buildTokenInstructionBytes('initialize_mint', payload);
+  };
+}
+
+function buildTickerFieldBytes(ticker: string): Uint8Array {
+  const normalized = ticker.trim().toUpperCase();
+  const tickerBytes = TEXT_ENCODER.encode(normalized);
+  if (tickerBytes.length > TICKER_MAX_LENGTH) {
+    throw new Error('Ticker must be 8 characters or less');
+  }
+
+  const padded = new Uint8Array(TICKER_MAX_LENGTH);
+  padded.set(tickerBytes);
+
+  return new TickerFieldBuilder()
+    .set_length(tickerBytes.length)
+    .set_bytes(Array.from(padded))
+    .build();
+}

package/src/instructions/mint-to.ts

@@ -0,0 +1,26 @@
+import { MintToInstructionBuilder } from '../abi/thru/program/token/types';
+import type { AccountLookupContext, MintToArgs, InstructionData } from '../types';
+import { buildTokenInstructionBytes } from './shared';
+
+type MintToInstructionBuilderWithBigInt = MintToInstructionBuilder & {
+  set_amount(value: number | bigint): MintToInstructionBuilder;
+};
+
+export function createMintToInstruction(args: MintToArgs): InstructionData {
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    const mintAccountIndex = context.getAccountIndex(args.mintAccountBytes);
+    const destinationIndex = context.getAccountIndex(args.destinationAccountBytes);
+    const authorityIndex = context.getAccountIndex(args.authorityAccountBytes);
+
+    const payloadBuilder = new MintToInstructionBuilder()
+      .set_mint_account_index(mintAccountIndex)
+      .set_dest_account_index(destinationIndex)
+      .set_authority_account_index(authorityIndex);
+
+    (payloadBuilder as MintToInstructionBuilderWithBigInt).set_amount(args.amount);
+
+    const payload = payloadBuilder.build();
+
+    return buildTokenInstructionBytes('mint_to', payload);
+  };
+}

package/src/instructions/shared.ts

@@ -0,0 +1,20 @@
+import {
+  TokenInstruction,
+  TokenInstructionBuilder,
+} from '../abi/thru/program/token/types';
+
+import type { AccountLookupContext } from '../types';
+
+export type { AccountLookupContext };
+
+type TokenInstructionVariantName =
+  (typeof TokenInstruction.payloadVariantDescriptors)[number]['name'];
+
+export function buildTokenInstructionBytes(
+  variant: TokenInstructionVariantName,
+  payload: Uint8Array
+): Uint8Array {
+  const builder = new TokenInstructionBuilder();
+  builder.payload().select(variant).writePayload(payload).finish();
+  return builder.build();
+}

package/src/instructions/transfer.ts

@@ -0,0 +1,24 @@
+import { TransferInstruction, TransferInstructionBuilder } from '../abi/thru/program/token/types';
+import type { AccountLookupContext, TransferArgs, InstructionData } from '../types';
+import { buildTokenInstructionBytes } from './shared';
+
+type TransferInstructionBuilderWithBigInt = TransferInstructionBuilder & {
+  set_amount(value: number | bigint): TransferInstructionBuilder;
+};
+
+export function createTransferInstruction(args: TransferArgs): InstructionData {
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    const sourceIndex = context.getAccountIndex(args.sourceAccountBytes);
+    const destinationIndex = context.getAccountIndex(args.destinationAccountBytes);
+
+    const payloadBuilder = TransferInstruction.builder()
+      .set_source_account_index(sourceIndex)
+      .set_dest_account_index(destinationIndex);
+
+    (payloadBuilder as TransferInstructionBuilderWithBigInt).set_amount(args.amount);
+
+    const payload = payloadBuilder.build();
+
+    return buildTokenInstructionBytes('transfer', payload);
+  };
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+export type AccountLookupContext = {
+  getAccountIndex: (pubkey: Uint8Array) => number;
+};
+
+export type InstructionData = (context: AccountLookupContext) => Promise<Uint8Array>;
+
+export interface MintAccountInfo {
+  decimals: number;
+  supply: bigint;
+  creator: string;
+  mintAuthority: string;
+  freezeAuthority: string | null;
+  hasFreezeAuthority: boolean;
+  ticker: string;
+}
+
+export interface TokenAccountInfo {
+  mint: string;
+  owner: string;
+  amount: bigint;
+  isFrozen: boolean;
+}
+
+export interface InitializeMintArgs {
+  mintAccountBytes: Uint8Array;
+  decimals: number;
+  creatorBytes?: Uint8Array;
+  mintAuthorityBytes: Uint8Array;
+  freezeAuthorityBytes?: Uint8Array;
+  ticker: string;
+  seedHex: string;
+  stateProof: Uint8Array;
+}
+
+export interface InitializeAccountArgs {
+  tokenAccountBytes: Uint8Array;
+  mintAccountBytes: Uint8Array;
+  ownerAccountBytes: Uint8Array;
+  seedBytes: Uint8Array;
+  stateProof: Uint8Array;
+}
+
+export interface MintToArgs {
+  mintAccountBytes: Uint8Array;
+  destinationAccountBytes: Uint8Array;
+  authorityAccountBytes: Uint8Array;
+  amount: bigint;
+}
+
+export interface TransferArgs {
+  sourceAccountBytes: Uint8Array;
+  destinationAccountBytes: Uint8Array;
+  amount: bigint;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  treeshake: true,
+});