summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--design-documents/006-extensions.rst135
-rw-r--r--design-documents/index.rst1
2 files changed, 136 insertions, 0 deletions
diff --git a/design-documents/006-extensions.rst b/design-documents/006-extensions.rst
new file mode 100644
index 00000000..e663b2f5
--- /dev/null
+++ b/design-documents/006-extensions.rst
@@ -0,0 +1,135 @@
+Design Document 006: Extensions for GNU Taler
+#############################################
+
+Summary
+=======
+
+This design document describes a generic framework for how extensions (i.e.
+optional features) to GNU Taler can be offered and used by the exchange,
+merchants and wallets.
+
+Motivation
+==========
+
+GNU Taler's list of supported features evolves over time. For example, the
+following features are going to be designed and implemented during the course
+of 2021 and 2022:
+
+* Peer-to-peer payments
+* Anonymous age-restriction
+* Escrow service for anonymous auctions
+
+We call a feature an *extension* when it is *optional* for either the
+exchange, wallet or merchant to enable and support it. (However, enabling
+a feature might *require* the other parties to support the feature, too)
+
+For optional features we therefore need a mechanism to express the
+availability, version and configuration of a particular feature, f.e. p2p or
+age-restriction offered by an exchange, and make it verifiable by the other
+participants.
+
+Requirements
+============
+
+TODO. Not sure if we have any requirements - other than particular
+ideas/designs for extensions?
+
+
+Proposed Solution
+=================
+
+Exchange
+^^^^^^^^
+
+The exchange will add two new REQUIRED fields in response to ``/keys``:
+
+#. The (but maybe empty) field ``extensions`` which contains a dictionary of
+ extension-names and their configuration, see below.
+
+#. The field ``extensions_sig`` that contains the EdDSA signature of the SHA256-hash
+ of the normalized JSON-string of the ``extenstions`` object.
+
+The names of extensions MUST be unique and SHOULD include a version information
+in Taler's `protocol version ranges notation`_ as suffix starting with letter
+'``v``', f.e.: ``age_restriction.v1`` or ``p2p.v1:2:3``.
+
+.. _protocol version ranges notation: https://docs.taler.net/core/api-common.html#protocol-version-ranges
+
+
+The necessary changes to ``ExchangeKeysResponse`` are highlighted here:
+
+.. ts:def:: ExchangeKeysResponse
+
+ interface ExchangeKeysResponse {
+ //...
+
+ // Required (but maybe emtpy) field with a dictionary of (name, object)
+ // pairs defining the supported extensions.
+ // The name MUST be unique and SHOULD include version information in Taler's
+ // protocol version ranges notation as suffix, starting with letter 'v',
+ // f.e.: "age_restriction.v1" or "p2p.v1:2:3".
+ extensions: { name: Extension };
+
+ // Signature by the exchange master key of the SHA-512 hash of the
+ // normalized JSON-object of field ``extenstions``.
+ // The signature MUST have purpose ``TALER_SIGNATURE_MASTER_EXTENSIONS``.
+ extensions_sig: EddsaSignature;
+
+ //...
+ }
+
+
+The definition of ``Extension`` object itself is mostly up to the particular
+feature. However, it MUST contain the following fields:
+
+* ``description`` ― a short description of the feature itself. Can be used by wallets to display information about the feature to the customer.
+
+* ``required`` ― a boolean that indicates if this feature MUST be supported by the wallets and/or merchants in order to use this exchange.
+
+.. ts:def:: Extension
+
+ interface Extension {
+ // Short description of the feature.
+ description: string;
+
+ // Set to ``true`` if this extension MUST be supported by wallets and/or
+ // merchants.
+ required: boolean;
+
+ // Additional fields defined by the feature itself
+ ...
+
+ }
+
+
+**TODO**:
+
+* Add examples for age-restriction and p2p.
+
+Merchant
+^^^^^^^^
+
+TODO:
+
+* Needs to express support for particular extensions, too. F.e. age-restriction.
+
+Alternatives
+============
+
+TODO. None yet.
+
+
+Drawbacks
+=========
+
+* We do not offer (yet) any lifetime cycle of a feature, that is: There are
+ only two states that a feature can be in: "available" or "not-available".
+
+* The existing design for peer-to-peer payments must be adapted to this.
+
+Discussion / Q&A
+================
+
+The initial ideas presented here are based on discussions between Özgür Kesim
+and Christian Grothoff.
+
diff --git a/design-documents/index.rst b/design-documents/index.rst
index e5cd09e6..7de0d2ea 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -14,6 +14,7 @@ and protocol.
003-tos-rendering
004-wallet-withdrawal-flow
005-wallet-backup-sync
+ 006-extensions
007-payment
008-fees
009-backup