Add contract catalogue to documentation

docs/source/contract-catalogue.rst

@@ -0,0 +1,64 @@
+Contracts
+=========
+
+There are a number of contracts supplied with Corda, which cover both core functionality (such as cash on ledger) and
+provide examples of how to model complex contracts (such as interest rate swaps). There is also a ``Dummy`` contract.
+However it does not provide any meaningful functionality, and is intended purely for testing purposes.
+
+Cash
+----
+
+The ``Cash`` contract's state objects represent an amount of some issued currency, owned by some party. Any currency
+can be issued by any party, and it is up to the recipient to determine whether they trust the issuer. Generally nodes
+are expected to have criteria (such as a whitelist) that issuers must fulfil for cash they issue to be accepted.
+
+Cash state objects implement the ``FungibleAsset`` interface, and can be used by the commercial paper and obligation
+contracts as part of settlement of an outstanding debt. The contracts' verification functions require that cash state
+objects of the correct value are received by the beneficiary as part of the settlement transaction.
+
+The cash contract supports issuing, moving and exiting (destroying) states. Note, however, that issuance cannot be part
+of the same transaction as other cash commands, in order to minimise complexity in balance verification.
+
+Commercial Paper
+----------------
+
+``CommercialPaper`` is a very simple obligation to pay an amount of cash at some future point in time (the maturity
+date), and exists primarily as a simplified contract for use in tutorials. Commercial paper supports issuing, moving
+and redeeming (settling) states. Unlike the full obligation contract it does not support locking the state so it cannot
+be settled if the obligor defaults on payment, or netting of state objects. All commands are exclusive of the other
+commercial paper commands. Use the ``Obligation`` contract for more advanced functionality.
+
+Interest Rate Swap
+------------------
+
+The Interest Rate Swap (IRS) contract is a bilateral contract to implement a vanilla fixed / floating same currency
+interest rate swap. In general, an IRS allows two counterparties to modify their exposure from changes in the underlying
+interest rate. They are often used as a hedging instrument, convert a fixed rate loan to a floating rate loan, vice
+versa etc.
+
+See ":doc:`contract-irs`" for full details on the IRS contract.
+
+Obligation
+----------
+
+The obligation contract's state objects represent an obligation to provide some asset, which would generally be a
+cash state object, but can be any contract state object fulfilling the ``FungibleAsset`` interface, including other
+obligations. The obligation contract uses objects referred to as ``Terms`` to group commands and state objects together.
+Terms are a subset of an obligation state object, including details of what should be paid, when, and to whom.
+
+Obligation state objects can be issued, moved and exited as with any fungible asset. The contract also supports state
+object netting and lifecycle changes (marking the obligation that a state object represents as having defaulted, or
+reverting it to the normal state after marking as having defaulted). The ``Net`` command cannot be included with any
+other obligation commands in the same transaction, as it applies to state objects with different beneficiaries, and
+as such applies across multiple terms.
+
+All other obligation contract commands specify obligation terms (what is to be delivered, by whom and by when)
+which are used as a grouping key for input/output states and commands. Issuance and lifecyle commands are mutually
+exclusive of other commands (move/exit) which apply to the same obligation terms, but multiple commands can be present
+in a single transaction if they apply to different terms. For example, a contract can have two different ``Issue``
+commands as long as they apply to different terms, but could not have an ``Issue`` and a ``Net``, or an ``Issue`` and
+``Move`` that apply to the same terms.
+
+Netting of obligations supports close-out netting (which can be triggered by either obligor or beneficiary, but is
+limited to bilateral netting), and payment netting (which requires signatures from all involved parties, but supports
+multilateral netting).

docs/source/contract-irs.rst

@@ -16,7 +16,7 @@ upon an amount that is not actually exchanged but notionally used for the calcul
 amount), and a rate that is either fixed at the creation of the swap (for the fixed leg), or based upon a reference rate
 that is retrieved during the swap (for the floating leg). An example reference rate might be something such as 'LIBOR 3M'.
 
-The fixed leg has its rate computed and set in advance, where as the floating leg has a fixing process whereas the rate
+The fixed leg has its rate computed and set in advance, whereas the floating leg has a fixing process whereas the rate
 for the next period is fixed with relation to a reference rate. Then, a calculation is performed such that the interest
 due over that period multiplied by the notional is paid (normally at the end of the period). If these two legs have the
 same payment date, then these flows can be offset against each other (in reality there are normally a number of these
@@ -33,7 +33,7 @@ the view of the floating leg receiver / fixed leg payer. The enumerated document
 it progresses (note that, the first version exists before the value date), the dots on the "y=0" represent an interest
 rate value becoming available and then the curved arrow indicates to which period the fixing applies.
 
-.. image:: irs.png
+.. image:: contract-irs.png
 
 Two days (by convention, although this can be modified), before the value date (ie the start of the swap) in the red
 period the reference rate is observed from an oracle and fixed in the instance at 1.1%. At the end of the accrual period,

docs/source/index.rst

@@ -31,7 +31,7 @@ Read on to learn:
    messaging
    running-the-demos
    node-administration
-   irs
+   contract-catalogue
 
 .. toctree::
    :maxdepth: 2