summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2014-11-20 09:23:59 +0100
committerChristian Grothoff <christian@grothoff.org>2014-11-20 09:23:59 +0100
commit3d108294a1f4a5e1a842f30921e56054a69fecce (patch)
tree2abfd6284078bd2bd91ea86bd146c6bee8007c12
downloaddocs-3d108294a1f4a5e1a842f30921e56054a69fecce.tar.gz
docs-3d108294a1f4a5e1a842f30921e56054a69fecce.tar.bz2
docs-3d108294a1f4a5e1a842f30921e56054a69fecce.zip
initial import of sphinx documentation
-rw-r--r--Makefile177
-rw-r--r--api-merchant.rst113
-rw-r--r--api-mint.rst640
-rw-r--r--conf.py265
-rw-r--r--impl-mint.rst242
-rw-r--r--index.rst54
-rw-r--r--wireformats.rst43
7 files changed, 1534 insertions, 0 deletions
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..8061450
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/neuro.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/neuro.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/neuro"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/neuro"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/api-merchant.rst b/api-merchant.rst
new file mode 100644
index 0000000..339498d
--- /dev/null
+++ b/api-merchant.rst
@@ -0,0 +1,113 @@
+The Merchant JSON API
+=====================
+
+The Merchant API serves the protocol interactions between a customer and a
+merchant. The protocol allows the customer and the merchant to agree upon a
+contract and for the customer to spend coins according to the contract at the
+merchant. It should be noted that the interactions are strictly one way: The
+customer *always* initiates the requests by contacting the merchant. It is also
+assumed that the customer knows the merchant's public key.
+
+The protocol allows for three different type of interactions. In the first type
+of interaction, which we refer to as *direct deposit*, an interested customer
+asks the merchant to provide a ``contract`` for the merchant's services or
+products. Details about the services or products and the merchant's payment
+information are provided in the contract. The customer then agrees upon one of
+these contracts by giving the the merchant a ``deposit permission``. The
+merchant then submits this deposit permission at the mint for verification.
+Upon successful verification, the merchant delivers the promised services or
+products.
+
+The second type of interaction, *incremental deposit*, allows the merchant to
+charge the customer incrementally. This is useful for subscription based
+e-commerce systems. Examples for such systems are app stores and news websites.
+The idea here is that the merchant will be assured that he will receive a
+certain amount of money from the transaction, and then he can charge small
+amounts over the assured amount without contacting the mint. In these
+interactions, the customer asks merchant to make an ``offer`` for the
+subscription by specifying the maximum amount the merchant may charge during the
+interaction. The customer conveys his acceptance of the offer by sending a
+``lock permission`` to the merchant. The merchant asks the mint to verify the
+lock permission and if verified successfully, the customer then obtains a
+contract from the merchant and the first type interaction follows. The customer
+can then obtain further contracts until the maximum amount made in the offer is
+reached.
+
+The thrid type of interactions allows probablistic spending. `To be done.`
+
+The following are the API made available by the merchant:
+
+.. http:GET:: /contract
+.. http:POST:: /contract
+
+ Ask the merchant to prepare a contract. The request parameters are specific
+ to the merchant's implementation, however, they are recommended to contain
+ information required for the merchant to identify which product or service
+ the customer is interested int.
+
+ **Success Response**
+
+ :status 200 OK: The request was successful.
+
+ The merchant responds with a JSON object containing the following fields:
+
+ * `transaction_id`: A string representing the transaction identifier.
+ * `expiry`: The timestamp after which this contract expires.
+ * `amount`: Price of the contract as a Denomination object.
+ * `description`: The contract description as string.
+ * `H_wire`: The hash of a JSON object containing the merchant's payment
+ information. See :ref:`wireformats`.
+ * `msig`: Signature of the merchant over the fields `m`, `t`, `f`, `a`, `H_wire`.
+
+ **Failure response**
+
+ :status 400: Request not understood.
+ :status 404: No products or services given in the request were found.
+
+ It is also possible to receive other error status codes depending on the
+ merchant's implementation.
+
+.. http:GET:: /deposit
+
+ Send a ``deposit-permission`` JSON object to the merchant. The object should
+ contain the following fields:
+
+ * `coin_pub`: The coin's public key.
+ * `mint_pub`: The public key of the mint from where the coin is obtained.
+ * `denom_pub`: Denomination key with which the coin is signed
+ * `ubsig`: Mint's unblinded signature of the coin
+ * `type`: the string constant `"DIRECT_DEPOSIT"` or `"INCREMENTAL_DEPOSIT"`
+ respectively for direct deposit or incremental deposit type of interaction.
+ * `transaction_id`: The transaction identifier obtained from the contract.
+ * `amount`: The amount to be deposited as a Denomination object. Its value should
+ be less than or equal to the coin's face value. Additionally, for direct
+ deposit type of interactions, this should be equal to the amount stated in
+ the contract.
+ * `merchant_pub`: The public key of the merchant.
+ * `H_a`: The hash of the contract.
+ * `H_wire`: The hash of the merchant's payment information.
+ * `csig`: The signature with the coin's private key over the parameters
+ `type`, `m`, `f`, `M`, `H_a` and, `H_wire`.
+
+ **Success Response**
+
+ :status 200 OK: The deposit permission is successful.
+
+ It is left upto the merchant's implementation to carry over the process of
+ fulfilling the agreed contract `a` from here. For example, for services or
+ products which can be served through HTTP, this response could contain them.
+
+ **Failure Response**
+
+ :status 400: Request not understood.
+ :status 404: The merchant does not entertain this type of interaction. Try
+ another one.
+ :status 403: The request doesn't comply to the contract provided. The
+ request should not be repeated.
+ :status 403: The deposit operation has failed because the coin has previously
+ been deposited or it has been already refreshed; the request
+ should not be repeated again. The response body contains the
+ failure response objects from the :ref:`Mint API deposit
+ request<deposit>`.
+
+Other interactions tbd..
diff --git a/api-mint.rst b/api-mint.rst
new file mode 100644
index 0000000..18e2bff
--- /dev/null
+++ b/api-mint.rst
@@ -0,0 +1,640 @@
+========================
+The Mint JSON API
+========================
+
+-------
+General
+-------
+
+ This section describes how certain types of values are
+ represented throughout the API.
+
+ * **Timestamps**:
+ Timestamps are represented in JSON as a string literal `"\\/Date(x)\\/"`, where `x` is the decimal representation
+ of the number of milliseconds past the Unix Epoch (January 1, 1970). The escaped slash (`\\/`) is interpreted in JSON simply
+ as a normal slash, but distinguishes the timestamp from a normal string literal.
+ * **Public key**: Public keys are represented using the Ed25519 standard
+ compact format (256 bits), converted to Base32Hex (RFC 4648) for
+ transmission.
+ * **Signatures**: Signatures are transmitted as a JSON object with the following fields:
+
+ * `purpose`: a unique number to state the context in which the signature is to be used in
+ * `size`: the number of bytes that were hashed (using SHA-512) to create the signature; note that signatures are always done over a packed, binary representation of the data and not the JSON representations.
+ * `r`: R value of the signature (256 bit, in Base32Hex).
+ * `s`: S value of the signature (256 bit, in Base32Hex).
+
+ The specific signature scheme in use (blind signature, EdDSA)
+ depends on the context and can be derived from the purpose.
+
+ * **Denominations**: Currency denominations are expressed as a JSON object with the following fields:
+
+ * `currency`: name of the currency using ISO 4217 currency code
+ * `value`: unsigned 32 bit value in the currency, note that "1" here would correspond to 1 EUR or 1 USD (depending on `currency`), not 1 cent.
+ * `fraction`: unsigned 32 bit fractional value (to be added to `value`) representing an additional currency fraction, in units of 1 in one million (1/1000000) of the base currency value. For example, a fraction of 50000000 (50 million) would correspond to 50 cents.
+
+ * **Large numbers**: Large numbers (typically 256 bits), such as blinding factors and private keys, are transmitted in Base32Hex encoding.
+
+-------------------
+Obtaining Mint Keys
+-------------------
+.. http:get:: /keys
+
+ Get a list of all denomination keys offered by the bank,
+ as well as the bank's current online signing key.
+
+ **Response on Success**
+
+ On success, the mint responds with HTTP status code `200 OK`.
+ The body of the response contains a JSON object with the following fields:
+
+ * `denoms`: A JSON list of denomination descriptions. Described below in detail.
+ * `denoms_date`: The date when the denomination keys were last updated.
+ * `denoms_sig`: A signature over the list of denomination keys and the date.
+ * `signing_key`: The mint's current signing key. Described below in detail.
+
+ A denomination description is a JSON object with the following fields:
+
+ * `value`: Value of the denomination. An integer, to be interpreted
+ relative to the currency provided by the mint.
+ * `stamp_start`: timestamp indicating when the denomination key becomes valid.
+ * `stamp_expire_withdraw`: timestamp indicating when the denomination key can't
+ be used anymore to withdraw new coins.
+ * `stamp_expire_deposit`: timestamp indicating when coins of this
+ denomination become invalid.
+ * `key`: Public key for the denomination.
+ * `kappa`: Security parameter for refreshing.
+ * `sig`: Signature over the expiration dates, value and the key, created
+ with the mint's master key.
+
+ The `signing_key` field contains a JSON object with the following fields:
+
+ * `key`: The actual mint's signing public key.
+ * `stamp_expire`: Expiration date for the signing key.
+ * `sig`: Signature over the `key` and `stamp_expire` by the mint master key.
+
+ .. note::
+
+ Both the individual denominations *and* the denomination list is signed,
+ allowing customers to prove that they received an inconsistent list.
+
+
+------------------
+Withdrawal
+------------------
+
+When transfering money to the mint via SEPA, the mint records
+a *purse*, which stores the remaining money from the transaction and the
+customer's withdrawal key for the purse.
+
+
+.. http:get:: /withdraw/status
+
+ Request information about a purse, including the blinding key that is necessary to
+ withdraw a coin.
+
+ :query withdraw_pub: Withdrawal key identifying the purse.
+
+ **Success Response**
+
+ The mint responds with a JSON object containing the following fields:
+
+ * `balance`: Money left in this purse. A list of denominations (in case multiple currencies happen to be in the same purse).
+ * `blind_session_pub`: Blinding key to be used for withdrawing from this purse.
+ The field may be absent if the balance is smaller than the smallest denomination offered by the mint.
+ * `expiration`: Expiration date of the purse.
+ * `sig`: Signature of the mint.
+
+ For the same `balance`, the blinding key `blinding_pub` must be the same. Otherwise the mint is faulty.
+
+ **Error Responses**
+
+ :status 402 Payment Required: The balance of the purse is not sufficient
+ to withdraw any coin denomination offered by the mint.
+
+ :status 400 Bad Request: The `withdraw_pub` parameter is missing or malformed.
+
+ :status 404 Not Found: The withdrawal key does not belong to a purse known to the mint.
+
+
+.. http:get:: /withdraw/sign
+
+ Withdraw a coin with a given denomination key.
+
+ :query denom: denomination key
+ :query blank: blinded coin blank
+ :blind_session_pub: blind session public key
+ :withdraw_pub: withdraw / purse public key
+ :query sig: signature, created with the withdrawal key
+
+ **Success Response**:
+
+ :status 200 OK: The request was succesful.
+
+ The response body of a succesful request contains a JSON object with the following fields:
+
+ * `bcsig`: The blindly signed coin.
+
+ **Error Responses**:
+
+ :status 400 Bad Request: A request parameter is missing or malformed.
+
+ :status 402 Payment Required: The balance of the purse is not sufficient to withdraw a coin of the
+ indicated denomination.
+
+ :status 401 Unauthorized: The signature is invalid.
+
+ :status 404 Not Found: The blinding key is not known to the mint.
+
+ :status 409 Conflict: A sign request for the same `big_r` has already been sent,
+ but with a different `denom` or `blank`.
+
+
+------------------
+Refreshing
+------------------
+
+Refreshing creates `n` new coins from `m` old coins, where the sum
+of denominations of the new coins must be smaller than the sum of
+the old coins' denominations plus a refreshing fee imposed by the mint.
+
+The new coins are linkable from all old coins.
+
+In order group multipe coins, the customer generates a refreshing session key.
+
+.. http:post:: /refresh/melt
+
+ "Melt" coins, marking it for refreshing. Invalidates the coins.
+
+ The request body must contain a JSON object with the following fields:
+ * `melt_coins`: List of coins to refresh.
+ * `new_denoms`: List of new denominations to order.
+ * `session_pub`: Session public key
+
+ The `melt_coins` field is a list of JSON objects with the following fields:
+ * `coin_pub`: Coin public key
+ * `coin_sig`: Signature by the coin over the session public key
+ * `denom_pub`: Denomination public key
+ * `denom_sig`: Signature over the coin public key by the denomination key
+
+
+ **Success Response**:
+
+ :status 200 OK: The request was succesful. In that case, the responst body is a json
+ object with `kappa` blind session keys for each new coin.
+
+ **Error Responses**:
+
+ :status 400 Bad Request: A request parameter is missing or malformed.
+
+ :status 401 Gone: The coin `coin` has already been refreshed.
+
+ :status 403 Forbidden: Either `csig` or `ssig` is invalid.
+
+.. http:post:: /refresh/commit
+
+ Commit values for the cut-and-choose in the refreshing protocol.
+ The request body must be a JSON object with the following fields:
+ * `session_pub`: Session to commit values for
+ * `session_sig`: Signature over the whole commitment
+ * `coin_evs`: For each new coin, `kappa` coin blanks.
+ * `transfer_pubs`: List of transfer public keys
+ * `new_encs`: For each new coin, a list of encryptions (one for each cnc instance)
+ * `secret_encs`: For each cut-and-choose instance, the linking encryption for each old coin
+
+ **Success Response**:
+
+ :status 202 Accepted: The mint accepted the commitment, but still needs more commitments.
+
+ The response body contains a JSON object with the following fields:
+
+ **Error Response**:
+
+ :status 400 Bad Request: A request parameter is missing or malformed.
+
+ :status 403 Forbidden: The signature `sig` is invalid.
+
+ :status 404 Not Found: The mint does not know the blind key `blindkey` given
+ in the request.
+
+.. http:post:: /refresh/reveal
+
+ Reveal previously commited values to the bank. Request body contains a JSON object with
+ the following fields:
+ * `session_pub`: The session public key
+ * `transfer_privs`: Revealed transfer private keys
+
+ **Success Response**:
+
+ :status 200 OK: All commitments were revealed successfully.
+
+ The mint responds with a JSON object containing the following
+ fields:
+
+ * `bcsig_list`: List of the mint's blind signatures on the ordered new coins.
+
+ :status 202 Accepted: The revealed value was accepted, but the mint
+ requires more reveals.
+
+ **Error Responses**:
+
+ If the reveal is incomplete, the JSON object contains:
+
+ * `reveal_missing`: List of blinding keys with missing reveals from the customer.
+
+ :status 400 Bad Request: Request parameters incomplete or malformed.
+ :status 403 Forbidden: The signature `ssig` is invalid.
+ :status 404 Not Found: The blinding key is not known to the mint.
+ :status 409 Conflict: The revealed value was inconsistent with the commitment.
+ :status 410 Gone: A conflict occured, the money is gone.
+
+.. http:get:: /refresh/link
+
+ Link an old key to the refreshed coin.
+
+ :query coin: coin public key
+ :query csig: signature by the coin
+
+ **Success Response**:
+
+ :status 200 OK: All commitments were revealed successfully.
+
+ The mint responds with a JSON object containing the following fields:
+ * `link_secret_enc`: ...
+ * `enc_list`: List of encrypted values for the result coins.
+ * `tpk_list`: List of transfer public keys for the new coins.
+ * `bscoin_list`: List of blind signatures on the new coins.
+
+ **Error Responses**:
+
+ :status 400 Bad Request: Request parameters incomplete or malformed.
+ :status 403 Forbidden: The signature `csig` is invalid.
+ :status 404 Not Found: The coin public key is not known to the bank, or was not involved
+ in a refresh.
+
+
+
+--------------------
+Locking and Deposit
+--------------------
+
+Locking and Deposit operations are requested by a merchant during a transaction.
+For locking operation, the merchant has to obtain a lock permission for a coin
+from the customer. Similarly, for deposit operation the merchant has to obtain
+deposit permission for the coin from the customer.
+
+.. http:GET:: /lock
+
+ Lock the given coin which is identified by the coin's public key.
+
+ :query C: coin's public key
+ :query K: denomination key with which the coin is signed
+ :query ubsig: mint's unblinded signature of the coin
+ :query t: timestamp indicating the lock expire time
+ :query m: transaction id for the transaction between merchant and customer
+ :query f: the maximum amount for which the coin has to be locked
+ :query M: the public key of the merchant
+ :query csig: the signature made by the customer with the coin's private key over
+ the parameters `t`, `m`, `f`, `M` and the string `"LOCK"`
+
+ The locking operation may succeed if the coin is not already locked or a
+ previous lock for the coin has already expired.
+
+ **Success response**
+
+ :status 200: the operation succeeded
+
+ The mint responds with a JSON object containing the following fields:
+
+ * `status`: The string constant `LOCK_OK`
+ * `C`: the coin's public key
+ * `t`: timestamp indicating the lock expire time
+ * `m`: transaction id for the transaction between merchant and customer
+ * `f`: the maximum amount for which the coin has to be locked
+ * `M`: the public key of the merchant
+ * `sig`: the signature made by the mint with the corresponding coin's
+ denomination key over the parameters `status`, `C`, `t`, `m`, `f`,
+ `M`
+
+ The merchant can then save this JSON object as a proof that the mint has
+ agreed to transfer a maximum amount equalling to the locked amount upon a
+ successful deposit request (see /deposit).
+
+ **Failure response**
+
+ :status 403: the locking operation has failed because the coin is already
+ locked or already refreshed and the same request should not be
+ repeated as it will always fail.
+
+ In this case the response contains a proof that the given coin is already
+ locked ordeposited.
+
+ If the coin is already locked, then the response contains the existing lock
+ object rendered as a JSON object with the following fields:
+
+ * `status`: the string constant `LOCKED`
+ * `C`: the coin's public key
+ * `t`: the expiration time of the existing lock
+ * `m`: the transaction ID which locked the coin
+ * `f`: the amount locked for the coin
+ * `M`: the public key of the merchant who locked the coin
+ * `csig`: the signature made by the customer with the coin's private key
+ over the parameters `t`, `m`, `f` and `M`
+
+ If the coin has already been refreshed then the mint responds with a JSON
+ object with the following fields:
+
+ * `status`: the string constant `REFRESHED`
+ * ... TBD
+
+ :status 404: the coin is not minted by this mint, or it has been expired
+ :status 501: the request or one of the query parameters are not valid and the
+ response body will contain an error string explaining why they are
+ invalid
+ :status 503: the mint is currently unavailable; the request can be retried after
+ the delay indicated in the Retry-After response header
+
+ In these failures, the response contains an error string describing the reason
+ why the request has failed.
+
+.. _deposit:
+.. http:POST:: /deposit
+
+ Deposit the given coin and ask the mint to transfer the given amount to the
+ merchants bank account. The request should contain a JSON object with the
+ following fields
+
+ * `C`: coin's public key
+ * `K`: denomination key with which the coin is signed
+ * `ubsig`: mint's unblinded signature of the coin
+ * `type`: the string constant `"DIRECT_DEPOSIT"` or `"INCREMENTAL_DEPOSIT"`
+ respectively for direct deposit or incremental deposit type of interaction
+ chosen by the customer and the merchant.
+ * `m`: transaction id for the transaction between merchant and customer
+ * `f`: the maximum amount for which the coin has to be locked
+ * `M`: the public key of the merchant
+ * `H_a`: the hash of the contract made between merchant and customer
+ * `H_wire`: the hash of the merchant's payment information `wire`
+ * `csig`: the signature made by the customer with the coin's private key over
+ the parameters `type`, `m`, `f`, `M`, `H_a` and, `H_wire`
+ * `wire`: this should be a JSON object whose format should comply to one of the
+ supported wire transfer formats. See :ref:`wireformats`
+
+ The deposit operation succeeds if the coin is valid for making a deposit and
+ is not already deposited or refreshed.
+
+ **Success response**
+
+ :status 200: the operation succeeded
+
+ The mint responds with a JSON object containing the following fields:
+
+ * `status`: the string constant `DEPOSIT_OK`
+ * `t`: the current timestamp
+ * `deposit_tx`: the transaction identifier of the transfer transaction made by the
+ mint to deposit money into the merchant's account
+ * `sig`: signature of the mint made over the parameters `status`, `t` and
+ `deposit_tx`
+
+ :status 202: the operation is accepted but will take a while to complete;
+ check back later for its reponse
+
+ This happens when the mint cannot immediately execute the SEPA transaction.
+ The response contains the following fields as part of a JSON object:
+
+ * `status`: the string contant `DEPOSIT_QUEUED`
+ * `t`: the current timestamp
+ * `retry`: timestamp indicating when the result of the request will be made
+ available
+ * `sig`: the signature of the mint made over the parameters `status`, `t`, and
+ `retry`
+
+ **Failure response**
+
+ :status 403: the deposit operation has failed because the coin has previously
+ been deposited or it has been already refreshed; the request
+ should not be repeated again
+
+ In case of failure due to the coin being already deposity, the response
+ contains a JSON object with the following fields:
+
+ * `status`: the string constant `DEPOSITED`
+ * `C`: the coin's public key
+ * `m`: ID of the past transaction which corresponding to this deposit
+ * `f`: the amount that has been deposited from this coin
+ * `M`: the public key of the merchant to whom the deposit was earlier made
+ * `H`: the hash of the contract made between the merchant identified by `M`
+ and the customer
+ * `csig`: the signature made by the owner of the coin with the coin's private
+ key over the parameters `m`, `f`, `M`, `H` and the string `"DEPOSIT"`
+ * `t`: the timestamp when the deposit was made
+ * `deposit_tx`: the transaction identifier of the SEPA transaction made by the
+ mint to deposit money into the merchant's account
+
+ In case if the coin has been already refreshed, the response contains a JSON
+ object with the following fields:
+
+ * `status`: the string constant `REFRESHED`
+ * ... TBD
+
+ :status 404: the coin is not minted by this mint, or it has been expired
+ :status 501: the request or one of the query parameters are not valid and the
+ response body will contain an error string explaining why they are
+ invalid
+ :status 503: the mint is currently unavailable; the request can be retried after
+ the delay indicated in the Retry-After response header
+
+ In these failures the response contains an error string describing the reason
+ why the request has failed.
+
+===========================
+Binary Blob Specification
+===========================
+This section specifies the binary representation of messages used in Neuro's protocols.
+The message formats are given in a C-style pseudocode notation. In contrast to real C structs,
+padding is always specified explicitly, and numeric values are little endian.
+
+.. sourcecode:: c
+
+ struct PublicKey {
+ uint8_t v[32];
+ };
+
+ struct PrivateKey {
+ uint8_t d[32];
+ };
+
+ struct Timestamp {
+ uint64_t val_us;
+ };
+
+ struct Signature {
+ uint8_t rs[64];
+ };
+
+In our notation, the type of a field can depend on the value of another field.
+For the following message, the length of the `payload` array must match the value
+of the `size` field.
+
+.. sourcecode:: c
+
+ struct SignedData {
+ uint32_t size;
+ uint32_t purpose;
+ uint8_t payload[size];
+ };
+
+ struct Denomination {
+ uint32_t value;
+ uint32_t fraction;
+ uint8_t currency_code[4];
+ };
+
+
+In the subsequent messages, we use the following notation
+
+.. sourcecode:: c
+
+ signed (purpose = SOME_CONSTANT) {
+ FIELDS
+ } msg;
+
+for signed data (contained in `FIELDS`) with the given purpose. The `size` field of the
+corresponding `struct SignedData` is determined by the size of `FIELDS`.
+
+.. sourcecode:: c
+
+ struct CoinIssue {
+ // signed by the master key
+ signed (purpose = COIN_ISSUE) {
+ struct PublicKey key;
+ struct Timestamp stamp_expire_withdraw;
+ struct Timestamp stamp_expire_deposit;
+ struct Timestamp stamp_start;
+ uint32_t kappa;
+ uint32_t padding;
+ struct Denomination denom;
+ };
+ };
+
+ struct CoinIssueList {
+ // signed by the master key
+ signed (purpose = COIN_ISSUE_LIST) {
+ uint32_t n;
+ struct Timestamp stamp_issue;
+ struct CoinIssue coins[n];
+ struct PublicKey mint_signing_key;
+ };
+ };
+
+ struct PurseInformation {
+ // signed with the mint signing key
+ signed (purpose = PURSE_INFO) {
+ struct PublicKey big_r;
+ struct Timestamp stamp_expire_purse;
+ struct Denomination balance;
+ struct Timestamp purse_expiration;
+ };
+ };
+
+ struct BlindBlankCoin {
+ TODO todo;
+ };
+
+ struct BlindSignedCoin {
+ TODO todo;
+ };
+
+ struct SignedCoin {
+ TODO todo;
+ };
+
+ struct WithdrawRequest {
+ // signed with the withdrawal key
+ signed (purpose = WITHDRAW_REQUEST) {
+ struct PublicKey denom_key;
+ struct PublicKey big_r;
+ struct BlindBlankCoin blank;
+ };
+ };
+
+ struct MeltRequest {
+ // signed with the coin key
+ signed (purpose = MELT_COIN) {
+ // signed with the session key
+ signed (purpose = MELT_SESSION) {
+ SignedCoin coin;
+ PublicKey session;
+ };
+ };
+ };
+
+ struct OrderRequest {
+ // signed with the session key
+ signed (purpose = REFRESH_REQUEST) {
+ struct PublicKey denom_key;
+ struct PublicKey session;
+ };
+ };
+
+
+In the following message, `n` is the number of coins
+melted by the customer, and `KAPPA` is a security parameter determined
+by the new coin's denomination.
+
+.. sourcecode:: c
+
+ struct OrderResponse {
+ signed (purpose = ORDER_RESPONSE) {
+ Denomination rest_balance;
+ struct {
+ PublicKey big_r;
+ PublicKey old_coin;
+ } challenges[KAPPA * n];
+ };
+ };
+
+ struct BlindFactor {
+ TODO todo;
+ };
+
+The `encrypted` block denotes an encrypted message.
+
+.. sourcecode:: c
+
+ struct RefreshEnc {
+ encrypted {
+ struct BlindFactor bf;
+ struct PrivateKey tsk;
+ struct PrivateKey csk;
+ };
+ };
+
+ struct CommitRequest {
+ signed (purpose = REFRESH_COMMIT) {
+ struct PublicKey tpk;
+ struct BlindBlankCoin blank;
+ struct RefreshEnc enc;
+ };
+ };
+
+ struct RevealRequest {
+ // FIXME: does this need to be signed?
+ struct PublicKey big_r;
+ struct BlindFactor bf;
+ struct PrivateKey csk;
+ };
+
+ struct LinkRequest {
+ signed (purpose = REFRESH_LINK) {
+ struct PublicKey coin;
+ };
+ };
+
+ struct LinkResponse {
+ uint16_t n;
+ struct BlindSignedCoin coins[n];
+ struct PublicKey tpks[n];
+ struct RefreshEnc encs[n];
+ };
+
+
diff --git a/conf.py b/conf.py
new file mode 100644
index 0000000..ae2d3ac
--- /dev/null
+++ b/conf.py
@@ -0,0 +1,265 @@
+# -*- coding: utf-8 -*-
+#
+# neuro documentation build configuration file, created by
+# sphinx-quickstart on Sat May 31 13:11:06 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'sphinx.ext.todo',
+ 'sphinx.ext.pngmath',
+ 'sphinxcontrib.httpdomain'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'neuro'
+copyright = u'2014, Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff (GPLv3+ or GFDL 1.3+)'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'neurodoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'taler.tex', u'Taler Documentation',
+ u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff',
+ 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'neuro', u'neuro Documentation',
+ [u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff'],
+ 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'neuro', u'neuro Documentation',
+ u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff',
+ 'neuro', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/impl-mint.rst b/impl-mint.rst
new file mode 100644
index 0000000..969a730
--- /dev/null
+++ b/impl-mint.rst
@@ -0,0 +1,242 @@
+===================================
+The Mint Reference Implementation
+===================================
+
+
+
+--------------------
+Key update
+--------------------
+New denomination and signing keys can be uploaded to the mint
+via the HTTP interface. It is, of course, only possible to upload keys signed
+by the mint's master key.
+
+As an additional constraint, it is only possible to upload new keys while the
+mint still has one valid signing key (otherwise, MitM-attacks would be possible).
+
+Alternative: Transfer key is signed by the master key.
+
+.. http:GET:: /admin/keyup/public
+
+ Transmit the public part of the new key in plain-text.
+
+ :query denom_info: Public part of the denomination issue
+ :query transfer_pub: Public key used by the party doing the key transfer
+
+.. http:GET:: /admin/keyup/private
+
+ Transmit the private part of the new text, encrypted with the shared secret derived from the
+ ephemeral public key and the sender's private key.
+
+
+-------------------
+Database Scheme
+-------------------
+
+.. sourcecode:: postgres
+
+ CREATE TABLE purses (
+ -- The customer's withdraw public key for the purse.
+ withdraw_pub BYTEA PRIMARY KEY,
+
+ -- Purse balance (value part).
+ balance_value INT4 NOT NULL,
+
+ -- Purse balance (fractional part).
+ balance_fraction INT4 NOT NULL,
+
+ -- Purse balance (fractional).
+ balance_currency VARCHAR(4),
+
+ -- Expiration time stamp for the purse.
+ expiration INT8,
+
+ -- The blinding key (public part) for the purse, can be NULL
+ -- if funds are insufficient or the mint has not
+ -- generated it yet.
+ blinding_pub BYTEA,
+
+ -- The blinding key (private part).
+ blinding_priv BYTEA,
+
+ -- Key that was used to create the last signature on the
+ -- purse status
+ status_sign_pub BYTEA,
+
+ -- Cached status signature
+ status_sig BYTEA
+ );
+
+
+.. sourcecode:: postgres
+
+ CREATE TABLE collectable_blindcoins (
+ -- The public part of the blinding key.
+ -- Note that this is not a foreign key,
+ -- as the blinding key is removed from the purse
+ -- table once a coin has been requested with it.
+ -- Furthermore, the private part is not required
+ -- anymore.
+ blind_pub bytea PRIMARY KEY,
+
+ -- The coin blank provided by the customer.
+ blind_blank_coin BYTEA,
+
+ -- Signature over the minting request by the customer.
+ customer_sig BYTEA,
+
+ -- The signed blind blank coin.
+ blind_signed_coin BYTEA,
+
+ -- The denomination public key used to sign the
+ -- blind signed coin.
+ denom_pub BYTEA,
+
+ -- The purse that requested the minting of this
+ -- coin.
+ withdraw_pub BYTEA REFERENCES purses(withdraw_pub)
+ );
+
+
+The table `coins` stores information about coins known to the mint.
+
+.. sourcecode:: postgres
+
+ CREATE TABLE coins (
+ denom_pub BYTEA NOT NULL,
+ denom_sig BYTEA NOT NULL,
+ coin_pub BYTEA NOT NULL,
+
+ -- melting session, or NULL if not melted
+ melt_session BYTEA,
+
+ -- remaining value of the coin
+ balance_currency int4,
+ balance_value int4,
+ balance_fraction int4,
+
+ -- lock id, not NULL if not locked
+ lock int
+ );
+
+The following tables are used for refreshing.
+
+.. sourcecode:: postgres
+
+ CREATE TABLE refresh_sessions (
+ session_pub BYTEA,
+ order_sig BYTEA,
+ index_reveal INT2,
+ );
+
+ CREATE TABLE refresh_melt (
+ session_pub BYTEA REFERENCES refresh_sessions (session_pub),
+ session_sig BYTEA,
+ denom_pub BYTEA,
+ denom_sig BYTEA,
+ coin_pub BYTEA,
+ coin_sig BYTEA,
+ );
+
+ -- create links to old coins
+ CREATE TABLE refresh_link_commits (
+ session_pub BYTEA,
+ session_sig BYTEA,
+ coin_pub BYTEA,
+ transfer_pub BYTEA,
+ link_secret_enc BYTEA,
+ link_secret_hash BYTEA,
+ idx INTEGER
+ );
+
+ CREATE TABLE refresh_order (
+ -- EdDSA public key of the melting session
+ session_pub BYTEA REFERENCES refresh_sessions (session_pub),
+ -- denomination key for the newly ordered coin
+ denom_pub BYTEA,
+ -- signature from session key over coin order
+ session_sig BYTEA,
+ );
+
+ CREATE TABLE refresh_coin_commits (
+ session_pub BYTEA,
+ idx INTEGER,
+ coin_link_enc BYTEA,
+ -- The blinding key (public part) for the purse, can be NULL
+ -- if funds are insufficient or the mint has not
+ -- generated it yet.
+ blinding_pub BYTEA,
+
+ -- The blinding key (private part).
+ blinding_priv BYTEA,
+ -- The coin blank provided by the customer.
+ blind_blank_coin BYTEA,
+ -- encrypted stuff
+ coin_link_enc BYTEA,
+ );
+
+
+----------------
+Key Management
+----------------
+The command line tool `neuro-mint-keyup` updates the signing key and
+list of denominations offered by the mint. This process requires the
+mint's master key, and should be done offline in order to protect the master key.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuring keys and coin types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The denominations and key expirations for the mint are specified in a configuration file.
+
+The section `[mint_keys]` containts the following entries:
+
+* `signkey_duration`: How long should one signing key be used?
+* `lookahead_sign`: For how far into the future should keys be issued? This determines the frequency
+ of offline signing with the master key.
+* `lookahead_provide`: How far into the future should the mint provide keys? This determines the attack
+ window on keys.
+* `coin_types`: Space-separated list of coin aliases that the mint should provide. The coin aliases
+ are used as the key configuration sections regarding the coin type.
+
+The configuration refers to each denomination type by an alphanumeric alias. This alias is used to identify
+the same denomination in different sections. Configuration values are assigned as `<ALIAS> = <VALUE>`
+in the respective section.
+
+* `[mint_denom_duration_withdraw]`: How long can a coin of this type be withdrawn?
+ This limits the losses incured by the mint when a denomination key is compromised.
+* `[mint_denom_duration_overlap]`: What is the overlap of the withdrawal timespan for
+ a coin type?
+* `[mint_denom_duration_spend]`: How long is a coin of the given type valid? Smaller
+ values result in lower storage costs for the mint.
+* `[mint_denom_value]`: What is the value of the coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_fee_withdraw]`: What does it cost to withdraw this coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_fee_refresh]`: What does it cost to refresh this coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_fee_deposit]`: What does it cost to refresh this coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_kappa]`: How easy should cheating be for the customer when refreshing?
+
+^^^^^^^^^^^^^^^^^^^
+Key Storage Format
+^^^^^^^^^^^^^^^^^^^
+The mint's key directory contains the two subdirectories `signkeys` and `coinkeys`.
+
+The file `master.pub` stores the mint's master public key.
+
+The directory `signkeys` contains signkey files, where the name is the start date of the respective key.
+
+The `coinkeys` directory additionaly contains a subdirectory for each coin type alias. These contain
+coinkey files, where the name is again the start timestamp of the respective key.
+
+
+-------
+Purses
+-------
+Incoming transactions to the mint's provider result in the creation or update of `purses`, identified
+by their withdrawal key.
+
+The command line tool `neuro-mint-modpurse` allows create and add money to purses in the mint's database.
+
+
diff --git a/index.rst b/index.rst
new file mode 100644
index 0000000..55b1dcb
--- /dev/null
+++ b/index.rst
@@ -0,0 +1,54 @@
+Welcome to Neuro's documentation!
+=================================
+
+We are building an anonymous, taxable payment system using modern
+cryptography. Customers will use traditional money transfers to send
+money to a digital Mint and in return receive (anonymized) digital
+cash. Customers can use this digital cash to anonymously pay
+Merchants. Merchants can redeem the digital cash for traditional
+money at the digital Mint. As Merchants are not anonymous, they can
+be taxed, enabling income or sales taxes to be withheld by the state
+while providing anonymity for Customers.
+
+Cryptography is used to ensure that none of the participants can
+defraud the others without being detected immediately; however, in
+practice a fradulent Mint might go bankrupt instead of paying the
+Merchants and thus the Mint will need to be audited regularly like any
+other banking institution.
+
+The system will be based on free software and open protocols.
+In this document, we describe the REST-based API of the Mint,
+which is at the heart of the system.
+
+
+Contents
+========
+
+Protocol Specification:
+
+.. toctree::
+ :maxdepth: 2
+
+ api-mint
+ api-merchant
+
+Implementation:
+
+.. toctree::
+ :maxdepth: 2
+
+ impl-mint
+
+Supported Wire Transfer Formats:
+
+.. toctree::
+ :maxdepth: 2
+
+ wireformats
+
+
+Indices and tables
+==================
+
+* :ref:`search`
+
diff --git a/wireformats.rst b/wireformats.rst
new file mode 100644
index 0000000..705f489
--- /dev/null
+++ b/wireformats.rst
@@ -0,0 +1,43 @@
+.. _wireformats:
+
+Wire Transfer Formats
+=====================
+
+A wire transfer is essential for the mint to transfer funds into a merchant's
+account upon a successful deposit (see :ref:`deposit request <deposit>`). The
+merchant has to include the necessary information for the mint to initiate the
+wire transfer.
+
+The information required for wire transfer depends on the type of wire transfer
+used. Since the wire transfers differ for each region, we document here the
+ones currently supported by the mint.
+
+SEPA
+----
+
+The Single Euro Payments Area (SEPA) [#sepa]_ is a regulation for electronic
+payments. Since its adoption in 2012, all of the banks in the Eurozone and some
+banks in other countries adhere to this standard for sending and receiving
+payments. Note that the currency of the transfer will always be *EURO*. In
+case the receiving account is in a currency other than EURO, the receiving bank
+may covert the amount into that currency; currency exchange charges may be
+levied by the receiving bank.
+
+For the merchant to receive deposits through SEPA, the deposit request should
+contain a JSON object with the following fields:
+
+ .. The following are taken from Page 33, SEPA_SCT.pdf .
+
+ * `type`: the string constant `"SEPA"`
+ * `IBAN`: the IBAN of the account of the beneficiary
+ * `name`: the name of the beneficiary
+ * `BIC`: the BIC code of the beneficiary's bank
+ * `edate`: the date given as a timestamp indicating when the transfer should
+ be executed
+ * `r`: a 64-bit random nounce
+
+The JSON object may optionally contain:
+ * `address`: the address of the Beneficiary
+
+.. [#sepa] SEPA - Single Euro Payments Area:
+ http://www.ecb.europa.eu/paym/sepa/html/index.en.html