summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMarcello Stanisci <marcello.stanisci@inria.fr>2016-12-26 18:42:18 +0100
committerMarcello Stanisci <marcello.stanisci@inria.fr>2016-12-26 18:42:18 +0100
commit0387814723b3c3d055153892e98b9ed6db7a1450 (patch)
tree96b535e9a48f292e3bff8f8ec9d2940ee942b623 /docs
parent79a8adba0386900dc7b4ca238fe1d36235ff4e61 (diff)
downloaddocs-0387814723b3c3d055153892e98b9ed6db7a1450.tar.gz
docs-0387814723b3c3d055153892e98b9ed6db7a1450.tar.bz2
docs-0387814723b3c3d055153892e98b9ed6db7a1450.zip
Still on splitting
Diffstat (limited to 'docs')
-rw-r--r--docs/conf.py285
-rw-r--r--docs/configuration-basics.rst79
-rw-r--r--docs/deployment.rst231
-rw-r--r--docs/dev-exchange.rst144
-rw-r--r--docs/dev-merchant.rst38
-rw-r--r--docs/dev-wallet-wx.rst212
-rw-r--r--docs/example-essay-store.rst616
-rw-r--r--docs/exts/__pycache__/tsref.cpython-35.pycbin0 -> 7448 bytes
-rw-r--r--docs/exts/tsref.py233
-rw-r--r--docs/global_licensing.rst215
-rw-r--r--docs/glossary.rst106
-rw-r--r--docs/index.rst103
-rw-r--r--docs/operate-exchange.rst246
-rw-r--r--docs/operate-merchant.rst212
14 files changed, 2720 insertions, 0 deletions
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000..8db3f93b
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,285 @@
+"""
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Lesser General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+ @author Marcello Stanisci
+"""
+# -*- coding: utf-8 -*-
+#
+# neuro documentation build configuration file, created by
+# sphinx-quickstart on Sat May 31 13:11:06 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '1.3'
+
+sys.path.append(os.path.abspath('exts'))
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'tsref',
+ 'sphinx.ext.todo',
+ 'sphinx.ext.pngmath',
+ 'sphinxcontrib.httpdomain'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Taler'
+copyright = u'2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'neurodoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'taler.tex', u'Taler Documentation',
+ u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff',
+ 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'neuro', u'neuro Documentation',
+ [u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff'],
+ 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'neuro', u'neuro Documentation',
+ u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff',
+ 'neuro', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/docs/configuration-basics.rst b/docs/configuration-basics.rst
new file mode 100644
index 00000000..50c3d532
--- /dev/null
+++ b/docs/configuration-basics.rst
@@ -0,0 +1,79 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+
+======================
+Configuration in Taler
+======================
+
+In Taler realm, any component obeys to the same pattern to get configuration
+values. According to this pattern, once the component has been installed, the
+installation deploys default values in `${prefix}/share/taler/config.d/`, in
+`.conf` files. In order to override these defaults, the user can write a custom
+`.conf` file and either pass it to the component at execution time, or name it
+`taler.conf` and place it under `$HOME/.config/`.
+
+
+--------------------
+Configuration format
+--------------------
+
+A config file is a text file containing `sections`, and each section contains
+its `values`. The right format follows::
+
+ [section1]
+ value1 = string
+ value2 = 23
+
+ [section2]
+ value21 = string
+ value22 = /path22
+
+Throughout any configuration file, it is possible to use ``$``-prefixed variables,
+like ``$VAR``, especially when they represent filesystem paths.
+It is also possible to provide defaults values for those variables that are unset,
+by using the following syntax: ``${VAR:-default}``.
+However, there are two ways a user can set ``$``-prefixable variables:
+
+by defining them under a ``[paths]`` section, see example below, ::
+
+ [paths]
+ TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
+ ..
+ [section-x]
+ path-x = ${TALER_DEPLOYMENT_SHARED}/x
+
+or by setting them in the environment::
+
+ $ export VAR=/x
+
+The configuration loader will give precedence to variables set under ``[path]``,
+though.
+
+The utility ``taler-config``, which gets installed along with the exchange, serves
+to get and set configuration values without directly editing the `.conf`.
+The option ``-f`` is particularly useful to resolve pathnames, when they use
+several levels of ``$``-expanded variables. See ``taler-config --help``.
+
+Note that, in this stage of development, the file ``$HOME/.config/taler.conf``
+can contain sections for *all* the component. For example, both an exchange and
+a bank can read values from it.
+
+The repository ``git://taler.net/deployment`` contains examples of configuration
+file used in our demos. See under ``deployment/config``.
+
+.. note::
+
+ Expectably, some components will not work just by using default values, as their
+ work is often interdependent. For example, a merchant needs to know an exchange
+ URL, or a database name.
diff --git a/docs/deployment.rst b/docs/deployment.rst
new file mode 100644
index 00000000..c0b07e43
--- /dev/null
+++ b/docs/deployment.rst
@@ -0,0 +1,231 @@
+===================
+Deployment Protocol
+===================
+
+------
+Wallet
+------
+
+.. code-block:: none
+
+ $ cd wallet-webex
+
+ # check dependencies
+ $ ./configure
+
+ # edit version and version_name
+ $ $EDITOR manifest.json
+
+ $ make package-stable
+
+The built wallet is now ready in `taler-wallet-stable-${version_name}${version}.zip`.
+
+FIXME: here, we should do some semi-automated testing with selenium, to see
+that everything works against `demo.taler.net`.
+
+The package can now be uploaded to https://chrome.google.com/webstore/developer/dashboard
+
+FIXME: include asset links and descriptions we use in the webstore in this document
+
+FIXME: include instructions for other app stores
+
+
+--------------------
+Deploying to stable
+--------------------
+
+First, make sure that the deployment *AND* the deployment scripts work on the `test.taler.net` deployment.
+
+For all repositories that have a separate stable branch (currently exchange.git,
+merchant.git, merchant-frontends.git, bank.git, landing.git) do:
+
+.. code-block:: none
+
+ $ cd $REPO
+ $ git pull origin master stable
+ $ git checkout stable
+
+ # option a: resolve conflicts resulting from hotfixes
+ $ git merge master
+ $ ...
+
+ # option b: force stable to master
+ $ git update-ref refs/heads/stable master
+
+ $ git push # possibly with --force
+
+ # continue development
+ $ git checkout master
+
+
+Log into taler.net with the account that is *not* active by looking
+at the `sockets` symlink of the `demo` account.
+
+The following instructions wipe out the old deployment completely.
+
+.. code-block:: none
+
+ $ ls -l ~demo/sockets
+
+ [...] sockets -> /home/demo-green/sockets/
+
+In this case, `demo-green` is the active deployment, and `demo-blue` should be updated.
+After the update is over, the `/home/demo/sockets` symlink will be pointed to `demo-blue`.
+
+.. code-block:: none
+
+ # Remove all existing files
+ $ find $HOME -exec rm -fr {} \;
+
+ $ git clone /var/git/deployment.git
+ $ ./deployment/bootstrap-bluegreen demo
+
+ # set environment appropriately
+ $ . activate
+ $ taler-deployment-build
+
+ # upgrade the database! this
+ # process depends on the specific version
+
+ $ taler-deployment-start
+
+ # look at the logs, verify that everything is okay
+
+Now the symlink can be updated.
+
+
+
+------------------
+Database upgrades
+------------------
+
+The exchange db can be re-initialized with
+
+.. code-block:: none
+
+ $ taler-exchange-dbinit -r
+
+CAUTION: YOU WILL LOSE ALL DATA WITH THIS!
+
+
+---------------------
+Standalone deployment
+---------------------
+
+This tecnique aims to set a thorough Taler installation up on a
+machine whose nginx configuration is configured by config files
+from https://git.taler.net/deployment.git/tree/etc/nginx.
+
+This installation assumes that all the steps are run with ``$HOME``
+as ``$CWD``.
+
+The first step is to fetch the `deployment` repository, which hosts all
+the needed scripts.
+
+.. code-block:: none
+
+ # Adapt the repository's URI to your needs.
+ $ git clone /var/git/deployment.git/
+
+The next step is to fetch all the codebases from all the components.
+
+.. code-block:: none
+
+ $ ./deployment/bootstrap-standalone
+
+If the previous step succeeded, a file named ``activate`` should be now
+in the ``$CWD``. It contains environmental definitions for ``$PATH`` and
+database names.
+
+.. note::
+
+ Please *ignore* the output from the previous script when it succeeds,
+ which is
+
+ .. code-block:: none
+
+ WARNING: enabling "trust" authentication for local connections
+ You can change this by editing pg_hba.conf or using the option -A, or
+ --auth-local and --auth-host, the next time you run initdb.
+
+ Success. You can now start the database server using:
+
+ /usr/lib/postgresql/9.5/bin/pg_ctl -D talerdb -l logfile start
+
+ The reason is that this message is generated by Postgresql's utilities and
+ you never need to start your database manually; it will be started by the
+ init script that launches all the Taler processes.
+
+Now we need to compile and install all the downloaded codebases.
+
+.. code-block:: none
+
+ # We first update ``$PATH``, in order to make all the compilation
+ and configuration utilities available.
+ $ source activate
+
+ # Double check if the previous step worked: $PATH should
+ # contain $HOME/local/bin.
+ $ echo $PATH
+
+ # The actual compilation:
+ $ taler-deployment-build
+
+The following step will generate config files for all the components.
+Please **note** that although a default currency will be picked up by the
+script, it is possible to have a custom currency by setting the environment
+variable ``TALER_CONFIG_CURRENCY`` to the wanted currency, and then runing
+the config generator.
+
+.. code-block:: none
+
+ $ taler-deployment-config-generate
+
+whereas the following one will place signatures inside wireformat JSON
+files.
+
+.. code-block:: none
+
+ $ taler-deployment-config-sign
+
+The next step is to generate `signkeys` and `denomkeys`.
+
+.. code-block:: none
+
+ $ taler-deployment-keyup
+
+..
+ An error of "invalid currency name" might be related to the current
+ policy of 12-chars limit for currency names; which is likely going to
+ be changed.
+
+It may be necessary to define database tables for the exchange. The
+following command does that.
+
+.. code-block:: none
+
+ # Erase all the data!
+ $ taler-exchange-dbinit -r
+
+As of the merchant backend, it creates tables at launch time, so it is
+not required to define tables before launching it. `However`, if some
+table's definition changed over the time, and there is a need to force
+a redefinition of tables, then the following command accomplishes that
+for the merchant:
+
+.. code-block:: none
+
+ # Erase all the data!
+ $ taler-merchant-dbinit -r
+
+If all previous steps succeeded, it is now possible to launch all the
+processes. That is accomplished by the following command:
+
+.. code-block:: none
+
+ $ taler-deployment-start
+
+.. note::
+
+ Please make sure your nginx works correctly with its configuration
+ at ``<DEPLOYMENT-REPO>/etc/nginx``.
diff --git a/docs/dev-exchange.rst b/docs/dev-exchange.rst
new file mode 100644
index 00000000..91278ee7
--- /dev/null
+++ b/docs/dev-exchange.rst
@@ -0,0 +1,144 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+ @author Marcello Stanisci
+
+========
+Exchange
+========
+
+.. _keys-duration:
+
+-------------
+Keys duration
+-------------
+
+`signkeys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
+is run, `taler-exchange-keyup` will generate `n` `signkeys`, where `t + (n * signkey_duration) = t +
+lookahead_sign`. In other words, we generate a number of keys which is sufficient to cover a period of
+`lookahead_sign`. As for the starting date, the first generated key will get a starting time of `t`,
+and the `j`-th key will get a starting time of `x + signkey_duration`, where `x` is the starting time
+of the `(j-1)`-th key.
+
+`denom keys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
+is run, `taler-exchange-keyup` will generate `n` `denom keys` for each denomination, where
+`t + (n * duration_withdraw) = t + lookahead_sign`. In other words, for each denomination, we generate a
+number of keys which is sufficient to cover a period of `lookahead_sign`. As for the starting date, the
+first generated key will get a starting time of `t`, and the `j`-th key will get a starting time of
+`x + duration_withdraw`, where `x` is the starting time of the `(j-1)`-th key.
+
+
+
+---------------
+Database Scheme
+---------------
+
+The exchange database must be initialized using `taler-exchange-dbinit`. This
+tool creates the tables required by the Taler exchange to operate. The
+tool also allows you to reset the Taler exchange database, which is useful
+for test cases but should never be used in production. Finally,
+`taler-exchange-dbinit` has a function to garbage collect a database,
+allowing administrators to purge records that are no longer required.
+
+The database scheme used by the exchange look as follows:
+
+.. image:: exchange-db.png
+
+
+-------------------
+Signing key storage
+-------------------
+
+The private online signing keys of the exchange are stored in a
+subdirectory "signkeys/" of the "KEYDIR" which is an option in the
+"[exchange]" section of the configuration file. The filename is the
+starting time at which the signing key can be used in microseconds
+since the Epoch. The file format is defined by the `struct
+TALER_EXCHANGEDB_PrivateSigningKeyInformationP`:
+
+.. sourcecode:: c
+
+ struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP {
+ struct TALER_ExchangePrivateKeyP signkey_priv;
+ struct TALER_ExchangeSigningKeyValidityPS issue;
+ };
+
+------------------------
+Denomination key storage
+------------------------
+
+The private denomination keys of the exchange are store in a
+subdirectory "denomkeys/" of the "KEYDIR" which is an option in the
+"[exchange]" section of the configuration file. "denomkeys/" contains
+further subdirectories, one per denomination. The specific name of
+the subdirectory under "denomkeys/" is ignored by the exchange.
+However, the name is important for the "taler-exchange-keyup" tool
+that generates the keys. The tool combines a human-readable encoding
+of the denomination (i.e. for EUR:1.50 the prefix would be
+"EUR_1_5-", or for EUR:0.01 the name would be "EUR_0_01-") with a
+postfix that is a truncated Crockford32 encoded hash of the various
+attributes of the denomination key (relative validity periods, fee
+structure and key size). Thus, if any attributes of a coin change,
+the name of the subdirectory will also change, even if the
+denomination remains the same.
+
+Within this subdirectory, each file represents a particular
+denomination key. The filename is the starting time at which the
+signing key can be used in microseconds since the Epoch. The
+format on disk begins with a
+`struct TALER_EXCHANGEDB_DenominationKeyInformationP` giving
+the attributes of the denomination key and the associated
+signature with the exchange's long-term offline key:
+
+.. sourcecode:: c
+
+ struct TALER_EXCHANGEDB_DenominationKeyInformationP {
+ struct TALER_MasterSignatureP signature;
+ struct TALER_DenominationKeyValidityPS properties;
+ };
+
+This is then followed by the variable-size RSA private key in
+libgcrypt's S-expression format, which can be decoded using
+`GNUNET_CRYPTO_rsa_private_key_decode()`.
+
+-------------------------
+Auditor signature storage
+-------------------------
+
+Signatures from auditors are stored in the directory specified
+in the exchange configuration section "exchangedb" under the
+option "AUDITOR_BASE_DIR". The exchange does not care about
+the specific names of the files in this directory.
+
+Each file must contain a header with the public key information
+of the auditor, the master public key of the exchange, and
+the number of signed denomination keys:
+
+.. sourcecode:: c
+
+ struct AuditorFileHeaderP {
+ struct TALER_AuditorPublicKeyP apub;
+ struct TALER_MasterPublicKeyP mpub;
+ uint32_t dki_len;
+ };
+
+This is then followed by `dki_len` signatures of the auditor of type
+`struct TALER_AuditorSignatureP`, which are then followed by another
+`dki_len` blocks of type `struct TALER_DenominationKeyValidityPS`.
+The auditor's signatures must be signatures over the information of
+the corresponding denomination key validity structures embedded in a
+`struct TALER_ExchangeKeyValidityPS` structure using the
+`TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS` purpose.
diff --git a/docs/dev-merchant.rst b/docs/dev-merchant.rst
new file mode 100644
index 00000000..e4cd4cbc
--- /dev/null
+++ b/docs/dev-merchant.rst
@@ -0,0 +1,38 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+
+========
+Merchant
+========
+
+.. _merchant-arch:
+
+------
+Design
+------
+
+In order for a merchant to be Taler-compatible, they need to run two distinct Web
+services: a *frontend* and a *backend*. The former is typically the Web site where
+the merchant exposes their goods, whereas the latter is a C program in charge of
+making all the Taler-related cryptography.
+
+In details, the frontend gathers all the information from customers about sales,
+and forwards it to the backend via its RESTful API. Typically, the backend will either
+cryptographically process this data or just forward it to the exchange.
+
+That saves the frontend developers from dealing with cryptography in scripting
+languages and from commmunicating at all with any exchange.
+
+Additionally, the backend RESTful API is such that a frontend might be run completely
+database-less.
diff --git a/docs/dev-wallet-wx.rst b/docs/dev-wallet-wx.rst
new file mode 100644
index 00000000..8ba29975
--- /dev/null
+++ b/docs/dev-wallet-wx.rst
@@ -0,0 +1,212 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+
+=====================
+WebExtensions Wallet
+=====================
+
+------------
+Introduction
+------------
+
+The WebExtensions Wallet (*wxwallet*) can be used to pay with GNU Taler on web
+sites from within modern web browsers. The `WebExtensions
+<https://wiki.mozilla.org/WebExtensions>`_ API enables the development of
+cross-browser extensions. Google Chrome / Chromium, Mozilla Firefox, Opera and
+Microsoft Edge will all offer support for WebExtensions and thus be able to support Taler.
+
+Currently Chrome hast the best support for WebExtensions (since the API is a
+superset of Chrome's extension API).
+
+-----------------------
+Development Environment
+-----------------------
+
+The *wxwallet* mainly written in the `TypeScript
+<http://www.typescriptlang.org/>`_ language, which is a statically typed
+superset of JavaScript.
+
+While the *wxwallet* is mainly intended to be run from inside a browser, the
+logic is implemented in browser-independent modules that can also be called
+from other environments such as `nodejs <https://nodejs.org>`_. This is
+especially useful for automatically running unit tests.
+
+
+-----------------
+Project Structure
+-----------------
+
+.. parsed-literal::
+
+ **manifest.json** extension configuration
+ **package.json** node.js package configuration
+ **tsconfig.json** TypeScript compiler configuration
+ **gulpfile.js** Build tasks script
+ **lib/**
+ **vendor/** 3rd party libraries
+ **wallet/** actual application logic
+ **emscripten/** emscripten object file and glue
+ **test/**
+ **run_tests.js** nodejs entry point for tests
+ **tests/** test cases
+ **content_scripts/notify.ts** wallet<->website signaling
+ **backgrond/main.ts** backend entry point
+ **img/** static image resources
+ **style/** CSS stylesheets
+ **pages/** pages shown in browser tabs
+ **popup/** pages shown the extension popup
+
+
+-------------------
+Building the Wallet
+-------------------
+
+To build the extension for use during development, simply run the TypeScript compiler
+from the extension directory:
+
+.. code-block:: sh
+
+ $ cd wallet.git/wallet_webextension/extension/
+ $ tsc
+
+This will use the ``tsconfig.json`` with development options such as `source map`_ support.
+
+.. _`source map`: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit
+
+When TypeScript source files are added or deleted to the project, make sure that the
+globs in ``gulpfile.js`` match them so that they will be compiled. The ``tsconfig.json``
+is generated by running:
+
+
+.. code-block:: sh
+
+ $ gulp tsconfig
+
+.. caution::
+
+ Do not edit the ``tsconfig.json`` manually. The source files should be defined in
+ one place, and that is ``gulpfile.js``.
+
+To pack the extension in a format that can be uploaded to the Google Webstore, run:
+
+.. code-block:: sh
+
+ $ gulp package
+
+This will build the wallet without source maps, copy resource files (which also need to be
+specified in ``gulpfile.js``) and create an archive.
+
+
+----------
+Emscripten
+----------
+
+`Emscripten <https://kripken.github.io/emscripten-site/index.html>`_ is C/C++
+to JavaScript compiler. Emscripten is used in the *wxwallet* to access
+low-level cryptography from *libgcrypt*, and miscellaneous functionality from
+*libgnunetutil* and *libtalerwallet*.
+
+TODO: say things about wrappers
+
+
+--------------------------------------
+Target Environments and Modularization
+--------------------------------------
+
+Modules in the wallet are declared in TypeScript with
+the ES6 module syntax. These modules are then compiled
+to `SystemJS <https://github.com/systemjs/systemjs>`_ `register` modules.
+
+SystemJS modules can be loaded from the browser as well as from nodejs.
+However they require special entry points that configure the module system,
+load modules and execute code. Examples are `backgrond/main.ts` for the
+browser and `test/run_tests.js` for nodejs.
+
+Note that special care has to be taken when loading the Emscript code,
+as it is not compatible with the SystemJS module, even in the `globals`
+compatibility mode.
+
+The TypeScript sources in the *wxwallet* are compiled down to ES5, both to
+enable running in node.js without transpilers and to avoid a `bug
+<https://github.com/Microsoft/TypeScript/issues/6426>`_ in the TypeScript
+compiler.
+
+----------------------------
+IndexedDB Query Abstractions
+----------------------------
+
+The *wxwallet* uses a fluent-style API for queries on IndexedDB.
+
+TODO: say more about this
+
+
+-------
+Testing
+-------
+
+Test cases for the wallet are written in TypeScript and
+run with `mochajs <http://mochajs.org/>`_ and the `better-assert <https://github.com/tj/better-assert>`_ assertion
+library.
+
+Run the default test suite with ``npm run test``, which will
+call `mocha` with the right parameters.
+
+
+--------------------
+Internationalisation
+--------------------
+
+Strings in the JavaScript code are internationalised using the following functions:
+
+- *i18n*: translate string with arbitrary arguments, the result is returned as string.
+
+.. code-block:: js
+
+ i18n`You have ${n} coins.`
+
+- *i18n.parts*: Interpolate i18nized values with arbitrary objects.
+ Useful for example to include HTML elements.
+
+.. code-block:: js
+
+ i18n.parts`Visit ${link} to get more coins.`
+
+- *i18n.pluralize*: translate with plural form.
+ The i18n.number() function returns a ``PluralNumber`` object
+ that specifies the argument that determines the plural form,
+ if not present the first numeric argument is used.
+
+.. code-block:: js
+
+ i18n.pluralize(
+ i18n`${i}: you have ${i18n.number(n)} coin.`,
+ `${i}: you have ${i18n.number(n)} coins.`);
+
+These functions are defined in ``lib/i18n.ts``.
+Include ``lib/vendor/jed.js``, ``lib/i18n.js``, ``lib/i18n-strings.js`` to use them.
+
+To extract strings from sources and update the .po files, run:
+
+.. code-block:: sh
+
+ $ make i18n
+
+In static HTML files the ``lang`` attribute is used for language-specific strings:
+
+.. code-block:: html
+
+ <p lang="en">Hello World!</p>
+ <p lang="de">Hallo Welt!</p>
+
+``lib/i18n.js`` and ``style/lang.css`` needs to be included for this to work.
diff --git a/docs/example-essay-store.rst b/docs/example-essay-store.rst
new file mode 100644
index 00000000..8ba28df6
--- /dev/null
+++ b/docs/example-essay-store.rst
@@ -0,0 +1,616 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014, 2015, 2016 INRIA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+
+====================
+Example: Essay Store
+====================
+
+This section shows how to set up a merchant :ref:`frontend <merchant-arch>`, and is
+inspired by our demonstration shop running at `https://shop.demo.taler.net/`.
+It is recommended that the reader is already familiar with the
+:ref:`payment protocol and terminology <payprot>`.
+
+The code we are going to describe is available at
+https://git.taler.net/merchant-frontends.git/tree/talerfrontends/blog
+and is implemented in Python+Flask.
+
+The desired effect is the homepage showing a list of buyable articles, and once the
+user clicks one of them, they will either get the Taler :ref:`contract <contract>`
+or a credit card paywall if they have no Taler wallet installed.
+
+Each article links thus to a `offer URL`, having the following
+layout:
+
+ `https://shop.demo.taler.net/essay/Appendix_A:_A_Note_on_Software`
+
+Once the server side logic receives a request for a offer URL, it needs to
+instruct the wallet to retrieve a Taler contract. This action can be taken
+either with or **without** the use of JavaScript, see the next section.
+
+-----------------------
+Triggering the contract
+-----------------------
+
+It is important to note that the contract is not returned simply
+as the offer URL's response, but rather the frontend `instructs`
+the browser on how to retrieve the contract. That is needed for
+the right handling of the cases where the wallet is not installed.
+
+.. note::
+
+ The code samples shown below are intentionally "incomplete", as often
+ one function contains logic for multiple actions. Thus in order to not
+ mix concepts form different actions under one section, parts of code not
+ related to the section being documented have been left out.
+
+**With JavaScript**
+
+In this case, the objective is to call the function ``taler.offerContractFrom()`` into the user browser, which will then retrieve the
+contract. In order to do that, we return a HTML page, whose
+template is in ``talerfrontends/blog/templates/purchase.html``,
+that imports ``taler-wallet-lib.js``, so that the function
+``taler.offerContractFrom()`` can be invoked into the user's
+browser.
+
+The server side handler for a offer URL needs to render ``purchase.html`` by passing
+the right parameters to ``taler.offerContractFrom()``.
+
+The rendering is done by the ``article`` function at ``talerfrontends/blog/blog.py``,
+and is done by Flask's ``render_template()``, see below.
+
+.. sourcecode:: python
+
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ ...
+ ...
+
+ return render_template('templates/purchase.html',
+ article_name=name,
+ no_contract=1,
+ contract_url=quote(contract_url),
+ data_attribute="data-taler-contractoffer=%s" % contract_url)
+
+After the rendering, (part of) ``purchase.html`` will look like shown below.
+
+.. sourcecode:: html
+
+ ...
+ <script src="/static/web-common/taler-wallet-lib.js" type="application/javascript"></script>
+ <script src="/static/purchase.js" type="application/javascript"></script>
+ ...
+ <meta name="contract_url" value="https://shop.demo.taler.net/generate-contract?article_name=Appendix_A:_A_Note_on_Software">
+
+ ...
+ ...
+
+ <div id="ccfakeform" class="fade">
+ <p>
+ Oops, it looks like you don't have a Taler wallet installed. Why don't you enter
+ all your credit card details before reading the article? <em>You can also
+ use GNU Taler to complete the purchase at any time.</em>
+ </p>
+
+ <form>
+ First name<br> <input type="text"></input><br>
+ Family name<br> <input type="text"></input><br>
+ Age<br> <input type="text"></input><br>
+ Nationality<br> <input type="text"></input><br>
+ Gender<br> <input type="radio" name"gender">Male</input>
+ CC number<br> <input type="text"></input><br>
+ <input type="radio" name="gender">Female</input><br>
+ </form>
+ <form method="get" action="/cc-payment/{{ article_name }}">
+ <input type="submit"></input>
+ </form>
+ </div>
+
+ <div id="talerwait">
+ <em>Processing payment with GNU Taler, please wait <span id="action-indicator"></span></em>
+ </div>
+ ...
+
+The script ``purchase.js`` is now in charge of implementing the behaviour we seek.
+It needs to register two handlers: one called whenever the wallet is detected in the
+browser, the other if the user has no wallet installed.
+
+That is done with:
+
+.. sourcecode:: javascript
+
+ taler.onPresent(handleWalletPresent);
+ taler.onAbsent(handleWalletAbsent);
+
+Note that the ``taler`` object is exported by ``taler-wallet-lib.js``, and contains all
+is needed to communicate with the wallet.
+
+
+``handleWalletAbsent`` doesn't need to do much: it has to only hide the "please wait"
+message and uncover the credit card pay form. See below.
+
+.. sourcecode:: javascript
+
+ function handleWalletAbsent() {
+ // Hide "please wait" message
+ document.getElementById("talerwait").style.display = "none";
+ // Uncover credit card pay form
+ document.body.style.display = "";
+ }
+
+On the other hand, ``handleWalletPresent`` needs to firstly hide the credit card
+pay form and show the "please wait" message. After that, it needs to fetch the
+contract URL from the responsible ``meta`` tag, and finally invoke ``taler.offerContractFrom()`` using it. See below both parts.
+
+.. sourcecode:: javascript
+
+ function handleWalletPresent() {
+ // Hide credit card paywall
+ document.getElementById("ccfakeform").style.display = "none";
+ // Show "please wait" message
+ document.getElementById("talerwait").style.display = "";
+ ...
+ ...
+ // Fetch contract URL from 'meta' tag.
+ let contract_url = document.querySelectorAll("[name=contract_url]")[0];
+ // If this call is successful, it will obtain the contract,
+ // hand it to the wallet, so the wallet can eventually
+ // show it to the user.
+ taler.offerContractFrom(decodeURIComponent(contract_url.getAttribute("value")));
+ ...
+ }
+
+.. note::
+
+ In order to get our code validated by W3C validators, we can't have inline
+ JavaScript in our pages, we are forced to import any used script instead.
+
+**Without JavaScript**
+
+This case is handled by the function ``article`` defined in
+``talerfrontends/blog/blog.py``. Its objective is to set the "402 Payment
+Required" HTTP status code, and the HTTP header ``X-Taler-Contract-Url``
+to the actual contract's URL for this purchase.
+
+Upon returning such a response, the wallet will automatically fetch the
+contract from the URL indicated by ``X-Taler-Contract-Url``, and show it
+to the user.
+
+Below is shown how the function ``article`` prepares and returns such a
+response.
+
+.. sourcecode:: python
+
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ ...
+ ...
+
+ # Create response.
+ response = make_response(render_template('templates/fallback.html'), 402)
+ # Set "X-Taler-Contract-Url" header to the contract's URL.
+ response.headers["X-Taler-Contract-Url"] = contract_url
+ return response
+
+The ``make_response`` function is exported by Flask, so it's beyond the scope
+of this document to explain it; however, it returns a "response object" having
+the "402 Payment Required" as HTTP status code, and the
+HTML file ``talerfrontends/blog/templates/fallback.html`` as the body.
+``fallback.html`` contains the credit card pay form, so that if the wallet is
+not installed, the browser would keep that page shown.
+
+``contract_url`` is defined in the earlier steps of the same function; however,
+in this example it looks like:
+
+ `https://shop.demo.taler.net/essay/generate-contract?article_name=Appendix_A:_A_Note_on_Software`.
+
+The frontend will also have to provide the contract. That is done
+by the handler ``generate_contract``, defined in
+``talerfrontends/blog/blog.py``. See below.
+
+.. sourcecode:: python
+
+ def generate_contract():
+ now = int(time.time())
+ tid = random.randint(1, 2**50)
+ article_name = expect_parameter("article_name")
+ contract = make_contract(article_name=article_name, tid=tid, timestamp=now)
+ contract_resp = sign_contract(contract)
+ logger.info("generated contract: %s" % str(contract_resp))
+ return jsonify(**contract_resp)
+
+
+Its task is to feed the ``make_contract`` subroutine with all the
+values it needs to generate a contract. Those values are: the timestamp
+for the contract, the transaction ID, and the article name; respectively,
+``now``, ``tid``, and ``article_name``.
+
+After ``make_contract`` returns, the variable ``contract`` will hold a
+`dict` type that complies with a contract :ref:`proposition <proposition>`.
+We then call ``sign_contract`` feeding it with the proposition, so that
+it can forward it to the backend and return it signed. Finally we return
+the signed proposition, complying with the :ref:`Offer <contract>` object.
+
+For simplicity, any article costs the same price, so the frontend
+doesn't need to map articles to prices.
+
+Both ``make_contract`` and ``sign_contract`` are defined in
+``talerfrontends/blog/helpers.py``.
+
+At this point, the user can accept the contract, which triggers the wallet
+to visit the fulfillment page. The main logic for a fulfillment page handler
+is to (1) return the claimed product, if it has been paid, or (2) instruct the
+wallet to send the payment.
+
+-----------------
+Fulfillment logic
+-----------------
+
+The state accounts for a product being paid or not, so the fulfillment handler
+will firstly check that:
+
+.. sourcecode:: python
+
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ # Get list of payed articles from the state
+ payed_articles = session.get("payed_articles", [])
+
+ if name in payed_articles:
+ ...
+ # The articles has been paid, so return it to the
+ # customer.
+ return send_file(get_article_file(article))
+ ...
+
+In case the article has not been paid yet, the fulfillment handler needs
+to `reconstruct` the contract, in order to get a precise reference about the
+purchase in being served.
+
+All the information needed to reconstruct the contract is contained in the
+fulfillment URL parameters. See below the URL layout:
+
+ `https://shop.demo.taler.net/essay/Appendix_A:_A_Note_on_Software?uuid=<CONTRACT-HASHCODE>&timestamp=<TIMESTAMP>tid=<TRANSACTION_ID>`
+
+The way the contract is reconstructed is exactly the same as it was generated
+in the previous steps: we need to call ``make_contract`` to get the original
+:ref:`proposition <proposition>` and then ``sign_contract``. Recall that aside
+from allowing the backend to add missing fields to the proposition, ``sign_contract``
+returns the contract hashcode also, that we should compare with the ``uuid``
+parameter provided by the wallet.
+
+In our blog, all the fulfillment logic is implemented in the function ``article``,
+defined in ``talerfrontends/blog/blog.py``. It is important to note that this
+function is `the same` function that runs the offer URL; in fact, as long as your
+URL design allows it, it is not mandatory to split up things. In our example, the
+offer URL differs from the fulfillment URL respect to the number (and type) of
+parameters, so the ``article`` function can easily decide whether it has to handle
+a "offer" or a "fulfillment" case. See below how the function detects the right
+case and reconstructs the contract.
+
+.. sourcecode:: python
+
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+
+ ...
+ hc = request.args.get("uuid")
+ tid_str = request.args.get("tid")
+ timestamp_str = request.args.get("timestamp")
+ if hc is None or tid_str is None or timestamp_str is None:
+ # Offer URL case.
+ contract_url = make_url("/generate-contract", ("article_name",name))
+ ... # Go on operating the offer URL and return
+
+ # Fulfillment URL case from here on.
+ try:
+ tid = int(tid_str)
+ except ValueError:
+ raise MalformedParameterError("tid")
+ try:
+ timestamp = int(timestamp_str)
+ except ValueError:
+ raise MalformedParameterError("timestamp")
+
+ restored_contract = make_contract(article_name=name, tid=tid, timestamp=timestamp)
+ contract_resp = sign_contract(restored_contract)
+
+ # Return error if uuid mismatch with the hashcode coming from the backend
+ if contract_resp["H_contract"] != hc:
+ e = jsonify(error="contract mismatch", was=hc, expected=contract_resp["H_contract"])
+ return e, 400
+
+ # We save the article's name in the state since after
+ # receiving the payment this value will point to the
+ # article to be delivered to the customer. Note how the
+ # contract's hashcode is used to index the state.
+ session[hc] = si = session.get(hc, {})
+ si['article_name'] = name
+
+
+After a successful contract reconstruction, the handler needs to instruct
+the wallet to actually send the payment. There are as usual two ways this
+can be accomplished: with and without JavaScript.
+
+**With JavaScript**
+
+..
+ Mention that the template is the same we used for a offer URL!
+
+We return a HTML page, whose template is in
+``talerfrontends/blog/templates/purchase.html``, that imports ``taler-wallet-lib.js``,
+so that the function ``taler.executePayment()`` can be invoked into the user's
+browser.
+
+The fulfillment handler needs to render ``purchase.html`` so that the right
+parameters get passed to ``taler.executePayment()``.
+
+See below how the function ``article`` does the rendering.
+
+.. sourcecode:: python
+
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+
+ ...
+ ...
+
+ return render_template('templates/purchase.html',
+ hc=hc,
+ pay_url=quote(pay_url),
+ offering_url=quote(offering_url),
+ article_name=name,
+ no_contract=0,
+ data_attribute="data-taler-executecontract=%s,%s,%s" % (hc, pay_url, offering_url))
+
+After the rendering, (part of) ``purchase.html`` will look like shown below.
+
+.. sourcecode:: html
+
+ ...
+ <script src="/static/web-common/taler-wallet-lib.js" type="application/javascript"></script>
+ <script src="/static/purchase.js" type="application/javascript"></script>
+ ...
+ <meta name="pay_url" value="https://shop.demo.taler.net/pay">
+ <meta name="offering_url" value="https://shop.demo.taler.net/essay/Appendix_A:_A_Note_on_Software">
+ <!-- Fake hashcode -->
+ <meta name="hc" value="D7D5HDJRP36GTBBRGHXP7204VR773HHQBNFFCY5YY4P18026PAJ0">
+
+ ...
+ ...
+
+ <div id="ccfakeform" class="fade">
+ <p>
+ Oops, it looks like you don't have a Taler wallet installed. Why don't you enter
+ all your credit card details before reading the article? <em>You can also
+ use GNU Taler to complete the purchase at any time.</em>
+ </p>
+
+ <form>
+ <!-- Credit card pay form. -->
+ </form>
+ </div>
+
+ <div id="talerwait">
+ <em>Processing payment with GNU Taler, please wait <span id="action-indicator"></span></em>
+ </div>
+ ...
+
+The script ``purchase.js`` is now in charge of calling ``taler.executePayment()``.
+It will try to register two handlers: one called whenever the wallet is detected in the
+browser, the other if the user has no wallet installed.
+
+That is done with:
+
+.. sourcecode:: javascript
+
+ taler.onPresent(handleWalletPresent);
+ taler.onAbsent(handleWalletAbsent);
+
+.. note::
+
+ So far, the template and the imported script (``purchase.js``)
+ are exactly the same as the offer URL case, since we use them
+ for both cases. See below how the script distinguishes "offer"
+ from "fulfillment" case.
+
+Note that the ``taler`` object is exported by ``taler-wallet-lib.js``, and contains all
+is needed to communicate with the wallet.
+
+
+``handleWalletAbsent`` doesn't need to do much: it has to only hide the "please wait"
+message and uncover the credit card pay form. See below.
+
+.. sourcecode:: javascript
+
+ function handleWalletAbsent() {
+ // Hide "please wait" message
+ document.getElementById("talerwait").style.display = "none";
+ // Uncover credit card pay form
+ document.body.style.display = "";
+ }
+
+On the other hand, ``handleWalletPresent`` needs to firstly hide the credit card
+pay form and show the "please wait" message. After that, it needs to fetch the
+needed parameters from the responsible ``meta`` tags, and finally invoke
+``taler.offerContractFrom()`` using those parameters. See below its whole definition.
+Note, that since we are in the fulfillment case, the credit card pay form is `almost`
+useless, as it is highly unlikely that the wallet is not installed.
+
+.. sourcecode:: javascript
+
+ function handleWalletPresent() {
+ // Hide the credit card pay form
+ document.getElementById("ccfakeform").style.display = "none";
+ // Show "please wait" message
+ document.getElementById("talerwait").style.display = "";
+
+ // The `no_contract` value is provided by the function `article` via a
+ // 'meta' tag in the template. When this value equals 1, then we are in the
+ // "offer" URL case, otherwise we are in the "fulfillment" URL case.
+ let no_contract = document.querySelectorAll("[name=no_contract]")[0];
+ if (Number(no_contract.getAttribute("value"))) {
+ // "Offer" case
+ let contract_url = document.querySelectorAll("[name=contract_url]")[0];
+ taler.offerContractFrom(decodeURIComponent(contract_url.getAttribute("value")));
+ }
+ else {
+ // "Fulfillment" case.
+ let hc = document.querySelectorAll("[name=hc]")[0];
+ let pay_url = document.querySelectorAll("[name=pay_url]")[0];
+ let offering_url = document.querySelectorAll("[name=offering_url]")[0];
+ taler.executePayment(hc.getAttribute("value"),
+ decodeURIComponent(pay_url.getAttribute("value")),
+ decodeURIComponent(offering_url.getAttribute("value")));
+ }
+ }
+
+Once the browser executes ``taler.executePayment(...)``, the wallet will send the coins
+to ``pay_url``. Once the payment succeeds, the wallet will again visit the
+fulfillment URL, this time getting the article thanks to the "payed" status set by
+the ``pay_url`` handler.
+
+**Without JavaScript**
+
+This case is handled by the function ``article`` defined in
+``talerfrontends/blog/blog.py``. Its objective is to set the "402 Payment
+Required" HTTP status code, along with the HTTP headers ``X-Taler-Contract-Hash``,
+``X-Taler-Pay-Url``, and ``X-Taler-Offer-Url``.
+
+..
+ FIXME:
+ Are those three parameters anywhere, at least 'kindof' introduced?
+
+Upon returning such a response, the wallet will automatically send the
+payment to the URL indicated in ``X-Taler-Pay-Url``.
+
+The excerpt below shows how the function ``article`` prepares and returns such a
+response.
+
+.. sourcecode:: python
+
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ ...
+
+ # 'make_response' is exported by Flask. It returns a
+ # "response object" with customizable status code, HTTP
+ # headers and body
+ response = make_response(render_template('templates/fallback.html'), 402)
+ response.headers["X-Taler-Contract-Hash"] = hc
+ response.headers["X-Taler-Pay-Url"] = pay_url
+ response.headers["X-Taler-Offer-Url"] = offering_url
+ return response
+
+The template ``fallback.html`` contains the credit card pay form, which will be
+used in the rare case where the wallet would not be detected in a fulfillment
+session. Once the payment succeeds, the wallet will again visits the
+fulfillment URL, this time getting the article thanks to the "payed" status set by
+the ``pay_url`` handler.
+
+---------
+Pay logic
+---------
+
+The pay handler for the blog is implemented by the function
+``pay`` at ``talerfrontends/blog/blog.py``. Its main duty is
+to receive the :ref:`deposit permission <DepositPermission>`
+from the wallet, forward it to the backend, and return the outcome
+to the wallet. See below the main steps of its implementation.
+
+.. sourcecode:: python
+
+ def pay():
+ # Get the uploaded deposit permission
+ deposit_permission = request.get_json()
+
+ if deposit_permission is None:
+ e = jsonify(error="no json in body")
+ return e, 400
+
+ # Pick the contract's hashcode from deposit permission
+ hc = deposit_permission.get("H_contract")
+
+ # Return error if no hashcode was found
+ if hc is None:
+ e = jsonify(error="malformed deposit permission", hint="H_contract missing")
+ return e, 400
+
+ # Get a handle to the state for this contract, using the
+ # hashcode from deposit permission as the index
+ si = session.get(hc)
+
+ # If no session was found for this contract, then either it
+ # expired or one of the hashcodes (the one we got from
+ # reconstructing the contract in the fulfillment handler,
+ # and the one we just picked from the deposit permission)
+ # is bogus. Note how using the contract's hashcode as index
+ # makes harder for the wallet to use different hashcodes
+ # in different steps of the protocol.
+ if si is None:
+ e = jsonify(error="no session for contract")
+ return e, 400
+
+ # Forward the deposit permission to the backend
+ r = requests.post(urljoin(BACKEND_URL, 'pay'), json=deposit_permission)
+
+ # Return error if the backend returned a HTTP status code
+ # other than 200 OK
+ if 200 != r.status_code:
+ raise BackendError(r.status_code, r.text)
+
+ # The payment went through..
+ ...
+
+ # Resume the article name
+ article = si["article_name"]
+
+ # Set the article's state as "payed". This is realized by
+ # appending it to a *list* of articles the customer is currently
+ # allowed to read.
+ payed_articles = session["payed_articles"] = session.get("payed_articles", [])
+ if article not in payed_articles:
+ payed_articles.append(article)
+
+ ...
+
+ # Return success
+ return r.text, 200
diff --git a/docs/exts/__pycache__/tsref.cpython-35.pyc b/docs/exts/__pycache__/tsref.cpython-35.pyc
new file mode 100644
index 00000000..abc92f00
--- /dev/null
+++ b/docs/exts/__pycache__/tsref.cpython-35.pyc
Binary files differ
diff --git a/docs/exts/tsref.py b/docs/exts/tsref.py
new file mode 100644
index 00000000..8187f67f
--- /dev/null
+++ b/docs/exts/tsref.py
@@ -0,0 +1,233 @@
+"""
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015 GNUnet e.V. and INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Lesser General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+"""
+
+"""
+This extension adds a new lexer "tsref" for TypeScript, which
+allows reST-style links inside comments (`LinkName`_),
+and semi-automatically adds links to the definition of types.
+
+For type TYPE, a reference to tsref-type-TYPE is added.
+
+Known bugs and limitations:
+ - The way the extension works right now interferes wiht
+ Sphinx's caching, the build directory should be cleared
+ before every build.
+"""
+
+
+from pygments.util import get_bool_opt
+from pygments.token import Name, Comment, Token, _TokenType
+from pygments.filter import Filter
+from sphinx.highlighting import PygmentsBridge
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.pygments_styles import SphinxStyle
+from pygments.formatters import HtmlFormatter
+from docutils import nodes
+from docutils.nodes import make_id
+import re
+
+
+_escape_html_table = {
+ ord('&'): u'&amp;',
+ ord('<'): u'&lt;',
+ ord('>'): u'&gt;',
+ ord('"'): u'&quot;',
+ ord("'"): u'&#39;',
+}
+
+
+class LinkingHtmlFormatter(HtmlFormatter):
+ def __init__(self, **kwargs):
+ super(LinkingHtmlFormatter, self).__init__(**kwargs)
+ self._builder = kwargs['_builder']
+
+ def _fmt(self, value, tok):
+ cls = self._get_css_class(tok)
+ href = tok_getprop(tok, "href")
+ caption = tok_getprop(tok, "caption")
+ content = caption if caption is not None else value
+ if href:
+ value = '<a style="color:inherit;text-decoration:underline" href="%s">%s</a>' % (href, content)
+ if cls is None or cls == "":
+ return value
+ return '<span class="%s">%s</span>' % (cls, value)
+
+ def _format_lines(self, tokensource):
+ """
+ Just format the tokens, without any wrapping tags.
+ Yield individual lines.
+ """
+ lsep = self.lineseparator
+ escape_table = _escape_html_table
+
+ line = ''
+ for ttype, value in tokensource:
+ link = get_annotation(ttype, "link")
+
+ parts = value.translate(escape_table).split('\n')
+
+ if len(parts) == 0:
+ # empty token, usually should not happen
+ pass
+ elif len(parts) == 1:
+ # no newline before or after token
+ line += self._fmt(parts[0], ttype)
+ else:
+ line += self._fmt(parts[0], ttype)
+ yield 1, line + lsep
+ for part in parts[1:-1]:
+ yield 1, self._fmt(part, ttype) + lsep
+ line = self._fmt(parts[-1], ttype)
+
+ if line:
+ yield 1, line + lsep
+
+
+class MyPygmentsBridge(PygmentsBridge):
+ def __init__(self, builder, trim_doctest_flags):
+ self.dest = "html"
+ self.trim_doctest_flags = trim_doctest_flags
+ self.formatter_args = {'style': SphinxStyle, '_builder': builder}
+ self.formatter = LinkingHtmlFormatter
+
+
+class MyHtmlBuilder(StandaloneHTMLBuilder):
+ name = "html-linked"
+ def init_highlighter(self):
+ if self.config.pygments_style is not None:
+ style = self.config.pygments_style
+ elif self.theme:
+ style = self.theme.get_confstr('theme', 'pygments_style', 'none')
+ else:
+ style = 'sphinx'
+ self.highlighter = MyPygmentsBridge(self, self.config.trim_doctest_flags)
+
+ def write_doc(self, docname, doctree):
+ self._current_docname = docname
+ super(MyHtmlBuilder, self).write_doc(docname, doctree)
+
+
+def get_annotation(tok, key):
+ if not hasattr(tok, "kv"):
+ return None
+ return tok.kv.get(key)
+
+
+def copy_token(tok):
+ new_tok = _TokenType(tok)
+ # This part is very fragile against API changes ...
+ new_tok.subtypes = set(tok.subtypes)
+ new_tok.parent = tok.parent
+ return new_tok
+
+
+def tok_setprop(tok, key, value):
+ tokid = id(tok)
+ e = token_props.get(tokid)
+ if e is None:
+ e = token_props[tokid] = (tok, {})
+ _, kv = e
+ kv[key] = value
+
+
+def tok_getprop(tok, key):
+ tokid = id(tok)
+ e = token_props.get(tokid)
+ if e is None:
+ return None
+ _, kv = e
+ return kv.get(key)
+
+
+link_reg = re.compile(r"`([^`<]+)\s*(?:<([^>]+)>)?\s*`_")
+
+# Map from token id to props.
+# Properties can't be added to tokens
+# since they derive from Python's tuple.
+token_props = {}
+
+
+class LinkFilter(Filter):
+ def __init__(self, app, **options):
+ self.app = app
+ Filter.__init__(self, **options)
+
+ def filter(self, lexer, stream):
+ id_to_doc = self.app.env.domaindata.get("_tsref", {})
+ for ttype, value in stream:
+ if ttype in Token.Keyword.Type:
+ defname = make_id('tsref-type-' + value);
+ t = copy_token(ttype)
+ if defname in id_to_doc:
+ docname = id_to_doc[defname]
+ href = self.app.builder.get_target_uri(docname) + "#" + defname
+ tok_setprop(t, "href", href)
+
+ yield t, value
+ elif ttype in Token.Comment:
+ last = 0
+ for m in re.finditer(link_reg, value):
+ pre = value[last:m.start()]
+ if pre:
+ yield ttype, pre
+ t = copy_token(ttype)
+ x1, x2 = m.groups()
+ if x2 is None:
+ caption = x1.strip()
+ id = make_id(x1)
+ else:
+ caption = x1.strip()
+ id = make_id(x2)
+ if id in id_to_doc:
+ docname = id_to_doc[id]
+ href = self.app.builder.get_target_uri(docname) + "#" + id
+ tok_setprop(t, "href", href)
+ tok_setprop(t, "caption", caption)
+ else:
+ self.app.builder.warn("unresolved link target in comment: " + id)
+ yield t, m.group(1)
+ last = m.end()
+ post = value[last:]
+ if post:
+ yield ttype, post
+ else:
+ yield ttype, value
+
+
+
+def remember_targets(app, doctree):
+ docname = app.env.docname
+ id_to_doc = app.env.domaindata.get("_tsref", None)
+ if id_to_doc is None:
+ id_to_doc = app.env.domaindata["_tsref"] = {}
+ for node in doctree.traverse():
+ if not isinstance(node, nodes.Element):
+ continue
+ ids = node.get("ids")
+ if ids:
+ for id in ids:
+ id_to_doc[id] = docname
+
+
+def setup(app):
+ from sphinx.highlighting import lexers
+ from pygments.lexers import TypeScriptLexer
+ from pygments.token import Name
+ from pygments.filters import NameHighlightFilter
+ lexer = TypeScriptLexer()
+ lexer.add_filter(LinkFilter(app))
+ app.add_lexer('tsref', lexer)
+ app.add_builder(MyHtmlBuilder)
+ app.connect("doctree-read", remember_targets)
diff --git a/docs/global_licensing.rst b/docs/global_licensing.rst
new file mode 100644
index 00000000..7a5e8226
--- /dev/null
+++ b/docs/global_licensing.rst
@@ -0,0 +1,215 @@
+===========================
+Taler licensing information
+===========================
+
+This file gives an overview of all Taler component's licensing and of
+runtime dependencies thereof. For "component" here is meant a set of
+source files which can be retrieved from a single repository. If
+components consist of sources under different licensing regimes, i.e.
+because we want to enable third party developments to easily integrate
+with Taler, those are described as well.
+
+All components are generally released under Lesser GPL, GPL or Affero
+GPL. The main strategy is for libraries that third parties may need
+to integrate with Taler to be under LGPL, standalone binaries and
+testcases to be under GPL, and Web servers implementing Web services
+to be under AGPL.
+
++++++++++++++++++++++++++
+API (git://taler.net/api)
++++++++++++++++++++++++++
+
+The specification has been jointly developed by INRIA and by individuals
+being under the juridical subject called 'GNUnet e.V.'. For each source
+file, the header indicated whose is holding the copyright, since some
+parts have been taken "verbatim" from the GNUnet e.V. foundation, and
+some other have been developed at INRIA "ex novo".
+
+Generally, GNU GPLv3 license is used for them; see COPYING.GPL.
+
+
+--------------------
+Runtime dependencies
+--------------------
+This component has no runtime dependencies as it is supposed to generate
+HTML.
+
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Firefox/Android/Python Wallet (git://taler.net/wallet)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This project includes contributions from INRIA and GNUnet
+e.V. developers. Please refer to each source file to obtain
+information about the copyright holder. The GNU GPLv3 is used as the
+license for Wallets. Some components may be under the LGPL.
+
+--------------------
+Runtime dependencies
+--------------------
+
+The following list encompasses all the runtime dependencies for this
+project, and gives the copyright holder for each of them:
+
+* libgnunetutil: GPLv3+, GNUnet e.V.
+* libgnunetjson: GPLv3+, GNUnet e.V.
+* libgcrypt: LGPL, Free Software Foundation
+* libunistring: LGPL, Free Software Foundation
+* Python: Python Software Foundation License, LGPL-Compatible, Python Software Foundation
+* Mozilla Firefox: Mozilla Public License, LGPL-Compatible, Mozilla Foundation
+
+
++++++++++++++++++++++++++++++++++++++++++++++++++++
+WebExtensions Wallet (git://taler.net/wallet-webex)
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The TypeScript code was developed 100% at INRIA, but the project
+involves compiling libgnunetutil and libtalerutil to JavaScript, and
+thus depends on software from GNUnet e.V.
+
+Each source carries its own copyright holder(s), but it is generally
+licensed under GPLv3+.
+
+--------------------
+Runtime dependencies
+--------------------
+
+The following list encompasses all the runtime dependencies for this
+project, and gives the copyright holder for each of them:
+
+* libgnunetutil: GPLv3+, GNUnet e.V.
+* libgnunetjson: GPLv3+, GNUnet e.V.
+* libgcrypt: LGPL, Free Software Foundation
+* libunistring: LGPL, Free Software Foundation
+
+Note that these dependencies are compiled into the extension and do
+not appear as separate binary files.
+
+
++++++++++++++++++++++++++++++++++++
+Merchant (git://taler.net/merchant)
++++++++++++++++++++++++++++++++++++
+
+This project contains code under two different licenses, and whose
+copyright is held by INRIA and/or GNUnet e.V.. Please refer to each
+source file to know which party holds the copyright.
+
+Source files are located in the following directories:
+
+* src/lib/
+* src/backend/
+* src/backenddb/
+* src/include/
+* src/tests/
+* examples/blog/
+* examples/shop/
+* copylib/
+
+In examples/blog/articles/ we included a book by Richard Stallman.
+It comes with its own permissive license (see COPYING in the
+directory).
+
+
+The merchant's backend (i.e. all the code in src/backend/) is under
+the GNU Affero GPL as it depends on libgnunetutil. Note that the use
+of the Affero GPL has little impact as the backend is not supposed to
+be directly accessible to the Internet). The license for this code is
+in COPYING.GPL and COPYING.AGPL.
+
+The merchant's frontend logic (i.e. JavaScript interacting with
+the wallet, sample code for a shop) is under the GNU LGPL (but
+we may choose to change this to be in the public domain or
+BSD-licensed if necessary; the code is so short that there is
+anyway the question whether it is copyrightable). Under this same
+license, it comes the merchant library (src/lib/) as it can be linked
+with more diverse licensed software. The license text for this code
+is in COPYING.LGPL.
+
+
+
+--------------------
+Runtime dependencies
+--------------------
+
+The following list encompasses all the runtime dependencies for this
+project, and gives the copyright holder for each of them:
+
+* libjansson: MIT License, AGPL- and LGPL-Compatible, owned by Petri Lehtinen and other individuals
+* libgcrypt: LGPL, owned by Free Software Foundation
+* postgresql: PostgreSQL License, AGPL- and LGPL-Compatible, owned by The PostgreSQL Global Development Group
+* libgnunetutil (in all of its variants): GPLv3+, owned by GNUnet e.V.
+* PHP: PHP License, AGPL- and LGPL-Compatible, owned by The PHP Group
+
++++++++++++++++++++++++++++
+Bank (git://taler.net/bank)
++++++++++++++++++++++++++++
+
+---------
+Licensing
+---------
+
+This project has been developed by INRIA. For each source file, the
+header indicated whose is holding the copyright. The licensing plan
+for the bank is to use the Affero GPLv3+.
+
+Source files of interest are located in the following directories:
+(The repository holds also scaffolded files autogenerated by Django,
+which do not have legal significance in this context.)
+
+* TalerBank/Bank/
+* TalerBank/Bank/templates/
+* TalerBank/my-static/
+* website/
+
+--------------------
+Runtime dependencies
+--------------------
+
+The following list encompasses all the runtime dependencies for this
+project, and gives the copyright holder for each of them:
+
+* Django: BSD License, AGPL-Compatible, owned by Django Software Foundation
+* validictory: BSD License, AGPL-Compatible, owned by James Turk
+* django-simple-math-captcha: Apache Software License, LGPL-Compatible (FIXME), Brandon Taylor
+* requests: Apache2 License, AGPL-Compatible, owned by Kenneth Reitz
+* Python: Python Software Foundation License, AGPL-Compatible, Python Software Foundation
+* PHP: PHP License, AGPL-Compatible, owned by The PHP Group
+
+
+.. _exchange-repo:
+
++++++++++++++++++++++++++++++++++++
+Exchange (git://taler.net/exchange)
++++++++++++++++++++++++++++++++++++
+
+This component is based on code initially developed in Munich for
+GNUnet e.V. Most recent improvements and maintenance has been done at
+Inria. The copyright is thus shared between both institutions.
+
+The licensing for exported libraries to access the exchange is LGPL,
+the exchange itself is under AGPL, and testcases and standalone
+binaries are under GPL.
+
+
+--------------------
+Runtime dependencies
+--------------------
+
+The following list encompasses all the runtime dependencies for this
+project, and gives the copyright holder for each of them:
+
+* libjansson: MIT License, AGPL- and LGPL-Compatible, owned by Petri Lehtinen and other individuals
+* libgcrypt: LGPL, owned by Free Software Foundation
+* postgresql: PostgreSQL License, AGPL- and LGPL-Compatible, owned by The PostgreSQL Global Development Group
+* libgnunetutil (in all of its variants): GPLv3+, owned by GNUnet e.V.
+* libgnunetjson: GPLv3+, GNUnet e.V.
+
+
++++++++++++++++++++++++++++++++++++++++++
+Web includes (git://taler.net/web-common)
++++++++++++++++++++++++++++++++++++++++++
+
+All copyright owned by INRIA (but questionable whether creativity
+threshold for copyright is even met).
+
+Sources are licensed under the GNU LGPL.
diff --git a/docs/glossary.rst b/docs/glossary.rst
new file mode 100644
index 00000000..d9a6cfa7
--- /dev/null
+++ b/docs/glossary.rst
@@ -0,0 +1,106 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Christian Grothoff
+
+.. _glossary:
+
+==============
+Taler Glossary
+==============
+
+.. glossary::
+
+ auditor
+ trusted third party that verifies that the exchange is operating correctly
+
+ bank
+ traditional financial service provider who offers wire :term:`transfers <transfer>` between accounts
+
+ coin
+ coins are individual token representing a certain amount of value, also known as the :term:`denomination` of the coin
+
+ contract
+ specification of the details of a transaction, specifies the payment obligations for the customer (i.e. the amount), the deliverables of the merchant and other related information, such as deadlines or locations
+
+ denomination
+ unit of currency, specifies both the currency and the face value of a :term:`coin`
+
+ denomination key
+ RSA key used by the exchange to certify that a given :term:`coin` is valid and of a particular :term:`denomination`
+
+ deposit
+ operation by which a merchant passes coins to an exchange, expecting the exchange to credit his :term:`bank` account in the future using a wire :term:`transfer`
+
+ dirty
+ a :term:`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 first
+
+ extension
+ implementation of a :term:`wallet` for browsers
+
+ fresh coin
+ a :term:`coin` is fresh if its public key is only known to the customer
+
+ master key
+ offline key used by the exchange to certify denomination keys and message signing keys
+
+ message signing key
+ key used by the exchange to sign online messages, other than coins
+
+ owner
+ a :term:`coin` is owned by the entity that knows the private key of the coin
+
+ proof
+ message that cryptographically demonstrates that a particular claim is correct
+
+ reserve
+ funds set aside for future use; either the balance of a customer at the exchange ready for :term:`withdrawal`, or the funds kept in the exchange's bank account to cover obligations from coins in circulation
+
+ refreshing
+ operation by which a :term:`dirty` :term:`coin` is converted into one or more :fresh: coins
+
+ refund
+ operation by which a merchant steps back from the right to funds that he obtained from a :term:`deposit` operation, giving the right to the funds back to the customer
+
+ sharing
+ users can share ownership of a :term:`coin` by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time.
+
+ signing key
+ see message signing key.
+
+ spending
+ operation by which a customer gives a merchant the right to :term:`deposit` coins in return for merchandise
+
+ transfer
+ method of sending funds between :term:`bank` accounts
+
+ transaction
+ method by which ownership is exclusively transferred from one entity to another
+
+ transaction id
+ unique number by which a merchant identifies a :term:`transaction`
+
+ wallet
+ software running on a customer's computer; withdraws, stores and spends coins
+
+ wire transfer
+ see :term:`transfer`
+
+ wire transfer identifier
+ subject of a wire :term:`transfer`; usually a random string to uniquely identify the :term:`transfer`
+
+ withdrawal
+ operation by which a :term:`wallet` can convert funds from a reserve to fresh coins
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..356811d2
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,103 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 GNUnet e.V.
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+
+GNU Taler Documentation
+=======================
+
+We are building an anonymous, taxable payment system using modern
+cryptography. Customers will use traditional money transfers to send
+money to a digital Exchange and in return receive (anonymized) digital
+cash. Customers can use this digital cash to anonymously pay
+Merchants. Merchants can redeem the digital cash for traditional
+money at the digital Exchange. As Merchants are not anonymous, they can
+be taxed, enabling income or sales taxes to be withheld by the state
+while providing anonymity for Customers.
+
+Cryptography is used to ensure that none of the participants can
+defraud the others without being detected immediately; however, in
+practice a fradulent Exchange might go bankrupt instead of paying the
+Merchants and thus the Exchange will need to be audited regularly like
+any other banking institution.
+
+The system will be based on free software and open protocols.
+
+In this document, we describe the REST-based APIs between the various
+components, internal architecture of key components, and how to get them
+installed.
+
+-----------------
+Operator Handbook
+-----------------
+
+The *Operator Handbook* is for people who want to run a exchange or a merchant.
+It focuses on how to install, configure and run the required software.
+
+.. toctree::
+ :maxdepth: 2
+
+ global_licensing
+ configuration-basics
+ operate-exchange
+ operate-merchant
+ versioning
+
+------------------------
+Web Integration Handbook
+------------------------
+
+The *Web Integration Handbook* is for those who want to interact with Taler
+wallets on their own website. Integrators will also have to be familiar with
+the material covered in the *Operator Handbook*.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ integration-general
+ integration-bank
+ integration-merchant
+ example-essay-store
+
+------------------
+Developer Handbook
+------------------
+
+The *Developer Handbook* brings developers up to speed who want to hack on the
+core components of the Taler reference implementation.
+
+.. toctree::
+ :maxdepth: 2
+
+ dev-wallet-wx
+ dev-exchange
+ dev-merchant
+ deployment.rst
+ releases.rst
+
+------------------
+Indices and tables
+------------------
+
+.. toctree::
+ :hidden:
+
+ glossary
+
+* :doc:`glossary`
+* :ref:`search`
diff --git a/docs/operate-exchange.rst b/docs/operate-exchange.rst
new file mode 100644
index 00000000..874b837c
--- /dev/null
+++ b/docs/operate-exchange.rst
@@ -0,0 +1,246 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
+======================
+Operating the Exchange
+======================
+
++++++++++++++
+Configuration
++++++++++++++
+
+The following data and facilities have to be set up, in order to run an exchange:
+
+* Keying
+* Serving
+* Currency
+* Bank account
+* Coins
+* Database
+
+In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.
+
+------
+Keying
+------
+
+The exchange works with three types of keys:
+
+* `master key`
+* `sign keys`
+* `denomination keys` (see section `Coins`)
+
+`master key`: in section `[exchange]`, edit the two following values:
+
+* `master_priv_file`: Path to the exchange's master private file.
+* `master_public_key`: Must specify the exchange's master public key.
+
+`sign keys`: the following two options under `[exchange_keys]` section control `sign keys`:
+
+* `signkey_duration`: How long should one signing key be used?
+* `lookahead_sign`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. See :ref:`keys-duration`.
+
+-------
+Serving
+-------
+
+The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this
+configuration *twice*, because it opens one connection for ordinary REST calls, and one
+for "/admin" and "/test" REST calls, because the operator may want to restrict the access to "/admin".
+
+The following values are to be configured under the section `[exchange]` and `[exchange-admin]`:
+
+* `serve`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
+* `port`: Set to the TCP port to listen on if `serve` Is `tcp`.
+* `unixpath`: set to the UNIX domain socket path to listen on if `serve` Is `unix`
+* `unixpath_mode`: number giving the mode with the access permissiON MASK for the `unixpath` (i.e. 660 = rw-rw----).
+
+The exchange can be started with the `-D` option to disable the administrative
+functions entirely. It is recommended that the administrative API is only
+accessible via a properly protected UNIX domain socket.
+
+--------
+Currency
+--------
+
+The exchange supports only one currency. This data is set under the respective
+option `currency` in section `[taler]`.
+
+------------
+Bank account
+------------
+
+Wireformat
+^^^^^^^^^^
+
+The wireformat is the protocol to be used between the exchange and the banks.
+The option is `wireformat`, under section `[exchange]`. The exchange currently supports
+the `test` wireformat. This wireformat is used for testing the system against a fictional bank.
+
+.. note::
+ The SEPA wireformat is work in progress.
+
+Incoming
+^^^^^^^^
+The bank account where the exchange gets money from customers is configured under
+the section `[exchange-wire-incoming-X]`, where `X` matches the value given to the
+option `wireformat`. This section contains only one option: `X_response_file`, which
+takes the path to a text file containing the exchange's bank account details in JSON
+format.
+
+The command line tool `taler-exchange-wire` is used to create such a file.
+For example, the utility may be invoked as follows::
+
+ $ taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json
+
+Note that the value given to option `-t` must match the value in the JSON's field ``"type"``.
+
+The generated file will be echoed by the exchange when serving :ref:`/wire <wire-req>` requests.
+
+Outgoing
+^^^^^^^^
+
+This exchange's bank account is used to give money to merchants, after successful :ref:`deposits <deposit-par>`
+operations. If `test` is the chosen wireformat, the outcoming bank account is configured by the following
+options under `[exchange-wire-outcoming-test]`:
+
+ * `exchange_account_numer`: which bank account number has the exchange
+ * `bank_uri`: base URL of the bank hosting the exchange bank account
+
+.. note::
+ The rationale behind having two bank accounts is that the exchange operator, as a security
+ measure, may want to instruct the bank that the incoming bank account is only supposed to
+ *receive* money.
+
+--------
+Database
+--------
+
+The option `db` under section `[exchange]` gets the DB backend's name the exchange
+is going to use. So far, only `db = postgres` is supported. After choosing the backend,
+it is mandatory to supply the connection string (namely, the database name). This is
+possible in two ways:
+
+* via an environment variable: `TALER_EXCHANGEDB_POSTGRES_CONFIG`.
+* via configuration option `db_conn_str`, under section `[exchangedb-BACKEND]`. For example, the demo exchange is configured as follows:
+
+.. code-block:: text
+
+ [exchange]
+ ...
+ db = postgres
+ ...
+
+ [exchangedb-postgres]
+ db_conn_str = postgres:///talerdemo
+
+-------------------------
+Coins (denomination keys)
+-------------------------
+
+Sections specifying denomination (coin) information start with "coin\_". By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. `[coin_eur_ct_10]` for a 10 cent piece. However, only the "coin\_" prefix is mandatory. Each "coin\_"-section must then have the following options:
+
+* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10".
+* `duration_withdraw`: How long can a coin of this type be withdrawn? This limits the losses incurred by the exchange when a denomination key is compromised.
+* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type?
+* `duration_spend`: How long is a coin of the given type valid? Smaller values result in lower storage costs for the exchange.
+* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`.
+* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`.
+* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`.
+* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin.
+
+-------------
+Keys duration
+-------------
+
+Both `signkeys` and `denom keys` have a :ref:`starting date <keys-duration>`. The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys
+whose starting date is younger than `lookahead_provide` will be issued by the exchange.
+
+.. _exchange-install:
+
+++++++++++++
+Installation
+++++++++++++
+
+Please install the following packages before proceeding with the exchange compilation.
+
+* autoconf >= 2.69
+* automake >= 1.14
+* libtool >= 2.4
+* autopoint >= 0.19
+* libltdl >= 2.4
+* libunistring >= 0.9.3
+* libcurl >= 7.26 (or libgnurl >= 7.26)
+* GNU libmicrohttpd >= 0.9.39
+* GNU libgcrypt >= 1.6
+* libjansson >= 2.7
+* Postgres >= 9.4, including libpq
+* libgnunetutil (from Git)
+* GNU Taler exchange (from Git)
+
+Except for the last two, these are available in most GNU/Linux
+distributions and should just be installed using the respective
+package manager.
+
+The following instructions will show how to install libgnunetutil and
+the GNU Taler exchange.
+
+
+Before you install libgnunetutil, you must download and install the
+dependencies mentioned above, otherwise the build may succeed but fail
+to export some of the tooling required by Taler.
+
+To download and install libgnunetutil, proceed as follows::
+
+ $ git clone https://gnunet.org/git/gnunet/
+ $ cd gnunet/
+ $ ./bootstrap
+ $ ./configure [--prefix=GNUNETPFX]
+ $ # Each dependency can be fetched from non standard locations via
+ $ # the '--with-<LIBNAME>' option. See './configure --help'.
+ $ make
+ # make install
+
+
+If you did not specify a prefix, GNUnet will install to
+``/usr/local``, which requires you to run the last step as
+``root``.
+
+To download and install the GNU Taler exchange, proceeds as follows::
+
+ $ git clone git://taler.net/exchange
+ $ cd exchange
+ $ ./bootstrap
+ $ ./configure [--prefix=EXCHANGEPFX] \
+ [--with-gnunet=GNUNETPFX]
+ $ # Each dependency can be fetched from non standard locations via
+ $ # the '--with-<LIBNAME>' option. See './configure --help'.
+ $ make
+ # make install
+
+If you did not specify a prefix, the exchange will install to
+``/usr/local``, which requires you to run the last step as
+``root``. Note that you have to specify ``--with-gnunet=/usr/local``
+if you installed GNUnet to ``/usr/local`` in the previous step.
+
++++++
+Other
++++++
+
+------------------
+Reserve management
+------------------
+
+Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their reserve key.
+The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database.
diff --git a/docs/operate-merchant.rst b/docs/operate-merchant.rst
new file mode 100644
index 00000000..484d6eba
--- /dev/null
+++ b/docs/operate-merchant.rst
@@ -0,0 +1,212 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+ @author Florian Dold
+
+==============================
+Operating the Merchant Backend
+==============================
+
++++++++++++++
+Configuration
++++++++++++++
+
+The following data and facilities have to be set up, in order to run a merchant backend:
+
+* Serving
+* Currency
+* Database
+* Exchanges
+* Keying
+* Bank account
+* Instances
+
+In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.
+
+-------
+Serving
+-------
+
+The merchant backend can serve HTTP over both TCP and UNIX domain socket.
+
+The following values are to be configured under the section `[merchant]`:
+
+* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
+* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`.
+* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix`
+* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----).
+
+--------
+Currency
+--------
+
+The merchant backend supports only one currency. This data is set under the respective
+option `currency` in section `[taler]`.
+
+--------
+Database
+--------
+
+The option `db` under section `[merchant]` gets the DB backend's name the merchant
+is going to use. So far, only `db = postgres` is supported. After choosing the backend,
+it is mandatory to supply the connection string (namely, the database name). This is
+possible in two ways:
+
+* via an environment variable: `TALER_MERCHANTDB_POSTGRES_CONFIG`.
+* via configuration option `config`, under section `[merchantdb-BACKEND]`. For example, the demo merchant is configured as follows:
+
+.. code-block:: text
+
+ [merchant]
+ ...
+ db = postgres
+ ...
+
+ [merchantdb-postgres]
+ config = postgres:///talerdemo
+
+---------
+Exchanges
+---------
+
+The options `uri` and `master_key`, under section `[merchant-exchange-MYEXCHANGE]`, let
+the merchant add the exchange `MYEXCHANGE` among the exchanges the merchant wants to work
+with. `MYEXCHAGE` is just a mnemonic name chosen by the merchant (which is not currently used
+in any computation), and the merchant can add as many exchanges as it is needed.
+`uri` is the exchange's base URL. Please note that a valid `uri` complies with the following
+pattern::
+
+ schema://hostname/
+
+`master_key` is the base32 encoding of the exchange's master key (see :ref:`/keys <keys>`).
+In our demo, we use the following configuration::
+
+ [merchant-exchange-test]
+ URI = https://exchange.test.taler.net/
+ MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+
+------
+Keying
+------
+
+The option `keyfile` under section `[merchant-instance-default]` is the path to the
+merchant's :ref:`default instance <instances-lab>` private key. This key is needed to
+sign certificates and other messages sent to wallets and exchanges.
+To generate a 100% compatible key, it is recommended to use the ``gnunet-ecc`` tool.
+
+------------
+Bank account
+------------
+
+This piece of information is used when the merchant redeems coins to the exchange.
+That way, the exchange will know to which bank account it has to transfer real money.
+The merchant must specify which system it wants receive wire transfers with. We support
+a `test` wire format so far, and supporting `SEPA` is among our priorities.
+
+The wire format is specified in the option `wireformat` under section `[merchant]`,
+and the wire details are given via a JSON file, whose path must be indicated in the
+option `X_response_file` under section `[default-wireformat]`, where `X` matches
+the chosen wireformat. In our demo, we have::
+
+ [merchant]
+ ..
+ wireformat = test
+ ..
+
+ [merchant-instance-wireformat-default]
+ test_response_file = ${TALER_CONFIG_HOME}/merchant/wire/test.json
+
+The file `test.json` obeys to the following specification
+
+.. code-block:: tsref
+
+ interface WireDetails {
+ // matches wireformat
+ type: string;
+
+ // base URL of the merchant's bank
+ bank_uri: string;
+
+ // merchant's signature (unused, can be any value)
+ signature: string;
+
+ // merchant's account number at the bank
+ account_number: Integer;
+
+ // the salt (unused, can be any value)
+ salt: any;
+ }
+
+As an example, `test.json` used in our demo is shown below::
+
+ {
+ "type": "test",
+ "bank_uri": "https://bank.test.taler.net/",
+ "sig": "MERCHANTSIGNATURE",
+ "account_number": 6,
+ "salt": "SALT"
+ }
+
+
+
+.. _instances-lab:
+
+---------
+Instances
+---------
+
+In Taler, multiple shops can rely on the same :ref:`merchant backend <merchant-arch>`.
+In Taler terminology, each of those shops is called `(merchant) instance`. Any instance
+is defined by its private key and its wire details. In order to add the instance `X` to
+the merchant backend, we have to add the sections `[merchant-instance-X]` and `[X-wireformat]`,
+and edit them as we did for the `default` instance. For example, in our demo we add the
+instance `Tor` as follows::
+
+ [merchant-instance-Tor]
+ KEYFILE = ${TALER_DATA_HOME}/merchant/tor.priv
+
+ ..
+
+ [merchant-instance-wireformat-Tor]
+ TEST_RESPONSE_FILE = ${TALER_CONFIG_HOME}/merchant/wire/tor.json
+
+Please note that :ref:`Taler messagging<merchant-api>` is designed so that the merchant
+frontend can instruct the backend on which instance has to be used in the various operations.
+This information is optional, and if not given, the backend will act as the `default` instance.
+
+++++++++++++
+Installation
+++++++++++++
+
+
+
+
+
+In order to compile your merchant backend, you firstly need to install the GNU Taler
+exchange. As of other dependencies, the merchant backend needs exactly the same ones
+as the exchange does. Follow :ref:`those instructions <exchange-install>` to build
+everything needed.
+
+Assuming all the dependencies have been correctly installed, we can now build the
+merchant backend using the following commands::
+
+ $ git clone git://taler.net/merchant
+ $ cd merchant
+ $ ./bootstrap
+ $ ./configure [--prefix=PFX] \
+ [--with-gnunet=GNUNETPFX] \
+ [--with-exchange=EXCHANGEPFX]
+ $ # Each dependency can be fetched from non standard locations via
+ $ # the '--with-<LIBNAME>' option. See './configure --help'.
+ $ make
+ $ make install