From 12b20845cdd54858484be235c2110fbf466324bc Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 15 May 2021 20:05:27 +0200 Subject: work on SQL comments --- design-documents/013-peer-to-peer-payments.rst | 67 ++++++++++++-------------- 1 file changed, 32 insertions(+), 35 deletions(-) diff --git a/design-documents/013-peer-to-peer-payments.rst b/design-documents/013-peer-to-peer-payments.rst index a938b5a1..06065a12 100644 --- a/design-documents/013-peer-to-peer-payments.rst +++ b/design-documents/013-peer-to-peer-payments.rst @@ -661,7 +661,7 @@ TODO/FIXME: update the following SQL: add missing comments! ,PRIMARY KEY (reserve_uuid, kyc_date) ); COMMENT ON TABLE kyc_requests - IS ''; + IS 'KYC processes initiated by the owner of a reserve'; COMMENT ON COLUMN kyc_requests.reserve_uuid IS 'Reserve for which the KYC request was triggered.'; COMMENT ON COLUMN kyc_requests.reserve_sig @@ -678,44 +678,41 @@ TODO/FIXME: update the following SQL: add missing comments! CREATE TABLE IF NOT EXISTS mergers (merge_request_serial_id BIGSERIAL UNIQUE ,reserve_uuid BYTEA NOT NULL REFERENCES reserves (reserve_uuid) ON DELETE CASCADE - ,purse_url TEXT NOT NULL, + ,reserve_url TEXT NOT NULL, ,purse_pub BYTEA NOT NULL CHECK (LENGTH(purse_pub)=32), ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) ,purse_sig BYTEA NOT NULL CHECK (LENGTH(purse_sig)=64)) ,merge_timestamp INT8 NOT NULL ,purse_expiration INT8 NOT NULL ,h_contract_terms BYTEA NOT NULL CHECK (LENGTH(h_contract_terms)=64)) - ,h_wire BYTEA NOT NULL CHECK (LENGTH(h_wire)=64)) ,purse_val INT8 NOT NULL ,purse_frac INT4 NOT NULL ,PRIMARY KEY (purse_pub) ); COMMENT ON TABLE mergers - IS ''; + IS 'Merge requests where a purse- and account-owner requested merging the purse into the account'; COMMENT ON COLUMN mergers.reserve_uuid - IS ''; - COMMENT ON COLUMN mergers.purse_url - IS ''; + IS 'identifies the reserve'; + COMMENT ON COLUMN mergers.reserve_url + IS 'payto://-URL of the reserve, identifies the exchange and the reserve'; COMMENT ON COLUMN mergers.purse_pub - IS ''; + IS 'public key of the purse'; COMMENT ON COLUMN mergers.reserve_sig - IS ''; + IS 'signature by the reserve private key affirming the merge'; COMMENT ON COLUMN mergers.purse_sig - IS ''; + IS 'signature by the purse private key affirming the merge'; COMMENT ON COLUMN mergers.merge_timestamp - IS ''; + IS 'when was the merge message signed'; COMMENT ON COLUMN mergers.purse_expiration - IS ''; + IS 'when is the purse set to expire'; COMMENT ON COLUMN mergers.h_contract_terms - IS ''; - COMMENT ON COLUMN mergers.h_wire - IS ''; + IS 'hash of the contract terms both sides are to agree upon'; COMMENT ON COLUMN mergers.purse_val - IS ''; + IS 'amount to be transferred from the purse to the reserve (excludes deposit fees)'; CREATE INDEX IF NOT EXISTS mergers_reserve_uuid ON mergers (reserve_uuid); COMMENT ON INDEX mergers_reserve_uuid - IS ''; + IS 'needed in reserve history computation'; -- CREATE TABLE IF NOT EXISTS contracts (contract_serial_id BIGSERIAL UNIQUE @@ -725,13 +722,13 @@ TODO/FIXME: update the following SQL: add missing comments! ,PRIMARY KEY (purse_pub) ); COMMENT ON TABLE contracts - IS ''; + IS 'encrypted contracts associated with purses'; COMMENT ON COLUMN contracts.purse_pub - IS ''; + IS 'public key of the purse that the contract is associated with'; COMMENT ON COLUMN contracts.pub_ckey - IS ''; + IS 'Public ECDH key used to encrypt the contract, to be used with the purse private key for decryption'; COMMENT ON COLUMN contracts.e_contract - IS ''; + IS 'AES-GCM encrypted contract terms (contains gzip compressed JSON after decryption)'; -- CREATE TABLE IF NOT EXISTS history_requests (reserve_uuid INT8 NOT NULL REFERENCES reserves(reserve_uuid) ON DELETE CASCADE, @@ -742,13 +739,13 @@ TODO/FIXME: update the following SQL: add missing comments! ,PRIMARY KEY (reserve_uuid,request_timestamp) ); COMMENT ON TABLE history_requests - IS ''; + IS 'Paid history requests issued by a client against a reserve'; COMMENT ON COLUMN history_requests.request_timestamp - IS ''; + IS 'When was the history request made'; COMMENT ON COLUMN history_requests.reserve_sig - IS ''; + IS 'Signature approving payment for the history request'; COMMENT ON COLUMN history_requests.history_fee_val - IS ''; + IS 'History fee approved by the signature'; -- CREATE TABLE IF NOT EXISTS close_requests (reserve_uuid INT8 NOT NULL REFERENCES reserves(reserve_uuid) ON DELETE CASCADE, @@ -759,13 +756,13 @@ TODO/FIXME: update the following SQL: add missing comments! ,PRIMARY KEY (reserve_uuid,close_timestamp) ); COMMENT ON TABLE close_requests - IS ''; + IS 'Explicit requests by a reserve owner to close a reserve immediately'; COMMENT ON COLUMN close_requests.close_timestamp - IS ''; + IS 'When the request was created by the client'; COMMENT ON COLUMN close_requests.reserve_sig - IS ''; + IS 'Signature affirming that the reserve is to be closed'; COMMENT ON COLUMN close_requests.close_val - IS ''; + IS 'Balance of the reserve at the time of closing, to be wired to the associated bank account (minus the closing fee)'; -- CREATE TABLE IF NOT EXISTS purse_deposits (purse_deposit_serial_id BIGSERIAL UNIQUE @@ -778,17 +775,17 @@ TODO/FIXME: update the following SQL: add missing comments! ,PRIMARY KEY (purse_pub,coin_pub) ); COMMENT ON TABLE purse_deposits - IS ''; + IS 'Requests depositing coins into a purse'; COMMENT ON COLUMN purse_deposits.purse_pub - IS ''; + IS 'Public key of the purse'; COMMENT ON COLUMN purse_deposits.purse_expiration - IS ''; + IS 'When the purse is set to expire'; COMMENT ON COLUMN purse_deposits.coin_pub - IS ''; + IS 'Public key of the coin being deposited'; COMMENT ON COLUMN purse_deposits.amount_with_fee_val - IS ''; + IS 'Total amount being deposited'; COMMENT ON COLUMN purse_deposits.coin_sig - IS ''; + IS 'Signature of the coin affirming the deposit into the purse, of type TALER_SIGNATURE_PURSE_DEPOSIT'; -- CREATE TABLE IF NOT EXISTS wads_out (wad_out_serial_id BIGSERIAL UNIQUE -- cgit v1.2.3