commit 0539d6bbcc9c271c7d6bece426677e07ba4ae954
parent d549dbba535dda3538fd08149111da956ff0c04e
Author: Iván Ávalos <avalos@disroot.org>
Date: Fri, 3 Oct 2025 13:03:15 +0200
update wallet-core API docs
Diffstat:
| M | wallet/wallet-core.md | | | 450 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------- |
1 file changed, 335 insertions(+), 115 deletions(-)
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
@@ -8,6 +8,10 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [SetWalletRunConfigOp](#setwalletrunconfigop)
* [GetVersionOp](#getversionop)
* [HintNetworkAvailabilityOp](#hintnetworkavailabilityop)
+### Donau
+* [SetDonauOp](#setdonauop)
+* [GetDonauOp](#getdonauop)
+* [GetDonauStatementsOp](#getdonaustatementsop)
### Basic Wallet Information
* [GetBalancesOp](#getbalancesop)
* [GetBalancesDetailOp](#getbalancesdetailop)
@@ -40,10 +44,12 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [SharePaymentOp](#sharepaymentop)
* [CheckPayForTemplateOp](#checkpayfortemplateop)
* [PreparePayForTemplateOp](#preparepayfortemplateop)
-* [GetContractTermsDetailsOp](#getcontracttermsdetailsop)
* [ConfirmPayOp](#confirmpayop)
* [StartRefundQueryForUriOp](#startrefundqueryforuriop)
* [StartRefundQueryOp](#startrefundqueryop)
+### Token family management
+* [ListDiscountsOp](#listdiscountsop)
+* [DeleteDiscountOp](#deletediscountop)
### Global Currency management
* [ListGlobalCurrencyAuditorsOp](#listglobalcurrencyauditorsop)
* [ListGlobalCurrencyExchangesOp](#listglobalcurrencyexchangesop)
@@ -52,6 +58,7 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [RemoveGlobalCurrencyExchangeOp](#removeglobalcurrencyexchangeop)
* [RemoveGlobalCurrencyAuditorOp](#removeglobalcurrencyauditorop)
### Exchange Management
+* [CompleteExchangeBaseUrlOp](#completeexchangebaseurlop)
* [ListExchangesOp](#listexchangesop)
* [StartExchangeWalletKycOp](#startexchangewalletkycop)
* [TestingWaitExchangeWalletKycOp](#testingwaitexchangewalletkycop)
@@ -77,7 +84,6 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [GenerateDepositGroupTxIdOp](#generatedepositgrouptxidop)
* [CreateDepositGroupOp](#createdepositgroupop)
* [CheckDepositOp](#checkdepositop)
-* [PrepareDepositOp](#preparedepositop)
### Backups
* [ExportBackupRecoveryOp](#exportbackuprecoveryop)
* [ImportBackupRecoveryOp](#importbackuprecoveryop)
@@ -133,6 +139,7 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n
* [TestingGetReserveHistoryOp](#testinggetreservehistoryop)
* [TestingResetAllRetriesOp](#testingresetallretriesop)
* [TestingGetDenomStatsOp](#testinggetdenomstatsop)
+* [TestingRunFixupOp](#testingrunfixupop)
* [SetCoinSuspendedOp](#setcoinsuspendedop)
* [ForceRefreshOp](#forcerefreshop)
## Operation Reference
@@ -223,6 +230,86 @@ export interface HintNetworkAvailabilityRequest {
```
+### SetDonauOp
+```typescript
+/**
+ * Set the donation authority for this wallet.
+ */
+export type SetDonauOp = {
+ op: WalletApiOperation.SetDonau;
+ request: SetDonauRequest;
+ response: EmptyObject;
+};
+// SetDonau = "setDonau"
+
+```
+```typescript
+export interface SetDonauRequest {
+ donauBaseUrl: string;
+ taxPayerId: string;
+}
+
+```
+
+### GetDonauOp
+```typescript
+/**
+ * Get the currently configured donation authority for this
+ * wallet.
+ */
+export type GetDonauOp = {
+ op: WalletApiOperation.GetDonau;
+ request: EmptyObject;
+ response: GetDonauResponse;
+};
+// GetDonau = "getDonau"
+
+```
+```typescript
+export interface GetDonauResponse {
+ currentDonauInfo:
+ | {
+ donauBaseUrl: string;
+ taxPayerId: string;
+ }
+ | undefined;
+}
+
+```
+
+### GetDonauStatementsOp
+```typescript
+/**
+ * Get a list of donation statements
+ * for this wallet.
+ * Both donation statements for the currently configured
+ * donation authority as well as past configurations (if they exist)
+ * are returned.
+ */
+export type GetDonauStatementsOp = {
+ op: WalletApiOperation.GetDonauStatements;
+ request: EmptyObject;
+ response: GetDonauStatementsResponse;
+};
+// GetDonauStatements = "getDonauStatements"
+
+```
+```typescript
+export interface GetDonauStatementsResponse {
+ statements: DonauStatementItem[];
+}
+
+```
+```typescript
+export interface DonauStatementItem {
+ total: AmountString;
+ uri: string;
+ donationStatementSig: EddsaSignatureString;
+ donauPub: EddsaPublicKeyString;
+}
+
+```
+
### GetBalancesOp
```typescript
/**
@@ -1105,7 +1192,7 @@ export type GetChoicesForPaymentResult = {
* Data extracted from the contract terms that
* is relevant for payment processing in the wallet.
*/
- contractData: WalletContractData;
+ contractTerms: MerchantContractTerms;
};
```
@@ -1281,23 +1368,6 @@ export type TemplateParams = {
```
-### GetContractTermsDetailsOp
-```typescript
-export type GetContractTermsDetailsOp = {
- op: WalletApiOperation.GetContractTermsDetails;
- request: GetContractTermsDetailsRequest;
- response: WalletContractData;
-};
-// GetContractTermsDetails = "getContractTermsDetails"
-
-```
-```typescript
-export interface GetContractTermsDetailsRequest {
- transactionId: string;
-}
-
-```
-
### ConfirmPayOp
```typescript
/**
@@ -1315,6 +1385,7 @@ export type ConfirmPayOp = {
```typescript
export interface ConfirmPayRequest {
transactionId: TransactionIdStr;
+ useDonau?: boolean;
sessionId?: string;
forcedCoinSel?: ForcedCoinSel;
/**
@@ -1401,6 +1472,101 @@ export interface StartRefundQueryRequest {
```
+### ListDiscountsOp
+```typescript
+/**
+ * List discount tokens stored in the wallet. Listed tokens
+ * will be grouped by expiration date (@e validityEnd)
+ */
+export type ListDiscountsOp = {
+ op: WalletApiOperation.ListDiscounts;
+ request: ListDiscountsRequest;
+ response: ListDiscountsResponse;
+};
+// ListDiscounts = "listDiscounts"
+
+```
+```typescript
+export interface ListDiscountsRequest {
+ /**
+ * Filter by hash of token issue public key.
+ */
+ tokenIssuePubHash?: string;
+ /**
+ * Filter by merchant base URL.
+ */
+ merchantBaseUrl?: string;
+}
+
+```
+```typescript
+export interface ListDiscountsResponse {
+ discounts: DiscountListDetail[];
+}
+
+```
+```typescript
+export interface DiscountListDetail {
+ /**
+ * Hash of token family info.
+ */
+ tokenFamilyHash: string;
+ /**
+ * Hash of token issue public key.
+ */
+ tokenIssuePubHash: string;
+ /**
+ * URL of the merchant issuing the token.
+ */
+ merchantBaseUrl: string;
+ /**
+ * Human-readable name for the token family.
+ */
+ name: string;
+ /**
+ * Human-readable description for the token family.
+ */
+ description: string;
+ /**
+ * Optional map from IETF BCP 47 language tags to localized descriptions.
+ */
+ descriptionI18n: any | undefined;
+ /**
+ * Start time of the token's validity period.
+ */
+ validityStart: Timestamp;
+ /**
+ * End time of the token's validity period.
+ */
+ validityEnd: Timestamp;
+ /**
+ * Number of tokens available to use.
+ */
+ tokensAvailable: number;
+}
+
+```
+
+### DeleteDiscountOp
+```typescript
+export type DeleteDiscountOp = {
+ op: WalletApiOperation.DeleteDiscount;
+ request: DeleteDiscountRequest;
+ response: EmptyObject;
+};
+// DeleteDiscount = "deleteDiscount"
+
+```
+```typescript
+export interface DeleteDiscountRequest {
+ /**
+ * Hash of token family info.
+ */
+ tokenFamilyHash: string;
+}
+
+```
+
### ListGlobalCurrencyAuditorsOp
```typescript
export type ListGlobalCurrencyAuditorsOp = {
@@ -1519,6 +1685,49 @@ export interface RemoveGlobalCurrencyAuditorRequest {
```
+### CompleteExchangeBaseUrlOp
+```typescript
+/**
+ * Force a refresh on coins where it would not
+ * be necessary.
+ */
+export type CompleteExchangeBaseUrlOp = {
+ op: WalletApiOperation.CompleteExchangeBaseUrl;
+ request: CompleteBaseUrlRequest;
+ response: CompleteBaseUrlResult;
+};
+// CompleteExchangeBaseUrl = "completeExchangeBaseUrl"
+
+```
+```typescript
+export interface CompleteBaseUrlRequest {
+ url: string;
+}
+
+```
+```typescript
+export type CompleteBaseUrlResult =
+ | {
+ /**
+ * ok: completion is a proper exchange
+ */
+ status: "ok";
+ /** Completed exchange base URL, if completion was possible */
+ completion: string;
+ }
+ | {
+ /**
+ * bad-syntax: url is so badly malformed, it can't be completed
+ * bad-network: syntax okay, but exchange can't be reached
+ * bad-exchange: syntax and network okay, but not talking to an exchange
+ */
+ status: "bad-syntax" | "bad-network" | "bad-exchange";
+ /** Error details in case status is not "ok" */
+ error: TalerErrorDetail;
+ };
+
+```
+
### ListExchangesOp
```typescript
/**
@@ -1671,19 +1880,27 @@ export type AddExchangeOp = {
```typescript
export interface AddExchangeRequest {
/**
- * @deprecated Use {@link uri} instead
- */
- exchangeBaseUrl?: string;
- /**
* Either an http(s) exchange base URL or
* a taler://add-exchange/ URI.
*/
uri?: string;
+ /**
+ * Only ephemerally add the exchange.
+ */
ephemeral?: boolean;
/**
+ * Allow passing incomplete URLs. The wallet will try to complete
+ * the URL and throw an error if completion is not possible.
+ */
+ allowCompletion?: boolean;
+ /**
* @deprecated use a separate API call to start a forced exchange update instead
*/
forceUpdate?: boolean;
+ /**
+ * @deprecated Use {@link uri} instead
+ */
+ exchangeBaseUrl?: string;
}
```
@@ -2316,18 +2533,58 @@ export type CheckDepositOp = {
// CheckDeposit = "checkDeposit"
```
+```typescript
+export interface CheckDepositRequest {
+ /**
+ * Payto URI to identify the (bank) account that the exchange will wire
+ * the money to.
+ */
+ depositPaytoUri: string;
+ /**
+ * Amount that should be deposited.
+ *
+ * Raw amount, fees will be added on top.
+ */
+ amount: AmountString;
+ /**
+ * Restrict the deposit to a certain scope.
+ */
+ restrictScope?: ScopeInfo;
+ /**
+ * ID provided by the client to cancel the request.
+ *
+ * If the same request is made again with the same clientCancellationId,
+ * all previous requests are cancelled.
+ *
+ * The cancelled request will receive an error response with
+ * an error code that indicates the cancellation.
+ *
+ * The cancellation is best-effort, responses might still arrive.
+ */
+ clientCancellationId?: string;
+}
-### PrepareDepositOp
+```
```typescript
-/**
- * @deprecated use CheckDepositOp instead
- */
-export type PrepareDepositOp = {
- op: WalletApiOperation.PrepareDeposit;
- request: CheckDepositRequest;
- response: CheckDepositResponse;
-};
-// PrepareDeposit = "prepareDeposit"
+export interface CheckDepositResponse {
+ totalDepositCost: AmountString;
+ effectiveDepositAmount: AmountString;
+ fees: DepositGroupFees;
+ kycSoftLimit?: AmountString;
+ kycHardLimit?: AmountString;
+ /**
+ * Base URL of exchanges that would likely require soft KYC.
+ */
+ kycExchanges?: string[];
+}
+
+```
+```typescript
+export interface DepositGroupFees {
+ coin: AmountString;
+ wire: AmountString;
+ refresh: AmountString;
+}
```
@@ -3712,7 +3969,7 @@ export interface TestingWaitTransactionRequest {
* an error instead.
*/
timeout?: DurationUnitSpec;
- txState: TransactionStatePattern | TransactionStatePattern[];
+ txState: TransactionStatePattern | TransactionStatePattern[] | number;
}
```
@@ -3817,6 +4074,23 @@ export interface TestingGetDenomStatsResponse {
```
+### TestingRunFixupOp
+```typescript
+export type TestingRunFixupOp = {
+ op: WalletApiOperation.TestingRunFixup;
+ request: RunFixupRequest;
+ response: EmptyObject;
+};
+// TestingRunFixup = "testingRunFixup"
+
+```
+```typescript
+export interface RunFixupRequest {
+ id: string;
+}
+
+```
+
### SetCoinSuspendedOp
```typescript
/**
@@ -3908,6 +4182,15 @@ export interface WalletRunConfig {
*/
features: {
allowHttp: boolean;
+ /**
+ * If set to true, enable V1 contracts. Otherwise, emulate v0 contracts
+ * to wallet-core clients.
+ *
+ * Will become enabled by default in the future.
+ *
+ * Added 2025-08-19.
+ */
+ enableV1Contracts: boolean;
};
/**
* Start processing tasks only when explicitly required, even after
@@ -3967,6 +4250,13 @@ export interface WalletCoreVersion {
export type EmptyObject = Record<string, never>;
```
```typescript
+export type AmountString =
+ | (string & {
+ [__amount_str]: true;
+ })
+ | LitAmountString;
+```
+```typescript
export type ScopeInfo = ScopeInfoGlobal | ScopeInfoExchange | ScopeInfoAuditor;
```
```typescript
@@ -3998,13 +4288,6 @@ export type ScopeInfoAuditor = {
};
```
```typescript
-export type AmountString =
- | (string & {
- [__amount_str]: true;
- })
- | LitAmountString;
-```
-```typescript
export type AccountRestriction =
| RegexAccountRestriction
| DenyAllAccountRestriction;
@@ -4082,6 +4365,10 @@ export interface TransactionCommon {
*/
txState: TransactionState;
/**
+ * Wallet-internal state ID, only used for debugging and testing.
+ */
+ stId: number;
+ /**
* Possible transitions based on the current state.
*/
txActions: TransactionAction[];
@@ -4392,6 +4679,7 @@ export interface CurrencySpecification {
alt_unit_names: {
[log10: string]: string;
};
+ common_amounts?: AmountString[];
}
```
```typescript
@@ -4851,6 +5139,7 @@ export interface TransactionPeerPullCredit extends TransactionCommon {
export interface PeerInfoShort {
expiration: TalerProtocolTimestamp | undefined;
summary: string | undefined;
+ iconId: string | undefined;
}
```
```typescript
@@ -5254,7 +5543,7 @@ export declare enum InsufficientBalanceHint {
export interface PreparePayResultAlreadyConfirmed {
status: PreparePayResultType.AlreadyConfirmed;
transactionId: TransactionIdStr;
- contractTerms: MerchantContractTermsV0;
+ contractTerms: MerchantContractTerms;
paid: boolean;
amountRaw: AmountString;
amountEffective: AmountString | undefined;
@@ -5269,6 +5558,9 @@ export interface PreparePayResultAlreadyConfirmed {
```typescript
/**
* Payment is possible.
+ *
+ * This response is only returned for v0 contracts
+ * or when v1 are not enabled yet.
*/
export interface PreparePayResultPaymentPossible {
status: PreparePayResultType.PaymentPossible;
@@ -5314,27 +5606,6 @@ export interface ForcedCoinSel {
}
```
```typescript
-/**
- * Data extracted from the contract terms that is relevant for payment
- * processing in the wallet.
- */
-export type WalletContractData = MerchantContractTerms & {
- /**
- * Fulfillment URL, or the empty string if the order has no fulfillment URL.
- *
- * Stored as a non-nullable string as we use this field for IndexedDB indexing.
- */
- fulfillmentUrl: string;
- contractTermsHash: string;
- merchantSig: string;
- /**
- * Amounts are undefined for unfinished v1 orders.
- */
- amountRaw?: AmountString;
- amountEffective?: AmountString;
-};
-```
-```typescript
export interface WalletBankAccountInfo {
bankAccountId: string;
paytoUri: string;
@@ -5368,57 +5639,6 @@ export interface WireTypeDetails {
}
```
```typescript
-export interface CheckDepositRequest {
- /**
- * Payto URI to identify the (bank) account that the exchange will wire
- * the money to.
- */
- depositPaytoUri: string;
- /**
- * Amount that should be deposited.
- *
- * Raw amount, fees will be added on top.
- */
- amount: AmountString;
- /**
- * Restrict the deposit to a certain scope.
- */
- restrictScope?: ScopeInfo;
- /**
- * ID provided by the client to cancel the request.
- *
- * If the same request is made again with the same clientCancellationId,
- * all previous requests are cancelled.
- *
- * The cancelled request will receive an error response with
- * an error code that indicates the cancellation.
- *
- * The cancellation is best-effort, responses might still arrive.
- */
- clientCancellationId?: string;
-}
-```
-```typescript
-export interface CheckDepositResponse {
- totalDepositCost: AmountString;
- effectiveDepositAmount: AmountString;
- fees: DepositGroupFees;
- kycSoftLimit?: AmountString;
- kycHardLimit?: AmountString;
- /**
- * Base URL of exchanges that would likely require soft KYC.
- */
- kycExchanges?: string[];
-}
-```
-```typescript
-export interface DepositGroupFees {
- coin: AmountString;
- wire: AmountString;
- refresh: AmountString;
-}
-```
-```typescript
export interface BackupRecovery {
walletRootPriv: string;
providers: {
