commit 9537195690c2147d3452ade6e1bafad4ef6b82fa
parent 4a8ae5654906acf850eebc7807a0fd47575eae44
Author: Florian Dold <florian@dold.me>
Date: Thu, 12 Sep 2024 13:38:54 +0200
update wallet-core API docs
Diffstat:
| M | wallet/wallet-core.md | | | 365 | +++++++++++++++++++++++++++++++++++++++++++++---------------------------------- |
1 file changed, 207 insertions(+), 158 deletions(-)
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
@@ -4,18 +4,16 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core
### Initialization
* [InitWalletOp](#initwalletop)
* [ShutdownOp](#shutdownop)
+* [HintApplicationResumedOp](#hintapplicationresumedop)
* [SetWalletRunConfigOp](#setwalletrunconfigop)
* [GetVersionOp](#getversionop)
* [HintNetworkAvailabilityOp](#hintnetworkavailabilityop)
### Basic Wallet Information
* [GetBalancesOp](#getbalancesop)
* [GetBalancesDetailOp](#getbalancesdetailop)
-* [GetPlanForOperationOp](#getplanforoperationop)
* [ConvertDepositAmountOp](#convertdepositamountop)
* [GetMaxDepositAmountOp](#getmaxdepositamountop)
-* [ConvertPeerPushAmountOp](#convertpeerpushamountop)
-* [GetMaxPeerPushAmountOp](#getmaxpeerpushamountop)
-* [ConvertWithdrawalAmountOp](#convertwithdrawalamountop)
+* [GetMaxPeerPushDebitAmountOp](#getmaxpeerpushdebitamountop)
### Managing Transactions
* [GetTransactionsOp](#gettransactionsop)
* [ListAssociatedRefreshesOp](#listassociatedrefreshesop)
@@ -74,6 +72,7 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core
### Deposits
* [GenerateDepositGroupTxIdOp](#generatedepositgrouptxidop)
* [CreateDepositGroupOp](#createdepositgroupop)
+* [CheckDepositOp](#checkdepositop)
* [PrepareDepositOp](#preparedepositop)
### Backups
* [ExportBackupRecoveryOp](#exportbackuprecoveryop)
@@ -157,6 +156,22 @@ export type ShutdownOp = {
```
+### HintApplicationResumedOp
+```typescript
+/**
+ * Give wallet-core a kick and restart all pending tasks.
+ * Useful when the host application gets suspended and resumed,
+ * and active network requests might have stalled.
+ */
+export type HintApplicationResumedOp = {
+ op: WalletApiOperation.HintApplicationResumed;
+ request: EmptyObject;
+ response: EmptyObject;
+};
+// HintApplicationResumed = "hintApplicationResumed"
+
+```
+
### SetWalletRunConfigOp
```typescript
/**
@@ -284,11 +299,11 @@ export interface PaymentBalanceDetails {
*/
balanceAgeAcceptable: AmountJson;
/**
- * Balance of type "merchant-acceptable" (see balance.ts for definition).
+ * Balance of type "receiver-acceptable" (see balance.ts for definition).
*/
balanceReceiverAcceptable: AmountJson;
/**
- * Balance of type "merchant-depositable" (see balance.ts for definition).
+ * Balance of type "receiver-depositable" (see balance.ts for definition).
*/
balanceReceiverDepositable: AmountJson;
/**
@@ -297,7 +312,11 @@ export interface PaymentBalanceDetails {
* and wire fee configuration.
*/
balanceExchangeDepositable: AmountJson;
- maxEffectiveSpendAmount: AmountJson;
+ /**
+ * Estimated maximum amount that the wallet could pay for, under the assumption
+ * that the merchant pays absolutely no fees.
+ */
+ maxMerchantEffectiveDepositAmount: AmountJson;
}
```
@@ -323,105 +342,98 @@ export interface AmountJson {
```
-### GetPlanForOperationOp
+### ConvertDepositAmountOp
```typescript
-export type GetPlanForOperationOp = {
- op: WalletApiOperation.GetPlanForOperation;
- request: GetPlanForOperationRequest;
- response: GetPlanForOperationResponse;
+export type ConvertDepositAmountOp = {
+ op: WalletApiOperation.ConvertDepositAmount;
+ request: ConvertAmountRequest;
+ response: AmountResponse;
};
-// GetPlanForOperation = "getPlanForOperation"
-
-```
-```typescript
-export type GetPlanForOperationRequest =
- | GetPlanForWithdrawRequest
- | GetPlanForDepositRequest;
-
-```
-```typescript
-interface GetPlanForWithdrawRequest extends GetPlanForWalletInitiatedOperation {
- type: TransactionType.Withdrawal;
- exchangeUrl?: string;
-}
+// ConvertDepositAmount = "convertDepositAmount"
```
```typescript
-interface GetPlanForWalletInitiatedOperation {
- instructedAmount: AmountString;
- mode: TransactionAmountMode;
+export interface ConvertAmountRequest {
+ amount: AmountString;
+ type: TransactionAmountMode;
+ depositPaytoUri: PaytoString;
}
```
```typescript
-interface GetPlanForDepositRequest extends GetPlanForWalletInitiatedOperation {
- type: TransactionType.Deposit;
- account: string;
+/**
+ * How the amount should be interpreted in a transaction
+ * Effective = how the balance is change
+ * Raw = effective amount without fee
+ *
+ * Depending on the transaction, raw can be higher than effective
+ */
+export declare enum TransactionAmountMode {
+ Effective = "effective",
+ Raw = "raw",
}
```
```typescript
-export interface GetPlanForOperationResponse {
+export interface AmountResponse {
effectiveAmount: AmountString;
rawAmount: AmountString;
- counterPartyAmount?: AmountString;
- details: any;
}
```
-### ConvertDepositAmountOp
-```typescript
-export type ConvertDepositAmountOp = {
- op: WalletApiOperation.ConvertDepositAmount;
- request: ConvertAmountRequest;
- response: AmountResponse;
-};
-// ConvertDepositAmount = "convertDepositAmount"
-
-```
-
### GetMaxDepositAmountOp
```typescript
export type GetMaxDepositAmountOp = {
op: WalletApiOperation.GetMaxDepositAmount;
- request: GetAmountRequest;
- response: AmountResponse;
+ request: GetMaxDepositAmountRequest;
+ response: GetMaxDepositAmountResponse;
};
// GetMaxDepositAmount = "getMaxDepositAmount"
```
+```typescript
+export interface GetMaxDepositAmountRequest {
+ currency: string;
+ depositPaytoUri?: string;
+}
-### ConvertPeerPushAmountOp
+```
```typescript
-export type ConvertPeerPushAmountOp = {
- op: WalletApiOperation.ConvertPeerPushAmount;
- request: ConvertAmountRequest;
- response: AmountResponse;
-};
-// ConvertPeerPushAmount = "ConvertPeerPushAmount"
+export interface GetMaxDepositAmountResponse {
+ effectiveAmount: AmountString;
+ rawAmount: AmountString;
+}
```
-### GetMaxPeerPushAmountOp
+### GetMaxPeerPushDebitAmountOp
```typescript
-export type GetMaxPeerPushAmountOp = {
- op: WalletApiOperation.GetMaxPeerPushAmount;
- request: GetAmountRequest;
- response: AmountResponse;
+export type GetMaxPeerPushDebitAmountOp = {
+ op: WalletApiOperation.GetMaxPeerPushDebitAmount;
+ request: GetMaxPeerPushDebitAmountRequest;
+ response: GetMaxPeerPushDebitAmountResponse;
};
-// GetMaxPeerPushAmount = "getMaxPeerPushAmount"
+// GetMaxPeerPushDebitAmount = "getMaxPeerPushDebitAmount"
```
+```typescript
+export interface GetMaxPeerPushDebitAmountRequest {
+ currency: string;
+ /**
+ * Preferred exchange to use for the p2p payment.
+ */
+ exchangeBaseUrl?: string;
+ restrictScope?: ScopeInfo;
+}
-### ConvertWithdrawalAmountOp
+```
```typescript
-export type ConvertWithdrawalAmountOp = {
- op: WalletApiOperation.ConvertWithdrawalAmount;
- request: ConvertAmountRequest;
- response: AmountResponse;
-};
-// ConvertWithdrawalAmount = "convertWithdrawalAmount"
+export interface GetMaxPeerPushDebitAmountResponse {
+ effectiveAmount: AmountString;
+ rawAmount: AmountString;
+ exchangeBaseUrl?: string;
+}
```
@@ -725,6 +737,18 @@ export interface WithdrawalDetailsForAmount {
* Scope info of the currency withdrawn.
*/
scopeInfo: ScopeInfo;
+ /**
+ * KYC soft limit.
+ *
+ * Withdrawals over that amount will require KYC.
+ */
+ kycSoftLimit?: AmountString;
+ /**
+ * KYC soft limits.
+ *
+ * Withdrawals over that amount will be denied.
+ */
+ kycHardLimit?: AmountString;
}
```
@@ -1694,7 +1718,25 @@ export interface GetDepositWireTypesForCurrencyRequest {
* enter their payment information.
*/
export interface GetDepositWireTypesForCurrencyResponse {
+ /**
+ * @deprecated, use wireTypeDetails instead.
+ */
wireTypes: string[];
+ /**
+ * Details for each wire type.
+ */
+ wireTypeDetails: WireTypeDetails[];
+}
+
+```
+```typescript
+export interface WireTypeDetails {
+ paymentTargetType: string;
+ /**
+ * Allowed hostnames for the deposit payto URI.
+ * Only applicable to x-taler-bank.
+ */
+ talerBankHostnames?: string[];
}
```
@@ -1992,59 +2034,28 @@ export interface CreateDepositGroupResponse {
```
-### PrepareDepositOp
+### CheckDepositOp
```typescript
-// FIXME: Rename to checkDeposit, as it does not create a transaction, just computes fees!
-export type PrepareDepositOp = {
- op: WalletApiOperation.PrepareDeposit;
- request: PrepareDepositRequest;
- response: PrepareDepositResponse;
+export type CheckDepositOp = {
+ op: WalletApiOperation.CheckDeposit;
+ request: CheckDepositRequest;
+ response: CheckDepositResponse;
};
-// PrepareDeposit = "prepareDeposit"
+// CheckDeposit = "checkDeposit"
```
-```typescript
-export interface PrepareDepositRequest {
- /**
- * 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;
- /**
- * 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 PrepareDepositResponse {
- totalDepositCost: AmountString;
- effectiveDepositAmount: AmountString;
- fees: DepositGroupFees;
-}
-
-```
+### PrepareDepositOp
```typescript
-export interface DepositGroupFees {
- coin: AmountString;
- wire: AmountString;
- refresh: AmountString;
-}
+/**
+ * @deprecated use CheckDepositOp instead
+ */
+export type PrepareDepositOp = {
+ op: WalletApiOperation.PrepareDeposit;
+ request: CheckDepositRequest;
+ response: CheckDepositResponse;
+};
+// PrepareDeposit = "prepareDeposit"
```
@@ -2440,6 +2451,11 @@ export interface CheckPeerPushDebitRequest {
*/
amount: AmountString;
/**
+ * Restrict the scope of funds that can be spent via the given
+ * scope info.
+ */
+ restrictScope?: ScopeInfo;
+ /**
* ID provided by the client to cancel the request.
*
* If the same request is made again with the same clientCancellationId,
@@ -2489,6 +2505,11 @@ export type InitiatePeerPushDebitOp = {
```typescript
export interface InitiatePeerPushDebitRequest {
exchangeBaseUrl?: string;
+ /**
+ * Restrict the scope of funds that can be spent via the given
+ * scope info.
+ */
+ restrictScope?: ScopeInfo;
partialContractTerms: PeerContractTerms;
}
@@ -3337,7 +3358,7 @@ export type TestingWaitTransactionStateOp = {
```typescript
export interface TestingWaitTransactionRequest {
transactionId: TransactionIdStr;
- txState: TransactionState;
+ txState: TransactionState | TransactionState[];
}
```
@@ -3600,6 +3621,13 @@ export type ScopeInfoExchange = {
};
```
```typescript
+export interface Exchange {
+ url: string;
+ priority: Integer;
+ master_pub: EddsaPublicKey;
+}
+```
+```typescript
export type ScopeInfoAuditor = {
type: ScopeType.Auditor;
currency: string;
@@ -3614,37 +3642,6 @@ export type AmountString =
| LitAmountString;
```
```typescript
-/**
- * How the amount should be interpreted in a transaction
- * Effective = how the balance is change
- * Raw = effective amount without fee
- *
- * Depending on the transaction, raw can be higher than effective
- */
-export declare enum TransactionAmountMode {
- Effective = "effective",
- Raw = "raw",
-}
-```
-```typescript
-export interface ConvertAmountRequest {
- amount: AmountString;
- type: TransactionAmountMode;
- depositPaytoUri: PaytoString;
-}
-```
-```typescript
-export interface AmountResponse {
- effectiveAmount: AmountString;
- rawAmount: AmountString;
-}
-```
-```typescript
-export interface GetAmountRequest {
- currency: string;
-}
-```
-```typescript
export interface TransactionsResponse {
transactions: Transaction[];
}
@@ -3724,6 +3721,7 @@ export interface TransactionCommon {
* KYC access token. Useful for testing, not so useful for UIs.
*/
kycAccessToken?: string;
+ kycAuthTransferInfo?: KycAuthTransferInfo;
}
```
```typescript
@@ -3804,6 +3802,7 @@ export declare enum TransactionMinorState {
MergeKycRequired = "merge-kyc",
BalanceKycRequired = "balance-kyc",
BalanceKycInit = "balance-kyc-init",
+ KycAuthRequired = "kyc-auth",
Track = "track",
SubmitPayment = "submit-payment",
RebindSession = "rebind-session",
@@ -3879,6 +3878,25 @@ export interface TalerProtocolDuration {
}
```
```typescript
+export interface KycAuthTransferInfo {
+ /**
+ * Payto URI of the account that must make the transfer.
+ *
+ * The KYC auth transfer will *not* work if it originates
+ * from a different account.
+ */
+ debitPaytoUri: string;
+ /**
+ * Account public key that must be included in the subject.
+ */
+ accountPub: string;
+ /**
+ * Possible target payto URIs.
+ */
+ creditPaytoUris: string[];
+}
+```
+```typescript
export type WithdrawalDetails =
| WithdrawalDetailsForManualTransfer
| WithdrawalDetailsForTalerBankIntegrationApi;
@@ -4559,7 +4577,7 @@ export interface MerchantContractTerms {
merchant_pub: string;
delivery_date?: TalerProtocolTimestamp;
delivery_location?: Location;
- exchanges: ExchangeHandle[];
+ exchanges: Exchange[];
products?: Product[];
refund_deadline: TalerProtocolTimestamp;
wire_transfer_deadline: TalerProtocolTimestamp;
@@ -4575,16 +4593,6 @@ export interface MerchantContractTerms {
}
```
```typescript
-/**
- * Information about an exchange as stored inside a
- * merchant's contract terms.
- */
-export interface ExchangeHandle {
- url: string;
- master_pub: EddsaPublicKeyString;
-}
-```
-```typescript
export interface Product {
product_id?: string;
description: string;
@@ -4718,6 +4726,47 @@ export interface AcceptExchangeTosRequest {
}
```
```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;
+ /**
+ * 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;
+}
+```
+```typescript
+export interface DepositGroupFees {
+ coin: AmountString;
+ wire: AmountString;
+ refresh: AmountString;
+}
+```
+```typescript
export interface BackupRecovery {
walletRootPriv: string;
providers: {
