commit 24783f56cad281e43f28ab1f545c18938781941d parent 18f258f14217fdde4de5225eedddd6f2333f7c5a Author: sebasjm+llm <sebasjm@numis.ar> Date: Sat, 3 Oct 2026 16:05:03 -0300 fix some docs Diffstat:
31 files changed, 153 insertions(+), 63 deletions(-)
diff --git a/core/wallet-core/balances/get-balance-detail.rst b/core/wallet-core/balances/get-balance-detail.rst @@ -23,10 +23,15 @@ balance the wallet believes it could spend right now, without waiting for any operations to complete. The remaining balances are subsets of the material balance: ``balanceAgeAcceptable`` applies an age - restriction, the ``balanceReceiver*Acceptable`` balances restrict to - funds that a receiver accepts based on exchange URL, exchange public - key or auditor URL, and the depositable balances additionally require - that the funds can be deposited via a supported wire method. + restriction (always zero for this operation), the + ``balanceReceiver*Acceptable`` balances restrict to funds that a + receiver accepts based on exchange URL, exchange public key or + auditor URL, and the depositable balances additionally require that + the funds can be deposited via a supported wire method. Coins signed + by a master key that the exchange has since replaced (and not + re-advertised) are excluded from all of these balances, as coin + selection would never pick them; unlike in :ts:op:`getBalances`, they + are not reported at all here. .. ts:def:: GetBalanceDetailRequest diff --git a/core/wallet-core/bank-accounts/add-bank-account.rst b/core/wallet-core/bank-accounts/add-bank-account.rst @@ -30,6 +30,10 @@ identifier; the request fails with ``WALLET_BANK_ACCOUNT_NOT_FOUND`` when no such account exists. + In all cases the stored account is rewritten with the values from + the request, so updating or replacing an account resets its + ``kycCompleted`` flag to ``false``. + .. ts:def:: AddBankAccountRequest interface AddBankAccountRequest { diff --git a/core/wallet-core/bank-accounts/list-bank-accounts.rst b/core/wallet-core/bank-accounts/list-bank-accounts.rst @@ -15,7 +15,8 @@ When ``currency`` is specified, only accounts that support the currency are returned; accounts whose supported currencies are - unknown are always included. + unknown are always included. Stored accounts whose ``paytoUri`` + can no longer be parsed are silently skipped. .. ts:def:: ListBankAccountsRequest diff --git a/core/wallet-core/database/import-db.rst b/core/wallet-core/database/import-db.rst @@ -32,6 +32,9 @@ ``progressToken`` is set, progress is reported via notifications and the import can be cancelled with :ts:op:`cancelProgressToken`; a cancelled import fails with ``WALLET_CORE_REQUEST_CANCELLED``. + After a successful import, all in-memory caches (exchange, + denomination and refresh-cost data) are cleared, and the imported + records are used to recompute the derived transaction view. .. ts:def:: ImportDbRequest diff --git a/core/wallet-core/database/migrate-database.rst b/core/wallet-core/database/migrate-database.rst @@ -29,7 +29,10 @@ When the wallet already uses the native SQLite schema, the request succeeds with ``migrated`` set to false. The optional ``progressToken`` correlates progress notifications and allows - cancellation via :ts:op:`cancelProgressToken`. + cancellation via :ts:op:`cancelProgressToken`. If the migration + itself fails, the request fails with ``WALLET_DB_UNAVAILABLE`` and + the existing (IndexedDB) database remains active; a cancelled + migration fails with ``WALLET_CORE_REQUEST_CANCELLED``. .. ts:def:: MigrateDatabaseRequest diff --git a/core/wallet-core/diagnostics/get-diagnostics.rst b/core/wallet-core/diagnostics/get-diagnostics.rst @@ -26,7 +26,8 @@ exchanges, coins, bank accounts and the newest transactions (at most ``transactionLimit`` of them). The ``WALLET_CORE_API_BAD_REQUEST`` error is raised when - ``transactionLimit`` is not a non-negative safe integer. + ``transactionLimit`` is not a non-negative safe integer smaller + than ``Number.MAX_SAFE_INTEGER``. .. ts:def:: GetDiagnosticsRequest diff --git a/core/wallet-core/exchanges/delete-exchange.rst b/core/wallet-core/exchanges/delete-exchange.rst @@ -17,7 +17,7 @@ **Expected errors:** The caller can handle the following errors inline: - ``WALLET_EXCHANGE_ENTRY_NOT_FOUND``, ``WALLET_EXCHANGE_ENTRY_USED``. + ``WALLET_EXCHANGE_ENTRY_USED``. **Details:** @@ -25,7 +25,8 @@ exchange still has associated resources (see :ts:op:`getExchangeResources`), unless ``purge`` is set. Some transactions related to the exchange (payments, peer payments and - refreshes) are kept even when purging. + refreshes) are kept even when purging. Deleting an exchange that + is not known to the wallet succeeds silently. .. ts:def:: DeleteExchangeRequest diff --git a/core/wallet-core/exchanges/update-exchange-entry.rst b/core/wallet-core/exchanges/update-exchange-entry.rst @@ -22,18 +22,18 @@ network and notifications are emitted; completion is reported asynchronously. - **Expected errors:** - - The caller can handle the following errors inline: - ``WALLET_EXCHANGE_ENTRY_NOT_FOUND``, - ``WALLET_EXCHANGE_ENTRY_UPDATE_CONFLICT``, - ``WALLET_EXCHANGE_UNAVAILABLE``. - **Details:** Setting ``force`` starts the update even when the entry was recently updated or the exchange is currently marked unavailable. + If no exchange entry exists for ``exchangeBaseUrl`` yet, a new + entry is created and the update proceeds; the request does not + fail for unknown base URLs. Failures of the update itself (for + example the exchange being unreachable) are not reported as + request errors but asynchronously: they surface via notifications + and the ``lastUpdateErrorInfo`` of :ts:op:`listExchanges`. + .. ts:def:: UpdateExchangeEntryRequest interface UpdateExchangeEntryRequest { diff --git a/core/wallet-core/hints/dismiss-wallet-warning.rst b/core/wallet-core/hints/dismiss-wallet-warning.rst @@ -13,8 +13,9 @@ **Side effects:** - Persistently marks a completed renewal notice as dismissed; a - ``balance-change`` notification is emitted. + Persistently marks a completed renewal notice as dismissed; when a + notice was actually dismissed, a ``balance-change`` notification is + emitted. **Details:** diff --git a/core/wallet-core/hints/hint-network-availability.rst b/core/wallet-core/hints/hint-network-availability.rst @@ -21,7 +21,8 @@ running background tasks: tasks that are blocked waiting for the network resume when connectivity is back, and tasks notice the outage and wait when it goes away. Reporting the already known state has no - effect. + effect. Network availability defaults to available, so clients that + never send this hint do not block background network activity. .. ts:def:: HintNetworkAvailabilityRequest diff --git a/core/wallet-core/hints/hint-power-state.rst b/core/wallet-core/hints/hint-power-state.rst @@ -24,6 +24,12 @@ power. The ``unknown`` power source never qualifies. When the power source changes, wallet-core restarts all running background tasks. + The reported power source is a transient observation: it is discarded + when wallet-core restarts, and if no fresh hint arrives within 60 + seconds the effective power source falls back to ``unknown``. Clients + should therefore re-report the power state periodically and after any + change. + .. ts:def:: HintPowerStateRequest interface HintPowerStateRequest { diff --git a/core/wallet-core/init/get-version.rst b/core/wallet-core/init/get-version.rst @@ -12,6 +12,12 @@ On success, the result is a `WalletCoreVersion` object. + **Details:** + + The wallet must have been initialized first (see + :ts:op:`initWallet`); before initialization this operation fails + with ``WALLET_CORE_NOT_AVAILABLE``. + .. ts:def:: WalletCoreVersion interface WalletCoreVersion { diff --git a/core/wallet-core/init/init-wallet.rst b/core/wallet-core/init/init-wallet.rst @@ -14,17 +14,27 @@ **Side effects:** - Initializes the wallet: opens the wallet database (migrating it - to the native sqlite schema when ``config.features.migrateNativeDb`` - is set), installs the built-in default exchanges (unless - ``config.testing.skipDefaults`` is set) and starts the background - task loop (unless ``config.lazyTaskLoop`` is set). + 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 :ts:op:`setWalletRunConfig`. + like :ts:op:`setWalletRunConfig`. Fields not present in + ``config`` are reset to their defaults. .. ts:def:: InitRequest diff --git a/core/wallet-core/mailbox/delete-mailbox-message.rst b/core/wallet-core/mailbox/delete-mailbox-message.rst @@ -20,7 +20,8 @@ The message is identified by the ``originMailboxBaseUrl`` and ``talerUri`` fields of the given message; the ``downloadedAt`` field is ignored. Deleting a message that does not exist is not - an error. + an error; the ``mailbox-message-deleted`` notification is emitted + regardless. .. ts:def:: DeleteMailboxMessageRequest diff --git a/core/wallet-core/mailbox/initialize-mailbox.rst b/core/wallet-core/mailbox/initialize-mailbox.rst @@ -21,7 +21,8 @@ **Expected errors:** The caller can handle the following errors inline: - ``WALLET_MAILBOX_UNAVAILABLE``, ``GENERIC_FORBIDDEN``. + ``WALLET_MAILBOX_UNAVAILABLE``, ``GENERIC_FORBIDDEN``, + ``WALLET_RECEIVED_MALFORMED_RESPONSE``. **Details:** @@ -32,7 +33,8 @@ succeeds and the returned configuration has ``payUri`` set, which the client can use to pay for the registration. ``GENERIC_FORBIDDEN`` indicates that the mailbox service refused - the registration. + the registration. ``WALLET_RECEIVED_MALFORMED_RESPONSE`` indicates + that the service asked for payment but did not say how to pay. .. ts:def:: MailboxConfiguration diff --git a/core/wallet-core/mailbox/refresh-mailbox.rst b/core/wallet-core/mailbox/refresh-mailbox.rst @@ -25,13 +25,18 @@ **Expected errors:** The caller can handle the following errors inline: - ``WALLET_MAILBOX_UNAVAILABLE``. + ``WALLET_MAILBOX_UNAVAILABLE``, ``WALLET_RECEIVED_MALFORMED_RESPONSE``. **Details:** - Each downloaded message is stored like in - :ts:op:`addMailboxMessage`. Messages that cannot be decrypted are - skipped. At most 100 batches are fetched in one call. + The configuration of the mailbox service (message size and response + limit) is fetched before the first batch. Each downloaded message + is stored like in :ts:op:`addMailboxMessage`. Messages that cannot + be decrypted are skipped. At most 100 batches are fetched in one + call. ``WALLET_RECEIVED_MALFORMED_RESPONSE`` indicates that the + mailbox service returned an invalid response (invalid response + limit, or a message list whose size is not a multiple of the + advertised message size). .. ts:def:: MailboxMessageRecordsResponse diff --git a/core/wallet-core/p2p/check-peer-push-debit-v2.rst b/core/wallet-core/p2p/check-peer-push-debit-v2.rst @@ -24,8 +24,11 @@ **Expected errors:** The caller can handle the following errors inline: - ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE``, - ``WALLET_NO_SUITABLE_EXCHANGE``, ``WALLET_CORE_API_BAD_REQUEST``. + ``WALLET_CORE_API_BAD_REQUEST``. + + An insufficient balance (including the case where no exchange can + serve the payment) is not reported as an error but via the typed + ``"insufficient-balance"`` result. .. ts:def:: CheckPeerPushDebitResponse diff --git a/core/wallet-core/p2p/check-peer-push-debit.rst b/core/wallet-core/p2p/check-peer-push-debit.rst @@ -25,8 +25,9 @@ **Expected errors:** The caller can handle the following errors inline: - ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE``, - ``WALLET_NO_SUITABLE_EXCHANGE``, ``WALLET_CORE_API_BAD_REQUEST``. + ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE`` (also reported + when no exchange can serve the payment), + ``WALLET_CORE_API_BAD_REQUEST``. .. ts:def:: CheckPeerPushDebitRequest @@ -63,8 +64,9 @@ // the coin. maxExpirationDate: TalerProtocolTimestamp; - // Default expiration, as given by the exchange - // (or 1 week if the exchange does not specify it). + // Default expiration: the default given by the exchange + // (or 1 week if the exchange does not specify it), capped so + // that the purse does not outlive the coins' maxExpirationDate. defaultExpiration: TalerProtocolDuration; // Opaque description of the values reviewed by the caller. diff --git a/core/wallet-core/p2p/get-max-peer-push-debit-amount.rst b/core/wallet-core/p2p/get-max-peer-push-debit-amount.rst @@ -30,6 +30,8 @@ currency: string; // Preferred exchange to use for the p2p payment. + // Currently ignored by wallet-core; use ``restrictScope`` + // to constrain the exchanges that are considered. exchangeBaseUrl?: string; restrictScope?: ScopeInfo; diff --git a/core/wallet-core/p2p/initiate-peer-push-debit.rst b/core/wallet-core/p2p/initiate-peer-push-debit.rst @@ -20,7 +20,8 @@ The caller can handle the following errors inline: ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE``, - ``WALLET_NO_SUITABLE_EXCHANGE``, ``WALLET_CORE_API_BAD_REQUEST``. + ``WALLET_PEER_PUSH_PAYMENT_QUOTE_CHANGED``, + ``WALLET_CORE_API_BAD_REQUEST``. **Details:** diff --git a/core/wallet-core/payments/get-choices-for-payment.rst b/core/wallet-core/payments/get-choices-for-payment.rst @@ -21,9 +21,9 @@ **Side effects:** - This operation is normally a pure read, but it may refresh outdated - exchange key material over the network and write denomination - verification results to the wallet database. + None; this operation is a pure read. The payability of each choice + is evaluated against the coin, exchange and token information + already stored in the wallet database, without any network access. **Expected errors:** diff --git a/core/wallet-core/payments/prepare-pay-for-uri-v2.rst b/core/wallet-core/payments/prepare-pay-for-uri-v2.rst @@ -18,17 +18,25 @@ **Side effects:** - Fetches the order and contract terms from the merchant over the - network, claims the order, and creates a payment transaction in - dialog state. + The operation itself is deliberately local-only: it creates (or + reuses) the payment transaction record in the wallet database and + wakes the transaction's background task. Claiming the order and + downloading the contract terms from the merchant happen + asynchronously as part of the transaction's processing; the + transaction moves to dialog state once the contract terms have been + downloaded. **Expected errors:** The caller can handle the following errors inline: - ``WALLET_TALER_URI_MALFORMED``, ``WALLET_MERCHANT_ORDER_NOT_FOUND``, + ``WALLET_INVALID_TALER_PAY_URI``. + + Errors from claiming the order and downloading the contract terms + (such as ``WALLET_MERCHANT_ORDER_NOT_FOUND``, ``WALLET_ORDER_ALREADY_CLAIMED``, ``WALLET_ORDER_ALREADY_PAID``, - ``WALLET_CONTRACT_TERMS_MALFORMED``, - ``WALLET_CONTRACT_TERMS_UNSUPPORTED``. + ``WALLET_CONTRACT_TERMS_MALFORMED`` or + ``WALLET_CONTRACT_TERMS_UNSUPPORTED``) do not fail this operation; + they are reported as the last error of the payment transaction. .. ts:def:: PreparePayRequest diff --git a/core/wallet-core/testing/run-integration-test.rst b/core/wallet-core/testing/run-integration-test.rst @@ -1,8 +1,12 @@ .. ts:op:: runIntegrationTest Run a simple integration test on a test deployment of the exchange - and merchant: withdraw ``amountToWithdraw`` via the corebank API and - then spend ``amountToSpend`` at the merchant. + and merchant: withdraw ``amountToWithdraw`` via the corebank API, + spend ``amountToSpend`` at the merchant, and then exercise a refund: + withdraw a second, fixed amount (``18`` in the currency of + ``amountToSpend``), pay ``7``, refund ``6`` of it and pay another + ``3``. The operation waits for all involved transactions (including + refreshes) to reach a final state before returning. **Request:** @@ -14,7 +18,7 @@ **Side effects:** - Performs a real withdrawal and a real payment at the test + Performs real withdrawals, payments and a refund at the test deployment over the network. .. ts:def:: IntegrationTestArgs diff --git a/core/wallet-core/testing/set-coin-suspended.rst b/core/wallet-core/testing/set-coin-suspended.rst @@ -16,6 +16,14 @@ Marks the coin as (un-)suspended; suspended coins are excluded from payments. + **Details:** + + Only fresh coins can be suspended, and only suspended coins can be + un-suspended; requesting any other status transition is a no-op. + An unknown ``coinPub`` is silently ignored (a warning is logged). + Suspension updates the coin availability counters of the + denomination accordingly. + .. ts:def:: SetCoinSuspendedRequest interface SetCoinSuspendedRequest { diff --git a/core/wallet-core/testing/testing-plan-migrate-exchange-base-url.rst b/core/wallet-core/testing/testing-plan-migrate-exchange-base-url.rst @@ -1,8 +1,11 @@ .. ts:op:: testingPlanMigrateExchangeBaseUrl Enable migration from an old exchange base URL to a new exchange base - URL. The actual migration is only applied once the exchange returns - the new base URL. + URL. The plan is only kept in memory (not persisted). The actual + migration is applied on the next exchange update when either the + exchange advertises the new base URL, or downloading keys from the + old base URL fails while the new base URL is reachable and + advertises itself as its own base URL. **Request:** diff --git a/core/wallet-core/transactions/retry-transaction.rst b/core/wallet-core/transactions/retry-transaction.rst @@ -19,7 +19,8 @@ **Expected errors:** The caller can handle the following errors inline: - ``WALLET_TRANSACTION_NOT_FOUND``. + ``WALLET_TRANSACTION_NOT_FOUND``, + ``WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED``. **Details:** diff --git a/core/wallet-core/transactions/wait-transaction-state.rst b/core/wallet-core/transactions/wait-transaction-state.rst @@ -39,12 +39,17 @@ until the ``timeout`` expires; the wait then fails with ``GENERIC_TIMEOUT``. + If no transaction with the given ``transactionId`` exists, the + wait fails with ``WALLET_TRANSACTION_NOT_FOUND`` instead of + waiting. + When ``progressToken`` is set, the wait reports request progress notifications (including recorded transaction errors with their retry counter and remaining retry delay) and can be cancelled with :ts:op:`cancelProgressToken` or nudged with - :ts:op:`retryProgressTokenNow`. Cancellation stops only the - wait, not the transaction. + :ts:op:`retryProgressTokenNow`. Cancellation fails the wait + with ``WALLET_CORE_REQUEST_CANCELLED``; it stops only the wait, + not the transaction. .. ts:def:: WaitTransactionStateRequest diff --git a/core/wallet-core/validation/convert-iban-payto-to-account-field.rst b/core/wallet-core/validation/convert-iban-payto-to-account-field.rst @@ -18,7 +18,8 @@ Hungarian IBANs are converted to the domestic BBAN form (a developer experiment enables the same conversion for Swiss - IBANs); all other IBANs are returned unchanged. + IBANs); all other IBANs are returned unchanged. An error is + thrown when ``paytoUri`` is not a valid payto URI. .. ts:def:: ConvertIbanPaytoToAccountFieldRequest diff --git a/core/wallet-core/validation/get-banking-choices-for-payto.rst b/core/wallet-core/validation/get-banking-choices-for-payto.rst @@ -19,7 +19,8 @@ Currently, choices are only returned for the ``KUDOS`` demonstration currency (links to the demonstrator bank's website and app); the list is empty when the payto URI carries - no amount or no choice is known for the currency. + no amount or no choice is known for the currency. An error is + thrown when ``paytoUri`` is not a valid payto URI. .. ts:def:: GetBankingChoicesForPaytoRequest diff --git a/core/wallet-core/withdrawals/accept-bank-integrated-withdrawal.rst b/core/wallet-core/withdrawals/accept-bank-integrated-withdrawal.rst @@ -7,10 +7,10 @@ Accept a bank-integrated withdrawal in one step, equivalent to preparing the withdrawal and then confirming it with the given - exchange and amount. Before returning, the wallet tries to register - the reserve with the bank. Thus, after this call returns, the - withdrawal operation can be confirmed with the bank via - ``confirmTransferUrl``. + exchange and amount. A background task then registers the reserve + with the bank and withdraws the coins; once the bank has registered + the reserve, the user authorizes the wire transfer in their banking + application via the returned ``confirmTransferUrl``. **Request:** diff --git a/core/wallet-core/withdrawals/prepare-bank-integrated-withdrawal.rst b/core/wallet-core/withdrawals/prepare-bank-integrated-withdrawal.rst @@ -39,7 +39,8 @@ again with the same ``talerWithdrawUri`` returns the existing withdrawal transaction instead of creating a new one. If the bank reports the withdrawal operation as already selected, confirmed or - aborted and the wallet has no transaction for it, the request fails. + aborted and the wallet has no transaction for it, the request fails + with ``WALLET_WITHDRAWAL_OPERATION_ABORTED_BY_BANK``. .. ts:def:: PrepareBankIntegratedWithdrawalRequest