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 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 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 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:

Amount<Obligation.State<Currency>>

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 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 TransactionState 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.

The TransactionState is a container for a ContractState (the custom data used by a contract program) and additional platform-level state information, such as the notary pointer (see Consensus model).

A number of interfaces then extend ContractState, representing standardised functionality for states:

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.

FungibleAssets and Cash

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 lifecycle types

The WireTransaction class contains the core of a transaction without signatures, and with references to attachments in place of the attachments themselves (see also 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 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

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).

Note

These types are provisional and are likely to change in future, for example to add additional information to Party.

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.

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.