finish DD13

1 files changed, 62 insertions, 40 deletions

diff --git a/design-documents/013-peer-to-peer-payments.rst b/design-documents/013-peer-to-peer-payments.rst
index 06065a12..7be20217 100644
--- a/design-documents/013-peer-to-peer-payments.rst
+++ b/design-documents/013-peer-to-peer-payments.rst
@@ -624,10 +624,6 @@ reasons to have that association for legal inquiries. (However, it would
 also be possible to keep that link only in the external KYC service's
 database.)
 
-
-TODO/FIXME: update the following SQL: add missing comments!
-
-
 .. sourcecode:: sql
 
   -- Everything in one big transaction
@@ -763,6 +759,30 @@ TODO/FIXME: update the following SQL: add missing comments!
     IS 'Signature affirming that the reserve is to be closed';
   COMMENT ON COLUMN close_requests.close_val
     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_requests
+  (purse_deposit_serial_id BIGSERIAL UNIQUE
+  ,purse_pub BYTEA NOT NULL CHECK (LENGTH(purse_pub)=32),
+  ,purse_expiration INT8 NOT NULL
+  ,h_contract_terms BYTEA NOT NULL CHECK (LENGTH(h_contract_terms)=64)
+  ,amount_with_fee_val INT8 NOT NULL
+  ,amount_with_fee_frac INT4 NOT NULL
+  ,purse_sig BYTEA NOT NULL CHECK(LENGTH(purse_sig)=64)
+  ,PRIMARY KEY (purse_pub,coin_pub)
+  );
+  COMMENT ON TABLE purse_requests
+    IS 'Requests establishing purses, associating them with a contract but without a target reserve';
+  COMMENT ON COLUMN purse_requests.purse_pub
+    IS 'Public key of the purse';
+  COMMENT ON COLUMN purse_requests.purse_expiration
+    IS 'When the purse is set to expire';
+  COMMENT ON COLUMN purse_requests.h_contract_terms
+    IS 'Hash of the contract the parties are to agree to';
+  COMMENT ON COLUMN purse_requests.amount_with_fee_val
+    IS 'Total amount expected to be in the purse';
+  COMMENT ON COLUMN purse_requests.purse_sig
+    IS 'Signature of the purse affirming the purse parameters, of type TALER_SIGNATURE_PURSE_REQUEST';
   --
   CREATE TABLE IF NOT EXISTS purse_deposits
   (purse_deposit_serial_id BIGSERIAL UNIQUE
@@ -797,15 +817,15 @@ TODO/FIXME: update the following SQL: add missing comments!
   ,UNIQUE (exchange_url, execution_time)
   );
   COMMENT ON TABLE wads_out
-    IS '';
+    IS 'Wire transfers made to another exchange to transfer purse funds';
   COMMENT ON COLUMN wads_out.wad_id
-    IS '';
+    IS 'Unique identifier of the wad, part of the wire transfer subject';
   COMMENT ON COLUMN wads_out.target_exchange_url
-    IS '';
+    IS 'Base URL of the target exchange';
   COMMENT ON COLUMN wads_out.amount_val
-    IS '';
+    IS 'Amount that was wired';
   COMMENT ON COLUMN wads_out.execution_time
-    IS '';
+    IS 'Time when the wire transfer was scheduled';
   --
   CREATE TABLE IF NOT EXISTS wad_out_entries
   (wad_out_entry_serial_id BIGSERIAL UNIQUE
@@ -824,30 +844,32 @@ TODO/FIXME: update the following SQL: add missing comments!
   ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64))
   ,purse_sig BYTEA NOT NULL CHECK (LENGTH(purse_sig)=64))
   );
+  CREATE INDEX IF NOT EXISTS wad_out_entries_index_by_wad
+    ON wad_out_entries (wad_out_serial_id);
   COMMENT ON TABLE wad_out_entries
-    IS '';
+    IS 'Purses combined into a wad';
   COMMENT ON COLUMN wad_out_entries.wad_out_serial_id
-    IS '';
+    IS 'Wad the purse was part of';
   COMMENT ON COLUMN wad_out_entries.reserve_pub
-    IS '';
+    IS 'Target reserve for the purse';
   COMMENT ON COLUMN wad_out_entries.purse_pub
-    IS '';
+    IS 'Public key of the purse';
   COMMENT ON COLUMN wad_out_entries.h_contract
-    IS '';
+    IS 'Hash of the contract associated with the purse';
   COMMENT ON COLUMN wad_out_entries.purse_expiration
-    IS '';
+    IS 'Time when the purse expires';
   COMMENT ON COLUMN wad_out_entries.merge_timestamp
-    IS '';
+    IS 'Time when the merge was approved';
   COMMENT ON COLUMN wad_out_entries.amount_with_fee_val
-    IS '';
+    IS 'Total amount in the purse';
   COMMENT ON COLUMN wad_out_entries.wad_fee_val
-    IS '';
+    IS 'Wat fee charged to the purse';
   COMMENT ON COLUMN wad_out_entries.deposit_fees_val
-    IS '';
+    IS 'Total deposit fees charged to the purse';
   COMMENT ON COLUMN wad_out_entries.reserve_sig
-    IS '';
+    IS 'Signature by the receiving reserve, of purpose TALER_SIGNATURE_ACCOUNT_MERGE';
   COMMENT ON COLUMN wad_out_entries.purse_sig
-    IS '';
+    IS 'Signature by the purse of purpose TALER_SIGNATURE_PURSE_MERGE';
   --
   CREATE TABLE IF NOT EXISTS wads_in
   (wad_in_serial_id BIGSERIAL UNIQUE
@@ -859,15 +881,15 @@ TODO/FIXME: update the following SQL: add missing comments!
   ,UNIQUE (wad_id, origin_exchange_url)
   );
   COMMENT ON TABLE wads_in_entries
-    IS '';
+    IS 'Incoming exchange-to-exchange wad wire transfers';
   COMMENT ON COLUMN wads_in.wad_id
-    IS '';
+    IS 'Unique identifier of the wad, part of the wire transfer subject';
   COMMENT ON COLUMN wads_in.origin_exchange_url
-    IS '';
+    IS 'Base URL of the originating URL, also part of the wire transfer subject';
   COMMENT ON COLUMN wads_in.amount_val
-    IS '';
+    IS 'Actual amount that was received by our exchange';
   COMMENT ON COLUMN wads_in.arrival_time
-    IS '';
+    IS 'Time when the wad was received';
   --
   CREATE TABLE IF NOT EXISTS wad_in_entries
   (wad_in_entry_serial_id BIGSERIAL UNIQUE
@@ -887,37 +909,37 @@ TODO/FIXME: update the following SQL: add missing comments!
   ,purse_sig BYTEA NOT NULL CHECK (LENGTH(purse_sig)=64))
   );
   COMMENT ON TABLE wad_in_entries
-    IS '';
+    IS 'list of purses aggregated in a wad according to the sending exchange';
   COMMENT ON COLUMN wad_in_entries.wad_in_serial_id
-    IS '';
+    IS 'wad for which the given purse was included in the aggregation';
   COMMENT ON COLUMN wad_in_entries.reserve_pub
-    IS '';
+    IS 'target account of the purse (must be at the local exchange)';
   COMMENT ON COLUMN wad_in_entries.purse_pub
-    IS '';
+    IS 'public key of the purse that was merged';
   COMMENT ON COLUMN wad_in_entries.h_contract
-    IS '';
+    IS 'hash of the contract terms of the purse';
   COMMENT ON COLUMN wad_in_entries.purse_expiration
-    IS '';
+    IS 'Time when the purse was set to expire';
   COMMENT ON COLUMN wad_in_entries.merge_timestamp
-    IS '';
+    IS 'Time when the merge was approved';
   COMMENT ON COLUMN wad_in_entries.amount_with_fee_val
-    IS '';
+    IS 'Total amount in the purse';
   COMMENT ON COLUMN wad_in_entries.wad_fee_val
-    IS '';
+    IS 'Total wad fees paid by the purse';
   COMMENT ON COLUMN wad_in_entries.deposit_fees_val
-    IS '';
+    IS 'Total deposit fees paid when depositing coins into the purse';
   COMMENT ON COLUMN wad_in_entries.reserve_sig
-    IS '';
+    IS 'Signature by the receiving reserve, of purpose TALER_SIGNATURE_ACCOUNT_MERGE';
   COMMENT ON COLUMN wad_in_entries.purse_sig
-    IS '';
+    IS 'Signature by the purse of purpose TALER_SIGNATURE_PURSE_MERGE';
   CREATE INDEX IF NOT EXISTS wad_in_entries_wad_in_serial
     ON wad_in_entries (wad_in_serial_id);
   CREATE INDEX IF NOT EXISTS wad_in_entries_reserve_pub
     ON wad_in_entries (reserve_pub);
   COMMENT ON INDEX wad_in_entries_wad_in_serial
-    IS '';
+    IS 'needed to lookup all transfers associated with a wad';
   COMMENT ON INDEX wad_in_entries_reserve_pub
-    IS '';
+    IS 'needed to compute reserve history';
   -- Complete transaction
   COMMIT;