Table of Contents

The Ricardian Financial Instrument Contract



Introduction

In the simplest possible terms, a Ricardian Contract is a formatted document that is both human readable and program parsable. It identifies a Legal Issuer and an Issuance Server, and includes (OpenPGP) keys for those parties. The document is signed in (OpenPGP) cleartext form by the Legal Issuer's contract signing key.

A unique identifier is formed by a canonical message digest (hash) which provides an unforgeable link to the accounting system.

Current Version is 1.5

Added Arrays.

Old Versions

Past Changes:

Syntax

Characters

7 bit ASCII is the default. See UTF-8 for UTF-8 conventions.

Tabs should not be used, and should be considered to illegal.

Format

A Ricardian Contract is an ASCII (or UTF-8 pending) readable file using canonical conventions. Lines should have no more than 80 columns, and indeed should probably have less as modern mailers truncate at around 65-70. Lines are terminated by CR/NL or by NL, and whitespace at the end of the line should not be present (may be removed or ignored).

Whitespace is defined to be any unprintable character or any character that may be suppressed in transmission. Note that this is not a precise definition, and contract writers should take care to have clean lines.

Comments are [;-#] initiated, and apply to a whole line only (i.e., no end of line comments).

Note that the first line will be the signature header, the last will be the signature trailer; the file is signed under the OpenPGP ascii-armoured cleartext signature conventions (so as to be compatible and readable by OpenPGP user clients).

Lines before the signature header and after the signature trailer are not part of the contract (and may be stripped).

Fields

Fields follow the following semi-formal description: 

          name = text ...

where name is a ascii word-chars string (i.e. [_a-zA-Z0-9]). The following specific exclusions apply: a name may not start with an underscore or a digit, and the class of names local_ is not legal in a contract (.asc) file. See the .loc file description at the end. The name should be 7 bit ASCII. The name is optionally prefixed with the section name, as shown below.

Multiline text

Text is ascii text up to the end of line. Whitespace is stripped before and after the name, the symbols ("=", "*", "{", "}"), and (total) text. I.e., whitespace (spaces, tabs) is stripped from the end of each line, but not from the beginning, in accordance with signing whitespace conventions. Multiline fields are done by: 

        name = *
        {
        multiline text
        ...
        }

An additional older format is: 

        name = 'multiline text...
        ...
        '

Which has first appeared in SOX-2. The former is preferred as it is clearer to the eye.

Array

An array of fields may be introduced by the += form: 

        url += http://one.com:42/
        url += http://two.org:69/

Mixing the array form with other forms is illegal. There is no meaning to the order of the array.

Sections

Some fields are necessary for issuer software, some for trading, and others for browsers. Additional fields are not a problem, where the name is unique.

A section can be indicated by a line with only [section name] in it. The name is case sensitive, and lower case tends to be preferred.

Canonical Digest

The message digest, or hash, of the file is taken using a canonical form, in order to preserve the value over different file storage forms.

The text stream is calculated similarly to the clear text signature method of PGP:

If these conventions are not followed, the message digest will not be equivalent.

Note. OpenPGP also drops the line ending for the last line. It is not clear if these are all dropped as yet. As the signature code and digest code derive from a common root, this standard should probably follow suit, even though it is more complex.

Versions exist:

The version can be specified in the Local File in order to force correct calculation.

Pending. See also notes on UTF-8.

The Contract File - Primary Sections

The [entity] Information Section

This section is compulsory.

This section describes the legal issuer, that entity which signs this contract and stands by the signature.

The [issue] Issuer Information Section

This section is compulsory for all items that are managed by issuer software (it is conceivable that a private contract been two parties is not managed by an issuer, but we ignore this case for now). Notwithstanding the above, its contents do not appear to have a lot of importance.

The section refers to details about the item that keeps it running as an Internet financial instrument. Here, the issuer refers the technical manager of the item, not the entity that backs the value.

The [definitions] and [conditions] Legal Sections

As a custom that has arisen through experience, two sections have been added that have no technical components.

The section [definitions] includes terms and definitions that generally desire to be defined in a contract. Following normal procedure in english common law contracts, this section goes up front.

Later on (after the [entity] and [issue]) is added a [conditions] section. This includes the meat of the contract in clauses. In general, there is little in here for the program to read, its terms are for the human reader.

The [keys] Section and The Ricardian Public Key Infrastructure

This section optionally holds public keys that may or may not be relevant.

Public Keys can be included. They can play a role in dissemination of the issuer's certification and contract keys. Contents are loosely defined as follows: 

        certification=*
        {
        Type bits/keyID    Date        User ID
        pub  2048/45766115 1996/11/29  Systemics, Ltd V1.1 [certification] info@systemics.com
        -----BEGIN PGP PUBLIC KEY BLOCK-----
        Version: 2.6.2
        
        mQENAjKfEs [snip]
        -----END PGP PUBLIC KEY BLOCK-----
        
        }
        contract=*
        {
        ...
        }

Note that the existance of any keys in this section does not by itself confirm the validity of the signature. The security derives from the contract being signed with a [contract] key that is itself signed by the entity's [certification] key.

Then, security rests on knowing that the [certification] key is valid, and ensuring a chain of signatures to the contract. Understanding why the key included in the contract cannot be used is left as an exercise to the reader.

The [signatures] Section

At the very end of the contract file to be signed, PGP, for example, is used to sign the file using the above [contract] key. Note that:

See also Initiating the New Contract.

Extended Sections

Each of these sections is an extension indicating a semantically different type of issue. There should be one only of these included.

The [bond] Financial Item Description Section

This section is only included if type_of_issue == bond.

Bond can be displayed as entity_shortname bond_identity currency face.

Remember, the face amount of currency units is paid on the maturity date. It is not necessarily the traded currency - that is up to the market. The Zero contract is a one-cash-flow financial instrument, and is the only contract that the market currently supports.

The [share] Financial Instrument Description Section

This section only included if type_of_issue == share. Not much experience has been earnt with real shares as yet, so this section is dynamic.

Share can be displayed simply as share_symbol and is therefore required to be unique. It can be up to 8 characters.

There are few important details here, as just about all details are changeable and non-standard. See entity_www for details of the AGM, share_type rights, entity documents, share quantities, annual reports, and the like.

The [currency] Financial Instrument Description Section

This section only included if type_of_issue == currency.

A currency is a money item that is issued by a cash issuer. It is often backed by deposits and "specie", or reserves, and redeemed in some common value unit. However, this is not always the case, rather it is a marketing decision by the issuer. For example, US dollars are not redeemable in anything other than more dollars.

The [task] Financial Instrument Description Section

This section only included if type_of_issue == task.

A task is a future on the delivery of a project. Tasks (or rather, task units) are sold when programmers offer to sell futures, and essentially enter into a contract to supply the underlying deliverable, if the market clears. Contributors bid to buy task units, which return them futures unit on the delivery of the project, if the market clears.

Whether the tasks have any value is not really defined, although the task_ware variable, below, says something about value.

The following is also in the Local File for task market contracts.

The Local File

For local management of Contracts, the following convention exists. Along side the "name.asc" file holding the InfoFile, place a "name.loc" file with local additional information included. This .loc file is not part of any contract, but refers to additional conditions applicable on the local site.

It is not currently signed.

In the name.loc file, local_ fields are in a protected name space as they cannot be valid in the name.asc file. Other fields are incorporated according to software conventions, and no priority is defined.

In a dynamic local file context, such as new items, setting a field to <undef> will signal that this line is now deleted. This allows the contract reading classes *Info.pm to do field deletions where refreshes are allowed. This feature only makes sense in the local file.

The Standard Local File

The following are applicable to any SOX-compliant server.

The Issuer Local File

The Ricardian Issuance Server, which is a SOX-compliant Server, may have additional fields. None are currently defined.

The Market Local File

As well as the above, the market uses these:

Other fields are likely to include opening hours, etc.

UTF-8

Intro

By default, the content of the text is 7 bit ASCII, but UTF-8 may be used. UTF-8 is a 7 bit ASCII compatible format that uses the sign bit to generate sequences up to 6 bytes long to encode a single character.

Latin, 8-bit ASCII, UTF-16 and any other format is not supported.

Warning: Embedded line ending characters may challenge the definition of the canonical hash. The OpenPGP format specifies that only space (0x20) and tab (0x09) are to be stripped from the end of the lines. Tabs are illegal in Ricardian Contracts.

Explanation. UTF-8 was chosen because it is the emerging standard, it is the OpenPGP cleartext signed format, and it is the Java format. Only limited experience with UTF-8 contracts has been had so far.

Currency

The Brit pound is an 8-bit char 0xA3. In Unicode this is written \u00A3 or U+00A3, which is hexadecimal 2 bytes (or UCS-2 as they call it). In UTF-8, it expands to be 2 bytes 0x C2 A3. Likewise, the Euro is \u20AC which expands to be 3 bytes 0x E2 82 AC.

name html simul Unicode UTF-8
pound £ # 00AC C2 A3
Euro € C 20 AC E2 82 AC
Yen ¥ Y 00A5 C2 A5

Spanish

useful javascript calculator

name html simul Unicode UTF-8
enya &enya; ny 00F1 C3 B1
Enya &enya; NY 00D1 C3 91
quote right >> 00BB C2 BB
quote left << 00AB C2 AB
Copyright © 1995-2005 Systemics Inc. All rights reserved