update taler-exchange-offline manual

1 files changed, 100 insertions, 14 deletions

diff --git a/manpages/taler-exchange-offline.1.rst b/manpages/taler-exchange-offline.1.rst
index 21d0275b..fcae1549 100644
--- a/manpages/taler-exchange-offline.1.rst
+++ b/manpages/taler-exchange-offline.1.rst
@@ -258,11 +258,10 @@ in a format suitable for the ``upload`` subcommand.
 enable-account
 --------------
 
-This subcommand
-informs an exchange that it should advertise a bank account as belonging to
-the exchange on its ``/wire`` endpoint.  Note that this does *not* ensure that
-the exchange will use this bank account for incoming or outgoing wire
-transfers! For this, the **taler-exchange-transfer** and
+This subcommand informs an exchange that it should advertise a bank account as
+belonging to the exchange on its ``/wire`` endpoint.  Note that this does
+*not* ensure that the exchange will use this bank account for incoming or
+outgoing wire transfers! For this, the **taler-exchange-transfer** and
 **taler-exchange-wirewatch** tools must be configured.  Furthermore, the bank
 account information advertised could theoretically differ from that which
 these tool actually use, for example if the public bank account is only a
@@ -271,12 +270,47 @@ front for the actual internal business accounts.
 The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given
 as the first argument to the subcommand.
 
+Afterwards, optional arguments can be given:
+
+  * ``conversion-url`` $URL: specifies that using this bank account is subject
+    to currency conversion. $URL must be the address of a currency conversion
+    REST API that allows merchants and wallets to determine the current
+    conversion rate.
+
+  * ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are
+    restrictions in place when crediting this bank account. Details depend on
+    the restriction $TYPE. This argument may be given multiple times, in which
+    case debitor accounts must satisfy all restrictions. Restriction types are
+    discussed below.
+
+  * ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions
+    in place when receiving money from the exchange. Wallets and merchants
+    must check that their target bank account satisfies these restrictions
+    before sending deposit requests to the exchange. Details depend on the
+    restriction $TYPE. This argument may be given multiple times, in which
+    case debitor accounts must satisfy all restrictions. Restriction types are
+    discussed below.
+
+The following types of credit- and debit-restrictions are supported:
+
+  * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used
+    for the given operation.  ``deny`` takes no further arguments.
+
+  * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's
+    bank account ``payto``-URI representation must follow a certain regular
+    expression given in $EXPR where the syntax follows posix-egrep, but
+    without support for character classes, GNU extensions, back-references or
+    intervals. See
+    `https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html`
+    for a description of the posix-egrep syntax. The $HINT must be a
+    human-readable description of the $EXPR.  $JSON should be a JSON array
+    mapping IETF BCP 47 language tags to localized versions of $HINT.
+
 The subcommand takes no inputs from ``stdin`` or other subcommands.
 
 It outputs the signature affirming the addition of the wire account,
 in a format suitable for the ``upload`` subcommand.
 
-
 disable-account
 ---------------
 
@@ -456,25 +490,58 @@ Upload signatures about future public keys (online)
 Download, sign and upload, all in one (online)
 ----------------------------------------------
 
-Note that doing this is only recommended in non-production deployments.
+Note that doing this is only recommended in non-production deployments,
+as this requires putting the "offline" key onto a system that is actually
+online!
 
 .. code-block:: console
 
-   $ taler-exchange-offline download sign upload
+   $ taler-exchange-offline \
+       download \
+       sign \
+       upload
 
 Here is a variant that shows the output of ``download``, but does not consume it,
 so that ``sign`` can see it as input, as in the variant without ``show``.
 
 .. code-block:: console
 
-   $ taler-exchange-offline download show - sign upload
+   $ taler-exchange-offline \
+       download \
+       show - \
+       sign \
+       upload
+
 
 Create signature to enable bank account (offline)
 -------------------------------------------------
 
+The following command sets up an unrestricted simple exchange bank account
+without conversion:
+
 .. code-block:: console
 
-   $ taler-exchange-offline enable-account payto://iban/DE24242 > account.json
+   $ taler-exchange-offline \
+       enable-account payto://iban/DE24242?receiver-name=operator > account.json
+
+The following command would set up an exchange bank account with conversion
+and restrict it to only receive money from Switzerland and deny its use for
+debit operations:
+
+.. code-block:: shell-session
+
+  $ taler-exchange-offline \
+    enable-account payto://x-taler-bank/example.com/?receiver-name=name \
+    conversion-url http://conversion.exchange.com/ \
+    debit-restriction \
+      deny \
+    credit-restriction \
+      regex \
+        'payto://iban/.*/CH.*?receiver-name=.*' \
+        'Swiss only' \
+        '{ "de" : "nur Schweiz", \
+           "fr" : "Suisse uniquement" }'
+
 
 Upload bank account signature (online)
 --------------------------------------
@@ -487,9 +554,19 @@ Upload bank account signature (online)
 Combine signing keys and enabling bank account (offline)
 --------------------------------------------------------
 
+You can chain multiple commands into one invocation:
+
 .. code-block:: console
 
-   $ taler-exchange-offline sign enable-account payto://iban/DE24242 < keys.json > combo.json
+   $ taler-exchange-offline \
+       sign \
+       enable-account \
+         payto://iban/DE24242 < keys.json > combo.json
+
+Note that ``sign`` must be first as it consumes the ``keys.json``
+input.  The resulting output combines the outputs of the ``sign``
+and ``enable-account`` subcommands.
+
 
 Upload various signatures (online)
 ----------------------------------
@@ -501,11 +578,20 @@ Upload various signatures (online)
 Create multiple revocation messages in one pass (offline)
 ---------------------------------------------------------
 
+You can freely combine almost all commands, including those for
+key revocation:
+
 .. code-block:: console
 
-   $ taler-exchange-offline revoke-denomination $DKH1 revoke-denomination $DKH2 > revoke.json
-   $ taler-exchange-offline revoke-signkey $SK1 revoke-signkey $SK2 > revoke.json
-   $ taler-exchange-offline revoke-signkey $SK revoke-denomkey $DKH > mix.json
+   $ taler-exchange-offline \
+       revoke-denomination $DKH1 \
+       revoke-denomination $DKH2 > revoke.json
+   $ taler-exchange-offline \
+       revoke-signkey $SK1 \
+       revoke-signkey $SK2 > revoke.json
+   $ taler-exchange-offline \
+       revoke-signkey $SK \
+       revoke-denomkey $DKH > mix.json
 
 The outputs ("revoke.json", "mix.json") must be uploaded using the ``upload``
 subcommand to the exchange to actually revoke the keys.