CrossmintRuntimeWalletBase

Abstract Base Class Base class for chain-specific runtime wallets (EVM, Solana, Stellar).

abstract base class CrossmintRuntimeWalletBase

Wraps a server-issued CrossmintWallet with signer management, transaction/signature approval flows, device-signer recovery, and token operations. Use the chain subclasses (CrossmintEvmWallet, CrossmintSolanaWallet, CrossmintStellarWallet) rather than this class directly.

Constructors

CrossmintRuntimeWalletBase

CrossmintRuntimeWalletBase({
  required this.client,
  required this.wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  this.deviceSignerKeyStorage,
  this.onAuthRequired,
})

Properties

client

final CrossmintClient client

Top-level Crossmint client shared by all wallet operations.

wallet

final CrossmintWallet wallet

Server-issued wallet snapshot backing this runtime instance.

deviceSignerKeyStorage

final DeviceSignerKeyStorage? deviceSignerKeyStorage

Storage backend for hardware-backed device signer keys.

onAuthRequired

final CrossmintSignerAuthRequiredCallback? onAuthRequired

Callback invoked when a signer operation requires user authentication.

defaultChain

String get defaultChain

Chain identifier used when the wallet snapshot has no explicit chain.

chain

String get chain

Blockchain this wallet operates on (falls back to defaultChain).

address

String get address

On-chain address of the wallet.

owner

String? get owner

Owner identifier associated with the wallet, if any.

recoveryMethods

List<CrossmintSignerConfig> get recoveryMethods

Every recovery method configured on the wallet.

recovery

CrossmintSignerConfig? get recovery

Primary recovery signer config, the first of recoveryMethods.

locator

String get locator

Unique wallet locator used for API calls.

signer

CrossmintWalletApprovalSigner? get signer

Currently active approval signer, or null if none is selected.

additionalSigners

List<CrossmintWalletApprovalSigner> get additionalSigners

Secondary signers available alongside the primary signer.

needsRecovery

bool get needsRecovery

Whether the wallet needs recovery (signer registration) before the next transaction.

canExportPrivateKey

bool get canExportPrivateKey

Whether the active signer supports private-key export.

debugIsRecovering

bool get debugIsRecovering

Test-only: true while recover() is in flight. Lets concurrency tests assert that concurrent callers coalesce onto a single recovery future.

Methods

useSigner

Future<void> useSigner(
  CrossmintSignerConfig signer, {
  List<CrossmintSignerConfig> additionalSigners =
      const <CrossmintSignerConfig>[],
})

Sets the active signer for this wallet. Accepts a signer config object; the locator is inferred internally. Works for device, non-custodial, external-wallet, and passkey signers.

useRecoveryMethod

Future<void> useRecoveryMethod(CrossmintSignerConfig recoveryMethod)

Selects which recovery method authorizes admin operations: addSigner, removeSigner, and device-signer recovery. Unlike useSigner, this does not change the active signer used for transactions and signatures.

balances

Future<CrossmintWalletBalanceSnapshot> balances({
  List<String> tokens = const <String>[],
})

Returns the wallet balances — always includes USDC and the native token. Pass additional tokens to request extra token balances.

transactions

Future<List<CrossmintTransactionSummary>> transactions()

Lists transaction summaries for this wallet.

transaction

Future<CrossmintTransactionDetails?> transaction(String transactionId)

Retrieves details for a specific transaction by ID.

approve

Future<CrossmintWalletApproveResult> approve(
  CrossmintWalletApproveRequest request,
)

Approves a pending transaction or signature request.

nfts

Future<CrossmintWalletNftPage> nfts({int page = 1, int perPage = 50})

Returns the wallet’s NFTs (paginated).

fund

Future<CrossmintWalletFundResult> fund(CrossmintWalletFundRequest request)

Initiates a funding (on-ramp) request for this wallet.

transfers

Future<List<CrossmintJsonMap>> transfers({
  int page = 1,
  int perPage = 50,
  List<String> tokens = const <String>[],
  String? status,
})

Reads transfer history for this wallet (unstable API).

send

Future<CrossmintTransactionDetails> send(
  CrossmintWalletTokenTransferRequest request,
)

Sends a token transfer and waits for confirmation.

sendToken

Future<CrossmintTransactionDetails> sendToken(
  String to,
  String token,
  String amount, {
  bool prepareOnly = false,
  String? transactionType,
})

Convenience wrapper around send for simple token transfers.

signers

Future<List<CrossmintWalletSigner>> signers()

Lists all signers registered on this wallet with their current status.

removeSigner

Future<CrossmintTransactionDetails> removeSigner(
  String signerLocator, {
  bool prepareOnly = false,
})

Removes a signer from the wallet by its locator.

signerIsRegistered

Future<bool> signerIsRegistered(String signerLocator)

Checks whether a signer with the given locator is registered.

isSignerApproved

Future<bool> isSignerApproved(String signerLocator)

Checks whether a registered signer is approved and usable.

addSigner

Future<CrossmintWalletAddSignerResult> addSigner(
  CrossmintSignerConfig signer, {
  bool prepareOnly = false,
  bool deployImmediately = true,
})

Registers a new signer on the wallet and approves the registration.

preAuthIfNeeded

Future<void> preAuthIfNeeded()

Awaits any in-flight recovery; if _needsRecovery is set and no recovery is in-flight, starts one and awaits it. Concurrent callers coalesce onto the same future so a single recovery runs per wallet. Then authenticates a non-custodial active signer, so an OTP round-trip happens before the operation exists rather than inside the window in which a Solana blockhash stays valid. Mirrors the TypeScript SDK.

recover

Future<void> recover()

Runs device-signer recovery: resumes any pending operation or registers a new device signer using the recovery signer. Returns early if the device signer is already approved on-chain.

debugRegisterRecoverySigner

void debugRegisterRecoverySigner(CrossmintWalletApprovalSigner signer)

Test-only: inject a pre-assembled recovery signer, bypassing the constructor-config resolution path. Used by tests that wire a fake bridge into a non-custodial signer without exercising hiddenSignerBridgeController. Not part of the supported public API.

debugSelectRecoveryApprover

Future<String?> debugSelectRecoveryApprover()

Test-only: the approver locator an admin API call would carry, or null on a wallet with a single recovery method.

debugRecoverySignerForPendingOperation

Future<CrossmintWalletApprovalSigner> debugRecoverySignerForPendingOperation(
  String approverLocator,
)

Test-only: the signer that can approve an operation addressed to approverLocator.

debugResolveRecoverySigner

Future<CrossmintWalletApprovalSigner> debugResolveRecoverySigner()

Test-only: the signer the selected recovery method resolves to. Throws when the selected method cannot sign from this client.

exportPrivateKey

Future<void> exportPrivateKey({CrossmintExportSignerBridge? bridge})

Exports the wallet’s private key via the export signer bridge.

approveSignatureAndWaitInternal

Future<String> approveSignatureAndWaitInternal(String signatureId)

Approves a pending signature and polls until it completes.

approveSignatureInternal

Future<CrossmintSignatureRecord> approveSignatureInternal( String signatureId, )

Submits approvals for a pending signature request.

approveTransactionAndWait

Future<CrossmintTransactionDetails> approveTransactionAndWait(
  String transactionId, {
  CrossmintTransactionDetails? seedTransaction,
})

Approves a pending transaction and polls until it reaches a terminal state.

approveTransactionInternal

Future<CrossmintTransactionDetails> approveTransactionInternal(
  String transactionId,
)

Submits approvals for a pending transaction.

transactionApprovalPayload

String transactionApprovalPayload({
  required CrossmintTransactionDetails transaction,
  required CrossmintJsonMap pendingApproval,
  required CrossmintWalletApprovalSigner signer,
})

Extracts the signable payload from a pending transaction approval.

completeApprovedTransaction

Future<CrossmintTransactionDetails> completeApprovedTransaction(
  CrossmintTransactionDetails transaction, {
  required String transactionId,
})

Polls a transaction until it reaches a terminal state and attaches explorer links.

waitForTransaction

Future<CrossmintTransactionDetails> waitForTransaction( String transactionId, )

Polls a transaction by ID until it succeeds or fails.

walletSnapshotForSigners

Future<CrossmintWallet> walletSnapshotForSigners()

Fetches a fresh wallet snapshot to inspect registered signers.

requireActiveSigner

CrossmintWalletApprovalSigner requireActiveSigner(String operation)

Returns the active signer or throws if none is selected.