initWallet

Initialize wallet-core. This must be the first request made to wallet-core; every other operation fails until initialization has completed.

Request:

The request must be an InitRequest object.

Response:

On success, the result is an InitResponse object.

Side effects:

Initializes the wallet: opens the wallet database (using the native sqlite schema for a new, empty database when config.features.useNativeDb is set, and migrating an existing database to the native sqlite schema when config.features.migrateNativeDb is set), installs the built-in default exchanges (unless config.testing.skipDefaults is set), applies config.logLevel as the global log level, runs internal data migrations and — on the first initialization only — cleans up failed and leftover claims and deletes ephemeral exchanges, and starts the background task loop (unless config.lazyTaskLoop is set).

Details:

Initialization fails with WALLET_DB_UNAVAILABLE if the wallet database cannot be opened for writing.

Calling initWallet again after a successful initialization re-initializes the wallet with the new configuration, exactly like setWalletRunConfig. Fields not present in config are reset to their defaults.

interface InitRequest {
  // Configuration overrides; omitted fields fall back to defaults.
  config?: PartialWalletRunConfig;
}

interface PartialWalletRunConfig {
  testing?: Partial<WalletRunConfig["testing"]>;
  features?: Partial<WalletRunConfig["features"]>;
  lazyTaskLoop?: Partial<WalletRunConfig["lazyTaskLoop"]>;
  logLevel?: Partial<WalletRunConfig["logLevel"]>;
}

interface WalletRunConfig {
  // Unsafe options which should only be used to create
  // testing environments.
  testing: {
    devModeActive: boolean;
    insecureTrustExchange: boolean;
    preventThrottling: boolean;
    skipDefaults: boolean;
    emitObservabilityEvents?: boolean;

    // Coin selection algorithm to use when spending.
    // Defaults to the TALER_WALLET_COINSEL environment variable,
    // and to "default" when that is unset.
    coinSelectionAlgorithm: CoinSelectionAlgorithm;
  };

  // Configuration values that may be safe to show to the user.
  features: {
    allowHttp: boolean;

    // Migrate the wallet database to wallet-core's native sqlite
    // schema, replacing the IndexedDB emulation.  Checked on every
    // initialization; off by default.
    migrateNativeDb: boolean;

    // Use the native sqlite schema when initializing a new, empty
    // database; never converts an existing IndexedDB wallet.
    useNativeDb: boolean;
  };

  // Start processing tasks only when explicitly required, even
  // after init has been called.
  lazyTaskLoop: boolean;

  // Global log level.
  logLevel: string;
}

// Coin selection algorithm the wallet uses when spending.
// "legacy-2024" is the algorithm shipped in 2024, kept for external
// test suites that pin the coin selections it produces.
type CoinSelectionAlgorithm = "default" | "legacy-2024";

interface InitResponse {
  // Version information about the initialized wallet-core.
  versionInfo: WalletCoreVersion;

  // Database backend used by the initialized wallet.
  databaseBackend: WalletDatabaseBackend;
}

// Database backends that wallet-core can run on.
type WalletDatabaseBackend = "indexeddb" | "sqlite";