[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-docs] branch master updated: texinfo support
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [taler-docs] branch master updated: texinfo support |
|
Date: |
Thu, 29 Aug 2019 13:32:38 +0200 |
This is an automated email from the git hooks/post-receive script.
dold pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 4b82b7c texinfo support
4b82b7c is described below
commit 4b82b7c171068c4722f10855391b9ca3a6ea20a9
Author: Florian Dold <address@hidden>
AuthorDate: Thu Aug 29 13:32:36 2019 +0200
texinfo support
---
Makefile | 7 +
_exts/httpdomain/httpdomain.py | 2 +-
conf.py | 6 +-
index.rst | 8 +-
merchant-api.rst | 1703 ----------------------------------------
merchant-manual.rst | 1228 -----------------------------
taler-bank.rst | 190 -----
taler-exchange.rst | 869 --------------------
8 files changed, 14 insertions(+), 3999 deletions(-)
diff --git a/Makefile b/Makefile
index 4b7e30a..e15550e 100644
--- a/Makefile
+++ b/Makefile
@@ -20,6 +20,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees
$(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp
epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: texinfo-exchange
help:
@echo "Please use \`make <target>' where <target> is one of"
@@ -148,6 +149,12 @@ texinfo:
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
+texinfo-exchange:
+ $(SPHINXBUILD) -b texinfo . $(BUILDDIR)/texinfo-exchange
./taler-bank.rst -D master_doc=taler-exchange
+ @echo
+ @echo "Build finished. The Texinfo files are in
$(BUILDDIR)/texinfo-exchange."
+ @echo "Run \`make' in that directory to run these through makeinfo"
+
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
diff --git a/_exts/httpdomain/httpdomain.py b/_exts/httpdomain/httpdomain.py
index a5e3471..f2569b5 100644
--- a/_exts/httpdomain/httpdomain.py
+++ b/_exts/httpdomain/httpdomain.py
@@ -631,7 +631,7 @@ class HTTPDomain(Domain):
'any': {}
}
- indices = [HTTPIndex]
+ indices = []
@property
def routes(self):
diff --git a/conf.py b/conf.py
index bfc817d..c49c67a 100644
--- a/conf.py
+++ b/conf.py
@@ -272,10 +272,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'taler', u'GNU Taler Documentation',
- u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff',
- 'neuro', 'One-Click Cash Payments.',
- 'Miscellaneous'),
+ ("taler-exchange-manual", "taler-exchange", "Taler Exchange Manual", "GNU
Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"),
+ ("taler-merchant-manual", "taler-merchant", "Taler Merchant Manual", "GNU
Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"),
]
# Documents to append as an appendix to all manuals.
diff --git a/index.rst b/index.rst
index 7ffc9bb..1997b39 100644
--- a/index.rst
+++ b/index.rst
@@ -53,10 +53,10 @@ interfaces between the core components of Taler.
:maxdepth: 2
core/index
- taler-exchange
- merchant-manual
- merchant-api
- taler-bank
+ taler-exchange-manual
+ taler-merchant-manual
+ taler-merchant-api-tutorial
+ taler-bank-manual
backoffice
onboarding
global-licensing
diff --git a/merchant-api.rst b/merchant-api.rst
deleted file mode 100644
index cc4ede9..0000000
--- a/merchant-api.rst
+++ /dev/null
@@ -1,1703 +0,0 @@
-The GNU Taler Merchant API Tutorial
-###################################
-
-Introduction
-============
-
-About GNU Taler
----------------
-
-GNU Taler is an open protocol for an electronic payment system with a
-free software reference implementation. GNU Taler offers secure, fast
-and easy payment processing using well understood cryptographic
-techniques. GNU Taler allows customers to remain anonymous, while
-ensuring that merchants can be held accountable by governments. Hence,
-GNU Taler is compatible with anti-money-laundering (AML) and
-know-your-customer (KYC) regulation, as well as data protection
-regulation (such as GDPR).
-
-About this tutorial
--------------------
-
-This tutorial addresses how to process payments using the GNU Taler
-merchant Backend. This chapter explains some basic concepts. In the
-second chapter, you will learn how to do basic payments.
-
-This version of the tutorial has examples for Python3. It uses the
-requests library for HTTP requests. Versions for other
-languages/environments are available as well.
-
-examples
-git
-If you want to look at some simple, running examples, check out these:
-
-- The `essay
- merchant <https://git.taler.net/blog.git/tree/talerblog/blog/blog.py>`__
- that sells single chapters of a book.
-
-- The `donation
- page
<https://git.taler.net/donations.git/tree/talerdonations/donations/donations.py>`__
- that accepts donations for software projects and gives donation
- receipts.
-
-- The
- `survey
<https://git.taler.net/survey.git/tree/talersurvey/survey/survey.py>`__
- that gives users who answer a question a small reward.
-
-Architecture overview
----------------------
-
-The Taler software stack for a merchant consists of the following main
-components:
-
-- frontend
- A frontend which interacts with the customer’s browser. The frontend
- enables the customer to build a shopping cart and place an order.
- Upon payment, it triggers the respective business logic to satisfy
- the order. This component is not included with Taler, but rather
- assumed to exist at the merchant. This tutorial describes how to
- develop a Taler frontend.
-
-- backend
- A Taler-specific payment backend which makes it easy for the frontend
- to process financial transactions with Taler. For this tutorial, you
- will use a public sandbox backend. For production use, you must
- either set up your own backend or ask another person to do so for
- you.
-
-The following image illustrates the various interactions of these key
-components:
-
-|image0|
-
-The backend provides the cryptographic protocol support, stores
-Taler-specific financial information and communicates with the GNU Taler
-exchange over the Internet. The frontend accesses the backend via a
-RESTful API. As a result, the frontend never has to directly communicate
-with the exchange, and also does not deal with sensitive data. In
-particular, the merchant’s signing keys and bank account information are
-encapsulated within the Taler backend.
-
-Some functionality of the backend (the “public interface“) is also
-exposed to the customer’s browser directly. In the HTTP API, all public
-endpoints are prefixed with ``/public/``.
-
-Public Sandbox Backend and Authentication
------------------------------------------
-
-sandbox
-authorization
-How the frontend authenticates to the Taler backend depends on the
-configuration. See Taler Merchant Operating Manual.
-
-The public sandbox backend https://backend.demo.taler.net/ uses an API
-key in the ``Authorization`` header. The value of this header must be
-``ApiKey sandbox`` for the public sandbox backend.
-
-::
-
- >>> import requests
- >>> requests.get("https://backend.demo.taler.net";,
- ... headers={"Authorization": "ApiKey sandbox"})
- <Response [200]>
-
-If an HTTP status code other than 200 is returned, something went wrong.
-You should figure out what the problem is before continuing with this
-tutorial.
-
-The sandbox backend https://backend.demo.taler.net/ uses ``KUDOS`` as an
-imaginary currency. Coins denominated in ``KUDOS`` can be withdrawn from
-https://bank.demo.taler.net/.
-
-Merchant Instances
-------------------
-
-instance
-The same Taler merchant backend server can be used by multiple separate
-merchants that are separate business entities. Each of these separate
-business entities is called a *merchant instance*, and is identified by
-an alphanumeric *instance id*. If the instance is omitted, the instance
-id ``default`` is assumed.
-
-The following merchant instances are configured on
-https://backend.demo.taler.net/:
-
-- ``GNUnet`` (The GNUnet project)
-
-- ``FSF`` (The Free Software Foundation)
-
-- ``Tor`` (The Tor Project)
-
-- ``default`` (Kudos Inc.)
-
-Note that these are fictional merchants used for our demonstrators and
-not affiliated with or officially approved by the respective projects.
-
-.. _Accepting-a-Simple-Payment:
-
-Accepting a Simple Payment
-==========================
-
-Creating an Order for a Payment
--------------------------------
-
-order
-Payments in Taler revolve around an *order*, which is a machine-readable
-description of the business transaction for which the payment is to be
-made. Before accepting a Taler payment as a merchant you must create
-such an order.
-
-This is done by posting a JSON object to the backend’s ``/order`` API
-endpoint. At least the following fields must be given:
-
-- amount: The amount to be paid, as a string in the format
- ``CURRENCY:DECIMAL_VALUE``, for example ``EUR:10`` for 10 Euros or
- ``KUDOS:1.5`` for 1.5 KUDOS.
-
-- summary: A human-readable summary for what the payment is about. The
- summary should be short enough to fit into titles, though no hard
- limit is enforced.
-
-- fulfillment_url: A URL that will be displayed once the payment is
- completed. For digital goods, this should be a page that displays the
- product that was purchased. On successful payment, the wallet
- automatically appends the ``order_id`` as a query parameter, as well
- as the ``session_sig`` for session-bound payments (discussed later).
-
-Orders can have many more fields, see `The Taler Order
-Format <#The-Taler-Order-Format>`__.
-
-After successfully ``POST``\ ing to ``/order``, an ``order_id`` will be
-returned. Together with the merchant ``instance``, the order id uniquely
-identifies the order within a merchant backend.
-
-::
-
- >>> import requests
- >>> order = dict(order=dict(amount="KUDOS:10",
- ... summary="Donation",
- ...
fulfillment_url="https://example.com/thanks.html";))
- >>> order_resp = requests.post("https://backend.demo.taler.net/order";,
json=order,
- ... headers={"Authorization": "ApiKey sandbox"})
- <Response [200]>
-
-The backend will fill in some details missing in the order, such as the
-address of the merchant instance. The full details are called the
-*contract terms*. contract terms
-
-Checking Payment Status and Prompting for Payment
--------------------------------------------------
-
-The status of a payment can be checked with the ``/check-payment``
-endpoint. If the payment is yet to be completed by the customer,
-``/check-payment`` will give the frontend a URL (the
-payment_redirect_url) that will trigger the customer’s wallet to execute
-the payment.
-
-Note that the only way to obtain the payment_redirect_url is to check
-the status of the payment, even if you know that the user did not pay
-yet.
-
-::
-
- >>> import requests
- >>> r = requests.get("https://backend.demo.taler.net/check-payment";,
- ... params=dict(order_id=order_resp.json()["order_id"]),
- ... headers={"Authorization": "ApiKey sandbox"})
- >>> print(r.json())
-
-If the paid field in the response is ``true``, the other fields in the
-response will be different. Once the payment was completed by the user,
-the response will contain the following fields:
-
-- paid: Set to true.
-
-- contract_terms: The full contract terms of the order.
-
-- refunded: ``true`` if a (possibly partial) refund was granted for
- this purchase.
-
-- refunded_amount: Amount that was refunded
-
-- last_session_id: Last session ID used by the customer’s wallet. See
- `Session-Bound Payments <#Session_002dBound-Payments>`__.
-
-Once the frontend has confirmed that the payment was successful, it
-usually needs to trigger the business logic for the merchant to fulfill
-the merchant’s obligations under the contract.
-
-.. _Giving-Refunds:
-
-Giving Refunds
-==============
-
-refunds
-A refund in GNU Taler is a way to “undo” a payment. It needs to be
-authorized by the merchant. Refunds can be for any fraction of the
-original amount paid, but they cannot exceed the original payment.
-Refunds are time-limited and can only happen while the exchange holds
-funds for a particular payment in escrow. The time during which a refund
-is possible can be controlled by setting the ``refund_deadline`` in an
-order. The default value for this refund deadline is specified in the
-configuration of the merchant’s backend.
-
-The frontend can instruct the merchant backend to authorize a refund by
-``POST``\ ing to the ``/refund`` endpoint.
-
-The refund request JSON object has the following fields:
-
-- order_id: Identifies for which order a customer should be refunded.
-
-- instance: Merchant instance to use.
-
-- refund: Amount to be refunded. If a previous refund was authorized
- for the same order, the new amount must be higher, otherwise the
- operation has no effect. The value indicates the total amount to be
- refunded, *not* an increase in the refund.
-
-- reason: Human-readable justification for the refund. The reason is
- only used by the Back Office and is not exposed to the customer.
-
-If the request is successful (indicated by HTTP status code 200), the
-response includes a ``refund_redirect_url``. The frontend must redirect
-the customer’s browser to that URL to allow the refund to be processed
-by the wallet.
-
-This code snipped illustrates giving a refund:
-
-::
-
- >>> import requests
- >>> refund_req = dict(order_id="2018.058.21.46.06-024C85K189H8P",
- ... refund="KUDOS:10",
- ... instance="default",
- ... reason="Customer did not like the product")
- >>> requests.post("https://backend.demo.taler.net/refund";, json=refund_req,
- ... headers={"Authorization": "ApiKey sandbox"})
- <Response [200]>
-
-.. _Giving-Customers-Tips:
-
-Giving Customers Tips
-=====================
-
-tips
-GNU Taler allows Web sites to grant small amounts directly to the
-visitor. The idea is that some sites may want incentivize actions such
-as filling out a survey or trying a new feature. It is important to note
-that tips are not enforceable for the visitor, as there is no contract.
-It is simply a voluntary gesture of appreciation of the site to its
-visitor. However, once a tip has been granted, the visitor obtains full
-control over the funds provided by the site.
-
-The “merchant” backend of the site must be properly configured for
-tipping, and sufficient funds must be made available for tipping See
-Taler Merchant Operating Manual.
-
-To check if tipping is configured properly and if there are sufficient
-funds available for tipping, query the ``/tip-query`` endpoint:
-
-::
-
- >>> import requests
- >>>
requests.get("https://backend.demo.taler.net/tip-query?instance=default";,
- ... headers={"Authorization": "ApiKey sandbox"})
- <Response [200]>
-
-authorize tip
-To authorize a tip, ``POST`` to ``/tip-authorize``. The following fields
-are recognized in the JSON request object:
-
-- amount: Amount that should be given to the visitor as a tip.
-
-- instance: Merchant instance that grants the tip (each instance may
- have its own independend tipping funds configured).
-
-- justification: Description of why the tip was granted. Human-readable
- text not exposed to the customer, but used by the Back Office.
-
-- next_url: The URL that the user’s browser should be redirected to by
- the wallet, once the tip has been processed.
-
-The response from the backend contains a ``tip_redirect_url``. The
-customer’s browser must be redirected to this URL for the wallet to pick
-up the tip. pick up tip
-
-This code snipped illustrates giving a tip:
-
-::
-
- >>> import requests
- >>> tip_req = dict(amount="KUDOS:0.5",
- ... instance="default",
- ... justification="User filled out survey",
- ... next_url="https://merchant.com/thanks.html";)
- >>> requests.post("https://backend.demo.taler.net/tip-authorize";,
json=tip_req,
- ... headers={"Authorization": "ApiKey sandbox"})
- <Response [200]>
-
-.. _Advanced-topics:
-
-Advanced topics
-===============
-
-.. _Detecting-the-Presence-of-the-Taler-Wallet:
-
-Detecting the Presence of the Taler Wallet
-------------------------------------------
-
-wallet
-Taler offers ways to detect whether a user has the wallet installed in
-their browser. This allows Web sites to adapt accordingly. Note that not
-all platforms can do presence detection reliably. Some platforms might
-have a Taler wallet installed as a separate App instead of using a Web
-extension. In these cases, presence detection will fail. Thus, sites may
-want to allow users to request Taler payments even if a wallet could not
-be detected, especially for visitors using mobiles.
-
-Presence detection without JavaScript
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Presence detection without JavaScript is based on CSS classes. You can
-hide or show elements selectively depending on whether the wallet is
-detected or not.
-
-In order to work correctly, a special fallback stylesheet must be
-included that will be used when the wallet is not present. The
-stylesheet can be put into any file, but must be included via a ``link``
-tag with the ``id`` attribute set to ``taler-presence-stylesheet``. If a
-wallet is present, it will “hijack” this stylesheet to change how
-elements with the following classes are rendered:
-
-The following CSS classes can be used:
-
-``taler-installed-hide``
- A CSS rule will set the ``display`` property for this class to
- ``none`` once the Taler wallet is installed and enabled. If the
- wallet is not installed, ``display`` will be ``inherit``.
-
-``taler-installed-show``
- A CSS rule will set the ``display`` property for this class to
- ``inherit`` once the Taler wallet is installed and enabled. If the
- wallet is not installed, ``display`` will be ``none``.
-
-The following is a complete example:
-
-::
-
- <!DOCTYPE html>
- <html data-taler-nojs="true">
- <head>
- <title>Tutorial</title>
- <link rel="stylesheet"
- type="text/css"
- href="/web-common/taler-fallback.css"
- id="taler-presence-stylesheet" />
- </head>
- <body>
- <p class="taler-installed-hide">
- No wallet found.
- </p>
- <p class="taler-installed-show">
- Wallet found!
- </p>
- </body>
- </html>
-
-The ``taler-fallback.css`` is part of the Taler’s *web-common*
-repository, available at
-https://git.taler.net/web-common.git/tree/taler-fallback.css. You may
-have to adjust the ``href`` attribute in the HTML code above to point to
-the correct location of the ``taler-fallback.css`` file on your Web
-site.
-
-Detection with JavaScript
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following functions are defined in the ``taler`` namespace of the
-``taler-wallet-lib`` helper library available at
-https://git.taler.net/web-common.git/tree/taler-wallet-lib.js.
-
-``onPresent(callback: () => void)``
- Adds a callback to be called when support for Taler payments is
- detected.
-
-``onAbsent(callback: () => void)``
- Adds a callback to be called when support for Taler payments is
- disabled.
-
-Note that the registered callbacks may be called more than once. This
-may happen if a user disables or enables the wallet in the browser’s
-extension settings while a shop’s frontend page is open.
-
-.. _Integration-with-the-Back-Office:
-
-Integration with the Back Office
---------------------------------
-
-Taler ships a Back Office application as a stand-alone Web application.
-The Back Office has its own documentation at
-https://docs.taler.net/backoffice/html/manual.html.
-
-Developers wishing to tightly integrate back office support for
-Taler-based payments into an existing back office application should
-focus on the wire transfer tracking and transaction history sections of
-the Taler Backend API specification at
-https://docs.taler.net/api/api-merchant.html
-
-.. _Session_002dBound-Payments:
-
-Session-Bound Payments
-----------------------
-
-session
-Sometimes checking if an order has been paid for is not enough. For
-example, when selling access to online media, the publisher may want to
-be paid for exactly the same product by each customer. Taler supports
-this model by allowing the mechant to check whether the “payment
-receipt” is available on the user’s current device. This prevents users
-from easily sharing media access by transmitting a link to the
-fulfillment page. Of course sophisticated users could share payment
-receipts as well, but this is not as easy as sharing a link, and in this
-case they are more likely to just share the media directly.
-
-To use this feature, the merchant must first assign the user’s current
-browser an ephemeral ``session_id``, usually via a session cookie. When
-executing or re-playing a payment, the wallet will receive an additional
-signature (``session_sig``). This signature certifies that the wallet
-showed a payment receipt for the respective order in the current
-session. cookie
-
-Session-bound payments are triggerd by passing the ``session_id``
-parameter to the ``/check-payment`` endpoint. The wallet will then
-redirect to the fulfillment page, but include an additional
-``session_sig`` parameter. The frontend can query ``/check-payment``
-with both the ``session_id`` and the ``session_sig`` to verify that the
-signature is correct.
-
-The last session ID that was successfuly used to prove that the payment
-receipt is in the user’s wallet is also available as ``last_session_id``
-in the response to ``/check-payment``.
-
-.. _Product-Identification:
-
-Product Identification
-----------------------
-
-resource url
-In some situations the user may have paid for some digital good, but the
-frontend does not know the exact order ID, and thus cannot instruct the
-wallet to reveil the existing payment receipt. This is common for simple
-shops without a login system. In this case, the user would be prompted
-for payment again, even though they already purchased the product.
-
-To allow the wallet to instead find the existing payment receipt, the
-shop must use a unique fulfillment URL for each product. Then, the
-frontend must provide an additional ``resource_url`` parameter to to
-``/check-payment``. It should identify this unique fulfillment URL for
-the product. The wallet will then check whether it has paid for a
-contract with the same ``resource_url`` before, and if so replay the
-previous payment.
-
-.. _The-Taler-Order-Format:
-
-The Taler Order Format
-----------------------
-
-contract
-terms
-order
-A Taler order can specify many details about the payment. This section
-describes each of the fields in depth.
-
-Financial amounts are always specified as a string in the format
-``"CURRENCY:DECIMAL_VALUE"``.
-
-amount
- amount
- Specifies the total amount to be paid to the merchant by the
- customer.
-
-max_fee
- fees
- maximum deposit fee
- This is the maximum total amount of deposit fees that the merchant is
- willing to pay. If the deposit fees for the coins exceed this amount,
- the customer has to include it in the payment total. The fee is
- specified using the same triplet used for amount.
-
-max_wire_fee
- fees
- maximum wire fee
- Maximum wire fee accepted by the merchant (customer share to be
- divided by the ’wire_fee_amortization’ factor, and further reduced if
- deposit fees are below ’max_fee’). Default if missing is zero.
-
-wire_fee_amortization
- fees
- maximum fee amortization
- Over how many customer transactions does the merchant expect to
- amortize wire fees on average? If the exchange’s wire fee is above
- ’max_wire_fee’, the difference is divided by this number to compute
- the expected customer’s contribution to the wire fee. The customer’s
- contribution may further be reduced by the difference between the
- ’max_fee’ and the sum of the actual deposit fees. Optional, default
- value if missing is 1. 0 and negative values are invalid and also
- interpreted as 1.
-
-pay_url
- pay_url
- Which URL accepts payments. This is the URL where the wallet will
- POST coins.
-
-fulfillment_url
- fulfillment URL
- Which URL should the wallet go to for obtaining the fulfillment, for
- example the HTML or PDF of an article that was bought, or an order
- tracking system for shipments, or a simple human-readable Web page
- indicating the status of the contract.
-
-order_id
- order ID
- Alphanumeric identifier, freely definable by the merchant. Used by
- the merchant to uniquely identify the transaction.
-
-summary
- summary
- Short, human-readable summary of the contract. To be used when
- displaying the contract in just one line, for example in the
- transaction history of the customer.
-
-timestamp
- Time at which the offer was generated.
-
-pay_deadline
- payment deadline
- Timestamp of the time by which the merchant wants the exchange to
- definitively wire the money due from this contract. Once this
- deadline expires, the exchange will aggregate all deposits where the
- contracts are past the refund_deadline and execute one large wire
- payment for them. Amounts will be rounded down to the wire transfer
- unit; if the total amount is still below the wire transfer unit, it
- will not be disbursed.
-
-refund_deadline
- refund deadline
- Timestamp until which the merchant willing (and able) to give refunds
- for the contract using Taler. Note that the Taler exchange will hold
- the payment in escrow at least until this deadline. Until this time,
- the merchant will be able to sign a message to trigger a refund to
- the customer. After this time, it will no longer be possible to
- refund the customer. Must be smaller than the pay_deadline.
-
-products
- product description
- Array of products that are being sold to the customer. Each entry
- contains a tuple with the following values:
-
- description
- Description of the product.
-
- quantity
- Quantity of the items to be shipped. May specify a unit (``1 kg``)
- or just the count.
-
- price
- Price for quantity units of this product shipped to the given
- delivery_location. Note that usually the sum of all of the prices
- should add up to the total amount of the contract, but it may be
- different due to discounts or because individual prices are
- unavailable.
-
- product_id
- Unique ID of the product in the merchant’s catalog. Can generally
- be chosen freely as it only has meaning for the merchant, but
- should be a number in the range :math:`[0,2^{51})`.
-
- taxes
- Map of applicable taxes to be paid by the merchant. The label is
- the name of the tax, i.e. VAT, sales tax or income tax, and the
- value is the applicable tax amount. Note that arbitrary labels are
- permitted, as long as they are used to identify the applicable tax
- regime. Details may be specified by the regulator. This is used to
- declare to the customer which taxes the merchant intends to pay,
- and can be used by the customer as a receipt. The information is
- also likely to be used by tax audits of the merchant.
-
- delivery_date
- Time by which the product is to be delivered to the
- delivery_location.
-
- delivery_location
- This should give a label in the locations map, specifying where
- the item is to be delivered.
-
- Values can be omitted if they are not applicable. For example, if a
- purchase is about a bundle of products that have no individual prices
- or product IDs, the product_id or price may not be specified in the
- contract. Similarly, for virtual products delivered directly via the
- fulfillment URI, there is no delivery location.
-
-merchant
- address
- This should give a label in the locations map, specifying where
- the merchant is located.
-
- name
- This should give a human-readable name for the merchant’s
- business.
-
- jurisdiction
- This should give a label in the locations map, specifying the
- jurisdiction under which this contract is to be arbitrated.
-
-locations
- location
- Associative map of locations used in the contract. Labels for
- locations in this map can be freely chosen and used whenever a
- location is required in other parts of the contract. This way, if the
- same location is required many times (such as the business address of
- the customer or the merchant), it only needs to be listed (and
- transmitted) once, and can otherwise be referred to via the label. A
- non-exhaustive list of location attributes is the following:
-
- country
- Name of the country for delivery, as found on a postal package,
- i.e. “France”.
-
- state
- Name of the state for delivery, as found on a postal package, i.e.
- “NY”.
-
- region
- Name of the region for delivery, as found on a postal package.
-
- province
- Name of the province for delivery, as found on a postal package.
-
- city
- Name of the city for delivery, as found on a postal package.
-
- ZIP code
- ZIP code for delivery, as found on a postal package.
-
- street
- Street name for delivery, as found on a postal package.
-
- street number
- Street number (number of the house) for delivery, as found on a
- postal package.
-
- name receiver name for delivery, either business or person name.
-
- Note that locations are not required to specify all of these fields,
- and they is also allowed to have additional fields. Contract
- renderers must render at least the fields listed above, and should
- render fields that they do not understand as a key-value list.
-
-.. _GNU_002dLGPL:
-
-GNU-LGPL
-========
-
-license
-LGPL
-Version 2.1, February 1999
-::
-
- Copyright © 1991, 1999 Free Software Foundation, Inc.
- 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- [This is the first released version of the Lesser GPL. It also counts
- as the successor of the GNU Library Public License, version 2, hence the
- version number 2.1.]
-
-**Preamble**
-
-The licenses for most software are designed to take away your freedom to
-share and change it. By contrast, the GNU General Public Licenses are
-intended to guarantee your freedom to share and change free software—to
-make sure the software is free for all its users.
-
-This license, the Lesser General Public License, applies to some
-specially designated software—typically libraries—of the Free Software
-Foundation and other authors who decide to use it. You can use it too,
-but we suggest you first think carefully about whether this license or
-the ordinary General Public License is the better strategy to use in any
-particular case, based on the explanations below.
-
-When we speak of free software, we are referring to freedom of use, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish); that you receive source code or can get it if
-you want it; that you can change the software and use pieces of it in
-new free programs; and that you are informed that you can do these
-things.
-
-To protect your rights, we need to make restrictions that forbid
-distributors to deny you these rights or to ask you to surrender these
-rights. These restrictions translate to certain responsibilities for you
-if you distribute copies of the library or if you modify it.
-
-For example, if you distribute copies of the library, whether gratis or
-for a fee, you must give the recipients all the rights that we gave you.
-You must make sure that they, too, receive or can get the source code.
-If you link other code with the library, you must provide complete
-object files to the recipients, so that they can relink them with the
-library after making changes to the library and recompiling it. And you
-must show them these terms so they know their rights.
-
-We protect your rights with a two-step method: (1) we copyright the
-library, and (2) we offer you this license, which gives you legal
-permission to copy, distribute and/or modify the library.
-
-To protect each distributor, we want to make it very clear that there is
-no warranty for the free library. Also, if the library is modified by
-someone else and passed on, the recipients should know that what they
-have is not the original version, so that the original author’s
-reputation will not be affected by problems that might be introduced by
-others.
-
-Finally, software patents pose a constant threat to the existence of any
-free program. We wish to make sure that a company cannot effectively
-restrict the users of a free program by obtaining a restrictive license
-from a patent holder. Therefore, we insist that any patent license
-obtained for a version of the library must be consistent with the full
-freedom of use specified in this license.
-
-Most GNU software, including some libraries, is covered by the ordinary
-GNU General Public License. This license, the GNU Lesser General Public
-License, applies to certain designated libraries, and is quite different
-from the ordinary General Public License. We use this license for
-certain libraries in order to permit linking those libraries into
-non-free programs.
-
-When a program is linked with a library, whether statically or using a
-shared library, the combination of the two is legally speaking a
-combined work, a derivative of the original library. The ordinary
-General Public License therefore permits such linking only if the entire
-combination fits its criteria of freedom. The Lesser General Public
-License permits more lax criteria for linking other code with the
-library.
-
-We call this license the Lesser General Public License because it does
-*Less* to protect the user’s freedom than the ordinary General Public
-License. It also provides other free software developers Less of an
-advantage over competing non-free programs. These disadvantages are the
-reason we use the ordinary General Public License for many libraries.
-However, the Lesser license provides advantages in certain special
-circumstances.
-
-For example, on rare occasions, there may be a special need to encourage
-the widest possible use of a certain library, so that it becomes a
-de-facto standard. To achieve this, non-free programs must be allowed to
-use the library. A more frequent case is that a free library does the
-same job as widely used non-free libraries. In this case, there is
-little to gain by limiting the free library to free software only, so we
-use the Lesser General Public License.
-
-In other cases, permission to use a particular library in non-free
-programs enables a greater number of people to use a large body of free
-software. For example, permission to use the GNU C Library in non-free
-programs enables many more people to use the whole GNU operating system,
-as well as its variant, the GNU/Linux operating system.
-
-Although the Lesser General Public License is Less protective of the
-users’ freedom, it does ensure that the user of a program that is linked
-with the Library has the freedom and the wherewithal to run that program
-using a modified version of the Library.
-
-The precise terms and conditions for copying, distribution and
-modification follow. Pay close attention to the difference between a
-“work based on the library” and a “work that uses the library”. The
-former contains code derived from the library, whereas the latter must
-be combined with the library in order to run.
-
-**TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION**
-
-1. This License Agreement applies to any software library or other
- program which contains a notice placed by the copyright holder or
- other authorized party saying it may be distributed under the terms
- of this Lesser General Public License (also called “this License”).
- Each licensee is addressed as “you”.
-
- A “library” means a collection of software functions and/or data
- prepared so as to be conveniently linked with application programs
- (which use some of those functions and data) to form executables.
-
- The “Library”, below, refers to any such software library or work
- which has been distributed under these terms. A “work based on the
- Library” means either the Library or any derivative work under
- copyright law: that is to say, a work containing the Library or a
- portion of it, either verbatim or with modifications and/or
- translated straightforwardly into another language. (Hereinafter,
- translation is included without limitation in the term
- “modification”.)
-
- “Source code” for a work means the preferred form of the work for
- making modifications to it. For a library, complete source code
- means all the source code for all modules it contains, plus any
- associated interface definition files, plus the scripts used to
- control compilation and installation of the library.
-
- Activities other than copying, distribution and modification are not
- covered by this License; they are outside its scope. The act of
- running a program using the Library is not restricted, and output
- from such a program is covered only if its contents constitute a
- work based on the Library (independent of the use of the Library in
- a tool for writing it). Whether that is true depends on what the
- Library does and what the program that uses the Library does.
-
-2. You may copy and distribute verbatim copies of the Library’s
- complete source code as you receive it, in any medium, provided that
- you conspicuously and appropriately publish on each copy an
- appropriate copyright notice and disclaimer of warranty; keep intact
- all the notices that refer to this License and to the absence of any
- warranty; and distribute a copy of this License along with the
- Library.
-
- You may charge a fee for the physical act of transferring a copy,
- and you may at your option offer warranty protection in exchange for
- a fee.
-
-3. You may modify your copy or copies of the Library or any portion of
- it, thus forming a work based on the Library, and copy and
- distribute such modifications or work under the terms of Section 1
- above, provided that you also meet all of these conditions:
-
- a. The modified work must itself be a software library.
-
- b. You must cause the files modified to carry prominent notices
- stating that you changed the files and the date of any change.
-
- c. You must cause the whole of the work to be licensed at no charge
- to all third parties under the terms of this License.
-
- d. If a facility in the modified Library refers to a function or a
- table of data to be supplied by an application program that uses
- the facility, other than as an argument passed when the facility
- is invoked, then you must make a good faith effort to ensure
- that, in the event an application does not supply such function
- or table, the facility still operates, and performs whatever part
- of its purpose remains meaningful.
-
- (For example, a function in a library to compute square roots has
- a purpose that is entirely well-defined independent of the
- application. Therefore, Subsection 2d requires that any
- application-supplied function or table used by this function must
- be optional: if the application does not supply it, the square
- root function must still compute square roots.)
-
- These requirements apply to the modified work as a whole. If
- identifiable sections of that work are not derived from the Library,
- and can be reasonably considered independent and separate works in
- themselves, then this License, and its terms, do not apply to those
- sections when you distribute them as separate works. But when you
- distribute the same sections as part of a whole which is a work
- based on the Library, the distribution of the whole must be on the
- terms of this License, whose permissions for other licensees extend
- to the entire whole, and thus to each and every part regardless of
- who wrote it.
-
- Thus, it is not the intent of this section to claim rights or
- contest your rights to work written entirely by you; rather, the
- intent is to exercise the right to control the distribution of
- derivative or collective works based on the Library.
-
- In addition, mere aggregation of another work not based on the
- Library with the Library (or with a work based on the Library) on a
- volume of a storage or distribution medium does not bring the other
- work under the scope of this License.
-
-4. You may opt to apply the terms of the ordinary GNU General Public
- License instead of this License to a given copy of the Library. To
- do this, you must alter all the notices that refer to this License,
- so that they refer to the ordinary GNU General Public License,
- version 2, instead of to this License. (If a newer version than
- version 2 of the ordinary GNU General Public License has appeared,
- then you can specify that version instead if you wish.) Do not make
- any other change in these notices.
-
- Once this change is made in a given copy, it is irreversible for
- that copy, so the ordinary GNU General Public License applies to all
- subsequent copies and derivative works made from that copy.
-
- This option is useful when you wish to copy part of the code of the
- Library into a program that is not a library.
-
-5. You may copy and distribute the Library (or a portion or derivative
- of it, under Section 2) in object code or executable form under the
- terms of Sections 1 and 2 above provided that you accompany it with
- the complete corresponding machine-readable source code, which must
- be distributed under the terms of Sections 1 and 2 above on a medium
- customarily used for software interchange.
-
- If distribution of object code is made by offering access to copy
- from a designated place, then offering equivalent access to copy the
- source code from the same place satisfies the requirement to
- distribute the source code, even though third parties are not
- compelled to copy the source along with the object code.
-
-6. A program that contains no derivative of any portion of the Library,
- but is designed to work with the Library by being compiled or linked
- with it, is called a “work that uses the Library”. Such a work, in
- isolation, is not a derivative work of the Library, and therefore
- falls outside the scope of this License.
-
- However, linking a “work that uses the Library” with the Library
- creates an executable that is a derivative of the Library (because
- it contains portions of the Library), rather than a “work that uses
- the library”. The executable is therefore covered by this License.
- Section 6 states terms for distribution of such executables.
-
- When a “work that uses the Library” uses material from a header file
- that is part of the Library, the object code for the work may be a
- derivative work of the Library even though the source code is not.
- Whether this is true is especially significant if the work can be
- linked without the Library, or if the work is itself a library. The
- threshold for this to be true is not precisely defined by law.
-
- If such an object file uses only numerical parameters, data
- structure layouts and accessors, and small macros and small inline
- functions (ten lines or less in length), then the use of the object
- file is unrestricted, regardless of whether it is legally a
- derivative work. (Executables containing this object code plus
- portions of the Library will still fall under Section 6.)
-
- Otherwise, if the work is a derivative of the Library, you may
- distribute the object code for the work under the terms of Section
- 6. Any executables containing that work also fall under Section 6,
- whether or not they are linked directly with the Library itself.
-
-7. As an exception to the Sections above, you may also combine or link
- a “work that uses the Library” with the Library to produce a work
- containing portions of the Library, and distribute that work under
- terms of your choice, provided that the terms permit modification of
- the work for the customer’s own use and reverse engineering for
- debugging such modifications.
-
- You must give prominent notice with each copy of the work that the
- Library is used in it and that the Library and its use are covered
- by this License. You must supply a copy of this License. If the work
- during execution displays copyright notices, you must include the
- copyright notice for the Library among them, as well as a reference
- directing the user to the copy of this License. Also, you must do
- one of these things:
-
- a. Accompany the work with the complete corresponding
- machine-readable source code for the Library including whatever
- changes were used in the work (which must be distributed under
- Sections 1 and 2 above); and, if the work is an executable linked
- with the Library, with the complete machine-readable “work that
- uses the Library”, as object code and/or source code, so that the
- user can modify the Library and then relink to produce a modified
- executable containing the modified Library. (It is understood
- that the user who changes the contents of definitions files in
- the Library will not necessarily be able to recompile the
- application to use the modified definitions.)
-
- b. Use a suitable shared library mechanism for linking with the
- Library. A suitable mechanism is one that (1) uses at run time a
- copy of the library already present on the user’s computer
- system, rather than copying library functions into the
- executable, and (2) will operate properly with a modified version
- of the library, if the user installs one, as long as the modified
- version is interface-compatible with the version that the work
- was made with.
-
- c. Accompany the work with a written offer, valid for at least three
- years, to give the same user the materials specified in
- Subsection 6a, above, for a charge no more than the cost of
- performing this distribution.
-
- d. If distribution of the work is made by offering access to copy
- from a designated place, offer equivalent access to copy the
- above specified materials from the same place.
-
- e. Verify that the user has already received a copy of these
- materials or that you have already sent this user a copy.
-
- For an executable, the required form of the “work that uses the
- Library” must include any data and utility programs needed for
- reproducing the executable from it. However, as a special exception,
- the materials to be distributed need not include anything that is
- normally distributed (in either source or binary form) with the
- major components (compiler, kernel, and so on) of the operating
- system on which the executable runs, unless that component itself
- accompanies the executable.
-
- It may happen that this requirement contradicts the license
- restrictions of other proprietary libraries that do not normally
- accompany the operating system. Such a contradiction means you
- cannot use both them and the Library together in an executable that
- you distribute.
-
-8. You may place library facilities that are a work based on the
- Library side-by-side in a single library together with other library
- facilities not covered by this License, and distribute such a
- combined library, provided that the separate distribution of the
- work based on the Library and of the other library facilities is
- otherwise permitted, and provided that you do these two things:
-
- a. Accompany the combined library with a copy of the same work based
- on the Library, uncombined with any other library facilities.
- This must be distributed under the terms of the Sections above.
-
- b. Give prominent notice with the combined library of the fact that
- part of it is a work based on the Library, and explaining where
- to find the accompanying uncombined form of the same work.
-
-9. You may not copy, modify, sublicense, link with, or distribute the
- Library except as expressly provided under this License. Any attempt
- otherwise to copy, modify, sublicense, link with, or distribute the
- Library is void, and will automatically terminate your rights under
- this License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses terminated
- so long as such parties remain in full compliance.
-
-10. You are not required to accept this License, since you have not
- signed it. However, nothing else grants you permission to modify or
- distribute the Library or its derivative works. These actions are
- prohibited by law if you do not accept this License. Therefore, by
- modifying or distributing the Library (or any work based on the
- Library), you indicate your acceptance of this License to do so, and
- all its terms and conditions for copying, distributing or modifying
- the Library or works based on it.
-
-11. Each time you redistribute the Library (or any work based on the
- Library), the recipient automatically receives a license from the
- original licensor to copy, distribute, link with or modify the
- Library subject to these terms and conditions. You may not impose
- any further restrictions on the recipients’ exercise of the rights
- granted herein. You are not responsible for enforcing compliance by
- third parties with this License.
-
-12. If, as a consequence of a court judgment or allegation of patent
- infringement or for any other reason (not limited to patent issues),
- conditions are imposed on you (whether by court order, agreement or
- otherwise) that contradict the conditions of this License, they do
- not excuse you from the conditions of this License. If you cannot
- distribute so as to satisfy simultaneously your obligations under
- this License and any other pertinent obligations, then as a
- consequence you may not distribute the Library at all. For example,
- if a patent license would not permit royalty-free redistribution of
- the Library by all those who receive copies directly or indirectly
- through you, then the only way you could satisfy both it and this
- License would be to refrain entirely from distribution of the
- Library.
-
- If any portion of this section is held invalid or unenforceable
- under any particular circumstance, the balance of the section is
- intended to apply, and the section as a whole is intended to apply
- in other circumstances.
-
- It is not the purpose of this section to induce you to infringe any
- patents or other property right claims or to contest validity of any
- such claims; this section has the sole purpose of protecting the
- integrity of the free software distribution system which is
- implemented by public license practices. Many people have made
- generous contributions to the wide range of software distributed
- through that system in reliance on consistent application of that
- system; it is up to the author/donor to decide if he or she is
- willing to distribute software through any other system and a
- licensee cannot impose that choice.
-
- This section is intended to make thoroughly clear what is believed
- to be a consequence of the rest of this License.
-
-13. If the distribution and/or use of the Library is restricted in
- certain countries either by patents or by copyrighted interfaces,
- the original copyright holder who places the Library under this
- License may add an explicit geographical distribution limitation
- excluding those countries, so that distribution is permitted only in
- or among countries not thus excluded. In such case, this License
- incorporates the limitation as if written in the body of this
- License.
-
-14. The Free Software Foundation may publish revised and/or new versions
- of the Lesser General Public License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns.
-
- Each version is given a distinguishing version number. If the
- Library specifies a version number of this License which applies to
- it and “any later version”, you have the option of following the
- terms and conditions either of that version or of any later version
- published by the Free Software Foundation. If the Library does not
- specify a license version number, you may choose any version ever
- published by the Free Software Foundation.
-
-15. If you wish to incorporate parts of the Library into other free
- programs whose distribution conditions are incompatible with these,
- write to the author to ask for permission. For software which is
- copyrighted by the Free Software Foundation, write to the Free
- Software Foundation; we sometimes make exceptions for this. Our
- decision will be guided by the two goals of preserving the free
- status of all derivatives of our free software and of promoting the
- sharing and reuse of software generally.
-
- NO WARRANTY
-16. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
- WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
- PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND,
- EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
- LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
- THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-17. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
- WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
- AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
- FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
- CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
- LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
- RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
- FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
- SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGES.
-
-**END OF TERMS AND CONDITIONS**
-
-**How to Apply These Terms to Your New Libraries**
-
-If you develop a new library, and you want it to be of the greatest
-possible use to the public, we recommend making it free software that
-everyone can redistribute and change. You can do so by permitting
-redistribution under these terms (or, alternatively, under the terms of
-the ordinary General Public License).
-
-To apply these terms, attach the following notices to the library. It is
-safest to attach them to the start of each source file to most
-effectively convey the exclusion of warranty; and each file should have
-at least the “copyright” line and a pointer to where the full notice is
-found.
-
-::
-
- one line to give the library's name and an idea of what it does.
- Copyright (C) year name of author
-
- This library 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 of the License, or (at
- your option) any later version.
-
- This library 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 this library; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
- USA.
-
-Also add information on how to contact you by electronic and paper mail.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a “copyright disclaimer” for the library, if
-necessary. Here is a sample; alter the names:
-
-::
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the library
- `Frob' (a library for tweaking knobs) written by James Random Hacker.
-
- signature of Ty Coon, 1 April 1990
- Ty Coon, President of Vice
-
-That’s all there is to it!
-
-.. _GNU_002dFDL:
-
-GNU-FDL
-=======
-
-license
-GNU Free Documentation License
-Version 1.3, 3 November 2008
-::
-
- Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
- http://fsf.org/
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-1. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- functional and useful document free in the sense of freedom: to
- assure everyone the effective freedom to copy and redistribute it,
- with or without modifying it, either commercially or
- noncommercially. Secondarily, this License preserves for the author
- and publisher a way to get credit for their work, while not being
- considered responsible for modifications made by others.
-
- This License is a kind of “copyleft”, which means that derivative
- works of the document must themselves be free in the same sense. It
- complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to software
- manuals; it can be used for any textual work, regardless of subject
- matter or whether it is published as a printed book. We recommend
- this License principally for works whose purpose is instruction or
- reference.
-
-2. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work, in any medium,
- that contains a notice placed by the copyright holder saying it can
- be distributed under the terms of this License. Such a notice grants
- a world-wide, royalty-free license, unlimited in duration, to use
- that work under the conditions stated herein. The “Document”, below,
- refers to any such manual or work. Any member of the public is a
- licensee, and is addressed as “you”. You accept the license if you
- copy, modify or distribute the work in a way requiring permission
- under copyright law.
-
- A “Modified Version” of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A “Secondary Section” is a named appendix or a front-matter section
- of the Document that deals exclusively with the relationship of the
- publishers or authors of the Document to the Document’s overall
- subject (or to related matters) and contains nothing that could fall
- directly within that overall subject. (Thus, if the Document is in
- part a textbook of mathematics, a Secondary Section may not explain
- any mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of legal,
- commercial, philosophical, ethical or political position regarding
- them.
-
- The “Invariant Sections” are certain Secondary Sections whose titles
- are designated, as being those of Invariant Sections, in the notice
- that says that the Document is released under this License. If a
- section does not fit the above definition of Secondary then it is
- not allowed to be designated as Invariant. The Document may contain
- zero Invariant Sections. If the Document does not identify any
- Invariant Sections then there are none.
-
- The “Cover Texts” are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice that
- says that the Document is released under this License. A Front-Cover
- Text may be at most 5 words, and a Back-Cover Text may be at most 25
- words.
-
- A “Transparent” copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, that is suitable for revising the document
- straightforwardly with generic text editors or (for images composed
- of pixels) generic paint programs or (for drawings) some widely
- available drawing editor, and that is suitable for input to text
- formatters or for automatic translation to a variety of formats
- suitable for input to text formatters. A copy made in an otherwise
- Transparent file format whose markup, or absence of markup, has been
- arranged to thwart or discourage subsequent modification by readers
- is not Transparent. An image format is not Transparent if used for
- any substantial amount of text. A copy that is not “Transparent” is
- called “Opaque”.
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTEX input format, SGML
- or XML using a publicly available DTD, and standard-conforming
- simple HTML, PostScript or PDF designed for human modification.
- Examples of transparent image formats include PNG, XCF and JPG.
- Opaque formats include proprietary formats that can be read and
- edited only by proprietary word processors, SGML or XML for which
- the DTD and/or processing tools are not generally available, and the
- machine-generated HTML, PostScript or PDF produced by some word
- processors for output purposes only.
-
- The “Title Page” means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, “Title
- Page” means the text near the most prominent appearance of the
- work’s title, preceding the beginning of the body of the text.
-
- The “publisher” means any person or entity that distributes copies
- of the Document to the public.
-
- A section “Entitled XYZ” means a named subunit of the Document whose
- title either is precisely XYZ or contains XYZ in parentheses
- following text that translates XYZ in another language. (Here XYZ
- stands for a specific section name mentioned below, such as
- “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To
- “Preserve the Title” of such a section when you modify the Document
- means that it remains a section “Entitled XYZ” according to this
- definition.
-
- The Document may include Warranty Disclaimers next to the notice
- which states that this License applies to the Document. These
- Warranty Disclaimers are considered to be included by reference in
- this License, but only as regards disclaiming warranties: any other
- implication that these Warranty Disclaimers may have is void and has
- no effect on the meaning of this License.
-
-3. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You may
- not use technical measures to obstruct or control the reading or
- further copying of the copies you make or distribute. However, you
- may accept compensation in exchange for copies. If you distribute a
- large enough number of copies you must also follow the conditions in
- section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
-4. COPYING IN QUANTITY
-
- If you publish printed copies (or copies in media that commonly have
- printed covers) of the Document, numbering more than 100, and the
- Document’s license notice requires Cover Texts, you must enclose the
- copies in covers that carry, clearly and legibly, all these Cover
- Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
- the back cover. Both covers must also clearly and legibly identify
- you as the publisher of these copies. The front cover must present
- the full title with all words of the title equally prominent and
- visible. You may add other material on the covers in addition.
- Copying with changes limited to the covers, as long as they preserve
- the title of the Document and satisfy these conditions, can be
- treated as verbatim copying in other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto adjacent
- pages.
-
- If you publish or distribute Opaque copies of the Document numbering
- more than 100, you must either include a machine-readable
- Transparent copy along with each Opaque copy, or state in or with
- each Opaque copy a computer-network location from which the general
- network-using public has access to download using public-standard
- network protocols a complete Transparent copy of the Document, free
- of added material. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will remain
- thus accessible at the stated location until at least one year after
- the last time you distribute an Opaque copy (directly or through
- your agents or retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of copies,
- to give them a chance to provide you with an updated version of the
- Document.
-
-5. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document under
- the conditions of sections 2 and 3 above, provided that you release
- the Modified Version under precisely this License, with the Modified
- Version filling the role of the Document, thus licensing
- distribution and modification of the Modified Version to whoever
- possesses a copy of it. In addition, you must do these things in the
- Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title as a
- previous version if the original publisher of that version gives
- permission.
-
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it has
- fewer than five), unless they release you from this requirement.
-
- C. State on the Title page the name of the publisher of the Modified
- Version, as the publisher.
-
- D. Preserve all the copyright notices of the Document.
-
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
-
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document’s license
- notice.
-
- H. Include an unaltered copy of this License.
-
- I. Preserve the section Entitled “History”, Preserve its Title, and
- add to it an item stating at least the title, year, new authors,
- and publisher of the Modified Version as given on the Title Page.
- If there is no section Entitled “History” in the Document, create
- one stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item describing
- the Modified Version as stated in the previous sentence.
-
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions
- it was based on. These may be placed in the “History” section.
- You may omit a network location for a work that was published at
- least four years before the Document itself, or if the original
- publisher of the version it refers to gives permission.
-
- K. For any section Entitled “Acknowledgements” or “Dedications”,
- Preserve the Title of the section, and preserve in the section
- all the substance and tone of each of the contributor
- acknowledgements and/or dedications given therein.
-
- L. Preserve all the Invariant Sections of the Document, unaltered in
- their text and in their titles. Section numbers or the equivalent
- are not considered part of the section titles.
-
- M. Delete any section Entitled “Endorsements”. Such a section may
- not be included in the Modified Version.
-
- N. Do not retitle any existing section to be Entitled “Endorsements”
- or to conflict in title with any Invariant Section.
-
- O. Preserve any Warranty Disclaimers.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option designate
- some or all of these sections as invariant. To do this, add their
- titles to the list of Invariant Sections in the Modified Version’s
- license notice. These titles must be distinct from any other section
- titles.
-
- You may add a section Entitled “Endorsements”, provided it contains
- nothing but endorsements of your Modified Version by various
- parties—for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition of
- a standard.
-
- You may add a passage of up to five words as a Front-Cover Text, and
- a passage of up to 25 words as a Back-Cover Text, to the end of the
- list of Cover Texts in the Modified Version. Only one passage of
- Front-Cover Text and one of Back-Cover Text may be added by (or
- through arrangements made by) any one entity. If the Document
- already includes a cover text for the same cover, previously added
- by you or by arrangement made by the same entity you are acting on
- behalf of, you may not add another; but you may replace the old one,
- on explicit permission from the previous publisher that added the
- old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
-6. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination all
- of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your combined
- work in its license notice, and that you preserve all their Warranty
- Disclaimers.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique
- number. Make the same adjustment to the section titles in the list
- of Invariant Sections in the license notice of the combined work.
-
- In the combination, you must combine any sections Entitled “History”
- in the various original documents, forming one section Entitled
- “History”; likewise combine any sections Entitled
- “Acknowledgements”, and any sections Entitled “Dedications”. You
- must delete all sections Entitled “Endorsements.”
-
-7. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the documents
- in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert a
- copy of this License into the extracted document, and follow this
- License in all other respects regarding verbatim copying of that
- document.
-
-8. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other separate
- and independent documents or works, in or on a volume of a storage
- or distribution medium, is called an “aggregate” if the copyright
- resulting from the compilation is not used to limit the legal rights
- of the compilation’s users beyond what the individual works permit.
- When the Document is included in an aggregate, this License does not
- apply to the other works in the aggregate which are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one half
- of the entire aggregate, the Document’s Cover Texts may be placed on
- covers that bracket the Document within the aggregate, or the
- electronic equivalent of covers if the Document is in electronic
- form. Otherwise they must appear on printed covers that bracket the
- whole aggregate.
-
-9. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License, and all the license notices in the
- Document, and any Warranty Disclaimers, provided that you also
- include the original English version of this License and the
- original versions of those notices and disclaimers. In case of a
- disagreement between the translation and the original version of
- this License or a notice or disclaimer, the original version will
- prevail.
-
- If a section in the Document is Entitled “Acknowledgements”,
- “Dedications”, or “History”, the requirement (section 4) to Preserve
- its Title (section 1) will typically require changing the actual
- title.
-
-10. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided under this License. Any attempt
- otherwise to copy, modify, sublicense, or distribute it is void, and
- will automatically terminate your rights under this License.
-
- However, if you cease all violation of this License, then your
- license from a particular copyright holder is reinstated (a)
- provisionally, unless and until the copyright holder explicitly and
- finally terminates your license, and (b) permanently, if the
- copyright holder fails to notify you of the violation by some
- reasonable means prior to 60 days after the cessation.
-
- Moreover, your license from a particular copyright holder is
- reinstated permanently if the copyright holder notifies you of the
- violation by some reasonable means, this is the first time you have
- received notice of violation of this License (for any work) from
- that copyright holder, and you cure the violation prior to 30 days
- after your receipt of the notice.
-
- Termination of your rights under this section does not terminate the
- licenses of parties who have received copies or rights from you
- under this License. If your rights have been terminated and not
- permanently reinstated, receipt of a copy of some or all of the same
- material does not give you any rights to use it.
-
-11. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered version
- of this License “or any later version” applies to it, you have the
- option of following the terms and conditions either of that
- specified version or of any later version that has been published
- (not as a draft) by the Free Software Foundation. If the Document
- does not specify a version number of this License, you may choose
- any version ever published (not as a draft) by the Free Software
- Foundation. If the Document specifies that a proxy can decide which
- future versions of this License can be used, that proxy’s public
- statement of acceptance of a version permanently authorizes you to
- choose that version for the Document.
-
-12. RELICENSING
-
- “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
- World Wide Web server that publishes copyrightable works and also
- provides prominent facilities for anybody to edit those works. A
- public wiki that anybody can edit is an example of such a server. A
- “Massive Multiauthor Collaboration” (or “MMC”) contained in the site
- means any set of copyrightable works thus published on the MMC site.
-
- “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
- license published by Creative Commons Corporation, a not-for-profit
- corporation with a principal place of business in San Francisco,
- California, as well as future copyleft versions of that license
- published by that same organization.
-
- “Incorporate” means to publish or republish a Document, in whole or
- in part, as part of another Document.
-
- An MMC is “eligible for relicensing” if it is licensed under this
- License, and if all works that were first published under this
- License somewhere other than this MMC, and subsequently incorporated
- in whole or in part into the MMC, (1) had no cover texts or
- invariant sections, and (2) were thus incorporated prior to November
- 1, 2008.
-
- The operator of an MMC Site may republish an MMC contained in the
- site under CC-BY-SA on the same site at any time before August 1,
- 2009, provided the MMC is eligible for relicensing.
-
-**ADDENDUM: How to use this License for your documents**
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
-::
-
- Copyright (C) year your name.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the “with…Texts.” line with this:
-
-::
-
- with the Invariant Sections being list their titles, with
- the Front-Cover Texts being list, and with the Back-Cover Texts
- being list.
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of free
-software license, such as the GNU General Public License, to permit
-their use in free software.
-
-.. _Concept-Index:
-
-Concept Index
-=============
-
-.. |image0| image:: arch-api.png
-
diff --git a/merchant-manual.rst b/merchant-manual.rst
deleted file mode 100644
index 563a1e9..0000000
--- a/merchant-manual.rst
+++ /dev/null
@@ -1,1228 +0,0 @@
-
-
-This manual is for the GNU Taler merchant backend (version 0.5.0, 17
-August 2019),
-
-Copyright © 2016, 2017, 2019 Taler Systems SA
-
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with no
- Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
- Texts. A copy of the license is included in the section entitled “GNU
- Free Documentation License”.
-
-The GNU Taler manual for Web shops
-##################################
-
-This manual is for the GNU Taler merchant backend (version 0.5.0, 17
-August 2019),
-
-Copyright © 2016, 2017, 2019 Taler Systems SA
-
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with no
- Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
- Texts. A copy of the license is included in the section entitled “GNU
- Free Documentation License”.
-
-Introduction
-============
-
-About GNU Taler
----------------
-
-GNU Taler is an open protocol for an electronic payment system with a
-free software reference implementation. GNU Taler offers secure, fast
-and easy payment processing using well understood cryptographic
-techniques. GNU Taler allows customers to remain anonymous, while
-ensuring that merchants can be held accountable by governments. Hence,
-GNU Taler is compatible with anti-money-laundering (AML) and
-know-your-customer (KYC) regulation, as well as data protection
-regulation (such as GDPR).
-
-GNU Taler is not yet production-ready, after following this manual you
-will have a backend that can process payments in “KUDOS”, but not
-regular currencies. This is not so much because of limitations in the
-backend, but because we are not aware of a Taler exchange operator
-offering regular currencies today.
-
-.. _About-this-manual:
-
-About this manual
------------------
-
-This tutorial targets system administrators who want to install a GNU
-Taler merchant *backend*.
-
-We expect some moderate familiarity with the compilation and
-installation of free software packages. An understanding of cryptography
-is not required.
-
-This first chapter of the tutorial will give a brief overview of the
-overall Taler architecture, describing the environment in which the
-Taler backend operates. The second chapter then explains how to install
-the software, including key dependencies. The third chapter will explain
-how to configure the backend, including in particular the configuration
-of the bank account details of the merchant.
-
-The last chapter gives some additional information about advanced topics
-which will be useful for system administrators but are not necessary for
-operating a basic backend.
-
-.. _Architecture-overview:
-
-Architecture overview
----------------------
-
-crypto-currency
-KUDOS
-Taler is a pure payment system, not a new crypto-currency. As such, it
-operates in a traditional banking context. In particular, this means
-that in order to receive funds via Taler, the merchant must have a
-regular bank account, and payments can be executed in ordinary
-currencies such as USD or EUR. For testing purposes, Taler uses a
-special currency “KUDOS” and includes its own special bank.
-
-The Taler software stack for a merchant consists of four main
-components:
-
-- frontend
- A frontend which interacts with the customer’s browser. The frontend
- enables the customer to build a shopping cart and place an order.
- Upon payment, it triggers the respective business logic to satisfy
- the order. This component is not included with Taler, but rather
- assumed to exist at the merchant. This manual describes how to
- integrate Taler with Web shop frontends.
-
-- back office
- A back office application that enables the shop operators to view
- customer orders, match them to financial transfers, and possibly
- approve refunds if an order cannot be satisfied. This component is
- again not included with Taler, but rather assumed to exist at the
- merchant. This manual will describe how to integrate such a component
- to handle payments managed by Taler.
-
-- backend
- A Taler-specific payment backend which makes it easy for the frontend
- to process financial transactions with Taler. The next two chapters
- will describe how to install and configure this backend.
-
-- DBMS
- Postgres
- A DBMS which stores the transaction history for the Taler backend.
- For now, the GNU Taler reference implemenation only supports
- Postgres, but the code could be easily extended to support another
- DBMS.
-
-The following image illustrates the various interactions of these key
-components:
-
-::
-
- Missing diagram image
-
-RESTful
-Basically, the backend provides the cryptographic protocol support,
-stores Taler-specific financial information in a DBMS and communicates
-with the GNU Taler exchange over the Internet. The frontend accesses the
-backend via a RESTful API. As a result, the frontend never has to
-directly communicate with the exchange, and also does not deal with
-sensitive data. In particular, the merchant’s signing keys and bank
-account information is encapsulated within the Taler backend.
-
-Installation
-============
-
-This chapter describes how to install the GNU Taler merchant backend.
-
-Installing Taler using Docker
------------------------------
-
-This section provides instructions for the merchant backend installation
-using ‘Docker‘.
-
-For security reasons, we run Docker against a VirtualBox instance, so
-the ``docker`` command should connect to a ``docker-machine`` instance
-that uses the VirtualBox driver.
-
-Therefore, the needed tools are: “docker“, “docker-machine“, and
-“docker-compose“. Please refer to Docker’s official [1]_ documentation
-in order to get those components installed, as that is not in this
-manual’s scope.
-
-Before starting to build the merchant’s image, make sure a
-“docker-machine“ instance is up and running.
-
-Because all of the Docker source file are kept in our “deployment“
-repository, we start by checking out the ``git://taler.net/deployment``
-codebase:
-
-::
-
- $ git clone git://taler.net/deployment
-
-Now we actually build the merchant’s image. From the same directory as
-above:
-
-::
-
- $ cd deployment/docker/merchant/
- $ docker-compose build
-
-If everything worked as expected, the merchant is ready to be launched.
-From the same directory as the previous step:
-
-::
-
- # Recall: the docker-machine should be up and running.
- $ docker-compose up
-
-You should see some live logging from all the involved containers. At
-this stage of development, you should also ignore some (harmless) error
-message from postresql about already existing roles and databases.
-
-To test if everything worked as expected, it suffices to issue a simple
-request to the merchant, as:
-
-::
-
- $ curl http://$(docker-machine ip)/
- # A greeting message should be returned by the merchant.
-
-.. _Generic-instructions:
-
-Generic instructions
---------------------
-
-This section provides generic instructions for the merchant backend
-installation independent of any particular operating system. Operating
-system specific instructions are provided in the following sections. You
-should follow the operating system specific instructions if those are
-available, and only consult the generic instructions if no
-system-specific instructions are provided for your specific operating
-system.
-
-.. _Installation-of-dependencies:
-
-Installation of dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following packages need to be installed before we can compile the
-backend:
-
-- 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 sections will provide detailed instructions for installing
-the libgnunetutil and GNU Taler exchange dependencies.
-
-.. _Installing-libgnunetutil:
-
-Installing libgnunetutil
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-GNUnet
-Before you install libgnunetutil, you must download and install the
-dependencies mentioned in the previous section, 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``.
-
-.. _Installing-the-GNU-Taler-exchange:
-
-Installing the GNU Taler exchange
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-exchange
-After installing GNUnet, you can download and install the exchange 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.
-
-.. _Installing-the-GNU-Taler-merchant-backend:
-
-Installing the GNU Taler merchant backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-backend
-The following steps assume all dependencies are installed.
-
-Use the following commands to download and install the merchant backend:
-
-::
-
- $ 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
-
-Note that you have to specify ``--with-exchange=/usr/local`` and/or
-``--with-exchange=/usr/local`` if you installed the exchange and/or
-GNUnet to ``/usr/local`` in the previous steps.
-
-.. _Installing-Taler-on-Debian-GNU_002fLinux:
-
-Installing Taler on Debian GNU/Linux
-------------------------------------
-
-Wheezy
-Debian
-Debian wheezy is too old and lacks most of the packages required.
-
-On Debian jessie, only GNU libmicrohttpd needs to be compiled from
-source. To install dependencies on Debian jesse, run the following
-commands:
-
-::
-
- # apt-get install \
- autoconf \
- automake \
- autopoint \
- libtool \
- libltdl-dev \
- libunistring-dev \
- libcurl4-gnutls-dev \
- libgcrypt20-dev \
- libjansson-dev \
- libpq-dev \
- postgresql-9.4
- # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz
- # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
- # gpg -v libmicrohttpd-latest.tar.gz # Should show signed by
939E6BE1E29FC3CC
- # tar xf libmicrohttpd-latest.tar.gz
- # cd libmicrohttpd-0*
- # ./configure
- # make install
-
-For more recent versions of Debian, you should instead run:
-
-::
-
- # apt-get install \
- autoconf \
- automake \
- autopoint \
- libtool \
- libltdl-dev \
- libunistring-dev \
- libcurl4-gnutls-dev \
- libgcrypt20-dev \
- libjansson-dev \
- libpq-dev \
- postgresql-9.5 \
- libmicrohttpd-dev
-
-For the rest of the installation, follow the generic installation
-instructions starting with the installation of libgnunetutil. Note that
-if you used the Debian wheezy instructions above, you need to pass
-``--with-microhttpd=/usr/local/`` to all ``configure`` invocations.
-
-How to configure the merchant’s backend
-=======================================
-
-taler-config
-taler.conf
-The installation already provides reasonable defaults for most of the
-configuration options. However, some must be provided, in particular the
-database account and bank account that the backend should use. By
-default, the file ``$HOME/.config/taler.conf`` is where the Web shop
-administrator specifies configuration values that augment or override
-the defaults. The format of the configuration file is the well-known INI
-file format. You can edit the file by hand, or use the ``taler-config``
-commands given as examples. For more information on ``taler-config``,
-see `Using taler-config <#Using-taler_002dconfig>`__.
-
-.. _Backend-options:
-
-Backend options
----------------
-
-The following table describes the options that commonly need to be
-modified. Here, the notation ``[$section]/$option`` denotes the option
-``$option`` under the section ``[$section]`` in the configuration file.
-
-Service address
- The following option sets the transport layer address used by the
- merchant backend:
-
- UNIX domain socket
- TCP
- ::
-
- [MERCHANT]/SERVE = TCP | UNIX
-
- If given,
-
- - ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT``
-
- - ``UNIX``, then we need to set the unix domain socket path and mode
- in ``[MERCHANT]/UNIXPATH`` and ``[MERCHANT]/UNIXPATH_MODE``. The
- latter takes the usual permission mask given as a number, e.g. 660
- for user/group read-write access.
-
- The frontend can then connect to the backend over HTTP using the
- specified address. If frontend and backend run within the same
- operating system, the use of a UNIX domain socket is recommended to
- avoid accidentally exposing the backend to the network.
-
- port
- To run the Taler backend on TCP port 8888, use:
-
- ::
-
- $ taler-config -s MERCHANT -o SERVE -V TCP
- $ taler-config -s MERCHANT -o PORT -V 8888
-
-Currency
- Which currency the Web shop deals in, i.e. “EUR” or “USD”, is
- specified using the option
-
- currency
- KUDOS
- ::
-
- [TALER]/CURRENCY
-
- For testing purposes, the currency MUST match “KUDOS” so that tests
- will work with the Taler demonstration exchange at
- https://exchange.demo.taler.net/:
-
- ::
-
- $ taler-config -s TALER -o CURRENCY -V KUDOS
-
-Database
- DBMS
- In principle is possible for the backend to support different DBMSs.
- The option
-
- ::
-
- [MERCHANT]/DB
-
- specifies which DBMS is to be used. However, currently only the value
- "postgres" is supported. This is also the default.
-
- In addition to selecting the DBMS software, the backend requires
- DBMS-specific options to access the database.
-
- For postgres, you need to provide:
-
- ::
-
- [merchantdb-postgres]/config
-
- Postgres
- This option specifies a postgres access path using the format
- ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the
- Postgres database you want to use. Suppose ``$USER`` is the name of
- the user who will run the backend process. Then, you need to first
- run
-
- ::
-
- $ sudu -u postgres createuser -d $USER
-
- as the Postgres database administrator (usually ``postgres``) to
- grant ``$USER`` the ability to create new databases. Next, you should
- as ``$USER`` run:
-
- ::
-
- $ createdb $DBNAME
-
- to create the backend’s database. Here, ``$DBNAME`` must match the
- database name given in the configuration file.
-
- To configure the Taler backend to use this database, run:
-
- ::
-
- $ taler-config -s MERCHANTDB-postgres -o CONFIG \
- -V postgres:///$DBNAME
-
-Exchange
- exchange
- To add an exchange to the list of trusted payment service providers,
- you create a section with a name that starts with “exchange-”. In
- that section, the following options need to be configured:
-
- - The “url” option specifies the exchange’s base URL. For example,
- to use the Taler demonstrator use:
-
- ::
-
- $ taler-config -s EXCHANGE-demo -o URL \
- -V https://exchange.demo.taler.net/
-
- - master key
- The “master_key” option specifies the exchange’s master public key
- in base32 encoding. For the Taler demonstrator, use:
-
- ::
-
- $ taler-config -s EXCHANGE-demo -o master_key \
- -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
-
- Note that multiple exchanges can be added to the system by using
- different tokens in place of ``demo`` in the example above. Note
- that all of the exchanges must use the same currency. If you need
- to support multiple currencies, you need to configure a backend
- per currency.
-
-Instances
- instance
- The backend allows the user to run multiple instances of shops with
- distinct business entities against a single backend. Each instance
- uses its own bank accounts and key for signing contracts. It is
- mandatory to configure a "default" instance.
-
- - The “KEYFILE” option specifies the file containing the instance’s
- private signing key. For example, use:
-
- ::
-
- $ taler-config -s INSTANCE-default -o KEYFILE \
- -V '${TALER_CONFIG_HOME}/merchant/instace/default.key'
-
- - The “NAME” option specifies a human-readable name for the
- instance. For example, use:
-
- ::
-
- $ taler-config -s INSTANCE-default -o NAME \
- -V 'Kudos Inc.'
-
- - The optional “TIP_EXCHANGE” and “TIP_EXCHANGE_PRIV_FILENAME”
- options are discussed in Tipping visitors
-
-Accounts
- wire format
- In order to receive payments, the merchant backend needs to
- communicate bank account details to the exchange. For this, the
- configuration must include one or more sections named “ACCOUNT-name”
- where ``name`` can be replaced by some human-readable word
- identifying the account. For each section, the following options
- should be provided:
-
- - The “URL” option specifies a ``payto://``-URL for the account of
- the merchant. For example, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o NAME \
- -V 'payto://x-taler-bank/bank.demo.taler.net/4'
-
- - The “WIRE_RESPONSE” option specifies where Taler should store the
- (salted) JSON encoding of the wire account. The file given will be
- created if it does not exist. For example, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \
- -V '{$TALER_CONFIG_HOME}/merchant/bank.json'
-
- - The “PLUGIN” option specifies which wire plugin should be used for
- this account. The plugin must support the wire method used by the
- URL. For example, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o PLUGIN \
- -V taler_bank
-
- - For each ``instance`` that should use this account, you should set
- ``HONOR_instance`` and ``ACTIVE_instance`` to YES. The first
- option will cause the instance to accept payments to the account
- (for existing contracts), while the second will cause the backend
- to include the account as a possible option for new contracts.
-
- For example, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o HONOR_default \
- -V YES
- $ taler-config -s ACCOUNT-bank -o ACTIVE_default \
- -V YES
-
- to use “account-bank” for the “default” instance.
-
- Depending on which PLUGIN you configured, you may additionally
- specfiy authentication options to enable the plugin to use the
- account.
-
- For example, with ``taler_bank`` plugin, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o TALER_BANK_AUTH_METHOD \
- -V basic
- $ taler-config -s ACCOUNT-bank -o USERNAME \
- -V user42
- $ taler-config -s ACCOUNT-bank -o PASSWORD \
- -V pass42
-
- Note that additional instances can be specified using different
- tokens in the section name instead of ``default``.
-
-.. _Sample-backend-configuration:
-
-Sample backend configuration
-----------------------------
-
-configuration
-The following is an example for a complete backend configuration:
-
-::
-
- [TALER]
- CURRENCY = KUDOS
-
- [MERCHANT]
- SERVE = TCP
- PORT = 8888
- DATABASE = postgres
-
- [MERCHANTDB-postgres]
- CONFIG = postgres:///donations
-
- [INSTANCE-default]
- KEYFILE = $DATADIR/key.priv
- NAME = "Kudos Inc."
-
- [ACCOUNT-bank]
- URL = payto://x-taler-bank/bank.demo.taler.net/4
- WIRE_RESPONSE = $DATADIR/bank.json
- PLUGIN = taler_bank
- HONOR_default = YES
- ACTIVE_default = YES
- TALER_BANK_AUTH_METHOD = basic
- USERNAME = my_user
- PASSWORD = 1234pass
-
- [EXCHANGE-trusted]
- URL = https://exchange.demo.taler.net/
- MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
- CURRENCY = KUDOS
-
-Given the above configuration, the backend will use a database named
-``donations`` within Postgres.
-
-The backend will deposit the coins it receives to the exchange at
-https://exchange.demo.taler.net/, which has the master key
-"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".
-
-Please note that ``doc/config.sh`` will walk you through all
-configuration steps, showing how to invoke ``taler-config`` for each of
-them.
-
-.. _Launching-the-backend:
-
-Launching the backend
----------------------
-
-backend
-taler-merchant-httpd
-Assuming you have configured everything correctly, you can launch the
-merchant backend using:
-
-::
-
- $ taler-merchant-httpd
-
-When launched for the first time, this command will print a message
-about generating your private key. If everything worked as expected, the
-command
-
-::
-
- $ curl http://localhost:8888/
-
-should return the message
-
-::
-
- Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
-
-Please note that your backend is right now likely globally reachable.
-Production systems should be configured to bind to a UNIX domain socket
-or properly restrict access to the port.
-
-.. _Testing:
-
-Testing
-=======
-
-The tool ``taler-merchant-generate-payments`` can be used to test the
-merchant backend installation. It implements all the payment’s steps in
-a programmatically way, relying on the backend you give it as input.
-Note that this tool gets installed along all the merchant backend’s
-binaries.
-
-This tool gets configured by a config file, that must have the following
-layout:
-
-::
-
- [PAYMENTS-GENERATOR]
-
- # The exchange used during the test: make sure the merchant backend
- # being tested accpets this exchange.
- # If the sysadmin wants, she can also install a local exchange
- # and test against it.
- EXCHANGE = https://exchange.demo.taler.net/
-
- # This value must indicate some URL where the backend
- # to be tested is listening; it doesn't have to be the
- # "official" one, though.
- MERCHANT = http://localbackend/
-
- # This value is used when the tool tries to withdraw coins,
- # and must match the bank used by the exchange. If the test is
- # done against the exchange at https://exchange.demo.taler.net/,
- # then this value can be "https://bank.demo.taler.net/";.
- BANK = https://bank.demo.taler.net/
-
- # The merchant instance in charge of serving the payment.
- # Make sure this instance has a bank account at the same bank
- # indicated by the 'bank' option above.
- INSTANCE = default
-
- # The currency used during the test. Must match the one used
- # by merchant backend and exchange.
- CURRENCY = KUDOS
-
-Run the test in the following way:
-
-::
-
- $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL]
-
-The argument ``config`` given to ``-c`` points to the configuration file
-and is optional – ``~/.config/taler.conf`` will be checked by default.
-By default, the tool forks two processes: one for the merchant backend,
-and one for the exchange. The option ``-e`` (``-m``) avoids any exchange
-(merchant backend) fork, and just runs the generator against the
-exchange (merchant backend) running at ``EURL`` (``MURL``).
-
-Please NOTE that the generator contains *hardcoded* values, as for
-deposit fees of the coins it uses. In order to work against the used
-exchange, those values MUST match the ones used by the exchange.
-
-The following example shows how the generator "sets" a deposit fee of
-EUR:0.01 for the 5 EURO coin.
-
-::
-
- // from <merchant_repository>/src/sample/generate_payments.c
- { .oc = OC_PAY,
- .label = "deposit-simple",
- .expected_response_code = MHD_HTTP_OK,
- .details.pay.contract_ref = "create-proposal-1",
- .details.pay.coin_ref = "withdraw-coin-1",
- .details.pay.amount_with_fee = concat_amount (currency, "5"),
- .details.pay.amount_without_fee = concat_amount (currency, "4.99") },
-
-The logic calculates the deposit fee according to the subtraction:
-``amount_with_fee - amount_without_fee``.
-
-The following example shows a 5 EURO coin configuration - needed by the
-used exchange - which is compatible with the hardcoded example above.
-
-::
-
- [COIN_eur_5]
- value = EUR:5
- duration_overlap = 5 minutes
- duration_withdraw = 7 days
- duration_spend = 2 years
- duration_legal = 3 years
- fee_withdraw = EUR:0.00
- fee_deposit = EUR:0.01 # important bit
- fee_refresh = EUR:0.00
- fee_refund = EUR:0.00
- rsa_keysize = 1024
-
-If the command terminates with no errors, then the merchant backend is
-correctly installed.
-
-After this operation is done, the merchant database will have some dummy
-data in it, so it may be convenient to clean all the tables; to this
-purpose, issue the following command:
-
-::
-
- $ taler-merchant-dbinit -r
-
-
-Advanced topics
-===============
-
-Configuration format
---------------------
-
-configuration
-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/.
-
-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.
-
-.. _Using-taler_002dconfig:
-
-Using taler-config
-------------------
-
-taler-config
-The tool ``taler-config`` can be used to extract or manipulate
-configuration values; however, the configuration use the well-known INI
-file format and can also be edited by hand.
-
-Run
-
-::
-
- $ taler-config -s $SECTION
-
-to list all of the configuration values in section ``$SECTION``.
-
-Run
-
-::
-
- $ taler-config -s $section -o $option
-
-to extract the respective configuration value for option ``$option`` in
-section ``$section``.
-
-Finally, to change a setting, run
-
-::
-
- $ taler-config -s $section -o $option -V $value
-
-to set the respective configuration value to ``$value``. Note that you
-have to manually restart the Taler backend after you change the
-configuration to make the new configuration go into effect.
-
-Some default options will use $-variables, such as ``$DATADIR`` within
-their value. To expand the ``$DATADIR`` or other $-variables in the
-configuration, pass the ``-f`` option to ``taler-config``. For example,
-compare:
-
-::
-
- $ taler-config -s ACCOUNT-bank \
- -o WIRE_RESPONSE
- $ taler-config -f -s ACCOUNT-bank \
- -o WIRE_RESPONSE
-
-While the configuration file is typically located at
-``$HOME/.config/taler.conf``, an alternative location can be specified
-to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c``
-option.
-
-.. _Merchant-key-management:
-
-Merchant key management
------------------------
-
-merchant key
-KEYFILE
-The option “KEYFILE” in the section “INSTANCE-default” specifies the
-path to the instance’s private key. You do not need to create a key
-manually, the backend will generate it automatically if it is missing.
-While generally unnecessary, it is possible to display the corresponding
-public key using the ``gnunet-ecc`` command-line tool:
-
-::
-
- $ gnunet-ecc -p \
- $(taler-config -f -s INSTANCE-default \
- -o KEYFILE)
-
-.. _SEPA-configuration:
-
-Using the SEPA wire transfer method
------------------------------------
-
-SEPA
-EBICS
-The following is a sample configuration for the SEPA wire transfer
-method: [2]_.
-
-Then, to configure the EBICS backend for SEPA payments in EUR, the
-following configuration options need to be set:
-
-::
-
- $ taler-config -s TALER -o CURRENCY -V EUR
- $ taler-config -s ACCOUNT-e -o PLUGIN -V ebics
- $ taler-config -s ACCOUNT-e -o URL \
- -V payto://sepa/XY00111122223333444455556666
- $ taler-config -s ACCOUNT-e -o WIRE_RESPONSE
- -V '${DATADIR}/b.json'
-
-Please note that you will also have to configure an exchange and/or
-auditors that support SEPA. However, we cannot explain how to do this
-yet as such entities do not yet exist. Once such entities do exist, we
-expect future versions of the Taler backend to ship with pre-configured
-exchanges and auditors for common denominations.
-
-.. _Tipping-visitors:
-
-Tipping visitors
-----------------
-
-tipping
-Taler can also be used to tip Web site visitors. For example, you may be
-running an online survey, and you want to reward those people that have
-dutifully completed the survey. If they have installed a Taler wallet,
-you can provide them with a tip for their deeds. This section describes
-how to setup the Taler merchant backend for tipping.
-
-There are four basic steps that must happen to tip a visitor.
-
-.. _Configure-a-reserve-and-exchange-for-tipping:
-
-Configure a reserve and exchange for tipping
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-gnunet-ecc
-reserve key
-To tip users, you first need to create a reserve. A reserve is a pool of
-money held in escrow at the Taler exchange. This is the source of the
-funds for the tips. Tipping will fail (resulting in disappointed
-visitors) if you do not have enough funds in your reserve!
-
-First, we configure the backend. You need to enable tipping for each
-instance separately, or you can use an instance only for tipping. To
-configure the “default” instance for tipping, use the following
-configuration:
-
-::
-
- [INSTANCE-default]
- # this is NOT the tip.priv
- KEYFILE = signing_key.priv
- # replace the URL with the URL of the exchange you will use
- TIP_EXCHANGE = https://exchange:443/
- # here put the path to the file created with "gnunet-ecc -g1 tip.priv"
- TIP_RESERVE_PRIV_FILENAME = tip.priv
-
-Note that the KEYFILE option should have already been present for the
-instance. It has nothing to do with the “tip.priv” file we created
-above, and you should probably use a different file here.
-
-Instead of manually editing the configuration, you could also run:
-
-::
-
- $ taler-config -s INSTANCE-default \
- -o TIP_RESERVE_PRIV_FILENAME \
- -V tip.priv
- $ taler-config -s INSTANCE-default \
- -o TIP_EXCHANGE \
- -V https://exchange:443/
-
-Next, to create the ``TIP_RESERVE_PRIV_FILENAME`` file, use:
-
-::
-
- $ gnunet-ecc -g 1 \
- $(taler-config -f -s INSTANCE-default \
- -o TIP-RESERVE_PRIV_FILENAME)
-
-This will create a file with the private key that will be used to
-identify the reserve. You need to do this once for each instance that is
-configured to tip.
-
-Now you can (re)start the backend with the new configuration.
-
-.. _Fund-the-reserve:
-
-Fund the reserve
-~~~~~~~~~~~~~~~~
-
-reserve
-close
-To fund the reserve, you must first extract the public key from
-“tip.priv”:
-
-::
-
- $ gnunet-ecc --print-public-key \
- $(taler-config -f -s INSTANCE-default \
- -o TIP-RESERVE_PRIV_FILENAME)
-
-In our example, the output for the public key is:
-
-::
-
- QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
-
-You now need to make a wire transfer to the exchange’s bank account
-using the public key as the wire transfer subject. The exchange’s bank
-account details can be found in JSON format at
-“https://exchange:443//wire/METHOD” where METHOD is the respective wire
-method (i.e. “sepa”). Depending on the exchange’s operator, you may also
-be able to find the bank details in a human-readable format on the main
-page of the exchange.
-
-Make your wire transfer and (optionally) check at
-“https://exchange:443/reserve/status/reserve_pub=QPE24X...” whether your
-transfer has arrived at the exchange.
-
-Once the funds have arrived, you can start to use the reserve for
-tipping.
-
-Note that an exchange will typically close a reserve after four weeks,
-wiring all remaining funds back to the sender’s account. Thus, you
-should plan to wire funds corresponding to a campaign of about two weeks
-to the exchange initially. If your campaign runs longer, you should wire
-further funds to the reserve every other week to prevent it from
-expiring.
-
-.. _Authorize-a-tip:
-
-Authorize a tip
-~~~~~~~~~~~~~~~
-
-When your frontend has reached the point where a client is supposed to
-receive a tip, it needs to first authorize the tip. For this, the
-frontend must use the “/tip-authorize” API of the backend. To authorize
-a tip, the frontend has to provide the following information in the body
-of the POST request:
-
-- The amount of the tip
-
-- The justification (only used internally for the back-office)
-
-- The URL where the wallet should navigate next after the tip was
- processed
-
-- The tip-pickup URL (see next section)
-
-In response to this request, the backend will return a tip token, an
-expiration time and the exchange URL. The expiration time will indicate
-how long the tip is valid (when the reserve expires). The tip token is
-an opaque string that contains all the information needed by the wallet
-to process the tip. The frontend must send this tip token to the browser
-in a special “402 Payment Required” response inside the ``X-Taler-Tip``
-header.
-
-The frontend should handle errors returned by the backend, such as
-missconfigured instances or a lack of remaining funds for tipping.
-
-.. _Picking-up-of-the-tip:
-
-Picking up of the tip
-~~~~~~~~~~~~~~~~~~~~~
-
-The wallet will POST a JSON object to the shop’s “/tip-pickup” handler.
-The frontend must then forward this request to the backend. The response
-generated by the backend can then be forwarded directly to the wallet.
-
-.. _Generate-payments:
-
-Generate payments
------------------
-
-testing database
-The merchant codebase offers the ``taler-merchant-benchmark`` tool to
-populate the database with fake payments. This tool is in charge of
-starting a merchant, exchange, and bank processes, and provide them all
-the input to accomplish payments. Note that each component will use its
-own configuration (as they would do in production).
-
-The tool takes all of the values it needs from the command line, with
-some of them being mandatory. Among those, we have:
-
-- ``--currency=K`` Use currency *K*, for example to craft coins to
- withdraw.
-
-- ``--bank-url=URL`` Assume that the bank is serving under the base URL
- *URL*. This option is only actually used by the tool to check if the
- bank was well launched.
-
-- ``--merchant-url=URL`` Reach the merchant through *URL*, for
- downloading contracts and sending payments.
-
-The tool then comes with two operation modes: *ordinary*, and *corner*.
-The first just executes normal payments, meaning that it uses the
-default instance and make sure that all payments get aggregated. The
-second gives the chance to leave some payments unaggregated, and also to
-use merchant instances other than the default (which is, actually, the
-one used by default by the tool).
-
-Note: the abilty of driving the aggregation policy is useful for testing
-the backoffice facility.
-
-Any subcommand is also equipped with the canonical ``--help`` option, so
-feel free to issue the following command in order to explore all the
-possibilities. For example:
-
-::
-
- $ taler-merchant-benchmark corner --help
-
-will show all the options offered by the *corner* mode. Among the most
-interesting, there are:
-
-- ``--two-coins=TC`` This option instructs the tool to perform *TC*
- many payments that use two coins, because normally only one coin is
- spent per payment.
-
-- ``--unaggregated-number=UN`` This option instructs the tool to
- perform *UN* (one coin) payments that will be left unaggregated.
-
-- ``--alt-instance=AI`` This option instructs the tool to perform
- payments using the merchant instance *AI* (instead of the *default*
- instance)
-
-As for the ``ordinary`` subcommand, it is worth explaining the following
-options:
-
-- ``--payments-number=PN`` Instructs the tool to perform *PN* payments.
-
-- ``--tracks-number=TN`` Instructs the tool to perform *TN* tracking
- operations. Note that the **total** amount of operations will be two
- times *TN*, since "one" tracking operation accounts for
- ``/track/transaction`` and ``/track/transfer``. This command should
- only be used to see if the operation ends without problems, as no
- actual measurement of performance is provided (despite of the
- ’benchmark’ work used in the tool’s name).
-
-.. [1]
- https://docs.docker.com/
-
-.. [2]
- Supporting SEPA is still work in progress; the backend will accept
- this configuration, but the exchange will not work with SEPA today.
diff --git a/taler-bank.rst b/taler-bank.rst
deleted file mode 100644
index c85e0aa..0000000
--- a/taler-bank.rst
+++ /dev/null
@@ -1,190 +0,0 @@
-The GNU Taler bank manual
-#########################
-
-Introduction
-============
-
-About GNU Taler
----------------
-
-GNU Taler is an open protocol for an electronic payment system with a
-free software reference implementation. GNU Taler offers secure, fast
-and easy payment processing using well understood cryptographic
-techniques. GNU Taler allows customers to remain anonymous, while
-ensuring that merchants can be held accountable by governments. Hence,
-GNU Taler is compatible with anti-money-laundering (AML) and
-know-your-customer (KYC) regulation, as well as data protection
-regulation (such as GDPR).
-
-About this manual
------------------
-
-This manual documents how the demonstrator bank interoperates with the
-other GNU Taler components. The demonstrator bank implements a simple
-closed banking system for the purpose of illustrating how GNU Taler
-works in the Taler demo. It could also be used as a starting point for a
-local/regional currency. Finally, “real” banks might use it as a
-reference implementation for a tight integration with the GNU Taler
-wallet.
-
-.. _Reference:
-
-Reference
-=========
-
-.. _Bank_002dWallet-interaction:
-
-Bank-Wallet interaction
------------------------
-
-The HTTP status code ``202 Accepted`` can be used by the bank website to
-trigger operations in the user agent. The operation is determined by the
-``X-Taler-Operation`` header. The following operations are understood:
-
-``create-reserve``
- Ask the Taler wallet to create a reserve and call back the bank with
- the reserve public key. The following headers are mandatory:
-
- - ``X-Taler-Callback-Url``: URL that the wallet will visit when the
- reserve was created and the user has selected an exchange.
-
- - ``X-Taler-Wt-Types``: JSON-encoded array of wire transfer types
- that this bank supports.
-
- - ``X-Taler-Amount``: The amount that will be transferred to the
- reserve.
-
- - ``X-Taler-Sender-Wire``: JSON-encoded wire account details of the
- sender, that is the user that is currently logged in with the bank
- and creates the reserve.
-
- The following header is optional:
-
- - ``X-Taler-Suggested-Exchange``: Exchange that the bank recommends
- the customer to use. Note that this is a suggestion and can be
- ignored by the wallet or changed by the user.
-
- On successful reserve creation, the wallet will navigate to the
- callback URL (effectively requesting it with a GET) with the
- following additional request parameters:
-
- - ``exchange``: The URL of the exchange selected by the user
-
- - ``wire_details``: The wire details of the exchange.
-
- - ``reserve_pub``: The reserve public key that the bank should
- transmit to the exchange when transmitting the funds.
-
-``confirm-reserve``
- To secure the operation, the (demo) bank then shows a "CAPTCHA page"
- – a real bank would instead show some PIN entry dialog or similar
- security method – where the customer can finally prove she their
- identity and thereby confirm the withdraw operation to the bank.
-
- Afterwards, the bank needs to confirm to the wallet that the user
- completed the required steps to transfer funds to an exchange to
- establish the reserve identified by the ``X-Taler-Reserve-Pub``
- header.
-
- This does not guarantee that the reserve is already created at the
- exchange (since the actual money transfer might be executed
- asynchronously), but it informs that wallet that it can start polling
- for the reserve.
-
-.. _Bank_002dExchange-interaction:
-
-Bank-Exchange interaction
--------------------------
-
-The interaction between a bank and the exchange happens in two
-situations: when a wallet withdraws coins, and when the exchange pays a
-merchant.
-
-Withdraw
-~~~~~~~~
-
-Once a withdrawal operation with the wallet has been confirmed, the the
-bank must wire transfer the withdrawn amount from the customer account
-to the exchange’s. After this operation is done, the exchange needs to
-be informed so that it will create the reserve.
-
-For the moment, the bank will use the exchange’s ``/admin/add/incoming``
-API, providing those arguments it got along the ``X-Taler-Callback-Url``
-URL. (In the future, the exchange will poll for this information.)
-However, the bank will define two additional values for this API:
-``execution_date`` (a operation’s timestamp), and ``transfer_details``
-(just a "seed" to make unique the operation). See
-https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions.
-
-The polling mechanism is possbile thanks to the ``/history`` API
-provided by the bank. The exchange will periodically use this API to see
-if it has received new wire transfers; upon receiving a new wire
-transfer, the exchange will automatically create a reserve and allow the
-money sender to withdraw.
-
-``GET /history``
- Ask the bank to return a list of money transactions related to a
- caller’s bank account.
-
- - ``auth`` a string indicating the authentication method to use;
- only ``"basic"`` value is accepted so far. The username and
- password credentials have to be sent along the HTTP request
- headers. Namely, the bank will look for the following two headers:
- ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
- will contain those plain text credentials.
-
- - ``delta`` returns the first ``N`` records younger (older) than
- ``start`` if ``+N`` (``-N``) is specified.
-
- - ``start`` according to delta, only those records with row id
- strictly greater (lesser) than start will be returned. This
- argument is optional; if not given, delta youngest records will be
- returned.
-
- - ``direction`` optional argument taking values debit or credit,
- according to the caller willing to receive both incoming and
- outgoing, only outgoing, or only incoming records
-
- - ``account_number`` optional argument indicating the bank account
- number whose history is to be returned. If not given, then the
- history of the calling user will be returned
-
-Exchange pays merchant
-~~~~~~~~~~~~~~~~~~~~~~
-
-To allow the exchange to send payments to a merchant, the bank exposes
-the ``/admin/add/incoming`` API to exchanges.
-
-``POST /admin/add/incoming``
- Ask the bank to transfer money from the caller’s account to the
- receiver’s.
-
- - ``auth`` a string indicating the authentication method to use;
- only ``"basic"`` value is accepted so far. The username and
- password credentials have to be sent along the HTTP request
- headers. Namely, the bank will look for the following two headers:
- ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
- will contain those plain text credentials.
-
- - ``amount`` a JSON object complying to the Taler amounts layout.
- Namely, this object must contain the following fields: ``value``
- (number), ``fraction`` (number), and ``currency`` (string).
-
- - ``exchange_url`` a string indicating the calling exchange base
- URL. The bank will use this value to define wire transfers subject
- lines.
-
- - ``wtid`` a alphanumeric string that uniquely identifies this
- transfer at the exchange database. The bank will use this value
- too to define wire transfers subject lines. Namely, subject lines
- will have the following format: ``'wtid exchange_url'``.
-
- - ``debit_account`` number indicating the exchange bank account.
- NOTE: this field is currently ignored, as the bank can retrieve
- the exchange account number from the login credentials. However,
- in future release, an exchange could have multiple account at the
- same bank, thereby it will have the chance to specify any of them
- in this field.
-
- - ``credit_account`` bank account number that will receive the
- transfer. Tipically the merchant account number.
diff --git a/taler-exchange.rst b/taler-exchange.rst
deleted file mode 100644
index 363a8f9..0000000
--- a/taler-exchange.rst
+++ /dev/null
@@ -1,869 +0,0 @@
-The GNU Taler Exchange Operator Manual
-######################################
-
-Introduction
-============
-
-This manual is an early draft that still needs significant editing work
-to become readable.
-
-About GNU Taler
----------------
-
-GNU Taler is an open protocol for an electronic payment system with a
-free software reference implementation. GNU Taler offers secure, fast
-and easy payment processing using well understood cryptographic
-techniques. GNU Taler allows customers to remain anonymous, while
-ensuring that merchants can be held accountable by governments. Hence,
-GNU Taler is compatible with anti-money-laundering (AML) and
-know-your-customer (KYC) regulation, as well as data protection
-regulation (such as GDPR).
-
-GNU Taler is not yet production-ready, after following this manual you
-will have a backend that can process payments in “KUDOS”, but not
-regular currencies. This is not so much because of limitations in the
-backend, but because we are not aware of a Taler exchange operator
-offering regular currencies today.
-
-About this manual
------------------
-
-This tutorial targets system administrators who want to install and
-operate a GNU Taler exchange.
-
-Organizational prerequisites
-----------------------------
-
-Operating a GNU Taler exchange means that you are operating a payment
-service provider, which means that you will most likely need a bank
-license and/or follow applicable financial regulation.
-
-GNU Taler payment service providers generally need to ensure high
-availability and have *really* good backups (synchronous replication,
-asynchronous remote replication, off-site backup, 24/7 monitoring,
-etc.). [1]_ This manual will not cover these aspects of operating a
-payment service provider.
-
-We will assume that you can operate a (high-availability,
-high-assurance) Postgres database. Furthermore, we expect some moderate
-familiarity with the compilation and installation of free software
-packages. You need to understand the cryptographic concepts of private
-and public keys and must be able to protect private keys stored in files
-on disk. An exchange uses an *offline* master key as well as *online*
-keys. You are advised to secure your private master key and any copies
-on encrypted, always-offline computers. Again, we assume that you are
-familiar with good best practices in operational security, including
-securing key material. [2]_
-
-Architecture overview
----------------------
-
-Taler is a pure payment system, not a new crypto-currency. As such, it
-operates in a traditional banking context. In particular, this means
-that in order to receive funds via Taler, the merchant must have a
-regular bank account, and payments can be executed in ordinary
-currencies such as USD or EUR. Similarly, the Taler exchange must
-interact with a bank. The bank of the exchange holds the exchange’s
-funds in an escrow account.
-
-When customers wire money to the escrow account, the bank notifies the
-exchange about the incoming wire transfers. The exchange then creates a
-*reserve* based on the subject of the wire transfer. The wallet which
-knows the secret key matching the wire transfer subject can then
-withdraw coins from the reserve, thereby draining it. The liability of
-the exchange against the reserve is thereby converted into a liability
-against digital coins issued by the exchange. When the customer later
-spends the coins at a merchant, and the merchant *deposits* the coins at
-the exchange, the exchange first *aggregates* the amount from multiple
-deposits from the same merchant and then instructs its bank to make a
-wire transfer to the merchant, thereby fulfilling its obligation and
-eliminating the liability. The exchange charges *fees* for some or all
-of its operations to cover costs and possibly make a profit.
-
-*Auditors* are third parties, for example financial regulators, that
-verify that the exchange operates correctly. The same software is also
-used to calculate the exchange’s profits, risk and liabilities by the
-accountants of the exchange.
-
-The Taler software stack for an exchange consists of the following
-components:
-
-- HTTP frontend
- The HTTP frontend interacts with Taler wallets and merchant backends.
- It is used to withdraw coins, deposit coins, refresh coins, issue
- refunds, map wire transfers to Taler transactions, inquire about the
- exchange’s bank account details, signing keys and fee structure. The
- binary is the ``taler-exchange-httpd``.
-
-- Aggregator
- The aggregator combines multiple deposits made by the same merchant
- and (eventually) triggers wire transfers for the aggregate amount.
- The merchant can control how quickly wire transfers are made. The
- exchange may be charge a fee per wire transfer to discourage
- excessively frequent transfers. The binary is the
- ``taler-exchange-aggregator``.
-
-- Auditor
- The auditor verifies that the transactions performed by the exchange
- were done properly. It checks the various signatures, totals up the
- amounts and alerts the operator to any inconsistencies. It also
- computes the expected bank balance, revenue and risk exposure of the
- exchange operator. The main binary is the ``taler-auditor``.
-
-- Wire plugin
- A wire plugin enables the HTTP frontend to talk to the bank. Its role
- is to allow the exchange to validate bank addresses (i.e. IBAN
- numbers), for the aggregator to execute wire transfers and for the
- auditor to query bank transaction histories. Wire plugins are
- *plugins* as there can be many different implementations to deal with
- different banking standards. Wire plugins are automatically located
- and used by the exchange, aggregator and auditor.
-
-- DBMS
- Postgres
- The exchange requires a DBMS to stores the transaction history for
- the Taler exchange and aggregator, and a (typically separate) DBMS
- for the Taler auditor. For now, the GNU Taler reference implemenation
- only supports Postgres, but the code could be easily extended to
- support another DBMS.
-
-Installation
-============
-
-Please install the following packages before proceeding with the
-exchange compilation.
-
-- GNU autoconf >= 2.69
-
-- GNU automake >= 1.14
-
-- GNU libtool >= 2.4
-
-- GNU autopoint >= 0.19
-
-- GNU libltdl >= 2.4
-
-- GNU libunistring >= 0.9.3
-
-- libcurl >= 7.26 (or libgnurl >= 7.26)
-
-- GNU libmicrohttpd >= 0.9.59
-
-- GNU libgcrypt >= 1.6
-
-- libjansson >= 2.7
-
-- Postgres >= 9.6, 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://git.gnunet.org/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://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.
-
-Configuration
-=============
-
-This chapter provides an overview of the exchange configuration. Or at
-least eventually will do so, for now it is a somewhat wild description
-of some of the options.
-
-Configuration format
---------------------
-
-configuration
-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/.
-
-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.
-
-.. _Using-taler_002dconfig-exchange:
-
-Using taler-config
-------------------
-
-The tool ``taler-config`` can be used to extract or manipulate
-configuration values; however, the configuration use the well-known INI
-file format and can also be edited by hand.
-
-Run
-
-::
-
- $ taler-config -s $SECTION
-
-to list all of the configuration values in section ``$SECTION``.
-
-Run
-
-::
-
- $ taler-config -s $section -o $option
-
-to extract the respective configuration value for option ``$option`` in
-section ``$section``.
-
-Finally, to change a setting, run
-
-::
-
- $ taler-config -s $section -o $option -V $value
-
-to set the respective configuration value to ``$value``. Note that you
-have to manually restart the Taler backend after you change the
-configuration to make the new configuration go into effect.
-
-Some default options will use $-variables, such as ``$DATADIR`` within
-their value. To expand the ``$DATADIR`` or other $-variables in the
-configuration, pass the ``-f`` option to ``taler-config``. For example,
-compare:
-
-::
-
- $ taler-config -s ACCOUNT-bank \
- -o WIRE_RESPONSE
- $ taler-config -f -s ACCOUNT-bank \
- -o WIRE_RESPONSE
-
-While the configuration file is typically located at
-``$HOME/.config/taler.conf``, an alternative location can be specified
-to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c``
-option.
-
-.. _Keying:
-
-Keying
-------
-
-The exchange works with three types of keys:
-
-- master key
-
-- sign keys
-
-- denomination keys (see section Coins)
-
-- MASTER_PRIV_FILE: Path to the exchange’s master private file.
-
-- MASTER_PUBLIC_KEY: Must specify the exchange’s master public key.
-
-.. _Serving:
-
-Serving
--------
-
-The exchange can serve HTTP over both TCP and UNIX domain socket.
-
-The following values are to be configured in the section [exchange]:
-
-- 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:
-
-Currency
---------
-
-The exchange supports only one currency. This data is set under the
-respective option currency in section [taler].
-
-.. _Bank-account:
-
-Bank account
-------------
-
-To configure a bank account in Taler, we need to furnish four pieces of
-information:
-
-- The ``payto://`` URL of the bank account, which uniquely idenfies the
- account. Examples for such URLs include
- ``payto://sepa/CH9300762011623852957`` for a bank account in the
- single European payment area (SEPA) or
- ``payto://x-taler-bank/localhost:8080/2`` for the 2nd bank account a
- the Taler bank demonstrator running at ``localhost`` on port 8080.
- The first part of the URL following ``payto://`` (“sepa” or
- “x-taler-bank”) is called the wire method.
-
-- A matching wire plugin that implements a protocol to interact with
- the banking system. For example, the EBICS plugin can be used for
- SEPA transfers, or the “taler-bank” plugin can interact with the
- Taler bank demonstrator. A wire plugin only supports one particular
- wire method. Thus, you must make sure to pick a plugin that supports
- the wire method used in the URL.
-
-- A file containing the signed JSON-encoded bank account details for
- the /wire API. This is necessary as Taler supports offline signing
- for bank accounts for additional security.
-
-- Finally, the plugin needs to be provided resources for authentication
- to the respective banking service. The format in which the
- authentication information must be provided depends on the wire
- plugin.
-
-You can configure multiple accounts for an exchange by creating sections
-starting with “account-” for the section name. You can ENABLE for each
-account whether it should be used, and for what (incoming or outgoing
-wire transfers):
-
-::
-
- [account-1]
- URL = "payto://sepa/CH9300762011623852957"
- WIRE_RESPONSE = ${TALER_CONFIG_HOME}/account-1.json
-
- # Currently, only the 'taler_bank' plugin is implemented.
- PLUGIN = <plugin_name_here>
-
- # Use for exchange-aggregator (outgoing transfers)
- ENABLE_DEBIT = YES
- # Use for exchange-wirewatch (and listed in /wire)
- ENABLE_CREDIT = YES
-
- # Authentication options for the chosen plugin go here.
- # (Next sections have examples of authentication mechanisms)
-
-The command line tool taler-exchange-wire is used to create the
-``account-1.json`` file. For example, the utility may be invoked as
-follows to create all of the WIRE_RESPONSE files (in the locations
-specified by the configuration):
-
-::
-
- $ taler-exchange-wire
-
-The generated file will be echoed by the exchange when serving
-/wire [3]_ requests.
-
-.. _Wire-plugin-_0060_0060taler_005fbank_0027_0027:
-
-Wire plugin “taler_bank”
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-x-taler-bank
-taler_bank plugin
-The ``taler_bank`` plugin implements the wire method “x-taler-bank”.
-
-The format of the ``payto://`` URL is
-``payto://x-taler-bank/HOSTNAME[:PORT]``.
-
-For basic authentication, the ``taler_bank`` plugin only supports simple
-password-based authentication. For this, the configuration must contain
-the “USERNAME” and “PASSWORD” of the respective account at the bank.
-
-::
-
- [account-1]
-
- # Bank account details here..
- # ..
-
- # Authentication options for the taler_bank plugin below:
-
- TALER_BANK_AUTH_METHOD = basic
- USERNAME = exchange
- PASSWORD = super-secure
-
-.. _Wire-plugin-_0060_0060ebics_0027_0027:
-
-Wire plugin “ebics”
-~~~~~~~~~~~~~~~~~~~
-
-The “ebics” wire plugin is not fully implemented and today does not
-support actual wire transfers.
-
- **Note**
-
- The rationale behind having multiple 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.
-
-.. _Wire-fee-structure:
-
-Wire fee structure
-~~~~~~~~~~~~~~~~~~
-
-wire fee
-fee
-For each wire method (“sepa” or “x-taler-wire”, but not per plugin!) the
-exchange configuration must specify applicable wire fees. This is done
-in configuration sections of the format ``fees-METHOD``. There are two
-types of fees, simple wire fees and closing fees. Wire fees apply
-whenever the aggregator transfers funds to a merchant. Closing fees
-apply whenever the exchange closes a reserve (sending back funds to the
-customer). The fees must be constant for a full year, which is specified
-as part of the name of the option.
-
-::
-
- [fees-iban]
- WIRE-FEE-2018 = EUR:0.01
- WIRE-FEE-2019 = EUR:0.01
- CLOSING-FEE-2018 = EUR:0.01
- CLOSING-FEE-2019 = EUR:0.01
-
- [fees-x-taler-bank]
- WIRE-FEE-2018 = KUDOS:0.01
- WIRE-FEE-2019 = KUDOS:0.01
- CLOSING-FEE-2018 = KUDOS:0.01
- CLOSING-FEE-2019 = KUDOS:0.01
-
-.. _Database:
-
-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 CONFIG, under section [exchangedb-BACKEND].
- For example, the demo exchange is configured as follows:
-
-::
-
- [exchange]
- ...
- DB = postgres
- ...
-
- [exchangedb-postgres]
- CONFIG = postgres:///talerdemo
-
-.. _Coins-denomination-keys:
-
-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:
-
-Keys duration
--------------
-
-Both signkeys and denom keys have a starting date. The option
-lookahead_provide, under section [exchange], is such that only keys
-whose starting date is younger than lookahead_provide will be issued by
-the exchange.
-
-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.
-
-To change these settings, edit the following values in section
-[exchange]:
-
-- SIGNKEY_DURATION: How long should one signing key be used?
-
-- LOOKAHEAD_SIGN: How much time we want to cover with our signing keys?
- Note that if SIGNKEY_DURATION is bigger than LOOKAHEAD_SIGN,
- ``taler-exchange-keyup`` will generate a quantity of signing keys
- which is sufficient to cover all the gap.
-
-.. _Deployment:
-
-Deployment
-==========
-
-.. _Keys-generation:
-
-Keys generation
----------------
-
-Once the configuration is properly set up, all the keys can be generated
-by the tool ``taler-exchange-keyup``. The following command generates
-denomkeys and signkeys, plus the "blob" that is to be signed by the
-auditor.
-
-::
-
- taler-exchange-keyup -o blob
-
-*blob* contains data about denomkeys that the exchange operator needs to
-get signed by every auditor he wishes (or is forced to) work with.
-
-In a normal scenario, an auditor must have some way of receiving the
-blob to sign (Website, manual delivery, ..). Nonetheless, the exchange
-admin can fake an auditor signature — for testing purposes — by running
-the following command
-
-::
-
- taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o
OUTPUT_FILE
-
-Those arguments are all mandatory.
-
-- ``EXCHANGE_MASTER_PUB`` the base32 Crockford-encoded exchange’s
- master public key. Tipically, this value lies in the configuration
- option ``[exchange]/master_public_key``.
-
-- ``BLOB`` the blob generated in the previous step.
-
-- ``AUDITOR_URL`` the URL that identifies the auditor.
-
-- ``OUTPUT_FILE`` where on the disk the signed blob is to be saved.
-
-``OUTPUT_FILE`` must then be copied into the directory specified by the
-option ``AUDITOR_BASE_DIR`` under the section ``[exchangedb]``. Assuming
-``AUDITOR_BASE_DIR = ${HOME}/.local/share/taler/auditors``, the
-following command will "add" the auditor identified by ``AUDITOR_URL``
-to the exchange.
-
-::
-
- cp OUTPUT_FILE ${HOME}/.local/share/taler/auditors
-
-If the auditor has been correctly added, the exchange’s ``/keys``
-response must contain an entry in the ``auditors`` array mentioning the
-auditor’s URL.
-
-.. _Database-upgrades:
-
-Database upgrades
------------------
-
-Currently, there is no way to upgrade the database between Taler
-versions.
-
-The exchange database can be re-initialized using:
-
-::
-
- $ taler-exchange-dbinit -r
-
-However, running this command will result in all data in the database
-being lost, which may result in significant financial liabilities as the
-exchange can then not detect double-spending. Hence this operation must
-not be performed in a production system.
-
-.. _Diagnostics:
-
-Diagnostics
-===========
-
-This chapter includes various (very unpolished) sections on specific
-topics that might be helpful to understand how the exchange operates,
-which files should be backed up. The information may also be helpful for
-diagnostics.
-
-.. _Reserve-management:
-
-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.
-
-.. _Database-Scheme:
-
-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:
-
-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:
-
-::
-
- struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP {
- struct TALER_ExchangePrivateKeyP signkey_priv;
- struct TALER_ExchangeSigningKeyValidityPS issue;
- };
-
-.. _Denomination-key-storage:
-
-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:
-
-::
-
- 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().
-
-.. _Revocations:
-
-Revocations
-~~~~~~~~~~~
-
-When an exchange goes out of business or detects that the private key of
-a denomination key pair has been compromised, it may revoke some or all
-of its denomination keys. At this point, the hashes of the revoked keys
-must be returned as part of the ``/keys`` response under “payback”.
-Wallets detect this, and then return unspent coins of the respective
-denomination key using the ``/payback`` API.
-
-When a denomination key is revoked, a revocation file is placed into the
-respective subdirectory of “denomkeys/”. The file has the same prefix as
-the file that stores the struct
-TALER_EXCHANGEDB_DenominationKeyInformationP information, but is
-followed by the “.rev” suffix. It contains a 64-byte EdDSA signature
-made with the master key of the exchange with purpose
-``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``. If such a file is
-present, the exchange must check the signature and if it is valid treat
-the respective denomination key as revoked.
-
-Revocation files can be generated using the ``taler-exchange-keyup``
-command-line tool using the ``-r`` option. The Taler auditor will
-instruct operators to generate revocations if it detects a key
-compromise (which is possible more coins of a particular denomination
-were deposited than issued).
-
-It should be noted that denomination key revocations should only happen
-under highly unusual (“emergency”) conditions and not under normal
-conditions.
-
-.. _Auditor-signature-storage:
-
-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:
-
-::
-
- 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.
-
-
-.. [1]
- Naturally, you could operate a Taler exchange for a toy currency
- without any real value on low-cost setups like a Raspberry Pi, but we
- urge you to limit the use of such setups to research and education as
- with GNU Taler data loss instantly results in financial losses.
-
-.. [2]
- The current implementation does not make provisions for secret
- splitting. Still, the use of a hardware security module (HSM) for
- protecting private keys is adviseable, so please contact the
- developers for HSM integration support.
-
-.. [3]
- https://api.taler.net/api-exchange.html#wire-req
-
--
To stop receiving notification emails like this one, please contact
address@hidden.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] [taler-docs] branch master updated: texinfo support,
gnunet <=