diff options
Diffstat (limited to 'core/api-exchange.rst')
| -rw-r--r-- | core/api-exchange.rst | 2894 |
1 files changed, 2328 insertions, 566 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 1aae8e75..db192e07 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2021 Taler Systems SA + Copyright (C) 2014-2022 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 @@ -15,59 +15,18 @@ @author Christian Grothoff -============================= -The Exchange RESTful JSON API -============================= +======================== +The Exchange 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. -.. _keys: - --------------------- -Terms of service API --------------------- - -These APIs allow merchants and wallets to obtain the terms of service -and the privacy policy of an exchange. - - -.. http:get:: /terms - - Get the terms of service of the exchange. - The exchange will consider the "Accept" and "Accept-Language" and - "Accept-Encoding" headers when generating a response. Specifically, - it will try to find a response with an acceptable mime-type, then - pick the version in the most preferred language of the user, and - finally apply compression if that is allowed by the client and - deemed beneficial. - - The exchange will set an "Etag", and subsequent requests of the - same client should provide the tag in an "If-None-Match" header - to detect if the terms of service have changed. If not, a - "204 Not Modified" response will be returned. - - If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the terms of service were not configured correctly. - - -.. http:get:: /privacy - - Get the privacy policy of the exchange. - The exchange will consider the "Accept" and "Accept-Language" and - "Accept-Encoding" headers when generating a response. Specifically, - it will try to find a response with an acceptable mime-type, then - pick the version in the most preferred language of the user, and - finally apply compression if that is allowed by the client and - deemed beneficial. +.. include:: tos.rst - The exchange will set an "Etag", and subsequent requests of the - same client should provide the tag in an "If-None-Match" header - to detect if the privacy policy has changed. If not, a - "204 Not Modified" response will be returned. - - If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the privacy policy was not configured correctly. +.. _keys: --------------------------- Exchange status information @@ -120,9 +79,17 @@ possibly by using HTTPS. // The format is "current:revision:age". version: string; - // The exchange's currency. + // The exchange's base URL. + base_url: string; + + // The exchange's currency or asset unit. currency: string; + // Type of the asset. "fiat", "crypto", "regional" + // or "stock". Wallets should adjust their UI/UX + // based on this value. + asset_type: string; + // EdDSA master public key of the exchange, used to sign entries // in ``denoms`` and ``signkeys``. master_public_key: EddsaPublicKey; @@ -131,16 +98,30 @@ possibly by using HTTPS. // not signed (!), can change without notice. reserve_closing_delay: RelativeTime; + // Threshold amounts beyond which wallet should + // trigger the KYC process of the issuing + // exchange. Optional option, if not given there is no limit. + // Currency must match ``currency``. + wallet_balance_limit_without_kyc?: Amount[]; + // Denominations offered by this exchange. + // DEPRECATED: Will eventually be replaced by the + // differently structured "denominations" field. denoms: Denom[]; + // Denominations offered by this exchange + denominations: DenomGroup[]; + + // Compact EdDSA `signature` (binary-only) over the XOR of all + // .hash fields (in binary) in the list "denominations". + // Signature of `TALER_ExchangeKeySetPS` + denominations_sig: EddsaSignature; + // Denominations for which the exchange currently offers/requests recoup. recoup: Recoup[]; - // Fees relevant for wallet-to-wallet (or peer-to-peer) payments. - // If no fees are provided for a given time range, then the - // exchange simply does not support purses/p2p-payments at that time. - p2p_fees: P2PFees[]; + // Array of globally applicable fees by time range. + global_fees: GlobalFees[]; // The date when the denomination keys were last updated. list_issue_date: Timestamp; @@ -151,6 +132,15 @@ possibly by using HTTPS. // The exchange's signing keys. signkeys: SignKey[]; + // Optional field with a dictionary of (name, object) pairs defining the + // supported and enabled extensions, such as ``age_restriction``. + extensions?: { name: ExtensionManifest }; + + // Signature by the exchange master key of the SHA-256 hash of the + // normalized JSON-object of field extensions, if it was set. + // The signature has purpose TALER_SIGNATURE_MASTER_EXTENSIONS. + extensions_sig?: EddsaSignature; + // 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 @@ -161,6 +151,7 @@ possibly by using HTTPS. // different users. If an exchange were to do this, this signature allows the // clients to demonstrate to the public that the exchange is dishonest. // Signature of `TALER_ExchangeKeySetPS` + // DEPRICATED: Will eventually replaced by "denominations_sig" eddsa_sig: EddsaSignature; // Public EdDSA key of the exchange that was used to generate the signature. @@ -170,13 +161,9 @@ possibly by using HTTPS. eddsa_pub: EddsaPublicKey; } - .. ts:def:: P2PFees + .. ts:def:: GlobalFees - .. note:: - - This is a draft API that is not yet implemented. - - interface P2PFees { + interface GlobalFees { // What date (inclusive) does these fees go into effect? start_date: Timestamp; @@ -184,15 +171,9 @@ possibly by using HTTPS. // What date (exclusive) does this fees stop going into effect? end_date: Timestamp; - // KYC fee, charged when a user wants to create an account. - // The first year of the account_annual_fee after the KYC is - // always included. - kyc_fee: Amount; - // Account history fee, charged when a user wants to - // obtain the full account history, and not just the - // recent transactions in an account. - account_history_fee: Amount; + // obtain a reserve/account history. + history_fee: Amount; // Annual fee charged for having an open account at the // exchange. Charged to the account. If the account @@ -200,24 +181,17 @@ possibly by using HTTPS. // is automatically deleted/closed. (Note that the exchange // will keep the account history around for longer for // regulatory reasons.) - account_annual_fee: Amount; - - // How long will the exchange preserve the account history? - // After an account was deleted/closed, the exchange will - // retain the account history for legal reasons until this time. - legal_history_retention: RelativeTime; - - // How long does the exchange promise to keep funds - // an account for which the KYC has never happened - // after a purse was merged into an account? Basically, - // after this time funds in an account without KYC are - // forfeit. - account_kyc_timeout: RelativeTime; + account_fee: Amount; // Purse fee, charged only if a purse is abandoned // and was not covered by the account limit. purse_fee: Amount; + // How long will the exchange preserve the account history? + // After an account was deleted/closed, the exchange will + // retain the account history for legal reasons until this time. + history_expiration: RelativeTime; + // Non-negative number of concurrent purses that any // account holder is allowed to create without having // to pay the purse_fee. @@ -229,9 +203,120 @@ possibly by using HTTPS. // plus this value. purse_timeout: RelativeTime; - // Signature of `TALER_P2PFeesPS`. + // Signature of `TALER_GlobalFeesPS`. + master_sig: EddsaSignature; + + } + + + .. ts:def:: AgeMask + + // Binary representation of the age groups. + // The bits set in the mask mark the edges at the beginning of a next age + // group. F.e. for the age groups + // 0-7, 8-9, 10-11, 12-13, 14-15, 16-17, 18-21, 21-* + // the following bits are set: + // + // 31 24 16 8 0 + // | | | | | + // oooooooo oo1oo1o1 o1o1o1o1 ooooooo1 + // + // A value of 0 means that the exchange does not support the extension for + // age-restriction. + type AgeMask = Integer; + + .. ts:def:: DenomGroup + + type DenomGroup = + | DenomGroupRsa + | DenomGroupCs + | DenomGroupRsaAgeRestricted + | DenomGroupCsAgeRestricted; + + .. 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:: DenomGroupRsaAgeRestricted + + interface DenomGroupRsaAgeRestricted extends DenomGroupCommon { + cipher: "RSA+age_restricted"; + age_mask: AgeMask; + + denoms: ({ + rsa_pub: RsaPublicKey; + } & DenomCommon)[]; + } + + .. ts:def:: DenomGroupCsAgeRestricted + + interface DenomGroupCSAgeRestricted extends DenomGroupCommon { + cipher: "CS+age_restricted"; + age_mask: AgeMask; + + 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; + + // Fee charged by the exchange for withdrawing a coin of this denomination. + fee_withdraw: Amount; + + // Fee charged by the exchange for depositing a coin of this denomination. + fee_deposit: Amount; + + // Fee charged by the exchange for refreshing a coin of this denomination. + fee_refresh: Amount; + + // 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 + + 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 exchange will afterwards destroy its evidence relating to + // transactions involving this coin. + stamp_expire_legal: Timestamp; } .. ts:def:: Denom @@ -252,8 +337,8 @@ possibly by using HTTPS. // transactions involving this coin. stamp_expire_legal: Timestamp; - // Public (RSA) key for the denomination. - denom_pub: RsaPublicKey; + // Public key for the denomination. + denom_pub: DenominationKey; // Fee charged by the exchange for withdrawing a coin of this denomination. fee_withdraw: Amount; @@ -271,6 +356,37 @@ possibly by using HTTPS. 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 @@ -385,7 +501,7 @@ possibly by using HTTPS. // incoming wire transfers. accounts: WireAccount[]; - // Object mapping names of wire methods (i.e. "sepa" or "x-taler-bank") + // Object mapping names of wire methods (i.e. "iban" or "x-taler-bank") // to wire fees. fees: { method : AggregateTransferFee }; @@ -422,6 +538,9 @@ possibly by using HTTPS. // Per transfer closing fee. closing_fee: Amount; + // Per exchange-to-exchange transfer (wad) fee. + wad_fee: Amount; + // What date (inclusive) does this fee go into effect? // The different fees must cover the full time period in which // any of the denomination keys are valid without overlap. @@ -446,9 +565,6 @@ possibly by using HTTPS. // Public master key of the partner exchange. partner_master_pub: EddsaPublicKey; - // Wallet-to-wallet transfer wad fee charged. - wad_fee: Amount; - // Exchange-to-exchange wad (wire) transfer frequency. wad_frequency: RelativeTime; @@ -832,6 +948,23 @@ Management operations authorized by master key } +.. http:post:: /management/global-fees + + Provides global fee configuration for a timeframe. + + **Request:** + + The request must be a `GlobalFees` message. + + **Response** + + :http:statuscode:`204 No content`: + The configuration update has been processed successfully. The body is empty. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + :http:statuscode:`409 Conflict`: + The exchange has previously received a conflicting configuration message. + .. http:post:: /management/wire @@ -928,26 +1061,51 @@ Management operations authorized by master key } -.. http:post:: /management/p2pfees - - Provides fee configuration for purses. +.. http:post:: /management/drain - .. note:: - - This is a draft API that is not yet implemented. + This request is used to drain profits from the + exchange's escrow account to another regular + bank account of the exchange. The actual drain + requires running the ``taler-exchange-drain`` tool. **Request:** - The request must be a `P2PFees` message. + The request must be a `DrainProfitsMessage`. - **Response** + **Response:** :http:statuscode:`204 No content`: - The configuration update has been processed successfully. The body is empty. + The profit drain was scheduled. :http:statuscode:`403 Forbidden`: - The signature is invalid. - :http:statuscode:`409 Conflict`: - The exchange has previously received a conflicting configuration message. + The master signature is invalid. + + **Details:** + + .. ts:def:: DrainProfitsMessage + + interface DrainProfitsMessage { + + // Configuration section of the account to debit. + debit_account_section: string; + + // Credit payto URI + credit_payto_uri: string; + + // Wire transfer identifier to use. + wtid: Base32; + + // Signature by the exchange master key over a + // `TALER_MasterDrainProfitPS`. + // Must have purpose ``TALER_SIGNATURE_MASTER_DRAIN_PROFITS``. + master_sig: EddsaSignature; + + // When was the message created. + date: Timestamp; + + // Amount to be drained. + amount: Amount; + + } .. http:post:: /management/partners @@ -1062,10 +1220,43 @@ exchange. .. note:: - Eventually the exchange will need to advertize a policy for how long it will + Eventually the exchange 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 - advertize those terms of service. + advertise those terms of service. + + +.. http:get:: /reserves/$RESERVE_PUB + + Request information about a reserve. + + **Request:** + + :query timeout_ms=MILLISECONDS: *Optional.* If specified, the exchange 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 exchange responds with a `ReserveSummary` object; the reserve was known to the exchange. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + + **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 exchange's output to /keys. + maximum_age_group?: number; + } .. http:post:: /reserves/$RESERVE_PUB/status @@ -1074,24 +1265,15 @@ exchange. **Request:** - :query history=BOOLEAN: *Optional.* If specified, the exchange - will return the recent account history. - This is still free of charge. - :query full_history=BOOLEAN: *Optional.* If 'true' is specified, - the exchange will return the full account history. This - may incur a fee that will be charged to the account. - The request body must be a `ReserveStatusRequest` object. **Response:** :http:statuscode:`200 OK`: The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange. - :http:statuscode:`401 Unauthorized`: - The *Account-Request-Signature* is invalid. - This response comes with a standard `ErrorDetail` response. :http:statuscode:`403 Forbidden`: - The provided timestamp is not close to the current time. + 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 exchange. @@ -1118,13 +1300,9 @@ exchange. // Balance left in the reserve. balance: Amount; - // True if the owner of the account currently satisfies - // the required KYC checks. - kyc_passed: boolean; - - // True if the reserve history includes a merge of a purse - // and thus the owner must pass KYC checks before withdrawing. - kyc_required: boolean; + // 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 (!). @@ -1141,9 +1319,60 @@ exchange. | AccountSetupTransaction | ReserveHistoryTransaction | ReserveWithdrawTransaction + | ReserveAgeWithdrawTransaction | ReserveCreditTransaction | ReserveClosingTransaction - | ReserveRecoupTransaction; + | ReserveOpenRequestTransaction + | ReserveCloseRequestTransaction + | PurseMergeTransaction; + + .. 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; + } .. ts:def:: ReserveHistoryTransaction @@ -1151,7 +1380,7 @@ exchange. type: "HISTORY"; // Fee agreed to by the reserve owner. - history_fee: Amount; + amount: Amount; // Time when the request was made. request_timestamp: Timestamp; @@ -1183,7 +1412,7 @@ exchange. // Signature created with the reserve's private key. // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` over - // a `TALER_AccountSetupRequestSignaturePS`. + // a ``TALER_AccountSetupRequestSignaturePS``. reserve_sig: EddsaSignature; } @@ -1252,6 +1481,26 @@ exchange. withdraw_fee: Amount; } + .. ts:def:: ReserveAgeWithdrawTransaction + + interface ReserveAgeWithdrawTransaction { + type: "AGEWITHDRAW"; + + // Total Amount withdrawn. + amount: Amount; + + // Commitment of all ``n*kappa`` coins. + age_restricted_coins_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 @@ -1285,7 +1534,7 @@ exchange. closing_fee: Amount; // Wire transfer subject. - wtid: string; + wtid: Base32; // ``payto://`` URI of the wire account into which the funds were returned to. receiver_account_details: string; @@ -1303,27 +1552,64 @@ exchange. } - .. ts:def:: ReserveRecoupTransaction + .. ts:def:: ReserveOpenRequestTransaction - interface ReserveRecoupTransaction { - type: "RECOUP"; + interface ReserveOpenRequestTransaction { + type: "OPEN"; - // Amount paid back. - amount: Amount; + // Open fee paid from the reserve. + open_fee: Amount; // This is a signature over - // a struct `TALER_RecoupConfirmationPS` with purpose - // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``. - exchange_sig: EddsaSignature; + // a struct `TALER_ReserveOpenPS` with purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN``. + reserve_sig: EddsaSignature; - // Public key used to create 'exchange_sig'. - exchange_pub: EddsaPublicKey; + // Timestamp of the open request. + request_timestamp: Timestamp; - // Time when the funds were paid back into the reserve. - timestamp: Timestamp; + // Requested expiration. + requested_expiration: Timestamp; - // Public key of the coin that was paid back. - coin_pub: CoinPublicKey; + // 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?: string; + + // 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 exchange that + // uniquely identifies the wire transfer that credited the reserve. + wire_reference: Integer; + + // Timestamp of the incoming wire transfer. + timestamp: Timestamp; } @@ -1340,11 +1626,9 @@ exchange. :http:statuscode:`200 OK`: The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange. - :http:statuscode:`401 Unauthorized`: - The *Account-Request-Signature* is invalid. - This response comes with a standard `ErrorDetail` response. :http:statuscode:`403 Forbidden`: - 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 exchange. :http:statuscode:`412 Precondition failed`: @@ -1369,6 +1653,138 @@ exchange. } +.. _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 exchange + will delete the account even if there is a balance remaining. + + **Response:** + + :http:statuscode:`200 OK`: + The operation succeeded, the exchange 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 exchange. + :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 exchange, used as part of + // what the exchange 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 exchange. + h_wire: HashCode; + + // This is a signature over a + // struct ``TALER_AccountDeleteConfirmationPS`` with purpose + // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``. + exchange_sig: EddsaSignature; + + } + + + +Withdraw +~~~~~~~~ + +.. http:post:: /csr-withdraw + + Obtain exchange-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 exchange. + :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 exchange 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 + | ExchangeWithdrawValue; + + .. ts:def:: ExchangeWithdrawValue + + type ExchangeWithdrawValue = + | ExchangeRsaWithdrawValue + | ExchangeCsWithdrawValue; + + .. ts:def:: ExchangeRsaWithdrawValue + + interface ExchangeRsaWithdrawValue { + cipher: "RSA"; + } + + .. ts:def:: ExchangeCsWithdrawValue + + interface ExchangeCsWithdrawValue { + cipher: "CS"; + + // CSR R0 value + r_pub_0: CsRPublic; + + // CSR R1 value + r_pub_1: CsRPublic; + } + + .. http:post:: /reserves/$RESERVE_PUB/withdraw Withdraw a coin of the specified denomination. Note that the client should @@ -1386,27 +1802,9 @@ exchange. 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:`202 Accepted`: - 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. - :http:statuscode:`403 Forbidden`: The signature is invalid. + This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The denomination key or the reserve are not known to the exchange. If the denomination key is unknown, this suggests a bug in the wallet as the @@ -1426,6 +1824,25 @@ exchange. `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:** @@ -1481,19 +1898,54 @@ exchange. .. ts:def:: WithdrawResponse interface WithdrawResponse { - // The blinded RSA signature over the 'coin_ev', affirms the coin's + // The blinded signature over the 'coin_ev', affirms the coin's // validity after unblinding. - ev_sig: BlindedRsaSignature; + ev_sig: BlindedDenominationSignature; + + } + + .. ts:def:: BlindedDenominationSignature + + type BlindedDenominationSignature = + | RsaBlindedDenominationSignature + | CSBlindedDenominationSignature; + + .. ts:def:: RsaBlindedDenominationSignature + + interface RsaBlindedDenominationSignature { + cipher: "RSA"; + + // (blinded) RSA signature + blinded_rsa_signature: BlindedRsaSignature; + } + + .. ts:def:: CSBlindedDenominationSignature + + interface CSBlindedDenominationSignature { + type: "CS"; + + // Signer chosen bit value, 0 or 1, used + // in Clause Blind Schnorr to make the + // ROS problem harder. + b: Integer; + + // Blinded scalar calculated from c_b. + s: Cs25519Scalar; } .. ts:def:: KycNeededRedirect interface KycNeededRedirect { - // Payment target that the merchant should + + // Hash of the payto:// account URI that identifies + // the account which is being KYCed. + h_payto: PaytoHash; + + // Legitimization target that the merchant should // use to check for its KYC status using - // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint. - payment_target_uuid: Integer; + // the ``/kyc-check/$REQUIREMENT_ROW/...`` endpoint. + requirement_row: Integer; } @@ -1510,80 +1962,323 @@ exchange. balance: Amount; // History of the reserve's activity, in the same format - // as returned by ``/reserve/status``. + // as returned by ``/reserve/$RID/history``. history: TransactionHistoryItem[] } -.. _delete-reserve: -.. http:DELETE:: /reserves/$RESERVE_PUB - Forcefully closes a reserve. - The request header must contain an *Account-Request-Signature*. - **Request:** +Batch Withdraw +~~~~~~~~~~~~~~ - *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 exchange - will delete the account even if there is a balance remaining. +.. 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 operation succeeded, the exchange provides details - about the account deletion. - The response will include a `ReserveClosedResponse` object. - :http:statuscode:`401 Unauthorized`: - The *Account-Request-Signature* is invalid. + 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`: - The account is unknown to the exchange. + A denomination key or the reserve are not known to the exchange. 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 exchange 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`: - 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. + The balance of the reserve is not sufficient to withdraw the coins of the + indicated denominations. The response is `WithdrawError` object. + :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:: ReserveClosedResponse + .. ts:def:: BatchWithdrawRequest - interface ReserveClosedResponse { + interface BatchWithdrawRequest { + // Array of requests for the individual coins to withdraw. + planchets: WithdrawRequest[]; - // Final balance of the account. - closing_amount: Amount; + } - // Current time of the exchange, used as part of - // what the exchange 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 exchange. - h_wire: HashCode; + .. ts:def:: BatchWithdrawResponse - // This is a signature over a - // struct ``TALER_AccountDeleteConfirmationPS`` with purpose - // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``. + interface BatchWithdrawResponse { + // Array of blinded signatures, in the same order as was + // given in the request. + ev_sigs: WithdrawResponse[]; + + } + +Withdraw with Age Restriction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the reserve was marked with a maximum age group, the client has to perform a +cut&choose protocol with the exchange. It first calls +``/reserves/$RESERVE_PUB/age-withdraw`` and commits to ``n*kappa`` coins. On +success, the exchange answers this request with an noreveal-index. The client +then has to call ``/age-withdraw/$ACH/reveal`` to reveal all ``n*(kappa - 1)`` +coins along with their age commitments to proof that they were appropriate. +If so, the exchange will blindly sign ``n`` undisclosed coins from the request. + + +.. http:POST:: /reserves/$RESERVE_PUB/age-withdraw + + Withdraw multiple coins *with age restriction* 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 `AgeWithdrawRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `AgeWithdrawResponse`. + 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:`409 Conflict`: + The balance of the reserve is not sufficient to withdraw the coins of the + given amount. The response is a `WithdrawError` object. + :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. + + .. ts:def:: AgeWithdrawRequest + + interface AgeWithdrawRequest { + // Commitment to the coins with age restriction. This is the SHA512 + // hash value $ACH over all n*kappa `BlindedCoinHash` values of all + // coins and their age commitments. It is alter used as part of the URL + // in the subsequent call to /age-withdraw/$ACH/reveal. + age_restricted_coins_commitment: HashCode; + + // The total amount that the client wants to withdraw from the reserve + // and must be at most the balance of the reserve. The balance of the + // reserve will be immediatley reduced by that amount. + // In the subsequent call to /age-withdraw/$ACH/reveal, the client has to + // provide the list of denominations (with support for age restriction) + // that the coins shall be signed with. The sum of the values of those + // denominations MUST equal this amount. + amount: Amount; + + // The maximum age group to commit to. MUST be the same as the maximum + // age group in the reserve. + max_age_group: number; + + // Signature of `TALER_AgeWithdrawRequestPS` created with + // the `reserves's private key <reserve-priv>` + // using purpose ``TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW``. + reserve_sig: EddsaSignature; + } + + .. ts:def:: AgeWithdrawResponse + + interface AgeWithdrawResponse { + // index of the commitments that the client doesn't + // have to disclose + noreveal_index: Integer; + + // Signature of `TALER_AgeWithdrawRequestPS` whereby + // the exchange confirms the ``noreveal_index``. exchange_sig: EddsaSignature; + // `Public EdDSA key <sign-key-pub>` of the exchange that was used to + // generate the signature. Should match one of the exchange's signing + // keys from ``/keys``. Again given explicitly as the client might + // otherwise be confused by clock skew as to which signing key was used. + exchange_pub: EddsaPublicKey; } +.. http:POST:: /age-withdraw/$ACH/reveal + + The client has previously committed to multiple coins with age restriction + in a call to ``/reserve/$RESERVE_PUB/age-withdraw`` and got a + `AgeWithdrawResponse` from the exchange. By calling this + endpoint, the client has to reveal each coin and their ``kappa - 1`` + age commitments, except for the age commitments with index + ``noreveal_index``. The hash of all commitments from the former withdraw + request is given as the ``$ACH`` value in the URL to this endpoint. + + + **Request:** The request body must be a `AgeWithdrawRevealRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `BlindedSignaturesResponse`. + 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:`404 Not found`: + The provided commitment $ACH is unknown. + :http:statuscode:`409 Conflict`: + The reveal operation failed and the response is an `WithdrawError` object. + The error codes indicate one of two cases: + + 1. An age commitment for one of the coins did not fulfill the required + maximum age requirement of the corresponding reserve. Error code: + ``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``. + 2. The sum of all denominations in the request is not equal to the amount + that was given in the previous commitment via the call to + /reserves/$RESERVE_PUB/age-withdraw. Error code: + ``TALER_EC_EXCHANGE_GENERIC_MISMATCH_OF_AMOUNT_AND_DENOMINATIONS``. + + + .. ts:def:: AgeWithdrawRevealRequest + + interface AgeWithdrawRevealRequest { + // The public key of the reserve that was used for the initial commitment + // request. Needed for optimized database lookup. + reserve_pub: EddsaPublicKey; + + // Array of ``n`` hash codes of denomination public keys to order. + // These denominations MUST support age restriction as defined in the + // output to /keys. + // The sum of all denomination's values MUST equal the original amount + // of the previous commitment. + denoms_h: HashCode[]; + + // Array of ``n`` entries with blinded coins, which are the non-desclosed + // coins in the previous commitment. They match the respective entries + // in ``denoms_h``. + coin_evs: CoinEnvelope[]; + + // Array of ``n`` arrays of ``kappa - 1`` disclosed coin private keys, + // from which the associated age commitments are also derived. + disclosed_coins: DisclosedAgeRestrictedCoin[][]; + + } + + .. ts:def:: DisclosedAgeRestrictedCoin + + interface DisclosedAgeRestrictedCoin { + // A coin's private key. The associated blinding and age commitment for + // this coin MUST be derived from this private key as follows: + // + // Calculate the blinding beta as + // beta := HKDF(coin_priv, "blinding") + // + // If the denominations are for Clause-Schnorr-Signatures, calculate the + // nonce as + // nonce := HKDF(coin_priv, "cs-nonce") + // + // Let m ∈ {1,...,M} be the maximum age group as defined in the reserve + // that the wallet can commit to. + // + // For age group $AG ∈ {1,...m}, set + // seed = HDKF(coin_priv, "age-commitment", $AG) + // p[$AG] = Edx25519_generate_private(seed) + // and calculate the corresponding Edx25519PublicKey as + // q[$AG] = Edx25519_public_from_private(p[$AG]) + // + // For age groups $AG ∈ {m,...,M}, set + // f[$AG] = HDKF(coin_priv, "age-factor", $AG) + // and calculate the corresponding Edx25519PublicKey as + // q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG]) + // + // Finally, with coin_priv and age commitment (q[]), the exchange + // will calculate the coin's public key coin_pub and use the + // TALER_CoinPubHashP(coin_pub, age_commitment_hash(q)) + // during the verification of the original age-withdraw-commitment. + coin_priv: EddsaPrivateKey; + + } + + .. ts:def:: PublishedAgeRestrictionBaseKey + + // The value for ``PublishedAgeRestrictionBaseKey`` is a randomly chosen + // `Edx25519PublicKey` for which the private key is not known to the clients. It is + // used during the age-withdraw protocol so that clients can proof that they + // derived all public keys to age groups higher than their allowed maximum + // from this particular value. + const PublishedAgeRestrictionBaseKey = + new Edx25519PublicKey("DZJRF6HXN520505XDAWM8NMH36QV9J3VH77265WQ09EBQ76QSKCG"); + + + .. _deposit-par: ------- Deposit ------- -Deposit operations are requested by a merchant during a transaction. For the -deposit operation, 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. +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 ``exchange_sig`` field from the `DepositSuccess` message as a +proof to the seller for the escrow of sufficient fund. + .. _deposit: @@ -1606,8 +2301,9 @@ denomination. :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that no double-spending took place. The response will include a `DepositSuccess` object. - :http:statuscode:`401 Unauthorized`: + :http:statuscode:`403 Forbidden`: One of the signatures is invalid. + This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: Either the denomination key is not recognized (expired or invalid), or the wire type is not recognized. @@ -1618,7 +2314,8 @@ denomination. residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is can be decided by looking at the error code - (``TALER_EC_EXCHANGE_DEPOSIT_INSUFFICIENT_FUNDS`` or ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). + (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). The fields of the response are the same in both cases. The request should not be repeated again with this coin. In this case, the response is a `DepositDoubleSpendError`. @@ -1639,16 +2336,12 @@ denomination. contribution: Amount; // The merchant's account details. + // In case of an auction policy, it refers to the seller. + merchant_payto_uri: string; + // The salt is used to hide the ``payto_uri`` from customers - // that learn the ``h_wire`` of the merchant. - wire: { - payto_uri: string; - salt: HashCode; - }; - - // SHA-512 hash of the merchant's payment details from ``wire``. Although - // strictly speaking redundant, this helps detect inconsistencies. - h_wire: HashCode; + // 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 exchange. @@ -1657,29 +2350,217 @@ denomination. // Hash of denomination RSA key with which the coin is signed. denom_pub_hash: HashCode; + // IFF the corresponding denomination has support for + // age restriction enabled, this field MUST contain the SHA256 + // value of the age commitment that MUST have been provided during the + // purchase. + age_commitment_hash?: AgeCommitmentHash; + // Exchange's unblinded RSA signature of the coin. - ub_sig: RsaSignature; + ub_sig: DenominationSignature; // Timestamp when the contract was finalized. timestamp: Timestamp; // Indicative time by which the exchange undertakes to transfer the funds to - // the merchant, in case of successful payment. + // 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. + // + // THIS FIELD WILL BE DEPRICATED, once the refund mechanism becomes a + // policy via extension. merchant_pub: EddsaPublicKey; // Date until which the merchant can issue a refund to the customer via the // exchange, 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 deposit. + // This might be a refund, auction or escrow policy. + // + // Note that support for policies is an optional feature of the exchange. + // Optional features are so called "extensions" in Taler. The exchange + // provides the list of supported extensions, including policies, in the + // `ExtensionsManifestsResponse` response to the ``/keys`` endpoint. + policy?: DepositPolicy; + // Signature over `TALER_DepositRequestPS`, made by the customer with the // `coin's private key <coin-priv>`. coin_sig: EddsaSignature; } + .. ts:def:: DenominationSignature + + type DenominationSignature = + | RsaDenominationSignature + | CSDenominationSignature; + + .. ts:def:: RsaDenominationSignature + + interface RsaDenominationSignature { + cipher: "RSA"; + + // RSA signature + rsa_signature: RsaSignature; + } + + .. ts:def:: CSDenominationSignature + + interface CSDenominationSignature { + type: "CS"; + + // R value component of the signature. + cs_signature_r: Cs25519Point; + + // s value component of the signature. + cs_signature_s: Cs25519Scalar: + + } + + .. ts:def:: DepositPolicy + + type DepositPolicy = + | PolicyMerchantRefund + | PolicyBrandtVickreyAuction + | PolicyEscrowedPayment; + + .. ts:def:: PolicyMerchantRefund + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyMerchantRefund { + type: "merchant_refund"; + + // 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 ``/extensions/policy_refund``-endpoint of the exchange. + deadline: Timestamp; + } + + .. ts:def:: PolicyBrandtVickreyAuction + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyBrandtVickreyAuction { + type: "brandt_vickrey_auction"; + + // Public key of this bidder. + // + // The bidder uses this key to sign the auction information and + // the messages it sends to the seller during the auction. + bidder_pub: EddsaPublicKey; + + // Hash of the auction terms + // + // The hash should be taken over a normalized JSON object of type + // `BrandtVickreyAuction`. + h_auction: HashCode; + + // The amount that this bidder commits to for this auction + // + // This amount can be larger than the contribution of a single coin. + // The bidder can increase funding of this auction policy by using + // sufficiently many coins during the deposit operation (single or batch) + // with the same policy. + commitment: Amount; + + // Date until the auction must have been successfully executed and + // a valid transcript provided to the + // ``/extensions/policy_brandt_vickrey_auction``-endpoint of the + // exchange. + // + // [If the auction has not been executed by then] OR [has been executed + // before then, but this bidder did not win], the coin's value doesn't + // change and the owner can refresh the coin. + // + // If this bidder won the auction, the winning price/amount from the + // outcome will be substracted from the coin and transfered to the + // merchant's ``payout_uri`` from the deposit request (minus a potential + // auction fee). For any remaining value, the bidder can refresh the + // coin to retrieve change. + deadline: Timestamp; + } + + .. ts:def:: BrandtVickreyAuction + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This structure defines an auction of Brandt-Vickory kind. + // It is used for the `PolicyBrandtVickreyAuction`. + interface BrandtVickreyAuction { + // Start date of the auction + time_start: Timestamp; + + // Maximum duration per round. There are four rounds in an auction of + // Brandt-Vickrey kind. + time_round: RelativeTime; + + // This integer m refers to the (m+1)-type of the Brandt-Vickrey-auction. + // - Type 0 refers to an auction with one highest-price winner, + // - Type 1 refers to an auction with one winner, paying the second + // highest price, + // - Type 2 refers to an auction with two winners, paying + // the third-highest price, + // - etc. + auction_type: number; + + // The vector of prices for the Brandt-Vickrey auction. The values MUST + // be in strictly increasing order. + prices: Amount[]; + + // The type of outcome of the auction. + // In case the auction is declared public, each bidder can calculate the + // winning price. This field is not relevant for the replay of a + // transcript, as the transcript must be provided by the seller who sees + // the winner(s) and winning price of the auction. + outcome_public: boolean; + + // The public key of the seller. + pubkey: EddsaPublicKey; + + // The seller's account details. + payto_uri: string; + } + + + .. ts:def:: PolicyEscrowedPayment + + // CAVEAT: THIS IS STILL WORK IN PROGRESS + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyEscrowedPayment { + type: "escrowed_payment"; + + // Public key of this trustor, the owner of the coins. + // + // To claim the deposit, the merchant must provide the valid signature + // of the ``h_contract_terms`` field from the deposit, signed by _this_ + // key, to the ``/extensions/policy_escrow``-endpoint of the exchange, + // after the date specified in ``not_before`` and before the date + // specified in ``not_after``. + trustor_pub: EddsaPublicKey; + + // Latest date by which the deposit must be claimed. If the deposit + // has not been claimed by that date, the deposited coins can be + // refreshed by the (still) owner. + deadline: Timestamp; + } + + 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. @@ -1697,11 +2578,6 @@ denomination. // URL, or if the base URL has changed since the deposit. transaction_base_url?: string; - // Payment target that the merchant should - // use to check for its KYC status using - // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint. - payment_target_uuid: Integer; - // Timestamp when the deposit was received by the exchange. exchange_timestamp: Timestamp; @@ -1741,7 +2617,8 @@ denomination. | CoinOldCoinRecoupTransaction | CoinRecoupRefreshTransaction | CoinPurseDepositTransaction - | CoinPurseRefundTransaction; + | CoinPurseRefundTransaction + | CoinReserveOpenDepositTransaction; .. ts:def:: CoinDepositTransaction @@ -1947,16 +2824,16 @@ denomination. exchange_pub: EddsaPublicKey; // Blinding factor of the revoked new coin. - new_coin_blinding_secret: RsaBlindingKeySecret; + new_coin_blinding_secret: DenominationBlindingKeySecret; // Blinded public key of the revoked new coin. - new_coin_ev: RsaBlindingKeySecret; + new_coin_ev: DenominationBlindingKeySecret; } .. ts:def:: CoinPurseDepositTransaction interface CoinPurseDepositTransaction { - type: "PURSE_DEPOSIT"; + type: "PURSE-DEPOSIT"; // The total amount of the coin's value absorbed // by this transaction. @@ -1990,7 +2867,7 @@ denomination. .. ts:def:: CoinPurseRefundTransaction interface CoinPurseRefundTransaction { - type: "PURSE_REFUND"; + type: "PURSE-REFUND"; // The total amount of the coin's value restored // by this transaction. @@ -2003,11 +2880,6 @@ denomination. // fee will be waived. refund_fee: Amount; - // Share of the purse fee charged to this coin. - // The sum of all purse fee shares will match the - // total purse fee. - purse_fee_share: Amount; - // Public key of the purse that expired. purse_pub: EddsaPublicKey; @@ -2016,11 +2888,184 @@ denomination. // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PURSE_REFUND``. exchange_sig: EddsaSignature; - // Public key used to sign 'exchange_sig'. + // Public key used to sign 'exchange_sig'. exchange_pub: EddsaPublicKey; } + .. ts:def:: CoinReserveOpenDepositTransaction + + interface CoinReserveOpenDepositTransaction { + type: "RESERVE-OPEN-DEPOSIT"; + + // The total amount of the coin's value absorbed + // by this transaction. + // Note that this means the amount given includes + // the deposit fee. + coin_contribution: Amount; + + // Signature of the reserve open operation being paid for. + reserve_sig: EddsaSignature; + + // Signature by the coin over a + // `TALER_ReserveOpenDepositSignaturePS` of + // purpose ``TALER_SIGNATURE_RESERVE_OPEN_DEPOSIT``. + coin_sig: EddsaSignature; + + } + + +.. http:POST:: /batch-deposit + + Deposit multiple coins and ask the exchange 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 exchange 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_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). + The fields of the response are the same in both cases. + The request should not be repeated again with this coin. + In this case, the response is a `DepositDoubleSpendError` with + an additional ``coin_pub`` field specifying the public key of the + coin that was double-spent. + :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 exchange. + 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 exchange 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 + // exchange, 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; + + // Exchange'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 exchange 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 exchange 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 exchange. + exchange_timestamp: Timestamp; + + // `Public EdDSA key of the exchange <sign-key-pub>` that was used to + // generate the signature. + // Should match one of the exchange'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. + exchange_pub: EddsaPublicKey; + + // Array of deposit confirmation signatures from the exchange + // Entries must be in the same order the coins were given + // in the batch deposit request. + exchange_sigs: DepositConfirmationSignature[]; + } + + .. ts:def:: DepositConfirmationSignature + + interface DepositConfirmationSignature { + // The EdDSA signature of `TALER_DepositConfirmationPS` using a current + // `signing key of the exchange <sign-key-priv>` affirming the successful + // deposit and that the exchange will transfer the funds after the refund + // deadline, or as soon as possible if the refund deadline is zero. + exchange_sig: EddsaSignature; + } + ---------- Refreshing @@ -2038,6 +3083,73 @@ using the ``/refresh/link`` request. While ``/refresh/link`` must be implemente the exchange to achieve taxability, wallets do not really ever need that part of the API during normal operation. + +.. http:post:: /csr-melt + + Obtain exchange-side input values in preparation for a + melt step for certain denomination cipher types, + specifically at this point for Clause-Schnorr blind + signatures. + + **Request:** The request body must be a `MeltPrepareRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `MeltPrepareResponse`. 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`: + A denomination key is not known to the exchange. + :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. + + **Details:** + + .. ts:def:: MeltPrepareRequest + + interface WithdrawPrepareRequest { + + // Master seed for the Clause-schnorr R-value + // creation. + // Must not have been used in any prior request. + rms: RefreshMasterSeed; + + // Array of denominations and coin offsets for + // each of the fresh coins with a CS-cipher + // denomination. + nks: MeltPrepareDenomNonce[]; + + } + + .. ts:def:: MeltPrepareDenomNonce + + interface MeltPrepareDenomNonce { + + // Offset of this coin in the list of + // fresh coins. May not match the array offset + // as the fresh coins may include non-CS + // denominations as well. + coin_offset: Integer; + + // Hash of the public key of the denomination the + // request relates to. Must be a CS denomination type. + denom_pub_hash: HashCode; + } + + + .. ts:def:: MeltPrepareResponse + + interface MeltPrepareResponse { + // Responses for each request, in the same + // order that was used in the request. + ewvs: ExchangeWithdrawValue[]; + } + + .. _refresh: .. http:post:: /coins/$COIN_PUB/melt @@ -2065,7 +3177,8 @@ the API during normal operation. residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is can be decided by looking at the error code - (``TALER_EC_EXCHANGE_MELT_INSUFFICIENT_FUNDS`` or ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). + (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). The response is `MeltForbiddenResponse` in both cases. :http:statuscode:`410 Gone`: The requested denomination key is not yet or no longer valid. @@ -2085,7 +3198,7 @@ the API during normal operation. denom_pub_hash: HashCode; // Signature over the `coin public key <eddsa-coin-pub>` by the denomination. - denom_sig: RsaSignature; + denom_sig: DenominationSignature; // Signature by the `coin <coin-priv>` over the melt commitment. confirm_sig: EddsaSignature; @@ -2098,6 +3211,17 @@ the API during normal operation. // See also ``TALER_refresh_get_commitment()``. rc: TALER_RefreshCommitmentP; + // Master seed for the Clause-schnorr R-value + // creation. Must match the /csr-melt request. + // Must not have been used in any prior melt request. + // Must be present if one of the fresh coin's + // denominations is of type Clause-Schnorr. + rms?: RefreshMasterSeed; + + // IFF the denomination has age restriction support, the client MUST + // provide the SHA256 hash of the age commitment of the coin. + // MUST be omitted otherwise. + age_commitment_hash?: AgeCommitmentHash; } For details about the HKDF used to derive the new coin private keys and @@ -2148,18 +3272,6 @@ the API during normal operation. // Detailed error code. code: Integer; - // Public key of a melted coin that had insufficient funds. - coin_pub: EddsaPublicKey; - - // Original total value of the coin. - original_value: Amount; - - // Remaining value of the coin. - residual_value: Amount; - - // Amount of the coin's value that was to be melted. - requested_value: Amount; - // The transaction list of the respective coin that failed to have sufficient funds left. // Note that only the transaction history for one bogus coin is given, // even if multiple coins would have failed the check. @@ -2232,6 +3344,13 @@ the API during normal operation. // Signs over a `TALER_CoinLinkSignaturePS`. link_sigs: EddsaSignature[]; + // IFF the corresponding denomination has support for age restriction, + // the client MUST provide the original age commitment, i. e. the + // vector of public keys. + // The size of the vector MUST be the number of age groups as defined by the + // Exchange in the field ``.age_groups`` of the extension ``age_restriction``. + old_age_commitment?: Edx25519PublicKey[]; + } @@ -2239,7 +3358,7 @@ the API during normal operation. interface RevealResponse { // List of the exchange's blinded RSA signatures on the new coins. - ev_sigs : Array<{ ev_sig: BlindedRsaSignature }>; + ev_sigs : Array<{ ev_sig: BlindedDenominationSignature }>; } @@ -2267,9 +3386,7 @@ the API during normal operation. **Response:** :http:statuscode:`200 OK`: - All commitments were revealed successfully. The exchange returns an array, - typically consisting of only one element, in which each each element contains - information about a melting session that the coin was used in. + All commitments were revealed successfully. The exchange returns an array (typically consisting of only one element), in which each each element of the array contains a `LinkResponse` entry with information about a melting session that the coin was used in. :http:statuscode:`404 Not found`: The exchange has no linkage data for the given public key, as the coin has not yet been involved in a refresh operation. @@ -2295,11 +3412,19 @@ the API during normal operation. denom_pub: RsaPublicKey; // Exchange's blinded signature over the fresh coin. - ev_sig: BlindedRsaSignature; + ev_sig: BlindedDenominationSignature; // Blinded coin. coin_ev : CoinEnvelope; + // Values contributed by the exchange during the + // withdraw operation (see /csr-melt). + ewv: ExchangeWithdrawValue; + + // Offset of this coin in the refresh operation. + // Input needed to derive the private key. + coin_idx: Integer; + // Signature made by the old coin over the refresh request. // Signs over a `TALER_CoinLinkSignaturePS`. link_sig: EddsaSignature; @@ -2329,11 +3454,10 @@ in using this API. exchange. The exchange MUST return a 307 or 308 redirection to the correct base URL if this is the case. - Depending whether ``$COIN_PUB`` is a withdrawn coin or a refreshed coin, - the remaining amount on the coin will be credited either on the reserve or - the old coin that ``$COIN_PUB`` was withdrawn/refreshed from. + The remaining amount on the coin will be credited to the reserve + that ``$COIN_PUB`` was withdrawn from. - Note that the original withdrawal/refresh fees will **not** be recouped. + Note that the original withdrawal fees will **not** be recouped. **Request:** The request body must be a `RecoupRequest` object. @@ -2341,13 +3465,14 @@ in using this API. **Response:** :http:statuscode:`200 OK`: - The request was successful, and the response is a `RecoupConfirmation`. + The request was successful, and the response is a `RecoupWithdrawalConfirmation`. 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:`401 Unauthorized`: + :http:statuscode:`403 Forbidden`: The coin's signature is invalid. + This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The denomination key is unknown, or the blinded coin is not known to have been withdrawn. @@ -2358,8 +3483,7 @@ in using this API. residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is can be decided by looking at the error code - (``TALER_EC_EXCHANGE_RECOUP_COIN_BALANCE_ZERO`` or - ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). + (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS``). The response is a `DepositDoubleSpendError`. :http:statuscode:`410 Gone`: The requested denomination key is not yet or no longer valid. @@ -2373,49 +3497,120 @@ in using this API. .. ts:def:: RecoupRequest interface RecoupRequest { - // Hash of denomination public key (RSA), specifying the type of coin the client + // Hash of denomination public key, specifying the type of coin the client // would like the exchange to pay back. denom_pub_hash: HashCode; // Signature over the `coin public key <eddsa-coin-pub>` by the denomination. - denom_sig: RsaSignature; + denom_sig: DenominationSignature; - // Coin's blinding factor. - coin_blind_key_secret: RsaBlindingKeySecret; + // Exchange-contributed values during the refresh + // operation (see /csr-withdraw). + ewv: ExchangeWithdrawValue; // Signature of `TALER_RecoupRequestPS` created with // the `coin's private key <coin-priv>`. coin_sig: EddsaSignature; - // Was the coin refreshed (and thus the recoup should go to the old coin)? - // While this information is technically redundant, it helps the exchange - // to respond faster. - // *Optional* (for backwards compatibility); if absent, ``false`` is assumed. - refreshed?: boolean; - } - + // Coin's blinding factor. + coin_blind_key_secret: DenominationBlindingKeySecret; - .. ts:def:: RecoupConfirmation + // Nonce that was used by the exchange to derive + // its private inputs from during withdraw. Only + // present if the cipher of the revoked denomination + // is of type Clause-Schnorr (CS). + cs_nonce?: CSNonce; + } - type RecoupConfirmation = | RecoupRefreshConfirmation - | RecoupWithdrawalConfirmation; .. ts:def:: RecoupWithdrawalConfirmation interface RecoupWithdrawalConfirmation { - // Tag to distinguish the `RecoupConfirmation` response type. - refreshed: false; - // Public key of the reserve that will receive the recoup. reserve_pub: EddsaPublicKey; } + +.. http:post:: /coins/$COIN_PUB/recoup-refresh + + Demand that a coin be refunded via wire transfer to the original owner. + + The base URL for ``/coins/``-requests may differ from the main base URL of the + exchange. The exchange MUST return a 307 or 308 redirection to the correct + base URL if this is the case. + + The remaining amount on the coin will be credited to + the old coin that ``$COIN_PUB`` was refreshed from. + + Note that the original refresh fees will **not** be recouped. + + + **Request:** The request body must be a `RecoupRefreshRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `RecoupRefreshConfirmation`. + 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`: + The coin's signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The denomination key is unknown, or the blinded + coin is not known to have been withdrawn. + If the denomination key is unknown, the response will be + a `DenominationUnknownMessage`. + :http:statuscode:`409 Conflict`: + The operation is not allowed as the coin has insufficient + residual value, or because the same public key of the coin has been + previously used with a different denomination. Which case it is + can be decided by looking at the error code + (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE``). + The response is a `DepositDoubleSpendError`. + :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 not yet 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:: RecoupRefreshRequest + + interface RecoupRefreshRequest { + // Hash of denomination public key, specifying the type of coin the client + // would like the exchange to pay back. + denom_pub_hash: HashCode; + + // Signature over the `coin public key <eddsa-coin-pub>` by the denomination. + denom_sig: DenominationSignature; + + // Exchange-contributed values during the refresh + // operation (see /csr-melt). + ewv: ExchangeWithdrawValue; + + // Signature of `TALER_RecoupRequestPS` created with + // the `coin's private key <coin-priv>`. + coin_sig: EddsaSignature; + + // Coin's blinding factor. + coin_blind_key_secret: DenominationBlindingKeySecret; + + // Nonce that was used by the exchange to derive + // its private inputs from during withdraw. Only + // present if the cipher of the revoked denomination + // is of type Clause-Schnorr (CS). + cs_nonce?: CSNonce; + } + + .. ts:def:: RecoupRefreshConfirmation interface RecoupRefreshConfirmation { - // Tag to distinguish the `RecoupConfirmation` response type. - refreshed: true; - // Public key of the old coin that will receive the recoup. old_coin_pub: EddsaPublicKey; } @@ -2480,8 +3675,8 @@ typically also view the balance.) // Public key of the merchant (identical for all deposits). merchant_pub: EddsaPublicKey; - // Hash of the wire details (identical for all deposits). - h_wire: HashCode; + // Hash of the payto:// account URI (identical for all deposits). + h_payto: PaytoHash; // Time of the execution of the wire transfer by the exchange. execution_time: Timestamp; @@ -2539,8 +3734,9 @@ typically also view the balance.) executed. Hence the exchange does not yet have a wire transfer identifier. The merchant should come back later and ask again. The response body is a `TrackTransactionAcceptedResponse`. - :http:statuscode:`401 Unauthorized`: + :http:statuscode:`403 Forbidden`: A signature is invalid. + This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The deposit operation is unknown to the exchange. @@ -2550,11 +3746,6 @@ typically also view the balance.) interface TrackTransactionResponse { - // Payment target that the merchant should - // use to check for its KYC status using - // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint. - payment_target_uuid: Integer; - // Raw wire transfer identifier of the deposit. wtid: Base32; @@ -2583,12 +3774,22 @@ typically also view the balance.) interface TrackTransactionAcceptedResponse { - // Payment target that the merchant should + // Legitimization target that the merchant should // use to check for its KYC status using - // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint. - payment_target_uuid: Integer; + // the ``/kyc-check/$REQUIREMENT_ROW/...`` endpoint. + // Optional, not present if the deposit has not + // yet been aggregated to the point that a KYC + // need has been evaluated. + requirement_row?: Integer; + + // True if the KYC check for the merchant has been + // satisfied. False does not mean that KYC + // is strictly needed, unless also a + // legitimization_uuid is provided. + kyc_ok: boolean; // Time by which the exchange currently thinks the deposit will be executed. + // Actual execution may be later if the KYC check is not satisfied by then. execution_time: Timestamp; } @@ -2609,7 +3810,7 @@ Refunds :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess` object. - :http:statuscode:`401 Unauthorized`: + :http:statuscode:`403 Forbidden`: Merchant signature is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: @@ -2698,32 +3899,23 @@ Refunds Wallet-to-wallet transfers -------------------------- - .. note:: - - This is a draft API that is not yet implemented. - +.. http:GET:: /purses/$PURSE_PUB/merge +.. http:GET:: /purses/$PURSE_PUB/deposit -.. http:GET:: /purses/$PURSE_PUB - - Obtain information about a purse. The request header must - contain a *Purse-Request-Signature*. Endpoint used by - the party that did not create the purse. + Obtain information about a purse. Depending on the suffix, + the long-polling (if any) will wait for either a merge or + a deposit event. **Request:** - *Purse-Request-Signature*: The client must provide Base-32 encoded EdDSA signature made with ``$PURSE_PRIV``, affirming its authorization to download the purse status. The purpose used MUST be ``TALER_SIGNATURE_PURSE_STATUS_REQUEST``. - - :query merge_timeout_ms=NUMBER: *Optional.* If specified, + :query timeout_ms=NUMBER: *Optional.* If specified, the exchange - will wait up to ``timeout_ms`` milliseconds for completion + will wait up to ``NUMBER`` milliseconds for completion of a merge operation before sending the HTTP response. :query deposit_timeout_ms=NUMBER: *Optional.* If specified, the exchange - will wait up to ``timeout_ms`` milliseconds for completion + will wait up to ``NUMBER`` milliseconds for completion of a deposit operation before sending the HTTP response. - :query contract=BOOLEAN: *Optional.* If 'false' is specified, - the exchange will not return the encrypted contract, saving - bandwidth for clients that already know it. **Response:** @@ -2731,11 +3923,10 @@ Wallet-to-wallet transfers The operation succeeded, the exchange provides details about the purse. The response will include a `PurseStatus` object. - :http:statuscode:`401 Unauthorized`: - The *Purse-Request-Signature* is invalid. - This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The purse is unknown to the exchange. + :http:statuscode:`410 Gone`: + The purse expired before the deposit or merge was completed. **Details:** @@ -2748,26 +3939,18 @@ Wallet-to-wallet transfers // exceeds 'merge_value_after_fees', and a // 'merge_request' exists for the purse, then the // purse will (have been) merged with the account. - total_deposit_amount: Amount; - - // Indicative time by which the purse expires - // if it has not been merged into an account. At this - // point, all of the deposits made will be auto-refunded. - purse_expiration: Timestamp; - - // Desired total amount to be merged into the reserve. - // (excludes fees). - merge_value_after_fees: Amount; - - // Indicative time at which the exchange is answering the - // status request. Used as part of 'exchange_sig'. - status_timestamp: Timestamp; + balance: Amount; - // Deposit fees charged so far to all deposited coins. - deposit_fees: Amount; + // Time of the merge, missing if "never". + merge_timestamp?: Timestamp; - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; + // Time of the deposits being complete, missing if "never". + // Note that this time may not be "stable": once sufficient + // deposits have been made, is "now" before the purse + // expiration, and otherwise set to the purse expiration. + // However, this should also not be relied upon. The key + // property is that it is either "never" or in the past. + deposit_timestamp?: Timestamp; // EdDSA signature of the exchange over a // `TALER_PurseStatusResponseSignaturePS` @@ -2778,26 +3961,17 @@ Wallet-to-wallet transfers // EdDSA public key exchange used for 'exchange_sig'. exchange_pub: EddsaPublicKey; - // AES-GCM Encrypted contract terms using encryption - // key derived from DH of 'contract_pub' and the 'purse_pub'. - // Optional, may be omitted if not desired by the client. - e_contract_terms?: string; - - // If a merge request was received, information about the - // merge request. Omitted if the purse has not yet received - // a merge request. - merge_request?: MergeRequest; - } -.. http:POST:: /purses/$PURSE_PUB/deposit - Deposit money into a purse. Endpoint used by the buyer. +.. http:POST:: /purses/$PURSE_PUB/create + + Create a purse by depositing money into it. First step of a PUSH payment. **Request:** - The request body must be a `PurseRequest` object. + The request body must be a `PurseCreate` object. **Response:** @@ -2805,138 +3979,133 @@ Wallet-to-wallet transfers The operation succeeded, the exchange confirms that all coins were deposited into the purse. The response will include a `PurseDepositSuccess` object. - :http:statuscode:`202 Accepted`: - The payment was accepted, but insufficient to reach the - specified purse balance. If an encrypted contract was - provided, it will have been stored in the database. - The client should make further - purse deposits before the expiration deadline. - The response will include a `PurseDepositAccepted` object. - :http:statuscode:`401 Unauthorized`: - A coin signature is invalid. The response will - include a `PurseDepositSignatureErrorDetail` :http:statuscode:`403 Forbidden`: - The server is denying the operation as a purse with a - different contract or total amount already exists. - This response comes with a standard `PurseConflict` response. - :http:statuscode:`404 Not found`: - FIXME: when exactly does this happen? + A coin, denomination or contract signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not Found`: + The denomination of one of the coins is unknown to the exchange. :http:statuscode:`409 Conflict`: The deposit operation has either failed because a coin has insufficient residual value, or because the same public key of the coin has been - previously used with a different denomination. Which case it is + previously used with a different denomination, or because a purse with + the same public key but different meta data was created previously. + Which case it is can be decided by looking at the error code - (``TALER_EC_EXCHANGE_DEPOSIT_INSUFFICIENT_FUNDS`` or - ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). - The fields of the response are the same in both cases. - The request should not be repeated again with this coin. - In this case, the response is a `PurseDepositDoubleSpendError`. - If the value of all successful coins is below the purse fee, - the exchange may not setup the purse at all. The encrypted - contract will not have been associated with the purse if this - status code is returned. However, all coins that were not - double-spent will have been deposited into the purse. + (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or + ``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA`` or + ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA`` or + ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA``). + The specific fields of the response depend on the error code + and include the signatures (and what was signed over) proving the + conflict. :http:statuscode:`425 Too Early`: This response type is used if the given purse expiration time is too far in the future (at least from the perspective of the exchange). Thus, retrying at a later time may - succeed. The client should look at the ``Date:`` header of the response to see if a minor time difference is to blame and possibly adjust the request accordingly. + succeed. The client should look at the ``Date:`` header + of the response to see if a minor time difference is to + blame and possibly adjust the request accordingly. + (Note: this status code is not yet used.) **Details:** - .. ts:def:: PurseRequest + .. ts:def:: PurseCreate - interface PurseRequest { + interface PurseCreate { + + // Total value of the purse, excluding fees. + amount: Amount; + + // Minimum age required for all coins deposited into the purse. + min_age: Integer; + + // Optional encrypted contract, in case the buyer is + // proposing the contract and thus establishing the + // purse with the payment. + econtract?: EncryptedContract; + + // EdDSA public key used to approve merges of this purse. + merge_pub: EddsaPublicKey; // EdDSA signature of the purse over a // `TALER_PurseRequestSignaturePS` - // of purpose ``TALER_SIGNATURE_PURSE_REQUEST`` + // of purpose ``TALER_SIGNATURE_WALLET_PURSE_CREATE`` // confirming the key // invariants associated with the purse. // (amount, h_contract_terms, expiration). purse_sig: EddsaSignature; - // Total amount to be paid into the purse. - // Clients may make several requests, i.e. if a - // first request failed with a double-spending error. - // The exchange will confirm the creation of the - // purse once the amount given here is reached. - merge_value_after_fees: Amount; - // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; - // Client-side timestamp of when the payment was made. - payment_timestamp: Timestamp; + // Array of coins being deposited into the purse. + // Maximum length is 128. + deposits: PurseDeposit[]; // 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 will be auto-refunded. purse_expiration: Timestamp; - // Optional encrypted contract, in case the buyer is - // proposing the contract and thus establishing the - // purse with the payment. - contract?: EncryptedContract; - - // Array of coins being deposited into the purse. - // Maximum length is 128. - deposits: PurseDeposit[]; } - .. ts:def:: EncryptedContract + .. ts:def:: EncryptedContract interface EncryptedContract { - // ECDH contract_public key used to encrypt the contract. - // Optional as the contract terms may already be known - // to the exchange or the other wallet from a different - // interaction. - contract_pub: TALER_EcdhEphemeralPublicKeyP; + // Encrypted contract. + econtract: string; + + // Signature over the (encrypted) contract. + econtract_sig: EddsaSignature; + + // Ephemeral public key for the DH operation to decrypt the encrypted contract. + contract_pub: EddsaPublicKey; - // AES-GCM Encrypted contract terms using encryption - // key derived from DH of ``contract_pub`` and the ``purse_pub``. - // Optional as the contract terms may already be known - // to the exchange or the other wallet from a different - // interaction. - e_contract_terms: string; } .. ts:def:: PurseDeposit interface PurseDeposit { - // Public key of the coin being deposited into the purse. - coin_pub: EddsaPublicKey; - // Amount to be deposited, can be a fraction of the // coin's total value. - contribution: Amount; + amount: Amount; // Hash of denomination RSA key with which the coin is signed. denom_pub_hash: HashCode; // Exchange's unblinded RSA signature of the coin. - ub_sig: RsaSignature; + ub_sig: DenominationSignature; + + // Age commitment for the coin, if the denomination is age-restricted. + age_commitment?: AgeCommitment; + + // Attestation for the minimum age, if the denomination is age-restricted. + attest?: Attestation; // Signature over `TALER_PurseDepositSignaturePS` - // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT`` + // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT`` // made by the customer with the // `coin's private key <coin-priv>`. coin_sig: EddsaSignature; + // Public key of the coin being deposited into the purse. + coin_pub: EddsaPublicKey; + } .. ts:def:: PurseDepositSuccess interface PurseDepositSuccess { - // Total amount paid into the purse. - total_purse_amount: Amount; + // Total amount deposited into the purse so far (without fees). + total_deposited: Amount; - // Total deposit fees charged. - total_deposit_fees: Amount; + // Time at the exchange. + exchange_timestamp: Timestamp; // EdDSA signature of the exchange affirming the payment, // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED`` @@ -2950,39 +4119,27 @@ Wallet-to-wallet transfers } - .. ts:def:: PurseDepositAccepted - - interface PurseDepositAccepted { - - // Total amount paid so far into the purse, in this - // and previous requests. - total_amount_deposited: Amount; - - // Total amount contributed by the current request. - total_amount_contributed: Amount; - - } - .. ts:def:: PurseConflict - // Union discriminated by the "type" field. + // Union discriminated by the "code" field. type PurseConflict = - | PurseMergeConflict - | PurseRequestConflict; + | DepositDoubleSpendError + | PurseCreateConflict + | PurseDepositConflict + | PurseContractConflict; - .. ts:def:: PurseMergeConflict + .. ts:def:: PurseCreateConflict - interface PurseMergeConflict { - type: "MERGE"; - - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; + interface PurseCreateConflict { + // Must be equal to TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA + code: Integer; - // Hash of the wire details of the reserve. - h_wire: HashCode; + // Total amount to be merged into the reserve. + // (excludes fees). + amount: Amount; - // Reserve merging the purse. - reserve_pub: EddsaPublicKey; + // Minimum age required for all coins deposited into the purse. + min_age: Integer; // Indicative time by which the purse should expire // if it has not been merged into an account. At this @@ -2990,136 +4147,125 @@ Wallet-to-wallet transfers // auto-refunded. purse_expiration: Timestamp; - // When was the merge request generated. - merge_timestamp: Timestamp; - - // Total amount to be merged into the reserve. - // (excludes fees). - merge_value_after_fees: Amount; - // EdDSA signature of the purse over // `TALER_PurseMergeSignaturePS` of - // purpose ``TALER_SIGNATURE_PURSE_MERGE`` + // purpose ``TALER_SIGNATURE_WALLET_PURSE_MERGE`` // confirming that the // above details hold for this purse. purse_sig: EddsaSignature; + + // 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; } - .. ts:def:: PurseRequestConflict + .. ts:def:: PurseDepositConflict - interface PurseRequestConflict { - type: "REQUEST"; + interface PurseDepositConflict { + // Must be equal to TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA + code: Integer; - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; + // Public key of the coin being deposited into the purse. + coin_pub: EddsaPublicKey; - // 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; + // Signature over `TALER_PurseDepositSignaturePS` + // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT`` + // made by the customer with the + // `coin's private key <coin-priv>`. + coin_sig: EddsaSignature; - // Total amount to be paid into the purse as per - // the previous request. - total_purse_amount: Amount; + // Target exchange URL for the purse. Not present for the + // same exchange. + partner_url?: string; - // EdDSA signature of the purse over - // `TALER_PurseRequestSignaturePS` of - // purpose ``TALER_SIGNATURE_PURSE_REQUEST`` - // confirming that the - // above details hold for this purse. - purse_sig: EddsaSignature; + // Amount to be contributed to the purse by this coin. + amount: Amount; } - .. ts:def:: PurseDepositDoubleSpendError + .. ts:def:: PurseContractConflict - interface DepositDoubleSpendError { - // Taler error code. - code: number; + interface PurseContractConflict { + // Must be equal to TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA + code: Integer; + + // Hash of the encrypted contract. + h_econtract: HashCode; - // Human-readable description of the error, i.e. "insufficient funds". - hint?: string; + // Signature over the contract. + econtract_sig: EddsaSignature; - // Total amount contributed by the current request. - // Note that some coins may have been successfully - // deposited into the purse, so the total amount - // from these coins is listed here. - total_amount_contributed: Amount; + // Ephemeral public key for the DH operation to decrypt the contract. + contract_pub: EddsaPublicKey; - // Public keys of coins that could not be deposited - // into the purse, mapped to the coin's histories. - coin_map: EddsaPublicKey -> CoinSpendHistoryItem[]; } - .. ts:def:: PurseDepositSignatureErrorDetail - interface PurseDepositSignatureErrorDetail { - // Taler error code, summarizing the problem. - // Note that for problems about specific - // coins, the 'coin_error_map' should be consulted. - // The 'coin_error_map' will be empty if the - // 'purse_sig' was invalid. In this case, - // the coins will not even have been checked by - // the exchange. - code: number; +.. http:delete:: /purses/$PURSE_PUB - // Human-readable description of the error, i.e. "invalid siganture". - hint?: string; + Delete a purse that is unmerged and not yet expired. Refunds any money that + is already in the purse. - // Total amount contributed by the current request. - // Note that some coins may have been successfully - // deposited into the purse, so the total amount - // from these coins is listed here. - total_amount_contributed: Amount; + **Request:** - // Public keys of coins that could not be deposited - // into the purse, mapped to the coin's histories. - coin_error_map: EddsaPublicKey -> ErrorDetail[]; - } + The request body must be empty, as recommended for HTTP delete in general. + To authorize the request, the header must contain a + ``Taler-Purse-Signature: $PURSE_SIG`` where ``$PURSE_SIG`` is the Crockford base32-encoded + EdDSA signature of purpose TALER_SIGNATURE_WALLET_PURSE_DELETE. + + **Response:** + + :http:statuscode:`204 No Content`: + The operation succeeded, the exchange confirms that the purse + was deleted. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not Found`: + The purse is not known. Might have already been deleted previously. + :http:statuscode:`409 Conflict`: + It is too late to delete the purse, its fate (merge or expiration) + was already decided. .. http:POST:: /purses/$PURSE_PUB/merge Merge purse with account, adding the value of the purse into - the account. Endpoint to be used by the seller. + the account. Endpoint to be used by the receiver of a PUSH payment. **Request:** The request body must be a `MergeRequest` object. - :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will - wait up to ``timeout_ms`` milliseconds to receive payment before - reporting on the completion of merge operation. Basically - forstalls returning a 202 response for up to timeout milliseconds - to possibly return a 200 response instead. - **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that the funds were merged into the account. The response will include a `MergeSuccess` object. - :http:statuscode:`202 Accepted`: - The operation succeeded, the exchange confirms that the - merge request is valid. Alas, the purse was still not - funded and thus the actual merge is delayed. - The response will include a `MergeAccepted` object. - :http:statuscode:`401 Unauthorized`: - Account signature is invalid. + :http:statuscode:`402 Payment Required`: + The purse is not yet full and more money needs to be deposited + before the merge can be made. + :http:statuscode:`403 Forbidden`: + The signature of the merge request or the reserve was invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: - The refund operation failed as we could not find the purse. + The merge operation failed as we could not find the purse + or the partner exchange. This response comes with a standard `ErrorDetail` response. + :http:statuscode:`409 Conflict`: + The purse was already merged into a different reserve. + The response will include a `MergeConflict` object. :http:statuscode:`410 Gone`: The purse has already expired and thus can no longer be merged. This response comes with a standard `ErrorDetail` response. - :http:statuscode:`429 Too Many Requests`: - This account is not at this exchange, has not yet passed the - KYC checks, or it has exceeded the number of open purses. - The client must include payment to create another purse or - wait until existing purses have expired. + :http:statuscode:`451 Unavailable For Legal Reasons`: + This account has not yet passed the KYC checks. + The client must pass KYC checks before proceeding with the merge. + The response will be an `KycNeededRedirect` object. **Details:** @@ -3139,13 +4285,146 @@ Wallet-to-wallet transfers // EdDSA signature of the purse private key affirming the merge // over a `TALER_PurseMergeSignaturePS`. // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. - purse_sig: EddsaSignature; + merge_sig: EddsaSignature; + + // Client-side timestamp of when the merge request was made. + merge_timestamp: Timestamp; + + } + + .. ts:def:: MergeSuccess + + interface MergeSuccess { + + // Amount merged (excluding deposit fees). + merge_amount: Amount; + + // Time at which the merge came into effect. + // Maximum of the "payment_timestamp" and the + // "merge_timestamp". + exchange_timestamp: Timestamp; + + // EdDSA signature of the exchange affirming the merge of + // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS`` + // over `TALER_PurseMergeSuccessSignaturePS`. + // Signs over the above and the account public key. + exchange_sig: EddsaSignature; + + // public key used to create the signature. + exchange_pub: EddsaPublicKey; + + } + + .. ts:def:: MergeConflict + + interface MergeConflict { + + // Client-side timestamp of when the merge request was made. + merge_timestamp: Timestamp; + + // EdDSA signature of the purse private key affirming the merge + // over a `TALER_PurseMergeSignaturePS`. + // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. + merge_sig: EddsaSignature; + + // Base URL of the exchange receiving the payment, only present + // if the exchange hosting the reserve is not this exchange. + partner_url?: string; + + // Public key of the reserve that the purse was merged into. + reserve_pub: EddsaPublicKey; + } + + + +.. http:POST:: /reserves/$RESERVE_PUB/purse + + Create purse for an account. First step of a PULL payment. + + **Request:** + + The request body must be a `ReservePurseRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The operation succeeded, the exchange confirms that the + purse was allocated. + The response will include a `PurseDepositSuccess` object. + :http:statuscode:`402 Payment Required`: + The account needs to contain more funding to create more purses. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`403 Forbidden`: + Account or contract signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The purse creation operation failed as we could not find the reserve. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`409 Conflict`: + The purse creation failed because a purse with + the same public key but different meta data was + created previously. Which specific conflict it is + can be decided by looking at the error code + (``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA`` or + ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA`` or + ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA``). + The specific fields of the response depend on the error code + and include the signatures (and what was signed over) proving the + conflict. + The response will be a `PurseConflict` response + (but not a `DepositDoubleSpendError`). + :http:statuscode:`451 Unavailable For Legal Reasons`: + This account has not yet passed the KYC checks. + The client must pass KYC checks before proceeding with the merge. + The response will be an `KycNeededRedirect` object. + + **Details:** + + .. ts:def:: ReservePurseRequest + + interface ReservePurseRequest { // Minimum amount that must be credited to the reserve, that is // the total value of the purse minus the deposit fees. // If the deposit fees are lower, the contribution to the // reserve can be higher! - merge_value_after_fees: Amount; + purse_value: Amount; + + // Minimum age required for all coins deposited into the purse. + min_age: Integer; + + // Purse fee the reserve owner is willing to pay + // for the purse creation. Optional, if not present + // the purse is to be created from the purse quota + // of the reserve. + purse_fee: Amount; + + // Optional encrypted contract, in case the buyer is + // proposing the contract and thus establishing the + // purse with the payment. + econtract?: EncryptedContract; + + // EdDSA public key used to approve merges of this purse. + merge_pub: EddsaPublicKey; + + // EdDSA signature of the purse private key affirming the merge + // over a `TALER_PurseMergeSignaturePS`. + // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. + merge_sig: EddsaSignature; + + // EdDSA signature of the account/reserve affirming the merge. + // Must be of purpose ``TALER_SIGNATURE_WALLET_ACCOUNT_MERGE`` + reserve_sig: EddsaSignature; + + // Purse public key. + purse_pub: EddsaPublicKey; + + // EdDSA signature of the purse over + // `TALER_PurseRequestSignaturePS` of + // purpose ``TALER_SIGNATURE_PURSE_REQUEST`` + // confirming that the + // above details hold for this purse. + purse_sig: EddsaSignature; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; @@ -3157,32 +4436,110 @@ Wallet-to-wallet transfers // if it has not been paid. purse_expiration: Timestamp; - // Optional encrypted contract, in case the seller is - // proposing the contract and thus establishing the - // purse with the payment. - contract?: EncryptedContract; + } + +.. http:POST:: /purses/$PURSE_PUB/deposit + + Deposit money into a purse. Used by the buyer for a PULL payment. + + **Request:** + + The request body must be a `PurseDeposits` object. + + **Response:** + + :http:statuscode:`200 OK`: + The operation succeeded, the exchange confirms that all + coins were deposited into the purse. + The response will include a `PurseDepositSuccess` object. + :http:statuscode:`403 Forbidden`: + A coin or denomination signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The purse is unknown. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`409 Conflict`: + The deposit operation has either failed because a coin has insufficient + residual value, or because the same public key of the coin has been + previously used with a different denomination. Which case it is + can be decided by looking at the error code + (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or + ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA``). + This response comes with a standard `PurseConflict` response + (alas some cases are impossible). + :http:statuscode:`410 Gone`: + The purse has expired. + + + **Details:** + + .. ts:def:: PurseDeposits + + interface PurseDeposits { + + // Array of coins to deposit into the purse. + deposits: PurseDeposit[]; } - .. ts:def:: MergeSuccess + .. ts:def:: PurseDeposit - interface MergeSuccess { + interface PurseDeposit { - // Amount merged (excluding deposit fees). - merge_amount: Amount; + // Amount to be deposited, can be a fraction of the + // coin's total value. + amount: Amount; + + // Hash of denomination RSA key with which the coin is signed. + denom_pub_hash: HashCode; + + // Exchange's unblinded RSA signature of the coin. + ub_sig: DenominationSignature; + + // Age commitment for the coin, if the denomination is age-restricted. + age_commitment?: AgeCommitment; + + // Attestation for the minimum age, if the denomination is age-restricted. + attest?: Attestation; + + // Signature over `TALER_PurseDepositSignaturePS` + // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT`` + // made by the customer with the + // `coin's private key <coin-priv>`. + coin_sig: EddsaSignature; + + // Public key of the coin being deposited into the purse. + coin_pub: EddsaPublicKey; + + } + + .. ts:def:: PurseDepositSuccess + + interface PurseDepositSuccess { + + // Total amount paid into the purse. + total_deposited: Amount; + + // Total amount expected in the purse. + purse_value_after_fees: Amount; + + // Time at which the deposit came into effect. + exchange_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 will be auto-refunded. + purse_expiration: Timestamp; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; - // Time at which the merge came into effect. - // Maximum of the "payment_timestamp" and the - // "merge_timestamp". - contract_time: Timestamp; - - // EdDSA signature of the exchange affirming the merge of - // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS`` - // over `TALER_PurseMergeSuccessSignaturePS`. - // Signs over the above and the account public key. + // EdDSA signature of the exchange affirming the payment, + // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED`` + // over a `TALER_PurseDepositConfirmedSignaturePS`. + // Signs over the above and the purse public key and + // the hash of the contract terms. exchange_sig: EddsaSignature; // public key used to create the signature. @@ -3190,17 +4547,17 @@ Wallet-to-wallet transfers } - .. ts:def:: MergeAccepted - - interface MergeAccepted { + .. ts:def:: AgeCommitment - // The number of remaining purses that can still be opened - // under the given account. - remaining_purses: Integer; - - } + // AgeCommitment is an array of public keys, one for each age group of the + // age-restricted denomination. + type AgeCommitment = Edx25519PublicKey[]; + .. ts:def:: Attestation + // An attestation for a minimum age is an Edx25519 signature of the age + // with purpose ``TALER_SIGNATURE_WALLET_AGE_ATTESTATION``. + type Attestation = string; .. _exchange_wads: @@ -3305,22 +4662,77 @@ wallet-to-wallet payments. Only another exchange should access this endpoint. KYC status updates ------------------ - .. note:: +.. http:POST:: /kyc-wallet - This is a draft API that is not yet implemented. + Setup KYC identification for a wallet. Returns the KYC UUID. + + **Request:** + + The request body must be a `WalletKycRequest` object. + **Response:** -.. http:GET:: /kyc-check/$PAYMENT_TARGET_UUID + :http:statuscode:`204 No Content`: + KYC is disabled at this exchange, or the balance + is below the threshold that requires KYC, or this + wallet already satisfied the KYC check for the + given balance. + :http:statuscode:`403 Forbidden`: + The provided signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`451 Unavailable for Legal Reasons`: + The wallet must undergo a KYC check. A KYC ID was created. + The response will be a `WalletKycUuid` object. + + **Details:** + + .. ts:def:: WalletKycRequest + + interface WalletKycRequest { + + // Balance threshold (not necessarily exact balance) + // to be crossed by the wallet that (may) trigger + // additional KYC requirements. + balance: Amount; + + // EdDSA signature of the wallet affirming the + // request, must be of purpose + // ``TALER_SIGNATURE_WALLET_ACCOUNT_SETUP`` + reserve_sig: EddsaSignature; + + // long-term wallet reserve-account + // public key used to create the signature. + reserve_pub: EddsaPublicKey; + } + + .. ts:def:: WalletKycUuid + + interface WalletKycUuid { + + // UUID that the wallet should use when initiating + // the KYC check. + requirement_row: number; + + // Hash of the payto:// account URI for the wallet. + h_payto: PaytoHash; + + } + + +.. http:GET:: /kyc-check/$REQUIREMENT_ROW/$H_PAYTO/$USERTYPE Check or update KYC status of a particular payment target. Returns the current KYC status of the account and, if negative, returns the URL where the KYC process can be - initiated using OAuth. + initiated. The ``$REQUIREMENT_ROW`` must have been + returned previously from an exchange API endpoint that + determined that KYC was needed. The ``$H_PATYO`` must be + the hash of the payto:// URI of the payment target. + The ``$USERTYPE`` states whether the entity to perform + the KYC is an "individual" or "business". **Request:** - :query h_payto=HASH: Specifies the hash of the payto:// URI of the payment - target. Weak security check used to authorize the status request. :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds if the payment target is currently not legitimized. Ignored if the payment target @@ -3332,7 +4744,7 @@ KYC status updates :http:statuscode:`200 Ok`: The KYC operation succeeded, the exchange confirms that the - payment target is now authorized to transact. + payment target already authorized to transact. The response will be an `AccountKycStatus` object. :http:statuscode:`202 Accepted`: The user should be redirected to the provided location to perform @@ -3342,7 +4754,10 @@ KYC status updates :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus generally all accounts are simply considered legitimate. - :http:statuscode:`401 Unauthorized`: + :http:statuscode:`402 Payment Required`: + The client must pay the KYC fee for the KYC process. + **This is currently not implemented, see #7365.** + :http:statuscode:`403 Forbidden`: The provided hash does not match the payment target. :http:statuscode:`404 Not found`: The payment target is unknown. @@ -3351,7 +4766,11 @@ KYC status updates .. ts:def:: AccountKycStatus - interface AccountKycStatus { + interface AccountKycStatus { + + // Details about the KYC check that the user + // passed. + kyc_details: KycDetails; // Current time of the exchange, used as part of // what the exchange signs over. @@ -3360,7 +4779,7 @@ KYC status updates // EdDSA signature of the exchange affirming the account // is KYC'ed, must be of purpose // ``TALER_SIGNATURE_EXCHANGE_ACCOUNT_SETUP_SUCCESS`` - // and over `TALER_AccountSetupStatusSignaturePS`. + // and over ``TALER_AccountSetupStatusSignaturePS``. exchange_sig: EddsaSignature; // public key used to create the signature. @@ -3369,7 +4788,7 @@ KYC status updates .. ts:def:: AccountKycRedirect - interface AccountKycRedirect { + interface AccountKycRedirect { // URL that the user should open in a browser to // proceed with the KYC process. @@ -3377,20 +4796,34 @@ KYC status updates } + .. ts:def:: KycDetails + + // Object that specifies which KYC checks are satisfied. + interface KycDetails { + + // Keys are the names of the check(s). + // The values are for now always empty objects. -.. http:GET:: /kyc-proof/$PAYMENT_TARGET_UUID + } + +.. http:GET:: /kyc-proof/$H_PAYTO/$PROVIDER_SECTION Update KYC status of a particular payment target. Provides - the token to the exchange that allows it to verify that the - user has completed the KYC process. The HTTP method must be - a GET due to requirements from the OAuth 2.0 protocol. + information to the exchange that allows it to verify that the + user has completed the KYC process. The details depend on + the logic, which is selected by the $PROVIDER_SECTION. **Request:** - :query code=CODE: OAuth 2.0 code argument. + Details on the request depend on the specific KYC logic + that was used. + + If $LOGIC is "oauth2.0", the query parameters are: + + :query code=CODE: OAuth 2.0 code argument. :query state=CODE: OAuth 2.0 state argument. - ..note:: + .. note:: Depending on the OAuth variant used, additional query parameters may need to be passed here. @@ -3403,12 +4836,341 @@ KYC status updates The browser is redirected to a human-readable page configured by the exchange operator. :http:statuscode:`401 Unauthorized`: - The provided OAuth 2.0 authentication token is invalid. + The provided authorization token is invalid. :http:statuscode:`404 Not found`: The payment target is unknown. :http:statuscode:`502 Bad Gateway`: - The exchange received an invalid reply from the OAuth-based + The exchange received an invalid reply from the legitimization service. :http:statuscode:`504 Gateway Timeout`: - The exchange did not receive a reply from the OAuth legitimization + The exchange did not receive a reply from the legitimization service within a reasonable time period. + + +.. http:GET:: /kyc-webhook/$PROVIDER_SECTION/* +.. http:POST:: /kyc-webhook/$PROVIDER_SECTION/* +.. http:GET:: /kyc-webhook/$LOGIC/* +.. http:POST:: /kyc-webhook/$LOGIC/* + + Update KYC status of a particular payment target. Provides + information to the KYC logic of the exchange that allows + it to verify that the user has completed the KYC process. + May be a GET or a POST request, depending on $LOGIC or + $PROVIDER_SECTION. + + **Request:** + + Details on the request depend on the specific KYC logic + that was used. + + **Response:** + + :http:statuscode:`204 No content`: + The webhook succeeded. + :http:statuscode:`404 Not found`: + The specified logic is unknown. + + +--------------- +Reserve control +--------------- + +This section describes the reserve control API which can be used to (1) +prevent a reserve from expiring (which is useful if the reserve is used for +tipping), to (2) pay an annual fee to allow a number of purses to be created +for the respective reserve without paying a purse fee each time, to (3) obtain +KYC information associated with a reserve to prove the identity of the person +sending an invoice to the payer, and to (4) close a reserve before it would +naturally expire and possibly (5) wire the funds to a designated account. + + .. note:: + + This section is about a proposed API. It is not implemented. See also DD 31. + +.. http:post:: /reserves/$RESERVE_PUB/open + + Request keeping a reserve open for tipping or invoicing. + + **Request:** + + The request body must be a `ReserveOpenRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `ReserveOpenResponse` object. + :http:statuscode:`402 Payment Required`: + The exchange responds with a `ReserveOpenFailure` object when + the payment offered is insufficient for the requested operation. + :http:statuscode:`403 Forbidden`: + The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + :http:statuscode:`409 Conflict`: + The balance of the reserve or of a coin was insufficient. + Which case it is can be decided by looking at the error code + (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or + ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or + ``TALER_EC_EXCHANGE_OPEN_INSUFFICIENT_FUNDS``). + The specific fields of the response depend on the error code + and include the signatures (and what was signed over) proving the + conflict. + The response is `WithdrawError` object or a `DepositDoubleSpendError` + depending on the error type. + :http:statuscode:`451 Unavailable For Legal Reasons`: + This account has not yet passed the KYC checks. + The client must pass KYC checks before the reserve can be opened. + The response will be an `KycNeededRedirect` object. + + **Details:** + + .. ts:def:: ReserveOpenRequest + + interface ReserveOpenRequest { + // Signature of purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over + // a `TALER_ReserveOpenRequestSignaturePS`. + reserve_sig: EddsaSignature; + + // Array of payments made towards the cost of the + // operation. + payments: OpenPaymentDetail[]; + + // Amount to be paid from the reserve for this + // operation. + reserve_payment: Amount; + + // Time when the client made the request. + // Timestamp must be reasonably close to the time of + // the exchange, otherwise the exchange may reject + // the request (with a status code of 400). + request_timestamp: Timestamp; + + // Desired new expiration time for the reserve. + // If the reserve would expire before this time, + // the exchange will charge account fees (and + // possibly KYC fees) until the expiration time + // exceeds this timestamp. Note that the exchange + // will refuse requests (with a status code of 400) + // if the time is so far in the future that the + // fees are not yet known (see /keys). + reserve_expiration: Timestamp; + + // Desired open purse limit. Can be used to pay the + // annual account fee more than once to get a larger + // purse limit. + purse_limit: Integer; + + } + + .. ts:def:: ReserveOpenResponse + + interface ReserveOpenResponse { + // Transaction cost for extending the expiration time. + // Excludes KYC fees. + open_cost: Amount; + + // Current expiration time for the reserve. + reserve_expiration: Timestamp; + } + + .. ts:def:: ReserveOpenFailure + + interface ReserveOpenFailure { + // Transaction cost that should have been paid + // to extending the reserve as requested. + // Excludes KYC fees. + open_cost: Amount; + + // Remaining expiration time for the reserve. + reserve_expiration: Timestamp; + } + + .. ts:def:: OpenPaymentDetail + + interface OpenPaymentDetail { + + // Contribution of this coin to the overall amount. + // Can be a fraciton of the coin's total value. + amount: Amount; + + // Hash of denomination RSA key with which the coin is signed. + denom_pub_hash: HashCode; + + // Exchange's unblinded RSA signature of the coin. + ub_sig: DenominationSignature; + + // Age commitment for the coin, if the denomination is age-restricted. + age_commitment?: AgeCommitment; + + // Signature over `TALER_ReserveOpenDepositSignaturePS` + // of purpose ``TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT`` + // made by the customer with the + // `coin's private key <coin-priv>`. + coin_sig: EddsaSignature; + + // Public key of the coin being used to pay for + // opening the reserve. + coin_pub: EddsaPublicKey; + + } + + +.. http:get:: /reserves-attest/$RESERVE_PUB + + Request list of available KYC attributes about the owner of a reserve. + Used as a preliminary step to find out which subsets of attributes the + exchange could provide signatures over. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `ReserveKycAttributes` object. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + :http:statuscode:`409 Conflict`: + The exchange does not have the requested KYC information. + + **Details:** + + .. ts:def:: ReserveKycAttributes + + interface ReserveKycAttributes { + // Array of KYC attributes available. The attribute names + // listed are expected to be from the respective GANA + // registry. + details: string[]; + } + + +.. http:post:: /reserves-attest/$RESERVE_PUB + + Request signed KYC information about the owner of a reserve. + This can be used by a reserve owner to include a proof + of their identity in invoices. + + **Request:** + + The request body must be a `ReserveAttestRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `ReserveAttestResponse` object. + :http:statuscode:`403 Forbidden`: + The *TALER_SIGNATURE_WALLET_KYC_DETAILS* signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + :http:statuscode:`409 Conflict`: + The exchange does not have the requested KYC information. + + **Details:** + + .. ts:def:: ReserveAttestRequest + + interface ReserveAttestRequest { + // Signature of purpose + // ``TALER_SIGNATURE_WALLET_ATTEST_DETAILS`` over + // a `TALER_WalletReserveAttestRequestSignaturePS`. + reserve_sig: EddsaSignature; + + // Client's time for the request. + request_timestamp: Timestamp; + + // Array of KYC attributes requested. + details: string[]; + } + + .. ts:def:: ReserveAttestResponse + + interface ReserveAttestResponse { + // Signature of purpose + // ``TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS`` over + // a `TALER_ExchangeReserveAttestDetailsSignaturePS`. + exchange_sig: EddsaSignature; + + // Exchange public key used to create the + // signature. + exchange_pub: EddsaPublicKey; + + // Time when the exchange created the signature. + exchange_timestamp: Timestamp; + + // Expiration time for the provided information. + expiration_time: Timestamp; + + // KYC details (key-value pairs) as requested. + // The keys will match the elements of the + // ``details`` array from the request. + attributes: Object; + } + + +.. http:post:: /reserves/$RESERVE_PUB/close + + Force immediate closure of a reserve. Does not actually + delete the reserve or the KYC data, but merely forces + the reserve's current balance to be wired back to the + account where it originated from, or another account of + the user's choosing if they performed the required KYC + check and designated another target account. + + **Request:** + + The request body must be a `ReserveCloseRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `ReserveCloseResponse` object. + :http:statuscode:`403 Forbidden`: + The *TALER_SIGNATURE_WALLET_RESERVE_CLOSE* signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The reserve key does not belong to a reserve known to the exchange. + :http:statuscode:`409 Conflict`: + No target account was given, and the exchange does not know an + origin account for this reserve. + :http:statuscode:`451 Unavailable For Legal Reasons`: + This account has not yet passed the KYC checks, hence wiring + funds to a non-origin account is not allowed. + The client must pass KYC checks before the reserve can be opened. + The response will be an `KycNeededRedirect` object. + + **Details:** + + .. ts:def:: ReserveCloseRequest + + interface ReserveCloseRequest { + // Signature of purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE`` over + // a `TALER_ReserveCloseRequestSignaturePS`. + reserve_sig: EddsaSignature; + + // Time when the client made the request. + // Timestamp must be reasonably close to the time of + // the exchange, otherwise the exchange may reject + // the request (with a status code of 400). + request_timestamp: Timestamp; + + // payto://-URI of the account the reserve balance is to be + // wired to. Must be of the form: 'payto://$METHOD' for a + // wire method supported by this exchange (if the + // method is not supported, this is a bad request (400)). + // If not given, the reserve's origin account + // will be used. If no origin account is known for the + // reserve and not given, this is a conflict (409). + payto_uri?: string; + + } + + .. ts:def:: ReserveCloseResponse + + interface ReserveCloseResponse { + + // Actual amount that will be wired (excludes closing fee). + wire_amount: Amount; + + } |