commit 3167a1b8dae9ac4482988b3b417607b6ae88c0bc
parent d583c80f1297c34aae6e94165dfcf7244a93fc9c
Author: Mikolai Gütschow <mikolai.guetschow@tu-dresden.de>
Date: Tue, 19 May 2026 17:34:12 +0200
procotol/payment: fix deposit fee calculation, properly document canonicalJSON
Diffstat:
3 files changed, 757 insertions(+), 697 deletions(-)
diff --git a/draft-guetschow-taler-protocol.md b/draft-guetschow-taler-protocol.md
@@ -36,6 +36,7 @@ normative:
RFC6234:
RFC7748:
RFC8032:
+ RFC8785:
HKDF: DOI.10.1007/978-3-642-14623-7_34
SHS: DOI.10.6028/NIST.FIPS.180-4
@@ -566,11 +567,22 @@ Hash-Denom(denom) =
Hash-Planchet(planchet, denom) =
SHA-512( SHA-512( denom.pub ) | uint32(0x1) | planchet )
+Hash-Contract(contract) =
+ SHA-512( canonicalJSON(contract) | 0x0)
+
Check-Subtract(value, subtrahend) =
Check value >= subtrahend
Persist value -= subtrahend
~~~
+`canonicalJSON(data)` canonicalizes `data` represented as JSON
+according to the JSON Canonicalization Scheme (JCS) defined in [RFC8785].
+Note that `data` as input to `canonicalJSON` is restricted as follows for Taler:
+
+- For JSON Object member names, only strings matching the regular expression `^[0-9A-Z_a-z]+$` or the literal names `$forgettable` or `$forgotten` are allowed.
+This makes the sorting of object members easier, as [RFC8785] requires sorting by UTF-16 code points.
+- Floating point numbers are forbidden. Numbers must be integers in the range `-(2**53 - 1)` to `(2**52) - 1`.
+
# The Taler Crypto Protocol {#protocol}
The Taler payment protocol is a token-based _e-cash_ system
@@ -855,10 +867,11 @@ Check order.token? == token?
h_wire = HKDF(wire_salt, payto, "merchant-wire-signature", 64)
timestamp = now()
Determine refund_deadline, wire_deadline from timestamp
-contract = (order.{id,price,info,token?}, exchange, h_wire, timestamp, refund_deadline, wire_deadline)
+Determine max_fees from price
+contract = (order.{id,price,info,token?}, exchange, h_wire, timestamp, refund_deadline, wire_deadline, max_fees)
contract.nonce = nonce.pub
Persist contract
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
msg = Gen-Msg(MERCHANT_CONTRACT, h_contract)
sig = Ed25519-Sign(merchant.priv, msg)
~~~
@@ -866,32 +879,36 @@ sig = Ed25519-Sign(merchant.priv, msg)
~~~ pseudocode
(W2) payment preparation (wallet)
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
msg = Gen-Msg(MERCHANT_CONTRACT, h_contract)
Check Ed25519-Verify(merchant.pub, msg, sig)
Check contract.nonce == nonce
// TODO: double-check extra hash check?
for i in 0..n:
- Determine coinᵢ, denomᵢ, contributionᵢ for contract.{exchange,price}
- Check-Subtract(coinᵢ.value, contributionᵢ + denomᵢ.fee_deposit)
+ Determine coinᵢ, denomᵢ, contribution_netᵢ for contract.{exchange,price,max_fees}
+ contribution_grossᵢ = contribution_netᵢ + denomᵢ.fee_deposit
+ Check-Subtract(coinᵢ.value, contribution_grossᵢ)
msgᵢ = Gen-Msg(WALLET_COIN_DEPOSIT,
( h_contract | uint256(0x0)
| uint512(0x0) | contract.h_wire | coinᵢ.h_denom
| timestamp | contract.refund_deadline
- | contributionᵢ + denomᵢ.fee_deposit
- | denomᵢ.fee_deposit | merchant.pub | uint512(0x0) ))
+ | contribution_grossᵢ | denomᵢ.fee_deposit
+ | merchant.pub | uint512(0x0) ))
sigᵢ = Ed25519-Sign(coinᵢ.priv, msgᵢ)
- depositᵢ = (coinᵢ.{pub,sig,h_denom}, contributionᵢ, sigᵢ)
+ depositᵢ = (coinᵢ.{pub,sig,h_denom}, contribution_grossᵢ, sigᵢ)
Persist (contract, ⟨sigᵢ⟩, ⟨depositᵢ⟩)
~~~
~~~ pseudocode
(M3) deposit preparation (merchant)
-Check Sum ⟨depositᵢ.contribution⟩ == contract.price
+for i in 0..n:
+ denomᵢ = Lookup by depositᵢ.coin.h_denom
+ contribution_netᵢ = depositᵢ.contribution_gross - denomᵢ.fee_deposit
+Check Sum ⟨contribution_netᵢ⟩ >= contract.price - contract.max_fees
info.time = contract.{timestamp, wire_deadline, refund_deadline}
info.wire = (payto, wire_salt)
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
msg = Gen-Msg(MERCHANT_CONTRACT, h_contract)
sig = Ed25519-Sign(merchant.priv, msg)
~~~
@@ -907,16 +924,15 @@ for i in 0..n:
coinᵢ = depositᵢ.coin
denomᵢ = Lookup by coinᵢ.h_denom
Check denomᵢ known and not deposit-expired
- totalᵢ = depositᵢ.contribution + denomᵢ.fee_deposit
msgᵢ = Gen-Msg(WALLET_COIN_DEPOSIT,
( h_contract | uint256(0x0)
| uint512(0x0) | h_wire | coinᵢ.h_denom
| info.time.timestamp | info.time.refund_deadline
- | totalᵢ
- | denomᵢ.fee_deposit | merchant.pub | uint512(0x0) ))
+ | depositᵢ.contribution_gross | denomᵢ.fee_deposit
+ | merchant.pub | uint512(0x0) ))
Check Ed25519-Verify(coinᵢ.pub, msgᵢ, depositᵢ.sig)
Check RSA-FDH-Verify(SHA-512(coinᵢ.pub), coinᵢ.sig, denomᵢ.pub)
- Check-Subtract(coinᵢ.value, total)
+ Check-Subtract(coinᵢ.value, depositᵢ.contribution_gross)
Persist deposit-record
schedule bank transfer to payto
time_deposit = now()
@@ -924,7 +940,7 @@ msg = Gen-Msg(EXCHANGE_CONFIRM_DEPOSIT,
( h_contract | h_wire | uint512(0x0)
| time_deposit | info.time.wire_deadline
| info.time.refund_deadline
- | Sum ⟨depositᵢ.contribution⟩
+ | Sum ⟨depositᵢ.contribution_gross⟩
| SHA-512( ⟨depositᵢ.sig⟩ ) | merchant.pub ))
sig = Ed25519-Sign(exchange.priv, msg)
~~~
@@ -1015,7 +1031,7 @@ where (for RSA, without age-restriction)
~~~ pseudocode
(W1) refund request (wallet)
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
~~~
{::comment}
diff --git a/draft-guetschow-taler-protocol.xml b/draft-guetschow-taler-protocol.xml
@@ -24,20 +24,20 @@
<email>mikolai.guetschow@tu-dresden.de</email>
</address>
</author>
- <date year="2026" month="May" day="18"/>
+ <date year="2026" month="May" day="19"/>
<workgroup>independent</workgroup>
<keyword>taler</keyword>
<keyword>cryptography</keyword>
<keyword>ecash</keyword>
<keyword>payments</keyword>
<abstract>
- <?line 45?>
+ <?line 46?>
<t>[ TBW ]</t>
</abstract>
</front>
<middle>
- <?line 49?>
+ <?line 50?>
<section anchor="introduction">
<name>Introduction</name>
@@ -542,10 +542,25 @@ Hash-Denom(denom) =
Hash-Planchet(planchet, denom) =
SHA-512( SHA-512( denom.pub ) | uint32(0x1) | planchet )
+Hash-Contract(contract) =
+ SHA-512( canonicalJSON(contract) | 0x0)
+
Check-Subtract(value, subtrahend) =
Check value >= subtrahend
Persist value -= subtrahend
]]></artwork>
+ <t><tt>canonicalJSON(data)</tt> canonicalizes <tt>data</tt> represented as JSON
+according to the JSON Canonicalization Scheme (JCS) defined in <xref target="RFC8785"/>.
+Note that <tt>data</tt> as input to <tt>canonicalJSON</tt> is restricted as follows for Taler:</t>
+ <ul spacing="normal">
+ <li>
+ <t>For JSON Object member names, only strings matching the regular expression <tt>^[0-9A-Z_a-z]+$</tt> or the literal names <tt>$forgettable</tt> or <tt>$forgotten</tt> are allowed.
+This makes the sorting of object members easier, as <xref target="RFC8785"/> requires sorting by UTF-16 code points.</t>
+ </li>
+ <li>
+ <t>Floating point numbers are forbidden. Numbers must be integers in the range <tt>-(2**53 - 1)</tt> to <tt>(2**52) - 1</tt>.</t>
+ </li>
+ </ul>
</section>
</section>
<section anchor="protocol">
@@ -813,41 +828,46 @@ Check order.token? == token?
h_wire = HKDF(wire_salt, payto, "merchant-wire-signature", 64)
timestamp = now()
Determine refund_deadline, wire_deadline from timestamp
-contract = (order.{id,price,info,token?}, exchange, h_wire, timestamp, refund_deadline, wire_deadline)
+Determine max_fees from price
+contract = (order.{id,price,info,token?}, exchange, h_wire, timestamp, refund_deadline, wire_deadline, max_fees)
contract.nonce = nonce.pub
Persist contract
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
msg = Gen-Msg(MERCHANT_CONTRACT, h_contract)
sig = Ed25519-Sign(merchant.priv, msg)
]]></sourcecode>
<sourcecode type="pseudocode"><![CDATA[
(W2) payment preparation (wallet)
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
msg = Gen-Msg(MERCHANT_CONTRACT, h_contract)
Check Ed25519-Verify(merchant.pub, msg, sig)
Check contract.nonce == nonce
// TODO: double-check extra hash check?
for i in 0..n:
- Determine coinᵢ, denomᵢ, contributionᵢ for contract.{exchange,price}
- Check-Subtract(coinᵢ.value, contributionᵢ + denomᵢ.fee_deposit)
+ Determine coinᵢ, denomᵢ, contribution_netᵢ for contract.{exchange,price,max_fees}
+ contribution_grossᵢ = contribution_netᵢ + denomᵢ.fee_deposit
+ Check-Subtract(coinᵢ.value, contribution_grossᵢ)
msgᵢ = Gen-Msg(WALLET_COIN_DEPOSIT,
( h_contract | uint256(0x0)
| uint512(0x0) | contract.h_wire | coinᵢ.h_denom
| timestamp | contract.refund_deadline
- | contributionᵢ + denomᵢ.fee_deposit
- | denomᵢ.fee_deposit | merchant.pub | uint512(0x0) ))
+ | contribution_grossᵢ | denomᵢ.fee_deposit
+ | merchant.pub | uint512(0x0) ))
sigᵢ = Ed25519-Sign(coinᵢ.priv, msgᵢ)
- depositᵢ = (coinᵢ.{pub,sig,h_denom}, contributionᵢ, sigᵢ)
+ depositᵢ = (coinᵢ.{pub,sig,h_denom}, contribution_grossᵢ, sigᵢ)
Persist (contract, ⟨sigᵢ⟩, ⟨depositᵢ⟩)
]]></sourcecode>
<sourcecode type="pseudocode"><![CDATA[
(M3) deposit preparation (merchant)
-Check Sum ⟨depositᵢ.contribution⟩ == contract.price
+for i in 0..n:
+ denomᵢ = Lookup by depositᵢ.coin.h_denom
+ contribution_netᵢ = depositᵢ.contribution_gross - denomᵢ.fee_deposit
+Check Sum ⟨contribution_netᵢ⟩ >= contract.price - contract.max_fees
info.time = contract.{timestamp, wire_deadline, refund_deadline}
info.wire = (payto, wire_salt)
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
msg = Gen-Msg(MERCHANT_CONTRACT, h_contract)
sig = Ed25519-Sign(merchant.priv, msg)
]]></sourcecode>
@@ -861,16 +881,15 @@ for i in 0..n:
coinᵢ = depositᵢ.coin
denomᵢ = Lookup by coinᵢ.h_denom
Check denomᵢ known and not deposit-expired
- totalᵢ = depositᵢ.contribution + denomᵢ.fee_deposit
msgᵢ = Gen-Msg(WALLET_COIN_DEPOSIT,
( h_contract | uint256(0x0)
| uint512(0x0) | h_wire | coinᵢ.h_denom
| info.time.timestamp | info.time.refund_deadline
- | totalᵢ
- | denomᵢ.fee_deposit | merchant.pub | uint512(0x0) ))
+ | depositᵢ.contribution_gross | denomᵢ.fee_deposit
+ | merchant.pub | uint512(0x0) ))
Check Ed25519-Verify(coinᵢ.pub, msgᵢ, depositᵢ.sig)
Check RSA-FDH-Verify(SHA-512(coinᵢ.pub), coinᵢ.sig, denomᵢ.pub)
- Check-Subtract(coinᵢ.value, total)
+ Check-Subtract(coinᵢ.value, depositᵢ.contribution_gross)
Persist deposit-record
schedule bank transfer to payto
time_deposit = now()
@@ -878,7 +897,7 @@ msg = Gen-Msg(EXCHANGE_CONFIRM_DEPOSIT,
( h_contract | h_wire | uint512(0x0)
| time_deposit | info.time.wire_deadline
| info.time.refund_deadline
- | Sum ⟨depositᵢ.contribution⟩
+ | Sum ⟨depositᵢ.contribution_gross⟩
| SHA-512( ⟨depositᵢ.sig⟩ ) | merchant.pub ))
sig = Ed25519-Sign(exchange.priv, msg)
]]></sourcecode>
@@ -958,7 +977,7 @@ Knows contract | for coinᵢ.pub
<sourcecode type="pseudocode"><![CDATA[
(W1) refund request (wallet)
-h_contract = SHA-512(canonicalJSON(contract))
+h_contract = Hash-Contract(contract)
]]></sourcecode>
<sourcecode type="pseudocode"><![CDATA[
(M1) refund processing (merchant)
@@ -1381,6 +1400,21 @@ In Taler, interaction with exchange, therefore called wallet-to-wallet transacti
<seriesInfo name="RFC" value="8032"/>
<seriesInfo name="DOI" value="10.17487/RFC8032"/>
</reference>
+ <reference anchor="RFC8785">
+ <front>
+ <title>JSON Canonicalization Scheme (JCS)</title>
+ <author fullname="A. Rundgren" initials="A." surname="Rundgren"/>
+ <author fullname="B. Jordan" initials="B." surname="Jordan"/>
+ <author fullname="S. Erdtman" initials="S." surname="Erdtman"/>
+ <date month="June" year="2020"/>
+ <abstract>
+ <t>Cryptographic operations like hashing and signing need the data to be expressed in an invariant format so that the operations are reliably repeatable. One way to address this is to create a canonical representation of the data. Canonicalization also permits data to be exchanged in its original form on the "wire" while cryptographic operations performed on the canonicalized counterpart of the data in the producer and consumer endpoints generate consistent results.</t>
+ <t>This document describes the JSON Canonicalization Scheme (JCS). This specification defines how to create a canonical representation of JSON data by building on the strict serialization methods for JSON primitives defined by ECMAScript, constraining JSON data to the Internet JSON (I-JSON) subset, and by using deterministic property sorting.</t>
+ </abstract>
+ </front>
+ <seriesInfo name="RFC" value="8785"/>
+ <seriesInfo name="DOI" value="10.17487/RFC8785"/>
+ </reference>
<reference anchor="HKDF">
<front>
<title>Cryptographic Extraction and Key Derivation: The HKDF Scheme</title>
@@ -1406,7 +1440,7 @@ In Taler, interaction with exchange, therefore called wallet-to-wallet transacti
<refcontent>National Institute of Standards and Technology (U.S.)</refcontent>
</reference>
</references>
- <?line 1444?>
+ <?line 1460?>
<section anchor="test-vectors">
<name>Test Vectors</name>
@@ -1723,6 +1757,7 @@ coin₁.sig = 355aa5b6bf10591375f22a014640cd242f470834759fab
wire_salt = 4c5249caea865380e0e519fc38177686
order.id = ORDER-40
order.price = KUDOS:7.42
+order.max_fees = KUDOS:0.01
]]></sourcecode>
<sourcecode type="pseudocode"><![CDATA[
(W1) nonce generation (wallet)
@@ -1785,14 +1820,14 @@ sig = c249ee766b4dd256560d48b367d05a41cf7169306247ec
<sourcecode type="pseudocode"><![CDATA[
(W2) payment preparation (wallet)
-contribution₀ = KUDOS:5.12
-contribution₁ = KUDOS:2.3
+contribution_net₀ = KUDOS:5.11
+contribution_net₁ = KUDOS:2.3
sig₀ = 8876dce4ca504df355f17c783e8327ea29b2cbcd7dde60
8b473644af3580621d3eb429022f6d1c4937328db478c6
ed9784f6788e2e18dc16927efd4bc9c10908
-sig₁ = 031283a02cb413308cea4b69bd3d1b7beef87be7788fcf
- c1d7b83f8d97cd4ede218d0f753ba8fc92e22415a66065
- f5c1dff402368de8e85eca0c0ac7358e3602
+sig₁ = ee97e05b9bcd4b49b4518b8d6fdd90b5003178ec6bb4ac
+ b5e9b14f189050c2320489042299b563e8ce0ba889d88c
+ 30d4b438b6d9a1609be3326ea9e12ee46a0b
]]></sourcecode>
<sourcecode type="pseudocode"><![CDATA[
(M3) deposit preparation (merchant)
@@ -1801,10 +1836,10 @@ sig₁ = 031283a02cb413308cea4b69bd3d1b7beef87be7788fcf
<sourcecode type="pseudocode"><![CDATA[
(E1) deposit check (exchange)
-time_exchange = Sat Feb 14 13:37:44 2026
-sig = 09338dd4b1e692431290355b7df62d627a894718db68cf
- 4a8e083bfed7b6c98a0dde3c5724f3cb3db0e6737f57c9
- eb35136997eaf403f27f82c0a9f1cf27d308
+time_deposit = Sat Feb 14 13:37:44 2026
+sig = dffeeb7b3ee0094a2356a3bfed370ae0f082af00ab09a8
+ 35de67db0a8720488419c4da975e9b548e7e554767f1d1
+ b380afc2ea72a93f83885ca3fbc138e4f80d
]]></sourcecode>
<sourcecode type="pseudocode"><