[Webfunds-commits] html/guide sox.html Intertrader.html Makefile index.html ricardian.html token.html
Ian Grigg
iang@cypherpunks.ai
Wed, 5 Jul 2000 10:28:53 -0400 (AST)
iang 00/07/05 10:28:53
Modified: guide Intertrader.html Makefile index.html ricardian.html
token.html
Added: guide sox.html
Log:
update for Intertrader
Revision Changes Path
1.2 +81 -68 html/guide/Intertrader.html
Index: Intertrader.html
===================================================================
RCS file: /home/webfunds/cvsroot/html/guide/Intertrader.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Intertrader.html 2000/06/20 09:57:05 1.1
+++ Intertrader.html 2000/07/05 14:28:52 1.2
@@ -5,95 +5,108 @@
<h1>Terminology</h1>
<p>
-Ricardo terminology follows.
+Both Ricardo and
+<a href="http://www.intertrader.com/">Intertrader</a>
+terminology are
+contrasted below
+equivalents described.
+</p>
+<p>
+Here is the quick summary:
+</p>
+
+<blockquote>
+<table border=5>
+ <tr bgcolor="#00FF00">
+ <td><i>Ricardo</i> <td><i>Intertrader</i>
+ <tr>
+ <td>application (WebFunds / Teller) <td>Wallet / CashBox
+ <tr>
+ <td>wallet <td>instrument
+ <tr>
+ <td><a href="ricardian.html#terms">contract</a>(instrument, item)
+ <td>currency
+</tr></table>
+</blockquote>
<h2>Application</h2>
+
+<p>
+An Application is a programme that does something.
+For example,
+</p>
+
+<blockquote>
+<table border=5>
+ <tr bgcolor="#00FF00">
+ <td>Side <td><i>Ricardo</i> <td><i>Intertrader</i>
+
+ <tr>
+ <td>Client - downloadable user applications
+
+ <td>
+ <b>WebFunds</b>
+ can hold different
+ <a href="#wallet">wallets</a>,
+ and can use the payment technologies
+ within in a sensible fashion.
+
+ <td>
+ the <b>Wallet</b>
+ can hold different
+ Instruments, each of which manages a particular
+ payment technology. It can integrate with the
+ browser via a proxy in order to seamlessly enable
+ web retail activities. Currently implemented with
+ Mondex and e-gold (demo status).
+
+ <tr>
+ <td>Server - payments facilitation for retail merchants,
+ extends from client side.
-An Application is a programme that does something. For example,
+ <td>
+ <b>Teller</b>
+ is an early version that
+ can receive requests to deposit incoming
+ payments and requests to write outgoing
+ payments. It only works with one wallet,
+ being the SOX Wallet.
+
+ <td>
+ <b>CashBox</b>
+ works with many Instruments to take payins
+ (only) from different technologies.
-<ul><li>
- <b>WebFunds</b> is a user client that can hold different
- <a href="#wallet">wallets</a>,
- and can use the payment technologies within in a sensible fashion.
-
- </li><p></p><li>
- <b>Teller</b> is a merchant application that can receive
- requests to deposit incoming payments and requests to write outgoing
- payments. It only works with one wallet, being the SOX Wallet.
-
- </li><p></p><li>
- <b>CashBox</b> is an <a href="http://www.intertrader.com/">Intertrader</a>
- Payments management system that
- works with many wallets (which they call Instruments). It
- has a client side downloadable application and a merchant
- side payments manager.
-</li></ul>
+</tr></table>
+</blockquote>
-<h2><a name="wallet">Wallet</a></h2>
+<h2><a name="wallet">WebFunds Wallet == Intertrader Instrument</a></h2>
<p>
-A Wallet is a module offering payments of a particular type
-and technology. E.g., SOX wallet can do SOX payments and deposits.
+A WebFunds Wallet or an Intertrader Instrument
+is a module offering payments of a particular type
+and technology. E.g., SOX wallet can do SOX payments and deposits,
+and a Mondex Instrument can handle the Mondex cash cards.
<p>
There are two other wallets in preparation for WebFunds: a DBS wallet
using Wagner blinding, and a trading wallet. Both of these are
-likely to be extensions of the SOX Wallet.
+likely to be extensions of the SOX Wallet. For Intertrader,
+there is a demo status e-gold Instrument.
<p>
-Each Wallet conforms to the interface located in
+Each WebFunds Wallet conforms to the interface located in
<tt>webfunds/client/WalletInterface.java</tt>.
-In the case of the SOX wallet, the module is at
+In the case of the SOX wallet, the module itself is at
<tt>webfunds/client/sox/SOXWallet.java</tt>.
<p>
-The SOX Wallet will probably change to insert a GUI-free wallet
+The SOX Wallet will change to insert a GUI-free wallet
(and internal interface) in something
like <tt>webfunds/soxwallet</tt> or <tt>webfunds/sox/wallet</tt>.
Then, the original SOXWallet will add the GUI stuff to the new
GUI-free wallet. This is a precondition for non-GUI exporters
working with SOX (merchant applications like Teller and CashBox).
-
-<h2>Item, Contract, Instrument</h2>
-These terms may sometimes mean the same thing:
-
-<p>
-<ul><li>
- <b>item</b> is a SOX value identifier (byte array), literally, the
- field in the SOX payment or the SOX sub account that identifies
- value type.
-
- </li><p></p><li>
- <b>contract</b> is a Ricardian contract, the hash of which is used as
- an item (SHA1). WebFunds assumes that all value, regardless of the
- wallet, is identified by a Ricardian contract. So, if we were to
- add a form of value that was distinct, say, smart card money, then
- we may have to write some contract wrappers to keep WebFunds happy
- with its assumption.
-
- </li><p></p><li>
- <b>instrument</b> is a financially traded ricardian contract, as opposed
- to a contract that is not traded, or outside the trading context.
-
-</li></ul>
-
-<p>
-So, DigiGold might be an instrument, a contract, and an item,
-depending on the context..
-
-<h2>Some Intertrader Terminology</h2>
-We have some words that are swapped with Intertrader usage.
+<h2>Summary of Term Swaps</h2>
-<blockquote>
-<table border=5>
- <tr bgcolor="#00FF00">
- <td><i>Ricardo</i> <td><i>Intertrader</i>
- <tr>
- <td>application <td>wallet
- <tr>
- <td>wallet <td>instrument
- <tr>
- <td>instrument (contract) <td>currency (payer?), instrument (payee?)
-</tr></table>
-</blockquote>
1.7 +2 -0 html/guide/Makefile
Index: Makefile
===================================================================
RCS file: /home/webfunds/cvsroot/html/guide/Makefile,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Makefile 2000/06/07 22:04:05 1.6
+++ Makefile 2000/07/05 14:28:52 1.7
@@ -14,5 +14,7 @@
mailgroup.a \
swaperoo.a \
ricardian.a \
+ sox.a \
+ Intertrader.a \
1.11 +5 -3 html/guide/index.html
Index: index.html
===================================================================
RCS file: /home/webfunds/cvsroot/html/guide/index.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- index.html 2000/06/07 22:04:05 1.10
+++ index.html 2000/07/05 14:28:52 1.11
@@ -18,12 +18,14 @@
</li><p><li>
Links to <a href="ricardian.html">Ricardian Contracts</a> doco.
</li><p><li>
- <a href="token.html">How to add Token Money to WebFunds</a>.
+ Links to <a href="sox.html">SOX Protocol</a> notes.
</li><p><li>
- Some <a href="../v12/index.html">old doco</a> on V1/2
+ <a href="token.html">How to add Token Money to WebFunds</a>.
</li><p><li>
- Sotes on <a href="swaperoo.html">SWAPEROO</a>, a 1998
+ Notes on <a href="swaperoo.html">SWAPEROO</a>, a 1998
project similar to WebFunds.
+ </li><p><li>
+ Some <a href="../v12/index.html">old doco</a> on V1/2
</li></ul>
<h1>How To ...</h1>
1.2 +63 -0 html/guide/ricardian.html
Index: ricardian.html
===================================================================
RCS file: /home/webfunds/cvsroot/html/guide/ricardian.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ricardian.html 2000/06/07 22:04:05 1.1
+++ ricardian.html 2000/07/05 14:28:52 1.2
@@ -12,6 +12,9 @@
suitability to describe value even within wallets that have
yet to be seen or incorporated.
</p>
+
+<h2>Reading</h2>
+
<p>
Documentation is a little scattered. Here's some from the
various Systemics' sources:
@@ -43,5 +46,65 @@
Static Governance section, about half way down.
</li></ol>
+
+<h2><a name="terms">Terms</a></h2>
+
+<p>
+Within the Ricardo world, there are several terms
+that are often used interchangeably:
+</p>
+
+<p>
+<ul><li>
+ <p>
+ <b>item</b> is a SOX value identifier (byte array), literally, the
+ field in the SOX payment or the SOX sub account that identifies
+ value type. As far as the SOX protocol is concerned, this can
+ be anything; as far as the implementation goes, it has to be
+ a Ricardian contract identifier, below.
+ </p>
+
+ </li><p></p><li>
+ <p>
+ <b>contract</b> is a Ricardian contract, the hash of which is used as
+ an item (SHA1). WebFunds assumes that all value, regardless of the
+ wallet, is identified by a Ricardian contract. So, if we were to
+ add a form of value that was distinct, say, smart card money, then
+ we may have to write some contract wrappers to keep WebFunds happy
+ with its assumption.
+ </p>
+
+ <p>
+ Within the general term contract, we can talk about specific
+ broad classes of contract:
+ </p>
+ <ul><li>
+ Currency - money
+ </li><li>
+ Shares - portions of ownership
+ </li><li>
+ Bonds - fixed income streams owed by borrowers to holders
+ </li><li>
+ Other - contracts that describe something that is not
+ countable in the accounting sense.
+ </li></ul>
+ <p>
+ where these are implemented by extending classes.
+ Often, Currency is used where Contract is meant, as
+ the current set of contracts envisage Currencies more
+ than other potential Contracts.
+ </p>
+
+
+ </li><p></p><li>
+ <b>instrument</b> is a financially traded ricardian contract, as opposed
+ to a contract that is not traded, or outside the trading context.
+
+</li></ul>
+
+<p>
+So, DigiGold might be an instrument, a contract, and an item,
+depending on the context...
+</p>
</body></html>
1.2 +150 -52 html/guide/token.html
Index: token.html
===================================================================
RCS file: /home/webfunds/cvsroot/html/guide/token.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- token.html 2000/04/10 22:10:56 1.1
+++ token.html 2000/07/05 14:28:52 1.2
@@ -6,27 +6,37 @@
Status: incomplete.
<h1> Token Money </h1>
-<P>
-How to do Token Money - blinded coins a.k.a. ecash or DBS -
-within WebFunds.
-</P>
+<p>
+This design note describes how to add Token Money
+- blinded packets in the style of eCash coins -
+to WebFunds.
+</p>
+
+<h2> Choices </h2>
+
+There are fundamentally two choices:
+
+<ul><li>
+ Separate Wallet
+ </li><li>
+ Extend SOX
+</li></ul>
-<h2> WebFunds Wallet </h2>
+Each is discussed below.
-<P>
-Within WebFunds, there are several ways to add token money.
+<h2> WebFunds Wallet </h2>
-<P>
-The most
-obvious way is to add a separate wallet, and in fact, that's
+<p>
+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.
+in WebFunds terms, manages a type of payment
+instrument, like SOX, tokens, etc.
See
<a href="design.html">Design</a>.
-<P>
+<p>
The file
<code>
client/WalletInterface.java</a></code>
@@ -36,7 +46,7 @@
client/sox/SOXWallet.java</a></code>
provides the obvious example.
-<P>
+<p>
The essential architecture is that of SOX,
which may or may not be useful.
See comment in
@@ -44,19 +54,19 @@
client/WalletInterface.java</a></code>.
-<P>
+<p>
Choosing the path of adding a separate wallet consists of:
<ul>
<li>
- defining an account / subaccount (contract) architecture
- for the token system
+ defining an account / subaccount (contract)
+ architecture for the token system
<li>
writing all the code...
</ul>
-In that last step, there would be these components:
+There would be these components:
<ul>
<li>
@@ -65,8 +75,9 @@
account.
<li>
- A request to transfer from a (named) "bank" account into
- coins and recover those coins blinded into WebFunds' control.
+ A request to transfer from a (named) "bank" account
+ into coins and recover those coins blinded into
+ WebFunds' control.
<li>
Some way to store the coins - local DB.
@@ -79,25 +90,46 @@
</ul>
<li>
- Deposit of coins into "bank" account or rollover that returns
- cleanly minted and blinded coins.
+ Deposit of coins into "bank" account or rollover
+ that returns cleanly minted and blinded coins.
</ul>
And, of course, all the associated server side code.
<h2> SOX Request </h2>
-<P>
+<p>
A more subtle way to add tokens is to expand SOX. The most
important reason for this is that it already provides 90% of
the infrastructure required to do a token style payment system.
-There are other reasons, and disadvantages, which will be deferred
-for now.
+There are other reasons, and disadvantages, which will be
+deferred for now.
+</p>
+
+<p>
+Components required include
+</p>
+<ul><li>
+ Withdrawal Request
+ </li><li>
+ wallet storage method for coins
+ </li><li>
+ ascii-armoured method for coins
+ </li><li>
+ protocol recovery in case of failed Withdrawal.
+</li></ul>
+
-<P>
+<h3> Withdrawal </h3>
+<p>
The major step required is a withdrawal request. We'll
call such a request a
-<code>WithdrawalRequest</code>.
+<code>WithdrawalRequest</code>
+(and will require a matching <code>WithdrawalReply</code>
+but we don't consider that further here.
+</p>
+
+<p>
It will
sit alongside the
<code>
@@ -111,21 +143,31 @@
Issuer (as it is called in SOX terms) that included some consideration,
and request coins in return.
-<P>
+<p>
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,
-as a configuration option.
+To a large extent, many could be provided in a mature
+implementation, as a configuration option.
-<P>
+<p>
The Issuer, acting as Mint (as it is called in token money terms),
would settle the value into its minted coins account,
-and would then proceed on the coins withdrawal protocol.
-This protocol is quite complex, and differs from blinding method
-to blinding method, but goes something like this (only the case
-of one coin will be considered here):
+and would then proceed on the coins withdrawal protocol,
+returning results in the reply as appropriate.
+
+<h3> Multi-phase Withdrawal. </h3>
-<P>
+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.
+
+<p>
+A multi-phase withdrawal goes something like this
+(only the case of one coin will be considered here):
+
+<p>
<!-- this bit is incomplete, but it illustrates
the multi-phase nature, which is the important point. -->
<ol>
@@ -135,13 +177,13 @@
This would be in the first part of the request.
<li>
The Mint would sign these numbers using a special
- formula that was XXXX with the blinding formula.
+ formula that was commutative with the blinding formula.
The numbers would be returned to the user.
<li>
The user then takes these numbers, unblinds them,
- and stored these in the local coin database.
+ and stores these in the local coin database.
<li>
- Fudge bit. For some reason I can't recall, the
+ 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.
@@ -150,30 +192,24 @@
user to unblind the numbers and store them in
the local coin database. Protocol complete.
</ol>
-
-<P>
-There are a few other changes needed here, but they are minor:
-making the Deposit request and ascii-armour envelope work with a
-coin packet. And we still need to do backend stuff like spent
-coins.
-<P>
-But, the really interesting architecture issue is how to make
+<p>
+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.
-<P>
+<p>
The importance of this is quite high: everything about SOX is
-oriented to idempotent, request model, no state, etc etc. So,
+oriented to idempotent, stateless, request model. So,
adding a stateful, multi-phase request might not be trivial.
-<P>
+<p>
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.
-<P>
+<p>
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
@@ -183,7 +219,7 @@
next phase. This would effectively set up a state machine
within the Wallet.
-<P>
+<p>
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
@@ -191,5 +227,67 @@
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.
+
+<h3> Transmitting User Coins </h3>
+
+<p>
+These sections are not as much work as the above.
+</p>
+
+<p>
+In order to transmit the coins to another client WebFunds,
+the coins will need to be ascii-armoured. There might be
+two ways to do this.
+
+<ol><li>
+ define a new packet that includes the coins,
+ </li><li>
+ extend the SOX payment to include coins.
+</li></ol>
+
+Then, serialise the packet and ascii-armour it appropriately.
+
+<h3> Depositing User Coins </h3>
+
+<p>
+Now, the coins need to be de-armoured, and the coins extracted
+(which is the easy bit).
+</p>
+
+<p>
+Once extracted, the coins need to be deposited in either
+a deposit to some account (assume SOX account)
+or rolled over in order to guaruntee that only the current
+client has the coins.
+</p>
+
+<p>
+The former - deposit to SOX account, is covered by modifying
+the payment to incorporate coins, or modifying the deposit
+request to include coins.
+</p>
+
+<p>
+The latter - roll-over - is a variation on the withdrawal,
+but this time providing the existing coins as consideration.
+</p>
+
+<h2> Server-Side </h2>
+
+For any method there will be the following server side
+components, all of which combined make up a Mint.
+
+<ul><li>
+ A double-spending database.
+ </li><li>
+ The coin production unit. This is the module that
+ creates the signed token, and handles the various
+ state aspects of the blinded withdrawal protocol.
+ </li><li>
+ Double-entry accounts for treasury reserve and issued float.
+ </li><li>
+ Something to manage access to normal bank accounts, or
+ an exchange into an alternate money system.
+</li></ul>
</body></html>
1.1 html/guide/sox.html
Index: sox.html
===================================================================
<html><head>
<title>The SOX Payment Protocol</title>
</head>
<body>
<h1> SOX </h1>
<p>
SOX is a payment protocol that is implemented within
WebFunds as a wallet. It consists of a request model
over an encryption layer. Requests go from client to
server and are repeatable.
</p>
<h2>Reading</h2>
<p>
Documentation is a little scattered. Here's some from the
various Systemics' sources:
</p>
<ol><li>
<a href="http://www.systemics.com/docs/sox/overview.html">
Overview</a>
is the original author's paper on the protocol.
Whilst the concepts have changed little, this
paper is in need of an update.
</li><p></p><li>
<a href="http://www.systemics.com/docs/sox/execsummary.html">
Executive Summary</a>
quickly describes the core features of the protocol.
</li></ol>
<h2><a name="terms">Terms</a></h2>
<p>
Start with the Executive Summary, above.
Here are some other terms not covered there.
</p>
<p>
<ul><li>
<p>
<b>account</b> is primarily
a public and private key pair.
The private key is kept secret and the public key can
be <i>registered</i> with the Issuer, thus making the account
the unit of
<i>authentication</i>.
</p>
</li><p></p><li>
<p>
<b>item</b> is a SOX value identifier (byte array), literally, the
field in the SOX payment or the SOX sub account that identifies
value type. As far as the SOX protocol is concerned, this can
be anything; as far as the current implementations goes, it is
the identifier for a
<a href="ricardian.html">Ricardian contract</a>.
</p>
</li><p></p><li>
<p>
<b>subaccount</b> is the unit of work.
In general, with a standard payments implementation,
this consists of the item, and a database containing
any receipts collected, and state of any pending
transactions.
</li></ul>
<p>
</p>
</body></html>