Token Money

This note describes the Token Money project within WebFunds.


Tokens are also known as digital coins - discrete packets that act as a single denomination and can be passed hand to hand.

The most famous example of this concept was the blinded money packets known as eCash coins, created by the DigiCash company using David Chaum's blinding formula. WebFunds differs from the old DigiCash project in several ways:

Project Status

As of the end of 2003, status is:


Written and installed. Lacks coin DB.
SOX and Frontend
Written and tested, single phase only. Lacks ability to acquire signing keys and test coins for correct signature.
Backend (mint)
written and tested.
In 3rd generation code model (see UML below), working with BRN, Chaum blinding is present but not complete.

Operational Token Money

One Issue is enabled with BRN, being the test currency "Sava-Cheks". To get access, you need the latest versions of WebFunds, and you need to put the "test" status to true. Then, the "Special Pay" dialog allows selection of the BRN form. (You also need the Sava-Cheks contract.)

Here is an example token. In the BRN format, ("Big Random Numbers") these tokens are traceable:

This is a Big Random Numbers payment for IGD 5
from LotsOfDosh (c3a09de3e9e48e9eb7968bf04bf04fa4ea3afb07)
to   <OPEN>
Cut and Paste the following lines into an email:

Comment: SOX 2.5
Version: 2.0.3



Actually, it's a SOX message with 2 coins in it, one of 1 and one of 4 making total value of 5.


Conceptual Choices

There were originally two choices, fundamentally, in the design space for adding token money:

As extending SOX (choice 2) was chosen for implementation, that is primarily discussed here. The choice of the Value Manager is relegated to Appendix 1.

Extending SOX


A subtle way to add tokens is to expand SOX. This is not the first thought or choice because it has always been assumed that the SOX protocol was unsuited to the needs of tokens. On the face of it, the SOX design is very holistic, and tightly coupled with its design requirements - none of which support tokens, and many of which are contrary to token principles.

The most important reason for choosing SOX is that it (and Ricardo) already provides 99% of the infrastructure required to do a token style payment system.

Regardless of design intentions and project considerations, it turns out that SOX is in fact a very suitable platform or carrier protocol for token coins. It has many advantages that do turn to token money's benefit, far more than the apparent disadvantages would have lead us to believe. In fact, SOX is a compelling platform for token payments, so much so that in comparison to other protocol ideas, it seems to easily dominate. These aspects are however ignored in this document, which is more about the current world.


Components required include


The major step required is a withdrawal request. Here, we'll call such a request a WithdrawalRequest. Bear in mind that we will require a matching WithdrawalReply but we don't consider that further here. Also the current implementation does not use these names, see for the current implementation.

The WithdrawalRequest sits alongside the sox/ request within the sox/ subaccount. The request is packaged in the SOXWallet 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 (in the current implementation, only SOX payments can be used 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 seems that there exist methods from most blinded formulas that can be done in a single phase, in which case this section can be ignored..

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 SOXWallet, which does manage state. So, in this second method, there would be several Withdraw requests, one for each phase. SOXWallet 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 SOXWallet. (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.

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. (See the packages webfunds.token.random and webfunds.token.chaum for examples).

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


SOXWallet now implements its own plugin Payment dialog, labelled on the subaccount menu "Special Pay". This dialog is capable of requesting withdrawals in various money types, including the different token types. The types need to be added manually into the dialog.

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.


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.

A1. Separate Value Manager within WebFunds


The most obvious way to add token money was to add a separate value manager.

In fact, that is why WebFunds G3 (3rd generation) included the ability to add separate value managers. Each value manager, in WebFunds terms, manages a type of payment instrument, like SOX, tokens, etc. See Design. As a side note, WebFunds G4 - Lucaya - does not include this architecture, so this section is now of historical interest only. In essence, the notion of a separated Value Manager was proven to be uneconomic, and won't likely be reborn.


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 value manager consists of:


There would be these components:

And, of course, all the associated server side code.

Back to Index.

Copyright © 2000-2003 Systemics Ltd. All rights reserved.