commit 90669a5fb3178025d38258616194f91812b02764 parent 7a1ddc0871176ba1e5adf7eb55c7bea39e80f1c7 Author: Florian Dold <florian@dold.me> Date: Mon, 4 Sep 2023 18:59:33 +0200 various doc fixes Diffstat:
94 files changed, 463 insertions(+), 450 deletions(-)
diff --git a/Makefile b/Makefile @@ -50,39 +50,9 @@ help: clean: rm -rf $(BUILDDIR)/* - -arch-api.png: arch-api.dot - dot -Tpng arch-api.dot > arch-api.png -transaction-common-states.png: transaction-common-states.dot - dot -Tpng transaction-common-states.dot > transaction-common-states.png -transaction-withdrawal-states.png: transaction-withdrawal-states.dot - dot -Tpng transaction-withdrawal-states.dot > transaction-withdrawal-states.png -transaction-payment-states.png: transaction-payment-states.dot - dot -Tpng transaction-payment-states.dot > transaction-payment-states.png -transaction-refund-states.png: transaction-refund-states.dot - dot -Tpng transaction-refund-states.dot > transaction-refund-states.png -transaction-refresh-states.png: transaction-refresh-states.dot - dot -Tpng transaction-refresh-states.dot > transaction-refresh-states.png -transaction-reward-states.png: transaction-reward-states.dot - dot -Tpng transaction-reward-states.dot > transaction-reward-states.png -transaction-deposit-states.png: transaction-deposit-states.dot - dot -Tpng transaction-deposit-states.dot > transaction-deposit-states.png -transaction-push-debit-states.png: transaction-push-debit-states.dot - dot -Tpng transaction-push-debit-states.dot > transaction-push-debit-states.png -transaction-push-credit-states.png: transaction-push-credit-states.dot - dot -Tpng transaction-push-credit-states.dot > transaction-push-credit-states.png -transaction-pull-credit-states.png: transaction-pull-credit-states.dot - dot -Tpng transaction-pull-credit-states.dot > transaction-pull-credit-states.png -transaction-pull-debit-states.png: transaction-pull-debit-states.dot - dot -Tpng transaction-pull-debit-states.dot > transaction-pull-debit-states.png -coin.png: coin.dot - dot -Tpng coin.dot > coin.png -deposit.png: deposit.dot - dot -Tpng deposit.dot > deposit.png -reserve.png: reserve.dot - dot -Tpng reserve.dot > reserve.png - -diagrams: arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png +.PHONY: diagrams +diagrams: + $(MAKE) -C images/ # The html-linked builder does not support caching, so we diff --git a/arch-api.png b/arch-api.png Binary files differ. diff --git a/arch.png b/arch.png Binary files differ. diff --git a/auditor-db.png b/auditor-db.png Binary files differ. diff --git a/coin.png b/coin.png Binary files differ. diff --git a/conf.py b/conf.py @@ -108,6 +108,8 @@ exclude_patterns = [ "prebuilt", "**/README.md", "extract-tsdefs", + "frags", + "orphaned", ] # The reST default role (used for this markup: `text`) to use for all @@ -161,7 +163,7 @@ html_short_title = "GNU Taler" # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = "taler-logo.svg" +html_logo = "images/taler-logo.svg" # 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 diff --git a/core/api-common.rst b/core/api-common.rst @@ -18,6 +18,8 @@ .. _http-common: +.. _foo_bar: + ================================== Conventions for Taler RESTful APIs ================================== @@ -1016,6 +1018,7 @@ within the }; .. _TALER_AgeWithdrawConfirmationPS: + .. sourcecode:: c struct TALER_AgeWithdrawConfirmationPS { @@ -1029,7 +1032,9 @@ within the .. _TALER_DepositRequestPS: + .. sourcecode:: c + :caption: struct declaration struct TALER_DepositRequestPS { /** @@ -1051,7 +1056,9 @@ within the }; .. _TALER_DepositConfirmationPS: + .. sourcecode:: c + :caption: struct declaration struct TALER_DepositConfirmationPS { /** diff --git a/core/api-exchange.rst b/core/api-exchange.rst @@ -120,7 +120,7 @@ possibly by using HTTPS. // with by default. Small capitals should // be used to render fractions beyond the number // given here (like on gas stations). - currency_fraction_digits: integer; + currency_fraction_digits: Integer; // Absolute cost offset for the STEFAN curve used // to (over) approximate fees payable by amount. diff --git a/core/api-libeufin-bank.rst b/core/api-libeufin-bank.rst @@ -77,7 +77,7 @@ Config Account Management ------------------ -.. _libeufin-account-register: +.. _libeufin-bank-account-register: .. http:post:: /accounts @@ -185,7 +185,7 @@ Account Management // If missing, cashouts will fail. // In the future, might be used for other transactions // as well. - challenge_data?: ChallengeData; + challenge_contact_data?: ChallengeContactData; // 'payto' address pointing a bank account // external to the libeufin-bank. @@ -324,6 +324,7 @@ Account Management debit_threshold: Amount; } +.. _libeufin-bank-account-info: .. http:get:: /accounts/$username @@ -353,7 +354,7 @@ Account Management // Number indicating the max debit allowed for the requesting user. debit_threshold: Amount; - contact_data?: ContactData; + contact_data?: ChallengeContactData; // 'payto' address pointing the bank account // where to send cashouts. This field is optional diff --git a/core/api-merchant.rst b/core/api-merchant.rst @@ -1342,7 +1342,7 @@ KYC status checks ------------- Bank Accounts --------------- +------------- One or more bank accounts must be associated with an instance so that the instance can receive payments. Payments may be made diff --git a/core/api-overview.rst b/core/api-overview.rst @@ -84,25 +84,20 @@ Overview :doc:`Docs <api-bank-integration>` - * Taler Bank Access API + * Libefin Bank API - **Summary**: Protocol to manage access to a bank account by the owner of the account. Allows access to account balance, transaction list, payment initiation. + **Summary**: Protocol to manage a simple core bank with optional regional + currency support. Allows access to a bank account by the owner of the + account. The owner can access the account balance, transaction list, and initate + payments. **Providers**: LibEuFin demobank, Taler Fakebank (partial) **Consumers**: Cashier App, demobank-ui - :doc:`Docs <api-bank-access>` + :doc:`Docs <api-libeufin-bank>` - * Taler Bank Circuits API - - **Summary**: Allows management of bank user accounts in a regional currency bank deployment. - - **Providers**: LibEuFin Sandbox demobank - - **Consumers**: demobank-ui - * Taler Wire Gateway API **Summary**: Allows the Taler Exchange to query incoming transactions and initiate payments with a protocol that abstracts away details of the underlying banking system. @@ -111,7 +106,7 @@ Overview **Consumers**: GNU Taler Exchange, Wire Auditor - :doc:`Docs <api-wire>` + :doc:`Docs <api-bank-wire>` * Taler Sync API diff --git a/design-documents/004-wallet-withdrawal-flow.rst b/design-documents/004-wallet-withdrawal-flow.rst @@ -104,7 +104,7 @@ For those, the wallet should not offer the option to change an exchange. After confirming the withdrawal, the user is brought to the list of transactions of the current currency. -It will include a pending `TransactionWithdrawal` which might require additional user confirmation +It will include a pending ``TransactionWithdrawal`` which might require additional user confirmation such as a two-factor-authentication step with the bank. 1. The bank transfer happens immediately @@ -114,7 +114,7 @@ such as a two-factor-authentication step with the bank. 3. The bank provides a ``bankConfirmationUrl`` that the user needs to visit. If the withdrawal proceeds very quickly, -the `TransactionWithdrawal` might not show as pending +the ``TransactionWithdrawal`` might not show as pending and its effective amount is added to the displayed balance right away. Alternatives diff --git a/design-documents/016-backoffice-order-management.rst b/design-documents/016-backoffice-order-management.rst @@ -32,7 +32,7 @@ Proposed Solution Listing orders -------------- -.. image:: ../backoffice-order-list.svg +.. image:: ../images/backoffice-order-list.svg :width: 800 4 tabs will be show for an easy access to common filter, click on any of this and @@ -101,7 +101,7 @@ In both cases, the total unit and price of the products will be calculated and shown in the bottom of the section. If the merchant collapse one of the product list a line with a resume of the total price and units will be shown. -.. image:: ../backoffice-order-create.product-section.svg +.. image:: ../images/backoffice-order-create.product-section.svg :width: 800 Create order: Price section @@ -117,7 +117,7 @@ of all products prices will be shown. The ``order price`` will default to ``total products price``. The ``products taxes`` and ``profit`` will be shown since ``order price`` cannot be less that ``product taxes``. -.. image:: ../backoffice-order-create.price-section.svg +.. image:: ../images/backoffice-order-create.price-section.svg :width: 800 Create order: Payment section @@ -142,7 +142,7 @@ This section show optional values that can be overwritten by the merchant * ``wire_fee_amortization``: default value from the instance -.. image:: ../backoffice-order-create.payment-section.svg +.. image:: ../images/backoffice-order-create.payment-section.svg :width: 800 Create order: all section expanded @@ -150,7 +150,7 @@ Create order: all section expanded An example of how all section in a page will be shown. -.. image:: ../backoffice-order-create.all-expanded.svg +.. image:: ../images/backoffice-order-create.all-expanded.svg :width: 800 @@ -291,10 +291,10 @@ Ask for: * drop down options: duplicated, requested by customer, other * after selecting, free text for additional information -.. image:: ../backoffice-order-refund.svg +.. image:: ../images/backoffice-order-refund.svg :width: 800 -.. image:: ../backoffice-order-refund.already.svg +.. image:: ../images/backoffice-order-refund.already.svg :width: 800 Example of details by status @@ -302,16 +302,16 @@ Example of details by status -.. image:: ../backoffice-order-details.paid.svg +.. image:: ../images/backoffice-order-details.paid.svg :width: 800 -.. image:: ../backoffice-order-details.unpaid.svg +.. image:: ../images/backoffice-order-details.unpaid.svg :width: 800 -.. image:: ../backoffice-order-details.claimed.svg +.. image:: ../images/backoffice-order-details.claimed.svg :width: 800 -.. image:: ../backoffice-order-details.refunded.svg +.. image:: ../images/backoffice-order-details.refunded.svg :width: 800 @@ -323,7 +323,7 @@ pagination ---------- order list was originally thought with pagination footer -.. image:: ../backoffice-order-list.pagination.svg +.. image:: ../images/backoffice-order-list.pagination.svg :width: 800 ascending boolean flag cloud be eliminated using the load before and load after diff --git a/design-documents/017-backoffice-inventory-management.rst b/design-documents/017-backoffice-inventory-management.rst @@ -31,7 +31,7 @@ Proposed Solution Inspecting inventory -------------------- -.. image:: ../backoffice-product-list.svg +.. image:: ../images/backoffice-product-list.svg :width: 800 Listing the product will shown this columns: @@ -53,7 +53,7 @@ Actions will be Create and Update Product form ------------------------------ -.. image:: ../backoffice-product-create.svg +.. image:: ../images/backoffice-product-create.svg :width: 800 Update product will use the same form except for the ``product_id`` @@ -111,7 +111,7 @@ Stock management * a label at the end of the section will inform about the final result -.. image:: ../backoffice-product-create.stock.svg +.. image:: ../images/backoffice-product-create.stock.svg :width: 800 @@ -124,7 +124,7 @@ Alternatives * rows in the table can be expandable when clicked to get access to some common actions like increase stock or change price -.. image:: ../backoffice-product-list.actions.svg +.. image:: ../images/backoffice-product-list.actions.svg :width: 800 * detail page was intentionally left out since all information can be access diff --git a/design-documents/020-backoffice-rewards-management.rst b/design-documents/020-backoffice-rewards-management.rst @@ -29,7 +29,7 @@ Proposed Solution Listing reserves ---------------- -.. image:: ../backoffice-reserve-list.svg +.. image:: ../images/backoffice-reserve-list.svg :width: 400 @@ -54,7 +54,7 @@ columns: Create new reserve ------------------ -.. image:: ../backoffice-reserve-create.svg +.. image:: ../images/backoffice-reserve-create.svg :width: 400 fields: @@ -73,23 +73,23 @@ Authorize Reward The merchant can authorize rewards clicking in the plus (+) button that will bring the next popup -.. image:: ../backoffice-reward-create.svg +.. image:: ../images/backoffice-reward-create.svg :width: 400 after confirm it will continue with a success page: -.. image:: ../backoffice-reward-create.confirmation.svg +.. image:: ../images/backoffice-reward-create.confirmation.svg :width: 400 Details of reserve ------------------ -.. image:: ../backoffice-reserve-details.svg +.. image:: ../images/backoffice-reserve-details.svg :width: 400 Rewards sorted from newer to older When the reserve has not yet funded -.. image:: ../backoffice-reserve-details.unfunded.svg +.. image:: ../images/backoffice-reserve-details.unfunded.svg :width: 400 diff --git a/design-documents/025-withdraw-from-wallet.rst b/design-documents/025-withdraw-from-wallet.rst @@ -29,7 +29,7 @@ This screen the user will be able to select the currency from a list of known currencies, switch the exchange, go to a page to add an exchange and define an amount to be withdraw. -.. image:: ../wallet-start-manual-withdraw.svg +.. image:: ../images/wallet-start-manual-withdraw.svg :width: 800 @@ -39,7 +39,7 @@ Success Here the user will see the account details where it needs to send money to complete the withdrawal. -.. image:: ../wallet-confirm-withdraw.svg +.. image:: ../images/wallet-confirm-withdraw.svg :width: 800 Transaction history diff --git a/design-documents/029-mobile-ui.rst b/design-documents/029-mobile-ui.rst @@ -23,7 +23,7 @@ Requirements Proposed Solution ================= -.. image:: ../wallet-mobile-overview.svg +.. image:: ../images/wallet-mobile-overview.svg :width: 800 diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst @@ -60,7 +60,7 @@ indicates errors the wallet experienced while taking active steps to abort the t ``aborted``: Similar to ``done``, but the transaction was successfully aborted instead of successfully finished. It will have the information of when (timestamp) it was aborted and in which pending sub-state the abort action was initiated. Also, we can -include more information information relevant to the transaction in `abortReason` +include more information information relevant to the transaction in ``abortReason`` ``suspended``: Similar to a ``aborted`` transaction, but the transaction was could be resumed and may then still succeed. @@ -135,7 +135,7 @@ the transaction type, and usually only one of the four choices should be offered. -.. image:: ../transaction-common-states.png +.. image:: ../images/transaction-common-states.png Boxed labels indicate an end state in which there is no network activity and @@ -324,7 +324,7 @@ Transaction Type: Withdrawal Only once all coins were spent, the withdraw is fully removed. -.. image:: ../transaction-withdrawal-states.png +.. image:: ../images/transaction-withdrawal-states.png Transaction Type: Payment to Merchant @@ -452,7 +452,7 @@ Transaction Type: Payment to Merchant When a payment is deleted, associated refund transactions are always deleted with it. -.. image:: ../transaction-payment-states.png +.. image:: ../images/transaction-payment-states.png Transaction Type: Refund @@ -471,7 +471,7 @@ payment transaction. The refund failed permanently. -.. image:: ../transaction-refund-states.png +.. image:: ../images/transaction-refund-states.png Transaction Type: Refresh @@ -522,7 +522,7 @@ the same as if the double-spending transaction had been deleted by the user. All memory of the refresh operation is lost, but of course the resulting fresh coins are preserved. -.. image:: ../transaction-refresh-states.png +.. image:: ../images/transaction-refresh-states.png @@ -580,7 +580,7 @@ Transaction Type: Reward All memory of the reward operation is lost, but of course the resulting fresh coins are preserved. -.. image:: ../transaction-reward-states.png +.. image:: ../images/transaction-reward-states.png Transaction Type: Deposit @@ -679,7 +679,7 @@ Transaction Type: Deposit All memory of the deposit operation is lost. -.. image:: ../transaction-deposit-states.png +.. image:: ../images/transaction-deposit-states.png Transaction Type: Peer Push Debit @@ -757,7 +757,7 @@ States and transitions: All memory of the push debit operation is lost. -.. image:: ../transaction-push-debit-states.png +.. image:: ../images/transaction-push-debit-states.png Transaction Type: Peer Push Credit @@ -879,7 +879,7 @@ States and transitions: All memory of the push credit operation is lost. -.. image:: ../transaction-push-credit-states.png +.. image:: ../images/transaction-push-credit-states.png Transaction Type: Peer Pull Credit @@ -983,7 +983,7 @@ TODO: Also specify variant where account reserve needs to be created / funded fi * ``deleted`` -.. image:: ../transaction-pull-credit-states.png +.. image:: ../images/transaction-pull-credit-states.png Transaction Type: Peer Pull Debit @@ -1055,7 +1055,7 @@ Transaction Type: Peer Pull Debit All information about the invoice has been deleted. -.. image:: ../transaction-pull-debit-states.png +.. image:: ../images/transaction-pull-debit-states.png Alternatives ============ diff --git a/design-documents/038-demobanks-protocol-suppliers.rst b/design-documents/038-demobanks-protocol-suppliers.rst @@ -101,7 +101,7 @@ Static X-LIBEUFIN-BANK with dynamic demobank The ``x-libeufin-bank`` protocol supplier is reachable under ``/demobanks/{demobankName}/access-api/``. As the path suggests, -it offers banking operations via the :doc:`Access API </core/api-bank-access>`. +it offers banking operations via the :doc:`Libeufin Bank API </core/api-libeufin-bank>`. It is static in the sense that it's not possible to assign a name to one particular x-libeufin-bank protocol supplier. On the other hand, the demobank is dynamic because can be specified along the path diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst @@ -292,7 +292,7 @@ The contract terms v1 will have the following structure: }; - .. ts:def:: ContractInputRation +.. ts:def:: ContractInputRation interface ContractInputRation { @@ -322,7 +322,7 @@ The contract terms v1 will have the following structure: // Number of tokens of this type required. // Defaults to one if the field is not provided. - number?: integer; + number?: Integer; }; @@ -380,11 +380,13 @@ The contract terms v1 will have the following structure: details: OutputTokenClass; } +.. ts:def:: OutputTokenClass + type OutputTokenClass = | OutputTokenClassSubscription | OutputTokenClassDiscount -.. ts:def::OutputTokenClassSubscription +.. ts:def:: OutputTokenClassSubscription interface OutputTokenClassSubscription { @@ -444,7 +446,7 @@ The contract terms v1 will have the following structure: // Number of tokens issued according to ASS authority // FIXME: this is still rather speculative in the design... - ass?: integer; + ass?: Integer; // Signature affirming sum of token issuance deposit (?) fees // collected by an exchange according to the ASS authority. @@ -481,10 +483,10 @@ consumes an available discount token, that contract should be moved up in the list. Which specific alternative contract was chosen by the user is indicated in the -subcontract index field of the `TALER_DepositRequestPS`. +subcontract index field of the :ref:`TALER_DepositRequestPS`. FIXME-DOLD: Should we also sign over this in the -`TALER_DepositConfirmationPS`? +:ref:`TALER_DepositConfirmationPS`? Output Commitments @@ -498,13 +500,13 @@ but of course not the reserve signature. .. note:: We can probably spec this rather nicely if we first change the -batch-withdraw API to only use a single reserve signature. + batch-withdraw API to only use a single reserve signature. This array of blinded values is hashed to create the output commitment hash -(``h_outputs``) in the `TALER_DepositRequestPS`. +(``h_outputs``) in the :ref:`TALER_DepositRequestPS`. FIXME-DOLD: Should we also sign over this in the -`TALER_DepositConfirmationPS`? +:ref:`TALER_DepositConfirmationPS`? diff --git a/design-documents/047-stefan.rst b/design-documents/047-stefan.rst @@ -50,7 +50,7 @@ offered by the exchange. that we can invert the computation and calculate gross amounts from net amounts and actually get a nice invertible computation where both directions always match. Note that the computation itself is nevertheless - non-trivial involving Newton's method to solve `f(x)=0` using a + non-trivial involving Newton's method to solve ``f(x)=0`` using a well-estimated starting point for the iteration to avoid divergence issues. Finally, while we do the STEFAN-curve computations using doubles, we should then convert the final amounts back into "human-friendly" numbers rounding diff --git a/exchange-db.png b/exchange-db.png Binary files differ. diff --git a/frags/installing-challenger.rst b/frags/installing-challenger.rst @@ -0,0 +1 @@ +TBD. diff --git a/images/Makefile b/images/Makefile @@ -0,0 +1,33 @@ +diagrams: arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png + +arch-api.png: arch-api.dot + dot -Tpng arch-api.dot > arch-api.png +transaction-common-states.png: transaction-common-states.dot + dot -Tpng transaction-common-states.dot > transaction-common-states.png +transaction-withdrawal-states.png: transaction-withdrawal-states.dot + dot -Tpng transaction-withdrawal-states.dot > transaction-withdrawal-states.png +transaction-payment-states.png: transaction-payment-states.dot + dot -Tpng transaction-payment-states.dot > transaction-payment-states.png +transaction-refund-states.png: transaction-refund-states.dot + dot -Tpng transaction-refund-states.dot > transaction-refund-states.png +transaction-refresh-states.png: transaction-refresh-states.dot + dot -Tpng transaction-refresh-states.dot > transaction-refresh-states.png +transaction-reward-states.png: transaction-reward-states.dot + dot -Tpng transaction-reward-states.dot > transaction-reward-states.png +transaction-deposit-states.png: transaction-deposit-states.dot + dot -Tpng transaction-deposit-states.dot > transaction-deposit-states.png +transaction-push-debit-states.png: transaction-push-debit-states.dot + dot -Tpng transaction-push-debit-states.dot > transaction-push-debit-states.png +transaction-push-credit-states.png: transaction-push-credit-states.dot + dot -Tpng transaction-push-credit-states.dot > transaction-push-credit-states.png +transaction-pull-credit-states.png: transaction-pull-credit-states.dot + dot -Tpng transaction-pull-credit-states.dot > transaction-pull-credit-states.png +transaction-pull-debit-states.png: transaction-pull-debit-states.dot + dot -Tpng transaction-pull-debit-states.dot > transaction-pull-debit-states.png +coin.png: coin.dot + dot -Tpng coin.dot > coin.png +deposit.png: deposit.dot + dot -Tpng deposit.dot > deposit.png +reserve.png: reserve.dot + dot -Tpng reserve.dot > reserve.png + diff --git a/arch-api.dot b/images/arch-api.dot diff --git a/arch.dot b/images/arch.dot diff --git a/backoffice-order-create.all-expanded.svg b/images/backoffice-order-create.all-expanded.svg diff --git a/backoffice-order-create.payment-section.svg b/images/backoffice-order-create.payment-section.svg diff --git a/backoffice-order-create.price-section.svg b/images/backoffice-order-create.price-section.svg diff --git a/backoffice-order-create.product-section.svg b/images/backoffice-order-create.product-section.svg diff --git a/backoffice-order-details.claimed.svg b/images/backoffice-order-details.claimed.svg diff --git a/backoffice-order-details.paid.svg b/images/backoffice-order-details.paid.svg diff --git a/backoffice-order-details.refunded.svg b/images/backoffice-order-details.refunded.svg diff --git a/backoffice-order-details.unpaid.svg b/images/backoffice-order-details.unpaid.svg diff --git a/backoffice-order-list.pagination.svg b/images/backoffice-order-list.pagination.svg diff --git a/backoffice-order-list.svg b/images/backoffice-order-list.svg diff --git a/backoffice-order-refund.already.svg b/images/backoffice-order-refund.already.svg diff --git a/backoffice-order-refund.svg b/images/backoffice-order-refund.svg diff --git a/backoffice-product-create.stock.svg b/images/backoffice-product-create.stock.svg diff --git a/backoffice-product-create.svg b/images/backoffice-product-create.svg diff --git a/backoffice-product-create.with-stock.svg b/images/backoffice-product-create.with-stock.svg diff --git a/backoffice-product-create.without-stock.svg b/images/backoffice-product-create.without-stock.svg diff --git a/backoffice-product-list.actions.svg b/images/backoffice-product-list.actions.svg diff --git a/backoffice-product-list.svg b/images/backoffice-product-list.svg diff --git a/backoffice-product-update.svg b/images/backoffice-product-update.svg diff --git a/backoffice-reserve-create.svg b/images/backoffice-reserve-create.svg diff --git a/backoffice-reserve-details.svg b/images/backoffice-reserve-details.svg diff --git a/backoffice-reserve-details.unfunded.svg b/images/backoffice-reserve-details.unfunded.svg diff --git a/backoffice-reserve-list.svg b/images/backoffice-reserve-list.svg diff --git a/backoffice-tip-create.confirmation.svg b/images/backoffice-reward-create.confirmation.svg diff --git a/backoffice-tip-create.svg b/images/backoffice-reward-create.svg diff --git a/coin.dot b/images/coin.dot diff --git a/deposit.dot b/images/deposit.dot diff --git a/diagram.dot b/images/diagram.dot diff --git a/replication.svg b/images/replication.svg diff --git a/reserve.dot b/images/reserve.dot diff --git a/taler-logo.svg b/images/taler-logo.svg diff --git a/transaction-common-states.dot b/images/transaction-common-states.dot diff --git a/transaction-common-states.svg b/images/transaction-common-states.svg diff --git a/transaction-deposit-states.dot b/images/transaction-deposit-states.dot diff --git a/transaction-payment-states.dot b/images/transaction-payment-states.dot diff --git a/transaction-pull-credit-states.dot b/images/transaction-pull-credit-states.dot diff --git a/transaction-pull-debit-states.dot b/images/transaction-pull-debit-states.dot diff --git a/transaction-push-credit-states.dot b/images/transaction-push-credit-states.dot diff --git a/transaction-push-debit-states.dot b/images/transaction-push-debit-states.dot diff --git a/transaction-refresh-states.dot b/images/transaction-refresh-states.dot diff --git a/transaction-refund-states.dot b/images/transaction-refund-states.dot diff --git a/transaction-reward-states.dot b/images/transaction-reward-states.dot diff --git a/transaction-withdrawal-states.dot b/images/transaction-withdrawal-states.dot diff --git a/transaction-withdrawal-states.svg b/images/transaction-withdrawal-states.svg diff --git a/wallet-confirm-withdraw.svg b/images/wallet-confirm-withdraw.svg diff --git a/wallet-mobile-overview.svg b/images/wallet-mobile-overview.svg diff --git a/wallet-start-manual-withdraw.svg b/images/wallet-start-manual-withdraw.svg diff --git a/libeufin/circuit-cli-commands.rst b/libeufin/circuit-cli-commands.rst @@ -9,19 +9,19 @@ name is one subcommand available in this pattern: Finally, each section name links to the related API documentation of the endpoint being addressed. -:ref:`circuit-account-info <circuit-account-info>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-account-info +^^^^^^^^^^^^^^^^^^^^ - Retrieve Circuit information about one account. Useful to get cash-out - address and contact details. +Retrieve Circuit information about one account. Useful to get cash-out +address and contact details. Options: --username TEXT Username of the account to retrieve. It defaults to LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin'. --help Show this message and exit. -:ref:`circuit-accounts <circuit-account-list>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-accounts +^^^^^^^^^^^^^^^^ Gets the list of all the accounts managed by the Circuit. Only 'admin' allowed @@ -29,10 +29,10 @@ Options: Options: --help Show this message and exit. -:ref:`circuit-cashout <circuit-cashout>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-cashout +^^^^^^^^^^^^^^^ - Create a cash-out operation. If successful, the user gets a TAN. +Create a cash-out operation. If successful, the user gets a TAN. Options: --subject TEXT Payment subject to associate to the outgoing and @@ -50,20 +50,20 @@ Options: --help Show this message and exit. -:ref:`circuit-cashout-abort <circuit-cashout-abort>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-cashout-abort +^^^^^^^^^^^^^^^^^^^^^ - Abort a cash-out operation. Admin and author are allowed to request. +Abort a cash-out operation. Admin and author are allowed to request. Options: --uuid TEXT UUID of the cash-out operation to abort. [required] --help Show this message and exit. -:ref:`circuit-cashout-confirm <circuit-cashout-confirm>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-cashout-confirm +^^^^^^^^^^^^^^^^^^^^^^^ - Confirm a cash-out operation. Only the author is allowed (no admin). +Confirm a cash-out operation. Only the author is allowed (no admin). Options: --tan TEXT TAN that authorizes the cash-out operaion. [required] @@ -71,42 +71,42 @@ Options: --help Show this message and exit. -:ref:`circuit-cashout-details <circuit-cashout-details>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-cashout-details +^^^^^^^^^^^^^^^^^^^^^^^ - Retrieve status information about one cash-out operation. Admin and author - are allowed to request. +Retrieve status information about one cash-out operation. Admin and author +are allowed to request. Options: --uuid TEXT UUID of the cash-out operation to retrieve. [required] --help Show this message and exit. -:ref:`circuit-cashouts <circuit-cashouts>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-cashouts +^^^^^^^^^^^^^^^^ - Gets the list of all the pending and confirmed cash-out operations. +Gets the list of all the pending and confirmed cash-out operations. Options: --help Show this message and exit. -:ref:`circuit-delete-account <circuit-delete-account>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-delete-account +^^^^^^^^^^^^^^^^^^^^^^ - Delete one account. Only available to the administrator and for accounts - with zero balance. +Delete one account. Only available to the administrator and for accounts +with zero balance. Options: --username TEXT account to delete [required] --help Show this message and exit. -:ref:`circuit-password-reconfig <circuit-password-reconfig>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-password-reconfig +^^^^^^^^^^^^^^^^^^^^^^^^^ - Ask interactively to change the password. It needs administrator or owner - credentials +Ask interactively to change the password. It needs administrator or owner +credentials Options: --username TEXT Username whose password will change. Defaults to @@ -115,11 +115,11 @@ Options: --help Show this message and exit. -:ref:`circuit-reconfig <circuit-reconfig>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-reconfig +^^^^^^^^^^^^^^^^ - Reconfigure an account with cash-out capabilities. It needs administrator - or owner credentials +Reconfigure an account with cash-out capabilities. It needs administrator +or owner credentials Options: --phone TEXT Phone number for the SMS TAN @@ -132,12 +132,12 @@ Options: --help Show this message and exit. -:ref:`circuit-register <circuit-register>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +circuit-register +^^^^^^^^^^^^^^^^ - Register a new account with cash-out capabilities. It needs administrator - credentials, and the new account password exported in - LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD. +Register a new account with cash-out capabilities. It needs administrator +credentials, and the new account password exported in +LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD. Options: --username TEXT new account username [required] diff --git a/libeufin/ebics3-test-tutorial.rst b/libeufin/ebics3-test-tutorial.rst @@ -2,7 +2,7 @@ EBICS 3.0 with PostFinance ########################## This tutorial shows how LibEuFin and the PostFinance test platform -communicate via EBICS 3. LibEuFin acts as the client via the `Nexus` +communicate via EBICS 3. LibEuFin acts as the client via the Nexus component. To hide the configuration details to the user, all the client activity is handled by a Docker image. diff --git a/libeufin/local-currencies-tutorial.rst b/libeufin/local-currencies-tutorial.rst @@ -9,7 +9,7 @@ into fiat (a.k.a. cashing out). The banking capabilities are offered by a LibEuFin service called *Sandbox*. In particular, the tutorial relies on the -:ref:`Circuit API <circuit-api>`. More information about libEufin +:ref:`Libeufin Bank API <libeufin-bank-api>`. More information about libEufin can be found in the :doc:`How-To page </libeufin/nexus-tutorial>`. The following sections show how to install and launch Sandbox diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst @@ -438,7 +438,7 @@ The responsible options are For more information on the available commands, use the built-in ``--help`` flag. The full functionality of the sandbox is available via -the :ref:`Sandbox API <sandbox-api>`. +the :ref:`Libeufin Bank API <libeufin-bank-api>`. Connect Nexus with the bank. ============================ diff --git a/manpages/sync-dbconfig.1.rst b/manpages/sync-dbconfig.1.rst @@ -13,12 +13,12 @@ Synopsis ======== **sync-dbconfig** -[**-c** *FILENAME* *] +[**-c** *FILENAME*] [**-h**] -[**-n** *NAME* *] +[**-n** *NAME*] [**-r**] [**-s**] -[**-u** *USER* *] +[**-u** *USER*] Description =========== diff --git a/manpages/taler-auditor-dbconfig.1.rst b/manpages/taler-auditor-dbconfig.1.rst @@ -13,12 +13,12 @@ Synopsis ======== **taler-auditor-dbconfig** -[**-c** *FILENAME* *] +[**-c** *FILENAME*] [**-h**] -[**-n** *NAME* *] +[**-n** *NAME*] [**-r**] [**-s**] -[**-u** *USER* *] +[**-u** *USER*] Description =========== diff --git a/manpages/taler-exchange-dbconfig.1.rst b/manpages/taler-exchange-dbconfig.1.rst @@ -13,12 +13,12 @@ Synopsis ======== **taler-exchange-dbconfig** -[**-c** *FILENAME* *] +[**-c** *FILENAME*] [**-h**] -[**-n** *NAME* *] +[**-n** *NAME*] [**-r**] [**-s**] -[**-u** *USER* *] +[**-u** *USER*] Description =========== diff --git a/manpages/taler-merchant-dbconfig.1.rst b/manpages/taler-merchant-dbconfig.1.rst @@ -13,12 +13,12 @@ Synopsis ======== **taler-merchant-dbconfig** -[**-c** *FILENAME* *] +[**-c** *FILENAME*] [**-h**] -[**-n** *NAME* *] +[**-n** *NAME*] [**-r**] [**-s**] -[**-u** *USER* *] +[**-u** *USER*] Description =========== diff --git a/merchant-db.png b/merchant-db.png Binary files differ. diff --git a/orphaned/README b/orphaned/README @@ -0,0 +1,2 @@ +This document contains documentation that we currently don't link anywhere, +but that we might still want to salvage sometime. diff --git a/taler-mcig.rst b/orphaned/taler-mcig.rst diff --git a/orphaned/taler-nfc-guide.rst b/orphaned/taler-nfc-guide.rst @@ -0,0 +1,285 @@ +GNU Taler NFC Guide +################### + +This guide explains how NFC (near-field communication) is +used in the GNU Taler payment system. + +Introduction +============ + +NFC is currently used for two different purposes: + +1. Operations in the wallet (payment, withdrawal, ...) can be triggered by a + merchant PoS (Point-of-Sale) terminal or Taler-capable ATM. +2. When either the wallet or the merchant do not have Internet connectivity, + the protocol messages to the exchange or merchant backend service can be + tunneled via NFC through the party that has Internet connectivity. + + +Background: Payment Processing with GNU Taler +============================================= + +The following steps show a simple payment process with GNU Taler. Examples are +written in `Bash <https://www.gnu.org/software/bash/>`_ syntax, +using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. +They make use of the :http:post:`[/instances/$INSTANCE]/private/orders` +and :http:get:`[/instances/$INSTANCE]/private/orders` endpoints. + +1. The merchant creates an *order*, which contains the details of the payment + and the product/service that the customer will receive. + An order is identified by an alphanumeric *order ID*. + + The *fulfillment URL* is an URL that the wallet will redirect the customer + to once the payment is complete. For digital products, this is typically an + ``https(s)://`` URL that renders the purchased content. For physical + products and in-store purchases, a ``taler://fulfillment-success/<message>`` + URL should be specified instead. The wallet will display the URL-encoded + UTF-8 text ``<message>`` when the payment has succeeded. + + .. hint:: + + When an ``http(s)://`` URL is used as the fulfillment URL in an in-store / NFC payment, + the user might not be able to view the page, as request tunneling only works for requests + made by the wallet to the merchant backend / exchange. + + In these situations, wallets should display to the user that a page to view the purchase + can be opened, and give a warning if it is detected that the devices does not have Internet + connectivity. + + The following POST ``/private/orders`` request to the merchant backend creates a + simple order: + + .. code-block:: console + + $ backend_base_url=https://backend.demo.taler.net/ + $ auth_header='Authorization: ApiKey sandbox' + $ order_req=$(cat <<EOF + { + "order": { + "summary": "one ice cream", + "amount": "KUDOS:1.5", + "fulfillment_url": + "taler://fulfillment-success/Enjoy+your+ice+cream!" + } + } + EOF + ) + $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/private/orders + { + "order_id": "2019.255-02YDHMXCBQP6J" + } + +2. The merchant checks the payment status of the order using + GET ``/private/orders/$ORDER_ID``: + + .. code-block:: console + + $ backend_base_url=https://backend.demo.taler.net/ + $ auth_header='Authorization: ApiKey sandbox' + $ curl -XGET -H"$auth_header" \ + "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" + # Response: + { + "taler_pay_uri": "taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J", + "paid": false, + # ... (some fields omitted) + } + + As expected, the order is not paid. To actually proceed with the payment, the value of ``taler_pay_uri`` + must be processed by the customer's wallet. There are multiple ways for the wallet to obtain the ``taler://pay/`` URI + + * in a QR code + * in the ``Taler:`` HTTP header of a Web site + * by manually entering it in the command-line wallet + * **via NFC** (explained in this guide) + + The details of ``taler://`` URIs are specified in `LSD 0006 <https://lsd.gnunet.org/lsd0006/>`_. + +3. The wallet processes the ``taler://pay/`` URI. In this example, we use the + command-line wallet: + + .. code-block:: console + + # Withdraw some toy money (KUDOS) from the demo bank + $ taler-wallet-cli test-withdraw \ + -e https://exchange.demo.taler.net/ \ + -b https://bank.demo.taler.net/ \ + -a KUDOS:10 + # Pay for the order from the merchant. + $ taler-wallet-cli pay-uri 'taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J' + # [... User is asked to confirm the payment ...] + + .. hint:: + + The command-line wallet is typically used by developers and not by end-users. + See the :ref:`wallet manual <command-line-wallet>` for installation instructions. + + +4. The merchant checks the payment status again: + + .. code-block:: console + + $ backend_base_url=https://backend.demo.taler.net/ + $ auth_header='Authorization: ApiKey sandbox' + $ curl -XGET -H"$auth_header" \ + "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" + # Response: + { + "paid": true, + # ... (some fields omitted) + } + + .. note:: + + When paying for digital products displayed on a Web site identified by the + fulfillment URL, the merchant only needs to check the payment status + before responding with the fulfillment page. + + For in-store payments, the merchant must periodically check the payment status. + Instead of polling in a busy loop, the ``timeout_ms`` parameter + of GET ``/private/orders/$ORDER_ID`` + should be used. + + +Taler NFC Basics +================ + +The NFC communication in GNU Taler follows the ISO-DEP (`ISO 14443-4 +<https://www.iso.org/standard/73599.html>`_) standard. The wallet always acts +as a tag (or more precisely, emulated card), while the merchant PoS terminal +and bank terminal act as a reader. + +The basic communication unit is the application protocol data unit (`APDU +<https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit>`_), with the structure +and commands defined in `ISO 7816 <https://cardwerk.com/iso-7816-smart-card-standard>`_. + +The GNU Taler wallet uses the AID (application identifier) ``F00054414c4552``. +The ``F`` prefix indicates the proprietary/unregistered namespace of AIDs, and +the rest of the identifier is the hex-encoded ASCII-string ``TALER`` (with one +0-byte left padding). + +During the time that the wallet is paired with a reader, there is state +associated with the communication channel. Most importantly, the first message +sent by the reader to the wallet must be a ``SELECT FILE (=0xA4)`` that selects +the GNU Taler AID. Messages that are sent before the correct ``SELECT FILE`` +message results in implementation-defined behavior, such as the tag disconnecting, +ignoring the message or an app other than the wallet receiving the message. + +The reader sends commands to the wallet with the ``PUT DATA (=0xDA)`` +instruction, using the instruction parameters ``0x0100``, denoting a +proprietary instruction. + +The command data of the ``PUT DATA`` APDU is prefixed by a one-byte Taler +instruction ID (TID). Currently, the following TIDs are used: + +.. list-table:: + :widths: 5 50 + :header-rows: 1 + + * - TID (reader to wallet) + - Description + * - ``0x01`` + - Dereference the UTF-8 encoded ``taler://`` URI in the remainder of the command data. + * - ``0x02`` + - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling response. + + +The ``GET DATA (=0xCA)`` instruction (again with the instruction parameters +``0x0100`` is used to request a command from the wallet. The APDU with this +instruction must be sent with a ``0x0000`` trailer to indicate that up to 65536 +bytes of data are expected in the response from the wallet. Note that the +wallet itself cannot initiate communication, and thus the reader must "poll" +the wallet for commands. + +The response to the ``GET DATA`` instruction has a Taler instruction ID in the +first byte. The rest of the +body is interpreted depending on the TID. + +.. list-table:: + :widths: 15 50 + :header-rows: 1 + + * - TID + (wallet to reader) + - Description + * - ``0x03`` + - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling request. + + +Sending taler:// URIs to the Wallet via NFC +=========================================== + +To make the wallet process a ``taler://`` URI via NFC, the merchant PoS +terminal sends a ``SELECT FILE`` command with the GNU Taler AID, and a ``PUT +DATA`` command with TID ``0x01`` and the URI in the rest +of the command data. + +Here is an example protocol trace from an interaction which caused the wallet +to dereference the ``taler://pay`` URI from the example above: + +.. code-block:: none + + # SELECT FILE + m->w 00A4040007F00054414c4552 + # success response with no data + m<-w 9000 + + # PUT DATA (TID=0x01) + m->w 00DA01007c0174616c65723a2f2f7061792f6261636b656e642e64656d6f2e74 + 616c65722e6e65742f2d2f2d2f323031392e3235352d30325944484d58434251 + 50364a + # success response with no data + m<-w 9000 + +(Note that this process works analogously for communication between a bank/ATM +terminal or "reward provider".) + + +Request tunneling +================= + +Request tunneling allows tunneling a (very) restricted subset of HTTP through +NFC. In particular, only JSON request and response bodies are allowed. + +It is currently assumed that the requests and responses fit into one APDU frame. +For devices with more limited maximum APDU sizes, additional TIDs for segmented +tunnel requests/responses may be defined in the future. + +A request for tunneling is initiated with TID ``0x03`` and responded to with +TID ``0x02`` (see tables above). A tunneling request is identified by a +numeric ID, which must be unique during one pairing between reader and tag. + +The request tunneling request/response JSON messages have the following schema: + +.. code-block:: tsref + + interface TalerRequestTunnelRequest { + // Identifier for the request + id: number; + + // Request URL + url: string; + + // HTTP method to use + method: "post" | "get"; + + // Request headers + headers?: { [name: string]: string }; + + // JSON body for the request, only applicable to POST requests + body?: object; + } + + interface TalerRequestTunnelResponse { + // Identifier for the request + id: number; + + // Response HTTP status code, + // "0" if there was no response. + status: number; + + // JSON body of the response, or undefined + // if the response wasn't JSON. + // May contain error details if 'status==0' + body?: object; + } diff --git a/replication.png b/replication.png Binary files differ. diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst @@ -582,7 +582,7 @@ The next key step for the auditor is to configure replication of the *exchange*'s database in-house. This should be performed in two steps as illustrated in the following figure: -.. image:: replication.png +.. image:: images/replication.png First, the exchange should use standard PostgreSQL replication features to enable the auditor to obtain a full copy of the exchange's database. @@ -968,7 +968,7 @@ The auditor's database The database scheme used by the exchange looks as follows: -.. image:: auditor-db.png +.. image:: images/auditor-db.png Invariants checked by the auditor diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst @@ -91,6 +91,7 @@ headers and libraries! .. include:: frags/installing-taler-exchange.rst + .. include:: frags/installing-challenger.rst .. include:: frags/install-before-check.rst diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst @@ -24,6 +24,7 @@ Developer's Manual checklist-release checklist-demo-upgrade + python-guidelines .. note:: diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst @@ -2151,7 +2151,7 @@ allowing administrators to purge records that are no longer required. The database scheme used by the exchange looks as follows: -.. image:: exchange-db.png +.. image:: images/exchange-db.png .. _Database-upgrades: diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst @@ -98,7 +98,7 @@ components: The following image illustrates the various interactions of these key components: -.. image:: arch-api.png +.. image:: images/arch-api.png The backend provides the cryptographic protocol support, stores Taler-specific financial information and communicates with the GNU Taler diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst @@ -102,7 +102,7 @@ The Taler software stack for a merchant consists of four main components: The following image illustrates the various interactions of these key components: -.. image:: arch-api.png +.. image:: images/arch-api.png .. index:: RESTful @@ -1034,7 +1034,7 @@ allowing administrators to purge records that are no longer required. The database scheme used by the merchant looks as follows: -.. image:: merchant-db.png +.. image:: images/merchant-db.png .. _MerchantBenchmarking: diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst @@ -1,285 +0,0 @@ -GNU Taler NFC Guide -################### - -This guide explains how NFC (near-field communication) is -used in the GNU Taler payment system. - -Introduction -============ - -NFC is currently used for two different purposes: - -1. Operations in the wallet (payment, withdrawal, ...) can be triggered by a - merchant PoS (Point-of-Sale) terminal or Taler-capable ATM. -2. When either the wallet or the merchant do not have Internet connectivity, - the protocol messages to the exchange or merchant backend service can be - tunneled via NFC through the party that has Internet connectivity. - - -Background: Payment Processing with GNU Taler -============================================= - -The following steps show a simple payment process with GNU Taler. Examples are -written in `Bash <https://www.gnu.org/software/bash/>`_ syntax, -using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. -They make use of the :http:post:`[/instances/$INSTANCE]/private/orders` -and :http:get:`[/instances/$INSTANCE]/private/orders` endpoints. - -1. The merchant creates an *order*, which contains the details of the payment - and the product/service that the customer will receive. - An order is identified by an alphanumeric *order ID*. - - The *fulfillment URL* is an URL that the wallet will redirect the customer - to once the payment is complete. For digital products, this is typically an - ``https(s)://`` URL that renders the purchased content. For physical - products and in-store purchases, a ``taler://fulfillment-success/<message>`` - URL should be specified instead. The wallet will display the URL-encoded - UTF-8 text ``<message>`` when the payment has succeeded. - - .. hint:: - - When an ``http(s)://`` URL is used as the fulfillment URL in an in-store / NFC payment, - the user might not be able to view the page, as request tunneling only works for requests - made by the wallet to the merchant backend / exchange. - - In these situations, wallets should display to the user that a page to view the purchase - can be opened, and give a warning if it is detected that the devices does not have Internet - connectivity. - - The following POST ``/private/orders`` request to the merchant backend creates a - simple order: - - .. code-block:: console - - $ backend_base_url=https://backend.demo.taler.net/ - $ auth_header='Authorization: ApiKey sandbox' - $ order_req=$(cat <<EOF - { - "order": { - "summary": "one ice cream", - "amount": "KUDOS:1.5", - "fulfillment_url": - "taler://fulfillment-success/Enjoy+your+ice+cream!" - } - } - EOF - ) - $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/private/orders - { - "order_id": "2019.255-02YDHMXCBQP6J" - } - -2. The merchant checks the payment status of the order using - GET ``/private/orders/$ORDER_ID``: - - .. code-block:: console - - $ backend_base_url=https://backend.demo.taler.net/ - $ auth_header='Authorization: ApiKey sandbox' - $ curl -XGET -H"$auth_header" \ - "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" - # Response: - { - "taler_pay_uri": "taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J", - "paid": false, - # ... (some fields omitted) - } - - As expected, the order is not paid. To actually proceed with the payment, the value of ``taler_pay_uri`` - must be processed by the customer's wallet. There are multiple ways for the wallet to obtain the ``taler://pay/`` URI - - * in a QR code - * in the ``Taler:`` HTTP header of a Web site - * by manually entering it in the command-line wallet - * **via NFC** (explained in this guide) - - The details of ``taler://`` URIs are specified in :ref:`LSD 0006 <https://lsd.gnunet.org/lsd0006/>`_. - -3. The wallet processes the ``taler://pay/`` URI. In this example, we use the - command-line wallet: - - .. code-block:: console - - # Withdraw some toy money (KUDOS) from the demo bank - $ taler-wallet-cli test-withdraw \ - -e https://exchange.demo.taler.net/ \ - -b https://bank.demo.taler.net/ \ - -a KUDOS:10 - # Pay for the order from the merchant. - $ taler-wallet-cli pay-uri 'taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J' - # [... User is asked to confirm the payment ...] - - .. hint:: - - The command-line wallet is typically used by developers and not by end-users. - See the :ref:`wallet manual <command-line-wallet>` for installation instructions. - - -4. The merchant checks the payment status again: - - .. code-block:: console - - $ backend_base_url=https://backend.demo.taler.net/ - $ auth_header='Authorization: ApiKey sandbox' - $ curl -XGET -H"$auth_header" \ - "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" - # Response: - { - "paid": true, - # ... (some fields omitted) - } - - .. note:: - - When paying for digital products displayed on a Web site identified by the - fulfillment URL, the merchant only needs to check the payment status - before responding with the fulfillment page. - - For in-store payments, the merchant must periodically check the payment status. - Instead of polling in a busy loop, the ``timeout_ms`` parameter - of GET ``/private/orders/$ORDER_ID`` - should be used. - - -Taler NFC Basics -================ - -The NFC communication in GNU Taler follows the ISO-DEP (`ISO 14443-4 -<https://www.iso.org/standard/73599.html>`_) standard. The wallet always acts -as a tag (or more precisely, emulated card), while the merchant PoS terminal -and bank terminal act as a reader. - -The basic communication unit is the application protocol data unit (`APDU -<https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit>`_), with the structure -and commands defined in `ISO 7816 <https://cardwerk.com/iso-7816-smart-card-standard>`_. - -The GNU Taler wallet uses the AID (application identifier) ``F00054414c4552``. -The ``F`` prefix indicates the proprietary/unregistered namespace of AIDs, and -the rest of the identifier is the hex-encoded ASCII-string ``TALER`` (with one -0-byte left padding). - -During the time that the wallet is paired with a reader, there is state -associated with the communication channel. Most importantly, the first message -sent by the reader to the wallet must be a ``SELECT FILE (=0xA4)`` that selects -the GNU Taler AID. Messages that are sent before the correct ``SELECT FILE`` -message results in implementation-defined behavior, such as the tag disconnecting, -ignoring the message or an app other than the wallet receiving the message. - -The reader sends commands to the wallet with the ``PUT DATA (=0xDA)`` -instruction, using the instruction parameters ``0x0100``, denoting a -proprietary instruction. - -The command data of the ``PUT DATA`` APDU is prefixed by a one-byte Taler -instruction ID (TID). Currently, the following TIDs are used: - -.. list-table:: - :widths: 5 50 - :header-rows: 1 - - * - TID (reader to wallet) - - Description - * - ``0x01`` - - Dereference the UTF-8 encoded ``taler://`` URI in the remainder of the command data. - * - ``0x02`` - - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling response. - - -The ``GET DATA (=0xCA)`` instruction (again with the instruction parameters -``0x0100`` is used to request a command from the wallet. The APDU with this -instruction must be sent with a ``0x0000`` trailer to indicate that up to 65536 -bytes of data are expected in the response from the wallet. Note that the -wallet itself cannot initiate communication, and thus the reader must "poll" -the wallet for commands. - -The response to the ``GET DATA`` instruction has a Taler instruction ID in the -first byte. The rest of the -body is interpreted depending on the TID. - -.. list-table:: - :widths: 15 50 - :header-rows: 1 - - * - TID - (wallet to reader) - - Description - * - ``0x03`` - - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling request. - - -Sending taler:// URIs to the Wallet via NFC -=========================================== - -To make the wallet process a ``taler://`` URI via NFC, the merchant PoS -terminal sends a ``SELECT FILE`` command with the GNU Taler AID, and a ``PUT -DATA`` command with TID ``0x01`` and the URI in the rest -of the command data. - -Here is an example protocol trace from an interaction which caused the wallet -to dereference the ``taler://pay`` URI from the example above: - -.. code-block:: none - - # SELECT FILE - m->w 00A4040007F00054414c4552 - # success response with no data - m<-w 9000 - - # PUT DATA (TID=0x01) - m->w 00DA01007c0174616c65723a2f2f7061792f6261636b656e642e64656d6f2e74 - 616c65722e6e65742f2d2f2d2f323031392e3235352d30325944484d58434251 - 50364a - # success response with no data - m<-w 9000 - -(Note that this process works analogously for communication between a bank/ATM -terminal or "reward provider".) - - -Request tunneling -================= - -Request tunneling allows tunneling a (very) restricted subset of HTTP through -NFC. In particular, only JSON request and response bodies are allowed. - -It is currently assumed that the requests and responses fit into one APDU frame. -For devices with more limited maximum APDU sizes, additional TIDs for segmented -tunnel requests/responses may be defined in the future. - -A request for tunneling is initiated with TID ``0x03`` and responded to with -TID ``0x02`` (see tables above). A tunneling request is identified by a -numeric ID, which must be unique during one pairing between reader and tag. - -The request tunneling request/response JSON messages have the following schema: - -.. code-block:: tsref - - interface TalerRequestTunnelRequest { - // Identifier for the request - id: number; - - // Request URL - url: string; - - // HTTP method to use - method: "post" | "get"; - - // Request headers - headers?: { [name: string]: string }; - - // JSON body for the request, only applicable to POST requests - body?: object; - } - - interface TalerRequestTunnelResponse { - // Identifier for the request - id: number; - - // Response HTTP status code, - // "0" if there was no response. - status: number; - - // JSON body of the response, or undefined - // if the response wasn't JSON. - // May contain error details if 'status==0' - body?: object; - } diff --git a/taler-user-guide.rst b/taler-user-guide.rst @@ -299,7 +299,7 @@ on the triggering event, the templates will be expanded with event-specific data. Pay events -^^^^^^^^^^ +---------- For "pay" events, the backend will provide the following information to the Mustach templating engine: @@ -309,7 +309,7 @@ information to the Mustach templating engine: Refund events -^^^^^^^^^^^^^ +------------- For "refund" events, the backend will provide the following information to the Mustach templating engine: @@ -323,8 +323,6 @@ Mustach templating engine: this information to the consumer - - .. _Rewarding-visitors: Rewarding visitors
