From 91d03a694912fb416cadc23a2fc45d05dda2abb7 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Tue, 11 Oct 2016 18:19:59 +0200 Subject: polishing merchant's documetation --- api-merchant.rst | 101 ++++++++++++++++++------------------------------------- 1 file changed, 33 insertions(+), 68 deletions(-) (limited to 'api-merchant.rst') diff --git a/api-merchant.rst b/api-merchant.rst index 749681d3..a15e0b28 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -57,11 +57,13 @@ The Frontent HTTP API .. code-block:: tsref interface DepositPermission { - // the hashed :ref:`wire details ` of this merchant. The wallet takes this value as-is from the contract - // `MyStruct`_ - H_wire: MyStruct; + // the hashed `wire details `_ of this merchant. + // The wallet takes this value as-is from the contract + H_wire: HashCode; - // the base32 encoding of the field `h_contract` of the contract `blob `. The wallet can choose whether to take this value obtained from the field `h_contract`, or regenerating one starting from the values it gets within the contract + // `base32`_ encoded `TALER_ContractPS`_. The wallet can choose whether + // to take this value obtained from the field `h_contract`, + // or regenerating one starting from the values it gets within the contract H_contract: HashCode; // a 53-bit number corresponding to the contract being agreed on @@ -73,10 +75,11 @@ The Frontent HTTP API // maximum fees merchant agreed to cover as per the contract max_fee: Amount; - // The merchant instance which is going to receive the final wire transfer. See :ref:`instances-lab` + // The merchant instance which is going to receive the final wire transfer. + // See `instances-lab`_ receiver: string; - // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT + // Signature of `TALER_ContractPS`_ merchant_sig: EddsaSignature; // a timestamp of this deposit permission. It equals just the contract's timestamp @@ -107,10 +110,10 @@ The Frontent HTTP API // denomination key denom_pub: RsaPublicKey; - // exchange's signature over this coin's public key + // exchange's signature over this `coin's public key `_ ub_sig: RsaSignature; - // the signature made by the coin's private key on a `struct TALER_DepositRequestPS`. See section `Signatures` on the exchange's API page. + // Signature of `TALER_DepositRequestPS`_ coin_sig: EddsaSignature; } @@ -204,7 +207,7 @@ The following API are made available by the merchant's `backend` to the merchant .. code-block:: tsref interface PaymentResponse { - // Signature of TALER_SIGNATURE_MERCHANT_PAYMENT_OK made by the merchant + // Signature of `TALER_PaymentResponsePS`_ merchant_sig: EddsaSignature; // Contract's hash being signed over @@ -322,12 +325,6 @@ The following API are made available by the merchant's `backend` to the merchant total_amount: Amount; } ---------- -Encodings ---------- - -Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`. - .. _contract: ------------------ @@ -345,16 +342,24 @@ that is legally non-binding: // The actual contract contract: Contract; - // The hash of the contract, encoded in base32, provided - // as a convenience. All components that do not fully trust - // the merchant must verify this field. + // Contract's hash, provided as a convenience. All components that do + // not fully trust the merchant must verify this field. H_contract: HashCode ; - // Signature over the contract made by the merchant. - // Must confirm to the `Signature specification`_ below. + // Signature over the hashcode of `contract` made by the merchant. merchant_sig: EddsaSignature; } +.. note:: + When the contract is signed by the merchant or the wallet, the + signature is made over the hash of the JSON text, as the contract may + be confidential between merchant and customer and should not be + exposed to the exchange. The hashcode is generated by hashing the + encoding of the contract's JSON obtained by using the flags + ``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson + documentation + `_. + The `contract` must have the following structure: .. _tsref-type-Contract: @@ -419,9 +424,8 @@ The `contract` must have the following structure: // Exchanges that the merchant accepts even if it does not accept any auditors that audit them. exchanges: Exchange[]; - // Map from label to a `Location`_. - // The label strings must not contain a colon (`:`). - locations: { [label: string]: Location>; + // Map from label to a location + locations: { [label: string]: Location }; // FIXME make 'Location' clickable } The wallet must select a exchange that either the mechant accepts directly by listing it in the exchanges arry, or for which the merchant accepts an auditor that audits that exchange by listing it in the auditors array. @@ -488,19 +492,22 @@ The `contract` must have the following structure: street_number?: string; } - .. code-block:: ts + .. _tsref-type-Auditor: + .. code-block:: tsref interface Auditor { // official name name: string; - auditor_pub: EddsaPublicKey + // Auditor's public key + auditor_pub: EddsaPublicKey; // Base URL of the auditor url: string; } - .. code-block:: ts + .. _tsref-type-Exchange: + .. code-block:: tsref interface Exchange { // the exchange's base URL @@ -509,45 +516,3 @@ The `contract` must have the following structure: // master public key of the exchange master_pub: EddsaPublicKey; } - - -.. _`Signature specification`: - -When the contract is signed by the merchant or the wallet, the -signature is made over the hash of the JSON text, as the contract may -be confidential between merchant and customer and should not be -exposed to the exchange. The hashcode is generated by hashing the -encoding of the contract's JSON obtained by using the flags -``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson -documentation -`_. -The following structure is a container for the signature. The purpose -should be set to ``TALER_SIGNATURE_MERCHANT_CONTRACT``. - -.. _contract-blob: -.. code-block:: c - - struct MERCHANT_Contract - { - struct GNUNET_CRYPTO_EccSignaturePurpose purpose; - /** - * Transaction ID must match the one in the JSON contract, here given - * in big endian. - */ - uint64_t transaction_id; - - /** - * Total amount to be paid for the contract, must match JSON "amount". - */ - struct TALER_AmountNBO total_amount; - - /** - * Total amount to be paid for the contract, must match JSON "max_fee". - */ - struct TALER_AmountNBO max_fee; - - /** - * Hash of the overall JSON contract. - */ - struct GNUNET_HashCode h_contract; - } -- cgit v1.2.3 From 6dce8e6a5904bb79a2389c736dc287de4fa48f74 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 13 Oct 2016 13:45:49 +0200 Subject: #4713 --- api-merchant.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'api-merchant.rst') diff --git a/api-merchant.rst b/api-merchant.rst index a15e0b28..5a05d831 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -366,6 +366,9 @@ The `contract` must have the following structure: .. code-block:: tsref interface Contract { + // Human-readable description of the whole purchase + summary: string; + // Total price for the transaction. // The exchange will subtract deposit fees from that amount // before transfering it to the merchant. -- cgit v1.2.3 From ebc9d338c9a677f99a6560bd85236cc45ab9e4a6 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 13 Oct 2016 13:46:08 +0200 Subject: note --- api-merchant.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'api-merchant.rst') diff --git a/api-merchant.rst b/api-merchant.rst index 5a05d831..e8c9c9cd 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -367,6 +367,7 @@ The `contract` must have the following structure: interface Contract { // Human-readable description of the whole purchase + // NOTE: still not implemented summary: string; // Total price for the transaction. -- cgit v1.2.3