From 34063b822bd5f9c48ce11770907c7004784fe9c4 Mon Sep 17 00:00:00 2001
From: Özgür Kesim <oec@codeblau.de>
Date: Thu, 14 Oct 2021 11:46:34 +0200
Subject: Added design doc 006: extensions

---
 design-documents/006-extensions.rst | 135 ++++++++++++++++++++++++++++++++++++
 design-documents/index.rst          |   1 +
 2 files changed, 136 insertions(+)
 create mode 100644 design-documents/006-extensions.rst

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
-- 
cgit v1.2.3