diff options
Diffstat (limited to 'core/api-common.rst')
| -rw-r--r-- | core/api-common.rst | 93 |
1 files changed, 91 insertions, 2 deletions
diff --git a/core/api-common.rst b/core/api-common.rst index 44d4eb00..987ba664 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -121,6 +121,61 @@ handle the error as if an internal error (500) had been returned. type_actual?: string; } +----------------------- +Protocol Version Ranges +----------------------- + +Some of the Taler services (e.g. exchange, merchant, bank integration API) +expose the range of API versions they support. Clients in turn have an API +version range they support. These version ranges are written down in the +`libtool version format <https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html>`__. + +A protocol version is a positive, non-zero integer. A protocol version range consists of three components: + +1. The ``current`` version. This is the latest version of the protocol supported by the client or service. +2. The ``revision`` number. This value should usually not be interpreted by the client/server, but serves + purely as a comment. Each time a service/client for a protocol is updated while supporting the same + set of protocol versions, the revision should be increased. + In rare cases, the revision number can be used to work around unintended breakage in deployed + versions of a service. This is discouraged and should only be used in exceptional situations. +3. The ``age`` number. This non-zero integer identifies with how many previous protocol versions this + implementation is compatible. An ``age`` of 0 implies that the implementation only supports + the ``current`` protocol version. The ``age`` must be less or equal than the ``current`` protocol version. + +To avoid confusion with semantic versions, the protocol version range is written down in the following format: + +.. code:: none + + current[:revision[:age]] + +The angle brackets mark optional components. If either ``revision`` or ``age`` are omitted, they default to 0. + +Examples: + +* "1" and "1" are compatible +* "1" and "2" are **incompatible** +* "2:0:1" and "1:0:0" are compatible +* "2:5:1" and "1:10:0" are compatible +* "4:0:1" and "2:0:0" are **incompatible** +* "4:0:1" and "3:0:0" are compatible + +.. note:: + + `Semantic versions <https://semver.org/>`__ are not a good tool for this job, as we concisely want to express + that the client/server supports the last ``n`` versions of the protocol. + Semantic versions don't support this, and semantic version ranges are too complex for this. + +.. warning:: + + A client doesn't have one single protocol version range. Instead, it has + a protocol version range for each type of service it talks to. + +.. warning:: + + For privacy reasons, the protocol version range of a client should not be + sent to the service. Instead, the client should just use the two version ranges + to decide whether it will talk to the service. + .. _encodings-ref: @@ -212,6 +267,14 @@ Integers // JavaScript numbers restricted to integers type Integer = number; +Objects +^^^^^^^ + +.. ts:def:: Object + + // JavaScript objects, no further restrictions + type Object = object; + Keys ^^^^ @@ -494,10 +557,24 @@ uses 512-bit hash codes (64 bytes). uint8_t eddsa_priv[32]; }; - struct TALER_MasterSignatureP { + struct TALER_MasterSignatureP { uint8_t eddsa_signature[64]; }; +.. _WireTransferIdentifierRawP: +.. sourcecode:: c + + struct WireTransferIdentifierRawP { + uint8_t raw[32]; + }; + +.. _UUID: +.. sourcecode:: c + + struct UUID { + uint32_t value[4]; + }; + .. _eddsa-coin-pub: .. sourcecode:: c @@ -595,6 +672,7 @@ within the struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct GNUNET_HashCode h_contract_terms; struct GNUNET_HashCode h_wire; + struct GNUNET_HashCode h_denom_pub; struct GNUNET_TIME_AbsoluteNBO timestamp; struct GNUNET_TIME_AbsoluteNBO refund_deadline; struct TALER_AmountNBO amount_with_fee; @@ -634,6 +712,7 @@ within the */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct GNUNET_HashCode session_hash; + struct GNUNET_HashCode h_denom_pub; struct TALER_AmountNBO amount_with_fee; struct TALER_AmountNBO melt_fee; union TALER_CoinSpendPublicKeyP coin_pub; @@ -881,7 +960,17 @@ within the .. _TALER_RecoupRefreshConfirmationPS: .. sourcecode:: c - // FIXME: put definition here + struct TALER_RecoupRefreshConfirmationPS { + + /** + * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_AbsoluteNBO timestamp; + struct TALER_AmountNBO recoup_amount; + struct TALER_CoinSpendPublicKeyP coin_pub; + struct TALER_CoinSpendPublicKeyP old_coin_pub; + }; .. _TALER_RecoupConfirmationPS: .. sourcecode:: c |