commit a48df8856b92669652bfad5e3369394d86a18a27
parent 0a83018da4c8f59c2c2f8d532f97b43cdf28bb14
Author: Mikolai Gütschow <mikolai.guetschow@tu-dresden.de>
Date: Tue, 12 May 2026 18:24:36 +0200
protocol: add introductory text
Diffstat:
2 files changed, 772 insertions(+), 652 deletions(-)
diff --git a/draft-guetschow-taler-protocol.md b/draft-guetschow-taler-protocol.md
@@ -57,7 +57,7 @@ Use at your own risk!
# Notation
-- `"abc"` denotes the literal string `abc` encoded as ASCII [RFC20]
+- `"abc"` denotes the literal string `abc` encoded as ASCII [RFC20], without trailing '\0' character.
- `a | b` denotes the concatenation of a with b
- `len(a)` denotes the length in bytes of the byte string a
- `padZero(y, a)` denotes the byte string a, zero-padded to the length of y bytes
@@ -211,7 +211,7 @@ do until OKM < N:
## Non-Blind Signatures
-### Ed25519
+### Ed25519 {#ed25519}
Taler uses EdDSA instantiated with curve25519 as Ed25519,
as defined in Section 5.1 of [RFC8032].
@@ -494,7 +494,7 @@ exp = sig ** pubkey.e (mod pubkey.N)
out = (data == exp)
~~~
-### Clause-Schnorr
+### Clause-Schnorr {#cbs}
# Datatypes and Notation
@@ -572,9 +572,60 @@ Check-Subtract(value, subtrahend) =
# The Taler Crypto Protocol {#protocol}
-// todo: briefly introduce the three components wallet, exchange, merchant; maybe with ASCII diagram version
-
-// todo: capitalize wallet, exchange, merchant?
+The Taler payment protocol is a token-based _e-cash_ system
+which ensures anonymity for payers (much like physical cash),
+while guaranteing income transparency on the payees' side (much like most digital payment systems).
+Contrary to what the name might suggest,
+Taler neither is a separate currency (as cryptocurrencies do)
+nor is it tied to a specific currency.
+Instead, the payment system operator offering the Taler payment protocol
+can freely choose the assets backing the payment system.
+
+The basic system consists of three types of entities:
+
+1. The Taler _exchange_ is run by the payment system operator.
+It is the central, trusted entity which hands out e-cash and holds the corresponding value.
+2. A Taler _wallet_ manages e-cash in self-custody for end users.
+3. A Taler _merchant_ can redeem e-cash at the exchange
+after the wallet authorized a deposit permission during a payment.
+
+E-cash in Taler is represented as digital tokens called _coins_.
+They are public-private keypairs where ownership of the coin
+is equivalent to the knowledge of the private key `coin.priv`.
+Every coin has an initial value corresponding to a denomination (`denom`) offered by the exchange.
+The validity of coins is signaled by the presence of
+a valid denomination signature `coin.sig` on the (hash of the) public key `coin.pub`.
+To ensure payer anonymity, the exchange generates `coin.sig` without learning the actual (hash of) `coin.pub`
+using a _blind_ signature scheme.
+
+Wallets obtain coins from the exchange during _withdrawal_ (cf. {{withdraw}})
+and use them during _payment_ at merchants, who in turn _deposit_ them at the exchange (cf. {{payment}}).
+Residual value on partly spent coins can be _refreshed_ by the wallet subsequently in order to obtain unlinkable change (cf. {{refresh}}).
+Taler also supports receiving e-cash in a wallet without acting as a merchant using _wallet-to-wallet payments_ (W2W, cf. {{w2w}}),
+which are always handled via the exchange.
+
+Honest operation of the exchange can be optionally supervised by an independant third-party Taler _auditor_.
+This supervision is not part of the basic Taler protocol and thus not part of this document.
+
+~~~
+ - exchange -
+ / \
+ Withdrawal / \ Deposit
+ Refresh / W2W \
+ / \
+ wallet ----------- merchant
+ Payment
+~~~
+
+// todo: capitalize wallet, exchange, merchant everywhere?
+
+In the default configuration, Taler uses RSA-FDH (cf. {{rsa-fdh}}) for (blind) denomination signatures
+and Ed25519 (cf. {{ed25519}}) signatures everywhere else.
+Clause-Schnorr Signatures (cf. {{cbs}}) provide an alternative blind signature scheme operating on Elliptic Curves.
+As their usage is still experimental, they are not described as part of this document.
+
+Taler has optional support for age-restricted coins, enabling privacy-preserving age restriction.
+As an optional feature, it is not part of the basic Taler protocol and thus left out of the description in this document.
## Obtaining E-Cash
@@ -637,8 +688,6 @@ together with an integer index.
This is strictly speaking an implementation detail since the seed is never revealed to any other party,
and might be chosen to be implemented differently.
-// todo: blind_secret/coin.priv differently generated in TALER_EXCHANGE_post_withdraw_start/prepare_coins, double check with wallet-core (probably implementation detail here)
-
~~~ pseudocode
(W2) coin generation and blinding (wallet)
@@ -712,6 +761,8 @@ The payment is complete as soon as the merchant successfully redeems the deposit
Deposit could also be used directly by a wallet with its own payto and a minimal contract.
+// todo: should we integrate payment templates here?
+
~~~
wallet merchant exchange
Knows ⟨coinᵢ⟩ Knows merchant.priv Knows exchange.priv
@@ -778,7 +829,7 @@ where (without age restriction, policy and wallet data hash)
(M1) order generation (merchant)
wire_salt = random(128)
-determine id, price, info, token?
+determine price, and ASCII strings id, info, token?
Persist order = (id, price, info, token?, wire_salt)
~~~
@@ -978,7 +1029,7 @@ h_contract = SHA-512(canonicalJSON(contract))
Check h_contract known and refund possible
time = now()
⟨coinᵢ⟩ = Lookup by h_contract
-id = ?
+id = uint32(random(32))
for i in 0..n:
denomᵢ = Lookup by coinᵢ.h_denom
valueᵢ = refund amount // todo: split wisely
@@ -1006,7 +1057,7 @@ for i in 0..n:
Check valueᵢ >= denomᵢ.fee_refund
remove/update scheduled wire transfer
mark coin part as unspent
- msgᵢ = Gen-Msg(MERCHANT_REFUND_OK, SHA-512(order.id)) // todo: hashing string without terminating \0
+ msgᵢ = Gen-Msg(MERCHANT_REFUND_OK, SHA-512(order.id))
sigᵢ = Ed25519-Sign(exchange.priv, msgᵢ)
~~~
@@ -1019,7 +1070,7 @@ for i in 0..n:
(M2) refund confirmation (merchant)
for i in 0..n:
- msgᵢ = Gen-Msg(MERCHANT_REFUND_OK, SHA-512(order.id)) // todo: hashing string without terminating \0
+ msgᵢ = Gen-Msg(MERCHANT_REFUND_OK, SHA-512(order.id))
Check Ed25519-Verify(exchange.pub, msgᵢ, sigᵢ)
update business logic
refundᵢ = (valueᵢ, sigᵢ, id, coinᵢ.pub, time)
@@ -1126,7 +1177,6 @@ where (for RSA, without age-restriction)
// see TALER_EXCHANGE_get_melt_data
⟨batch_seedₖ⟩ // see TALER_refresh_expand_seed_to_kappa_batch_seeds
⟨transferₖᵢ.priv⟩ // see TALER_refresh_expand_batch_seed_to_transfer_data
-// todo: pretty sure ECDH-GetPub and Ed25519-GetPub are equivalent, if not, transferₖᵢ.pub needs to change
h_planchetₖᵢ // see TALER_coin_ev_hash
h_planchetsₖ // see TALER_wallet_blinded_planchet_details_hash
commitment // see TALER_refresh_get_commitment
diff --git a/draft-guetschow-taler-protocol.xml b/draft-guetschow-taler-protocol.xml
@@ -24,7 +24,7 @@
<email>mikolai.guetschow@tu-dresden.de</email>
</address>
</author>
- <date year="2026" month="May" day="11"/>
+ <date year="2026" month="May" day="12"/>
<workgroup>independent</workgroup>
<keyword>taler</keyword>
<keyword>cryptography</keyword>
@@ -49,7 +49,7 @@ Use at your own risk!</t>
<name>Notation</name>
<ul spacing="normal">
<li>
- <t><tt>"abc"</tt> denotes the literal string <tt>abc</tt> encoded as ASCII <xref target="RFC20"/></t>
+ <t><tt>"abc"</tt> denotes the literal string <tt>abc</tt> encoded as ASCII <xref target="RFC20"/>, without trailing '\0' character.</t>
</li>
<li>
<t><tt>a | b</tt> denotes the concatenation of a with b</t>
@@ -459,7 +459,7 @@ out = (data == exp)
]]></artwork>
</section>
</section>
- <section anchor="clause-schnorr">
+ <section anchor="cbs">
<name>Clause-Schnorr</name>
</section>
</section>
@@ -547,8 +547,58 @@ Check-Subtract(value, subtrahend) =
</section>
<section anchor="protocol">
<name>The Taler Crypto Protocol</name>
- <t>// todo: briefly introduce the three components wallet, exchange, merchant; maybe with ASCII diagram version</t>
- <t>// todo: capitalize wallet, exchange, merchant?</t>
+ <t>The Taler payment protocol is a token-based <em>e-cash</em> system
+which ensures anonymity for payers (much like physical cash),
+while guaranteing income transparency on the payees' side (much like most digital payment systems).
+Contrary to what the name might suggest,
+Taler neither is a separate currency (as cryptocurrencies do)
+nor is it tied to a specific currency.
+Instead, the payment system operator offering the Taler payment protocol
+can freely choose the assets backing the payment system.</t>
+ <t>The basic system consists of three types of entities:</t>
+ <ol spacing="normal" type="1"><li>
+ <t>The Taler <em>exchange</em> is run by the payment system operator.
+It is the central, trusted entity which hands out e-cash and holds the corresponding value.</t>
+ </li>
+ <li>
+ <t>A Taler <em>wallet</em> manages e-cash in self-custody for end users.</t>
+ </li>
+ <li>
+ <t>A Taler <em>merchant</em> can redeem e-cash at the exchange
+after the wallet authorized a deposit permission during a payment.</t>
+ </li>
+ </ol>
+ <t>E-cash in Taler is represented as digital tokens called <em>coins</em>.
+They are public-private keypairs where ownership of the coin
+is equivalent to the knowledge of the private key <tt>coin.priv</tt>.
+Every coin has an initial value corresponding to a denomination (<tt>denom</tt>) offered by the exchange.
+The validity of coins is signaled by the presence of
+a valid denomination signature <tt>coin.sig</tt> on the (hash of the) public key <tt>coin.pub</tt>.
+To ensure payer anonymity, the exchange generates <tt>coin.sig</tt> without learning the actual (hash of) <tt>coin.pub</tt>
+using a <em>blind</em> signature scheme.</t>
+ <t>Wallets obtain coins from the exchange during <em>withdrawal</em> (cf. <xref target="withdraw"/>)
+and use them during <em>payment</em> at merchants, who in turn <em>deposit</em> them at the exchange (cf. <xref target="payment"/>).
+Residual value on partly spent coins can be <em>refreshed</em> by the wallet subsequently in order to obtain unlinkable change (cf. <xref target="refresh"/>).
+Taler also supports receiving e-cash in a wallet without acting as a merchant using <em>wallet-to-wallet payments</em> (W2W, cf. <xref target="w2w"/>),
+which are always handled via the exchange.</t>
+ <t>Honest operation of the exchange can be optionally supervised by an independant third-party Taler <em>auditor</em>.
+This supervision is not part of the basic Taler protocol and thus not part of this document.</t>
+ <artwork><![CDATA[
+ - exchange -
+ / \
+ Withdrawal / \ Deposit
+ Refresh / W2W \
+ / \
+ wallet ----------- merchant
+ Payment
+]]></artwork>
+ <t>// todo: capitalize wallet, exchange, merchant everywhere?</t>
+ <t>In the default configuration, Taler uses RSA-FDH (cf. <xref target="rsa-fdh"/>) for (blind) denomination signatures
+and Ed25519 (cf. <xref target="ed25519"/>) signatures everywhere else.
+Clause-Schnorr Signatures (cf. <xref target="cbs"/>) provide an alternative blind signature scheme operating on Elliptic Curves.
+As their usage is still experimental, they are not described as part of this document.</t>
+ <t>Taler has optional support for age-restricted coins, enabling privacy-preserving age restriction.
+As an optional feature, it is not part of the basic Taler protocol and thus left out of the description in this document.</t>
<section anchor="obtaining-e-cash">
<name>Obtaining E-Cash</name>
<section anchor="withdraw">
@@ -603,7 +653,6 @@ Persist (reserve, value)
together with an integer index.
This is strictly speaking an implementation detail since the seed is never revealed to any other party,
and might be chosen to be implemented differently.</t>
- <t>// todo: blind_secret/coin.priv differently generated in TALER_EXCHANGE_post_withdraw_start/prepare_coins, double check with wallet-core (probably implementation detail here)</t>
<sourcecode type="pseudocode"><![CDATA[
(W2) coin generation and blinding (wallet)
@@ -674,6 +723,7 @@ Payment of the order is prepared by signing (partial) deposit authorizations <tt
where the sum of all contributions (<tt>contributionᵢ <= denomᵢ.value</tt>) must match the <tt>contract.price</tt> plus potential deposit fees.
The payment is complete as soon as the merchant successfully redeems the deposit authorizations at the exchange.</t>
<t>Deposit could also be used directly by a wallet with its own payto and a minimal contract.</t>
+ <t>// todo: should we integrate payment templates here?</t>
<artwork><![CDATA[
wallet merchant exchange
Knows ⟨coinᵢ⟩ Knows merchant.priv Knows exchange.priv
@@ -738,7 +788,7 @@ Knows ⟨coinᵢ⟩ Knows merchant.priv Knows exchange.
(M1) order generation (merchant)
wire_salt = random(128)
-determine id, price, info, token?
+determine price, and ASCII strings id, info, token?
Persist order = (id, price, info, token?, wire_salt)
]]></sourcecode>
<sourcecode type="pseudocode"><![CDATA[
@@ -913,7 +963,7 @@ h_contract = SHA-512(canonicalJSON(contract))
Check h_contract known and refund possible
time = now()
⟨coinᵢ⟩ = Lookup by h_contract
-id = ?
+id = uint32(random(32))
for i in 0..n:
denomᵢ = Lookup by coinᵢ.h_denom
valueᵢ = refund amount // todo: split wisely
@@ -935,14 +985,14 @@ for i in 0..n:
Check valueᵢ >= denomᵢ.fee_refund
remove/update scheduled wire transfer
mark coin part as unspent
- msgᵢ = Gen-Msg(MERCHANT_REFUND_OK, SHA-512(order.id)) // todo: hashing string without terminating \0
+ msgᵢ = Gen-Msg(MERCHANT_REFUND_OK, SHA-512(order.id))
sigᵢ = Ed25519-Sign(exchange.priv, msgᵢ)
]]></sourcecode>
<sourcecode type="pseudocode"><