[taler-docs] branch master updated: docs

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 879fc64  docs
     new 6d0bf4f  Merge branch 'master' of git+ssh://git.taler.net/docs
879fc64 is described below

commit 879fc64fbdc2049e1bba5dd7b0c793c344348c2f
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Wed Mar 31 00:07:51 2021 +0200

    docs
---
 anastasis.rst | 100 ++++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 79 insertions(+), 21 deletions(-)

diff --git a/anastasis.rst b/anastasis.rst
index 562c296..19612a0 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1869,23 +1869,44 @@ Example results are thus:
 
 **pay:**
 
-FIXME: this is wrong! long polling!
-Optional arguments to try uploading just specific truths (example):
+This transition suggests to the reducer that a payment may have been made or
+is immanent, and that the reducer should check with the Anastasis service
+provider to see if the operation is now possible.  The operation takes one
+optional argument, which is a ``timeout`` value that specifies how long the
+reducer may wait (in long polling) for the payment to complete:
 
 .. code-block:: json
 
     {
-      "truth_index": [
-        1,
-        2
-      ]
+      "timeout":  { "d_ms" : 5000 },
     }
 
-..note::
+The specified timeout is passed on to the Anastasis service provider(s), which
+will wait this long before giving up.  If no timeout is given, the check is
+done as quickly as possible without additional delays.  The reducer will 
continue
+to either an updated state with the remaining payment requests, to the
+``BACKUP_FINISHED`` state (if all payments have been completed and the backup
+finished), or into an ``ERROR`` state in case there was an irrecoverable error,
+indicating the specific provider and how it failed.  An example for this
+final error state would be:
+
+.. code-block:: json
+
+    {
+      "backup_state": "ERROR",
+      "http_status" : 500,
+      "upload_status" : 52,
+      "provider_url" : "https://bad.example.com/";,
+    }
 
-  This is currently not supported (#6761).
+Here, the fields have the following meaning:
 
+  - **http_status** is the HTTP status returned by the Anastasis provider
+  - **upload_status** is the Taler error code return by the provider
+  - **provider_url** is the base URL of the failing provider
 
+In the above example, 52 would thus imply that the Anastasis provider failed to
+store information into its database.
 
 
 Recovery transitions
@@ -1893,7 +1914,12 @@ Recovery transitions
 
 **enter_user_attributes:**
 
-Arguments (example):
+This transition provides the user's personal attributes. The specific set of
+attributes required depends on the country of residence of the user.  Some
+attributes may be optional, in which case they should be omitted entirely
+(that is, not simply be set to ``null`` or an empty string).  The
+arguments are identical to the **enter_user_attributes__ transition from
+the backup process.  Example arguments would thus be:
 
 .. code-block:: json
 
@@ -1901,28 +1927,58 @@ Arguments (example):
       "identity_attributes": {
         "full_name": "Max Musterman",
         "social_security_number": "123456789",
-        "birth_year": 2000,
-        "birth_month": 1,
-        "birth_day": 1
+        "birthdate": "2000-01-01",
+        "birthplace": "Earth"
       }
     }
 
-Expected new state:
+However, in contrast to the backup process, the reducer will attempt to
+retrieve the latest recovery document from all known providers for the
+selected currency given the above inputs.  If a recovery document was found
+by any provider, the reducer will attempt to load it and transition to
+a state where the user can choose which challenges to satisfy:
 
 .. code-block:: json
 
     {
-      "backup_state": "CHALLENGE_SELECTING",
-      "identity_attributes": {
-        "full_name": "Max Musterman",
-        "social_security_number": "123456789",
-        "birth_year": 2000,
-        "birth_month": 1,
-        "birth_day": 1
-      }
+      "recovery_state": "CHALLENGE_SELECTING",
+      FIXME: document rest of state here!
     }
 
+If a recovery document was not found, either the user never performed
+a backup, entered incorrect attributes or used a provider not yet in
+the list of Anastasis providers.  Hence, the user must now either
+select a different provider, or go ``back`` and update the identity
+attributes.  In the case a recovery document was not found, an
+example for the new state is:
+
+.. code-block:: json
+
+    {
+      "recovery_state": "CHALLENGE_SELECTING",
+      FIXME: document rest of state here!
+    }
 
+**change_version:**
+
+Even if a recovery document was found, it is possible that the user
+intended to recover a different version, or recover a backup where
+the recovery document is stored at a different provider. Thus, the
+reducer allows the user to explicitly switch to a different provider
+or recovery document version using the ``change_version`` transition,
+which takes a provider URL and policy version as arguments:
+
+.. code-block:: json
+
+    {
+      "provider_url": "https://localhost:8080/";,
+      "version": 2 // FIXME: correct like this?
+    }
+
+The resulting states are the same as those of the
+``enter_user_attributes`` transition, except that the recovery
+document version is not necessarily the latest available version
+at the provider.
 
 
 **select_challenge:**
@@ -1931,6 +1987,8 @@ Selecting a challenge takes various formats, depending on 
the method.
 Specifically, in the case of a security question, the answer should
 already be provided.
 
+FIXME: give more details!
+
 Arguments (example):
 
 .. code-block:: json

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.