@chainlink/ccip-sdk 0.90.2 → 0.91.0

package/src/solana/index.ts

@@ -1,23 +1,14 @@
-import util from 'util'
+import { Buffer } from 'buffer'
 
-import {
-  type Idl,
-  type IdlTypes,
-  AnchorProvider,
-  BorshAccountsCoder,
-  BorshCoder,
-  Program,
-  Wallet,
-  eventDiscriminator,
-} from '@coral-xyz/anchor'
+import { type Idl, type IdlTypes, BorshAccountsCoder, BorshCoder, Program } from '@coral-xyz/anchor'
 import { NATIVE_MINT } from '@solana/spl-token'
 import {
   type Commitment,
-  type ConfirmedSignatureInfo,
   type ConnectionConfig,
+  type Finality,
+  type SignaturesForAddressOptions,
   type VersionedTransactionResponse,
   Connection,
-  Keypair,
   PublicKey,
   SYSVAR_CLOCK_PUBKEY,
   SystemProgram,
@@ -31,21 +22,19 @@ import {
   dataSlice,
   encodeBase58,
   encodeBase64,
-  getBytes,
   hexlify,
   isHexString,
   toBigInt,
 } from 'ethers'
-import moize, { type Moized } from 'moize'
+import { type Memoized, memoize } from 'micro-memoize'
+import type { PickDeep, SetRequired } from 'type-fest'
 
 import {
-  type ChainTransaction,
   type LogFilter,
   type RateLimiterState,
   type TokenInfo,
   type TokenPoolRemote,
   Chain,
-  ChainFamily,
 } from '../chain.ts'
 import { type EVMExtraArgsV2, type ExtraArgs, EVMExtraArgsV2Tag } from '../extra-args.ts'
 import type { LeafHasher } from '../hasher/common.ts'
@@ -57,14 +46,18 @@ import {
   type CCIPExecution,
   type CCIPMessage,
   type CCIPRequest,
+  type ChainTransaction,
   type CommitReport,
   type ExecutionReceipt,
   type ExecutionReport,
   type Lane,
   type Log_,
+  type MergeArrayElements,
   type NetworkInfo,
   type OffchainTokenData,
+  type WithLogger,
   CCIPVersion,
+  ChainFamily,
   ExecutionState,
 } from '../types.ts'
 import {
@@ -76,9 +69,10 @@ import {
   networkInfo,
   parseTypeAndVersion,
   toLeArray,
+  util,
 } from '../utils.ts'
 import { cleanUpBuffers } from './cleanup.ts'
-import { executeReport } from './exec.ts'
+import { generateUnsignedExecuteReport } from './exec.ts'
 import { getV16SolanaLeafHasher } from './hasher.ts'
 import { IDL as BASE_TOKEN_POOL } from './idl/1.6.0/BASE_TOKEN_POOL.ts'
 import { IDL as BURN_MINT_TOKEN_POOL } from './idl/1.6.0/BURN_MINT_TOKEN_POOL.ts'
@@ -86,9 +80,22 @@ import { IDL as CCIP_CCTP_TOKEN_POOL } from './idl/1.6.0/CCIP_CCTP_TOKEN_POOL.ts
 import { IDL as CCIP_OFFRAMP_IDL } from './idl/1.6.0/CCIP_OFFRAMP.ts'
 import { IDL as CCIP_ROUTER_IDL } from './idl/1.6.0/CCIP_ROUTER.ts'
 import { fetchSolanaOffchainTokenData } from './offchain.ts'
-import { ccipSend, getFee } from './send.ts'
-import type { CCIPMessage_V1_6_Solana } from './types.ts'
-import { bytesToBuffer, getErrorFromLogs, parseSolanaLogs, simulationProvider } from './utils.ts'
+import { generateUnsignedCcipSend, getFee } from './send.ts'
+import { type CCIPMessage_V1_6_Solana, type UnsignedSolanaTx, isWallet } from './types.ts'
+import {
+  bytesToBuffer,
+  getErrorFromLogs,
+  hexDiscriminator,
+  parseSolanaLogs,
+  simulateAndSendTxs,
+  simulationProvider,
+} from './utils.ts'
+import {
+  fetchAllMessagesInBatch,
+  fetchCCIPRequestById,
+  fetchCCIPRequestsInTx,
+} from '../requests.ts'
+import { patchBorsh } from './patchBorsh.ts'
 
 const routerCoder = new BorshCoder(CCIP_ROUTER_IDL)
 const offrampCoder = new BorshCoder(CCIP_OFFRAMP_IDL)
@@ -117,95 +124,101 @@ const unknownTokens: { [mint: string]: string } = {
   '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU': 'USDC', // devnet
 }
 
-// some circular specialized types, but all good with proper references
-type SolanaLog = Log_ & { tx: SolanaTransaction }
-type SolanaTransaction = ChainTransaction & {
-  tx: VersionedTransactionResponse
-  logs: SolanaLog[]
-}
-
-function hexDiscriminator(eventName: string): string {
-  return hexlify(eventDiscriminator(eventName))
-}
+/** Solana-specific log structure with transaction reference and log level. */
+export type SolanaLog = Log_ & { tx: SolanaTransaction; data: string; level: number }
+/** Solana-specific transaction structure with versioned transaction response. */
+export type SolanaTransaction = MergeArrayElements<
+  ChainTransaction,
+  {
+    tx: VersionedTransactionResponse
+    logs: readonly SolanaLog[]
+  }
+>
 
+/**
+ * Solana chain implementation supporting Solana networks.
+ */
 export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
+  static {
+    patchBorsh()
+    supportedChains[ChainFamily.Solana] = SolanaChain
+  }
   static readonly family = ChainFamily.Solana
   static readonly decimals = 9
 
-  readonly network: NetworkInfo<typeof ChainFamily.Solana>
-  readonly connection: Connection
-  readonly commitment: Commitment = 'confirmed'
-
-  _getSignaturesForAddress: (
-    programId: string,
-    before?: string,
-  ) => Promise<ConfirmedSignatureInfo[]>
+  connection: Connection
+  commitment: Commitment = 'confirmed'
 
-  constructor(connection: Connection, network: NetworkInfo) {
-    super()
+  /**
+   * Creates a new SolanaChain instance.
+   * @param connection - Solana connection instance.
+   * @param network - Network information for this chain.
+   */
+  constructor(connection: Connection, network: NetworkInfo, ctx?: WithLogger) {
+    super(network, ctx)
 
-    if (network.family !== ChainFamily.Solana) {
-      throw new Error(`Invalid network family for SolanaChain: ${network.family}`)
-    }
-    this.network = network
     this.connection = connection
 
     // Memoize expensive operations
-    this.typeAndVersion = moize.default(this.typeAndVersion.bind(this), {
+    this.typeAndVersion = memoize(this.typeAndVersion.bind(this), {
       maxArgs: 1,
-      isPromise: true,
+      async: true,
     })
-    this.getBlockTimestamp = moize.default(this.getBlockTimestamp.bind(this), {
-      isPromise: true,
+    this.getBlockTimestamp = memoize(this.getBlockTimestamp.bind(this), {
+      async: true,
       maxSize: 100,
-      updateCacheForKey: (key) => typeof key[key.length - 1] !== 'number',
+      forceUpdate: (key) => typeof key[key.length - 1] !== 'number',
     })
-    this.getTransaction = moize.default(this.getTransaction.bind(this), {
+    this.getTransaction = memoize(this.getTransaction.bind(this), {
       maxSize: 100,
       maxArgs: 1,
     })
-    this.getWallet = moize.default(this.getWallet.bind(this), { maxSize: 1, maxArgs: 0 })
-    this.getTokenForTokenPool = moize.default(this.getTokenForTokenPool.bind(this))
-    this.getTokenInfo = moize.default(this.getTokenInfo.bind(this))
-    this._getSignaturesForAddress = moize.default(
-      (programId: string, before?: string) =>
-        this.connection.getSignaturesForAddress(
-          new PublicKey(programId),
-          { limit: 1000, before },
-          'confirmed',
-        ),
+    this.getTokenForTokenPool = memoize(this.getTokenForTokenPool.bind(this))
+    this.getTokenInfo = memoize(this.getTokenInfo.bind(this))
+    this.connection.getSignaturesForAddress = memoize(
+      this.connection.getSignaturesForAddress.bind(this.connection),
       {
         maxSize: 100,
-        maxAge: 60000,
-        maxArgs: 2,
-        isPromise: true,
-        updateExpire: true,
-        // only expire undefined before (i.e. recent getSignaturesForAddress calls)
-        onExpire: ([, before]) => !before,
+        async: true,
+        // if options.before is defined, caches for long, otherwise for short (recent signatures)
+        expires: (key) => (key[1] ? 2 ** 31 - 1 : 5e3),
+        transformKey: ([address, options, commitment]: [
+          address: PublicKey,
+          options?: SignaturesForAddressOptions,
+          commitment?: Finality,
+        ]) =>
+          [
+            address.toBase58(),
+            options?.before,
+            options?.until,
+            options?.limit,
+            commitment,
+          ] as const,
       },
     )
     // cache account info for 30 seconds
-    this.connection.getAccountInfo = moize.default(
-      this.connection.getAccountInfo.bind(this.connection),
-      {
-        maxSize: 100,
-        maxArgs: 2,
-        maxAge: 30e3,
-        transformArgs: ([address, commitment]) =>
-          [(address as PublicKey).toString(), commitment] as const,
-      },
-    )
-
-    this._getRouterConfig = moize.default(this._getRouterConfig.bind(this), {
-      maxArgs: 1,
+    this.connection.getAccountInfo = memoize(this.connection.getAccountInfo.bind(this.connection), {
+      maxSize: 100,
+      maxArgs: 2,
+      expires: 30e3,
+      transformKey: ([address, commitment]) =>
+        [(address as PublicKey).toString(), commitment] as const,
     })
 
-    this.listFeeTokens = moize.default(this.listFeeTokens.bind(this), {
-      maxArgs: 1,
-    })
+    this._getRouterConfig = memoize(this._getRouterConfig.bind(this), { maxArgs: 1 })
+
+    this.getFeeTokens = memoize(this.getFeeTokens.bind(this), { maxArgs: 1 })
+    this.getOffRampsForRouter = memoize(this.getOffRampsForRouter.bind(this), { maxArgs: 1 })
   }
 
-  static _getConnection(url: string): Connection {
+  /**
+   * Creates a Solana connection from a URL.
+   * @param url - RPC endpoint URL (https://, http://, wss://, or ws://).
+   * @param ctx - context containing logger.
+   * @returns Solana Connection instance.
+   */
+  static _getConnection(url: string, ctx?: WithLogger): Connection {
+    const { logger = console } = ctx ?? {}
     if (!url.startsWith('http') && !url.startsWith('ws')) {
       throw new Error(
         `Invalid Solana RPC URL format (should be https://, http://, wss://, or ws://): ${url}`,
@@ -214,62 +227,37 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
 
     const config: ConnectionConfig = { commitment: 'confirmed' }
     if (url.includes('.solana.com')) {
-      config.fetch = createRateLimitedFetch({
-        maxRequests: 10,
-        maxRetries: 3,
-        windowMs: 11e3,
-      }) // public nodes
-      console.warn('Using rate-limited fetch for public solana nodes, commands may be slow')
+      config.fetch = createRateLimitedFetch(undefined, ctx) // public nodes
+      logger.warn('Using rate-limited fetch for public solana nodes, commands may be slow')
     }
 
     return new Connection(url, config)
   }
 
-  static async fromConnection(connection: Connection): Promise<SolanaChain> {
+  /**
+   * Creates a SolanaChain instance from an existing connection.
+   * @param connection - Solana Connection instance.
+   * @param ctx - context containing logger.
+   * @returns A new SolanaChain instance.
+   */
+  static async fromConnection(connection: Connection, ctx?: WithLogger): Promise<SolanaChain> {
     // Get genesis hash to use as chainId
-    return new SolanaChain(connection, networkInfo(await connection.getGenesisHash()))
-  }
-
-  static async fromUrl(url: string): Promise<SolanaChain> {
-    const connection = this._getConnection(url)
-    return this.fromConnection(connection)
-  }
-
-  async destroy(): Promise<void> {
-    // Solana Connection doesn't have an explicit destroy method
-    // The memoized functions will be garbage collected when the instance is destroyed
-  }
-
-  static getWallet(_opts?: { wallet?: unknown }): Promise<Wallet> {
-    throw new Error('Wallet not implemented')
+    return new SolanaChain(connection, networkInfo(await connection.getGenesisHash()), ctx)
   }
 
   /**
-   * Load wallet
-   * @param opts - options to load wallet
-   * @param opts.wallet - private key as 0x or base58 string, or async getter function resolving to
-   *   Wallet instance
-   * @returns Wallet, after caching in instance
+   * Creates a SolanaChain instance from an RPC URL.
+   * @param url - RPC endpoint URL.
+   * @param ctx - context containing logger.
+   * @returns A new SolanaChain instance.
    */
-  async getWallet(opts: { wallet?: unknown } = {}): Promise<Wallet> {
-    try {
-      if (typeof opts.wallet === 'string')
-        return new Wallet(
-          Keypair.fromSecretKey(
-            opts.wallet.startsWith('0x') ? getBytes(opts.wallet) : bs58.decode(opts.wallet),
-          ),
-        )
-    } catch (_) {
-      // pass
-    }
-    return (this.constructor as typeof SolanaChain).getWallet(opts)
-  }
-
-  async getWalletAddress(opts?: { wallet?: unknown }): Promise<string> {
-    return (await this.getWallet(opts)).publicKey.toBase58()
+  static async fromUrl(url: string, ctx?: WithLogger): Promise<SolanaChain> {
+    const connection = this._getConnection(url, ctx)
+    return this.fromConnection(connection, ctx)
   }
 
   // cached
+  /** {@inheritDoc Chain.getBlockTimestamp} */
   async getBlockTimestamp(block: number | 'finalized'): Promise<number> {
     if (block === 'finalized') {
       const slot = await this.connection.getSlot('finalized')
@@ -287,7 +275,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return blockTime
   }
 
-  // cached
+  /** {@inheritDoc Chain.getTransaction} */
   async getTransaction(hash: string): Promise<SolanaTransaction> {
     const tx = await this.connection.getTransaction(hash, {
       commitment: 'confirmed',
@@ -295,16 +283,15 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     })
     if (!tx) throw new Error(`Transaction not found: ${hash}`)
     if (tx.blockTime) {
-      ;(this.getBlockTimestamp as Moized<typeof this.getBlockTimestamp>).set(
-        [tx.slot],
-        Promise.resolve(tx.blockTime),
-      )
+      ;(
+        this.getBlockTimestamp as Memoized<typeof this.getBlockTimestamp, { async: true }>
+      ).cache.set([tx.slot], Promise.resolve(tx.blockTime))
     } else {
       tx.blockTime = await this.getBlockTimestamp(tx.slot)
     }
 
     // Parse logs from transaction using helper function
-    const logs_: Log_[] = tx.meta?.logMessages?.length
+    const logs_ = tx.meta?.logMessages?.length
       ? parseSolanaLogs(tx.meta?.logMessages).map((l) => ({
           ...l,
           transactionHash: hash,
@@ -313,7 +300,6 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
       : []
 
     const chainTx: SolanaTransaction = {
-      chain: this,
       hash,
       logs: [] as SolanaLog[],
       blockNumber: tx.slot,
@@ -327,59 +313,70 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return chainTx
   }
 
-  // implements inner paging logic for this.getLogs
-  async *_getTransactionsForAddress(
+  /**
+   * Internal method to get transactions for an address with pagination.
+   * @param opts - Log filter options.
+   * @returns Async generator of Solana transactions.
+   */
+  async *getTransactionsForAddress(
     opts: Omit<LogFilter, 'topics'>,
   ): AsyncGenerator<SolanaTransaction> {
     if (!opts.address) throw new Error('Program address is required for Solana log filtering')
 
     let allSignatures
+    const limit = Math.min(opts?.page || 1000, 1000)
     if (opts.startBlock || opts.startTime) {
       // forward collect all matching sigs in array
-      const allSigs: { signature: string; slot: number; blockTime?: number | null }[] = []
-      let batch: Awaited<ReturnType<typeof this.connection.getSignaturesForAddress>> | undefined,
-        popped = false
-      while (!popped && (batch?.length ?? true)) {
-        batch = await this._getSignaturesForAddress(
-          opts.address,
-          allSigs[allSigs.length - 1]?.signature,
+      allSignatures = [] as Awaited<ReturnType<typeof this.connection.getSignaturesForAddress>>
+      let batch: typeof allSignatures
+      do {
+        batch = await this.connection.getSignaturesForAddress(
+          new PublicKey(opts.address),
+          { limit, before: allSignatures[allSignatures.length - 1]?.signature },
+          'confirmed',
         )
+
         while (
           batch.length > 0 &&
           (batch[batch.length - 1].slot < (opts.startBlock || 0) ||
             (batch[batch.length - 1].blockTime || -1) < (opts.startTime || 0))
         ) {
-          batch.pop() // pop tail of txs which are older than requested start
-          popped = true
+          batch.length-- // truncate tail of txs which are older than requested start
         }
-        allSigs.push(...batch)
-      }
-      allSigs.reverse()
+
+        allSignatures.push(...batch) // concat in descending order
+      } while (batch.length >= limit)
+
+      allSignatures.reverse()
+
       while (
         opts.endBlock &&
-        allSigs.length > 0 &&
-        allSigs[allSigs.length - 1].slot > opts.endBlock
+        allSignatures.length > 0 &&
+        allSignatures[allSignatures.length - 1].slot > opts.endBlock
       ) {
-        allSigs.pop() // pop head (after reverse) of txs which are newer than requested end
+        allSignatures.length-- // truncate head (after reverse) of txs newer than requested end
       }
-      allSignatures = allSigs
     } else {
       allSignatures = async function* (this: SolanaChain) {
-        let batch: { signature: string; slot: number; blockTime?: number | null }[] | undefined
-        while (batch?.length ?? true) {
-          batch = await this._getSignaturesForAddress(
-            opts.address!,
-            batch?.length
-              ? batch[batch.length - 1].signature
-              : opts.endBefore
-                ? opts.endBefore
-                : undefined,
+        let batch: Awaited<ReturnType<typeof this.connection.getSignaturesForAddress>> | undefined
+        do {
+          batch = await this.connection.getSignaturesForAddress(
+            new PublicKey(opts.address!),
+            {
+              limit,
+              before: batch?.length
+                ? batch[batch.length - 1].signature
+                : opts.endBefore
+                  ? opts.endBefore
+                  : undefined,
+            },
+            'confirmed',
           )
           for (const sig of batch) {
             if (opts.endBlock && sig.slot > opts.endBlock) continue
             yield sig
           }
-        }
+        } while (batch.length >= limit)
       }.call(this) // generate backwards until depleting getSignaturesForAddress
     }
 
@@ -403,17 +400,16 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    *   * Fetches signatures in reverse chronological order (newest first)
    *   * Returns logs in reverse chronological order (newest first)
    *
-   * @param opts - Log filter options
-   * @param opts.startBlock - Starting slot number (inclusive)
-   * @param opts.startTime - Starting Unix timestamp (inclusive)
-   * @param opts.endBlock - Ending slot number (inclusive)
-   * @param opts.address - Program address to filter logs by (required for Solana)
-   * @param opts.topics - Array of topics to filter logs by (optional);
-   *   either 0x-8B discriminants or event names
-   * @param.opts.programs - a special option to allow querying by address of interest, but
-   *   yielding matching logs from specific (string address) program or any (true)
-   * @param opts.commit - Special param for fetching ExecutionReceipts, to narrow down the search
-   * @returns AsyncIterableIterator of parsed Log_ objects
+   * @param opts - Log filter options containing:
+   *   - `startBlock`: Starting slot number (inclusive)
+   *   - `startTime`: Starting Unix timestamp (inclusive)
+   *   - `endBlock`: Ending slot number (inclusive)
+   *   - `address`: Program address to filter logs by (required for Solana)
+   *   - `topics`: Array of topics to filter logs by (optional); either 0x-8B discriminants or event names
+   *   - `programs`: Special option to allow querying by address of interest, but yielding matching
+   *     logs from specific (string address) program or any (true)
+   *   - `commit`: Special param for fetching ExecutionReceipts, to narrow down the search
+   * @returns AsyncIterableIterator of parsed Log_ objects.
    */
   async *getLogs(
     opts: LogFilter & { sender?: string; programs?: string[] | true; commit?: CommitReport },
@@ -440,7 +436,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
 
     // Process signatures and yield logs
-    for await (const tx of this._getTransactionsForAddress(opts)) {
+    for await (const tx of this.getTransactionsForAddress(opts)) {
       for (const log of tx.logs) {
         // Filter and yield logs from the specified program, and which match event discriminant or log prefix
         if (
@@ -452,16 +448,57 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
             ))
         )
           continue
-        yield Object.assign(log, { timestamp: new Date(tx.timestamp * 1000) })
+        yield log
       }
     }
   }
 
+  /** {@inheritDoc Chain.fetchRequestsInTx} */
+  async fetchRequestsInTx(tx: string | ChainTransaction): Promise<CCIPRequest[]> {
+    return fetchCCIPRequestsInTx(this, typeof tx === 'string' ? await this.getTransaction(tx) : tx)
+  }
+
+  /** {@inheritDoc Chain.fetchRequestById} */
+  override fetchRequestById(
+    messageId: string,
+    onRamp?: string,
+    opts?: { page?: number },
+  ): Promise<CCIPRequest> {
+    if (!onRamp) throw new Error('onRamp is required')
+    return fetchCCIPRequestById(this, messageId, { address: onRamp, ...opts })
+  }
+
+  /** {@inheritDoc Chain.fetchAllMessagesInBatch} */
+  async fetchAllMessagesInBatch<
+    R extends PickDeep<
+      CCIPRequest,
+      'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.header.sequenceNumber'
+    >,
+  >(
+    request: R,
+    commit: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>,
+    opts?: { page?: number },
+  ): Promise<R['message'][]> {
+    const [destChainStatePda] = PublicKey.findProgramAddressSync(
+      [Buffer.from('dest_chain_state'), toLeArray(request.lane.destChainSelector, 8)],
+      new PublicKey(request.log.address),
+    )
+    // fetchAllMessagesInBatch pass opts back to getLogs; use it to narrow getLogs filter only to
+    // txs touching destChainStatePda
+    const opts_: Parameters<SolanaChain['getLogs']>[0] = {
+      ...opts,
+      programs: [request.log.address],
+      address: destChainStatePda.toBase58(),
+    }
+    return fetchAllMessagesInBatch(this, request, commit, opts_)
+  }
+
+  /** {@inheritDoc Chain.typeAndVersion} */
   async typeAndVersion(address: string) {
     const program = new Program(
       CCIP_OFFRAMP_IDL, // `typeVersion` schema should be the same
       new PublicKey(address),
-      simulationProvider(this.connection),
+      simulationProvider(this),
     )
 
     // Create the typeVersion instruction
@@ -474,10 +511,12 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return res
   }
 
+  /** {@inheritDoc Chain.getRouterForOnRamp} */
   getRouterForOnRamp(onRamp: string, _destChainSelector: bigint): Promise<string> {
     return Promise.resolve(onRamp) // Solana's router is also the onRamp
   }
 
+  /** {@inheritDoc Chain.getRouterForOffRamp} */
   async getRouterForOffRamp(offRamp: string, _sourceChainSelector: bigint): Promise<string> {
     const offRamp_ = new PublicKey(offRamp)
     const program = new Program(CCIP_OFFRAMP_IDL as Idl, offRamp_, {
@@ -500,10 +539,12 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return router.toBase58()
   }
 
+  /** {@inheritDoc Chain.getNativeTokenForRouter} */
   getNativeTokenForRouter(_router: string): Promise<string> {
     return Promise.resolve(NATIVE_MINT.toBase58())
   }
 
+  /** {@inheritDoc Chain.getOffRampsForRouter} */
   async getOffRampsForRouter(router: string, sourceChainSelector: bigint): Promise<string[]> {
     // feeQuoter is present in router's config, and has a DestChainState account which is updated by
     // the offramps, so we can use it to narrow the search for the offramp
@@ -524,10 +565,12 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     throw new Error(`Could not find OffRamp events in feeQuoter=${feeQuoter.toString()} txs`)
   }
 
+  /** {@inheritDoc Chain.getOnRampForRouter} */
   getOnRampForRouter(router: string, _destChainSelector: bigint): Promise<string> {
     return Promise.resolve(router) // solana's Router is also the OnRamp
   }
 
+  /** {@inheritDoc Chain.getOnRampForOffRamp} */
   async getOnRampForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
     const program = new Program(CCIP_OFFRAMP_IDL, new PublicKey(offRamp), {
       connection: this.connection,
@@ -548,10 +591,12 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     )
   }
 
+  /** {@inheritDoc Chain.getCommitStoreForOffRamp} */
   getCommitStoreForOffRamp(offRamp: string): Promise<string> {
     return Promise.resolve(offRamp) // Solana supports only CCIP>=1.6, for which OffRamp and CommitStore are the same
   }
 
+  /** {@inheritDoc Chain.getTokenForTokenPool} */
   async getTokenForTokenPool(tokenPool: string): Promise<string> {
     const tokenPoolInfo = await this.connection.getAccountInfo(new PublicKey(tokenPool))
     if (!tokenPoolInfo) throw new Error(`TokenPool info not found: ${tokenPool}`)
@@ -562,6 +607,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return config.mint.toString()
   }
 
+  /** {@inheritDoc Chain.getTokenInfo} */
   async getTokenInfo(token: string): Promise<TokenInfo> {
     const mint = new PublicKey(token)
     const mintInfo = await this.connection.getParsedAccountInfo(mint)
@@ -597,7 +643,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
           }
         } catch (error) {
           // Metaplex metadata fetch failed, keep the default values
-          console.debug(`Failed to fetch Metaplex metadata for token ${token}:`, error)
+          this.logger.debug(`Failed to fetch Metaplex metadata for token ${token}:`, error)
         }
       }
 
@@ -611,6 +657,11 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
   }
 
+  /**
+   * Fetches token metadata from Metaplex.
+   * @param mintPublicKey - Token mint public key.
+   * @returns Token name and symbol, or null if not found.
+   */
   async _fetchTokenMetadata(
     mintPublicKey: PublicKey,
   ): Promise<{ name: string; symbol: string } | null> {
@@ -668,40 +719,32 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
 
       return name || symbol ? { name, symbol } : null
     } catch (error) {
-      console.debug('Error fetching token metadata:', error)
+      this.logger.debug('Error fetching token metadata:', error)
       return null
     }
   }
 
+  /**
+   * Decodes a CCIP message from a Solana log event.
+   * @param log - Log with data field.
+   * @returns Decoded CCIPMessage or undefined if not valid.
+   */
   static decodeMessage({ data }: { data: unknown }): CCIPMessage | undefined {
     if (!data || typeof data !== 'string') return undefined
-    let eventDataBuffer
+
+    // Verify the discriminant matches CCIPMessageSent
     try {
-      eventDataBuffer = bytesToBuffer(data)
+      if (dataSlice(getDataBytes(data), 0, 8) !== hexDiscriminator('CCIPMessageSent')) return
     } catch (_) {
       return
     }
 
-    const disc = dataSlice(eventDataBuffer, 0, 8)
-    if (disc !== hexDiscriminator('CCIPMessageSent')) return
-
-    // Use module-level BorshCoder for decoding structs
-
-    // Manually parse event header (discriminator + event-level fields)
-    let offset = 8
-
-    // Parse event-level fields
-    const _destChainSelector = eventDataBuffer.readBigUInt64LE(offset)
-    offset += 8
-
-    const _sequenceNumber = eventDataBuffer.readBigUInt64LE(offset)
-    offset += 8
-
-    // Now decode the SVM2AnyRampMessage struct using BorshCoder
-    const messageBytes = eventDataBuffer.subarray(offset)
-
-    const message: IdlTypes<typeof CCIP_ROUTER_IDL>['SVM2AnyRampMessage'] =
-      routerCoder.types.decode('SVM2AnyRampMessage', messageBytes)
+    const decoded = routerCoder.events.decode<
+      (typeof CCIP_ROUTER_IDL)['events'][number] & { name: 'CCIPMessageSent' },
+      IdlTypes<typeof CCIP_ROUTER_IDL>
+    >(data)
+    if (decoded?.name !== 'CCIPMessageSent') return
+    const message = decoded.data.message
 
     // Convert BN/number types to bigints
     const sourceChainSelector = BigInt(message.header.sourceChainSelector.toString())
@@ -760,6 +803,11 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     } as CCIPMessage<typeof CCIPVersion.V1_6>
   }
 
+  /**
+   * Decodes extra arguments from Solana CCIP messages.
+   * @param extraArgs - Encoded extra arguments bytes.
+   * @returns Decoded EVMExtraArgsV2 or undefined if unknown format.
+   */
   static decodeExtraArgs(
     extraArgs: BytesLike,
   ): (EVMExtraArgsV2 & { _tag: 'EVMExtraArgsV2' }) | undefined {
@@ -782,6 +830,11 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
   }
 
+  /**
+   * Encodes extra arguments for Solana CCIP messages.
+   * @param args - Extra arguments to encode.
+   * @returns Encoded extra arguments as hex string.
+   */
   static encodeExtraArgs(args: ExtraArgs): string {
     if ('computeUnits' in args) throw new Error('Solana can only encode EVMExtraArgsV2')
     const gasLimitUint128Le = toLeArray(args.gasLimit, 16)
@@ -792,6 +845,12 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     ])
   }
 
+  /**
+   * Decodes commit reports from a Solana log event.
+   * @param log - Log with data field.
+   * @param lane - Lane info for filtering.
+   * @returns Array of CommitReport or undefined if not valid.
+   */
   static decodeCommits(
     log: Pick<Log_, 'data'>,
     lane?: Omit<Lane, 'destChainSelector'>,
@@ -801,45 +860,27 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
       throw new Error('Log data is missing or not a string')
     }
 
-    const eventDataBuffer = bytesToBuffer(log.data)
-
-    // Verify the discriminant matches CommitReportAccepted
-    const expectedDiscriminant = hexDiscriminator('CommitReportAccepted')
-    const actualDiscriminant = hexlify(eventDataBuffer.subarray(0, 8))
-    if (actualDiscriminant !== expectedDiscriminant) return
-
-    // Skip the 8-byte discriminant and decode the event data manually
-    let offset = 8
-
-    // Decode Option<MerkleRoot> - first byte indicates Some(1) or None(0)
-    const hasValue = eventDataBuffer.readUInt8(offset)
-    offset += 1
-    if (!hasValue) return []
-
-    // Decode MerkleRoot struct using the types decoder
-    // We need to read the remaining bytes as a MerkleRoot struct
-    const merkleRootBytes = eventDataBuffer.subarray(offset)
-
-    type MerkleRootData = {
-      sourceChainSelector: BN
-      onRampAddress: Buffer
-      minSeqNr: BN
-      maxSeqNr: BN
-      merkleRoot: number[]
+    try {
+      // Verify the discriminant matches CommitReportAccepted
+      if (dataSlice(getDataBytes(log.data), 0, 8) !== hexDiscriminator('CommitReportAccepted'))
+        return
+    } catch (_) {
+      return
     }
 
-    const merkleRootData: MerkleRootData = offrampCoder.types.decode('MerkleRoot', merkleRootBytes)
-
-    if (!merkleRootData) {
-      throw new Error('Failed to decode MerkleRoot data')
-    }
+    const decoded = offrampCoder.events.decode<
+      (typeof CCIP_OFFRAMP_IDL)['events'][number] & { name: 'CommitReportAccepted' },
+      IdlTypes<typeof CCIP_OFFRAMP_IDL>
+    >(log.data)
+    if (decoded?.name !== 'CommitReportAccepted' || !decoded.data?.merkleRoot) return
+    const merkleRoot = decoded.data.merkleRoot
 
     // Verify the source chain selector matches our lane
-    const sourceChainSelector = BigInt(merkleRootData.sourceChainSelector.toString())
+    const sourceChainSelector = BigInt(merkleRoot.sourceChainSelector.toString())
 
     // Convert the onRampAddress from bytes to the proper format
     const onRampAddress = decodeOnRampAddress(
-      merkleRootData.onRampAddress,
+      merkleRoot.onRampAddress,
       networkInfo(sourceChainSelector).family,
     )
     if (lane) {
@@ -852,49 +893,50 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
       {
         sourceChainSelector,
         onRampAddress,
-        minSeqNr: BigInt(merkleRootData.minSeqNr.toString()),
-        maxSeqNr: BigInt(merkleRootData.maxSeqNr.toString()),
-        merkleRoot: hexlify(new Uint8Array(merkleRootData.merkleRoot)),
+        minSeqNr: BigInt(merkleRoot.minSeqNr.toString()),
+        maxSeqNr: BigInt(merkleRoot.maxSeqNr.toString()),
+        merkleRoot: hexlify(getDataBytes(merkleRoot.merkleRoot)),
       },
     ]
   }
 
+  /**
+   * Decodes an execution receipt from a Solana log event.
+   * @param log - Log with data, tx, and index fields.
+   * @returns ExecutionReceipt or undefined if not valid.
+   */
   static decodeReceipt(log: Pick<Log_, 'data' | 'tx' | 'index'>): ExecutionReceipt | undefined {
     // Check if this is a ExecutionStateChanged event by looking at the discriminant
     if (!log.data || typeof log.data !== 'string') {
       throw new Error('Log data is missing or not a string')
     }
 
-    // Verify the discriminant matches ExecutionStateChanged
-    if (dataSlice(getDataBytes(log.data), 0, 8) !== hexDiscriminator('ExecutionStateChanged'))
+    try {
+      // Verify the discriminant matches ExecutionStateChanged
+      if (dataSlice(getDataBytes(log.data), 0, 8) !== hexDiscriminator('ExecutionStateChanged'))
+        return
+    } catch (_) {
       return
-    const eventDataBuffer = bytesToBuffer(log.data)
-
-    // Note: We manually decode the event fields rather than using BorshCoder
-    // since ExecutionStateChanged is an event, not a defined type
-
-    // Skip the 8-byte discriminant and manually decode the event fields
-    let offset = 8
-
-    // Decode sourceChainSelector (u64)
-    const sourceChainSelector = eventDataBuffer.readBigUInt64LE(offset)
-    offset += 8
-
-    // Decode sequenceNumber (u64)
-    const sequenceNumber = eventDataBuffer.readBigUInt64LE(offset)
-    offset += 8
-
-    // Decode messageId ([u8; 32])
-    const messageId = hexlify(eventDataBuffer.subarray(offset, offset + 32))
-    offset += 32
+    }
 
-    // Decode messageHash ([u8; 32])
-    const messageHash = hexlify(eventDataBuffer.subarray(offset, offset + 32))
-    offset += 32
+    const decoded = offrampCoder.events.decode<
+      (typeof CCIP_OFFRAMP_IDL)['events'][number] & { name: 'ExecutionStateChanged' },
+      IdlTypes<typeof CCIP_OFFRAMP_IDL>
+    >(log.data)
+    if (decoded?.name !== 'ExecutionStateChanged') return
+    const messageId = hexlify(getDataBytes(decoded.data.messageId))
 
     // Decode state enum (MessageExecutionState)
     // Enum discriminant is a single byte: Untouched=0, InProgress=1, Success=2, Failure=3
-    let state = eventDataBuffer.readUInt8(offset) as ExecutionState
+    let state: ExecutionState
+    if (decoded.data.state.inProgress) {
+      state = ExecutionState.InProgress
+    } else if (decoded.data.state.success) {
+      state = ExecutionState.Success
+    } else if (decoded.data.state.failure) {
+      state = ExecutionState.Failed
+    } else throw new Error(`Invalid ExecutionState: ${util.inspect(decoded.data.state)}`)
+
     let returnData
     if (log.tx) {
       // use only last receipt per tx+message (i.e. skip intermediary InProgress=1 states for Solana)
@@ -915,15 +957,20 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
 
     return {
-      sourceChainSelector,
-      sequenceNumber,
+      sourceChainSelector: BigInt(decoded.data.sourceChainSelector.toString()),
+      sequenceNumber: BigInt(decoded.data.sequenceNumber.toString()),
       messageId,
-      messageHash,
+      messageHash: hexlify(getDataBytes(decoded.data.messageHash)),
       state,
       returnData,
     }
   }
 
+  /**
+   * Converts bytes to a Solana address (Base58).
+   * @param bytes - Bytes to convert.
+   * @returns Base58-encoded Solana address.
+   */
   static getAddress(bytes: BytesLike): string {
     try {
       if (typeof bytes === 'string' && bs58.decode(bytes).length === 32) return bytes
@@ -933,10 +980,16 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return encodeBase58(getDataBytes(bytes))
   }
 
-  static getDestLeafHasher(lane: Lane): LeafHasher<typeof CCIPVersion.V1_6> {
-    return getV16SolanaLeafHasher(lane)
+  /**
+   * Gets the leaf hasher for Solana destination chains.
+   * @param lane - Lane configuration.
+   * @returns Leaf hasher function.
+   */
+  static getDestLeafHasher(lane: Lane, ctx?: WithLogger): LeafHasher<typeof CCIPVersion.V1_6> {
+    return getV16SolanaLeafHasher(lane, ctx)
   }
 
+  /** {@inheritDoc Chain.getTokenAdminRegistryFor} */
   async getTokenAdminRegistryFor(address: string): Promise<string> {
     const [type] = await this.typeAndVersion(address)
     if (!type.includes('Router')) throw new Error(`Not a Router: ${address} is ${type}`)
@@ -944,79 +997,161 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return address
   }
 
+  /** {@inheritDoc Chain.getFee} */
+  getFee(router: string, destChainSelector: bigint, message: AnyMessage): Promise<bigint> {
+    return getFee(this, router, destChainSelector, message)
+  }
+
   /**
-   * Get the fee required to send a CCIP message from the Solana router.
+   * Raw/unsigned version of [[sendMessage]]
+   *
+   * @param sender - sender/feePayer address
+   * @param router - router address
+   * @param destChainSelector - destination chain selector
+   * @param message - AnyMessage to send (with or without fee)
+   * @param approveMax - approve max amount of tokens if needed, instead of only what's needed
+   * @returns instructions - array of instructions; `ccipSend` is last, after any approval
+   *   lookupTables - array of lookup tables for `ccipSend` call
+   *   mainIndex - instructions.length - 1
    */
-  getFee(router: string, destChainSelector: bigint, message: AnyMessage): Promise<bigint> {
-    return getFee(this.connection, router, destChainSelector, message)
+  async generateUnsignedSendMessage(
+    sender: string,
+    router: string,
+    destChainSelector: bigint,
+    message: AnyMessage & { fee?: bigint },
+    opts?: { approveMax?: boolean },
+  ): Promise<UnsignedSolanaTx> {
+    if (!message.fee) message.fee = await this.getFee(router, destChainSelector, message)
+    return generateUnsignedCcipSend(
+      this,
+      new PublicKey(sender),
+      new PublicKey(router),
+      destChainSelector,
+      message as SetRequired<typeof message, 'fee'>,
+      opts,
+    )
   }
 
+  /** {@inheritDoc Chain.sendMessage} */
   async sendMessage(
-    router_: string,
+    router: string,
     destChainSelector: bigint,
-    message: AnyMessage & { fee: bigint },
-    opts?: { wallet?: unknown; approveMax?: boolean },
-  ): Promise<ChainTransaction> {
-    const wallet = await this.getWallet(opts)
-
-    const router = new Program(
-      CCIP_ROUTER_IDL,
-      new PublicKey(router_),
-      new AnchorProvider(this.connection, wallet, { commitment: this.commitment }),
+    message: AnyMessage & { fee?: bigint },
+    opts: { wallet: unknown; approveMax?: boolean },
+  ): Promise<CCIPRequest> {
+    const wallet = opts.wallet
+    if (!isWallet(wallet)) throw new Error(`Expected Wallet, got=${util.inspect(wallet)}`)
+    const unsigned = await this.generateUnsignedSendMessage(
+      wallet.publicKey.toBase58(),
+      router,
+      destChainSelector,
+      message,
+      opts,
     )
-    const { hash } = await ccipSend(router, destChainSelector, message, opts)
-    return this.getTransaction(hash)
+
+    const hash = await simulateAndSendTxs(this, wallet, unsigned)
+    return (await this.fetchRequestsInTx(await this.getTransaction(hash)))[0]
   }
 
+  /** {@inheritDoc Chain.fetchOffchainTokenData} */
   async fetchOffchainTokenData(request: CCIPRequest): Promise<OffchainTokenData[]> {
-    return fetchSolanaOffchainTokenData(this.connection, request)
+    return fetchSolanaOffchainTokenData(request, this)
   }
 
-  async executeReport(
+  /**
+   * Raw/unsigned version of [[executeReport]]
+   * @param payer - payer address of the execution transaction
+   * @param offRamp - OffRamp contract address
+   * @param execReport_ - ExecutionReport of a dest=Solana message
+   * @param opts - execute report options
+   *   - forceBuffer - Whether to force the use of a buffer account
+   *   - forceLookupTable - Whether to force creation of a lookup table for the call
+   * @returns instructions - array of instructions to execute the report
+   *   lookupTables - array of lookup tables for `manuallyExecute` call
+   *   mainIndex - index of the `manuallyExecute` instruction in the array; last unless
+   *   forceLookupTable is set, in which case last is ALT deactivation tx, and manuallyExecute is
+   *   second to last
+   */
+  async generateUnsignedExecuteReport(
+    payer: string,
     offRamp: string,
     execReport_: ExecutionReport,
-    opts?: {
-      wallet?: string
+    opts?: { forceBuffer?: boolean; forceLookupTable?: boolean },
+  ): Promise<UnsignedSolanaTx> {
+    if (!('computeUnits' in execReport_.message))
+      throw new Error("ExecutionReport's message not for Solana")
+    const execReport = execReport_ as ExecutionReport<CCIPMessage_V1_6_Solana>
+    const offRamp_ = new PublicKey(offRamp)
+    return generateUnsignedExecuteReport(this, new PublicKey(payer), offRamp_, execReport, opts)
+  }
+
+  /** {@inheritDoc Chain.executeReport} */
+  async executeReport(
+    offRamp: string,
+    execReport: ExecutionReport,
+    opts: {
+      wallet: unknown
       gasLimit?: number
       forceLookupTable?: boolean
       forceBuffer?: boolean
-      clearLeftoverAccounts?: boolean
-      dontWait?: boolean
+      waitDeactivation?: boolean
     },
   ): Promise<ChainTransaction> {
-    if (!('computeUnits' in execReport_.message))
-      throw new Error("ExecutionReport's message not for Solana")
-    const execReport = execReport_ as ExecutionReport<CCIPMessage_V1_6_Solana>
-
-    const wallet = await this.getWallet(opts)
-    const provider = new AnchorProvider(this.connection, wallet, { commitment: this.commitment })
-    const offrampProgram = new Program(CCIP_OFFRAMP_IDL, new PublicKey(offRamp), provider)
+    const wallet = opts.wallet
+    if (!isWallet(wallet)) throw new Error(`Expected Wallet, got=${util.inspect(wallet)}`)
 
-    const rep = await executeReport({ offrampProgram, execReport, ...opts })
-    if (opts?.clearLeftoverAccounts) {
+    let hash
+    do {
       try {
-        await this.cleanUpBuffers(opts)
+        const unsigned = await this.generateUnsignedExecuteReport(
+          wallet.publicKey.toBase58(),
+          offRamp,
+          execReport,
+          opts,
+        )
+        hash = await simulateAndSendTxs(this, wallet, unsigned, opts?.gasLimit)
       } catch (err) {
-        console.warn('Error while trying to clean up buffers:', err)
+        if (
+          !(err instanceof Error) ||
+          !['encoding overruns Uint8Array', 'too large'].some((e) => err.message.includes(e))
+        )
+          throw err
+        // in case of failure to serialize a report, first try buffering (because it gets
+        // auto-closed upon successful execution), then ALTs (need a grace period ~3min after
+        // deactivation before they can be closed/recycled)
+        if (!opts?.forceBuffer) opts = { ...opts, forceBuffer: true }
+        else if (!opts?.forceLookupTable) opts = { ...opts, forceLookupTable: true }
+        else throw err
       }
+    } while (!hash)
+
+    try {
+      await this.cleanUpBuffers(opts)
+    } catch (err) {
+      this.logger.warn('Error while trying to clean up buffers:', err)
     }
-    return this.getTransaction(rep.hash)
+    return this.getTransaction(hash)
   }
 
   /**
    * Clean up and recycle buffers and address lookup tables owned by wallet
-   * CAUTION: this will close ANY lookup table owned by this wallet
-   * @param wallet - wallet options
-   * @param dontWait - Whether to skip waiting for lookup table deactivation cool down period
-   *   (513 slots) to pass before closing; by default, we deactivate (if needed) and wait to close
-   *   before returning from this method
+   * @param opts - cleanUp options
+   *   - wallet - wallet instance to sign txs
+   *   - waitDeactivation - Whether to wait for lookup table deactivation cool down period
+   *       (513 slots) to pass before closing; by default, we deactivate (if needed) and move on, to
+   *       close other ready ALTs
    */
-  async cleanUpBuffers(opts?: { wallet?: string; dontWait?: boolean }): Promise<void> {
-    const wallet = await this.getWallet(opts)
-    const provider = new AnchorProvider(this.connection, wallet, { commitment: this.commitment })
-    await cleanUpBuffers(provider, this.getLogs.bind(this), opts)
+  async cleanUpBuffers(opts: { wallet: unknown; waitDeactivation?: boolean }): Promise<void> {
+    const wallet = opts.wallet
+    if (!isWallet(wallet)) throw new Error(`Expected Wallet, got=${util.inspect(wallet)}`)
+    await cleanUpBuffers(this, wallet, this.getLogs.bind(this), opts)
   }
 
+  /**
+   * Parses raw Solana data into typed structures.
+   * @param data - Raw data to parse.
+   * @returns Parsed data or undefined.
+   */
   static parse(data: unknown) {
     if (!data) return
     try {
@@ -1044,13 +1179,9 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
   /**
    * Solana optimization: we use getProgramAccounts with
    */
-  async fetchCommitReport(
+  override async fetchCommitReport(
     commitStore: string,
-    request: {
-      lane: Lane
-      message: { header: { sequenceNumber: bigint } }
-      timestamp?: number
-    },
+    request: PickDeep<CCIPRequest, 'lane' | 'message.header.sequenceNumber' | 'tx.timestamp'>,
     hints?: { startBlock?: number; page?: number },
   ): Promise<CCIPCommit> {
     const commitsAroundSeqNum = await this.connection.getProgramAccounts(
@@ -1069,8 +1200,8 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
               bytes: encodeBase58(toLeArray(request.lane.sourceChainSelector, 8)),
             },
           },
-          // dirty trick: memcmp report.min with msg.sequenceNumber's without least-significant byte;
-          // this should be ~256 around seqNum, i.e. big chance of a match
+          // hack: memcmp report.min with msg.sequenceNumber's without least-significant byte;
+          // this should be ~256 around seqNum, i.e. big chance of a match; requires PDAs to be alive
           {
             memcmp: {
               offset: 8 + 1 + 8 + 32 + 8 + 1,
@@ -1108,44 +1239,34 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return super.fetchCommitReport(commitStore, request, hints)
   }
 
-  // specialized override with stricter address-of-interest
-  async *fetchExecutionReceipts(
+  /** {@inheritDoc Chain.fetchExecutionReceipts} */
+  override async *fetchExecutionReceipts(
     offRamp: string,
-    messageIds: Set<string>,
-    hints?: { startBlock?: number; startTime?: number; page?: number; commit?: CommitReport },
-  ): AsyncGenerator<CCIPExecution> {
-    if (!hints?.commit) {
-      // if no commit, fall back to generic implementation
-      yield* super.fetchExecutionReceipts(offRamp, messageIds, hints)
-      return
-    }
-    // otherwise, use `commit_report` PDA as more specialized address
-    const [commitReportPda] = PublicKey.findProgramAddressSync(
-      [
-        Buffer.from('commit_report'),
-        toLeArray(hints.commit.sourceChainSelector, 8),
-        bytesToBuffer(hints.commit.merkleRoot),
-      ],
-      new PublicKey(offRamp),
-    )
-    // rest is similar to generic implemenetation
-    const onlyLast = !hints?.startBlock && !hints?.startTime // backwards
-    for await (const log of this.getLogs({
-      ...hints,
-      programs: [offRamp],
-      address: commitReportPda.toBase58(),
-      topics: ['ExecutionStateChanged'],
-    })) {
-      const receipt = (this.constructor as typeof SolanaChain).decodeReceipt(log)
-      if (!receipt || !messageIds.has(receipt.messageId)) continue
-      if (onlyLast || receipt.state === ExecutionState.Success) messageIds.delete(receipt.messageId)
-
-      const timestamp = await this.getBlockTimestamp(log.blockNumber)
-      yield { receipt, log, timestamp }
-      if (!messageIds.size) break
+    request: PickDeep<CCIPRequest, 'lane' | 'message.header.messageId' | 'tx.timestamp'>,
+    commit?: CCIPCommit,
+    opts?: { page?: number },
+  ): AsyncIterableIterator<CCIPExecution> {
+    let opts_: Parameters<SolanaChain['getLogs']>[0] | undefined = opts
+    if (commit) {
+      // if we know of commit, use `commit_report` PDA as more specialized address
+      const [commitReportPda] = PublicKey.findProgramAddressSync(
+        [
+          Buffer.from('commit_report'),
+          toLeArray(request.lane.sourceChainSelector, 8),
+          bytesToBuffer(commit.report.merkleRoot),
+        ],
+        new PublicKey(offRamp),
+      )
+      opts_ = {
+        ...opts,
+        programs: [offRamp],
+        address: commitReportPda.toBase58(),
+      }
     }
+    yield* super.fetchExecutionReceipts(offRamp, request, commit, opts_)
   }
 
+  /** {@inheritDoc Chain.getRegistryTokenConfig} */
   async getRegistryTokenConfig(
     registry: string,
     token: string,
@@ -1201,6 +1322,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return config
   }
 
+  /** {@inheritDoc Chain.getTokenPoolConfigs} */
   async getTokenPoolConfigs(tokenPool: string): Promise<{
     token: string
     router: string
@@ -1230,6 +1352,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
   }
 
+  /** {@inheritDoc Chain.getTokenPoolRemotes} */
   async getTokenPoolRemotes(
     tokenPool: string,
     remoteChainSelector?: bigint,
@@ -1379,13 +1502,14 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
           outboundRateLimiterState,
         }
       } catch (err) {
-        console.warn('Failed to decode ChainConfig account:', err)
+        this.logger.warn('Failed to decode ChainConfig account:', err)
       }
     }
 
     return remotes
   }
 
+  /** {@inheritDoc Chain.getSupportedTokens} */
   async getSupportedTokens(router: string): Promise<string[]> {
     // `mint` offset in TokenAdminRegistry account data; more robust against changes in layout
     const mintOffset = 8 + 1 + 32 + 32 + 32 + 16 * 2 // = 137
@@ -1413,7 +1537,8 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return res
   }
 
-  async listFeeTokens(router: string): Promise<Record<string, TokenInfo>> {
+  /** {@inheritDoc Chain.getFeeTokens} */
+  async getFeeTokens(router: string): Promise<Record<string, TokenInfo>> {
     const { feeQuoter } = await this._getRouterConfig(router)
     const tokenConfigs = await this.connection.getProgramAccounts(feeQuoter, {
       filters: [
@@ -1430,14 +1555,18 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return Object.fromEntries(
       await Promise.all(
         tokenConfigs.map(async (acc) => {
-          const token = new PublicKey(acc.account.data.subarray(10, 10 + 32))
-          return [token.toBase58(), await this.getTokenInfo(token.toBase58())] as const
+          const token = new PublicKey(acc.account.data.subarray(10, 10 + 32)).toBase58()
+          return [token, await this.getTokenInfo(token)] as const
         }),
       ),
     )
   }
 
-  // cached
+  /**
+   * Gets the router configuration from the Config PDA.
+   * @param router - Router program address.
+   * @returns Router configuration including feeQuoter.
+   */
   async _getRouterConfig(router: string) {
     const program = new Program(CCIP_ROUTER_IDL, new PublicKey(router), {
       connection: this.connection,
@@ -1450,5 +1579,3 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return program.account.config.fetch(configPda)
   }
 }
-
-supportedChains[ChainFamily.Solana] = SolanaChain