diff options
Diffstat (limited to 'texinfo/taler-developer-manual.texi')
| -rw-r--r-- | texinfo/taler-developer-manual.texi | 592 |
1 files changed, 340 insertions, 252 deletions
diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 4896a6ff..8bad28d3 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.texi @@ -21,7 +21,7 @@ @copying @quotation -GNU Taler 0.8.2, Aug 08, 2021 +GNU Taler 0.8.2, Jun 20, 2022 GNU Taler team @@ -69,6 +69,7 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) * GNU Taler Release Checklist:: * GNU Taler Demo Upgrade Checklist:: * Fundamentals:: +* Debian and Ubuntu Repositories:: * Language-Specific Guidelines:: * Taler Deployment on gv.taler.net: Taler Deployment on gv taler net. * Demo Upgrade Procedure:: @@ -103,13 +104,13 @@ Wallet: [ ] build wallet @item -[ ] verify wallet works against ‘test.taler.net’ +[ ] verify wallet works against 'test.taler.net' @item [ ] tag repo. @item -[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’ +[ ] upgrade 'demo.taler.net' to 'test.taler.net' @item [ ] upload new wallet release to app store @@ -133,7 +134,7 @@ For exchange: @itemize - @item -[ ] check no compiler warnings at “-Wall” +[ ] check no compiler warnings at "-Wall" @item [ ] ensure Coverity static analysis passes @@ -142,10 +143,10 @@ For exchange: [ ] make check. @item -[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’ +[ ] upgrade 'demo.taler.net' to 'test.taler.net' @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. @@ -178,7 +179,7 @@ For merchant (C backend): @itemize - @item -[ ] check no compiler warnings at “-Wall” +[ ] check no compiler warnings at "-Wall" @item [ ] ensure Coverity static analysis passes @@ -187,10 +188,10 @@ For merchant (C backend): [ ] make check. @item -[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’ +[ ] upgrade 'demo.taler.net' to 'test.taler.net' @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. @@ -365,7 +366,7 @@ and related components. It is not intended for a general audience. @end quotation @end cartouche -@node Fundamentals,Language-Specific Guidelines,GNU Taler Demo Upgrade Checklist,Top +@node Fundamentals,Debian and Ubuntu Repositories,GNU Taler Demo Upgrade Checklist,Top @anchor{taler-developer-manual fundamentals}@anchor{6} @chapter Fundamentals @@ -376,6 +377,7 @@ and related components. It is not intended for a general audience. * Committing code:: * Observing changes:: * Communication:: +* What to put in bootstrap:: @end menu @@ -486,7 +488,7 @@ our main dependencies, namely GNUnet and GNU libmicrohttpd. While it can be high volume, the lists is a good way to follow overall development. -@node Communication,,Observing changes,Fundamentals +@node Communication,What to put in bootstrap,Observing changes,Fundamentals @anchor{taler-developer-manual communication}@anchor{b} @section Communication @@ -497,8 +499,92 @@ all developers should probably subscribe to the low-volume Taler mailinglist. There are separate low-volume mailinglists for gnunet-developers (@@gnu.org) and for libmicrohttpd (@@gnu.org). -@node Language-Specific Guidelines,Taler Deployment on gv taler net,Fundamentals,Top -@anchor{taler-developer-manual language-specific-guidelines}@anchor{c} +@node What to put in bootstrap,,Communication,Fundamentals +@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{c} +@section What to put in bootstrap + + +Each repository has a @code{bootstrap} script, which contains commands for the +developer to run after a repository checkout (i.e., after @code{git clone} or +@code{git pull}). +Typically, this updates and initializes submodules, prepares the tool chain, +and runs @code{autoreconf}. +The last step generates the @code{configure} script, whether for immediate use or +for inclusion in the distribution tarball. + +One common submodule is @code{contrib/gana}, which pulls from the +GNUnet GANA repository@footnote{https://git.gnunet.org/gana.git/}. +For example, in the +Taler exchange repository@footnote{https://git.taler.net/exchange.git}, +the bootstrap script eventually runs the @code{git submodule update} command +early on, and later runs script @code{./contrib/gana.sh}, which in turn +runs script @code{./contrib/gana-update.sh}, which performs various tasks, +such as generating the file @code{src/include/taler_signatures.h}. + +Thus, to update that file, you need to: + + +@itemize - + +@item +(in GANA repo) Find a suitable (unused) name and number for the Signature +Purposes database. + +@item +Add it to GANA, in @code{gnunet-signatures/registry.rec}. +(You can check for uniqueness with the @code{recfix} utility.) + +@item +Commit the change, and push it to the GANA Git repo. + +@item +(in Taler Repo) Change directory to @code{contrib/gana} and run +command @code{git pull} there. + +@item +Bootstrap, configure, do @code{make install}, @code{make check}, etc. +(Basically, make sure the change does not break anything.) + +@item +Commit the submodule change, and push it to the Taler exchange Git repo. +@end itemize + +A similiar 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} +@chapter Debian and Ubuntu Repositories + + +We package our software for Debian and Ubuntu. + +@menu +* Nightly Repositories:: + +@end menu + +@node Nightly Repositories,,,Debian and Ubuntu Repositories +@anchor{taler-developer-manual nightly-repositories}@anchor{e} +@section Nightly Repositories + + +To try the latest, unstable and untested versions of packages, +you can add the nightly package sources. + +@example +# For Ubuntu (focal-fossa) +$ echo "deb https://deb.taler.net/apt-nightly focal-taler-nightly main" > /etc/apt/sources.list.d/taler.list + +# For Debian (bullseye) +$ echo "deb https://deb.taler.net/apt-nightly bullseye-taler-nightly main" > /etc/apt/sources.list.d/taler.list + +# Both: Install signing key for nightly packages +$ 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} @chapter Language-Specific Guidelines @@ -510,7 +596,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{d} +@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{10} @chapter Taler Deployment on gv.taler.net @@ -531,7 +617,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{e} +@anchor{taler-developer-manual dns}@anchor{11} @section DNS @@ -540,7 +626,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{f} +@anchor{taler-developer-manual user-acccounts}@anchor{12} @section User Acccounts @@ -576,7 +662,7 @@ 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{10} +@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{13} @chapter Demo Upgrade Procedure @@ -601,7 +687,7 @@ sure everything is working. @end menu @node Tagging components,Environment Layout,,Demo Upgrade Procedure -@anchor{taler-developer-manual tagging-components}@anchor{11} +@anchor{taler-developer-manual tagging-components}@anchor{14} @section Tagging components @@ -617,7 +703,7 @@ SS = serial @end example @node Environment Layout,Using envcfg py,Tagging components,Demo Upgrade Procedure -@anchor{taler-developer-manual environment-layout}@anchor{12} +@anchor{taler-developer-manual environment-layout}@anchor{15} @section Environment Layout @@ -640,7 +726,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{13} +@anchor{taler-developer-manual using-envcfg-py}@anchor{16} @section Using envcfg.py @@ -671,7 +757,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{14} +@anchor{taler-developer-manual bootstrapping-an-environment}@anchor{17} @section Bootstrapping an Environment @@ -689,7 +775,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{15} +@anchor{taler-developer-manual upgrading-an-existing-environment}@anchor{18} @section Upgrading an Existing Environment @@ -705,7 +791,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{16} +@anchor{taler-developer-manual switching-demo-colors}@anchor{19} @section Switching Demo Colors @@ -717,7 +803,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{17} +@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{1a} @chapter Environments and Builders on taler.net @@ -734,7 +820,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{18} +@anchor{taler-developer-manual buildbot-implementation}@anchor{1b} @section Buildbot implementation @@ -779,13 +865,13 @@ 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{19} +@anchor{taler-developer-manual documentation-builder}@anchor{1c} @section Documentation Builder All the Taler documentation is built by the user @code{docbuilder} that runs a Buildbot worker. The following commands set the @code{docbuilder} up, -starting with a empty home directory. +starting with an empty home directory. @example # Log-in as the 'docbuilder' user. @@ -801,13 +887,13 @@ $ 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{1a} +@anchor{taler-developer-manual website-builder}@anchor{1d} @section Website Builder Taler Websites, @code{www.taler.net} and @code{stage.taler.net}, are built by the user @code{taler-websites} by the means of a Buildbot worker. The following -commands set the @code{taler-websites} up, starting with a empty home directory. +commands set the @code{taler-websites} up, starting with an empty home directory. @example # Log-in as the 'taler-websites' user. @@ -823,7 +909,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{1b} +@anchor{taler-developer-manual code-coverage}@anchor{1e} @section Code coverage @@ -846,7 +932,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{1c} +@anchor{taler-developer-manual service-checker}@anchor{1f} @section Service Checker @@ -868,7 +954,7 @@ $ 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{1d} +@anchor{taler-developer-manual tipping-reserve-top-up}@anchor{20} @section Tipping reserve top-up @@ -889,7 +975,7 @@ $ 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{1e} +@anchor{taler-developer-manual producing-auditor-reports}@anchor{21} @section Producing auditor reports @@ -910,11 +996,11 @@ $ 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{1f} +@anchor{taler-developer-manual database-schema-versioning}@anchor{22} @section Database schema versioning -The Postgres databases of the exchange and the auditor are versioned. +The PostgreSQL databases of the exchange and the auditor are versioned. See the 0000.sql file in the respective directory for documentation. Every set of changes to the database schema must be stored in a new @@ -926,7 +1012,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{20} +@anchor{taler-developer-manual releases}@anchor{23} @chapter Releases @@ -942,7 +1028,7 @@ outside of this versioning. @end menu @node Release Process and Checklists,Tagging,,Releases -@anchor{taler-developer-manual release-process-and-checklists}@anchor{21} +@anchor{taler-developer-manual release-process-and-checklists}@anchor{24} @section Release Process and Checklists @@ -976,7 +1062,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{22} +@anchor{taler-developer-manual tagging}@anchor{25} @section Tagging @@ -988,7 +1074,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{23} +@anchor{taler-developer-manual database-for-tests}@anchor{26} @section Database for tests @@ -1006,7 +1092,7 @@ unauthorized access. @end cartouche @node Exchange merchant,Wallet WebExtension,Database for tests,Releases -@anchor{taler-developer-manual exchange-merchant}@anchor{24} +@anchor{taler-developer-manual exchange-merchant}@anchor{27} @section Exchange, merchant @@ -1065,7 +1151,7 @@ $ make install check @end example @node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases -@anchor{taler-developer-manual wallet-webextension}@anchor{25} +@anchor{taler-developer-manual wallet-webextension}@anchor{28} @section Wallet WebExtension @@ -1079,7 +1165,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{26} +@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{29} @section Upload to GNU mirrors @@ -1096,7 +1182,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{27} +@anchor{taler-developer-manual creating-debian-packages}@anchor{2a} @section Creating Debian packages @@ -1114,24 +1200,26 @@ in the respective source directory (GNUnet, exchange, merchant) to create the @code{.deb} files. Note that they will be created in the parent directory. This can be done on gv.taler.net, or on another (secure) machine. +On @code{gv}, we use the @code{aptbuilder} user to manage the reprepro repository. + Next, the @code{*.deb} files should be copied to gv.taler.net, say to -@code{/root/incoming}. Then, run +@code{/home/aptbuilder/incoming}. Then, run @example -# cd /var/www/repos/apt/debian/ -# reprepro includedeb sid /root/incoming/*.deb +# cd /home/aptbuilder/apt +# reprepro includedeb bullseye ~/incoming/*.deb @end example -to import all Debian files from @code{/root/incoming/} into the @code{sid} +to import all Debian files from @code{~/incoming/} into the @code{bullseye} distribution. If Debian packages were build against other distributions, reprepro may need to be first configured for those and the import command updated accordingly. -Finally, make sure to clean up @code{/root/incoming/} (by deleting the +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{28} +@anchor{taler-developer-manual continuous-integration}@anchor{2b} @chapter Continuous integration @@ -1149,7 +1237,7 @@ There is also the possibility to trigger builds manually, but this is only reserved to “admin” users. @node Internationalization,Android Apps,Continuous integration,Top -@anchor{taler-developer-manual internationalization}@anchor{29} +@anchor{taler-developer-manual internationalization}@anchor{2c} @chapter Internationalization @@ -1170,14 +1258,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{2a} +@anchor{taler-developer-manual who-can-register}@anchor{2d} @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{2b} +@anchor{taler-developer-manual about-privilege-levels}@anchor{2e} @section About Privilege Levels @@ -1200,21 +1288,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{2c} +@anchor{taler-developer-manual upgrading-privileges}@anchor{2f} @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{2d} +@anchor{taler-developer-manual how-to-create-a-project}@anchor{30} @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{2e} +@anchor{taler-developer-manual how-to-create-a-component}@anchor{31} @section How to Create a Component @@ -1254,7 +1342,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{2f} +@anchor{taler-developer-manual how-to-create-a-translation}@anchor{32} @section How to Create a Translation @@ -1273,7 +1361,7 @@ Under @emph{https://weblate.taler.net/create/component/vcs/}: You may also wish to refer to @indicateurl{https://docs.weblate.org/} . @node Translation Standards and Practices,GPG Signing of Translations,How to Create a Translation,Internationalization -@anchor{taler-developer-manual translation-standards-and-practices}@anchor{30} +@anchor{taler-developer-manual translation-standards-and-practices}@anchor{33} @section Translation Standards and Practices @@ -1284,7 +1372,7 @@ When asked, set the license to GPLv3 or later. Set commit/push to manual only. @node GPG Signing of Translations,,Translation Standards and Practices,Internationalization -@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{31} +@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{34} @section GPG Signing of Translations @@ -1293,7 +1381,7 @@ weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F26 This means that contributions made through weblate will not be signed with the individual contributor’s key when they are checked into the Git repository, but with the weblate key. @node Android Apps,Code Coverage,Internationalization,Top -@anchor{taler-developer-manual android-apps}@anchor{32} +@anchor{taler-developer-manual android-apps}@anchor{35} @chapter Android Apps @@ -1306,7 +1394,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{33} +@anchor{taler-developer-manual android-app-nightly-builds}@anchor{36} @section Android App Nightly Builds @@ -1357,7 +1445,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{34}@anchor{taler-developer-manual building-apps-from-source}@anchor{35} +@anchor{taler-developer-manual build-apps-from-source}@anchor{37}@anchor{taler-developer-manual building-apps-from-source}@anchor{38} @section Building apps from source @@ -1443,7 +1531,7 @@ After the build finished successfully, you will find your APK in @code{merchant-terminal/build/outputs/apk/release/}. @node Update translations,Release process,Building apps from source,Android Apps -@anchor{taler-developer-manual update-translations}@anchor{36} +@anchor{taler-developer-manual update-translations}@anchor{39} @section Update translations @@ -1477,7 +1565,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{37} +@anchor{taler-developer-manual release-process}@anchor{3a} @section Release process @@ -1508,7 +1596,7 @@ $ git tag -s $APP-$VERSION @end menu @node F-Droid,Google Play,,Release process -@anchor{taler-developer-manual id1}@anchor{38} +@anchor{taler-developer-manual id1}@anchor{3b} @subsection F-Droid @@ -1532,7 +1620,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{39} +@anchor{taler-developer-manual google-play}@anchor{3c} @subsection Google Play @@ -1554,7 +1642,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{3a}@anchor{taler-developer-manual id3}@anchor{3b} +@anchor{taler-developer-manual id2}@anchor{3d}@anchor{taler-developer-manual id3}@anchor{3e} @chapter Code Coverage @@ -1564,7 +1652,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{3c} +@anchor{taler-developer-manual coding-conventions}@anchor{3f} @chapter Coding Conventions @@ -1579,7 +1667,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{3d} +@anchor{taler-developer-manual components-written-in-c}@anchor{40} @section Components written in C @@ -1599,7 +1687,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{3e} +@anchor{taler-developer-manual naming-conventions}@anchor{41} @subsection Naming conventions @@ -1760,7 +1848,7 @@ must be called “perf_module-under-test_case-description.c” @end itemize @node Shell Scripts,Kotlin,Components written in C,Coding Conventions -@anchor{taler-developer-manual shell-scripts}@anchor{3f} +@anchor{taler-developer-manual shell-scripts}@anchor{42} @section Shell Scripts @@ -1787,7 +1875,7 @@ $ set -eu @end example @node Kotlin,Python,Shell Scripts,Coding Conventions -@anchor{taler-developer-manual kotlin}@anchor{40} +@anchor{taler-developer-manual kotlin}@anchor{43} @section Kotlin @@ -1795,7 +1883,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{41} +@anchor{taler-developer-manual python}@anchor{44} @section Python @@ -1807,14 +1895,14 @@ for the language. @end menu @node Supported Python Versions,Style,,Python -@anchor{taler-developer-manual supported-python-versions}@anchor{42} +@anchor{taler-developer-manual supported-python-versions}@anchor{45} @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{43} +@anchor{taler-developer-manual style}@anchor{46} @subsection Style @@ -1824,7 +1912,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{44} +@anchor{taler-developer-manual python-for-scripting}@anchor{47} @subsection Python for Scripting @@ -1846,7 +1934,7 @@ over the older APIs. @end itemize @node Testing library,User-Facing Terminology,Coding Conventions,Top -@anchor{taler-developer-manual testing-library}@anchor{45} +@anchor{taler-developer-manual testing-library}@anchor{48} @chapter Testing library @@ -1854,7 +1942,7 @@ This chapter is a VERY ABSTRACT description of how testing is implemented in Taler, and in NO WAY wants to substitute the reading of the actual source code by the user. -In Taler, a test case is a array of @code{struct TALER_TESTING_Command}, +In Taler, a test case is an array of @code{struct TALER_TESTING_Command}, informally referred to as @code{CMD}, that is iteratively executed by the testing interpreter. This latter is transparently initiated by the testing library. @@ -1877,7 +1965,7 @@ CMDs: for example, CMD1 may create some key material and CMD2 needs this key material to encrypt data. The offering of internal values from CMD1 to CMD2 is made by @emph{traits}. A -trait is a @code{struct TALER_TESTING_Trait}, and each CMD contains a array +trait is a @code{struct TALER_TESTING_Trait}, and each CMD contains an array of traits, that it offers via the public trait interface to other commands. The definition and filling of such array happens transparently to the test developer. @@ -1919,7 +2007,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{46} +@anchor{taler-developer-manual user-facing-terminology}@anchor{49} @chapter User-Facing Terminology @@ -1933,7 +2021,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{47} +@anchor{taler-developer-manual terms-to-avoid}@anchor{4a} @section Terms to Avoid @@ -2002,7 +2090,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{48} +@anchor{taler-developer-manual terms-to-use}@anchor{4b} @section Terms to Use @@ -2054,7 +2142,7 @@ and payments. @end table @node Developer Glossary,Developer Tools,User-Facing Terminology,Top -@anchor{taler-developer-manual developer-glossary}@anchor{49} +@anchor{taler-developer-manual developer-glossary}@anchor{4c} @chapter Developer Glossary @@ -2063,137 +2151,137 @@ use when talking to end users or even system administrators. @table @asis -@anchor{taler-developer-manual term-absolute-time}@anchor{4a} +@anchor{taler-developer-manual term-absolute-time}@anchor{4d} @geindex absolute time @item absolute time -method of keeping time in @ref{4b,,GNUnet} where the time is represented +method of keeping time in @ref{4e,,GNUnet} where the time is represented as the number of microseconds since 1.1.1970 (UNIX epoch). Called -absolute time in contrast to @ref{4c,,relative time}. -@anchor{taler-developer-manual term-aggregate}@anchor{4d} +absolute time in contrast to @ref{4f,,relative time}. +@anchor{taler-developer-manual term-aggregate}@anchor{50} @geindex aggregate @item aggregate -the @ref{4e,,exchange} combines multiple payments received by the -same @ref{4f,,merchant} into one larger @ref{50,,wire transfer} to -the respective merchant’s @ref{51,,bank} account -@anchor{taler-developer-manual term-auditor}@anchor{52} +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} @geindex auditor @item auditor -trusted third party that verifies that the @ref{4e,,exchange} is operating correctly -@anchor{taler-developer-manual term-bank}@anchor{51} +trusted third party that verifies that the @ref{51,,exchange} is operating correctly +@anchor{taler-developer-manual term-bank}@anchor{54} @geindex bank @item bank -traditional financial service provider who offers wire @ref{53,,transfers} between accounts -@anchor{taler-developer-manual term-buyer}@anchor{54} +traditional financial service provider who offers wire @ref{56,,transfers} between accounts +@anchor{taler-developer-manual term-buyer}@anchor{57} @geindex buyer @item buyer -individual in control of a Taler @ref{55,,wallet}, usually using it to -@ref{56,,spend} the @ref{57,,coins} on @ref{58,,contracts} (see also @ref{59,,customer}). -@anchor{taler-developer-manual term-close}@anchor{5a} +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} @geindex close -@item close@anchor{taler-developer-manual term-closes}@anchor{5b} +@item close@anchor{taler-developer-manual term-closes}@anchor{5e} @geindex closes -@itemx closes@anchor{taler-developer-manual term-closed}@anchor{5c} +@itemx closes@anchor{taler-developer-manual term-closed}@anchor{5f} @geindex closed -@itemx closed@anchor{taler-developer-manual term-closing}@anchor{5d} +@itemx closed@anchor{taler-developer-manual term-closing}@anchor{60} @geindex closing @itemx closing -operation an @ref{4e,,exchange} performs on a @ref{5e,,reserve} that has not been -@ref{5f,,drained} by @ref{60,,withdraw} operations. When closing a reserve, the -exchange wires the remaining funds back to the customer, minus a @ref{61,,fee} +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} for closing -@anchor{taler-developer-manual term-coin}@anchor{62} +@anchor{taler-developer-manual term-coin}@anchor{65} @geindex coin -@item coin@anchor{taler-developer-manual term-coins}@anchor{57} +@item coin@anchor{taler-developer-manual term-coins}@anchor{5a} @geindex coins @itemx coins -coins are individual token representing a certain amount of value, also known as the @ref{63,,denomination} of the coin -@anchor{taler-developer-manual term-commitment}@anchor{64} +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} @geindex commitment -@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{65} +@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{68} @geindex refresh commitment @itemx refresh commitment -data that the wallet commits to during the @ref{66,,melt} stage of the -@ref{67,,refresh} protocol where it -has to prove to the @ref{4e,,exchange} that it is deriving the @ref{68,,fresh} +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} coins as specified by the Taler protocol. The commitment is verified -probabilistically (see: @ref{69,,kappa}) during the @ref{6a,,reveal} stage. -@anchor{taler-developer-manual term-contract}@anchor{6b} +probabilistically (see: @ref{6c,,kappa}) during the @ref{6d,,reveal} stage. +@anchor{taler-developer-manual term-contract}@anchor{6e} @geindex contract -@item contract@anchor{taler-developer-manual term-contracts}@anchor{58} +@item contract@anchor{taler-developer-manual term-contracts}@anchor{5b} @geindex contracts @itemx contracts -formal agreement between @ref{4f,,merchant} and @ref{59,,customer} specifying the -@ref{6c,,contract terms} and signed by the merchant and the @ref{57,,coins} of the +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 customer -@anchor{taler-developer-manual term-contract-terms}@anchor{6c} +@anchor{taler-developer-manual term-contract-terms}@anchor{6f} @geindex contract terms @item contract terms the individual clauses specifying what the buyer is purchasing from the -@ref{4f,,merchant} -@anchor{taler-developer-manual term-customer}@anchor{59} +@ref{52,,merchant} +@anchor{taler-developer-manual term-customer}@anchor{5c} @geindex customer @item customer individual that directs the buyer (perhaps the same individual) to make a purchase -@anchor{taler-developer-manual term-denomination}@anchor{63} +@anchor{taler-developer-manual term-denomination}@anchor{66} @geindex denomination @item denomination -unit of currency, specifies both the currency and the face value of a @ref{62,,coin}, +unit of currency, specifies both the currency and the face value of a @ref{65,,coin}, as well as associated fees and validity periods -@anchor{taler-developer-manual term-denomination-key}@anchor{6d} +@anchor{taler-developer-manual term-denomination-key}@anchor{70} @geindex denomination key @item denomination key -(RSA) key used by the exchange to certify that a given @ref{62,,coin} is valid and of a -particular @ref{63,,denomination} -@anchor{taler-developer-manual term-deposit}@anchor{6e} +(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} @geindex deposit -@item deposit@anchor{taler-developer-manual term-deposits}@anchor{6f} +@item deposit@anchor{taler-developer-manual term-deposits}@anchor{72} @geindex deposits -@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{70} +@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{73} @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{4d,,aggregate} @ref{50,,wire transfer} -@anchor{taler-developer-manual term-dirty}@anchor{71} +@ref{50,,aggregate} @ref{53,,wire transfer} +@anchor{taler-developer-manual term-dirty}@anchor{74} @geindex dirty -@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{72} +@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{75} @geindex dirty coin @itemx dirty coin @@ -2201,30 +2289,30 @@ exchange to credit his bank account in the future using an a coin is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin’s owner if the coin is not refreshed -@anchor{taler-developer-manual term-drain}@anchor{73} +@anchor{taler-developer-manual term-drain}@anchor{76} @geindex drain -@item drain@anchor{taler-developer-manual term-drained}@anchor{5f} +@item drain@anchor{taler-developer-manual term-drained}@anchor{62} @geindex drained @itemx drained -a @ref{5e,,reserve} is being drained when a @ref{55,,wallet} is using the -reserve’s private key to @ref{60,,withdraw} coins from it. This reduces +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 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{5c,,closed} by the exchange. -@anchor{taler-developer-manual term-exchange}@anchor{4e} +(which is the normal process) are @ref{5f,,closed} by the exchange. +@anchor{taler-developer-manual term-exchange}@anchor{51} @geindex exchange @item exchange Taler’s payment service operator. Issues electronic coins during withdrawal and redeems them when they are deposited by merchants -@anchor{taler-developer-manual term-expired}@anchor{74} +@anchor{taler-developer-manual term-expired}@anchor{77} @geindex expired -@item expired@anchor{taler-developer-manual term-expiration}@anchor{75} +@item expired@anchor{taler-developer-manual term-expiration}@anchor{78} @geindex expiration @itemx expiration @@ -2238,47 +2326,47 @@ expiration, which specifies how long the exchange keeps records beyond the deposit expiration time. This latter expiration matters for legal disputes in courts and also creates an upper limit for refreshing operations on special zombie coin -@anchor{taler-developer-manual term-fakebank}@anchor{76} +@anchor{taler-developer-manual term-fakebank}@anchor{79} @geindex fakebank @item fakebank -implementation of the @ref{51,,bank} API in memory to be used only for test +implementation of the @ref{54,,bank} API in memory to be used only for test cases. -@anchor{taler-developer-manual term-fee}@anchor{61} +@anchor{taler-developer-manual term-fee}@anchor{64} @geindex fee @item fee -an @ref{4e,,exchange} charges various fees for its service. The different +an @ref{51,,exchange} charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for -@ref{77,,withdrawing}, @ref{70,,depositing}, @ref{78,,melting}, and -@ref{79,,refunding}. Furthermore, there are fees per wire transfer -for @ref{5d,,closing} a @ref{5e,,reserve}: and for -@ref{4d,,aggregate} @ref{7a,,wire transfers} to the @ref{4f,,merchant}. -@anchor{taler-developer-manual term-fresh}@anchor{68} +@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} @geindex fresh -@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{7b} +@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{7e} @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{4b} +@anchor{taler-developer-manual term-GNUnet}@anchor{4e} @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{7c} +@anchor{taler-developer-manual term-json}@anchor{7f} @geindex json -@item json@anchor{taler-developer-manual term-JSON}@anchor{7d} +@item json@anchor{taler-developer-manual term-JSON}@anchor{80} @geindex JSON -@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{7e} +@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{81} @geindex JavaScript Object Notation @itemx JavaScript Object Notation @@ -2286,190 +2374,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{69} +@anchor{taler-developer-manual term-kappa}@anchor{6c} @geindex kappa @item kappa -security parameter used in the @ref{67,,refresh} protocol. Defined to be 3. +security parameter used in the @ref{6a,,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{7f} +@anchor{taler-developer-manual term-LibEuFin}@anchor{82} @geindex LibEuFin @item LibEuFin FIXME: explain -@anchor{taler-developer-manual term-link}@anchor{80} +@anchor{taler-developer-manual term-link}@anchor{83} @geindex link -@item link@anchor{taler-developer-manual term-linking}@anchor{81} +@item link@anchor{taler-developer-manual term-linking}@anchor{84} @geindex linking @itemx linking -specific step in the @ref{67,,refresh} protocol that an exchange must offer -to prevent abuse of the @ref{67,,refresh} mechanism. The link step is +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 not needed in normal operation, it just must be offered. -@anchor{taler-developer-manual term-master-key}@anchor{82} +@anchor{taler-developer-manual term-master-key}@anchor{85} @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{66} +@anchor{taler-developer-manual term-melt}@anchor{69} @geindex melt -@item melt@anchor{taler-developer-manual term-melted}@anchor{83} +@item melt@anchor{taler-developer-manual term-melted}@anchor{86} @geindex melted -@itemx melted@anchor{taler-developer-manual term-melting}@anchor{78} +@itemx melted@anchor{taler-developer-manual term-melting}@anchor{7b} @geindex melting @itemx melting -step of the @ref{67,,refresh} protocol where a @ref{72,,dirty coin} -is invalidated to be reborn @ref{68,,fresh} in a subsequent -@ref{6a,,reveal} step. -@anchor{taler-developer-manual term-merchant}@anchor{4f} +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} @geindex merchant @item merchant party receiving payments (usually in return for goods or services) -@anchor{taler-developer-manual term-message-signing-key}@anchor{84} +@anchor{taler-developer-manual term-message-signing-key}@anchor{87} @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{85} +@anchor{taler-developer-manual term-order}@anchor{88} @geindex order @item order FIXME: to be written! -@anchor{taler-developer-manual term-owner}@anchor{86} +@anchor{taler-developer-manual term-owner}@anchor{89} @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{87} +@anchor{taler-developer-manual term-planchet}@anchor{8a} @geindex planchet @item planchet -precursor data for a @ref{62,,coin}. A planchet includes the coin’s internal +precursor data for a @ref{65,,coin}. A planchet includes the coin’s internal secrets (coin private key, blinding factor), but lacks the RSA signature -of the @ref{4e,,exchange}. When @ref{77,,withdrawing}, a @ref{55,,wallet} +of the @ref{51,,exchange}. When @ref{7a,,withdrawing}, a @ref{58,,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{88} +@anchor{taler-developer-manual term-privacy-policy}@anchor{8b} @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{89} +@anchor{taler-developer-manual term-proof}@anchor{8c} @geindex proof @item proof Message that cryptographically demonstrates that a particular claim is correct. -@anchor{taler-developer-manual term-proposal}@anchor{8a} +@anchor{taler-developer-manual term-proposal}@anchor{8d} @geindex proposal @item proposal -a list of @ref{6c,,contract terms} that has been completed and signed by the +a list of @ref{6f,,contract terms} that has been completed and signed by the merchant backend. -@anchor{taler-developer-manual term-purchase}@anchor{8b} +@anchor{taler-developer-manual term-purchase}@anchor{8e} @geindex purchase @item purchase -Refers to the overall process of negotiating a @ref{6b,,contract} and then -making a payment with @ref{57,,coins} to a @ref{4f,,merchant}. -@anchor{taler-developer-manual term-recoup}@anchor{8c} +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} @geindex recoup @item recoup Operation by which an exchange returns the value of coins affected -by a @ref{8d,,revocation} to their @ref{86,,owner}, either by allowing the owner to -withdraw new coins or wiring funds back to the bank account of the @ref{86,,owner}. -@anchor{taler-developer-manual term-refresh}@anchor{67} +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} @geindex refresh -@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{8e} +@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{91} @geindex refreshing @itemx refreshing -operation by which a @ref{72,,dirty coin} is converted into one or more -@ref{68,,fresh} coins. Involves @ref{78,,melting} the @ref{72,,dirty coin} and -then @ref{8f,,revealing} so-called @ref{90,,transfer keys}. -@anchor{taler-developer-manual term-refund}@anchor{91} +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} @geindex refund -@item refund@anchor{taler-developer-manual term-refunding}@anchor{79} +@item refund@anchor{taler-developer-manual term-refunding}@anchor{7c} @geindex refunding @itemx refunding operation by which a merchant steps back from the right to funds that he -obtained from a @ref{6e,,deposit} operation, giving the right to the funds back +obtained from a @ref{71,,deposit} operation, giving the right to the funds back to the customer -@anchor{taler-developer-manual term-refund-transaction-id}@anchor{92} +@anchor{taler-developer-manual term-refund-transaction-id}@anchor{95} @geindex refund transaction id @item refund transaction id -unique number by which a merchant identifies a @ref{91,,refund}. Needed +unique number by which a merchant identifies a @ref{94,,refund}. Needed as refunds can be partial and thus there could be multiple refunds for -the same @ref{8b,,purchase}. -@anchor{taler-developer-manual term-relative-time}@anchor{4c} +the same @ref{8e,,purchase}. +@anchor{taler-developer-manual term-relative-time}@anchor{4f} @geindex relative time @item relative time -method of keeping time in @ref{4b,,GNUnet} where the time is represented +method of keeping time in @ref{4e,,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{4a,,absolute time}. -@anchor{taler-developer-manual term-reserve}@anchor{5e} +contrast to @ref{4d,,absolute time}. +@anchor{taler-developer-manual term-reserve}@anchor{61} @geindex reserve @item reserve accounting mechanism used by the exchange to track customer funds -from incoming @ref{7a,,wire transfers}. A reserve is created whenever +from incoming @ref{7d,,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{55,,wallet} -to @ref{60,,withdraw} up to the amount received in @ref{68,,fresh} -@ref{57,,coins} from the reserve, thereby draining the reserve. If a -reserve is not drained, the exchange eventually @ref{5b,,closes} it. +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. 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{6a} +@anchor{taler-developer-manual term-reveal}@anchor{6d} @geindex reveal -@item reveal@anchor{taler-developer-manual term-revealing}@anchor{8f} +@item reveal@anchor{taler-developer-manual term-revealing}@anchor{92} @geindex revealing @itemx revealing -step in the @ref{67,,refresh} protocol where some of the transfer private +step in the @ref{6a,,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{68,,fresh} coins. -@anchor{taler-developer-manual term-revoke}@anchor{93} +In the reveal step, the exchange returns the signed @ref{6b,,fresh} coins. +@anchor{taler-developer-manual term-revoke}@anchor{96} @geindex revoke -@item revoke@anchor{taler-developer-manual term-revocation}@anchor{8d} +@item revoke@anchor{taler-developer-manual term-revocation}@anchor{90} @geindex revocation @itemx revocation @@ -2478,109 +2566,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{94} +@anchor{taler-developer-manual term-sharing}@anchor{97} @geindex sharing @item sharing -users can share ownership of a @ref{62,,coin} by sharing access to the coin's +users can share ownership of a @ref{65,,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{56} +@anchor{taler-developer-manual term-spend}@anchor{59} @geindex spend -@item spend@anchor{taler-developer-manual term-spending}@anchor{95} +@item spend@anchor{taler-developer-manual term-spending}@anchor{98} @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{96} +@anchor{taler-developer-manual term-terms}@anchor{99} @geindex terms @item terms the general terms of service of an operator, possibly including -the @ref{88,,privacy policy}. Not to be confused with the -@ref{6c,,contract terms} which are about the specific purchase. -@anchor{taler-developer-manual term-transaction}@anchor{97} +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} @geindex transaction @item transaction method by which ownership is exclusively transferred from one entity -@anchor{taler-developer-manual term-transfer}@anchor{53} +@anchor{taler-developer-manual term-transfer}@anchor{56} @geindex transfer -@item transfer@anchor{taler-developer-manual term-transfers}@anchor{98} +@item transfer@anchor{taler-developer-manual term-transfers}@anchor{9b} @geindex transfers -@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{50} +@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{53} @geindex wire transfer -@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7a} +@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7d} @geindex wire transfers @itemx wire transfers -method of sending funds between @ref{51,,bank} accounts -@anchor{taler-developer-manual term-transfer-key}@anchor{99} +method of sending funds between @ref{54,,bank} accounts +@anchor{taler-developer-manual term-transfer-key}@anchor{9c} @geindex transfer key -@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{90} +@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{93} @geindex transfer keys @itemx transfer keys -special cryptographic key used in the @ref{67,,refresh} protocol, some of which -are revealed during the @ref{6a,,reveal} step. Note that transfer keys have, -despite the name, no relationship to @ref{7a,,wire transfers}. They merely -help to transfer the value from a @ref{72,,dirty coin} to a @ref{7b,,fresh coin} -@anchor{taler-developer-manual term-user}@anchor{9a} +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} @geindex user @item user any individual using the Taler payment system -(see @ref{59,,customer}, @ref{54,,buyer}, @ref{4f,,merchant}). -@anchor{taler-developer-manual term-version}@anchor{9b} +(see @ref{5c,,customer}, @ref{57,,buyer}, @ref{52,,merchant}). +@anchor{taler-developer-manual term-version}@anchor{9e} @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{4e,,exchange}, -@ref{52,,auditor} or @ref{4f,,merchant}. There is a protocol +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 version (CURRENT:REVISION:AGE, see GNU libtool) which specifies -the network protocol spoken by an @ref{4e,,exchange} or @ref{4f,,merchant} +the network protocol spoken by an @ref{51,,exchange} or @ref{52,,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{55} +@anchor{taler-developer-manual term-wallet}@anchor{58} @geindex wallet @item wallet software running on a customer’s computer; withdraws, stores and spends coins -@anchor{taler-developer-manual term-WebExtension}@anchor{9c} +@anchor{taler-developer-manual term-WebExtension}@anchor{9f} @geindex WebExtension @item WebExtension Cross-browser API used to implement the GNU Taler wallet browser extension. -@anchor{taler-developer-manual term-wire-gateway}@anchor{9d} +@anchor{taler-developer-manual term-wire-gateway}@anchor{a0} @geindex wire gateway @item wire gateway FIXME: explain -@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{9e} +@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a1} @geindex wire transfer identifier -@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{9f} +@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{a2} @geindex wtid @itemx wtid @@ -2588,35 +2676,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{60} +@anchor{taler-developer-manual term-withdraw}@anchor{63} @geindex withdraw -@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{77} +@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{7a} @geindex withdrawing -@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a0} +@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a3} @geindex withdrawal @itemx withdrawal -operation by which a @ref{55,,wallet} can convert funds from a @ref{5e,,reserve} to +operation by which a @ref{58,,wallet} can convert funds from a @ref{61,,reserve} to fresh coins -@anchor{taler-developer-manual term-zombie}@anchor{a1} +@anchor{taler-developer-manual term-zombie}@anchor{a4} @geindex zombie -@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a2} +@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a5} @geindex zombie coin @itemx zombie coin -coin where the respective @ref{6d,,denomination key} is past its -@ref{6e,,deposit} @ref{75,,expiration} time, but which is still (again) valid -for an operation because it was @ref{83,,melted} while it was still -valid, and then later again credited during a @ref{8c,,recoup} process +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 @end table @node Developer Tools,Index,Developer Glossary,Top -@anchor{taler-developer-manual developer-tools}@anchor{a3} +@anchor{taler-developer-manual developer-tools}@anchor{a6} @chapter Developer Tools @@ -2629,7 +2717,7 @@ developer. @end menu @node taler-config-generate,,,Developer Tools -@anchor{taler-developer-manual taler-config-generate}@anchor{a4} +@anchor{taler-developer-manual taler-config-generate}@anchor{a7} @section taler-config-generate @@ -2708,7 +2796,7 @@ Print version information. @item @strong{-w} @emph{WIREFORMAT} | @strong{–wire} @emph{WIREFORMAT} -Specifies which wire format to use (i.e. “test” or “sepa”) +Specifies which wire format to use (i.e. “x-talerbank” or “iban”) @item @strong{–bank-uri} |