[taler-docs] branch master updated: 028: description of the fulfilment states

[gnunet]

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

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new a592c2d  028: description of the fulfilment states
a592c2d is described below

commit a592c2dec2e1ddb573db3af12faf9067679a2a28
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Mon Oct 10 12:50:43 2022 +0200

    028: description of the fulfilment states
---
 design-documents/028-deposit-policies.rst | 75 ++++++++++++++++++++++++++++---
 1 file changed, 68 insertions(+), 7 deletions(-)

diff --git a/design-documents/028-deposit-policies.rst 
b/design-documents/028-deposit-policies.rst
index 7d11dbf..166a5e4 100644
--- a/design-documents/028-deposit-policies.rst
+++ b/design-documents/028-deposit-policies.rst
@@ -6,7 +6,7 @@ DD28: Deposit Policy Extensions
   This is Work-In-Progress.
 
 Summary
-=======
+*******
 
 We will propose here a plugable mechanism in the exchange to support deposits
 with associated policy.  An exchange can enable support for such policies via
@@ -33,17 +33,17 @@ The policies shall be implemented as *extensions* to the 
exchange (see
 :doc:`006-extensions`).  
 
 Motivation
-==========
+**********
 
 TODO
 
 Background and Requirements
-===========================
+***************************
 
 TODO
 
 Proposed Solution
-=================
+*****************
 
 TODO, explain:
 
@@ -54,7 +54,7 @@ TODO, explain:
 - Typical choreography of a deposit with policy and its fulfilment
 
 Database-schema
-^^^^^^^^^^^^^^^
+===============
 
 TODO: Description
 
@@ -81,7 +81,7 @@ TODO: Description
                 label=<<B>policy_details</B>>
                 margin=20
                 policy_details [
-                  label="<id>id\l|<serial>serial_id 
(unique)\l|deadline\l|fulfilment_state\l"
+                  label="<id>id\l|<serial>serial_id 
(unique)\l|deadline\l|timeout_fulfilment_state\l|fulfilment_state\l"
                 ]
         }
 
@@ -98,7 +98,7 @@ TODO: Description
                 label=<<B>policy_details_fulfilments</B>>
                 margin=20
                 policy_details_fulfilments [
-                  
label="<ref_details>serial_id\l|<ref_fulfilments>fulfilment_id\l"
+                  
label="<ref_details>serial_id\l|<ref_fulfilments>fulfilment_id\l|new_amount\l"
                 ]
         }
 
@@ -108,6 +108,67 @@ TODO: Description
 
    }
 
+Policy Fulfilment States
+========================
+
+The fulfilment of a policy can be in one of the following six states, grouped
+in four classes (Pending, Success, Failure, Timeout):
+
+Pending
+       Initial state of a policy.  The proof of fulfilment is pending.
+
+Success-Transfer
+       Policy provably fulfilled. The semantics of the policy require that the
+       exchange MUST transfer a specific amount to the payto-URI in the
+       associated deposit.  The final amount might be different from the
+       original value during deposit and can be provided by the policy handler.
+
+Success-Refreshable
+       Policy provably fulfilled. The semantics of the policy require that
+       the coins' value in the associated deposit remains and the owner can
+       refresh them.
+
+Failure-Transfer
+       Policy provably UNfulfilled. The semantics of the policy require that
+       the exchange *MUST* transfer a specific amount to the payto-URI in the
+       associated deposit.  The final amount might be different from the 
original
+       amount during deposit and can be provided by the policy handler.
+
+Failure-Refreshable
+       Policy provably UNfulfilled. The semantics of the policy require that
+       the coins' value in the associated deposit remains and the owner can
+       refresh them.
+
+Timeout-Transfer
+       Policy timed out. The semantics of the policy require that the
+       exchange MUST transfer amount in the associated deposit to the
+       payto-URI.
+
+Timeout-Refreshable
+       Policy timed out. The semantics of the policy require that the
+       coins' value in the associated deposit remains and the owner can
+       refresh them.
+
+
+Invariants
+^^^^^^^^^^
+
+The following invariants need to be fulfilled and be checked by the auditor:
+
+1. When the fulfilment state of a policy in one of the classes **Pending** or
+   **Timeout**, there MUST NOT be an entry in the ``policy_details_fulfilment``
+   table for the corresponding ``serial_id``.
+
+2. Otherwise, fulfilment state of a policy MUST be in one of the classes
+   **Success** or **Failure**, IF AND ONLY IF there exists an entry in the
+   ``policy_details_fulfilment`` table for the corresponding ``serial_id``.
+
+3. If the amount in ``policy_details_fulfilment.new_amount`` is not NULL, it
+   MUST be less or equal to the total sum of all amounts defined in the
+   corresponding deposit entries, that reference the same ``policy_details``.
+
+   
+
 Alternatives
 ============
 

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