diff options
Diffstat (limited to 'texinfo/taler-developer-manual.texi')
| -rw-r--r-- | texinfo/taler-developer-manual.texi | 722 |
1 files changed, 368 insertions, 354 deletions
diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 51a1b9fa..bc3d1966 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.texi @@ -10,9 +10,9 @@ @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Networking @direntry -* MENU ENTRY: (taler-developer-manual.info). DESCRIPTION +* GNU Taler Development: (taler-developer-manual.info). Manual for GNU Taler contributors @end direntry @c %**end of header @@ -79,17 +79,6 @@ and related components. It is not intended for a general audience. * Demo Upgrade Procedure:: * Environments and Builders on taler.net: Environments and Builders on taler net. * QA Plans:: -* Wallet Platforms:: -* Running Deployments:: -* Wallet Flows:: -* libeufin-bank Flows:: -* Merchant Backend SPA Flows:: -* Regio Deployment:: -* Android Merchant PoS:: -* Android Cashier App:: -* CI:: -* Debian Repository:: -* GNU Release:: * Releases:: * Continuous integration:: * Internationalization:: @@ -123,15 +112,15 @@ overview: exchange: core payment processing logic with a REST API, plus various helper processes for interaction with banks and cryptographic computations. Also includes the logic for the auditor and an -in-memory "bank" API implementation for testing. +in-memory “bank” API implementation for testing. @item -libeufin: implementation of the "bank" API using the EBICS protocol +libeufin: implementation of the “bank” API using the EBICS protocol used by banks in the EU. Allows an exchange to interact with European banks. @item -deploymerization: implementation of the "bank" API on top of +deploymerization: implementation of the “bank” API on top of blockchains, specifically Bitcoin and Ethereum. Allows an exchange to interact with crypto-currencies. @@ -190,7 +179,7 @@ sending invoices or payments to other wallets. @item taler-merchant-demos: various demonstration services operated at -'demo.taler.net', including a simple shop and a donation page. +‘demo.taler.net’, including a simple shop and a donation page. @end itemize @end quotation @@ -363,7 +352,7 @@ A complete list of all the existing repositories is currently found at 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 @@ -636,7 +625,7 @@ $ curl -fsSL https://get.docker.com/rootless | sh 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. Please use the demo upgrade checklist to make sure everything is working. Nginx is already configured to reach the services as exported by @@ -738,7 +727,7 @@ taler-wallet-cli api 'runIntegrationTestV2' '@{"exchangeBaseUrl":"https://exchan @subsection Wallets -We consider the following published wallets to be "production wallets": +We consider the following published wallets to be “production wallets”: @itemize * @@ -988,7 +977,7 @@ fulfillment page. add product with 1 in stock and preview image @item - add "advanced" order with inventory product and a 2 minute wire delay + add “advanced” order with inventory product and a 2 minute wire delay @item claim order, check available stock goes down in inventory @@ -1156,7 +1145,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. @@ -1174,7 +1163,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>} @@ -1298,7 +1287,7 @@ The results are then published at @code{https://lcov.taler.net/}. @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. @@ -1330,14 +1319,39 @@ environment), existing scripts MUST be immutable. Developers and operators MUST NOT make changes to database schema outside of this versioning. All tables of a GNU Taler component should live in their own schema. -@node QA Plans,Wallet Platforms,Environments and Builders on taler net,Top +@node QA Plans,Releases,Environments and Builders on taler net,Top @anchor{taler-developer-manual qa-plans}@anchor{2b} @chapter QA Plans -@node Wallet Platforms,Running Deployments,QA Plans,Top -@anchor{taler-developer-manual wallet-platforms}@anchor{2c} -@chapter Wallet Platforms +@menu +* Taler 0.9.4 QA Plan: Taler 0 9 4 QA Plan. + +@end menu + +@node Taler 0 9 4 QA Plan,,,QA Plans +@anchor{taler-developer-manual taler-0-9-4-qa-plan}@anchor{2c} +@section Taler 0.9.4 QA Plan + + +@menu +* Wallet Platforms:: +* Running Deployments:: +* Wallet Flows:: +* libeufin-bank Flows:: +* Merchant Backend SPA Flows:: +* Regio Deployment:: +* Android Merchant PoS:: +* Android Cashier App:: +* CI:: +* Debian Repository:: +* GNU Release:: + +@end menu + +@node Wallet Platforms,Running Deployments,,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-platforms}@anchor{2d} +@subsection Wallet Platforms Platforms listed here are the officially supported platforms for this release. @@ -1388,9 +1402,9 @@ Firefox: @indicateurl{https://addons.mozilla.org/en-US/firefox/addon/taler-walle iOS @end itemize -@node Running Deployments,Wallet Flows,Wallet Platforms,Top -@anchor{taler-developer-manual running-deployments}@anchor{2d} -@chapter Running Deployments +@node Running Deployments,Wallet Flows,Wallet Platforms,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual running-deployments}@anchor{2e} +@subsection Running Deployments These deployments are maintained by us and should work for the release: @@ -1422,9 +1436,9 @@ regio-taler.fdold.eu @end itemize @end itemize -@node Wallet Flows,libeufin-bank Flows,Running Deployments,Top -@anchor{taler-developer-manual wallet-flows}@anchor{2e} -@chapter Wallet Flows +@node Wallet Flows,libeufin-bank Flows,Running Deployments,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-flows}@anchor{2f} +@subsection Wallet Flows @@ -1437,7 +1451,7 @@ Bank-integrated withdrawal @itemize * @item -webext: "Continue with Mobile Wallet" flow +webext: “Continue with Mobile Wallet” flow @end itemize @item @@ -1454,10 +1468,10 @@ Currency conversion withdrawal @end itemize @item -Peer push payments ("Send Money") +Peer push payments (“Send Money”) @item -Peer pull payments ("Receive Money") +Peer pull payments (“Receive Money”) @item Deposit into bank account @@ -1485,7 +1499,7 @@ on survey directly initiated via merchant SPA @item -webext: "Pay with Mobile Wallet" flow +webext: “Pay with Mobile Wallet” flow @end itemize @item @@ -1512,9 +1526,9 @@ Deleting an exchange @end itemize @end itemize -@node libeufin-bank Flows,Merchant Backend SPA Flows,Wallet Flows,Top -@anchor{taler-developer-manual libeufin-bank-flows}@anchor{2f} -@chapter libeufin-bank Flows +@node libeufin-bank Flows,Merchant Backend SPA Flows,Wallet Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual libeufin-bank-flows}@anchor{30} +@subsection libeufin-bank Flows @@ -1579,9 +1593,9 @@ Lower cash-out limit enforced @end itemize @end itemize -@node Merchant Backend SPA Flows,Regio Deployment,libeufin-bank Flows,Top -@anchor{taler-developer-manual merchant-backend-spa-flows}@anchor{30} -@chapter Merchant Backend SPA Flows +@node Merchant Backend SPA Flows,Regio Deployment,libeufin-bank Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual merchant-backend-spa-flows}@anchor{31} +@subsection Merchant Backend SPA Flows @@ -1619,7 +1633,7 @@ Add Taler Bank Revenue API Check bank transfer list (for wire transfer of previously paid+wired order) @item -Check order payment status goes to "final" automatically +Check order payment status goes to “final” automatically @end itemize @item @@ -1670,9 +1684,9 @@ Delete template @end itemize @end itemize -@node Regio Deployment,Android Merchant PoS,Merchant Backend SPA Flows,Top -@anchor{taler-developer-manual regio-deployment}@anchor{31} -@chapter Regio Deployment +@node Regio Deployment,Android Merchant PoS,Merchant Backend SPA Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual regio-deployment}@anchor{32} +@subsection Regio Deployment @@ -1723,9 +1737,9 @@ Check logs @end itemize @end itemize -@node Android Merchant PoS,Android Cashier App,Regio Deployment,Top -@anchor{taler-developer-manual android-merchant-pos}@anchor{32} -@chapter Android Merchant PoS +@node Android Merchant PoS,Android Cashier App,Regio Deployment,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual android-merchant-pos}@anchor{33} +@subsection Android Merchant PoS @@ -1735,9 +1749,9 @@ Check logs Test against demo.taler.net @end itemize -@node Android Cashier App,CI,Android Merchant PoS,Top -@anchor{taler-developer-manual android-cashier-app}@anchor{33} -@chapter Android Cashier App +@node Android Cashier App,CI,Android Merchant PoS,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual android-cashier-app}@anchor{34} +@subsection Android Cashier App @@ -1747,9 +1761,9 @@ Test against demo.taler.net Test against demo.taler.net @end itemize -@node CI,Debian Repository,Android Cashier App,Top -@anchor{taler-developer-manual ci}@anchor{34} -@chapter CI +@node CI,Debian Repository,Android Cashier App,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual ci}@anchor{35} +@subsection CI @@ -1762,9 +1776,9 @@ Test against demo.taler.net CI should pass @end itemize -@node Debian Repository,GNU Release,CI,Top -@anchor{taler-developer-manual debian-repository}@anchor{35} -@chapter Debian Repository +@node Debian Repository,GNU Release,CI,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual debian-repository}@anchor{36} +@subsection Debian Repository @@ -1797,9 +1811,9 @@ supported codename(s): mantic @end itemize @end itemize -@node GNU Release,Releases,Debian Repository,Top -@anchor{taler-developer-manual gnu-release}@anchor{36} -@chapter GNU Release +@node GNU Release,,Debian Repository,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual gnu-release}@anchor{37} +@subsection GNU Release @@ -1812,8 +1826,8 @@ Release announcement FTP upload @end itemize -@node Releases,Continuous integration,GNU Release,Top -@anchor{taler-developer-manual releases}@anchor{37} +@node Releases,Continuous integration,QA Plans,Top +@anchor{taler-developer-manual releases}@anchor{38} @chapter Releases @@ -1830,7 +1844,7 @@ FTP upload @end menu @node GNU Taler Release Checklist,Release Process,,Releases -@anchor{taler-developer-manual gnu-taler-release-checklist}@anchor{38} +@anchor{taler-developer-manual gnu-taler-release-checklist}@anchor{39} @section GNU Taler Release Checklist @@ -1840,10 +1854,10 @@ For exchange: @itemize - @item - no compiler warnings at "-Wall" with gcc + no compiler warnings at “-Wall” with gcc @item - no compiler warnings at "-Wall" with clang + no compiler warnings at “-Wall” with clang @item ensure Coverity static analysis passes @@ -1852,7 +1866,7 @@ For exchange: make check. @item - make dist, make check on result of 'make dist'. + make dist, make check on result of ‘make dist’. @item Change version number in configure.ac. @@ -1867,7 +1881,7 @@ For exchange: verify dist builds from source @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run demo upgrade checklist @@ -1876,13 +1890,13 @@ For exchange: tag repo. @item - use 'deployment.git/packaging/*-docker/' to build Debian and Ubuntu packages + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages @item - upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) @item - change 'demo.taler.net' deployment to use new tag. + change ‘demo.taler.net’ deployment to use new tag. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -1894,10 +1908,10 @@ For merchant (C backend): @itemize - @item - no compiler warnings at "-Wall" with gcc + no compiler warnings at “-Wall” with gcc @item - no compiler warnings at "-Wall" with clang + no compiler warnings at “-Wall” with clang @item ensure Coverity static analysis passes @@ -1906,7 +1920,7 @@ For merchant (C backend): make check. @item - make dist, make check on result of 'make dist'. + make dist, make check on result of ‘make dist’. @item update SPA (prebuilt branch) @@ -1921,7 +1935,7 @@ For merchant (C backend): verify dist builds from source @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run demo upgrade checklist @@ -1930,13 +1944,13 @@ For merchant (C backend): tag repo. @item - use 'deployment.git/packaging/*-docker/' to build Debian and Ubuntu packages + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages @item - upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) @item - change 'demo.taler.net' deployment to use new tag. + change ‘demo.taler.net’ deployment to use new tag. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -1948,10 +1962,10 @@ For sync: @itemize - @item - no compiler warnings at "-Wall" with gcc + no compiler warnings at “-Wall” with gcc @item - no compiler warnings at "-Wall" with clang + no compiler warnings at “-Wall” with clang @item ensure Coverity static analysis passes @@ -1960,7 +1974,7 @@ For sync: make check. @item - make dist, make check on result of 'make dist'. + make dist, make check on result of ‘make dist’. @item Change version number in configure.ac. @@ -1972,7 +1986,7 @@ For sync: verify dist builds from source @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run demo upgrade checklist @@ -1981,13 +1995,13 @@ For sync: tag repo. @item - use 'deployment.git/packaging/*-docker/' to build Debian and Ubuntu packages + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages @item - upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) @item - change 'demo.taler.net' deployment to use new tag. + change ‘demo.taler.net’ deployment to use new tag. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -1999,7 +2013,7 @@ For taler-mdb: @itemize - @item - no compiler warnings at "-Wall" with gcc + no compiler warnings at “-Wall” with gcc @item ensure Coverity static analysis passes @@ -2014,10 +2028,10 @@ For taler-mdb: tag repo. @item - use 'deployment.git/packaging/*-docker/' to build Debian and Ubuntu packages + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages @item - upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -2029,10 +2043,10 @@ For taler-twister: @itemize - @item - no compiler warnings at "-Wall" with gcc + no compiler warnings at “-Wall” with gcc @item - no compiler warnings at "-Wall" with clang + no compiler warnings at “-Wall” with clang @item ensure Coverity static analysis passes @@ -2041,7 +2055,7 @@ For taler-twister: make check. @item - make dist, make check on result of 'make dist'. + make dist, make check on result of ‘make dist’. @item Change version number in configure.ac. @@ -2053,7 +2067,7 @@ For taler-twister: verify dist builds from source @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run demo upgrade checklist @@ -2077,7 +2091,7 @@ For libeufin: build libeufin @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run demo upgrade checklist @@ -2092,13 +2106,13 @@ For libeufin: tag repo. @item - use 'deployment.git/packaging/*-docker/' to build Debian and Ubuntu packages + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages @item - upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) @item - change 'demo.taler.net' deployment to use new tag. + change ‘demo.taler.net’ deployment to use new tag. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -2110,13 +2124,13 @@ For Python merchant frontend: @itemize - @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run demo upgrade checklist @item - change 'demo.taler.net' deployment to use new tag. + change ‘demo.taler.net’ deployment to use new tag. @end itemize Wallet-core: @@ -2140,13 +2154,13 @@ Wallet-core: tag repo. @item - use 'deployment.git/packaging/*-docker/' to build Debian and Ubuntu packages + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages @item - upload packages to 'deb.taler.net' (note: only Florian/Christian can sign) + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) @item - change 'demo.taler.net' deployment to use new tag. + change ‘demo.taler.net’ deployment to use new tag. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -2207,7 +2221,7 @@ Release announcement: @end itemize @node Release Process,Tagging,GNU Taler Release Checklist,Releases -@anchor{taler-developer-manual release-process}@anchor{39} +@anchor{taler-developer-manual release-process}@anchor{3a} @section Release Process @@ -2242,7 +2256,7 @@ wallet-core (wallet-core.git) @end itemize @node Tagging,Database for tests,Release Process,Releases -@anchor{taler-developer-manual tagging}@anchor{3a} +@anchor{taler-developer-manual tagging}@anchor{3b} @section Tagging @@ -2254,7 +2268,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{3b} +@anchor{taler-developer-manual database-for-tests}@anchor{3c} @section Database for tests @@ -2271,7 +2285,7 @@ secured from unauthorized access. @end cartouche @node Exchange merchant,Wallet WebExtension,Database for tests,Releases -@anchor{taler-developer-manual exchange-merchant}@anchor{3c} +@anchor{taler-developer-manual exchange-merchant}@anchor{3d} @section Exchange, merchant @@ -2318,7 +2332,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 @@ -2330,7 +2344,7 @@ $ make install check @end example @node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases -@anchor{taler-developer-manual wallet-webextension}@anchor{3d} +@anchor{taler-developer-manual wallet-webextension}@anchor{3e} @section Wallet WebExtension @@ -2344,7 +2358,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{3e} +@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{3f} @section Upload to GNU mirrors @@ -2362,7 +2376,7 @@ symlink: taler-exchange-0.1.0.tar.gz taler-exchange-latest.tar.gz Upload the files in `binary mode' to the ftp servers. @node Creating Debian packages,,Upload to GNU mirrors,Releases -@anchor{taler-developer-manual creating-debian-packages}@anchor{3f} +@anchor{taler-developer-manual creating-debian-packages}@anchor{40} @section Creating Debian packages @@ -2401,7 +2415,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{40} +@anchor{taler-developer-manual continuous-integration}@anchor{41} @chapter Continuous integration @@ -2409,21 +2423,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,iOS Apps,Continuous integration,Top -@anchor{taler-developer-manual internationalization}@anchor{41} +@anchor{taler-developer-manual internationalization}@anchor{42} @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. @@ -2440,14 +2454,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{42} +@anchor{taler-developer-manual who-can-register}@anchor{43} @section Who can Register At this time, anyone can register an account at @indicateurl{https://weblate.taler.net/} to create translations. Registered users default to the `Users' and `Viewers' privilege level. @node About Privilege Levels,Upgrading Privileges,Who can Register,Internationalization -@anchor{taler-developer-manual about-privilege-levels}@anchor{43} +@anchor{taler-developer-manual about-privilege-levels}@anchor{44} @section About Privilege Levels @@ -2470,21 +2484,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{44} +@anchor{taler-developer-manual upgrading-privileges}@anchor{45} @section Upgrading Privileges To upgrade from `Users'/`Viewers', a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck. @node How to Create a Project,How to Create a Component,Upgrading Privileges,Internationalization -@anchor{taler-developer-manual how-to-create-a-project}@anchor{45} +@anchor{taler-developer-manual how-to-create-a-project}@anchor{46} @section How to Create a Project The `GNU Taler' project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created. @node How to Create a Component,How to Create a Translation,How to Create a Project,Internationalization -@anchor{taler-developer-manual how-to-create-a-component}@anchor{46} +@anchor{taler-developer-manual how-to-create-a-component}@anchor{47} @section How to Create a Component @@ -2511,7 +2525,7 @@ Under `https://weblate.taler.net/create/component/vcs/': `Repository push URL' - This is generally @code{git+ssh://git@@git.taler.net/<reponame>`} Check with @code{git remote -v}. @item -`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. +`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 `Merge style' - `Rebase', in line with GNU Taler development procedures @@ -2524,7 +2538,7 @@ Under `https://weblate.taler.net/create/component/vcs/': @end itemize @node How to Create a Translation,Translation Standards and Practices,How to Create a Component,Internationalization -@anchor{taler-developer-manual how-to-create-a-translation}@anchor{47} +@anchor{taler-developer-manual how-to-create-a-translation}@anchor{48} @section How to Create a Translation @@ -2536,34 +2550,34 @@ Under `https://weblate.taler.net/create/component/vcs/': 4 - Choose the `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{48} +@anchor{taler-developer-manual translation-standards-and-practices}@anchor{49} @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 `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 `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{49} +@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{4a} @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 iOS Apps,Android Apps,Internationalization,Top -@anchor{taler-developer-manual ios-apps}@anchor{4a} +@anchor{taler-developer-manual ios-apps}@anchor{4b} @chapter iOS Apps @@ -2573,7 +2587,7 @@ This means that contributions made through weblate will not be signed with the i @end menu @node Building Taler Wallet for iOS from source,,,iOS Apps -@anchor{taler-developer-manual build-ios-from-source}@anchor{4b}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{4c} +@anchor{taler-developer-manual build-ios-from-source}@anchor{4c}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{4d} @section Building Taler Wallet for iOS from source @@ -2587,7 +2601,7 @@ the official Git repository@footnote{https://git.taler.net/taler-ios.git}. @end menu @node Compatibility,Building,,Building Taler Wallet for iOS from source -@anchor{taler-developer-manual compatibility}@anchor{4d} +@anchor{taler-developer-manual compatibility}@anchor{4e} @subsection Compatibility @@ -2595,7 +2609,7 @@ The minimum version of iOS supported is 15.0. This app runs on all iPhone models at least as new as the iPhone 6S. @node Building,,Compatibility,Building Taler Wallet for iOS from source -@anchor{taler-developer-manual building}@anchor{4e} +@anchor{taler-developer-manual building}@anchor{4f} @subsection Building @@ -2605,7 +2619,7 @@ and the wallet-core repo@footnote{https://git.taler.net/wallet-core.git}. Have all 3 local repos (wallet-core, quickjs-tart, and this one) adjacent at -the same level (e.g. in a "GNU_Taler" folder) +the same level (e.g. in a “GNU_Taler” folder) Taler.xcworkspace expects the QuickJS framework sub-project to be at @code{../quickjs-tart/QuickJS-rt.xcodeproj}. @@ -2617,17 +2631,17 @@ $ make embedded $ open packages/taler-wallet-embedded/dist @end example -then drag or move its product "taler-wallet-core-qjs.mjs" +then drag or move its product “taler-wallet-core-qjs.mjs” into your quickjs-tart folder right at the top level. -Open Taler.xcworkspace, and set scheme / target to Taler_Wallet. Build&run... +Open Taler.xcworkspace, and set scheme / target to Taler_Wallet. Build&run… -Don't open QuickJS-rt.xcodeproj or TalerWallet.xcodeproj and build anything +Don’t open QuickJS-rt.xcodeproj or TalerWallet.xcodeproj and build anything there - all needed libraries and frameworks will be built automatically from Taler.xcworkspace. @node Android Apps,Code Coverage,iOS Apps,Top -@anchor{taler-developer-manual android-apps}@anchor{4f} +@anchor{taler-developer-manual android-apps}@anchor{50} @chapter Android Apps @@ -2640,7 +2654,7 @@ Taler.xcworkspace. @end menu @node Android App Nightly Builds,Building apps from source,,Android Apps -@anchor{taler-developer-manual android-app-nightly-builds}@anchor{50} +@anchor{taler-developer-manual android-app-nightly-builds}@anchor{51} @section Android App Nightly Builds @@ -2665,7 +2679,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. @@ -2691,7 +2705,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{51}@anchor{taler-developer-manual building-apps-from-source}@anchor{52} +@anchor{taler-developer-manual build-apps-from-source}@anchor{52}@anchor{taler-developer-manual building-apps-from-source}@anchor{53} @section Building apps from source @@ -2715,7 +2729,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 @@ -2732,12 +2746,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 @@ -2770,18 +2784,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{53} +@anchor{taler-developer-manual update-translations}@anchor{54} @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 @@ -2811,7 +2825,7 @@ Afterwards, build the entire project from source and test the UI to ensure that no erroneous translations (missing placeholders) are breaking things. @node Release process,,Update translations,Android Apps -@anchor{taler-developer-manual id1}@anchor{54} +@anchor{taler-developer-manual id1}@anchor{55} @section Release process @@ -2842,12 +2856,12 @@ $ git tag -s $APP-$VERSION @end menu @node F-Droid,Google Play,,Release process -@anchor{taler-developer-manual id2}@anchor{55} +@anchor{taler-developer-manual id2}@anchor{56} @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: @@ -2866,7 +2880,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{56} +@anchor{taler-developer-manual google-play}@anchor{57} @subsection Google Play @@ -2888,7 +2902,7 @@ All uploads are going to the beta track by default. These can be promoted to production later or immediately after upload if you feel daring. @node Code Coverage,Coding Conventions,Android Apps,Top -@anchor{taler-developer-manual id3}@anchor{57}@anchor{taler-developer-manual id4}@anchor{58} +@anchor{taler-developer-manual id3}@anchor{58}@anchor{taler-developer-manual id4}@anchor{59} @chapter Code Coverage @@ -2898,7 +2912,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{59} +@anchor{taler-developer-manual coding-conventions}@anchor{5a} @chapter Coding Conventions @@ -2915,7 +2929,7 @@ GNU Taler is developed primarily in C, Kotlin, Python, Swift and TypeScript. @end menu @node Components written in C,Shell Scripts,,Coding Conventions -@anchor{taler-developer-manual components-written-in-c}@anchor{5a} +@anchor{taler-developer-manual components-written-in-c}@anchor{5b} @section Components written in C @@ -2935,7 +2949,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{5b} +@anchor{taler-developer-manual naming-conventions}@anchor{5c} @subsection Naming conventions @@ -2949,22 +2963,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 @@ -2997,22 +3011,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 @@ -3054,14 +3068,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 @@ -3081,7 +3095,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 @@ -3091,12 +3105,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{5c} +@anchor{taler-developer-manual shell-scripts}@anchor{5d} @section Shell Scripts @@ -3123,7 +3137,7 @@ $ set -eu @end example @node Kotlin,Python,Shell Scripts,Coding Conventions -@anchor{taler-developer-manual kotlin}@anchor{5d} +@anchor{taler-developer-manual kotlin}@anchor{5e} @section Kotlin @@ -3131,7 +3145,7 @@ We so far have no specific guidelines, please follow best practices for the language. @node Python,Swift,Kotlin,Coding Conventions -@anchor{taler-developer-manual python}@anchor{5e} +@anchor{taler-developer-manual python}@anchor{5f} @section Python @@ -3143,14 +3157,14 @@ for the language. @end menu @node Supported Python Versions,Style,,Python -@anchor{taler-developer-manual supported-python-versions}@anchor{5f} +@anchor{taler-developer-manual supported-python-versions}@anchor{60} @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{60} +@anchor{taler-developer-manual style}@anchor{61} @subsection Style @@ -3160,7 +3174,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{61} +@anchor{taler-developer-manual python-for-scripting}@anchor{62} @subsection Python for Scripting @@ -3177,26 +3191,26 @@ 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 Swift,TypeScript,Python,Coding Conventions -@anchor{taler-developer-manual swift}@anchor{62} +@anchor{taler-developer-manual swift}@anchor{63} @section Swift Please follow best practices for the language. @node TypeScript,,Swift,Coding Conventions -@anchor{taler-developer-manual typescript}@anchor{63} +@anchor{taler-developer-manual typescript}@anchor{64} @section TypeScript Please follow best practices for the language. @node Testing library,User-Facing Terminology,Coding Conventions,Top -@anchor{taler-developer-manual testing-library}@anchor{64} +@anchor{taler-developer-manual testing-library}@anchor{65} @chapter Testing library @@ -3269,7 +3283,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{65} +@anchor{taler-developer-manual user-facing-terminology}@anchor{66} @chapter User-Facing Terminology @@ -3283,7 +3297,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{66} +@anchor{taler-developer-manual terms-to-avoid}@anchor{67} @section Terms to Avoid @@ -3295,21 +3309,21 @@ used in the user interface and help materials. Refreshing is the internal technical terminology for the protocol to give change for partially spent coins -`Use instead': "Obtaining change" +`Use instead': “Obtaining change” @item Charge Charge has two opposite meanings (charge to a credit card vs. charge a battery). This can confuse users. -`Use instead': "Obtain", "Credit", "Debit", "Withdraw", "Top up" +`Use instead': “Obtain”, “Credit”, “Debit”, “Withdraw”, “Top up” @item Coin Coins are an internal construct, the user should never be aware that their balance is represented by coins of different denominations. -`Use instead': "(Digital) Cash" or "(Wallet) Balance" +`Use instead': “(Digital) Cash” or “(Wallet) Balance” @item Consumer @@ -3324,7 +3338,7 @@ of the signed contract terms for an order. `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 @@ -3332,14 +3346,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). -`Use instead': "Privacy-preserving", "Privacy-friendly" +`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. -`Use instead': In the event history, "re-activated digital content purchase" +`Use instead': In the event history, “re-activated digital content purchase” could be used. (FIXME: this is still not nice.) @item Session ID @@ -3359,7 +3373,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{67} +@anchor{taler-developer-manual terms-to-use}@anchor{68} @section Terms to Use @@ -3375,16 +3389,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 @@ -3392,12 +3406,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 @@ -3406,12 +3420,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{68} +@anchor{taler-developer-manual developer-glossary}@anchor{69} @chapter Developer Glossary @@ -3420,134 +3434,134 @@ use when talking to end users or even system administrators. @table @asis -@anchor{taler-developer-manual term-absolute-time}@anchor{69} +@anchor{taler-developer-manual term-absolute-time}@anchor{6a} @geindex absolute time @item absolute time -method of keeping time in @ref{6a,,GNUnet} where the time is represented +method of keeping time in @ref{6b,,GNUnet} where the time is represented as the number of microseconds since 1.1.1970 (UNIX epoch). Called -absolute time in contrast to @ref{6b,,relative time}. -@anchor{taler-developer-manual term-aggregate}@anchor{6c} +absolute time in contrast to @ref{6c,,relative time}. +@anchor{taler-developer-manual term-aggregate}@anchor{6d} @geindex aggregate @item aggregate -the @ref{6d,,exchange} combines multiple payments received by the -same @ref{6e,,merchant} into one larger @ref{6f,,wire transfer} to -the respective merchant's @ref{70,,bank} account -@anchor{taler-developer-manual term-auditor}@anchor{71} +the @ref{6e,,exchange} combines multiple payments received by the +same @ref{6f,,merchant} into one larger @ref{70,,wire transfer} to +the respective merchant’s @ref{71,,bank} account +@anchor{taler-developer-manual term-auditor}@anchor{72} @geindex auditor @item auditor -trusted third party that verifies that the @ref{6d,,exchange} is operating correctly -@anchor{taler-developer-manual term-bank}@anchor{70} +trusted third party that verifies that the @ref{6e,,exchange} is operating correctly +@anchor{taler-developer-manual term-bank}@anchor{71} @geindex bank @item bank traditional financial service provider who offers -@ref{6f,,wire transfers} between accounts -@anchor{taler-developer-manual term-buyer}@anchor{72} +@ref{70,,wire transfers} between accounts +@anchor{taler-developer-manual term-buyer}@anchor{73} @geindex buyer @item buyer -individual in control of a Taler @ref{73,,wallet}, usually using it to -@ref{74,,spend} the @ref{75,,coins} on @ref{76,,contracts} (see also @ref{77,,customer}). -@anchor{taler-developer-manual term-close}@anchor{78} +individual in control of a Taler @ref{74,,wallet}, usually using it to +@ref{75,,spend} the @ref{76,,coins} on @ref{77,,contracts} (see also @ref{78,,customer}). +@anchor{taler-developer-manual term-close}@anchor{79} @geindex close @item close -operation an @ref{6d,,exchange} performs on a @ref{79,,reserve} that has not been -@ref{7a,,emptied} by @ref{7b,,withdraw} operations. When closing a reserve, the -exchange wires the remaining funds back to the customer, minus a @ref{7c,,fee} +operation an @ref{6e,,exchange} performs on a @ref{7a,,reserve} that has not been +@ref{7b,,emptied} by @ref{7c,,withdraw} operations. When closing a reserve, the +exchange wires the remaining funds back to the customer, minus a @ref{7d,,fee} for closing -@anchor{taler-developer-manual term-coin}@anchor{75} +@anchor{taler-developer-manual term-coin}@anchor{76} @geindex coin @item coin -coins are individual token representing a certain amount of value, also known as the @ref{7d,,denomination} of the coin -@anchor{taler-developer-manual term-contract}@anchor{76} +coins are individual token representing a certain amount of value, also known as the @ref{7e,,denomination} of the coin +@anchor{taler-developer-manual term-contract}@anchor{77} @geindex contract @item contract -formal agreement between @ref{6e,,merchant} and @ref{77,,customer} specifying the -@ref{7e,,contract terms} and signed by the merchant and the @ref{75,,coins} of the +formal agreement between @ref{6f,,merchant} and @ref{78,,customer} specifying the +@ref{7f,,contract terms} and signed by the merchant and the @ref{76,,coins} of the customer -@anchor{taler-developer-manual term-contract-terms}@anchor{7e} +@anchor{taler-developer-manual term-contract-terms}@anchor{7f} @geindex contract terms @item contract terms the individual clauses specifying what the buyer is purchasing from the -@ref{6e,,merchant} -@anchor{taler-developer-manual term-customer}@anchor{77} +@ref{6f,,merchant} +@anchor{taler-developer-manual term-customer}@anchor{78} @geindex customer @item customer individual that directs the buyer (perhaps the same individual) to make a purchase -@anchor{taler-developer-manual term-denomination}@anchor{7d} +@anchor{taler-developer-manual term-denomination}@anchor{7e} @geindex denomination @item denomination -unit of currency, specifies both the currency and the face value of a @ref{75,,coin}, +unit of currency, specifies both the currency and the face value of a @ref{76,,coin}, as well as associated fees and validity periods -@anchor{taler-developer-manual term-denomination-key}@anchor{7f} +@anchor{taler-developer-manual term-denomination-key}@anchor{80} @geindex denomination key @item denomination key -(RSA) key used by the exchange to certify that a given @ref{75,,coin} is valid and of a -particular @ref{7d,,denomination} -@anchor{taler-developer-manual term-deposit}@anchor{80} +(RSA) key used by the exchange to certify that a given @ref{76,,coin} is valid and of a +particular @ref{7e,,denomination} +@anchor{taler-developer-manual term-deposit}@anchor{81} @geindex deposit @item deposit operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using an -@ref{6c,,aggregate} @ref{6f,,wire transfer} -@anchor{taler-developer-manual term-dirty}@anchor{81} +@ref{6d,,aggregate} @ref{70,,wire transfer} +@anchor{taler-developer-manual term-dirty}@anchor{82} @geindex dirty @item dirty -a @ref{75,,coin} is dirty if its public key may be known to an entity other than +a @ref{76,,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{82} +link multiple transactions of coin’s owner if the coin is not refreshed +@anchor{taler-developer-manual term-drain}@anchor{83} @geindex drain @item drain process by which an exchange operator takes the profits -(from @ref{7c,,fees}) out of the escrow account and moves them into +(from @ref{7d,,fees}) out of the escrow account and moves them into their regular business account -@anchor{taler-developer-manual term-empty}@anchor{7a} +@anchor{taler-developer-manual term-empty}@anchor{7b} @geindex empty @item empty -a @ref{79,,reserve} is being emptied when a @ref{73,,wallet} is using the -reserve's private key to @ref{7b,,withdraw} coins from it. This reduces +a @ref{7a,,reserve} is being emptied when a @ref{74,,wallet} is using the +reserve’s private key to @ref{7c,,withdraw} coins from it. This reduces the balance of the reserve. Once the balance reaches zero, we say that the reserve has been (fully) emptied. Reserves that are not emptied -(which is the normal process) are @ref{78,,closed} by the exchange. -@anchor{taler-developer-manual term-exchange}@anchor{6d} +(which is the normal process) are @ref{79,,closed} by the exchange. +@anchor{taler-developer-manual term-exchange}@anchor{6e} @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{83} +@anchor{taler-developer-manual term-expired}@anchor{84} @geindex expired @item expired @@ -3556,44 +3570,44 @@ 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{84} +@anchor{taler-developer-manual term-fakebank}@anchor{85} @geindex fakebank @item fakebank -implementation of the @ref{70,,bank} API in memory to be used only for test +implementation of the @ref{71,,bank} API in memory to be used only for test cases. -@anchor{taler-developer-manual term-fee}@anchor{7c} +@anchor{taler-developer-manual term-fee}@anchor{7d} @geindex fee @item fee -an @ref{6d,,exchange} charges various fees for its service. The different +an @ref{6e,,exchange} charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for -@ref{7b,,withdrawing}, @ref{80,,depositing}, @ref{85,,melting}, and -@ref{86,,refunding}. Furthermore, there are fees per wire transfer -when a @ref{79,,reserve} is @ref{78,,closed} -and for @ref{6c,,aggregate} @ref{6f,,wire transfers} -to the @ref{6e,,merchant}. -@anchor{taler-developer-manual term-fresh}@anchor{87} +@ref{7c,,withdrawing}, @ref{81,,depositing}, @ref{86,,melting}, and +@ref{87,,refunding}. Furthermore, there are fees per wire transfer +when a @ref{7a,,reserve} is @ref{79,,closed} +and for @ref{6d,,aggregate} @ref{70,,wire transfers} +to the @ref{6f,,merchant}. +@anchor{taler-developer-manual term-fresh}@anchor{88} @geindex fresh @item fresh -a @ref{75,,coin} is fresh if its public key is only known to the customer -@anchor{taler-developer-manual term-GNUnet}@anchor{6a} +a @ref{76,,coin} is fresh if its public key is only known to the customer +@anchor{taler-developer-manual term-GNUnet}@anchor{6b} @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{88} +@anchor{taler-developer-manual term-JSON}@anchor{89} @geindex JSON @item JSON @@ -3602,182 +3616,182 @@ JavaScript Object Notation (JSON) is a 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{89} +@anchor{taler-developer-manual term-kappa}@anchor{8a} @geindex kappa @item kappa -security parameter used in the @ref{8a,,refresh} protocol. Defined to be 3. +security parameter used in the @ref{8b,,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{8b} +@anchor{taler-developer-manual term-libeufin}@anchor{8c} @geindex libeufin @item libeufin Kotlin component that implements a regional currency bank and an adapter to communicate via EBICS with European core banking systems. -@anchor{taler-developer-manual term-link}@anchor{8c} +@anchor{taler-developer-manual term-link}@anchor{8d} @geindex link @item link -specific step in the @ref{8a,,refresh} protocol that an exchange must offer -to prevent abuse of the @ref{8a,,refresh} mechanism. The link step is +specific step in the @ref{8b,,refresh} protocol that an exchange must offer +to prevent abuse of the @ref{8b,,refresh} mechanism. The link step is not needed in normal operation, it just must be offered. -@anchor{taler-developer-manual term-master-key}@anchor{8d} +@anchor{taler-developer-manual term-master-key}@anchor{8e} @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{85} +@anchor{taler-developer-manual term-melt}@anchor{86} @geindex melt @item melt -step of the @ref{8a,,refresh} protocol where a @ref{81,,dirty} @ref{75,,coin} -is invalidated to be reborn @ref{87,,fresh} in a subsequent -@ref{8e,,reveal} step. -@anchor{taler-developer-manual term-merchant}@anchor{6e} +step of the @ref{8b,,refresh} protocol where a @ref{82,,dirty} @ref{76,,coin} +is invalidated to be reborn @ref{88,,fresh} in a subsequent +@ref{8f,,reveal} step. +@anchor{taler-developer-manual term-merchant}@anchor{6f} @geindex merchant @item merchant party receiving payments (usually in return for goods or services) -@anchor{taler-developer-manual term-message-signing-key}@anchor{8f} +@anchor{taler-developer-manual term-message-signing-key}@anchor{90} @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{90} +@anchor{taler-developer-manual term-order}@anchor{91} @geindex order @item order offer made by the merchant to a wallet; pre-cursor to a contract where the wallet is not yet fixed. Turns -into a @ref{76,,contract} when a wallet claims the order. -@anchor{taler-developer-manual term-owner}@anchor{91} +into a @ref{77,,contract} when a wallet claims the order. +@anchor{taler-developer-manual term-owner}@anchor{92} @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{92} +@anchor{taler-developer-manual term-planchet}@anchor{93} @geindex planchet @item planchet -precursor data for a @ref{75,,coin}. A planchet includes the coin's internal +precursor data for a @ref{76,,coin}. A planchet includes the coin’s internal secrets (coin private key, blinding factor), but lacks the RSA signature -of the @ref{6d,,exchange}. When @ref{7b,,withdrawing}, a @ref{73,,wallet} +of the @ref{6e,,exchange}. When @ref{7c,,withdrawing}, a @ref{74,,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{93} +@anchor{taler-developer-manual term-privacy-policy}@anchor{94} @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{94} +@anchor{taler-developer-manual term-proof}@anchor{95} @geindex proof @item proof Message that cryptographically demonstrates that a particular claim is correct. -@anchor{taler-developer-manual term-proposal}@anchor{95} +@anchor{taler-developer-manual term-proposal}@anchor{96} @geindex proposal @item proposal -a list of @ref{7e,,contract terms} that has been completed and signed by the +a list of @ref{7f,,contract terms} that has been completed and signed by the merchant backend. -@anchor{taler-developer-manual term-purchase}@anchor{96} +@anchor{taler-developer-manual term-purchase}@anchor{97} @geindex purchase @item purchase -Refers to the overall process of negotiating a @ref{76,,contract} and then -making a payment with @ref{75,,coins} to a @ref{6e,,merchant}. -@anchor{taler-developer-manual term-recoup}@anchor{97} +Refers to the overall process of negotiating a @ref{77,,contract} and then +making a payment with @ref{76,,coins} to a @ref{6f,,merchant}. +@anchor{taler-developer-manual term-recoup}@anchor{98} @geindex recoup @item recoup Operation by which an exchange returns the value of coins affected -by a @ref{98,,revocation} to their @ref{91,,owner}, either by allowing the owner to -withdraw new coins or wiring funds back to the bank account of the @ref{91,,owner}. -@anchor{taler-developer-manual term-refresh}@anchor{8a} +by a @ref{99,,revocation} to their @ref{92,,owner}, either by allowing the owner to +withdraw new coins or wiring funds back to the bank account of the @ref{92,,owner}. +@anchor{taler-developer-manual term-refresh}@anchor{8b} @geindex refresh @item refresh -operation by which a @ref{81,,dirty} @ref{75,,coin} is converted into one or more -@ref{87,,fresh} coins. Involves @ref{85,,melting} the @ref{81,,dirty} coins and -then @ref{8e,,revealing} so-called @ref{99,,transfer keys}. -@anchor{taler-developer-manual term-refresh-commitment}@anchor{9a} +operation by which a @ref{82,,dirty} @ref{76,,coin} is converted into one or more +@ref{88,,fresh} coins. Involves @ref{86,,melting} the @ref{82,,dirty} coins and +then @ref{8f,,revealing} so-called @ref{9a,,transfer keys}. +@anchor{taler-developer-manual term-refresh-commitment}@anchor{9b} @geindex refresh commitment @item refresh commitment -data that the wallet commits to during the @ref{85,,melt} stage of the -@ref{8a,,refresh} protocol where it -has to prove to the @ref{6d,,exchange} that it is deriving the @ref{87,,fresh} +data that the wallet commits to during the @ref{86,,melt} stage of the +@ref{8b,,refresh} protocol where it +has to prove to the @ref{6e,,exchange} that it is deriving the @ref{88,,fresh} coins as specified by the Taler protocol. The commitment is verified -probabilistically (see: @ref{89,,kappa}) during the @ref{8e,,reveal} stage. -@anchor{taler-developer-manual term-refund}@anchor{86} +probabilistically (see: @ref{8a,,kappa}) during the @ref{8f,,reveal} stage. +@anchor{taler-developer-manual term-refund}@anchor{87} @geindex refund @item refund operation by which a merchant steps back from the right to funds that he -obtained from a @ref{80,,deposit} operation, giving the right to the funds back +obtained from a @ref{81,,deposit} operation, giving the right to the funds back to the customer -@anchor{taler-developer-manual term-refund-transaction-id}@anchor{9b} +@anchor{taler-developer-manual term-refund-transaction-id}@anchor{9c} @geindex refund transaction id @item refund transaction id -unique number by which a merchant identifies a @ref{86,,refund}. Needed +unique number by which a merchant identifies a @ref{87,,refund}. Needed as refunds can be partial and thus there could be multiple refunds for -the same @ref{96,,purchase}. -@anchor{taler-developer-manual term-relative-time}@anchor{6b} +the same @ref{97,,purchase}. +@anchor{taler-developer-manual term-relative-time}@anchor{6c} @geindex relative time @item relative time -method of keeping time in @ref{6a,,GNUnet} where the time is represented +method of keeping time in @ref{6b,,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{69,,absolute time}. -@anchor{taler-developer-manual term-reserve}@anchor{79} +contrast to @ref{6a,,absolute time}. +@anchor{taler-developer-manual term-reserve}@anchor{7a} @geindex reserve @item reserve accounting mechanism used by the exchange to track customer funds -from incoming @ref{6f,,wire transfers}. A reserve is created whenever +from incoming @ref{70,,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{73,,wallet} -to @ref{7b,,withdraw} up to the amount received in @ref{87,,fresh} -@ref{75,,coins} from the reserve, thereby emptying the reserve. If a -reserve is not emptied, the exchange will eventually @ref{78,,close} it. +in the subject. The exchange then allows the customer’s @ref{74,,wallet} +to @ref{7c,,withdraw} up to the amount received in @ref{88,,fresh} +@ref{76,,coins} from the reserve, thereby emptying the reserve. If a +reserve is not emptied, the exchange will eventually @ref{79,,close} 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{8e} +@anchor{taler-developer-manual term-reveal}@anchor{8f} @geindex reveal @item reveal -step in the @ref{8a,,refresh} protocol where some of the transfer private +step in the @ref{8b,,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{87,,fresh} coins. -@anchor{taler-developer-manual term-revoke}@anchor{98} +In the reveal step, the exchange returns the signed @ref{88,,fresh} coins. +@anchor{taler-developer-manual term-revoke}@anchor{99} @geindex revoke @item revoke @@ -3786,79 +3800,79 @@ 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{9c} +@anchor{taler-developer-manual term-sharing}@anchor{9d} @geindex sharing @item sharing -users can share ownership of a @ref{75,,coin} by sharing access to the coin's +users can share ownership of a @ref{76,,coin} by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time. -@anchor{taler-developer-manual term-spend}@anchor{74} +@anchor{taler-developer-manual term-spend}@anchor{75} @geindex spend @item spend operation by which a customer gives a merchant the right to deposit coins in return for merchandise -@anchor{taler-developer-manual term-terms}@anchor{9d} +@anchor{taler-developer-manual term-terms}@anchor{9e} @geindex terms @item terms the general terms of service of an operator, possibly including -the @ref{93,,privacy policy}. Not to be confused with the -@ref{7e,,contract terms} which are about the specific purchase. -@anchor{taler-developer-manual term-transaction}@anchor{9e} +the @ref{94,,privacy policy}. Not to be confused with the +@ref{7f,,contract terms} which are about the specific purchase. +@anchor{taler-developer-manual term-transaction}@anchor{9f} @geindex transaction @item transaction method by which ownership is exclusively transferred from one entity -@anchor{taler-developer-manual term-transfer-key}@anchor{99} +@anchor{taler-developer-manual term-transfer-key}@anchor{9a} @geindex transfer key @item transfer key -special cryptographic key used in the @ref{8a,,refresh} protocol, some of which -are revealed during the @ref{8e,,reveal} step. Note that transfer keys have, -despite the name, no relationship to @ref{6f,,wire transfers}. They merely -help to transfer the value from a @ref{81,,dirty} coin to a @ref{87,,fresh} coin -@anchor{taler-developer-manual term-user}@anchor{9f} +special cryptographic key used in the @ref{8b,,refresh} protocol, some of which +are revealed during the @ref{8f,,reveal} step. Note that transfer keys have, +despite the name, no relationship to @ref{70,,wire transfers}. They merely +help to transfer the value from a @ref{82,,dirty} coin to a @ref{88,,fresh} coin +@anchor{taler-developer-manual term-user}@anchor{a0} @geindex user @item user any individual using the Taler payment system -(see @ref{77,,customer}, @ref{72,,buyer}, @ref{6e,,merchant}). -@anchor{taler-developer-manual term-version}@anchor{a0} +(see @ref{78,,customer}, @ref{73,,buyer}, @ref{6f,,merchant}). +@anchor{taler-developer-manual term-version}@anchor{a1} @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{6d,,exchange}, -@ref{71,,auditor} or @ref{6e,,merchant}. There is a protocol +the state of the table structure in the database of an @ref{6e,,exchange}, +@ref{72,,auditor} or @ref{6f,,merchant}. There is a protocol version (CURRENT:REVISION:AGE, see GNU libtool) which specifies -the network protocol spoken by an @ref{6d,,exchange} or @ref{6e,,merchant} +the network protocol spoken by an @ref{6e,,exchange} or @ref{6f,,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{73} +@anchor{taler-developer-manual term-wallet}@anchor{74} @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{a1} +@anchor{taler-developer-manual term-WebExtension}@anchor{a2} @geindex WebExtension @item WebExtension Cross-browser API used to implement the GNU Taler wallet browser extension. -@anchor{taler-developer-manual term-wire-gateway}@anchor{a2} +@anchor{taler-developer-manual term-wire-gateway}@anchor{a3} @geindex wire gateway @item wire gateway @@ -3867,13 +3881,13 @@ API used by the exchange to talk with some real-time gross settlement system (core banking system, blockchain) to notice inbound credits wire transfers (during withdraw) and to trigger outbound debit wire transfers (primarily for deposits). -@anchor{taler-developer-manual term-wire-transfer}@anchor{6f} +@anchor{taler-developer-manual term-wire-transfer}@anchor{70} @geindex wire transfer @item wire transfer -a wire transfer is a method of sending funds between @ref{70,,bank} accounts -@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a3} +a wire transfer is a method of sending funds between @ref{71,,bank} accounts +@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a4} @geindex wire transfer identifier @item wire transfer identifier @@ -3881,26 +3895,26 @@ a wire transfer is a method of sending funds between @ref{70,,bank} accounts 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{7b} +@anchor{taler-developer-manual term-withdraw}@anchor{7c} @geindex withdraw @item withdraw -operation by which a @ref{73,,wallet} can convert funds from a @ref{79,,reserve} to +operation by which a @ref{74,,wallet} can convert funds from a @ref{7a,,reserve} to fresh coins -@anchor{taler-developer-manual term-zombie}@anchor{a4} +@anchor{taler-developer-manual term-zombie}@anchor{a5} @geindex zombie @item zombie -@ref{75,,coin} where the respective @ref{7f,,denomination key} is past its -@ref{80,,deposit} @ref{83,,expiration} time, but which is still (again) valid -for an operation because it was @ref{85,,melted} while it was still -valid, and then later again credited during a @ref{97,,recoup} process +@ref{76,,coin} where the respective @ref{80,,denomination key} is past its +@ref{81,,deposit} @ref{84,,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{98,,recoup} process @end table @node Developer Tools,Index,Developer Glossary,Top -@anchor{taler-developer-manual developer-tools}@anchor{a5} +@anchor{taler-developer-manual developer-tools}@anchor{a6} @chapter Developer Tools @@ -3913,7 +3927,7 @@ developer. @end menu @node taler-harness,,,Developer Tools -@anchor{taler-developer-manual taler-harness}@anchor{a6} +@anchor{taler-developer-manual taler-harness}@anchor{a7} @section taler-harness |