This design document proposes an extension of the Taler protocol that allows payments from wallet-to-wallet without a merchant.
To be usable as an electronic payment system with cash-like properties, customers should be able to transfer money between themselves without needing to setup anything beyond their wallet(s).
This will be used for payments via e-mail and other messaging apps, as well as possibly for transfers via NFC/QR code between mobile phones.
account is a non-expiring reserve for which entity knowing the
reserve private key has completed a KYC procedure sufficient to enable
receiving income under that address.purse is a public-private key pair where the public key is
an exchange address from which any owners of an account
can merge the amount left at a purse into their
account balance assuming they know the purse private key.wad is an exchange-to-exchange wire transfer that wires money
into a group of accounts at the target exchange.The standard Taler Customer-to-Merchant payments always use a contract terms JSON object to record the modalities of the payment and the resulting obligations of a successful payment.
The contract terms concept does not directly carry over to W2W payments, because:
As a result, some of the existing fields of the contract terms no longer apply to wallet-to-wallet payments.
Contract metadata for W2W payments can be exchanged in three ways:
Inline, as part of the payment request / payment offer. In this case, both parties are already aware of the contract’s contents and the exchange’s contract exchange facility is simply not used.
The payee can create a purse and immediately associate it with an account by sending a signed merge request together with the (encrypted) contract.
The payer can store a contract with the exchange by POSTing an encrypted contract to the exchange as part of creating a purse.
The exchange charges the purse fee to payers for purses that are refunded after not being merged.
When paying into a purse, the coin signature includes the purse public key, the contract hash and the desired expiration date (how long a merge is allowed).
Payment offers are not allowed if the amount transacted is below the purse fee.
The exchange auto-refunds coins in purses with deposits matching expired contracts.
Note
While the refund fee amount can be reused, these types of refunds are not approved by a merchant’s signature. Thus, we will need a new message type in the coin history to represent these events.
payto://taler/$EXCHANGE_BASE_URL/$ACCOUNT_PUB
target address (for which the payee knows the corresponding
account private key).ACCOUNT_PUB.
Possible replies are in-progress and succeeded. An in-progress
status should be accompanied with
information how the customer may complete the KYC check./account/$ACCOUNT_PUB/kyc
allows wallets to request a KYC for an
$ACCOUNT_PUB. Such a request may include the requirement to pay
a KYC fee. The KYC fee may be charged to that account (if it exists),
or could be waved if the account was established via a wire transfer
from a partner bank.taler-exchange-wirewatch cannot cause the long
polling to be resumed, only transfers within the same exchange can benefit
from long-polling acceleration.In this protocol variant, the payer is initiating the process.
The payer creates a purse by computing a public-private key pair.
The payer POSTs to the /purse/$PURSE_PUB/depost endpoint to
deposit coins into the purse and optionally upload the encrypted contract terms.
The deposit signatures should use payto://taler/$PURSE_PUB
as the target address and signing over the $CONTRACT_HASH as
usual in deposit operations. Note that the lack of a hostname
indicates that the target address is a local purse.
The payer shares the purse’s private key and the base URL
of the exchange where the purse was created with the payee.
This can be done using a taler://purse/$BASE_URL/$PURSE_PRIV URL.
The payee uses the new /purse/$PURSE_PUB endpoint to retrieve
the encrypted contract (if available) and purse balance, which includes all
(coin) deposits and merges involving the purse.
The payee’s wallet must ensure that either:
If neither case applies, the payee’s wallet must reject the payment.
The payee can then POST to /purse/$PURSE_PUB/merge a
request signed by the purse’s private key to merge the
funds into an account. A second signature must be provided
by the account private key, signing the $CONTRACT_HASH thereby
affirming that the payee accepted the contract.
The account is of the form payto://taler/$EXCHANGE_BASE_URL/$ACCOUNT_PUB.
Processing continues depending on the location of the account:
$EXCHANGE_BASE_URL matches the local exchange, then
the exchange processes the merge request akin to the logic
for payments into known accounts, as detailed above.$EXCHANGE_BASE_URL does not match the local exchange,
a wad fee is charged, and the remaining amount are placed into a wad
to inform the target exchange, as detailed below. Wad fees may be covered
by the merchant, just like deposit fees, depending on the contract.The exchange confirms the merge (per response to the merge request). This allows the payee software to instantly affirm to the users that the transaction is final (even if it may not be instantly available to the payee if the payee did not complete the KYC process for the account).
The payer uses the GET /purse/$PURSE_PUB endpoint
to obtain the receipt from the payee (in the form of the
merge signature). Query parameters are used to avoid
downloading the (already known) encrypted contract and the
deposit operations. Long-polling must also be possible for
this request.
/purse/$PURSE_PUB/merge endpoint to
both upload the encrypted contract, associate it with the payer’s
account and signal its agreement to the contract. The
merge request must be signed by the purse’s private key.
A second signature must be provided by the account private key,
signing the $CONTRACT_HASH thereby affirming that the payee
accepted the contract.$PURSE_PRIV to the payer./purse/$PURSE_PUB endpoint to retrieve
the encrypted contract and the merge request, which signifies that
the payee would agree to the contract./purse/$PURSE_PUB/depost endpoint to
deposit coins into the purse. The deposit signatures should use
payto://taler/$PURSE_PUB
as the target address and signing over the $CONTRACT_HASH as
usual in deposit operations. Note that the lack of a hostname
indicates that the target address is a local purse./deposit endpoint and a target account of the form
payto://taler/$EXCHANGE_BASE_URL/$ACCOUNT_PUB. In this case,
the remote exchange charges a wad fee and places the remaining
amount into a wad to inform the target exchange, as detailed below./purse/$PURSE_PUB endpoint (possibly with long-polling)
to be notified about the successful deposit and subsequent completion of the
merge request.In case the coins and the accounts in the transaction flows above are at different exchanges, an aggregated exchange-to-exchange payment (short wad) is used.
Exchanges specify a new wad fee that they charge for exchange-to-exchange payments. They also specify their wad policy, that is how often they perform exchange-to-exchange transfers.
Note
We may want to consider allowing for different wad-speed levels, where express payments (without aggregation) are allowed in return for higher wad fees.
The payer’s exchange creates a wad by grouping all wad requests to the same target exchange. It executes the transaction when either the wad threshold (maximum number of transactons aggregated per wad) or the wad delay (maximum delay for transfers) has been reached.
If the (aggregated) wire transfer fails (say the
/wire endpoint of the payee exchange does not
resolve to a valid bank account), the
originating exchange automatically creates a full refund for
all involved coins (refund fees apply).
Note
While the refund fee amount can be reused, these types of refunds are not approved by a merchant’s signature. Thus, we will need a new message type in the coin history to represent these events.
The payee’s exchange observes the wire transfer with a wire transfer
subject with the originating exchange base URL and a $WATID,
and uses a GET /wad/$WATID request to obtain
details about the target accounts.
When the payer’s exchange is requested to provide information about
aggregated transfers under the $WATID, it provides a signed list of
account public keys and associated amounts that must add up to an
amount below the total amount transferred. If they do not, the
payee’s exchange does not credit any of the accounts and instead
preserves the bogus reply (to justify its inaction with its own
auditor) and reports the issue to the auditor of the payer’s exchange
(keeping the received funds for future manual resolution).
taler-exchange-wirewatch and the Taler wire gateway API will
need to be extended to allow passing inbound wire transfers with $WATID
and exchange base URL to the exchange. Furthermore, another tool
is needed to lookup the wad data at remote exchanges.
If the payee trusts the originating exchange, it may consider the
transaction final once the originating exchange has affirmed the
deposit (assuming the payer has a way to submit the evidence of that
payment, which may not apply in uni-directional scenarios).
Otherwise, the payee may simply only trust its own exchange,
resulting in the transfer only being considered final after the
receiving exchange has confirmed that the wad has arrived.
Cross-exchange W2W payment request:
taler://purse/{EXCHANGE_URL}/{PURSE_PRIV}
link that she can share with Bob. Bob receives the link and opens it with
his Taler wallet. Bob is using a different EUR exchange than Alice. Bob’s
wallet makes a /deposit request to his own exchange. Shortly after, Alice’s
exchange receives the wad from Bob’s exchange, and credits the money into
Alice’s purse.Cross-exchange W2W payment offer:
taler://purse/{EXCHANGE_URL}/{PURSE_PRIV} in an e-mail to Dave.
Dave opens they link in the e-mail with his Taler wallet.
Since Dave is using a different exchange than Alice, Dave’s wallet
issues a merge request to Alice’s exchange pointing Alice’s exchange
to Dave’s account at his exchange. Shortly after,
Dave’s exchange receives a wad from Alice’s exchange,
and credits Dave’s account with the money.// The "OPEN-ACCOUNT" start state implies that the purse is associated
// with an account and a merge request for that account.
-> OPEN-ACCOUNT
// "Partial" means that it is filled with a fraction of the coins
// indicated in the creation request.
OPEN-ACCOUNT -> PARTIAL
// The purse was filled with as many coins
// as indicated in the creation request, resulting in the transaction to complete.
OPEN-ACCOUNT -> ACCEPTED
// The offer expired before any payment was received.
OPEN-ACCOUNT -> CLOSED
// The purse was filled with as many coins
// as indicated in the creation request, resulting in the transaction to complete.
PARTIAL -> ACCEPTED
// During an abort, already deposited coins are being taken out of the purse.
PARTIAL -> OPEN-ACCOUNT
// All coins put into the purse are refunded because the
// payer never completed the purchase before the timeout.
PARTIAL -> CLOSED
// The "OPEN-DEPOSIT" start state implies that the purse is filled with
// deposited coins.
-> OPEN-DEPOSIT
// Paid and merged with an account (locally or via a wad)
OPEN-DEPOSIT -> ACCEPTED
// The offer expired without a merge request.
OPEN-DEPOSIT -> CLOSED
/deposit.The overall changes required are not small:
/keys endpoint (similar to closing and wire fees),
requires some work across toolchain (offline signature, etc.)taler wire method needs special case to possibly bypass
(same exchange scenario, with long-poll trigger) the usual aggregation logic.transfers requests for purses
(another separate process)./account/$ACCOUNT_PUB/kyc endpoint required./purse/$PURSE_PUB/merge endpoint required.taler-exchange-wirewatch needs to support receiving purses closures
and exchange-to-exchange wire transfers with WTIDs.Aside from implementation complexity, the solution has the following drawbacks:
/deposit of coins cannot be negotiated. Furthermore,
the sender of the payment cannot be sure that the account of
the sender is still valid.