<h1>Writing a contract using clauses<aclass="headerlink"href="#writing-a-contract-using-clauses"title="Permalink to this headline">¶</a></h1>
<p>This tutorial will take you through restructuring the commercial paper contract to use clauses. You should have
already completed “<aclass="reference internal"href="tutorial-contract.html"><spanclass="doc">Writing a contract</span></a>”.</p>
<p>Clauses are essentially micro-contracts which contain independent verification logic, and can be logically composed
together to form a contract. Clauses are designed to enable re-use of common logic, for example issuing state objects
is generally the same for all fungible contracts, so a common issuance clause can be inherited for each contract’s
issue clause. This cuts down on scope for error, and improves consistency of behaviour. By splitting verification logic
into smaller chunks, they can also be readily tested in isolation.</p>
<p>Clauses can be composed of subclauses, for example the <codeclass="docutils literal"><spanclass="pre">AllClause</span></code> or <codeclass="docutils literal"><spanclass="pre">AnyClause</span></code> clauses take list of clauses
that they delegate to. Clauses can also change the scope of states and commands being verified, for example grouping
together fungible state objects and running a clause against each distinct group.</p>
<p>The commercial paper contract has a <codeclass="docutils literal"><spanclass="pre">Group</span></code> outermost clause, which contains the <codeclass="docutils literal"><spanclass="pre">Issue</span></code>, <codeclass="docutils literal"><spanclass="pre">Move</span></code> and <codeclass="docutils literal"><spanclass="pre">Redeem</span></code>
clauses. The result is a contract that looks something like this:</p>
<blockquote>
<div><olclass="arabic">
<li><dlclass="first docutils">
<dt>Group input and output states together, and then apply the following clauses on each group:</dt>
<dd><olclass="first last loweralpha simple">
<li>If an <codeclass="docutils literal"><spanclass="pre">Issue</span></code> command is present, run appropriate tests and end processing this group.</li>
<li>If a <codeclass="docutils literal"><spanclass="pre">Move</span></code> command is present, run appropriate tests and end processing this group.</li>
<li>If a <codeclass="docutils literal"><spanclass="pre">Redeem</span></code> command is present, run appropriate tests and end processing this group.</li>
</ol>
</dd>
</dl>
</li>
</ol>
</div></blockquote>
<divclass="section"id="commercial-paper-class">
<h2>Commercial paper class<aclass="headerlink"href="#commercial-paper-class"title="Permalink to this headline">¶</a></h2>
<p>To use the clause verification logic, the contract needs to call the <codeclass="docutils literal"><spanclass="pre">verifyClause</span></code> function, passing in the
transaction, a clause to verify, and a collection of commands the clauses are expected to handle all of. This list of
commands is important because <codeclass="docutils literal"><spanclass="pre">verifyClause</span></code> checks that none of the commands are left unprocessed at the end, and
raises an error if they are. The top level clause would normally be a composite clause (such as <codeclass="docutils literal"><spanclass="pre">AnyComposition</span></code>,
<codeclass="docutils literal"><spanclass="pre">AllComposition</span></code>, etc.) which contains further clauses. The following examples are trimmed to the modified class
<h2>Clauses<aclass="headerlink"href="#clauses"title="Permalink to this headline">¶</a></h2>
<p>We’ll tackle the inner clauses that contain the bulk of the verification logic, first, and the clause which handles
grouping of input/output states later. The clauses must extend the <codeclass="docutils literal"><spanclass="pre">Clause</span></code> abstract class, which defines
the <codeclass="docutils literal"><spanclass="pre">verify</span></code> function, and the <codeclass="docutils literal"><spanclass="pre">requiredCommands</span></code> property used to determine the conditions under which a clause
is triggered. Composite clauses should extend the <codeclass="docutils literal"><spanclass="pre">CompositeClause</span></code> abstract class, which extends <codeclass="docutils literal"><spanclass="pre">Clause</span></code> to
add support for wrapping around multiple clauses.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">verify</span></code> function defined in the <codeclass="docutils literal"><spanclass="pre">Clause</span></code> interface is similar to the conventional <codeclass="docutils literal"><spanclass="pre">Contract</span></code> verification
function, although it adds new parameters and returns the set of commands which it has processed. Normally this returned
set is identical to the <codeclass="docutils literal"><spanclass="pre">requiredCommands</span></code> used to trigger the clause, however in some cases the clause may process
further optional commands which it needs to report that it has handled.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">Move</span></code> clause for the commercial paper contract is relatively simple, so we will start there:</p>
<spanclass="s">"the transaction is signed by the owner of the CP"</span><spanclass="k">by</span><spanclass="p">(</span><spanclass="n">input</span><spanclass="p">.</span><spanclass="n">owner</span><spanclass="k">in</span><spanclass="n">command</span><spanclass="p">.</span><spanclass="n">signers</span><spanclass="p">)</span>
<spanclass="s">"the state is propagated"</span><spanclass="k">by</span><spanclass="p">(</span><spanclass="n">outputs</span><spanclass="p">.</span><spanclass="n">size</span><spanclass="p">==</span><spanclass="m">1</span><spanclass="p">)</span>
<spanclass="c1">// Don't need to check anything else, as if outputs.size == 1 then the output is equal to</span>
<spanclass="c1">// the input ignoring the owner field due to the grouping.</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="n">IllegalStateException</span><spanclass="o">(</span><spanclass="s">"Failed requirement: the transaction is signed by the owner of the CP"</span><spanclass="o">);</span>
<spanclass="c1">// Check the output CP state is the same as the input state, ignoring the owner field.</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="n">IllegalStateException</span><spanclass="o">(</span><spanclass="s">"the state is propagated"</span><spanclass="o">);</span>
<spanclass="o">}</span>
<spanclass="c1">// Don't need to check anything else, as if outputs.size == 1 then the output is equal to</span>
<spanclass="c1">// the input ignoring the owner field due to the grouping.</span>
<p>We need to wrap the move clause (as well as the issue and redeem clauses - see the relevant contract code for their
full specifications) in an outer clause that understands how to group contract states and objects. For this we extend
the standard <codeclass="docutils literal"><spanclass="pre">GroupClauseVerifier</span></code> and specify how to group input/output states, as well as the top-level to run on
each group. As with the top level clause on a contract, this is normally a composite clause that delegates to subclauses.</p>
<p>For the <codeclass="docutils literal"><spanclass="pre">CommercialPaper</span></code> contract, this is the top level clause for the contract, and is passed directly into
<codeclass="docutils literal"><spanclass="pre">verifyClause</span></code> (see the example code at the top of this tutorial).</p>
</div>
<divclass="section"id="summary">
<h2>Summary<aclass="headerlink"href="#summary"title="Permalink to this headline">¶</a></h2>
<p>In summary the top level contract <codeclass="docutils literal"><spanclass="pre">CommercialPaper</span></code> specifies a single grouping clause of type
<codeclass="docutils literal"><spanclass="pre">CommercialPaper.Clauses.Group</span></code> which in turn specifies <codeclass="docutils literal"><spanclass="pre">GroupClause</span></code> implementations for each type of command
(<codeclass="docutils literal"><spanclass="pre">Redeem</span></code>, <codeclass="docutils literal"><spanclass="pre">Move</span></code> and <codeclass="docutils literal"><spanclass="pre">Issue</span></code>). This reflects the flow of verification: In order to verify a <codeclass="docutils literal"><spanclass="pre">CommercialPaper</span></code>
we first group states, check which commands are specified, and run command-specific verification logic accordingly.</p>
</div>
<divclass="section"id="debugging">
<h2>Debugging<aclass="headerlink"href="#debugging"title="Permalink to this headline">¶</a></h2>
<p>Debugging clauses which have been composed together can be complicated due to the difficulty in knowing which clauses
have been matched, whether specific clauses failed to match or passed verification, etc. There is “trace” level
logging code in the clause verifier which evaluates which clauses will be matched and logs them, before actually
performing the validation. To enable this, ensure trace level logging is enabled on the <codeclass="docutils literal"><spanclass="pre">Clause</span></code> interface.</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>.
