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:
The protocol is SOX, which is a generic Internet secure capabilities protocol that happens to do payments as its primary application. As a side effect, there is no need to do the clumsy underlying bank account mechanism from DigiCash's mint project, tokens are withdrawn from SOX nymous payment accounts.
Because it is SOX, the end-to-end protocol transactions are reliable, something that wasn't clearly available in eCash's protocol.
As of the end of 2003, status is:
- WebFunds
- 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.
- Tokens
- In 3rd generation code model (see UML below), working with BRN, Chaum blinding is present but not complete.
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: -----BEGIN SOX MESSAGE----- Comment: SOX 2.5 Version: 2.0.3 hQ0gX5cgl7tUO2ZwBHo0b7UcBkOARUiNH1/DoJ3j6eSOnreW i/BL8E+k6jr7BwAHD1AxMDcyMjAxODIwNzkzKwcHZGdjY2hh dAUAAAAAAAAABQAGAgeBF4QCAAIAAgEBAQAABxRvvQKDd5Nt lhdfvNDUJZbY9IJCoAd0MHIwDQYJKoZIhvcNAQEEBQADYQAS WgzDUp3Big9r5p36xtTku20T9vGKQ5lBuy7sW+YfToCtUZI6 1XnoiyyCyvRTxY6+icqeglK5XjagJV4RHPY4I8TM79S8qXdf LGFuSiAz15ucupJeeGXV43ueKguj/ZsHgReEAgACAAIBAQMA AAcUyOjTHVZvlxi+TLcrcbFcAnV5eg8HdDByMA0GCSqGSIb3 DQEBBAUAA2EACMxb70MwFC3mDtcwUCSfzYpIhYf/Mfo/ymAb 0Nj6PwveFFiPUwEUowk/1o/8jcDrY5QqxOXMw2RBInSeZPum BeMSwY0PrcL5qsslmbdH1q83EwDo1FHfLkb5JAysvixs =/iT+ -----END SOX MESSAGE-----
Actually, it's a SOX message with 2 coins in it, one of 1 and one of 4 making total value of 5.
There were originally two choices, fundamentally, in the design space for adding token money:
Separate Value Manager to manage Tokens
Extend SOX to add a Withdrawal Request
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.
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
Withdrawal Request
value manager storage method for coins
ascii-armoured method for coins
protocol recovery in case of failed Withdrawal.
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 webfunds.sox.pay for the
current implementation.
The
WithdrawalRequest
sits alongside the
sox/DepositRequest.java
request within the
sox/ValueAccount.java
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.
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):
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.
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.
The user then takes these numbers, unblinds them, and stores these in the local coin database.
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.
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.
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.
(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:
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} tuple).
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.
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.
A double-spending database. This is currently
implemented using existing DBs. The unique identifier
of each token is acquired from
the applicable webfunds.token.TokenSigner.getUniqueId
method.
The coin production unit. This is the module that
signs the accepted proto-token, and handles the various
state aspects of the blinded withdrawal protocol.
This is all implemented with calls into the
webfunds.token.TokenSigner
class.
There are some administrative niceties to do with setting up of accounts and permitting token money to be accessed.
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/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 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.