1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
====================
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 <https://gnunet.org>`_ project, and the latter from `taler <https://taler.net>`_
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 <http://emscripten.org>`_ 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 <http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html#sdk-download-and-install>`_.
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 <http://kripken.github.io/emscripten-site/docs/compiling/Building-Projects.html#building-projects>`_ 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
|
