diff options
Diffstat (limited to 'texinfo/taler-developer-manual.texi')
| -rw-r--r-- | texinfo/taler-developer-manual.texi | 1636 |
1 files changed, 1038 insertions, 598 deletions
diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 247338d7..0df117ea 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.texi @@ -3,7 +3,7 @@ @setfilename taler-developer-manual.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 3.4.3.@* +@*Generated by Sphinx 5.3.0.@* @end ifinfo @settitle Taler Developer Manual @defindex ge @@ -15,13 +15,11 @@ * MENU ENTRY: (taler-developer-manual.info). DESCRIPTION @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.9.0, Nov 03, 2022 +GNU Taler 0.9.0, Sep 24, 2023 GNU Taler team @@ -68,6 +66,8 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+) @menu * GNU Taler Release Checklists:: * GNU Taler Demo Upgrade Checklist:: +* Guidelines for Python Packages:: +* Project Overview:: * Fundamentals:: * Debian and Ubuntu Repositories:: * Language-Specific Guidelines:: @@ -77,6 +77,7 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+) * Releases:: * Continuous integration:: * Internationalization:: +* iOS Apps:: * Android Apps:: * Code Coverage:: * Coding Conventions:: @@ -99,10 +100,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 @@ -111,19 +112,22 @@ 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. @item + update man pages / info page documentation (prebuilt branch) + +@item make dist for release @item verify dist builds from source @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run @ref{4,,demo upgrade checklist} @@ -132,13 +136,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 @@ -150,10 +154,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 @@ -162,7 +166,10 @@ 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) @item Change version number in configure.ac. @@ -174,7 +181,58 @@ For merchant (C backend): verify dist builds from source @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ + +@item + run @ref{4,,demo upgrade checklist} + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For sync: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + no compiler warnings at “-Wall” with clang + +@item + ensure Coverity static analysis passes + +@item + make check. + +@item + make dist, make check on result of ‘make dist’. + +@item + Change version number in configure.ac. + +@item + make dist for release + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ @item run @ref{4,,demo upgrade checklist} @@ -183,13 +241,85 @@ 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 +@end itemize + +For taler-mdb: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + ensure Coverity static analysis passes + +@item + Change version number in configure.ac. + +@item + make dist for release. + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For taler-twister: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + no compiler warnings at “-Wall” with clang + +@item + ensure Coverity static analysis passes + +@item + make check. + +@item + make dist, make check on result of ‘make dist’. + +@item + Change version number in configure.ac. + +@item + make dist for release. + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ + +@item + run @ref{4,,demo upgrade checklist} + +@item + tag repo. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -207,7 +337,7 @@ For libeufin: build libeufin @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run @ref{4,,demo upgrade checklist} @@ -222,13 +352,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 @@ -240,13 +370,13 @@ For Python merchant frontend: @itemize - @item - upgrade 'demo.taler.net' + upgrade ‘demo.taler.net’ @item run @ref{4,,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: @@ -270,7 +400,13 @@ Wallet-core: tag repo. @item - change 'demo.taler.net' deployment to use new tag. + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. @item Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha @@ -330,7 +466,7 @@ Release announcement: Send announcement to @email{coordinator@@translationproject.org} @end itemize -@node GNU Taler Demo Upgrade Checklist,Fundamentals,GNU Taler Release Checklists,Top +@node GNU Taler Demo Upgrade Checklist,Guidelines for Python Packages,GNU Taler Release Checklists,Top @anchor{checklist-demo-upgrade doc}@anchor{4}@anchor{checklist-demo-upgrade gnu-taler-demo-upgrade-checklist}@anchor{5} @chapter GNU Taler Demo Upgrade Checklist @@ -341,9 +477,6 @@ Post-upgrade checks: @itemize - @item - Run @code{taler-deployment-arm -I} to verify that all services are running. - -@item Run the headless wallet to check that services are actually working: @example @@ -418,7 +551,7 @@ Blog demo: @item Go back to @indicateurl{https://shop.demo.taler.net/} and click on the same article -link. Verify that the article is shown and @strong{no} repeated payment is +link. Verify that the article is shown and `no' repeated payment is requested. @item @@ -469,13 +602,67 @@ that the payment is requested again, instead of showing the previous fulfillment page. @end itemize -Survey/Tipping: +Merchant SPA: @itemize - @item - Visit @indicateurl{https://survey.demo.taler.net/} and receive a tip. + test SPA loads + +@item + try to login with wrong password + +@item + try to login with correct password + +@item + create instance + +@item + modify instance + +@item + add product + +@item + add order with inventory product + +@item + pay for order with wallet + +@item + trigger refund + +@item + accept refund with wallet + +@item + TBD: rewards + +@item + TBD: products with previews + +@item + TBD: inventory management + +@item + TBD: adding transactions + +@item + TBD: test various settings + +@item + TBD: … +@end itemize + +Survey/Rewards: + + +@itemize - + +@item + Visit @indicateurl{https://survey.demo.taler.net/} and receive a reward. @item Verify that the survey stats page (@indicateurl{https://survey.demo.taler.net/survey-stats}) is working, @@ -509,6 +696,124 @@ P2P payments: delete history entry @end itemize +@node Guidelines for Python Packages,Project Overview,GNU Taler Demo Upgrade Checklist,Top +@anchor{python-guidelines doc}@anchor{6}@anchor{python-guidelines guidelines-for-python-packages}@anchor{7} +@chapter Guidelines for Python Packages + + +This document describes conventions used for Python repos in the Taler project. + +@menu +* Packaging:: +* GNU Compatibility Layer:: +* Formatting:: +* Distro Packaging:: + +@end menu + +@node Packaging,GNU Compatibility Layer,,Guidelines for Python Packages +@anchor{python-guidelines packaging}@anchor{8} +@section Packaging + + + +@itemize * + +@item +We use poetry@footnote{https://github.com/python-poetry/poetry} for managing dependencies and dev-dependencies. + +@item +The @code{poetry.lock} file must be committed to repo. + +@item +Entry points `must not' be defined as shell scripts. Instead, use poetry’s script facility to define entry points. This makes the package work on different platforms properly. +@end itemize + +@node GNU Compatibility Layer,Formatting,Packaging,Guidelines for Python Packages +@anchor{python-guidelines gnu-compatibility-layer}@anchor{9} +@section GNU Compatibility Layer + + +In addition to the Python-native tooling, we provide a GNU-style interface for the build system. +The commands supported by every Python repo should be: + + +@itemize * + +@item +@code{./bootstrap}: Only necessary when the repo is checked out via git. +Initializes the build system and checks out git submodules if applicable. + +@item +@code{./configure}: Should check for build-time dependencies, `including' Python tooling. + +@item +@code{make}: Invoking make without a target should create the Python wheel for the project. + +@item +@code{make install}: Installation should `only' install the Python package +based on the wheel via @code{pip}. Note that we can’t do dependency tracking +properly, so the @code{install} target will always re-build the wheel and +install it. + +@item +@code{make pretty}: Should invoke the pretty-printer (@code{black} for Python projects). + +@item +@code{make dist}: This should create the source tarball. + +@item +@code{make clean}: Should delete generated files. +@end itemize + +The build-common.git@footnote{https://git.taler.net/build-common.git/} repository contains helpers +to make the GNU compatibility easier. Here are some hints for using it: + + +@itemize * + +@item +The @code{build-common.git} repo should added as a submodule in the path @code{build-system/taler-build-scripts} +of the repository. + +@item +The bootstrap template@footnote{https://git.taler.net/build-common.git/tree/bootstrap.template} should +be copied as @code{./bootstrap} to the root of the repository. + +@item +The configure script is automatically created by @code{./bootstrap}. + +@item +Dependencies for the configure file are defined in @code{build-system/configure.py}. +There is no documentation yet, but adjusting the example file@footnote{https://git.taler.net/build-common.git/tree/testconfigure.py} is a good starting point. + +@item +The source distribution (@code{make dist}) should either be created via @code{poetry build -f sdist} +or using the git-archive-all@footnote{https://git.taler.net/build-common.git/tree/archive-with-submodules/git_archive_all.py}. +@end itemize + +@node Formatting,Distro Packaging,GNU Compatibility Layer,Guidelines for Python Packages +@anchor{python-guidelines formatting}@anchor{a} +@section Formatting + + + +@itemize * + +@item +We follow pep8@footnote{https://www.python.org/dev/peps/pep-0008/}. + +@item +Code should be auto-formatted with black@footnote{https://github.com/psf/black}. +@end itemize + +@node Distro Packaging,,Formatting,Guidelines for Python Packages +@anchor{python-guidelines distro-packaging}@anchor{b} +@section Distro Packaging + + +For Debian, we should try to use wheel2deb@footnote{https://github.com/upciti/wheel2deb}. + @cartouche @quotation Note This manual contains information for developers working on GNU Taler @@ -516,8 +821,124 @@ and related components. It is not intended for a general audience. @end quotation @end cartouche -@node Fundamentals,Debian and Ubuntu Repositories,GNU Taler Demo Upgrade Checklist,Top -@anchor{taler-developer-manual fundamentals}@anchor{6} +@node Project Overview,Fundamentals,Guidelines for Python Packages,Top +@anchor{taler-developer-manual project-overview}@anchor{c} +@chapter Project Overview + + +GNU Taler consists of a large (and growing) number of components +in various Git repositories. The following list gives a first +overview: + +@quotation + + +@itemize * + +@item +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. + +@item +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 +blockchains, specifically Bitcoin and Ethereum. Allows an exchange +to interact with crypto-currencies. + +@item +merchant: payment processing backend to be run by merchants, +offering a REST API. + +@item +wallet-core: platform-independent implementation of a wallet to be run by +normal users. Includes also the WebExtension for various browsers. +Furthermore, includes various single-page apps used by other +components (especially as libeufin and merchant). Also includes +command-line wallet and tools for testing. + +@item +taler-android: Android Apps including the Android wallet, the +Android point-of-sale App and the Android casher app. + +@item +taler-ios: iOS wallet App. + +@item +sync: backup service, provides a simple REST API to allow users to +make encrypted backups of their wallet state. + +@item +anastasis: key escrow service, provides a simple REST API to allow +users to distribute encryption keys across multiple providers and +define authorization policies for key recovery. + +@item +taler-mdb: integration of Taler with the multi-drop-bus (MDB) API +used by vending machines. Allows Taler payments to be integrated +with vending machines. + +@item +gnu-taler-payment-for-woocommerce: payment plugin for the +woocommerce (wordpress) E-commerce solution. + +@item +twister: man-in-the-middle proxy for tests that require fuzzing a +REST/JSON protocol. Used for some of our testing. + +@item +challenger: implementation of an OAuth 2.0 provider that can be used +to verify that a user can receive SMS or E-mail at particular addresses. +Used as part of KYC processes of the exchange. + +@item +taler-mailbox: messaging service used to store and forward payment +messages to Taler wallets. + +@item +taldir: directory service used to lookup Taler wallet addresses for +sending invoices or payments to other wallets. + +@item +taler-merchant-demos: various demonstration services operated at +‘demo.taler.net’, including a simple shop, donation page and a +survey with reward functionality. +@end itemize +@end quotation + +There are other important repositories without code, including: + +@quotation + + +@itemize * + +@item +gana: Hosted on git.gnunet.org, this repository defines various +constants used in the GNU Taler project. + +@item +docs: documentation, including this very document. + +@item +marketing: various presentations, papers and other resources for +outreach. + +@item +large-media: very large data objects, such as videos. + +@item +www: the taler.net website. +@end itemize +@end quotation + +@node Fundamentals,Debian and Ubuntu Repositories,Project Overview,Top +@anchor{taler-developer-manual fundamentals}@anchor{d} @chapter Fundamentals @@ -534,7 +955,7 @@ and related components. It is not intended for a general audience. @end menu @node Testing Tools,Manual Testing Database Reset,,Fundamentals -@anchor{taler-developer-manual testing-tools}@anchor{7} +@anchor{taler-developer-manual testing-tools}@anchor{e} @section Testing Tools @@ -557,7 +978,7 @@ The @code{make check} should be able to function without them, but their presence permits some tests to run that would otherwise be skipped. @node Manual Testing Database Reset,Bug Tracking,Testing Tools,Fundamentals -@anchor{taler-developer-manual manual-testing-database-reset}@anchor{8} +@anchor{taler-developer-manual manual-testing-database-reset}@anchor{f} @section Manual Testing Database Reset @@ -578,7 +999,7 @@ doing these steps automatically in the @code{make check} flow. (If @code{make check} still fails after the reset, file a bug report as usual.) @node Bug Tracking,Code Repositories,Manual Testing Database Reset,Fundamentals -@anchor{taler-developer-manual bug-tracking}@anchor{9} +@anchor{taler-developer-manual bug-tracking}@anchor{10} @section Bug Tracking @@ -588,7 +1009,7 @@ needed in order to use the bug tracker, only read access is granted without a login. @node Code Repositories,Committing code,Bug Tracking,Fundamentals -@anchor{taler-developer-manual code-repositories}@anchor{a} +@anchor{taler-developer-manual code-repositories}@anchor{11} @section Code Repositories @@ -603,13 +1024,13 @@ A complete list of all the existing repositories is currently found at @indicateurl{https://git.taler.net/}. @node Committing code,Observing changes,Code Repositories,Fundamentals -@anchor{taler-developer-manual committing-code}@anchor{b} +@anchor{taler-developer-manual committing-code}@anchor{12} @section Committing code Before you can obtain Git write access, you must sign the copyright agreement. As we collaborate closely with GNUnet, we use their -copyright agreement -- with the understanding that your contributions +copyright agreement – with the understanding that your contributions to GNU Taler are included in the assignment. You can find the agreement on the GNUnet site@footnote{https://gnunet.org/en/copyright.html}. Please sign and mail it to Christian Grothoff as he currently collects @@ -672,7 +1093,7 @@ $ git pull --rebase -S @end example @node Observing changes,Communication,Committing code,Fundamentals -@anchor{taler-developer-manual observing-changes}@anchor{c} +@anchor{taler-developer-manual observing-changes}@anchor{13} @section Observing changes @@ -685,18 +1106,18 @@ it can be high volume, the lists is a good way to follow overall development. @node Communication,What to put in bootstrap,Observing changes,Fundamentals -@anchor{taler-developer-manual communication}@anchor{d} +@anchor{taler-developer-manual communication}@anchor{14} @section Communication -We use the #taler channel on the Freenode IRC network and the @email{taler@@gnu.org} -public mailinglist for discussions. Not all developers are active on IRC, but -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). +For public discussions we use the @email{taler@@gnu.org} mailinglist. All developers +should subscribe to the low-volume Taler mailinglist. There are separate +low-volume mailinglists for gnunet-developers (@@gnu.org) and for libmicrohttpd +(@@gnu.org). For internal discussions we use @indicateurl{https://mattermost.taler.net/} +(invitation only, but also achieved). @node What to put in bootstrap,,Communication,Fundamentals -@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{e} +@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{15} @section What to put in bootstrap @@ -712,10 +1133,9 @@ 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}. +the bootstrap script eventually runs the @code{git submodule update --init} command +early on, and later runs script @code{./contrib/gana-generate.sh}, which +generates files such as @code{src/include/taler_signatures.h}. Thus, to update that file, you need to: @@ -734,8 +1154,7 @@ Add it to GANA, in @code{gnunet-signatures/registry.rec}. 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. +(in Taler Repo) Run the @code{contrib/gana-latest.sh} script. @item Bootstrap, configure, do @code{make install}, @code{make check}, etc. @@ -749,7 +1168,7 @@ A similar procedure is required for other databases in GANA. See file @code{README} in the various directories for specific instructions. @node Debian and Ubuntu Repositories,Language-Specific Guidelines,Fundamentals,Top -@anchor{taler-developer-manual debian-and-ubuntu-repositories}@anchor{f} +@anchor{taler-developer-manual debian-and-ubuntu-repositories}@anchor{16} @chapter Debian and Ubuntu Repositories @@ -761,7 +1180,7 @@ We package our software for Debian and Ubuntu. @end menu @node Nightly Repositories,,,Debian and Ubuntu Repositories -@anchor{taler-developer-manual nightly-repositories}@anchor{10} +@anchor{taler-developer-manual nightly-repositories}@anchor{17} @section Nightly Repositories @@ -780,7 +1199,7 @@ $ wget -O - https://taler.net/taler-systems-nightly.gpg.key | apt-key add - @end example @node Language-Specific Guidelines,Taler Deployment on gv taler net,Debian and Ubuntu Repositories,Top -@anchor{taler-developer-manual language-specific-guidelines}@anchor{11} +@anchor{taler-developer-manual language-specific-guidelines}@anchor{18} @chapter Language-Specific Guidelines @@ -788,23 +1207,19 @@ $ wget -O - https://taler.net/taler-systems-nightly.gpg.key | apt-key add - @itemize * @item -Python Guidelines +@ref{6,,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{12} +@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{19} @chapter Taler Deployment on gv.taler.net -This section describes the GNU Taler deployment on @code{gv.taler.net}. -@code{gv} is our server at BFH. It hosts the Git repositories, Web sites, -CI and other services. Developers can receive an SSH account and -e-mail alias for the system. As with Git, ask your primary team -contact for shell access if you think you need it. - -Our old server, @code{tripwire}, is currently offline and will likely -go back online to host @code{production} systems for operating real -Taler payments at BFH in the future. +This section describes the GNU Taler deployment on @code{gv.taler.net}. @code{gv} +is our server at BFH. It hosts the Git repositories, Web sites, CI and other +services. Developers can receive an SSH account and e-mail alias for the +system, you should contact Javier, Christian or Florian. As with Git, ask +your primary team contact for shell access if you think you need it. @menu * DNS:: @@ -813,16 +1228,16 @@ 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{13} +@anchor{taler-developer-manual dns}@anchor{1a} @section DNS -DNS records for taler.net are controlled by the GNU Taler -maintainers, specifically Christian and Florian. If you -need a sub-domain to be added, please contact one of them. +DNS records for taler.net are controlled by the GNU Taler maintainers, +specifically Christian and Florian, and our system administrator, Javier. 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{14} +@anchor{taler-developer-manual user-acccounts}@anchor{1b} @section User Acccounts @@ -837,186 +1252,128 @@ serve Taler on the Internet: built by Buildbot. @item -@code{taler-internal}: serves @code{*.int.taler.net}, and does @emph{NOT} get +@code{taler-internal}: serves @code{*.int.taler.net}, and does `NOT' get automatically built. -@end itemize - -The following two users are @emph{never} automatically built, and they both -serve @code{*.demo.taler.net}. At any given time, only one is active and -serves the HTTP requests from the outside; the other one can so be -compiled without any downtime. If the compilation succeeds, the inactive -user can be switched to become active (see next section), and vice versa. - - -@itemize - @item -@code{demo-blue} - -@item -@code{demo-green} +@code{demo}: serves @code{*.demo.taler.net}. Never automatically built. @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{15} +@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{1c} @chapter Demo Upgrade Procedure -Upgrading the @code{demo} environment should be done with care, and ideally be -coordinated on the mailing list before. It is our goal for @code{demo} to always -run a "working version" that is compatible with various published wallets. -Before deploying on @code{demo}, the same version of all components @strong{must} -be deployed @emph{and} tested on @code{int}. +@enumerate -Please use the @ref{4,,demo upgrade checklist} to make -sure everything is working. - -@menu -* Tagging components:: -* Environment Layout:: -* Using envcfg.py: Using envcfg py. -* Bootstrapping an Environment:: -* Upgrading an Existing Environment:: -* Switching Demo Colors:: - -@end menu - -@node Tagging components,Environment Layout,,Demo Upgrade Procedure -@anchor{taler-developer-manual tagging-components}@anchor{16} -@section Tagging components +@item +Login as the @code{demo} user on @code{gv.taler.net}. +@item +Pull the latest @code{deployment.git} code. -All Taler components must be tagged with git before they are deployed on the -@code{demo} environment, using a tag of the following form: +@item +Navigate to the @code{deployment.git/docker/demo} directory. -@example -demo-YYYY-MM-DD-SS -YYYY = year -MM = month -DD = day -SS = serial -@end example +@item +Refer to the README, or the smaller cheat sheet below. +@end enumerate -@node Environment Layout,Using envcfg py,Tagging components,Demo Upgrade Procedure -@anchor{taler-developer-manual environment-layout}@anchor{17} -@section Environment Layout +The deployment is based on rootless Docker, managed by the +SystemD unit in userspace: @code{docker.service}. The running daemon +is reached by every Docker command at the address held into the +@code{DOCKER_HOST} environment variable. Normally, it points to +@code{unix:///run/user/$(id -u)/docker.sock}. Such variable is automatically +exported by @code{~/.bashrc}. +@cartouche +@quotation Note +@quotation -Environments have the following layout: +Should the rootless Docker be installed, run the following command +or consult the official documentation@footnote{https://docs.docker.com/engine/security/rootless/}. +@end quotation @example -$HOME/ - deployment (deployment.git checkout) - envcfg.py (configuration of the Taler environment) - activate (bash file, sourced to set environment variables) - logs/ (log files) - local/ (locally installed software) - sources/ (sources repos of locally build components) - sockets/ (unix domain sockets of running components) - taler-data (on-disk state, public and private keys) - .config/taler.conf (main Taler configuration file) +$ curl -fsSL https://get.docker.com/rootless | sh @end example +@end quotation +@end cartouche -On @code{demo-blue} and @code{demo-green}, @code{taler-data} is a symlink pointing to @code{$HOME/demo/shared-data} -instead of a directory. - -@node Using envcfg py,Bootstrapping an Environment,Environment Layout,Demo Upgrade Procedure -@anchor{taler-developer-manual using-envcfg-py}@anchor{18} -@section Using envcfg.py - - -The @code{$HOME/envcfg.py} file contains (1) the name of the environment and (2) the version -of all components we build (in the form of a git rev). - -The @code{envcfg.py} for demo looks like this: +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. +Please use the @ref{4,,demo upgrade checklist} to make +sure everything is working. +Nginx is already configured to reach the services as exported by +Docker Compose. -@example -env = "demo" -tag = "demo-2019-10-05-01: -tag_gnunet = tag -tag_libmicrohttpd = tag -tag_exchange = tag -tag_merchant = tag -tag_bank = tag -tag_twister = tag -tag_landing = tag -tag_donations = tag -tag_blog = tag -tag_survey = tag -tag_backoffice = tag -tag_sync = tag -@end example +@menu +* Cheat sheet:: +* Tagging components:: -Currently only the variables @code{env} and @code{tag_$@{component@}} are used. +@end menu -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 Cheat sheet,Tagging components,,Demo Upgrade Procedure +@anchor{taler-developer-manual cheat-sheet}@anchor{1d} +@section Cheat sheet -@node Bootstrapping an Environment,Upgrading an Existing Environment,Using envcfg py,Demo Upgrade Procedure -@anchor{taler-developer-manual bootstrapping-an-environment}@anchor{19} -@section Bootstrapping an Environment +All commands run from deployment.git/docker/demo. @example -$ git clone https://git.taler.net/deployment.git ~/deployment -$ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py -$ ./deployment/bin/taler-deployment bootstrap -$ source ~/activate -$ taler-deployment build -$ taler-deployment-prepare -$ taler-deployment-start -$ taler-deployment-arm -I # check everything works -# The following command sets up the 'blog' and 'donations' instances. -$ taler-config-instances -@end example +# Start services. +$ docker-compose start --remove-orphans -d -@node Upgrading an Existing Environment,Switching Demo Colors,Bootstrapping an Environment,Demo Upgrade Procedure -@anchor{taler-developer-manual upgrading-an-existing-environment}@anchor{1a} -@section Upgrading an Existing Environment +# Stop services. +$ docker-compose stop +# Build base image (without tags-file builds master) +$ ./build_base.sh images/base/Dockerfile [tags-file] -@example -$ rm -rf ~/sources ~/local -$ git -C ~/deployment pull -$ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py -$ taler-deployment bootstrap -$ taler-deployment build -$ taler-deployment-prepare -$ taler-deployment-restart -$ taler-deployment-arm -I # check everything works +# Build all the services based on the latest base image +$ docker-compose build + +# View live logs of the daemonized services. +$ docker-compose logs @end example -@node Switching Demo Colors,,Upgrading an Existing Environment,Demo Upgrade Procedure -@anchor{taler-developer-manual switching-demo-colors}@anchor{1b} -@section Switching Demo Colors +@node Tagging components,,Cheat sheet,Demo Upgrade Procedure +@anchor{taler-developer-manual tagging-components}@anchor{1e} +@section Tagging components -As the @code{demo} user, to switch to color @code{$@{COLOR@}}, -run the following script from @code{deployment/bin}: +All Taler components must be tagged with git before they are deployed on the +@code{demo} environment, using a tag of the following form: @example -$ taler-deployment switch-demo +demo-YYYY-MM-DD-SS +YYYY = year +MM = month +DD = day +SS = serial @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{1c} +@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{1f} @chapter Environments and Builders on taler.net @menu * Buildbot implementation:: +* Test builder:: +* Wallet builder:: * Documentation Builder:: * Website Builder:: * Code coverage:: -* Service Checker:: -* Tipping reserve top-up:: * Producing auditor reports:: * Database schema versioning:: @end menu -@node Buildbot implementation,Documentation Builder,,Environments and Builders on taler net -@anchor{taler-developer-manual buildbot-implementation}@anchor{1d} +@node Buildbot implementation,Test builder,,Environments and Builders on taler net +@anchor{taler-developer-manual buildbot-implementation}@anchor{20} @section Buildbot implementation @@ -1034,7 +1391,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. @@ -1052,7 +1409,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>} @@ -1060,8 +1417,52 @@ 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{1e} +@node Test builder,Wallet builder,Buildbot implementation,Environments and Builders on taler net +@anchor{taler-developer-manual test-builder}@anchor{21} +@section Test builder + + +This builder (@code{test-builder}) compiles and starts every Taler component. +The associated worker is run by the @code{taler-test} Gv user, via the SystemD +unit @code{buildbot-worker-taler}. The following commands start/stop/restart +the worker: + +@example +systemctl --user start buildbot-worker-taler +systemctl --user stop buildbot-worker-taler +systemctl --user restart buildbot-worker-taler +@end example + +@cartouche +@quotation Note +the mentioned unit file can be found at @code{deployment.git/systemd-services/} +@end quotation +@end cartouche + +@node Wallet builder,Documentation Builder,Test builder,Environments and Builders on taler net +@anchor{taler-developer-manual wallet-builder}@anchor{22} +@section Wallet builder + + +This builder (@code{wallet-builder}) compiles every Taler component +and runs the wallet integration tests. The associated worker is +run by the @code{walletbuilder} Gv user, via the SystemD unit @code{buildbot-worker-wallet}. +The following commands start/stop/restart the worker: + +@example +systemctl --user start buildbot-worker-wallet +systemctl --user stop buildbot-worker-wallet +systemctl --user restart buildbot-worker-wallet +@end example + +@cartouche +@quotation Note +the mentioned unit file can be found at @code{deployment.git/systemd-services/} +@end quotation +@end cartouche + +@node Documentation Builder,Website Builder,Wallet builder,Environments and Builders on taler net +@anchor{taler-developer-manual documentation-builder}@anchor{23} @section Documentation Builder @@ -1083,7 +1484,7 @@ $ buildbot-worker start worker/ @end example @node Website Builder,Code coverage,Documentation Builder,Environments and Builders on taler net -@anchor{taler-developer-manual website-builder}@anchor{1f} +@anchor{taler-developer-manual website-builder}@anchor{24} @section Website Builder @@ -1104,8 +1505,8 @@ $ ./deployment/bootstrap-sitesbuilder $ 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{20} +@node Code coverage,Producing auditor reports,Website Builder,Environments and Builders on taler net +@anchor{taler-developer-manual code-coverage}@anchor{25} @section Code coverage @@ -1127,55 +1528,12 @@ $ 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{21} -@section Service Checker - - -The user @code{demo-checker} runs periodic checks to see if all the -@code{*.demo.taler.net} services are up and running. It is driven by -Buildbot, and can be bootstrapped as follows. - -@example -# Log-in as the 'demo-checker' user - -$ cd $HOME -$ git clone git://git.taler.net/deployment -$ ./deployment/bootstrap-demochecker - -# If the previous step worked, the setup is -# complete and the Buildbot worker can be started. - -$ 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{22} -@section Tipping reserve top-up - - -Both 'test' and 'demo' setups get their tip reserve topped up -by a Buildbot worker. The following steps get the reserve topper -prepared. - -@example -# Log-in as <env>-topper, with <env> being either 'test' or 'demo' - -$ git clone git://git.taler.net/deployment -$ ./deployment/prepare-reservetopper <env> - -# If the previous steps worked, then it should suffice to start -# the worker, with: - -$ 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{23} +@node Producing auditor reports,Database schema versioning,Code coverage,Environments and Builders on taler net +@anchor{taler-developer-manual producing-auditor-reports}@anchor{26} @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. @@ -1183,7 +1541,7 @@ prepared. # Log-in as <env>-auditor, with <env> being either 'test' or 'demo' $ git clone git://git.taler.net/deployment -$ ./deployment/prepare-auditorreporter <env> +$ ./deployment/buildbot/bootstrap-scripts/prepare-auditorreporter <env> # If the previous steps worked, then it should suffice to start # the worker, with: @@ -1192,12 +1550,12 @@ $ 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{24} +@anchor{taler-developer-manual database-schema-versioning}@anchor{27} @section Database schema versioning The PostgreSQL databases of the exchange and the auditor are versioned. -See the 0000.sql file in the respective directory for documentation. +See the @code{versioning.sql} file in the respective directory for documentation. Every set of changes to the database schema must be stored in a new versioned SQL script. The scripts must have contiguous numbers. After @@ -1205,10 +1563,10 @@ any release (or version being deployed to a production or staging environment), existing scripts MUST be immutable. Developers and operators MUST NOT make changes to database schema -outside of this versioning. +outside of this versioning. All tables of a GNU Taler component should live in their own schema. @node Releases,Continuous integration,Environments and Builders on taler net,Top -@anchor{taler-developer-manual releases}@anchor{25} +@anchor{taler-developer-manual releases}@anchor{28} @chapter Releases @@ -1224,7 +1582,7 @@ outside of this versioning. @end menu @node Release Process and Checklists,Tagging,,Releases -@anchor{taler-developer-manual release-process-and-checklists}@anchor{26} +@anchor{taler-developer-manual release-process-and-checklists}@anchor{29} @section Release Process and Checklists @@ -1258,11 +1616,11 @@ taler-wallet-webex (wallet-webex.git) @end itemize @node Tagging,Database for tests,Release Process and Checklists,Releases -@anchor{taler-developer-manual tagging}@anchor{27} +@anchor{taler-developer-manual tagging}@anchor{2a} @section Tagging -Tag releases with an @strong{annotated} commit, like +Tag releases with an `annotated' commit, like @example $ git tag -a v0.1.0 -m "Official release v0.1.0" @@ -1270,25 +1628,24 @@ $ git push origin v0.1.0 @end example @node Database for tests,Exchange merchant,Tagging,Releases -@anchor{taler-developer-manual database-for-tests}@anchor{28} +@anchor{taler-developer-manual database-for-tests}@anchor{2b} @section Database for tests For tests in the exchange and merchant to run, make sure that a database -@emph{talercheck} is accessible by @emph{$USER}. Otherwise tests involving the +`talercheck' is accessible by `$USER'. Otherwise tests involving the database logic are skipped. @cartouche @quotation Note -The Taler merchant backend stores private keys and other sensitive -business and customer data in the database. The backend operator -SHOULD ensure that backup operations are encrypted and secured from -unauthorized access. +Taler may store sensitive business and customer data in the database. Any +operator SHOULD thus ensure that backup operations are encrypted and +secured from unauthorized access. @end quotation @end cartouche @node Exchange merchant,Wallet WebExtension,Database for tests,Releases -@anchor{taler-developer-manual exchange-merchant}@anchor{29} +@anchor{taler-developer-manual exchange-merchant}@anchor{2c} @section Exchange, merchant @@ -1335,7 +1692,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 @@ -1347,12 +1704,12 @@ $ make install check @end example @node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases -@anchor{taler-developer-manual wallet-webextension}@anchor{2a} +@anchor{taler-developer-manual wallet-webextension}@anchor{2d} @section Wallet WebExtension -The version of the wallet is in @emph{manifest.json}. The @code{version_name} -should be adjusted, and @emph{version} should be increased independently on +The version of the wallet is in `manifest.json'. The @code{version_name} +should be adjusted, and `version' should be increased independently on every upload to the WebStore. @example @@ -1361,7 +1718,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{2b} +@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{2e} @section Upload to GNU mirrors @@ -1375,10 +1732,10 @@ directory: taler filename: taler-exchange-0.1.0.tar.gz @end example -Upload the files in @strong{binary mode} to the ftp servers. +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{2c} +@anchor{taler-developer-manual creating-debian-packages}@anchor{2f} @section Creating Debian packages @@ -1395,6 +1752,8 @@ $ dpkg-buildpackage -rfakeroot -b -uc -us 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. +Actual release builds should be done via the Docker images +that can be found in @code{deployment.git} under packaging. On @code{gv}, we use the @code{aptbuilder} user to manage the reprepro repository. @@ -1415,7 +1774,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{2d} +@anchor{taler-developer-manual continuous-integration}@anchor{30} @chapter Continuous integration @@ -1423,21 +1782,21 @@ CI is done with Buildbot (@indicateurl{https://buildbot.net/}), and builds are triggered by the means of Git hooks. The results are published at @indicateurl{https://buildbot.taler.net/} . -In order to avoid downtimes, CI uses a "blue/green" deployment +In order to avoid downtimes, CI uses a “blue/green” deployment technique. In detail, there are two users building code on the system, -the "green" and the "blue" user; and at any given time, one is running +the “green” and the “blue” user; and at any given time, one is running Taler services and the other one is either building the code or waiting for that. There is also the possibility to trigger builds manually, but this is -only reserved to "admin" users. +only reserved to “admin” users. -@node Internationalization,Android Apps,Continuous integration,Top -@anchor{taler-developer-manual internationalization}@anchor{2e} +@node Internationalization,iOS Apps,Continuous integration,Top +@anchor{taler-developer-manual internationalization}@anchor{31} @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. @@ -1454,14 +1813,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{2f} +@anchor{taler-developer-manual who-can-register}@anchor{32} @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. +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{30} +@anchor{taler-developer-manual about-privilege-levels}@anchor{33} @section About Privilege Levels @@ -1471,113 +1830,169 @@ This is the breakdown of privilege levels in Weblate: @itemize * @item -@strong{Users}/@strong{Viewers} = Can log in, view Translations (@emph{applies to new users}) +`Users'/`Viewers' = Can log in, view Translations (`applies to new users') @item -@strong{Reviewers} = Can contribute Translations to existing @emph{Components} +`Reviewers' = Can contribute Translations to existing `Components' @item -@strong{Managers} = Can create new @emph{Components} of existing @emph{Projects} +`Managers' = Can create new `Components' of existing `Projects' @item -@strong{Superusers} = Can create new @emph{Projects} +`Superusers' = Can create new `Projects' @end itemize @node Upgrading Privileges,How to Create a Project,About Privilege Levels,Internationalization -@anchor{taler-developer-manual upgrading-privileges}@anchor{31} +@anchor{taler-developer-manual upgrading-privileges}@anchor{34} @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. +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{32} +@anchor{taler-developer-manual how-to-create-a-project}@anchor{35} @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. +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{33} +@anchor{taler-developer-manual how-to-create-a-component}@anchor{36} @section How to Create a Component Reference: @indicateurl{https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#component-configuration} -In Weblate, a @emph{Component} is a subset of a @emph{Project} and each Component contains N translations. A Component is generally associated with a Git repo. +In Weblate, a `Component' is a subset of a `Project' and each Component contains N translations. A Component is generally associated with a Git repo. -To create a Component, log into @indicateurl{https://weblate.taler.net/} with your @emph{Manager} or higher credentials and choose @strong{+ Add} from the upper-right corner. +To create a Component, log into @indicateurl{https://weblate.taler.net/} with your `Manager' or higher credentials and choose `+ Add' from the upper-right corner. What follows is a sort of Wizard. You can find detailed docs at @indicateurl{https://docs.weblate.org/}. Here are some important notes about connecting your Component to the Taler Git repository: -Under @emph{https://weblate.taler.net/create/component/vcs/}: +Under `https://weblate.taler.net/create/component/vcs/': @itemize * @item -@strong{Source code repository} - Generally @code{git+ssh://git@@git.taler.net/<reponame>`}. Check with @code{git remote -v}. +`Source code repository' - Generally @code{git+ssh://git@@git.taler.net/<reponame>`}. Check with @code{git remote -v}. @item -@strong{Repository branch} - Choose the correct branch to draw from and commit to. +`Repository branch' - Choose the correct branch to draw from and commit to. @item -@strong{Repository push URL} - This is generally @code{git+ssh://git@@git.taler.net/<reponame>`} Check with @code{git remote -v}. +`Repository push URL' - This is generally @code{git+ssh://git@@git.taler.net/<reponame>`} Check with @code{git remote -v}. @item -@strong{Repository browser} - This is the www URL of the Git repo's file browser. Example @code{https://git.taler.net/<repositoryname>.git/tree/@{@{filename@}@}?h=@{@{branch@}@}#n@{@{line@}@}} where @code{<repositoryname>} gets replaced but @code{@{@{filename@}@}} and other items in braces are actual variables in the string. +`Repository browser' - This is the www URL of the Git repo’s file browser. Example @code{https://git.taler.net/<repositoryname>.git/tree/@{@{filename@}@}?h=@{@{branch@}@}#n@{@{line@}@}} where @code{<repositoryname>} gets replaced but @code{@{@{filename@}@}} and other items in braces are actual variables in the string. @item -@strong{Merge style} - @emph{Rebase}, in line with GNU Taler development procedures +`Merge style' - `Rebase', in line with GNU Taler development procedures @item -@strong{Translation license} - @emph{GNU Affero General Public License v3.0 or Later} +`Translation license' - `GNU Affero General Public License v3.0 or Later' @item -@strong{Adding new translation} - Decide how to handle adding new translations +`Adding new translation' - Decide how to handle adding new translations @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{34} +@anchor{taler-developer-manual how-to-create-a-translation}@anchor{37} @section How to Create a Translation 1 - Log into @indicateurl{https://weblate.taler.net} -2 - Navigate to @emph{Projects} > @emph{Browse all projects} +2 - Navigate to `Projects' > `Browse all projects' -3 - Choose the @emph{Project} you wish to contribute to. +3 - Choose the `Project' you wish to contribute to. -4 - Choose the @emph{Component} you wish to contribute to. +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{35} +@anchor{taler-developer-manual translation-standards-and-practices}@anchor{38} @section Translation Standards and Practices -By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the @emph{Component} you want to translate for, and click "Start new translation" to begin. If you require a privilege upgrade, please contact a superuser with your request. +By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the `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{36} +@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{39} @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{3a} +@chapter iOS Apps + + +@menu +* Building Taler Wallet for iOS from source:: + +@end menu -@node Android Apps,Code Coverage,Internationalization,Top -@anchor{taler-developer-manual android-apps}@anchor{37} +@node Building Taler Wallet for iOS from source,,,iOS Apps +@anchor{taler-developer-manual build-ios-from-source}@anchor{3b}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{3c} +@section Building Taler Wallet for iOS from source + + +Currently the iOS Wallet app is in +the official Git repository@footnote{https://git.taler.net/taler-ios.git}: + +@menu +* Compatibility:: +* Building:: + +@end menu + +@node Compatibility,Building,,Building Taler Wallet for iOS from source +@anchor{taler-developer-manual compatibility}@anchor{3d} +@subsection Compatibility + + +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{3e} +@subsection Building + + +Before building the iOS wallet, you must first checkout the +quickjs-tart repo@footnote{https://git.taler.net/quickjs-tart.git} +and the +wallet-core repo@footnote{https://git.taler.net/wallet-core.git}. + +Build wallet-core first, then copy/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… + +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. + +Have all 3 local repos (wallet-core, quickjs-tart, and this one) adjacent at +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}. + +@node Android Apps,Code Coverage,iOS Apps,Top +@anchor{taler-developer-manual android-apps}@anchor{3f} @chapter Android Apps @@ -1590,7 +2005,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{38} +@anchor{taler-developer-manual android-app-nightly-builds}@anchor{40} @section Android App Nightly Builds @@ -1615,7 +2030,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. @@ -1635,13 +2050,13 @@ GNU Taler Nightly F-Droid Repository@footnote{fdroidrepos://gnu-taler.gitlab.io/ @cartouche @quotation Note Nightly apps can be installed alongside official releases -and thus are meant @strong{only for testing purposes}. +and thus are meant `only for testing purposes'. Use at your own risk! @end quotation @end cartouche @node Building apps from source,Update translations,Android App Nightly Builds,Android Apps -@anchor{taler-developer-manual build-apps-from-source}@anchor{39}@anchor{taler-developer-manual building-apps-from-source}@anchor{3a} +@anchor{taler-developer-manual build-apps-from-source}@anchor{41}@anchor{taler-developer-manual building-apps-from-source}@anchor{42} @section Building apps from source @@ -1665,7 +2080,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 @@ -1682,12 +2097,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 @@ -1720,18 +2135,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{3b} +@anchor{taler-developer-manual update-translations}@anchor{43} @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 @@ -1761,7 +2176,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{3c} +@anchor{taler-developer-manual release-process}@anchor{44} @section Release process @@ -1792,12 +2207,12 @@ $ git tag -s $APP-$VERSION @end menu @node F-Droid,Google Play,,Release process -@anchor{taler-developer-manual id1}@anchor{3d} +@anchor{taler-developer-manual id1}@anchor{45} @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: @@ -1816,7 +2231,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{3e} +@anchor{taler-developer-manual google-play}@anchor{46} @subsection Google Play @@ -1838,7 +2253,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{3f}@anchor{taler-developer-manual id3}@anchor{40} +@anchor{taler-developer-manual id2}@anchor{47}@anchor{taler-developer-manual id3}@anchor{48} @chapter Code Coverage @@ -1848,22 +2263,24 @@ 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{41} +@anchor{taler-developer-manual coding-conventions}@anchor{49} @chapter Coding Conventions -GNU Taler is developed primarily in C, Kotlin, Python and TypeScript. +GNU Taler is developed primarily in C, Kotlin, Python, Swift and TypeScript. @menu * Components written in C:: * Shell Scripts:: * Kotlin:: * Python:: +* Swift:: +* TypeScript:: @end menu @node Components written in C,Shell Scripts,,Coding Conventions -@anchor{taler-developer-manual components-written-in-c}@anchor{42} +@anchor{taler-developer-manual components-written-in-c}@anchor{4a} @section Components written in C @@ -1883,7 +2300,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{43} +@anchor{taler-developer-manual naming-conventions}@anchor{4b} @subsection Naming conventions @@ -1897,22 +2314,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 @@ -1945,22 +2362,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 @@ -2002,14 +2419,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 @@ -2029,7 +2446,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 @@ -2039,12 +2456,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{44} +@anchor{taler-developer-manual shell-scripts}@anchor{4c} @section Shell Scripts @@ -2071,15 +2488,15 @@ $ set -eu @end example @node Kotlin,Python,Shell Scripts,Coding Conventions -@anchor{taler-developer-manual kotlin}@anchor{45} +@anchor{taler-developer-manual kotlin}@anchor{4d} @section Kotlin 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{46} +@node Python,Swift,Kotlin,Coding Conventions +@anchor{taler-developer-manual python}@anchor{4e} @section Python @@ -2091,14 +2508,14 @@ for the language. @end menu @node Supported Python Versions,Style,,Python -@anchor{taler-developer-manual supported-python-versions}@anchor{47} +@anchor{taler-developer-manual supported-python-versions}@anchor{4f} @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{48} +@anchor{taler-developer-manual style}@anchor{50} @subsection Style @@ -2108,7 +2525,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{49} +@anchor{taler-developer-manual python-for-scripting}@anchor{51} @subsection Python for Scripting @@ -2125,12 +2542,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{52} +@section Swift + + +Please follow best practices for the language. + +@node TypeScript,,Swift,Coding Conventions +@anchor{taler-developer-manual typescript}@anchor{53} +@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{4a} +@anchor{taler-developer-manual testing-library}@anchor{54} @chapter Testing library @@ -2156,11 +2587,11 @@ former contains the main logic to test feature @code{x}, whereas the latter cleans the memory up after execution. In a test life, each CMD needs some internal state, made by values it -keeps in memory. Often, the test has to @emph{share} those values with other +keeps in memory. Often, the test has to `share' those values with other 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 +The offering of internal values from CMD1 to CMD2 is made by `traits'. A 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 @@ -2195,7 +2626,7 @@ of supposedly well-behaved components. This is needed when, for example, we want the exchange to return some corrupted signature in order to check if the merchant backend detects it. -This alteration is accomplished by another service called @emph{twister}. The +This alteration is accomplished by another service called `twister'. The twister acts as a proxy between service A and B, and can be programmed to tamper with the data exchanged by A and B. @@ -2203,7 +2634,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{4b} +@anchor{taler-developer-manual user-facing-terminology}@anchor{55} @chapter User-Facing Terminology @@ -2217,7 +2648,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{4c} +@anchor{taler-developer-manual terms-to-avoid}@anchor{56} @section Terms to Avoid @@ -2229,29 +2660,36 @@ used in the user interface and help materials. Refreshing is the internal technical terminology for the protocol to give change for partially spent coins -@strong{Use instead}: "Obtaining change" +`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” @item Coin Coins are an internal construct, the user should never be aware that their balance -is represented by coins if different denominations. +is represented by coins of different denominations. -@strong{Use instead}: "(Digital) Cash" or "(Wallet) Balance" +`Use instead': “(Digital) Cash” or “(Wallet) Balance” @item Consumer Has bad connotation of consumption. -@strong{Use instead}: Customer or user. +`Use instead': Customer or user. @item Proposal The term used to describe the process of the merchant facilitating the download of the signed contract terms for an order. -@strong{Avoid}. Generally events that relate to proposal downloads +`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 @@ -2259,14 +2697,14 @@ Should be generally avoided, since Taler is only anonymous for the customer. Also some people are scared of anonymity (which as a term is also way too absolute, as anonymity is hardly ever perfect). -@strong{Use instead}: "Privacy-preserving", "Privacy-friendly" +`Use instead': “Privacy-preserving”, “Privacy-friendly” @item Payment Replay The process of proving to the merchant that the customer is entitled to view a digital product again, as they already paid for it. -@strong{Use instead}: In the event history, "re-activated digital content purchase" +`Use instead': In the event history, “re-activated digital content purchase” could be used. (FIXME: this is still not nice.) @item Session ID @@ -2277,7 +2715,7 @@ See Payment Replay. Too ambiguous in the wallet. -@strong{Use instead}: Purchase +`Use instead': Purchase @item Fulfillment URL @@ -2286,7 +2724,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{4d} +@anchor{taler-developer-manual terms-to-use}@anchor{57} @section Terms to Use @@ -2302,16 +2740,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 @@ -2319,12 +2757,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 @@ -2333,12 +2771,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{4e} +@anchor{taler-developer-manual developer-glossary}@anchor{58} @chapter Developer Glossary @@ -2347,168 +2785,168 @@ use when talking to end users or even system administrators. @table @asis -@anchor{taler-developer-manual term-absolute-time}@anchor{4f} +@anchor{taler-developer-manual term-absolute-time}@anchor{59} @geindex absolute time @item absolute time -method of keeping time in @ref{50,,GNUnet} where the time is represented +method of keeping time in @ref{5a,,GNUnet} where the time is represented as the number of microseconds since 1.1.1970 (UNIX epoch). Called -absolute time in contrast to @ref{51,,relative time}. -@anchor{taler-developer-manual term-aggregate}@anchor{52} +absolute time in contrast to @ref{5b,,relative time}. +@anchor{taler-developer-manual term-aggregate}@anchor{5c} @geindex aggregate @item aggregate -the @ref{53,,exchange} combines multiple payments received by the -same @ref{54,,merchant} into one larger @ref{55,,wire transfer} to -the respective merchant's @ref{56,,bank} account -@anchor{taler-developer-manual term-auditor}@anchor{57} +the @ref{5d,,exchange} combines multiple payments received by the +same @ref{5e,,merchant} into one larger @ref{5f,,wire transfer} to +the respective merchant’s @ref{60,,bank} account +@anchor{taler-developer-manual term-auditor}@anchor{61} @geindex auditor @item auditor -trusted third party that verifies that the @ref{53,,exchange} is operating correctly -@anchor{taler-developer-manual term-bank}@anchor{56} +trusted third party that verifies that the @ref{5d,,exchange} is operating correctly +@anchor{taler-developer-manual term-bank}@anchor{60} @geindex bank @item bank -traditional financial service provider who offers wire @ref{58,,transfers} between accounts -@anchor{taler-developer-manual term-buyer}@anchor{59} +traditional financial service provider who offers wire @ref{62,,transfers} between accounts +@anchor{taler-developer-manual term-buyer}@anchor{63} @geindex buyer @item buyer -individual in control of a Taler @ref{5a,,wallet}, usually using it to -@ref{5b,,spend} the @ref{5c,,coins} on @ref{5d,,contracts} (see also @ref{5e,,customer}). -@anchor{taler-developer-manual term-close}@anchor{5f} +individual in control of a Taler @ref{64,,wallet}, usually using it to +@ref{65,,spend} the @ref{66,,coins} on @ref{67,,contracts} (see also @ref{68,,customer}). +@anchor{taler-developer-manual term-close}@anchor{69} @geindex close -@item close@anchor{taler-developer-manual term-closes}@anchor{60} +@item close@anchor{taler-developer-manual term-closes}@anchor{6a} @geindex closes -@itemx closes@anchor{taler-developer-manual term-closed}@anchor{61} +@itemx closes@anchor{taler-developer-manual term-closed}@anchor{6b} @geindex closed -@itemx closed@anchor{taler-developer-manual term-closing}@anchor{62} +@itemx closed@anchor{taler-developer-manual term-closing}@anchor{6c} @geindex closing @itemx closing -operation an @ref{53,,exchange} performs on a @ref{63,,reserve} that has not been -@ref{64,,drained} by @ref{65,,withdraw} operations. When closing a reserve, the -exchange wires the remaining funds back to the customer, minus a @ref{66,,fee} +operation an @ref{5d,,exchange} performs on a @ref{6d,,reserve} that has not been +@ref{6e,,drained} by @ref{6f,,withdraw} operations. When closing a reserve, the +exchange wires the remaining funds back to the customer, minus a @ref{70,,fee} for closing -@anchor{taler-developer-manual term-coin}@anchor{67} +@anchor{taler-developer-manual term-coin}@anchor{71} @geindex coin -@item coin@anchor{taler-developer-manual term-coins}@anchor{5c} +@item coin@anchor{taler-developer-manual term-coins}@anchor{66} @geindex coins @itemx coins -coins are individual token representing a certain amount of value, also known as the @ref{68,,denomination} of the coin -@anchor{taler-developer-manual term-commitment}@anchor{69} +coins are individual token representing a certain amount of value, also known as the @ref{72,,denomination} of the coin +@anchor{taler-developer-manual term-commitment}@anchor{73} @geindex commitment -@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{6a} +@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{74} @geindex refresh commitment @itemx refresh commitment -data that the wallet commits to during the @ref{6b,,melt} stage of the -@ref{6c,,refresh} protocol where it -has to prove to the @ref{53,,exchange} that it is deriving the @ref{6d,,fresh} +data that the wallet commits to during the @ref{75,,melt} stage of the +@ref{76,,refresh} protocol where it +has to prove to the @ref{5d,,exchange} that it is deriving the @ref{77,,fresh} coins as specified by the Taler protocol. The commitment is verified -probabilistically (see: @ref{6e,,kappa}) during the @ref{6f,,reveal} stage. -@anchor{taler-developer-manual term-contract}@anchor{70} +probabilistically (see: @ref{78,,kappa}) during the @ref{79,,reveal} stage. +@anchor{taler-developer-manual term-contract}@anchor{7a} @geindex contract -@item contract@anchor{taler-developer-manual term-contracts}@anchor{5d} +@item contract@anchor{taler-developer-manual term-contracts}@anchor{67} @geindex contracts @itemx contracts -formal agreement between @ref{54,,merchant} and @ref{5e,,customer} specifying the -@ref{71,,contract terms} and signed by the merchant and the @ref{5c,,coins} of the +formal agreement between @ref{5e,,merchant} and @ref{68,,customer} specifying the +@ref{7b,,contract terms} and signed by the merchant and the @ref{66,,coins} of the customer -@anchor{taler-developer-manual term-contract-terms}@anchor{71} +@anchor{taler-developer-manual term-contract-terms}@anchor{7b} @geindex contract terms @item contract terms the individual clauses specifying what the buyer is purchasing from the -@ref{54,,merchant} -@anchor{taler-developer-manual term-customer}@anchor{5e} +@ref{5e,,merchant} +@anchor{taler-developer-manual term-customer}@anchor{68} @geindex customer @item customer individual that directs the buyer (perhaps the same individual) to make a purchase -@anchor{taler-developer-manual term-denomination}@anchor{68} +@anchor{taler-developer-manual term-denomination}@anchor{72} @geindex denomination @item denomination -unit of currency, specifies both the currency and the face value of a @ref{67,,coin}, +unit of currency, specifies both the currency and the face value of a @ref{71,,coin}, as well as associated fees and validity periods -@anchor{taler-developer-manual term-denomination-key}@anchor{72} +@anchor{taler-developer-manual term-denomination-key}@anchor{7c} @geindex denomination key @item denomination key -(RSA) key used by the exchange to certify that a given @ref{67,,coin} is valid and of a -particular @ref{68,,denomination} -@anchor{taler-developer-manual term-deposit}@anchor{73} +(RSA) key used by the exchange to certify that a given @ref{71,,coin} is valid and of a +particular @ref{72,,denomination} +@anchor{taler-developer-manual term-deposit}@anchor{7d} @geindex deposit -@item deposit@anchor{taler-developer-manual term-deposits}@anchor{74} +@item deposit@anchor{taler-developer-manual term-deposits}@anchor{7e} @geindex deposits -@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{75} +@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{7f} @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{52,,aggregate} @ref{55,,wire transfer} -@anchor{taler-developer-manual term-dirty}@anchor{76} +@ref{5c,,aggregate} @ref{5f,,wire transfer} +@anchor{taler-developer-manual term-dirty}@anchor{80} @geindex dirty -@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{77} +@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{81} @geindex dirty coin @itemx dirty coin a coin is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to -link multiple transactions of coin's owner if the coin is not refreshed -@anchor{taler-developer-manual term-drain}@anchor{78} +link multiple transactions of coin’s owner if the coin is not refreshed +@anchor{taler-developer-manual term-drain}@anchor{82} @geindex drain -@item drain@anchor{taler-developer-manual term-drained}@anchor{64} +@item drain@anchor{taler-developer-manual term-drained}@anchor{6e} @geindex drained @itemx drained -a @ref{63,,reserve} is being drained when a @ref{5a,,wallet} is using the -reserve's private key to @ref{65,,withdraw} coins from it. This reduces +a @ref{6d,,reserve} is being drained when a @ref{64,,wallet} is using the +reserve’s private key to @ref{6f,,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{61,,closed} by the exchange. -@anchor{taler-developer-manual term-exchange}@anchor{53} +(which is the normal process) are @ref{6b,,closed} by the exchange. +@anchor{taler-developer-manual term-exchange}@anchor{5d} @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{79} +@anchor{taler-developer-manual term-expired}@anchor{83} @geindex expired -@item expired@anchor{taler-developer-manual term-expiration}@anchor{7a} +@item expired@anchor{taler-developer-manual term-expiration}@anchor{84} @geindex expiration @itemx expiration @@ -2517,52 +2955,52 @@ Various operations come with time limits. In particular, denomination keys come with strict time limits for the various operations involving the coin issued under the denomination. The most important limit is the deposit expiration, which specifies until when wallets are allowed to -use the coin in deposit or refreshing operations. There is also a "legal" +use the coin in deposit or refreshing operations. There is also a “legal” expiration, which specifies how long the exchange keeps records beyond the deposit expiration time. This latter expiration matters for legal disputes in courts and also creates an upper limit for refreshing operations on special zombie coin -@anchor{taler-developer-manual term-fakebank}@anchor{7b} +@anchor{taler-developer-manual term-fakebank}@anchor{85} @geindex fakebank @item fakebank -implementation of the @ref{56,,bank} API in memory to be used only for test +implementation of the @ref{60,,bank} API in memory to be used only for test cases. -@anchor{taler-developer-manual term-fee}@anchor{66} +@anchor{taler-developer-manual term-fee}@anchor{70} @geindex fee @item fee -an @ref{53,,exchange} charges various fees for its service. The different +an @ref{5d,,exchange} charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for -@ref{7c,,withdrawing}, @ref{75,,depositing}, @ref{7d,,melting}, and -@ref{7e,,refunding}. Furthermore, there are fees per wire transfer -for @ref{62,,closing} a @ref{63,,reserve}: and for -@ref{52,,aggregate} @ref{7f,,wire transfers} to the @ref{54,,merchant}. -@anchor{taler-developer-manual term-fresh}@anchor{6d} +@ref{86,,withdrawing}, @ref{7f,,depositing}, @ref{87,,melting}, and +@ref{88,,refunding}. Furthermore, there are fees per wire transfer +for @ref{6c,,closing} a @ref{6d,,reserve}: and for +@ref{5c,,aggregate} @ref{89,,wire transfers} to the @ref{5e,,merchant}. +@anchor{taler-developer-manual term-fresh}@anchor{77} @geindex fresh -@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{80} +@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{8a} @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{50} +@anchor{taler-developer-manual term-GNUnet}@anchor{5a} @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{81} +@anchor{taler-developer-manual term-json}@anchor{8b} @geindex json -@item json@anchor{taler-developer-manual term-JSON}@anchor{82} +@item json@anchor{taler-developer-manual term-JSON}@anchor{8c} @geindex JSON -@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{83} +@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{8d} @geindex JavaScript Object Notation @itemx JavaScript Object Notation @@ -2570,190 +3008,192 @@ GNU Taler depends upon. serialization format derived from the JavaScript language which is commonly used in the Taler protocol as the payload of HTTP requests and responses. -@anchor{taler-developer-manual term-kappa}@anchor{6e} +@anchor{taler-developer-manual term-kappa}@anchor{78} @geindex kappa @item kappa -security parameter used in the @ref{6c,,refresh} protocol. Defined to be 3. +security parameter used in the @ref{76,,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{84} +@anchor{taler-developer-manual term-LibEuFin}@anchor{8e} @geindex LibEuFin @item LibEuFin FIXME: explain -@anchor{taler-developer-manual term-link}@anchor{85} +@anchor{taler-developer-manual term-link}@anchor{8f} @geindex link -@item link@anchor{taler-developer-manual term-linking}@anchor{86} +@item link@anchor{taler-developer-manual term-linking}@anchor{90} @geindex linking @itemx linking -specific step in the @ref{6c,,refresh} protocol that an exchange must offer -to prevent abuse of the @ref{6c,,refresh} mechanism. The link step is +specific step in the @ref{76,,refresh} protocol that an exchange must offer +to prevent abuse of the @ref{76,,refresh} mechanism. The link step is not needed in normal operation, it just must be offered. -@anchor{taler-developer-manual term-master-key}@anchor{87} +@anchor{taler-developer-manual term-master-key}@anchor{91} @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{6b} +@anchor{taler-developer-manual term-melt}@anchor{75} @geindex melt -@item melt@anchor{taler-developer-manual term-melted}@anchor{88} +@item melt@anchor{taler-developer-manual term-melted}@anchor{92} @geindex melted -@itemx melted@anchor{taler-developer-manual term-melting}@anchor{7d} +@itemx melted@anchor{taler-developer-manual term-melting}@anchor{87} @geindex melting @itemx melting -step of the @ref{6c,,refresh} protocol where a @ref{77,,dirty coin} -is invalidated to be reborn @ref{6d,,fresh} in a subsequent -@ref{6f,,reveal} step. -@anchor{taler-developer-manual term-merchant}@anchor{54} +step of the @ref{76,,refresh} protocol where a @ref{81,,dirty coin} +is invalidated to be reborn @ref{77,,fresh} in a subsequent +@ref{79,,reveal} step. +@anchor{taler-developer-manual term-merchant}@anchor{5e} @geindex merchant @item merchant party receiving payments (usually in return for goods or services) -@anchor{taler-developer-manual term-message-signing-key}@anchor{89} +@anchor{taler-developer-manual term-message-signing-key}@anchor{93} @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{8a} +@anchor{taler-developer-manual term-order}@anchor{94} @geindex order @item order -FIXME: to be written! -@anchor{taler-developer-manual term-owner}@anchor{8b} +offer made by the merchant to a wallet; pre-cursor to +a contract where the wallet is not yet fixed. Turns +into a @ref{7a,,contract} when a wallet claims the order. +@anchor{taler-developer-manual term-owner}@anchor{95} @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{8c} +@anchor{taler-developer-manual term-planchet}@anchor{96} @geindex planchet @item planchet -precursor data for a @ref{67,,coin}. A planchet includes the coin's internal +precursor data for a @ref{71,,coin}. A planchet includes the coin’s internal secrets (coin private key, blinding factor), but lacks the RSA signature -of the @ref{53,,exchange}. When @ref{7c,,withdrawing}, a @ref{5a,,wallet} +of the @ref{5d,,exchange}. When @ref{86,,withdrawing}, a @ref{64,,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{8d} +@anchor{taler-developer-manual term-privacy-policy}@anchor{97} @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{8e} +@anchor{taler-developer-manual term-proof}@anchor{98} @geindex proof @item proof Message that cryptographically demonstrates that a particular claim is correct. -@anchor{taler-developer-manual term-proposal}@anchor{8f} +@anchor{taler-developer-manual term-proposal}@anchor{99} @geindex proposal @item proposal -a list of @ref{71,,contract terms} that has been completed and signed by the +a list of @ref{7b,,contract terms} that has been completed and signed by the merchant backend. -@anchor{taler-developer-manual term-purchase}@anchor{90} +@anchor{taler-developer-manual term-purchase}@anchor{9a} @geindex purchase @item purchase -Refers to the overall process of negotiating a @ref{70,,contract} and then -making a payment with @ref{5c,,coins} to a @ref{54,,merchant}. -@anchor{taler-developer-manual term-recoup}@anchor{91} +Refers to the overall process of negotiating a @ref{7a,,contract} and then +making a payment with @ref{66,,coins} to a @ref{5e,,merchant}. +@anchor{taler-developer-manual term-recoup}@anchor{9b} @geindex recoup @item recoup Operation by which an exchange returns the value of coins affected -by a @ref{92,,revocation} to their @ref{8b,,owner}, either by allowing the owner to -withdraw new coins or wiring funds back to the bank account of the @ref{8b,,owner}. -@anchor{taler-developer-manual term-refresh}@anchor{6c} +by a @ref{9c,,revocation} to their @ref{95,,owner}, either by allowing the owner to +withdraw new coins or wiring funds back to the bank account of the @ref{95,,owner}. +@anchor{taler-developer-manual term-refresh}@anchor{76} @geindex refresh -@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{93} +@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{9d} @geindex refreshing @itemx refreshing -operation by which a @ref{77,,dirty coin} is converted into one or more -@ref{6d,,fresh} coins. Involves @ref{7d,,melting} the @ref{77,,dirty coin} and -then @ref{94,,revealing} so-called @ref{95,,transfer keys}. -@anchor{taler-developer-manual term-refund}@anchor{96} +operation by which a @ref{81,,dirty coin} is converted into one or more +@ref{77,,fresh} coins. Involves @ref{87,,melting} the @ref{81,,dirty coin} and +then @ref{9e,,revealing} so-called @ref{9f,,transfer keys}. +@anchor{taler-developer-manual term-refund}@anchor{a0} @geindex refund -@item refund@anchor{taler-developer-manual term-refunding}@anchor{7e} +@item refund@anchor{taler-developer-manual term-refunding}@anchor{88} @geindex refunding @itemx refunding operation by which a merchant steps back from the right to funds that he -obtained from a @ref{73,,deposit} operation, giving the right to the funds back +obtained from a @ref{7d,,deposit} operation, giving the right to the funds back to the customer -@anchor{taler-developer-manual term-refund-transaction-id}@anchor{97} +@anchor{taler-developer-manual term-refund-transaction-id}@anchor{a1} @geindex refund transaction id @item refund transaction id -unique number by which a merchant identifies a @ref{96,,refund}. Needed +unique number by which a merchant identifies a @ref{a0,,refund}. Needed as refunds can be partial and thus there could be multiple refunds for -the same @ref{90,,purchase}. -@anchor{taler-developer-manual term-relative-time}@anchor{51} +the same @ref{9a,,purchase}. +@anchor{taler-developer-manual term-relative-time}@anchor{5b} @geindex relative time @item relative time -method of keeping time in @ref{50,,GNUnet} where the time is represented +method of keeping time in @ref{5a,,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{4f,,absolute time}. -@anchor{taler-developer-manual term-reserve}@anchor{63} +contrast to @ref{59,,absolute time}. +@anchor{taler-developer-manual term-reserve}@anchor{6d} @geindex reserve @item reserve accounting mechanism used by the exchange to track customer funds -from incoming @ref{7f,,wire transfers}. A reserve is created whenever +from incoming @ref{89,,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{5a,,wallet} -to @ref{65,,withdraw} up to the amount received in @ref{6d,,fresh} -@ref{5c,,coins} from the reserve, thereby draining the reserve. If a -reserve is not drained, the exchange eventually @ref{60,,closes} it. +in the subject. The exchange then allows the customer’s @ref{64,,wallet} +to @ref{6f,,withdraw} up to the amount received in @ref{77,,fresh} +@ref{66,,coins} from the reserve, thereby draining the reserve. If a +reserve is not drained, the exchange eventually @ref{6a,,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{6f} +@anchor{taler-developer-manual term-reveal}@anchor{79} @geindex reveal -@item reveal@anchor{taler-developer-manual term-revealing}@anchor{94} +@item reveal@anchor{taler-developer-manual term-revealing}@anchor{9e} @geindex revealing @itemx revealing -step in the @ref{6c,,refresh} protocol where some of the transfer private +step in the @ref{76,,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{6d,,fresh} coins. -@anchor{taler-developer-manual term-revoke}@anchor{98} +In the reveal step, the exchange returns the signed @ref{77,,fresh} coins. +@anchor{taler-developer-manual term-revoke}@anchor{a2} @geindex revoke -@item revoke@anchor{taler-developer-manual term-revocation}@anchor{92} +@item revoke@anchor{taler-developer-manual term-revocation}@anchor{9c} @geindex revocation @itemx revocation @@ -2762,109 +3202,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{99} +@anchor{taler-developer-manual term-sharing}@anchor{a3} @geindex sharing @item sharing -users can share ownership of a @ref{67,,coin} by sharing access to the coin's +users can share ownership of a @ref{71,,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{5b} +@anchor{taler-developer-manual term-spend}@anchor{65} @geindex spend -@item spend@anchor{taler-developer-manual term-spending}@anchor{9a} +@item spend@anchor{taler-developer-manual term-spending}@anchor{a4} @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{9b} +@anchor{taler-developer-manual term-terms}@anchor{a5} @geindex terms @item terms the general terms of service of an operator, possibly including -the @ref{8d,,privacy policy}. Not to be confused with the -@ref{71,,contract terms} which are about the specific purchase. -@anchor{taler-developer-manual term-transaction}@anchor{9c} +the @ref{97,,privacy policy}. Not to be confused with the +@ref{7b,,contract terms} which are about the specific purchase. +@anchor{taler-developer-manual term-transaction}@anchor{a6} @geindex transaction @item transaction method by which ownership is exclusively transferred from one entity -@anchor{taler-developer-manual term-transfer}@anchor{58} +@anchor{taler-developer-manual term-transfer}@anchor{62} @geindex transfer -@item transfer@anchor{taler-developer-manual term-transfers}@anchor{9d} +@item transfer@anchor{taler-developer-manual term-transfers}@anchor{a7} @geindex transfers -@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{55} +@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{5f} @geindex wire transfer -@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7f} +@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{89} @geindex wire transfers @itemx wire transfers -method of sending funds between @ref{56,,bank} accounts -@anchor{taler-developer-manual term-transfer-key}@anchor{9e} +method of sending funds between @ref{60,,bank} accounts +@anchor{taler-developer-manual term-transfer-key}@anchor{a8} @geindex transfer key -@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{95} +@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{9f} @geindex transfer keys @itemx transfer keys -special cryptographic key used in the @ref{6c,,refresh} protocol, some of which -are revealed during the @ref{6f,,reveal} step. Note that transfer keys have, -despite the name, no relationship to @ref{7f,,wire transfers}. They merely -help to transfer the value from a @ref{77,,dirty coin} to a @ref{80,,fresh coin} -@anchor{taler-developer-manual term-user}@anchor{9f} +special cryptographic key used in the @ref{76,,refresh} protocol, some of which +are revealed during the @ref{79,,reveal} step. Note that transfer keys have, +despite the name, no relationship to @ref{89,,wire transfers}. They merely +help to transfer the value from a @ref{81,,dirty coin} to a @ref{8a,,fresh coin} +@anchor{taler-developer-manual term-user}@anchor{a9} @geindex user @item user any individual using the Taler payment system -(see @ref{5e,,customer}, @ref{59,,buyer}, @ref{54,,merchant}). -@anchor{taler-developer-manual term-version}@anchor{a0} +(see @ref{68,,customer}, @ref{63,,buyer}, @ref{5e,,merchant}). +@anchor{taler-developer-manual term-version}@anchor{aa} @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{53,,exchange}, -@ref{57,,auditor} or @ref{54,,merchant}. There is a protocol +the state of the table structure in the database of an @ref{5d,,exchange}, +@ref{61,,auditor} or @ref{5e,,merchant}. There is a protocol version (CURRENT:REVISION:AGE, see GNU libtool) which specifies -the network protocol spoken by an @ref{53,,exchange} or @ref{54,,merchant} +the network protocol spoken by an @ref{5d,,exchange} or @ref{5e,,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{5a} +@anchor{taler-developer-manual term-wallet}@anchor{64} @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{ab} @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{ac} @geindex wire gateway @item wire gateway FIXME: explain -@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a3} +@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{ad} @geindex wire transfer identifier -@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{a4} +@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{ae} @geindex wtid @itemx wtid @@ -2872,35 +3312,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{65} +@anchor{taler-developer-manual term-withdraw}@anchor{6f} @geindex withdraw -@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{7c} +@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{86} @geindex withdrawing -@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a5} +@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{af} @geindex withdrawal @itemx withdrawal -operation by which a @ref{5a,,wallet} can convert funds from a @ref{63,,reserve} to +operation by which a @ref{64,,wallet} can convert funds from a @ref{6d,,reserve} to fresh coins -@anchor{taler-developer-manual term-zombie}@anchor{a6} +@anchor{taler-developer-manual term-zombie}@anchor{b0} @geindex zombie -@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a7} +@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{b1} @geindex zombie coin @itemx zombie coin -coin where the respective @ref{72,,denomination key} is past its -@ref{73,,deposit} @ref{7a,,expiration} time, but which is still (again) valid -for an operation because it was @ref{88,,melted} while it was still -valid, and then later again credited during a @ref{91,,recoup} process +coin where the respective @ref{7c,,denomination key} is past its +@ref{7d,,deposit} @ref{84,,expiration} time, but which is still (again) valid +for an operation because it was @ref{92,,melted} while it was still +valid, and then later again credited during a @ref{9b,,recoup} process @end table @node Developer Tools,Index,Developer Glossary,Top -@anchor{taler-developer-manual developer-tools}@anchor{a8} +@anchor{taler-developer-manual developer-tools}@anchor{b2} @chapter Developer Tools @@ -2913,100 +3353,100 @@ developer. @end menu @node taler-config-generate,,,Developer Tools -@anchor{taler-developer-manual taler-config-generate}@anchor{a9} +@anchor{taler-developer-manual taler-config-generate}@anchor{b3} @section taler-config-generate -@strong{taler-config-generate} - tool to simplify Taler configuration generation - -@strong{taler-config-generate} -[@strong{-C} @emph{CURRENCY} | @strong{--currency=}@emph{CURRENCY}] -[@strong{-c} @emph{FILENAME} | @strong{--config=}@emph{FILENAME}] -[@strong{-e} | @strong{--exchange}] -[@strong{-f} @emph{AMOUNT} | @emph{--wirefee=}@emph{AMOUNT}] -[@strong{-h} | @strong{--help}] -[@strong{-J} @emph{JSON} | @strong{--wire-json-exchange=}@emph{JSON}] -[@strong{-j} @emph{JSON} | @strong{--wire-json-merchant=}@emph{JSON}] -[@strong{-L} @emph{LOGLEVEL} | @strong{--loglevel=}@emph{LOGLEVEL}] -[@strong{-m} | @strong{--merchant}] -[@strong{-t} | @strong{--trusted}] -[@strong{-v} | @strong{--version}] -[@strong{-w} @emph{WIREFORMAT} | @strong{--wire} @emph{WIREFORMAT}] -[@strong{--bank-uri}] -[@strong{--exchange-bank-account}] -[@strong{--merchant-bank-account}] - -@strong{taler-config-generate} can be used to generate configuration files +`taler-config-generate' - tool to simplify Taler configuration generation + +`taler-config-generate' +[`-C' `CURRENCY' | `–currency='`CURRENCY'] +[`-c' `FILENAME' | `–config='`FILENAME'] +[`-e' | `–exchange'] +[`-f' `AMOUNT' | `–wirefee='`AMOUNT'] +[`-h' | `–help'] +[`-J' `JSON' | `–wire-json-exchange='`JSON'] +[`-j' `JSON' | `–wire-json-merchant='`JSON'] +[`-L' `LOGLEVEL' | `–loglevel='`LOGLEVEL'] +[`-m' | `–merchant'] +[`-t' | `–trusted'] +[`-v' | `–version'] +[`-w' `WIREFORMAT' | `–wire' `WIREFORMAT'] +[`–bank-uri'] +[`–exchange-bank-account'] +[`–merchant-bank-account'] + +`taler-config-generate' can be used to generate configuration files for the Taler exchange or Taler merchants. @table @asis -@item @strong{-C} @emph{CURRENCY} | @strong{--currency=}@emph{CURRENCY} +@item `-C' `CURRENCY' | `–currency='`CURRENCY' Which currency should we use in the configuration. -@item @strong{-c} @emph{FILENAME} | @strong{--config=}@emph{FILENAME} +@item `-c' `FILENAME' | `–config='`FILENAME' Location where to write the generated configuration. Existing file will be updated, not overwritten. -@item @strong{-e} | @strong{--exchange} +@item `-e' | `–exchange' Generate configuration for a Taler exchange. -@item @strong{-f} @emph{AMOUNT} | @emph{-wirefee=}@emph{AMOUNT} +@item `-f' `AMOUNT' | `-wirefee='`AMOUNT' Setup wire transfer fees for the next 5 years for the exchange (for all wire methods). -@item @strong{-h} | @strong{--help} +@item `-h' | `–help' Shows this man page. -@item @strong{-J} @emph{JSON} | @strong{--wire-json-exchange=}@emph{JSON} +@item `-J' `JSON' | `–wire-json-exchange='`JSON' Wire configuration to use for the exchange. -@item @strong{-j} @emph{JSON} | @strong{--wire-json-merchant=}@emph{JSON} +@item `-j' `JSON' | `–wire-json-merchant='`JSON' Wire configuration to use for the merchant. -@item @strong{-L} @emph{LOGLEVEL} | @strong{--loglevel=}@emph{LOGLEVEL} +@item `-L' `LOGLEVEL' | `–loglevel='`LOGLEVEL' Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. -@item @strong{-m} | @strong{--merchant} +@item `-m' | `–merchant' Generate configuration for a Taler merchant. -@item @strong{-t} | @strong{--trusted} +@item `-t' | `–trusted' Setup current exchange as trusted with current merchant. Generally only useful when configuring for testcases. -@item @strong{-v} | @strong{--version} +@item `-v' | `–version' Print version information. -@item @strong{-w} @emph{WIREFORMAT} | @strong{--wire} @emph{WIREFORMAT} +@item `-w' `WIREFORMAT' | `–wire' `WIREFORMAT' Specifies which wire format to use (i.e. “x-talerbank” or “iban”) -@item @strong{--bank-uri} +@item `–bank-uri' Alternative to specify wire configuration to use for the exchange and merchant for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the URI of the bank. -@item @strong{--exchange-bank-account} +@item `–exchange-bank-account' Alternative to specify wire configuration to use for the exchange for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the bank account number of the exchange. -@item @strong{--merchant-bank-account} +@item `–merchant-bank-account' Alternative to specify wire configuration to use for the merchant for the “test” wire method. Only useful if WIREFORMAT was set to “test”. |