From 9cdcaaa606bf1e46e4541510495f9ec6780beaf5 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Tue, 7 Jun 2016 17:47:16 +0100 Subject: [PATCH] Add documentation of transaction data types --- docs/source/index.rst | 1 + docs/source/transaction-data-types.rst | 75 ++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 docs/source/transaction-data-types.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index d4f6725976..f18a72c5a4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,6 +26,7 @@ Read on to learn: inthebox getting-set-up data-model + transaction-data-types consensus messaging running-the-demos diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst new file mode 100644 index 0000000000..64b63dca9e --- /dev/null +++ b/docs/source/transaction-data-types.rst @@ -0,0 +1,75 @@ +Transaction Data Types +====================== + +There is a large library of data types used in Corda transactions and contract state objects. + +Amount +------ + +The ``Amount`` class is used to represent an amount of some fungible asset. It is a generic class which wraps around +a type used to define the underlying asset, for example a ``TokenDefinition``, or this can be a more complex type +such as an obligation contract issuance definition (which in turn contains a token definition for whatever the obligation +is to be settled in). + +.. note:: Fungible means that instances of an asset is interchangeable for any other identical instance, for example a +£5 note can reasonably be exchanged for any other £5 note. + +Contract State +-------------- + +A Corda contract is composed of three parts; the executable code, the legal prose, and the state object that represents +the details of the contract. States essentially convert the generic template (code and legal prose) into a specific +instance. In a ``WireTransaction``, outputs are provided as ``ContractState`` implementations, while the inputs are +references to the outputs of a previous transaction. These references are then stored as ``StateRef`` objects, which are +converted to ``StateAndRef`` on demand. + +A number of interfaces then extend ``ContractState``, representing standardised functionality for states: + +* ``OwnableState`` +* ``LinearState`` +* ``DealState`` +* ``FixableDealState`` + +Things (such as attachments) which are identified by their hash should implement the ``NamedByHash`` interface, +which standardises how the ID is extracted. + +FungibleAssets and Cash +~~~~~~~~~~~~~~~~~~~~~~~ + +There is a common ``FungibleAsset`` superclass for contracts which model fungible assets, with ``Cash`` being the obvious +example. This is intended to be readily extensible to cover other assets, for example commodities could be modelled by +using a state object that included further details such as location of the commodity. + +Transaction Types +----------------- + +The core of a transaction (see :doc:`data-model` for detailed discussion of the transaction data model) without +signatures or attachments is represented using the ``WireTransaction`` class, which once signed is encapsulated in the +``SignedTransaction`` class. For processing a transaction (i.e. to verify it) it is first converted to a +``LedgerTransaction``, which involves verifying the signatures and attaching them to the relevant command(s). Commands +with valid signatures are encapsulated in the ``AuthenticatedObject`` type. + +Party and PublicKey +~~~~~~~~~~~~~~~~~~~ + +Identities of parties involved in signing a transaction can be represented simply by their ``PublicKey``, or by further +information (such as name) using the ``Party`` class. An ``AuthenticatedObject`` contains a list of the public keys +for signatures present on the transaction, as well as list of parties for those public keys (where known). + +Date Support +------------ + +There are a number of supporting interfaces and classes for use by contract which deal with dates (especially in the +context of deadlines). As contract negotiation typically deals with deadlines in terms such as "overnight", "T+3", +etc., it's desirable to allow conversion of these terms to their equivalent deadline. ``Tenor`` models the interval +before a deadline, such as 3 days, etc., while ``DateRollConvention`` describes how deadlines are modified to take +into account bank holidays or other events that modify normal working days. + +Business Calendar +~~~~~~~~~~~~~~~~~ + +Calculating the rollover of a deadline based on working days requires information on the bank holidays involved +(and where a contract's parties are in different countries, for example, this can involve multiple separate sets of +bank holidays). The ``BusinessCalendar`` class models these calendars of business holidays; currently it loads these +from files on disk, but in future this is likely to involve reference data oracles in order to ensure consensus on the +dates used.