document taler-exchange-drain

3 files changed, 81 insertions, 0 deletions

diff --git a/conf.py b/conf.py
index b0985e97..9cc26ddd 100644
--- a/conf.py
+++ b/conf.py
@@ -301,6 +301,9 @@ man_pages = [
     ("manpages/taler-exchange-closer.1", "taler-exchange-closer",
      "close idle reserves", "GNU Taler contributors",
      1),
+    ("manpages/taler-exchange-drain.1", "taler-exchange-drain",
+     "drain profits from exchange", "GNU Taler contributors",
+     1),
     ("manpages/taler-exchange-expire.1", "taler-exchange-expire",
      "refund expired purses", "GNU Taler contributors",
      1),
diff --git a/manpages/taler-exchange-drain.1.rst b/manpages/taler-exchange-drain.1.rst
new file mode 100644
index 00000000..ade7c00e
--- /dev/null
+++ b/manpages/taler-exchange-drain.1.rst
@@ -0,0 +1,56 @@
+taler-exchange-drain(1)
+#########################
+
+.. only:: html
+
+   Name
+   ====
+
+   **taler-exchange-drain** - drain profits from exchange escrow account
+
+Synopsis
+========
+
+**taler-exchange-drain**
+[**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*]
+[**-h** | **--help**]
+[**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*]
+[**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*]
+[**-v** | **--version**]
+
+Description
+===========
+
+**taler-exchange-drain** is used to trigger a wire transfer from the exchange's escrow account to a normal (non-escrowed) bank account of the exchange.  The entire drain process is necessary to ensure that the auditor is aware of the
+balance changes arising from an exchange making profits from fees.
+
+To use it, you must first create an upload a 'drain' command using **taler-exchange-offline**. Afterwards this command should be run to actually queue the drain. The actual drain will then be executed by **taler-exchange-transfer**.
+
+
+**-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME*
+   Use the configuration and other resources for the exchange to operate
+   from *FILENAME*.
+
+**-h** \| **--help**
+   Print short help on options.
+
+**-L** *LOGLEVEL* \| **--loglevel=**\ ‌\ *LOGLEVEL*
+   Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``,
+   ``WARNING``, ``ERROR``.
+
+**-l** *FILENAME* \| **--logfile=**\ ‌\ *FILENAME*
+   Send logging output to *FILENAME*.
+
+**-v** \| **--version**
+   Print version information.
+
+See Also
+========
+
+taler-exchange-transfer(1), taler-exchange-offline(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-offline.1.rst b/manpages/taler-exchange-offline.1.rst
index 10ab398d..29c8fc75 100644
--- a/manpages/taler-exchange-offline.1.rst
+++ b/manpages/taler-exchange-offline.1.rst
@@ -160,6 +160,28 @@ Note that an extension on the exchange will only become activated at runtime
 *after* the extension's configurations has been signed by the offline tool with
 the signing key and the signed configuration been uploaded to the exchange.
 
+drain
+-----
+
+This subcommand allows an exchange operator to transfer the
+profits made from transaction fees to a regular (non-escrowed) bank
+account.  Using this command, draining profits from the
+escrow account can be done in such a way that the auditor
+is aware of the special transaction and does not flag the
+resulting balance as fundamentally problematic.  Note that
+the drained amounts must still total up to less than the fees
+earned by the exchange.
+
+Arguments to the ``drain`` command are the amount to be drained (in the usual
+Taler amount format), the section of the exchange configuration specifying the
+account to be debited (this argument is currently ignored, and the account is
+purely derived from the wire method and the account being set for debiting),
+and finally the payto://-URI to wire the funds to.
+
+Note that to actually wire the funds, the exchange administrator must run
+**taler-exchange-drain** manually and confirm the operation after the
+``upload`` was completed.
+
 
 revoke-denomination
 -------------------