diff options
| -rw-r--r-- | core/api-exchange.rst | 162 | ||||
| -rw-r--r-- | design-documents/031-invoicing.rst | 25 |
2 files changed, 160 insertions, 27 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 357aa565..6680cd88 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -4378,7 +4378,17 @@ KYC status updates Reserve control --------------- -This section is about a proposed API. It is not implemented. +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 @@ -4393,8 +4403,7 @@ This section is about a proposed API. It is not implemented. :http:statuscode:`200 OK`: The exchange responds with a `ReserveOpenResponse` object. :http:statuscode:`402 Payment Required`: - The reserve balance is insufficient to pay for the open operation. - The exchange responds with a `RequiredBalanceResponse` object. + The exchange responds with a `ReserveOpenFailure` object. :http:statuscode:`403 Forbidden`: The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid. This response comes with a standard `ErrorDetail` response. @@ -4415,6 +4424,10 @@ This section is about a proposed API. It is not implemented. // a `TALER_ReserveOpenRequestSignaturePS`. reserve_sig: EddsaSignature; + // Array of payments made towards the cost of the + // operation. + payments: OpenPaymentDetail[]; + // Time when the client made the request. // Timestamp must be reasonably close to the time of // the exchange, otherwise the exchange may reject @@ -4441,33 +4454,139 @@ This section is about a proposed API. It is not implemented. .. ts:def:: ReserveOpenResponse interface ReserveOpenResponse { - // Balance left in the reserve after the account_fee - // was charged. - balance: Amount; - // Transaction cost for extending the expiration time. // Excludes KYC fees. open_cost: Amount; - // New expiration time for the reserve. + // Current expiration time for the reserve. reserve_expiration: Timestamp; } - .. ts:def:: RequiredBalanceResponse + .. ts:def:: ReserveOpenFailure - interface RequiredBalanceResponse { - // Balance left in the reserve after the account_fee - // was charged. - balance: Amount; + 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. + contribution: 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/$RESERVE_PUB/attest + + 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:** - // Transaction cost for extending to the - // requested expiration time. - // Includes applicable KYC fees. - required: Amount; + .. 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/$RESERVE_PUB/attest + + 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; + + // 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`. + reserve_sig: EddsaSignature; + + // 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 @@ -4516,13 +4635,6 @@ This section is about a proposed API. It is not implemented. // the request (with a status code of 400). request_timestamp: Timestamp; - // Maximum amount to transfer to the indicated - // account (after fees). If not given, the - // reserve will be completely drained. The amount - // given may exceed the reserve balance, in which case - // the reserve will also be completely drained. - maximum_transfer?: Amount; - // 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 @@ -4537,8 +4649,6 @@ This section is about a proposed API. It is not implemented. .. ts:def:: ReserveCloseResponse interface ReserveCloseResponse { - // Balance left in the reserve after the close. - balance: Amount; // Actual amount that will be wired (excludes closing fee). wire_amount: Amount; diff --git a/design-documents/031-invoicing.rst b/design-documents/031-invoicing.rst index 4e2ebc5f..24c64d79 100644 --- a/design-documents/031-invoicing.rst +++ b/design-documents/031-invoicing.rst @@ -36,6 +36,25 @@ Requirements * Reasonable UX and overall design impact. +Unclear in the current proposal are: + + * How to pay for the opening. Do we support the use of + coins, or should we require the user to have a + sufficient balance in the reserve, or do we allow + both? Probably best to only support one. As + reserves are typically instant-drained by the + wallet, might be best to require coins? + + * Here (and in other places!), the payment of the KYC + fee remains, eh, obscure. This should probably be + part of the KYC endpoints, and not for each + KYC-trigger. + + * Proposed table structure does not properly capture + if user paid extra for more purses (I could open + for 3 years, then pay for 5x purses in year 1, but + should not automatically get 5x purses in years 2/3). + Proposed Solution ================= @@ -55,18 +74,22 @@ reserve after tips are no longer issued. The solution needs three new tables for: * account creation data: + - serial - timestamp - signature affirming desire to create account - KYC requirement row * account creation payment data: + - serial (for replication) - coin signature (affirming payment) - amount contributed - account creation link (serial row ID) * reserve closure request data: + + - serial (for replication) - timestamp - reserve signature - target account payto:// URI @@ -100,7 +123,7 @@ Reserve Attestation * This new endpoint ``/reserve/$RID/attest`` allows the user to obtain exchange-signed KYC information about themselves. - This will basically be a list of (standardized) attributes + This will basically be a list of (GANA standardized) attributes and exchange signatures. The user can then choose which of these attributes to include when invoicing. The available set of attributes may differ depending on the KYC providers |