[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: update DONAU API
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: update DONAU API |
|
Date: |
Tue, 26 Sep 2023 14:39:31 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 18e226ff update DONAU API
18e226ff is described below
commit 18e226ffd88601ebd865874d480909a46458dfb8
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Sep 26 14:39:26 2023 +0200
update DONAU API
---
core/api-donau.rst | 673 ++++++++------------------------------------------
core/api-exchange.rst | 4 -
2 files changed, 108 insertions(+), 569 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
index 6ab3bee9..222609cf 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -35,11 +35,11 @@ Donau status information
------------------------
This API is used by wallets and merchants to obtain global information about
-the donau, such as online signing keys, available denominations and the fee
-structure. This is typically the first call any donau client makes, as it
+the Donau, such as online signing keys, available donation units and the fee
+structure. This is typically the first call any Donau client makes, as it
returns information required to process all of the other interactions with the
-donau. The returned information is secured by (1) signature(s) from the donau,
-especially the long-term offline signing key of the donau, which clients should
+Donau. The returned information is secured by (1) signature(s) from the Donau,
+especially the long-term offline signing key of the Donau, which clients should
cache; (2) signature(s) from auditors, and the auditor keys should be
hard-coded into the wallet as they are the trust anchors for Taler; (3)
possibly by using HTTPS.
@@ -47,7 +47,7 @@ possibly by using HTTPS.
.. http:get:: /seed
- Return an entropy seed. The donau will return a high-entropy
+ Return an entropy seed. The Donau will return a high-entropy
value that will differ for every call. The response is NOT in
JSON, but simply high-entropy binary data in the HTTP body.
This API should be used by wallets to guard themselves against
@@ -57,7 +57,10 @@ possibly by using HTTPS.
.. http:get:: /config
- Return the protocol version and currency supported by this donau backend, as
well as the list of possible KYC requirements. This endpoint is largely for
the SPA for AML officers. Merchants should use ``/keys`` which also contains
the protocol version and currency.
+ Return the protocol version and currency supported by this Donau backend, as
+ well as the list of possible KYC requirements. This endpoint is largely for
+ the SPA for AML officers. Merchants should use ``/keys`` which also contains
+ the protocol version and currency.
**Response:**
@@ -83,21 +86,29 @@ possibly by using HTTPS.
}
-
.. http:get:: /keys
- Get a list of all denomination keys offered by the donau,
- as well as the donau's current online signing key.
+ Get a list of all denomination keys offered by the Donau,
+ as well as the Donau's current online signing key.
**Request:**
- :query last_issue_date: Optional argument specifying the maximum value of
any of the ``stamp_start`` members of the denomination keys of a ``/keys``
response that is already known to the client. Allows the donau to only return
keys that have changed since that timestamp. The given value must be an
unsigned 64-bit integer representing seconds after 1970. If the timestamp does
not exactly match the ``stamp_start`` of one of the denomination keys, all keys
are returned.
+ :query last_issue_date: Optional argument specifying the maximum value of
+ any of the ``stamp_start`` members of the
+ denomination keys of a ``/keys`` response that is
+ already known to the client. Allows the Donau to
+ only return keys that have changed since that
+ timestamp. The given value must be an unsigned
+ 64-bit integer representing seconds after 1970. If
+ the timestamp does not exactly match the
+ ``stamp_start`` of one of the denomination keys, all
+ keys are returned.
**Response:**
:http:statuscode:`200 OK`:
- The donau responds with a `DonauKeysResponse` object. This request should
- virtually always be successful. It only fails if the donau is
misconfigured or
+ The Donau responds with a `DonauKeysResponse` object. This request should
+ virtually always be successful. It only fails if the Donau is
misconfigured or
has not yet been provisioned with key signatures via
``taler-donau-offline``.
**Details:**
@@ -110,13 +121,13 @@ possibly by using HTTPS.
// The format is "current:revision:age".
version: string;
- // Financial domain by this donau.
+ // Financial domain this donau operates for.
domain: string;
// The donau's base URL.
base_url: string;
- // The donau's currency or asset unit.
+ // The donau's currency.
currency: string;
// How many digits should the amounts be rendered
@@ -129,84 +140,66 @@ possibly by using HTTPS.
// in ``denoms`` and ``signkeys``.
master_public_key: EddsaPublicKey;
- // Denominations offered by this donau
- denominations: DenomGroup[];
-
- // Compact EdDSA `signature` (binary-only) over the XOR of all
- // .hash fields (in binary) in the list "denominations".
- // Signature of `TALER_DonauKeySetPS`
- denominations_sig: EddsaSignature;
+ // Donation Units offered by this donau
+ donaton_units: DonationUnitGroup[];
// The date when the denomination keys were last updated.
list_issue_date: Timestamp;
- // The donau's signing keys.
+ // The Donau's signing keys.
signkeys: SignKey[];
- // Compact EdDSA `signature` (binary-only) over the SHA-512 hash of the
- // concatenation of all SHA-512 hashes of the RSA denomination public
keys
- // in ``denoms`` in the same order as they were in ``denoms``. Note
that for
- // hashing, the binary format of the RSA public keys is used, and not
their
- // `base32 encoding <base32>`. Wallets cannot do much with this
signature by itself;
- // it is only useful when multiple clients need to establish that the
donau
- // is sabotaging end-user anonymity by giving disjoint denomination keys
to
- // different users. If an donau were to do this, this signature allows
the
- // clients to demonstrate to the public that the donau is dishonest.
+ // Compact EdDSA `signature` (binary-only) over the list "donation
units".
// Signature of `TALER_DonauKeySetPS`
- // DEPRICATED: Will eventually replaced by "denominations_sig"
- eddsa_sig: EddsaSignature;
+ exchange_sig: EddsaSignature;
- // Public EdDSA key of the donau that was used to generate the signature.
- // Should match one of the donau's signing keys from ``/keys``. It is
given
+ // Public EdDSA key of the Donau that was used to generate the
exchange_sig.
+ // Should match one of the Donau's signing keys from ``/keys``. It is
given
// explicitly as the client might otherwise be confused by clock skew as
to
// which signing key was used.
- eddsa_pub: EddsaPublicKey;
+ exchange_pub: EddsaPublicKey;
}
- .. ts:def:: DenomGroup
+ .. ts:def:: DonauDonationUnitGroup
- type DenomGroup =
- | DenomGroupRsa
- | DenomGroupCs;
+ type DonauDonationUnitGroup =
+ | DonauDonationUnitGroupRsa
+ | DonauDonationUnitGroupCs;
- .. ts:def:: DenomGroupRsa
+ .. ts:def:: DonauDonationUnitGroupRsa
- interface DenomGroupRsa extends DenomGroupCommon {
+ interface DonauDonationUnitGroupRsa extends DonauDonationUnitGroupCommon {
cipher: "RSA";
denoms: ({
rsa_pub: RsaPublicKey;
- } & DenomCommon)[];
+ } & DonauDonationUnitCommon)[];
}
- .. ts:def:: DenomGroupCs
+ .. ts:def:: DonauDonationUnitGroupCs
- interface DenomGroupCs extends DenomGroupCommon {
+ interface DonauDonationUnitGroupCs extends DonauDonationUnitGroupCommon {
cipher: "CS";
denoms: ({
cs_pub: Cs25519Point;
- } & DenomCommon)[];
+ } & DonauDonationUnitCommon)[];
}
- .. ts:def:: DenomGroupCommon
+ .. ts:def:: DonauDonationUnitGroupCommon
// Common attributes for all denomination groups
- interface DenomGroupCommon {
+ interface DonauDonationUnitGroupCommon {
// How much are coins of this denomination worth?
value: Amount;
- // XOR of all the SHA-512 hash values of the denominations' public keys
- // in this group. Note that for hashing, the binary format of the
- // public keys is used, and not their base32 encoding.
- hash: HashCode;
}
- .. ts:def:: DenomCommon
+ .. ts:def:: DonauDonationUnitCommon
- interface DenomCommon {
- // Signature of `TALER_DenominationKeyValidityPS`.
+ interface DonauDonationUnitCommon {
+ // Signature of `TALER_DonauDonationUnitKeyValidityPS`.
master_sig: EddsaSignature;
// When does the denomination key become valid?
@@ -217,11 +210,11 @@ possibly by using HTTPS.
stamp_expire_withdraw: Timestamp;
// Timestamp indicating by when legal disputes relating to these coins
must
- // be settled, as the donau will afterwards destroy its evidence
relating to
+ // be settled, as the Donau will afterwards destroy its evidence
relating to
// transactions involving this coin.
stamp_expire_legal: Timestamp;
- // Set to 'true' if the donau somehow "lost"
+ // Set to 'true' if the Donau somehow "lost"
// the private key. The denomination was not
// necessarily revoked, but still cannot be used
// to withdraw coins at this time (theoretically,
@@ -231,10 +224,10 @@ possibly by using HTTPS.
lost?: boolean;
}
- .. ts:def:: Denom
+ .. ts:def:: DonauDonationUnit
- interface Denom {
- // How much are coins of this denomination worth?
+ interface DonauDonationUnit {
+ // How much are donation receipts of this denomination worth?
value: Amount;
// When does the denomination key become valid?
@@ -250,38 +243,32 @@ possibly by using HTTPS.
stamp_expire_legal: Timestamp;
// Public key for the denomination.
- denom_pub: DenominationKey;
+ denom_pub: DonauDonationUnitKey;
- // Signature of `TALER_DenominationKeyValidityPS`.
+ // Signature of `TALER_DonauDonationUnitKeyValidityPS`.
master_sig: EddsaSignature;
}
- .. ts:def:: DenominationKey
+ .. ts:def:: DonauDonationUnitKey
- type DenominationKey =
- | RsaDenominationKey
- | CSDenominationKey;
+ type DonauDonationUnitKey =
+ | RsaDonauDonationUnitKey
+ | CSDonauDonationUnitKey;
- .. ts:def:: RsaDenominationKey
+ .. ts:def:: RsaDonauDonationUnitKey
- interface RsaDenominationKey {
+ interface RsaDonauDonationUnitKey {
cipher: "RSA";
- // 32-bit age mask.
- age_mask: Integer;
-
// RSA public key
rsa_public_key: RsaPublicKey;
}
- .. ts:def:: CSDenominationKey
+ .. ts:def:: CSDonauDonationUnitKey
- interface CSDenominationKey {
+ interface CSDonauDonationUnitKey {
cipher: "CS";
- // 32-bit age mask.
- age_mask: Integer;
-
// Public key of the denomination.
cs_public_key: Cs25519Point;
@@ -321,7 +308,7 @@ possibly by using HTTPS.
.. note::
- Both the individual denominations *and* the denomination list is signed,
+ Both the individual donation units *and* the denomination list is signed,
allowing customers to prove that they received an inconsistent list.
@@ -348,9 +335,9 @@ Management operations authorized by master key
interface FutureKeysResponse {
- // Future denominations to be offered by this donau
+ // Future donation units to be offered by this donau
// (only those lacking a master signature).
- future_denoms: FutureDenom[];
+ future_denoms: FutureDonationUnit[];
// The donau's future signing keys (only those lacking a master
signature).
future_signkeys: FutureSignKey[];
@@ -367,9 +354,9 @@ Management operations authorized by master key
}
- .. ts:def:: FutureDenom
+ .. ts:def:: FutureDonationUnit
- interface FutureDenom {
+ interface FutureDonationUnit {
// Name in the configuration file that defines this denomination.
section_name: string;
@@ -408,7 +395,7 @@ Management operations authorized by master key
fee_refund: Amount;
// Signature by the denomination security module
- // over `TALER_DenominationKeyAnnouncementPS`
+ // over `TALER_DonationUnitKeyAnnouncementPS`
// for this denomination with purpose
// ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
denom_secmod_sig: EddsaSignature;
@@ -463,21 +450,21 @@ Management operations authorized by master key
interface MasterSignatures {
// Provided master signatures for future denomination keys.
- denom_sigs: DenomSignature[];
+ denom_sigs: DonationUnitSignature[];
// Provided master signatures for future online signing keys.
signkey_sigs: SignKeySignature[];
}
- .. ts:def:: DenomSignature
+ .. ts:def:: DonationUnitSignature
- interface DenomSignature {
+ interface DonationUnitSignature {
// Hash of the public (RSA) key of the denomination.
h_denom_pub: HashCode;
- // Signature over `TALER_DenominationKeyValidityPS`.
+ // Signature over `TALER_DonationUnitKeyValidityPS`.
// Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY``
master_sig: EddsaSignature;
@@ -497,63 +484,6 @@ Management operations authorized by master key
}
-.. http:post:: /management/denominations/$H_DENOM_PUB/revoke
-
- Revoke denomination key, preventing further use by the donau.
- Only to be used by the donau's offline key management team. Not useful
- for anyone else.
-
- **Request:** The request body must be a `DenomRevocationSignature` object.
-
- **Response:**
-
- :http:statuscode:`204 No content`:
- The request was successfully processed.
- :http:statuscode:`403 Forbidden`:
- The provided signature is invalid.
-
- **Details:**
-
- .. ts:def:: DenomRevocationSignature
-
- interface DenomRevocationSignature {
-
- // Signature by the donau master key over a
- // `TALER_MasterDenominationKeyRevocationPS`.
- // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``.
- master_sig: EddsaSignature;
-
- }
-
-.. http:post:: /management/signkeys/$DONAU_PUB/revoke
-
- Revoke donau online signing key, preventing further use by the donau.
- Only to be used by the donau's offline key management team. Not useful
- for anyone else.
-
- **Request:** The request body must be a `SignkeyRevocationSignature` object.
-
- **Response:**
-
- :http:statuscode:`204 No content`:
- The request was successfully processed.
- :http:statuscode:`403 Forbidden`:
- The provided signature is invalid.
-
- **Details:**
-
- .. ts:def:: SignkeyRevocationSignature
-
- interface SignkeyRevocationSignature {
-
- // Signature by the donau master key over a
- // `TALER_MasterSigningKeyRevocationPS`.
- // Must have purpose ``TALER_SIGNATURE_MASTER_SIGN_KEY_REVOKED``.
- master_sig: EddsaSignature;
-
- }
-
-
----------
Withdrawal
----------
@@ -581,7 +511,10 @@ donau.
**Request:**
- :query timeout_ms=MILLISECONDS: *Optional.* If specified, the donau will
wait up to MILLISECONDS for incoming funds before returning a 404 if the
reserve does not yet exist.
+ :query timeout_ms=MILLISECONDS: *Optional.* If specified, the donau will
+ wait up to MILLISECONDS for incoming funds
+ before returning a 404 if the reserve does
+ not yet exist.
**Response:**
@@ -598,42 +531,35 @@ donau.
// Balance left in the reserve.
balance: Amount;
- // If set, age restriction is required to be set for each coin to this
- // value during the withdrawal from this reserve. The client then MUST
- // use a denomination with support for age restriction enabled for the
- // withdrawal.
- // The value represents a valid age group from the list of permissible
- // age groups as defined by the donau's output to /keys.
- maximum_age_group?: number;
}
-.. http:post:: /reserves/$RESERVE_PUB/status
+.. http:post:: /reserves/$RESERVE_PUB/history
- Request information about a reserve or an account.
+ Request information about the history of a reserve.
**Request:**
- The request body must be a `ReserveStatusRequest` object.
+ The request body must be a `ReserveHistoryRequest` object.
**Response:**
:http:statuscode:`200 OK`:
- The donau responds with a `ReserveStatus` object; the reserve was known to
the donau.
+ The Donau responds with a `ReserveStatus` object; the reserve was known to
the Donau.
:http:statuscode:`403 Forbidden`:
- The *TALER_SIGNATURE_RESERVE_STATUS_REQUEST* signature is invalid.
- This response comes with a standard `ErrorDetail` response. Alternatively,
the provided timestamp is not close to the current time.
+ The *TALER_SIGNATURE_RESERVE_HISTORY_REQUEST* is invalid.
+ This response comes with a standard `ErrorDetail` response.
Alternatively, the provided timestamp is not close to the current time.
:http:statuscode:`404 Not found`:
The reserve key does not belong to a reserve known to the donau.
**Details:**
- .. ts:def:: ReserveStatusRequest
+ .. ts:def:: ReserveHistoryRequest
- interface ReserveStatusRequest {
- // Signature of purpose
- // ``TALER_SIGNATURE_RESERVE_STATUS_REQUEST`` over
- // a `TALER_ReserveStatusRequestSignaturePS`.
+ interface ReserveHistoryRequest {
+ // Signature of type
+ // ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST``
+ // over a `TALER_ReserveHistoryRequestSignaturePS`.
reserve_sig: EddsaSignature;
// Time when the client made the request.
@@ -664,58 +590,8 @@ donau.
// Union discriminated by the "type" field.
type TransactionHistoryItem =
- | AccountSetupTransaction
- | ReserveHistoryTransaction
| ReserveWithdrawTransaction
- | ReserveAgeWithdrawTransaction
- | ReserveCreditTransaction
- | ReserveClosingTransaction
- | ReserveOpenRequestTransaction
- | ReserveCloseRequestTransaction
- | PurseMergeTransaction;
-
- .. ts:def:: AccountSetupTransaction
-
- interface AccountSetupTransaction {
- type: "SETUP";
-
- // KYC fee agreed to by the reserve owner.
- kyc_fee: Amount;
-
- // Time when the KYC was triggered.
- kyc_timestamp: Timestamp;
-
- // Hash of the wire details of the account.
- // Note that this hash is unsalted and potentially
- // private (as it could be inverted), hence access
- // to this endpoint must be authorized using the
- // private key of the reserve.
- h_wire: HashCode;
-
- // Signature created with the reserve's private key.
- // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` over
- // a ``TALER_AccountSetupRequestSignaturePS``.
- reserve_sig: EddsaSignature;
-
- }
-
- .. ts:def:: ReserveHistoryTransaction
-
- interface ReserveHistoryTransaction {
- type: "HISTORY";
-
- // Fee agreed to by the reserve owner.
- amount: Amount;
-
- // Time when the request was made.
- request_timestamp: Timestamp;
-
- // Signature created with the reserve's private key.
- // Must be of purpose ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` over
- // a `TALER_ReserveHistoryRequestSignaturePS`.
- reserve_sig: EddsaSignature;
-
- }
+ | ReserveCreditTransaction;
.. ts:def:: ReserveWithdrawTransaction
@@ -740,27 +616,6 @@ donau.
withdraw_fee: Amount;
}
- .. ts:def:: ReserveAgeWithdrawTransaction
-
- interface ReserveAgeWithdrawTransaction {
- type: "AGEWITHDRAW";
-
- // Total Amount withdrawn.
- amount: Amount;
-
- // Commitment of all ``n*kappa`` blinded coins.
- h_commitment: HashCode;
-
- // Signature over a `TALER_AgeWithdrawRequestPS`
- // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW``
- // created with the reserve's private key.
- reserve_sig: EddsaSignature;
-
- // Fee that is charged for withdraw.
- withdraw_fee: Amount;
- }
-
-
.. ts:def:: ReserveCreditTransaction
interface ReserveCreditTransaction {
@@ -781,243 +636,6 @@ donau.
}
- .. ts:def:: ReserveClosingTransaction
-
- interface ReserveClosingTransaction {
- type: "CLOSING";
-
- // Closing balance.
- amount: Amount;
-
- // Closing fee charged by the donau.
- closing_fee: Amount;
-
- // Wire transfer subject.
- wtid: Base32;
-
- // ``payto://`` URI of the wire account into which the funds were
returned to.
- receiver_account_details: string;
-
- // This is a signature over a
- // struct `TALER_ReserveCloseConfirmationPS` with purpose
- // ``TALER_SIGNATURE_DONAU_RESERVE_CLOSED``.
- donau_sig: EddsaSignature;
-
- // Public key used to create 'donau_sig'.
- donau_pub: EddsaPublicKey;
-
- // Time when the reserve was closed.
- timestamp: Timestamp;
- }
-
-
- .. ts:def:: ReserveOpenRequestTransaction
-
- interface ReserveOpenRequestTransaction {
- type: "OPEN";
-
- // Open fee paid from the reserve.
- open_fee: Amount;
-
- // This is a signature over
- // a struct `TALER_ReserveOpenPS` with purpose
- // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN``.
- reserve_sig: EddsaSignature;
-
- // Timestamp of the open request.
- request_timestamp: Timestamp;
-
- // Requested expiration.
- requested_expiration: Timestamp;
-
- // Requested number of free open purses.
- requested_min_purses: Integer;
-
- }
-
- .. ts:def:: ReserveCloseRequestTransaction
-
- interface ReserveCloseRequestTransaction {
- type: "CLOSE";
-
- // This is a signature over
- // a struct `TALER_ReserveClosePS` with purpose
- // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE``.
- reserve_sig: EddsaSignature;
-
- // Target account ``payto://``, optional.
- h_payto?: PaytoHash;
-
- // Timestamp of the close request.
- request_timestamp: Timestamp;
- }
-
- .. ts:def:: ReserveCreditTransaction
-
- interface ReserveCreditTransaction {
- type: "CREDIT";
-
- // Amount deposited.
- amount: Amount;
-
- // Sender account ``payto://`` URL.
- sender_account_url: string;
-
- // Opaque identifier internal to the donau that
- // uniquely identifies the wire transfer that credited the reserve.
- wire_reference: Integer;
-
- // Timestamp of the incoming wire transfer.
- timestamp: Timestamp;
- }
-
- .. ts:def:: PurseMergeTransaction
-
- interface PurseMergeTransaction {
- type: "MERGE";
-
- // SHA-512 hash of the contact of the purse.
- h_contract_terms: HashCode;
-
- // EdDSA public key used to approve merges of this purse.
- merge_pub: EddsaPublicKey;
-
- // Minimum age required for all coins deposited into the purse.
- min_age: Integer;
-
- // Number that identifies who created the purse
- // and how it was paid for.
- flags: Integer;
-
- // Purse public key.
- purse_pub: EddsaPublicKey;
-
- // EdDSA signature of the account/reserve affirming the merge
- // over a `TALER_AccountMergeSignaturePS`.
- // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE``
- reserve_sig: EddsaSignature;
-
- // Client-side timestamp of when the merge request was made.
- merge_timestamp: Timestamp;
-
- // Indicative time by which the purse should expire
- // if it has not been merged into an account. At this
- // point, all of the deposits made should be
- // auto-refunded.
- purse_expiration: Timestamp;
-
- // Purse fee the reserve owner paid for the purse creation.
- purse_fee: Amount;
-
- // Total amount merged into the reserve.
- // (excludes fees).
- amount: Amount;
-
- // True if the purse was actually merged.
- // If false, only the purse_fee has an impact
- // on the reserve balance!
- merged: boolean;
- }
-
-
-.. http:post:: /reserves/$RESERVE_PUB/history
-
- Request information about the full history of
- a reserve or an account.
-
- **Request:**
-
- The request body must be a `ReserveHistoryRequest` object.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The donau responds with a `ReserveStatus` object; the reserve was known to
the donau.
- :http:statuscode:`403 Forbidden`:
- The *TALER_SIGNATURE_RESERVE_HISTORY_REQUEST* is invalid.
- This response comes with a standard `ErrorDetail` response.
Alternatively, the provided timestamp is not close to the current time.
- :http:statuscode:`404 Not found`:
- The reserve key does not belong to a reserve known to the donau.
- :http:statuscode:`412 Precondition failed`:
- The balance in the reserve is insufficient to pay for the history request.
- This response comes with a standard `ErrorDetail` response.
-
- **Details:**
-
- .. ts:def:: ReserveHistoryRequest
-
- interface ReserveHistoryRequest {
- // Signature of type
- // ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST``
- // over a `TALER_ReserveHistoryRequestSignaturePS`.
- reserve_sig: EddsaSignature;
-
- // Time when the client made the request.
- // Timestamp must be reasonably close to the time of
- // the donau, otherwise the donau may reject
- // the request.
- request_timestamp: Timestamp;
- }
-
-
-.. _delete-reserve:
-
-.. http:DELETE:: /reserves/$RESERVE_PUB
-
- Forcefully closes a reserve.
- The request header must contain an *Account-Request-Signature*.
- Note: this endpoint is not currently implemented!
-
- **Request:**
-
- *Account-Request-Signature*: The client must provide Base-32 encoded EdDSA
signature made with ``$ACCOUNT_PRIV``, affirming its authorization to delete
the account. The purpose used MUST be ``TALER_SIGNATURE_RESERVE_CLOSE``.
-
- :query force=BOOLEAN: *Optional.* If set to 'true' specified, the donau
- will delete the account even if there is a balance remaining.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The operation succeeded, the donau provides details
- about the account deletion.
- The response will include a `ReserveClosedResponse` object.
- :http:statuscode:`403 Forbidden`:
- The *Account-Request-Signature* is invalid.
- This response comes with a standard `ErrorDetail` response.
- :http:statuscode:`404 Not found`:
- The account is unknown to the donau.
- :http:statuscode:`409 Conflict`:
- The account is still has digital cash in it, the associated
- wire method is ``void`` and the *force* option was not provided.
- This response comes with a standard `ErrorDetail` response.
-
- **Details:**
-
- .. ts:def:: ReserveClosedResponse
-
- interface ReserveClosedResponse {
-
- // Final balance of the account.
- closing_amount: Amount;
-
- // Current time of the donau, used as part of
- // what the donau signs over.
- close_time: Timestamp;
-
- // Hash of the wire account into which the remaining
- // balance will be transferred. Note: may be the
- // hash over ``payto://void/`, in which case the
- // balance is forfeit to the profit of the donau.
- h_wire: HashCode;
-
- // This is a signature over a
- // struct ``TALER_AccountDeleteConfirmationPS`` with purpose
- // ``TALER_SIGNATURE_DONAU_RESERVE_CLOSED``.
- donau_sig: EddsaSignature;
-
- }
-
-
Withdraw
~~~~~~~~
@@ -1041,7 +659,7 @@ Withdraw
:http:statuscode:`410 Gone`:
The requested denomination key is not yet or no longer valid.
It either before the validity start, past the expiration or was revoked.
The response is a
- `DenominationExpiredMessage`. Clients must evaluate
+ `DonationUnitExpiredMessage`. Clients must evaluate
the error code provided to understand which of the
cases this is and handle it accordingly.
@@ -1121,45 +739,21 @@ Batch Withdraw
A denomination key or the reserve are not known to the donau. If the
denomination key is unknown, this suggests a bug in the wallet as the
wallet should have used current denomination keys from ``/keys``.
- In this case, the response will be a `DenominationUnknownMessage`.
+ In this case, the response will be a `DonationUnitUnknownMessage`.
If the reserve is unknown, the wallet should not report a hard error yet,
but
instead simply wait for up to a day, as the wire transaction might simply
not yet have completed and might be known to the donau in the near future.
In this case, the wallet should repeat the exact same request later again
using exactly the same blinded coin.
:http:statuscode:`409 Conflict`:
- One of the following reasons occured:
-
- 1. The balance of the reserve is not sufficient to withdraw the coins of
the
- indicated denominations. The response is `WithdrawError` object.
-
- 2. The reserve has a birthday set and requires a request to
``/age-withdraw`` instead.
- The response comes with a standard `ErrorDetail` response with error-code
``TALER_EC_DONAU_RESERVES_AGE_RESTRICTION_REQUIRED`` and an additional field
``maximum_allowed_age`` for the maximum age (in years) that the client can
commit to in the call to ``/age-withdraw``
+ The balance of the reserve is not sufficient to withdraw the coins of the
+ indicated donation units.
:http:statuscode:`410 Gone`:
A requested denomination key is not yet or no longer valid.
It either before the validity start, past the expiration or was revoked.
- The response is a `DenominationExpiredMessage`. Clients must evaluate the
+ The response is a `DonationUnitExpiredMessage`. Clients must evaluate the
error code provided to understand which of the cases this is and handle it
accordingly.
- :http:statuscode:`451 Unavailable for Legal Reasons`:
- This reserve has received funds from a purse or the amount withdrawn
- exceeds another legal threshold and thus the reserve must
- be upgraded to an account (with KYC) before the withdraw can
- complete. Note that this response does NOT affirm that the
- withdraw will ultimately complete with the requested amount.
- The user should be redirected to the provided location to perform
- the required KYC checks to open the account before withdrawing.
- Afterwards, the request should be repeated.
- The response will be an `KycNeededRedirect` object.
-
- Implementation note: internally, we need to
- distinguish between upgrading the reserve to an
- account (due to P2P payment) and identifying the
- owner of the origin bank account (due to exceeding
- the withdraw amount threshold), as we need to create
- a different payto://-URI for the KYC check depending
- on the case.
-
**Details:**
@@ -1171,7 +765,6 @@ Batch Withdraw
}
-
.. ts:def:: BatchWithdrawResponse
interface BatchWithdrawResponse {
@@ -1224,7 +817,7 @@ proof to the seller for the escrow of sufficient fund.
Either one of the denomination keys is not recognized (expired or invalid),
or the wire type is not recognized.
If a denomination key is unknown, the response will be
- a `DenominationUnknownMessage`.
+ a `DonationUnitUnknownMessage`.
:http:statuscode:`409 Conflict`:
The deposit operation has either failed because a coin has insufficient
residual value, or because the same public key of a coin has been
@@ -1241,7 +834,7 @@ proof to the seller for the escrow of sufficient fund.
:http:statuscode:`410 Gone`:
The requested denomination key is not yet or no longer valid.
It either before the validity start, past the expiration or was revoked.
The response is a
- `DenominationExpiredMessage`. Clients must evaluate
+ `DonationUnitExpiredMessage`. Clients must evaluate
the error code provided to understand which of the
cases this is and handle it accordingly.
@@ -1251,43 +844,13 @@ proof to the seller for the escrow of sufficient fund.
interface BatchDepositRequest {
- // The merchant's account details.
- merchant_payto_uri: string;
-
- // The salt is used to hide the ``payto_uri`` from customers
- // when computing the ``h_wire`` of the merchant.
- wire_salt: WireSalt;
-
- // SHA-512 hash of the contract of the merchant with the customer.
Further
- // details are never disclosed to the donau.
- h_contract_terms: HashCode;
-
// The list of coins that are going to be deposited with this Request.
coins: BatchDepositRequestCoin[];
- // Timestamp when the contract was finalized.
- timestamp: Timestamp;
-
- // Indicative time by which the donau undertakes to transfer the funds to
- // the merchant, in case of successful payment. A wire transfer deadline
of 'never'
- // is not allowed.
- wire_transfer_deadline: Timestamp;
-
- // EdDSA `public key of the merchant <merchant-pub>`, so that the client
can identify the
- // merchant for refund requests.
- merchant_pub: EddsaPublicKey;
-
- // Date until which the merchant can issue a refund to the customer via
the
- // donau, to be omitted if refunds are not allowed.
- //
- // THIS FIELD WILL BE DEPRICATED, once the refund mechanism becomes a
- // policy via extension.
- refund_deadline?: Timestamp;
-
- // CAVEAT: THIS IS WORK IN PROGRESS
- // (Optional) policy for the batch-deposit.
- // This might be a refund, auction or escrow policy.
- policy?: DepositPolicy;
+ // FIXME: maybe add tax year?
+
+ // Hash of the salted tax payer identification number.
+ h_donor: DonorTaxDataHash;
}
.. ts:def:: BatchDepositRequestCoin
@@ -1300,13 +863,9 @@ proof to the seller for the escrow of sufficient fund.
denom_pub_hash: HashCode;
// Donau's unblinded RSA signature of the coin.
- ub_sig: DenominationSignature;
-
- // Amount to be deposited, can be a fraction of the
- // coin's total value.
- contribution: Amount;
+ ub_sig: DonationUnitSignature;
- // Signature over `TALER_DepositRequestPS`, made by the customer with the
+ // Signature over `TALER_DonauDepositRequestPS`, made by the customer
with the
// `coin's private key <coin-priv>`.
coin_sig: EddsaSignature;
}
@@ -1317,20 +876,11 @@ proof to the seller for the escrow of sufficient fund.
.. ts:def:: BatchDepositSuccess
interface BatchDepositSuccess {
- // Optional base URL of the donau for looking up wire transfers
- // associated with this transaction. If not given,
- // the base URL is the same as the one used for this request.
- // Can be used if the base URL for ``/transactions/`` differs from that
- // for ``/coins/``, i.e. for load balancing. Clients SHOULD
- // respect the ``transaction_base_url`` if provided. Any HTTP server
- // belonging to an donau MUST generate a 307 or 308 redirection
- // to the correct base URL should a client uses the wrong base
- // URL, or if the base URL has changed since the deposit.
- transaction_base_url?: string;
-
- // Timestamp when the deposit was received by the donau.
+ // FIXME: maybe add tax year instead?
donau_timestamp: Timestamp;
+ // FIXME: maybe add total amount?
+
// `Public EdDSA key of the donau <sign-key-pub>` that was used to
// generate the signature.
// Should match one of the donau's signing keys from ``/keys``. It is
given
@@ -1338,18 +888,11 @@ proof to the seller for the escrow of sufficient fund.
// which signing key was used.
donau_pub: EddsaPublicKey;
- // Array of deposit confirmation signatures from the donau
- // Entries must be in the same order the coins were given
- // in the batch deposit request.
- donau_sigs: DepositConfirmationSignature[];
- }
-
- .. ts:def:: DepositConfirmationSignature
-
- interface DepositConfirmationSignature {
- // The EdDSA signature of `TALER_DepositConfirmationPS` using a current
+ // Final tax receipt signature from the donau.
+ // The EdDSA signature of `TALER_DonauTaxDeductionConfirmationPS` using
a current
// `signing key of the donau <sign-key-priv>` affirming the successful
// deposit and that the donau will transfer the funds after the refund
// deadline, or as soon as possible if the refund deadline is zero.
donau_sig: EddsaSignature;
}
+
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 5baa894b..8eb38a89 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -349,10 +349,6 @@ possibly by using HTTPS.
// Fee charged by the exchange for refunding a coin of this denomination.
fee_refund: Amount;
- // XOR of all the SHA-512 hash values of the denominations' public keys
- // in this group. Note that for hashing, the binary format of the
- // public keys is used, and not their base32 encoding.
- hash: HashCode;
}
.. ts:def:: DenomCommon
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: update DONAU API,
gnunet <=