<h2>How clauses work?<aclass="headerlink"href="#how-clauses-work"title="Permalink to this headline">¶</a></h2>
<p>We have different types of clauses, the most basic are the ones that define verification logic for particular command set.
We will see them later as elementary building blocks that commercial paper consist of - <codeclass="docutils literal"><spanclass="pre">Move</span></code>, <codeclass="docutils literal"><spanclass="pre">Issue</span></code> and <codeclass="docutils literal"><spanclass="pre">Redeem</span></code>.
As a developer you need to identify reusable parts of your contract and decide how they should be combined. It is where
composite clauses become useful. They gather many clause subcomponents and resolve how and which of them should be checked.</p>
<p>For example, assume that we want to verify a transaction using all constraints defined in separate clauses. We need to
wrap classes that define them into <codeclass="docutils literal"><spanclass="pre">AllComposition</span></code> composite clause. It assures that all clauses from that combination
match with commands in a transaction - only then verification logic can be executed.
It may be a little confusing, but composite clause is also a clause and you can even wrap it in the special grouping clause.
In <codeclass="docutils literal"><spanclass="pre">CommercialPaper</span></code> it looks like that:</p>
<p>The most basic types of composite clauses are <codeclass="docutils literal"><spanclass="pre">AllComposition</span></code>, <codeclass="docutils literal"><spanclass="pre">AnyComposition</span></code> and <codeclass="docutils literal"><spanclass="pre">FirstComposition</span></code>.
In this tutorial we will use <codeclass="docutils literal"><spanclass="pre">GroupClauseVerifier</span></code> and <codeclass="docutils literal"><spanclass="pre">AnyComposition</span></code>. It’s important to understand how they work.
Charts showing execution and more detailed information can be found in <aclass="reference internal"href="clauses.html"><spanclass="doc">Clauses</span></a>.</p>
<spanid="verify-ref"></span><h2>Commercial paper class<aclass="headerlink"href="#commercial-paper-class"title="Permalink to this headline">¶</a></h2>
<p>We start from defining <codeclass="docutils literal"><spanclass="pre">CommercialPaper</span></code> class. As in previous tutorial we need some elementary parts: <codeclass="docutils literal"><spanclass="pre">Commands</span></code> interface,
<codeclass="docutils literal"><spanclass="pre">generateMove</span></code>, <codeclass="docutils literal"><spanclass="pre">generateIssue</span></code>, <codeclass="docutils literal"><spanclass="pre">generateRedeem</span></code> - so far so good that stays the same. The new part is verification and
<codeclass="docutils literal"><spanclass="pre">Clauses</span></code> interface (you will see them later in code). Let’s start from the basic structure:</p>
<p>As you can see we used <codeclass="docutils literal"><spanclass="pre">verifyClause</span></code> function with <codeclass="docutils literal"><spanclass="pre">Clauses.Group()</span></code> in place of previous verification.
It’s an entry point to running clause logic. <codeclass="docutils literal"><spanclass="pre">verifyClause</span></code> takes the transaction, a clause (usually a composite one)
to verify, and a collection of commands the clause is 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.</p>
<h2>Simple Clauses<aclass="headerlink"href="#simple-clauses"title="Permalink to this headline">¶</a></h2>
<p>Let’s move to constructing contract logic in terms of clauses language. Commercial paper contract has three commands and
three corresponding behaviours: <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>. Each of them has a specific set of requirements that must be satisfied -
perfect material for defining clauses. For brevity we will show only <codeclass="docutils literal"><spanclass="pre">Move</span></code> clause, rest is constructed in similar manner
and included in the <codeclass="docutils literal"><spanclass="pre">CommercialPaper.kt</span></code> code.</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 took part of code for <codeclass="docutils literal"><spanclass="pre">Command.Move</span></code> verification from previous tutorial and put it into the verify function
of <codeclass="docutils literal"><spanclass="pre">Move</span></code> class. Notice that this class 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. In the above example it means that the clause will run verification when the <codeclass="docutils literal"><spanclass="pre">Commands.Move</span></code> is present in a transaction.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Notice that commands refer to all input and output states in a transaction. For clause to be executed, transaction has
to include all commands from <codeclass="docutils literal"><spanclass="pre">requiredCommands</span></code> set.</p>
</div>
<p>Few important changes:</p>
<ulclass="simple">
<li><codeclass="docutils literal"><spanclass="pre">verify</span></code> function 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.</li>
<li>Verification takes new parameters. Usually inputs and outputs are some subset of the original transaction entries
passed to the clause by outer composite or grouping clause. <codeclass="docutils literal"><spanclass="pre">groupingKey</span></code> is a key used to group original states.</li>
</ul>
<p>As a simple example imagine input states:</p>
<olclass="arabic simple">
<li>1000 GBP issued by Bank of England</li>
<li>500 GBP issued by Bank of England</li>
<li>1000 GBP issued by Bank of Scotland</li>
</ol>
<p>We will group states by Issuer so in the first group we have inputs 1 and 2, in second group input number 3. Grouping keys are:
‘GBP issued by Bank of England’ and ‘GBP issued by Bank of Scotland’.</p>
<p>How the states can be grouped and passed in that form to the <codeclass="docutils literal"><spanclass="pre">Move</span></code> clause? That leads us to the concept of <codeclass="docutils literal"><spanclass="pre">GroupClauseVerifier</span></code>.</p>
<p>We may have a transaction with similar but unrelated state evolutions which need to be validated independently. It
makes sense to check <codeclass="docutils literal"><spanclass="pre">Move</span></code> command on groups of related inputs and outputs (see example above). Thus, we need to collect
relevant states together.
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
clause to run on each group. In our example a top-level is a composite clause - <codeclass="docutils literal"><spanclass="pre">AnyCompostion</span></code> that delegates verification to
it’s subclasses (wrapped move, issue, redeem). Any in this case means that it will take 0 or more clauses that match transaction commands.</p>
<p>For the <codeclass="docutils literal"><spanclass="pre">CommercialPaper</span></code> contract, <codeclass="docutils literal"><spanclass="pre">Group</span></code> is the main 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). We used <codeclass="docutils literal"><spanclass="pre">groupStates</span></code> function here, it’s worth reminding
how it works: <aclass="reference internal"href="tutorial-contract.html#state-ref"><spanclass="std std-ref">Using state groups</span></a>.</p>
<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>
<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>.
