Token Money

This design note describes how to add Token Money - blinded money packets in the style of eCash coins - to WebFunds.

Conceptual Choices

There are fundamentally two choices: Each is discussed below.

1. Separate Wallet within WebFunds

The most obvious way to add token money is to add a separate wallet, and in fact, that's why the application includes the ability to add separate wallets. Each wallet, in WebFunds terms, manages a type of payment instrument, like SOX, tokens, etc. See Design.

The file client/ defines the interface, and client/sox/ provides the obvious example.

The essential architecture of WebFunds is that of SOX and Ricardian Contracts, which may or may not be useful. See comment in client/

Choosing the path of adding a separate wallet consists of:

There would be these components: And, of course, all the associated server side code.

2. SOX Request


A more subtle way to add tokens is to expand SOX. The most important reason for this is that it already provides 99% of the infrastructure required to do a token style payment system. There are other reasons, and disadvantages, which will be deferred for now.

Components required include


The major step required is a withdrawal request. Here, we'll call such a request a WithdrawalRequest (and will require a matching WithdrawalReply but we don't consider that further here) but also bear in mind that the currenct implementation does a variant of the Deposit Request with a flag set and a proto payment provided.

The WithdrawalRequest sits alongside the sox/ request within the sox/ subaccount. The request is packaged in the SOX Wallet with the addition of some consideration in order to pay for the returned coins, and also a proto-payment presented for signing.

The above mentioned consideration could be a SOX payment, some token coins, or some other payment mechanism. To a large extent, many could be provided in a mature implementation, as a configuration option (only SOX payments currently implemented for paying for coins).

The Issuer, acting as Mint (as it is called in token money terms), would settle the value into its minted coins float account, and would then proceed on the coins withdrawal protocol, returning results in the reply as appropriate.

Multi-phase Withdrawal.

The protocol for withdrawal can be quite complex, and differs from blinding method to blinding method. It may be that methods such as Wagner can be done in a single phase, in which case this section can be skipped.

A multi-phase withdrawal goes something like this (only the case of one coin will be considered here):

  1. The user provides to the Mint a number that is the blinded counterpart of another number. This would be in the first part of the request.
  2. The Mint would sign these numbers using a special formula that was commutative with the blinding formula. The numbers would be returned to the user.
  3. The user then takes these numbers, unblinds them, and stores these in the local coin database.
  4. Fudge bit. For some reason I cannot recall, the protocol now needs the user to go back to the mint in order to complete the protocol. The user goes back and asks for the blah blah.
  5. The mint returns the blah blah which allows the user to unblind the numbers and store them in the local coin database. Protocol complete.

The really interesting architectural issue is how to make the SOX request work when it now has a multi-phase action instead of a simple request-reply action.

The importance of this is quite high: everything about SOX is oriented to idempotent, stateless, request model. So, adding a stateful, multi-phase request might not be trivial.

There are two ways to do it: Firstly, just keep the connection open and slug through till the end of the protocol. This is plausible (if you can get access to the code at that level) but is only short term because there is no state recovery potential.

As SOX has no state, the only way to preserve the place in the sequence is to pass it up to Wallet, which does manage state. So, in this second method, there would be several Withdraw requests, one for each phase. The Wallet would log each phase, then call the subaccount to conduct each request, and deal with the result, before going on to the next phase. This would effectively set up a state machine within the Wallet. (The implemented DepositRequest variant has a state value within it to facilitate this idea.)

Why go to all this - and more - trouble? Because, in SOX, we have set the standard that all transactions can complete to a known state, as long as there is net. We need to carry that standard on to token money if it is to seriously compete with SOX. For this reason, it would also be highly desirable to impose idempotency on the protocol, in that each request can be repeated as an expected event.

3. Structure of Token Money within SOX


To facilitate the addition of other close forms of payment such as Token money to SOX, payments now have the following structure:

Payment Clases UML

Figure 1. Payment Classes (UML)

In order to add a token money method, an extended version of webfunds.token.BaseToken needs to be written within the token package. (At the time of writing, only webfunds.token.chaum and webfunds.token.random have been partially written.)

Additionally, webfunds.sox.PaymentFactory specifies various factory methods for converting and processing. Read and modify that to suit.


Now let us turn our attention to the webfunds.token package. The webfunds.sox.TokenPayment class is basically a container for BaseTokens, which is the core class in the tokens package. That latter class is an abstract class, further refined with these four abstract class:

Token Clases UML

Figure 2. Token Classes (UML)

Alongside the above set is a separate set of paramaters classes:

Paramater Clases UML

Figure 3. Paramater Classes (UML)

A concrete token implementation will extend from each of the above Token Classes and the Paramater Classes, thus resulting in seven classes. It in envisaged that each implementation will be packaged as

WebFunds Withdrawal

The SOX Wallet now implements its own plugin Payment dialog. This dialog is capable of requesting withdrawals in various token money types. The types need to be added manually.

Depositing User Coins

Once the withdrawal is done, a TokenPayment is returned that carries the tokens in an array of BaseToken objects. That payment can now be treated like any other payment, and sent or deposited.

At the moment, that's all you can do as there is no client-side token database.

4. Server-Side

For any method there will be the following server side components, all of which combined make up a Mint.

There are some administrative niceties to do with setting up of accounts and permitting token money to be accessed.

5. Project Status

As of 01 April 2001, status is:

Written, evolving to suite other parts. Lacks coin DB.
Written and tested for earlier generations.
written and tested for earlier generations.
Currently in 3rd generation model, with most of Chaum done, params for Random done.

This project advances on an any-idle-sunday basis. We are currently importing our 3rd generation model of token layout.

Copyright © 2001 Systemics Inc. All rights reserved
Mail us.