@xswap-link/sdk 0.10.7 → 0.10.9

package/src/services/svm/README.md

@@ -0,0 +1,483 @@
+# CCIP Solana SDK
+
+A TypeScript SDK for interacting with the Chainlink CCIP protocol on Solana.
+
+## Installation
+
+This SDK is part of the CCIP library and is not published as a standalone npm package. To use it:
+
+1. Clone this repository
+2. Import the modules directly from the codebase
+
+```typescript
+// Example import from local codebase
+import { CCIPClient } from "../path/to/ccip-lib/svm";
+```
+
+## Key Features
+
+- Fee calculation for CCIP messages with support for various token types
+- Message sending with transaction monitoring and compute budget management
+- Message ID extraction from transaction logs with event parsing
+- ExtraArgs generation for cross-chain messages with customizable gas limits
+- Comprehensive PDA utilities for all CCIP account types
+- Anchor-generated bindings for all CCIP accounts and instructions
+- Flexible configuration management with dependency injection
+- Structured logging throughout the SDK
+- Token pool management (burn-mint pools) for cross-chain token transfers
+
+## Architecture
+
+The SDK follows a modular architecture with clear separation of concerns:
+
+### Core Components
+
+- **CCIPClient**: Main entry point for SDK functionality (fee calculation, message sending, token pool access)
+- **CCIPAccountReader**: Handles fetching and decoding on-chain CCIP accounts
+- **Models**: Type definitions shared across all components
+
+### Token Pools
+
+- **TokenPoolClient**: Abstract interface for token pool operations
+- **BurnMintTokenPoolClient**: Implementation for burn-mint token pools
+- **TokenPoolFactory**: Factory for creating and detecting token pool types
+
+### Bindings
+
+- **Accounts**: Auto-generated Anchor bindings for all on-chain account structs
+- **Instructions**: Auto-generated Anchor bindings for all on-chain instructions
+- **Types**: Type definitions for core CCIP protocol data structures
+
+### Utilities
+
+- **PDAs**: Comprehensive utilities for deriving all program-derived addresses
+- **Logger**: Structured logging with configurable log levels
+- **Conversion**: Helper functions for data type conversions
+- **Error Handling**: Standardized error types and handling
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { 
+  CCIPClient, 
+  CCIPSendRequest,
+  ExtraArgsOptions,
+  CCIPContext,
+  CCIPProvider,
+  CCIPCoreConfig,
+  LogLevel,
+  createLogger,
+} from "../path/to/ccip-lib/svm";
+import { PublicKey, Connection, Keypair } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+
+// Create a provider (application responsibility)
+const connection = new Connection("https://api.devnet.solana.com", "confirmed");
+const keypair = Keypair.fromSecretKey(/* your secret key */);
+
+const provider: CCIPProvider = {
+  connection,
+  wallet: keypair,
+  getAddress(): PublicKey {
+    return keypair.publicKey;
+  },
+  async signTransaction(tx) {
+    if (tx instanceof VersionedTransaction) {
+      tx.sign([keypair]);
+    } else {
+      tx.partialSign(keypair);
+    }
+    return tx;
+  },
+};
+
+// Create configuration (application responsibility)
+const config: CCIPCoreConfig = {
+  ccipRouterProgramId: new PublicKey(
+    "Ccip8ZTcM2qHjVt8FYHtuCAqjc637yLKnsJ5q5r2e6eL"
+  ),
+  feeQuoterProgramId: new PublicKey(
+    "FeeQhewH1cd6ZyHqhfMiKAQntgzPT6bWwK26cJ5qSFo6"
+  ),
+  rmnRemoteProgramId: new PublicKey(
+    "RmnAZiCJdaYtwR1f634Ba7yNJXuK3pS6kHuX4FgNgX8"
+  ),
+  linkTokenMint: new PublicKey("D3HCrigxfvScYyokPC1YGpNgqyheVMVwbgP7XPywvEdc"),
+  tokenMint: new PublicKey("7AC59PVvR64EoMnLX45FHnJAYzPsxdViyYBsaGEQPFvh"),
+  nativeSol: PublicKey.default,
+  systemProgramId: new PublicKey("11111111111111111111111111111111"),
+  ethereumSepoliaSelector: BigInt("16015286601757825753"),
+  programId: new PublicKey("52XvWQKuZHRjnR7qHsEGE532jqgQ3MBiBMgVkBowP1LD"),
+};
+
+// Create context with provider and config
+const context: CCIPContext = {
+  provider,
+  config,
+  logger: createLogger("my-app", { level: LogLevel.INFO }),
+};
+
+// Create CCIPClient with the context
+const client = new CCIPClient(context);
+
+// Create extraArgs configuration
+const extraArgsConfig: ExtraArgsOptions = {
+  gasLimit: 200000,
+  allowOutOfOrderExecution: true,
+};
+
+// Generate the extraArgs buffer
+const extraArgs = client.createExtraArgs(extraArgsConfig);
+
+// Create a CCIP send request
+const sendRequest: CCIPSendRequest = {
+  destChainSelector: new BN("16015286601757825753"),
+  receiver: Buffer.from(
+    "0x9d087fC03ae39b088326b67fA3C788236645b717".slice(2),
+    "hex"
+  ),
+  data: Buffer.alloc(0), // Empty data for token transfer only
+  tokenAmounts: [
+    {
+      token: new PublicKey("7AC59PVvR64EoMnLX45FHnJAYzPsxdViyYBsaGEQPFvh"),
+      amount: new BN(10000000), // 0.01 tokens with 9 decimals
+    },
+  ],
+  feeToken: PublicKey.default, // Use native SOL
+  extraArgs: extraArgs,
+};
+
+// Calculate fee first (optional)
+const feeRequest = {
+  destChainSelector: sendRequest.destChainSelector,
+  message: {
+    receiver: sendRequest.receiver,
+    data: sendRequest.data,
+    tokenAmounts: sendRequest.tokenAmounts,
+    feeToken: sendRequest.feeToken,
+    extraArgs: extraArgs,
+  },
+};
+
+const feeResult = await client.getFee(feeRequest);
+console.log(`Estimated fee: ${feeResult.amount.toString()}`);
+
+// Send the message and get message ID
+const result = await client.sendWithMessageId(sendRequest);
+console.log(`Message sent! Transaction: ${result.txSignature}`);
+console.log(`Message ID: ${result.messageId}`);
+console.log(`Destination Chain Selector: ${result.destinationChainSelector}`);
+console.log(`Sequence Number: ${result.sequenceNumber}`);
+```
+
+### Using with Wallet Adapters
+
+You can easily integrate with Solana wallet adapters:
+
+```typescript
+import { 
+  CCIPClient, 
+  CCIPContext, 
+  CCIPProvider,
+  CCIPCoreConfig,
+} from "../path/to/ccip-lib/svm";
+import {
+  Connection,
+  PublicKey,
+  Transaction,
+  VersionedTransaction,
+} from "@solana/web3.js";
+import { useWallet } from "@solana/wallet-adapter-react";
+
+// In your React component
+function MyComponent() {
+  const { publicKey, signTransaction } = useWallet();
+  const connection = new Connection("https://api.devnet.solana.com");
+
+  // Create provider from wallet adapter
+  const provider: CCIPProvider = {
+    connection,
+    wallet: null, // Not used directly with wallet adapter
+    getAddress(): PublicKey {
+      return publicKey;
+    },
+    async signTransaction(tx: Transaction | VersionedTransaction) {
+      return await signTransaction(tx);
+    },
+  };
+
+  // Get your config from application
+  const config: CCIPCoreConfig = {
+    // ...your config properties
+  };
+
+  // Create context
+  const context: CCIPContext = {
+    provider,
+    config,
+  };
+
+  // Create client
+  const client = new CCIPClient(context);
+  
+  // Use client...
+}
+```
+
+### ExtraArgs Configuration
+
+The SDK supports creating properly formatted extraArgs for CCIP messages:
+
+```typescript
+// Configure extraArgs with options
+const extraArgs = client.createExtraArgs({
+  gasLimit: 200000, // Gas limit for execution on destination chain
+  allowOutOfOrderExecution: true, // Whether to allow out-of-order execution
+});
+
+// Or use default values
+const defaultExtraArgs = client.createExtraArgs();
+```
+
+### Using the Account Reader
+
+The CCIPAccountReader provides convenient methods to fetch and decode on-chain accounts:
+
+```typescript
+// Get the account reader from the client
+const accountReader = client.getAccountReader();
+
+// Fetch token admin registry for a token
+const tokenRegistry = await accountReader.getTokenAdminRegistry(tokenMint);
+
+// Fetch CCIP configuration
+const config = await accountReader.getConfig();
+
+// Fetch destination chain state
+const destChainState = await accountReader.getDestChainState(destChainSelector);
+```
+
+## PDA Utilities
+
+The SDK provides comprehensive utility functions for calculating Program Derived Addresses (PDAs) used throughout the CCIP protocol.
+
+### Token Pools Signer PDAs
+
+When delegating token authority for CCIP cross-chain transfers, it's crucial to understand that there are two different types of PDA signers:
+
+1. `feeBillingSignerPDA` - Used for fee payments (derived with the `fee_billing_signer` seed)
+2. `tokenPoolsSignerPDA` - Used for token transfers (derived with the `external_token_pools_signer` seed)
+
+#### Important Note About Token Pool Signers
+
+The token pool signer PDA is more complex than it initially appears. In the CCIP protocol, the actual PDA used for token transfers is derived using **both**:
+
+1. The `external_token_pools_signer` seed
+2. The pool program ID (which is specific to each token)
+
+The pool program ID is stored in a lookup table that is part of the token admin registry for each token. This means a simple `findExternalTokenPoolsSignerPDA` function that uses only the seed is **not sufficient** for accurate delegation.
+
+#### PDA Functions
+
+To address this complexity, the SDK provides several functions:
+
+```typescript
+// Basic function - not sufficient for token transfers
+findExternalTokenPoolsSignerPDA(programId: PublicKey): [PublicKey, number]
+
+// Recommended - dynamically finds the correct token pool signer PDA
+findDynamicTokenPoolsSignerPDA(
+  mint: PublicKey, 
+  routerProgramId: PublicKey,
+  connection: Connection
+): Promise<[PublicKey, number]>
+
+// Alternative using CCIPAccountReader
+findTokenPoolsSignerWithAccountReader(
+  mint: PublicKey,
+  routerProgramId: PublicKey,
+  accountReader: CCIPAccountReader,
+  connection: Connection
+): Promise<[PublicKey, number]>
+```
+
+### Other Important PDAs
+
+The SDK provides utilities for all PDAs used in the CCIP protocol:
+
+```typescript
+// Router configuration PDA
+findConfigPDA(programId: PublicKey): [PublicKey, number]
+
+// Fee billing signer PDA (for fee payments)
+findFeeBillingSignerPDA(programId: PublicKey): [PublicKey, number]
+
+// Token admin registry PDA
+findTokenAdminRegistryPDA(mint: PublicKey, programId: PublicKey): [PublicKey, number]
+
+// Destination chain state PDA
+findDestChainStatePDA(chainSelector: bigint, programId: PublicKey): [PublicKey, number]
+
+// Nonce PDA
+findNoncePDA(chainSelector: bigint, authority: PublicKey, programId: PublicKey): [PublicKey, number]
+
+// Token pool chain config PDA
+findTokenPoolChainConfigPDA(
+  chainSelector: bigint,
+  tokenMint: PublicKey,
+  programId: PublicKey
+): [PublicKey, number]
+```
+
+#### Usage for Token Delegation
+
+When delegating token authority to the CCIP protocol, you should:
+
+1. Use `findFeeBillingSignerPDA` for fee token delegation (e.g., SOL)
+2. Use `findDynamicTokenPoolsSignerPDA` for token transfer delegation (e.g., BnM, LINK) 
+
+```typescript
+// For fee token delegation (e.g., SOL)
+const [feeBillingSigner] = findFeeBillingSignerPDA(routerProgramId);
+
+// For token transfer delegation (e.g., BnM, LINK)
+const [tokenPoolsSigner] = await findDynamicTokenPoolsSignerPDA(
+  tokenMint, 
+  routerProgramId,
+  connection
+);
+```
+
+## Token Pool Support
+
+The SDK provides support for interacting with different types of token pools used by CCIP for cross-chain transfers.
+
+### Token Pool Types
+
+Currently, the SDK supports the following pool types:
+
+- **Burn-Mint Pools**: Tokens are burned on the source chain and minted on the destination chain.
+
+### Using Token Pools
+
+Token pools can be accessed through the `CCIPClient`:
+
+```typescript
+// Get a burn-mint token pool client
+const burnMintPool = client.getTokenPoolClient(TokenPoolType.BURN_MINT);
+
+// Or auto-detect the pool type for a specific token mint
+const pool = await client.getTokenPoolClientForMint(tokenMint);
+
+// Create a new pool for a token
+const txSignature = await pool.createPool(tokenMint);
+
+// Configure a chain for cross-chain transfers
+const chainConfig = {
+  enabled: true,
+  maxTokensPerMessage: new BN(1000000000), // 1 token with 9 decimals
+  feeBps: 10 // 0.1% fee
+};
+await pool.configureChain(tokenMint, destinationChainSelector, chainConfig);
+
+// Set rate limits for a token
+await pool.setRateLimit(
+  tokenMint,
+  new BN(1000000000), // Capacity: 1 token with 9 decimals
+  new BN(100000000)   // Rate: 0.1 tokens per second
+);
+
+// Transfer admin role for a token pool
+await pool.transferAdminRole(tokenMint, newAdminPublicKey);
+```
+
+### Token Pool Factory
+
+For advanced usage, you can use the `TokenPoolFactory` directly:
+
+```typescript
+import { TokenPoolFactory, TokenPoolType } from "../path/to/ccip-lib/svm";
+
+// Create a specific token pool type
+const pool = TokenPoolFactory.create(TokenPoolType.BURN_MINT, context);
+
+// Auto-detect the token pool type for a mint
+const poolType = await TokenPoolFactory.detectPoolType(tokenMint, context);
+const pool = TokenPoolFactory.create(poolType, context);
+```
+
+### PDA Utilities for Token Pools
+
+The SDK provides functions to derive all program-derived addresses used in token pools:
+
+```typescript
+import {
+  findBurnMintPoolConfigPDA,
+  findBurnMintPoolChainConfigPDA,
+  findRateLimitPDA
+} from "../path/to/ccip-lib/svm";
+
+// Get the pool config PDA
+const [poolConfigPDA] = findBurnMintPoolConfigPDA(tokenMint, burnMintPoolProgramId);
+
+// Get the chain config PDA
+const [chainConfigPDA] = findBurnMintPoolChainConfigPDA(
+  chainSelector,
+  tokenMint, 
+  burnMintPoolProgramId
+);
+
+// Get the rate limit PDA
+const [rateLimitPDA] = findRateLimitPDA(tokenMint, burnMintPoolProgramId);
+```
+
+## Error Handling
+
+The SDK uses standardized error handling with custom error types:
+
+```typescript
+import {
+  CCIPError,
+  CCIPTransactionError,
+  CCIPAccountError,
+} from "../path/to/ccip-lib/svm";
+
+try {
+  await client.sendWithMessageId(sendRequest);
+} catch (error) {
+  if (error instanceof CCIPTransactionError) {
+    console.error(`Transaction failed: ${error.message}`, error.txSignature);
+  } else if (error instanceof CCIPAccountError) {
+    console.error(`Account error: ${error.message}`, error.account);
+  } else if (error instanceof CCIPError) {
+    console.error(`CCIP error: ${error.message}`);
+  } else {
+    console.error(`Unknown error: ${error}`);
+  }
+}
+```
+
+## Logging
+
+The SDK supports structured logging with configurable log levels:
+
+```typescript
+import { createLogger, LogLevel } from "../path/to/ccip-lib/svm";
+
+// Create a logger with custom configuration
+const logger = createLogger("my-component", { 
+  level: LogLevel.DEBUG,
+  pretty: true, // For human-readable logs
+  skipTimestamp: false, // Include timestamps
+});
+
+// Use the logger
+logger.info("Processing request", { destination: "ethereum" });
+logger.debug("Technical details", { request: sendRequest });
+logger.error("Operation failed", { error });
+
+// Change log level at runtime
+logger.setLevel(LogLevel.WARN);
+```

package/src/services/svm/bindings/accounts/AllowedOfframp.ts

@@ -0,0 +1,73 @@
+import { PublicKey, Connection } from "@solana/web3.js"
+import BN from "bn.js" // eslint-disable-line @typescript-eslint/no-unused-vars
+import * as borsh from "@coral-xyz/borsh" // eslint-disable-line @typescript-eslint/no-unused-vars
+import * as types from "../types" // eslint-disable-line @typescript-eslint/no-unused-vars
+import { PROGRAM_ID } from "../programId"
+
+export interface AllowedOfframpFields {}
+
+export interface AllowedOfframpJSON {}
+
+export class AllowedOfframp {
+  static readonly discriminator = Buffer.from([
+    247, 97, 179, 16, 207, 36, 236, 132,
+  ])
+
+  static readonly layout = borsh.struct([])
+
+  constructor(fields: AllowedOfframpFields) {}
+
+  static async fetch(
+    c: Connection,
+    address: PublicKey,
+    programId: PublicKey = PROGRAM_ID
+  ): Promise<AllowedOfframp | null> {
+    const info = await c.getAccountInfo(address)
+
+    if (info === null) {
+      return null
+    }
+    if (!info.owner.equals(programId)) {
+      throw new Error("account doesn't belong to this program")
+    }
+
+    return this.decode(info.data)
+  }
+
+  static async fetchMultiple(
+    c: Connection,
+    addresses: PublicKey[],
+    programId: PublicKey = PROGRAM_ID
+  ): Promise<Array<AllowedOfframp | null>> {
+    const infos = await c.getMultipleAccountsInfo(addresses)
+
+    return infos.map((info) => {
+      if (info === null) {
+        return null
+      }
+      if (!info.owner.equals(programId)) {
+        throw new Error("account doesn't belong to this program")
+      }
+
+      return this.decode(info.data)
+    })
+  }
+
+  static decode(data: Buffer): AllowedOfframp {
+    if (!data.slice(0, 8).equals(AllowedOfframp.discriminator)) {
+      throw new Error("invalid account discriminator")
+    }
+
+    const dec = AllowedOfframp.layout.decode(data.slice(8))
+
+    return new AllowedOfframp({})
+  }
+
+  toJSON(): AllowedOfframpJSON {
+    return {}
+  }
+
+  static fromJSON(obj: AllowedOfframpJSON): AllowedOfframp {
+    return new AllowedOfframp({})
+  }
+}

package/src/services/svm/bindings/accounts/Config.ts

@@ -0,0 +1,153 @@
+import { PublicKey, Connection } from "@solana/web3.js"
+import BN from "bn.js" // eslint-disable-line @typescript-eslint/no-unused-vars
+import * as borsh from "@coral-xyz/borsh" // eslint-disable-line @typescript-eslint/no-unused-vars
+import * as types from "../types" // eslint-disable-line @typescript-eslint/no-unused-vars
+import { PROGRAM_ID } from "../programId"
+
+export interface ConfigFields {
+  version: number
+  defaultCodeVersion: types.CodeVersionKind
+  svmChainSelector: BN
+  owner: PublicKey
+  proposedOwner: PublicKey
+  feeQuoter: PublicKey
+  rmnRemote: PublicKey
+  linkTokenMint: PublicKey
+  feeAggregator: PublicKey
+}
+
+export interface ConfigJSON {
+  version: number
+  defaultCodeVersion: types.CodeVersionJSON
+  svmChainSelector: string
+  owner: string
+  proposedOwner: string
+  feeQuoter: string
+  rmnRemote: string
+  linkTokenMint: string
+  feeAggregator: string
+}
+
+export class Config {
+  readonly version: number
+  readonly defaultCodeVersion: types.CodeVersionKind
+  readonly svmChainSelector: BN
+  readonly owner: PublicKey
+  readonly proposedOwner: PublicKey
+  readonly feeQuoter: PublicKey
+  readonly rmnRemote: PublicKey
+  readonly linkTokenMint: PublicKey
+  readonly feeAggregator: PublicKey
+
+  static readonly discriminator = Buffer.from([
+    155, 12, 170, 224, 30, 250, 204, 130,
+  ])
+
+  static readonly layout = borsh.struct([
+    borsh.u8("version"),
+    types.CodeVersion.layout("defaultCodeVersion"),
+    borsh.u64("svmChainSelector"),
+    borsh.publicKey("owner"),
+    borsh.publicKey("proposedOwner"),
+    borsh.publicKey("feeQuoter"),
+    borsh.publicKey("rmnRemote"),
+    borsh.publicKey("linkTokenMint"),
+    borsh.publicKey("feeAggregator"),
+  ])
+
+  constructor(fields: ConfigFields) {
+    this.version = fields.version
+    this.defaultCodeVersion = fields.defaultCodeVersion
+    this.svmChainSelector = fields.svmChainSelector
+    this.owner = fields.owner
+    this.proposedOwner = fields.proposedOwner
+    this.feeQuoter = fields.feeQuoter
+    this.rmnRemote = fields.rmnRemote
+    this.linkTokenMint = fields.linkTokenMint
+    this.feeAggregator = fields.feeAggregator
+  }
+
+  static async fetch(
+    c: Connection,
+    address: PublicKey,
+    programId: PublicKey = PROGRAM_ID
+  ): Promise<Config | null> {
+    const info = await c.getAccountInfo(address)
+
+    if (info === null) {
+      return null
+    }
+    if (!info.owner.equals(programId)) {
+      throw new Error("account doesn't belong to this program")
+    }
+
+    return this.decode(info.data)
+  }
+
+  static async fetchMultiple(
+    c: Connection,
+    addresses: PublicKey[],
+    programId: PublicKey = PROGRAM_ID
+  ): Promise<Array<Config | null>> {
+    const infos = await c.getMultipleAccountsInfo(addresses)
+
+    return infos.map((info) => {
+      if (info === null) {
+        return null
+      }
+      if (!info.owner.equals(programId)) {
+        throw new Error("account doesn't belong to this program")
+      }
+
+      return this.decode(info.data)
+    })
+  }
+
+  static decode(data: Buffer): Config {
+    if (!data.slice(0, 8).equals(Config.discriminator)) {
+      throw new Error("invalid account discriminator")
+    }
+
+    const dec = Config.layout.decode(data.slice(8))
+
+    return new Config({
+      version: dec.version,
+      defaultCodeVersion: types.CodeVersion.fromDecoded(dec.defaultCodeVersion),
+      svmChainSelector: dec.svmChainSelector,
+      owner: dec.owner,
+      proposedOwner: dec.proposedOwner,
+      feeQuoter: dec.feeQuoter,
+      rmnRemote: dec.rmnRemote,
+      linkTokenMint: dec.linkTokenMint,
+      feeAggregator: dec.feeAggregator,
+    })
+  }
+
+  toJSON(): ConfigJSON {
+    return {
+      version: this.version,
+      defaultCodeVersion: this.defaultCodeVersion.toJSON(),
+      svmChainSelector: this.svmChainSelector.toString(),
+      owner: this.owner.toString(),
+      proposedOwner: this.proposedOwner.toString(),
+      feeQuoter: this.feeQuoter.toString(),
+      rmnRemote: this.rmnRemote.toString(),
+      linkTokenMint: this.linkTokenMint.toString(),
+      feeAggregator: this.feeAggregator.toString(),
+    }
+  }
+
+  static fromJSON(obj: ConfigJSON): Config {
+    return new Config({
+      version: obj.version,
+      defaultCodeVersion: types.CodeVersion.fromJSON(obj.defaultCodeVersion),
+      svmChainSelector: new BN(obj.svmChainSelector),
+      owner: new PublicKey(obj.owner),
+      proposedOwner: new PublicKey(obj.proposedOwner),
+      feeQuoter: new PublicKey(obj.feeQuoter),
+      rmnRemote: new PublicKey(obj.rmnRemote),
+      linkTokenMint: new PublicKey(obj.linkTokenMint),
+      feeAggregator: new PublicKey(obj.feeAggregator),
+    })
+  }
+}