ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-22 22:32:26 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
f9c4c6eba7
corda/docs/build/html/clauses.html
Joel Dudley f9c4c6eba7 Rebuilds docs.
2017-02-08 16:08:46 +00:00

533 lines
39 KiB
HTML
Raw Blame History

<!-- If you edit this, then please make the same changes to layout_for_doc_website.html, as that is used for the web
doc site generation which we put analytics tracking on to identify any potential problem pages -->
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Clauses &mdash; R3 Corda latest documentation</title>
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
<link rel="next" title="Transaction tear-offs" href="merkle-trees.html"/>
<link rel="prev" title="Network Simulator" href="network-simulator.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> R3 Corda
</a>
<div class="version">
latest
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<br>
API reference: <a href="api/kotlin/corda/index.html">Kotlin</a>/ <a href="api/javadoc/index.html">JavaDoc</a>
<br>
<a href="https://discourse.corda.net">Discourse Forums</a>
<br>
<a href="http://slack.corda.net">Slack</a>
<br>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Getting started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up-fault-finding.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
<li class="toctree-l1"><a class="reference internal" href="CLI-vs-IDE.html">CLI vs IDE</a></li>
</ul>
<p class="caption"><span class="caption-text">Key concepts</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="key-concepts.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-ecosystem.html">Corda ecosystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-core-types.html">Core types</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-financial-model.html">Financial model</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-flow-framework.html">Flow framework</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-consensus-notaries.html">Consensus and notaries</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-vault.html">Vault</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-security-model.html">Security model</a></li>
</ul>
<p class="caption"><span class="caption-text">CorDapps</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html">CorDapp basics</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html">The example CorDapp</a></li>
</ul>
<p class="caption"><span class="caption-text">The Corda node</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-configuration-file.html">Node configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-plugins.html">The Corda plugin framework</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-services.html">Brief introduction to the node services</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-explorer.html">Node Explorer</a></li>
<li class="toctree-l1"><a class="reference internal" href="permissioning.html">Network permissioning</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract.html">Writing a contract</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract-clauses.html">Writing a contract using clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-test-dsl.html">Writing a contract test</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-integration-testing.html">Integration testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-building-transactions.html">Building transactions</a></li>
<li class="toctree-l1"><a class="reference internal" href="flow-state-machines.html">Writing flows</a></li>
<li class="toctree-l1"><a class="reference internal" href="flow-testing.html">Writing flow tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-a-notary.html">Running a notary service</a></li>
<li class="toctree-l1"><a class="reference internal" href="using-a-notary.html">Using a notary service</a></li>
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-attachments.html">Using attachments</a></li>
<li class="toctree-l1"><a class="reference internal" href="event-scheduling.html">Event scheduling</a></li>
</ul>
<p class="caption"><span class="caption-text">Other</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Clauses</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#basic-clause-structure">Basic clause structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="#composition-clauses">Composition clauses</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#allof">AllOf</a></li>
<li class="toctree-l3"><a class="reference internal" href="#anyof">AnyOf</a></li>
<li class="toctree-l3"><a class="reference internal" href="#firstof">FirstOf</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#other-types-of-clauses">Other types of clauses</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#groupclauseverifier">GroupClauseVerifier</a></li>
<li class="toctree-l3"><a class="reference internal" href="#abstractconserveamount">AbstractConserveAmount</a></li>
<li class="toctree-l3"><a class="reference internal" href="#abstractissue">AbstractIssue</a></li>
<li class="toctree-l3"><a class="reference internal" href="#nozerosizedoutputs">NoZeroSizedOutputs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#filteron">FilterOn</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction tear-offs</a></li>
</ul>
<p class="caption"><span class="caption-text">Component library</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest rate swaps</a></li>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="loadtesting.html">Load testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="setting-up-a-corda-network.html">What is a corda network?</a></li>
<li class="toctree-l1"><a class="reference internal" href="secure-coding-guidelines.html">Secure coding guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-process.html">Release process</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="further-notes-on-kotlin.html">Further notes on Kotlin</a></li>
<li class="toctree-l1"><a class="reference internal" href="publishing-corda.html">Publishing Corda</a></li>
<li class="toctree-l1"><a class="reference internal" href="azure-vm.html">Working with the Corda Demo on Azure Marketplace</a></li>
</ul>
<p class="caption"><span class="caption-text">Glossary</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">R3 Corda</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Clauses</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/clauses.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="clauses">
<h1>Clauses<a class="headerlink" href="#clauses" title="Permalink to this headline"></a></h1>
<div class="section" id="basic-clause-structure">
<h2>Basic clause structure<a class="headerlink" href="#basic-clause-structure" title="Permalink to this headline"></a></h2>
<p>A clause is a small building block for assembling contract verification logic, reusable and ready to test in separation.
To see clauses in action go to: <a class="reference internal" href="tutorial-contract-clauses.html"><span class="doc">Writing a contract using clauses</span></a>.
Let&#8217;s take a look at a simplified structure of the <code class="docutils literal"><span class="pre">Clause</span></code> class:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">abstract</span> <span class="k">class</span> <span class="nc">Clause</span><span class="p">&lt;</span><span class="k">in</span> <span class="n">S</span> <span class="p">:</span> <span class="n">ContractState</span><span class="p">,</span> <span class="n">C</span> <span class="p">:</span> <span class="n">CommandData</span><span class="p">,</span> <span class="k">in</span> <span class="n">K</span> <span class="p">:</span> <span class="n">Any</span><span class="p">&gt;</span> <span class="p">{</span>
<span class="cm">/** Determine whether this clause runs or not */</span>
<span class="k">open</span> <span class="k">val</span> <span class="py">requiredCommands</span><span class="p">:</span> <span class="n">Set</span><span class="p">&lt;</span><span class="n">Class</span><span class="p">&lt;</span><span class="k">out</span> <span class="n">CommandData</span><span class="p">&gt;&gt;</span> <span class="p">=</span> <span class="n">emptySet</span><span class="p">()</span>
<span class="n">@Throws</span><span class="p">(</span><span class="n">IllegalStateException</span><span class="o">::</span><span class="k">class</span><span class="p">)</span>
<span class="k">abstract</span> <span class="k">fun</span> <span class="nf">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForContract</span><span class="p">,</span>
<span class="n">inputs</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">S</span><span class="p">&gt;,</span>
<span class="n">outputs</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">S</span><span class="p">&gt;,</span>
<span class="n">commands</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">AuthenticatedObject</span><span class="p">&lt;</span><span class="n">C</span><span class="p">&gt;&gt;,</span>
<span class="n">groupingKey</span><span class="p">:</span> <span class="n">K</span><span class="p">?):</span> <span class="n">Set</span><span class="p">&lt;</span><span class="n">C</span><span class="p">&gt;</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>Basic clause structure contains two important components: <code class="docutils literal"><span class="pre">requiredCommands</span></code> and <code class="docutils literal"><span class="pre">verify</span></code> function.
A clause is triggered when all <code class="docutils literal"><span class="pre">requiredCommands</span></code> are present in transaction&#8217;s command set (opposite inclusion doesn&#8217;t have to hold).
Then the <code class="docutils literal"><span class="pre">verify</span></code> function is run, which checks if transaction meets conditions specified by this clause. Verification
is no different than normal contract verification but using clauses it&#8217;s split into smaller generic code blocks with single verify method.</p>
<p>When writing a contract you need to override the contract&#8217;s <code class="docutils literal"><span class="pre">verify</span></code> function which should call <code class="docutils literal"><span class="pre">verifyClause</span></code>. See: <a class="reference internal" href="tutorial-contract-clauses.html#verify-ref"><span class="std std-ref">Commercial paper class</span></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">A clause <code class="docutils literal"><span class="pre">verify</span></code> function returns the set of processed commands, at the end of <code class="docutils literal"><span class="pre">verifyClause</span></code> execution
there is a check if all of transaction&#8217;s commands were matched. If not, then an exception is raised. This is done to
enforce that spurious commands cannot be included in a transaction, ensuring that the transaction is as clear as
possible. As an example imagine a transaction with two commands: <code class="docutils literal"><span class="pre">Move</span></code> and <code class="docutils literal"><span class="pre">Issue</span></code> included, with verification written
using <code class="docutils literal"><span class="pre">FirstOf</span></code> on clauses that require single command set. Thus only one of transaction&#8217;s commands will match
leaving the second unprocessed. It should raise an error - we want to ensure that commands set is minimal to simplify
analysis of intent of a transaction.</p>
</div>
<p>An example <code class="docutils literal"><span class="pre">verify</span></code> from <code class="docutils literal"><span class="pre">Obligation</span></code> contract:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">override</span> <span class="k">fun</span> <span class="nf">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForContract</span><span class="p">)</span> <span class="p">=</span> <span class="n">verifyClause</span><span class="p">&lt;</span><span class="n">Commands</span><span class="p">&gt;(</span><span class="n">tx</span><span class="p">,</span> <span class="n">FirstOf</span><span class="p">&lt;</span><span class="n">ContractState</span><span class="p">,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Unit</span><span class="p">&gt;(</span>
<span class="n">Clauses</span><span class="p">.</span><span class="n">Net</span><span class="p">&lt;</span><span class="n">Commands</span><span class="p">,</span> <span class="n">P</span><span class="p">&gt;(),</span>
<span class="n">Clauses</span><span class="p">.</span><span class="n">Group</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;()</span>
<span class="p">),</span> <span class="n">tx</span><span class="p">.</span><span class="n">commands</span><span class="p">.</span><span class="n">select</span><span class="p">&lt;</span><span class="n">Obligation</span><span class="p">.</span><span class="n">Commands</span><span class="p">&gt;())</span>
</pre></div>
</div>
</div>
<p>It takes transaction to be verified, and passes it along with a top-level clause and commands to the <code class="docutils literal"><span class="pre">verifyClause</span></code>
function. As you can see above we have used <code class="docutils literal"><span class="pre">FirstOf</span></code> which is a special type of clause, which extends the
<code class="docutils literal"><span class="pre">CompositeClause</span></code> abstract class (in that particular case, it ensures that either <code class="docutils literal"><span class="pre">Net</span></code> or <code class="docutils literal"><span class="pre">Group</span></code> will run - for explanation see <a class="reference internal" href="#firstof">FirstOf</a>).
It&#8217;s a type of clause that adds support for encapsulating multiple clauses and defines common behaviour for that composition.
There is also a <code class="docutils literal"><span class="pre">GroupClauseVerifier</span></code> special clause, which specifies how to group transaction input/output states
together and passes them to adequate clause for further processing.</p>
</div>
<div class="section" id="composition-clauses">
<h2>Composition clauses<a class="headerlink" href="#composition-clauses" title="Permalink to this headline"></a></h2>
<p>One of the most important concepts of clauses - composition clauses which extend <code class="docutils literal"><span class="pre">CompositeClause</span></code> abstract class,
providing a range of ways of assembling clauses together. They define a logic of verification execution specifying which clauses
will be run.</p>
<div class="section" id="allof">
<h3>AllOf<a class="headerlink" href="#allof" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Composes a number of clauses, such that all of the clauses must run for verification to pass.</p>
<img alt="_images/allOfChart.png" src="_images/allOfChart.png" />
<p>Short description:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">AllOf</span></code> holds clauses <em>Cl1,..,Cl5</em>.</li>
<li>Check if all clauses that compose <code class="docutils literal"><span class="pre">AllOf</span></code> have associated commands in a command set - if not, verification fails.</li>
<li>After successful check runs verification logic specific for every clause <em>Cl1,..,Cl5</em> from that composition.</li>
</ul>
<p><strong>Usage</strong></p>
<p>See code in <a class="reference internal" href="#groupclauseverifier">GroupClauseVerifier</a>.</p>
</div>
<div class="section" id="anyof">
<h3>AnyOf<a class="headerlink" href="#anyof" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Composes a number of clauses, such that 1 or more of the clauses can be run.</p>
<img alt="_images/anyOfChart.png" src="_images/anyOfChart.png" />
<p>Short description:</p>
<ul class="simple">
<li>Checks if one or more clauses that compose AnyOf have associated commands in a command set.</li>
<li>After success runs verification logic specific for every <em>matched</em> (in this case <em>Cl2, Cl4, Cl5</em>) clause from composition.</li>
</ul>
<p><strong>Usage</strong></p>
<p>Example from <code class="docutils literal"><span class="pre">CommercialPaper.kt</span></code>:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Group</span> <span class="p">:</span> <span class="n">GroupClauseVerifier</span><span class="p">&lt;</span><span class="n">State</span><span class="p">,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&gt;&gt;(</span>
<span class="n">AnyOf</span><span class="p">(</span>
<span class="n">Redeem</span><span class="p">(),</span>
<span class="n">Move</span><span class="p">(),</span>
<span class="n">Issue</span><span class="p">()))</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">groupStates</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForContract</span><span class="p">):</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">TransactionForContract</span><span class="p">.</span><span class="n">InOutGroup</span><span class="p">&lt;</span><span class="n">State</span><span class="p">,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&gt;&gt;&gt;</span>
<span class="p">=</span> <span class="n">tx</span><span class="p">.</span><span class="n">groupStates</span><span class="p">&lt;</span><span class="n">State</span><span class="p">,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&gt;&gt;</span> <span class="p">{</span> <span class="n">it</span><span class="p">.</span><span class="n">token</span> <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="firstof">
<h3>FirstOf<a class="headerlink" href="#firstof" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Composes a number of clauses, such that the first match is run, and it errors if none is run.</p>
<img alt="_images/firstOfChart.png" src="_images/firstOfChart.png" />
<p>Short description:</p>
<ul class="simple">
<li>Takes first clause that matches and if none found throws an exception.</li>
<li>If successful runs verification on the clause that matched (in this case <em>Cl4</em>).</li>
</ul>
<p><strong>Usage</strong></p>
<p>See code in <a class="reference internal" href="#groupclauseverifier">GroupClauseVerifier</a>.</p>
</div>
</div>
<div class="section" id="other-types-of-clauses">
<h2>Other types of clauses<a class="headerlink" href="#other-types-of-clauses" title="Permalink to this headline"></a></h2>
<p>There are certain types of clauses that are specialized in particular types of contracts (like <code class="docutils literal"><span class="pre">AbstractIssue</span></code>) or generally
should be used as helpers in building parts of logic (the most important one is <code class="docutils literal"><span class="pre">GroupClauseVerifier</span></code>).</p>
<div class="section" id="groupclauseverifier">
<h3>GroupClauseVerifier<a class="headerlink" href="#groupclauseverifier" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Groups input and output states according to <code class="docutils literal"><span class="pre">groupStates</span></code> function. Runs the top-level clause verification on each
group in turn.</p>
<img alt="_images/groupClauseVerifyChart.png" src="_images/groupClauseVerifyChart.png" />
<p>Short description:</p>
<p><code class="docutils literal"><span class="pre">GroupClauseVerifier</span></code> wraps clause <em>Cl1</em>. After grouping relevant states together with <code class="docutils literal"><span class="pre">groupStates</span></code> into three groups
<em>Gr1, Gr2, Gr3</em> runs <em>Cl1.verify(Gr1), Cl1.verify(Gr2), Cl1.verify(Gr3)</em>.</p>
<p>For more detailed example head to <a class="reference internal" href="tutorial-contract.html#state-ref"><span class="std std-ref">Using state groups</span></a>.</p>
<p><strong>Usage</strong></p>
<p>You need to extend <code class="docutils literal"><span class="pre">GroupClauseVerifier</span></code> clause and define <code class="docutils literal"><span class="pre">groupStates</span></code> function which takes transaction and returns
grouped input and output states with a grouping key used for each group. Example from <code class="docutils literal"><span class="pre">Obligation.kt</span></code> contract:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Group</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;</span> <span class="p">:</span> <span class="n">GroupClauseVerifier</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;&gt;&gt;(</span>
<span class="n">AllOf</span><span class="p">(</span>
<span class="n">NoZeroSizedOutputs</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Terms</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;&gt;(),</span>
<span class="n">FirstOf</span><span class="p">(</span>
<span class="n">SetLifecycle</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;(),</span>
<span class="n">AllOf</span><span class="p">(</span>
<span class="n">VerifyLifecycle</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;&gt;,</span> <span class="n">P</span><span class="p">&gt;(),</span>
<span class="n">FirstOf</span><span class="p">(</span>
<span class="n">Settle</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;(),</span>
<span class="n">Issue</span><span class="p">(),</span>
<span class="n">ConserveAmount</span><span class="p">()</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="p">)</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">groupStates</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForContract</span><span class="p">):</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">TransactionForContract</span><span class="p">.</span><span class="n">InOutGroup</span><span class="p">&lt;</span><span class="n">Obligation</span><span class="p">.</span><span class="n">State</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;&gt;&gt;&gt;</span>
<span class="p">=</span> <span class="n">tx</span><span class="p">.</span><span class="n">groupStates</span><span class="p">&lt;</span><span class="n">Obligation</span><span class="p">.</span><span class="n">State</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;,</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;&gt;&gt;</span> <span class="p">{</span> <span class="n">it</span><span class="p">.</span><span class="n">amount</span><span class="p">.</span><span class="n">token</span> <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>Usually it&#8217;s convenient to use <code class="docutils literal"><span class="pre">groupStates</span></code> function defined on <code class="docutils literal"><span class="pre">TransactionForContract</span></code> class. Which given a type and a
selector function, that returns a grouping key, associates inputs and outputs together so that they can be processed as one.
The grouping key is any arbitrary object that can act as a map key (so must implement equals and hashCode).</p>
</div>
<div class="section" id="abstractconserveamount">
<h3>AbstractConserveAmount<a class="headerlink" href="#abstractconserveamount" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Standardised clause for checking input/output balances of fungible assets. Requires that a
Move command is provided, and errors if absent. Conserve amount clause can only be used on grouped states.</p>
<p><strong>Usage</strong></p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm"> * Generic move/exit clause for fungible assets</span>
<span class="cm"> */</span>
<span class="k">class</span> <span class="nc">ConserveAmount</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;</span> <span class="p">:</span> <span class="n">AbstractConserveAmount</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Terms</span><span class="p">&lt;</span><span class="n">P</span><span class="p">&gt;&gt;()</span>
</pre></div>
</div>
</div>
<p>See code in <a class="reference internal" href="#groupclauseverifier">GroupClauseVerifier</a>.</p>
</div>
<div class="section" id="abstractissue">
<h3>AbstractIssue<a class="headerlink" href="#abstractissue" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Standard issue clause for contracts that issue fungible assets.</p>
<p><strong>Usage</strong></p>
<p>Example from <code class="docutils literal"><span class="pre">CommercialPaper.kt</span></code>:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Issue</span> <span class="p">:</span> <span class="n">AbstractIssue</span><span class="p">&lt;</span><span class="n">State</span><span class="p">,</span> <span class="n">Commands</span><span class="p">,</span> <span class="n">Terms</span><span class="p">&gt;(</span>
<span class="p">{</span> <span class="n">map</span> <span class="p">{</span> <span class="n">Amount</span><span class="p">(</span><span class="n">it</span><span class="p">.</span><span class="n">faceValue</span><span class="p">.</span><span class="n">quantity</span><span class="p">,</span> <span class="n">it</span><span class="p">.</span><span class="n">token</span><span class="p">)</span> <span class="p">}.</span><span class="n">sumOrThrow</span><span class="p">()</span> <span class="p">},</span>
<span class="p">{</span> <span class="n">token</span> <span class="p">-&gt;</span> <span class="n">map</span> <span class="p">{</span> <span class="n">Amount</span><span class="p">(</span><span class="n">it</span><span class="p">.</span><span class="n">faceValue</span><span class="p">.</span><span class="n">quantity</span><span class="p">,</span> <span class="n">it</span><span class="p">.</span><span class="n">token</span><span class="p">)</span> <span class="p">}.</span><span class="n">sumOrZero</span><span class="p">(</span><span class="n">token</span><span class="p">)</span> <span class="p">})</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">val</span> <span class="py">requiredCommands</span><span class="p">:</span> <span class="n">Set</span><span class="p">&lt;</span><span class="n">Class</span><span class="p">&lt;</span><span class="k">out</span> <span class="n">CommandData</span><span class="p">&gt;&gt;</span> <span class="p">=</span> <span class="n">setOf</span><span class="p">(</span><span class="n">Commands</span><span class="p">.</span><span class="n">Issue</span><span class="o">::</span><span class="k">class</span><span class="p">.</span><span class="n">java</span><span class="p">)</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForContract</span><span class="p">,</span>
<span class="n">inputs</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&gt;,</span>
<span class="n">outputs</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&gt;,</span>
<span class="n">commands</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">AuthenticatedObject</span><span class="p">&lt;</span><span class="n">Commands</span><span class="p">&gt;&gt;,</span>
<span class="n">groupingKey</span><span class="p">:</span> <span class="n">Issued</span><span class="p">&lt;</span><span class="n">Terms</span><span class="p">&gt;?):</span> <span class="n">Set</span><span class="p">&lt;</span><span class="n">Commands</span><span class="p">&gt;</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">consumedCommands</span> <span class="p">=</span> <span class="k">super</span><span class="p">.</span><span class="n">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">,</span> <span class="n">inputs</span><span class="p">,</span> <span class="n">outputs</span><span class="p">,</span> <span class="n">commands</span><span class="p">,</span> <span class="n">groupingKey</span><span class="p">)</span>
<span class="p">...</span>
</pre></div>
</div>
</div>
<p>First function in constructor converts a list of states into an amount of the token. Must error if there are no states in the list.
Second function converts a list of states into an amount of the token, and returns zero if there are no states in the list.
Takes in an instance of the token definition for constructing the zero amount if needed.</p>
</div>
<div class="section" id="nozerosizedoutputs">
<h3>NoZeroSizedOutputs<a class="headerlink" href="#nozerosizedoutputs" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Clause for fungible asset contracts, which enforces that no output state should have a balance of zero.</p>
<p><strong>Usage</strong></p>
<p>See code in <a class="reference internal" href="#groupclauseverifier">GroupClauseVerifier</a>.</p>
</div>
<div class="section" id="filteron">
<h3>FilterOn<a class="headerlink" href="#filteron" title="Permalink to this headline"></a></h3>
<p><strong>Description</strong></p>
<p>Filter the states that are passed through to the wrapped clause, to restrict them to a specific type.</p>
<p><code class="docutils literal"><span class="pre">FilterOn</span></code> narrows the scope of the states being verified.
Let&#8217;s take a transaction with multiple cash states of different currencies, we want to run a clause that focuses
on only GBP cash states rather than all cash states.</p>
<p><strong>Usage</strong></p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">FilterOn</span><span class="p">(</span><span class="n">clause</span><span class="p">,</span> <span class="p">{</span> <span class="n">states</span> <span class="p">-&gt;</span> <span class="n">states</span><span class="p">.</span><span class="n">filter</span> <span class="p">{</span> <span class="n">it</span><span class="p">.</span><span class="n">amount</span><span class="p">.</span><span class="n">token</span> <span class="p">==</span> <span class="n">GBP</span><span class="p">}</span> <span class="p">})</span>
</pre></div>
</div>
</div>
<p>Takes <code class="docutils literal"><span class="pre">filterStates</span></code> function that limits states passed to <code class="docutils literal"><span class="pre">clause</span></code> verification.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="merkle-trees.html" class="btn btn-neutral float-right" title="Transaction tear-offs" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="network-simulator.html" class="btn btn-neutral" title="Network Simulator" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2016, R3 Limited.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink