commit 989e03f40a0d6ee9a69566fb5e22e9f7f8c74343
parent f9a453f19dbabba5174007fb071131cbd1a1668f
Author: Florian Dold <florian@dold.me>
Date: Thu, 3 Sep 2026 00:10:33 +0200
update wallet-core docs
Diffstat:
| M | wallet/wallet-core.md | | | 216 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------- |
1 file changed, 173 insertions(+), 43 deletions(-)
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
@@ -63,7 +63,8 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [PreparePayForPaivanaOp](#preparepayforpaivanaop)
* [GetPaivanaCookieOp](#getpaivanacookieop)
* [GetChoicesForPaymentOp](#getchoicesforpaymentop)
-* [SharePaymentOp](#sharepaymentop)
+* [UnclaimPaymentOp](#unclaimpaymentop)
+* [ReclaimPaymentOp](#reclaimpaymentop)
* [CheckPayForTemplateOp](#checkpayfortemplateop)
* [ConfirmPayOp](#confirmpayop)
* [StartRefundQueryForUriOp](#startrefundqueryforuriop)
@@ -105,6 +106,7 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [GetExchangeEntryByUrlOp](#getexchangeentrybyurlop)
* [GetExchangeResourcesOp](#getexchangeresourcesop)
* [DeleteExchangeOp](#deleteexchangeop)
+* [PurgeExchangeLegacyKeysOp](#purgeexchangelegacykeysop)
* [GetCurrencySpecificationOp](#getcurrencyspecificationop)
### Deposits
* [CreateDepositGroupOp](#createdepositgroupop)
@@ -132,6 +134,7 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
### Database Management
* [ExportDbOp](#exportdbop)
* [ImportDbOp](#importdbop)
+* [MigrateDatabaseOp](#migratedatabaseop)
* [ClearDbOp](#cleardbop)
* [RecycleOp](#recycleop)
### Testing and Debugging
@@ -158,6 +161,7 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [TestingResetAllRetriesOp](#testingresetallretriesop)
* [TestingGetDenomStatsOp](#testinggetdenomstatsop)
* [TestingRunFixupOp](#testingrunfixupop)
+* [GetDiagnosticsOp](#getdiagnosticsop)
* [TestingGetDiagnosticsOp](#testinggetdiagnosticsop)
* [TestingGetFlightRecordsOp](#testinggetflightrecordsop)
* [TestingCorruptWithdrawalCoinSelOp](#testingcorruptwithdrawalcoinselop)
@@ -1148,7 +1152,10 @@ export type ResolveTransactionReferenceOp = {
// ResolveTransactionReference = "resolveTransactionReference"
```
```{ts:def} ResolveTransactionReferenceRequest
-/** Resolve a wallet-local transaction identifier to its stable identifier. */
+/**
+ * Resolve a stable transaction ID, a wallet-local identifier, or an external
+ * withdrawal reference containing a reserve public key to a stable ID.
+ */
export interface ResolveTransactionReferenceRequest {
transactionReference: string;
}
@@ -1734,24 +1741,40 @@ export interface ChoiceSelectionDetailInsufficientBalance {
}
```
-### SharePaymentOp
-```{ts:def} SharePaymentOp
-export type SharePaymentOp = {
- op: WalletApiOperation.SharePayment;
- request: SharePaymentRequest;
- response: SharePaymentResult;
+### UnclaimPaymentOp
+```{ts:def} UnclaimPaymentOp
+export type UnclaimPaymentOp = {
+ op: WalletApiOperation.UnclaimPayment;
+ request: UnclaimPaymentRequest;
+ response: UnclaimPaymentResult;
};
-// SharePayment = "sharePayment"
+// UnclaimPayment = "unclaimPayment"
```
-```{ts:def} SharePaymentRequest
-export interface SharePaymentRequest {
- merchantBaseUrl: string;
- orderId: string;
+```{ts:def} UnclaimPaymentRequest
+export interface UnclaimPaymentRequest {
+ transactionId: TransactionIdStr;
+ /** Enables progress correlation and cancellation through cancelProgressToken. */
+ progressToken?: string;
}
```
-```{ts:def} SharePaymentResult
-export interface SharePaymentResult {
- privatePayUri: string;
+```{ts:def} UnclaimPaymentResult
+export interface UnclaimPaymentResult {
+ talerPayUri: TalerUriString;
+}
+```
+
+### ReclaimPaymentOp
+```{ts:def} ReclaimPaymentOp
+export type ReclaimPaymentOp = {
+ op: WalletApiOperation.ReclaimPayment;
+ request: ReclaimPaymentRequest;
+ response: EmptyObject;
+};
+// ReclaimPayment = "reclaimPayment"
+```
+```{ts:def} ReclaimPaymentRequest
+export interface ReclaimPaymentRequest {
+ transactionId: TransactionIdStr;
}
```
@@ -3056,6 +3079,27 @@ export interface DeleteExchangeRequest {
}
```
+### PurgeExchangeLegacyKeysOp
+```{ts:def} PurgeExchangeLegacyKeysOp
+/** Purge every non-current key set retained for an exchange URL. */
+export type PurgeExchangeLegacyKeysOp = {
+ op: WalletApiOperation.PurgeExchangeLegacyKeys;
+ request: PurgeExchangeLegacyKeysRequest;
+ response: EmptyObject;
+};
+// PurgeExchangeLegacyKeys = "purgeExchangeLegacyKeys"
+```
+```{ts:def} PurgeExchangeLegacyKeysRequest
+export interface PurgeExchangeLegacyKeysRequest {
+ exchangeBaseUrl: string;
+ /**
+ * Current master key observed by the client before confirming the purge.
+ * The operation fails atomically if the exchange has changed keys since.
+ */
+ currentMasterPub: string;
+}
+```
+
### GetCurrencySpecificationOp
```{ts:def} GetCurrencySpecificationOp
export type GetCurrencySpecificationOp = {
@@ -3216,8 +3260,8 @@ export interface ExportDbToFileRequest {
/**
* Force the format of the export.
*
- * Currently only "json" is supported as a forced
- * export format.
+ * Supported values on filesystem-capable hosts are "json" and "sqlite3".
+ * If omitted, the host's default is "sqlite3".
*/
forceFormat?: string;
}
@@ -3234,7 +3278,7 @@ export interface ExportDbToFileResponse {
### ImportDbFromFileOp
```{ts:def} ImportDbFromFileOp
/**
- * Export the database from a file.
+ * Import the database from a JSON or SQLite file.
*
* CAUTION: Overrides existing data.
*/
@@ -3248,9 +3292,11 @@ export type ImportDbFromFileOp = {
```{ts:def} ImportDbFromFileRequest
export interface ImportDbFromFileRequest {
/**
- * Full path to the backup.
+ * Full path to a .json or .sqlite3 backup.
*/
path: string;
+ /** Correlates progress notifications and allows cancellation. */
+ progressToken?: string;
}
```
@@ -3701,6 +3747,37 @@ export type ImportDbOp = {
```{ts:def} ImportDbRequest
export interface ImportDbRequest {
dump?: any;
+ /** Correlates progress notifications and allows cancellation. */
+ progressToken?: string;
+}
+```
+
+### MigrateDatabaseOp
+```{ts:def} MigrateDatabaseOp
+/**
+ * Explicitly migrate an IndexedDB-emulation wallet to the native sqlite
+ * schema. The operation is idempotent when the wallet is already native.
+ */
+export type MigrateDatabaseOp = {
+ op: WalletApiOperation.MigrateDatabase;
+ request: MigrateDatabaseRequest;
+ response: MigrateDatabaseResponse;
+};
+// MigrateDatabase = "migrateDatabase"
+```
+```{ts:def} MigrateDatabaseRequest
+/** Start an explicit migration from IndexedDB emulation to native sqlite. */
+export interface MigrateDatabaseRequest {
+ /** Enables progress correlation and cancellation through cancelProgressToken. */
+ progressToken?: string;
+}
+```
+```{ts:def} MigrateDatabaseResponse
+export interface MigrateDatabaseResponse {
+ /** Whether this request changed the active database backend. */
+ migrated: boolean;
+ /** Database backend active after the request. */
+ databaseBackend: WalletDatabaseBackend;
}
```
@@ -4514,29 +4591,12 @@ export interface RunFixupRequest {
}
```
+### GetDiagnosticsOp
+
### TestingGetDiagnosticsOp
```{ts:def} TestingGetDiagnosticsOp
-export type TestingGetDiagnosticsOp = {
- op: WalletApiOperation.GetDiagnostics;
- request: EmptyObject;
- response: TestingGetDiagnosticsResponse;
-};
-// GetDiagnostics = "getDiagnostics"
-```
-```{ts:def} TestingGetDiagnosticsResponse
-export interface TestingGetDiagnosticsResponse {
- version: 0;
- /**
- * Statistics about the size of object stores.
- */
- idbObjectStoreCounts?: Record<string, number>;
- exchangeEntries: {
- exchangeBaseUrl: string;
- numDenoms: number;
- numWithdrawableDenoms: number;
- numCandidateWithdrawableDenoms: number;
- }[];
-}
+/** @deprecated Use {@link GetDiagnosticsOp}. */
+export type TestingGetDiagnosticsOp = GetDiagnosticsOp;
```
### TestingGetFlightRecordsOp
@@ -4684,6 +4744,7 @@ export enum WalletApiOperation {
GetExchangeResources = "getExchangeResources",
CompleteExchangeBaseUrl = "completeExchangeBaseUrl",
DeleteExchange = "deleteExchange",
+ PurgeExchangeLegacyKeys = "purgeExchangeLegacyKeys",
ConfirmExchangeKeyChange = "confirmExchangeKeyChange",
SetExchangeTosAccepted = "setExchangeTosAccepted",
SetExchangeTosForgotten = "setExchangeTosForgotten",
@@ -4702,7 +4763,8 @@ export enum WalletApiOperation {
PreparePayForTemplateV2 = "preparePayForTemplateV2",
PreparePayForPaivana = "preparePayForPaivana",
GetPaivanaCookie = "getPaivanaCookie",
- SharePayment = "sharePayment",
+ UnclaimPayment = "unclaimPayment",
+ ReclaimPayment = "reclaimPayment",
CheckPayForTemplate = "checkPayForTemplate",
StartRefundQueryForUri = "startRefundQueryForUri",
StartRefundQuery = "startRefundQuery",
@@ -4758,6 +4820,7 @@ export enum WalletApiOperation {
ExportDb = "exportDb",
ExportDbToFile = "exportDbToFile",
ImportDbFromFile = "importDbFromFile",
+ MigrateDatabase = "migrateDatabase",
ClearDb = "clearDb",
Recycle = "recycle",
// Testing
@@ -4859,6 +4922,14 @@ export interface WalletRunConfig {
* browser extension.
*/
migrateNativeDb: boolean;
+ /**
+ * Use wallet-core's native sqlite schema when initializing a new, empty
+ * database.
+ *
+ * Unlike migrateNativeDb, this never converts an existing IndexedDB
+ * wallet. Hosts without a native sqlite backend ignore the preference.
+ */
+ useNativeDb: boolean;
};
/**
* Start processing tasks only when explicitly required, even after
@@ -5090,7 +5161,7 @@ export declare enum TalerUriAction {
*/
WithdrawExchange = "withdraw-exchange",
/**
- * https://lsd.gnunet.org/lsd0006/#section-5.11
+ * https://lsd.gnunet.org/lsd0006/#section-5.12
*/
WithdrawalTransferResult = "withdrawal-transfer-result",
/**
@@ -5335,6 +5406,11 @@ export interface TransactionWithdrawal extends TransactionCommon {
export interface TransactionCommon {
transactionId: TransactionIdStr;
/**
+ * The transaction produced funds under an exchange key set that the user
+ * subsequently purged from the wallet.
+ */
+ legacy?: boolean;
+ /**
* Short identifier assigned by this wallet for local, human-facing use.
*
* It has the form `#${type}:${localIdent}`. It is intentionally not
@@ -5476,6 +5552,7 @@ export declare enum TransactionMinorState {
CheckRefund = "check-refund",
ClaimProposal = "claim-proposal",
CompletedByOtherWallet = "completed-by-other-wallet",
+ ContinuedWithOtherWallet = "continued-with-other-wallet",
CreatePurse = "create-purse",
DeletePurse = "delete-purse",
Deposit = "deposit",
@@ -5502,6 +5579,7 @@ export declare enum TransactionMinorState {
Track = "track",
Unknown = "unknown",
Withdraw = "withdraw",
+ WaitingForOtherWallet = "waiting-for-other-wallet",
Abort = "abort",
}
```
@@ -5776,6 +5854,11 @@ interface WithdrawalDetailsForTalerBankIntegrationApi {
export interface TransactionPayment extends TransactionCommon {
type: TransactionType.Payment;
/**
+ * Public payment URI shown while this wallet waits for another wallet to
+ * claim an order that it released.
+ */
+ unclaimedPayUri?: TalerUriString;
+ /**
* Additional information about the payment.
*
* Only present if the information about the
@@ -5841,6 +5924,11 @@ export interface TransactionPayment extends TransactionCommon {
choiceIndex?: number;
}
```
+```{ts:def} TalerUriString
+export type TalerUriString = string & {
+ [__action_str]: true;
+};
+```
```{ts:def} OrderShortInfo
export interface OrderShortInfo {
/**
@@ -6491,6 +6579,12 @@ export interface ExchangeListItem {
source?: ExchangeEntrySource;
masterPub: string | undefined;
/**
+ * Master public keys this exchange URL used before its current key.
+ *
+ * The array is sorted and does not include {@link masterPub}.
+ */
+ legacyMasterPubs: string[];
+ /**
* Set when the exchange changed its key set and the user has not confirmed
* the change yet. Withdrawals are refused while this is present.
*/
@@ -7216,3 +7310,39 @@ export interface WithdrawTestBalanceResult {
accountPaytoUri: string;
}
```
+```{ts:def} GetDiagnosticsOp
+export type GetDiagnosticsOp = {
+ op: WalletApiOperation.GetDiagnostics;
+ request: GetDiagnosticsRequest;
+ response: GetDiagnosticsResponse;
+};
+```
+```{ts:def} GetDiagnosticsRequest
+export interface GetDiagnosticsRequest {
+ /** Serialized output format. Defaults to JSON. */
+ format?: DiagnosticsFormat;
+ /** Maximum number of newest transactions to include. Defaults to 100. */
+ transactionLimit?: number;
+ /** Information supplied by the wallet frontend invoking wallet-core. */
+ frontendInfo?: DiagnosticsFrontendInfo;
+}
+```
+```{ts:def} DiagnosticsFormat
+export type DiagnosticsFormat = "json" | "yaml";
+```
+```{ts:def} DiagnosticsFrontendInfo
+export interface DiagnosticsFrontendInfo {
+ name: string;
+ version: string;
+ platform?: string;
+}
+```
+```{ts:def} GetDiagnosticsResponse
+/**
+ * A serialized diagnostics report in the requested format.
+ *
+ * Returning the report as a string lets clients save it without duplicating
+ * formatters or depending on the report's internal schema.
+ */
+export type GetDiagnosticsResponse = string;
+```
