new coins => fresh coins, also move comments into the database itself

src/auditor/taler-auditor.c

@@ -3630,7 +3630,7 @@ struct RevealContext
   /**
    * Size of the @a new_dp and @a new_dps arrays.
    */
-  unsigned int num_newcoins;
+  unsigned int num_freshcoins;
 };
 
 
@@ -3638,15 +3638,15 @@ struct RevealContext
  * Function called with information about a refresh order.
  *
  * @param cls closure
- * @param num_newcoins size of the @a rrcs array
+ * @param num_freshcoins size of the @a rrcs array
- * @param rrcs array of @a num_newcoins information about coins to be created
+ * @param rrcs array of @a num_freshcoins information about coins to be created
  * @param num_tprivs number of entries in @a tprivs, should be #TALER_CNC_KAPPA - 1
  * @param tprivs array of @e num_tprivs transfer private keys
  * @param tp transfer public key information
  */
 static void
 reveal_data_cb (void *cls,
-                uint32_t num_newcoins,
+                uint32_t num_freshcoins,
                 const struct TALER_EXCHANGEDB_RefreshRevealedCoin *rrcs,
                 unsigned int num_tprivs,
                 const struct TALER_TransferPrivateKeyP *tprivs,
@@ -3657,10 +3657,10 @@ reveal_data_cb (void *cls,
   (void) num_tprivs;
   (void) tprivs;
   (void) tp;
-  rctx->num_newcoins = num_newcoins;
+  rctx->num_freshcoins = num_freshcoins;
-  rctx->new_dps = GNUNET_new_array (num_newcoins,
+  rctx->new_dps = GNUNET_new_array (num_freshcoins,
                                     struct TALER_DenominationPublicKey);
-  for (unsigned int i = 0; i<num_newcoins; i++)
+  for (unsigned int i = 0; i<num_freshcoins; i++)
     rctx->new_dps[i].rsa_public_key
       = GNUNET_CRYPTO_rsa_public_key_dup (rrcs[i].denom_pub.rsa_public_key);
 }
@@ -3839,7 +3839,7 @@ refresh_session_cb (void *cls,
       return GNUNET_SYSERR;
     }
     if ( (GNUNET_DB_STATUS_SUCCESS_NO_RESULTS == qs) ||
-         (0 == reveal_ctx.num_newcoins) )
+         (0 == reveal_ctx.num_freshcoins) )
     {
       /* This can happen if /refresh/reveal was not yet called or only
          with invalid data, even if the exchange is correctly
@@ -3858,12 +3858,12 @@ refresh_session_cb (void *cls,
 
     {
       const struct TALER_DenominationKeyValidityPS *new_issues[reveal_ctx.
-                                                               num_newcoins];
+                                                               num_freshcoins];
 
       /* Update outstanding amounts for all new coin's denominations, and check
          that the resulting amounts are consistent with the value being refreshed. */
       err = GNUNET_OK;
-      for (unsigned int i = 0; i<reveal_ctx.num_newcoins; i++)
+      for (unsigned int i = 0; i<reveal_ctx.num_freshcoins; i++)
       {
         /* lookup new coin denomination key */
         qs = get_denomination_info (&reveal_ctx.new_dps[i],
@@ -3893,7 +3893,7 @@ refresh_session_cb (void *cls,
         return (GNUNET_SYSERR == err) ? GNUNET_SYSERR : GNUNET_OK;
 
       /* calculate total refresh cost */
-      for (unsigned int i = 0; i<reveal_ctx.num_newcoins; i++)
+      for (unsigned int i = 0; i<reveal_ctx.num_freshcoins; i++)
       {
         /* update cost of refresh */
         struct TALER_Amount fee;
@@ -3949,7 +3949,7 @@ refresh_session_cb (void *cls,
       }
 
       /* update outstanding denomination amounts */
-      for (unsigned int i = 0; i<reveal_ctx.num_newcoins; i++)
+      for (unsigned int i = 0; i<reveal_ctx.num_freshcoins; i++)
       {
         struct DenominationSummary *dsi;
         struct TALER_Amount value;

src/exchange/taler-exchange-httpd_deposits_get.c

@@ -238,14 +238,14 @@ track_transaction_transaction (void *cls,
   struct DepositWtidContext *ctx = cls;
   enum GNUNET_DB_QueryStatus qs;
 
-  qs = TEH_plugin->wire_lookup_deposit_wtid (TEH_plugin->cls,
+  qs = TEH_plugin->lookup_transfer_by_deposit (TEH_plugin->cls,
-                                             session,
+                                               session,
-                                             &ctx->tps->h_contract_terms,
+                                               &ctx->tps->h_contract_terms,
-                                             &ctx->tps->h_wire,
+                                               &ctx->tps->h_wire,
-                                             &ctx->tps->coin_pub,
+                                               &ctx->tps->coin_pub,
-                                             ctx->merchant_pub,
+                                               ctx->merchant_pub,
-                                             &handle_wtid_data,
+                                               &handle_wtid_data,
-                                             ctx);
+                                               ctx);
   if (0 > qs)
   {
     if (GNUNET_DB_STATUS_HARD_ERROR == qs)

src/exchange/taler-exchange-httpd_refreshes_reveal.c

@@ -48,22 +48,22 @@
  * Send a response for "/refresh/reveal".
  *
  * @param connection the connection to send the response to
- * @param num_newcoins number of new coins for which we reveal data
+ * @param num_freshcoins number of new coins for which we reveal data
- * @param sigs array of @a num_newcoins signatures revealed
+ * @param sigs array of @a num_freshcoins signatures revealed
  * @return a MHD result code
  */
 static int
 reply_refresh_reveal_success (struct MHD_Connection *connection,
-                              unsigned int num_newcoins,
+                              unsigned int num_freshcoins,
                               const struct TALER_DenominationSignature *sigs)
 {
   json_t *list;
   int ret;
 
   list = json_array ();
-  for (unsigned int newcoin_index = 0;
+  for (unsigned int freshcoin_index = 0;
-       newcoin_index < num_newcoins;
+       freshcoin_index < num_freshcoins;
-       newcoin_index++)
+       freshcoin_index++)
   {
     json_t *obj;
 
@@ -71,7 +71,7 @@ reply_refresh_reveal_success (struct MHD_Connection *connection,
     json_object_set_new (obj,
                          "ev_sig",
                          GNUNET_JSON_from_rsa_signature (
-                           sigs[newcoin_index].rsa_signature));
+                           sigs[freshcoin_index].rsa_signature));
     GNUNET_assert (0 ==
                    json_array_append_new (list,
                                           obj));
@@ -181,15 +181,15 @@ struct RevealContext
  * again.
  *
  * @param cls closure with a `struct RevealContext`
- * @param num_newcoins size of the @a rrcs array
+ * @param num_freshcoins size of the @a rrcs array
- * @param rrcs array of @a num_newcoins information about coins to be created
+ * @param rrcs array of @a num_freshcoins information about coins to be created
  * @param num_tprivs number of entries in @a tprivs, should be #TALER_CNC_KAPPA - 1
  * @param tprivs array of @e num_tprivs transfer private keys
  * @param tp transfer public key information
  */
 static void
 check_exists_cb (void *cls,
-                 uint32_t num_newcoins,
+                 uint32_t num_freshcoins,
                  const struct TALER_EXCHANGEDB_RefreshRevealedCoin *rrcs,
                  unsigned int num_tprivs,
                  const struct TALER_TransferPrivateKeyP *tprivs,
@@ -197,7 +197,7 @@ check_exists_cb (void *cls,
 {
   struct RevealContext *rctx = cls;
 
-  if (0 == num_newcoins)
+  if (0 == num_freshcoins)
   {
     GNUNET_break (0);
     return;
@@ -215,9 +215,9 @@ check_exists_cb (void *cls,
      we do find the operation in the database, we could use this: */
   if (NULL == rctx->ev_sigs)
   {
-    rctx->ev_sigs = GNUNET_new_array (num_newcoins,
+    rctx->ev_sigs = GNUNET_new_array (num_freshcoins,
                                       struct TALER_DenominationSignature);
-    for (unsigned int i = 0; i<num_newcoins; i++)
+    for (unsigned int i = 0; i<num_freshcoins; i++)
       rctx->ev_sigs[i].rsa_signature
         = GNUNET_CRYPTO_rsa_signature_dup (rrcs[i].coin_sig.rsa_signature);
   }

src/exchangedb/exchange-0001.sql

@@ -21,7 +21,6 @@ BEGIN;
 SELECT _v.register_patch('exchange-0001', NULL, NULL);
 
 
--- Main denominations table. All the coins the exchange knows about.
 CREATE TABLE IF NOT EXISTS denominations
   (denom_pub_hash BYTEA PRIMARY KEY CHECK (LENGTH(denom_pub_hash)=64)
   ,denom_pub BYTEA NOT NULL
@@ -42,20 +41,23 @@ CREATE TABLE IF NOT EXISTS denominations
   ,fee_refund_val INT8 NOT NULL
   ,fee_refund_frac INT4 NOT NULL
   );
+COMMENT ON TABLE denominations
+  IS 'Main denominations table. All the coins the exchange knows about.';
+
 CREATE INDEX IF NOT EXISTS denominations_expire_legal_index
   ON denominations
   (expire_legal);
 
--- denomination_revocations table is for remembering which denomination keys have been revoked
+
 CREATE TABLE IF NOT EXISTS denomination_revocations
   (denom_revocations_serial_id BIGSERIAL UNIQUE
   ,denom_pub_hash BYTEA PRIMARY KEY REFERENCES denominations (denom_pub_hash) ON DELETE CASCADE
   ,master_sig BYTEA NOT NULL CHECK (LENGTH(master_sig)=64)
   );
--- reserves table is for summarization of a reserve.  It is updated when new
+COMMENT ON TABLE denomination_revocations
--- funds are added and existing funds are withdrawn.  The 'expiration_date'
+  IS 'remembering which denomination keys have been revoked';
--- can be used to eventually get rid of reserves that have not been used
+
--- for a very long time (usually by refunding the owner)
+
 CREATE TABLE IF NOT EXISTS reserves
   (reserve_pub BYTEA PRIMARY KEY CHECK(LENGTH(reserve_pub)=32)
   ,account_details TEXT NOT NULL
@@ -64,24 +66,30 @@ CREATE TABLE IF NOT EXISTS reserves
   ,expiration_date INT8 NOT NULL
   ,gc_date INT8 NOT NULL
   );
--- index on reserves table (TODO: useless due to primary key!?)
+COMMENT ON TABLE reserves
-CREATE INDEX IF NOT EXISTS reserves_reserve_pub_index
+  IS 'Summarizes the balance of a reserve. Updated when new funds are added or withdrawn.';
-  ON reserves
+COMMENT ON COLUMN reserves.expiration_date
-  (reserve_pub);
+  IS 'Used to trigger closing of reserves that have not been drained after some time';
--- index for get_expired_reserves
+COMMENT ON COLUMN reserves.gc_date
+  IS 'Used to forget all information about a reserve during garbage collection';
+
+
 CREATE INDEX IF NOT EXISTS reserves_expiration_index
   ON reserves
   (expiration_date
   ,current_balance_val
   ,current_balance_frac
   );
--- index for reserve GC operations
+COMMENT ON INDEX reserves_expiration_index
+  IS 'used in get_expired_reserves';
+
 CREATE INDEX IF NOT EXISTS reserves_gc_index
   ON reserves
   (gc_date);
--- reserves_in table collects the transactions which transfer funds
+COMMENT ON INDEX reserves_gc_index
--- into the reserve.  The rows of this table correspond to each
+  IS 'for reserve garbage collection';
--- incoming transaction.
+
+
 CREATE TABLE IF NOT EXISTS reserves_in
   (reserve_in_serial_id BIGSERIAL UNIQUE
   ,reserve_pub BYTEA NOT NULL REFERENCES reserves (reserve_pub) ON DELETE CASCADE
@@ -93,7 +101,9 @@ CREATE TABLE IF NOT EXISTS reserves_in
   ,execution_date INT8 NOT NULL
   ,PRIMARY KEY (reserve_pub, wire_reference)
   );
--- Create indices on reserves_in
+COMMENT ON TABLE reserves_in
+  IS 'list of transfers of funds into the reserves, one per incoming wire transfer';
+
 CREATE INDEX IF NOT EXISTS reserves_in_execution_index
   ON reserves_in
   (exchange_account_section
@@ -104,8 +114,8 @@ CREATE INDEX IF NOT EXISTS reserves_in_exchange_account_serial
   (exchange_account_section,
   reserve_in_serial_id DESC
   );
--- This table contains the data for wire transfers the exchange has
+
--- executed to close a reserve.
+
 CREATE TABLE IF NOT EXISTS reserves_close
   (close_uuid BIGSERIAL PRIMARY KEY
   ,reserve_pub BYTEA NOT NULL REFERENCES reserves (reserve_pub) ON DELETE CASCADE
@@ -116,15 +126,14 @@ CREATE TABLE IF NOT EXISTS reserves_close
   ,amount_frac INT4 NOT NULL
   ,closing_fee_val INT8 NOT NULL
   ,closing_fee_frac INT4 NOT NULL);
+COMMENT ON TABLE reserves_close
+  IS 'wire transfers executed by the reserve to close reserves';
+
 CREATE INDEX IF NOT EXISTS reserves_close_by_reserve
   ON reserves_close
   (reserve_pub);
--- Table with the withdraw operations that have been performed on a reserve.
+
---  The 'h_blind_ev' is the hash of the blinded coin. It serves as a primary
+
--- key, as (broken) clients that use a non-random coin and blinding factor
--- should fail to even withdraw, as otherwise the coins will fail to deposit
--- (as they really must be unique).
--- For the denom_pub, we do NOT CASCADE on DELETE, we may keep the denomination key alive!
 CREATE TABLE IF NOT EXISTS reserves_out
   (reserve_out_serial_id BIGSERIAL UNIQUE
   ,h_blind_ev BYTEA PRIMARY KEY CHECK (LENGTH(h_blind_ev)=64)
@@ -136,10 +145,18 @@ CREATE TABLE IF NOT EXISTS reserves_out
   ,amount_with_fee_val INT8 NOT NULL
   ,amount_with_fee_frac INT4 NOT NULL
   );
--- Index blindcoins(reserve_pub) for get_reserves_out statement
+COMMENT ON TABLE reserves_out
+  IS 'Withdraw operations performed on reserves.';
+COMMENT ON COLUMN reserves_out.h_blind_ev
+  IS 'Hash of the blinded coin, used as primary key here so that broken clients that use a non-random coin or blinding factor fail to withdraw (otherwise they would fail on deposit when the coin is not unique there).';
+COMMENT ON COLUMN reserves_out.denom_pub_hash
+  IS 'We do not CASCADE ON DELETE here, we may keep the denomination data alive';
+
 CREATE INDEX IF NOT EXISTS reserves_out_reserve_pub_index
   ON reserves_out
   (reserve_pub);
+COMMENT ON INDEX reserves_out_reserve_pub_index
+  IS 'for get_reserves_out';
 CREATE INDEX IF NOT EXISTS reserves_out_execution_date
   ON reserves_out
   (execution_date);
@@ -148,17 +165,21 @@ CREATE INDEX IF NOT EXISTS reserves_out_for_get_withdraw_info
   (denom_pub_hash
   ,h_blind_ev
   );
--- Table with coins that have been (partially) spent, used to track
+
--- coin information only once.
+
 CREATE TABLE IF NOT EXISTS known_coins
   (coin_pub BYTEA NOT NULL PRIMARY KEY CHECK (LENGTH(coin_pub)=32)
   ,denom_pub_hash BYTEA NOT NULL REFERENCES denominations (denom_pub_hash) ON DELETE CASCADE
   ,denom_sig BYTEA NOT NULL
   );
+COMMENT ON TABLE known_coins
+  IS 'information about coins and their signatures, so we do not have to store the signatures more than once if a coin is involved in multiple operations';
+
 CREATE INDEX IF NOT EXISTS known_coins_by_denomination
   ON known_coins
   (denom_pub_hash);
--- Table with the commitments made when melting a coin. */
+
+
 CREATE TABLE IF NOT EXISTS refresh_commitments
   (melt_serial_id BIGSERIAL UNIQUE
   ,rc BYTEA PRIMARY KEY CHECK (LENGTH(rc)=64)
@@ -168,48 +189,66 @@ CREATE TABLE IF NOT EXISTS refresh_commitments
   ,amount_with_fee_frac INT4 NOT NULL
   ,noreveal_index INT4 NOT NULL
   );
+COMMENT ON TABLE refresh_commitments
+  IS 'Commitments made when melting coins and the gamma value chosen by the exchange.';
+
 CREATE INDEX IF NOT EXISTS refresh_commitments_old_coin_pub_index
   ON refresh_commitments
   (old_coin_pub);
--- Table with the revelations about the new coins that are to be created
+
--- during a melting session.  Includes the session, the cut-and-choose
+
--- index and the index of the new coin, and the envelope of the new
--- coin to be signed, as well as the encrypted information about the
--- private key and the blinding factor for the coin (for verification
--- in case this newcoin_index is chosen to be revealed)
 CREATE TABLE IF NOT EXISTS refresh_revealed_coins
   (rc BYTEA NOT NULL REFERENCES refresh_commitments (rc) ON DELETE CASCADE
-  ,newcoin_index INT4 NOT NULL
+  ,freshcoin_index INT4 NOT NULL
   ,link_sig BYTEA NOT NULL CHECK(LENGTH(link_sig)=64)
   ,denom_pub_hash BYTEA NOT NULL REFERENCES denominations (denom_pub_hash) ON DELETE CASCADE
   ,coin_ev BYTEA UNIQUE NOT NULL
   ,h_coin_ev BYTEA NOT NULL CHECK(LENGTH(h_coin_ev)=64)
   ,ev_sig BYTEA NOT NULL
-  ,PRIMARY KEY (rc, newcoin_index)
+  ,PRIMARY KEY (rc, freshcoin_index)
   ,UNIQUE (h_coin_ev)
   );
+COMMENT ON TABLE refresh_revealed_coins
+  IS 'Revelations about the new coins that are to be created during a melting session.';
+COMMENT ON COLUMN refresh_revealed_coins.rc
+  IS 'refresh commitment identifying the melt operation';
+COMMENT ON COLUMN refresh_revealed_coins.freshcoin_index
+  IS 'index of the fresh coin being created (one melt operation may result in multiple fresh coins)';
+COMMENT ON COLUMN refresh_revealed_coins.coin_ev
+  IS 'envelope of the new coin to be signed';
+COMMENT ON COLUMN refresh_revealed_coins.h_coin_ev
+  IS 'hash of the envelope of the new coin to be signed (for lookups)';
+COMMENT ON COLUMN refresh_revealed_coins.ev_sig
+  IS 'exchange signature over the envelope';
+
 CREATE INDEX IF NOT EXISTS refresh_revealed_coins_coin_pub_index
   ON refresh_revealed_coins
   (denom_pub_hash);
--- Table with the transfer keys of a refresh operation; includes
+
--- the rc for which this is the link information, the
+
--- transfer public key (for gamma) and the revealed transfer private
--- keys (array of TALER_CNC_KAPPA - 1 entries, with gamma being skipped) */
 CREATE TABLE IF NOT EXISTS refresh_transfer_keys
   (rc BYTEA NOT NULL PRIMARY KEY REFERENCES refresh_commitments (rc) ON DELETE CASCADE
   ,transfer_pub BYTEA NOT NULL CHECK(LENGTH(transfer_pub)=32)
   ,transfer_privs BYTEA NOT NULL
   );
--- for get_link (not sure if this helps, as there should be very few
+COMMENT ON TABLE refresh_transfer_keys
--- transfer_pubs per rc, but at least in theory this helps the ORDER BY
+  IS 'Transfer keys of a refresh operation (the data revealed to the exchange).';
--- clause.
+COMMENT ON COLUMN refresh_transfer_keys.rc
+  IS 'refresh commitment identifying the melt operation';
+COMMENT ON COLUMN refresh_transfer_keys.transfer_pub
+  IS 'transfer public key for the gamma index';
+COMMENT ON COLUMN refresh_transfer_keys.transfer_privs
+  IS 'array of TALER_CNC_KAPPA - 1 transfer private keys that have been revealed, with the gamma entry being skipped';
+
 CREATE INDEX IF NOT EXISTS refresh_transfer_keys_coin_tpub
   ON refresh_transfer_keys
   (rc
   ,transfer_pub
   );
--- This table contains the wire transfers the exchange is supposed to
+COMMENT ON INDEX refresh_transfer_keys_coin_tpub
--- execute to transmit funds to the merchants (and manage refunds).
+  IS 'for get_link (unsure if this helps or hurts for performance as there should be very few transfer public keys per rc, but at least in theory this helps the ORDER BY clause)';
+
+
 CREATE TABLE IF NOT EXISTS deposits
   (deposit_serial_id BIGSERIAL PRIMARY KEY
   ,coin_pub BYTEA NOT NULL REFERENCES known_coins (coin_pub) ON DELETE CASCADE
@@ -227,14 +266,21 @@ CREATE TABLE IF NOT EXISTS deposits
   ,done BOOLEAN NOT NULL DEFAULT FALSE
   ,UNIQUE (coin_pub, merchant_pub, h_contract_terms)
   );
--- Index for get_deposit_for_wtid and get_deposit_statement */
+COMMENT ON TABLE deposits
+  IS 'Deposits we have received and for which we need to make (aggregate) wire transfers (and manage refunds).';
+COMMENT ON COLUMN deposits.done
+  IS 'Set to TRUE once we have included this deposit in some aggregate wire transfer to the merchant';
+COMMENT ON COLUMN deposits.tiny
+  IS 'Set to TRUE if we decided that the amount is too small to ever trigger a wire transfer by itself (requires real aggregation)';
+
 CREATE INDEX IF NOT EXISTS deposits_coin_pub_merchant_contract_index
   ON deposits
   (coin_pub
   ,merchant_pub
   ,h_contract_terms
   );
--- Index for deposits_get_ready
+COMMENT ON INDEX deposits_coin_pub_merchant_contract_index
+  IS 'for get_deposit_for_wtid and test_deposit_done';
 CREATE INDEX IF NOT EXISTS deposits_get_ready_index
   ON deposits
   (tiny
@@ -242,18 +288,19 @@ CREATE INDEX IF NOT EXISTS deposits_get_ready_index
   ,wire_deadline
   ,refund_deadline
   );
--- Index for deposits_iterate_matching
+COMMENT ON INDEX deposits_coin_pub_merchant_contract_index
-CREATE INDEX IF NOT EXISTS deposits_iterate_matching
+  IS 'for deposits_get_ready';
+CREATE INDEX IF NOT EXISTS deposits_iterate_matching_index
   ON deposits
   (merchant_pub
   ,h_wire
   ,done
   ,wire_deadline
   );
--- Table with information about coins that have been refunded. (Technically
+COMMENT ON INDEX deposits_iterate_matching_index
--- one of the deposit operations that a coin was involved with is refunded.)
+  IS 'for deposits_iterate_matching';
--- The combo of coin_pub, merchant_pub, h_contract_terms and rtransaction_id
+
--- MUST be unique, and we usually select by coin_pub so that one goes first. */
+
 CREATE TABLE IF NOT EXISTS refunds
   (refund_serial_id BIGSERIAL UNIQUE
   ,coin_pub BYTEA NOT NULL REFERENCES known_coins (coin_pub) ON DELETE CASCADE
@@ -265,11 +312,16 @@ CREATE TABLE IF NOT EXISTS refunds
   ,amount_with_fee_frac INT4 NOT NULL
   ,PRIMARY KEY (coin_pub, merchant_pub, h_contract_terms, rtransaction_id)
   );
+COMMENT ON TABLE refunds
+  IS 'Data on coins that were refunded. Technically, refunds always apply against specific deposit operations involving a coin. The combination of coin_pub, merchant_pub, h_contract_terms and rtransaction_id MUST be unique, and we usually select by coin_pub so that one goes first.';
+COMMENT ON COLUMN refunds.rtransaction_id
+  IS 'used by the merchant to make refunds unique in case the same coin for the same deposit gets a subsequent (higher) refund';
+
 CREATE INDEX IF NOT EXISTS refunds_coin_pub_index
   ON refunds
   (coin_pub);
--- This table contains the data for
+
--- wire transfers the exchange has executed.
+
 CREATE TABLE IF NOT EXISTS wire_out
   (wireout_uuid BIGSERIAL PRIMARY KEY
   ,execution_date INT8 NOT NULL
@@ -279,18 +331,25 @@ CREATE TABLE IF NOT EXISTS wire_out
   ,amount_val INT8 NOT NULL
   ,amount_frac INT4 NOT NULL
   );
--- Table for the tracking API, mapping from wire transfer identifier
+COMMENT ON TABLE wire_out
--- to transactions and back
+  IS 'wire transfers the exchange has executed';
+
+
 CREATE TABLE IF NOT EXISTS aggregation_tracking
   (aggregation_serial_id BIGSERIAL UNIQUE
   ,deposit_serial_id INT8 PRIMARY KEY REFERENCES deposits (deposit_serial_id) ON DELETE CASCADE
   ,wtid_raw BYTEA  CONSTRAINT wire_out_ref REFERENCES wire_out(wtid_raw) ON DELETE CASCADE DEFERRABLE
   );
--- Index for lookup_transactions statement on wtid
+COMMENT ON TABLE aggregation_tracking
+  IS 'mapping from wire transfer identifiers (WTID) to deposits (and back)';
+
 CREATE INDEX IF NOT EXISTS aggregation_tracking_wtid_index
   ON aggregation_tracking
   (wtid_raw);
--- Table for the wire fees.
+COMMENT ON INDEX aggregation_tracking_wtid_index
+  IS 'for lookup_transactions';
+
+
 CREATE TABLE IF NOT EXISTS wire_fee
   (wire_method VARCHAR NOT NULL
   ,start_date INT8 NOT NULL
@@ -302,11 +361,14 @@ CREATE TABLE IF NOT EXISTS wire_fee
   ,master_sig BYTEA NOT NULL CHECK (LENGTH(master_sig)=64)
   ,PRIMARY KEY (wire_method, start_date)
   );
+COMMENT ON TABLE wire_fee
+  IS 'list of the wire fees of this exchange, by date';
+
 CREATE INDEX IF NOT EXISTS wire_fee_gc_index
   ON wire_fee
   (end_date);
--- Table for /recoup information
+
--- Do not cascade on the coin_pub, as we may keep the coin alive! */
+
 CREATE TABLE IF NOT EXISTS recoup
   (recoup_uuid BIGSERIAL UNIQUE
   ,coin_pub BYTEA NOT NULL REFERENCES known_coins (coin_pub)
@@ -317,6 +379,11 @@ CREATE TABLE IF NOT EXISTS recoup
   ,timestamp INT8 NOT NULL
   ,h_blind_ev BYTEA NOT NULL REFERENCES reserves_out (h_blind_ev) ON DELETE CASCADE
   );
+COMMENT ON TABLE recoup
+  IS 'Information about recoups that were executed';
+COMMENT ON COLUMN recoup.coin_pub
+  IS 'Do not CASCADE ON DROP on the coin_pub, as we may keep the coin alive!';
+
 CREATE INDEX IF NOT EXISTS recoup_by_coin_index
   ON recoup
   (coin_pub);
@@ -328,8 +395,8 @@ CREATE INDEX IF NOT EXISTS recoup_for_by_reserve
   (coin_pub
   ,h_blind_ev
   );
--- Table for /recoup-refresh information
+
--- Do not cascade on the coin_pub, as we may keep the coin alive! */
+
 CREATE TABLE IF NOT EXISTS recoup_refresh
   (recoup_refresh_uuid BIGSERIAL UNIQUE
   ,coin_pub BYTEA NOT NULL REFERENCES known_coins (coin_pub)
@@ -340,6 +407,9 @@ CREATE TABLE IF NOT EXISTS recoup_refresh
   ,timestamp INT8 NOT NULL
   ,h_blind_ev BYTEA NOT NULL REFERENCES refresh_revealed_coins (h_coin_ev) ON DELETE CASCADE
   );
+COMMENT ON COLUMN recoup_refresh.coin_pub
+  IS 'Do not CASCADE ON DROP on the coin_pub, as we may keep the coin alive!';
+
 CREATE INDEX IF NOT EXISTS recoup_refresh_by_coin_index
   ON recoup_refresh
   (coin_pub);
@@ -351,18 +421,23 @@ CREATE INDEX IF NOT EXISTS recoup_refresh_for_by_reserve
   (coin_pub
   ,h_blind_ev
   );
--- This table contains the pre-commit data for
+
--- wire transfers the exchange is about to execute.
+
 CREATE TABLE IF NOT EXISTS prewire
   (prewire_uuid BIGSERIAL PRIMARY KEY
   ,type TEXT NOT NULL
   ,finished BOOLEAN NOT NULL DEFAULT false
   ,buf BYTEA NOT NULL
   );
--- Index for wire_prepare_data_get and gc_prewire statement
+COMMENT ON TABLE prewire
+  IS 'pre-commit data for wire transfers we are about to execute';
+
 CREATE INDEX IF NOT EXISTS prepare_iteration_index
   ON prewire
   (finished);
+COMMENT ON INDEX prepare_iteration_index
+  IS 'for wire_prepare_data_get and gc_prewire';
+
 
 -- Complete transaction
 COMMIT;

src/exchangedb/plugin_exchangedb_postgres.c

@@ -670,7 +670,7 @@ postgres_get_session (void *cls)
       GNUNET_PQ_make_prepare ("insert_refresh_revealed_coin",
                               "INSERT INTO refresh_revealed_coins "
                               "(rc "
-                              ",newcoin_index "
+                              ",freshcoin_index "
                               ",link_sig "
                               ",denom_pub_hash "
                               ",coin_ev"
@@ -683,7 +683,7 @@ postgres_get_session (void *cls)
          operation, used in #postgres_get_refresh_reveal() */
       GNUNET_PQ_make_prepare ("get_refresh_revealed_coins",
                               "SELECT "
-                              " newcoin_index"
+                              " freshcoin_index"
                               ",denom.denom_pub"
                               ",link_sig"
                               ",coin_ev"
@@ -692,7 +692,7 @@ postgres_get_session (void *cls)
                               "    JOIN denominations denom "
                               "      USING (denom_pub_hash)"
                               " WHERE rc=$1"
-                              "   ORDER BY newcoin_index ASC"
+                              "   ORDER BY freshcoin_index ASC"
                               " FOR UPDATE;",
                               1),
 
@@ -843,7 +843,7 @@ postgres_get_session (void *cls)
                               " ORDER BY deposit_serial_id ASC;",
                               1),
       /* Fetch an existing deposit request.
-         Used in #postgres_wire_lookup_deposit_wtid(). */
+         Used in #postgres_lookup_transfer_by_deposit(). */
       GNUNET_PQ_make_prepare ("get_deposit_for_wtid",
                               "SELECT"
                               " amount_with_fee_val"
@@ -999,7 +999,7 @@ postgres_get_session (void *cls)
                               "      USING (wtid_raw)"
                               " WHERE wtid_raw=$1;",
                               1),
-      /* Used in #postgres_wire_lookup_deposit_wtid */
+      /* Used in #postgres_lookup_transfer_by_deposit */
       GNUNET_PQ_make_prepare ("lookup_deposit_wtid",
                               "SELECT"
                               " aggregation_tracking.wtid_raw"
@@ -3629,7 +3629,7 @@ add_revealed_coins (void *cls,
     struct TALER_EXCHANGEDB_RefreshRevealedCoin *rrc = &grctx->rrcs[i];
     uint32_t off;
     struct GNUNET_PQ_ResultSpec rs[] = {
-      GNUNET_PQ_result_spec_uint32 ("newcoin_index",
+      GNUNET_PQ_result_spec_uint32 ("freshcoin_index",
                                     &off),
       GNUNET_PQ_result_spec_rsa_public_key ("denom_pub",
                                             &rrc->denom_pub.rsa_public_key),
@@ -4656,18 +4656,18 @@ postgres_lookup_wire_transfer (void *cls,
  * @return transaction status code
  - */
 static enum GNUNET_DB_QueryStatus
-postgres_wire_lookup_deposit_wtid (void *cls,
+postgres_lookup_transfer_by_deposit (void *cls,
-                                   struct TALER_EXCHANGEDB_Session *session,
+                                     struct TALER_EXCHANGEDB_Session *session,
-                                   const struct
+                                     const struct
-                                   GNUNET_HashCode *h_contract_terms,
+                                     GNUNET_HashCode *h_contract_terms,
-                                   const struct GNUNET_HashCode *h_wire,
+                                     const struct GNUNET_HashCode *h_wire,
-                                   const struct
+                                     const struct
-                                   TALER_CoinSpendPublicKeyP *coin_pub,
+                                     TALER_CoinSpendPublicKeyP *coin_pub,
-                                   const struct
+                                     const struct
-                                   TALER_MerchantPublicKeyP *merchant_pub,
+                                     TALER_MerchantPublicKeyP *merchant_pub,
-                                   TALER_EXCHANGEDB_WireTransferByCoinCallback
+                                     TALER_EXCHANGEDB_WireTransferByCoinCallback
-                                   cb,
+                                     cb,
-                                   void *cb_cls)
+                                     void *cb_cls)
 {
   struct PostgresClosure *pg = cls;
   enum GNUNET_DB_QueryStatus qs;
@@ -7313,7 +7313,7 @@ libtaler_plugin_exchangedb_postgres_init (void *cls)
   plugin->get_coin_transactions = &postgres_get_coin_transactions;
   plugin->free_coin_transaction_list = &common_free_coin_transaction_list;
   plugin->lookup_wire_transfer = &postgres_lookup_wire_transfer;
-  plugin->wire_lookup_deposit_wtid = &postgres_wire_lookup_deposit_wtid;
+  plugin->lookup_transfer_by_deposit = &postgres_lookup_transfer_by_deposit;
   plugin->insert_aggregation_tracking = &postgres_insert_aggregation_tracking;
   plugin->insert_wire_fee = &postgres_insert_wire_fee;
   plugin->get_wire_fee = &postgres_get_wire_fee;

src/exchangedb/test_exchangedb.c

@@ -330,15 +330,15 @@ static struct TALER_TransferPublicKeyP tpub;
  *
  * @param cls closure
  * @param rowid unique serial ID for the row in our database
- * @param num_newcoins size of the @a rrcs array
+ * @param num_freshcoins size of the @a rrcs array
- * @param rrcs array of @a num_newcoins information about coins to be created
+ * @param rrcs array of @a num_freshcoins information about coins to be created
  * @param num_tprivs number of entries in @a tprivs, should be #TALER_CNC_KAPPA - 1
  * @param tprivs array of @e num_tprivs transfer private keys
  * @param tp transfer public key information
  */
 static void
 never_called_cb (void *cls,
-                 uint32_t num_newcoins,
+                 uint32_t num_freshcoins,
                  const struct TALER_EXCHANGEDB_RefreshRevealedCoin *rrcs,
                  unsigned int num_tprivs,
                  const struct TALER_TransferPrivateKeyP *tprivs,
@@ -354,15 +354,15 @@ never_called_cb (void *cls,
  *
  * @param cls closure
  * @param rowid unique serial ID for the row in our database
- * @param num_newcoins size of the @a rrcs array
+ * @param num_freshcoins size of the @a rrcs array
- * @param rrcs array of @a num_newcoins information about coins to be created
+ * @param rrcs array of @a num_freshcoins information about coins to be created
  * @param num_tprivs number of entries in @a tprivs, should be #TALER_CNC_KAPPA - 1
  * @param tprivsr array of @e num_tprivs transfer private keys
  * @param tpr transfer public key information
  */
 static void
 check_refresh_reveal_cb (void *cls,
-                         uint32_t num_newcoins,
+                         uint32_t num_freshcoins,
                          const struct
                          TALER_EXCHANGEDB_RefreshRevealedCoin *rrcs,
                          unsigned int num_tprivs,
@@ -370,7 +370,7 @@ check_refresh_reveal_cb (void *cls,
                          const struct TALER_TransferPublicKeyP *tpr)
 {
   /* compare the refresh commit coin arrays */
-  for (unsigned int cnt = 0; cnt < num_newcoins; cnt++)
+  for (unsigned int cnt = 0; cnt < num_freshcoins; cnt++)
   {
     const struct TALER_EXCHANGEDB_RefreshRevealedCoin *acoin =
       &revealed_coins[cnt];
@@ -411,7 +411,7 @@ static unsigned int auditor_row_cnt;
  * @param coin_pub public key of the coin
  * @param coin_sig signature from the coin
  * @param amount_with_fee amount that was deposited including fee
- * @param num_newcoins how many coins were issued
+ * @param num_freshcoins how many coins were issued
  * @param noreveal_index which index was picked by the exchange in cut-and-choose
  * @param rc what is the session hash
  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
@@ -1235,14 +1235,14 @@ test_wire_out (struct TALER_EXCHANGEDB_Session *session,
 
     h_contract_terms_wt2.bits[0]++;
     FAILIF (GNUNET_DB_STATUS_SUCCESS_NO_RESULTS !=
-            plugin->wire_lookup_deposit_wtid (plugin->cls,
+            plugin->lookup_transfer_by_deposit (plugin->cls,
-                                              session,
+                                                session,
-                                              &h_contract_terms_wt2,
+                                                &h_contract_terms_wt2,
-                                              &h_wire_wt,
+                                                &h_wire_wt,
-                                              &coin_pub_wt,
+                                                &coin_pub_wt,
-                                              &merchant_pub_wt,
+                                                &merchant_pub_wt,
-                                              &cb_wtid_never,
+                                                &cb_wtid_never,
-                                              NULL));
+                                                NULL));
   }
   /* insert WT data */
   FAILIF (GNUNET_DB_STATUS_SUCCESS_ONE_RESULT !=
@@ -1286,14 +1286,14 @@ test_wire_out (struct TALER_EXCHANGEDB_Session *session,
                                         &cb_wt_check,
                                         &cb_wt_never));
   FAILIF (GNUNET_DB_STATUS_SUCCESS_ONE_RESULT !=
-          plugin->wire_lookup_deposit_wtid (plugin->cls,
+          plugin->lookup_transfer_by_deposit (plugin->cls,
-                                            session,
+                                              session,
-                                            &h_contract_terms_wt,
+                                              &h_contract_terms_wt,
-                                            &h_wire_wt,
+                                              &h_wire_wt,
-                                            &coin_pub_wt,
+                                              &coin_pub_wt,
-                                            &merchant_pub_wt,
+                                              &merchant_pub_wt,
-                                            &cb_wtid_check,
+                                              &cb_wtid_check,
-                                            &cb_wtid_never));
+                                              &cb_wtid_never));
   FAILIF (GNUNET_DB_STATUS_SUCCESS_ONE_RESULT !=
           plugin->select_wire_out_above_serial_id (plugin->cls,
                                                    session,

src/include/taler_exchangedb_lib.h

@@ -169,7 +169,7 @@ TALER_EXCHANGEDB_revocations_iterate (const char *revocation_dir,
 
 /**
  * Mark the given denomination key as revoked and request the wallets
- * to initiate /recoup.
+ * to initiate recoup.
  *
  * @param revocation_dir where to write the revocation certificate
  * @param denom_hash hash of the denomination key to revoke

src/include/taler_exchangedb_plugin.h

@@ -1,6 +1,6 @@
 /*
   This file is part of TALER
-  Copyright (C) 2014-2017 Taler Systems SA
+  Copyright (C) 2014-2020 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
@@ -1145,15 +1145,15 @@ struct TALER_EXCHANGEDB_RefreshRevealedCoin
  *
  * @param cls closure
  * @param rowid unique serial ID for the row in our database
- * @param num_newcoins size of the @a rrcs array
+ * @param num_freshcoins size of the @a rrcs array
- * @param rrcs array of @a num_newcoins information about coins to be created
+ * @param rrcs array of @a num_freshcoins information about coins to be created
  * @param num_tprivs number of entries in @a tprivs, should be #TALER_CNC_KAPPA - 1
  * @param tprivs array of @e num_tprivs transfer private keys
  * @param tp transfer public key information
  */
 typedef void
 (*TALER_EXCHANGEDB_RefreshCallback)(void *cls,
-                                    uint32_t num_newcoins,
+                                    uint32_t num_freshcoins,
                                     const struct
                                     TALER_EXCHANGEDB_RefreshRevealedCoin *rrcs,
                                     unsigned int num_tprivs,
@@ -2147,7 +2147,7 @@ struct TALER_EXCHANGEDB_Plugin
 
 
   /**
-   * Lookup in the database for the @a num_newcoins coins that we
+   * Lookup in the database for the @a num_freshcoins coins that we
    * created in the given refresh operation.
    *
    * @param cls the @e cls of this struct with the plugin-specific state
@@ -2251,15 +2251,16 @@ struct TALER_EXCHANGEDB_Plugin
    * @return transaction status code
    */
   enum GNUNET_DB_QueryStatus
-  (*wire_lookup_deposit_wtid)(void *cls,
+  (*lookup_transfer_by_deposit)(void *cls,
-                              struct TALER_EXCHANGEDB_Session *session,
+                                struct TALER_EXCHANGEDB_Session *session,
-                              const struct GNUNET_HashCode *h_contract_terms,
+                                const struct GNUNET_HashCode *h_contract_terms,
-                              const struct GNUNET_HashCode *h_wire,
+                                const struct GNUNET_HashCode *h_wire,
-                              const struct TALER_CoinSpendPublicKeyP *coin_pub,
+                                const struct
-                              const struct
+                                TALER_CoinSpendPublicKeyP *coin_pub,
-                              TALER_MerchantPublicKeyP *merchant_pub,
+                                const struct
-                              TALER_EXCHANGEDB_WireTransferByCoinCallback cb,
+                                TALER_MerchantPublicKeyP *merchant_pub,
-                              void *cb_cls);
+                                TALER_EXCHANGEDB_WireTransferByCoinCallback cb,
+                                void *cb_cls);
 
 
   /**
@@ -2546,6 +2547,7 @@ struct TALER_EXCHANGEDB_Plugin
                                         TALER_EXCHANGEDB_ReserveInCallback cb,
                                         void *cb_cls);
 
+
   /**
    * Select inbound wire transfers into reserves_in above @a serial_id
    * in monotonically increasing order by @a account_name.
@@ -2569,6 +2571,7 @@ struct TALER_EXCHANGEDB_Plugin
                                                    cb,
                                                    void *cb_cls);
 
+
   /**
    * Select withdraw operations from reserves_out above @a serial_id
    * in monotonically increasing order.
@@ -2589,6 +2592,7 @@ struct TALER_EXCHANGEDB_Plugin
                                         TALER_EXCHANGEDB_WithdrawCallback cb,
                                         void *cb_cls);
 
+
   /**
    * Function called to select outgoing wire transfers the exchange
    * executed, ordered by serial ID (monotonically increasing).