diff options
author | Christian Grothoff <christian@grothoff.org> | 2022-06-02 11:20:42 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2022-06-02 11:21:42 +0200 |
commit | 319cbc562b6b4627e4ec5ac23d8cb8a059d33409 (patch) | |
tree | 1ee85adca14837805f9eece7bdcbc145080f6be3 /core | |
parent | fa8f882a4e24ecfdc3cab00cbc44161e5619036f (diff) | |
download | docs-319cbc562b6b4627e4ec5ac23d8cb8a059d33409.tar.gz docs-319cbc562b6b4627e4ec5ac23d8cb8a059d33409.tar.bz2 docs-319cbc562b6b4627e4ec5ac23d8cb8a059d33409.zip |
-work on p2p docs
Diffstat (limited to 'core')
-rw-r--r-- | core/api-exchange.rst | 84 |
1 files changed, 29 insertions, 55 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index b55fb6be..0a1a1f8f 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1121,7 +1121,7 @@ exchange. balance: Amount; } - + .. http:post:: /reserves/$RESERVE_PUB/status Request information about a reserve or an account. @@ -2990,23 +2990,16 @@ 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. - TODO: maybe use POST to /purses/$PURSE_PUB/status instead? + 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 ``NUMBER`` milliseconds for completion of a merge operation before sending the HTTP response. @@ -3014,9 +3007,6 @@ Wallet-to-wallet transfers the exchange 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:** @@ -3024,11 +3014,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:** @@ -3041,26 +3030,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, possibly "never". + merge_timestamp: Timestamp; - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; + // Time of the deposits being complete, possibly "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. + merge_timestamp: Timestamp; // EdDSA signature of the exchange over a // `TALER_PurseStatusResponseSignaturePS` @@ -3071,19 +3052,6 @@ Wallet-to-wallet transfers // EdDSA public key exchange used for 'exchange_sig'. exchange_pub: EddsaPublicKey; - // EdDSA public key used to approve merges of this purse. - merge_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; - } @@ -3145,6 +3113,12 @@ Wallet-to-wallet transfers interface PurseRequest { + // Array of coins to deposit into the purse. + deposits: PurseDeposit[]; + } + + interface PurseDeposit { + // EdDSA signature of the purse over a // `TALER_PurseRequestSignaturePS` // of purpose ``TALER_SIGNATURE_WALLET_PURSE_CREATE`` @@ -3168,7 +3142,7 @@ Wallet-to-wallet transfers // Minimum age of deposits made into the purse minimum_age: Integer; - + // 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. @@ -3465,7 +3439,7 @@ Wallet-to-wallet transfers .. ts:def:: MergeAccepted interface MergeAccepted { - + // Current balance in the purse. balance: Amount; @@ -3542,9 +3516,9 @@ Wallet-to-wallet transfers } - + -- TODO: API to deposit into existing purse - + .. _exchange_wads: |