DD50, notes and FIXMEs.

1 files changed, 52 insertions, 34 deletions

diff --git a/design-documents/050-libeufin-nexus.rst b/design-documents/050-libeufin-nexus.rst
index 16d92c53..fc09888f 100644
--- a/design-documents/050-libeufin-nexus.rst
+++ b/design-documents/050-libeufin-nexus.rst
@@ -15,6 +15,10 @@ The existing Nexus design is overly complex to configure, develop and
 maintain.  It supports EBICS features we do not need, and lacks key features
 (like long-polling) that are absolutely needed.
 
+..
+  long-polling at the TWG is NOT NetzBon-critical, as the TWG is only offered
+  by the Bank.
+
 We also have several implementations with Nexus, Bank and Depolymerization
 subsystems, and it would be good to combine some of them.
 
@@ -56,11 +60,11 @@ Configuration file
   USER_ID = myuser
   PARTNER_ID = myorg
   SYSTEM_ID = banksys
-  ACCOUNT_NUMBER = DE1234567890 # could be an IBAN, does not have to be
+  ACCOUNT_NUMBER = DE1234567890 # could be an IBAN, does not have to be (FIXME: what? Maybe the alphanumeric name given by the bank?)
   BANK_PUBLIC_KEYS_FILE = enc-auth-keys.json
   CLIENT_PRIVATE_KEY_FILE = my-private-key.json
   ACCOUNT_META_DATA_FILE = ebics-meta.json
-  EBICS_DIALECT = postfinance
+  EBICS_DIALECT = postfinance # (FIXME: should this be removed and only do postfinance, at least for the very first version?  Also 'EBICS dialect' was always misleading because the variations happen at EBICS but also at the ISO20022 layer.)
   
   [nexus-postgres]
   CONFIG = postgres:///libeufin-nexus
@@ -117,42 +121,43 @@ JSON with:
   * bank_code
   * account_holder_name
 
-
 Database schema
 ---------------
 
-CREATE TABLE incoming_transactions
-  (incoming_transaction_id INT8 GENERATED BY DEFAULT AS IDENTITY
-  ,amount taler_amount NOT NULL
-  ,wire_transfer_subject TEXT
-  ,execution_time INT8 NOT NULL
-  ,debit_payto_uri TEXT NOT NULL
-  ,bank_transfer_id TEXT NOT NULL -- EBICS or Depolymerizer (generic)
-  ,bounced BOOL DEFAULT FALSE -- to track if we bounced it
-  );
-
-CREATE TABLE outgoing_transactions
-  (outgoing_transaction_id INT8 GENERATED BY DEFAULT AS IDENTITY
-  ,amount taler_amount NOT NULL
-  ,wire_transfer_subject TEXT
-  ,execution_time INT8 NOT NULL
-  ,credit_payto_uri TEXT NOT NULL
-  ,bank_transfer_id TEXT NOT NULL
-  );
-
-CREATE TABLE initiated_outgoing_transactions
-  (initiated_outgoing_transaction_id INT8 GENERATED BY DEFAULT AS IDENTITY -- used as our ID in PAIN
-  ,amount taler_amount NOT NULL
-  ,wire_transfer_subject TEXT
-  ,execution_time INT8 NOT NULL
-  ,credit_payto_uri TEXT NOT NULL
-  ,out_transaction_id INT8 REFERENCES outgoing_transactions (out_transaction_id) -- NULL if not initiated, set by EBICS server
-  ,initiated BOOL DEFAULT FALSE
-  ,hidden BOOL DEFAULT FALSE
-  ,client_request_uuid TEXT NOT NULL UNIQUE
-  ,failure_message TEXT
-  );
 
+.. code-block:: shell-session
+
+  CREATE TABLE incoming_transactions
+    (incoming_transaction_id INT8 GENERATED BY DEFAULT AS IDENTITY
+    ,amount taler_amount NOT NULL
+    ,wire_transfer_subject TEXT
+    ,execution_time INT8 NOT NULL
+    ,debit_payto_uri TEXT NOT NULL
+    ,bank_transfer_id TEXT NOT NULL -- EBICS or Depolymerizer (generic)
+    ,bounced BOOL DEFAULT FALSE -- to track if we bounced it
+    );
+  
+  CREATE TABLE outgoing_transactions
+    (outgoing_transaction_id INT8 GENERATED BY DEFAULT AS IDENTITY
+    ,amount taler_amount NOT NULL
+    ,wire_transfer_subject TEXT
+    ,execution_time INT8 NOT NULL
+    ,credit_payto_uri TEXT NOT NULL
+    ,bank_transfer_id TEXT NOT NULL
+    );
+  
+  CREATE TABLE initiated_outgoing_transactions
+    (initiated_outgoing_transaction_id INT8 GENERATED BY DEFAULT AS IDENTITY -- used as our ID in PAIN
+    ,amount taler_amount NOT NULL
+    ,wire_transfer_subject TEXT
+    ,execution_time INT8 NOT NULL
+    ,credit_payto_uri TEXT NOT NULL
+    ,out_transaction_id INT8 REFERENCES outgoing_transactions (out_transaction_id) -- NULL if not initiated, set by EBICS server -- NOTE/FIXME: this is NULL also if it is initiated; it gets non-NULL only after it has been fetched from the bank.
+    ,initiated BOOL DEFAULT FALSE -- FIXME: would 'submitted' here be a better name?  initiated==false where the table name starts with 'initiated_..' sounds contradictory.
+    ,hidden BOOL DEFAULT FALSE -- NOTE/FIXME: please, exaplain this.
+    ,client_request_uuid TEXT NOT NULL UNIQUE
+    ,failure_message TEXT -- NOTE: that may mix soon failures (those found at initiation time), or late failures (those found out along a fetch operation)
+    );
 
 nexus-ebics-setup
 -----------------
@@ -164,6 +169,12 @@ The ebics-setup tool performs the following:
     --check-full-config, also sanity-check the configuration options of the
     other subsystems.
 
+..
+  Not extremely important, but: try to imitate the 'dry run' option offered
+  by the exchange, to avoid having a big config-check upfront, and instead
+  spread the check along the execution.
+
+
   * Checks if the private keys file exists, if not creates new private keys
     with flags "not submitted".
 
@@ -251,6 +262,13 @@ nexus-httpd
   * Runs facade-specific logic, such as bouncing transactions with mal-formed
     wire transfer subjects.
 
+..
+  FIXME (the above point): moving the bouncing to nexus-fetch would save one DB notification,
+  as nexus-fetch is the first component that's aware of incoming payments.
+  Another advantage is to still provide bouncing in case nexus-httpd is down.
+  That is still in line with the new policy of making Nexus Taler-specific,
+  as opposed to be a generic EBICS client.
+
   * Listens to notifications from nexus-ebics-fetch to run facade-logic and
     wake-up long pollers.