summaryrefslogtreecommitdiff
path: root/texinfo
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2022-11-03 23:37:59 +0100
committerChristian Grothoff <christian@grothoff.org>2022-11-03 23:37:59 +0100
commit8452f991dd967328207fab52a99beb19e2cb4dff (patch)
tree5d28f2ab91b64a13ab22f5d9a12de3c2fa3c02e3 /texinfo
parentb988d98d4856758484eb23c27bfdc9e602d4235a (diff)
downloaddocs-8452f991dd967328207fab52a99beb19e2cb4dff.tar.gz
docs-8452f991dd967328207fab52a99beb19e2cb4dff.tar.bz2
docs-8452f991dd967328207fab52a99beb19e2cb4dff.zip
update prebuilt from source
Diffstat (limited to 'texinfo')
-rw-r--r--texinfo/taler-auditor.texi187
-rw-r--r--texinfo/taler-developer-manual.texi978
-rw-r--r--texinfo/taler-exchange.texi49
-rw-r--r--texinfo/taler-merchant-api-tutorial.texi24
-rw-r--r--texinfo/taler-merchant.texi43
5 files changed, 746 insertions, 535 deletions
diff --git a/texinfo/taler-auditor.texi b/texinfo/taler-auditor.texi
index 9a50ce32..e90120de 100644
--- a/texinfo/taler-auditor.texi
+++ b/texinfo/taler-auditor.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.9.0, Jul 06, 2022
+GNU Taler 0.9.0, Nov 03, 2022
GNU Taler team
@@ -102,7 +102,7 @@ Configuration
* Using taler-config::
* Initial configuration::
* Keys::
-* Configuring the auditor’s REST endpoint::
+* Configuring the auditor's REST endpoint::
* Bank account::
* Database::
@@ -129,7 +129,7 @@ Operation
Auditor implementation guide
-* The auditor’s database::
+* The auditor's database::
* Invariants checked by the auditor::
* Testing the auditor::
@@ -197,7 +197,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
@@ -209,9 +209,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.
@@ -219,7 +219,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:
@@ -245,7 +245,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
@@ -266,8 +266,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:
@@ -299,7 +299,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}.
@@ -319,7 +319,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}
@@ -365,6 +365,11 @@ Python3 module @code{jinja2}
@itemize -
@item
+"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})
+
+@item
libsqlite3 >= 3.16.2
@item
@@ -580,22 +585,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 @emph{offline} machine
+offline --- manages the offline key, on a separate @emph{offline} machine
@end itemize
@end quotation
@@ -615,10 +620,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
@@ -635,16 +640,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
@@ -676,7 +681,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.
@@ -685,7 +690,7 @@ This section discusses configuration options related to the auditor.
* Using taler-config::
* Initial configuration::
* Keys::
-* Configuring the auditor’s REST endpoint::
+* Configuring the auditor's REST endpoint::
* Bank account::
* Database::
@@ -834,7 +839,7 @@ $ taler-config -s auditor -o BASE_URL -V 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:
@@ -845,14 +850,14 @@ $ taler-config -s exchange -o BASE_URL -V https://exchange.example.com/
$ taler-config -s exchange -o MASTER_PUBLIC_KEY -V $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{13}@anchor{taler-auditor-manual keys}@anchor{14}
@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 @emph{offline} (and backed up adequately). As with the exchange’s
+a particular exchange's denomination keys. This key can and should
+be kept @emph{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.
@@ -893,9 +898,9 @@ You can set this configuration value using:
$ taler-config -s auditor -o PUBLIC_KEY -V $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{15}@anchor{taler-auditor-manual configuring-the-auditor-s-rest-endpoint}@anchor{16}
-@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.
@@ -921,7 +926,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{17}@anchor{taler-auditor-manual bank-account}@anchor{18}
@section Bank account
@@ -964,14 +969,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
@@ -992,7 +997,7 @@ CONFIG = postgres:///exchangedemo
@anchor{taler-auditor-manual wallets}@anchor{1d}
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.
@@ -1000,7 +1005,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::
@@ -1014,13 +1019,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
@@ -1030,7 +1035,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.
@@ -1068,7 +1073,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
@@ -1103,21 +1108,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
-@emph{exchange}’s database in-house. This should be performed in two steps
+@emph{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.
@@ -1133,7 +1138,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.
@@ -1146,10 +1151,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
@@ -1163,7 +1168,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.
@@ -1186,7 +1191,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
@@ -1196,7 +1201,7 @@ $ taler-config -s exchangedb-postgres -o CONFIG -V "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
@@ -1213,7 +1218,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
@@ -1228,20 +1233,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
@@ -1273,11 +1278,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
@@ -1303,7 +1308,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
@@ -1353,7 +1358,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:
@@ -1419,14 +1424,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}
@@ -1471,7 +1476,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.
@@ -1480,12 +1485,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 @emph{42}.
@@ -1517,15 +1522,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.
@@ -1534,22 +1539,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{34}
-@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{35}
@section Invariants checked by the auditor
@@ -1574,7 +1579,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:
@@ -1686,7 +1691,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:
@@ -1694,9 +1699,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).
@@ -1792,7 +1797,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:
@@ -1854,11 +1859,11 @@ target account does not match origin account
This auditor is special in that it is the only pass that is required to have
-@emph{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
+@emph{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:
@@ -1920,7 +1925,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
@@ -1933,13 +1938,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.texi b/texinfo/taler-developer-manual.texi
index 66d96eed..247338d7 100644
--- a/texinfo/taler-developer-manual.texi
+++ b/texinfo/taler-developer-manual.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.9.0, Jul 06, 2022
+GNU Taler 0.9.0, Nov 03, 2022
GNU Taler team
@@ -66,7 +66,7 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
@c @author Christian Grothoff
@menu
-* GNU Taler Release Checklist::
+* GNU Taler Release Checklists::
* GNU Taler Demo Upgrade Checklist::
* Fundamentals::
* Debian and Ubuntu Repositories::
@@ -88,182 +88,249 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
@end menu
-@node GNU Taler Release Checklist,GNU Taler Demo Upgrade Checklist,Top,Top
-@anchor{checklist-release doc}@anchor{1}@anchor{checklist-release developer-s-manual}@anchor{2}@anchor{checklist-release gnu-taler-release-checklist}@anchor{3}
-@chapter GNU Taler Release Checklist
+@node GNU Taler Release Checklists,GNU Taler Demo Upgrade Checklist,Top,Top
+@anchor{checklist-release doc}@anchor{1}@anchor{checklist-release developer-s-manual}@anchor{2}@anchor{checklist-release gnu-taler-release-checklists}@anchor{3}
+@chapter GNU Taler Release Checklists
-Release checklists for GNU Taler:
-
-Wallet:
+For exchange:
@itemize -
@item
-[ ] build wallet
+ no compiler warnings at "-Wall" with gcc
@item
-[ ] verify wallet works against ‘test.taler.net’
+ no compiler warnings at "-Wall" with clang
@item
-[ ] tag repo.
+ ensure Coverity static analysis passes
@item
-[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’
+ make check.
@item
-[ ] upload new wallet release to app store
+ make dist, make check on result of 'make dist'.
@item
-[ ] Update bug tracker (mark release, resolved -> closed)
+ Change version number in configure.ac.
@item
-[ ] Send announcement to @email{taler@@gnu.org}
+ make dist for release
@item
-[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only)
+ verify dist builds from source
@item
-[ ] Send announcement to @email{coordinator@@translationproject.org}
+ upgrade 'demo.taler.net'
+
+@item
+ run @ref{4,,demo upgrade checklist}
+
+@item
+ tag repo.
+
+@item
+ use deployment.git/packaging/>>*<<-docker/ to build Debian and Ubuntu packages
+
+@item
+ upload packages to deb.taler.net/ (note: only Florian/Christian can sign)
+
+@item
+ change 'demo.taler.net' deployment to use new tag.
+
+@item
+ Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha
@end itemize
-For exchange:
+For merchant (C backend):
@itemize -
@item
-[ ] check no compiler warnings at “-Wall”
+ no compiler warnings at "-Wall" with gcc
+
+@item
+ no compiler warnings at "-Wall" with clang
+
+@item
+ ensure Coverity static analysis passes
@item
-[ ] ensure Coverity static analysis passes
+ make check.
@item
-[ ] make check.
+ make dist, make check on result of 'make dist'.
@item
-[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’
+ Change version number in configure.ac.
@item
-[ ] make dist, make check on result of ‘make dist’.
+ make dist for release.
@item
-[ ] Change version number in configure.ac.
+ verify dist builds from source
@item
-[ ] make dist for release.
+ upgrade 'demo.taler.net'
@item
-[ ] tag repo.
+ run @ref{4,,demo upgrade checklist}
@item
-[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha
+ tag repo.
@item
-[ ] Update bug tracker (mark release, resolved -> closed)
+ use deployment.git/packaging/>>*<<-docker/ to build Debian and Ubuntu packages
@item
-[ ] Send announcement to @email{taler@@gnu.org}
+ upload packages to deb.taler.net/ (note: only Florian/Christian can sign)
@item
-[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only)
+ change 'demo.taler.net' deployment to use new tag.
@item
-[ ] Send announcement to @email{coordinator@@translationproject.org}
+ Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha
@end itemize
-For merchant (C backend):
+For libeufin:
@itemize -
@item
-[ ] check no compiler warnings at “-Wall”
+ update SPA of bank
@item
-[ ] ensure Coverity static analysis passes
+ build libeufin
@item
-[ ] make check.
+ upgrade 'demo.taler.net'
@item
-[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’
+ run @ref{4,,demo upgrade checklist}
@item
-[ ] make dist, make check on result of ‘make dist’.
+ make dist for release.
@item
-[ ] Change version number in configure.ac.
+ verify dist builds from source
@item
-[ ] make dist for release.
+ tag repo.
@item
-[ ] tag repo.
+ use deployment.git/packaging/>>*<<-docker/ to build Debian and Ubuntu packages
@item
-[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha
+ upload packages to deb.taler.net/ (note: only Florian/Christian can sign)
@item
-[ ] Update bug tracker (mark release, resolved -> closed)
+ change 'demo.taler.net' deployment to use new tag.
@item
-[ ] Send announcement to @email{taler@@gnu.org}
+ Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha
+@end itemize
+
+For Python merchant frontend:
+
+
+@itemize -
+
+@item
+ upgrade 'demo.taler.net'
@item
-[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only)
+ run @ref{4,,demo upgrade checklist}
@item
-[ ] Send announcement to @email{coordinator@@translationproject.org}
+ change 'demo.taler.net' deployment to use new tag.
@end itemize
-For bank:
+Wallet-core:
@itemize -
@item
-TBD
-@end itemize
+ build wallet
-For Python merchant frontend:
+@item
+ run integration test
+@item
+ make dist for release.
-@itemize -
+@item
+ verify dist builds from source
+
+@item
+ tag repo.
+
+@item
+ change 'demo.taler.net' deployment to use new tag.
@item
-TBD
+ Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha
@end itemize
-For PHP merchant frontend:
+Android-Wallet:
@itemize -
@item
-TBD
+ build wallet
+
+@item
+ run @ref{4,,demo upgrade checklist}
+
+@item
+ tag repo.
+
+@item
+ upload new wallet release to app store
@end itemize
-For auditor:
+Webextension-Wallet:
@itemize -
@item
-TBD
+ build wallet
+
+@item
+ run @ref{4,,demo upgrade checklist}
+
+@item
+ tag repo.
+
+@item
+ upload new wallet release to app store
@end itemize
-For libebics:
+Release announcement:
@itemize -
@item
-TBD
+ Update bug tracker (mark release, resolved -> closed)
+
+@item
+ Send announcement to @email{taler@@gnu.org}
+
+@item
+ Send announcement to @email{info-gnu@@gnu.org} (major releases only)
+
+@item
+ Send announcement to @email{coordinator@@translationproject.org}
@end itemize
-@node GNU Taler Demo Upgrade Checklist,Fundamentals,GNU Taler Release Checklist,Top
+@node GNU Taler Demo Upgrade Checklist,Fundamentals,GNU Taler Release Checklists,Top
@anchor{checklist-demo-upgrade doc}@anchor{4}@anchor{checklist-demo-upgrade gnu-taler-demo-upgrade-checklist}@anchor{5}
@chapter GNU Taler Demo Upgrade Checklist
@@ -298,12 +365,38 @@ Basics:
Visit @indicateurl{https://demo.taler.net/} to see if the landing page is displayed correctly
@item
+ landing language switcher
+
+@item
Visit the wallet installation page, install the wallet, and see if the presence
indicator is updated correctly.
@item
- Visit @indicateurl{https://bank.demo.taler.net/}, register a new user and withdraw coins into the
-browser wallet.
+ Visit @indicateurl{https://bank.demo.taler.net/}, register a new user
+
+@item
+ bank language switcher
+
+@item
+ bank logout
+
+@item
+ bank login
+
+@item
+ bank-integrated withdraw process, abort in bank
+
+@item
+ transaction history: delete pending withdraw
+
+@item
+ do bank-integrated withdraw process (5 KUDOS)
+
+@item
+ do wallet-initiated withdraw process (5 KUDOS)
+
+@item
+ withdraw process of large amount (20 KUDOS) runs into KYC check
@end itemize
Blog demo:
@@ -312,7 +405,13 @@ Blog demo:
@itemize -
@item
- Visit @indicateurl{https://shop.demo.taler.net/} and purchase an article.
+ Visit @indicateurl{https://shop.demo.taler.net/}
+
+@item
+ blog page article list renders
+
+@item
+ payment for blog article
@item
Verify that the balance in the wallet was updated correctly.
@@ -330,6 +429,18 @@ requested.
Delete cookies on @indicateurl{https://shop.demo.taler.net/} and click on the same article again.
Verify that the wallet detects that the article has already purchased and successfully
redirects to the article without spending more money.
+
+@item
+ payment for other blog article
+
+@item
+ refund of 2nd blog article (button at the end)
+
+@item
+ wallet transaction history rendering
+
+@item
+ delete history entry
@end itemize
Donation demo:
@@ -338,7 +449,19 @@ Donation demo:
@itemize -
@item
- Make a donation on @indicateurl{https://donations.demo.taler.net}
+ Reset wallet
+
+@item
+ Withdraw age-restricted coins (< 14)
+
+@item
+ Try to make a donation on @indicateurl{https://donations.demo.taler.net/}, fail due to age-restriction
+
+@item
+ Withdraw age-restricted coins (>= 14)
+
+@item
+ Make a donation on @indicateurl{https://donations.demo.taler.net/}
@item
Make another donation with the same parameters and verify
@@ -359,6 +482,33 @@ Survey/Tipping:
and that the survey reserve has sufficient funds.
@end itemize
+P2P payments:
+
+
+@itemize -
+
+@item
+ generating push payment (to self is OK)
+
+@item
+ accepting push payment (from self is OK)
+
+@item
+ generating pull payment (to self is OK)
+
+@item
+ accepting pull payment (from self is OK)
+
+@item
+ sending money back from wallet to bank account
+
+@item
+ wallet transaction history rendering
+
+@item
+ delete history entry
+@end itemize
+
@cartouche
@quotation Note
This manual contains information for developers working on GNU Taler
@@ -372,6 +522,8 @@ and related components. It is not intended for a general audience.
@menu
+* Testing Tools::
+* Manual Testing Database Reset::
* Bug Tracking::
* Code Repositories::
* Committing code::
@@ -381,8 +533,52 @@ and related components. It is not intended for a general audience.
@end menu
-@node Bug Tracking,Code Repositories,,Fundamentals
-@anchor{taler-developer-manual bug-tracking}@anchor{7}
+@node Testing Tools,Manual Testing Database Reset,,Fundamentals
+@anchor{taler-developer-manual testing-tools}@anchor{7}
+@section Testing Tools
+
+
+For full @code{make check} support, install these programs:
+
+
+@itemize -
+
+@item
+jq@footnote{https://github.com/stedolan/jq}
+
+@item
+curl@footnote{http://curl.haxx.se}
+
+@item
+faketime@footnote{https://github.com/wolfcw/libfaketime}
+@end itemize
+
+The @code{make check} should be able to function without them, but
+their presence permits some tests to run that would otherwise be skipped.
+
+@node Manual Testing Database Reset,Bug Tracking,Testing Tools,Fundamentals
+@anchor{taler-developer-manual manual-testing-database-reset}@anchor{8}
+@section Manual Testing Database Reset
+
+
+Sometimes @code{make check} will fail with some kind of database (SQL)
+error, perhaps with a message like @code{OBJECT does not exist} in the
+@code{test-suite.log} file, where @code{OBJECT} is the name of a table or function.
+In that case, it may be necessary to reset the @code{talercheck} database
+with the commands:
+
+@example
+$ dropdb talercheck
+$ createdb talercheck
+@end example
+
+This is because, at the moment, there is no support for
+doing these steps automatically in the @code{make check} flow.
+
+(If @code{make check} still fails after the reset, file a bug report as usual.)
+
+@node Bug Tracking,Code Repositories,Manual Testing Database Reset,Fundamentals
+@anchor{taler-developer-manual bug-tracking}@anchor{9}
@section Bug Tracking
@@ -392,7 +588,7 @@ needed in order to use the bug tracker, only read access is granted without a
login.
@node Code Repositories,Committing code,Bug Tracking,Fundamentals
-@anchor{taler-developer-manual code-repositories}@anchor{8}
+@anchor{taler-developer-manual code-repositories}@anchor{a}
@section Code Repositories
@@ -407,13 +603,13 @@ A complete list of all the existing repositories is currently found at
@indicateurl{https://git.taler.net/}.
@node Committing code,Observing changes,Code Repositories,Fundamentals
-@anchor{taler-developer-manual committing-code}@anchor{9}
+@anchor{taler-developer-manual committing-code}@anchor{b}
@section Committing code
Before you can obtain Git write access, you must sign the copyright
agreement. As we collaborate closely with GNUnet, we use their
-copyright agreement – with the understanding that your contributions
+copyright agreement -- with the understanding that your contributions
to GNU Taler are included in the assignment. You can find the
agreement on the GNUnet site@footnote{https://gnunet.org/en/copyright.html}.
Please sign and mail it to Christian Grothoff as he currently collects
@@ -476,7 +672,7 @@ $ git pull --rebase -S
@end example
@node Observing changes,Communication,Committing code,Fundamentals
-@anchor{taler-developer-manual observing-changes}@anchor{a}
+@anchor{taler-developer-manual observing-changes}@anchor{c}
@section Observing changes
@@ -489,7 +685,7 @@ it can be high volume, the lists is a good way to follow overall
development.
@node Communication,What to put in bootstrap,Observing changes,Fundamentals
-@anchor{taler-developer-manual communication}@anchor{b}
+@anchor{taler-developer-manual communication}@anchor{d}
@section Communication
@@ -500,7 +696,7 @@ There are separate low-volume mailinglists for gnunet-developers (@@gnu.org)
and for libmicrohttpd (@@gnu.org).
@node What to put in bootstrap,,Communication,Fundamentals
-@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{c}
+@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{e}
@section What to put in bootstrap
@@ -553,7 +749,7 @@ A similar procedure is required for other databases in GANA.
See file @code{README} in the various directories for specific instructions.
@node Debian and Ubuntu Repositories,Language-Specific Guidelines,Fundamentals,Top
-@anchor{taler-developer-manual debian-and-ubuntu-repositories}@anchor{d}
+@anchor{taler-developer-manual debian-and-ubuntu-repositories}@anchor{f}
@chapter Debian and Ubuntu Repositories
@@ -565,7 +761,7 @@ We package our software for Debian and Ubuntu.
@end menu
@node Nightly Repositories,,,Debian and Ubuntu Repositories
-@anchor{taler-developer-manual nightly-repositories}@anchor{e}
+@anchor{taler-developer-manual nightly-repositories}@anchor{10}
@section Nightly Repositories
@@ -584,7 +780,7 @@ $ wget -O - https://taler.net/taler-systems-nightly.gpg.key | apt-key add -
@end example
@node Language-Specific Guidelines,Taler Deployment on gv taler net,Debian and Ubuntu Repositories,Top
-@anchor{taler-developer-manual language-specific-guidelines}@anchor{f}
+@anchor{taler-developer-manual language-specific-guidelines}@anchor{11}
@chapter Language-Specific Guidelines
@@ -596,7 +792,7 @@ Python Guidelines
@end itemize
@node Taler Deployment on gv taler net,Demo Upgrade Procedure,Language-Specific Guidelines,Top
-@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{10}
+@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{12}
@chapter Taler Deployment on gv.taler.net
@@ -617,7 +813,7 @@ Taler payments at BFH in the future.
@end menu
@node DNS,User Acccounts,,Taler Deployment on gv taler net
-@anchor{taler-developer-manual dns}@anchor{11}
+@anchor{taler-developer-manual dns}@anchor{13}
@section DNS
@@ -626,7 +822,7 @@ maintainers, specifically Christian and Florian. If you
need a sub-domain to be added, please contact one of them.
@node User Acccounts,,DNS,Taler Deployment on gv taler net
-@anchor{taler-developer-manual user-acccounts}@anchor{12}
+@anchor{taler-developer-manual user-acccounts}@anchor{14}
@section User Acccounts
@@ -662,13 +858,13 @@ user can be switched to become active (see next section), and vice versa.
@end itemize
@node Demo Upgrade Procedure,Environments and Builders on taler net,Taler Deployment on gv taler net,Top
-@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{13}
+@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{15}
@chapter Demo Upgrade Procedure
Upgrading the @code{demo} environment should be done with care, and ideally be
coordinated on the mailing list before. It is our goal for @code{demo} to always
-run a “working version” that is compatible with various published wallets.
+run a "working version" that is compatible with various published wallets.
Before deploying on @code{demo}, the same version of all components @strong{must}
be deployed @emph{and} tested on @code{int}.
@@ -687,7 +883,7 @@ sure everything is working.
@end menu
@node Tagging components,Environment Layout,,Demo Upgrade Procedure
-@anchor{taler-developer-manual tagging-components}@anchor{14}
+@anchor{taler-developer-manual tagging-components}@anchor{16}
@section Tagging components
@@ -703,7 +899,7 @@ SS = serial
@end example
@node Environment Layout,Using envcfg py,Tagging components,Demo Upgrade Procedure
-@anchor{taler-developer-manual environment-layout}@anchor{15}
+@anchor{taler-developer-manual environment-layout}@anchor{17}
@section Environment Layout
@@ -726,7 +922,7 @@ On @code{demo-blue} and @code{demo-green}, @code{taler-data} is a symlink pointi
instead of a directory.
@node Using envcfg py,Bootstrapping an Environment,Environment Layout,Demo Upgrade Procedure
-@anchor{taler-developer-manual using-envcfg-py}@anchor{16}
+@anchor{taler-developer-manual using-envcfg-py}@anchor{18}
@section Using envcfg.py
@@ -757,7 +953,7 @@ Currently only the variables @code{env} and @code{tag_$@{component@}} are used.
When deploying to @code{demo}, the @code{envcfg.py} should be committed to @code{deployment.git/envcfg/envcfg-demo-YYYY-MM-DD-SS.py}.
@node Bootstrapping an Environment,Upgrading an Existing Environment,Using envcfg py,Demo Upgrade Procedure
-@anchor{taler-developer-manual bootstrapping-an-environment}@anchor{17}
+@anchor{taler-developer-manual bootstrapping-an-environment}@anchor{19}
@section Bootstrapping an Environment
@@ -775,7 +971,7 @@ $ taler-config-instances
@end example
@node Upgrading an Existing Environment,Switching Demo Colors,Bootstrapping an Environment,Demo Upgrade Procedure
-@anchor{taler-developer-manual upgrading-an-existing-environment}@anchor{18}
+@anchor{taler-developer-manual upgrading-an-existing-environment}@anchor{1a}
@section Upgrading an Existing Environment
@@ -791,7 +987,7 @@ $ taler-deployment-arm -I # check everything works
@end example
@node Switching Demo Colors,,Upgrading an Existing Environment,Demo Upgrade Procedure
-@anchor{taler-developer-manual switching-demo-colors}@anchor{19}
+@anchor{taler-developer-manual switching-demo-colors}@anchor{1b}
@section Switching Demo Colors
@@ -803,7 +999,7 @@ $ taler-deployment switch-demo
@end example
@node Environments and Builders on taler net,Releases,Demo Upgrade Procedure,Top
-@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{1a}
+@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{1c}
@chapter Environments and Builders on taler.net
@@ -820,7 +1016,7 @@ $ taler-deployment switch-demo
@end menu
@node Buildbot implementation,Documentation Builder,,Environments and Builders on taler net
-@anchor{taler-developer-manual buildbot-implementation}@anchor{1b}
+@anchor{taler-developer-manual buildbot-implementation}@anchor{1d}
@section Buildbot implementation
@@ -838,7 +1034,7 @@ The WORKER is the config that that lives on a shell account on a localhost (tale
The WORKER running buildbot-worker receives these commands by authenticating and communicating with the buildbot server using parameters that were specified when the worker was created in that shell account with the @code{buildbot-worker} command.
@item
-The buildbot server’s master.cfg file contains FACTORY declarations which specify the commands that the WORKER will run on localhost.
+The buildbot server's master.cfg file contains FACTORY declarations which specify the commands that the WORKER will run on localhost.
@item
The FACTORY is tied to the WORKER in master.cfg by a BUILDER.
@@ -856,7 +1052,7 @@ Best Practices:
@itemize -
@item
-When creating a new WORKER in the @code{master.cfg} file, leave a comment specifying the server and user account that this WORKER is called from. (At this time, taler.net is the only server used by this implementation, but it’s still good practice.)
+When creating a new WORKER in the @code{master.cfg} file, leave a comment specifying the server and user account that this WORKER is called from. (At this time, taler.net is the only server used by this implementation, but it's still good practice.)
@item
Create a worker from a shell account with this command: @code{buildbot-worker create-worker <workername> localhost <username> <password>}
@@ -865,7 +1061,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 Documentation Builder,Website Builder,Buildbot implementation,Environments and Builders on taler net
-@anchor{taler-developer-manual documentation-builder}@anchor{1c}
+@anchor{taler-developer-manual documentation-builder}@anchor{1e}
@section Documentation Builder
@@ -887,7 +1083,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{1d}
+@anchor{taler-developer-manual website-builder}@anchor{1f}
@section Website Builder
@@ -909,7 +1105,7 @@ $ buildbot-worker start worker/
@end example
@node Code coverage,Service Checker,Website Builder,Environments and Builders on taler net
-@anchor{taler-developer-manual code-coverage}@anchor{1e}
+@anchor{taler-developer-manual code-coverage}@anchor{20}
@section Code coverage
@@ -932,7 +1128,7 @@ $ buildbot-worker start worker/
The results are then published at @code{https://lcov.taler.net/}.
@node Service Checker,Tipping reserve top-up,Code coverage,Environments and Builders on taler net
-@anchor{taler-developer-manual service-checker}@anchor{1f}
+@anchor{taler-developer-manual service-checker}@anchor{21}
@section Service Checker
@@ -954,11 +1150,11 @@ $ buildbot-worker start worker/
@end example
@node Tipping reserve top-up,Producing auditor reports,Service Checker,Environments and Builders on taler net
-@anchor{taler-developer-manual tipping-reserve-top-up}@anchor{20}
+@anchor{taler-developer-manual tipping-reserve-top-up}@anchor{22}
@section Tipping reserve top-up
-Both ‘test’ and ‘demo’ setups get their tip reserve topped up
+Both 'test' and 'demo' setups get their tip reserve topped up
by a Buildbot worker. The following steps get the reserve topper
prepared.
@@ -975,11 +1171,11 @@ $ buildbot-worker start worker/
@end example
@node Producing auditor reports,Database schema versioning,Tipping reserve top-up,Environments and Builders on taler net
-@anchor{taler-developer-manual producing-auditor-reports}@anchor{21}
+@anchor{taler-developer-manual producing-auditor-reports}@anchor{23}
@section Producing auditor reports
-Both ‘test’ and ‘demo’ setups get their auditor reports compiled
+Both 'test' and 'demo' setups get their auditor reports compiled
by a Buildbot worker. The following steps get the reports compiler
prepared.
@@ -996,7 +1192,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{22}
+@anchor{taler-developer-manual database-schema-versioning}@anchor{24}
@section Database schema versioning
@@ -1012,7 +1208,7 @@ Developers and operators MUST NOT make changes to database schema
outside of this versioning.
@node Releases,Continuous integration,Environments and Builders on taler net,Top
-@anchor{taler-developer-manual releases}@anchor{23}
+@anchor{taler-developer-manual releases}@anchor{25}
@chapter Releases
@@ -1028,7 +1224,7 @@ outside of this versioning.
@end menu
@node Release Process and Checklists,Tagging,,Releases
-@anchor{taler-developer-manual release-process-and-checklists}@anchor{24}
+@anchor{taler-developer-manual release-process-and-checklists}@anchor{26}
@section Release Process and Checklists
@@ -1062,7 +1258,7 @@ taler-wallet-webex (wallet-webex.git)
@end itemize
@node Tagging,Database for tests,Release Process and Checklists,Releases
-@anchor{taler-developer-manual tagging}@anchor{25}
+@anchor{taler-developer-manual tagging}@anchor{27}
@section Tagging
@@ -1074,7 +1270,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{26}
+@anchor{taler-developer-manual database-for-tests}@anchor{28}
@section Database for tests
@@ -1092,7 +1288,7 @@ unauthorized access.
@end cartouche
@node Exchange merchant,Wallet WebExtension,Database for tests,Releases
-@anchor{taler-developer-manual exchange-merchant}@anchor{27}
+@anchor{taler-developer-manual exchange-merchant}@anchor{29}
@section Exchange, merchant
@@ -1139,7 +1335,7 @@ For bootstrap, you will need to install
GNU Recutils@footnote{https://www.gnu.org/software/recutils/}.
For the exchange test cases to pass, @code{make install} must be run first.
-Without it, test cases will fail because plugins can’t be located.
+Without it, test cases will fail because plugins can't be located.
@example
$ ./bootstrap
@@ -1151,7 +1347,7 @@ $ make install check
@end example
@node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases
-@anchor{taler-developer-manual wallet-webextension}@anchor{28}
+@anchor{taler-developer-manual wallet-webextension}@anchor{2a}
@section Wallet WebExtension
@@ -1165,7 +1361,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{29}
+@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{2b}
@section Upload to GNU mirrors
@@ -1182,7 +1378,7 @@ filename: taler-exchange-0.1.0.tar.gz
Upload the files in @strong{binary mode} to the ftp servers.
@node Creating Debian packages,,Upload to GNU mirrors,Releases
-@anchor{taler-developer-manual creating-debian-packages}@anchor{2a}
+@anchor{taler-developer-manual creating-debian-packages}@anchor{2c}
@section Creating Debian packages
@@ -1219,7 +1415,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{2b}
+@anchor{taler-developer-manual continuous-integration}@anchor{2d}
@chapter Continuous integration
@@ -1227,21 +1423,21 @@ CI is done with Buildbot (@indicateurl{https://buildbot.net/}), and builds are
triggered by the means of Git hooks. The results are published at
@indicateurl{https://buildbot.taler.net/} .
-In order to avoid downtimes, CI uses a “blue/green” deployment
+In order to avoid downtimes, CI uses a "blue/green" deployment
technique. In detail, there are two users building code on the system,
-the “green” and the “blue” user; and at any given time, one is running
+the "green" and the "blue" user; and at any given time, one is running
Taler services and the other one is either building the code or waiting
for that.
There is also the possibility to trigger builds manually, but this is
-only reserved to “admin” users.
+only reserved to "admin" users.
@node Internationalization,Android Apps,Continuous integration,Top
-@anchor{taler-developer-manual internationalization}@anchor{2c}
+@anchor{taler-developer-manual internationalization}@anchor{2e}
@chapter Internationalization
-Internationalization (a.k.a “Translation”) is handled with Weblate (@indicateurl{https://weblate.org}) via our instance at @indicateurl{https://weblate.taler.net/} .
+Internationalization (a.k.a "Translation") is handled with Weblate (@indicateurl{https://weblate.org}) via our instance at @indicateurl{https://weblate.taler.net/} .
At this time, this system is still very new for Taler.net and this documentation may be incorrect and is certainly incomplete.
@@ -1258,14 +1454,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{2d}
+@anchor{taler-developer-manual who-can-register}@anchor{2f}
@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 @strong{Users} and @strong{Viewers} privilege level.
@node About Privilege Levels,Upgrading Privileges,Who can Register,Internationalization
-@anchor{taler-developer-manual about-privilege-levels}@anchor{2e}
+@anchor{taler-developer-manual about-privilege-levels}@anchor{30}
@section About Privilege Levels
@@ -1288,21 +1484,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{2f}
+@anchor{taler-developer-manual upgrading-privileges}@anchor{31}
@section Upgrading Privileges
To upgrade from @strong{Users}/@strong{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{30}
+@anchor{taler-developer-manual how-to-create-a-project}@anchor{32}
@section How to Create a Project
The @emph{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{31}
+@anchor{taler-developer-manual how-to-create-a-component}@anchor{33}
@section How to Create a Component
@@ -1329,7 +1525,7 @@ Under @emph{https://weblate.taler.net/create/component/vcs/}:
@strong{Repository push URL} - This is generally @code{git+ssh://git@@git.taler.net/<reponame>`} Check with @code{git remote -v}.
@item
-@strong{Repository browser} - This is the www URL of the Git repo’s file browser. Example @code{https://git.taler.net/<repositoryname>.git/tree/@{@{filename@}@}?h=@{@{branch@}@}#n@{@{line@}@}} where @code{<repositoryname>} gets replaced but @code{@{@{filename@}@}} and other items in braces are actual variables in the string.
+@strong{Repository browser} - This is the www URL of the Git repo's file browser. Example @code{https://git.taler.net/<repositoryname>.git/tree/@{@{filename@}@}?h=@{@{branch@}@}#n@{@{line@}@}} where @code{<repositoryname>} gets replaced but @code{@{@{filename@}@}} and other items in braces are actual variables in the string.
@item
@strong{Merge style} - @emph{Rebase}, in line with GNU Taler development procedures
@@ -1342,7 +1538,7 @@ Under @emph{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{32}
+@anchor{taler-developer-manual how-to-create-a-translation}@anchor{34}
@section How to Create a Translation
@@ -1354,34 +1550,34 @@ Under @emph{https://weblate.taler.net/create/component/vcs/}:
4 - Choose the @emph{Component} you wish to contribute to.
-5 - Find the language you want to translate into. Click “Translate” on that line.
+5 - Find the language you want to translate into. Click "Translate" on that line.
6 - Find a phrase and translate it.
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{33}
+@anchor{taler-developer-manual translation-standards-and-practices}@anchor{35}
@section Translation Standards and Practices
-By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the @emph{Component} you want to translate for, and click “Start new translation” to begin. If you require a privilege upgrade, please contact a superuser with your request.
+By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the @emph{Component} you want to translate for, and click "Start new translation" to begin. If you require a privilege upgrade, please contact a superuser with your request.
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{34}
+@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{36}
@section GPG Signing of Translations
weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at @indicateurl{https://weblate.taler.net/keys/}.
-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.
+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 Android Apps,Code Coverage,Internationalization,Top
-@anchor{taler-developer-manual android-apps}@anchor{35}
+@anchor{taler-developer-manual android-apps}@anchor{37}
@chapter Android Apps
@@ -1394,7 +1590,7 @@ This means that contributions made through weblate will not be signed with the i
@end menu
@node Android App Nightly Builds,Building apps from source,,Android Apps
-@anchor{taler-developer-manual android-app-nightly-builds}@anchor{36}
+@anchor{taler-developer-manual android-app-nightly-builds}@anchor{38}
@section Android App Nightly Builds
@@ -1419,7 +1615,7 @@ Cashier
Their git repositories are mirrored at Gitlab@footnote{https://gitlab.com/gnu-taler/taler-android}
to utilize their CI
-and F-Droid@footnote{https://f-droid.org}’s Gitlab integration
+and F-Droid@footnote{https://f-droid.org}'s Gitlab integration
to publish automatic nightly builds@footnote{https://f-droid.org/docs/Publishing_Nightly_Builds/}
for each change on the @code{master} branch.
@@ -1445,7 +1641,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{37}@anchor{taler-developer-manual building-apps-from-source}@anchor{38}
+@anchor{taler-developer-manual build-apps-from-source}@anchor{39}@anchor{taler-developer-manual building-apps-from-source}@anchor{3a}
@section Building apps from source
@@ -1469,7 +1665,7 @@ git
unzip
@end itemize
-Then you can get the app’s source code using git:
+Then you can get the app's source code using git:
@example
# Start by cloning the Android git repository
@@ -1486,12 +1682,12 @@ The last command will return something like @code{compileSdkVersion 29}.
So visit the Android Rebuilds@footnote{http://android-rebuilds.beuc.net/} project
and look for that version of the Android SDK there.
If the SDK version is not yet available as a free rebuild,
-you can try to lower the @code{compileSdkVersion} in the app’s @code{merchant-terminal/build.gradle} file.
+you can try to lower the @code{compileSdkVersion} in the app's @code{merchant-terminal/build.gradle} file.
Note that this might break things
or require you to also lower other versions such as @code{targetSdkVersion}.
In our example, the version is @code{29} which is available,
-so download the “SDK Platform” package of “Android 10.0.0 (API 29)”
+so download the "SDK Platform" package of "Android 10.0.0 (API 29)"
and unpack it:
@example
@@ -1524,18 +1720,18 @@ build-tools;29.0.3 Android SDK Build-Tools 29.0.3
@end table
@end quotation
-you can try changing the @code{buildToolsVersion} in the app’s @code{merchant-terminal/build.gradle} file
-to the latest “Android SDK build tools” version supported by the Android Rebuilds project.
+you can try changing the @code{buildToolsVersion} in the app's @code{merchant-terminal/build.gradle} file
+to the latest "Android SDK build tools" version supported by the Android Rebuilds project.
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{39}
+@anchor{taler-developer-manual update-translations}@anchor{3b}
@section Update translations
-Translations are managed with Taler’s weblate instance:
+Translations are managed with Taler's weblate instance:
@indicateurl{https://weblate.taler.net/projects/gnu-taler/}
To update translations, enter the taler-android git repository
@@ -1565,7 +1761,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 release-process}@anchor{3a}
+@anchor{taler-developer-manual release-process}@anchor{3c}
@section Release process
@@ -1596,12 +1792,12 @@ $ git tag -s $APP-$VERSION
@end menu
@node F-Droid,Google Play,,Release process
-@anchor{taler-developer-manual id1}@anchor{3b}
+@anchor{taler-developer-manual id1}@anchor{3d}
@subsection F-Droid
Nightly builds get published automatically (see above) after pushing code to the official repo.
-Actual releases get picked up by F-Droid’s official repository via git tags.
+Actual releases get picked up by F-Droid's official repository via git tags.
So ensure that all releases get tagged properly.
Some information for F-Droid official repository debugging:
@@ -1620,7 +1816,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{3c}
+@anchor{taler-developer-manual google-play}@anchor{3e}
@subsection Google Play
@@ -1642,7 +1838,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 id2}@anchor{3d}@anchor{taler-developer-manual id3}@anchor{3e}
+@anchor{taler-developer-manual id2}@anchor{3f}@anchor{taler-developer-manual id3}@anchor{40}
@chapter Code Coverage
@@ -1652,7 +1848,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{3f}
+@anchor{taler-developer-manual coding-conventions}@anchor{41}
@chapter Coding Conventions
@@ -1667,7 +1863,7 @@ GNU Taler is developed primarily in C, Kotlin, Python and TypeScript.
@end menu
@node Components written in C,Shell Scripts,,Coding Conventions
-@anchor{taler-developer-manual components-written-in-c}@anchor{40}
+@anchor{taler-developer-manual components-written-in-c}@anchor{42}
@section Components written in C
@@ -1687,7 +1883,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{41}
+@anchor{taler-developer-manual naming-conventions}@anchor{43}
@subsection Naming conventions
@@ -1701,22 +1897,22 @@ include files (very similar to GNUnet):
@itemize *
@item
-if installed, must start with “@code{taler_}” (exception: platform.h),
+if installed, must start with "@code{taler_}" (exception: platform.h),
and MUST live in src/include/
@item
-if NOT installed, must NOT start with “@code{taler_}” and
+if NOT installed, must NOT start with "@code{taler_}" and
MUST NOT live in src/include/ and
SHOULD NOT be included from outside of their own directory
@item
-end in “_lib” for “simple” libraries
+end in "_lib" for "simple" libraries
@item
-end in “_plugin” for plugins
+end in "_plugin" for plugins
@item
-end in “_service” for libraries accessing a service, i.e. the exchange
+end in "_service" for libraries accessing a service, i.e. the exchange
@end itemize
@item
@@ -1749,22 +1945,22 @@ logging
@item
tools use their full name in GNUNET_log_setup
-(i.e. ‘taler-exchange-offline’) and log using plain ‘GNUNET_log’.
+(i.e. 'taler-exchange-offline') and log using plain 'GNUNET_log'.
@item
-pure libraries (without associated service) use ‘GNUNET_log_from’
-with the component set to their library name (without lib or ‘.so’),
-which should also be their directory name (i.e. ‘util’)
+pure libraries (without associated service) use 'GNUNET_log_from'
+with the component set to their library name (without lib or '.so'),
+which should also be their directory name (i.e. 'util')
@item
-plugin libraries (without associated service) use ‘GNUNET_log_from’
-with the component set to their type and plugin name (without lib or ‘.so’),
-which should also be their directory name (i.e. ‘exchangedb-postgres’)
+plugin libraries (without associated service) use 'GNUNET_log_from'
+with the component set to their type and plugin name (without lib or '.so'),
+which should also be their directory name (i.e. 'exchangedb-postgres')
@item
-libraries with associated service) use ‘GNUNET_log_from’
+libraries with associated service) use 'GNUNET_log_from'
with the name of the service, which should also be their
-directory name (i.e. ‘exchange’)
+directory name (i.e. 'exchange')
@item
for tools with @code{-l LOGFILE}, its absence means write logs to stderr
@@ -1806,14 +2002,14 @@ structs:
@itemize *
@item
-structs that are ‘packed’ and do not contain pointers and are
+structs that are 'packed' and do not contain pointers and are
thus suitable for hashing or similar operations are distinguished
-by adding a “P” at the end of the name. (NEW) Note that this
+by adding a "P" at the end of the name. (NEW) Note that this
convention does not hold for the GNUnet-structs (yet).
@item
structs that are used with a purpose for signatures, additionally
-get an “S” at the end of the name.
+get an "S" at the end of the name.
@end itemize
@item
@@ -1833,7 +2029,7 @@ testcases
@itemize *
@item
-must be called “test_module-under-test_case-description.c”
+must be called "test_module-under-test_case-description.c"
@end itemize
@item
@@ -1843,12 +2039,12 @@ performance tests
@itemize *
@item
-must be called “perf_module-under-test_case-description.c”
+must be called "perf_module-under-test_case-description.c"
@end itemize
@end itemize
@node Shell Scripts,Kotlin,Components written in C,Coding Conventions
-@anchor{taler-developer-manual shell-scripts}@anchor{42}
+@anchor{taler-developer-manual shell-scripts}@anchor{44}
@section Shell Scripts
@@ -1875,7 +2071,7 @@ $ set -eu
@end example
@node Kotlin,Python,Shell Scripts,Coding Conventions
-@anchor{taler-developer-manual kotlin}@anchor{43}
+@anchor{taler-developer-manual kotlin}@anchor{45}
@section Kotlin
@@ -1883,7 +2079,7 @@ We so far have no specific guidelines, please follow best practices
for the language.
@node Python,,Kotlin,Coding Conventions
-@anchor{taler-developer-manual python}@anchor{44}
+@anchor{taler-developer-manual python}@anchor{46}
@section Python
@@ -1895,14 +2091,14 @@ for the language.
@end menu
@node Supported Python Versions,Style,,Python
-@anchor{taler-developer-manual supported-python-versions}@anchor{45}
+@anchor{taler-developer-manual supported-python-versions}@anchor{47}
@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{46}
+@anchor{taler-developer-manual style}@anchor{48}
@subsection Style
@@ -1912,7 +2108,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{47}
+@anchor{taler-developer-manual python-for-scripting}@anchor{49}
@subsection Python for Scripting
@@ -1929,12 +2125,12 @@ are useful:
@code{pathlib} for path manipulation (part of the standard library)
@item
-@code{subprocess} for “shelling out” to other programs. Prefer @code{subprocess.run}
+@code{subprocess} for "shelling out" to other programs. Prefer @code{subprocess.run}
over the older APIs.
@end itemize
@node Testing library,User-Facing Terminology,Coding Conventions,Top
-@anchor{taler-developer-manual testing-library}@anchor{48}
+@anchor{taler-developer-manual testing-library}@anchor{4a}
@chapter Testing library
@@ -2007,7 +2203,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{49}
+@anchor{taler-developer-manual user-facing-terminology}@anchor{4b}
@chapter User-Facing Terminology
@@ -2021,7 +2217,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{4a}
+@anchor{taler-developer-manual terms-to-avoid}@anchor{4c}
@section Terms to Avoid
@@ -2033,14 +2229,14 @@ used in the user interface and help materials.
Refreshing is the internal technical terminology for the protocol to
give change for partially spent coins
-@strong{Use instead}: “Obtaining change”
+@strong{Use instead}: "Obtaining change"
@item Coin
Coins are an internal construct, the user should never be aware that their balance
is represented by coins if different denominations.
-@strong{Use instead}: “(Digital) Cash” or “(Wallet) Balance”
+@strong{Use instead}: "(Digital) Cash" or "(Wallet) Balance"
@item Consumer
@@ -2055,7 +2251,7 @@ of the signed contract terms for an order.
@strong{Avoid}. Generally events that relate to proposal downloads
should not be shown to normal users, only developers. Instead, use
-“communication with mechant failed” if a proposed order can’t be downloaded.
+"communication with mechant failed" if a proposed order can't be downloaded.
@item Anonymous E-Cash
@@ -2063,14 +2259,14 @@ Should be generally avoided, since Taler is only anonymous for
the customer. Also some people are scared of anonymity (which as
a term is also way too absolute, as anonymity is hardly ever perfect).
-@strong{Use instead}: “Privacy-preserving”, “Privacy-friendly”
+@strong{Use instead}: "Privacy-preserving", "Privacy-friendly"
@item Payment Replay
The process of proving to the merchant that the customer is entitled
to view a digital product again, as they already paid for it.
-@strong{Use instead}: In the event history, “re-activated digital content purchase”
+@strong{Use instead}: In the event history, "re-activated digital content purchase"
could be used. (FIXME: this is still not nice.)
@item Session ID
@@ -2090,7 +2286,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{4b}
+@anchor{taler-developer-manual terms-to-use}@anchor{4d}
@section Terms to Use
@@ -2106,16 +2302,16 @@ Regulatory entity that certifies exchanges and oversees their operation.
The entity/service that gives out digital cash in exchange for some
other means of payment.
-In some contexts, using “Issuer” could also be appropriate.
+In some contexts, using "Issuer" could also be appropriate.
When showing a balance breakdown,
-we can say “100 Eur (issued by exchange.euro.taler.net)”.
-Sometimes we may also use the more generic term “Payment Service Provider”
-when the concept of an “Exchange” is still unclear to the reader.
+we can say "100 Eur (issued by exchange.euro.taler.net)".
+Sometimes we may also use the more generic term "Payment Service Provider"
+when the concept of an "Exchange" is still unclear to the reader.
@item Refund
-A refund is given by a merchant to the customer (rather the customer’s wallet)
-and “undoes” a previous payment operation.
+A refund is given by a merchant to the customer (rather the customer's wallet)
+and "undoes" a previous payment operation.
@item Payment
@@ -2123,12 +2319,12 @@ The act of sending digital cash to a merchant to pay for an order.
@item Purchase
-Used to refer to the “result” of a payment, as in “view purchase”.
-Use sparsingly, as the word doesn’t fit for all payments, such as donations.
+Used to refer to the "result" of a payment, as in "view purchase".
+Use sparsingly, as the word doesn't fit for all payments, such as donations.
@item Contract Terms
-Partially machine-readable representation of the merchant’s obligation after the
+Partially machine-readable representation of the merchant's obligation after the
customer makes a payment.
@item Merchant
@@ -2137,12 +2333,12 @@ Party that receives a payment.
@item Wallet
-Also “Taler Wallet”. Software component that manages the user’s digital cash
+Also "Taler Wallet". Software component that manages the user's digital cash
and payments.
@end table
@node Developer Glossary,Developer Tools,User-Facing Terminology,Top
-@anchor{taler-developer-manual developer-glossary}@anchor{4c}
+@anchor{taler-developer-manual developer-glossary}@anchor{4e}
@chapter Developer Glossary
@@ -2151,168 +2347,168 @@ use when talking to end users or even system administrators.
@table @asis
-@anchor{taler-developer-manual term-absolute-time}@anchor{4d}
+@anchor{taler-developer-manual term-absolute-time}@anchor{4f}
@geindex absolute time
@item absolute time
-method of keeping time in @ref{4e,,GNUnet} where the time is represented
+method of keeping time in @ref{50,,GNUnet} where the time is represented
as the number of microseconds since 1.1.1970 (UNIX epoch). Called
-absolute time in contrast to @ref{4f,,relative time}.
-@anchor{taler-developer-manual term-aggregate}@anchor{50}
+absolute time in contrast to @ref{51,,relative time}.
+@anchor{taler-developer-manual term-aggregate}@anchor{52}
@geindex aggregate
@item aggregate
-the @ref{51,,exchange} combines multiple payments received by the
-same @ref{52,,merchant} into one larger @ref{53,,wire transfer} to
-the respective merchant’s @ref{54,,bank} account
-@anchor{taler-developer-manual term-auditor}@anchor{55}
+the @ref{53,,exchange} combines multiple payments received by the
+same @ref{54,,merchant} into one larger @ref{55,,wire transfer} to
+the respective merchant's @ref{56,,bank} account
+@anchor{taler-developer-manual term-auditor}@anchor{57}
@geindex auditor
@item auditor
-trusted third party that verifies that the @ref{51,,exchange} is operating correctly
-@anchor{taler-developer-manual term-bank}@anchor{54}
+trusted third party that verifies that the @ref{53,,exchange} is operating correctly
+@anchor{taler-developer-manual term-bank}@anchor{56}
@geindex bank
@item bank
-traditional financial service provider who offers wire @ref{56,,transfers} between accounts
-@anchor{taler-developer-manual term-buyer}@anchor{57}
+traditional financial service provider who offers wire @ref{58,,transfers} between accounts
+@anchor{taler-developer-manual term-buyer}@anchor{59}
@geindex buyer
@item buyer
-individual in control of a Taler @ref{58,,wallet}, usually using it to
-@ref{59,,spend} the @ref{5a,,coins} on @ref{5b,,contracts} (see also @ref{5c,,customer}).
-@anchor{taler-developer-manual term-close}@anchor{5d}
+individual in control of a Taler @ref{5a,,wallet}, usually using it to
+@ref{5b,,spend} the @ref{5c,,coins} on @ref{5d,,contracts} (see also @ref{5e,,customer}).
+@anchor{taler-developer-manual term-close}@anchor{5f}
@geindex close
-@item close@anchor{taler-developer-manual term-closes}@anchor{5e}
+@item close@anchor{taler-developer-manual term-closes}@anchor{60}
@geindex closes
-@itemx closes@anchor{taler-developer-manual term-closed}@anchor{5f}
+@itemx closes@anchor{taler-developer-manual term-closed}@anchor{61}
@geindex closed
-@itemx closed@anchor{taler-developer-manual term-closing}@anchor{60}
+@itemx closed@anchor{taler-developer-manual term-closing}@anchor{62}
@geindex closing
@itemx closing
-operation an @ref{51,,exchange} performs on a @ref{61,,reserve} that has not been
-@ref{62,,drained} by @ref{63,,withdraw} operations. When closing a reserve, the
-exchange wires the remaining funds back to the customer, minus a @ref{64,,fee}
+operation an @ref{53,,exchange} performs on a @ref{63,,reserve} that has not been
+@ref{64,,drained} by @ref{65,,withdraw} operations. When closing a reserve, the
+exchange wires the remaining funds back to the customer, minus a @ref{66,,fee}
for closing
-@anchor{taler-developer-manual term-coin}@anchor{65}
+@anchor{taler-developer-manual term-coin}@anchor{67}
@geindex coin
-@item coin@anchor{taler-developer-manual term-coins}@anchor{5a}
+@item coin@anchor{taler-developer-manual term-coins}@anchor{5c}
@geindex coins
@itemx coins
-coins are individual token representing a certain amount of value, also known as the @ref{66,,denomination} of the coin
-@anchor{taler-developer-manual term-commitment}@anchor{67}
+coins are individual token representing a certain amount of value, also known as the @ref{68,,denomination} of the coin
+@anchor{taler-developer-manual term-commitment}@anchor{69}
@geindex commitment
-@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{68}
+@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{6a}
@geindex refresh commitment
@itemx refresh commitment
-data that the wallet commits to during the @ref{69,,melt} stage of the
-@ref{6a,,refresh} protocol where it
-has to prove to the @ref{51,,exchange} that it is deriving the @ref{6b,,fresh}
+data that the wallet commits to during the @ref{6b,,melt} stage of the
+@ref{6c,,refresh} protocol where it
+has to prove to the @ref{53,,exchange} that it is deriving the @ref{6d,,fresh}
coins as specified by the Taler protocol. The commitment is verified
-probabilistically (see: @ref{6c,,kappa}) during the @ref{6d,,reveal} stage.
-@anchor{taler-developer-manual term-contract}@anchor{6e}
+probabilistically (see: @ref{6e,,kappa}) during the @ref{6f,,reveal} stage.
+@anchor{taler-developer-manual term-contract}@anchor{70}
@geindex contract
-@item contract@anchor{taler-developer-manual term-contracts}@anchor{5b}
+@item contract@anchor{taler-developer-manual term-contracts}@anchor{5d}
@geindex contracts
@itemx contracts
-formal agreement between @ref{52,,merchant} and @ref{5c,,customer} specifying the
-@ref{6f,,contract terms} and signed by the merchant and the @ref{5a,,coins} of the
+formal agreement between @ref{54,,merchant} and @ref{5e,,customer} specifying the
+@ref{71,,contract terms} and signed by the merchant and the @ref{5c,,coins} of the
customer
-@anchor{taler-developer-manual term-contract-terms}@anchor{6f}
+@anchor{taler-developer-manual term-contract-terms}@anchor{71}
@geindex contract terms
@item contract terms
the individual clauses specifying what the buyer is purchasing from the
-@ref{52,,merchant}
-@anchor{taler-developer-manual term-customer}@anchor{5c}
+@ref{54,,merchant}
+@anchor{taler-developer-manual term-customer}@anchor{5e}
@geindex customer
@item customer
individual that directs the buyer (perhaps the same individual) to make a purchase
-@anchor{taler-developer-manual term-denomination}@anchor{66}
+@anchor{taler-developer-manual term-denomination}@anchor{68}
@geindex denomination
@item denomination
-unit of currency, specifies both the currency and the face value of a @ref{65,,coin},
+unit of currency, specifies both the currency and the face value of a @ref{67,,coin},
as well as associated fees and validity periods
-@anchor{taler-developer-manual term-denomination-key}@anchor{70}
+@anchor{taler-developer-manual term-denomination-key}@anchor{72}
@geindex denomination key
@item denomination key
-(RSA) key used by the exchange to certify that a given @ref{65,,coin} is valid and of a
-particular @ref{66,,denomination}
-@anchor{taler-developer-manual term-deposit}@anchor{71}
+(RSA) key used by the exchange to certify that a given @ref{67,,coin} is valid and of a
+particular @ref{68,,denomination}
+@anchor{taler-developer-manual term-deposit}@anchor{73}
@geindex deposit
-@item deposit@anchor{taler-developer-manual term-deposits}@anchor{72}
+@item deposit@anchor{taler-developer-manual term-deposits}@anchor{74}
@geindex deposits
-@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{73}
+@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{75}
@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{50,,aggregate} @ref{53,,wire transfer}
-@anchor{taler-developer-manual term-dirty}@anchor{74}
+@ref{52,,aggregate} @ref{55,,wire transfer}
+@anchor{taler-developer-manual term-dirty}@anchor{76}
@geindex dirty
-@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{75}
+@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{77}
@geindex dirty coin
@itemx dirty coin
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{76}
+link multiple transactions of coin's owner if the coin is not refreshed
+@anchor{taler-developer-manual term-drain}@anchor{78}
@geindex drain
-@item drain@anchor{taler-developer-manual term-drained}@anchor{62}
+@item drain@anchor{taler-developer-manual term-drained}@anchor{64}
@geindex drained
@itemx drained
-a @ref{61,,reserve} is being drained when a @ref{58,,wallet} is using the
-reserve’s private key to @ref{63,,withdraw} coins from it. This reduces
+a @ref{63,,reserve} is being drained when a @ref{5a,,wallet} is using the
+reserve's private key to @ref{65,,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{5f,,closed} by the exchange.
-@anchor{taler-developer-manual term-exchange}@anchor{51}
+(which is the normal process) are @ref{61,,closed} by the exchange.
+@anchor{taler-developer-manual term-exchange}@anchor{53}
@geindex exchange
@item exchange
-Taler’s payment service operator. Issues electronic coins during
+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{77}
+@anchor{taler-developer-manual term-expired}@anchor{79}
@geindex expired
-@item expired@anchor{taler-developer-manual term-expiration}@anchor{78}
+@item expired@anchor{taler-developer-manual term-expiration}@anchor{7a}
@geindex expiration
@itemx expiration
@@ -2321,52 +2517,52 @@ Various operations come with time limits. In particular, denomination keys
come with strict time limits for the various operations involving the
coin issued under the denomination. The most important limit is the
deposit expiration, which specifies until when wallets are allowed to
-use the coin in deposit or refreshing operations. There is also a “legal”
+use the coin in deposit or refreshing operations. There is also a "legal"
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{79}
+@anchor{taler-developer-manual term-fakebank}@anchor{7b}
@geindex fakebank
@item fakebank
-implementation of the @ref{54,,bank} API in memory to be used only for test
+implementation of the @ref{56,,bank} API in memory to be used only for test
cases.
-@anchor{taler-developer-manual term-fee}@anchor{64}
+@anchor{taler-developer-manual term-fee}@anchor{66}
@geindex fee
@item fee
-an @ref{51,,exchange} charges various fees for its service. The different
+an @ref{53,,exchange} charges various fees for its service. The different
fees are specified in the protocol. There are fees per coin for
-@ref{7a,,withdrawing}, @ref{73,,depositing}, @ref{7b,,melting}, and
-@ref{7c,,refunding}. Furthermore, there are fees per wire transfer
-for @ref{60,,closing} a @ref{61,,reserve}: and for
-@ref{50,,aggregate} @ref{7d,,wire transfers} to the @ref{52,,merchant}.
-@anchor{taler-developer-manual term-fresh}@anchor{6b}
+@ref{7c,,withdrawing}, @ref{75,,depositing}, @ref{7d,,melting}, and
+@ref{7e,,refunding}. Furthermore, there are fees per wire transfer
+for @ref{62,,closing} a @ref{63,,reserve}: and for
+@ref{52,,aggregate} @ref{7f,,wire transfers} to the @ref{54,,merchant}.
+@anchor{taler-developer-manual term-fresh}@anchor{6d}
@geindex fresh
-@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{7e}
+@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{80}
@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{4e}
+@anchor{taler-developer-manual term-GNUnet}@anchor{50}
@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{7f}
+@anchor{taler-developer-manual term-json}@anchor{81}
@geindex json
-@item json@anchor{taler-developer-manual term-JSON}@anchor{80}
+@item json@anchor{taler-developer-manual term-JSON}@anchor{82}
@geindex JSON
-@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{81}
+@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{83}
@geindex JavaScript Object Notation
@itemx JavaScript Object Notation
@@ -2374,190 +2570,190 @@ 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{6c}
+@anchor{taler-developer-manual term-kappa}@anchor{6e}
@geindex kappa
@item kappa
-security parameter used in the @ref{6a,,refresh} protocol. Defined to be 3.
+security parameter used in the @ref{6c,,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{82}
+@anchor{taler-developer-manual term-LibEuFin}@anchor{84}
@geindex LibEuFin
@item LibEuFin
FIXME: explain
-@anchor{taler-developer-manual term-link}@anchor{83}
+@anchor{taler-developer-manual term-link}@anchor{85}
@geindex link
-@item link@anchor{taler-developer-manual term-linking}@anchor{84}
+@item link@anchor{taler-developer-manual term-linking}@anchor{86}
@geindex linking
@itemx linking
-specific step in the @ref{6a,,refresh} protocol that an exchange must offer
-to prevent abuse of the @ref{6a,,refresh} mechanism. The link step is
+specific step in the @ref{6c,,refresh} protocol that an exchange must offer
+to prevent abuse of the @ref{6c,,refresh} mechanism. The link step is
not needed in normal operation, it just must be offered.
-@anchor{taler-developer-manual term-master-key}@anchor{85}
+@anchor{taler-developer-manual term-master-key}@anchor{87}
@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{69}
+@anchor{taler-developer-manual term-melt}@anchor{6b}
@geindex melt
-@item melt@anchor{taler-developer-manual term-melted}@anchor{86}
+@item melt@anchor{taler-developer-manual term-melted}@anchor{88}
@geindex melted
-@itemx melted@anchor{taler-developer-manual term-melting}@anchor{7b}
+@itemx melted@anchor{taler-developer-manual term-melting}@anchor{7d}
@geindex melting
@itemx melting
-step of the @ref{6a,,refresh} protocol where a @ref{75,,dirty coin}
-is invalidated to be reborn @ref{6b,,fresh} in a subsequent
-@ref{6d,,reveal} step.
-@anchor{taler-developer-manual term-merchant}@anchor{52}
+step of the @ref{6c,,refresh} protocol where a @ref{77,,dirty coin}
+is invalidated to be reborn @ref{6d,,fresh} in a subsequent
+@ref{6f,,reveal} step.
+@anchor{taler-developer-manual term-merchant}@anchor{54}
@geindex merchant
@item merchant
party receiving payments (usually in return for goods or services)
-@anchor{taler-developer-manual term-message-signing-key}@anchor{87}
+@anchor{taler-developer-manual term-message-signing-key}@anchor{89}
@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{88}
+@anchor{taler-developer-manual term-order}@anchor{8a}
@geindex order
@item order
FIXME: to be written!
-@anchor{taler-developer-manual term-owner}@anchor{89}
+@anchor{taler-developer-manual term-owner}@anchor{8b}
@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{8a}
+@anchor{taler-developer-manual term-planchet}@anchor{8c}
@geindex planchet
@item planchet
-precursor data for a @ref{65,,coin}. A planchet includes the coin’s internal
+precursor data for a @ref{67,,coin}. A planchet includes the coin's internal
secrets (coin private key, blinding factor), but lacks the RSA signature
-of the @ref{51,,exchange}. When @ref{7a,,withdrawing}, a @ref{58,,wallet}
+of the @ref{53,,exchange}. When @ref{7c,,withdrawing}, a @ref{5a,,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{8b}
+@anchor{taler-developer-manual term-privacy-policy}@anchor{8d}
@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{8c}
+@anchor{taler-developer-manual term-proof}@anchor{8e}
@geindex proof
@item proof
Message that cryptographically demonstrates that a particular claim is correct.
-@anchor{taler-developer-manual term-proposal}@anchor{8d}
+@anchor{taler-developer-manual term-proposal}@anchor{8f}
@geindex proposal
@item proposal
-a list of @ref{6f,,contract terms} that has been completed and signed by the
+a list of @ref{71,,contract terms} that has been completed and signed by the
merchant backend.
-@anchor{taler-developer-manual term-purchase}@anchor{8e}
+@anchor{taler-developer-manual term-purchase}@anchor{90}
@geindex purchase
@item purchase
-Refers to the overall process of negotiating a @ref{6e,,contract} and then
-making a payment with @ref{5a,,coins} to a @ref{52,,merchant}.
-@anchor{taler-developer-manual term-recoup}@anchor{8f}
+Refers to the overall process of negotiating a @ref{70,,contract} and then
+making a payment with @ref{5c,,coins} to a @ref{54,,merchant}.
+@anchor{taler-developer-manual term-recoup}@anchor{91}
@geindex recoup
@item recoup
Operation by which an exchange returns the value of coins affected
-by a @ref{90,,revocation} to their @ref{89,,owner}, either by allowing the owner to
-withdraw new coins or wiring funds back to the bank account of the @ref{89,,owner}.
-@anchor{taler-developer-manual term-refresh}@anchor{6a}
+by a @ref{92,,revocation} to their @ref{8b,,owner}, either by allowing the owner to
+withdraw new coins or wiring funds back to the bank account of the @ref{8b,,owner}.
+@anchor{taler-developer-manual term-refresh}@anchor{6c}
@geindex refresh
-@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{91}
+@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{93}
@geindex refreshing
@itemx refreshing
-operation by which a @ref{75,,dirty coin} is converted into one or more
-@ref{6b,,fresh} coins. Involves @ref{7b,,melting} the @ref{75,,dirty coin} and
-then @ref{92,,revealing} so-called @ref{93,,transfer keys}.
-@anchor{taler-developer-manual term-refund}@anchor{94}
+operation by which a @ref{77,,dirty coin} is converted into one or more
+@ref{6d,,fresh} coins. Involves @ref{7d,,melting} the @ref{77,,dirty coin} and
+then @ref{94,,revealing} so-called @ref{95,,transfer keys}.
+@anchor{taler-developer-manual term-refund}@anchor{96}
@geindex refund
-@item refund@anchor{taler-developer-manual term-refunding}@anchor{7c}
+@item refund@anchor{taler-developer-manual term-refunding}@anchor{7e}
@geindex refunding
@itemx refunding
operation by which a merchant steps back from the right to funds that he
-obtained from a @ref{71,,deposit} operation, giving the right to the funds back
+obtained from a @ref{73,,deposit} operation, giving the right to the funds back
to the customer
-@anchor{taler-developer-manual term-refund-transaction-id}@anchor{95}
+@anchor{taler-developer-manual term-refund-transaction-id}@anchor{97}
@geindex refund transaction id
@item refund transaction id
-unique number by which a merchant identifies a @ref{94,,refund}. Needed
+unique number by which a merchant identifies a @ref{96,,refund}. Needed
as refunds can be partial and thus there could be multiple refunds for
-the same @ref{8e,,purchase}.
-@anchor{taler-developer-manual term-relative-time}@anchor{4f}
+the same @ref{90,,purchase}.
+@anchor{taler-developer-manual term-relative-time}@anchor{51}
@geindex relative time
@item relative time
-method of keeping time in @ref{4e,,GNUnet} where the time is represented
+method of keeping time in @ref{50,,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{4d,,absolute time}.
-@anchor{taler-developer-manual term-reserve}@anchor{61}
+contrast to @ref{4f,,absolute time}.
+@anchor{taler-developer-manual term-reserve}@anchor{63}
@geindex reserve
@item reserve
accounting mechanism used by the exchange to track customer funds
-from incoming @ref{7d,,wire transfers}. A reserve is created whenever
+from incoming @ref{7f,,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{58,,wallet}
-to @ref{63,,withdraw} up to the amount received in @ref{6b,,fresh}
-@ref{5a,,coins} from the reserve, thereby draining the reserve. If a
-reserve is not drained, the exchange eventually @ref{5e,,closes} it.
+in the subject. The exchange then allows the customer's @ref{5a,,wallet}
+to @ref{65,,withdraw} up to the amount received in @ref{6d,,fresh}
+@ref{5c,,coins} from the reserve, thereby draining the reserve. If a
+reserve is not drained, the exchange eventually @ref{60,,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{6d}
+@anchor{taler-developer-manual term-reveal}@anchor{6f}
@geindex reveal
-@item reveal@anchor{taler-developer-manual term-revealing}@anchor{92}
+@item reveal@anchor{taler-developer-manual term-revealing}@anchor{94}
@geindex revealing
@itemx revealing
-step in the @ref{6a,,refresh} protocol where some of the transfer private
+step in the @ref{6c,,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{6b,,fresh} coins.
-@anchor{taler-developer-manual term-revoke}@anchor{96}
+In the reveal step, the exchange returns the signed @ref{6d,,fresh} coins.
+@anchor{taler-developer-manual term-revoke}@anchor{98}
@geindex revoke
-@item revoke@anchor{taler-developer-manual term-revocation}@anchor{90}
+@item revoke@anchor{taler-developer-manual term-revocation}@anchor{92}
@geindex revocation
@itemx revocation
@@ -2566,109 +2762,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{97}
+@anchor{taler-developer-manual term-sharing}@anchor{99}
@geindex sharing
@item sharing
-users can share ownership of a @ref{65,,coin} by sharing access to the coin's
+users can share ownership of a @ref{67,,coin} by sharing access to the coin&#39;s
private key, thereby allowing all co-owners to spend the coin at any
time.
-@anchor{taler-developer-manual term-spend}@anchor{59}
+@anchor{taler-developer-manual term-spend}@anchor{5b}
@geindex spend
-@item spend@anchor{taler-developer-manual term-spending}@anchor{98}
+@item spend@anchor{taler-developer-manual term-spending}@anchor{9a}
@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{99}
+@anchor{taler-developer-manual term-terms}@anchor{9b}
@geindex terms
@item terms
the general terms of service of an operator, possibly including
-the @ref{8b,,privacy policy}. Not to be confused with the
-@ref{6f,,contract terms} which are about the specific purchase.
-@anchor{taler-developer-manual term-transaction}@anchor{9a}
+the @ref{8d,,privacy policy}. Not to be confused with the
+@ref{71,,contract terms} which are about the specific purchase.
+@anchor{taler-developer-manual term-transaction}@anchor{9c}
@geindex transaction
@item transaction
method by which ownership is exclusively transferred from one entity
-@anchor{taler-developer-manual term-transfer}@anchor{56}
+@anchor{taler-developer-manual term-transfer}@anchor{58}
@geindex transfer
-@item transfer@anchor{taler-developer-manual term-transfers}@anchor{9b}
+@item transfer@anchor{taler-developer-manual term-transfers}@anchor{9d}
@geindex transfers
-@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{53}
+@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{55}
@geindex wire transfer
-@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7d}
+@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7f}
@geindex wire transfers
@itemx wire transfers
-method of sending funds between @ref{54,,bank} accounts
-@anchor{taler-developer-manual term-transfer-key}@anchor{9c}
+method of sending funds between @ref{56,,bank} accounts
+@anchor{taler-developer-manual term-transfer-key}@anchor{9e}
@geindex transfer key
-@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{93}
+@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{95}
@geindex transfer keys
@itemx transfer keys
-special cryptographic key used in the @ref{6a,,refresh} protocol, some of which
-are revealed during the @ref{6d,,reveal} step. Note that transfer keys have,
-despite the name, no relationship to @ref{7d,,wire transfers}. They merely
-help to transfer the value from a @ref{75,,dirty coin} to a @ref{7e,,fresh coin}
-@anchor{taler-developer-manual term-user}@anchor{9d}
+special cryptographic key used in the @ref{6c,,refresh} protocol, some of which
+are revealed during the @ref{6f,,reveal} step. Note that transfer keys have,
+despite the name, no relationship to @ref{7f,,wire transfers}. They merely
+help to transfer the value from a @ref{77,,dirty coin} to a @ref{80,,fresh coin}
+@anchor{taler-developer-manual term-user}@anchor{9f}
@geindex user
@item user
any individual using the Taler payment system
-(see @ref{5c,,customer}, @ref{57,,buyer}, @ref{52,,merchant}).
-@anchor{taler-developer-manual term-version}@anchor{9e}
+(see @ref{5e,,customer}, @ref{59,,buyer}, @ref{54,,merchant}).
+@anchor{taler-developer-manual term-version}@anchor{a0}
@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{51,,exchange},
-@ref{55,,auditor} or @ref{52,,merchant}. There is a protocol
+the state of the table structure in the database of an @ref{53,,exchange},
+@ref{57,,auditor} or @ref{54,,merchant}. There is a protocol
version (CURRENT:REVISION:AGE, see GNU libtool) which specifies
-the network protocol spoken by an @ref{51,,exchange} or @ref{52,,merchant}
+the network protocol spoken by an @ref{53,,exchange} or @ref{54,,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{58}
+@anchor{taler-developer-manual term-wallet}@anchor{5a}
@geindex wallet
@item wallet
-software running on a customer’s computer; withdraws, stores and
+software running on a customer's computer; withdraws, stores and
spends coins
-@anchor{taler-developer-manual term-WebExtension}@anchor{9f}
+@anchor{taler-developer-manual term-WebExtension}@anchor{a1}
@geindex WebExtension
@item WebExtension
Cross-browser API used to implement the GNU Taler wallet browser extension.
-@anchor{taler-developer-manual term-wire-gateway}@anchor{a0}
+@anchor{taler-developer-manual term-wire-gateway}@anchor{a2}
@geindex wire gateway
@item wire gateway
FIXME: explain
-@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a1}
+@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a3}
@geindex wire transfer identifier
-@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{a2}
+@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{a4}
@geindex wtid
@itemx wtid
@@ -2676,35 +2872,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{63}
+@anchor{taler-developer-manual term-withdraw}@anchor{65}
@geindex withdraw
-@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{7a}
+@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{7c}
@geindex withdrawing
-@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a3}
+@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a5}
@geindex withdrawal
@itemx withdrawal
-operation by which a @ref{58,,wallet} can convert funds from a @ref{61,,reserve} to
+operation by which a @ref{5a,,wallet} can convert funds from a @ref{63,,reserve} to
fresh coins
-@anchor{taler-developer-manual term-zombie}@anchor{a4}
+@anchor{taler-developer-manual term-zombie}@anchor{a6}
@geindex zombie
-@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a5}
+@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a7}
@geindex zombie coin
@itemx zombie coin
-coin where the respective @ref{70,,denomination key} is past its
-@ref{71,,deposit} @ref{78,,expiration} time, but which is still (again) valid
-for an operation because it was @ref{86,,melted} while it was still
-valid, and then later again credited during a @ref{8f,,recoup} process
+coin where the respective @ref{72,,denomination key} is past its
+@ref{73,,deposit} @ref{7a,,expiration} time, but which is still (again) valid
+for an operation because it was @ref{88,,melted} while it was still
+valid, and then later again credited during a @ref{91,,recoup} process
@end table
@node Developer Tools,Index,Developer Glossary,Top
-@anchor{taler-developer-manual developer-tools}@anchor{a6}
+@anchor{taler-developer-manual developer-tools}@anchor{a8}
@chapter Developer Tools
@@ -2717,28 +2913,28 @@ developer.
@end menu
@node taler-config-generate,,,Developer Tools
-@anchor{taler-developer-manual taler-config-generate}@anchor{a7}
+@anchor{taler-developer-manual taler-config-generate}@anchor{a9}
@section taler-config-generate
@strong{taler-config-generate} - tool to simplify Taler configuration generation
@strong{taler-config-generate}
-[@strong{-C} @emph{CURRENCY} | @strong{–currency=}‌@emph{CURRENCY}]
-[@strong{-c} @emph{FILENAME} | @strong{–config=}‌@emph{FILENAME}]
-[@strong{-e} | @strong{–exchange}]
-[@strong{-f} @emph{AMOUNT} | @emph{–wirefee=}‌@emph{AMOUNT}]
-[@strong{-h} | @strong{–help}]
-[@strong{-J} @emph{JSON} | @strong{–wire-json-exchange=}‌@emph{JSON}]
-[@strong{-j} @emph{JSON} | @strong{–wire-json-merchant=}‌@emph{JSON}]
-[@strong{-L} @emph{LOGLEVEL} | @strong{–loglevel=}‌@emph{LOGLEVEL}]
-[@strong{-m} | @strong{–merchant}]
-[@strong{-t} | @strong{–trusted}]
-[@strong{-v} | @strong{–version}]
-[@strong{-w} @emph{WIREFORMAT} | @strong{–wire} @emph{WIREFORMAT}]
-[@strong{–bank-uri}]
-[@strong{–exchange-bank-account}]
-[@strong{–merchant-bank-account}]
+[@strong{-C} @emph{CURRENCY} | @strong{--currency=}‌@emph{CURRENCY}]
+[@strong{-c} @emph{FILENAME} | @strong{--config=}‌@emph{FILENAME}]
+[@strong{-e} | @strong{--exchange}]
+[@strong{-f} @emph{AMOUNT} | @emph{--wirefee=}‌@emph{AMOUNT}]
+[@strong{-h} | @strong{--help}]
+[@strong{-J} @emph{JSON} | @strong{--wire-json-exchange=}‌@emph{JSON}]
+[@strong{-j} @emph{JSON} | @strong{--wire-json-merchant=}‌@emph{JSON}]
+[@strong{-L} @emph{LOGLEVEL} | @strong{--loglevel=}‌@emph{LOGLEVEL}]
+[@strong{-m} | @strong{--merchant}]
+[@strong{-t} | @strong{--trusted}]
+[@strong{-v} | @strong{--version}]
+[@strong{-w} @emph{WIREFORMAT} | @strong{--wire} @emph{WIREFORMAT}]
+[@strong{--bank-uri}]
+[@strong{--exchange-bank-account}]
+[@strong{--merchant-bank-account}]
@strong{taler-config-generate} can be used to generate configuration files
for the Taler exchange or Taler merchants.
@@ -2746,16 +2942,16 @@ for the Taler exchange or Taler merchants.
@table @asis
-@item @strong{-C} @emph{CURRENCY} | @strong{–currency=}‌@emph{CURRENCY}
+@item @strong{-C} @emph{CURRENCY} | @strong{--currency=}‌@emph{CURRENCY}
Which currency should we use in the configuration.
-@item @strong{-c} @emph{FILENAME} | @strong{–config=}‌@emph{FILENAME}
+@item @strong{-c} @emph{FILENAME} | @strong{--config=}‌@emph{FILENAME}
Location where to write the generated configuration. Existing file
will be updated, not overwritten.
-@item @strong{-e} | @strong{–exchange}
+@item @strong{-e} | @strong{--exchange}
Generate configuration for a Taler exchange.
@@ -2764,53 +2960,53 @@ Generate configuration for a Taler exchange.
Setup wire transfer fees for the next 5 years for the exchange (for
all wire methods).
-@item @strong{-h} | @strong{–help}
+@item @strong{-h} | @strong{--help}
Shows this man page.
-@item @strong{-J} @emph{JSON} | @strong{–wire-json-exchange=}‌@emph{JSON}
+@item @strong{-J} @emph{JSON} | @strong{--wire-json-exchange=}‌@emph{JSON}
Wire configuration to use for the exchange.
-@item @strong{-j} @emph{JSON} | @strong{–wire-json-merchant=}‌@emph{JSON}
+@item @strong{-j} @emph{JSON} | @strong{--wire-json-merchant=}‌@emph{JSON}
Wire configuration to use for the merchant.
-@item @strong{-L} @emph{LOGLEVEL} | @strong{–loglevel=}‌@emph{LOGLEVEL}
+@item @strong{-L} @emph{LOGLEVEL} | @strong{--loglevel=}‌@emph{LOGLEVEL}
Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and
ERROR.
-@item @strong{-m} | @strong{–merchant}
+@item @strong{-m} | @strong{--merchant}
Generate configuration for a Taler merchant.
-@item @strong{-t} | @strong{–trusted}
+@item @strong{-t} | @strong{--trusted}
Setup current exchange as trusted with current merchant. Generally
only useful when configuring for testcases.
-@item @strong{-v} | @strong{–version}
+@item @strong{-v} | @strong{--version}
Print version information.
-@item @strong{-w} @emph{WIREFORMAT} | @strong{–wire} @emph{WIREFORMAT}
+@item @strong{-w} @emph{WIREFORMAT} | @strong{--wire} @emph{WIREFORMAT}
Specifies which wire format to use (i.e. “x-talerbank” or “iban”)
-@item @strong{–bank-uri}
+@item @strong{--bank-uri}
Alternative to specify wire configuration to use for the exchange and
merchant for the “test” wire method. Only useful if WIREFORMAT was
set to “test”. Specifies the URI of the bank.
-@item @strong{–exchange-bank-account}
+@item @strong{--exchange-bank-account}
Alternative to specify wire configuration to use for the exchange for
the “test” wire method. Only useful if WIREFORMAT was set to “test”.
Specifies the bank account number of the exchange.
-@item @strong{–merchant-bank-account}
+@item @strong{--merchant-bank-account}
Alternative to specify wire configuration to use for the merchant for
the “test” wire method. Only useful if WIREFORMAT was set to “test”.
diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi
index 8a1fb072..6690110a 100644
--- a/texinfo/taler-exchange.texi
+++ b/texinfo/taler-exchange.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.9.0, Jul 06, 2022
+GNU Taler 0.9.0, Nov 03, 2022
GNU Taler team
@@ -275,7 +275,7 @@ binary is the @code{taler-exchange-httpd}.
@item
Crypto-Helpers
The @code{taler-exchange-secmod-rsa} and @code{taler-exchange-secmod-eddsa}
-are two programs that are responsible for managing the exchange’s
+are two programs that are responsible for managing the exchange's
online signing keys. They must run on the same machine as the
@code{taler-exchange-httpd} as the HTTP frontend communicates with the
crypto helpers using UNIX Domain Sockets.
@@ -294,7 +294,7 @@ Closer
The @code{taler-exchange-closer} tool check that reserves are properly
closed. If a customer wires funds to an exchange and then fails
to withdraw them, the closer will (eventually) trigger a wire
-transfer that sends the customer’s funds back to the originating
+transfer that sends the customer's funds back to the originating
wire account.
@item
@@ -335,7 +335,7 @@ the Python bank provides a bank that directly provides
the wire adapter API.
@item
-For production, libeufin’s Nexus component implements a wire
+For production, libeufin's Nexus component implements a wire
adapter towards the traditional SEPA banking system with IBAN
accounts.
@end enumerate
@@ -372,7 +372,7 @@ copy of the database.
The exchange (and ideally also auditors) uses a long-term offline master
siging key that identifies the operator and is used to authenticate critical
-information, such as the exchange’s bank account and the actual keys the
+information, such as the exchange's bank account and the actual keys the
exchange uses online.
Interactions with the offline system are performed using the
@@ -431,7 +431,7 @@ expires or if they are informed about a key having been revoked.
From a security point of view, the helpers are designed to @emph{only} make it
-harder for an attacker who took control of the HTTP daemon’s account to
+harder for an attacker who took control of the HTTP daemon's account to
extract the private keys, limiting the attackers ability to creating
signatures to the duration of their control of that account.
@@ -451,8 +451,8 @@ The helper processes should be run under a user ID that is separate from that
of the user running the main @code{taler-exchange-httpd} service. For security,
it is important that helpers run under a different user ID than the main HTTP
frontend, in fact ideally each helper should run under its own user ID. The
-@code{taler-exchange-httpd} service’s will securely communicate with the helpers
-using UNIX domain sockets. To enable access to the keys, the service’s user
+@code{taler-exchange-httpd} service's will securely communicate with the helpers
+using UNIX domain sockets. To enable access to the keys, the service's user
must be in the group of the helper processes (and no other users should be in
that group).
@@ -490,6 +490,11 @@ Python3 module @code{jinja2}
@itemize -
@item
+"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})
+
+@item
libsqlite3 >= 3.16.2
@item
@@ -888,9 +893,9 @@ denomination keys (signs electronic coins, see section Coins)
security module keys (signs sign keys and denomination keys)
@end itemize
-Additionally, the exchange is sometimes concerned with the auditor’s public
+Additionally, the exchange is sometimes concerned with the auditor's public
key (to verify messages signed by auditors approved by the exchange operator)
-and the merchant’s public key (to verify refunds are authorized by the
+and the merchant's public key (to verify refunds are authorized by the
merchant).
Key options include:
@@ -1007,7 +1012,7 @@ must then have the following options:
@item
@code{VALUE}: How much is the coin worth, the format is
-CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is “EUR:0.10”.
+CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10".
@item
@code{DURATION_WITHDRAW}: How long can a coin of this type be withdrawn?
@@ -1126,7 +1131,7 @@ delayed.
@section Terms of Service
-The exchange has an endpoint “/terms” to return the terms of service
+The exchange has an endpoint "/terms" to return the terms of service
(in legal language) of the exchange operator. The wallet will show
those terms of service to the user when the user is first withdrawing
coins. Terms of service are optional for experimental deployments,
@@ -1140,7 +1145,7 @@ in the @code{[exchange]} section:
@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
@@ -1154,7 +1159,7 @@ process.
The @code{TERMS_DIR} directory structure must follow a particular layout.
First, inside of @code{TERMS_DIR}, there should be sub-directories using
-two-letter language codes like “en”, “de”, or “jp”. Each of these
+two-letter language codes 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.
@@ -1176,7 +1181,7 @@ present, the exchange may show a warning on startup.
@subsection Example
-A sample file structure for a @code{TERMS_ETAG} of “v1” would be:
+A sample file structure for a @code{TERMS_ETAG} of "v1" would be:
@itemize -
@@ -1203,7 +1208,7 @@ TERMS_DIR/de/v1.pdf
TERMS_DIR/fr/v1.pdf
@end itemize
-If the user requests an HTML format with language preferences “fr” followed by “en”,
+If the user requests an HTML format with language preferences "fr" followed by "en",
the exchange would return @code{TERMS_DIR/en/v1.html} lacking an HTML version in
French.
@@ -1329,7 +1334,7 @@ The exchange must be informed about any auditor that is expected to provision
it with auditor signatures. This is also done using the
@code{taler-exchange-offline} tool on the offline system. First, the auditor
must be configured and provide the exchange operator with its public key and
-the URL of it’s REST API. The exchange operator also needs a human-readable
+the URL of it's REST API. The exchange operator also needs a human-readable
name that may be shown to users to identify the auditor. Given this
information, the exchange operator can enable the auditor:
@@ -1586,7 +1591,7 @@ helpful for diagnostics.
While an exchange should use an external auditor to attest to regulators that
-it is operating correctly, an exchange operator can also use the auditor’s
+it is operating correctly, an exchange operator can also use the auditor's
logic to perform internal checks. For this, an exchange operator can generally
follow the auditor guide. However, instead of using @code{taler-auditor-sync},
an internal audit can and likely should be performed either directly against
@@ -1632,14 +1637,14 @@ The database scheme used by the exchange looks as follows:
This chapter describes how to run the Taler exchange benchmark. The benchmark
can be used to measure the performance of the exchange by running a (possibly
large) number of simulated clients against one Taler deployment with a bank,
-exchange and auditor. For the bank, both a “fakebank” (@code{-f}) and a
-“Pythonbank” deployment are currently supported. The
+exchange and auditor. For the bank, both a "fakebank" (@code{-f}) and a
+"Pythonbank" deployment are currently supported. The
@code{taler-exchange-benchmark} program can launch all required services and
clients, or only launch the parallel clients (@code{-m}), for example for
distributed testing over a network.
For each @emph{parallel} (@code{-p}) client, a number of @emph{reserves} (@code{-r}) is first established by
-@strong{transferring} money from a “user” account (42) to the Exchange’s account
+@strong{transferring} money from a "user" account (42) to the Exchange's account
with the respective reserve public key as wire subject. Next, the
client will @strong{withdraw} a @emph{number of coins} (@code{-n}) from the reserve and
@strong{deposit} them. Additionally, a @emph{fraction} (@code{-R}) of the dirty coins will then be
@@ -1659,7 +1664,7 @@ You can run a first simple benchmark using:
@cartouche
@quotation Note
FIXME-TTN/CG: these instructions are incomplete and untested for the
-current iteration of the code…
+current iteration of the code...
@end quotation
@end cartouche
diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi
index c4ce9ffb..558313fe 100644
--- a/texinfo/taler-merchant-api-tutorial.texi
+++ b/texinfo/taler-merchant-api-tutorial.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.9.0, Jul 06, 2022
+GNU Taler 0.9.0, Nov 03, 2022
GNU Taler team
@@ -242,7 +242,7 @@ key in the @code{Authorization} header. The value of this header must be
@example
>>> import requests
>>> requests.get("https://backend.demo.taler.net",
-... headers=@{"Authorization": "ApiKey sandbox"@})
+... headers=@{"Authorization": "secret-token:secret"@})
<Response [200]>
@end example
@@ -363,9 +363,9 @@ A minimal Python snippet for creating an order would look like this:
... summary="Donation",
... fulfillment_url="https://example.com/thanks.html"),
... create_token=false)
->>> response = requests.post("https://backend.demo.taler.net/private/order",
+>>> response = requests.post("https://backend.demo.taler.net/private/orders",
... json=body,
-... headers=@{"Authorization": "ApiKey sandbox"@})
+... headers=@{"Authorization": "secret-token:secret"@})
<Response [200]>
@end example
@@ -424,7 +424,7 @@ backend to do it is the safest method.
@example
>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/private/orders/" + order_id,
-... headers=@{"Authorization": "ApiKey sandbox"@})
+... headers=@{"Authorization": "secret-token:secret"@})
>>> print(r.json())
@end example
@@ -453,7 +453,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}.
@@ -508,7 +508,7 @@ This code snipped illustrates giving a refund:
... reason="Customer did not like the product")
>>> requests.post("https://backend.demo.taler.net/private/orders/"
... + order_id + "/refund", json=refund_req,
-... headers=@{"Authorization": "ApiKey sandbox"@})
+... headers=@{"Authorization": "secret-token:secret"@})
<Response [200]>
@end example
@@ -551,8 +551,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 @emph{session ID} and @emph{fulfillment URL} there is an
+"new" unpaid order is checked (or already in long-polling), the backend
+detects that for the browser's @emph{session ID} and @emph{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.
@@ -595,7 +595,7 @@ funds available for tipping, query the @code{/tip-query} endpoint:
@example
>>> import requests
>>> requests.get("https://backend.demo.taler.net/tip-query?instance=default",
-... headers=@{"Authorization": "ApiKey sandbox"@})
+... headers=@{"Authorization": "secret-token:secret"@})
<Response [200]>
@end example
@anchor{taler-merchant-api-tutorial authorize-tip}@anchor{14}
@@ -634,7 +634,7 @@ This code snipped illustrates giving a tip:
... justification="User filled out survey",
... next_url="https://merchant.com/thanks.html")
>>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req,
-... headers=@{"Authorization": "ApiKey sandbox"@})
+... headers=@{"Authorization": "secret-token:secret"@})
<Response [200]>
@end example
@@ -1020,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.texi b/texinfo/taler-merchant.texi
index a0429339..a8396143 100644
--- a/texinfo/taler-merchant.texi
+++ b/texinfo/taler-merchant.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.9.0, Jul 06, 2022
+GNU Taler 0.9.0, Nov 03, 2022
GNU Taler team
@@ -354,7 +354,7 @@ the main Taler configuration (accepted currency, exchanges and auditors).
To receive payments, an instance must have configured one or more bank
@emph{accounts}. The backend does not have accounts for users, and instances are
-also not really ‘accounts’. So whenever we use the term @emph{account}, it is about
+also not really 'accounts'. So whenever we use the term @emph{account}, it is about
a bank account of a merchant.
@node Inventory,Orders and Contracts,Accounts,Terminology
@@ -460,7 +460,7 @@ decade), contract information is deleted.
The Taler backend can be used to verify that the exchange correctly wired all
of the funds to the merchant. However, the backend does not have access to the
-incoming wire transfers of the merchant’s bank account. Thus, merchants must
+incoming wire transfers of the merchant's bank account. Thus, merchants must
manually provide the backend with wire @emph{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.
@@ -552,6 +552,11 @@ backend:
@itemize -
@item
+"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})
+
+@item
libsqlite3 >= 3.16.2
@item
@@ -635,7 +640,7 @@ shared object libraries (@code{.so} files)
visible to the various installed programs.
There is no need to actually run a GNUnet peer to use the Taler merchant
-backend – all the merchant needs from GNUnet is a number of headers and
+backend -- all the merchant needs from GNUnet is a number of headers and
libraries!
@node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source
@@ -663,7 +668,7 @@ which requires you to run the last step as @code{root}. You have to specify
previous step.
There is no need to actually run a Taler exchange to use the Taler merchant
-backend – all the merchant needs from the Taler exchange is a few headers and
+backend -- all the merchant needs from the Taler exchange is a few headers and
libraries!
@node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source
@@ -1351,7 +1356,7 @@ you create a section with a name that starts with “MERCHANT-AUDITOR-”. In
@item
The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL.
-For example, to use the Taler demonstrator’s auditor, specify:
+For example, to use the Taler demonstrator's auditor, specify:
@example
$ taler-config -s MERCHANT-AUDITOR-demo \
@@ -1360,7 +1365,7 @@ $ taler-config -s MERCHANT-AUDITOR-demo \
@end example
@item
-The @code{AUDITOR_KEY} option specifies the auditor’s public key
+The @code{AUDITOR_KEY} option specifies the auditor's public key
in base32 encoding. For the Taler demonstrator, use:
@example
@@ -1611,7 +1616,7 @@ create a file @code{instance.json} with an InstanceConfigurationMessage
In the text above, you must replace @code{$PAYTO_URI} with your actual
@code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the
setup is for an actual bank. The @code{name} field will be shown as the name of
-your shop. The @code{address} field is expected to contain your shop’s physical
+your shop. The @code{address} field is expected to contain your shop's physical
address. The various defaults specify defaults for transaction fees your shop
is willing to cover, how long offers made to the customer are valid, and how
long the exchange has before it must wire the funds to your bank
@@ -1668,9 +1673,9 @@ $ taler-config -s MERCHANT -o SERVE -V UNIX
$ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
@end example
-Do not use a UNIX domain socket path in “/tmp”: systemd (or other init
-systems) may give Web servers a private “/tmp” thereby hiding UNIX domain
-sockets created by other users/processes in “/tmp”.
+Do not use a UNIX domain socket path in "/tmp": systemd (or other init
+systems) may give Web servers a private "/tmp" thereby hiding UNIX domain
+sockets created by other users/processes in "/tmp".
If UNIX domain sockets are for some reason not possible, you @emph{may} use a
host-based firewall to block access to the TCP port of the merchant backend,
@@ -1997,7 +2002,7 @@ process to hold open file handles for all of these files. You may want
to increase the @code{ulimit} of the @code{taler-merchant-httpd} process if you have
templates for many languages.
-The backend determines the MIME type based on the file’s extension. The list
+The backend determines the MIME type based on the file's extension. The list
of supported extensions is hard-coded and includes common text and image
formats.
@@ -2097,7 +2102,7 @@ You now need to make a wire transfer to the exchange’s bank account
using the given wire transfer subject.
Make your wire transfer and (optionally) check at
-“@indicateurl{https://exchange/reserves/QPE24X}…” whether your transfer has arrived at the
+“@indicateurl{https://exchange/reserves/QPE24X}...” whether your transfer has arrived at the
exchange.
Once the funds have arrived, you can start to use the reserve for
@@ -2367,13 +2372,13 @@ start.
The @code{taler-merchant-benchmark} tool will automatically launch and configure the
exchange, (Python) bank and other tools required for the benchmark. However,
the configuration file must be provided and have consistent options set. The
-options that require special care include the exchange’s public key (which
+options that require special care include the exchange's public key (which
must match the private key in the file specified by the configuration), the
currency (which must be consistent across the file), the denomination
structure (which must enable payments in the range of 100ths of the unit
currency (often called cents)). Furthermore, the benchmark will set the
-Exchange bank account password to be “x”, so the configuration must also
-specify “x” for the passphrase. Finally, the bank must be configured to allow
+Exchange bank account password to be "x", so the configuration must also
+specify "x" for the passphrase. Finally, the bank must be configured to allow
for substantial debt least the transactions by the benchmark run out of
digital cash.
@@ -2505,10 +2510,10 @@ rsa_keysize = 1024
@end example
-Note that the public key must match the exchange’s
+Note that the public key must match the exchange's
private key and that the PostgreSQL database must
exist before launching the benchmark. You also
-will need to ensure that the Exchange’s
+will need to ensure that the Exchange's
details are set up.
For details, see the Exchange Operator Manual.
@@ -2577,7 +2582,7 @@ options:
@item
@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking
operations. Note that the @strong{total} amount of operations will be two
-times @emph{TN}, since “one” tracking operation accounts for
+times @emph{TN}, since "one" tracking operation accounts for
@code{/track/transaction} and @code{/track/transfer}. This command should
only be used to see if the operation ends without problems, as no
actual measurement of performance is provided (despite of the