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.