From 4bfab9803e89e3095dd4bc751887337ebd9d7e07 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 7 Oct 2016 15:20:11 +0200 Subject: porting exchange API to new style --- api-exchange.rst | 66 +++++++++++++++++++++++--------------------------------- 1 file changed, 27 insertions(+), 39 deletions(-) (limited to 'api-exchange.rst') diff --git a/api-exchange.rst b/api-exchange.rst index 9bf1eb40..3891306e 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -357,12 +357,10 @@ exchange. // Transfer details uniquely identifying the transfer, only present if type is "DEPOSIT". transfer_details?: any; - // `base32`_ encoding of `TALER_WithdrawRequestPS`_. This field appears only if `type` - // is "WITHDRAW". + // `base32`_ encoding of `TALER_WithdrawRequestPS`_ with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. This field appears only if `type` is "WITHDRAW". details?: string; // Signature over the transaction `details`. - // Purpose: TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW signature?: EddsaSignature; } @@ -413,14 +411,12 @@ exchange. // denomination private key coin_ev: CoinEnvelope; - // public (EdDSA) key of the reserve from which the coin should be + // `public (EdDSA) key `_ of the reserve from which the coin should be // withdrawn. The total amount deducted will be the coin's value plus the // withdrawal fee as specified with the denomination information. reserve_pub: EddsaPublicKey; - // Signature (binary-only) of purpose - // `TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW` created with the reserves's - // private key + // Signature of `TALER_WithdrawRequestPS`_ created with the `reserves's private key `_ reserve_sig: EddsaSignature; } @@ -500,7 +496,7 @@ denomination. // The merchant's account details. This must be a JSON object whose format // must correspond to one of the supported wire transfer formats of the exchange. // See `wireformats`_. - wire: WireFormat; + wire: Object; // SHA-512 hash of the merchant's payment details from `wire`. Although // strictly speaking redundant, this helps detect inconsistencies. @@ -510,7 +506,7 @@ denomination. // details are never disclosed to the exchange. H_contract: HashCode; - // coin's public key, both ECDHE and EdDSA. + // `coin's public key `_, both ECDHE and EdDSA. coin_pub: CoinPublicKey; // denomination RSA key with which the coin is signed @@ -530,7 +526,7 @@ denomination. // 64-bit transaction id for the transaction between merchant and customer transaction_id: number; - // EdDSA public key of the merchant, so that the client can identify the + // EdDSA `public key of the merchant `_, so that the client can identify the // merchant for refund requests. merchant_pub: EddsaPublicKey; @@ -538,9 +534,7 @@ denomination. // exchange, possibly zero if refunds are not allowed. refund_deadline: Timestamp; - // The EdDSA signature (binary-only) made with purpose - // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` made by the customer with the coin's - // private key. + // Signature of `TALER_DepositRequestPS`_, made by the customer with the `coin's private key `_ coin_sig: EddsaSignature; } @@ -555,14 +549,14 @@ denomination. // The string constant "DEPOSIT_OK" status: string; - // the EdDSA :ref:`signature` (binary-only) with purpose - // `TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT` using a current signing key of the - // exchange 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. + // the EdDSA signature of `TALER_DepositConfirmation`_ using a current + // `signing key of the exchange `_ 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. sig: EddsaSignature; - // public EdDSA key of the exchange that was used to generate the signature. + // `public EdDSA key of the exchange `_ 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. @@ -581,6 +575,7 @@ denomination. history: CoinSpendHistoryItem[]; } + .. _`tsref-type-CoinSpendHistoryItem`: .. _CoinSpendHistoryItem: .. code-block:: tsref @@ -596,20 +591,14 @@ denomination. // the coin's denomination value. amount: Amount; - // base32 binary encoding of the transaction data as a - // `TALER_DepositRequestPS` or `TALER_RefreshMeltCoinAffirmationPS` - // or `TALER_RefundRequestPS` - // struct described in :ref:`Signatures`. Its `purpose` should match our - // `type`, `amount_with_fee`, should match our `amount`, and its `size` - // should be consistent with the respective struct type. + // `base32`_ binary encoding of the transaction data as a + // `TALER_DepositRequestPS`_ or `TALER_RefreshMeltCoinAffirmationPS`_ + // or `TALER_RefundRequestPS`_ details: string; - // the EdDSA :ref:`signature` (binary-only) made with purpose - // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` or - // `TALER_SIGNATURE_WALLET_COIN_MELT` or - // `TALER_SIGNATURE_MERCHANT_REFUND` over the transaction's details. + // `EdDSA Signature `_ of what we got in `details`. // Note that in the case of a 'refund', the signature is made with - // the public key of the merchant, and not that of the coin. + // the `public key of the merchant `_, and not `that of the coin `_ signature: EddsaSignature; } @@ -664,7 +653,7 @@ the API during normal operation. // For each of the `n` new coins, `kappa` transfer keys. // coin_evs[j][k] is the k-th blank (of kappa) for the k-th new coin (of n). - coin_evs: CoinBlank[][] + coin_evs: CoinBlank[][]; // FIXME TBD // `kappa` transfer public keys (ephemeral ECDHE keys) transfer_pubs: EddsaPublicKey[]; @@ -682,16 +671,16 @@ the API during normal operation. .. code-block:: tsref interface MeltCoin { - // Coin public key, uniquely identifies the coin + // `Coin public key `_, uniquely identifies the coin coin_pub: string; // The denomination public key allows the exchange to determine total coin value. denom_pub: RsaPublicKey; - // Signature over the coin public key by the denomination. + // Signature over the `coin public key `_ by the denomination. denom_sig: RsaSignature; - // Signature by the coin over the session public key + // Signature by the `coin `_ over the session public key (FIXME: put link to some C definition of this key?) confirm_sig: EddsaSignature; // Amount of the value of the coin that should be melted as part of @@ -716,12 +705,11 @@ the API during normal operation. // Which of the `kappa` indices does the client not have to reveal. noreveal_index: number; - // binary-only Signature_ for purpose `TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT` - // whereby the exchange affirms the successful melt and confirming the - // `noreveal_index` + // Signature of `TALER_RefreshMeltConfirmationPS`_ whereby the exchange + // affirms the successful melt and confirming the `noreveal_index` exchange_sig: EddsaSignature; - // public EdDSA key of the exchange that was used to generate the signature. + // `public EdDSA key `_ 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. @@ -823,7 +811,7 @@ the API during normal operation. object: string; // Information about each melted coin - refresh_melt_info: OldCoinInfo; + refresh_melt_info: OldCoinInfo; // FIXME // array with RSA denomination public keys of the coins the original // refresh request asked to be exchangeed -- cgit v1.2.3