==================== The Wallet Reference ==================== This chapter explains how to set up a wallet. It is worth noting that there are two versions for this componenet - one browser based and the other implemented as an `app` for mobile systems. ------- General ------- Mints and merchants have a base URL for their service. This URL *must* be in a canonical form when it is stored (e.g. in the wallet's database) or transmitted (e.g. to a bank page). 1. The URL must be absolute. This implies that the URL has a schema. 2. The path component of the URL must end with a slash. 3. The URL must not contain a fragment or query. When a user enters a URL that is, technically, relative (such as "alice.example.com/mint"), wallets *may* transform it into a canonical base URL ("http://alice.example.com/mint/"). Other components *should not* accept URLs that are not canonical. Rationale: Joining non-canonical URLs with relative URLs (e.g. "mint.example.com" with "reserve/status") results in different and slightly unexpected behavior in some URL handling libraries. Canonical URLs give more predictable results with standard URL joining. --------------- Error Handling --------------- --------------- User Experience --------------- Balance Overview ~~~~~~~~~~~~~~~~ Transactions Log ~~~~~~~~~~~~~~~~ The transaction log shows all events that lead to a change in balance, including withdrawal and purchases. Error Log ~~~~~~~~~ -------------------- Browser based wallet -------------------- This paragraph gives instructions on how to proceed from getting the source code to build the final `.xpi` that can be installed into the Web browser. .. ^^^^^^^^^^^^^^^^^^^^^^^. .. Getting the source code. .. ^^^^^^^^^^^^^^^^^^^^^^^. *clone* into our repository to get the latest version of the code, .. sourcecode:: bash git clone http://git.taler.net/wallet.git the actual build of the `.xpi` file is managed by `make`, so .. sourcecode:: bash cd wallet/wallet_button/firefox_src/ make The extension is now placed in ``wallet/wallet_button/bin/``, called ``taler-button.xpi``. To load it into the Web browser, it suffices to open it as a normal file or it could even be placed on the Web and installed by just visiting its URI. ^^^^^^^^^^ Emscripten ^^^^^^^^^^ Since the wallet makes extensive use of cryptographic primitives and of coin manipulation primitives, it relies on two fundamental libraries: ``libgnunetutils_taler_wallet`` and ``libtalerutil_wallet``; being the former from the `gnunet `_ project, and the latter from `taler `_ project itself. Moreover, since those libraries depend on `libgpg-error`, `libgcrypt` and `libunistring`, and the non markup part of the extension is JavaScript, a language-to-language compiler such as `Emscripten `_ has been used to port `C` sources to JavaScript. .. note:: To just compile the extension and install it into your browser, it suffices to follow the above steps and simply ignore this section. That is possible since `git master` ships a previously made JavaScript version of ``libgnunetutil_taler_wallet``, that the extension is properly linked against to. So this section is dedicated to those who want to reproduce the steps needed to port all the required libraries to JavaScript. We begin by getting the sources for all the needed parts, so issue the following commands .. sourcecode:: bash git://git.gnupg.org/libgpg-error.git # code downloaded in 'libgpg-error/' git://git.gnupg.org/libgcrypt.git # code downloaded in 'libgcrypt/' git://git.savannah.gnu.org/libunistring.git # code downloaded in 'libunistring/' svn co https://gnunet.org/svn/gnunet # code downloaded in 'gnunet/' git clone https://git.taler.net/mint.git # code downloaded in 'mint/' Before delving into the proper compilation, let's assume that the wallet `git master` has been cloned into some direcory called ``wallet``. In ``wallet/wallet_button/emscripten/${component}``, where ``${component}`` ranges over ``libgpg-error``, ``libgcrypt``, ``libunistring``, there is a shell script called ``myconf-${component}.sh`` that will take care of configuring and building the referred components. As for `gnunet`, let ``${g_component}`` and ``${t_component}`` be respectively ``gnunet`` and ``taler``; the scripts we need are ``wallet/wallet_button/emscripten/lib${g_component}util_taler_wallet.sh``. To install emscripten, refer to the `official documentation `_. It is worth noting that all our tests have been run using the `emscripten SDK`, though any other alternative method of setting up emscripten should work. At the time of this writing the following versions have been used for each component * emscripten 1.33.2 * libgpg-error 1.19 (commit 4171d61a97d9628532db84b590a9c135f360fa90) * libgcrypt 1.7 (commit a36ee7501f68ad7ebcfe31f9659430b9d2c3ddd1) * libunistring 0.9.5 (commit 4b0cfb0e39796400149767bdeb6097927895635a) * gnunet 0.10.1 (commit r35923) * taler `mint` Pre-alpha (commit 28f9f7b54077d0105fa5f97ab0c97d80262dcfee) Please note that the order in which each component is listed must reflect the order in which each of them is compiled. To configure and build any component, it suffices to copy the provided script into any tree of the targeted component. For `libgpg-error`, `libgcrypt` and `libunistring`, do .. sourcecode:: bash cp wallet/wallet_button/emscripten/${component}/myconf-${component}.sh ${component}/ As for ``libgnunetutils_taler_wallet`` and ``libtalerutil_wallet``, do .. sourcecode:: bash cp wallet/wallet_button/emscripten/myconf-libgnunetutil_taler_wallet.sh gnunet/ cp wallet/wallet_button/emscripten/myconf-libtalerutil_wallet.sh mint/ Then to generate the native configure script, for `lib-gpgerror` `libgcrypt` and `libunistring` .. sourcecode:: bash cd ${component} ./autogen.sh whereas for `gnunet` and `taler`, do .. sourcecode:: bash cd ${component} ./bootstrap.sh Finally, run the respective `myconf-*.sh` scripts in the order of the components given above. All generated files will be placed under ``/tmp/emscripten``. At this point, you have the header files and the static library for each component compiled in the `LLVM` intermediate form. To see some final JavaScript, it is needed to compile a `C` program, though that is not the only way against the libraries we have just built. See the official `emscripten's documentation `_ for more details. In `taler`'s case, this task is accomplished by a `C` source file called ``wrap.c``, that is located at ``wallet/wallet_button/emscripten``. Its main purpose is to save JavaScript land from manipulating `C` structures to pass to `libgnunetutil_taler_wallet`'s and `libtalerutil_wallet`'s primitives, and to provide some handy functions. In order to compile it, issue .. sourcecode:: bash cd wallet/wallet_button/emscripten/lib_wrapper ./final-build.sh the build script will build and copy the generated ``lib_wrapper.js`` inside ``wallet/wallet_button/firefox_src/content/lib/``, so that the extension's code can properly import it. Some simple tests written in `C` are placed into our wallte's source tree, so .. sourcecode:: bash cd wallet/wallet_button/emscripten/hello_world/ source final_build-${X}.sh # with ${X} being either 'fancy' or 'time' Your environment has now two functions, ``assmb`` and ``linkit``, where the former will just assemble the test ``${X}.c`` (leaving a file named ``${X}.o`` inspectable by ``llvm-nm`` or ``llvm-objdump``) and the latter will link the final JavaScript called ``${X}.js``. Thus, to see some output, issue .. sourcecode:: bash assmb linkit nodejs ${X}.js The same directory offers a more "playful" example, called ``time_glue.c``. Its purpose is to be compiled as a JavaScript "library" that could be imported by a Web browser, which can, in turn, call the functions provided. After sourcing ``final_build-time_glue.sh``, the assembling and linking phases, accomplished in the same way as the previous examples, yield a HTML containing the JavaScript translation of ``time_glue.c``, called ``time_glue.html``. .. note:: The following steps have been tested exclusively on Mozilla Firefox (39) In order to import the library into the browser and call its functions, 1. Open ``time_glue.html`` 2. Open the JavaScript shell environment (`CTRL+K`) 3. Import the function which retrieves the current time in binary format by allocating a proper structure and returning its pointer: at the prompt, issue ``var time = window.Module.cwrap('get_absolute_time', 'number');`` 4. Import the function which convert such a binary format in a human readable string, ``var pretty = window.Module.cwrap('get_fancy_time_dealloc', 'string', ['number']);``. The `_dealloc` part is due to our choice to make this example easier by avoiding the passing of whole C structures as parameters. Although doable with emscripted code, that adds more complexity than expectable for an example. Instead of calling a further function with the sole aim of deallocating the time holding structure from emscripten's heap, we therefore chose to do so from this function. 5. Import the "printer", ``var printTime = window.Module.cwrap('print_time', 'void', ['string']);`` 6. Normally call the imported functions: .. sourcecode:: JavaScript var timeRaw = time(); var timeString = pretty(timeRaw); printTime(timePretty); // this last command should give some ouput on the black canvas