commit 650f924522aab65632cde4fac53543212c4aef89
parent ce0bf34be42a49bef317ef58ea705accbb51a232
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 1 May 2026 22:42:39 +0200
improve exchange package descriptions
Diffstat:
| M | debian/control | | | 158 | +++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------- |
1 file changed, 106 insertions(+), 52 deletions(-)
diff --git a/debian/control b/debian/control
@@ -36,12 +36,18 @@ Depends:
netbase,
${misc:Depends},
${shlibs:Depends}
-Description: Libraries to talk to a GNU Taler exchange.
- The package also contains various files fundamental
- to all GNU Taler installations, such as the
- taler-config configuration command-line tool,
- various base configuration files and associated
- documentation.
+Description: shared libraries to talk to a GNU Taler exchange
+ GNU Taler is the privacy-preserving digital payment system from the GNU
+ project. This package contains the shared C libraries used by clients
+ and services to interact with a Taler exchange via its REST API, to parse
+ and verify exchange-issued cryptographic objects (denomination keys,
+ signing keys, deposit confirmations, ...) and to handle Taler amounts.
+ .
+ Also included is taler-exchange-config, the command-line tool to read
+ and edit Taler configuration files, along with the base configuration
+ fragments and documentation shared by all Taler exchange components.
+ Every other taler-exchange-* and taler-auditor* package depends on this
+ one.
Package: taler-terms-generator
Architecture: any
@@ -54,9 +60,17 @@ Depends:
groff,
ghostscript,
${misc:Depends}
-Description: Tool to generate the terms of service
- and privacy policy for various languages and data
- formats. Useful for various GNU Taler components.
+Description: generator for GNU Taler terms of service and privacy policy
+ taler-terms-generator converts a reStructuredText source document into
+ the bundle of HTML, Markdown, plain-text, EPUB and PDF renderings (and
+ multiple languages) that a Taler service expects to find on disk in
+ order to answer the /terms and /pp REST endpoints with the appropriate
+ content negotiation.
+ .
+ It is useful for GNU Taler exchange, merchant and auditor operators who
+ wish to publish or update their legal documents. Pandoc, groff and
+ Ghostscript are pulled in as runtime dependencies to perform the
+ conversions.
Package: taler-exchange-database
Architecture: any
@@ -67,10 +81,18 @@ Depends:
netbase,
${misc:Depends},
${shlibs:Depends}
-Description: Programs and libraries to manage a GNU Taler exchange database.
- This package contains only the code to setup the
- (Postgresql) database interaction (taler-exchange-dbinit
- and associated resource files).
+Description: database initialisation tool for the GNU Taler exchange
+ GNU Taler is the privacy-preserving digital payment system from the GNU
+ project. This package contains taler-exchange-dbinit together with the
+ SQL resource files it loads. The tool creates the schema, indices,
+ customisation hooks and (optionally) the auditor notification triggers
+ used by the exchange and the auditor in their PostgreSQL database, and
+ supports incremental garbage collection and shard-lock recovery after
+ crashes.
+ .
+ Both taler-exchange and taler-auditor depend on this package, as the
+ two services share a database layout and the same setup tooling. A
+ PostgreSQL server (>= 15) is required at runtime.
Package: taler-exchange
Architecture: any
@@ -93,22 +115,30 @@ Recommends:
apache2 | nginx | httpd,
robocop,
postgresql (>=15.0)
-Description: GNU's payment system operator.
- GNU Taler is the privacy-preserving digital payment
- system from the GNU project. This package contains the
- core logic that must be run by the payment service
- provider or bank to offer payments to consumers and
- merchants. At least one exchange must be operated
- per currency.
- In addition to the core logic, an exchange operator
- must also have a system running the "offline" logic
- which is packaged as taler-exchange-offline. It is
- recommended to keep the "offline" logic on a system
- that is never connected to the Internet. However, it
- is also possible to run the "offline" logic directly
- on the production system, especially for testing.
- Finally, an exchange operator should also be prepared
- to run a taler-auditor.
+Description: GNU Taler payment system - exchange operator daemons
+ GNU Taler is the privacy-preserving digital payment system from the GNU
+ project. The exchange is the central service operated by a payment
+ service provider or bank to issue and redeem digital coins for a given
+ currency; at least one exchange must be operated per currency.
+ .
+ This package ships the daemons required to run an exchange in
+ production:
+ * taler-exchange-httpd, the public REST frontend talked to by wallets
+ and merchant backends;
+ * taler-exchange-secmod-rsa, -cs and -eddsa, the security modules that
+ hold the online signing keys and communicate with the HTTPD over
+ UNIX-domain sockets;
+ * taler-exchange-aggregator, -transfer, -wirewatch and -closer, which
+ drive the interaction with the bank (aggregating deposits, executing
+ outgoing wire transfers, observing incoming transfers, and refunding
+ abandoned reserves);
+ * taler-exchange-expire, -sanctionscheck and the KYC/AML pipeline
+ helpers (taler-exchange-kyc-* converters and triggers).
+ .
+ Running an exchange additionally requires the air-gapped offline-signing
+ tool packaged as taler-exchange-offline (recommended). It is also
+ recommended to run a taler-auditor to check the operation and determine
+ expected balance in the escrow account and profits from fees.
Package: taler-exchange-offline
Architecture: any
@@ -121,14 +151,22 @@ Depends:
netbase,
${misc:Depends},
${shlibs:Depends}
-Description: Tools for managing the GNU Taler exchange offline keys.
- A GNU Taler exchange uses an offline key to sign its online
- keys, fee structure, bank routing information and other meta
- data. The offline signing key is the root of the Taler PKI
- that is then embedded in consumer wallets and merchant backends.
- This package includes the tool to download material to sign
- from the exchange, create signatures, and upload the resulting
- signatures to the exchange.
+Description: air-gapped signing tool for the GNU Taler exchange master key
+ A GNU Taler exchange uses a long-term offline master key to sign its
+ online signing keys, denomination keys, fee structure, bank account
+ details, auditor and partner-exchange registrations, AML staff entries
+ and key-revocation messages. The corresponding master public key forms
+ the root of the Taler PKI embedded in consumer wallets and merchant
+ backends, so the private key must be protected with great care.
+ .
+ This package contains taler-exchange-offline, the command-line tool
+ used to set up the master key, download future signing material from a
+ running exchange, inspect and sign it offline, and upload the resulting
+ signatures back to the exchange. It is recommended to install
+ this package on a dedicated machine that is never connected to the
+ Internet; it also must be installed on some online system to
+ download key material from the exchange and to upload signatures and
+ configuration data to the exchange.
Package: taler-exchange-typst
Architecture: any
@@ -136,11 +174,15 @@ Depends:
pdftk
Recommends:
typst
-Description: Typst packages for GNU Taler exchange.
+Description: Typst templates for GNU Taler exchange PDF generation
+ This package ships the Typst templates that the GNU Taler
+ exchange uses to render PDF artefacts (such as receipts and reports)
+ from structured data.
.
- This package contains Typst packages used by the
- exchange for PDF generation. It should be installed
- alongside Typst and pdftk for PDF generation.
+ The pdftk dependency is required at runtime to assemble the resulting
+ PDFs; the typst compiler itself is recommended but kept optional as
+ distros still often lack a native Typst package and thus operators
+ are likely to supply a locally built or vendored Typst compiler.
Package: taler-auditor
Architecture: any
@@ -155,15 +197,21 @@ Depends:
netbase,
${misc:Depends},
${shlibs:Depends}
-Description: GNU's payment system auditor.
- GNU Taler is the privacy-preserving digital payment
- system from the GNU project. This package contains the
- auditor logic. It verifies that the taler-exchange run
- by a payment service provider is correctly performing
- its bank transactions and thus has the correct balance
- in its escrow account. Each exchange operator is
- expected to make use of one or more auditors as part
- of its regulatory compliance.
+Description: GNU Taler payment system - independent auditor
+ GNU Taler is the privacy-preserving digital payment system from the GNU
+ project. An auditor is an independent third party (or the exchange
+ operator themselves) that verifies the correct operation
+ of a Taler exchange: it checks all cryptographic signatures recorded in
+ the exchange's database, recomputes balances, and reconciles the
+ reported state against the bank account, alerting the operator to any
+ inconsistencies and computing expected balance, revenue and risk
+ exposure.
+ .
+ This package provides the taler-auditor incremental audit tool, the
+ long-running taler-auditor-httpd REST service, the taler-auditor-sync
+ helper that maintains a safe replica of the exchange database, and the
+ corresponding helper daemons. The offline-signing tool used
+ by the auditor is also included.
Package: libtalerexchange-dev
Section: libdevel
@@ -175,6 +223,12 @@ Depends:
libmicrohttpd-dev (>=0.9.71),
${misc:Depends},
${shlibs:Depends}
-Description: libraries to talk to a GNU Taler exchange (development)
+Description: GNU Taler exchange client libraries - development files
+ This package contains the C header files, static libraries and
+ pkg-config files needed to build software against the GNU Taler
+ exchange client libraries shipped in libtalerexchange.
.
- This package contains the development files.
+ It also installs taler-fakebank-run, an in-memory implementation of the
+ Taler Wire Gateway API used by the Taler test suite. The fake bank is
+ not suitable for production use: all transaction state is kept in RAM
+ and lost on shutdown.
