taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

init-wallet.rst (3758B)

      1 .. ts:op:: initWallet
      2 
      3   Initialize wallet-core.  This must be the first request made to
      4   wallet-core; every other operation fails until initialization has
      5   completed.
      6 
      7   **Request:**
      8 
      9     The request must be an `InitRequest` object.
     10 
     11   **Response:**
     12 
     13     On success, the result is an `InitResponse` object.
     14 
     15   **Side effects:**
     16 
     17     Initializes the wallet: opens the wallet database (using the
     18     native sqlite schema for a new, empty database when
     19     ``config.features.useNativeDb`` is set, and migrating an existing
     20     database to the native sqlite schema when
     21     ``config.features.migrateNativeDb`` is set), installs the built-in
     22     default exchanges (unless ``config.testing.skipDefaults`` is set),
     23     applies ``config.logLevel`` as the global log level, runs internal
     24     data migrations and — on the first initialization only — cleans up
     25     failed and leftover claims and deletes ephemeral exchanges, and
     26     starts the background task loop (unless ``config.lazyTaskLoop`` is
     27     set).
     28 
     29   **Details:**
     30 
     31     Initialization fails with ``WALLET_DB_UNAVAILABLE`` if the wallet
     32     database cannot be opened for writing.
     33 
     34     Calling ``initWallet`` again after a successful initialization
     35     re-initializes the wallet with the new configuration, exactly
     36     like :ts:op:`setWalletRunConfig`.  Fields not present in
     37     ``config`` are reset to their defaults.
     38 
     39 .. ts:def:: InitRequest
     40 
     41   interface InitRequest {
     42     // Configuration overrides; omitted fields fall back to defaults.
     43     config?: PartialWalletRunConfig;
     44   }
     45 
     46 .. ts:def:: PartialWalletRunConfig
     47 
     48   interface PartialWalletRunConfig {
     49     testing?: Partial<WalletRunConfig["testing"]>;
     50     features?: Partial<WalletRunConfig["features"]>;
     51     lazyTaskLoop?: Partial<WalletRunConfig["lazyTaskLoop"]>;
     52     logLevel?: Partial<WalletRunConfig["logLevel"]>;
     53   }
     54 
     55 .. ts:def:: WalletRunConfig
     56 
     57   interface WalletRunConfig {
     58     // Unsafe options which should only be used to create
     59     // testing environments.
     60     testing: {
     61       devModeActive: boolean;
     62       insecureTrustExchange: boolean;
     63       preventThrottling: boolean;
     64       skipDefaults: boolean;
     65       emitObservabilityEvents?: boolean;
     66 
     67       // Coin selection algorithm to use when spending.
     68       // Defaults to the TALER_WALLET_COINSEL environment variable,
     69       // and to "default" when that is unset.
     70       coinSelectionAlgorithm: CoinSelectionAlgorithm;
     71     };
     72 
     73     // Configuration values that may be safe to show to the user.
     74     features: {
     75       allowHttp: boolean;
     76 
     77       // Migrate the wallet database to wallet-core's native sqlite
     78       // schema, replacing the IndexedDB emulation.  Checked on every
     79       // initialization; off by default.
     80       migrateNativeDb: boolean;
     81 
     82       // Use the native sqlite schema when initializing a new, empty
     83       // database; never converts an existing IndexedDB wallet.
     84       useNativeDb: boolean;
     85     };
     86 
     87     // Start processing tasks only when explicitly required, even
     88     // after init has been called.
     89     lazyTaskLoop: boolean;
     90 
     91     // Global log level.
     92     logLevel: string;
     93   }
     94 
     95 .. ts:def:: CoinSelectionAlgorithm
     96 
     97   // Coin selection algorithm the wallet uses when spending.
     98   // "legacy-2024" is the algorithm shipped in 2024, kept for external
     99   // test suites that pin the coin selections it produces.
    100   type CoinSelectionAlgorithm = "default" | "legacy-2024";
    101 
    102 .. ts:def:: InitResponse
    103 
    104   interface InitResponse {
    105     // Version information about the initialized wallet-core.
    106     versionInfo: WalletCoreVersion;
    107 
    108     // Database backend used by the initialized wallet.
    109     databaseBackend: WalletDatabaseBackend;
    110   }
    111 
    112 .. ts:def:: WalletDatabaseBackend
    113 
    114   // Database backends that wallet-core can run on.
    115   type WalletDatabaseBackend = "indexeddb" | "sqlite";