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.
The file
client/WalletInterface.java
defines the interface,
and
client/sox/SOXWallet.java
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/WalletInterface.java.
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
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/DepositRequest.java
request within the
sox/ValueAccount.java
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.
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 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:
TokenBuilder
is the class used for the client to initially create
a proto-token.
TokenSigner
is received by the Mint and is signed according to the
protocol expressed within.
TokenSpender
is sent back to the client as a fully signed token, ready
for valuable exchange.
TokenDead
is 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:
AbstractParams
is a superclass for an encodable Paramaters class
(not extended by a concrete token implementation).
AbstractPrivateParams
is extended from the above AbstractParams in order
to sign tokens.
AbstractPublicParams
is extended from AbstractParams and
is made available to the client somehow so that the each
phase can be conducted.
ParamsPair
is 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 AbstractPrivateParams and
AbstractPublicParams objects.
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.token.name.
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 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.
webfunds.token.TokenSigner.getUniqueId
method.
webfunds.token.TokenSigner
class.
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:
- WebFunds
- Written, evolving to suite other parts. Lacks coin DB.
- Frontend
- Written and tested for earlier generations.
- Backend
- written and tested for earlier generations.
- Tokens
- 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.