[taler-cashless2ecash] branch master updated: sql: add comment statements for table, columns and types

[gnunet]

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

joel-haeberli pushed a commit to branch master
in repository cashless2ecash.

The following commit(s) were added to refs/heads/master by this push:
     new fc93689  sql: add comment statements for table, columns and types
fc93689 is described below

commit fc93689cf80f9695e99dad88428a0ef14aa097d0
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Wed Mar 13 10:03:14 2024 +0100

    sql: add comment statements for table, columns and types
---
 data/nonce2ecash_schema.sql                   | 134 ++++++++++++++------------
 specs/api-nonce2ecash.rst                     |  33 ++++++-
 specs/db_nonce2ecash_erd.plantuml             |  22 -----
 specs/provider_registration_sequence.plantuml |  13 ---
 4 files changed, 102 insertions(+), 100 deletions(-)

diff --git a/data/nonce2ecash_schema.sql b/data/nonce2ecash_schema.sql
index 7a4f9a8..71d338a 100644
--- a/data/nonce2ecash_schema.sql
+++ b/data/nonce2ecash_schema.sql
@@ -1,93 +1,107 @@
 --  => proper versioning.sql nehmen (siehe exchange.git),
 DROP SCHEMA IF EXISTS nonce2ecash CASCADE;
 
--- The schema nonce2ecash contains all 
 CREATE SCHEMA nonce2ecash;
+COMMENT ON SCHEMA nonce2ecash
+  IS 'Schema containing all tables and types related to nonce2ecash';
 
--- The enumeration contains the states which a withdrawal can be in.
--- The states are the same as in the bank-integration API:
---      pending  : the operation is pending parameters selection (exchange and 
reserve public key)
---      selected : the operations has been selected and is pending confirmation
---      aborted  : the operation has been aborted
---      confirmed: the transfer has been confirmed and registered by the bank
-CREATE TYPE nonce2ecash.withdrawal_operation_status AS ENUM (
+SET search_path TO nonce2ecash;
+
+CREATE TYPE withdrawal_operation_status AS ENUM (
      'pending',
      'selected',
-     -- => bound? -> I wanted to stick to the same terms as the 
bank-integration API
      'aborted',
      'confirmed'
 );
+COMMENT ON TYPE withdrawal_operation_status
+  IS 'Enumerates the states of a withdrawal operation.
+   The states are the same as in the bank-integration API:
+    pending  : the operation is pending parameters selection (exchange and 
reserve public key)
+    selected : the operations has been selected and is pending confirmation
+    aborted  : the operation has been aborted
+    confirmed: the transfer has been confirmed and registered by the bank';
+
 
--- copied from 
https://git.taler.net/merchant.git/tree/src/backenddb/merchant-0001.sql
-CREATE TYPE nonce2ecash.taler_amount_currency
+CREATE TYPE taler_amount_currency
   AS (val INT8, frac INT4 , curr VARCHAR(12));
-COMMENT ON TYPE nonce2ecash.taler_amount_currency
-  IS 'Stores an amount, fraction is in units of 1/100000000 of the base value';
+COMMENT ON TYPE taler_amount_currency
+  IS 'Stores an amount, fraction is in units of 1/100000000 of the base value.
+  copied from 
https://git.taler.net/merchant.git/tree/src/backenddb/merchant-0001.sql';
+
 
--- The terminal_provider table describes a specific provider of a 
cashless2ecash
--- terminal provider. 
-CREATE TABLE IF NOT EXISTS nonce2ecash.terminal_provider (
-    -- Uniquely identifies a provider.
+CREATE TABLE IF NOT EXISTS terminal_provider (
     provider_terminal_id INT8 GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
-    -- Name of the provider. Must be unique, because used to choose the 
process 
-    -- proofing the transaction. 
     name TEXT NOT NULL UNIQUE,
-    -- The url of the providers backend, used to proof the transaction.
     backend_base_url TEXT NOT NULL,
-    -- Credentials used to access the backend of the provider.
     backend_credentials TEXT NOT NULL
 );
+COMMENT ON TABLE terminal_provider
+  IS 'Table describing providers of nonce2ecash terminal';
+COMMENT ON COLUMN terminal_provider.provider_terminal_id
+  IS 'Uniquely identifies a provider';
+COMMENT ON COLUMN terminal_provider.name
+  IS 'Name of the provider, used for selection in transaction proofing';
+COMMENT ON COLUMN terminal_provider.backend_base_url
+  IS 'URL of the provider backend for transaction proofing';
+COMMENT ON COLUMN terminal_provider.backend_credentials
+  IS 'Credentials used to access the backend of the provider';
 
--- The terminal table contains information about terminals of providers.
--- This includes the information if they are active (allowed to do 
transactions)
--- and their credentials.
-CREATE TABLE IF NOT EXISTS nonce2ecash.terminal (
-    -- Uniquely identifies a terminal.
+
+CREATE TABLE IF NOT EXISTS terminal (
     terminal_id INT8 GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
-    -- The access token of the terminal. The access token is used to 
-    -- authenticate against the nonce2ecash API.
     access_token BYTEA CHECK (LENGTH(access_token)=32) NOT NULL,
-    -- A terminal may be deactivated. This MUST be checked at each request of
-    -- the terminal. This allows to immediately block any terminal from the 
-    -- withdrawal process if necessary.
-    active BOOLEAN DEFAULT TRUE NOT NULL,
-    -- The description is thought to help humans to identify a terminal.
-    -- This may include the location and an identifier of the terminal.
+    active BOOLEAN NOT NULL DEFAULT TRUE,
     description TEXT,
-    -- Each terminal belongs to a specific terminal provider. The terminal
-    -- provider indicates which process is used by nonce2ecash to proof a 
-    -- transaction.
     provider_id INT8 NOT NULL REFERENCES 
terminal_provider(provider_terminal_id)
 );
+COMMENT ON TABLE terminal
+  IS 'Table containing information about terminals of providers';
+COMMENT ON COLUMN terminal.terminal_id
+  IS 'Uniquely identifies a terminal';
+COMMENT ON COLUMN terminal.access_token
+  IS 'The access token of the terminal used for authentication against the 
nonce2ecash API';
+COMMENT ON COLUMN terminal.active
+  IS 'Indicates if the terminal is active or deactivated';
+COMMENT ON COLUMN terminal.description
+  IS 'Description to help identify the terminal. This may include the location 
and an identifier of the terminal.';
+COMMENT ON COLUMN terminal.provider_id
+  IS 'Indicates the terminal provider to which the terminal belongs';
+
 
--- A withdrawal represents a withdrawal process initiated by one terminal.
-CREATE TABLE IF NOT EXISTS nonce2ecash.withdrawal (
-    -- The withdrawal id is a nonce generated by the terminal requesting a 
-    -- withdrawal.
+CREATE TABLE IF NOT EXISTS withdrawal (
     withdrawal_id BYTEA PRIMARY KEY CHECK (LENGTH(withdrawal_id)=32),
-    -- The reserve public key which will hold the amount of the withdrawal
-    -- after completion.
     reserve_pub_key BYTEA CHECK (LENGTH(reserve_pub_key)=32) NOT NULL,
-    -- The timestamp, when the withdrawal request was initially issued.
     registration_ts INT8 NOT NULL,
-    -- The amount of the withdrawal. This amount is the effective amount to be 
-    -- put into the reserve. Fees are stored in the fees field.
-    amount nonce2ecash.taler_amount_currency NOT NULL,
-    -- The fees of the withdrawal. This includes the fees of the exchange and 
the
-    -- fees of the provider.
-    fees nonce2ecash.taler_amount_currency NOT NULL,
-    -- The status of the withdrawal. Indicates in which step of the process
-    -- the withdrawal currently is.
+    amount taler_amount_currency NOT NULL,
+    fees taler_amount_currency NOT NULL,
     withdrawal_status withdrawal_operation_status NOT NULL,
-    -- The terminal id indicates at which terminal the withdrawal was 
initiated.
-    terminal_id BIGINT NOT NULL REFERENCES terminal(id)
-    -- Stores a transaction identifiers supplied by the provider which helps to
-    -- request information about it at the providers backend.
+    terminal_id INT8 NOT NULL REFERENCES terminal(terminal_id),
     provider_transaction_id TEXT,
-    -- Timestamp allowing to remember when we asked last about this 
transaction.
-    -- This helps us controlling retries.
     last_retry_ts INT8,
-    -- stores proof of transaction upon final completion delivered by the 
-    -- providers system
+    retry_counter INT4 NOT NULL DEFAULT 0,
     completion_proof BLOB
 );
+COMMENT ON TABLE withdrawal
+  IS 'Table representing withdrawal processes initiated by terminals';
+COMMENT ON COLUMN withdrawal.withdrawal_id
+  IS 'The withdrawal id is a nonce generated by the terminal requesting a 
withdrawal';
+COMMENT ON COLUMN withdrawal.reserve_pub_key
+  IS 'Reserve public key for the reserve which will hold the withdrawal amount 
after completion';
+COMMENT ON COLUMN withdrawal.registration_ts
+  IS 'Timestamp of when the withdrawal request was registered';
+COMMENT ON COLUMN withdrawal.amount
+  IS 'Effective amount to be put into the reserve after completion';
+COMMENT ON COLUMN withdrawal.fees
+  IS 'Fees associated with the withdrawal, including exchange and provider 
fees';
+COMMENT ON COLUMN withdrawal.withdrawal_status
+  IS 'Status of the withdrawal process';
+COMMENT ON COLUMN withdrawal.terminal_id
+  IS 'ID of the terminal that initiated the withdrawal';
+COMMENT ON COLUMN withdrawal.provider_transaction_id
+  IS 'Transaction identifier supplied by the provider for backend request';
+COMMENT ON COLUMN withdrawal.last_retry_ts
+  IS 'Timestamp of the last retry attempt';
+COMMENT ON COLUMN withdrawal.retry_counter
+  IS 'Number of retry attempts';
+COMMENT ON COLUMN withdrawal.completion_proof
+  IS 'Proof of transaction upon final completion delivered by the providers 
system';
diff --git a/specs/api-nonce2ecash.rst b/specs/api-nonce2ecash.rst
index f82fdf6..0d88de5 100644
--- a/specs/api-nonce2ecash.rst
+++ b/specs/api-nonce2ecash.rst
@@ -16,9 +16,9 @@
 
   @author Joel Häberli
 
-==========================
+=====================
 Taler nonce2ecash API
-==========================
+=====================
 
 This chapter describe the APIs that third party providers need to integrate 
withdrawal through indirect
 payment channels like credit cards or ATM.
@@ -64,7 +64,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
 
 .. http:post:: /withdrawal-operation
 
-  Query information about a withdrawal operation, identified by the 
``WITHDRAWAL_ID``.
+  Initiate the withdrawal operation, identified by the ``WITHDRAWAL_ID``.
 
   **Request:**
 
@@ -81,8 +81,9 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
       // Optional amount for the withdrawal.
       amount?: Amount;
 
-      // Id of the provider requesting a withdrawal by nonce.
-      provider_id: SafeUint64;
+      // Id of the terminal of the provider requesting a withdrawal by nonce.
+      // Assigned by the exchange.
+      provider_terminal_id: SafeUint64;
     }
 
   **Response:**
@@ -94,6 +95,28 @@ operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation and
   :http:statuscode:`500 Internal Server error`:
     The registration of the withdrawal failed due to server side issues.
 
+.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
+
+  Query information about a withdrawal operation, identified by the 
``WITHDRAWAL_ID``.
+
+  **Response:**
+
+    .. ts:def:: CashlessWithdrawal
+
+    interface CashlessWithdrawal {
+
+      // Reserve public key generated by the wallet.
+      // According to TALER_ReservePublicKeyP 
(https://docs.taler.net/core/api-common.html#cryptographic-primitives)
+      reserve_pub_key: EddsaPublicKey;
+    }
+
+  :http:statuscode:`204 No content`:
+    The withdrawal was successfully registered.
+  :http:statuscode:`404 Bad request`:
+    No withdrawal with this ``WITHDRAWAL_ID`` exists.
+  :http:statuscode:`500 Internal Server error`:
+    The registration of the withdrawal failed due to server side issues.
+
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
 
     Notifies nonce2ecash about an executed payment for a specific withdrawal.
diff --git a/specs/db_nonce2ecash_erd.plantuml 
b/specs/db_nonce2ecash_erd.plantuml
deleted file mode 100644
index bc9603a..0000000
--- a/specs/db_nonce2ecash_erd.plantuml
+++ /dev/null
@@ -1,22 +0,0 @@
-@startuml
-entity n2c_status {
-    id: number
-    name: string
-}
-
-entity n2c_provider_type {
-    id: number
-    name: string
-}
-
-entity n2c_nonce_reservepubkey {
-    nonce: number
-    provider_type_id: n2c_provider_type
-    reserve_pubkey: number
-    n2c_status_id: n2c_status
-    registration_ts: timestamp
-}
-
-n2c_nonce_reservepubkey --* n2c_status
-n2c_nonce_reservepubkey --* n2c_provider_type
-@enduml
diff --git a/specs/provider_registration_sequence.plantuml 
b/specs/provider_registration_sequence.plantuml
deleted file mode 100644
index cfc7fde..0000000
--- a/specs/provider_registration_sequence.plantuml
+++ /dev/null
@@ -1,13 +0,0 @@
-@startuml
-
-participant Provider
-participant Exchange
-actor ExchangeOperator as "Exchange Operator"
-
-Provider -> Provider: Generate Provider Key Pair
-Provider -> Provider: Sign Provider Pubkey
-Provider -> ExchangeOperator: filled out N2CRegistrationRequest
-ExchangeOperator -> Exchange: N2CRegistrationRequest
-Exchange -> Exchange: Verify signature and add Provider if legit
-
-@enduml
\ No newline at end of file

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