diff options
| author | Christian Grothoff <christian@grothoff.org> | 2024-02-10 23:07:31 +0100 |
|---|---|---|
| committer | Christian Grothoff <christian@grothoff.org> | 2024-02-10 23:07:31 +0100 |
| commit | ff81b14cfa6a753e6b9015a7057519c2b444c9bb (patch) | |
| tree | c067b83c5aec951f7ca3985483109543b4811f7e /texinfo | |
| parent | 300a469342ba879b16ff93aaaf170fa1b88e75fb (diff) | |
| download | docs-ff81b14cfa6a753e6b9015a7057519c2b444c9bb.tar.gz docs-ff81b14cfa6a753e6b9015a7057519c2b444c9bb.tar.bz2 docs-ff81b14cfa6a753e6b9015a7057519c2b444c9bb.zip | |
regen
Diffstat (limited to 'texinfo')
| -rw-r--r-- | texinfo/challenger.texi | 2 | ||||
| -rw-r--r-- | texinfo/taler-auditor.texi | 202 | ||||
| -rw-r--r-- | texinfo/taler-developer-manual-figures/arch-api.png | bin | 60110 -> 57007 bytes | |||
| -rw-r--r-- | texinfo/taler-developer-manual.texi | 485 | ||||
| -rw-r--r-- | texinfo/taler-exchange.texi | 535 | ||||
| -rw-r--r-- | texinfo/taler-merchant-api-tutorial-figures/arch-api.png | bin | 60110 -> 57007 bytes | |||
| -rw-r--r-- | texinfo/taler-merchant-api-tutorial.texi | 94 | ||||
| -rw-r--r-- | texinfo/taler-merchant-figures/arch-api.png | bin | 60110 -> 57007 bytes | |||
| -rw-r--r-- | texinfo/taler-merchant.texi | 680 |
9 files changed, 1157 insertions, 841 deletions
diff --git a/texinfo/challenger.texi b/texinfo/challenger.texi index 53187060..7f9e6ef3 100644 --- a/texinfo/challenger.texi +++ b/texinfo/challenger.texi @@ -19,7 +19,7 @@ @copying @quotation -GNU Taler 0.9.0, Feb 10, 2024 +GNU Taler 0.9.0, Jan 06, 2024 GNU Taler team diff --git a/texinfo/taler-auditor.texi b/texinfo/taler-auditor.texi index 8593c05b..10e41d03 100644 --- a/texinfo/taler-auditor.texi +++ b/texinfo/taler-auditor.texi @@ -19,7 +19,7 @@ @copying @quotation -GNU Taler 0.9.0, Feb 10, 2024 +GNU Taler 0.9.0, Jan 06, 2024 GNU Taler team @@ -99,7 +99,7 @@ Configuration * Configuration format:: * Initial configuration:: * Keys:: -* Configuring the auditor's REST endpoint:: +* Configuring the auditor’s REST endpoint:: * Bank account:: * Database:: * Legal conditions for using the service:: @@ -137,7 +137,7 @@ Operation Auditor implementation guide -* The auditor's database:: +* The auditor’s database:: * Invariants checked by the auditor:: * Testing the auditor:: @@ -220,7 +220,7 @@ to other parties. To perform this duty, you will need at least (read-only) access to the bank transactions of the exchange, as well as a continuously synchronized replica -of the exchange's database. The general assumption for running the auditor +of the exchange’s database. The general assumption for running the auditor is that this is done on a separate system controlled by the auditor. After all, the goal is to detect nerfarious activity of the exchange operator, which cannot be effectively done on a machine controlled by the exchange @@ -232,9 +232,9 @@ withdrawals made by consumers and income received by merchants. As a result, the auditor is expected to provide high confidentiality for the database. In general, the auditor does not have to offer high-availability: the exchange operator can continue operations without the auditor, and the auditor can -catch up with it later when the auditor's systems are restored. However, of +catch up with it later when the auditor’s systems are restored. However, of course any downtime would provide a window of opportunity for fraud and should -thus be minimized. Finally, the auditor's copy of the exchange's database can +thus be minimized. Finally, the auditor’s copy of the exchange’s database can be useful as a backup to the exchange in case the exchange experiences a loss of its own copies. Thus, business agreements between auditor and exchanges may include availability requirements as well. @@ -242,7 +242,7 @@ include availability requirements as well. Then, with the software provided, auditors can verify the cryptographic proofs collected by the exchange and detect if any improper bank transactions have been made. There are additional tasks which an auditor should perform. While this -manual only focuses on the audit of the exchange's database and wire transfers +manual only focuses on the audit of the exchange’s database and wire transfers with the existing tools, a proper auditor should also perform the following tasks: @@ -268,7 +268,7 @@ verification that the exchange properly implements the @code{/link} protocol @item verification that the exchange properly reports coins issued during the refresh protocol (by irregularly refreshing coins withdrawn by -the auditor and comparing against the exchange's database --- the +the auditor and comparing against the exchange’s database — the code required to support this is not yet implemented) @end itemize @@ -289,8 +289,8 @@ oversight function. Auditors should generally be independent third parties that verify that the exchange operates correctly. However, an exchange is likely to also run the auditing logic, as it is also used to calculate the exchange’s profits, risk -and liabilities. Furthermore, it's usually a good idea to not only rely on -third parties to verify one's own work. +and liabilities. Furthermore, it’s usually a good idea to not only rely on +third parties to verify one’s own work. The Taler software stack for an auditor consists of the following components: @@ -322,7 +322,7 @@ the auditor to detect if an exchange is underreporting deposits. In the future, the Web service should be extended to allow customers and merchants to automatically upload cryptographic proof of other violations of the specification by the exchange. However, for now it is assumed that -the respective cryptographic proofs are reported and verified manually --- +the respective cryptographic proofs are reported and verified manually — as with a well-behaved exchange this should obviously be a rare event. The main binary of this component is the @code{taler-auditor-httpd}. @@ -342,7 +342,7 @@ needs access to the wire gateway). The @code{taler-helper-auditor-wire} auditor verifies that the bank transactions performed by the exchange were done properly. This component must have access to the bank account -of the exchange, as well as to a copy of the exchange's database. +of the exchange, as well as to a copy of the exchange’s database. The @code{taler-auditor} script invokes the various helpers, each generating a JSON report. It then invokes the @code{taler-helper-auditor-render.py} @@ -388,7 +388,7 @@ Python3 module @code{jinja2} @itemize - @item -"Sphinx RTD Theme" Python package aka @code{python3-sphinx-rtd-theme} +“Sphinx RTD Theme” Python package aka @code{python3-sphinx-rtd-theme} on Debian-based systems (for GNUnet documentation support, can be omitted if GNUnet is configured with @code{--disable-documentation}) @@ -646,22 +646,22 @@ is not recommended for security. The recommended set of users includes: @itemize * @item -auditor --- runs the main auditing process and HTTP backend +auditor — runs the main auditing process and HTTP backend @item -sync --- synchronizes the ingres database with the production database +sync — synchronizes the ingres database with the production database @item -helper --- runs taler-auditor-offline download and upload commands +helper — runs taler-auditor-offline download and upload commands @item -auditor-ingres --- imports database from exchange production system +auditor-ingres — imports database from exchange production system @item -auditor-wire --- imports wire transfer data from bank production system +auditor-wire — imports wire transfer data from bank production system @item -offline --- manages the offline key, on a separate `offline' machine +offline — manages the offline key, on a separate `offline' machine @end itemize @end quotation @@ -681,10 +681,10 @@ distribution would typically create for you): @itemize * @item -www-data --- runs the HTTPS frontend (usually nginx or Apache) +www-data — runs the HTTPS frontend (usually nginx or Apache) @item -postgres --- runs the PostgreSQL database +postgres — runs the PostgreSQL database @end itemize @end quotation @@ -701,16 +701,16 @@ We recommend using the following databases for the auditor: @itemize * @item -exchange-ingres --- synchronized exchange database over the network +exchange-ingres — synchronized exchange database over the network @item -exchange-production --- local copy of exchange database with trusted schema +exchange-production — local copy of exchange database with trusted schema @item -auditor --- auditor production database with current state of the audit +auditor — auditor production database with current state of the audit @item -libeufin --- local state of the auditor-wire tool for the bank transfer data import +libeufin — local state of the auditor-wire tool for the bank transfer data import @end itemize @end quotation @@ -742,7 +742,7 @@ $ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql libeufin @chapter Configuration -The auditor's configuration works the same way as the configuration of other +The auditor’s configuration works the same way as the configuration of other Taler components. This section discusses configuration options related to the auditor. @@ -750,7 +750,7 @@ This section discusses configuration options related to the auditor. * Configuration format:: * Initial configuration:: * Keys:: -* Configuring the auditor's REST endpoint:: +* Configuring the auditor’s REST endpoint:: * Bank account:: * Database:: * Legal conditions for using the service:: @@ -865,7 +865,7 @@ BASE_URL = https://auditor.example.com/ The @code{helper} user that is used to download information from the exchange needs to know details about the exchange. Similarly, the @code{offline} user -needs to check signatures signed with the exchange's offline key. Hence, you +needs to check signatures signed with the exchange’s offline key. Hence, you need to obtain the @code{MASTER_PUBLIC_KEY} from the exchange operator (they need to run @code{taler-exchange-offline setup}) and the REST endpoint of the exchange and configure these: @@ -877,14 +877,14 @@ BASE_URL = https://exchange.example.com/ MASTER_PUBLIC_KEY = $SOMELONGBASE32VALUEHERE @end example -@node Keys,Configuring the auditor's REST endpoint,Initial configuration,Configuration +@node Keys,Configuring the auditor’s REST endpoint,Initial configuration,Configuration @anchor{taler-auditor-manual auditorkeys}@anchor{12}@anchor{taler-auditor-manual keys}@anchor{13} @section Keys The auditor works with one signing key to certify that it is auditing -a particular exchange's denomination keys. This key can and should -be kept `offline' (and backed up adequately). As with the exchange's +a particular exchange’s denomination keys. This key can and should +be kept `offline' (and backed up adequately). As with the exchange’s offline key, it is only used for a few cryptographic signatures and thus the respective code can be run on modest hardware, like a Raspberry Pi. @@ -926,9 +926,9 @@ You can set this configuration value using: PUBLIC_KEY = $SOMELONGBASE32VALUEHERE @end example -@node Configuring the auditor's REST endpoint,Bank account,Keys,Configuration +@node Configuring the auditor’s REST endpoint,Bank account,Keys,Configuration @anchor{taler-auditor-manual auditorserving}@anchor{14}@anchor{taler-auditor-manual configuring-the-auditor-s-rest-endpoint}@anchor{15} -@section Configuring the auditor's REST endpoint +@section Configuring the auditor’s REST endpoint The auditor can serve HTTP over both TCP and UNIX domain socket. @@ -954,7 +954,7 @@ HTTP over a UNIX domain socket for @code{unixpath} (i.e. 660 = @code{rw-rw----}). @end itemize -@node Bank account,Database,Configuring the auditor's REST endpoint,Configuration +@node Bank account,Database,Configuring the auditor’s REST endpoint,Configuration @anchor{taler-auditor-manual auditorbank-account}@anchor{16}@anchor{taler-auditor-manual bank-account}@anchor{17} @section Bank account @@ -997,14 +997,14 @@ CONFIG = postgres:///auditordemo If an exchange runs its own auditor, it may use the same database for the auditor and the exchange itself. -The @code{taler-auditor-dbinit} tool is used to initialize the auditor's +The @code{taler-auditor-dbinit} tool is used to initialize the auditor’s tables. After running this tool, the rights to CREATE or DROP tables are no longer required and should be removed. Both the @code{taler-auditor-httpd} and the @code{taler-auditor} (and its helpers) also need (read-only) access to a (recent, current, synchronized) copy of the -exchange's database. The configuration options are the same that are also -used when configuring the exchange' database: +exchange’s database. The configuration options are the same that are also +used when configuring the exchange’ database: @quotation @@ -1050,7 +1050,7 @@ setup and configure the legal conditions. @section Terms of Service -The service has an endpoint "/terms" to return the terms of service (in legal +The service has an endpoint “/terms” to return the terms of service (in legal language) of the service operator. Client software show these terms of service to the user when the user is first interacting with the service. Terms of service are optional for experimental deployments, if none are @@ -1064,7 +1064,7 @@ in the configuration file for the service: @itemize - @item -@code{TERMS_ETAG}: The current "Etag" to return for the terms of service. +@code{TERMS_ETAG}: The current “Etag” to return for the terms of service. This value must be changed whenever the terms of service are updated. A common value to use would be a version number. Note that if you change the @code{TERMS_ETAG}, you MUST also provide @@ -1081,7 +1081,7 @@ process. @section Privacy Policy -The service has an endpoint "/pp" to return the terms privacy policy (in legal +The service has an endpoint “/pp” to return the terms privacy policy (in legal language) of the service operator. Clients should show the privacy policy to the user when the user explicitly asks for it, but it should not be shown by default. Privacy policies are optional for experimental deployments, if none @@ -1095,7 +1095,7 @@ in the configuration file for the service: @itemize - @item -@code{PRIVACY_ETAG}: The current "Etag" to return for the privacy policy. +@code{PRIVACY_ETAG}: The current “Etag” to return for the privacy policy. This value must be changed whenever the privacy policy is updated. A common value to use would be a version number. Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide @@ -1116,7 +1116,7 @@ The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a particular layout. You may use the same directory for both the terms of service and the privacy policy, as long as you use different ETAGs. Inside of the directory, there should be sub-directories using two-letter language codes -like "en", "de", or "jp". Each of these directories would then hold +like “en”, “de”, or “jp”. Each of these directories would then hold translations of the current terms of service into the respective language. Empty directories are permitted in case translations are not available. @@ -1124,7 +1124,7 @@ Then, inside each language directory, files with the name of the value set as the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each of the files should be typical for the respective mime type. The set of supported mime types is currently hard-coded in the service, and includes -".epub", ".html", ".md", ".pdf" and ".txt" files. If other files are present, +“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present, the service may show a warning on startup. @menu @@ -1137,7 +1137,7 @@ the service may show a warning on startup. @subsection Example -A sample file structure for a @code{TERMS_ETAG} of "tos-v0" would be: +A sample file structure for a @code{TERMS_ETAG} of “tos-v0” would be: @itemize - @@ -1173,8 +1173,8 @@ TERMS_DIR/de/tos-v0.epub TERMS_DIR/de/tos-v0.md @end itemize -If the user requests an HTML format with language preferences "fr" followed by -"en", the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in +If the user requests an HTML format with language preferences “fr” followed by +“en”, the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in French. @node Generating the Legal Terms,Adding translations,Legal policies directory layout,Configuration @@ -1264,7 +1264,7 @@ restart the service. @anchor{taler-auditor-manual wallets}@anchor{24} Before GNU Taler wallets will happily interact with an exchange, the -respective auditor's public key (as obtained via @code{taler-auditor-offline +respective auditor’s public key (as obtained via @code{taler-auditor-offline setup} from the @code{offline} user) must be added under the respective currency to the wallet. This is usually expected to be hard-coded into the Taler wallet. @@ -1272,7 +1272,7 @@ wallet. Users can also manually add auditors for a particular currency via a Web page offering the respective pairing. -FIXME-DOLD: explain how that Web page works, once it works... +FIXME-DOLD: explain how that Web page works, once it works… @menu * Exchange:: @@ -1286,13 +1286,13 @@ FIXME-DOLD: explain how that Web page works, once it works... @section Exchange -The next step is to add the exchange's master public key and the base URL of +The next step is to add the exchange’s master public key and the base URL of the exchange to the list of exchanges audited by the auditor. This is done using the @code{taler-auditor-exchange} tool. The tool basically creates the -respective record in the auditor's database. +respective record in the auditor’s database. If this step is skipped, the auditor will malfunction at all future stages -with a foreign key violation, as it does not know the exchange's master public +with a foreign key violation, as it does not know the exchange’s master public key. @example @@ -1302,7 +1302,7 @@ $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL An equivalent step must be performed by the exchange operator. Here, the exchange operator must use the @code{taler-exchange-offline} tool to add the -auditor's public key, base URL and (business) name to the list of approved +auditor’s public key, base URL and (business) name to the list of approved auditors of the exchange. For details, see Auditor-configuration in the exchange operator manual. @@ -1340,7 +1340,7 @@ process that is outside of the scope of this document. Note that the @code{input.json} does not contain any confidential data. However, signing the wrong keys would be fatal in that it may allow an illegitimate exchange to convince users that it is a trustworthy operator and subsequently -betray the user's trust that is anchored in the existence of a trustworthy +betray the user’s trust that is anchored in the existence of a trustworthy auditor. Given the verified JSON input, the auditor can then sign it (typically @@ -1375,21 +1375,21 @@ command-line option, send logging output to standard error by default. The next key step for the auditor is to configure replication of the -`exchange''s database in-house. This should be performed in two steps +`exchange'’s database in-house. This should be performed in two steps as illustrated in the following figure: @image{taler-auditor-figures/replication,,,,png} First, the exchange should use standard PostgreSQL replication features to -enable the auditor to obtain a full copy of the exchange's database. -Second, the auditor should make a "trusted" local copy, ensuring that it +enable the auditor to obtain a full copy of the exchange’s database. +Second, the auditor should make a “trusted” local copy, ensuring that it never replicates malicious changes using @code{taler-auditor-sync}. Both of these steps are described in more detail below. We note that as a result of these steps, the auditor will have three databases: its own production primary database (as configured in -@code{auditordb-postgres}), its on production copy of the exchange's database -(@code{exchangedb-postgress}), and a third, untrusted "ingres" copy of the +@code{auditordb-postgres}), its on production copy of the exchange’s database +(@code{exchangedb-postgress}), and a third, untrusted “ingres” copy of the exchange database. The untrusted database should run as a separate PostgreSQL instance and is only accessed via @code{taler-auditor-sync} and the replication mechanism driven by the exchange operator. @@ -1405,7 +1405,7 @@ mechanism driven by the exchange operator. @subsection Ingres replication of the exchange production database -Ingres operation should be done using the @code{auditor-ingres} user --- or +Ingres operation should be done using the @code{auditor-ingres} user — or depending on the setup parts of the operation may be done by the @code{postgres} user directly. @@ -1418,10 +1418,10 @@ that asynchronous replication should suffice. The resulting auditor database should be treated as read-only on the auditor side. The @code{taler-exchange-dbinit} tool can be used to setup the schema, or -the schema can be replicated using PostgreSQL's standard mechanisms. The same +the schema can be replicated using PostgreSQL’s standard mechanisms. The same applies for schema upgrades: if logical replication is used (which does not replicate schema changes), @code{taler-exchange-dbinit} can be used to migrate -the schema(s) in both the ingres and production copies of the exchange's +the schema(s) in both the ingres and production copies of the exchange’s database as well. On the exchange side, a database user must be created that has the right @@ -1435,7 +1435,7 @@ $ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange @end example The exchange must share the password of the publication with the auditor. A -good @code{$NAME} relates to the auditor's business unit name. A secure tunnel +good @code{$NAME} relates to the auditor’s business unit name. A secure tunnel must be setup between the exchange and the auditor, for example using SSH or Wireguard. @@ -1458,7 +1458,7 @@ PostgreSQL configuration: wal_level= logical @end example -Next, the @code{postgres} user of the auditor's system must first initialize the +Next, the @code{postgres} user of the auditor’s system must first initialize the local tables: @example @@ -1474,7 +1474,7 @@ CONFIG = "postgres:///taler-ingress" $ taler-exchange-dbinit @end example -To complete the replication, the @code{postgres} user of the auditor's +To complete the replication, the @code{postgres} user of the auditor’s system must subscribe: @example @@ -1491,7 +1491,7 @@ For details, we refer to the PostgreSQL manual. Depending on the replication method used, the exchange may perform unexpected changes to the schema or perform @code{UPDATE}, @code{DELETE} or @code{DROP} operations on the tables. Hence, the auditor cannot rely upon the -exchange's primary copy to respect schema constraints, especially as we +exchange’s primary copy to respect schema constraints, especially as we have to presume that the exchange could act maliciously. Furthermore, it is unclear to what degree PostgreSQL database replication mechanisms are robust against a malicious master database. Thus, the auditor should @@ -1506,20 +1506,20 @@ process, from its actual operational data. Using @code{taler-auditor-sync} as the @code{sync} user, the auditor should -make a second "safe" copy of the exchange's ingres database. +make a second “safe” copy of the exchange’s ingres database. @code{taler-auditor-sync} basically reads from one exchange database and inserts all records found into a second exchange database. If the source database violates invariants, the tool halts with an error. This way, records violating invariants are never even copied, and in particular schema changes and -deletions or updates are not propagated into the auditor's production +deletions or updates are not propagated into the auditor’s production database. While @code{taler-auditor-sync} could in theory be run directly against the -exchange's production system, this is likely a bad idea due to the high +exchange’s production system, this is likely a bad idea due to the high latency from the network between auditor and exchange operator. Thus, we -recommend first making an "untrusted" ingress copy of the exchange's +recommend first making an “untrusted” ingress copy of the exchange’s production database using standard PostgreSQL tooling, and then using -@code{taler-auditor-sync} to create a second "safe" copy. The "safe" copy used +@code{taler-auditor-sync} to create a second “safe” copy. The “safe” copy used by the production system should also run under a different UID. Before @code{taler-auditor-sync} can be used, the target database must be @@ -1557,11 +1557,11 @@ $ taler-auditor-sync -s src.conf -d dst.cfg -t When the exchange performs garbage collection to @code{DELETE} obsolete records, this change should be automatically replicated to the auditors untrusted -ingress database. However, as @code{taler-auditor-sync} tries to be "safe", -it will not replicate those deletions to the auditor's production database. +ingress database. However, as @code{taler-auditor-sync} tries to be “safe”, +it will not replicate those deletions to the auditor’s production database. Thus, it is necessary to (occasonally) run @code{taler-exchange-dbinit -g} on -the auditor's production database to garbage collect old data in the -auditor's production copy. We note that this does not have to be done +the auditor’s production database to garbage collect old data in the +auditor’s production copy. We note that this does not have to be done at the same time when the exchange runs its garbage collection. @node Operation,Auditor implementation guide,Deployment,Top @@ -1587,7 +1587,7 @@ at the same time when the exchange runs its garbage collection. The @code{taler-auditor-httpd} runs the required REST API for the auditor. The service must have @code{INSERT} (and @code{SELECT}) rights on the -@code{deposit_confirmations} table in the auditor's database. We expect that in +@code{deposit_confirmations} table in the auditor’s database. We expect that in future versions additional rights may be required. For now, we recommend simply running the @code{taler-auditor-httpd} under the @@ -1637,7 +1637,7 @@ anymore), this is not recommended in a production setup. @section Reading the report -The auditor's report needs to be read carefully, as it includes +The auditor’s report needs to be read carefully, as it includes several categories of failures of different severity: @@ -1703,14 +1703,14 @@ completing a @code{taler-audit} run against the old schema @item migrating the exchange schema (@code{taler-exchange-dbinit}) of the master database, possibly the ingres database and the -auditor's production copy +auditor’s production copy @item migrating the auditor database (@code{taler-auditor-dbinit}) @item -resuming database replication between the exchange's master -database and the auditor's ingres copy +resuming database replication between the exchange’s master +database and the auditor’s ingres copy @item resuming @code{taler-auditor-sync} @@ -1755,7 +1755,7 @@ For more information, see Revocations in the exchange operator manual. If all denominations of an exchange are revoked, the exchange includes logic to wire back all returned funds to the bank accounts from which they originate. If some denominations remain operational, wallets will generally -exchange old coins of revoked denominations for new coins -- while providing +exchange old coins of revoked denominations for new coins – while providing additional information to demonstrate that these coins were not forged from the compromised private key but obtained via a legitimate withdraw operation. @@ -1764,12 +1764,12 @@ the compromised private key but obtained via a legitimate withdraw operation. @section Failures -Most audit failures are handled by the auditor's regular reporting functionality, +Most audit failures are handled by the auditor’s regular reporting functionality, creating a (hopefully descriptive) PDF report detailing the problems found. However, there is one category of errors where this is not possible, which -concerns arithmetic overflows for amounts. Taler's specification limits amount -values to at most 2^52. If, during the auditor's calculations, amounts are +concerns arithmetic overflows for amounts. Taler’s specification limits amount +values to at most 2^52. If, during the auditor’s calculations, amounts are encountered that exceed this threshold, the auditor will not generate a regular report, but instead write a log statement explaining where the problem happened and exit with a status code of `42'. @@ -1801,15 +1801,15 @@ The auditor implementation is split into five main processes, called @code{taler-helper-auditor-XXX}. The split was done to realize the principle of least privilege and to enable independent logic to be possibly run in parallel. Only the taler-wire-auditor must have (read-only) access to the -exchange's bank account, the other components only need access to the +exchange’s bank account, the other components only need access to the database. All auditor subsystems basically start their audit from a certain transaction index (@code{BIG SERIAL}) in the auditor database which identifies where the last audit concluded. They then check that the transactions claimed in the -exchange's database match up internally, including the cryptographic +exchange’s database match up internally, including the cryptographic signatures and also with respect to amounts adding up. The auditor also -calculates the exchange's profits and expected bank balances. Once all +calculates the exchange’s profits and expected bank balances. Once all existing transactions are processed, the auditor processes store the current checkpoint in its database and generate a JSON report. @@ -1818,22 +1818,22 @@ uses Jinja2 with a TeX template to convert the five individual JSON reports into LaTeX and then into PDF. @menu -* The auditor's database:: +* The auditor’s database:: * Invariants checked by the auditor:: * Testing the auditor:: @end menu -@node The auditor's database,Invariants checked by the auditor,,Auditor implementation guide +@node The auditor’s database,Invariants checked by the auditor,,Auditor implementation guide @anchor{taler-auditor-manual the-auditor-s-database}@anchor{3b} -@section The auditor's database +@section The auditor’s database The database scheme used by the exchange looks as follows: @image{taler-auditor-figures/auditor-db,,,,png} -@node Invariants checked by the auditor,Testing the auditor,The auditor's database,Auditor implementation guide +@node Invariants checked by the auditor,Testing the auditor,The auditor’s database,Auditor implementation guide @anchor{taler-auditor-manual invariants-checked-by-the-auditor}@anchor{3c} @section Invariants checked by the auditor @@ -1858,7 +1858,7 @@ pass where it might seem applicable. @subsection Invariants checked by the taler-helper-auditor-aggregation -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -1970,7 +1970,7 @@ wire fee unavailable for given time @subsection Invariants checked by the taler-helper-auditor-coins -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -1978,9 +1978,9 @@ CodeBlau reports the following checks: @item check that all denominations used by the exchange have been signed using -this auditor's key. All denominations encountered in the database that +this auditor’s key. All denominations encountered in the database that this auditor did not officially sign for are reported (but still included -in the audit as they obviously may impact the exchange's bank balance). +in the audit as they obviously may impact the exchange’s bank balance). Depending on the business situation, this may be normal (say if an exchange is changing auditors and newer denominations are no longer supported until their end-of-life by the current auditor). @@ -2076,7 +2076,7 @@ merchants by simply not reporting deposits to the auditor. @subsection Invariants checked by the taler-helper-auditor-reserves -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -2138,11 +2138,11 @@ target account does not match origin account This auditor is special in that it is the only pass that is required to have -`read-only' access to the exchange's bank account (privilege separation). Its -main role is to verify that the wire transfers in the exchange's database and +`read-only' access to the exchange’s bank account (privilege separation). Its +main role is to verify that the wire transfers in the exchange’s database and those reported by the bank are identical. -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -2204,7 +2204,7 @@ closing fee above total amount The main objective of the auditor is to detect inconsistencies. Thus, the @code{test-auditor.sh} script deliberately introduces various inconsistencies into -a synthetic exchange database. For this, an "normal" exchange database is +a synthetic exchange database. For this, an “normal” exchange database is first generated using the @code{taler-wallet-cli}. Then, various fields or rows of that database are manipulated, and the auditor is let loose on the modified database. Afterwards, the test verifies that the JSON contains values @@ -2217,13 +2217,13 @@ cover as many code paths as possible in both the exchange and the auditor. It should also ideally create all interesting possible variations of the exchange database fields (within the constraints of the database schema). -In general, @code{test-auditor.sh} runs the tests against an "old" database where +In general, @code{test-auditor.sh} runs the tests against an “old” database where some transactions are past the due-date (and hence the aggregator would trigger wire transfers), as well as a freshly generated exchange database where the auditor would not perform any transfers. Auditor interactions can be made before or after the aggregator, depending on what is being tested. -The current script also rudimentarily tests the auditor's resume logic, +The current script also rudimentarily tests the auditor’s resume logic, by re-starting the auditor once against a database that the auditor has already seen. diff --git a/texinfo/taler-developer-manual-figures/arch-api.png b/texinfo/taler-developer-manual-figures/arch-api.png Binary files differindex 9cedb108..9e593ab4 100644 --- a/texinfo/taler-developer-manual-figures/arch-api.png +++ b/texinfo/taler-developer-manual-figures/arch-api.png diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 5b4efdd2..6ee92df6 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.texi @@ -19,7 +19,7 @@ @copying @quotation -GNU Taler 0.9.0, Feb 10, 2024 +GNU Taler 0.9.0, Jan 06, 2024 GNU Taler team @@ -178,7 +178,8 @@ sending invoices or payments to other wallets. @item taler-merchant-demos: various demonstration services operated at -'demo.taler.net', including a simple shop and a donation page. +'demo.taler.net', including a simple shop, donation page and a +survey with reward functionality. @end itemize @end quotation @@ -691,6 +692,7 @@ SS = serial * Blog demo:: * Donation demo:: * Merchant SPA:: +* Survey/Rewards:: * P2P payments:: * Shutdown:: @@ -934,7 +936,7 @@ that the payment is requested again, instead of showing the previous fulfillment page. @end itemize -@node Merchant SPA,P2P payments,Donation demo,GNU Taler Demo Upgrade Checklist +@node Merchant SPA,Survey/Rewards,Donation demo,GNU Taler Demo Upgrade Checklist @anchor{taler-developer-manual merchant-spa}@anchor{1f} @subsection Merchant SPA @@ -1015,6 +1017,9 @@ fulfillment page. check displayed TOTP code matches TOTP app @item + create reserve for rewards + +@item do manual wire transfer in bank to establish reserve funding @item @@ -1042,8 +1047,24 @@ fulfillment page. check that orders are marked as completed @end itemize -@node P2P payments,Shutdown,Merchant SPA,GNU Taler Demo Upgrade Checklist -@anchor{taler-developer-manual p2p-payments}@anchor{20} +@node Survey/Rewards,P2P payments,Merchant SPA,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual survey-rewards}@anchor{20} +@subsection Survey/Rewards + + + +@itemize - + +@item + Visit @indicateurl{https://survey.demo.taler.net/} and receive a reward. + +@item + Verify that the survey stats page (@indicateurl{https://survey.demo.taler.net/survey-stats}) is working, +and that the survey reserve has sufficient funds. +@end itemize + +@node P2P payments,Shutdown,Survey/Rewards,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual p2p-payments}@anchor{21} @subsection P2P payments @@ -1073,7 +1094,7 @@ fulfillment page. @end itemize @node Shutdown,,P2P payments,GNU Taler Demo Upgrade Checklist -@anchor{taler-developer-manual shutdown}@anchor{21} +@anchor{taler-developer-manual shutdown}@anchor{22} @subsection Shutdown @@ -1109,7 +1130,7 @@ fulfillment page. @end itemize @node Environments and Builders on taler net,Releases,Demo Upgrade Procedure,Top -@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{22} +@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{23} @chapter Environments and Builders on taler.net @@ -1126,7 +1147,7 @@ fulfillment page. @end menu @node Buildbot implementation,Test builder,,Environments and Builders on taler net -@anchor{taler-developer-manual buildbot-implementation}@anchor{23} +@anchor{taler-developer-manual buildbot-implementation}@anchor{24} @section Buildbot implementation @@ -1171,7 +1192,7 @@ Create a worker from a shell account with this command: @code{buildbot-worker cr Then make sure there is a WORKER defined in master.cfg like: @code{worker.Worker("<username>", "<password>")} @node Test builder,Wallet builder,Buildbot implementation,Environments and Builders on taler net -@anchor{taler-developer-manual test-builder}@anchor{24} +@anchor{taler-developer-manual test-builder}@anchor{25} @section Test builder @@ -1193,7 +1214,7 @@ the mentioned unit file can be found at @code{deployment.git/systemd-services/} @end cartouche @node Wallet builder,Documentation Builder,Test builder,Environments and Builders on taler net -@anchor{taler-developer-manual wallet-builder}@anchor{25} +@anchor{taler-developer-manual wallet-builder}@anchor{26} @section Wallet builder @@ -1215,7 +1236,7 @@ the mentioned unit file can be found at @code{deployment.git/systemd-services/} @end cartouche @node Documentation Builder,Website Builder,Wallet builder,Environments and Builders on taler net -@anchor{taler-developer-manual documentation-builder}@anchor{26} +@anchor{taler-developer-manual documentation-builder}@anchor{27} @section Documentation Builder @@ -1237,7 +1258,7 @@ $ buildbot-worker start worker/ @end example @node Website Builder,Code coverage,Documentation Builder,Environments and Builders on taler net -@anchor{taler-developer-manual website-builder}@anchor{27} +@anchor{taler-developer-manual website-builder}@anchor{28} @section Website Builder @@ -1259,7 +1280,7 @@ $ buildbot-worker start worker/ @end example @node Code coverage,Producing auditor reports,Website Builder,Environments and Builders on taler net -@anchor{taler-developer-manual code-coverage}@anchor{28} +@anchor{taler-developer-manual code-coverage}@anchor{29} @section Code coverage @@ -1282,7 +1303,7 @@ $ buildbot-worker start worker/ The results are then published at @code{https://lcov.taler.net/}. @node Producing auditor reports,Database schema versioning,Code coverage,Environments and Builders on taler net -@anchor{taler-developer-manual producing-auditor-reports}@anchor{29} +@anchor{taler-developer-manual producing-auditor-reports}@anchor{2a} @section Producing auditor reports @@ -1303,7 +1324,7 @@ $ buildbot-worker start worker/ @end example @node Database schema versioning,,Producing auditor reports,Environments and Builders on taler net -@anchor{taler-developer-manual database-schema-versioning}@anchor{2a}@anchor{taler-developer-manual databaseversioning}@anchor{5} +@anchor{taler-developer-manual database-schema-versioning}@anchor{2b}@anchor{taler-developer-manual databaseversioning}@anchor{5} @section Database schema versioning @@ -1319,7 +1340,7 @@ Developers and operators MUST NOT make changes to database schema outside of this versioning. All tables of a GNU Taler component should live in their own schema. @node Releases,Continuous integration,Environments and Builders on taler net,Top -@anchor{taler-developer-manual releases}@anchor{2b} +@anchor{taler-developer-manual releases}@anchor{2c} @chapter Releases @@ -1336,7 +1357,7 @@ outside of this versioning. All tables of a GNU Taler component should live in @end menu @node GNU Taler Release Checklist,Release Process,,Releases -@anchor{taler-developer-manual gnu-taler-release-checklist}@anchor{2c} +@anchor{taler-developer-manual gnu-taler-release-checklist}@anchor{2d} @section GNU Taler Release Checklist @@ -1713,7 +1734,7 @@ Release announcement: @end itemize @node Release Process,Tagging,GNU Taler Release Checklist,Releases -@anchor{taler-developer-manual release-process}@anchor{2d} +@anchor{taler-developer-manual release-process}@anchor{2e} @section Release Process @@ -1748,7 +1769,7 @@ wallet-core (wallet-core.git) @end itemize @node Tagging,Database for tests,Release Process,Releases -@anchor{taler-developer-manual tagging}@anchor{2e} +@anchor{taler-developer-manual tagging}@anchor{2f} @section Tagging @@ -1760,7 +1781,7 @@ $ git push origin v0.1.0 @end example @node Database for tests,Exchange merchant,Tagging,Releases -@anchor{taler-developer-manual database-for-tests}@anchor{2f} +@anchor{taler-developer-manual database-for-tests}@anchor{30} @section Database for tests @@ -1777,7 +1798,7 @@ secured from unauthorized access. @end cartouche @node Exchange merchant,Wallet WebExtension,Database for tests,Releases -@anchor{taler-developer-manual exchange-merchant}@anchor{30} +@anchor{taler-developer-manual exchange-merchant}@anchor{31} @section Exchange, merchant @@ -1836,7 +1857,7 @@ $ make install check @end example @node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases -@anchor{taler-developer-manual wallet-webextension}@anchor{31} +@anchor{taler-developer-manual wallet-webextension}@anchor{32} @section Wallet WebExtension @@ -1850,7 +1871,7 @@ $ make dist @end example @node Upload to GNU mirrors,Creating Debian packages,Wallet WebExtension,Releases -@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{32} +@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{33} @section Upload to GNU mirrors @@ -1868,7 +1889,7 @@ symlink: taler-exchange-0.1.0.tar.gz taler-exchange-latest.tar.gz Upload the files in `binary mode' to the ftp servers. @node Creating Debian packages,,Upload to GNU mirrors,Releases -@anchor{taler-developer-manual creating-debian-packages}@anchor{33} +@anchor{taler-developer-manual creating-debian-packages}@anchor{34} @section Creating Debian packages @@ -1907,7 +1928,7 @@ Finally, make sure to clean up @code{~/incoming/} (by deleting the now imported @code{*.deb} files). @node Continuous integration,Internationalization,Releases,Top -@anchor{taler-developer-manual continuous-integration}@anchor{34} +@anchor{taler-developer-manual continuous-integration}@anchor{35} @chapter Continuous integration @@ -1925,7 +1946,7 @@ There is also the possibility to trigger builds manually, but this is only reserved to "admin" users. @node Internationalization,iOS Apps,Continuous integration,Top -@anchor{taler-developer-manual internationalization}@anchor{35} +@anchor{taler-developer-manual internationalization}@anchor{36} @chapter Internationalization @@ -1946,14 +1967,14 @@ At this time, this system is still very new for Taler.net and this documentation @end menu @node Who can Register,About Privilege Levels,,Internationalization -@anchor{taler-developer-manual who-can-register}@anchor{36} +@anchor{taler-developer-manual who-can-register}@anchor{37} @section Who can Register At this time, anyone can register an account at @indicateurl{https://weblate.taler.net/} to create translations. Registered users default to the `Users' and `Viewers' privilege level. @node About Privilege Levels,Upgrading Privileges,Who can Register,Internationalization -@anchor{taler-developer-manual about-privilege-levels}@anchor{37} +@anchor{taler-developer-manual about-privilege-levels}@anchor{38} @section About Privilege Levels @@ -1976,21 +1997,21 @@ This is the breakdown of privilege levels in Weblate: @end itemize @node Upgrading Privileges,How to Create a Project,About Privilege Levels,Internationalization -@anchor{taler-developer-manual upgrading-privileges}@anchor{38} +@anchor{taler-developer-manual upgrading-privileges}@anchor{39} @section Upgrading Privileges To upgrade from `Users'/`Viewers', a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck. @node How to Create a Project,How to Create a Component,Upgrading Privileges,Internationalization -@anchor{taler-developer-manual how-to-create-a-project}@anchor{39} +@anchor{taler-developer-manual how-to-create-a-project}@anchor{3a} @section How to Create a Project The `GNU Taler' project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created. @node How to Create a Component,How to Create a Translation,How to Create a Project,Internationalization -@anchor{taler-developer-manual how-to-create-a-component}@anchor{3a} +@anchor{taler-developer-manual how-to-create-a-component}@anchor{3b} @section How to Create a Component @@ -2030,7 +2051,7 @@ Under `https://weblate.taler.net/create/component/vcs/': @end itemize @node How to Create a Translation,Translation Standards and Practices,How to Create a Component,Internationalization -@anchor{taler-developer-manual how-to-create-a-translation}@anchor{3b} +@anchor{taler-developer-manual how-to-create-a-translation}@anchor{3c} @section How to Create a Translation @@ -2049,7 +2070,7 @@ Under `https://weblate.taler.net/create/component/vcs/': You may also wish to refer to @indicateurl{https://docs.weblate.org/} . @node Translation Standards and Practices,GPG Signing of Translations,How to Create a Translation,Internationalization -@anchor{taler-developer-manual translation-standards-and-practices}@anchor{3c} +@anchor{taler-developer-manual translation-standards-and-practices}@anchor{3d} @section Translation Standards and Practices @@ -2060,7 +2081,7 @@ When asked, set the license to GPLv3 or later. Set commit/push to manual only. @node GPG Signing of Translations,,Translation Standards and Practices,Internationalization -@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{3d} +@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{3e} @section GPG Signing of Translations @@ -2069,7 +2090,7 @@ weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F26 This means that contributions made through weblate will not be signed with the individual contributor's key when they are checked into the Git repository, but with the weblate key. @node iOS Apps,Android Apps,Internationalization,Top -@anchor{taler-developer-manual ios-apps}@anchor{3e} +@anchor{taler-developer-manual ios-apps}@anchor{3f} @chapter iOS Apps @@ -2079,7 +2100,7 @@ This means that contributions made through weblate will not be signed with the i @end menu @node Building Taler Wallet for iOS from source,,,iOS Apps -@anchor{taler-developer-manual build-ios-from-source}@anchor{3f}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{40} +@anchor{taler-developer-manual build-ios-from-source}@anchor{40}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{41} @section Building Taler Wallet for iOS from source @@ -2093,7 +2114,7 @@ the official Git repository@footnote{https://git.taler.net/taler-ios.git}. @end menu @node Compatibility,Building,,Building Taler Wallet for iOS from source -@anchor{taler-developer-manual compatibility}@anchor{41} +@anchor{taler-developer-manual compatibility}@anchor{42} @subsection Compatibility @@ -2101,7 +2122,7 @@ The minimum version of iOS supported is 15.0. This app runs on all iPhone models at least as new as the iPhone 6S. @node Building,,Compatibility,Building Taler Wallet for iOS from source -@anchor{taler-developer-manual building}@anchor{42} +@anchor{taler-developer-manual building}@anchor{43} @subsection Building @@ -2133,7 +2154,7 @@ there - all needed libraries and frameworks will be built automatically from Taler.xcworkspace. @node Android Apps,Code Coverage,iOS Apps,Top -@anchor{taler-developer-manual android-apps}@anchor{43} +@anchor{taler-developer-manual android-apps}@anchor{44} @chapter Android Apps @@ -2146,7 +2167,7 @@ Taler.xcworkspace. @end menu @node Android App Nightly Builds,Building apps from source,,Android Apps -@anchor{taler-developer-manual android-app-nightly-builds}@anchor{44} +@anchor{taler-developer-manual android-app-nightly-builds}@anchor{45} @section Android App Nightly Builds @@ -2197,7 +2218,7 @@ Use at your own risk! @end cartouche @node Building apps from source,Update translations,Android App Nightly Builds,Android Apps -@anchor{taler-developer-manual build-apps-from-source}@anchor{45}@anchor{taler-developer-manual building-apps-from-source}@anchor{46} +@anchor{taler-developer-manual build-apps-from-source}@anchor{46}@anchor{taler-developer-manual building-apps-from-source}@anchor{47} @section Building apps from source @@ -2283,7 +2304,7 @@ After the build finished successfully, you will find your APK in @code{merchant-terminal/build/outputs/apk/release/}. @node Update translations,Release process,Building apps from source,Android Apps -@anchor{taler-developer-manual update-translations}@anchor{47} +@anchor{taler-developer-manual update-translations}@anchor{48} @section Update translations @@ -2317,7 +2338,7 @@ Afterwards, build the entire project from source and test the UI to ensure that no erroneous translations (missing placeholders) are breaking things. @node Release process,,Update translations,Android Apps -@anchor{taler-developer-manual id1}@anchor{48} +@anchor{taler-developer-manual id1}@anchor{49} @section Release process @@ -2348,7 +2369,7 @@ $ git tag -s $APP-$VERSION @end menu @node F-Droid,Google Play,,Release process -@anchor{taler-developer-manual id2}@anchor{49} +@anchor{taler-developer-manual id2}@anchor{4a} @subsection F-Droid @@ -2372,7 +2393,7 @@ PoS: [metadata@footnote{https://gitlab.com/fdroid/fdroiddata/-/blob/master/metad @end itemize @node Google Play,,F-Droid,Release process -@anchor{taler-developer-manual google-play}@anchor{4a} +@anchor{taler-developer-manual google-play}@anchor{4b} @subsection Google Play @@ -2394,7 +2415,7 @@ All uploads are going to the beta track by default. These can be promoted to production later or immediately after upload if you feel daring. @node Code Coverage,Coding Conventions,Android Apps,Top -@anchor{taler-developer-manual id3}@anchor{4b}@anchor{taler-developer-manual id4}@anchor{4c} +@anchor{taler-developer-manual id3}@anchor{4c}@anchor{taler-developer-manual id4}@anchor{4d} @chapter Code Coverage @@ -2404,7 +2425,7 @@ nightly (once a day) by a Buildbot worker. The coverage results are then published at @indicateurl{https://lcov.taler.net/} . @node Coding Conventions,Testing library,Code Coverage,Top -@anchor{taler-developer-manual coding-conventions}@anchor{4d} +@anchor{taler-developer-manual coding-conventions}@anchor{4e} @chapter Coding Conventions @@ -2421,7 +2442,7 @@ GNU Taler is developed primarily in C, Kotlin, Python, Swift and TypeScript. @end menu @node Components written in C,Shell Scripts,,Coding Conventions -@anchor{taler-developer-manual components-written-in-c}@anchor{4e} +@anchor{taler-developer-manual components-written-in-c}@anchor{4f} @section Components written in C @@ -2441,7 +2462,7 @@ by the GNUnet style: @indicateurl{https://docs.gnunet.org/handbook/gnunet.html#C @end menu @node Naming conventions,,,Components written in C -@anchor{taler-developer-manual naming-conventions}@anchor{4f} +@anchor{taler-developer-manual naming-conventions}@anchor{50} @subsection Naming conventions @@ -2602,7 +2623,7 @@ must be called "perf_module-under-test_case-description.c" @end itemize @node Shell Scripts,Kotlin,Components written in C,Coding Conventions -@anchor{taler-developer-manual shell-scripts}@anchor{50} +@anchor{taler-developer-manual shell-scripts}@anchor{51} @section Shell Scripts @@ -2629,7 +2650,7 @@ $ set -eu @end example @node Kotlin,Python,Shell Scripts,Coding Conventions -@anchor{taler-developer-manual kotlin}@anchor{51} +@anchor{taler-developer-manual kotlin}@anchor{52} @section Kotlin @@ -2637,7 +2658,7 @@ We so far have no specific guidelines, please follow best practices for the language. @node Python,Swift,Kotlin,Coding Conventions -@anchor{taler-developer-manual python}@anchor{52} +@anchor{taler-developer-manual python}@anchor{53} @section Python @@ -2649,14 +2670,14 @@ for the language. @end menu @node Supported Python Versions,Style,,Python -@anchor{taler-developer-manual supported-python-versions}@anchor{53} +@anchor{taler-developer-manual supported-python-versions}@anchor{54} @subsection Supported Python Versions Python code should be written and build against version 3.7 of Python. @node Style,Python for Scripting,Supported Python Versions,Python -@anchor{taler-developer-manual style}@anchor{54} +@anchor{taler-developer-manual style}@anchor{55} @subsection Style @@ -2666,7 +2687,7 @@ A reusable yapf style file can be found in @code{build-common}, which is intended to be used as a git submodule. @node Python for Scripting,,Style,Python -@anchor{taler-developer-manual python-for-scripting}@anchor{55} +@anchor{taler-developer-manual python-for-scripting}@anchor{56} @subsection Python for Scripting @@ -2688,21 +2709,21 @@ over the older APIs. @end itemize @node Swift,TypeScript,Python,Coding Conventions -@anchor{taler-developer-manual swift}@anchor{56} +@anchor{taler-developer-manual swift}@anchor{57} @section Swift Please follow best practices for the language. @node TypeScript,,Swift,Coding Conventions -@anchor{taler-developer-manual typescript}@anchor{57} +@anchor{taler-developer-manual typescript}@anchor{58} @section TypeScript Please follow best practices for the language. @node Testing library,User-Facing Terminology,Coding Conventions,Top -@anchor{taler-developer-manual testing-library}@anchor{58} +@anchor{taler-developer-manual testing-library}@anchor{59} @chapter Testing library @@ -2775,7 +2796,7 @@ Please refer to the Twister codebase (under the @code{test} directory) in order to see how to configure it. @node User-Facing Terminology,Developer Glossary,Testing library,Top -@anchor{taler-developer-manual user-facing-terminology}@anchor{59} +@anchor{taler-developer-manual user-facing-terminology}@anchor{5a} @chapter User-Facing Terminology @@ -2789,7 +2810,7 @@ used in the user interface and help materials. @end menu @node Terms to Avoid,Terms to Use,,User-Facing Terminology -@anchor{taler-developer-manual terms-to-avoid}@anchor{5a} +@anchor{taler-developer-manual terms-to-avoid}@anchor{5b} @section Terms to Avoid @@ -2865,7 +2886,7 @@ with their payment. Can also be something like a donation receipt. @end table @node Terms to Use,,Terms to Avoid,User-Facing Terminology -@anchor{taler-developer-manual terms-to-use}@anchor{5b} +@anchor{taler-developer-manual terms-to-use}@anchor{5c} @section Terms to Use @@ -2917,7 +2938,7 @@ and payments. @end table @node Developer Glossary,Developer Tools,User-Facing Terminology,Top -@anchor{taler-developer-manual developer-glossary}@anchor{5c} +@anchor{taler-developer-manual developer-glossary}@anchor{5d} @chapter Developer Glossary @@ -2926,137 +2947,137 @@ use when talking to end users or even system administrators. @table @asis -@anchor{taler-developer-manual term-absolute-time}@anchor{5d} +@anchor{taler-developer-manual term-absolute-time}@anchor{5e} @geindex absolute time @item absolute time -method of keeping time in @ref{5e,,GNUnet} where the time is represented +method of keeping time in @ref{5f,,GNUnet} where the time is represented as the number of microseconds since 1.1.1970 (UNIX epoch). Called -absolute time in contrast to @ref{5f,,relative time}. -@anchor{taler-developer-manual term-aggregate}@anchor{60} +absolute time in contrast to @ref{60,,relative time}. +@anchor{taler-developer-manual term-aggregate}@anchor{61} @geindex aggregate @item aggregate -the @ref{61,,exchange} combines multiple payments received by the -same @ref{62,,merchant} into one larger @ref{63,,wire transfer} to -the respective merchant's @ref{64,,bank} account -@anchor{taler-developer-manual term-auditor}@anchor{65} +the @ref{62,,exchange} combines multiple payments received by the +same @ref{63,,merchant} into one larger @ref{64,,wire transfer} to +the respective merchant's @ref{65,,bank} account +@anchor{taler-developer-manual term-auditor}@anchor{66} @geindex auditor @item auditor -trusted third party that verifies that the @ref{61,,exchange} is operating correctly -@anchor{taler-developer-manual term-bank}@anchor{64} +trusted third party that verifies that the @ref{62,,exchange} is operating correctly +@anchor{taler-developer-manual term-bank}@anchor{65} @geindex bank @item bank -traditional financial service provider who offers wire @ref{66,,transfers} between accounts -@anchor{taler-developer-manual term-buyer}@anchor{67} +traditional financial service provider who offers wire @ref{67,,transfers} between accounts +@anchor{taler-developer-manual term-buyer}@anchor{68} @geindex buyer @item buyer -individual in control of a Taler @ref{68,,wallet}, usually using it to -@ref{69,,spend} the @ref{6a,,coins} on @ref{6b,,contracts} (see also @ref{6c,,customer}). -@anchor{taler-developer-manual term-close}@anchor{6d} +individual in control of a Taler @ref{69,,wallet}, usually using it to +@ref{6a,,spend} the @ref{6b,,coins} on @ref{6c,,contracts} (see also @ref{6d,,customer}). +@anchor{taler-developer-manual term-close}@anchor{6e} @geindex close -@item close@anchor{taler-developer-manual term-closes}@anchor{6e} +@item close@anchor{taler-developer-manual term-closes}@anchor{6f} @geindex closes -@itemx closes@anchor{taler-developer-manual term-closed}@anchor{6f} +@itemx closes@anchor{taler-developer-manual term-closed}@anchor{70} @geindex closed -@itemx closed@anchor{taler-developer-manual term-closing}@anchor{70} +@itemx closed@anchor{taler-developer-manual term-closing}@anchor{71} @geindex closing @itemx closing -operation an @ref{61,,exchange} performs on a @ref{71,,reserve} that has not been -@ref{72,,drained} by @ref{73,,withdraw} operations. When closing a reserve, the -exchange wires the remaining funds back to the customer, minus a @ref{74,,fee} +operation an @ref{62,,exchange} performs on a @ref{72,,reserve} that has not been +@ref{73,,drained} by @ref{74,,withdraw} operations. When closing a reserve, the +exchange wires the remaining funds back to the customer, minus a @ref{75,,fee} for closing -@anchor{taler-developer-manual term-coin}@anchor{75} +@anchor{taler-developer-manual term-coin}@anchor{76} @geindex coin -@item coin@anchor{taler-developer-manual term-coins}@anchor{6a} +@item coin@anchor{taler-developer-manual term-coins}@anchor{6b} @geindex coins @itemx coins -coins are individual token representing a certain amount of value, also known as the @ref{76,,denomination} of the coin -@anchor{taler-developer-manual term-commitment}@anchor{77} +coins are individual token representing a certain amount of value, also known as the @ref{77,,denomination} of the coin +@anchor{taler-developer-manual term-commitment}@anchor{78} @geindex commitment -@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{78} +@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{79} @geindex refresh commitment @itemx refresh commitment -data that the wallet commits to during the @ref{79,,melt} stage of the -@ref{7a,,refresh} protocol where it -has to prove to the @ref{61,,exchange} that it is deriving the @ref{7b,,fresh} +data that the wallet commits to during the @ref{7a,,melt} stage of the +@ref{7b,,refresh} protocol where it +has to prove to the @ref{62,,exchange} that it is deriving the @ref{7c,,fresh} coins as specified by the Taler protocol. The commitment is verified -probabilistically (see: @ref{7c,,kappa}) during the @ref{7d,,reveal} stage. -@anchor{taler-developer-manual term-contract}@anchor{7e} +probabilistically (see: @ref{7d,,kappa}) during the @ref{7e,,reveal} stage. +@anchor{taler-developer-manual term-contract}@anchor{7f} @geindex contract -@item contract@anchor{taler-developer-manual term-contracts}@anchor{6b} +@item contract@anchor{taler-developer-manual term-contracts}@anchor{6c} @geindex contracts @itemx contracts -formal agreement between @ref{62,,merchant} and @ref{6c,,customer} specifying the -@ref{7f,,contract terms} and signed by the merchant and the @ref{6a,,coins} of the +formal agreement between @ref{63,,merchant} and @ref{6d,,customer} specifying the +@ref{80,,contract terms} and signed by the merchant and the @ref{6b,,coins} of the customer -@anchor{taler-developer-manual term-contract-terms}@anchor{7f} +@anchor{taler-developer-manual term-contract-terms}@anchor{80} @geindex contract terms @item contract terms the individual clauses specifying what the buyer is purchasing from the -@ref{62,,merchant} -@anchor{taler-developer-manual term-customer}@anchor{6c} +@ref{63,,merchant} +@anchor{taler-developer-manual term-customer}@anchor{6d} @geindex customer @item customer individual that directs the buyer (perhaps the same individual) to make a purchase -@anchor{taler-developer-manual term-denomination}@anchor{76} +@anchor{taler-developer-manual term-denomination}@anchor{77} @geindex denomination @item denomination -unit of currency, specifies both the currency and the face value of a @ref{75,,coin}, +unit of currency, specifies both the currency and the face value of a @ref{76,,coin}, as well as associated fees and validity periods -@anchor{taler-developer-manual term-denomination-key}@anchor{80} +@anchor{taler-developer-manual term-denomination-key}@anchor{81} @geindex denomination key @item denomination key -(RSA) key used by the exchange to certify that a given @ref{75,,coin} is valid and of a -particular @ref{76,,denomination} -@anchor{taler-developer-manual term-deposit}@anchor{81} +(RSA) key used by the exchange to certify that a given @ref{76,,coin} is valid and of a +particular @ref{77,,denomination} +@anchor{taler-developer-manual term-deposit}@anchor{82} @geindex deposit -@item deposit@anchor{taler-developer-manual term-deposits}@anchor{82} +@item deposit@anchor{taler-developer-manual term-deposits}@anchor{83} @geindex deposits -@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{83} +@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{84} @geindex depositing @itemx depositing operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using an -@ref{60,,aggregate} @ref{63,,wire transfer} -@anchor{taler-developer-manual term-dirty}@anchor{84} +@ref{61,,aggregate} @ref{64,,wire transfer} +@anchor{taler-developer-manual term-dirty}@anchor{85} @geindex dirty -@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{85} +@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{86} @geindex dirty coin @itemx dirty coin @@ -3064,30 +3085,30 @@ exchange to credit his bank account in the future using an a coin is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin's owner if the coin is not refreshed -@anchor{taler-developer-manual term-drain}@anchor{86} +@anchor{taler-developer-manual term-drain}@anchor{87} @geindex drain -@item drain@anchor{taler-developer-manual term-drained}@anchor{72} +@item drain@anchor{taler-developer-manual term-drained}@anchor{73} @geindex drained @itemx drained -a @ref{71,,reserve} is being drained when a @ref{68,,wallet} is using the -reserve's private key to @ref{73,,withdraw} coins from it. This reduces +a @ref{72,,reserve} is being drained when a @ref{69,,wallet} is using the +reserve's private key to @ref{74,,withdraw} coins from it. This reduces the balance of the reserve. Once the balance reaches zero, we say that the reserve has been (fully) drained. Reserves that are not drained -(which is the normal process) are @ref{6f,,closed} by the exchange. -@anchor{taler-developer-manual term-exchange}@anchor{61} +(which is the normal process) are @ref{70,,closed} by the exchange. +@anchor{taler-developer-manual term-exchange}@anchor{62} @geindex exchange @item exchange Taler's payment service operator. Issues electronic coins during withdrawal and redeems them when they are deposited by merchants -@anchor{taler-developer-manual term-expired}@anchor{87} +@anchor{taler-developer-manual term-expired}@anchor{88} @geindex expired -@item expired@anchor{taler-developer-manual term-expiration}@anchor{88} +@item expired@anchor{taler-developer-manual term-expiration}@anchor{89} @geindex expiration @itemx expiration @@ -3101,47 +3122,47 @@ expiration, which specifies how long the exchange keeps records beyond the deposit expiration time. This latter expiration matters for legal disputes in courts and also creates an upper limit for refreshing operations on special zombie coin -@anchor{taler-developer-manual term-fakebank}@anchor{89} +@anchor{taler-developer-manual term-fakebank}@anchor{8a} @geindex fakebank @item fakebank -implementation of the @ref{64,,bank} API in memory to be used only for test +implementation of the @ref{65,,bank} API in memory to be used only for test cases. -@anchor{taler-developer-manual term-fee}@anchor{74} +@anchor{taler-developer-manual term-fee}@anchor{75} @geindex fee @item fee -an @ref{61,,exchange} charges various fees for its service. The different +an @ref{62,,exchange} charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for -@ref{8a,,withdrawing}, @ref{83,,depositing}, @ref{8b,,melting}, and -@ref{8c,,refunding}. Furthermore, there are fees per wire transfer -for @ref{70,,closing} a @ref{71,,reserve}: and for -@ref{60,,aggregate} @ref{8d,,wire transfers} to the @ref{62,,merchant}. -@anchor{taler-developer-manual term-fresh}@anchor{7b} +@ref{8b,,withdrawing}, @ref{84,,depositing}, @ref{8c,,melting}, and +@ref{8d,,refunding}. Furthermore, there are fees per wire transfer +for @ref{71,,closing} a @ref{72,,reserve}: and for +@ref{61,,aggregate} @ref{8e,,wire transfers} to the @ref{63,,merchant}. +@anchor{taler-developer-manual term-fresh}@anchor{7c} @geindex fresh -@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{8e} +@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{8f} @geindex fresh coin @itemx fresh coin a coin is fresh if its public key is only known to the customer -@anchor{taler-developer-manual term-GNUnet}@anchor{5e} +@anchor{taler-developer-manual term-GNUnet}@anchor{5f} @geindex GNUnet @item GNUnet Codebase of various libraries for a better Internet, some of which GNU Taler depends upon. -@anchor{taler-developer-manual term-json}@anchor{8f} +@anchor{taler-developer-manual term-json}@anchor{90} @geindex json -@item json@anchor{taler-developer-manual term-JSON}@anchor{90} +@item json@anchor{taler-developer-manual term-JSON}@anchor{91} @geindex JSON -@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{91} +@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{92} @geindex JavaScript Object Notation @itemx JavaScript Object Notation @@ -3149,192 +3170,192 @@ GNU Taler depends upon. serialization format derived from the JavaScript language which is commonly used in the Taler protocol as the payload of HTTP requests and responses. -@anchor{taler-developer-manual term-kappa}@anchor{7c} +@anchor{taler-developer-manual term-kappa}@anchor{7d} @geindex kappa @item kappa -security parameter used in the @ref{7a,,refresh} protocol. Defined to be 3. +security parameter used in the @ref{7b,,refresh} protocol. Defined to be 3. The probability of successfully evading the income transparency with the refresh protocol is 1:kappa. -@anchor{taler-developer-manual term-LibEuFin}@anchor{92} +@anchor{taler-developer-manual term-LibEuFin}@anchor{93} @geindex LibEuFin @item LibEuFin FIXME: explain -@anchor{taler-developer-manual term-link}@anchor{93} +@anchor{taler-developer-manual term-link}@anchor{94} @geindex link -@item link@anchor{taler-developer-manual term-linking}@anchor{94} +@item link@anchor{taler-developer-manual term-linking}@anchor{95} @geindex linking @itemx linking -specific step in the @ref{7a,,refresh} protocol that an exchange must offer -to prevent abuse of the @ref{7a,,refresh} mechanism. The link step is +specific step in the @ref{7b,,refresh} protocol that an exchange must offer +to prevent abuse of the @ref{7b,,refresh} mechanism. The link step is not needed in normal operation, it just must be offered. -@anchor{taler-developer-manual term-master-key}@anchor{95} +@anchor{taler-developer-manual term-master-key}@anchor{96} @geindex master key @item master key offline key used by the exchange to certify denomination keys and message signing keys -@anchor{taler-developer-manual term-melt}@anchor{79} +@anchor{taler-developer-manual term-melt}@anchor{7a} @geindex melt -@item melt@anchor{taler-developer-manual term-melted}@anchor{96} +@item melt@anchor{taler-developer-manual term-melted}@anchor{97} @geindex melted -@itemx melted@anchor{taler-developer-manual term-melting}@anchor{8b} +@itemx melted@anchor{taler-developer-manual term-melting}@anchor{8c} @geindex melting @itemx melting -step of the @ref{7a,,refresh} protocol where a @ref{85,,dirty coin} -is invalidated to be reborn @ref{7b,,fresh} in a subsequent -@ref{7d,,reveal} step. -@anchor{taler-developer-manual term-merchant}@anchor{62} +step of the @ref{7b,,refresh} protocol where a @ref{86,,dirty coin} +is invalidated to be reborn @ref{7c,,fresh} in a subsequent +@ref{7e,,reveal} step. +@anchor{taler-developer-manual term-merchant}@anchor{63} @geindex merchant @item merchant party receiving payments (usually in return for goods or services) -@anchor{taler-developer-manual term-message-signing-key}@anchor{97} +@anchor{taler-developer-manual term-message-signing-key}@anchor{98} @geindex message signing key @item message signing key key used by the exchange to sign online messages, other than coins -@anchor{taler-developer-manual term-order}@anchor{98} +@anchor{taler-developer-manual term-order}@anchor{99} @geindex order @item order offer made by the merchant to a wallet; pre-cursor to a contract where the wallet is not yet fixed. Turns -into a @ref{7e,,contract} when a wallet claims the order. -@anchor{taler-developer-manual term-owner}@anchor{99} +into a @ref{7f,,contract} when a wallet claims the order. +@anchor{taler-developer-manual term-owner}@anchor{9a} @geindex owner @item owner a coin is owned by the entity that knows the private key of the coin -@anchor{taler-developer-manual term-planchet}@anchor{9a} +@anchor{taler-developer-manual term-planchet}@anchor{9b} @geindex planchet @item planchet -precursor data for a @ref{75,,coin}. A planchet includes the coin's internal +precursor data for a @ref{76,,coin}. A planchet includes the coin's internal secrets (coin private key, blinding factor), but lacks the RSA signature -of the @ref{61,,exchange}. When @ref{8a,,withdrawing}, a @ref{68,,wallet} +of the @ref{62,,exchange}. When @ref{8b,,withdrawing}, a @ref{69,,wallet} creates and persists a planchet before asking the exchange to sign it to get the coin. -@anchor{taler-developer-manual term-privacy-policy}@anchor{9b} +@anchor{taler-developer-manual term-privacy-policy}@anchor{9c} @geindex privacy policy @item privacy policy Statement of an operator how they will protect the privacy of users. -@anchor{taler-developer-manual term-proof}@anchor{9c} +@anchor{taler-developer-manual term-proof}@anchor{9d} @geindex proof @item proof Message that cryptographically demonstrates that a particular claim is correct. -@anchor{taler-developer-manual term-proposal}@anchor{9d} +@anchor{taler-developer-manual term-proposal}@anchor{9e} @geindex proposal @item proposal -a list of @ref{7f,,contract terms} that has been completed and signed by the +a list of @ref{80,,contract terms} that has been completed and signed by the merchant backend. -@anchor{taler-developer-manual term-purchase}@anchor{9e} +@anchor{taler-developer-manual term-purchase}@anchor{9f} @geindex purchase @item purchase -Refers to the overall process of negotiating a @ref{7e,,contract} and then -making a payment with @ref{6a,,coins} to a @ref{62,,merchant}. -@anchor{taler-developer-manual term-recoup}@anchor{9f} +Refers to the overall process of negotiating a @ref{7f,,contract} and then +making a payment with @ref{6b,,coins} to a @ref{63,,merchant}. +@anchor{taler-developer-manual term-recoup}@anchor{a0} @geindex recoup @item recoup Operation by which an exchange returns the value of coins affected -by a @ref{a0,,revocation} to their @ref{99,,owner}, either by allowing the owner to -withdraw new coins or wiring funds back to the bank account of the @ref{99,,owner}. -@anchor{taler-developer-manual term-refresh}@anchor{7a} +by a @ref{a1,,revocation} to their @ref{9a,,owner}, either by allowing the owner to +withdraw new coins or wiring funds back to the bank account of the @ref{9a,,owner}. +@anchor{taler-developer-manual term-refresh}@anchor{7b} @geindex refresh -@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{a1} +@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{a2} @geindex refreshing @itemx refreshing -operation by which a @ref{85,,dirty coin} is converted into one or more -@ref{7b,,fresh} coins. Involves @ref{8b,,melting} the @ref{85,,dirty coin} and -then @ref{a2,,revealing} so-called @ref{a3,,transfer keys}. -@anchor{taler-developer-manual term-refund}@anchor{a4} +operation by which a @ref{86,,dirty coin} is converted into one or more +@ref{7c,,fresh} coins. Involves @ref{8c,,melting} the @ref{86,,dirty coin} and +then @ref{a3,,revealing} so-called @ref{a4,,transfer keys}. +@anchor{taler-developer-manual term-refund}@anchor{a5} @geindex refund -@item refund@anchor{taler-developer-manual term-refunding}@anchor{8c} +@item refund@anchor{taler-developer-manual term-refunding}@anchor{8d} @geindex refunding @itemx refunding operation by which a merchant steps back from the right to funds that he -obtained from a @ref{81,,deposit} operation, giving the right to the funds back +obtained from a @ref{82,,deposit} operation, giving the right to the funds back to the customer -@anchor{taler-developer-manual term-refund-transaction-id}@anchor{a5} +@anchor{taler-developer-manual term-refund-transaction-id}@anchor{a6} @geindex refund transaction id @item refund transaction id -unique number by which a merchant identifies a @ref{a4,,refund}. Needed +unique number by which a merchant identifies a @ref{a5,,refund}. Needed as refunds can be partial and thus there could be multiple refunds for -the same @ref{9e,,purchase}. -@anchor{taler-developer-manual term-relative-time}@anchor{5f} +the same @ref{9f,,purchase}. +@anchor{taler-developer-manual term-relative-time}@anchor{60} @geindex relative time @item relative time -method of keeping time in @ref{5e,,GNUnet} where the time is represented +method of keeping time in @ref{5f,,GNUnet} where the time is represented as a relative number of microseconds. Thus, a relative time specifies an offset or a duration, but not a date. Called relative time in -contrast to @ref{5d,,absolute time}. -@anchor{taler-developer-manual term-reserve}@anchor{71} +contrast to @ref{5e,,absolute time}. +@anchor{taler-developer-manual term-reserve}@anchor{72} @geindex reserve @item reserve accounting mechanism used by the exchange to track customer funds -from incoming @ref{8d,,wire transfers}. A reserve is created whenever +from incoming @ref{8e,,wire transfers}. A reserve is created whenever a customer wires money to the exchange using a well-formed public key -in the subject. The exchange then allows the customer's @ref{68,,wallet} -to @ref{73,,withdraw} up to the amount received in @ref{7b,,fresh} -@ref{6a,,coins} from the reserve, thereby draining the reserve. If a -reserve is not drained, the exchange eventually @ref{6e,,closes} it. +in the subject. The exchange then allows the customer's @ref{69,,wallet} +to @ref{74,,withdraw} up to the amount received in @ref{7c,,fresh} +@ref{6b,,coins} from the reserve, thereby draining the reserve. If a +reserve is not drained, the exchange eventually @ref{6f,,closes} it. Other definition: Funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange;s bank account to cover obligations from coins in circulation. -@anchor{taler-developer-manual term-reveal}@anchor{7d} +@anchor{taler-developer-manual term-reveal}@anchor{7e} @geindex reveal -@item reveal@anchor{taler-developer-manual term-revealing}@anchor{a2} +@item reveal@anchor{taler-developer-manual term-revealing}@anchor{a3} @geindex revealing @itemx revealing -step in the @ref{7a,,refresh} protocol where some of the transfer private +step in the @ref{7b,,refresh} protocol where some of the transfer private keys are revealed to prove honest behavior on the part of the wallet. -In the reveal step, the exchange returns the signed @ref{7b,,fresh} coins. -@anchor{taler-developer-manual term-revoke}@anchor{a6} +In the reveal step, the exchange returns the signed @ref{7c,,fresh} coins. +@anchor{taler-developer-manual term-revoke}@anchor{a7} @geindex revoke -@item revoke@anchor{taler-developer-manual term-revocation}@anchor{a0} +@item revoke@anchor{taler-developer-manual term-revocation}@anchor{a1} @geindex revocation @itemx revocation @@ -3343,109 +3364,109 @@ exceptional operation by which an exchange withdraws a denomination from circulation, either because the signing key was compromised or because the exchange is going out of operation; unspent coins of a revoked denomination are subjected to recoup. -@anchor{taler-developer-manual term-sharing}@anchor{a7} +@anchor{taler-developer-manual term-sharing}@anchor{a8} @geindex sharing @item sharing -users can share ownership of a @ref{75,,coin} by sharing access to the coin's +users can share ownership of a @ref{76,,coin} by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time. -@anchor{taler-developer-manual term-spend}@anchor{69} +@anchor{taler-developer-manual term-spend}@anchor{6a} @geindex spend -@item spend@anchor{taler-developer-manual term-spending}@anchor{a8} +@item spend@anchor{taler-developer-manual term-spending}@anchor{a9} @geindex spending @itemx spending operation by which a customer gives a merchant the right to deposit coins in return for merchandise -@anchor{taler-developer-manual term-terms}@anchor{a9} +@anchor{taler-developer-manual term-terms}@anchor{aa} @geindex terms @item terms the general terms of service of an operator, possibly including -the @ref{9b,,privacy policy}. Not to be confused with the -@ref{7f,,contract terms} which are about the specific purchase. -@anchor{taler-developer-manual term-transaction}@anchor{aa} +the @ref{9c,,privacy policy}. Not to be confused with the +@ref{80,,contract terms} which are about the specific purchase. +@anchor{taler-developer-manual term-transaction}@anchor{ab} @geindex transaction @item transaction method by which ownership is exclusively transferred from one entity -@anchor{taler-developer-manual term-transfer}@anchor{66} +@anchor{taler-developer-manual term-transfer}@anchor{67} @geindex transfer -@item transfer@anchor{taler-developer-manual term-transfers}@anchor{ab} +@item transfer@anchor{taler-developer-manual term-transfers}@anchor{ac} @geindex transfers -@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{63} +@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{64} @geindex wire transfer -@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{8d} +@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{8e} @geindex wire transfers @itemx wire transfers -method of sending funds between @ref{64,,bank} accounts -@anchor{taler-developer-manual term-transfer-key}@anchor{ac} +method of sending funds between @ref{65,,bank} accounts +@anchor{taler-developer-manual term-transfer-key}@anchor{ad} @geindex transfer key -@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{a3} +@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{a4} @geindex transfer keys @itemx transfer keys -special cryptographic key used in the @ref{7a,,refresh} protocol, some of which -are revealed during the @ref{7d,,reveal} step. Note that transfer keys have, -despite the name, no relationship to @ref{8d,,wire transfers}. They merely -help to transfer the value from a @ref{85,,dirty coin} to a @ref{8e,,fresh coin} -@anchor{taler-developer-manual term-user}@anchor{ad} +special cryptographic key used in the @ref{7b,,refresh} protocol, some of which +are revealed during the @ref{7e,,reveal} step. Note that transfer keys have, +despite the name, no relationship to @ref{8e,,wire transfers}. They merely +help to transfer the value from a @ref{86,,dirty coin} to a @ref{8f,,fresh coin} +@anchor{taler-developer-manual term-user}@anchor{ae} @geindex user @item user any individual using the Taler payment system -(see @ref{6c,,customer}, @ref{67,,buyer}, @ref{62,,merchant}). -@anchor{taler-developer-manual term-version}@anchor{ae} +(see @ref{6d,,customer}, @ref{68,,buyer}, @ref{63,,merchant}). +@anchor{taler-developer-manual term-version}@anchor{af} @geindex version @item version Taler uses various forms of versioning. There is a database schema version (stored itself in the database, see *-0000.sql) describing -the state of the table structure in the database of an @ref{61,,exchange}, -@ref{65,,auditor} or @ref{62,,merchant}. There is a protocol +the state of the table structure in the database of an @ref{62,,exchange}, +@ref{66,,auditor} or @ref{63,,merchant}. There is a protocol version (CURRENT:REVISION:AGE, see GNU libtool) which specifies -the network protocol spoken by an @ref{61,,exchange} or @ref{62,,merchant} +the network protocol spoken by an @ref{62,,exchange} or @ref{63,,merchant} including backwards-compatibility. And finally there is the software release version (MAJOR.MINOR.PATCH, see @indicateurl{https://semver.org/}) of the respective code base. -@anchor{taler-developer-manual term-wallet}@anchor{68} +@anchor{taler-developer-manual term-wallet}@anchor{69} @geindex wallet @item wallet software running on a customer's computer; withdraws, stores and spends coins -@anchor{taler-developer-manual term-WebExtension}@anchor{af} +@anchor{taler-developer-manual term-WebExtension}@anchor{b0} @geindex WebExtension @item WebExtension Cross-browser API used to implement the GNU Taler wallet browser extension. -@anchor{taler-developer-manual term-wire-gateway}@anchor{b0} +@anchor{taler-developer-manual term-wire-gateway}@anchor{b1} @geindex wire gateway @item wire gateway FIXME: explain -@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{b1} +@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{b2} @geindex wire transfer identifier -@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{b2} +@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{b3} @geindex wtid @itemx wtid @@ -3453,35 +3474,35 @@ FIXME: explain Subject of a wire transfer from the exchange to a merchant; set by the aggregator to a random nonce which uniquely identifies the transfer. -@anchor{taler-developer-manual term-withdraw}@anchor{73} +@anchor{taler-developer-manual term-withdraw}@anchor{74} @geindex withdraw -@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{8a} +@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{8b} @geindex withdrawing -@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{b3} +@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{b4} @geindex withdrawal @itemx withdrawal -operation by which a @ref{68,,wallet} can convert funds from a @ref{71,,reserve} to +operation by which a @ref{69,,wallet} can convert funds from a @ref{72,,reserve} to fresh coins -@anchor{taler-developer-manual term-zombie}@anchor{b4} +@anchor{taler-developer-manual term-zombie}@anchor{b5} @geindex zombie -@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{b5} +@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{b6} @geindex zombie coin @itemx zombie coin -coin where the respective @ref{80,,denomination key} is past its -@ref{81,,deposit} @ref{88,,expiration} time, but which is still (again) valid -for an operation because it was @ref{96,,melted} while it was still -valid, and then later again credited during a @ref{9f,,recoup} process +coin where the respective @ref{81,,denomination key} is past its +@ref{82,,deposit} @ref{89,,expiration} time, but which is still (again) valid +for an operation because it was @ref{97,,melted} while it was still +valid, and then later again credited during a @ref{a0,,recoup} process @end table @node Developer Tools,Index,Developer Glossary,Top -@anchor{taler-developer-manual developer-tools}@anchor{b6} +@anchor{taler-developer-manual developer-tools}@anchor{b7} @chapter Developer Tools @@ -3494,7 +3515,7 @@ developer. @end menu @node taler-harness,,,Developer Tools -@anchor{taler-developer-manual taler-harness}@anchor{b7} +@anchor{taler-developer-manual taler-harness}@anchor{b8} @section taler-harness diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi index b5b1084b..972da817 100644 --- a/texinfo/taler-exchange.texi +++ b/texinfo/taler-exchange.texi @@ -19,7 +19,7 @@ @copying @quotation -GNU Taler 0.9.0, Feb 10, 2024 +GNU Taler 0.9.0, Jan 06, 2024 GNU Taler team @@ -48,7 +48,7 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+) @anchor{taler-exchange-manual doc}@anchor{0} @c This file is part of GNU TALER. @c -@c Copyright (C) 2014-2024 Taler Systems SA +@c Copyright (C) 2014-2023 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the @c terms of the GNU Affero General Public License as published by the Free Software @@ -123,8 +123,18 @@ Basic Setup: Currency, Denominations and Keys Wire Gateway Setup +* Installation and Basic Configuration:: +* Connecting Nexus with an EBICS account:: * Exchange Bank Account Configuration:: +Connecting Nexus with an EBICS account + +* Testing; Requesting the transaction history: Testing Requesting the transaction history. +* Testing; Making payments: Testing Making payments. +* Automatic scheduling:: +* Creating a Taler facade:: +* Managing Permissions and Users:: + Legal Setup * Legal conditions for using the service:: @@ -1608,59 +1618,401 @@ configuration of the online machine: @chapter Wire Gateway Setup -The Taler Wire Gateway is an API that -connects the Taler exchange to the underlying core banking system. There are -several implementations of wire gateways: +The Taler Wire Gateway is an API that connects the Taler exchange to +the underlying core banking system. -@quotation +LibEuFin is an implementation of the Wire Gateway API for the EBICS protocol. +This section will walk through (1) installing and configuring LibEuFin and +(2) connecting the Taler Exchange to LibEuFin. +@menu +* Installation and Basic Configuration:: +* Connecting Nexus with an EBICS account:: +* Exchange Bank Account Configuration:: -@itemize * +@end menu -@item -Project deploymerization@footnote{https://git.taler.net/depolymerization.git} implements a wire gateway on top of Bitcoin or Ethereum +@node Installation and Basic Configuration,Connecting Nexus with an EBICS account,,Wire Gateway Setup +@anchor{taler-exchange-manual installation-and-basic-configuration}@anchor{22} +@section Installation and Basic Configuration -@item -The libeufin-bank provides a wire gateway interface on top of a regional currency bank -@item -The `taler-fakebank-run' command is an in-memory bank simulator with a wire gateway interface for testing -@end itemize +First, install the @code{libeufin} package. This can be done on the @code{exchange-online} +machine or a different one. + +@example +[root@@exchange-online]# apt-get install -y libeufin +@end example + +The main component of LibEuFin is called the Nexus. It implements a Web +service that provides a JSON abstraction layer to access bank accounts. + +The HTTP port and database connection string can be edited in the configuration: + + +@float LiteralBlock + +@caption{/etc/libeufin/nexus.env} + +@example +LIBEUFIN_NEXUS_PORT=5017 +LIBEUFIN_NEXUS_DB_CONNECTION=jdbc:sqlite:/var/lib/libeufin/nexus/nexus-db.sqlite3 +@end example + +@end float + + +After configuring the database, you can start the service. +The database is initialized automatically. + +@example +[root@@exchange-online]# systemctl enable libeufin-nexus +[root@@exchange-online]# systemctl start libeufin-nexus +@end example + +You can now create a superuser account. The command to +create the superuser needs direct database access, thus +the configuration file is sourced first, and the relevant +environment variable is exported. + +@example +[root@@exchange-online]# source /etc/libeufin/nexus.env +[root@@exchange-online]# export LIBEUFIN_NEXUS_DB_CONNECTION +[root@@exchange-online]# NEXUS_ADMIN_PW=$(tr -dc A-Za-z0-9 </dev/urandom | head -c 13) +[root@@exchange-online]# libeufin-nexus superuser admin --password $NEXUS_ADMIN_PW +@end example + +If you omit @code{--password $NEXUS_ADMIN_PW}, you will interactively be asked for a password. +For simplicity, a superuser can as well act as a normal user, but an API +to create less privileged users is offered. + +@cartouche +@quotation Note +User and permissions management in LibEuFin is still under development. +In particular, permissions for non-superusers are very limited at the moment. @end quotation +@end cartouche -@c FIXME :ref:`libeufin-nexus <libeufin-nexus>` is an implementation of the Wire Gateway API for the EBICS protocol. Add to list above once nexus implements the TWG directly! +@node Connecting Nexus with an EBICS account,Exchange Bank Account Configuration,Installation and Basic Configuration,Wire Gateway Setup +@anchor{taler-exchange-manual connecting-nexus-with-an-ebics-account}@anchor{23} +@section Connecting Nexus with an EBICS account -Before continuing, you need to decide which wire gateway you want to use, -and install and configure it on your system. Afterwards, you need to -have two key pieces of information from that setup: -@quotation +The command line interface of the LibEuFin Nexus needs the following three +values to be defined in the environment: @code{LIBEUFIN_NEXUS_URL}, +@code{LIBEUFIN_NEXUS_USERNAME}, and @code{LIBEUFIN_NEXUS_PASSWORD}. In this example, +@code{LIBEUFIN_NEXUS_USERNAME} should be set to @code{admin}, and +@code{LIBEUFIN_NEXUS_PASSWORD} to the value hold in @code{NEXUS_ADMIN_PW} from the +previous step (the @code{libeufin-nexus superuser} command). The +@code{LIBEUFIN_NEXUS_URL} could be given as @code{http://localhost:5017/}. +Next, we create a EBICS `bank connection' that Nexus can use to communicate with the bank. -@itemize * +@example +[root@@exchange-online]# libeufin-cli \ + connections \ + new-ebics-connection \ + --ebics-url $EBICS_BASE_URL \ + --host-id $EBICS_HOST_ID \ + --partner-id $EBICS_PARTNER_ID \ + --ebics-user-id $EBICS_USER_ID \ + $CONNECTION_NAME +@end example -@item -The username and password to access the exchange's account in the system. +If this step executes correctly, Nexus will have created all the cryptographic +material that is needed on the client side; in this EBICS example, it created +the signature and identification keys. It is therefore advisable to `make +a backup copy' of such keys. -@item -The @code{payto://} URI of that account (see RFC 8905@footnote{https://www.rfc-editor.org/rfc/rfc8905}). -@end itemize +@example +[root@@exchange-online]# libeufin-cli \ + connections \ + export-backup \ + --passphrase $SECRET \ + --output-file $BACKUP_FILE \ + $CONNECTION_NAME +@end example + +At this point, Nexus needs to both communicate its keys to the bank, and +download the bank's keys. This synchronization happens through the INI, HIA, and +finally, HPB message types. + +After the electronic synchronization, the subscriber must confirm their keys +by sending a physical mail to the bank. The following command helps generating +such letter: + +@example +[root@@exchange-online]# libeufin-cli connections get-key-letter $CONNECTION_NAME out.pdf +@end example + +@example +[root@@exchange-online]# libeufin-cli \ + connections \ + connect \ + $CONNECTION_NAME +@end example + +@c FIXME: Maybe is not 100% clear that 'connecting' means exchanging keys +@c with the bank? + +Once the connection is synchronized, Nexus needs to import locally the data +corresponding to the bank accounts offered by the bank connection just made. +The command below downloads the list of the bank accounts offered by @code{$CONNECTION_NAME}. + +@example +[root@@exchange-online]# libeufin-cli \ + connections \ + download-bank-accounts \ + $CONNECTION_NAME +@end example + +It is now possible to list the accounts offered by the connection. + +@example +[root@@exchange-online]# libeufin-cli \ + connections \ + list-offered-bank-accounts \ + $CONNECTION_NAME +@end example + +@cartouche +@quotation Note +The @code{nexusBankAccountId} field should at this step be @code{null}, +as we have not yet imported the bank account and thus the account +does not yet have a local name. @end quotation +@end cartouche + +Nexus now needs an explicit import of the accounts it should manage. This +step is needed to let the user pick a custom name for such accounts. + +@example +[root@@exchange-online]# libeufin-cli \ + connections \ + import-bank-account \ + --offered-account-id testacct01 \ + --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \ + $CONNECTION_NAME +@end example + +Once a Nexus user imported a bank account (@code{$LOCAL_ACCOUNT_NAME}) +under a certain connection (@code{$CONNECTION_NAME}), it is possible +to accomplish the usual operations for any bank account: asking for the +list of transactions, and making a payment. @menu -* Exchange Bank Account Configuration:: +* Testing; Requesting the transaction history: Testing Requesting the transaction history. +* Testing; Making payments: Testing Making payments. +* Automatic scheduling:: +* Creating a Taler facade:: +* Managing Permissions and Users:: @end menu -@node Exchange Bank Account Configuration,,,Wire Gateway Setup -@anchor{taler-exchange-manual exchange-bank-account-configuration}@anchor{22}@anchor{taler-exchange-manual id3}@anchor{23} +@node Testing Requesting the transaction history,Testing Making payments,,Connecting Nexus with an EBICS account +@anchor{taler-exchange-manual testing-requesting-the-transaction-history}@anchor{24} +@subsection Testing: Requesting the transaction history + + +The LibEuFin Nexus keeps a local copy of the bank account's transaction +history. Before querying transactions locally, it is necessary +to request transactions for the bank account via the bank connection. + +This command asks Nexus to download the latest transaction reports/statements +through the bank connection: + +@example +[root@@exchange-online]# libeufin-cli accounts fetch-transactions $LOCAL_ACCOUNT_NAME +@end example + +@cartouche +@quotation Note +By default, the latest available transactions are fetched. It is also +possible to specify a custom date range (or even all available transactions) +and the type of transactions to fetch (inter-day statements or intra-day +reports). +@end quotation +@end cartouche + +@c FIXME: Possibly the date range filter is still missing, see #6243. + +Once Nexus has stored all the information in the database, the +client can ask to actually see the transactions: + +@example +[root@@exchange-online]# libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME +@end example + +@node Testing Making payments,Automatic scheduling,Testing Requesting the transaction history,Connecting Nexus with an EBICS account +@anchor{taler-exchange-manual testing-making-payments}@anchor{25} +@subsection Testing: Making payments + + +Payments pass through two phases: preparation and submission. The preparation +phase assigns the payment initiation a unique ID, which prevents accidental +double submissions of payments in case of network failures or other +disruptions. + +The following command prepares a payment: + +@example +[root@@exchange-online]# libeufin-cli accounts prepare-payment \ + --creditor-iban=$IBAN_TO_SEND_MONEY_TO \ + --creditor-bic=$BIC_TO_SEND_MONEY_TO \ + --creditor-name=$CREDITOR_NAME \ + --payment-amount=$AMOUNT \ + --payment-subject=$SUBJECT \ + $LOCAL_ACCOUNT_NAME +@end example + +Note: the @code{$AMOUNT} value needs the format @code{X.Y:CURRENCY}; for example +@code{EUR:10}, or @code{EUR:1.01}. + +The previous command should return a value (@code{$UUID}) that uniquely +identifies the prepared payment in the Nexus system. That is needed +in the next step, to `send the payment instructions to the bank': + +@example +[root@@exchange-online]# libeufin-cli accounts submit-payments \ + --payment-uuid $UUID \ + $LOCAL_ACCOUNT_NAME +@end example + +@node Automatic scheduling,Creating a Taler facade,Testing Making payments,Connecting Nexus with an EBICS account +@anchor{taler-exchange-manual automatic-scheduling}@anchor{26} +@subsection Automatic scheduling + + +With an EBICS bank connection, the LibEuFin Nexus needs to regularly query for +new transactions and (re-)submit prepared payments. + +It is possible to schedule these tasks via an external task scheduler such as +cron(8). However, the nexus also has an internal task scheduling mechanism for +accounts. + +The following three commands create a schedule for submitting payments hourly, +fetching transactions (intra-day reports) every 5 minutes, and (inter-day statements) +once at 11pm every day: + +@example +[root@@exchange-online]# libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \ + --task-type="submit" \ + --task-name='submit-payments-hourly' \ + --task-cronspec='0 0 *' + +[root@@exchange-online]# libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \ + --task-type="fetch" \ + --task-name='fetch-5min' \ + --task-cronspec='0 */5 *' \ + --task-param-level=report \ + --task-param-range-type=latest + +[root@@exchange-online]# libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \ + --task-type="fetch" \ + --task-name='fetch-daily' \ + --task-cronspec='0 0 23' \ + --task-param-level=statement \ + --task-param-range-type=latest +@end example + +The cronspec has the following format, which is slightly non-standard due to +the @code{SECONDS} field + +@example +SECONDS MINUTES HOURS DAY-OF-MONTH[optional] MONTH[optional] DAY-OF-WEEK[optional] +@end example + +@node Creating a Taler facade,Managing Permissions and Users,Automatic scheduling,Connecting Nexus with an EBICS account +@anchor{taler-exchange-manual creating-a-taler-facade}@anchor{27} +@subsection Creating a Taler facade + + +Facades are additional abstraction layers that can serve +specific purposes. For example, one application might need +a filtered version of the transaction history, or it might +want to refuse payments that do not conform to certain rules. + +At this moment, only the `Taler facade type' is implemented +in the Nexus, and the command below instantiates one under a +existing bank account / connection pair. You can freely +assign an identifier for the @code{$FACADE_NAME} below: + +@example +[root@@exchange-online]# libeufin-cli facades new-taler-wire-gateway-facade \ + --currency EUR \ + --facade-name $FACADE_NAME \ + $CONNECTION_NAME \ + $LOCAL_ACCOUNT_NAME +@end example + +At this point, the additional taler-wire-gateway API +becomes offered by the Nexus. The purpose is to let a Taler exchange rely on +Nexus to manage its bank account. + +The base URL of the facade that can be used by the Taler exchange +as the Taler Wire Gateway base URL can be seen by listing the facades: + +@example +[root@@exchange-online]# libeufin-cli facades list +@end example + +@node Managing Permissions and Users,,Creating a Taler facade,Connecting Nexus with an EBICS account +@anchor{taler-exchange-manual managing-permissions-and-users}@anchor{28} +@subsection Managing Permissions and Users + + +This guide has so far assumed that a superuser is accessing the LibEuFin Nexus. +However, it is advisable that the Nexus is accessed with users that only have a +minimal set of permissions. + +The Nexus currently only has support for giving non-superusers access to Taler +wire gateway facades. + +To create a new user, use the @code{users} subcommand of the CLI: + +@example +[root@@exchange-online]# libeufin-cli users list +# [ ... shows available users ... ] + +[root@@exchange-online]# libeufin-cli users create $USERNAME +# [ ... will prompt for password ... ] +@end example + +Permissions are managed with the @code{permissions} subcommand. +The following commands grant permissions to view the transaction history +and create payment initiations with a Taler wire gateway facade: + +@example +[root@@exchange-online]# libeufin-cli permissions grant \ + user $USERNAME \ + facade $FACADENAME \ + facade.talerwiregateway.history + +[root@@exchange-online]# libeufin-cli permissions grant \ + user $USERNAME \ + facade $FACADENAME \ + facade.talerwiregateway.transfer +@end example + +@c FIXME: The two commands above output an empty JSON object +@c when successful. Possibly, we should suppress that (just like +@c the other commands do). + +The list of all granted permissions can be reviewed: + +@example +[root@@exchange-online]# libeufin-cli permissions list +@end example + +@node Exchange Bank Account Configuration,,Connecting Nexus with an EBICS account,Wire Gateway Setup +@anchor{taler-exchange-manual bank-account}@anchor{29}@anchor{taler-exchange-manual exchange-bank-account-configuration}@anchor{2a} @section Exchange Bank Account Configuration An exchange must be configured with the right settings to access its bank -account via a Taler wire gateway. An -exchange can be configured to use multiple bank accounts by using multiple -wire gateways. Typically only one wire gateway is used. +account via a Taler Wire Gateway. An exchange can be configured to use +multiple bank accounts by using multiple Wire Gateways. Typically only one +Wire Gateway is used. To configure a bank account in Taler, we need to furnish two pieces of information: @@ -1675,8 +2027,8 @@ account. Examples for such URIs include an IBAN or @code{payto://x-taler-bank/localhost:8080/2} for the 2nd bank account a the Taler bank demonstrator running at @code{localhost} on port 8080. -The first part of the URI following @code{payto://} (@code{iban} or -@code{x-taler-bank}) is called the wire method. +The first part of the URI following @code{payto://} (“iban” or +“x-taler-bank”) is called the wire method. @item The @code{taler-exchange-wirewatch} and @code{taler-exchange-transfer} @@ -1686,22 +2038,20 @@ authentication information is currently a username and password for HTTP basic authentication. @end itemize -Each Taler wire gateway is configured in a configuration section that follows -the pattern @code{exchange-account-$id}, where @code{$id} is an internal identifier -for the bank account accessed by the exchange. The basic information for an +A Taler Wire Gateway is configured in a configuration section that follows the +pattern @code{exchange-account-$id}, where @code{$id} is an internal identifier for +the bank account accessed by the exchange. The basic information for an account should be put in @code{/etc/taler/conf.d/exchange-business.conf}. The secret credentials to access the Taler Wire Gateway API should be put into a corresponding @code{exchange-accountcredentials-$id} section in @code{/etc/taler/secrets/exchange-accountcredentials.conf}. The latter file -should be only readable for the @code{taler-exchange-wire} user. Only the -@code{taler-exchange-wirewatch} and @code{taler-exchange-transfer} services should -run as the @code{taler-exchange-wire} user. Other exchange processes do not need -to have access to the account credentials. +should already be only readable for the @code{taler-exchange-wire} user. Other +exchange processes should not have access to this information. You can configure multiple accounts for an exchange by creating sections -starting with @code{exchange-account-} for the section name. You must specify -@code{ENABLE_}-settings for each account whether it should be used, and for what -(incoming or outgoing wire transfers): +starting with “exchange-account-” for the section name. You can ENABLE for +each account whether it should be used, and for what (incoming or outgoing +wire transfers): @float LiteralBlock @@ -1745,18 +2095,18 @@ ENABLE_CREDIT = YES # LibEuFin expects basic auth. WIRE_GATEWAY_AUTH_METHOD = basic -# Username and password to access the Taler wire gateway. +# Username and password set in LibEuFin. USERNAME = ... PASSWORD = ... -# Base URL of the Taler wire gateway. +# Base URL of the wire gateway set up with LibEuFin. WIRE_GATEWAY_URL = ... @end example @end float -Such a wire gateway configuration can be tested with the following commands: +Such a Wire Gateway configuration can be tested with the following commands: @example [root@@exchange-online]# taler-exchange-wire-gateway-client \ @@ -1765,11 +2115,8 @@ Such a wire gateway configuration can be tested with the following commands: --section exchange-accountcredentials-1 --credit-history @end example -On success, you will see some of your account's transaction history (or an -empty history), while on failure you should see an error message. - @node Legal Setup,KYC Configuration,Wire Gateway Setup,Top -@anchor{taler-exchange-manual legal-setup}@anchor{24}@anchor{taler-exchange-manual legalsetup}@anchor{25} +@anchor{taler-exchange-manual legal-setup}@anchor{2b}@anchor{taler-exchange-manual legalsetup}@anchor{2c} @chapter Legal Setup @@ -1789,7 +2136,7 @@ legal requirements can safely skip these steps. @end menu @node Legal conditions for using the service,Terms of Service,,Legal Setup -@anchor{taler-exchange-manual legal-conditions-for-using-the-service}@anchor{26} +@anchor{taler-exchange-manual legal-conditions-for-using-the-service}@anchor{2d} @section Legal conditions for using the service @@ -1815,7 +2162,7 @@ user in various languages and various formats. This section describes how to setup and configure the legal conditions. @node Terms of Service,Privacy Policy,Legal conditions for using the service,Legal Setup -@anchor{taler-exchange-manual terms-of-service}@anchor{27} +@anchor{taler-exchange-manual terms-of-service}@anchor{2e} @section Terms of Service @@ -1846,7 +2193,7 @@ process. @end itemize @node Privacy Policy,Legal policies directory layout,Terms of Service,Legal Setup -@anchor{taler-exchange-manual privacy-policy}@anchor{28} +@anchor{taler-exchange-manual privacy-policy}@anchor{2f} @section Privacy Policy @@ -1877,7 +2224,7 @@ process. @end itemize @node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Legal Setup -@anchor{taler-exchange-manual legal-policies-directory-layout}@anchor{29} +@anchor{taler-exchange-manual legal-policies-directory-layout}@anchor{30} @section Legal policies directory layout @@ -1902,7 +2249,7 @@ the service may show a warning on startup. @end menu @node Example,,,Legal policies directory layout -@anchor{taler-exchange-manual example}@anchor{2a} +@anchor{taler-exchange-manual example}@anchor{31} @subsection Example @@ -1947,7 +2294,7 @@ If the user requests an HTML format with language preferences "fr" followed by French. @node Generating the Legal Terms,Adding translations,Legal policies directory layout,Legal Setup -@anchor{taler-exchange-manual generating-the-legal-terms}@anchor{2b} +@anchor{taler-exchange-manual generating-the-legal-terms}@anchor{32} @section Generating the Legal Terms @@ -1975,7 +2322,7 @@ languages (initially only English) in @code{$PREFIX/share/terms/}. The generato has a few options which are documented in its man page. @node Adding translations,Updating legal documents,Generating the Legal Terms,Legal Setup -@anchor{taler-exchange-manual adding-translations}@anchor{2c} +@anchor{taler-exchange-manual adding-translations}@anchor{33} @section Adding translations @@ -2010,7 +2357,7 @@ You must restart the service whenever adding or updating legal documents or thei @end cartouche @node Updating legal documents,,Adding translations,Legal Setup -@anchor{taler-exchange-manual updating-legal-documents}@anchor{2d} +@anchor{taler-exchange-manual updating-legal-documents}@anchor{34} @section Updating legal documents @@ -2028,7 +2375,7 @@ forget to update the @code{ETAG} configuration option to the new name and to restart the service. @node KYC Configuration,Deployment,Legal Setup,Top -@anchor{taler-exchange-manual kyc-configuration}@anchor{2e} +@anchor{taler-exchange-manual kyc-configuration}@anchor{35} @chapter KYC Configuration @@ -2056,7 +2403,7 @@ Wallet receives money via P2P payments over a threshold Merchant receives money over a threshold @item -Reserve is "opened" for invoicing (`planned feature') +Reserve is "opened" for invoicing or rewards (`planned feature') @end itemize @end quotation @@ -2079,7 +2426,7 @@ request should then succeed. @end menu @node Taler KYC Terminology,KYC Configuration Options,,KYC Configuration -@anchor{taler-exchange-manual taler-kyc-terminology}@anchor{2f} +@anchor{taler-exchange-manual taler-kyc-terminology}@anchor{36} @section Taler KYC Terminology @@ -2131,7 +2478,7 @@ implementing the respective API. @end itemize @node KYC Configuration Options,OAuth 2 0 specifics,Taler KYC Terminology,KYC Configuration -@anchor{taler-exchange-manual kyc-configuration-options}@anchor{30} +@anchor{taler-exchange-manual kyc-configuration-options}@anchor{37} @section KYC Configuration Options @@ -2203,7 +2550,7 @@ TIMEFRAME = 30d @node OAuth 2 0 specifics,Persona specifics,KYC Configuration Options,KYC Configuration -@anchor{taler-exchange-manual oauth-2-0-specifics}@anchor{31} +@anchor{taler-exchange-manual oauth-2-0-specifics}@anchor{38} @section OAuth 2.0 specifics @@ -2284,7 +2631,7 @@ configuration above and an exchange running on the host @code{https://exchange.example.com/kyc-proof/kyc-provider-challenger-oauth2/}. @node Persona specifics,KYC AID specifics,OAuth 2 0 specifics,KYC Configuration -@anchor{taler-exchange-manual persona-specifics}@anchor{32} +@anchor{taler-exchange-manual persona-specifics}@anchor{39} @section Persona specifics @@ -2352,7 +2699,7 @@ in JSON) expected by the exchange. The script will need to be adjusted based on the attributes collected by the specific template. @node KYC AID specifics,,Persona specifics,KYC Configuration -@anchor{taler-exchange-manual kyc-aid-specifics}@anchor{33} +@anchor{taler-exchange-manual kyc-aid-specifics}@anchor{3a} @section KYC AID specifics @@ -2399,7 +2746,7 @@ need to be adjusted based on the attributes collected by the specific template. @node Deployment,Offline Signing Setup Key Maintenance and Tear-Down,KYC Configuration,Top -@anchor{taler-exchange-manual deployment}@anchor{34}@anchor{taler-exchange-manual id4}@anchor{35} +@anchor{taler-exchange-manual deployment}@anchor{3b}@anchor{taler-exchange-manual id3}@anchor{3c} @chapter Deployment @@ -2414,7 +2761,7 @@ and configuration are completed. @end menu @node Serving,Reverse Proxy Setup,,Deployment -@anchor{taler-exchange-manual id5}@anchor{36}@anchor{taler-exchange-manual serving}@anchor{37} +@anchor{taler-exchange-manual id4}@anchor{3d}@anchor{taler-exchange-manual serving}@anchor{3e} @section Serving @@ -2450,7 +2797,7 @@ the group under which the exchange HTTP server is running. @end itemize @node Reverse Proxy Setup,Launching an exchange,Serving,Deployment -@anchor{taler-exchange-manual reverse-proxy-setup}@anchor{38}@anchor{taler-exchange-manual reverseproxy}@anchor{39} +@anchor{taler-exchange-manual reverse-proxy-setup}@anchor{3f}@anchor{taler-exchange-manual reverseproxy}@anchor{40} @section Reverse Proxy Setup @@ -2498,7 +2845,7 @@ With this last step, we are finally ready to launch the main exchange process. @node Launching an exchange,,Reverse Proxy Setup,Deployment -@anchor{taler-exchange-manual launch}@anchor{3a}@anchor{taler-exchange-manual launching-an-exchange}@anchor{3b} +@anchor{taler-exchange-manual launch}@anchor{41}@anchor{taler-exchange-manual launching-an-exchange}@anchor{42} @section Launching an exchange @@ -2598,7 +2945,7 @@ The request might take some time to complete on slow machines, because a lot of key material will be generated. @node Offline Signing Setup Key Maintenance and Tear-Down,AML Configuration,Deployment,Top -@anchor{taler-exchange-manual offline-signing-setup-key-maintenance-and-tear-down}@anchor{3c} +@anchor{taler-exchange-manual offline-signing-setup-key-maintenance-and-tear-down}@anchor{43} @chapter Offline Signing Setup, Key Maintenance and Tear-Down @@ -2661,7 +3008,7 @@ The following sections will discuss these steps in more depth. @end menu @node Signing the online signing keys,Account signing,,Offline Signing Setup Key Maintenance and Tear-Down -@anchor{taler-exchange-manual keys-generation}@anchor{3d}@anchor{taler-exchange-manual signing-the-online-signing-keys}@anchor{3e} +@anchor{taler-exchange-manual keys-generation}@anchor{44}@anchor{taler-exchange-manual signing-the-online-signing-keys}@anchor{45} @section Signing the online signing keys @@ -2703,7 +3050,7 @@ periodically, as it signs the various online signing keys of the exchange which periodically expire. @node Account signing,Wire fee structure,Signing the online signing keys,Offline Signing Setup Key Maintenance and Tear-Down -@anchor{taler-exchange-manual account-signing}@anchor{3f}@anchor{taler-exchange-manual exchange-account-signing}@anchor{40} +@anchor{taler-exchange-manual account-signing}@anchor{46} @section Account signing @@ -2712,7 +3059,7 @@ The @code{enable-account} step is important to must be used to sign the correct address to wire funds to. Note that for each bank account, additional options `must' be set in the configuration file to tell the exchange how to access the bank account. The offline tool `only' configures the externally -visible portions of the setup. The chapter on bank account configuration@footnote{_exchange-bank-account-configuration} has further details. +visible portions of the setup. The chapter on Bank account@footnote{_Bank-account} configuration has further details. taler-exchange-offline accepts additional options to configure the use of the account. For example, additional options can be used to add currency @@ -2729,7 +3076,7 @@ For details on optional @code{enable-account} arguments, see manpages/taler-exchange-offline.1. @node Wire fee structure,Auditor configuration,Account signing,Offline Signing Setup Key Maintenance and Tear-Down -@anchor{taler-exchange-manual id6}@anchor{41}@anchor{taler-exchange-manual wire-fee-structure}@anchor{42} +@anchor{taler-exchange-manual id6}@anchor{47}@anchor{taler-exchange-manual wire-fee-structure}@anchor{48} @section Wire fee structure @@ -2766,7 +3113,7 @@ this maintenance activity! @end cartouche @node Auditor configuration,Revocations,Wire fee structure,Offline Signing Setup Key Maintenance and Tear-Down -@anchor{taler-exchange-manual auditor-configuration}@anchor{43}@anchor{taler-exchange-manual id7}@anchor{44} +@anchor{taler-exchange-manual auditor-configuration}@anchor{49}@anchor{taler-exchange-manual id7}@anchor{4a} @section Auditor configuration @@ -2794,7 +3141,7 @@ As before, the `auditor.json' file must then be copied from the offline system to a system connected to the exchange and there @code{uploaded} to the exchange using @code{taler-exchange-offline upload}. @node Revocations,,Auditor configuration,Offline Signing Setup Key Maintenance and Tear-Down -@anchor{taler-exchange-manual id8}@anchor{45}@anchor{taler-exchange-manual revocations}@anchor{46} +@anchor{taler-exchange-manual id8}@anchor{4b}@anchor{taler-exchange-manual revocations}@anchor{4c} @section Revocations @@ -2827,7 +3174,7 @@ operation. @end cartouche @node AML Configuration,Setup Linting,Offline Signing Setup Key Maintenance and Tear-Down,Top -@anchor{taler-exchange-manual aml-configuration}@anchor{47} +@anchor{taler-exchange-manual aml-configuration}@anchor{4d} @chapter AML Configuration @@ -2847,7 +3194,7 @@ amount above which a further AML review is triggered. @end menu @node AML Officer Setup,AML Triggers,,AML Configuration -@anchor{taler-exchange-manual aml-officer-setup}@anchor{48} +@anchor{taler-exchange-manual aml-officer-setup}@anchor{4e} @section AML Officer Setup @@ -2883,7 +3230,7 @@ Access rights can be revoked at any time using: @end example @node AML Triggers,AML Forms,AML Officer Setup,AML Configuration -@anchor{taler-exchange-manual aml-triggers}@anchor{49} +@anchor{taler-exchange-manual aml-triggers}@anchor{4f} @section AML Triggers @@ -2935,7 +3282,7 @@ its default value of '[/usr/bin/]true'. To flag all new users for manual review, simply set the program to '[/usr/bin/]false'. @node AML Forms,,AML Triggers,AML Configuration -@anchor{taler-exchange-manual aml-forms}@anchor{4a} +@anchor{taler-exchange-manual aml-forms}@anchor{50} @section AML Forms @@ -2978,7 +3325,7 @@ from @code{https://git.taler.net/wallet-core.git/}, compile and copy the file from the @code{dist/prod}. @node Setup Linting,Testing and Troubleshooting,AML Configuration,Top -@anchor{taler-exchange-manual setup-linting}@anchor{4b} +@anchor{taler-exchange-manual setup-linting}@anchor{51} @chapter Setup Linting @@ -2995,7 +3342,7 @@ You can optionally pass the @code{--debug} option to get more verbose output, an failed. @node Testing and Troubleshooting,Benchmarking,Setup Linting,Top -@anchor{taler-exchange-manual testing-and-troubleshooting}@anchor{4c} +@anchor{taler-exchange-manual testing-and-troubleshooting}@anchor{52} @chapter Testing and Troubleshooting @@ -3102,12 +3449,12 @@ taler-wallet. @end menu @node taler-config,Using taler-config,,Testing and Troubleshooting -@anchor{taler-exchange-manual taler-config}@anchor{4d} +@anchor{taler-exchange-manual taler-config}@anchor{53} @section taler-config @node Using taler-config,Private key storage,taler-config,Testing and Troubleshooting -@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{4e}@anchor{taler-exchange-manual using-taler-config}@anchor{4f} +@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{54}@anchor{taler-exchange-manual using-taler-config}@anchor{55} @section Using taler-config @@ -3161,7 +3508,7 @@ While the configuration file is typically located at GNU Taler component using the @code{-c} option. @node Private key storage,Internal audits,Using taler-config,Testing and Troubleshooting -@anchor{taler-exchange-manual private-key-storage}@anchor{50} +@anchor{taler-exchange-manual private-key-storage}@anchor{56} @section Private key storage @@ -3173,7 +3520,7 @@ regenerated. However, we do recommend using RAID (1+1 or 1+1+1) for all disks of the system. @node Internal audits,Database Scheme,Private key storage,Testing and Troubleshooting -@anchor{taler-exchange-manual internal-audit}@anchor{51}@anchor{taler-exchange-manual internal-audits}@anchor{52} +@anchor{taler-exchange-manual internal-audit}@anchor{57}@anchor{taler-exchange-manual internal-audits}@anchor{58} @section Internal audits @@ -3201,7 +3548,7 @@ from the very beginning, this is generally not recommended as this may be too expensive. @node Database Scheme,Database upgrades,Internal audits,Testing and Troubleshooting -@anchor{taler-exchange-manual database-scheme}@anchor{53}@anchor{taler-exchange-manual id9}@anchor{54} +@anchor{taler-exchange-manual database-scheme}@anchor{59}@anchor{taler-exchange-manual id9}@anchor{5a} @section Database Scheme @@ -3217,7 +3564,7 @@ The database scheme used by the exchange looks as follows: @image{taler-exchange-figures/exchange-db,,,,png} @node Database upgrades,,Database Scheme,Testing and Troubleshooting -@anchor{taler-exchange-manual database-upgrades}@anchor{55}@anchor{taler-exchange-manual id10}@anchor{56} +@anchor{taler-exchange-manual database-upgrades}@anchor{5b}@anchor{taler-exchange-manual id10}@anchor{5c} @section Database upgrades @@ -3255,7 +3602,7 @@ not be performed in a production system. You still also need to then grant the permissions to the other exchange processes again. @node Benchmarking,FIXMEs,Testing and Troubleshooting,Top -@anchor{taler-exchange-manual benchmarking}@anchor{57}@anchor{taler-exchange-manual exchangebenchmarking}@anchor{58} +@anchor{taler-exchange-manual benchmarking}@anchor{5d}@anchor{taler-exchange-manual exchangebenchmarking}@anchor{5e} @chapter Benchmarking @@ -3295,7 +3642,7 @@ some options that are determined at runtime by the setup logic provided by @end menu @node Choosing a bank,taler-bank-benchmark,,Benchmarking -@anchor{taler-exchange-manual benchmark-choose-bank}@anchor{59}@anchor{taler-exchange-manual choosing-a-bank}@anchor{5a} +@anchor{taler-exchange-manual benchmark-choose-bank}@anchor{5f}@anchor{taler-exchange-manual choosing-a-bank}@anchor{60} @section Choosing a bank @@ -3333,7 +3680,7 @@ $ taler-unified-setup.sh -emwt -c $CONF -ns -u exchange-account-2 @end example @node taler-bank-benchmark,taler-exchange-benchmark,Choosing a bank,Benchmarking -@anchor{taler-exchange-manual taler-bank-benchmark}@anchor{5b} +@anchor{taler-exchange-manual taler-bank-benchmark}@anchor{61} @section taler-bank-benchmark @@ -3360,7 +3707,7 @@ Exchange's account with the respective reserve public key as wire subject. Processing is then handled by `parallel' (@code{-P}) service workers. @node taler-exchange-benchmark,taler-aggregator-benchmark,taler-bank-benchmark,Benchmarking -@anchor{taler-exchange-manual taler-exchange-benchmark}@anchor{5c} +@anchor{taler-exchange-manual taler-exchange-benchmark}@anchor{62} @section taler-exchange-benchmark @@ -3398,7 +3745,7 @@ repetitions (i.e. if the operation failed the first time), total execution time (operating system and user space) and other details. @node taler-aggregator-benchmark,,taler-exchange-benchmark,Benchmarking -@anchor{taler-exchange-manual taler-aggregator-benchmark}@anchor{5d} +@anchor{taler-exchange-manual taler-aggregator-benchmark}@anchor{63} @section taler-aggregator-benchmark @@ -3421,7 +3768,7 @@ time a single aggregator process in @code{--test} mode (asking it to terminate as soon as there is no more pending work). @node FIXMEs,Index,Benchmarking,Top -@anchor{taler-exchange-manual fixmes}@anchor{5e} +@anchor{taler-exchange-manual fixmes}@anchor{64} @chapter FIXMEs diff --git a/texinfo/taler-merchant-api-tutorial-figures/arch-api.png b/texinfo/taler-merchant-api-tutorial-figures/arch-api.png Binary files differindex 9cedb108..9e593ab4 100644 --- a/texinfo/taler-merchant-api-tutorial-figures/arch-api.png +++ b/texinfo/taler-merchant-api-tutorial-figures/arch-api.png diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi index fdc0b16a..33970265 100644 --- a/texinfo/taler-merchant-api-tutorial.texi +++ b/texinfo/taler-merchant-api-tutorial.texi @@ -19,7 +19,7 @@ @copying @quotation -GNU Taler 0.9.0, Feb 10, 2024 +GNU Taler 0.9.0, Jan 06, 2024 GNU Taler team @@ -69,6 +69,7 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+) * Merchant Payment Processing:: * Giving Refunds:: * Repurchase detection and fulfillment URLs:: +* Giving Customers Rewards:: * Advanced topics:: * Index:: @@ -157,6 +158,11 @@ that accepts donations for software projects and gives donation receipts. @item +The +survey@footnote{https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/survey} +that gives users who answer a question a small reward. + +@item The WooCommerce plugin@footnote{https://git.taler.net/gnu-taler-payment-for-woocommerce.git/} which is a comprehensive integration into a Web shop including the refund business process. @@ -449,7 +455,7 @@ the merchant’s obligations under the contract. @cartouche @quotation Note You do not need to keep querying to notice changes -to the order's transaction status. The endpoints +to the order’s transaction status. The endpoints support long polling, simply specify a @code{timeout_ms} query parameter with how long you want to wait at most for the order status to change to @code{paid}. @@ -525,7 +531,7 @@ under the @code{h_contract} field. @geindex repurchase -@node Repurchase detection and fulfillment URLs,Advanced topics,Giving Refunds,Top +@node Repurchase detection and fulfillment URLs,Giving Customers Rewards,Giving Refunds,Top @anchor{taler-merchant-api-tutorial repurchase}@anchor{10}@anchor{taler-merchant-api-tutorial repurchase-detection-and-fulfillment-urls}@anchor{11} @chapter Repurchase detection and fulfillment URLs @@ -547,8 +553,8 @@ from the QR code). The merchant backend then updates the session ID of the existing order to the current session ID of the browser. When the payment status for the -"new" unpaid order is checked (or already in long-polling), the backend -detects that for the browser's `session ID' and `fulfillment URL' there is an +“new” unpaid order is checked (or already in long-polling), the backend +detects that for the browser’s `session ID' and `fulfillment URL' there is an existing paid contract. It then tells the browser to immediately redirect to the fulfillment URL where the already paid article is available. @@ -565,9 +571,75 @@ also `only' done for HTTP(S) fulfillment URLs. In particular, this means fulfillment URIs like @code{taler://fulfillment-success/$MESSAGE} are not considered to identify a resource you can pay for and thus do not have to be unique. +@anchor{taler-merchant-api-tutorial giving-customers-rewards}@anchor{12} +@geindex rewards + +@node Giving Customers Rewards,Advanced topics,Repurchase detection and fulfillment URLs,Top +@anchor{taler-merchant-api-tutorial id3}@anchor{13} +@chapter Giving Customers Rewards + + +GNU Taler allows Web sites to grant digital cash directly to a visitor. The +idea is that some sites may want incentivize actions such as filling out a +survey or trying a new feature. It is important to note that receiving rewards is +not enforceable for the visitor, as there is no contract. It is simply a +voluntary gesture of appreciation of the site to its visitor. However, once a +reward has been granted, the visitor obtains full control over the funds provided +by the site. + +The merchant backend of the site must be properly configured for rewards, and +sufficient funds must be made available for rewards. See the Taler User +Guide for details. + +To check if rewards are configured properly and if there are sufficient +funds available for granting rewards, query the @code{/private/reserves} endpoint: + +@example +>>> import requests +>>> requests.get("https://backend.demo.taler.net/private/reserves", +... headers=@{"Authorization": "Bearer secret-token:sandbox"@}) +<Response [200]> +@end example + +Check that a reserve exists where the @code{merchant_initial_amount} is below the +@code{committed_amount} and that the reserve is @code{active}. +@anchor{taler-merchant-api-tutorial authorize-reward}@anchor{14} +To authorize a reward, @code{POST} to @code{/private/rewards}. The following fields +are recognized in the JSON request object: + + +@itemize - -@node Advanced topics,Index,Repurchase detection and fulfillment URLs,Top -@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{12}@anchor{taler-merchant-api-tutorial id3}@anchor{13} +@item +@code{amount}: Amount that should be given to the visitor as a reward. + +@item +@code{justification}: Description of why the reward was granted. Human-readable +text not exposed to the customer, but used by the Back Office. + +@item +@code{next_url}: The URL that the user’s browser should be redirected to by +the wallet, once the reward has been processed. +@end itemize + +The response from the backend contains a @code{taler_reward_url}. The +customer’s browser must be redirected to this URL for the wallet to pick +up the reward. +@anchor{taler-merchant-api-tutorial pick-up-reward}@anchor{15} +This code snipped illustrates giving a reward: + +@example +>>> import requests +>>> reward_req = dict(amount="KUDOS:0.5", +... justification="User filled out survey", +... next_url="https://merchant.com/thanks.html") +>>> requests.post("https://backend.demo.taler.net/private/rewards", json=reward_req, +... headers=@{"Authorization": "Bearer secret-token:sandbox"@}) +<Response [200]> +@end example + +@node Advanced topics,Index,Giving Customers Rewards,Top +@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{16}@anchor{taler-merchant-api-tutorial id4}@anchor{17} @chapter Advanced topics @@ -579,7 +651,7 @@ unique. @end menu @node Session-Bound Payments,Product Identification,,Advanced topics -@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{14}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{15} +@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{18}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{19} @section Session-Bound Payments @@ -616,7 +688,7 @@ receipt is in the user’s wallet is also available as @code{last_session_id} in the response to @code{/check-payment}. @node Product Identification,The Taler Order Format,Session-Bound Payments,Advanced topics -@anchor{taler-merchant-api-tutorial id4}@anchor{16}@anchor{taler-merchant-api-tutorial product-identification}@anchor{17} +@anchor{taler-merchant-api-tutorial id5}@anchor{1a}@anchor{taler-merchant-api-tutorial product-identification}@anchor{1b} @section Product Identification @@ -637,7 +709,7 @@ contract with the same @code{resource_url} before, and if so replay the previous payment. @node The Taler Order Format,,Product Identification,Advanced topics -@anchor{taler-merchant-api-tutorial id5}@anchor{18}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{19} +@anchor{taler-merchant-api-tutorial id6}@anchor{1c}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1d} @section The Taler Order Format @@ -948,8 +1020,8 @@ render fields that they do not understand as a key-value list. @printindex ge -@anchor{c}@w{ } @anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ } +@anchor{c}@w{ } @c %**end of body @bye diff --git a/texinfo/taler-merchant-figures/arch-api.png b/texinfo/taler-merchant-figures/arch-api.png Binary files differindex 9cedb108..9e593ab4 100644 --- a/texinfo/taler-merchant-figures/arch-api.png +++ b/texinfo/taler-merchant-figures/arch-api.png diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi index 88e858c2..acef0f99 100644 --- a/texinfo/taler-merchant.texi +++ b/texinfo/taler-merchant.texi @@ -19,7 +19,7 @@ @copying @quotation -GNU Taler 0.9.0, Feb 10, 2024 +GNU Taler 0.9.0, Jan 06, 2024 GNU Taler team @@ -67,10 +67,8 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+) * Introduction:: * Terminology:: * Installation:: -* How to configure the merchant backend:: +* How to configure the merchant’s backend:: * Instance setup:: -* Instance account setup:: -* Manually creating an order using the SPA:: * Secure setup:: * Customization:: * Upgrade procedure:: @@ -93,19 +91,18 @@ Terminology * Instance Bank Accounts:: * Inventory:: * Orders and Contracts:: -* Templates:: -* OTP Devices:: * Transfers:: -* Webhooks:: +* Rewards:: +* Reserves:: Installation +* Installing from source:: * Installing the GNU Taler binary packages on Debian:: * Installing the GNU Taler binary packages on Trisquel:: * Installing the GNU Taler binary packages on Ubuntu:: -* Installing from source:: -How to configure the merchant backend +How to configure the merchant’s backend * Configuration format:: * Backend options:: @@ -121,11 +118,8 @@ Backend options Instance setup -* Instance setup with the SPA:: -* Instance setup without the Web interface:: - -Instance account setup - +* Setup without the Web interface:: +* Accounts:: * Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. * Automatic Settlement Data Import:: @@ -340,10 +334,9 @@ This chapter describes some of the key concepts used throughout the manual. * Instance Bank Accounts:: * Inventory:: * Orders and Contracts:: -* Templates:: -* OTP Devices:: * Transfers:: -* Webhooks:: +* Rewards:: +* Reserves:: @end menu @@ -381,11 +374,11 @@ merchant backend and the bearer token is equivalent to a passphrase. @end quotation @node Instance Bank Accounts,Inventory,Instances,Terminology -@anchor{taler-merchant-manual instance-bank-account}@anchor{c}@anchor{taler-merchant-manual instance-bank-accounts}@anchor{d} +@anchor{taler-merchant-manual instance-bank-accounts}@anchor{c} @section Instance Bank Accounts -@geindex Bank account +@geindex instance-bank-account To receive payments, an instance must have configured one or more bank `accounts'. When configuring the bank account of an instance, one should @@ -398,7 +391,7 @@ This documentation exclusively uses the term `account' for the bank accounts of a merchant or shop that may be associated with an instance. @node Inventory,Orders and Contracts,Instance Bank Accounts,Terminology -@anchor{taler-merchant-manual inventory}@anchor{e} +@anchor{taler-merchant-manual inventory}@anchor{d} @section Inventory @@ -428,8 +421,8 @@ can also override prices of products in the inventory or set a total price for an order that is different from the price of the sum of the products in the order. -@node Orders and Contracts,Templates,Inventory,Terminology -@anchor{taler-merchant-manual orders-and-contracts}@anchor{f} +@node Orders and Contracts,Transfers,Inventory,Terminology +@anchor{taler-merchant-manual orders-and-contracts}@anchor{e} @section Orders and Contracts @@ -501,61 +494,8 @@ main legal reason is typically to provide tax records in case of a tax audit. After the `legal expiration' (by default: a decade), contract information is deleted when running the garbage collector using @code{taler-merchant-dbinit}. -@node Templates,OTP Devices,Orders and Contracts,Terminology -@anchor{taler-merchant-manual template}@anchor{10}@anchor{taler-merchant-manual templates}@anchor{11} -@section Templates - - -@geindex Template - -Usually, a merchant must use an authenticated endpoint to create an order and -then share the link to the order with a wallet. Templates are a mechanism that -allows wallets to create their own orders directly, using a public endpoint. -The template fixes some properties of the contracts created from it, while -other details may be left for the customer to provide. Templates are useful -in cases where the point-of-sale of a merchant is offline (and thus cannot -setup an order), or even in cases where a simple static QR code is desired to -accept payments or donations. - -When generating a template, the "summary" text of the contract and the -"amount" to be paid by the customer can be fixed or left for the customer to -specify. If the customer is expected to provide either or both of these -values, the template link (or QR code) can specify a default value. For -example, a cafeteria with a fixed price lunch may use a "lunch" template with -both values fixed to the lunch price and the "lunch" product, a bakery might -fix the summary to "baked goods" but allow the customer to enter the amount -based on the total price of the items being bought, and a charity may allow -donating an arbitrary amount and summary message while also suggesting default -values. - -If an offline merchant wants to confirm that a customer did actually pay the -agreed amount using an order derived from a template, they can associate an -OTP device with the template. - -@node OTP Devices,Transfers,Templates,Terminology -@anchor{taler-merchant-manual otp-device}@anchor{12}@anchor{taler-merchant-manual otp-devices}@anchor{13} -@section OTP Devices - - -@geindex OTP - -@geindex TOTP - -A One-Time-Password (OTP) generator is a device or application that generates -a 4 to 8 digit code typically used for authentication. The widely used TOTP -standard is described in RFC 6238@footnote{https://www.rfc-editor.org/rfc/rfc6238}. -For GNU Taler merchant backends, OTP devices are used as a way to assure a -merchant without network connectivity that a customer made a digital -payment. The idea is described in depth in our SUERF Policy Brief@footnote{https://www.suerf.org/suer-policy-brief/69851/practical-offline-payments-using-one-time-passcodes}. -To use this method, a merchant must configure the OTP device's shared secret -in the merchant backend, and then associate the OTP device with a -@ref{10,,Templates}. Once the customer has paid, they are given a list of OTP -codes which must be shown to the merchant who can check that at least one of -the codes matches their OTP device, proving that the customer made the -payment. - -@node Transfers,Webhooks,OTP Devices,Terminology -@anchor{taler-merchant-manual transfers}@anchor{14} +@node Transfers,Rewards,Orders and Contracts,Terminology +@anchor{taler-merchant-manual transfers}@anchor{f} @section Transfers @@ -571,155 +511,70 @@ backend with wire `transfer' data that specifies the `wire transfer subject' and the amount that was received. Given this information, the backend can detect and report any irregularities that might arise. -@node Webhooks,,Transfers,Terminology -@anchor{taler-merchant-manual webhooks}@anchor{15} -@section Webhooks - - -@geindex webhook - -A webhook is a pre-defined HTTP request that the GNU Taler merchant backend -will make upon certain events, such as an order being paid or refunded. When -the configured event happens, the merchant backend will make an HTTP request -to the endpoint configured in the webhook configuration, possibly sending -selected data about the event to the respective Web service. Webhooks can be -used to trigger additional business logic outside of the GNU Taler merchant -backend. - -@node Installation,How to configure the merchant backend,Terminology,Top -@anchor{taler-merchant-manual installation}@anchor{16} -@chapter Installation +@node Rewards,Reserves,Transfers,Terminology +@anchor{taler-merchant-manual rewards}@anchor{10} +@section Rewards -This chapter describes how to install the GNU Taler merchant backend. +@geindex reward -@menu -* Installing the GNU Taler binary packages on Debian:: -* Installing the GNU Taler binary packages on Trisquel:: -* Installing the GNU Taler binary packages on Ubuntu:: -* Installing from source:: - -@end menu - -@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,,Installation -@anchor{taler-merchant-manual generic-instructions}@anchor{17}@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{18} -@section Installing the GNU Taler binary packages on Debian - - -To install the GNU Taler Debian packages, first ensure that you have -the right Debian distribution. At this time, the packages are built for -Debian bookworm. - -You need to add a file to import the GNU Taler packages. Typically, -this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that -looks like this: - -@example -deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main -@end example - -Next, you must import the Taler Systems SA public package signing key -into your keyring and update the package lists: +@geindex pick up -@example -# wget -O /etc/apt/keyrings/taler-systems.gpg \ - https://taler.net/taler-systems.gpg -# apt update -@end example +Taler does not only allow a Website to be paid, but also to make voluntary, +non-contractual payments to visitors, called `rewards'. Such rewards could be +granted as a reward for filling in surveys or watching advertizements. For +rewards, there is no contract, rewards are always voluntary actions by the Web +site that do not arise from a contractual obligation. Before a Web site +can create rewards, it must establish a reserve. Once a reserve has been +established, the merchant can `grant' rewards, allowing wallets to `pick up' +the reward. @cartouche @quotation Note -You may want to verify the correctness of the Taler Systems SA key out-of-band. +Rewards are an optional feature, and exchanges may disable rewards (usually +if they see compliance issues). In this case, the reward feature will +not be available. @end quotation @end cartouche -Now your system is ready to install the official GNU Taler binary packages -using apt. - -To install the Taler merchant backend, you can now simply run: - -@example -# apt install taler-merchant -@end example - -Note that the package does not complete the integration of the backend with -the HTTP reverse proxy (typically with TLS certificates). A configuration -fragment for Nginx or Apache will be placed in -@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}. You must -furthermore still configure the database and the instances, and may need to -extend the fragment with access control restrictions for non-default -instances. - -@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation -@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{19} -@section Installing the GNU Taler binary packages on Trisquel - - -To install the GNU Taler Trisquel packages, first ensure that you have -the right Trisquel distribution. Packages are currently available for -Trisquel GNU/Linux 10.0. Simply follow the same instructions provided -for Ubuntu. - -@node Installing the GNU Taler binary packages on Ubuntu,Installing from source,Installing the GNU Taler binary packages on Trisquel,Installation -@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{1a} -@section Installing the GNU Taler binary packages on Ubuntu - +@node Reserves,,Rewards,Terminology +@anchor{taler-merchant-manual reserves}@anchor{11} +@section Reserves -To install the GNU Taler Ubuntu packages, first ensure that you have -the right Ubuntu distribution. At this time, the packages are built for -Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your -@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages -from Ubuntu @code{universe}. -A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup -would look like this for Ubuntu Lunar: - -@example -deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar -@end example +@geindex reserve -For Ubuntu Jammy use this instead: +@geindex close -@example -deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ jammy taler-jammy -@end example +A `reserve' is a pool of electronic cash at an exchange under the control of +a private key. Merchants withdraw coins from a reserve when granting +rewards. A reserve is established by first generating the required key material +in the merchant backend, and then wiring the desired amount of funds to the +exchange. -The last line is crucial, as it adds the GNU Taler packages. +An exchange will automatically `close' a reserve after a fixed period of time +(typically about a month), wiring any remaining funds back to the merchant. +While exchange APIs exists to (1) explicitly `open' a reserve to prevent it +from being automatically closed and to (2) explicitly `close' a reserve at any +time, the current merchant backend does not make use of these APIs. -Next, you must import the Taler Systems SA public package signing key -into your keyring and update the package lists: - -@example -# wget -O /etc/apt/keyrings/taler-systems.gpg \ - https://taler.net/taler-systems.gpg -# apt update -@end example - -@cartouche -@quotation Note -You may want to verify the correctness of the Taler Systems key out-of-band. -@end quotation -@end cartouche +@node Installation,How to configure the merchant’s backend,Terminology,Top +@anchor{taler-merchant-manual installation}@anchor{12} +@chapter Installation -Now your system is ready to install the official GNU Taler binary packages -using apt. -To install the Taler merchant backend, you can now simply run: +This chapter describes how to install the GNU Taler merchant backend. -@example -# apt install taler-merchant -@end example +@menu +* Installing from source:: +* Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: -Note that the package does not complete the integration of the backend with -the HTTP reverse proxy (typically with TLS certificates). A configuration -fragment for Nginx or Apache will be placed in -@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}. You must -furthermore still configure the database and the instances, and may need to -extend the fragment with access control restrictions for non-default -instances. +@end menu -@node Installing from source,,Installing the GNU Taler binary packages on Ubuntu,Installation -@anchor{taler-merchant-manual installing-from-source}@anchor{1b} +@node Installing from source,Installing the GNU Taler binary packages on Debian,,Installation +@anchor{taler-merchant-manual generic-instructions}@anchor{13}@anchor{taler-merchant-manual installing-from-source}@anchor{14} @section Installing from source @@ -927,9 +782,126 @@ latter ensures that necessary binaries are copied to the right place. In any case, if @code{make check} fails, please consider filing a bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. -@node How to configure the merchant backend,Instance setup,Installation,Top -@anchor{taler-merchant-manual how-to-configure-the-merchant-backend}@anchor{1c} -@chapter How to configure the merchant backend +@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Installing from source,Installation +@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{15} +@section Installing the GNU Taler binary packages on Debian + + +To install the GNU Taler Debian packages, first ensure that you have +the right Debian distribution. At this time, the packages are built for +Debian bookworm. + +You need to add a file to import the GNU Taler packages. Typically, +this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that +looks like this: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main +@end example + +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: + +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems SA key out-of-band. +@end quotation +@end cartouche + +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Taler merchant backend, you can now simply run: + +@example +# apt install taler-merchant +@end example + +Note that the package does not complete the integration of the backend with +the HTTP reverse proxy (typically with TLS certificates). A configuration +fragment for Nginx or Apache will be placed in +@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}. You must +furthermore still configure the database and the instances, and may need to +extend the fragment with access control restrictions for non-default +instances. + +@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation +@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{16} +@section Installing the GNU Taler binary packages on Trisquel + + +To install the GNU Taler Trisquel packages, first ensure that you have +the right Trisquel distribution. Packages are currently available for +Trisquel GNU/Linux 10.0. Simply follow the same instructions provided +for Ubuntu. + +@node Installing the GNU Taler binary packages on Ubuntu,,Installing the GNU Taler binary packages on Trisquel,Installation +@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{17} +@section Installing the GNU Taler binary packages on Ubuntu + + +To install the GNU Taler Ubuntu packages, first ensure that you have +the right Ubuntu distribution. At this time, the packages are built for +Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your +@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages +from Ubuntu @code{universe}. + +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar +@end example + +For Ubuntu Jammy use this instead: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ jammy taler-jammy +@end example + +The last line is crucial, as it adds the GNU Taler packages. + +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: + +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems key out-of-band. +@end quotation +@end cartouche + +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Taler merchant backend, you can now simply run: + +@example +# apt install taler-merchant +@end example + +Note that the package does not complete the integration of the backend with +the HTTP reverse proxy (typically with TLS certificates). A configuration +fragment for Nginx or Apache will be placed in +@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}. You must +furthermore still configure the database and the instances, and may need to +extend the fragment with access control restrictions for non-default +instances. + +@node How to configure the merchant’s backend,Instance setup,Installation,Top +@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{18} +@chapter How to configure the merchant’s backend @geindex taler.conf @@ -950,8 +922,8 @@ force the use of @code{/etc/taler/taler.conf} as the main configuration file. @end menu -@node Configuration format,Backend options,,How to configure the merchant backend -@anchor{taler-merchant-manual configuration-format}@anchor{1d} +@node Configuration format,Backend options,,How to configure the merchant’s backend +@anchor{taler-merchant-manual configuration-format}@anchor{19} @section Configuration format @@ -1036,8 +1008,8 @@ pathnames, when they use several levels of @code{$}-expanded variables. See The repository @code{git://git.taler.net/deployment} contains example code for generating configuration files under @code{deployment/netzbon/}. -@node Backend options,Sample backend configuration,Configuration format,How to configure the merchant backend -@anchor{taler-merchant-manual backend-options}@anchor{1e}@anchor{taler-merchant-manual id3}@anchor{1f} +@node Backend options,Sample backend configuration,Configuration format,How to configure the merchant’s backend +@anchor{taler-merchant-manual backend-options}@anchor{1a}@anchor{taler-merchant-manual id3}@anchor{1b} @section Backend options @@ -1074,7 +1046,7 @@ modified. Here, the notation @code{[$SECTION]/$OPTION} denotes the option @end menu @node Service address,Currency,,Backend options -@anchor{taler-merchant-manual service-address}@anchor{20} +@anchor{taler-merchant-manual service-address}@anchor{1c} @subsection Service address @@ -1136,7 +1108,7 @@ respective @code{sites-available} directories of Apache and Nginx. @end cartouche @node Currency,Database,Service address,Backend options -@anchor{taler-merchant-manual currency}@anchor{21} +@anchor{taler-merchant-manual currency}@anchor{1d} @subsection Currency @@ -1169,7 +1141,7 @@ directives and destroy the carefully setup path structure. @end cartouche @node Database,Exchange,Currency,Backend options -@anchor{taler-merchant-manual database}@anchor{22} +@anchor{taler-merchant-manual database}@anchor{1e} @subsection Database @@ -1248,7 +1220,7 @@ secured from unauthorized access. @c index: MASTER_KEY @node Exchange,,Database,Backend options -@anchor{taler-merchant-manual exchange}@anchor{23} +@anchor{taler-merchant-manual exchange}@anchor{1f} @subsection Exchange @@ -1316,8 +1288,8 @@ with the GNU Taler development team. @end quotation @end cartouche -@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant backend -@anchor{taler-merchant-manual id4}@anchor{24}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{25} +@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend +@anchor{taler-merchant-manual id4}@anchor{20}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{21} @section Sample backend configuration @@ -1335,7 +1307,7 @@ PORT = 8888 DATABASE = postgres [merchantdb-postgres] -CONFIG = postgres:///taler-merchant +CONFIG = postgres:///donations [merchant-exchange-kudos] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ @@ -1352,8 +1324,8 @@ The backend will deposit the coins it receives to the exchange at @indicateurl{https://exchange.demo.taler.net/}, which has the master key @code{FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0}. -@node Launching the backend,,Sample backend configuration,How to configure the merchant backend -@anchor{taler-merchant-manual id5}@anchor{26}@anchor{taler-merchant-manual launching-the-backend}@anchor{27} +@node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend +@anchor{taler-merchant-manual id5}@anchor{22}@anchor{taler-merchant-manual launching-the-backend}@anchor{23} @section Launching the backend @@ -1362,17 +1334,20 @@ The backend will deposit the coins it receives to the exchange at @geindex taler-merchant-httpd Assuming you have configured everything correctly, you can launch the -merchant backend as @code{$USER} using (to provide a trivial example): +merchant backend as @code{$USER} using @example $ taler-merchant-httpd & $ taler-merchant-webhook & $ taler-merchant-wirewatch & -$ taler-merchant-depositcheck & -$ taler-merchant-exchange & @end example -To ensure these processes run always in the background and also after +You only need to run @code{taler-merchant-webhook} if one of the instances is +configured to trigger web hooks. Similarly, @code{taler-merchant-wirewatch} is +only required if instances have accounts configured with automatic import of +wire transfers via a bank wire gateway. + +To ensure these processes runs always in the background and also after rebooting, you should use systemd, cron or some other init system of your operating system to launch the process. You should also periodically re-start these services to prevent them from exhausing the memory utilization of the @@ -1383,8 +1358,8 @@ how to start and stop daemons. @quotation Note When using the Debian/Ubuntu packages, the systemd configuration will already exist. You only need to enable and start the service -using @code{systemctl enable taler-merchant.target} and -@code{systemctl start taler-merchant.target}. Additionally, you should +using @code{systemctl enable taler-merchant-httpd} and +@code{systemctl start taler-merchant-httpd}. Additionally, you should review the @code{/etc/apache2/sites-available/taler-merchant.conf} or @code{/etc/nginx/sites-available/taler-merchant} (these files contain additional instructions to follow), symlink it to @@ -1411,7 +1386,7 @@ any access control. You can either: @itemize * @item -Use the @code{--auth=$TOKEN} command-line option to `taler-merchant-httpd' to set an access token to be provided in an @code{Authorize: Bearer $TOKEN} HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. +Use the @code{--auth=$TOKEN} command-line option to set an access token to be provided in an @code{Authorize: Bearer $TOKEN} HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. @item Set the @code{TALER_MERCHANT_TOKEN} environment variable to @code{$TOKEN} for the same effect. This method has the advantage of @code{$TOKEN} not being visible as a command-line interface to other local users on the same machine. @@ -1426,19 +1401,20 @@ and use TLS for improved network privacy, see @ref{9,,Secure setup}. @geindex instance -@node Instance setup,Instance account setup,How to configure the merchant backend,Top -@anchor{taler-merchant-manual id6}@anchor{28}@anchor{taler-merchant-manual instance-setup}@anchor{29} +@node Instance setup,Secure setup,How to configure the merchant’s backend,Top +@anchor{taler-merchant-manual id6}@anchor{24}@anchor{taler-merchant-manual instance-setup}@anchor{25} @chapter Instance setup -We recommend the use of the single-page administration application (SPA) that -is served by default at the base URL of the merchant backend. You can use it -to perform all steps described in this section (and more!), using a simple Web -interface. Alternatively, you can also use the @code{wget} commands given below. +First of all, we recommend the use of the single-page administration +application (SPA) that is served by default at the base URL of the merchant +backend. You can use it to perform all steps described in this section (and +more!), using a simple Web interface instead of the @code{wget} commands given +below. -Regardless of which approach you use, the first step for using the backend +Regardless of which tool you use, the first step for using the backend involves the creation of a @code{default} instance. The @code{default} instance can -also create, configure or delete other instances, similar to the @code{root} +also create / delete / configure other instances, similar to the @code{root} account on UNIX. When no instance exists and @code{taler-merchant-httpd} was started without the @code{--auth} option, then the backend is reachable without any access control (unless you configured some in the reverse proxy). @@ -1454,47 +1430,21 @@ This means unauthorized users can distinguish between the case where the instance does not exist (HTTP 404) and the case where access is denied (HTTP 403). This is concern can be addressed using a properly configured -@ref{2a,,reverse proxy}. +@ref{26,,reverse proxy}. @end quotation @end cartouche @menu -* Instance setup with the SPA:: -* Instance setup without the Web interface:: +* Setup without the Web interface:: +* Accounts:: +* Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. +* Automatic Settlement Data Import:: @end menu -@node Instance setup with the SPA,Instance setup without the Web interface,,Instance setup -@anchor{taler-merchant-manual instance-setup-with-the-spa}@anchor{2b} -@section Instance setup with the SPA - - -In order to setup an instance, you need the merchant backend to already be -running, and you must either have the credentials for the "default" instance, -or no instance must be configured at all yet. - -To start, point your browser to @code{$PROTO://backend.$DOMAIN_NAME/}, replacing -"$PROTO" with "https" or (rarely) "http" and "$DOMAIN_NAME" with your -organizations DNS domain or subdomain. - -@cartouche -@quotation Note -The label "backend" here is also just a suggestion, your administrator -can in principle choose any name. -@end quotation -@end cartouche - -You should be welcomed by the following merchant backoffice page: - -@image{taler-merchant-figures/merchant_first_login,,,,png} - -After supplying the required fields, primarily the name of your organization -and the desired access token, click @code{confirm}. You can change the instance -settings later via the @code{Settings} entry in the menu on the left. - -@node Instance setup without the Web interface,,Instance setup with the SPA,Instance setup -@anchor{taler-merchant-manual instance-setup-without-the-web-interface}@anchor{2c} -@section Instance setup without the Web interface +@node Setup without the Web interface,Accounts,,Instance setup +@anchor{taler-merchant-manual setup-without-the-web-interface}@anchor{27} +@section Setup without the Web interface Instances can be created by POSTing a request to @code{/management/instances} @@ -1506,7 +1456,7 @@ InstanceConfigurationMessage: @example @{ "id" : "default", - "name": "Example Inc.", + "name": "example.com", "address": @{ "country" : "zz" @}, "auth": @{ "method" : "external"@} , "jurisdiction": @{ "country" : "zz" @}, @@ -1538,9 +1488,9 @@ Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented in the Merchant Backend API documentation. -@node Instance account setup,Manually creating an order using the SPA,Instance setup,Top -@anchor{taler-merchant-manual id7}@anchor{2d}@anchor{taler-merchant-manual instance-account-setup}@anchor{2e} -@chapter Instance account setup +@node Accounts,Detecting Settlement Manually Adding Transfers,Setup without the Web interface,Instance setup +@anchor{taler-merchant-manual accounts}@anchor{28} +@section Accounts Before you can use an instance productively, you need to configure one or more @@ -1549,56 +1499,19 @@ operator to tell it where to wire the income from your sales. Every bank account has an associated `wire method' which determines how an exchange can transfer the funds. The most commonly supported wire method is `iban', which implies that bank accounts are identified by IBAN numbers and wire transfers -are to be executed between IBAN accounts. For regional currency setups, the -wire method could also be `x-taler-bank'. - -@cartouche -@quotation Note -When using a regional currency, you need to first create a bank account at -the regional bank. You may need to contact the respective administrator who -can set one up. After being able to login to the new bank account, you can -see your bank account number by clicking on the @code{Welcome, $USERNAME} -message in the profile page. Next to the bank account number, you can find -a convenient button to copy the number to the clipboard. -@end quotation -@end cartouche +are to be executed between IBAN accounts. Not every exchange will support every `wire method', and if you do not add a bank account with a wire method that is supported by a particular exchange, then you will not be able to receive payments via that exchange even if you configured the merchant backend to trust that exchange. -The simplest way to configure an account is to use the Web interface which has -specific forms for different wire methods. First, select @code{Bank account} at -the left of the page. The following page should be shown: - -@image{taler-merchant-figures/no_default_account_yet,,,,png} +The simplest way to configure an account is to use the Web interface which +has specific forms for different wire methods. Specifying the revenue gateway +with username and password is optional and discussed below. -Click on the blue "+" sign on the top right of the page to add a new -bank account. The following page should appear: - -@image{taler-merchant-figures/enter_instance_details,,,,png} - -First, you should select the wire method, after which the dialog will show you -additional fields specific to the wire method. For example, if youchoose -@code{iban} as the account type, the following page should appear: - -@image{taler-merchant-figures/instance_iban_config,,,,png} - -Specifying the revenue gateway with username and password is optional and -discussed in section @ref{2f,,Automatic Settlement Data Import} below. - -After providing the details and confirming, the shop is ready to generate orders -and accept payments. - -@menu -* Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. -* Automatic Settlement Data Import:: - -@end menu - -@node Detecting Settlement Manually Adding Transfers,Automatic Settlement Data Import,,Instance account setup -@anchor{taler-merchant-manual detecting-settlement-manually-adding-transfers}@anchor{30} +@node Detecting Settlement Manually Adding Transfers,Automatic Settlement Data Import,Accounts,Instance setup +@anchor{taler-merchant-manual detecting-settlement-manually-adding-transfers}@anchor{29} @section Detecting Settlement: Manually Adding Transfers @@ -1616,57 +1529,24 @@ information, the merchant backend will inquire with the exchange which individual payments were aggregated, check that the total amount is correct, and will then flag the respective contracts as wired. -You can manually enter wire transfers under @code{Transfers}. However, this is -tedious, and so if your banking setup supports it, we highly recommend -using the automatic settlement data import. - -@node Automatic Settlement Data Import,,Detecting Settlement Manually Adding Transfers,Instance account setup -@anchor{taler-merchant-manual automatic-settlement-data-import}@anchor{2f}@anchor{taler-merchant-manual id8}@anchor{31} +@node Automatic Settlement Data Import,,Detecting Settlement Manually Adding Transfers,Instance setup +@anchor{taler-merchant-manual automatic-settlement-data-import}@anchor{2a} @section Automatic Settlement Data Import -To automatically import settlement data, you need to provide the merchant -backend with the address and access credentials of a -taler-bank-merchant-http-api for each bank account of an instance. The -revenue API endpoint will allow the merchant backend to obtain a list of all -incoming wire transfers into your bank account and automatically import them -into the list of confirmed wire transfers. +To automatically import settlement data, you can provide the merchant backend +with the address and access credentials of a Taler revenue API for each bank +account of an instance. The revenue API endpoint will allow the merchant +backend to observe all incoming wire transfers into your bank account and +automatically import them into the list of wire transfers. Note that setting up a revenue API endpoint will usually require you to first -ask your bank for EBICS access and to set up libeufin-nexus to provide -the revenue API endpoint. The libeufin-bank used by regional currency -setups also provides a revenue API endpoint at -@code{$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/}. Thus, when using a -regional currency setup, simply use the @code{$BANK_URL} of your bank and specify -your bank login name and password in the @ref{2e,,Instance account setup} dialog. - -@node Manually creating an order using the SPA,Secure setup,Instance account setup,Top -@anchor{taler-merchant-manual manually-creating-an-order-using-the-spa}@anchor{32} -@chapter Manually creating an order using the SPA - - -Click on @code{Orders} at the top left corner of the merchant backoffice page; the -following page should appear - -@image{taler-merchant-figures/create_orders,,,,png} - -After having filled the required fields, the interface should show the -following page with the related links to check the status of the order and let -wallets pay for it. +ask your bank for EBICS access and to setup libeufin to provide the revenue +API endpoint. The taler-bank used by regional currency setups also provides +a revenue API endpoint. -@image{taler-merchant-figures/payment_links,,,,png} - -In order to test the setup, it should be now possible to use the command line wallet -to withdraw Taler coins and spend them to pay for the order we just created. - -In practice, you will rarely if ever setup orders manually like this. Instead, -a GNU Taler e-commerce front-end@footnote{https://taler.net/en/docs.html#extensions} or the -taler-merchant-pos-app will do this on-demand. Here, you will only need -to provide the respective front-ends with the URL of your instance -(e.g. @code{https://backend.$DOMAIN/instances/$NAME}) and your access token. - -@node Secure setup,Customization,Manually creating an order using the SPA,Top -@anchor{taler-merchant-manual id9}@anchor{33}@anchor{taler-merchant-manual secure-setup}@anchor{9} +@node Secure setup,Customization,Instance setup,Top +@anchor{taler-merchant-manual id7}@anchor{2b}@anchor{taler-merchant-manual secure-setup}@anchor{9} @chapter Secure setup @@ -1674,11 +1554,11 @@ to provide the respective front-ends with the URL of your instance @geindex TLS -The Taler backend is deliberately simple in terms of support for access -control or transport layer security (TLS). Thus, production setups `must' -deploy the Taler backend behind an HTTP(S) server that acts as a `reverse -proxy', performs TLS termination and authentication and then forwards requests -to the backend. +The Taler backend does not include even the most basic forms of access control +or transport layer security. Thus, production setups `must' deploy the +Taler backend behind an HTTP(S) server that acts as a `reverse proxy', +performs TLS termination and authentication and then forwards requests to the +backend. @menu * Using UNIX domain sockets:: @@ -1689,7 +1569,7 @@ to the backend. @end menu @node Using UNIX domain sockets,Reverse proxy configuration,,Secure setup -@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{34} +@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{2c} @section Using UNIX domain sockets @@ -1713,7 +1593,7 @@ instead strongly consider using the "BIND_TO" option to at least bind it only to "localhost". @node Reverse proxy configuration,Access control,Using UNIX domain sockets,Secure setup -@anchor{taler-merchant-manual id10}@anchor{35}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{2a} +@anchor{taler-merchant-manual id8}@anchor{2d}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{26} @section Reverse proxy configuration @@ -1724,7 +1604,7 @@ to "localhost". @end menu @node Nginx,Apache,,Reverse proxy configuration -@anchor{taler-merchant-manual nginx}@anchor{36} +@anchor{taler-merchant-manual nginx}@anchor{2e} @subsection Nginx @@ -1744,7 +1624,7 @@ not have HTTPS enabled. Make sure to restart the @code{taler-merchant-httpd} process after changing the @code{SERVE} configuration. @node Apache,,Nginx,Reverse proxy configuration -@anchor{taler-merchant-manual apache}@anchor{37} +@anchor{taler-merchant-manual apache}@anchor{2f} @subsection Apache @@ -1772,7 +1652,7 @@ you have TLS configured. Note that you must add the @code{https} header unless your site is not available via TLS. @node Access control,Status code remapping,Reverse proxy configuration,Secure setup -@anchor{taler-merchant-manual access-control}@anchor{38} +@anchor{taler-merchant-manual access-control}@anchor{30} @section Access control @@ -1792,7 +1672,7 @@ are expected to be fully exposed to the Internet, and wallets may have to interact with those endpoints directly without client authentication. @node Status code remapping,,Access control,Secure setup -@anchor{taler-merchant-manual status-code-remapping}@anchor{39} +@anchor{taler-merchant-manual status-code-remapping}@anchor{31} @section Status code remapping @@ -1809,7 +1689,7 @@ fragment, which remaps all 404 response codes to 403. @end menu @node Nginx<2>,Apache<2>,,Status code remapping -@anchor{taler-merchant-manual id11}@anchor{3a} +@anchor{taler-merchant-manual id9}@anchor{32} @subsection Nginx @@ -1818,7 +1698,7 @@ error_page 404 =403 /empty.gif; @end example @node Apache<2>,,Nginx<2>,Status code remapping -@anchor{taler-merchant-manual id12}@anchor{3b} +@anchor{taler-merchant-manual id10}@anchor{33} @subsection Apache @@ -1828,7 +1708,7 @@ set-status 403 @end example @node Customization,Upgrade procedure,Secure setup,Top -@anchor{taler-merchant-manual customization}@anchor{3c} +@anchor{taler-merchant-manual customization}@anchor{34} @chapter Customization @@ -1848,7 +1728,7 @@ set-status 403 @end menu @node Legal conditions for using the service,Terms of Service,,Customization -@anchor{taler-merchant-manual legal-conditions-for-using-the-service}@anchor{3d} +@anchor{taler-merchant-manual legal-conditions-for-using-the-service}@anchor{35} @section Legal conditions for using the service @@ -1874,7 +1754,7 @@ user in various languages and various formats. This section describes how to setup and configure the legal conditions. @node Terms of Service,Privacy Policy,Legal conditions for using the service,Customization -@anchor{taler-merchant-manual terms-of-service}@anchor{3e} +@anchor{taler-merchant-manual terms-of-service}@anchor{36} @section Terms of Service @@ -1905,7 +1785,7 @@ process. @end itemize @node Privacy Policy,Legal policies directory layout,Terms of Service,Customization -@anchor{taler-merchant-manual privacy-policy}@anchor{3f} +@anchor{taler-merchant-manual privacy-policy}@anchor{37} @section Privacy Policy @@ -1936,7 +1816,7 @@ process. @end itemize @node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Customization -@anchor{taler-merchant-manual legal-policies-directory-layout}@anchor{40} +@anchor{taler-merchant-manual legal-policies-directory-layout}@anchor{38} @section Legal policies directory layout @@ -1961,7 +1841,7 @@ the service may show a warning on startup. @end menu @node Example,,,Legal policies directory layout -@anchor{taler-merchant-manual example}@anchor{41} +@anchor{taler-merchant-manual example}@anchor{39} @subsection Example @@ -2006,7 +1886,7 @@ If the user requests an HTML format with language preferences "fr" followed by French. @node Generating the Legal Terms,Adding translations,Legal policies directory layout,Customization -@anchor{taler-merchant-manual generating-the-legal-terms}@anchor{42} +@anchor{taler-merchant-manual generating-the-legal-terms}@anchor{3a} @section Generating the Legal Terms @@ -2034,7 +1914,7 @@ languages (initially only English) in @code{$PREFIX/share/terms/}. The generato has a few options which are documented in its man page. @node Adding translations,Updating legal documents,Generating the Legal Terms,Customization -@anchor{taler-merchant-manual adding-translations}@anchor{43} +@anchor{taler-merchant-manual adding-translations}@anchor{3b} @section Adding translations @@ -2069,7 +1949,7 @@ You must restart the service whenever adding or updating legal documents or thei @end cartouche @node Updating legal documents,Mustach HTML Templates,Adding translations,Customization -@anchor{taler-merchant-manual updating-legal-documents}@anchor{44} +@anchor{taler-merchant-manual updating-legal-documents}@anchor{3c} @section Updating legal documents @@ -2087,7 +1967,7 @@ forget to update the @code{ETAG} configuration option to the new name and to restart the service. @node Mustach HTML Templates,Static files,Updating legal documents,Customization -@anchor{taler-merchant-manual mustach-html-templates}@anchor{45} +@anchor{taler-merchant-manual mustach-html-templates}@anchor{3d} @section Mustach HTML Templates @@ -2097,7 +1977,7 @@ own design. The templating language used is Mustach, and the templates are in the @code{share/taler/merchant/templates/} directory. @node Static files,Internationalization,Mustach HTML Templates,Customization -@anchor{taler-merchant-manual static-files}@anchor{46} +@anchor{taler-merchant-manual static-files}@anchor{3e} @section Static files @@ -2107,7 +1987,7 @@ logic to load a CSS file, but you can also put other resources such as images or JavaScript. @node Internationalization,Limitations,Static files,Customization -@anchor{taler-merchant-manual internationalization}@anchor{47} +@anchor{taler-merchant-manual internationalization}@anchor{3f} @section Internationalization @@ -2124,7 +2004,7 @@ returned. Otherwise, an internationalized file based on the language preferences indicated by the browser is returned. @node Limitations,,Internationalization,Customization -@anchor{taler-merchant-manual limitations}@anchor{48} +@anchor{taler-merchant-manual limitations}@anchor{40} @section Limitations @@ -2143,7 +2023,7 @@ template expansion, and does not make use of scopes and other Mustach features. @node Upgrade procedure,Advanced topics,Customization,Top -@anchor{taler-merchant-manual upgrade-procedure}@anchor{49} +@anchor{taler-merchant-manual upgrade-procedure}@anchor{41} @chapter Upgrade procedure @@ -2171,7 +2051,7 @@ REVOKE the database permissions. Finally, restart the merchant services processes, either via your systemd or init system, or directly. @node Advanced topics,Temporarily Abandoned Features,Upgrade procedure,Top -@anchor{taler-merchant-manual advanced-topics}@anchor{4a} +@anchor{taler-merchant-manual advanced-topics}@anchor{42} @chapter Advanced topics @@ -2184,14 +2064,14 @@ processes, either via your systemd or init system, or directly. @end menu @node taler-config,Using taler-config,,Advanced topics -@anchor{taler-merchant-manual taler-config}@anchor{4b} +@anchor{taler-merchant-manual taler-config}@anchor{43} @section taler-config @geindex taler-config @node Using taler-config,Database Scheme,taler-config,Advanced topics -@anchor{taler-merchant-manual using-taler-config}@anchor{4c} +@anchor{taler-merchant-manual using-taler-config}@anchor{44} @section Using taler-config @@ -2245,7 +2125,7 @@ While the configuration file is typically located at GNU Taler component using the @code{-c} option. @node Database Scheme,Benchmarking,Using taler-config,Advanced topics -@anchor{taler-merchant-manual database-scheme}@anchor{4d}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{4e} +@anchor{taler-merchant-manual database-scheme}@anchor{45}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{46} @section Database Scheme @@ -2261,7 +2141,7 @@ The database scheme used by the merchant looks as follows: @image{taler-merchant-figures/merchant-db,,,,png} @node Benchmarking,,Database Scheme,Advanced topics -@anchor{taler-merchant-manual benchmarking}@anchor{4f}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{50} +@anchor{taler-merchant-manual benchmarking}@anchor{47}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{48} @section Benchmarking @@ -2293,7 +2173,7 @@ See Taler Exchange Manual for how to use @code{taler-unified-setup.sh} to setup @end menu @node Running taler-merchant-benchmark,,,Benchmarking -@anchor{taler-merchant-manual running-taler-merchant-benchmark}@anchor{51} +@anchor{taler-merchant-manual running-taler-merchant-benchmark}@anchor{49} @subsection Running taler-merchant-benchmark @@ -2337,12 +2217,8 @@ second gives the chance to leave some payments unaggregated, and also to use merchant instances other than the default (which is, actually, the one used by default by the tool). -@cartouche -@quotation Note -The ability to drive the aggregation policy is useful for testing +Note: the ability of driving the aggregation policy is useful for testing the back-office facility. -@end quotation -@end cartouche Any subcommand is also equipped with the canonical @code{--help} option, so feel free to issue the following command in order to explore all the @@ -2379,7 +2255,7 @@ option: @end itemize @node Temporarily Abandoned Features,Index,Advanced topics,Top -@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{52} +@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{4a} @chapter Temporarily Abandoned Features @@ -2389,7 +2265,7 @@ option: @end menu @node Installing Taler using Docker,,,Temporarily Abandoned Features -@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{53} +@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{4b} @section Installing Taler using Docker |
