minimize wallet interface in Chains, move to CLI

ccip-sdk doesn't have static or cached `getWallet` anymore; instead, it
receives a `opts.wallet` directly in the `sendMessage` and
`executeReport` methods;
users are then expected to provide compatible wallets, like done by the
CLI without overriding any method in the SDK.

Author: andrevmatos

ccip-cli/src/commands/manual-exec.ts

@@ -22,7 +22,7 @@ import {
   selectRequest,
   withDateTimestamp,
 } from './utils.ts'
-import { fetchChainsFromRpcs } from '../providers/index.ts'
+import { fetchChainsFromRpcs, loadChainWallet } from '../providers/index.ts'
 
 // const MAX_QUEUE = 1000
 // const MAX_EXECS_IN_BATCH = 1
@@ -92,7 +92,6 @@ export const builder = (yargs: Argv) =>
     })
 
 export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']> & GlobalOpts) {
-  if (!argv.wallet) argv.wallet = process.env['USER_KEY'] || process.env['OWNER_KEY']
   let destroy
   const destroy$ = new Promise((resolve) => {
     destroy = resolve
@@ -193,7 +192,8 @@ async function manualExec(
     }
   }
 
-  const manualExecTx = await dest.executeReport(offRamp, execReport, argv)
+  const [, wallet] = await loadChainWallet(dest, argv)
+  const manualExecTx = await dest.executeReport(offRamp, execReport, { ...argv, wallet })
 
   console.log('🚀 manualExec tx =', manualExecTx.hash, 'to offRamp =', offRamp)
 

ccip-cli/src/commands/send.ts

@@ -17,7 +17,7 @@ import type { Argv } from 'yargs'
 import type { GlobalOpts } from '../index.ts'
 import { Format } from './types.ts'
 import { logParsedError, parseTokenAmounts, prettyRequest, withDateTimestamp } from './utils.ts'
-import { fetchChainsFromRpcs } from '../providers/index.ts'
+import { fetchChainsFromRpcs, loadChainWallet } from '../providers/index.ts'
 
 export const command = 'send <source> <router> <dest>'
 export const describe = 'Send a CCIP message from router on source to dest'
@@ -188,10 +188,12 @@ async function sendMessage(
     throw new Error('--token-receiver and --account intended only for Solana dest')
   }
 
+  let walletAddress, wallet
   if (!receiver) {
     if (sourceNetwork.family !== destNetwork.family)
       throw new Error('--receiver is required when sending to a different chain family')
-    receiver = await source.getWalletAddress(argv) // send to self if same family
+    ;[walletAddress, wallet] = await loadChainWallet(source, argv)
+    receiver = walletAddress // send to self if same family
   }
 
   if (argv.estimateGasLimit != null || argv.onlyEstimate) {
@@ -213,10 +215,11 @@ async function sendMessage(
       tokenAmounts,
     )
 
+    if (!walletAddress) [walletAddress, wallet] = await loadChainWallet(source, argv)
     const estimated = await estimateExecGasForRequest(source, dest, {
       lane,
       message: {
-        sender: await source.getWalletAddress(argv),
+        sender: walletAddress,
         receiver,
         data,
         tokenAmounts: destTokenAmounts,
@@ -283,11 +286,12 @@ async function sendMessage(
   )
   if (argv.onlyGetFee) return
 
+  if (!walletAddress) [walletAddress, wallet] = await loadChainWallet(source, argv)
   const request = await source.sendMessage(
     argv.router,
     destNetwork.chainSelector,
     { ...message, fee },
-    argv,
+    { ...argv, wallet },
   )
   console.log(
     '🚀 Sending message to',

ccip-cli/src/providers/aptos.ts

@@ -12,7 +12,6 @@ import {
   Ed25519Signature,
   generateSigningMessageForTransaction,
 } from '@aptos-labs/ts-sdk'
-import { AptosChain } from '@chainlink/ccip-sdk/src/index.ts'
 import AptosLedger from '@ledgerhq/hw-app-aptos'
 import HIDTransport from '@ledgerhq/hw-transport-node-hid'
 import { type BytesLike, getBytes, hexlify } from 'ethers'
@@ -72,7 +71,12 @@ export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
   }
 }
 
-AptosChain.getWallet = async function loadAptosWallet({ wallet: walletOpt }: { wallet?: unknown }) {
+/**
+ * Loads an Aptos wallet from the provided options.
+ * @param opts.wallet - wallet options (as passed from yargs argv)
+ * @returns Promise to AptosAsyncAccount instance
+ */
+export async function loadAptosWallet({ wallet: walletOpt }: { wallet?: unknown }) {
   if (!walletOpt) walletOpt = process.env['USER_KEY'] || process.env['OWNER_KEY']
   if (typeof walletOpt !== 'string')
     throw new Error(`Invalid wallet option: ${util.inspect(walletOpt)}`)

ccip-cli/src/providers/evm.ts

@@ -2,11 +2,17 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import util from 'util'
 
-import { EVMChain } from '@chainlink/ccip-sdk/src/index.ts'
 import { LedgerSigner } from '@ethers-ext/signer-ledger'
 import { password } from '@inquirer/prompts'
 import HIDTransport from '@ledgerhq/hw-transport-node-hid'
-import { type Provider, type Signer, BaseWallet, SigningKey, Wallet } from 'ethers'
+import {
+  type JsonRpcApiProvider,
+  type Provider,
+  type Signer,
+  BaseWallet,
+  SigningKey,
+  Wallet,
+} from 'ethers'
 
 // monkey-patch @ethers-ext/signer-ledger to preserve path when `.connect`ing provider
 Object.assign(LedgerSigner.prototype, {
@@ -18,14 +24,25 @@ Object.assign(LedgerSigner.prototype, {
 /**
  * Overwrite EVMChain.getWallet to support reading private key from file, env var or Ledger
  * @param provider - provider instance to be connected to signers
- * @param opts - wallet options (as passed to yargs argv)
+ * @param opts.wallet - wallet options (as passed to yargs argv)
  * @returns Promise to Signer instance
  */
-EVMChain.getWallet = async function loadEvmWallet(
-  provider: Provider,
+export async function loadEvmWallet(
+  provider: JsonRpcApiProvider,
   { wallet: walletOpt }: { wallet?: unknown },
 ): Promise<Signer> {
   if (!walletOpt) walletOpt = process.env['USER_KEY'] || process.env['OWNER_KEY']
+  if (
+    typeof walletOpt === 'number' ||
+    (typeof walletOpt === 'string' && walletOpt.match(/^(\d+|0x[a-fA-F0-9]{40})$/))
+  ) {
+    // if given a number, numeric string or address, use ethers `provider.getSigner` (e.g. geth or MM)
+    return provider.getSigner(
+      typeof walletOpt === 'string' && walletOpt.match(/^0x[a-fA-F0-9]{40}$/)
+        ? walletOpt
+        : Number(walletOpt),
+    )
+  }
   if (typeof walletOpt !== 'string')
     throw new Error(`Invalid wallet option: ${util.inspect(walletOpt)}`)
   if ((walletOpt ?? '').startsWith('ledger')) {

ccip-cli/src/providers/index.ts

@@ -4,13 +4,15 @@ import {
   type Chain,
   type ChainGetter,
   type ChainTransaction,
+  type EVMChain,
+  ChainFamily,
   networkInfo,
   supportedChains,
 } from '@chainlink/ccip-sdk/src/index.ts'
 
-import './aptos.ts'
-import './evm.ts'
-import './solana.ts'
+import { loadAptosWallet } from './aptos.ts'
+import { loadEvmWallet } from './evm.ts'
+import { loadSolanaWallet } from './solana.ts'
 
 const RPCS_RE = /\b(?:http|ws)s?:\/\/[\w/\\@&?%~#.,;:=+-]+/
 
@@ -141,3 +143,20 @@ export function fetchChainsFromRpcs(
     return chainGetter
   }
 }
+
+export async function loadChainWallet(chain: Chain, opts: { wallet?: unknown }) {
+  let wallet
+  switch (chain.network.family) {
+    case ChainFamily.EVM:
+      wallet = await loadEvmWallet((chain as EVMChain).provider, opts)
+      return [await wallet.getAddress(), wallet] as const
+    case ChainFamily.Solana:
+      wallet = await loadSolanaWallet(opts)
+      return [wallet.publicKey.toBase58(), wallet] as const
+    case ChainFamily.Aptos:
+      wallet = await loadAptosWallet(opts)
+      return [wallet.accountAddress.toString(), wallet] as const
+    default:
+      throw new Error(`Unsupported chain family: ${chain.network.family}`)
+  }
+}

ccip-cli/src/providers/solana.ts

@@ -1,8 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import util from 'node:util'
 
-import { SolanaChain } from '@chainlink/ccip-sdk/src/index.ts'
-import { Wallet as SolanaWallet } from '@coral-xyz/anchor'
+import { Wallet as AnchorWallet } from '@coral-xyz/anchor'
 import SolanaLedger from '@ledgerhq/hw-app-solana'
 import HIDTransport from '@ledgerhq/hw-transport-node-hid'
 import {
@@ -70,9 +69,14 @@ export class LedgerSolanaWallet {
   }
 }
 
-SolanaChain.getWallet = async function loadSolanaWallet({
+/**
+ * Loads a Solana wallet from a file or Ledger device.
+ * @param opts.wallet - wallet options (as passed to yargs argv)
+ * @returns Promise to Anchor Wallet instance
+ */
+export async function loadSolanaWallet({
   wallet: walletOpt,
-}: { wallet?: unknown } = {}): Promise<SolanaWallet> {
+}: { wallet?: unknown } = {}): Promise<AnchorWallet> {
   if (!walletOpt)
     walletOpt = process.env['USER_KEY'] || process.env['OWNER_KEY'] || '~/.config/solana/id.json'
   let wallet: string
@@ -83,11 +87,11 @@ SolanaChain.getWallet = async function loadSolanaWallet({
     let derivationPath = walletOpt.split(':')[1]
     if (!derivationPath) derivationPath = "44'/501'/0'"
     else if (!isNaN(Number(derivationPath))) derivationPath = `44'/501'/${derivationPath}'`
-    return (await LedgerSolanaWallet.create(derivationPath)) as SolanaWallet
+    return (await LedgerSolanaWallet.create(derivationPath)) as AnchorWallet
   } else if (existsSync(walletOpt)) {
     wallet = hexlify(new Uint8Array(JSON.parse(readFileSync(walletOpt, 'utf8'))))
   }
-  return new SolanaWallet(
+  return new AnchorWallet(
     Keypair.fromSecretKey(wallet.startsWith('0x') ? getBytes(wallet) : bs58.decode(wallet)),
   )
 }

ccip-sdk/README.md

@@ -55,26 +55,29 @@ constructor from the specific library provider (e.g. `EVMChain.fromProvider(prov
 
 ## Wallet
 
-Most chain families classes have a *cached* `getWallet` method, which handles creating a signer or
-wallet from raw private keys. They receive a generic `{ wallet?: unknown }` object, which may be
-passed from other methods, or CLI's `argv` options, to aid in wallet creation.
+Transaction-sending high-level methods, namely `Chain.sendMessage` and `Chain.executeReport`,
+require a `wallet` property in last `opts` parameter. This is marked as `unknown` in generic Chain
+abstract class, but required to be an asynchronous signer wallet respective to each chain family:
 
-If they can't, users may override the *static* `getWallet` function (with parameters depending on
-chain family implementation), which is called to try to construct a wallet or signer instead.
-This can be used to extend the library to create signers according to each environment, without
-requiring a full class inheritance.
+- `EVMChain` requires an `ethers` `Signer`
+- `SolanaChain` requires an `anchor` `Wallet`
+- `AptosChain` requires an `aptos-ts-sdk` `Account`
 
-Example:
-```ts
-import { EVMChain } from '@chainlink/ccip-sdk'
+These signers are used in the simplest way possible (i.e. using address accessors where needed,
+and `async signTransaction`-like methods), so developers may be able to easily inject their own
+implementations, to get called or intercept signature requests by these methods.
 
-EVMChain.getWallet = async function(opts?: { provider?: Provider, wallet?: unknown }): Promise<Signer> {
-  // instantiate Signer
-}
-```
+Optionally, `sendMessage` and `executeReport` also have companion `generateUnsignedSendMessage` and
+`generateUnsignedExecuteReport` methods, returning chain-family-specific unsigned data, which one
+can use to sign and send the transactions manually.
+
+Notice that these are lower-level methods, and require the developer to handle the signing and
+sending of the transactions themselves, skipping niceties from the higher-level methods, like
+retries, gas estimation and transactions batching.
 
 > [!TIP]
-> For EVMChain on Browsers, there's no need to override like the above, since providing a `{ wallet: number | address }` option object will make it create a signer from `provider.getSigner(number)`, which should load the account from the browser's wallet extension.
+> For EVMChain on Browsers, one can use `chain.provider.getSigner(numberOrAddress)` to fetch a
+provider-backed signer from compatible wallets, like Metamask.
 
 ## Tree-shakers
 

ccip-sdk/src/aptos/index.ts

@@ -1,13 +1,6 @@
 import util from 'util'
 
-import {
-  Account,
-  Aptos,
-  AptosConfig,
-  Ed25519PrivateKey,
-  Network,
-  TransactionResponseType,
-} from '@aptos-labs/ts-sdk'
+import { Aptos, AptosConfig, Network, TransactionResponseType } from '@aptos-labs/ts-sdk'
 import {
   type BytesLike,
   concat,
@@ -61,7 +54,7 @@ import { executeReport } from './exec.ts'
 import { getAptosLeafHasher } from './hasher.ts'
 import { getUserTxByVersion, getVersionTimestamp, streamAptosLogs } from './logs.ts'
 import { getTokenInfo } from './token.ts'
-import { type AptosAsyncAccount, EVMExtraArgsV2Codec, SVMExtraArgsV1Codec } from './types.ts'
+import { EVMExtraArgsV2Codec, SVMExtraArgsV1Codec, isAptosAccount } from './types.ts'
 import type { CCIPMessage_V1_6_EVM } from '../evm/messages.ts'
 import {
   decodeMessage,
@@ -116,7 +109,6 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
           .then((modules) => modules.map(({ abi }) => abi!.name)),
       { maxSize: 100, maxArgs: 1 },
     )
-    this.getWallet = memoize(this.getWallet.bind(this), { maxSize: 1, maxArgs: 0 })
     this.provider.getTransactionByVersion = memoize(
       this.provider.getTransactionByVersion.bind(this.provider),
       {
@@ -292,25 +284,6 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
     }
     return registry
   }
-
-  static getWallet(_opts: { wallet?: unknown } = {}): Promise<AptosAsyncAccount> {
-    return Promise.reject(new Error('TODO according to your environment'))
-  }
-
-  // cached
-  async getWallet(opts: { wallet?: unknown } = {}): Promise<AptosAsyncAccount> {
-    if (isBytesLike(opts.wallet)) {
-      return Account.fromPrivateKey({
-        privateKey: new Ed25519PrivateKey(opts.wallet, false),
-      })
-    }
-    return (this.constructor as typeof AptosChain).getWallet(opts)
-  }
-
-  async getWalletAddress(opts?: { wallet?: unknown }): Promise<string> {
-    return (await this.getWallet(opts)).accountAddress.toString()
-  }
-
   // Static methods for decoding
   static decodeMessage(log: {
     data: BytesLike | Record<string, unknown>
@@ -446,7 +419,12 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
     opts?: { wallet?: unknown; approveMax?: boolean },
   ): Promise<CCIPRequest> {
     if (!message.fee) message.fee = await this.getFee(router, destChainSelector, message)
-    const account = await this.getWallet(opts)
+    const account = opts?.wallet
+    if (!isAptosAccount(account)) {
+      throw new Error(
+        `${this.constructor.name}.sendMessage requires an Aptos account wallet, got=${util.inspect(opts?.wallet)}`,
+      )
+    }
 
     const hash = await ccipSend(
       this.provider,
@@ -470,7 +448,12 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
     execReport: ExecutionReport,
     opts?: { wallet?: unknown; gasLimit?: number },
   ): Promise<ChainTransaction> {
-    const account = await this.getWallet(opts)
+    const account = opts?.wallet
+    if (!isAptosAccount(account)) {
+      throw new Error(
+        `${this.constructor.name}.sendMessage requires an Aptos account wallet, got=${util.inspect(opts?.wallet)}`,
+      )
+    }
 
     if (!('allowOutOfOrderExecution' in execReport.message && 'gasLimit' in execReport.message)) {
       throw new Error('Aptos expects EVMExtraArgsV2 reports')

ccip-sdk/src/aptos/types.ts

@@ -20,6 +20,16 @@ export type AptosAsyncAccount = {
   ) => Promise<AccountAuthenticator> | AccountAuthenticator
 }
 
+export function isAptosAccount(account: unknown): account is AptosAsyncAccount {
+  return (
+    typeof account === 'object' &&
+    account !== null &&
+    'publicKey' in account &&
+    'accountAddress' in account &&
+    'signTransactionWithAuthenticator' in account
+  )
+}
+
 export const EVMExtraArgsV2Codec = bcs.struct('EVMExtraArgsV2', {
   gasLimit: bcs.u256(),
   allowOutOfOrderExecution: bcs.bool(),