028: description of the fulfilment states

1 files changed, 68 insertions, 7 deletions

diff --git a/design-documents/028-deposit-policies.rst b/design-documents/028-deposit-policies.rst
index 7d11dbfb..166a5e48 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
 ============