home -> developer -> IOU -> Design

previous version web-calculus

WaterkenTM IOU



This paper explains the design goals for the WaterkenTM IOU protocol and the design process used to derive the protocol from these goals.


Unlike a traditional paper contract, a smart contract effects the ownership transfers that it specifies. Title registrar procedures for ownership transfer are diverse, not only in the format of requests, but in the controls that must be satisfied for a transfer to be accepted. To make drafting and understanding of a smart contract tractable, a generic registrar interface is proposed. Design of the registrar interface demonstrates the need for a generic model for specifying interfaces that have detailed access control properties. The web-calculus is introduced to meet this need.


The purpose of a contract is to specify a transfer of rights. Diverse brands of right are transferred, with one brand of right being traded for another. The set of right brands is open. Anything that can be owned can be the subject of a transfer in a contract.

To be as useful as a traditional contract, a smart contract must also support transfer of diverse rights selected from an open set of right brands. This requirement is a special burden for a smart contract, since a smart contract effects ownership transfers, instead of merely specifying them. A traditional contract only specifies a transfer, and is thus isolated from the complexity arising from the various procedures for ownership transfer used by a title registrar. Adding the complexity of registrar procedures to the already substantial complexity innate in a contract could obfuscate the terms of a smart contract, making it more difficult to draft and understand.

Since a smart contract is software, software engineering techniques for managing complexity are applicable. To abstract out the complexity arising from diversity in registrar procedures, this paper proposes a generic registrar interface. The interface allows registrars to maintain the distinctive constraints enforced by their procedures, while isolating the smart contract from the complexity arising from this diversity.

Programming models for smart contracts, and even distributed programming models in general, are an active area of research. To gain independence from implementation choices, the proposed interface is described in terms of authorities, and patterns for granting authorities. The web-calculus provides the means for expressing the proposed interface. This paper additionally introduces the web-calculus as a generic model for expressing interfaces that have detailed access controls.


Explanation of the registrar interface begins with an enumeration of the requirements. Following this enumeration is a brief sketch of a simple trade implemented using the registrar interface. The sketch provides an overview of both the web-calculus and the registrar interface. An in-depth explanation of the web-calculus provides the necessary framework for a precise specification of the registrar interface.

Having specified the registrar interface, the paper deconstructs the interface, explaining both how and why the interface is designed as it is. This deconstruction provides a methodology by which other complex access control problems can be addressed.

Finally, the paper details various patterns for using the registrar interface and studies the network latency implications.


This section lists the features that must be supported by the registrar interface.

Generic Ownership

The interface for requesting a right transfer must be identical across all brands of right. It must be possible to draft a smart contract and later parameterize it with the actual right brands to be transferred.

For example, a smart contract that defines a kind of loan must be executable regardless of the brand of collateral agreed upon.

Safe-Safe Transaction

In a safe-safe transaction, each party requires absolute confirmation of the receipt of receivables before authority to release payment is granted. If confirmation fails, receivables are returned to their original holders. The interface must support expression of a safe-safe transaction.

Audit Trail

A registrar may require a complete log of all right transfers, indicating: the original holder; the amount transferred; and the recipient. The interface must support an implementation that maintains such a log.

Counterparty Restriction

A registrar may require that an owner meet certain criteria. The interface must support exclusion of potential owners.

For example, in some jurisdictions an investor must have a minimum net worth before acquiring stock in a private company.

Transfer Monopoly

A registrar may only allow specific smart contracts to request right transfers. The interface must support withholding the right transfer authority from right owners.

For example, a stock exchange may require that all trades of listed stocks be performed through the exchange's markets.

Transaction Fee

A registrar may extract a portion of a right transfer as a fee. The interface must support such an implementation.

For example, a currency issuer may place a tax on each transfer.

Preferential Terms

A registrar may grant preferential transfer terms to some users. The interface must support the existence of multiple refinements of the right transfer authority.

For example, a registrar may have different fees for different users. Some users may only be allowed to perform transfers during business hours.


Given a right transfer authority, the interface must support creation of a derivative right.

For example, a stock broker may create a "call" right and execute a smart contract that allows an owner of the call right to later purchase the underlying right at a fixed price.

Indivisible Right

Some kinds of right are by their nature indivisible. The interface must support the definition of a minimum transfer unit.

For example, a company may require that its shares be traded in a fixed size unit.

Simplicity of Use

The terms of a smart contract expressed using the interface must be readily understood. Expressing the terms of a contract using the interface must be straightforward.

Simplicity of Implementation

A site supporting online ownership transfer is an attractive target for thieves. An error in an implementation of the interface could be costly. A high level of confidence in the correctness of an implementation must be achievable. Currently, the only means of achieving such confidence is reduction of implementation complexity.

DOS Resistance

Each brand of right has multiple possible owners, and so the registrar's service has multiple independent users. The interface must not include any operations that consume a disproportionate amount of the service's computational resources. A user could exploit such variance in resource consumption to disrupt service to other users. Such disruptions could allow a user to gain an advantage in situations where opportunities change over short periods.

Network Efficiency

Registrars, owners, and smart contracts are independent entities operating from geographically dispersed computing centers. Execution of a smart contract requires communication between these entities. Network latency will be the dominant factor in the runtime of a smart contract. The runtime of a smart contract may be apparent in a human interface to a smart contract application. The registrar interface must aim to minimize the effect of network latency on the runtime of a smart contract.

Solution Sketch

The scenario involves two brands of right: brand A and brand B. Each brand of right is hosted by an independent registrar. Alice trades 30 rights of brand A to Bob, for 50 rights of brand B. Trent hosts the smart contract that executes the trade.

Prior to entering the contract, Alice, Bob and Trent have each acquired an account with each of registrars A and B. These accounts provide the owner with the authority to transact in the corresponding brand of right. Trent has additionally acquired the authority to perform right transfers from each of registrars A and B.

The owner of an account can request that the registrar produce a hold for that account. A hold is an independent container of rights used to pass rights between account owners. The account owner can later request that the hold be destroyed and any held rights deposited into the account from which the hold was created.

Rights in Alice's hold.

Figure 1: Entering the contract

Alice enters into the contract by creating a hold containing 30 rights of brand A, an empty hold of brand B and granting authority over these holds to Trent. [grant] Similarly, Bob creates a hold containing 50 rights of brand B, an empty hold of brand A, and grants authority over these holds to Trent.

Rights in Trent's hold.

Figure 2: Acquiring receivables

Using his accounts, Trent creates empty holds for each of brand A and brand B. Using his transfer authority, Trent requests that registrar A transfer the contents of Alice's brand A hold to Trent's brand A hold. Trent makes a similar request to registrar B with Bob's brand B hold. Upon confirmation of each of these initial transfers, Trent requests that registrar B transfer the contents of Trent's brand B hold to Alice's brand B hold. Trent makes a similar request to registrar A for transfer to Bob's brand A hold. If one of the initial transfers is not successful, Trent requests a transfer in the reverse direction for the successful transfer; moving rights from Trent's hold to either Alice's or Bob's hold.

Rights in Bob's hold.

Figure 3: Delivering receivables

Upon completion of the contract, Alice, Bob, and Trent each destroy each of their holds, claiming any held rights.


The web-calculus provides a means of specifying the authorities exported by a service and how these authorities may be exercised and combined. Interoperation between disparate programming environments is achieved by each environment mapping these authority definitions onto its native implementation. In some implementations, a network protocol provides the shared syntax that each environment maps from and to, when communicating with a foreign environment.

For the current problem, the programming environment for both the registrar, and the smart contract, is unknown and may vary. The level of abstraction provided by the web-calculus is crucial to defining the registrar interface that is the basis for interoperation between these two entities. This section provides an overview of the web-calculus sufficient to understand the presentation of the registrar interface.


The web-calculus is defined over a directed graph composed of immutable nodes linked by possibly mutable edges. The target node of a mutable edge may be reassigned any number of times.


Each node has an associated schema, identified by a URI, that distinguishes the node's outbound edges by name. A node is compatible with a schema if it is of the schema, or if it has an edge named 'super' whose target node is compatible with the schema.


Each edge may have an associated closure. A closure is an object with encapsulated state and a single anonymous method. The method has a fixed input parameter list and a single output parameter. Each argument is either a node or an edge. Invocation of a closure may grow the graph, and/or reassign existing edges. [closure]

Web diagram

A web diagram helps communicate an interface.

circle and arrow digram

Figure 4: A web diagram

Figure 4 provides an example web diagram depicting part of the registrar interface. Each node is depicted as a circle annotated with its schema URI. Each edge is depicted as a labeled arrow connecting a source node to a target node. As is the convention, edges with an associated closure are labeled with a verb, while those without are labeled with a noun.


Each edge in the graph is an authority, providing the holder with the ability to fetch the current target node, or invoke the corresponding closure. The holder of an authority may delegate the authority to another user.


The GET operation gets the current target node of an edge. [GET]


The POST operation invokes an edge's closure. The POST operation carries the list of arguments for the invocation. The return from the invocation is the operation return. If the invocation produces an error, the return is a node of schema <http://web-calculus.org/ref/Smashed> specifying the error. [POST]


A web-calculus interface is completely defined by the schemas that define the application graph. This section defines the schemas used in the registrar interface. For economy of space, each schema is defined here using a custom text format, instead of a web diagram. [schema]

Textual Schema Representation

A line starting with a '#' is a comment. The first non-comment line specifies the schema's URI, contained within angle brackets. Subsequent lines referring to the schema are indented once. A line beginning with a '-' defines an edge. The '-' is followed by the edge name, a colon, and the expected schema of the target node. Subsequent lines referring to the edge are indented twice. If the edge has an associated closure, there is a line starting with a: '+' for each parameter, '=' for the return, or '!' for each error. These lines specify the expected schema of the provided node, contained within angle brackets.

Table 1: Legend
symbol meaning
# comment
<> schema URI
- : edge declaration
+ parameter declaration
= return declaration
! error declaration


    # The authority to transact in a particular brand of right.
        # The brand of held right.
        - brand : <http://web-calculus.org/guid/GUID>
        # The number of held rights.
        - balance : <http://web-calculus.org/Integer>
        # Creates an empty child hold for accepting rights.
        - accept : <http://waterken.org/iou/Account-accept>
            # An empty child hold.
            = <http://waterken.org/iou/Hold>
        # Withdraws a portion of the held rights.
        - offer : <http://waterken.org/iou/Account-offer>
            # The number of rights to withdraw.
            + <http://web-calculus.org/Integer>
            # A child hold containing the withdrawn rights.
            = <http://waterken.org/iou/Hold>
            # Withdrawal amount is greater than balance of account.
            ! <http://waterken.org/iou/InsufficientFunds>
        # Destroys a child hold, refunding any held rights into
        # this account.
        - refund : <http://waterken.org/iou/Account-refund>
            # A child hold to destroy.
            + <http://waterken.org/iou/Hold>
            # The number of rights added to the account.
            = <http://web-calculus.org/Integer>
            # The provided hold was not created by the account.
            ! <http://web-calculus.org/brand/WrongBrand>
            # The provided hold was already destroyed.
            ! <http://web-calculus.org/ref/Gone>
    # The authority to hold a particular brand of right.
        # The brand of transferred right.
        - brand : <http://web-calculus.org/guid/GUID>
    # The authority to transfer a particular brand of right.
        # The brand of transferred right.
        - brand : <http://web-calculus.org/guid/GUID>
        # Transfers all held rights in a source hold to a
        # destination hold.
        - transfer : <http://waterken.org/iou/Terms-transfer>
            # A source hold to remove rights from.
            + <http://waterken.org/iou/Hold>
            # A destination hold to deliver rights to.
            + <http://waterken.org/iou/Hold>
            # The number of rights removed from the source hold.
            = <http://web-calculus.org/Integer>
            # A provided hold is not of the expected brand.
            ! <http://web-calculus.org/brand/WrongBrand>
            # A provided hold was previously destroyed.
            ! <http://web-calculus.org/ref/Gone>


The API design begins by defining a right abstraction. Authorities for manipulating this abstraction are then determined based on the requirements. Finally, these authorities are grouped according to expected roles, and authority granting patterns.


A right is an abstract ownership claim, independent of what is actually owned. A number of rights can be conceptualized as an entry in a ledger. The registrar interface defines the procedure for transferring value from one ledger entry to another.

GUID as Brand Identifier

The Generic Ownership and Derivatives requirements imply that new right brands are created frequently and locally, yet need to be unambiguously distinguished globally. Maintaining a global registry of right brands is infeasible and unnecessary. Each right brand is identified by a GUID: a large, randomly selected bitstring.

Natural Number Amounts

The Indivisible Right requirement dictates that right amounts be expressed in natural numbers. When creating a divisible kind of right, a unit smaller than any expected transfer should be chosen. If it is later discovered that the chosen unit was too large, a derivative right brand can be created, along with a contract that supports exchanging an amount of the derivative right for a base right. For example, a penny brand of right could be defined as a derivative of a dollar brand of right.


The Counterparty Restriction requirement has a shaping influence on the design. Withholding ownership authority requires reifying the authority. Ownership is reified as three authorities: the authority to offer; the authority to accept; and the authority to hold. Entering into a contract often requires providing rights for trade. Separating the hold authority from the other ownership authorities enables passing rights to another participant, without granting that participant full ownership authorities.


A hold authority holds an amount of rights. A hold authority is granted from one participant to another as the first step in a right transfer.


An offer authority withdraws an amount of rights from a parent account, creating a child hold.


An accept authority creates an empty, child hold of a parent account.


The Safe-Safe Transaction requirement dictates that a participant possessing only ownership authorities, not a transfer authority, still be able to take exclusive ownership of a refund. A refund authority deposits the rights held in a child hold into the parent account.


The Audit Trail, Transfer Monopoly, and Preferential Terms requirements dictate a right transfer authority. A transfer authority transfers the rights in one hold to another.


Defining the application authorities determines the edges in a web-calculus interface. Defining the expected roles in the application determines the nodes that arrange the edges into a web.


An owner is a participant with the authority to hold, offer and accept rights of a particular brand, as well as receive refunds. An owner must not implicitly get transfer authority.

An <Account> node provides 'offer' and 'accept' authorities. Invoking either the offer or accept authority returns a <Hold> node that provides the child 'hold' authority. An <Account> node additionally provide a 'refund' authority for reclaiming a created <Hold>.


The Safe-Safe Transaction requirement means that a contract typically requires the authority to transfer rights between holds, plus all the authorities of an owner. In a safe-safe transaction, the smart contract will temporarily become the owner of all input rights. The Transfer Monopoly and Preferential Terms requirements dictate that the transfer authority be kept separate from all others.

A <Terms> node provides a 'transfer' authority and documents the implemented transfer terms.


In studying message trips in a pattern, we assume that the messaging implementation supports pipeline references. A pipeline reference is a reference calculated by the message sender, that refers to the message return. The message sender can send this reference to other sites before receiving the message return.

Entering into a Contract

For each offered right brand, the owner uses an 'offer' to provide a <Hold> to the contract. For each wanted right brand, the owner uses a 'accept' to provide a <Hold> to the contract. Upon completion of contract execution, the owner invokes 'refund' with each created <Hold>.

The 'offer' and 'accept' POSTs are sent immediately. Using a pipeline reference for each <Hold>, the POST to the contract is also sent immediately.

Acquiring an Account

Each registrar will have custom vetting criteria for owners. A participant that meets these criteria is granted an <Account>. Contracts can then freely do business with any participant that can provide the required <Hold>s, and need not be concerned with any vetting logic.

Safe-Safe Contract

A safe-safe contract uses a 'accept' to create a temporary <Hold> for each offered right brand. A 'transfer' is used to transfer the contents of each offer <Hold> to the corresponding temporary <Hold>. If all transfers succeed, the contents of each temporary <Hold> are transferred to the buyer <Hold> dictated by the terms of the contract. Otherwise, a 'transfer' is used to transfer the contents of each temporary <Hold> to its corresponding offer <Hold>.

The 'accept' POSTs are sent immediately. Using a pipeline reference for each temporary <Hold>, the 'transfer' POSTs are also sent immediately. All transfers to either the seller or buyer <Hold> begin after the longest round trip in the first set of transfers.

Audit Trail

All right transfers between distinct owners are performed via a 'transfer'. A 'transfer' can be implemented to record the parent <Account> of each argument <Hold>, as well as the transferred amount.

Transaction fee

A 'transfer' can be implemented to transfer part of the source rights to one <Hold>, and the rest to the destination <Hold>.

Preferential Transfer Terms

The registrar grants a different 'transfer' to different contracts.


The specified requirements are satisfied by the proposed registrar interface. Integrating the registrar interface with a smart contract language is a future work. This future work will also determine if the listed requirements form a sufficient base for a useful smart contract application.


[Close03] T. Close; "WaterkenTM Web Calculus"; <http://www.waterken.com/dev/Web/Calculus/>; December 2003.

[ERTP99] Mark S. Miller; "ERTP: The Electronic Rights Transfer Protocol"; <http://www.erights.org/smart-contracts/index.html#ERTP>; 1999.

[Granovetter73] Mark Granovetter; "The Strength of Weak Ties"; American Journal of Sociology Vol. 78; pp.1360-1380; 1973. (online)

[Hardy95] Norman Hardy, Eric Dean Tribble; "The Digital Silk Road"; Agoric Systems: Market Based Computation; <http://www.agorics.com/Library/dsr.html>; September 1995.

[Kahn88] Ken Kahn, Mark S. Miller; "Language Design and Open Systems"; Ecology of Computation, Bernardo Huberman (ed.); Elsevier Science Publishers, North-Holland; 1988.

[Miller99] Mark S. Miller; "Message Pipelining"; <http://www.erights.org/elib/distrib/pipeline.html>; 1999.

[Miller00] Mark S. Miller, Chip Morningstar, Bill Frantz; "Capability-based Financial Instruments"; Proceedings of Financial Cryptography 2000, Springer Verlag; 2000. (online)

[Miller03] Mark S. Miller, Marc Stiegler; "The Digital Path: Smart Contracts and the Third World"; Markets, Information and Communication. Austrian Perspectives on the Internet Economy; Routledge 2003; 2003. (online)

[Szabo97] Nick Szabo; "Formalizing and Securing Relationships on Public Networks"; First Monday, Vol 2 no 9; 1997. (online)

[TAG03] W3C Technical Architecture Group; "Architecture of the World Wide Web, First Edition"; <http://www.w3.org/TR/webarch/>; 2003.

[Tribble95] Eric Dean Tribble, Mark S. Miller, Norm Hardy, Dave Krieger; "Joule: Distributed Application Foundations"; <http://www.agorics.com/joule.html>; 1995.


[grant] When a principal "grants" an authority to another principal, both principals have the ability to independently exercise the authority. After the grant, neither principal has any special powers with respect to the granted authority that the other lacks.

[closure] The term "closure", as used in this paper, is similar to what is returned by the defun function in LISP.

[GET] The GET message is similar in spirit to the GET message used in HTTP.

[POST] The POST message is similar in spirit to the POST message used in HTTP.

[schema] Typically, schemas are defined using an XML format which is not presented in this paper.


Copyright 2004-2005 Waterken Inc. All rights reserved.

Valid XHTML 1.0! Valid CSS!