commit fc93689cf80f9695e99dad88428a0ef14aa097d0
parent b02fedd6450abefe883565c7205e55a3b8f2932f
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Wed, 13 Mar 2024 10:03:14 +0100
sql: add comment statements for table, columns and types
Diffstat:
4 files changed, 102 insertions(+), 101 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
