[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: update wallet-core docs
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: update wallet-core docs |
|
Date: |
Tue, 20 Jun 2023 19:44:20 +0200 |
This is an automated email from the git hooks/post-receive script.
dold pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new c4290152 update wallet-core docs
c4290152 is described below
commit c4290152faffe635b0623259665bce99c95de933
Author: Florian Dold <florian@dold.me>
AuthorDate: Tue Jun 20 19:44:17 2023 +0200
update wallet-core docs
---
wallet/wallet-core.md | 367 +++++++++++++++++++++++++++++++++++++-------------
1 file changed, 276 insertions(+), 91 deletions(-)
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
index 5575a251..f860cfbd 100644
--- a/wallet/wallet-core.md
+++ b/wallet/wallet-core.md
@@ -7,14 +7,21 @@ This file is auto-generated from
[wallet-core](https://git.taler.net/wallet-core
### Basic Wallet Information
* [GetBalancesOp](#getbalancesop)
* [GetBalancesDetailOp](#getbalancesdetailop)
+* [GetPlanForOperationOp](#getplanforoperationop)
+* [ConvertDepositAmountOp](#convertdepositamountop)
+* [GetMaxDepositAmountOp](#getmaxdepositamountop)
+* [ConvertPeerPushAmountOp](#convertpeerpushamountop)
+* [GetMaxPeerPushAmountOp](#getmaxpeerpushamountop)
+* [ConvertWithdrawalAmountOp](#convertwithdrawalamountop)
### Managing Transactions
* [GetTransactionsOp](#gettransactionsop)
+* [TestingGetSampleTransactionsOp](#testinggetsampletransactionsop)
* [GetTransactionByIdOp](#gettransactionbyidop)
* [RetryPendingNowOp](#retrypendingnowop)
* [DeleteTransactionOp](#deletetransactionop)
* [RetryTransactionOp](#retrytransactionop)
* [AbortTransactionOp](#aborttransactionop)
-* [CancelAbortingTransactionOp](#cancelabortingtransactionop)
+* [FailTransactionOp](#failtransactionop)
* [SuspendTransactionOp](#suspendtransactionop)
* [ResumeTransactionOp](#resumetransactionop)
### Withdrawals
@@ -237,6 +244,122 @@ export interface AmountJson {
```
+### GetPlanForOperationOp
+```typescript
+export type GetPlanForOperationOp = {
+ op: WalletApiOperation.GetPlanForOperation;
+ request: GetPlanForOperationRequest;
+ response: GetPlanForOperationResponse;
+};
+// GetPlanForOperation = "getPlanForOperation"
+
+```
+```typescript
+export type GetPlanForOperationRequest =
+ | GetPlanForWithdrawRequest
+ | GetPlanForDepositRequest;
+
+```
+```typescript
+interface GetPlanForWithdrawRequest extends GetPlanForWalletInitiatedOperation
{
+ type: TransactionType.Withdrawal;
+ exchangeUrl?: string;
+}
+
+```
+```typescript
+interface GetPlanForWalletInitiatedOperation {
+ instructedAmount: AmountString;
+ mode: TransactionAmountMode;
+}
+
+```
+```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
+interface GetPlanForDepositRequest extends GetPlanForWalletInitiatedOperation {
+ type: TransactionType.Deposit;
+ account: string;
+}
+
+```
+```typescript
+export interface GetPlanForOperationResponse {
+ 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;
+};
+// GetMaxDepositAmount = "GetMaxDepositAmount"
+
+```
+
+### ConvertPeerPushAmountOp
+```typescript
+export type ConvertPeerPushAmountOp = {
+ op: WalletApiOperation.ConvertPeerPushAmount;
+ request: ConvertAmountRequest;
+ response: AmountResponse;
+};
+// ConvertPeerPushAmount = "ConvertPeerPushAmount"
+
+```
+
+### GetMaxPeerPushAmountOp
+```typescript
+export type GetMaxPeerPushAmountOp = {
+ op: WalletApiOperation.GetMaxPeerPushAmount;
+ request: GetAmountRequest;
+ response: AmountResponse;
+};
+// GetMaxPeerPushAmount = "GetMaxPeerPushAmount"
+
+```
+
+### ConvertWithdrawalAmountOp
+```typescript
+export type ConvertWithdrawalAmountOp = {
+ op: WalletApiOperation.ConvertWithdrawalAmount;
+ request: ConvertAmountRequest;
+ response: AmountResponse;
+};
+// ConvertWithdrawalAmount = "ConvertWithdrawalAmount"
+
+```
+
### GetTransactionsOp
```typescript
/**
@@ -267,10 +390,18 @@ export interface TransactionsRequest {
}
```
+
+### TestingGetSampleTransactionsOp
```typescript
-export interface TransactionsResponse {
- transactions: Transaction[];
-}
+/**
+ * Get sample transactions.
+ */
+export type TestingGetSampleTransactionsOp = {
+ op: WalletApiOperation.TestingGetSampleTransactions;
+ request: EmptyObject;
+ response: TransactionsResponse;
+};
+// TestingGetSampleTransactions = "testingGetSampleTransactions"
```
@@ -317,7 +448,7 @@ export type DeleteTransactionOp = {
```
```typescript
export interface DeleteTransactionRequest {
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -337,7 +468,7 @@ export type RetryTransactionOp = {
```
```typescript
export interface RetryTransactionRequest {
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -358,24 +489,24 @@ export type AbortTransactionOp = {
```
-### CancelAbortingTransactionOp
+### FailTransactionOp
```typescript
/**
* Cancel aborting a transaction
*
* For payment transactions, it puts the payment into an "aborting" state.
*/
-export type CancelAbortingTransactionOp = {
- op: WalletApiOperation.CancelAbortingTransaction;
- request: CancelAbortingTransactionRequest;
+export type FailTransactionOp = {
+ op: WalletApiOperation.FailTransaction;
+ request: FailTransactionRequest;
response: EmptyObject;
};
-// CancelAbortingTransaction = "cancelAbortingTransaction"
+// FailTransaction = "failTransaction"
```
```typescript
-export interface CancelAbortingTransactionRequest {
- transactionId: string;
+export interface FailTransactionRequest {
+ transactionId: TransactionIdStr;
}
```
@@ -444,6 +575,12 @@ export interface ManualWithdrawalDetails {
* Amount that will be added to the user's wallet balance.
*/
amountEffective: AmountString;
+ /**
+ * Number of coins that would be used for withdrawal.
+ *
+ * The UIs should warn if this number is too high (roughly at >100).
+ */
+ numCoins: number;
/**
* Ways to pay the exchange.
*/
@@ -512,7 +649,7 @@ export interface AcceptBankIntegratedWithdrawalRequest {
export interface AcceptWithdrawalResponse {
reservePub: string;
confirmTransferUrl?: string;
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -548,7 +685,7 @@ export interface AcceptManualWithdrawalResult {
* Public key of the newly created reserve.
*/
reservePub: string;
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -695,14 +832,14 @@ export type ConfirmPayResult = ConfirmPayResultDone |
ConfirmPayResultPending;
export interface ConfirmPayResultDone {
type: ConfirmPayResultType.Done;
contractTerms: MerchantContractTerms;
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
```typescript
export interface ConfirmPayResultPending {
type: ConfirmPayResultType.Pending;
- transactionId: string;
+ transactionId: TransactionIdStr;
lastError: TalerErrorDetail | undefined;
}
@@ -729,7 +866,7 @@ export interface PrepareRefundRequest {
```
```typescript
export interface StartRefundQueryForUriResponse {
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -746,7 +883,7 @@ export type StartRefundQueryOp = {
```
```typescript
export interface StartRefundQueryRequest {
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -775,8 +912,14 @@ export interface PrepareTipResult {
/**
* Unique ID for the tip assigned by the wallet.
* Typically different from the merchant-generated tip ID.
+ *
+ * @deprecated use transactionId instead
*/
walletTipId: string;
+ /**
+ * Tip transaction ID.
+ */
+ transactionId: string;
/**
* Has the tip already been accepted?
*/
@@ -829,7 +972,7 @@ export interface AcceptTipRequest {
```
```typescript
export interface AcceptTipResponse {
- transactionId: string;
+ transactionId: TransactionIdStr;
next_url?: string;
}
@@ -1169,7 +1312,7 @@ export type GenerateDepositGroupTxIdOp = {
```
```typescript
export interface TxIdResponse {
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -1207,7 +1350,7 @@ export interface CreateDepositGroupRequest {
```typescript
export interface CreateDepositGroupResponse {
depositGroupId: string;
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -1433,8 +1576,8 @@ export interface ProviderInfo {
* Last communication issue with the provider.
*/
lastError?: TalerErrorDetail;
- lastSuccessfulBackupTimestamp?: TalerProtocolTimestamp;
- lastAttemptedBackupTimestamp?: TalerProtocolTimestamp;
+ lastSuccessfulBackupTimestamp?: TalerPreciseTimestamp;
+ lastAttemptedBackupTimestamp?: TalerPreciseTimestamp;
paymentProposalIds: string[];
backupProblem?: BackupProblem;
paymentStatus: ProviderPaymentStatus;
@@ -1619,7 +1762,7 @@ export interface InitiatePeerPushDebitResponse {
mergePriv: string;
contractPriv: string;
talerUri: string;
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -1631,7 +1774,7 @@ export interface InitiatePeerPushDebitResponse {
*/
export type PreparePeerPushCreditOp = {
op: WalletApiOperation.PreparePeerPushCredit;
- request: PreparePeerPushCredit;
+ request: PreparePeerPushCreditRequest;
response: PreparePeerPushCreditResponse;
};
// PreparePeerPushCredit = "preparePeerPushCredit"
@@ -1647,6 +1790,7 @@ export interface PreparePeerPushCreditResponse {
amountRaw: AmountString;
amountEffective: AmountString;
peerPushPaymentIncomingId: string;
+ transactionId: string;
}
```
@@ -1730,7 +1874,7 @@ export interface InitiatePeerPullCreditResponse {
* that was requested.
*/
talerUri: string;
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
@@ -1764,6 +1908,7 @@ export interface PreparePeerPullDebitResponse {
amountRaw: AmountString;
amountEffective: AmountString;
peerPullPaymentIncomingId: string;
+ transactionId: string;
}
```
@@ -2118,7 +2263,7 @@ export interface PendingTaskInfoCommon {
/**
* Unique identifier for the pending task.
*/
- id: string;
+ id: TaskId;
/**
* Set to true if the operation indicates that something is really in
progress,
* as opposed to some regular scheduled operation that can be tried later.
@@ -2161,6 +2306,12 @@ export enum PendingTaskType {
PeerPullDebit = "peer-pull-debit",
}
+```
+```typescript
+export type TaskId = string & {
+ [__taskId]: true;
+};
+
```
```typescript
export interface RetryInfo {
@@ -2614,6 +2765,11 @@ export interface WalletCoreVersion {
}
```
```typescript
+export interface TransactionsResponse {
+ transactions: Transaction[];
+}
+```
+```typescript
export type Transaction =
| TransactionWithdrawal
| TransactionPayment
@@ -2624,9 +2780,13 @@ export type Transaction =
| TransactionPeerPullCredit
| TransactionPeerPullDebit
| TransactionPeerPushCredit
- | TransactionPeerPushDebit;
+ | TransactionPeerPushDebit
+ | TransactionInternalWithdrawal;
```
```typescript
+/**
+ * A withdrawal transaction (either bank-integrated or manual).
+ */
export interface TransactionWithdrawal extends TransactionCommon {
type: TransactionType.Withdrawal;
/**
@@ -2648,30 +2808,15 @@ export interface TransactionWithdrawal extends
TransactionCommon {
export interface TransactionCommon {
transactionId: TransactionIdStr;
type: TransactionType;
- timestamp: TalerProtocolTimestamp;
+ timestamp: TalerPreciseTimestamp;
/**
* Transaction state, as per DD37.
*/
txState: TransactionState;
/**
- * @deprecated in favor of statusMajor and statusMinor
- */
- extendedStatus: ExtendedStatus;
- /**
- * true if the transaction is still pending, false otherwise
- * If a transaction is not longer pending, its timestamp will be updated,
- * but its transactionId will remain unchanged
- *
- * @deprecated show extendedStatus
- */
- pending: boolean;
- /**
- * True if the transaction encountered a problem that might be
- * permanent. A frozen transaction won't be automatically retried.
- *
- * @deprecated show extendedStatus
+ * Possible transitions based on the current state.
*/
- frozen: boolean;
+ txActions: string[];
/**
* Raw amount of the transaction (exclusive of fees or other extra costs).
*/
@@ -2681,11 +2826,22 @@ export interface TransactionCommon {
*/
amountEffective: AmountString;
error?: TalerErrorDetail;
+ /**
+ * If the transaction minor state is in KycRequired this field is going to
+ * have the location where the user need to go to complete KYC information.
+ */
+ kycUrl?: string;
}
```
```typescript
+export type TransactionIdStr = `txn:${string}:${string}` & {
+ [__txId]: true;
+};
+```
+```typescript
export declare enum TransactionType {
Withdrawal = "withdrawal",
+ InternalWithdrawal = "internal-withdrawal",
Payment = "payment",
Refund = "refund",
Refresh = "refresh",
@@ -2698,8 +2854,25 @@ export declare enum TransactionType {
}
```
```typescript
+export interface TalerPreciseTimestamp {
+ /**
+ * Seconds (as integer) since epoch.
+ */
+ readonly t_s: number | "never";
+ /**
+ * Optional microsecond offset (non-negative integer).
+ */
+ readonly off_us?: number;
+ readonly _flavor?: typeof flavor_TalerPreciseTimestamp;
+}
+```
+```typescript
export interface TalerProtocolTimestamp {
+ /**
+ * Seconds (as integer) since epoch.
+ */
readonly t_s: number | "never";
+ readonly _flavor?: typeof flavor_TalerProtocolTimestamp;
}
```
```typescript
@@ -2719,8 +2892,8 @@ export declare enum TransactionMajorState {
Dialog = "dialog",
SuspendedAborting = "suspended-aborting",
Failed = "failed",
+ Expired = "expired",
Deleted = "deleted",
- Unknown = "unknown",
}
```
```typescript
@@ -2731,7 +2904,7 @@ export declare enum TransactionMinorState {
AmlRequired = "aml",
MergeKycRequired = "merge-kyc",
Track = "track",
- Pay = "pay",
+ SubmitPayment = "submit-payment",
RebindSession = "rebind-session",
Refresh = "refresh",
Pickup = "pickup",
@@ -2751,6 +2924,7 @@ export declare enum TransactionMinorState {
WithdrawCoins = "withdraw-coins",
ExchangeWaitReserve = "exchange-wait-reserve",
AbortingBank = "aborting-bank",
+ Aborting = "aborting",
Refused = "refused",
Withdraw = "withdraw",
MerchantOrderProposed = "merchant-order-proposed",
@@ -2760,16 +2934,6 @@ export declare enum TransactionMinorState {
}
```
```typescript
-export declare enum ExtendedStatus {
- Pending = "pending",
- Done = "done",
- Aborting = "aborting",
- Aborted = "aborted",
- Failed = "failed",
- KycRequired = "kyc-required",
-}
-```
-```typescript
export interface TalerErrorDetail {
code: TalerErrorCode;
when?: AbsoluteTime;
@@ -2783,6 +2947,8 @@ export interface AbsoluteTime {
* Timestamp in milliseconds.
*/
readonly t_ms: number | "never";
+ readonly _flavor?: typeof flavor_AbsoluteTime;
+ [opaque_AbsoluteTime]: true;
}
```
```typescript
@@ -2851,12 +3017,6 @@ export interface TransactionPayment extends
TransactionCommon {
* Wallet-internal end-to-end identifier for the payment.
*/
proposalId: string;
- /**
- * How far did the wallet get with processing the payment?
- *
- * @deprecated use extendedStatus
- */
- status: PaymentStatus;
/**
* Amount that must be paid for the contract
*/
@@ -2992,27 +3152,6 @@ export interface Tax {
}
```
```typescript
-export declare enum PaymentStatus {
- /**
- * Explicitly aborted after timeout / failure
- */
- Aborted = "aborted",
- /**
- * Payment failed, wallet will auto-retry.
- * User should be given the option to retry now / abort.
- */
- Failed = "failed",
- /**
- * Paid successfully
- */
- Paid = "paid",
- /**
- * User accepted, payment is processing.
- */
- Accepted = "accepted",
-}
-```
-```typescript
export interface RefundInfoShort {
transactionId: string;
timestamp: TalerProtocolTimestamp;
@@ -3023,9 +3162,23 @@ export interface RefundInfoShort {
```typescript
export interface TransactionRefund extends TransactionCommon {
type: TransactionType.Refund;
- refundedTransactionId: string;
amountRaw: AmountString;
amountEffective: AmountString;
+ refundedTransactionId: string;
+ paymentInfo: RefundPaymentInfo | undefined;
+}
+```
+```typescript
+/**
+ * Summary information about the payment that we got a refund for.
+ */
+export interface RefundPaymentInfo {
+ summary: string;
+ summary_i18n?: InternationalizedString;
+ /**
+ * More information about the merchant
+ */
+ merchant: MerchantInfo;
}
```
```typescript
@@ -3082,6 +3235,7 @@ export declare enum RefreshReason {
Refund = "refund",
AbortPay = "abort-pay",
AbortDeposit = "abort-deposit",
+ AbortPeerPushDebit = "abort-peer-push-debit",
Recoup = "recoup",
BackupRestored = "backup-restored",
Scheduled = "scheduled",
@@ -3214,8 +3368,39 @@ export interface TransactionPeerPushDebit extends
TransactionCommon {
}
```
```typescript
+/**
+ * Internal withdrawal operation, only reported on request.
+ *
+ * Some transactions (peer-*-credit) internally do a withdrawal,
+ * but only the peer-*-credit transaction is reported.
+ *
+ * The internal withdrawal transaction allows to access the details of
+ * the underlying withdrawal for testing/debugging.
+ *
+ * It is usually not reported, so that amounts of transactions properly
+ * add up, since the amountEffecive of the withdrawal is already reported
+ * in the peer-*-credit transaction.
+ */
+export interface TransactionInternalWithdrawal extends TransactionCommon {
+ type: TransactionType.InternalWithdrawal;
+ /**
+ * Exchange of the withdrawal.
+ */
+ exchangeBaseUrl: string;
+ /**
+ * Amount that got subtracted from the reserve balance.
+ */
+ amountRaw: AmountString;
+ /**
+ * Amount that actually was (or will be) added to the wallet's balance.
+ */
+ amountEffective: AmountString;
+ withdrawalDetails: WithdrawalDetails;
+}
+```
+```typescript
export interface AbortTransactionRequest {
- transactionId: string;
+ transactionId: TransactionIdStr;
}
```
```typescript
@@ -3279,7 +3464,7 @@ export type PreparePayResult =
```typescript
export interface PreparePayResultInsufficientBalance {
status: PreparePayResultType.InsufficientBalance;
- transactionId: string;
+ transactionId: TransactionIdStr;
proposalId: string;
contractTerms: MerchantContractTerms;
amountRaw: string;
@@ -3465,7 +3650,7 @@ export interface PayMerchantInsufficientBalanceDetails {
```typescript
export interface PreparePayResultAlreadyConfirmed {
status: PreparePayResultType.AlreadyConfirmed;
- transactionId: string;
+ transactionId: TransactionIdStr;
contractTerms: MerchantContractTerms;
paid: boolean;
amountRaw: string;
@@ -3481,7 +3666,7 @@ export interface PreparePayResultAlreadyConfirmed {
*/
export interface PreparePayResultPaymentPossible {
status: PreparePayResultType.PaymentPossible;
- transactionId: string;
+ transactionId: TransactionIdStr;
/**
* @deprecated use transactionId instead
*/
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated: update wallet-core docs,
gnunet <=