Class WalletApiClient

constructor

• new WalletApiClient(
      __namedParameters: {
          deployment: "create" | "deploy" | "sign";
          identity?: string;
          lambda?: Pick<LambdaClient, "send">;
      },
  ): WalletApiClient

  Parameters

  • __namedParameters: {
        deployment: "create" | "deploy" | "sign";
        identity?: string;
        lambda?: Pick<LambdaClient, "send">;
    }

    • deployment: "create" | "deploy" | "sign"

      Picks the function (WALLET_FUNCTION_NAME, WALLET_CREATE_FUNCTION_NAME or WALLET_DEPLOY_FUNCTION_NAME, a live alias when deployed) and so which ops it serves.

    • Optionalidentity?: string

      Recorded in wallet-api's invoke log, e.g. cfx-temporal-worker; absent, wallet-api records its own name.

    • Optionallambda?: Pick<LambdaClient, "send">

  Returns WalletApiClient

Staticinstance

cancelTransaction

• cancelTransaction(
      args: { id: string; reason?: unknown },
  ): Promise<
      | { ok: true; value: { status: "CANCELLED" } }
      | { error: WalletApiCancelError; ok: false },
  >

  Calls off a transaction that was never broadcast: the row and its nonce.

  Parameters

  • args: { id: string; reason?: unknown }

    • id: string

    • Optionalreason?: unknown

      Why, stored on the row as its error.

  Returns Promise<
      | { ok: true; value: { status: "CANCELLED" } }
      | { error: WalletApiCancelError; ok: false },
  >

createNonce

• createNonce(
      args: { reference: IdempotencyKey },
  ): Promise<
      | { ok: true; value: WalletApiNonceCreated }
      | { error: WalletApiNonceCreateError; ok: false },
  >

  Creates a pool nonce account derived from PAYER and reference, and adds it to the pool once finalized. The same reference is the same account.

  Parameters

  • args: { reference: IdempotencyKey }

    • reference: IdempotencyKey

      wallet-api's idempotency key: it derives the account from it.

  Returns Promise<
      | { ok: true; value: WalletApiNonceCreated }
      | { error: WalletApiNonceCreateError; ok: false },
  >

createTransaction

• createTransaction(
      request: WalletApiTransactionRequest,
  ): Promise<
      | { error: WalletApiSignError; ok: false }
      | { ok: true; value: WalletApiSigned },
  >

  Stores one Solana transaction and signs it when every required signer is CFX's (with send, broadcast and followed too). With any external signer it signs nothing: AWAITING_SIGNATURE, the unsigned wire and missingSigners. Idempotent by (reference, message).

  Parameters

  • request: WalletApiTransactionRequest

  Returns Promise<
      | { error: WalletApiSignError; ok: false }
      | { ok: true; value: WalletApiSigned },
  >

createWallet

• createWallet(
      args: {
          delegation?: WalletDelegation;
          derivationId: string;
          legacyMintfx?: { walletId: string };
      },
  ): Promise<
      | { ok: true; value: WalletApiCreated }
      | { error: WalletApiCreateError; ok: false },
  >

  A BIP39 wallet with its CFX share and primary address, and with legacyMintfx the ledger account's mintfx PDA as a LEGACY_MINTFX address.

  Parameters

  • args: {
        delegation?: WalletDelegation;
        derivationId: string;
        legacyMintfx?: { walletId: string };
    }

    • Optionaldelegation?: WalletDelegation

    • derivationId: string

      What the wallet is for, recorded as wallet.derivation_id.

    • OptionallegacyMintfx?: { walletId: string }

  Returns Promise<
      | { ok: true; value: WalletApiCreated }
      | { error: WalletApiCreateError; ok: false },
  >

deriveAddress

• deriveAddress(
      args: {
          accountIndex: 0;
          chain: "EVM" | "BITCOIN_SEGWIT" | "BITCOIN_TAPROOT" | "TRON";
          walletId: string;
      },
  ): Promise<
      | { ok: true; value: WalletApiDerived }
      | { error: WalletApiDeriveError; ok: false },
  >

  The wallet's live BIP39 secret's account-0 address on chain (EVM, TRON or a Bitcoin script type), derived through its CFX share and recorded; created: false when the wallet already held it.

  Parameters

  • args: {
        accountIndex: 0;
        chain: "EVM" | "BITCOIN_SEGWIT" | "BITCOIN_TAPROOT" | "TRON";
        walletId: string;
    }

  Returns Promise<
      | { ok: true; value: WalletApiDerived }
      | { error: WalletApiDeriveError; ok: false },
  >

evmDeploy

• evmDeploy<Op extends keyof WalletApiEvmDeployOpArgs>(
      op: Op,
      args: WalletApiEvmDeployOpArgs[Op],
  ): Promise<
      | { error: WalletApiEvmError; ok: false }
      | { ok: true; value: WalletApiEvmAlreadyDone | WalletApiEvmSigned },
  >

  A deploy, timelock or NTT op: the row it sent, or alreadyDeployed when the chain already holds the result (a deployed address, a granted role, a paused manager) and nothing was sent.

  Type Parameters

  • Op extends keyof WalletApiEvmDeployOpArgs

  Parameters

  • op: Op
  • args: WalletApiEvmDeployOpArgs[Op]

  Returns Promise<
      | { error: WalletApiEvmError; ok: false }
      | { ok: true; value: WalletApiEvmAlreadyDone | WalletApiEvmSigned },
  >

evmGasStation

• evmGasStation(
      args: { chainId: number },
  ): Promise<
      | { error: WalletApiEvmError; ok: false }
      | { ok: true; value: WalletApiGasStation },
  >

  The gas station's balance and the paymaster's deposit on chainId. Reads only.

  Parameters

  • args: { chainId: number }

  Returns Promise<
      | { error: WalletApiEvmError; ok: false }
      | { ok: true; value: WalletApiGasStation },
  >

evmTransaction

• evmTransaction<Op extends keyof WalletApiEvmOpArgs>(
      op: Op,
      args: WalletApiEvmOpArgs[Op],
  ): Promise<
      | { ok: true; value: WalletApiEvmSigned }
      | { error: WalletApiEvmError; ok: false },
  >

  One EVM intent, built, signed and stored by wallet-api as a UserOperation the chain's gas station submits (with send, broadcast and followed too). Idempotent on reference.

  Type Parameters

  • Op extends keyof WalletApiEvmOpArgs

  Parameters

  • op: Op
  • args: WalletApiEvmOpArgs[Op]

  Returns Promise<
      | { ok: true; value: WalletApiEvmSigned }
      | { error: WalletApiEvmError; ok: false },
  >

expireTransaction

• expireTransaction(
      args: { id: string; nonceHoldLapsed?: boolean },
  ): Promise<
      | { ok: true; value: WalletApiExpired }
      | { error: ServiceError; ok: false },
  >

  Expires one AWAITING_SIGNATURE row at its deadline: a lapsed lifetime (or, with nonceHoldLapsed, a pool-nonce hold that ended) cancels the row.

  Parameters

  • args: { id: string; nonceHoldLapsed?: boolean }

    • id: string

    • OptionalnonceHoldLapsed?: boolean

      The pool's verdict that the row's nonce hold ended (nonceSyncAction.ts).

  Returns Promise<
      | { ok: true; value: WalletApiExpired }
      | { error: ServiceError; ok: false },
  >

importWallet

• importWallet(
      args: {
          derivationId: string;
          legacyMintfx?: { walletId: string };
          secret: string;
          source: NonNullable<WalletImportSource | null>;
      },
  ): Promise<
      | { ok: true; value: WalletApiImported }
      | { error: WalletApiImportError; ok: false },
  >

  A customer's own key as an ALLOWED wallet, and with legacyMintfx the ledger account's PDA beside it. secret goes only into the invoke payload; nothing this throws or returns carries it.

  Parameters

  • args: {
        derivationId: string;
        legacyMintfx?: { walletId: string };
        secret: string;
        source: NonNullable<WalletImportSource | null>;
    }

  Returns Promise<
      | { ok: true; value: WalletApiImported }
      | { error: WalletApiImportError; ok: false },
  >

releaseNonce

• releaseNonce(
      args: { walletTransactionId: string },
  ): Promise<
      | { ok: true; value: { status: WalletApiReleaseStatus } }
      | { error: WalletApiReleaseError; ok: false },
  >

  Ends a nonced transaction and hands its pool nonce back. wallet-api reads the chain itself, advancing a nonce that has not moved.

  Parameters

  • args: { walletTransactionId: string }

  Returns Promise<
      | { ok: true; value: { status: WalletApiReleaseStatus } }
      | { error: WalletApiReleaseError; ok: false },
  >

sendEvmTransaction

• sendEvmTransaction(
      args: { commitment: WalletApiCommitment; id: string },
  ): Promise<
      | { ok: true; value: WalletApiEvmSigned }
      | { error: WalletApiEvmError; ok: false },
  >

  Resumes a stored EVM row: the same bytes, followed to commitment.

  Parameters

  • args: { commitment: WalletApiCommitment; id: string }

  Returns Promise<
      | { ok: true; value: WalletApiEvmSigned }
      | { error: WalletApiEvmError; ok: false },
  >

sendTransaction

• sendTransaction(
      args: {
          commitment: WalletApiCommitment;
          id: string;
          signedTransaction?: string;
      },
  ): Promise<
      | { error: WalletApiSignError; ok: false }
      | { ok: true; value: WalletApiSigned },
  >

  An AWAITING_SIGNATURE row's external signatures in signedTransaction: verified, then CFX signs last, stores, broadcasts and follows to commitment. A signed row not yet landed resumes; a settled one is answered as it stands.

  Parameters

  • args: { commitment: WalletApiCommitment; id: string; signedTransaction?: string }

    • commitment: WalletApiCommitment

    • id: string

    • OptionalsignedTransaction?: string

      Base64 wire; required on an AWAITING_SIGNATURE row, else the stored bytes or absent.

  Returns Promise<
      | { error: WalletApiSignError; ok: false }
      | { ok: true; value: WalletApiSigned },
  >

signEvmMessage

• signEvmMessage(
      args: WalletApiEvmMessageArgs,
  ): Promise<
      | { ok: true; value: WalletApiEvmMessageSigned }
      | {
          error:
              | ServiceError<"WALLET_API_ERROR">
              | ServiceError<
                  | "SIGNER_MISMATCH"
                  | "SIGNER_NOT_FOUND"
                  | "INVALID_ARGS"
                  | "CHAIN_NOT_CONFIGURED"
                  | "DELEGATE_MISMATCH",
              >;
          ok: false;
      },
  >

  An EIP-191, EIP-712 or EIP-7702 signature by the role signer.

  Parameters

  • args: WalletApiEvmMessageArgs

  Returns Promise<
      | { ok: true; value: WalletApiEvmMessageSigned }
      | {
          error:
              | ServiceError<"WALLET_API_ERROR">
              | ServiceError<
                  | "SIGNER_MISMATCH"
                  | "SIGNER_NOT_FOUND"
                  | "INVALID_ARGS"
                  | "CHAIN_NOT_CONFIGURED"
                  | "DELEGATE_MISMATCH",
              >;
          ok: false;
      },
  >

signMessage

• signMessage(
      args: { message: string; reference: string; signer: string },
  ): Promise<
      | { ok: true; value: WalletApiMessageSigned }
      | { error: WalletApiMessageSignError; ok: false },
  >

  Signs one base64 message as the role signer.

  Parameters

  • args: { message: string; reference: string; signer: string }

  Returns Promise<
      | { ok: true; value: WalletApiMessageSigned }
      | { error: WalletApiMessageSignError; ok: false },
  >