This design note describes how to add Token Money - blinded money packets in the style of eCash coins - to 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.
defines the interface,
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
Choosing the path of adding a separate wallet consists of:
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
(and will require a matching
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.
sits alongside the
request within the
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.
A multi-phase withdrawal goes something like this (only the case of one coin will be considered here):
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.
To facilitate the addition of other close forms of payment such as Token money to SOX, payments now have the following structure:
Figure 1. Payment Classes (UML)
In order to add a token money method,
an extended version of
needs to be written within the token package.
(At the time of writing, only
have been partially written.)
specifies various factory methods for converting
and processing. Read and modify that to suit.
Now let us turn our attention to the
is basically a container for
which is the core class in the tokens package.
That latter class is an abstract class, further refined with
these four abstract class:
TokenBuilderis the class used for the client to initially create a proto-token.
TokenSigneris received by the Mint and is signed according to the protocol expressed within.
TokenSpenderis sent back to the client as a fully signed token, ready for valuable exchange.
TokenDeadis that which results when the token is spent and is recorded as a spent token, for the purposes of closure of the state machine.
Figure 2. Token Classes (UML)
Alongside the above set is a separate set of paramaters classes:
AbstractParamsis a superclass for an encodable Paramaters class (not extended by a concrete token implementation).
AbstractPrivateParamsis extended from the above
AbstractParamsin order to sign tokens.
AbstractPublicParamsis extended from
AbstractParamsand is made available to the client somehow so that the each phase can be conducted.
ParamsPairis the class used by the server-side Mint to create the necessary keys or mathematical entities for one token series (that is, one contract, value, series intersection). It has methods to extract the private and public parts that are the concrete
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
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.
Once the withdrawal is done, a
TokenPayment is returned that
carries the tokens in an array of
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.
There are some administrative niceties to do with setting up of accounts and permitting token money to be accessed.
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.