From 9cdcaaa606bf1e46e4541510495f9ec6780beaf5 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Tue, 7 Jun 2016 17:47:16 +0100 Subject: [PATCH 1/9] 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. From fc3bc163aa564c90a36b5451a78bafdc58060fb7 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 10:46:27 +0100 Subject: [PATCH 2/9] Tweak wording (state -> states) --- docs/source/transaction-data-types.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index 64b63dca9e..fde275e45f 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -17,8 +17,9 @@ is to be settled in). 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 +A Corda contract is composed of three parts; the executable code, the legal prose, and the state objects that represent +the details of the contract (see :doc:`data-model` for further detail). 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. From 874892df93c8faf7f6777d91e1c8d7cc5fd9ffa7 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 11:25:41 +0100 Subject: [PATCH 3/9] Move fungible definition up the document --- docs/source/transaction-data-types.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index fde275e45f..8769fe6504 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -11,8 +11,9 @@ a type used to define the underlying asset, for example a ``TokenDefinition``, o 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. +.. note:: Fungible is used here to mean that instances of an asset is interchangeable for any other identical instance, +and that they can be split/merged. For example a £5 note can reasonably be exchanged for any other £5 note, and a +£10 note can be exchanged for two £5 notes, or vice-versa. Contract State -------------- @@ -35,7 +36,7 @@ Things (such as attachments) which are identified by their hash should implement 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 @@ -51,7 +52,7 @@ signatures or attachments is represented using the ``WireTransaction`` class, wh 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 From 8d1ac66787afcb4a571c2d79c77becee60039e95 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 11:27:26 +0100 Subject: [PATCH 4/9] Remove Business Calendar header --- docs/source/transaction-data-types.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index 8769fe6504..cbac98eaa6 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -67,9 +67,6 @@ etc., it's desirable to allow conversion of these terms to their equivalent dead 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 4b39ab03579f0896c26d6503ede00d634e8348a5 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 11:30:44 +0100 Subject: [PATCH 5/9] Clear up wording around how the FungibleAsset superclass is used Clear up wording around how the FungibleAsset superclass is used, and in particular that it contains contract code, but provides an interface that should be extended by subclass state objects. --- docs/source/transaction-data-types.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index cbac98eaa6..752b09e607 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -38,9 +38,10 @@ 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. +There is a common ``FungibleAsset`` superclass for contracts which model fungible assets, which also provides a standard +interface for its subclasses' state objects to implement. The clear use-case is ``Cash``, however ``FungibleAsset`` is +intended to be readily extensible to cover other assets, for example commodities could be modelled by using a subclass +whose state objects include further details (location of the commodity, origin, grade, etc.) as needed. Transaction Types ----------------- From 14463266db5df3a509fdd1b962d03da931a11c8b Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 16:17:08 +0100 Subject: [PATCH 6/9] Add definition of state interfaces --- docs/source/transaction-data-types.rst | 41 +++++++++++++++++++------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index 752b09e607..caf829994e 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -12,25 +12,46 @@ such as an obligation contract issuance definition (which in turn contains a tok is to be settled in). .. note:: Fungible is used here to mean that instances of an asset is interchangeable for any other identical instance, -and that they can be split/merged. For example a £5 note can reasonably be exchanged for any other £5 note, and a -£10 note can be exchanged for two £5 notes, or vice-versa. + and that they can be split/merged. For example a £5 note can reasonably be exchanged for any other £5 note, and a + £10 note can be exchanged for two £5 notes, or vice-versa. + +Where a contract refers directly to an amount of something, ``Amount`` should wrap ``TokenDefinition``, which in +turn can refer to a ``Currency`` (GBP, USD, CHF, etc.), or any other class. Future work in this area will include +introducing classes to represent non-currency things (such as commodities) that TokenDefinition can wrap. For more +complex amounts, ``Amount`` can wrap other types, for example to represent a number of Obligation contracts to be +delivered (themselves referring to a currency), an ``Amount`` such as the following would used: + +.. container:: codeset + + .. sourcecode:: kotlin + + Amount> Contract State -------------- A Corda contract is composed of three parts; the executable code, the legal prose, and the state objects that represent the details of the contract (see :doc:`data-model` for further detail). 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. +(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`` + ``OwnableState`` + A state which has an owner (represented as a ``PublicKey``, discussed later). Exposes the owner and a function for + replacing the owner. + + ``LinearState`` + A state which links back to its previous state, creating a thread of states over time. Intended to simplify tracking + state versions. + + ``DealState`` + A state representing an agreement between two or more parties. Intended to simplify implementing generic protocols + that manipulate many agreement types. + + ``FixableDealState`` + A deal state, with further functions exposed to support fixing of interest rates. Things (such as attachments) which are identified by their hash should implement the ``NamedByHash`` interface, which standardises how the ID is extracted. From 92b25af0926bb4f9c5ca3e453470953d5e28b3ad Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 16:34:43 +0100 Subject: [PATCH 7/9] Clarified contents of WireTransaction --- docs/source/transaction-data-types.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index caf829994e..0ee2dfbbc8 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -67,11 +67,12 @@ whose state objects include further details (location of the commodity, origin, 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 +The ``WireTransaction`` class contains the core of a transaction without signatures, and with references to attachments +in place of the attachments themselves (see also :doc:`data-model`). Once signed these are 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. +``LedgerTransaction``, which involves verifying the signatures and associating them to the relevant command(s), and +resolving the attachment references to the attachments. Commands with valid signatures are encapsulated in the +``AuthenticatedObject`` type. Party and PublicKey ------------------- From a96a05d857b36716f386d98659d4442a1189eaee Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 10 Jun 2016 16:39:21 +0100 Subject: [PATCH 8/9] Add note about party type being likely to change --- docs/source/transaction-data-types.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index 0ee2dfbbc8..a71ea1f706 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -81,6 +81,9 @@ Identities of parties involved in signing a transaction can be represented simpl 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). +.. note:: These types are provisional and are likely to change in future, for example to add additional information to + ``Party``. + Date Support ------------ From 76a5328e4b6630b8d2ab9bddbd0aadb0aedeeb88 Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Mon, 13 Jun 2016 17:39:42 +0100 Subject: [PATCH 9/9] Replace TokenDefinition with Issued --- docs/source/transaction-data-types.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/transaction-data-types.rst b/docs/source/transaction-data-types.rst index a71ea1f706..20872a7c01 100644 --- a/docs/source/transaction-data-types.rst +++ b/docs/source/transaction-data-types.rst @@ -7,17 +7,17 @@ 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). +a type used to define the underlying product, generally represented by an ``Issued`` instance, 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 is used here to mean that instances of an asset is interchangeable for any other identical instance, and that they can be split/merged. For example a £5 note can reasonably be exchanged for any other £5 note, and a £10 note can be exchanged for two £5 notes, or vice-versa. -Where a contract refers directly to an amount of something, ``Amount`` should wrap ``TokenDefinition``, which in +Where a contract refers directly to an amount of something, ``Amount`` should wrap ``Issued``, which in turn can refer to a ``Currency`` (GBP, USD, CHF, etc.), or any other class. Future work in this area will include -introducing classes to represent non-currency things (such as commodities) that TokenDefinition can wrap. For more +introducing classes to represent non-currency things (such as commodities) that Issued can wrap. For more complex amounts, ``Amount`` can wrap other types, for example to represent a number of Obligation contracts to be delivered (themselves referring to a currency), an ``Amount`` such as the following would used: