@rialo/spl-token 0.3.0-alpha.0

package/README.md

@@ -0,0 +1,522 @@
+# Rialo SPL Token
+
+A TypeScript library for SPL Token-2022 operations on the Rialo blockchain. Provides account parsing, PDA derivation, instruction building, and a high-level client API for token operations.
+
+## Installation
+
+```bash
+npm install @rialo/spl-token @rialo/ts-cdk
+```
+
+Note: `@rialo/ts-cdk` is a peer dependency required for cryptographic primitives and RPC communication.
+
+## Quick Start
+
+### Get Token Balance
+
+```typescript
+import { createRialoClient, PublicKey, RIALO_DEVNET_CHAIN } from "@rialo/ts-cdk";
+import { createSplTokenClient } from "@rialo/spl-token";
+
+const rialoClient = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
+const tokenClient = createSplTokenClient({ client: rialoClient });
+
+const wallet = PublicKey.fromString("7EqQdEULxWcraVx3mXKFjc84LhCkMGZCkRuDpvcMwJeK");
+const mint = PublicKey.fromString("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+
+const balance = await tokenClient.getBalance({ wallet, mint });
+console.log(`Token balance: ${balance}`);
+```
+
+### Get Mint Information
+
+```typescript
+const mintInfo = await tokenClient.getMintInfo({ mint });
+
+console.log(`Supply: ${mintInfo.supply}`);
+console.log(`Decimals: ${mintInfo.decimals}`);
+console.log(`Mint Authority: ${mintInfo.mintAuthority?.toString() ?? "disabled"}`);
+console.log(`Freeze Authority: ${mintInfo.freezeAuthority?.toString() ?? "disabled"}`);
+```
+
+### Transfer Tokens
+
+```typescript
+import { Keypair } from "@rialo/ts-cdk";
+
+const signer = Keypair.fromSecretKey(secretKeyBytes);
+const recipient = PublicKey.fromString("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");
+
+// Get current block height for transaction validity
+const validFrom = BigInt(Date.now());
+
+// Transfer 1 token (with 6 decimals = 1,000,000 smallest units)
+const signature = await tokenClient.transfer({
+  params: {
+    source: signer.publicKey,
+    destination: recipient,
+    mint,
+    amount: 1_000_000n,
+    decimals: 6,
+  },
+  validFrom,
+  signer,
+});
+
+console.log(`Transfer complete: ${signature}`);
+```
+
+## Core Modules
+
+### SplTokenClient
+
+High-level client for common token operations.
+
+```typescript
+import { createSplTokenClient, SplTokenClient } from "@rialo/spl-token";
+
+// Create client (defaults to Token-2022 program)
+const tokenClient = createSplTokenClient({ client: rialoClient });
+
+// Query operations
+const mintInfo = await tokenClient.getMintInfo({ mint });
+const balance = await tokenClient.getBalance({ wallet, mint });
+const metadata = await tokenClient.getTokenMetadata({ mint });
+const tokenAccountInfo = await tokenClient.getTokenAccountInfo({ tokenAccount });
+
+// ATA operations
+const { address, bump } = tokenClient.getAssociatedTokenAddress({ wallet, mint });
+const exists = await tokenClient.ataExists({ wallet, mint });
+
+// Transfer operations
+const instructions = await tokenClient.createTransferInstructions(params);
+const tx = await tokenClient.createTransferTransaction({ params, validFrom });
+const signature = await tokenClient.transfer({ params, validFrom, signer });
+```
+
+### Account Parsing
+
+Parse raw account data into structured TypeScript objects.
+
+```typescript
+import { parseMintAccount, parseTokenAccount, parseTokenMetadata } from "@rialo/spl-token";
+
+// Parse mint account
+const accountInfo = await rialoClient.getAccountInfo(mintPubkey);
+const mintInfo = parseMintAccount({ address: mintPubkey, data: accountInfo.data });
+
+// MintInfo structure:
+// {
+//   address: PublicKey,
+//   supply: bigint,
+//   decimals: number,
+//   isInitialized: boolean,
+//   mintAuthority: PublicKey | null,
+//   freezeAuthority: PublicKey | null,
+// }
+
+// Parse token account
+const tokenAccountInfo = await rialoClient.getAccountInfo(tokenAccountPubkey);
+const tokenAccount = parseTokenAccount({ address: tokenAccountPubkey, data: tokenAccountInfo.data });
+
+// TokenAccountInfo structure:
+// {
+//   address: PublicKey,
+//   mint: PublicKey,
+//   owner: PublicKey,
+//   amount: bigint,
+//   delegate: PublicKey | null,
+//   state: TokenAccountState,
+//   isNative: bigint | null,
+//   delegatedAmount: bigint,
+//   closeAuthority: PublicKey | null,
+// }
+
+// Parse Token-2022 native metadata extension
+const metadata = parseTokenMetadata({ mint: mintPubkey, data: accountInfo.data });
+if (metadata) {
+  console.log(`Name: ${metadata.name}`);
+  console.log(`Symbol: ${metadata.symbol}`);
+  console.log(`URI: ${metadata.uri}`);
+}
+```
+
+### PDA Derivation
+
+Derive Associated Token Addresses (ATAs) for wallet/mint combinations.
+
+```typescript
+import {
+  findAssociatedTokenAddress,
+  getAssociatedTokenAddressSync,
+} from "@rialo/spl-token";
+
+// Get ATA with bump seed
+const { address, bump } = findAssociatedTokenAddress({ wallet, mint });
+console.log(`ATA: ${address.toString()}`);
+console.log(`Bump: ${bump}`);
+
+// Get just the address (convenience function)
+const ata = getAssociatedTokenAddressSync({ wallet, mint });
+
+// Use with legacy Token program
+import { TOKEN_PROGRAM_ID } from "@rialo/spl-token";
+
+const legacyProgramId = PublicKey.fromString(TOKEN_PROGRAM_ID);
+const legacyAta = findAssociatedTokenAddress({ wallet, mint, programId: legacyProgramId });
+```
+
+### Instruction Building
+
+Build SPL Token instructions for transactions.
+
+```typescript
+import {
+  initializeMintInstruction,
+  mintToInstruction,
+  transferCheckedInstruction,
+  transferInstruction,
+  createAssociatedTokenAccountInstruction,
+  createAssociatedTokenAccountIdempotentInstruction,
+} from "@rialo/spl-token";
+import { TransactionBuilder } from "@rialo/ts-cdk";
+
+// Initialize mint (Token-2022)
+const initMintIx = initializeMintInstruction({
+  mint,
+  decimals: 6,
+  mintAuthority,
+  freezeAuthority,
+});
+
+// Mint tokens to an account
+const mintToIx = mintToInstruction({
+  mint,
+  destination: destinationTokenAccount,
+  authority: mintAuthority,
+  amount: 1_000_000n,
+});
+
+// TransferChecked (recommended - includes decimals verification)
+const transferIx = transferCheckedInstruction({
+  source: sourceTokenAccount, // Source ATA
+  mint,                       // Token mint
+  destination: destTokenAccount, // Destination ATA
+  authority,                  // Owner of source account (signer)
+  amount: 1_000_000n,         // Amount in smallest units
+  decimals: 6,                // Expected decimals
+});
+
+// Create ATA (fails if exists)
+const createAtaIx = createAssociatedTokenAccountInstruction({
+  payer,                      // Account paying rent
+  associatedToken: ata,       // ATA address to create
+  owner,                      // Wallet that will own the ATA
+  mint,                       // Token mint
+});
+
+// Create ATA idempotently (succeeds even if exists)
+const createAtaIdempotentIx = createAssociatedTokenAccountIdempotentInstruction({
+  payer,
+  associatedToken: ata,
+  owner,
+  mint,
+});
+
+// Build transaction
+const validFrom = BigInt(Date.now());
+const tx = TransactionBuilder.create()
+  .setPayer(payer)
+  .setValidFrom(validFrom)
+  .addInstruction(initMintIx)
+  .addInstruction(createAtaIdempotentIx)
+  .addInstruction(mintToIx)
+  .addInstruction(transferIx)
+  .build();
+
+const signedTx = tx.sign(keypair);
+const signature = await rialoClient.sendTransaction(signedTx.serialize());
+```
+
+### Error Handling
+
+Structured error handling with specific error codes.
+
+```typescript
+import { SplTokenError, SplTokenErrorCode } from "@rialo/spl-token";
+
+try {
+  const balance = await tokenClient.getBalance({ wallet, mint });
+} catch (error) {
+  if (error instanceof SplTokenError) {
+    switch (error.code) {
+      case SplTokenErrorCode.MINT_NOT_FOUND:
+        console.log("Mint does not exist");
+        break;
+      case SplTokenErrorCode.TOKEN_ACCOUNT_NOT_FOUND:
+        console.log("Token account does not exist");
+        break;
+      case SplTokenErrorCode.ACCOUNT_NOT_INITIALIZED:
+        console.log("Account exists but is not initialized");
+        break;
+      case SplTokenErrorCode.INSUFFICIENT_BALANCE:
+        console.log(`Insufficient balance: ${error.details?.available}`);
+        break;
+      case SplTokenErrorCode.ACCOUNT_FROZEN:
+        console.log("Token account is frozen");
+        break;
+      default:
+        console.log(`Token error: ${error.message}`);
+    }
+  }
+}
+```
+
+## Constants
+
+```typescript
+import {
+  // Program IDs
+  TOKEN_2022_PROGRAM_ID,      // "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
+  ASSOCIATED_TOKEN_PROGRAM_ID, // "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"
+  TOKEN_PROGRAM_ID,           // "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" (legacy)
+
+  // Account sizes
+  MINT_SIZE,          // 82 bytes
+  TOKEN_ACCOUNT_SIZE, // 165 bytes
+
+  // Enums
+  TokenAccountState,  // Uninitialized, Initialized, Frozen
+  TokenInstruction,   // Transfer, TransferChecked, etc.
+  ExtensionType,      // TokenMetadata, TransferFeeConfig, etc.
+  AccountType,        // Uninitialized, Mint, Account
+} from "@rialo/spl-token";
+```
+
+## Types
+
+```typescript
+import type {
+  MintInfo,
+  TokenAccountInfo,
+  TokenMetadata,
+  TransferParams,
+  AtaDerivationResult,
+  TokenAccountFilter,
+  RawExtension,
+  MetadataPointerExtension,
+  Instruction,
+  AccountMeta,
+} from "@rialo/spl-token";
+
+// TransferParams for high-level transfer operations
+const params: TransferParams = {
+  source: senderWallet,          // Source wallet public key
+  destination: recipientWallet,  // Destination wallet public key
+  mint: mintPubkey,              // Token mint
+  amount: 1_000_000n,            // Amount in smallest units
+  decimals: 6,                   // Token decimals
+  createDestinationAta: true,    // Auto-create destination ATA (default: true)
+};
+```
+
+## Token-2022 Extensions
+
+The library supports parsing Token-2022 extension data:
+
+```typescript
+import {
+  parseTokenMetadata,
+  parseMetadataPointerExtension,
+  getMintExtensions,
+  ExtensionType,
+} from "@rialo/spl-token";
+
+// Get all extensions from a mint
+const extensions = getMintExtensions({ data: mintAccountData });
+for (const ext of extensions) {
+  console.log(`Extension type: ${ext.type}`);
+}
+
+// Parse specific extensions
+const metadata = parseTokenMetadata({ mint, data: mintAccountData });
+const pointer = parseMetadataPointerExtension({ data: mintAccountData });
+```
+
+## Examples
+
+### Complete Transfer Workflow
+
+```typescript
+import { createRialoClient, Keypair, PublicKey, RIALO_DEVNET_CHAIN } from "@rialo/ts-cdk";
+import { createSplTokenClient } from "@rialo/spl-token";
+
+async function transferTokens() {
+  // Setup clients
+  const rialoClient = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
+  const tokenClient = createSplTokenClient({ client: rialoClient });
+
+  // Load wallet
+  const sender = Keypair.fromSecretKey(/* your secret key */);
+  const recipient = PublicKey.fromString("RecipientAddress...");
+  const mint = PublicKey.fromString("TokenMintAddress...");
+
+  // Get mint info for decimals
+  const mintInfo = await tokenClient.getMintInfo({ mint });
+
+  // Check sender balance
+  const senderBalance = await tokenClient.getBalance({ wallet: sender.publicKey, mint });
+  console.log(`Sender balance: ${senderBalance}`);
+
+  // Calculate transfer amount (1 token)
+  const amount = BigInt(10 ** mintInfo.decimals);
+
+  if (senderBalance < amount) {
+    throw new Error("Insufficient balance");
+  }
+
+  // Execute transfer
+  const validFrom = BigInt(Date.now());
+  const signature = await tokenClient.transfer({
+    params: {
+      source: sender.publicKey,
+      destination: recipient,
+      mint,
+      amount,
+      decimals: mintInfo.decimals,
+    },
+    validFrom,
+    signer: sender,
+  });
+
+  console.log(`Transfer successful: ${signature}`);
+
+  // Verify new balances
+  const newSenderBalance = await tokenClient.getBalance({ wallet: sender.publicKey, mint });
+  const recipientBalance = await tokenClient.getBalance({ wallet: recipient, mint });
+  console.log(`New sender balance: ${newSenderBalance}`);
+  console.log(`Recipient balance: ${recipientBalance}`);
+}
+```
+
+### Manual Transaction Building
+
+```typescript
+import { TransactionBuilder, PublicKey } from "@rialo/ts-cdk";
+import {
+  findAssociatedTokenAddress,
+  createAssociatedTokenAccountIdempotentInstruction,
+  transferCheckedInstruction,
+  TOKEN_2022_PROGRAM_ID,
+} from "@rialo/spl-token";
+
+async function buildTransferTransaction(
+  sender: PublicKey,
+  recipient: PublicKey,
+  mint: PublicKey,
+  amount: bigint,
+  decimals: number,
+) {
+  const programId = PublicKey.fromString(TOKEN_2022_PROGRAM_ID);
+
+  // Derive ATAs
+  const senderAta = findAssociatedTokenAddress({ wallet: sender, mint, programId }).address;
+  const recipientAta = findAssociatedTokenAddress({ wallet: recipient, mint, programId }).address;
+
+  // Build transaction with both instructions
+  const validFrom = BigInt(Date.now());
+  const tx = TransactionBuilder.create()
+    .setPayer(sender)
+    .setValidFrom(validFrom)
+    .addInstruction(
+      createAssociatedTokenAccountIdempotentInstruction({
+        payer: sender,
+        associatedToken: recipientAta,
+        owner: recipient,
+        mint,
+        programId,
+      }),
+    )
+    .addInstruction(
+      transferCheckedInstruction({
+        source: senderAta,
+        mint,
+        destination: recipientAta,
+        authority: sender,
+        amount,
+        decimals,
+        programId,
+      }),
+    )
+    .build();
+
+  return tx;
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+## API Reference
+
+### SplTokenClient Methods
+
+| Method | Description |
+| --- | --- |
+| `getMintInfo({ mint })` | Get mint account information |
+| `getTokenMetadata({ mint })` | Get Token-2022 native metadata |
+| `getTokenAccountInfo({ tokenAccount })` | Get token account information |
+| `getBalance({ wallet, mint })` | Get token balance for a wallet |
+| `getAssociatedTokenAddress({ wallet, mint })` | Derive ATA address |
+| `ataExists({ wallet, mint })` | Check if ATA exists |
+| `createTransferInstructions(params)` | Build transfer instructions |
+| `createTransferTransaction({ params, validFrom })` | Build complete transaction |
+| `transfer({ params, validFrom, signer })` | Execute transfer |
+
+### Parsing Functions
+
+| Function | Description |
+| --- | --- |
+| `parseMintAccount({ address, data })` | Parse mint account data |
+| `parseTokenAccount({ address, data })` | Parse token account data |
+| `parseTokenMetadata({ mint, data })` | Parse Token-2022 metadata extension |
+| `parseMetadataPointerExtension({ data })` | Parse metadata pointer extension |
+| `getMintExtensions({ data })` | Get all extensions from mint |
+
+### Instruction Builders
+
+| Function | Description |
+| --- | --- |
+| `initializeMintInstruction({ mint, decimals, mintAuthority, freezeAuthority?, programId? })` | Build InitializeMint2 instruction |
+| `mintToInstruction({ mint, destination, authority, amount, programId? })` | Build MintTo instruction |
+| `transferCheckedInstruction({ source, mint, destination, authority, amount, decimals, programId? })` | Build TransferChecked instruction |
+| `transferInstruction({ source, destination, authority, amount, programId? })` | Build Transfer instruction (legacy) |
+| `createAssociatedTokenAccountInstruction({ payer, associatedToken, owner, mint, programId? })` | Build CreateATA instruction |
+| `createAssociatedTokenAccountIdempotentInstruction({ payer, associatedToken, owner, mint, programId? })` | Build idempotent CreateATA |
+
+### PDA Functions
+
+| Function | Description |
+| --- | --- |
+| `findAssociatedTokenAddress({ wallet, mint, programId? })` | Derive ATA with bump |
+| `getAssociatedTokenAddressSync({ wallet, mint, programId? })` | Derive ATA address only |
+
+## License
+
+Apache License 2.0