CrossmintWalletController

Flutter Final Class

Final Class

Stateful orchestrator for Crossmint wallets in a Flutter app.

final class CrossmintWalletController extends ChangeNotifier

Holds the currently-loaded CrossmintWallet, exposes lifecycle operations (getWallet, createWallet, ensureLoaded, refresh, clear), surfaces OTP challenges via otp, and provides create*Wallet* convenience methods that wire a runtime wallet with a signer of your choosing (device, non-custodial, external, passkey).

Obtain one from CrossmintClient.createWalletController and pair it with CrossmintWalletHost (headless) or CrossmintWalletProvider (opt-in Material UI) so the hidden signer bridge has a place to mount.

Extends ChangeNotifier — listen to the controller for wallet-state changes. Mutations go through the controller’s public API; observation can additionally go through state for a narrower, read-only surface.

Constructors

CrossmintWalletController

CrossmintWalletController({
  required this.client,
  required this.config,
  CrossmintWalletStateRepository? stateRepository,
})

Creates a wallet controller. Prefer CrossmintClient.createWalletController over calling this directly.

Properties

client

final CrossmintClient client

The underlying client — exposed for code that needs direct access to sub-clients (auth, orders, credentials, etc.).

config

final CrossmintWalletControllerConfig config

The configuration this controller was built with.

otp

final CrossmintWalletOtpController otp

OTP controller for non-custodial email/phone signer challenges.

state

CrossmintWalletStateView get state

Read-only observation surface for the underlying wallet state. Advanced consumers can subscribe to wallet / status changes directly via this Listenable while still routing all mutations through the controller’s public API (getWallet, createWallet, refresh, clear, …).

currentWallet

CrossmintWallet? get currentWallet

The currently-loaded wallet, or null if none is loaded.

status

CrossmintWalletStatus get status

Current wallet lifecycle status.

onAuthRequired

CrossmintWalletAuthRequiredCallback get onAuthRequired

The auth-required callback the controller wires into every signer it builds. Exposed so apps building signers manually can share the same OTP-handling path.

pendingOtpChallenge

CrossmintOtpChallenge? get pendingOtpChallenge

Shortcut to CrossmintWalletOtpController.pendingChallenge.

otpChallengeListenable

ValueListenable<CrossmintOtpChallenge?> get otpChallengeListenable

Shortcut to CrossmintWalletOtpController.challengeListenable.

requireCurrentWallet

CrossmintWallet get requireCurrentWallet

Returns the currently-loaded wallet or throws CrossmintWalletException when none is loaded.

Methods

getWallet

Future<CrossmintWallet?> getWallet( CrossmintWalletLookupRequest request, )

Looks up an existing wallet and stores the result in controller state. Returns null when no wallet matches. Listeners fire on state changes.

loadWallet

Future<CrossmintWallet?> loadWallet(CrossmintWalletLookupRequest request)

Deprecated: use getWallet instead.

createWallet

Future<CrossmintWallet> createWallet( CrossmintWalletCreateRequest request, )

Creates a new wallet and stores it in controller state. Validates passkey signers up-front via crossmintValidatePasskeySigners and fires CrossmintWalletLifecycleCallbacks.onWalletCreationStart if set.

ensureLoaded

Future<CrossmintWallet?> ensureLoaded()

Ensures a wallet is loaded, creating one if configured to do so.

refresh

Future<CrossmintWallet?> refresh()

Re-fetches the currently-loaded wallet from the API. Returns null when nothing is loaded.

clear

Future<void> clear()

Drops the loaded wallet and any pending OTP challenge. Call during sign-out.

sendOtp

Future<void> sendOtp()

Shortcut to CrossmintWalletOtpController.sendOtp.

verifyOtp

Future<void> verifyOtp(String otpCode)

Shortcut to CrossmintWalletOtpController.verifyOtp.

rejectOtp

void rejectOtp([Object? error])

Shortcut to CrossmintWalletOtpController.reject.

createEvmWallet

CrossmintEvmWallet createEvmWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})

Wraps the currently-loaded wallet as a runtime CrossmintEvmWallet. Throws CrossmintWalletException if no wallet is loaded.

createSolanaWallet

CrossmintSolanaWallet createSolanaWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})

Wraps the currently-loaded wallet as a runtime CrossmintSolanaWallet. On Solana, device signer support depends on the wallet type and is validated server-side. A default device signer is not auto-injected for Solana; it is registered reactively and falls back to the recovery signer when the server rejects it.

createStellarWallet

CrossmintStellarWallet createStellarWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})

Wraps the currently-loaded wallet as a runtime CrossmintStellarWallet.

createEvmWalletWithDeviceSigner

CrossmintEvmWallet createEvmWalletWithDeviceSigner({
  required String signerLocator,
  String? address,
  DeviceSignerKeyStorage? storage,
})

Builds a runtime EVM wallet backed by a hardware-backed device signer. Use for low-friction, day-to-day signing with keys in Secure Enclave / Android Keystore.

createEvmWalletWithNonCustodialSigner

CrossmintEvmWallet createEvmWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})

Builds a runtime EVM wallet backed by a non-custodial email/phone signer. Requires CrossmintWalletHost (or CrossmintWalletProvider) mounted in the widget tree.

createSolanaWalletWithNonCustodialSigner

CrossmintSolanaWallet createSolanaWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})

Builds a runtime Solana wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

createStellarWalletWithNonCustodialSigner

CrossmintStellarWallet createStellarWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})

Builds a runtime Stellar wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

createStellarWalletWithDeviceSigner

CrossmintStellarWallet createStellarWalletWithDeviceSigner({
  required String signerLocator,
  String? address,
  DeviceSignerKeyStorage? storage,
})

Builds a runtime Stellar wallet backed by a hardware device signer.

createEvmWalletWithExternalWalletSigner

CrossmintEvmWallet createEvmWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})

Builds a runtime EVM wallet backed by a user-owned external wallet (e.g. MetaMask). The caller supplies onSign to perform signatures.

createSolanaWalletWithExternalWalletSigner

CrossmintSolanaWallet createSolanaWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})

Builds a runtime Solana wallet backed by a user-owned external wallet.

createStellarWalletWithExternalWalletSigner

CrossmintStellarWallet createStellarWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})

Builds a runtime Stellar wallet backed by a user-owned external wallet.

createEvmWalletWithPasskeySigner

CrossmintEvmWallet createEvmWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})

Builds a runtime EVM wallet backed by a passkey signer.

createSolanaWalletWithPasskeySigner

CrossmintSolanaWallet createSolanaWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})

Builds a runtime Solana wallet backed by a passkey signer. See createEvmWalletWithPasskeySigner for passkey selection semantics.

createStellarWalletWithPasskeySigner

CrossmintStellarWallet createStellarWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})

Builds a runtime Stellar wallet backed by a passkey signer. See createEvmWalletWithPasskeySigner for passkey selection semantics.

dispose

void dispose()