commit 12a4738f43286fd8da83c00b054e68529339d4df
parent 3c808661c6552fd2700cd25c42d5ff1e170f87c1
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 11 Aug 2023 20:58:33 +0200
add man pages for dbconfig commands
Diffstat:
7 files changed, 316 insertions(+), 38 deletions(-)
diff --git a/conf.py b/conf.py
@@ -496,6 +496,34 @@ man_pages = [
1,
),
(
+ "manpages/taler-auditor-dbconfig.1",
+ "taler-auditor-dbconfig",
+ "configure Taler auditor database",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/taler-exchange-dbconfig.1",
+ "taler-exchange-dbconfig",
+ "configure Taler exchange database",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/taler-merchant-dbconfig.1",
+ "taler-merchant-dbconfig",
+ "configure Taler merchant database",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/sync-dbconfig.1",
+ "sync-dbconfig",
+ "configure sync database",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
"manpages/taler-exchange-dbinit.1",
"taler-exchange-dbinit",
"initialize Taler exchange database",
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -135,7 +135,7 @@ possibly by using HTTPS.
// Linear cost factor for the STEFAN curve used
// to (over) approximate fees payable by amount.
-.
+ //
// Note that the total to be paid is first to be
// divided by the smallest denomination to obtain
// the value to be multiplied with.
@@ -231,6 +231,7 @@ possibly by using HTTPS.
// explicitly as the client might otherwise be confused by clock skew as to
// which signing key was used.
eddsa_pub: EddsaPublicKey;
+
}
.. ts:def:: GlobalFees
diff --git a/design-documents/041-wallet-balance-amount-definitions.rst b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -50,15 +50,15 @@ MANUAL_WITHDRAW
account may charge some fee that can be taken into account
``coins`` = select-coin-for-operation(credit, mode, instructed_amount)
-
+
if instructed_amount mode = raw
``raw_amount`` = instructed_amount
-
+
``effective_amount`` = instructed_amount - coins.withdrawal_fee
if instructed_amount mode = effective
``raw_amount`` = instructed_amount + coins.withdrawal_fee
-
+
``effective_amount`` = instructed_amount
DEPOSIT
@@ -71,7 +71,7 @@ DEPOSIT
if instructed_amount mode = raw
``raw_amount`` = instructed_amount
- ``effective_amount`` = instructed_amount + coins.deposit_fee + coins.refresh_fee + wire.transfer_fee
+ ``effective_amount`` = instructed_amount + coins.deposit_fee + coins.refresh_fee + wire.transfer_fee
if instructed_amount mode = effective
``raw_amount`` = instructed_amount - coins.deposit_fee - coins.refresh_fee - wire.transfer_fee
@@ -95,25 +95,25 @@ PULL CREDIT (creating an invoice)
``raw_amount`` = instructed_amount + coins.withdrawal_fee + purse_fee
``effective_amount`` = instructed_amount
-
+
if instructed_amount mode = counter-party
- ``raw_amount`` = instructed_amount - coins.counter-party_deposit_fee
+ ``raw_amount`` = instructed_amount - coins.counter-party_deposit_fee
``effective_amount`` = instructed_amount - coins.counter-party_deposit_fee - coins.withdrawal_fee - purse_fee
- ``counter-party_raw_amount`` = raw_amount
-
- ``counter-party_effective_amount`` = raw_amount + coins.counter-party_deposit_fee
+ ``counter-party_raw_amount`` = raw_amount
+
+ ``counter-party_effective_amount`` = raw_amount + coins.counter-party_deposit_fee
.. note::
- counter-party_effective_amount is an estimation since refresh fee is not included.
- Refresh fee can't be calculated because depends on the coins available in the wallet
+ counter-party_effective_amount is an estimation since refresh fee is not included.
+ Refresh fee can't be calculated because depends on the coins available in the wallet
of the counter-party
.. note::
coins.counter-party_deposit_fee is the minimum deposit_fee that can be calculated for the
- given exchange. Counter-party may pay more if it have different preferences doing the coin
+ given exchange. Counter-party may pay more if it have different preferences doing the coin
selection.
@@ -134,19 +134,19 @@ PUSH DEBIT (creating a transfer)
``raw_amount`` = instructed_amount - coins.deposit_fee - purse_fee
``effective_amount`` = instructed_amount
-
+
if instructed_amount mode = counter-party
- ``raw_amount`` = instructed_amount + coins.counter-party_withdraw_fee
+ ``raw_amount`` = instructed_amount + coins.counter-party_withdraw_fee
``effective_amount`` = instructed_amount - coins.counter-party_withdraw_fee - coins.withdrawal_fee - purse_fee
-
- ``counter-party_raw_amount`` = raw_amount
+
+ ``counter-party_raw_amount`` = raw_amount
``counter-party_effective_amount`` = raw_amount - coins.counter-party_withdraw_fee
.. note::
coins.counter-party_withdraw_fee is the minimum withdraw_fee that can be calculated for the
- given exchange. Counter-party may pay more if it have different preferences doing the coin
+ given exchange. Counter-party may pay more if it have different preferences doing the coin
selection.
@@ -155,7 +155,7 @@ Transaction types completed by the wallet
Next transaction types are not initiated in the wallet so instructed amount is not defined by the wallet user.
-We need to calculate effective_amount to check if the wallet is able to perform the operation or the user accept
+We need to calculate effective_amount to check if the wallet is able to perform the operation or the user accept
the fees.
BANK_WITHDRAW
@@ -164,15 +164,15 @@ BANK_WITHDRAW
account may charge some fee that can be taken into account
``coins`` = select-coin-for-operation(credit, mode, instructed_amount)
-
+
if instructed_amount mode = raw
``raw_amount`` = instructed_amount
-
+
``effective_amount`` = instructed_amount - coins.withdrawal_fee
if instructed_amount mode = effective
``raw_amount`` = instructed_amount + coins.withdrawal_fee
-
+
``effective_amount`` = instructed_amount
@@ -180,7 +180,7 @@ BANK_WITHDRAW
how much wire_fee the merchant is willing to pay
``merchant_wire_fee`` = min(wire.transfer_fee / contractTerms.amortization_factor, contractTerms.max_wire_fee)
-
+
``merchant_deposit_fee`` = min(contractTerms.max_fee, contract_wire_fee)
@@ -216,10 +216,10 @@ PUSH CREDIT (getting the transfer)
.. note::
In the case that the withdrawal_fee of the coin selection for the push-credit amount
is higher than the wire_fee of the exchange, can the wallet ask the exchange to make
- a wire transfer of the purse instead of proceeding?
+ a wire transfer of the purse instead of proceeding?
PULL DEBIT (paying an invoice)
- raw amount is the net value of the invoice without fees
+ raw amount is the net value of the invoice without fees
``instructed_amount`` = p2pContract.amount
@@ -234,7 +234,7 @@ REFUND
``instructed_amount`` = refund.amount
- ``raw_amount`` = instructed_amount
+ ``raw_amount`` = instructed_amount
``effective_amount`` = instructed_amount - refund_fee - refresh_fee
@@ -242,7 +242,7 @@ REFUND
There may be the case that the merchant should refund all the value of the purchase
and that may include paying for the refund_fee.
- Is there a way that the merchant can initiate a refund of purchase + refund_fee so
+ Is there a way that the merchant can initiate a refund of purchase + refund_fee so
the wallet will get the same effective_amount?
TIP
@@ -252,11 +252,11 @@ TIP
``raw_amount`` = instructed_amount + withdrawal_fee
- ``effective_amount`` = instructed_amount
+ ``effective_amount`` = instructed_amount
- .. note::
+ .. note::
We should not show fee for tips in the wallet since the merchant is the one choosing
- the exchange and we can assume that those tips are paid by the merchant.
+ the exchange and we can assume that those tips are paid by the merchant.
So the wallet only care about the effective.
Coin selection algorithm
@@ -266,17 +266,22 @@ Is an internal optimization algorithm that will choose coins given a denominatio
until amount is reached. The coins selected to minimize the fee spent.
``select-coin-for-operation`` will receive 3 parameters:
+
* operation: define if the coins are selected from wallet database or from denomination list. Possible values are:
- - credit: reduce withdrawal fee, use exchange denomination list
- - debit: reduce deposit fee, use database denomination and current coin count
+
+ - credit: reduce withdrawal fee, use exchange denomination list
+ - debit: reduce deposit fee, use database denomination and current coin count
+
* amount: how much value the coins need to sum up
* mode: the interpretation of the amount parameter
+
- net: the amount does not include the operation fee
- gross: the amount include the operation fee
If the operation is debit and with the current coins there is no way to reach the amount then
- 1. an optimized withdrawal operation can be suggested (list of denominations)
- 2. an optimized refresh operation can be suggested (amount gap, coin to be refreshed and list of denominations to withdraw)
+
+ 1. an optimized withdrawal operation can be suggested (list of denominations)
+ 2. an optimized refresh operation can be suggested (amount gap, coin to be refreshed and list of denominations to withdraw)
.. note::
@@ -287,8 +292,8 @@ If the operation is debit and with the current coins there is no way to reach th
withdrawal_fee = amount1 - amount2
- then the wallet should select the same coins using the correct mode
-
+ then the wallet should select the same coins using the correct mode
+
select-coin(withdraw, raw, amount1) == select-coin(withdraw, effective, amount2)
@@ -312,7 +317,7 @@ For deposits (where there is no contract that already specifies an amount):
* ``raw-mode`` (default): The instructed amount is what will be paid to the "merchant" (or the customer's bank account), ignoring wire fees
* ``effective-mode``: The instructed amount is how the wallet's balance will be affected. Difficult to compute accurately because refresh is involved. Note that the calculation should ideally again be made available when the user is asked to specify an amount when using a template.
-
+
For peer-push-debit:
* ``raw-mode`` (default): The instructed amount is what will be paid, deposit fees are covered by the sender, withdrawal fees from the reserve by the receiver
@@ -402,7 +407,7 @@ Balance Mismatch
----------------
The wallet uses the following terminology when an operation can't succeed
-because the balance is too low, even though the instructed amount
+because the balance is too low, even though the instructed amount
- "fee-gap-estimate": Additional (material) balance that the wallet estimates it
still needs for the operation to succeed.
diff --git a/manpages/sync-dbconfig.1.rst b/manpages/sync-dbconfig.1.rst
@@ -0,0 +1,61 @@
+sync-dbconfig(1)
+################
+
+.. only:: html
+
+ Name
+ ====
+
+ **sync-dbconfig** - configure sync database
+
+
+Synopsis
+========
+
+**sync-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**sync-dbconfig** is a simple shell script that configures
+a Postgresql database for use by ``sync-httpd``.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+ Write the database configuration to FILENAME. The tool
+ will append the required ``CONFIG`` option for the
+ Postgresql access to the respective file.
+
+**-h**
+ Print short help on options.
+
+**-n** *DBNAME*
+ Use DBNAME for the name of the created database.
+
+**-r**
+ Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+ Skip database initialization. Useful if you want to run
+ ``sync-dbinit`` manually.
+
+**-u** *USER*
+ Specifies the (main) sync user that will access the database.
+
+See Also
+========
+
+sync-dbinit(1), sync.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-auditor-dbconfig.1.rst b/manpages/taler-auditor-dbconfig.1.rst
@@ -0,0 +1,61 @@
+taler-auditor-dbconfig(1)
+#########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-auditor-dbconfig** - configure Taler auditor database
+
+
+Synopsis
+========
+
+**taler-auditor-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**taler-auditor-dbconfig** is a simple shell script that configures
+a Postgresql database for use by the GNU Taler auditor.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+ Write the database configuration to FILENAME. The tool
+ will append the required ``CONFIG`` option for the
+ Postgresql access to the respective file.
+
+**-h**
+ Print short help on options.
+
+**-n** *DBNAME*
+ Use DBNAME for the name of the created database.
+
+**-r**
+ Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+ Skip database initialization. Useful if you want to run
+ ``taler-auditor-dbinit`` manually.
+
+**-u** *USER*
+ Specifies the (main) auditor user that will access the database.
+
+See Also
+========
+
+taler-auditor-dbinit(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-exchange-dbconfig.1.rst b/manpages/taler-exchange-dbconfig.1.rst
@@ -0,0 +1,61 @@
+taler-exchange-dbconfig(1)
+##########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-exchange-dbconfig** - configure Taler exchange database
+
+
+Synopsis
+========
+
+**taler-exchange-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**taler-exchange-dbconfig** is a simple shell script that configures
+a Postgresql database for use by the GNU Taler exchange.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+ Write the database configuration to FILENAME. The tool
+ will append the required ``CONFIG`` option for the
+ Postgresql access to the respective file.
+
+**-h**
+ Print short help on options.
+
+**-n** *DBNAME*
+ Use DBNAME for the name of the created database.
+
+**-r**
+ Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+ Skip database initialization. Useful if you want to run
+ ``taler-exchange-dbinit`` manually.
+
+**-u** *USER*
+ Specifies the (main) exchange user that will access the database.
+
+See Also
+========
+
+taler-exchange-dbinit(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-merchant-dbconfig.1.rst b/manpages/taler-merchant-dbconfig.1.rst
@@ -0,0 +1,61 @@
+taler-merchant-dbconfig(1)
+##########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-merchant-dbconfig** - configure Taler merchant database
+
+
+Synopsis
+========
+
+**taler-merchant-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**taler-merchant-dbconfig** is a simple shell script that configures
+a Postgresql database for use by the GNU Taler merchant.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+ Write the database configuration to FILENAME. The tool
+ will append the required ``CONFIG`` option for the
+ Postgresql access to the respective file.
+
+**-h**
+ Print short help on options.
+
+**-n** *DBNAME*
+ Use DBNAME for the name of the created database.
+
+**-r**
+ Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+ Skip database initialization. Useful if you want to run
+ ``taler-merchant-dbinit`` manually.
+
+**-u** *USER*
+ Specifies the (main) merchant user that will access the database.
+
+See Also
+========
+
+taler-merchant-dbinit(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
