[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: donau draft, first cut
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: donau draft, first cut |
|
Date: |
Tue, 12 Sep 2023 15:50:15 +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 3597f974 donau draft, first cut
3597f974 is described below
commit 3597f97461d0a11c18a13a10da458a6aa9651839
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Sep 12 15:50:12 2023 +0200
donau draft, first cut
---
core/api-donau.rst | 1357 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 1357 insertions(+)
diff --git a/core/api-donau.rst b/core/api-donau.rst
new file mode 100644
index 00000000..2fed154a
--- /dev/null
+++ b/core/api-donau.rst
@@ -0,0 +1,1357 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2023 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free
Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
details.
+
+ You should have received a copy of the GNU Affero General Public License
along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
+========================
+The Donau RESTful API
+========================
+
+The API specified here follows the :ref:`general conventions <http-common>`
+for all details not specified in the individual requests.
+The `glossary <https://docs.taler.net/glossary.html#glossary>`_
+defines all specific terms used in this section.
+
+.. contents:: Table of Contents
+
+.. include:: tos.rst
+
+.. _keys:
+
+---------------------------
+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
+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
+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.
+
+
+.. http:get:: /seed
+
+ 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
+ running on low-entropy (bad PRNG) hardware. Naturally, the entropy
+ returned MUST be mixed with locally generated entropy.
+
+
+.. 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.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The body is a `VersionResponse`.
+
+ .. ts:def:: DonauVersionResponse
+
+ interface DonauVersionResponse {
+ // libtool-style representation of the Donau protocol version, see
+ //
https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ // The format is "current:revision:age".
+ version: string;
+
+ // Name of the protocol.
+ name: "taler-donau";
+
+ // Currency supported by this donau.
+ currency: string;
+
+ // Financial domain by this donau.
+ domain: string;
+
+ }
+
+
+.. http:get:: /keys
+
+ 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.
+
+ **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
+ has not yet been provisioned with key signatures via
``taler-donau-offline``.
+
+ **Details:**
+
+ .. ts:def:: DonauKeysResponse
+
+ interface DonauKeysResponse {
+ // libtool-style representation of the Donau protocol version, see
+ //
https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ // The format is "current:revision:age".
+ version: string;
+
+ // Financial domain by this donau.
+ domain: string;
+
+ // The donau's base URL.
+ base_url: string;
+
+ // The donau's currency or asset unit.
+ currency: string;
+
+ // How many digits should the amounts be rendered
+ // with by default. Small capitals should
+ // be used to render fractions beyond the number
+ // given here (like on gas stations).
+ currency_fraction_digits: Integer;
+
+ // EdDSA master public key of the donau, used to sign entries
+ // 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;
+
+ // The date when the denomination keys were last updated.
+ list_issue_date: Timestamp;
+
+ // 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.
+ // Signature of `TALER_DonauKeySetPS`
+ // DEPRICATED: Will eventually replaced by "denominations_sig"
+ eddsa_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
+ // explicitly as the client might otherwise be confused by clock skew as
to
+ // which signing key was used.
+ eddsa_pub: EddsaPublicKey;
+
+ }
+
+ .. ts:def:: DenomGroup
+
+ type DenomGroup =
+ | DenomGroupRsa
+ | DenomGroupCs;
+
+ .. ts:def:: DenomGroupRsa
+
+ interface DenomGroupRsa extends DenomGroupCommon {
+ cipher: "RSA";
+
+ denoms: ({
+ rsa_pub: RsaPublicKey;
+ } & DenomCommon)[];
+ }
+
+ .. ts:def:: DenomGroupCs
+
+ interface DenomGroupCs extends DenomGroupCommon {
+ cipher: "CS";
+
+ denoms: ({
+ cs_pub: Cs25519Point;
+ } & DenomCommon)[];
+ }
+
+ .. ts:def:: DenomGroupCommon
+
+ // Common attributes for all denomination groups
+ interface DenomGroupCommon {
+ // 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
+
+ interface DenomCommon {
+ // Signature of `TALER_DenominationKeyValidityPS`.
+ master_sig: EddsaSignature;
+
+ // When does the denomination key become valid?
+ stamp_start: Timestamp;
+
+ // When is it no longer possible to deposit coins
+ // of this denomination?
+ 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
+ // transactions involving this coin.
+ stamp_expire_legal: Timestamp;
+
+ // 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,
+ // the private key could be recovered in the
+ // future; coins signed with the private key
+ // remain valid).
+ lost?: boolean;
+ }
+
+ .. ts:def:: Denom
+
+ interface Denom {
+ // How much are coins of this denomination worth?
+ value: Amount;
+
+ // When does the denomination key become valid?
+ stamp_start: Timestamp;
+
+ // When is it no longer possible to deposit coins
+ // of this denomination?
+ 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
+ // transactions involving this coin.
+ stamp_expire_legal: Timestamp;
+
+ // Public key for the denomination.
+ denom_pub: DenominationKey;
+
+ // Signature of `TALER_DenominationKeyValidityPS`.
+ master_sig: EddsaSignature;
+ }
+
+ .. ts:def:: DenominationKey
+
+ type DenominationKey =
+ | RsaDenominationKey
+ | CSDenominationKey;
+
+ .. ts:def:: RsaDenominationKey
+
+ interface RsaDenominationKey {
+ cipher: "RSA";
+
+ // 32-bit age mask.
+ age_mask: Integer;
+
+ // RSA public key
+ rsa_public_key: RsaPublicKey;
+ }
+
+ .. ts:def:: CSDenominationKey
+
+ interface CSDenominationKey {
+ cipher: "CS";
+
+ // 32-bit age mask.
+ age_mask: Integer;
+
+ // Public key of the denomination.
+ cs_public_key: Cs25519Point;
+
+ }
+
+ Fees for any of the operations can be zero, but the fields must still be
+ present. The currency of the ``fee_deposit``, ``fee_refresh`` and
``fee_refund`` must match the
+ currency of the ``value``. Theoretically, the ``fee_withdraw`` could be in a
+ different currency, but this is not currently supported by the
+ implementation.
+
+ A signing key in the ``signkeys`` list is a JSON object with the following
fields:
+
+ .. ts:def:: SignKey
+
+ interface SignKey {
+ // The actual donau's EdDSA signing public key.
+ key: EddsaPublicKey;
+
+ // Initial validity date for the signing key.
+ stamp_start: Timestamp;
+
+ // Date when the donau will stop using the signing key, allowed to
overlap
+ // slightly with the next signing key's validity to allow for clock skew.
+ stamp_expire: Timestamp;
+
+ // Date when all signatures made by the signing key expire and should
+ // henceforth no longer be considered valid in legal disputes.
+ stamp_end: Timestamp;
+
+ // Signature over ``key`` and ``stamp_expire`` by the donau master key.
+ // Signature of `TALER_DonauSigningKeyValidityPS`.
+ // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
+ master_sig: EddsaSignature;
+ }
+
+
+ .. note::
+
+ Both the individual denominations *and* the denomination list is signed,
+ allowing customers to prove that they received an inconsistent list.
+
+
+
+----------------------------------------------
+Management operations authorized by master key
+----------------------------------------------
+
+.. http:get:: /management/keys
+
+ Get a list of future public keys to be used by the donau. Only to be
+ used by the donau's offline key management team. Not useful for anyone
+ else (but also not secret, so access is public).
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The donau responds with a `FutureKeysResponse` object. This request should
+ virtually always be successful.
+
+ **Details:**
+
+ .. ts:def:: FutureKeysResponse
+
+ interface FutureKeysResponse {
+
+ // Future denominations to be offered by this donau
+ // (only those lacking a master signature).
+ future_denoms: FutureDenom[];
+
+ // The donau's future signing keys (only those lacking a master
signature).
+ future_signkeys: FutureSignKey[];
+
+ // Master public key expected by this donau (provided so that the
+ // offline signing tool can check that it has the right key).
+ master_pub: EddsaPublicKey;
+
+ // Public key of the denomination security module.
+ denom_secmod_public_key: EddsaPublicKey;
+
+ // Public key of the signkey security module.
+ signkey_secmod_public_key: EddsaPublicKey;
+
+ }
+
+ .. ts:def:: FutureDenom
+
+ interface FutureDenom {
+ // Name in the configuration file that defines this denomination.
+ section_name: string;
+
+ // How much are coins of this denomination worth?
+ value: Amount;
+
+ // When does the denomination key become valid?
+ stamp_start: Timestamp;
+
+ // When is it no longer possible to withdraw coins
+ // of this denomination?
+ stamp_expire_withdraw: Timestamp;
+
+ // When is it no longer possible to deposit coins
+ // of this denomination?
+ stamp_expire_deposit: Timestamp;
+
+ // Timestamp indicating by when legal disputes relating to these coins
must
+ // be settled, as the donau will afterwards destroy its evidence
relating to
+ // transactions involving this coin.
+ stamp_expire_legal: Timestamp;
+
+ // Public (RSA) key for the denomination.
+ denom_pub: RsaPublicKey;
+
+ // Fee charged by the donau for withdrawing a coin of this denomination.
+ fee_withdraw: Amount;
+
+ // Fee charged by the donau for depositing a coin of this denomination.
+ fee_deposit: Amount;
+
+ // Fee charged by the donau for refreshing a coin of this denomination.
+ fee_refresh: Amount;
+
+ // Fee charged by the donau for refunding a coin of this denomination.
+ fee_refund: Amount;
+
+ // Signature by the denomination security module
+ // over `TALER_DenominationKeyAnnouncementPS`
+ // for this denomination with purpose
+ // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
+ denom_secmod_sig: EddsaSignature;
+
+ }
+
+ .. ts:def:: FutureSignKey
+
+ interface SignKey {
+ // The actual donau's EdDSA signing public key.
+ key: EddsaPublicKey;
+
+ // Initial validity date for the signing key.
+ stamp_start: Timestamp;
+
+ // Date when the donau will stop using the signing key, allowed to
overlap
+ // slightly with the next signing key's validity to allow for clock skew.
+ stamp_expire: Timestamp;
+
+ // Date when all signatures made by the signing key expire and should
+ // henceforth no longer be considered valid in legal disputes.
+ stamp_end: Timestamp;
+
+ // Signature over `TALER_SigningKeyAnnouncementPS`
+ // for this signing key by the signkey security
+ // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
+ signkey_secmod_sig: EddsaSignature;
+ }
+
+
+.. http:post:: /management/keys
+
+ Provide master signatures for future public keys to be used 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 `MasterSignatures` object.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The request was successfully processed.
+ :http:statuscode:`403 Forbidden`:
+ A provided signature is invalid.
+ :http:statuscode:`404 Not found`:
+ One of the keys for which a signature was provided is unknown to the donau.
+
+ **Details:**
+
+ .. ts:def:: MasterSignatures
+
+ interface MasterSignatures {
+
+ // Provided master signatures for future denomination keys.
+ denom_sigs: DenomSignature[];
+
+ // Provided master signatures for future online signing keys.
+ signkey_sigs: SignKeySignature[];
+
+ }
+
+ .. ts:def:: DenomSignature
+
+ interface DenomSignature {
+
+ // Hash of the public (RSA) key of the denomination.
+ h_denom_pub: HashCode;
+
+ // Signature over `TALER_DenominationKeyValidityPS`.
+ // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY``
+ master_sig: EddsaSignature;
+
+ }
+
+ .. ts:def:: SignKeySignature
+
+ interface SignKeySignature {
+ // The actual donau's EdDSA signing public key.
+ key: EddsaPublicKey;
+
+ // Signature by the donau master key over
+ // `TALER_DonauSigningKeyValidityPS`.
+ // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
+ master_sig: EddsaSignature;
+
+ }
+
+
+.. 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
+----------
+
+This API is used by the wallet to obtain digital coins.
+
+When transferring money to the donau such as via SEPA transfers, the donau
creates
+a *reserve*, which keeps the money from the customer. The customer must
+specify an EdDSA reserve public key as part of the transfer, and can then
+withdraw digital coins using the corresponding private key. All incoming and
+outgoing transactions are recorded under the corresponding public key by the
+donau.
+
+.. note::
+
+ Eventually the donau will need to advertise a policy for how long it will
+ keep transaction histories for inactive or even fully drained reserves. We
+ will therefore need some additional handler similar to ``/keys`` to
+ advertise those terms of service.
+
+
+.. http:get:: /reserves/$RESERVE_PUB
+
+ Request information about a reserve.
+
+ **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.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The donau responds with a `ReserveSummary` object; the reserve was known
to the donau.
+ :http:statuscode:`404 Not found`:
+ The reserve key does not belong to a reserve known to the donau.
+
+ **Details:**
+
+ .. ts:def:: ReserveSummary
+
+ interface ReserveSummary {
+ // 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
+
+ Request information about a reserve or an account.
+
+ **Request:**
+
+ The request body must be a `ReserveStatusRequest` 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_STATUS_REQUEST* signature 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
+
+ interface ReserveStatusRequest {
+ // Signature of purpose
+ // ``TALER_SIGNATURE_RESERVE_STATUS_REQUEST`` over
+ // a `TALER_ReserveStatusRequestSignaturePS`.
+ 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;
+ }
+
+ .. ts:def:: ReserveStatus
+
+ interface ReserveStatus {
+ // Balance left in the reserve.
+ balance: Amount;
+
+ // If set, gives the maximum age group that the client is required to set
+ // during withdrawal.
+ maximum_age_group: number;
+
+ // Transaction history for this reserve.
+ // May be partial (!).
+ history: TransactionHistoryItem[];
+ }
+
+ Objects in the transaction history have the following format:
+
+ .. ts:def:: TransactionHistoryItem
+
+ // 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;
+
+ }
+
+ .. ts:def:: ReserveWithdrawTransaction
+
+ interface ReserveWithdrawTransaction {
+ type: "WITHDRAW";
+
+ // Amount withdrawn.
+ amount: Amount;
+
+ // Hash of the denomination public key of the coin.
+ h_denom_pub: HashCode;
+
+ // Hash of the blinded coin to be signed.
+ h_coin_envelope: HashCode;
+
+ // Signature over a `TALER_WithdrawRequestPS`
+ // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW``
+ // created with the reserve's private key.
+ reserve_sig: EddsaSignature;
+
+ // Fee that is charged for withdraw.
+ 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 {
+ 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:: 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
+~~~~~~~~
+
+.. http:post:: /csr-withdraw
+
+ Obtain donau-side input values in preparation for a
+ withdraw step for certain denomination cipher types,
+ specifically at this point for Clause-Schnorr blind
+ signatures.
+
+ **Request:** The request body must be a `WithdrawPrepareRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The request was successful, and the response is a
`WithdrawPrepareResponse`. Note that repeating exactly the same request
+ will again yield the same response (assuming none of the denomination is
expired).
+ :http:statuscode:`404 Not found`:
+ The denomination key is not known to the donau.
+ :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
+ the error code provided to understand which of the
+ cases this is and handle it accordingly.
+
+ **Details:**
+
+ .. ts:def:: WithdrawPrepareRequest
+
+ interface WithdrawPrepareRequest {
+
+ // Nonce to be used by the donau to derive
+ // its private inputs from. Must not have ever
+ // been used before.
+ nonce: CSNonce;
+
+ // Hash of the public key of the denomination the
+ // request relates to.
+ denom_pub_hash: HashCode;
+
+ }
+
+ .. ts:def:: WithdrawPrepareResponse
+
+ type WithdrawPrepareResponse =
+ | DonauWithdrawValue;
+
+ .. ts:def:: DonauWithdrawValue
+
+ type DonauWithdrawValue =
+ | DonauRsaWithdrawValue
+ | DonauCsWithdrawValue;
+
+ .. ts:def:: DonauRsaWithdrawValue
+
+ interface DonauRsaWithdrawValue {
+ cipher: "RSA";
+ }
+
+ .. ts:def:: DonauCsWithdrawValue
+
+ interface DonauCsWithdrawValue {
+ cipher: "CS";
+
+ // CSR R0 value
+ r_pub_0: CsRPublic;
+
+ // CSR R1 value
+ r_pub_1: CsRPublic;
+ }
+
+
+
+Batch Withdraw
+~~~~~~~~~~~~~~
+
+
+.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw
+
+ Withdraw multiple coins from the same reserve. Note that the client should
+ commit all of the request details, including the private key of the coins and
+ the blinding factors, to disk *before* issuing this request, so that it can
+ recover the information if necessary in case of transient failures, like
+ power outage, network outage, etc.
+
+ **Request:** The request body must be a `BatchWithdrawRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The request was successful, and the response is a `BatchWithdrawResponse`.
+ Note that repeating exactly the same request will again yield the same
+ response, so if the network goes down during the transaction or before the
+ client can commit the coin signature to disk, the coin is not lost.
+ :http:statuscode:`403 Forbidden`:
+ A signature is invalid.
+ This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`404 Not found`:
+ 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`.
+ 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``
+ :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
+ 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:**
+
+ .. ts:def:: BatchWithdrawRequest
+
+ interface BatchWithdrawRequest {
+ // Array of requests for the individual coins to withdraw.
+ planchets: WithdrawRequest[];
+
+ }
+
+
+ .. ts:def:: BatchWithdrawResponse
+
+ interface BatchWithdrawResponse {
+ // Array of blinded signatures, in the same order as was
+ // given in the request.
+ ev_sigs: WithdrawResponse[];
+
+ }
+
+-------
+Deposit
+-------
+
+Deposit operations are requested f.e. by a merchant during a transaction or a
+bidder during an auction.
+
+For the deposit operation during purchase, the merchant has to obtain the
+deposit permission for a coin from their customer who owns the coin. When
+depositing a coin, the merchant is credited an amount specified in the deposit
+permission, possibly a fraction of the total coin's value, minus the deposit
+fee as specified by the coin's denomination.
+
+For auctions, a bidder performs an deposit operation and provides all relevant
+information for the auction policy (such as timeout and public key as bidder)
+and can use the ``donau_sig`` field from the `DepositSuccess` message as a
+proof to the seller for the escrow of sufficient fund.
+
+
+.. _deposit:
+
+.. http:POST:: /batch-deposit
+
+ Deposit multiple coins and ask the donau to transfer the given :ref:`amount`
+ into the merchant's bank account. This API is used by the merchant to redeem
+ the digital coins.
+
+ **Request:**
+
+ The request body must be a `BatchDepositRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The operation succeeded, the donau confirms that no double-spending took
+ place. The response will include a `BatchDepositSuccess` object.
+ :http:statuscode:`403 Forbidden`:
+ One of the signatures is invalid.
+ This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`404 Not found`:
+ 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`.
+ :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
+ previously used with a different denomination.
+ Which case it is
+ can be decided by looking at the error code
+ (``TALER_EC_DONAU_DEPOSIT_CONFLICTING_CONTRACT`` (same coin used in
different ways),
+ ``TALER_EC_DONAU_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient) or
+ ``TALER_EC_DONAU_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``
+ (same coin public key, but different denomination)).
+ The fields of the response are still evolving (see bug 7267),
+ for now the format of the response is a `DepositDoubleSpendError`.
+ The request should not be repeated again with this coin.
+ :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
+ the error code provided to understand which of the
+ cases this is and handle it accordingly.
+
+ **Details:**
+
+ .. ts:def:: BatchDepositRequest
+
+ 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;
+ }
+
+ .. ts:def:: BatchDepositRequestCoin
+
+ interface BatchDepositRequestCoin {
+ // EdDSA public key of the coin being deposited.
+ coin_pub: EddsaPublicKey;
+
+ // Hash of denomination RSA key with which the coin is signed.
+ 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;
+
+ // Signature over `TALER_DepositRequestPS`, made by the customer with the
+ // `coin's private key <coin-priv>`.
+ coin_sig: EddsaSignature;
+ }
+
+ The deposit operation succeeds if the coin is valid for making a deposit and
+ has enough residual value that has not already been deposited or melted.
+
+ .. 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.
+ donau_timestamp: Timestamp;
+
+ // `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
+ // explicitly as the client might otherwise be confused by clock skew as
to
+ // 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
+ // `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;
+ }
+
+
--
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: donau draft, first cut,
gnunet <=