Add documentation of transaction data types

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

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.