diff options
Diffstat (limited to 'texinfo/taler-developer-manual.texi')
| -rw-r--r-- | texinfo/taler-developer-manual.texi | 2976 |
1 files changed, 2091 insertions, 885 deletions
diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 4896a6ff..e778c351 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.texi @@ -3,29 +3,27 @@ @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 @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Network applications @direntry -* MENU ENTRY: (taler-developer-manual.info). DESCRIPTION +* GNU Taler Development: (taler-developer-manual.info). Manual for GNU Taler contributors @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.8.2, Aug 08, 2021 +GNU Taler 0.10.0, May 15, 2024 GNU Taler team -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -50,7 +48,7 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @anchor{taler-developer-manual doc}@anchor{0} @c This file is part of GNU TALER. @c -@c Copyright (C) 2014-2021 Taler Systems SA +@c Copyright (C) 2014-2023 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the @c terms of the GNU Affero General Public License as published by the Free Software @@ -65,17 +63,25 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @c @c @author Christian Grothoff +@cartouche +@quotation Note +This manual contains information for developers working on GNU Taler +and related components. It is not intended for a general audience. +@end quotation +@end cartouche + @menu -* GNU Taler Release Checklist:: -* GNU Taler Demo Upgrade Checklist:: +* Project Overview:: * Fundamentals:: -* Language-Specific Guidelines:: +* Debian and Ubuntu Repositories:: * Taler Deployment on gv.taler.net: Taler Deployment on gv taler net. * Demo Upgrade Procedure:: * Environments and Builders on taler.net: Environments and Builders on taler net. +* QA Plans:: * Releases:: * Continuous integration:: * Internationalization:: +* iOS Apps:: * Android Apps:: * Code Coverage:: * Coding Conventions:: @@ -87,300 +93,234 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end menu -@node GNU Taler Release Checklist,GNU Taler Demo Upgrade Checklist,Top,Top -@anchor{checklist-release doc}@anchor{1}@anchor{checklist-release developer-s-manual}@anchor{2}@anchor{checklist-release gnu-taler-release-checklist}@anchor{3} -@chapter GNU Taler Release Checklist - - -Release checklists for GNU Taler: +@node Project Overview,Fundamentals,Top,Top +@anchor{taler-developer-manual developer-s-manual}@anchor{1}@anchor{taler-developer-manual project-overview}@anchor{2} +@chapter Project Overview -Wallet: +GNU Taler consists of a large (and growing) number of components +in various Git repositories. The following list gives a first +overview: -@itemize - - -@item -[ ] build wallet - -@item -[ ] verify wallet works against ‘test.taler.net’ +@quotation -@item -[ ] tag repo. -@item -[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’ - -@item -[ ] upload new wallet release to app store - -@item -[ ] Update bug tracker (mark release, resolved -> closed) +@itemize * @item -[ ] Send announcement to @email{taler@@gnu.org} +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 -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +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 -[ ] Send announcement to @email{coordinator@@translationproject.org} -@end itemize - -For exchange: - - -@itemize - +deploymerization: implementation of the “bank” API on top of +blockchains, specifically Bitcoin and Ethereum. Allows an exchange +to interact with crypto-currencies. @item -[ ] check no compiler warnings at “-Wall” +merchant: payment processing backend to be run by merchants, +offering a REST API. @item -[ ] ensure Coverity static analysis passes +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 -[ ] make check. +taler-android: Android Apps including the Android wallet, the +Android point-of-sale App and the Android casher app. @item -[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’ +taler-ios: iOS wallet App. @item -[ ] make dist, make check on result of ‘make dist’. +sync: backup service, provides a simple REST API to allow users to +make encrypted backups of their wallet state. @item -[ ] Change version number in configure.ac. +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 -[ ] make dist for release. +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 -[ ] tag repo. +gnu-taler-payment-for-woocommerce: payment plugin for the +woocommerce (wordpress) E-commerce solution. @item -[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +twister: man-in-the-middle proxy for tests that require fuzzing a +REST/JSON protocol. Used for some of our testing. @item -[ ] Update bug tracker (mark release, resolved -> closed) +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 -[ ] Send announcement to @email{taler@@gnu.org} +taler-mailbox: messaging service used to store and forward payment +messages to Taler wallets. @item -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +taldir: directory service used to lookup Taler wallet addresses for +sending invoices or payments to other wallets. @item -[ ] Send announcement to @email{coordinator@@translationproject.org} +taler-merchant-demos: various demonstration services operated at +‘demo.taler.net’, including a simple shop and a donation page. @end itemize +@end quotation -For merchant (C backend): - - -@itemize - - -@item -[ ] check no compiler warnings at “-Wall” - -@item -[ ] ensure Coverity static analysis passes - -@item -[ ] make check. - -@item -[ ] upgrade ‘demo.taler.net’ to ‘test.taler.net’ +There are other important repositories without code, including: -@item -[ ] make dist, make check on result of ‘make dist’. +@quotation -@item -[ ] Change version number in configure.ac. -@item -[ ] make dist for release. - -@item -[ ] tag repo. +@itemize * @item -[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +gana: Hosted on git.gnunet.org, this repository defines various +constants used in the GNU Taler project. @item -[ ] Update bug tracker (mark release, resolved -> closed) +docs: documentation, including this very document. @item -[ ] Send announcement to @email{taler@@gnu.org} +marketing: various presentations, papers and other resources for +outreach. @item -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +large-media: very large data objects, such as videos. @item -[ ] Send announcement to @email{coordinator@@translationproject.org} -@end itemize - -For bank: - - -@itemize - - -@item -TBD +www: the taler.net website. @end itemize +@end quotation -For Python merchant frontend: +@node Fundamentals,Debian and Ubuntu Repositories,Project Overview,Top +@anchor{taler-developer-manual fundamentals}@anchor{3} +@chapter Fundamentals -@itemize - +@menu +* Versioning:: +* Testing Tools:: +* Manual Testing Database Reset:: +* Bug Tracking:: +* Code Repositories:: +* Committing code:: +* Observing changes:: +* Communication:: +* What to put in bootstrap:: -@item -TBD -@end itemize +@end menu -For PHP merchant frontend: +@node Versioning,Testing Tools,,Fundamentals +@anchor{taler-developer-manual versioning}@anchor{4} +@section Versioning + + +A central rule is to never break anything for any dependency. To accomplish +this, we use versioning, of the APIs, database schema and the protocol. The +database versioning approach is described in the @ref{5,,Database schema versioning} section. Here, we will focus on API and +protocol versioning. + +The key issue we need to solve with protocols and APIs (and that does not +apply to database versioning) is being able to introduce and remove features +without requiring a flag day where all components must update at the same +time. For this, we use GNU libtool style versioning with MAJOR:REVISION:AGE +and `not' semantic versioning (SEMVER). With GNU libtool style versioning, +first the REVISION should be increased on every change to the respective code. +Then, each time a feature is introduced or deprecated, the MAJOR and AGE +numbers are increased. Whenever an API is actually removed the AGE number is +reduced to match the distance since the removed API was deprecated. Thus, if +some client implements version X of the protocol (including not using any APIs +that have been deprecated), it is compatible for any implementation where +MAJOR is larger or equal to X, and MAJOR minus AGE is smaller or equal to X. +REVISION is not used for expected compatibility issues and merely serves to +uniquely identify each version (in combination with MAJOR). + +To evolve any implementation, it is thus critical to first of all never +just break an existing API or endpoint. The only acceptable modifications +are to return additional information (being aware of binary compatibility!) +or to accept additional optional arguments (again, in a way that does not +break existing users). Thus, the most common way to introduce changes will +be the addition of new endpoints. Breaking existing endpoints is only ever +at best acceptable while in the process of introducing it and if you are +absolutely sure that there are zero users in other components. + +When removing endpoints (or fields being returned), you must first deprecate +the existing API (incrementing MAJOR and AGE) and then wait for all clients, +including all clients in operation (e.g. Android and iOS Apps, e-commerce +integrations, etc.) to upgrade to a protocol implementation above the +deprecated MAJOR revision. Only then you should remove the endpoint and reduce +AGE. + +To document these changes, please try to use @code{@@since} annotations in the API +specifications to explain the MAJOR revision when a feature became available, +but most importantly use @code{@@deprecated X} annotations to indicate that an API +was deprecated and will be removed once MAJOR minus AGE is above X. When using +an API, use the @code{/config} endpoints to check for compatibility and show a +warning if the version(s) you support and the version(s) offered by the server +are incompatible. + +@node Testing Tools,Manual Testing Database Reset,Versioning,Fundamentals +@anchor{taler-developer-manual testing-tools}@anchor{6} +@section Testing Tools + + +For full @code{make check} support, install these programs: @itemize - @item -TBD -@end itemize - -For auditor: - - -@itemize - +jq@footnote{https://github.com/stedolan/jq} @item -TBD -@end itemize - -For libebics: - - -@itemize - +curl@footnote{http://curl.haxx.se} @item -TBD +faketime@footnote{https://github.com/wolfcw/libfaketime} @end itemize -@node GNU Taler Demo Upgrade Checklist,Fundamentals,GNU Taler Release Checklist,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 +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{7} +@section Manual Testing Database Reset -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: +Sometimes @code{make check} will fail with some kind of database (SQL) +error, perhaps with a message like @code{OBJECT does not exist} in the +@code{test-suite.log} file, where @code{OBJECT} is the name of a table or function. +In that case, it may be necessary to reset the @code{talercheck} database +with the commands: @example -$ taler-wallet-cli integrationtest \ - -e https://exchange.demo.taler.net/ \ - -m https://backend.demo.taler.net/ \ - -b https://bank.demo.taler.net \ - -w "KUDOS:10" \ - -s "KUDOS:5" +$ dropdb talercheck +$ createdb talercheck @end example -@end itemize - -Basics: - - -@itemize - - -@item - Visit @indicateurl{https://demo.taler.net/} to see if the landing page is displayed correctly - -@item - Visit the wallet installation page, install the wallet, and see if the presence -indicator is updated correctly. - -@item - Visit @indicateurl{https://bank.demo.taler.net/}, register a new user and withdraw coins into the -browser wallet. -@end itemize - -Blog demo: - - -@itemize - - -@item - Visit @indicateurl{https://shop.demo.taler.net/} and purchase an article. - -@item - Verify that the balance in the wallet was updated correctly. - -@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 -requested. - -@item - Open the fulfillment page from the previous step in an anonymous browsing session -(without the wallet installed) and verify that it requests a payment again. - -@item - Delete cookies on @indicateurl{https://shop.demo.taler.net/} and click on the same article again. -Verify that the wallet detects that the article has already purchased and successfully -redirects to the article without spending more money. -@end itemize -Donation demo: +This is because, at the moment, there is no support for +doing these steps automatically in the @code{make check} flow. +(If @code{make check} still fails after the reset, file a bug report as usual.) -@itemize - - -@item - Make a donation on @indicateurl{https://donations.demo.taler.net} - -@item - Make another donation with the same parameters and verify -that the payment is requested again, instead of showing the previous -fulfillment page. -@end itemize - -Survey/Tipping: - - -@itemize - - -@item - Visit @indicateurl{https://survey.demo.taler.net/} and receive a tip. - -@item - Verify that the survey stats page (@indicateurl{https://survey.demo.taler.net/survey-stats}) is working, -and that the survey reserve has sufficient funds. -@end itemize - -@cartouche -@quotation Note -This manual contains information for developers working on GNU Taler -and related components. It is not intended for a general audience. -@end quotation -@end cartouche - -@node Fundamentals,Language-Specific Guidelines,GNU Taler Demo Upgrade Checklist,Top -@anchor{taler-developer-manual fundamentals}@anchor{6} -@chapter Fundamentals - - -@menu -* Bug Tracking:: -* Code Repositories:: -* Committing code:: -* Observing changes:: -* Communication:: - -@end menu - -@node Bug Tracking,Code Repositories,,Fundamentals -@anchor{taler-developer-manual bug-tracking}@anchor{7} +@node Bug Tracking,Code Repositories,Manual Testing Database Reset,Fundamentals +@anchor{taler-developer-manual bug-tracking}@anchor{8} @section Bug Tracking @@ -390,7 +330,7 @@ needed in order to use the bug tracker, only read access is granted without a login. @node Code Repositories,Committing code,Bug Tracking,Fundamentals -@anchor{taler-developer-manual code-repositories}@anchor{8} +@anchor{taler-developer-manual code-repositories}@anchor{9} @section Code Repositories @@ -405,7 +345,7 @@ A complete list of all the existing repositories is currently found at @indicateurl{https://git.taler.net/}. @node Committing code,Observing changes,Code Repositories,Fundamentals -@anchor{taler-developer-manual committing-code}@anchor{9} +@anchor{taler-developer-manual committing-code}@anchor{a} @section Committing code @@ -474,7 +414,7 @@ $ git pull --rebase -S @end example @node Observing changes,Communication,Committing code,Fundamentals -@anchor{taler-developer-manual observing-changes}@anchor{a} +@anchor{taler-developer-manual observing-changes}@anchor{b} @section Observing changes @@ -486,43 +426,109 @@ our main dependencies, namely GNUnet and GNU libmicrohttpd. While it can be high volume, the lists is a good way to follow overall development. -@node Communication,,Observing changes,Fundamentals -@anchor{taler-developer-manual communication}@anchor{b} +@node Communication,What to put in bootstrap,Observing changes,Fundamentals +@anchor{taler-developer-manual communication}@anchor{c} @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 Language-Specific Guidelines,Taler Deployment on gv taler net,Fundamentals,Top -@anchor{taler-developer-manual language-specific-guidelines}@anchor{c} -@chapter Language-Specific Guidelines +@node What to put in bootstrap,,Communication,Fundamentals +@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{d} +@section What to put in bootstrap +Each repository has a @code{bootstrap} script, which contains commands for the +developer to run after a repository checkout (i.e., after @code{git clone} or +@code{git pull}). +Typically, this updates and initializes submodules, prepares the tool chain, +and runs @code{autoreconf}. +The last step generates the @code{configure} script, whether for immediate use or +for inclusion in the distribution tarball. -@itemize * +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 --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: + + +@itemize - + +@item +(in GANA repo) Find a suitable (unused) name and number for the Signature +Purposes database. + +@item +Add it to GANA, in @code{gnunet-signatures/registry.rec}. +(You can check for uniqueness with the @code{recfix} utility.) + +@item +Commit the change, and push it to the GANA Git repo. + +@item +(in Taler Repo) Run the @code{contrib/gana-latest.sh} script. @item -Python Guidelines +Bootstrap, configure, do @code{make install}, @code{make check}, etc. +(Basically, make sure the change does not break anything.) + +@item +Commit the submodule change, and push it to the Taler exchange Git repo. @end itemize -@node Taler Deployment on gv taler net,Demo Upgrade Procedure,Language-Specific Guidelines,Top -@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{d} -@chapter Taler Deployment on gv.taler.net +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,Taler Deployment on gv taler net,Fundamentals,Top +@anchor{taler-developer-manual debian-and-ubuntu-repositories}@anchor{e} +@chapter Debian and Ubuntu Repositories -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. +We package our software for Debian and Ubuntu. + +@menu +* Nightly Repositories:: + +@end menu + +@node Nightly Repositories,,,Debian and Ubuntu Repositories +@anchor{taler-developer-manual nightly-repositories}@anchor{f} +@section Nightly Repositories + + +To try the latest, unstable and untested versions of packages, +you can add the nightly package sources. + +@example +# For Ubuntu (focal-fossa) +$ echo "deb https://deb.taler.net/apt-nightly focal-taler-nightly main" > /etc/apt/sources.list.d/taler.list + +# For Debian (bullseye) +$ echo "deb https://deb.taler.net/apt-nightly bullseye-taler-nightly main" > /etc/apt/sources.list.d/taler.list + +# Both: Install signing key for nightly packages +$ wget -O - https://taler.net/taler-systems-nightly.gpg.key | apt-key add - +@end example + +@node Taler Deployment on gv taler net,Demo Upgrade Procedure,Debian and Ubuntu Repositories,Top +@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{10} +@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, 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:: @@ -531,16 +537,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{e} +@anchor{taler-developer-manual dns}@anchor{11} @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{f} +@anchor{taler-developer-manual user-acccounts}@anchor{12} @section User Acccounts @@ -555,53 +561,96 @@ 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. + +@item +@code{demo}: serves @code{*.demo.taler.net}. Never 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. +@node Demo Upgrade Procedure,Environments and Builders on taler net,Taler Deployment on gv taler net,Top +@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{13} +@chapter Demo Upgrade Procedure -@itemize - + +@enumerate @item -@code{demo-blue} +Login as the @code{demo} user on @code{gv.taler.net}. @item -@code{demo-green} -@end itemize +Pull the latest @code{deployment.git} code. -@node Demo Upgrade Procedure,Environments and Builders on taler net,Taler Deployment on gv taler net,Top -@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{10} -@chapter Demo Upgrade Procedure +@item +Navigate to the @code{deployment.git/docker/demo} directory. +@item +Refer to the README, or the smaller cheat sheet below. +@end enumerate + +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 + +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 +$ curl -fsSL https://get.docker.com/rootless | sh +@end example +@end quotation +@end cartouche 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}. - -Please use the @ref{4,,demo upgrade checklist} to make +Please use the demo upgrade checklist to make sure everything is working. +Nginx is already configured to reach the services as exported by +Docker Compose. @menu +* Cheat sheet:: * Tagging components:: -* Environment Layout:: -* Using envcfg.py: Using envcfg py. -* Bootstrapping an Environment:: -* Upgrading an Existing Environment:: -* Switching Demo Colors:: +* GNU Taler Demo Upgrade Checklist:: @end menu -@node Tagging components,Environment Layout,,Demo Upgrade Procedure -@anchor{taler-developer-manual tagging-components}@anchor{11} +@node Cheat sheet,Tagging components,,Demo Upgrade Procedure +@anchor{taler-developer-manual cheat-sheet}@anchor{14} +@section Cheat sheet + + +All commands run from deployment.git/docker/demo. + +@example +# Start services. +$ docker-compose start --remove-orphans -d + +# Stop services. +$ docker-compose stop + +# Build base image (without tags-file builds master) +$ ./build_base.sh images/base/Dockerfile [tags-file] + +# 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 Tagging components,GNU Taler Demo Upgrade Checklist,Cheat sheet,Demo Upgrade Procedure +@anchor{taler-developer-manual tagging-components}@anchor{15} @section Tagging components @@ -616,125 +665,456 @@ DD = day SS = serial @end example -@node Environment Layout,Using envcfg py,Tagging components,Demo Upgrade Procedure -@anchor{taler-developer-manual environment-layout}@anchor{12} -@section Environment Layout +@node GNU Taler Demo Upgrade Checklist,,Tagging components,Demo Upgrade Procedure +@anchor{taler-developer-manual gnu-taler-demo-upgrade-checklist}@anchor{16} +@section GNU Taler Demo Upgrade Checklist -Environments have the following layout: +@menu +* Domains:: +* Post-upgrade checks:: +* Wallets:: +* Basics:: +* Exchange AML SPA:: +* Blog demo:: +* Donation demo:: +* Merchant SPA:: +* P2P payments:: +* Shutdown:: -@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) -@end example +@end menu + +@node Domains,Post-upgrade checks,,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual domains}@anchor{17} +@subsection Domains -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{13} -@section Using envcfg.py +The checklist uses the @code{demo.taler.net} domains. However, +the same sandcastle demo can also be hosted at other domains. +The same instructions should apply. +@node Post-upgrade checks,Wallets,Domains,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual post-upgrade-checks}@anchor{18} +@subsection Post-upgrade checks -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: + +@itemize - + +@item + Run the headless wallet to check that services are actually working: @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 +taler-wallet-cli api 'runIntegrationTestV2' '@{"exchangeBaseUrl":"https://exchange.demo.taler.net", "corebankApiBaseUrl": "https://bank.demo.taler.net", "merchantBaseUrl": "https://backend.demo.taler.net", "merchantAuthToken":"secret-token:sandbox"@}' @end example +@end itemize -Currently only the variables @code{env} and @code{tag_$@{component@}} are used. +@node Wallets,Basics,Post-upgrade checks,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual wallets}@anchor{19} +@subsection Wallets -When deploying to @code{demo}, the @code{envcfg.py} should be committed to @code{deployment.git/envcfg/envcfg-demo-YYYY-MM-DD-SS.py}. -@node Bootstrapping an Environment,Upgrading an Existing Environment,Using envcfg py,Demo Upgrade Procedure -@anchor{taler-developer-manual bootstrapping-an-environment}@anchor{14} -@section Bootstrapping an Environment +We consider the following published wallets to be “production wallets”: -@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 +@itemize * + +@item +Browser: Firefox Add-On Store -@node Upgrading an Existing Environment,Switching Demo Colors,Bootstrapping an Environment,Demo Upgrade Procedure -@anchor{taler-developer-manual upgrading-an-existing-environment}@anchor{15} -@section Upgrading an Existing Environment +@item +Browser: Chrome Web Store +@item +Android: Google Play -@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 -@end example +@item +Android: F-Droid -@node Switching Demo Colors,,Upgrading an Existing Environment,Demo Upgrade Procedure -@anchor{taler-developer-manual switching-demo-colors}@anchor{16} -@section Switching Demo Colors +@item +iOS: Apple Store / Testflight +@end itemize +@node Basics,Exchange AML SPA,Wallets,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual basics}@anchor{1a} +@subsection Basics -As the @code{demo} user, to switch to color @code{$@{COLOR@}}, -run the following script from @code{deployment/bin}: -@example -$ taler-deployment switch-demo -@end example -@node Environments and Builders on taler net,Releases,Demo Upgrade Procedure,Top -@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{17} +@itemize - + +@item + Visit @indicateurl{https://demo.taler.net/} to see if the landing page is displayed correctly + +@item + landing language switcher + +@item + Visit the wallet installation page, install the wallet + +@item + see if the wallet presence indicator is updated correctly (in browsers). + +@item + Visit @indicateurl{https://bank.demo.taler.net/}, register a new user + +@item + bank language switcher + +@item + bank logout + +@item + bank login + +@item + bank-integrated withdraw process, abort in bank + +@item + transaction history: delete pending withdraw + +@item + do bank-integrated withdraw process (5 KUDOS) + +@item + do wallet-initiated withdraw process (5 KUDOS) + +@item + withdraw process of large amount (20 KUDOS) runs into KYC check + +@item + fail KYC check (if possible for the given setup) + +@item + pass KYC check (tests that 2nd attempt is possible) + +@item + withdraw process of very large amount (50 KUDOS) runs into AML check + +@item + visit exchange SPA, create AML officer key + +@item + register AML officer key with offline tool (if possible) + +@item + allow withdraw process blocked on AML to proceed (if possible) +@end itemize + +@node Exchange AML SPA,Blog demo,Basics,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual exchange-aml-spa}@anchor{1b} +@subsection Exchange AML SPA + + + +@itemize - + +@item + enter non-trivial form, change status to frozen + +@item + check account status in history is now frozen and shows in that category + +@item + enter another form, change status to normal, increase AML threshold + +@item + view forms in history, view previously submitted form + +@item + check account status in history is now normal and shows in that category + +@item + log out + +@item + check log in succeeds with correct password + +@item + check log in fails from different browser with same password +@end itemize + +@node Blog demo,Donation demo,Exchange AML SPA,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual blog-demo}@anchor{1c} +@subsection Blog demo + + + +@itemize - + +@item + Visit @indicateurl{https://shop.demo.taler.net/} + +@item + blog page article list renders + +@item + payment for blog article + +@item + Verify that the balance in the wallet was updated correctly. + +@item + Go back to @indicateurl{https://shop.demo.taler.net/} and click on the same article +link. Verify that the article is shown and `no' repeated payment is +requested. + +@item + Open the fulfillment page from the previous step in an anonymous browsing session +(without the wallet installed) and verify that it requests a payment again. + +@item + Delete cookies on @indicateurl{https://shop.demo.taler.net/} and click on the same article again. +Verify that the wallet detects that the article has already purchased and successfully +redirects to the article without spending more money. + +@item + payment for other blog article + +@item + refund of 2nd blog article (button at the end) + +@item + wallet transaction history rendering + +@item + delete refund history entry; check original purchase entry was also deleted + +@item + payment for other blog article + +@item + refund of 3rd blog article (button at the end) + +@item + wallet transaction history rendering + +@item + delete 3rd block purchase history entry; check refund entry was also deleted +@end itemize + +@node Donation demo,Merchant SPA,Blog demo,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual donation-demo}@anchor{1d} +@subsection Donation demo + + + +@itemize - + +@item + Reset wallet + +@item + Withdraw age-restricted coins (< 14) + +@item + Try to make a donation on @indicateurl{https://donations.demo.taler.net/}, fail due to age-restriction + +@item + Withdraw age-restricted coins (>= 14) + +@item + Make a donation on @indicateurl{https://donations.demo.taler.net/} + +@item + Make another donation with the same parameters and verify +that the payment is requested again, instead of showing the previous +fulfillment page. +@end itemize + +@node Merchant SPA,P2P payments,Donation demo,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual merchant-spa}@anchor{1e} +@subsection Merchant SPA + + + +@itemize - + +@item + test SPA loads + +@item + try to login with wrong password + +@item + try to login with correct password + +@item + create instance, check default is set to cover (STEFAN) fees + +@item + modify instance + +@item + add bank account + +@item + edit bank account + +@item + remove bank account + +@item + check order creation fails without bank account + +@item + add bank account again + +@item + add product with 1 in stock and preview image + +@item + add “advanced” order with inventory product and a 2 minute wire delay + +@item + claim order, check available stock goes down in inventory + +@item + create 2nd order, check this fails due to missing inventory + +@item + pay for 1st order with wallet + +@item + check transaction history for preview image + +@item + trigger partial refund + +@item + accept refund with wallet + +@item + create template with fixed summary, default editable price + +@item + scan template QR code, edit price and pay + +@item + add TOTP device (using some TOTP app to share secret with) + +@item + edit template to add TOTP device, set price to fixed, summary to be entered + +@item + scan template QR code, edit summary and pay + +@item + check displayed TOTP code matches TOTP app + +@item + do manual wire transfer in bank to establish reserve funding + +@item + check that partially refunded order is marked as awaiting wire transfer + +@item + check bank wired funds to merchant (if needed, wait) + +@item + add bank wire transfer manually to backend + +@item + change settings for merchant to not pay for (STEFAN) fees + +@item + create and pay for another order with 1 minute wire transfer delay + +@item + edit bank account details, adding revenue facade with credentials + +@item + wait and check if wire transfer is automatically imported + +@item + check that orders are marked as completed +@end itemize + +@node P2P payments,Shutdown,Merchant SPA,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual p2p-payments}@anchor{1f} +@subsection P2P payments + + + +@itemize - + +@item + generating push payment (to self is OK) + +@item + accepting push payment (from self is OK) + +@item + generating pull payment (to self is OK) + +@item + accepting pull payment (from self is OK) + +@item + sending money back from wallet to bank account + +@item + wallet transaction history rendering + +@item + delete history entry +@end itemize + +@node Shutdown,,P2P payments,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual shutdown}@anchor{20} +@subsection Shutdown + + + +@itemize - + +@item + create two full wallets, fill one only via (a large) P2P transfer + +@item + revoke highest-value denomination + +@item + spend money in a wallet such that the balance falls below highest denomination value + +@item + revoke all remaining denominations + +@item + fail to spend any more money + +@item + if wallet was filled via p2p payments, wallet asks for target deposit account (exchange going out of business) + +@item + enter bank account (if possible) + +@item + wallet balance goes to zero + +@item + specified bank account receives remaining balance +@end itemize + +@node Environments and Builders on taler net,QA Plans,Demo Upgrade Procedure,Top +@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{21} @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{18} +@node Buildbot implementation,Test builder,,Environments and Builders on taler net +@anchor{taler-developer-manual buildbot-implementation}@anchor{22} @section Buildbot implementation @@ -778,14 +1158,58 @@ Create a worker from a shell account with this command: @code{buildbot-worker cr Then make sure there is a WORKER defined in master.cfg like: @code{worker.Worker("<username>", "<password>")} -@node Documentation Builder,Website Builder,Buildbot implementation,Environments and Builders on taler net -@anchor{taler-developer-manual documentation-builder}@anchor{19} +@node Test builder,Wallet builder,Buildbot implementation,Environments and Builders on taler net +@anchor{taler-developer-manual test-builder}@anchor{23} +@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{24} +@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{25} @section Documentation Builder All the Taler documentation is built by the user @code{docbuilder} that runs a Buildbot worker. The following commands set the @code{docbuilder} up, -starting with a empty home directory. +starting with an empty home directory. @example # Log-in as the 'docbuilder' user. @@ -801,13 +1225,13 @@ $ buildbot-worker start worker/ @end example @node Website Builder,Code coverage,Documentation Builder,Environments and Builders on taler net -@anchor{taler-developer-manual website-builder}@anchor{1a} +@anchor{taler-developer-manual website-builder}@anchor{26} @section Website Builder Taler Websites, @code{www.taler.net} and @code{stage.taler.net}, are built by the user @code{taler-websites} by the means of a Buildbot worker. The following -commands set the @code{taler-websites} up, starting with a empty home directory. +commands set the @code{taler-websites} up, starting with an empty home directory. @example # Log-in as the 'taler-websites' user. @@ -822,8 +1246,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{1b} +@node Code coverage,Producing auditor reports,Website Builder,Environments and Builders on taler net +@anchor{taler-developer-manual code-coverage}@anchor{27} @section Code coverage @@ -845,51 +1269,8 @@ $ buildbot-worker start worker/ The results are then published at @code{https://lcov.taler.net/}. -@node Service Checker,Tipping reserve top-up,Code coverage,Environments and Builders on taler net -@anchor{taler-developer-manual service-checker}@anchor{1c} -@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{1d} -@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{1e} +@node Producing auditor reports,Database schema versioning,Code coverage,Environments and Builders on taler net +@anchor{taler-developer-manual producing-auditor-reports}@anchor{28} @section Producing auditor reports @@ -901,7 +1282,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: @@ -910,12 +1291,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{1f} +@anchor{taler-developer-manual database-schema-versioning}@anchor{29}@anchor{taler-developer-manual databaseversioning}@anchor{5} @section Database schema versioning -The Postgres databases of the exchange and the auditor are versioned. -See the 0000.sql file in the respective directory for documentation. +The PostgreSQL databases of the exchange and the auditor are versioned. +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 @@ -923,15 +1304,534 @@ 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 QA Plans,Releases,Environments and Builders on taler net,Top +@anchor{taler-developer-manual qa-plans}@anchor{2a} +@chapter QA Plans + + +@menu +* Taler 0.9.4 QA Plan: Taler 0 9 4 QA Plan. + +@end menu + +@node Taler 0 9 4 QA Plan,,,QA Plans +@anchor{taler-developer-manual taler-0-9-4-qa-plan}@anchor{2b} +@section Taler 0.9.4 QA Plan + + +@menu +* Wallet Platforms:: +* Running Deployments:: +* Wallet Flows:: +* libeufin-bank Flows:: +* Merchant Backend SPA Flows:: +* Regio Deployment:: +* Android Merchant PoS:: +* Android Cashier App:: +* CI:: +* Debian Repository:: +* GNU Release:: + +@end menu + +@node Wallet Platforms,Running Deployments,,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-platforms}@anchor{2c} +@subsection Wallet Platforms + + +Platforms listed here are the officially supported platforms for this release. + + +@itemize * + +@item +Overview / Installation Page + + +@itemize * + +@item +@indicateurl{https://taler.net/en/wallet.html} +@end itemize + +@item +Android + + +@itemize * + +@item +Google Play: @indicateurl{https://play.google.com/store/apps/details?id=net.taler.wallet} + +@item +F-Droid: @indicateurl{https://f-droid.org/en/packages/net.taler.wallet.fdroid/} + +@item +APK Download: TBD +@end itemize + +@item +Browser + + +@itemize * + +@item +Chrome: @indicateurl{https://chromewebstore.google.com/detail/gnu-taler-wallet/millncjiddlpgdmkklmhfadpacifaonc} + +@item +Firefox: @indicateurl{https://addons.mozilla.org/en-US/firefox/addon/taler-wallet/} +@end itemize + +@item +iOS +@end itemize + +@node Running Deployments,Wallet Flows,Wallet Platforms,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual running-deployments}@anchor{2d} +@subsection Running Deployments + + +These deployments are maintained by us and should work for the release: + + +@itemize * + +@item +Sandcastle-based: + -@node Releases,Continuous integration,Environments and Builders on taler net,Top -@anchor{taler-developer-manual releases}@anchor{20} +@itemize * + +@item +demo.taler.net + +@item +test.taler.net +@end itemize + +@item +Regio-based: + + +@itemize * + +@item +regio-taler.fdold.eu +@end itemize +@end itemize + +@node Wallet Flows,libeufin-bank Flows,Running Deployments,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-flows}@anchor{2e} +@subsection Wallet Flows + + + +@itemize * + +@item +Bank-integrated withdrawal + + +@itemize * + +@item +webext: “Continue with Mobile Wallet” flow +@end itemize + +@item +Manual withdrawal + + +@itemize * + +@item +@code{taler://withdraw-exchange} flow + +@item +Currency conversion withdrawal +@end itemize + +@item +Peer push payments (“Send Money”) + +@item +Peer pull payments (“Receive Money”) + +@item +Deposit into bank account + + +@itemize * + +@item +Check that deposit arrived +@end itemize + +@item +Payment at merchant + + +@itemize * + +@item +on blog merchant + +@item +on survey + +@item +directly initiated via merchant SPA + +@item +webext: “Pay with Mobile Wallet” flow +@end itemize + +@item +Pay templates + + +@itemize * + +@item +Payment TOTP codes +@end itemize + +@item +Exchange management + + +@itemize * + +@item +Reloading exchange keys + +@item +Deleting an exchange +@end itemize + +@item +Offline handling + + +@itemize * + +@item +Check error messages for other flows when internet connectivity +is bad or device is completely offline. +@end itemize +@end itemize + +@node libeufin-bank Flows,Merchant Backend SPA Flows,Wallet Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual libeufin-bank-flows}@anchor{2f} +@subsection libeufin-bank Flows + + + +@itemize * + +@item +Admin functionality + + +@itemize * + +@item +Login + +@item +Credential change + +@item +Conversion settings + +@item +Bank account creation + +@item +Test transfers +@end itemize + +@item +Normal account functionality + + +@itemize * + +@item +Transfers + + +@itemize * + +@item +Transfer to the exchange should bounce +@end itemize + +@item +Withdrawals + +@item +(conversion-only): Test cash-in + +@item +(conversion-only): Test cash-out + + +@itemize * + +@item +Lower cash-out limit enforced +@end itemize + +@item +2FA for withdrawals, cash-out +@end itemize +@end itemize + +@node Merchant Backend SPA Flows,Regio Deployment,libeufin-bank Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual merchant-backend-spa-flows}@anchor{30} +@subsection Merchant Backend SPA Flows + + + +@itemize * + +@item +Instance creation + +@item +Simple bank account setup + +@item +Order creation + + +@itemize * + +@item +Pay order (with short wire transfer deadline) + +@item +Check that money from order arrive at the bank with the right subject +@end itemize + +@item +Extended bank account setup + + +@itemize * + +@item +Add Taler Bank Revenue API + +@item +Check bank transfer list (for wire transfer of previously paid+wired order) + +@item +Check order payment status goes to “final” automatically +@end itemize + +@item +TOTP Device Management + + +@itemize * + +@item +Add device + +@item +Edit device (set new secret, export new secret as QR code) + +@item +Delete device +@end itemize + +@item +Templates + + +@itemize * + +@item +Add template + +@item +Edit template + +@item +Add TOTP device to template + +@item +Edit TOTP device associated with template + +@item +Pay template + +@item +Check TOTP code matches + +@item +Remove TOTP device from template + +@item +Delete template +@end itemize +@end itemize + +@node Regio Deployment,Android Merchant PoS,Merchant Backend SPA Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual regio-deployment}@anchor{31} +@subsection Regio Deployment + + + +@itemize * + +@item +Deployment Automation (deployment.git/regional-currency) + + +@itemize * + +@item +Test with Debian bookworm + +@item +Test with Ubuntu mantic + +@item +Check logs for errors + +@item +Test with telesign (SMS) + +@item +Set up EBICS integration + +@item +Check that ToS is configured +@end itemize + +@item +Deployment Functionality + + +@itemize * + +@item +All flows of the wallet should work (see @code{Wallet Flows} above) + +@item +All flows of libeufin-bank should work (see @code{libeufin-bank Flows} above) + +@item +Merchant backend should work (see @code{Merchant Backend SPA Flows} above) + +@item +Check logs +@end itemize +@end itemize + +@node Android Merchant PoS,Android Cashier App,Regio Deployment,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual android-merchant-pos}@anchor{32} +@subsection Android Merchant PoS + + + +@itemize * + +@item +Test against demo.taler.net +@end itemize + +@node Android Cashier App,CI,Android Merchant PoS,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual android-cashier-app}@anchor{33} +@subsection Android Cashier App + + + +@itemize * + +@item +Test against demo.taler.net +@end itemize + +@node CI,Debian Repository,Android Cashier App,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual ci}@anchor{34} +@subsection CI + + + +@itemize * + +@item +@indicateurl{https://buildbot.taler.net/#/waterfall} + +@item +CI should pass +@end itemize + +@node Debian Repository,GNU Release,CI,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual debian-repository}@anchor{35} +@subsection Debian Repository + + + +@itemize * + +@item +Debian + + +@itemize * + +@item +repo at @indicateurl{https://deb.taler.net/apt/debian/} + +@item +supported codename(s): bookworm +@end itemize + +@item +Ubuntu: + + +@itemize * + +@item +repo at @indicateurl{https://deb.taler.net/apt/ubuntu/} + +@item +supported codename(s): mantic +@end itemize +@end itemize + +@node GNU Release,,Debian Repository,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual gnu-release}@anchor{36} +@subsection GNU Release + + + +@itemize * + +@item +Release announcement + +@item +FTP upload +@end itemize + +@node Releases,Continuous integration,QA Plans,Top +@anchor{taler-developer-manual releases}@anchor{37} @chapter Releases @menu -* Release Process and Checklists:: +* GNU Taler Release Checklist:: +* Release Process:: * Tagging:: * Database for tests:: * Exchange@comma{} merchant: Exchange merchant. @@ -941,12 +1841,387 @@ outside of this versioning. @end menu -@node Release Process and Checklists,Tagging,,Releases -@anchor{taler-developer-manual release-process-and-checklists}@anchor{21} -@section Release Process and Checklists +@node GNU Taler Release Checklist,Release Process,,Releases +@anchor{taler-developer-manual gnu-taler-release-checklist}@anchor{38} +@section GNU Taler Release Checklist + + +For exchange: + + +@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 + update man pages / info page documentation (prebuilt branch) + +@item + make dist for release + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ + +@item + run 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 merchant (C backend): + + +@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 + update SPA (prebuilt branch) + +@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 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 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 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 demo upgrade checklist + +@item + tag repo. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For libeufin: + + +@itemize - + +@item + update SPA of bank + +@item + build libeufin + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + make dist for release. + +@item + verify dist builds from source + +@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 Python merchant frontend: + + +@itemize - + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + change ‘demo.taler.net’ deployment to use new tag. +@end itemize + +Wallet-core: + + +@itemize - + +@item + build wallet + +@item + run integration test + +@item + make dist for release. + +@item + verify dist builds from source + +@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 + +Android-Wallet: + + +@itemize - + +@item + build wallet + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + upload new wallet release to app store +@end itemize + +Webextension-Wallet: -Please use the @ref{1,,release checklist} +@itemize - + +@item + build wallet + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + upload new wallet release to app store +@end itemize + +Release announcement: + + +@itemize - + +@item + Update bug tracker (mark release, resolved -> closed) + +@item + Send announcement to @email{taler@@gnu.org} + +@item + Send announcement to @email{info-gnu@@gnu.org} (major releases only) + +@item + Send announcement to @email{coordinator@@translationproject.org} +@end itemize + +@node Release Process,Tagging,GNU Taler Release Checklist,Releases +@anchor{taler-developer-manual release-process}@anchor{39} +@section Release Process + This document describes the process for releasing a new version of the various Taler components to the official GNU mirrors. @@ -963,24 +2238,27 @@ taler-exchange (exchange.git) taler-merchant (merchant.git) @item -talerdonations (donations.git) +sync (sync.git) @item -talerblog (blog.git) +taler-mdb (taler-mdb.git) @item -taler-bank (bank.git) +libeufin (libeufin.git) @item -taler-wallet-webex (wallet-webex.git) +challenger (challenger.git) + +@item +wallet-core (wallet-core.git) @end itemize -@node Tagging,Database for tests,Release Process and Checklists,Releases -@anchor{taler-developer-manual tagging}@anchor{22} +@node Tagging,Database for tests,Release Process,Releases +@anchor{taler-developer-manual tagging}@anchor{3a} @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" @@ -988,25 +2266,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{23} +@anchor{taler-developer-manual database-for-tests}@anchor{3b} @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{24} +@anchor{taler-developer-manual exchange-merchant}@anchor{3c} @section Exchange, merchant @@ -1065,12 +2342,12 @@ $ make install check @end example @node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases -@anchor{taler-developer-manual wallet-webextension}@anchor{25} +@anchor{taler-developer-manual wallet-webextension}@anchor{3d} @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 @@ -1079,7 +2356,7 @@ $ make dist @end example @node Upload to GNU mirrors,Creating Debian packages,Wallet WebExtension,Releases -@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{26} +@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{3e} @section Upload to GNU mirrors @@ -1091,12 +2368,13 @@ Directive file: version: 1.2 directory: taler filename: taler-exchange-0.1.0.tar.gz +symlink: taler-exchange-0.1.0.tar.gz taler-exchange-latest.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{27} +@anchor{taler-developer-manual creating-debian-packages}@anchor{3f} @section Creating Debian packages @@ -1113,25 +2391,29 @@ $ 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. Next, the @code{*.deb} files should be copied to gv.taler.net, say to -@code{/root/incoming}. Then, run +@code{/home/aptbuilder/incoming}. Then, run @example -# cd /var/www/repos/apt/debian/ -# reprepro includedeb sid /root/incoming/*.deb +# cd /home/aptbuilder/apt +# reprepro includedeb bullseye ~/incoming/*.deb @end example -to import all Debian files from @code{/root/incoming/} into the @code{sid} +to import all Debian files from @code{~/incoming/} into the @code{bullseye} distribution. If Debian packages were build against other distributions, reprepro may need to be first configured for those and the import command updated accordingly. -Finally, make sure to clean up @code{/root/incoming/} (by deleting the +Finally, make sure to clean up @code{~/incoming/} (by deleting the now imported @code{*.deb} files). @node Continuous integration,Internationalization,Releases,Top -@anchor{taler-developer-manual continuous-integration}@anchor{28} +@anchor{taler-developer-manual continuous-integration}@anchor{40} @chapter Continuous integration @@ -1148,8 +2430,8 @@ for that. There is also the possibility to trigger builds manually, but this is only reserved to “admin” users. -@node Internationalization,Android Apps,Continuous integration,Top -@anchor{taler-developer-manual internationalization}@anchor{29} +@node Internationalization,iOS Apps,Continuous integration,Top +@anchor{taler-developer-manual internationalization}@anchor{41} @chapter Internationalization @@ -1170,14 +2452,14 @@ At this time, this system is still very new for Taler.net and this documentation @end menu @node Who can Register,About Privilege Levels,,Internationalization -@anchor{taler-developer-manual who-can-register}@anchor{2a} +@anchor{taler-developer-manual who-can-register}@anchor{42} @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{2b} +@anchor{taler-developer-manual about-privilege-levels}@anchor{43} @section About Privilege Levels @@ -1187,84 +2469,84 @@ 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{2c} +@anchor{taler-developer-manual upgrading-privileges}@anchor{44} @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{2d} +@anchor{taler-developer-manual how-to-create-a-project}@anchor{45} @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{2e} +@anchor{taler-developer-manual how-to-create-a-component}@anchor{46} @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{2f} +@anchor{taler-developer-manual how-to-create-a-translation}@anchor{47} @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. @@ -1273,18 +2555,18 @@ Under @emph{https://weblate.taler.net/create/component/vcs/}: You may also wish to refer to @indicateurl{https://docs.weblate.org/} . @node Translation Standards and Practices,GPG Signing of Translations,How to Create a Translation,Internationalization -@anchor{taler-developer-manual translation-standards-and-practices}@anchor{30} +@anchor{taler-developer-manual translation-standards-and-practices}@anchor{48} @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{31} +@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{49} @section GPG Signing of Translations @@ -1292,8 +2574,72 @@ weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F26 This means that contributions made through weblate will not be signed with the individual contributor’s key when they are checked into the Git repository, but with the weblate key. -@node Android Apps,Code Coverage,Internationalization,Top -@anchor{taler-developer-manual android-apps}@anchor{32} +@node iOS Apps,Android Apps,Internationalization,Top +@anchor{taler-developer-manual ios-apps}@anchor{4a} +@chapter iOS Apps + + +@menu +* Building Taler Wallet for iOS from source:: + +@end menu + +@node Building Taler Wallet for iOS from source,,,iOS Apps +@anchor{taler-developer-manual build-ios-from-source}@anchor{4b}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{4c} +@section Building Taler Wallet for iOS from source + + +The GNU Taler Wallet iOS 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{4d} +@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{4e} +@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}. + +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}. + +Build wallet-core first: + +@example +$ cd wallet-core +$ make embedded +$ open packages/taler-wallet-embedded/dist +@end example + +then drag or move its product “taler-wallet-core-qjs.mjs” +into your quickjs-tart folder right at the top level. + +Open Taler.xcworkspace, and set scheme / target to Taler_Wallet. Build&run… + +Don’t open QuickJS-rt.xcodeproj or TalerWallet.xcodeproj and build anything +there - all needed libraries and frameworks will be built automatically from +Taler.xcworkspace. + +@node Android Apps,Code Coverage,iOS Apps,Top +@anchor{taler-developer-manual android-apps}@anchor{4f} @chapter Android Apps @@ -1306,7 +2652,7 @@ This means that contributions made through weblate will not be signed with the i @end menu @node Android App Nightly Builds,Building apps from source,,Android Apps -@anchor{taler-developer-manual android-app-nightly-builds}@anchor{33} +@anchor{taler-developer-manual android-app-nightly-builds}@anchor{50} @section Android App Nightly Builds @@ -1351,13 +2697,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{34}@anchor{taler-developer-manual building-apps-from-source}@anchor{35} +@anchor{taler-developer-manual build-apps-from-source}@anchor{51}@anchor{taler-developer-manual building-apps-from-source}@anchor{52} @section Building apps from source @@ -1443,7 +2789,7 @@ After the build finished successfully, you will find your APK in @code{merchant-terminal/build/outputs/apk/release/}. @node Update translations,Release process,Building apps from source,Android Apps -@anchor{taler-developer-manual update-translations}@anchor{36} +@anchor{taler-developer-manual update-translations}@anchor{53} @section Update translations @@ -1477,7 +2823,7 @@ Afterwards, build the entire project from source and test the UI to ensure that no erroneous translations (missing placeholders) are breaking things. @node Release process,,Update translations,Android Apps -@anchor{taler-developer-manual release-process}@anchor{37} +@anchor{taler-developer-manual id1}@anchor{54} @section Release process @@ -1508,7 +2854,7 @@ $ git tag -s $APP-$VERSION @end menu @node F-Droid,Google Play,,Release process -@anchor{taler-developer-manual id1}@anchor{38} +@anchor{taler-developer-manual id2}@anchor{55} @subsection F-Droid @@ -1532,7 +2878,7 @@ PoS: [metadata@footnote{https://gitlab.com/fdroid/fdroiddata/-/blob/master/metad @end itemize @node Google Play,,F-Droid,Release process -@anchor{taler-developer-manual google-play}@anchor{39} +@anchor{taler-developer-manual google-play}@anchor{56} @subsection Google Play @@ -1554,7 +2900,7 @@ All uploads are going to the beta track by default. These can be promoted to production later or immediately after upload if you feel daring. @node Code Coverage,Coding Conventions,Android Apps,Top -@anchor{taler-developer-manual id2}@anchor{3a}@anchor{taler-developer-manual id3}@anchor{3b} +@anchor{taler-developer-manual id3}@anchor{57}@anchor{taler-developer-manual id4}@anchor{58} @chapter Code Coverage @@ -1564,22 +2910,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{3c} +@anchor{taler-developer-manual coding-conventions}@anchor{59} @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{3d} +@anchor{taler-developer-manual components-written-in-c}@anchor{5a} @section Components written in C @@ -1599,7 +2947,7 @@ by the GNUnet style: @indicateurl{https://docs.gnunet.org/handbook/gnunet.html#C @end menu @node Naming conventions,,,Components written in C -@anchor{taler-developer-manual naming-conventions}@anchor{3e} +@anchor{taler-developer-manual naming-conventions}@anchor{5b} @subsection Naming conventions @@ -1760,7 +3108,7 @@ must be called “perf_module-under-test_case-description.c” @end itemize @node Shell Scripts,Kotlin,Components written in C,Coding Conventions -@anchor{taler-developer-manual shell-scripts}@anchor{3f} +@anchor{taler-developer-manual shell-scripts}@anchor{5c} @section Shell Scripts @@ -1787,15 +3135,15 @@ $ set -eu @end example @node Kotlin,Python,Shell Scripts,Coding Conventions -@anchor{taler-developer-manual kotlin}@anchor{40} +@anchor{taler-developer-manual kotlin}@anchor{5d} @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{41} +@node Python,Swift,Kotlin,Coding Conventions +@anchor{taler-developer-manual python}@anchor{5e} @section Python @@ -1807,14 +3155,14 @@ for the language. @end menu @node Supported Python Versions,Style,,Python -@anchor{taler-developer-manual supported-python-versions}@anchor{42} +@anchor{taler-developer-manual supported-python-versions}@anchor{5f} @subsection Supported Python Versions Python code should be written and build against version 3.7 of Python. @node Style,Python for Scripting,Supported Python Versions,Python -@anchor{taler-developer-manual style}@anchor{43} +@anchor{taler-developer-manual style}@anchor{60} @subsection Style @@ -1824,7 +3172,7 @@ A reusable yapf style file can be found in @code{build-common}, which is intended to be used as a git submodule. @node Python for Scripting,,Style,Python -@anchor{taler-developer-manual python-for-scripting}@anchor{44} +@anchor{taler-developer-manual python-for-scripting}@anchor{61} @subsection Python for Scripting @@ -1845,8 +3193,22 @@ are useful: over the older APIs. @end itemize +@node Swift,TypeScript,Python,Coding Conventions +@anchor{taler-developer-manual swift}@anchor{62} +@section Swift + + +Please follow best practices for the language. + +@node TypeScript,,Swift,Coding Conventions +@anchor{taler-developer-manual typescript}@anchor{63} +@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{45} +@anchor{taler-developer-manual testing-library}@anchor{64} @chapter Testing library @@ -1854,7 +3216,7 @@ This chapter is a VERY ABSTRACT description of how testing is implemented in Taler, and in NO WAY wants to substitute the reading of the actual source code by the user. -In Taler, a test case is a array of @code{struct TALER_TESTING_Command}, +In Taler, a test case is an array of @code{struct TALER_TESTING_Command}, informally referred to as @code{CMD}, that is iteratively executed by the testing interpreter. This latter is transparently initiated by the testing library. @@ -1872,12 +3234,12 @@ 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 -trait is a @code{struct TALER_TESTING_Trait}, and each CMD contains a array +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 to the test developer. @@ -1911,7 +3273,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. @@ -1919,7 +3281,7 @@ Please refer to the Twister codebase (under the @code{test} directory) in order to see how to configure it. @node User-Facing Terminology,Developer Glossary,Testing library,Top -@anchor{taler-developer-manual user-facing-terminology}@anchor{46} +@anchor{taler-developer-manual user-facing-terminology}@anchor{65} @chapter User-Facing Terminology @@ -1933,7 +3295,7 @@ used in the user interface and help materials. @end menu @node Terms to Avoid,Terms to Use,,User-Facing Terminology -@anchor{taler-developer-manual terms-to-avoid}@anchor{47} +@anchor{taler-developer-manual terms-to-avoid}@anchor{66} @section Terms to Avoid @@ -1945,27 +3307,34 @@ 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. @@ -1975,14 +3344,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 @@ -1993,7 +3362,7 @@ See Payment Replay. Too ambiguous in the wallet. -@strong{Use instead}: Purchase +`Use instead': Purchase @item Fulfillment URL @@ -2002,7 +3371,7 @@ with their payment. Can also be something like a donation receipt. @end table @node Terms to Use,,Terms to Avoid,User-Facing Terminology -@anchor{taler-developer-manual terms-to-use}@anchor{48} +@anchor{taler-developer-manual terms-to-use}@anchor{67} @section Terms to Use @@ -2054,7 +3423,7 @@ and payments. @end table @node Developer Glossary,Developer Tools,User-Facing Terminology,Top -@anchor{taler-developer-manual developer-glossary}@anchor{49} +@anchor{taler-developer-manual developer-glossary}@anchor{68} @chapter Developer Glossary @@ -2063,171 +3432,137 @@ use when talking to end users or even system administrators. @table @asis -@anchor{taler-developer-manual term-absolute-time}@anchor{4a} +@anchor{taler-developer-manual term-absolute-time}@anchor{69} @geindex absolute time @item absolute time -method of keeping time in @ref{4b,,GNUnet} where the time is represented +method of keeping time in @ref{6a,,GNUnet} where the time is represented as the number of microseconds since 1.1.1970 (UNIX epoch). Called -absolute time in contrast to @ref{4c,,relative time}. -@anchor{taler-developer-manual term-aggregate}@anchor{4d} +absolute time in contrast to @ref{6b,,relative time}. +@anchor{taler-developer-manual term-aggregate}@anchor{6c} @geindex aggregate @item aggregate -the @ref{4e,,exchange} combines multiple payments received by the -same @ref{4f,,merchant} into one larger @ref{50,,wire transfer} to -the respective merchant’s @ref{51,,bank} account -@anchor{taler-developer-manual term-auditor}@anchor{52} +the @ref{6d,,exchange} combines multiple payments received by the +same @ref{6e,,merchant} into one larger @ref{6f,,wire transfer} to +the respective merchant’s @ref{70,,bank} account +@anchor{taler-developer-manual term-auditor}@anchor{71} @geindex auditor @item auditor -trusted third party that verifies that the @ref{4e,,exchange} is operating correctly -@anchor{taler-developer-manual term-bank}@anchor{51} +trusted third party that verifies that the @ref{6d,,exchange} is operating correctly +@anchor{taler-developer-manual term-bank}@anchor{70} @geindex bank @item bank -traditional financial service provider who offers wire @ref{53,,transfers} between accounts -@anchor{taler-developer-manual term-buyer}@anchor{54} +traditional financial service provider who offers +@ref{6f,,wire transfers} between accounts +@anchor{taler-developer-manual term-buyer}@anchor{72} @geindex buyer @item buyer -individual in control of a Taler @ref{55,,wallet}, usually using it to -@ref{56,,spend} the @ref{57,,coins} on @ref{58,,contracts} (see also @ref{59,,customer}). -@anchor{taler-developer-manual term-close}@anchor{5a} +individual in control of a Taler @ref{73,,wallet}, usually using it to +@ref{74,,spend} the @ref{75,,coins} on @ref{76,,contracts} (see also @ref{77,,customer}). +@anchor{taler-developer-manual term-close}@anchor{78} @geindex close -@item close@anchor{taler-developer-manual term-closes}@anchor{5b} -@geindex closes - -@itemx closes@anchor{taler-developer-manual term-closed}@anchor{5c} -@geindex closed - -@itemx closed@anchor{taler-developer-manual term-closing}@anchor{5d} -@geindex closing +@item close -@itemx closing - -operation an @ref{4e,,exchange} performs on a @ref{5e,,reserve} that has not been -@ref{5f,,drained} by @ref{60,,withdraw} operations. When closing a reserve, the -exchange wires the remaining funds back to the customer, minus a @ref{61,,fee} +operation an @ref{6d,,exchange} performs on a @ref{79,,reserve} that has not been +@ref{7a,,emptied} by @ref{7b,,withdraw} operations. When closing a reserve, the +exchange wires the remaining funds back to the customer, minus a @ref{7c,,fee} for closing -@anchor{taler-developer-manual term-coin}@anchor{62} +@anchor{taler-developer-manual term-coin}@anchor{75} @geindex coin -@item coin@anchor{taler-developer-manual term-coins}@anchor{57} -@geindex coins - -@itemx coins - -coins are individual token representing a certain amount of value, also known as the @ref{63,,denomination} of the coin -@anchor{taler-developer-manual term-commitment}@anchor{64} -@geindex commitment - -@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{65} -@geindex refresh commitment +@item coin -@itemx refresh commitment - -data that the wallet commits to during the @ref{66,,melt} stage of the -@ref{67,,refresh} protocol where it -has to prove to the @ref{4e,,exchange} that it is deriving the @ref{68,,fresh} -coins as specified by the Taler protocol. The commitment is verified -probabilistically (see: @ref{69,,kappa}) during the @ref{6a,,reveal} stage. -@anchor{taler-developer-manual term-contract}@anchor{6b} +coins are individual token representing a certain amount of value, also known as the @ref{7d,,denomination} of the coin +@anchor{taler-developer-manual term-contract}@anchor{76} @geindex contract -@item contract@anchor{taler-developer-manual term-contracts}@anchor{58} -@geindex contracts - -@itemx contracts +@item contract -formal agreement between @ref{4f,,merchant} and @ref{59,,customer} specifying the -@ref{6c,,contract terms} and signed by the merchant and the @ref{57,,coins} of the +formal agreement between @ref{6e,,merchant} and @ref{77,,customer} specifying the +@ref{7e,,contract terms} and signed by the merchant and the @ref{75,,coins} of the customer -@anchor{taler-developer-manual term-contract-terms}@anchor{6c} +@anchor{taler-developer-manual term-contract-terms}@anchor{7e} @geindex contract terms @item contract terms the individual clauses specifying what the buyer is purchasing from the -@ref{4f,,merchant} -@anchor{taler-developer-manual term-customer}@anchor{59} +@ref{6e,,merchant} +@anchor{taler-developer-manual term-customer}@anchor{77} @geindex customer @item customer individual that directs the buyer (perhaps the same individual) to make a purchase -@anchor{taler-developer-manual term-denomination}@anchor{63} +@anchor{taler-developer-manual term-denomination}@anchor{7d} @geindex denomination @item denomination -unit of currency, specifies both the currency and the face value of a @ref{62,,coin}, +unit of currency, specifies both the currency and the face value of a @ref{75,,coin}, as well as associated fees and validity periods -@anchor{taler-developer-manual term-denomination-key}@anchor{6d} +@anchor{taler-developer-manual term-denomination-key}@anchor{7f} @geindex denomination key @item denomination key -(RSA) key used by the exchange to certify that a given @ref{62,,coin} is valid and of a -particular @ref{63,,denomination} -@anchor{taler-developer-manual term-deposit}@anchor{6e} +(RSA) key used by the exchange to certify that a given @ref{75,,coin} is valid and of a +particular @ref{7d,,denomination} +@anchor{taler-developer-manual term-deposit}@anchor{80} @geindex deposit -@item deposit@anchor{taler-developer-manual term-deposits}@anchor{6f} -@geindex deposits - -@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{70} -@geindex depositing - -@itemx depositing +@item deposit operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using an -@ref{4d,,aggregate} @ref{50,,wire transfer} -@anchor{taler-developer-manual term-dirty}@anchor{71} +@ref{6c,,aggregate} @ref{6f,,wire transfer} +@anchor{taler-developer-manual term-dirty}@anchor{81} @geindex dirty -@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{72} -@geindex dirty coin +@item dirty -@itemx dirty coin - -a coin is dirty if its public key may be known to an entity other than +a @ref{75,,coin} is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin’s owner if the coin is not refreshed -@anchor{taler-developer-manual term-drain}@anchor{73} +@anchor{taler-developer-manual term-drain}@anchor{82} @geindex drain -@item drain@anchor{taler-developer-manual term-drained}@anchor{5f} -@geindex drained +@item drain + +process by which an exchange operator takes the profits +(from @ref{7c,,fees}) out of the escrow account and moves them into +their regular business account +@anchor{taler-developer-manual term-empty}@anchor{7a} +@geindex empty -@itemx drained +@item empty -a @ref{5e,,reserve} is being drained when a @ref{55,,wallet} is using the -reserve’s private key to @ref{60,,withdraw} coins from it. This reduces +a @ref{79,,reserve} is being emptied when a @ref{73,,wallet} is using the +reserve’s private key to @ref{7b,,withdraw} coins from it. This reduces the balance of the reserve. Once the balance reaches zero, we say that -the reserve has been (fully) drained. Reserves that are not drained -(which is the normal process) are @ref{5c,,closed} by the exchange. -@anchor{taler-developer-manual term-exchange}@anchor{4e} +the reserve has been (fully) emptied. Reserves that are not emptied +(which is the normal process) are @ref{78,,closed} by the exchange. +@anchor{taler-developer-manual term-exchange}@anchor{6d} @geindex exchange @item exchange Taler’s payment service operator. Issues electronic coins during withdrawal and redeems them when they are deposited by merchants -@anchor{taler-developer-manual term-expired}@anchor{74} +@anchor{taler-developer-manual term-expired}@anchor{83} @geindex expired -@item expired@anchor{taler-developer-manual term-expiration}@anchor{75} -@geindex expiration - -@itemx expiration +@item expired Various operations come with time limits. In particular, denomination keys come with strict time limits for the various operations involving the @@ -2238,385 +3573,346 @@ expiration, which specifies how long the exchange keeps records beyond the deposit expiration time. This latter expiration matters for legal disputes in courts and also creates an upper limit for refreshing operations on special zombie coin -@anchor{taler-developer-manual term-fakebank}@anchor{76} +@anchor{taler-developer-manual term-fakebank}@anchor{84} @geindex fakebank @item fakebank -implementation of the @ref{51,,bank} API in memory to be used only for test +implementation of the @ref{70,,bank} API in memory to be used only for test cases. -@anchor{taler-developer-manual term-fee}@anchor{61} +@anchor{taler-developer-manual term-fee}@anchor{7c} @geindex fee @item fee -an @ref{4e,,exchange} charges various fees for its service. The different +an @ref{6d,,exchange} charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for -@ref{77,,withdrawing}, @ref{70,,depositing}, @ref{78,,melting}, and -@ref{79,,refunding}. Furthermore, there are fees per wire transfer -for @ref{5d,,closing} a @ref{5e,,reserve}: and for -@ref{4d,,aggregate} @ref{7a,,wire transfers} to the @ref{4f,,merchant}. -@anchor{taler-developer-manual term-fresh}@anchor{68} +@ref{7b,,withdrawing}, @ref{80,,depositing}, @ref{85,,melting}, and +@ref{86,,refunding}. Furthermore, there are fees per wire transfer +when a @ref{79,,reserve} is @ref{78,,closed} +and for @ref{6c,,aggregate} @ref{6f,,wire transfers} +to the @ref{6e,,merchant}. +@anchor{taler-developer-manual term-fresh}@anchor{87} @geindex fresh -@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{7b} -@geindex fresh coin +@item fresh -@itemx fresh coin - -a coin is fresh if its public key is only known to the customer -@anchor{taler-developer-manual term-GNUnet}@anchor{4b} +a @ref{75,,coin} is fresh if its public key is only known to the customer +@anchor{taler-developer-manual term-GNUnet}@anchor{6a} @geindex GNUnet @item GNUnet Codebase of various libraries for a better Internet, some of which GNU Taler depends upon. -@anchor{taler-developer-manual term-json}@anchor{7c} -@geindex json - -@item json@anchor{taler-developer-manual term-JSON}@anchor{7d} +@anchor{taler-developer-manual term-JSON}@anchor{88} @geindex JSON -@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{7e} -@geindex JavaScript Object Notation - -@itemx JavaScript Object Notation +@item JSON +JavaScript Object Notation (JSON) is a serialization format derived from the JavaScript language which is commonly used in the Taler protocol as the payload of HTTP requests and responses. -@anchor{taler-developer-manual term-kappa}@anchor{69} +@anchor{taler-developer-manual term-kappa}@anchor{89} @geindex kappa @item kappa -security parameter used in the @ref{67,,refresh} protocol. Defined to be 3. +security parameter used in the @ref{8a,,refresh} protocol. Defined to be 3. The probability of successfully evading the income transparency with the refresh protocol is 1:kappa. -@anchor{taler-developer-manual term-LibEuFin}@anchor{7f} -@geindex LibEuFin +@anchor{taler-developer-manual term-libeufin}@anchor{8b} +@geindex libeufin -@item LibEuFin +@item libeufin -FIXME: explain -@anchor{taler-developer-manual term-link}@anchor{80} +Kotlin component that implements a regional currency bank and an +adapter to communicate via EBICS with European core banking systems. +@anchor{taler-developer-manual term-link}@anchor{8c} @geindex link -@item link@anchor{taler-developer-manual term-linking}@anchor{81} -@geindex linking - -@itemx linking +@item link -specific step in the @ref{67,,refresh} protocol that an exchange must offer -to prevent abuse of the @ref{67,,refresh} mechanism. The link step is +specific step in the @ref{8a,,refresh} protocol that an exchange must offer +to prevent abuse of the @ref{8a,,refresh} mechanism. The link step is not needed in normal operation, it just must be offered. -@anchor{taler-developer-manual term-master-key}@anchor{82} +@anchor{taler-developer-manual term-master-key}@anchor{8d} @geindex master key @item master key offline key used by the exchange to certify denomination keys and message signing keys -@anchor{taler-developer-manual term-melt}@anchor{66} +@anchor{taler-developer-manual term-melt}@anchor{85} @geindex melt -@item melt@anchor{taler-developer-manual term-melted}@anchor{83} -@geindex melted - -@itemx melted@anchor{taler-developer-manual term-melting}@anchor{78} -@geindex melting +@item melt -@itemx melting - -step of the @ref{67,,refresh} protocol where a @ref{72,,dirty coin} -is invalidated to be reborn @ref{68,,fresh} in a subsequent -@ref{6a,,reveal} step. -@anchor{taler-developer-manual term-merchant}@anchor{4f} +step of the @ref{8a,,refresh} protocol where a @ref{81,,dirty} @ref{75,,coin} +is invalidated to be reborn @ref{87,,fresh} in a subsequent +@ref{8e,,reveal} step. +@anchor{taler-developer-manual term-merchant}@anchor{6e} @geindex merchant @item merchant party receiving payments (usually in return for goods or services) -@anchor{taler-developer-manual term-message-signing-key}@anchor{84} +@anchor{taler-developer-manual term-message-signing-key}@anchor{8f} @geindex message signing key @item message signing key key used by the exchange to sign online messages, other than coins -@anchor{taler-developer-manual term-order}@anchor{85} +@anchor{taler-developer-manual term-order}@anchor{90} @geindex order @item order -FIXME: to be written! -@anchor{taler-developer-manual term-owner}@anchor{86} +offer made by the merchant to a wallet; pre-cursor to +a contract where the wallet is not yet fixed. Turns +into a @ref{76,,contract} when a wallet claims the order. +@anchor{taler-developer-manual term-owner}@anchor{91} @geindex owner @item owner a coin is owned by the entity that knows the private key of the coin -@anchor{taler-developer-manual term-planchet}@anchor{87} +@anchor{taler-developer-manual term-planchet}@anchor{92} @geindex planchet @item planchet -precursor data for a @ref{62,,coin}. A planchet includes the coin’s internal +precursor data for a @ref{75,,coin}. A planchet includes the coin’s internal secrets (coin private key, blinding factor), but lacks the RSA signature -of the @ref{4e,,exchange}. When @ref{77,,withdrawing}, a @ref{55,,wallet} +of the @ref{6d,,exchange}. When @ref{7b,,withdrawing}, a @ref{73,,wallet} creates and persists a planchet before asking the exchange to sign it to get the coin. -@anchor{taler-developer-manual term-privacy-policy}@anchor{88} +@anchor{taler-developer-manual term-privacy-policy}@anchor{93} @geindex privacy policy @item privacy policy Statement of an operator how they will protect the privacy of users. -@anchor{taler-developer-manual term-proof}@anchor{89} +@anchor{taler-developer-manual term-proof}@anchor{94} @geindex proof @item proof Message that cryptographically demonstrates that a particular claim is correct. -@anchor{taler-developer-manual term-proposal}@anchor{8a} +@anchor{taler-developer-manual term-proposal}@anchor{95} @geindex proposal @item proposal -a list of @ref{6c,,contract terms} that has been completed and signed by the +a list of @ref{7e,,contract terms} that has been completed and signed by the merchant backend. -@anchor{taler-developer-manual term-purchase}@anchor{8b} +@anchor{taler-developer-manual term-purchase}@anchor{96} @geindex purchase @item purchase -Refers to the overall process of negotiating a @ref{6b,,contract} and then -making a payment with @ref{57,,coins} to a @ref{4f,,merchant}. -@anchor{taler-developer-manual term-recoup}@anchor{8c} +Refers to the overall process of negotiating a @ref{76,,contract} and then +making a payment with @ref{75,,coins} to a @ref{6e,,merchant}. +@anchor{taler-developer-manual term-recoup}@anchor{97} @geindex recoup @item recoup Operation by which an exchange returns the value of coins affected -by a @ref{8d,,revocation} to their @ref{86,,owner}, either by allowing the owner to -withdraw new coins or wiring funds back to the bank account of the @ref{86,,owner}. -@anchor{taler-developer-manual term-refresh}@anchor{67} +by a @ref{98,,revocation} to their @ref{91,,owner}, either by allowing the owner to +withdraw new coins or wiring funds back to the bank account of the @ref{91,,owner}. +@anchor{taler-developer-manual term-refresh}@anchor{8a} @geindex refresh -@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{8e} -@geindex refreshing +@item refresh + +operation by which a @ref{81,,dirty} @ref{75,,coin} is converted into one or more +@ref{87,,fresh} coins. Involves @ref{85,,melting} the @ref{81,,dirty} coins and +then @ref{8e,,revealing} so-called @ref{99,,transfer keys}. +@anchor{taler-developer-manual term-refresh-commitment}@anchor{9a} +@geindex refresh commitment -@itemx refreshing +@item refresh commitment -operation by which a @ref{72,,dirty coin} is converted into one or more -@ref{68,,fresh} coins. Involves @ref{78,,melting} the @ref{72,,dirty coin} and -then @ref{8f,,revealing} so-called @ref{90,,transfer keys}. -@anchor{taler-developer-manual term-refund}@anchor{91} +data that the wallet commits to during the @ref{85,,melt} stage of the +@ref{8a,,refresh} protocol where it +has to prove to the @ref{6d,,exchange} that it is deriving the @ref{87,,fresh} +coins as specified by the Taler protocol. The commitment is verified +probabilistically (see: @ref{89,,kappa}) during the @ref{8e,,reveal} stage. +@anchor{taler-developer-manual term-refund}@anchor{86} @geindex refund -@item refund@anchor{taler-developer-manual term-refunding}@anchor{79} -@geindex refunding - -@itemx refunding +@item refund operation by which a merchant steps back from the right to funds that he -obtained from a @ref{6e,,deposit} operation, giving the right to the funds back +obtained from a @ref{80,,deposit} operation, giving the right to the funds back to the customer -@anchor{taler-developer-manual term-refund-transaction-id}@anchor{92} +@anchor{taler-developer-manual term-refund-transaction-id}@anchor{9b} @geindex refund transaction id @item refund transaction id -unique number by which a merchant identifies a @ref{91,,refund}. Needed +unique number by which a merchant identifies a @ref{86,,refund}. Needed as refunds can be partial and thus there could be multiple refunds for -the same @ref{8b,,purchase}. -@anchor{taler-developer-manual term-relative-time}@anchor{4c} +the same @ref{96,,purchase}. +@anchor{taler-developer-manual term-relative-time}@anchor{6b} @geindex relative time @item relative time -method of keeping time in @ref{4b,,GNUnet} where the time is represented +method of keeping time in @ref{6a,,GNUnet} where the time is represented as a relative number of microseconds. Thus, a relative time specifies an offset or a duration, but not a date. Called relative time in -contrast to @ref{4a,,absolute time}. -@anchor{taler-developer-manual term-reserve}@anchor{5e} +contrast to @ref{69,,absolute time}. +@anchor{taler-developer-manual term-reserve}@anchor{79} @geindex reserve @item reserve accounting mechanism used by the exchange to track customer funds -from incoming @ref{7a,,wire transfers}. A reserve is created whenever +from incoming @ref{6f,,wire transfers}. A reserve is created whenever a customer wires money to the exchange using a well-formed public key -in the subject. The exchange then allows the customer’s @ref{55,,wallet} -to @ref{60,,withdraw} up to the amount received in @ref{68,,fresh} -@ref{57,,coins} from the reserve, thereby draining the reserve. If a -reserve is not drained, the exchange eventually @ref{5b,,closes} it. +in the subject. The exchange then allows the customer’s @ref{73,,wallet} +to @ref{7b,,withdraw} up to the amount received in @ref{87,,fresh} +@ref{75,,coins} from the reserve, thereby emptying the reserve. If a +reserve is not emptied, the exchange will eventually @ref{78,,close} it. Other definition: Funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange;s bank account to cover obligations from coins in circulation. -@anchor{taler-developer-manual term-reveal}@anchor{6a} +@anchor{taler-developer-manual term-reveal}@anchor{8e} @geindex reveal -@item reveal@anchor{taler-developer-manual term-revealing}@anchor{8f} -@geindex revealing +@item reveal -@itemx revealing - -step in the @ref{67,,refresh} protocol where some of the transfer private +step in the @ref{8a,,refresh} protocol where some of the transfer private keys are revealed to prove honest behavior on the part of the wallet. -In the reveal step, the exchange returns the signed @ref{68,,fresh} coins. -@anchor{taler-developer-manual term-revoke}@anchor{93} +In the reveal step, the exchange returns the signed @ref{87,,fresh} coins. +@anchor{taler-developer-manual term-revoke}@anchor{98} @geindex revoke -@item revoke@anchor{taler-developer-manual term-revocation}@anchor{8d} -@geindex revocation - -@itemx revocation +@item revoke exceptional operation by which an exchange withdraws a denomination from circulation, either because the signing key was compromised or because the exchange is going out of operation; unspent coins of a revoked denomination are subjected to recoup. -@anchor{taler-developer-manual term-sharing}@anchor{94} +@anchor{taler-developer-manual term-sharing}@anchor{9c} @geindex sharing @item sharing -users can share ownership of a @ref{62,,coin} by sharing access to the coin's +users can share ownership of a @ref{75,,coin} by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time. -@anchor{taler-developer-manual term-spend}@anchor{56} +@anchor{taler-developer-manual term-spend}@anchor{74} @geindex spend -@item spend@anchor{taler-developer-manual term-spending}@anchor{95} -@geindex spending - -@itemx spending +@item spend operation by which a customer gives a merchant the right to deposit coins in return for merchandise -@anchor{taler-developer-manual term-terms}@anchor{96} +@anchor{taler-developer-manual term-terms}@anchor{9d} @geindex terms @item terms the general terms of service of an operator, possibly including -the @ref{88,,privacy policy}. Not to be confused with the -@ref{6c,,contract terms} which are about the specific purchase. -@anchor{taler-developer-manual term-transaction}@anchor{97} +the @ref{93,,privacy policy}. Not to be confused with the +@ref{7e,,contract terms} which are about the specific purchase. +@anchor{taler-developer-manual term-transaction}@anchor{9e} @geindex transaction @item transaction method by which ownership is exclusively transferred from one entity -@anchor{taler-developer-manual term-transfer}@anchor{53} -@geindex transfer - -@item transfer@anchor{taler-developer-manual term-transfers}@anchor{98} -@geindex transfers - -@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{50} -@geindex wire transfer - -@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7a} -@geindex wire transfers - -@itemx wire transfers - -method of sending funds between @ref{51,,bank} accounts @anchor{taler-developer-manual term-transfer-key}@anchor{99} @geindex transfer key -@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{90} -@geindex transfer keys - -@itemx transfer keys +@item transfer key -special cryptographic key used in the @ref{67,,refresh} protocol, some of which -are revealed during the @ref{6a,,reveal} step. Note that transfer keys have, -despite the name, no relationship to @ref{7a,,wire transfers}. They merely -help to transfer the value from a @ref{72,,dirty coin} to a @ref{7b,,fresh coin} -@anchor{taler-developer-manual term-user}@anchor{9a} +special cryptographic key used in the @ref{8a,,refresh} protocol, some of which +are revealed during the @ref{8e,,reveal} step. Note that transfer keys have, +despite the name, no relationship to @ref{6f,,wire transfers}. They merely +help to transfer the value from a @ref{81,,dirty} coin to a @ref{87,,fresh} coin +@anchor{taler-developer-manual term-user}@anchor{9f} @geindex user @item user any individual using the Taler payment system -(see @ref{59,,customer}, @ref{54,,buyer}, @ref{4f,,merchant}). -@anchor{taler-developer-manual term-version}@anchor{9b} +(see @ref{77,,customer}, @ref{72,,buyer}, @ref{6e,,merchant}). +@anchor{taler-developer-manual term-version}@anchor{a0} @geindex version @item version Taler uses various forms of versioning. There is a database schema version (stored itself in the database, see *-0000.sql) describing -the state of the table structure in the database of an @ref{4e,,exchange}, -@ref{52,,auditor} or @ref{4f,,merchant}. There is a protocol +the state of the table structure in the database of an @ref{6d,,exchange}, +@ref{71,,auditor} or @ref{6e,,merchant}. There is a protocol version (CURRENT:REVISION:AGE, see GNU libtool) which specifies -the network protocol spoken by an @ref{4e,,exchange} or @ref{4f,,merchant} +the network protocol spoken by an @ref{6d,,exchange} or @ref{6e,,merchant} including backwards-compatibility. And finally there is the software release version (MAJOR.MINOR.PATCH, see @indicateurl{https://semver.org/}) of the respective code base. -@anchor{taler-developer-manual term-wallet}@anchor{55} +@anchor{taler-developer-manual term-wallet}@anchor{73} @geindex wallet @item wallet software running on a customer’s computer; withdraws, stores and spends coins -@anchor{taler-developer-manual term-WebExtension}@anchor{9c} +@anchor{taler-developer-manual term-WebExtension}@anchor{a1} @geindex WebExtension @item WebExtension Cross-browser API used to implement the GNU Taler wallet browser extension. -@anchor{taler-developer-manual term-wire-gateway}@anchor{9d} +@anchor{taler-developer-manual term-wire-gateway}@anchor{a2} @geindex wire gateway @item wire gateway -FIXME: explain -@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{9e} -@geindex wire transfer identifier +API used by the exchange to talk with some real-time gross settlement system +(core banking system, blockchain) to notice inbound credits wire transfers +(during withdraw) and to trigger outbound debit wire transfers (primarily +for deposits). +@anchor{taler-developer-manual term-wire-transfer}@anchor{6f} +@geindex wire transfer -@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{9f} -@geindex wtid +@item wire transfer -@itemx wtid +a wire transfer is a method of sending funds between @ref{70,,bank} accounts +@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a3} +@geindex wire transfer identifier + +@item wire transfer identifier Subject of a wire transfer from the exchange to a merchant; set by the aggregator to a random nonce which uniquely identifies the transfer. -@anchor{taler-developer-manual term-withdraw}@anchor{60} +@anchor{taler-developer-manual term-withdraw}@anchor{7b} @geindex withdraw -@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{77} -@geindex withdrawing - -@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a0} -@geindex withdrawal +@item withdraw -@itemx withdrawal - -operation by which a @ref{55,,wallet} can convert funds from a @ref{5e,,reserve} to +operation by which a @ref{73,,wallet} can convert funds from a @ref{79,,reserve} to fresh coins -@anchor{taler-developer-manual term-zombie}@anchor{a1} +@anchor{taler-developer-manual term-zombie}@anchor{a4} @geindex zombie -@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a2} -@geindex zombie coin - -@itemx zombie coin +@item zombie -coin where the respective @ref{6d,,denomination key} is past its -@ref{6e,,deposit} @ref{75,,expiration} time, but which is still (again) valid -for an operation because it was @ref{83,,melted} while it was still -valid, and then later again credited during a @ref{8c,,recoup} process +@ref{75,,coin} where the respective @ref{7f,,denomination key} is past its +@ref{80,,deposit} @ref{83,,expiration} time, but which is still (again) valid +for an operation because it was @ref{85,,melted} while it was still +valid, and then later again credited during a @ref{97,,recoup} process @end table @node Developer Tools,Index,Developer Glossary,Top -@anchor{taler-developer-manual developer-tools}@anchor{a3} +@anchor{taler-developer-manual developer-tools}@anchor{a5} @chapter Developer Tools @@ -2624,110 +3920,20 @@ This section describes various internal programs to make life easier for the developer. @menu -* taler-config-generate:: +* taler-harness:: @end menu -@node taler-config-generate,,,Developer Tools -@anchor{taler-developer-manual taler-config-generate}@anchor{a4} -@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 -for the Taler exchange or Taler merchants. - - -@table @asis - -@item @strong{-C} @emph{CURRENCY} | @strong{–currency=}@emph{CURRENCY} - -Which currency should we use in the configuration. - -@item @strong{-c} @emph{FILENAME} | @strong{–config=}@emph{FILENAME} - -Location where to write the generated configuration. Existing file -will be updated, not overwritten. - -@item @strong{-e} | @strong{–exchange} - -Generate configuration for a Taler exchange. - -@item @strong{-f} @emph{AMOUNT} | @emph{-wirefee=}@emph{AMOUNT} - -Setup wire transfer fees for the next 5 years for the exchange (for -all wire methods). +@node taler-harness,,,Developer Tools +@anchor{taler-developer-manual taler-harness}@anchor{a6} +@section taler-harness -@item @strong{-h} | @strong{–help} -Shows this man page. +`taler-harness deployment gen-coin-config' is a tool to simplify Taler configuration generation. -@item @strong{-J} @emph{JSON} | @strong{–wire-json-exchange=}@emph{JSON} - -Wire configuration to use for the exchange. - -@item @strong{-j} @emph{JSON} | @strong{–wire-json-merchant=}@emph{JSON} - -Wire configuration to use for the merchant. - -@item @strong{-L} @emph{LOGLEVEL} | @strong{–loglevel=}@emph{LOGLEVEL} - -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and -ERROR. - -@item @strong{-m} | @strong{–merchant} - -Generate configuration for a Taler merchant. - -@item @strong{-t} | @strong{–trusted} - -Setup current exchange as trusted with current merchant. Generally -only useful when configuring for testcases. - -@item @strong{-v} | @strong{–version} - -Print version information. - -@item @strong{-w} @emph{WIREFORMAT} | @strong{–wire} @emph{WIREFORMAT} - -Specifies which wire format to use (i.e. “test” or “sepa”) - -@item @strong{–bank-uri} - -Alternative to specify wire configuration to use for the exchange and -merchant for the “test” wire method. Only useful if WIREFORMAT was -set to “test”. Specifies the URI of the bank. - -@item @strong{–exchange-bank-account} - -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} - -Alternative to specify wire configuration to use for the merchant for -the “test” wire method. Only useful if WIREFORMAT was set to “test”. -Specifies the bank account number of the merchant. -@end table +`taler-harness deployment gen-coin-config' +[`-min-amount**='`VALUE'] +[`-max-amount**='`VALUE'] @node Index,,Developer Tools,Top @unnumbered Index |