<h2>The Basic Lifecycle Of Transactions<aclass="headerlink"href="#the-basic-lifecycle-of-transactions"title="Permalink to this headline">¶</a></h2>
<p>Transactions in Corda are constructed in stages and contain a number of
elements. In particular a transaction’s core data structure is the
<codeclass="docutils literal"><spanclass="pre">net.corda.core.transactions.WireTransaction</span></code>, which is usually
manipulated via a
<codeclass="docutils literal"><spanclass="pre">net.corda.core.contracts.General.TransactionBuilder</span></code> and contains:</p>
<p>1. A set of Input state references that will be consumed by the final
accepted transaction.</p>
<p>2. A set of Output states to create/replace the consumed states and thus
become the new latest versions of data on the ledger.</p>
<p>3. A set of <codeclass="docutils literal"><spanclass="pre">Attachment</span></code> items which can contain legal documents, contract
code, or private encrypted sections as an extension beyond the native
contract states.</p>
<p>4. A set of <codeclass="docutils literal"><spanclass="pre">Command</span></code> items which give a context to the type of ledger
transition that is encoded in the transaction. Also each command has an
associated set of signer keys, which will be required to sign the
transaction.</p>
<p>5. A signers list, which is populated by the <codeclass="docutils literal"><spanclass="pre">TransactionBuilder</span></code> to
be the union of the signers on the individual Command objects.</p>
<p>6. A notary identity to specify the Notary node which is tracking the
state consumption. (If the input states are registered with different
notary nodes the flow will have to insert additional <codeclass="docutils literal"><spanclass="pre">NotaryChange</span></code>
transactions to migrate the states across to a consistent notary node,
before being allowed to mutate any states.)</p>
<p>7. Optionally a timestamp that can used in the Notary to time bound the
period in which the proposed transaction stays valid.</p>
<p>Typically, the <codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code> should be regarded as a proposal and
may need to be exchanged back and forth between parties before it can be
fully populated. This is an immediate consequence of the Corda privacy
model, which means that the input states are likely to be unknown to the
other node.</p>
<p>Once the proposed data is fully populated the flow code should freeze
the <codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code> and form a <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code>. This is key to
the ledger agreement process, as once a flow has attached a node’s
signature it has stated that all details of the transaction are
acceptable to it. A flow should take care not to attach signatures to
intermediate data, which might be maliciously used to construct a
different <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code>. For instance in a foreign exchange
scenario we shouldn’t send a <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> with only our sell
side populated as that could be used to take the money without the
expected return of the other currency. Also, it is best practice for
flows to receive back the <codeclass="docutils literal"><spanclass="pre">DigitalSignature.WithKey</span></code> of other parties
rather than a full <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> objects, because otherwise we
have to separately check that this is still the same
<codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> and not a malicious substitute.</p>
<p>The final stage of committing the transaction to the ledger is to
notarise the <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code>, distribute this to all appropriate
parties and record the data into the ledger. These actions are best
steps manually. However, do note that the final broadcast to the other
nodes is asynchronous, so care must be used in unit testing to
correctly await the Vault updates.</p>
</div>
<divclass="section"id="gathering-inputs">
<h2>Gathering Inputs<aclass="headerlink"href="#gathering-inputs"title="Permalink to this headline">¶</a></h2>
<p>One of the first steps to forming a transaction is gathering the set of
input references. This process will clearly vary according to the nature
of the business process being captured by the smart contract and the
parameterised details of the request. However, it will generally involve
searching the Vault via the <codeclass="docutils literal"><spanclass="pre">VaultService</span></code> interface on the
<codeclass="docutils literal"><spanclass="pre">ServiceHub</span></code> to locate the input states.</p>
<p>To give a few more specific details consider two simplified real world
scenarios. First, a basic foreign exchange Cash transaction. This
transaction needs to locate a set of funds to exchange. A flow
modelling this is implemented in <codeclass="docutils literal"><spanclass="pre">FxTransactionBuildTutorial.kt</span></code>.
Second, a simple business model in which parties manually accept, or
reject each other’s trade proposals which is implemented in
<codeclass="docutils literal"><spanclass="pre">WorkflowTransactionBuildTutorial.kt</span></code>. To run and explore these
examples using the IntelliJ IDE one can run/step the respective unit
tests in <codeclass="docutils literal"><spanclass="pre">FxTransactionBuildTutorialTest.kt</span></code> and
<codeclass="docutils literal"><spanclass="pre">WorkflowTransactionBuildTutorialTest.kt</span></code>, which drive the flows as
part of a simulated in-memory network of nodes. When creating the
IntelliJ run configuration for these unit test set the workspace
points to the root <codeclass="docutils literal"><spanclass="pre">r3prototyping</span></code> folder and add
<codeclass="docutils literal"><spanclass="pre">-javaagent:lib/quasar.jar</span></code> to the VM options, so that the <codeclass="docutils literal"><spanclass="pre">Quasar</span></code>
instrumentation is correctly configured.</p>
<p>For the Cash transaction let’s assume the cash resources are using the
standard <codeclass="docutils literal"><spanclass="pre">CashState</span></code> in the <codeclass="docutils literal"><spanclass="pre">:financial</span></code> Gradle module. The Cash
contract uses <codeclass="docutils literal"><spanclass="pre">FungibleAsset</span></code> states to model holdings of
interchangeable assets and allow the split/merge and summing of
states to meet a contractual obligation. We would normally use the
<codeclass="docutils literal"><spanclass="pre">generateSpend</span></code> method on the <codeclass="docutils literal"><spanclass="pre">VaultService</span></code> to gather the required
amount of cash into a <codeclass="docutils literal"><spanclass="pre">TransactionBuilder</span></code>, set the outputs and move
command. However, to elucidate more clearly example flow code is shown
here that will manually carry out the inputs queries using the lower
<p>As a foreign exchange transaction we expect an exchange of two
currencies, so we will also require a set of input states from the other
counterparty. However, the Corda privacy model means we do not know the
other node’s states. Our flow must therefore negotiate with the other
node for them to carry out a similar query and populate the inputs (See
the <codeclass="docutils literal"><spanclass="pre">ForeignExchangeFlow</span></code> for more details of the exchange). Having
identified a set of Input <codeclass="docutils literal"><spanclass="pre">StateRef</span></code> items we can then create the
output as discussed below.</p>
<p>For the trade approval flow we need to implement a simple workflow
pattern. We start by recording the unconfirmed trade details in a state
object implementing the <codeclass="docutils literal"><spanclass="pre">LinearState</span></code> interface. One field of this
record is used to map the business workflow to an enumerated state.
Initially the initiator creates a new state object which receives a new
<codeclass="docutils literal"><spanclass="pre">UniqueIdentifier</span></code> in its <codeclass="docutils literal"><spanclass="pre">linearId</span></code> property and a starting
workflow state of <codeclass="docutils literal"><spanclass="pre">NEW</span></code>. The <codeclass="docutils literal"><spanclass="pre">Contract.verify</span></code> method is written to
allow the initiator to sign this initial transaction and send it to the
other party. This pattern ensures that a permanent copy is recorded on
both ledgers for audit purposes, but the state is prevented from being
maliciously put in an approved state. The subsequent workflow steps then
follow with transactions that consume the state as inputs on one side
and output a new version with whatever state updates, or amendments
match to the business process, the <codeclass="docutils literal"><spanclass="pre">linearId</span></code> being preserved across
the changes. Attached <codeclass="docutils literal"><spanclass="pre">Command</span></code> objects help the verify method
restrict changes to appropriate fields and signers at each step in the
workflow. In this it is typical to have both parties sign the change
transactions, but it can be valid to allow unilateral signing, if for instance
one side could block a rejection. Commonly the manual initiator of these
workflows will query the Vault for states of the right contract type and
in the right workflow state over the RPC interface. The RPC will then
initiate the relevant flow using <codeclass="docutils literal"><spanclass="pre">StateRef</span></code>, or <codeclass="docutils literal"><spanclass="pre">linearId</span></code> values as
parameters to the flow to identify the states being operated upon. Thus
code to gather the latest input state would be:</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span><spanclass="c1">// Pull in the latest Vault version of the StateRef as a full StateAndRef</span>
<h2>Building the WireTransaction<aclass="headerlink"href="#building-the-wiretransaction"title="Permalink to this headline">¶</a></h2>
<p>Having gathered all the ingredients for the transaction we now need to
use a <codeclass="docutils literal"><spanclass="pre">TransactionBuilder</span></code> to construct the full <codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code>.
The initial <codeclass="docutils literal"><spanclass="pre">TransactionBuilder</span></code> should be created by calling the
<codeclass="docutils literal"><spanclass="pre">TransactionType.General.Builder</span></code> method. (The other
<codeclass="docutils literal"><spanclass="pre">TransactionBuilder</span></code> implementation is only used for the <codeclass="docutils literal"><spanclass="pre">NotaryChange</span></code> flow where
<codeclass="docutils literal"><spanclass="pre">ContractStates</span></code> need moving to a different Notary.) At this point the
Notary to associate with the states should be recorded. Then we keep
adding inputs, outputs, commands and attachments to fill the
transaction. Examples of this process are:</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span><spanclass="c1">// Modify the state field for new output. We use copy, to ensure no other modifications.</span>
<spanclass="c1">// It is especially important for a LinearState that the linearId is copied across,</span>
<spanclass="c1">// not accidentally assigned a new random id.</span>
<h2>Completing the SignedTransaction<aclass="headerlink"href="#completing-the-signedtransaction"title="Permalink to this headline">¶</a></h2>
<p>Having created an initial <codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code> and converted this to an
initial <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> the process of verifying and forming a
full <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> begins and then completes with the
notarisation. In practice this is a relatively stereotypical process,
because assuming the <codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code> is correctly constructed the
verification should be immediate. However, it is also important to
recheck the business details of any data received back from an external
node, because a malicious party could always modify the contents before
returning the transaction. Each remote flow should therefore check as
much as possible of the initial <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> inside the <codeclass="docutils literal"><spanclass="pre">unwrap</span></code> of
the receive before agreeing to sign. Any issues should immediately throw
an exception to abort the flow. Similarly the originator, should always
apply any new signatures to its original proposal to ensure the contents
of the transaction has not been altered by the remote parties.</p>
<p>The typical code therefore checks the received <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code>
using the <codeclass="docutils literal"><spanclass="pre">verifySignatures</span></code> method, but excluding itself, the notary
and any other parties yet to apply their signature. The contents of the
<codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code> inside the <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> should be fully
verified further by expanding with <codeclass="docutils literal"><spanclass="pre">toLedgerTransaction</span></code> and calling
<codeclass="docutils literal"><spanclass="pre">verify</span></code>. Further context specific and business checks should then be
made, because the <codeclass="docutils literal"><spanclass="pre">Contract.verify</span></code> is not allowed to access external
context. For example the flow may need to check that the parties are the
right ones, or that the <codeclass="docutils literal"><spanclass="pre">Command</span></code> present on the transaction is as
expected for this specific flow. An example of this from the demo code is:</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span><spanclass="c1">// First we receive the verdict transaction signed by their single key</span>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span><spanclass="c1">// Run the FinalityFlow to notarise and distribute the completed transaction.</span>
<h2>Partially Visible Transactions<aclass="headerlink"href="#partially-visible-transactions"title="Permalink to this headline">¶</a></h2>
<p>The discussion so far has assumed that the parties need full visibility
of the transaction to sign. However, there may be situations where each
party needs to store private data for audit purposes, or for evidence to
a regulator, but does not wish to share that with the other trading
partner. The tear-off/Merkle tree support in Corda allows flows to send
portions of the full transaction to restrict visibility to remote
parties. To do this one can use the
<codeclass="docutils literal"><spanclass="pre">WireTransaction.buildFilteredTransaction</span></code> extension method to produce
a <codeclass="docutils literal"><spanclass="pre">FilteredTransaction</span></code>. The elements of the <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code>
which we wish to be hide will be replaced with their secure hash. The
overall transaction txid is still provable from the
<codeclass="docutils literal"><spanclass="pre">FilteredTransaction</span></code> preventing change of the private data, but we do
not expose that data to the other node directly. A full example of this
can be found in the <codeclass="docutils literal"><spanclass="pre">NodeInterestRates</span></code> Oracle code from the
<codeclass="docutils literal"><spanclass="pre">irs-demo</span></code> project which interacts with the <codeclass="docutils literal"><spanclass="pre">RatesFixFlow</span></code> flow.
Also, refer to the <aclass="reference internal"href="merkle-trees.html"><spanclass="doc">Transaction tear-offs</span></a> documentation.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
