From 4e406e059e1fb5f9f91e22e197e9fc9b076dbd9f Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sun, 9 May 2021 13:41:43 +0200
Subject: document test vector for #6855

---
 core/api-merchant.rst                  | 17 +++++++++++-----
 design-documents/018-contract-json.rst | 36 +++++++++++++++++++++++++++++++++-
 2 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index c1de77e7..60840756 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1541,12 +1541,19 @@ Creating orders
     The backend has successfully created the proposal.  The response is a
     :ts:type:`PostOrderResponse`.
   :http:statuscode:`404 Not found`:
-    The order given used products from the inventory, but those were not found
-    in the inventory.  Or the merchant instance is unknown (including possibly the instance being not configured for new orders).  Details in the
-    error code. NOTE: no good way to find out which product is not in the
-    inventory, we MAY want to specify that in the reply.
+    Possible reasons are:
+    (1) The order given used products from the inventory, but those were
+        not found in the inventory.
+    (2) The merchant instance is unknown (including possibly the instance
+        being not configured for new orders).
+    (3) The wire method specified is not supported by the backend.
+    Details in the error code.
+    NOTE: currently the client has no good way to find out which product
+    is not in the inventory, we MAY want to specify that in the reply.
   :http:statuscode:`409 Conflict`:
-    A different proposal already exists under the specified order ID.
+    A different proposal already exists under the specified order ID,
+    or the requested currency is not supported by this backend. Details in
+    the error code.
   :http:statuscode:`410 Gone`:
     The order given used products from the inventory that are out of stock.
     The response is a :ts:type:`OutOfStockResponse`.
diff --git a/design-documents/018-contract-json.rst b/design-documents/018-contract-json.rst
index 4208febc..2162d6ed 100644
--- a/design-documents/018-contract-json.rst
+++ b/design-documents/018-contract-json.rst
@@ -102,7 +102,7 @@ member of the parent object.
     },
    }
 
-   => 
+   =>
 
    {
     ...props,
@@ -146,6 +146,40 @@ resulting bytes are terminated with a single 0-byte and then hashed with
 SHA512.
 
 
+Test vector
+-----------
+
+The follwing input contains top-level and nested forgettable
+fields, as well as booleans, integers, strings and objects
+as well as non-forgettable fields.  It is thus suitable as
+a minimal interoperability test:
+
+.. code-block:: json
+
+  {
+    "k1": 1,
+    "_forgettable": {
+      "k1": "SALT"
+    },
+    "k2": {
+      "n1": true,
+      "_forgettable": {
+        "n1": "salt"
+      }
+    },
+    "k3": {
+      "n1": "string"
+    }
+  }
+
+Hashing the above contract results in the following Crockford base32 encoded
+hash
+``287VXK8T6PXKD05W8Y94QJNEFCMRXBC9S7KNKTWGH2G2J2D7RYKPSHNH1HG9NT1K2HRHGC67W6QM6GEC4BSN1DPNEBCS0AVDT2DBP5G''.
+
+Note that typically the salt values must be chosen at random, only for this test we use static salt values.
+
+
+
 Discussion / Q&A
 ================
 
-- 
cgit v1.2.3