mirror of
https://github.com/corda/corda.git
synced 2025-06-12 20:28:18 +00:00
Docs: regenerate the HTML
This commit is contained in:
Mike Hearn
262
docs/build/html/tutorial.html
vendored
262
docs/build/html/tutorial.html
vendored
@ -92,6 +92,9 @@
|
||||
<li class="toctree-l2"><a class="reference internal" href="#the-verify-function">The verify function</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#understanding-fungibility">Understanding fungibility</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#checking-the-requirements">Checking the requirements</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#how-to-test-your-contract">How to test your contract</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#adding-a-crafting-api-to-your-contract">Adding a crafting API to your contract</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#non-asset-oriented-based-smart-contracts">Non-asset-oriented based smart contracts</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="roadmap.html">Roadmap</a></li>
|
||||
@ -148,7 +151,9 @@
|
||||
for how Kotlin syntax works.</p>
|
||||
<div class="section" id="starting-the-commercial-paper-class">
|
||||
<h2>Starting the commercial paper class<a class="headerlink" href="#starting-the-commercial-paper-class" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A smart contract is a class that implements the <code class="docutils literal"><span class="pre">Contract</span></code> interface. Therefore, we start like this:</p>
|
||||
<p>A smart contract is a class that implements the <code class="docutils literal"><span class="pre">Contract</span></code> interface. For now, they have to be a part of the main
|
||||
codebase, as dynamic loading of contract code is not yet implemented. Therefore, we start by creating a file named
|
||||
either <cite>CommercialPaper.kt</cite> or <cite>CommercialPaper.java</cite> in the src/contracts directory with the following contents:</p>
|
||||
<div class="codeset container">
|
||||
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommercialPaper</span> <span class="p">:</span> <span class="n">Contract</span> <span class="p">{</span>
|
||||
<span class="k">override</span> <span class="k">val</span> <span class="py">legalContractReference</span><span class="p">:</span> <span class="n">SecureHash</span> <span class="p">=</span> <span class="n">SecureHash</span><span class="p">.</span><span class="n">sha256</span><span class="p">(</span><span class="s">"https://en.wikipedia.org/wiki/Commercial_paper"</span><span class="p">);</span>
|
||||
@ -277,7 +282,10 @@ Beyond that it’s a freeform object into which we can put anything which ca
|
||||
<ul class="simple">
|
||||
<li><cite>issuance</cite>: a reference to a specific piece of commercial paper at an institution</li>
|
||||
<li><cite>owner</cite>: the public key of the current owner. This is the same concept as seen in Bitcoin: the public key has no
|
||||
attached identity and is expected to be one-time-use for privacy reasons.</li>
|
||||
attached identity and is expected to be one-time-use for privacy reasons. However, unlike in Bitcoin, we model
|
||||
ownership at the level of individual contracts rather than as a platform-level concept as we envisage many
|
||||
(possibly most) contracts on the platform will not represent “owner/issuer” relationships, but “party/party”
|
||||
relationships such as a derivative contract.</li>
|
||||
<li><cite>faceValue</cite>: an <cite>Amount</cite>, which wraps an integer number of pennies and a currency.</li>
|
||||
<li><cite>maturityDate</cite>: an <cite>Instant <https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html></cite>, which is a type
|
||||
from the Java 8 standard time library. It defines a point on the timeline.</li>
|
||||
@ -299,26 +307,34 @@ checked, so from the contract code’s perspective, a command is simply a da
|
||||
public keys. Each key had a signature proving that the corresponding private key was used to sign.</p>
|
||||
<p>Let’s define a couple of commands now:</p>
|
||||
<div class="codeset container">
|
||||
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">sealed</span> <span class="k">class</span> <span class="nc">Commands</span> <span class="p">:</span> <span class="n">Command</span> <span class="p">{</span>
|
||||
<span class="k">object</span> <span class="nc">Move</span> <span class="p">:</span> <span class="n">Commands</span><span class="p">()</span>
|
||||
<span class="k">object</span> <span class="nc">Redeem</span> <span class="p">:</span> <span class="n">Commands</span><span class="p">()</span>
|
||||
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">interface</span> <span class="n">Commands</span> <span class="p">:</span> <span class="n">Command</span> <span class="p">{</span>
|
||||
<span class="k">object</span> <span class="nc">Move</span> <span class="p">:</span> <span class="n">Commands</span>
|
||||
<span class="k">object</span> <span class="nc">Redeem</span> <span class="p">:</span> <span class="n">Commands</span>
|
||||
<span class="k">object</span> <span class="nc">Issue</span> <span class="p">:</span> <span class="n">Commands</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Commands</span> <span class="kd">implements</span> <span class="n">core</span><span class="o">.</span><span class="na">Command</span> <span class="o">{</span>
|
||||
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Move</span> <span class="kd">extends</span> <span class="n">Commands</span> <span class="o">{</span>
|
||||
<span class="nd">@Override</span>
|
||||
<span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">equals</span><span class="o">(</span><span class="n">Object</span> <span class="n">obj</span><span class="o">)</span> <span class="o">{</span>
|
||||
<span class="k">return</span> <span class="n">obj</span> <span class="k">instanceof</span> <span class="n">Move</span><span class="o">;</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Move</span> <span class="kd">extends</span> <span class="n">Commands</span> <span class="o">{</span>
|
||||
<span class="nd">@Override</span>
|
||||
<span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">equals</span><span class="o">(</span><span class="n">Object</span> <span class="n">obj</span><span class="o">)</span> <span class="o">{</span>
|
||||
<span class="k">return</span> <span class="n">obj</span> <span class="k">instanceof</span> <span class="n">Move</span><span class="o">;</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
|
||||
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Redeem</span> <span class="kd">extends</span> <span class="n">Commands</span> <span class="o">{</span>
|
||||
<span class="nd">@Override</span>
|
||||
<span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">equals</span><span class="o">(</span><span class="n">Object</span> <span class="n">obj</span><span class="o">)</span> <span class="o">{</span>
|
||||
<span class="k">return</span> <span class="n">obj</span> <span class="k">instanceof</span> <span class="n">Redeem</span><span class="o">;</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Redeem</span> <span class="kd">extends</span> <span class="n">Commands</span> <span class="o">{</span>
|
||||
<span class="nd">@Override</span>
|
||||
<span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">equals</span><span class="o">(</span><span class="n">Object</span> <span class="n">obj</span><span class="o">)</span> <span class="o">{</span>
|
||||
<span class="k">return</span> <span class="n">obj</span> <span class="k">instanceof</span> <span class="n">Redeem</span><span class="o">;</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
|
||||
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Issue</span> <span class="kd">extends</span> <span class="n">Commands</span> <span class="o">{</span>
|
||||
<span class="nd">@Override</span>
|
||||
<span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">equals</span><span class="o">(</span><span class="n">Object</span> <span class="n">obj</span><span class="o">)</span> <span class="o">{</span>
|
||||
<span class="k">return</span> <span class="n">obj</span> <span class="k">instanceof</span> <span class="n">Redeem</span><span class="o">;</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
@ -368,11 +384,16 @@ exception if there’s zero or more than one such command.</p>
|
||||
<p>We say states are <em>fungible</em> if they are treated identically to each other by the recipient, despite the fact that they
|
||||
aren’t quite identical. Dollar bills are fungible because even though one may be worn/a bit dirty and another may
|
||||
be crisp and new, they are still both worth exactly $1. Likewise, ten $1 bills are almost exactly equivalent to
|
||||
one $10 bill. On the other hand, $10 and £10 are not fungible: if you tried to pay for something that cost $20 with
|
||||
one $10 bill. On the other hand, $10 and £10 are not fungible: if you tried to pay for something that cost £20 with
|
||||
$10+£10 notes your trade would not be accepted.</p>
|
||||
<p>So whilst our ledger could represent every monetary amount with a collection of states worth one penny, this would become
|
||||
extremely unwieldy. It’s better to allow states to represent varying amounts and then define rules for merging them
|
||||
and splitting them.</p>
|
||||
and splitting them. Similarly, we could also have considered modelling cash as a single contract that records the
|
||||
ownership of all holders of a given currency from a given issuer. Whilst this is possible, and is effectively how
|
||||
some other platforms work, this prototype favours a design that doesn’t necessarily require state to be shared between
|
||||
multiple actors if they don’t have a direct relationship with each other (as would implicitly be required if we had a
|
||||
single state representing multiple people’s ownership). Keeping the states separated also has scalability benefits, as
|
||||
different parts of the global transaction graph can be updated in parallel.</p>
|
||||
<p>To make this easier the contract API provides a notion of groups. A group is a set of input states and output states
|
||||
that should be checked for validity independently. It solves the following problem: because every contract sees every
|
||||
input and output state in a transaction, it would easy to accidentally write a contract that disallows useful
|
||||
@ -423,6 +444,21 @@ logic.</p>
|
||||
<span class="s">"the paper must be destroyed"</span> <span class="k">by</span> <span class="p">(</span><span class="n">output</span> <span class="p">==</span> <span class="k">null</span><span class="p">)</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="k">is</span> <span class="n">Commands</span><span class="p">.</span><span class="n">Issue</span> <span class="p">-></span> <span class="p">{</span>
|
||||
<span class="k">val</span> <span class="py">output</span> <span class="p">=</span> <span class="n">group</span><span class="p">.</span><span class="n">outputs</span><span class="p">.</span><span class="n">single</span><span class="p">()</span>
|
||||
<span class="n">requireThat</span> <span class="p">{</span>
|
||||
<span class="c1">// Don't allow people to issue commercial paper under other entities identities.</span>
|
||||
<span class="s">"the issuance is signed by the claimed issuer of the paper"</span> <span class="k">by</span>
|
||||
<span class="p">(</span><span class="n">command</span><span class="p">.</span><span class="n">signers</span><span class="p">.</span><span class="n">contains</span><span class="p">(</span><span class="n">output</span><span class="p">.</span><span class="n">issuance</span><span class="p">.</span><span class="n">institution</span><span class="p">.</span><span class="n">owningKey</span><span class="p">))</span>
|
||||
<span class="s">"the face value is not zero"</span> <span class="k">by</span> <span class="p">(</span><span class="n">output</span><span class="p">.</span><span class="n">faceValue</span><span class="p">.</span><span class="n">pennies</span> <span class="p">></span> <span class="m">0</span><span class="p">)</span>
|
||||
<span class="s">"the maturity date is not in the past"</span> <span class="k">by</span> <span class="p">(</span><span class="n">output</span><span class="p">.</span><span class="n">maturityDate</span> <span class="p">></span> <span class="n">tx</span><span class="p">.</span><span class="n">time</span><span class="p">)</span>
|
||||
<span class="c1">// Don't allow an existing CP state to be replaced by this issuance.</span>
|
||||
<span class="s">"there is no input state"</span> <span class="k">by</span> <span class="n">group</span><span class="p">.</span><span class="n">inputs</span><span class="p">.</span><span class="n">isEmpty</span><span class="p">()</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="k">else</span> <span class="p">-></span> <span class="k">throw</span> <span class="n">IllegalArgumentException</span><span class="p">(</span><span class="s">"Unrecognised command"</span><span class="p">)</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
@ -455,6 +491,8 @@ logic.</p>
|
||||
<span class="k">throw</span> <span class="k">new</span> <span class="n">IllegalStateException</span><span class="o">(</span><span class="s">"Failed requirement: the received amount equals the face value"</span><span class="o">);</span>
|
||||
<span class="k">if</span> <span class="o">(!</span><span class="n">outputs</span><span class="o">.</span><span class="na">isEmpty</span><span class="o">())</span>
|
||||
<span class="k">throw</span> <span class="k">new</span> <span class="n">IllegalStateException</span><span class="o">(</span><span class="s">"Failed requirement: the paper must be destroyed"</span><span class="o">);</span>
|
||||
<span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">cmd</span><span class="o">.</span><span class="na">getValue</span><span class="o">()</span> <span class="k">instanceof</span> <span class="n">JavaCommercialPaper</span><span class="o">.</span><span class="na">Commands</span><span class="o">.</span><span class="na">Issue</span><span class="o">)</span> <span class="o">{</span>
|
||||
<span class="c1">// .. etc .. (see Kotlin for full definition)</span>
|
||||
<span class="o">}</span>
|
||||
<span class="o">}</span>
|
||||
</pre></div>
|
||||
@ -498,6 +536,8 @@ no such states <em>or</em> if there were different currencies represented in the
|
||||
imposes a limitation on the structure of a redemption transaction: you are not allowed to move currencies in the same
|
||||
transaction that the CP does not involve. This limitation could be addressed with better APIs, if it were to be a
|
||||
real limitation.</p>
|
||||
<p>Finally, we support an <cite>Issue</cite> command, to create new instances of commercial paper on the ledger. It likewise
|
||||
enforces various invariants upon the issuance.</p>
|
||||
<p>This contract is extremely simple and does not implement all the business logic a real commercial paper lifecycle
|
||||
management program would. For instance, there is no logic requiring a signature from the issuer for redemption:
|
||||
it is assumed that any transfer of money that takes place at the same time as redemption is good enough. Perhaps
|
||||
@ -506,6 +546,190 @@ bankrupt, if there is a dispute, and so on.</p>
|
||||
<p>As the prototype evolves, these requirements will be explored and this tutorial updated to reflect improvements in the
|
||||
contracts API.</p>
|
||||
</div>
|
||||
<div class="section" id="how-to-test-your-contract">
|
||||
<h2>How to test your contract<a class="headerlink" href="#how-to-test-your-contract" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Of course, it is essential to unit test your new nugget of business logic to ensure that it behaves as you expect.
|
||||
Although you can write traditional unit tests in Java, the platform also provides a <em>domain specific language</em>
|
||||
(DSL) for writing contract unit tests that automates many of the common patterns. This DSL builds on top of JUnit yet
|
||||
is a Kotlin DSL, and therefore this section will not show Java equivalent code (for Java unit tests you would not
|
||||
benefit from the DSL and would write them by hand).</p>
|
||||
<p>We start by defining a new test class, with a basic CP state:</p>
|
||||
<div class="codeset container">
|
||||
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommercialPaperTests</span> <span class="p">{</span>
|
||||
<span class="k">val</span> <span class="py">PAPER_1</span> <span class="p">=</span> <span class="n">CommercialPaper</span><span class="p">.</span><span class="n">State</span><span class="p">(</span>
|
||||
<span class="n">issuance</span> <span class="p">=</span> <span class="n">InstitutionReference</span><span class="p">(</span><span class="n">MEGA_CORP</span><span class="p">,</span> <span class="n">OpaqueBytes</span><span class="p">.</span><span class="n">of</span><span class="p">(</span><span class="m">123</span><span class="p">)),</span>
|
||||
<span class="n">owner</span> <span class="p">=</span> <span class="n">MEGA_CORP_KEY</span><span class="p">,</span>
|
||||
<span class="n">faceValue</span> <span class="p">=</span> <span class="m">1000.</span><span class="n">DOLLARS</span><span class="p">,</span>
|
||||
<span class="n">maturityDate</span> <span class="p">=</span> <span class="n">TEST_TX_TIME</span> <span class="p">+</span> <span class="m">7.</span><span class="n">days</span>
|
||||
<span class="p">)</span>
|
||||
|
||||
<span class="n">@Test</span>
|
||||
<span class="k">fun</span> <span class="nf">key_mismatch_at_issue</span><span class="p">()</span> <span class="p">{</span>
|
||||
<span class="n">transactionGroup</span> <span class="p">{</span>
|
||||
<span class="n">transaction</span> <span class="p">{</span>
|
||||
<span class="n">output</span> <span class="p">{</span> <span class="n">PAPER_1</span> <span class="p">}</span>
|
||||
<span class="n">arg</span><span class="p">(</span><span class="n">DUMMY_PUBKEY_1</span><span class="p">)</span> <span class="p">{</span> <span class="n">CommercialPaper</span><span class="p">.</span><span class="n">Commands</span><span class="p">.</span><span class="n">Issue</span><span class="p">()</span> <span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="n">expectFailureOfTx</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="s">"signed by the claimed issuer"</span><span class="p">)</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p>We start by defining a commercial paper state. It will be owned by a pre-defined unit test institution, affectionately
|
||||
called <cite>MEGA_CORP</cite> (this constant, along with many others, is defined in <cite>TestUtils.kt</cite>). Due to Kotin’s extensive
|
||||
type inference, many types are not written out explicitly in this code and it has the feel of a scripting language.
|
||||
But the types are there, and you can ask IntelliJ to reveal them by pressing Alt-Enter on a “val” or “var” and selecting
|
||||
“Specify type explicitly”.</p>
|
||||
<p>There are a few things that are unusual here:</p>
|
||||
<ul class="simple">
|
||||
<li>We can specify quantities of money by writing 1000.DOLLARS or 1000.POUNDS</li>
|
||||
<li>We can specify quantities of time by writing 7.days</li>
|
||||
<li>We can add quantities of time to the TEST_TX_TIME constant, which merely defines an arbitrary java.time.Instant</li>
|
||||
</ul>
|
||||
<p>If you examine the code in the actual repository, you will also notice that it makes use of method names with spaces
|
||||
in them by surrounding the name with backticks, rather than using underscores. We don’t show this here as it breaks the
|
||||
doc website’s syntax highlighting engine.</p>
|
||||
<p>The <cite>1000.DOLLARS</cite> construct is quite simple: Kotlin allows you to define extension functions on primitive types like
|
||||
Int or Double. So by writing 7.days, for instance, the compiler will emit a call to a static method that takes an int
|
||||
and returns a <cite>java.time.Duration</cite>.</p>
|
||||
<p>As this is JUnit, we must remember to annotate each test method with @Test. Let’s examine the contents of the first test.
|
||||
We are trying to check that it’s not possible for just anyone to issue commercial paper in MegaCorp’s name. That would
|
||||
be bad!</p>
|
||||
<p>The <cite>transactionGroup</cite> function works the same way as the <cite>requireThat</cite> construct above. It is an example of what
|
||||
Kotlin calls a type safe builder, which you can read about in <a class="reference external" href="https://kotlinlang.org/docs/reference/type-safe-builders.html">the documentation for builders</a>.
|
||||
The code block that follows it is run in the scope of a freshly created <cite>TransactionGroupForTest</cite> object, which assists
|
||||
you with building little transaction graphs and verifying them as a whole. Here, our “group” only actually has a
|
||||
single transaction in it, with a single output, no inputs, and an Issue command signed by <cite>DUMMY_PUBKEY_1</cite> which is just
|
||||
an arbitrary public key. As the paper claims to be issued by <cite>MEGA_CORP</cite>, this doesn’t match and should cause a
|
||||
failure. The <cite>expectFailureOfTx</cite> method takes a 1-based index (in this case we expect the first transaction to fail)
|
||||
and a string that should appear in the exception message. Then it runs the <cite>TransactionGroup.verify()</cite> method to
|
||||
invoke all the involved contracts.</p>
|
||||
<p>It’s worth bearing in mind that even though this code may look like a totally different language to normal Kotlin or
|
||||
Java, it’s actually not, and so you can embed arbitrary code anywhere inside any of these blocks.</p>
|
||||
<p>Let’s set up a full trade and ensure it works:</p>
|
||||
<div class="codeset container">
|
||||
<div class="highlight-kotlin"><div class="highlight"><pre> <span class="c1">// Generate a trade lifecycle with various parameters.</span>
|
||||
<span class="k">private</span> <span class="k">fun</span> <span class="nf">trade</span><span class="p">(</span><span class="n">redemptionTime</span><span class="p">:</span> <span class="n">Instant</span> <span class="p">=</span> <span class="n">TEST_TX_TIME</span> <span class="p">+</span> <span class="m">8.</span><span class="n">days</span><span class="p">,</span>
|
||||
<span class="n">aliceGetsBack</span><span class="p">:</span> <span class="n">Amount</span> <span class="p">=</span> <span class="m">1000.</span><span class="n">DOLLARS</span><span class="p">,</span>
|
||||
<span class="n">destroyPaperAtRedemption</span><span class="p">:</span> <span class="n">Boolean</span> <span class="p">=</span> <span class="k">true</span><span class="p">):</span> <span class="n">TransactionGroupForTest</span> <span class="p">{</span>
|
||||
<span class="k">val</span> <span class="py">someProfits</span> <span class="p">=</span> <span class="m">1200.</span><span class="n">DOLLARS</span>
|
||||
<span class="k">return</span> <span class="n">transactionGroup</span> <span class="p">{</span>
|
||||
<span class="n">roots</span> <span class="p">{</span>
|
||||
<span class="n">transaction</span><span class="p">(</span><span class="m">900.</span><span class="n">DOLLARS</span><span class="p">.</span><span class="n">CASH</span> <span class="n">owned_by</span> <span class="n">ALICE</span> <span class="n">label</span> <span class="s">"alice's $900"</span><span class="p">)</span>
|
||||
<span class="n">transaction</span><span class="p">(</span><span class="n">someProfits</span><span class="p">.</span><span class="n">CASH</span> <span class="n">owned_by</span> <span class="n">MEGA_CORP_KEY</span> <span class="n">label</span> <span class="s">"some profits"</span><span class="p">)</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="c1">// Some CP is issued onto the ledger by MegaCorp.</span>
|
||||
<span class="n">transaction</span> <span class="p">{</span>
|
||||
<span class="n">output</span><span class="p">(</span><span class="s">"paper"</span><span class="p">)</span> <span class="p">{</span> <span class="n">PAPER_1</span> <span class="p">}</span>
|
||||
<span class="n">arg</span><span class="p">(</span><span class="n">MEGA_CORP_KEY</span><span class="p">)</span> <span class="p">{</span> <span class="n">CommercialPaper</span><span class="p">.</span><span class="n">Commands</span><span class="p">.</span><span class="n">Issue</span><span class="p">()</span> <span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="c1">// The CP is sold to alice for her $900, $100 less than the face value. At 10% interest after only 7 days,</span>
|
||||
<span class="c1">// that sounds a bit too good to be true!</span>
|
||||
<span class="n">transaction</span> <span class="p">{</span>
|
||||
<span class="n">input</span><span class="p">(</span><span class="s">"paper"</span><span class="p">)</span>
|
||||
<span class="n">input</span><span class="p">(</span><span class="s">"alice's $900"</span><span class="p">)</span>
|
||||
<span class="n">output</span> <span class="p">{</span> <span class="m">900.</span><span class="n">DOLLARS</span><span class="p">.</span><span class="n">CASH</span> <span class="n">owned_by</span> <span class="n">MEGA_CORP_KEY</span> <span class="p">}</span>
|
||||
<span class="n">output</span><span class="p">(</span><span class="s">"alice's paper"</span><span class="p">)</span> <span class="p">{</span> <span class="n">PAPER_1</span> <span class="n">owned_by</span> <span class="n">ALICE</span> <span class="p">}</span>
|
||||
<span class="n">arg</span><span class="p">(</span><span class="n">ALICE</span><span class="p">)</span> <span class="p">{</span> <span class="n">Cash</span><span class="p">.</span><span class="n">Commands</span><span class="p">.</span><span class="n">Move</span> <span class="p">}</span>
|
||||
<span class="n">arg</span><span class="p">(</span><span class="n">MEGA_CORP_KEY</span><span class="p">)</span> <span class="p">{</span> <span class="n">CommercialPaper</span><span class="p">.</span><span class="n">Commands</span><span class="p">.</span><span class="n">Move</span> <span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="c1">// Time passes, and Alice redeem's her CP for $1000, netting a $100 profit. MegaCorp has received $1200</span>
|
||||
<span class="c1">// as a single payment from somewhere and uses it to pay Alice off, keeping the remaining $200 as change.</span>
|
||||
<span class="n">transaction</span><span class="p">(</span><span class="n">time</span> <span class="p">=</span> <span class="n">redemptionTime</span><span class="p">)</span> <span class="p">{</span>
|
||||
<span class="n">input</span><span class="p">(</span><span class="s">"alice's paper"</span><span class="p">)</span>
|
||||
<span class="n">input</span><span class="p">(</span><span class="s">"some profits"</span><span class="p">)</span>
|
||||
|
||||
<span class="n">output</span> <span class="p">{</span> <span class="n">aliceGetsBack</span><span class="p">.</span><span class="n">CASH</span> <span class="n">owned_by</span> <span class="n">ALICE</span> <span class="p">}</span>
|
||||
<span class="n">output</span> <span class="p">{</span> <span class="p">(</span><span class="n">someProfits</span> <span class="p">-</span> <span class="n">aliceGetsBack</span><span class="p">).</span><span class="n">CASH</span> <span class="n">owned_by</span> <span class="n">MEGA_CORP_KEY</span> <span class="p">}</span>
|
||||
<span class="k">if</span> <span class="p">(!</span><span class="n">destroyPaperAtRedemption</span><span class="p">)</span>
|
||||
<span class="n">output</span> <span class="p">{</span> <span class="n">PAPER_1</span> <span class="n">owned_by</span> <span class="n">ALICE</span> <span class="p">}</span>
|
||||
|
||||
<span class="n">arg</span><span class="p">(</span><span class="n">MEGA_CORP_KEY</span><span class="p">)</span> <span class="p">{</span> <span class="n">Cash</span><span class="p">.</span><span class="n">Commands</span><span class="p">.</span><span class="n">Move</span> <span class="p">}</span>
|
||||
<span class="n">arg</span><span class="p">(</span><span class="n">ALICE</span><span class="p">)</span> <span class="p">{</span> <span class="n">CommercialPaper</span><span class="p">.</span><span class="n">Commands</span><span class="p">.</span><span class="n">Redeem</span> <span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p>In this example we see some new features of the DSL:</p>
|
||||
<ul class="simple">
|
||||
<li>The <cite>roots</cite> construct. Sometimes you don’t want to write transactions that laboriously issue everything you need
|
||||
in a formally correct way. Inside <cite>roots</cite> you can create a bunch of states without any contract checking what you’re
|
||||
doing. As states may not exist outside of transactions, each line inside defines a fake/invalid transaction with the
|
||||
given output states, which may be <em>labelled</em> with a short string. Those labels can be used later to join transactions
|
||||
together.</li>
|
||||
<li>The <cite>.CASH</cite> suffix. This is a part of the unit test DSL specific to the cash contract. It takes a monetary amount
|
||||
like 1000.DOLLARS and then wraps it in a cash ledger state, with some fake data.</li>
|
||||
<li>The owned_by <a class="reference external" href="https://kotlinlang.org/docs/reference/functions.html#infix-notation">infix function</a>. This is just
|
||||
a normal function that we’re allowed to write in a slightly different way, which returns a copy of the cash state
|
||||
with the owner field altered to be the given public key. <cite>ALICE</cite> is a constant defined by the test utilities that
|
||||
is, like <cite>DUMMY_PUBKEY_1</cite>, just an arbitrary keypair.</li>
|
||||
<li>We are now defining several transactions that chain together. We can optionally label any output we create. Obviously
|
||||
then, the <cite>input</cite> method requires us to give the label of some other output that it connects to.</li>
|
||||
<li>The <cite>transaction</cite> function can also be given a time, to override the default timestamp on a transaction.</li>
|
||||
</ul>
|
||||
<p>The <cite>trade</cite> function is not itself a unit test. Instead it builds up a trade/transaction group, with some slight
|
||||
differences depending on the parameters provided (Kotlin allows parameters to have default valus). Then it returns
|
||||
it, unexecuted.</p>
|
||||
<p>We use it like this:</p>
|
||||
<div class="codeset container">
|
||||
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">@Test</span>
|
||||
<span class="k">fun</span> <span class="nf">ok</span><span class="p">()</span> <span class="p">{</span>
|
||||
<span class="n">trade</span><span class="p">().</span><span class="n">verify</span><span class="p">()</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="n">@Test</span>
|
||||
<span class="k">fun</span> <span class="nf">not_matured_at_redemption</span><span class="p">()</span> <span class="p">{</span>
|
||||
<span class="n">trade</span><span class="p">(</span><span class="n">redemptionTime</span> <span class="p">=</span> <span class="n">TEST_TX_TIME</span> <span class="p">+</span> <span class="m">2.</span><span class="n">days</span><span class="p">).</span><span class="n">expectFailureOfTx</span><span class="p">(</span><span class="m">3</span><span class="p">,</span> <span class="s">"must have matured"</span><span class="p">)</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<p>That’s pretty simple: we just call <cite>verify</cite> in order to check all the transactions in the group. If any are invalid,
|
||||
an exception will be thrown indicating which transaction failed and why. In the second case, we call <cite>expectFailureOfTx</cite>
|
||||
again to ensure the third transaction fails with a message that contains “must have matured” (it doesn’t have to be
|
||||
the exact message).</p>
|
||||
</div>
|
||||
<div class="section" id="adding-a-crafting-api-to-your-contract">
|
||||
<h2>Adding a crafting API to your contract<a class="headerlink" href="#adding-a-crafting-api-to-your-contract" title="Permalink to this headline">¶</a></h2>
|
||||
<p>TODO: Write this after the CP contract has had a crafting API actually added.</p>
|
||||
</div>
|
||||
<div class="section" id="non-asset-oriented-based-smart-contracts">
|
||||
<h2>Non-asset-oriented based smart contracts<a class="headerlink" href="#non-asset-oriented-based-smart-contracts" title="Permalink to this headline">¶</a></h2>
|
||||
<p>It is important to distinguish between the idea of a legal contract vs a code contract. In this document we use the
|
||||
term <em>contract</em> as a shorthand for code contract: a small module of widely shared, simultaneously executed business
|
||||
logic that uses standardised APIs and runs in a sandbox.</p>
|
||||
<p>Although this tutorial covers how to implement an owned asset, there is no requirement that states and code contracts
|
||||
<em>must</em> be concerned with ownership of an asset. It is better to think of states as representing useful facts about the
|
||||
world, and (code) contracts as imposing logical relations on how facts combine to produce new facts.</p>
|
||||
<p>For example, in the case that the transfer of an asset cannot be performed entirely on-ledger, one possible usage of
|
||||
the model is to implement a delivery-vs-payment lifecycle in which there is a state representing an intention to trade,
|
||||
another state representing an in-progress delivery, and a final state in which the delivery is marked as complete and
|
||||
payment is being awaited.</p>
|
||||
<p>As another example, consider multi-signature transactions, a feature which is commonly used in Bitcoin to implement
|
||||
various kinds of useful protocols. This technique allows you to lock an asset to ownership of a group, in which a
|
||||
threshold of signers (e.g. 3 out of 4) must all sign simultaneously to enable the asset to move. It is initially
|
||||
tempting to simply add this as another feature to each existing contract which someone might want to treat in this way.
|
||||
But that could lead to unnecessary duplication of work.</p>
|
||||
<p>A better approach is to model the fact of joint ownership as a new contract with its own state. In this approach, to
|
||||
lock up your commercial paper under multi-signature ownership you would make a transaction that looks like this:</p>
|
||||
<ul class="simple">
|
||||
<li><strong>Input</strong>: the CP state</li>
|
||||
<li><strong>Output</strong>: a multi-sig state that contains the list of keys and the signing threshold desired (e.g. 3 of 4). The state has a hash of H.</li>
|
||||
<li><strong>Output</strong>: the same CP state, with a marker that says a state with hash H must exist in any transaction that spends it.</li>
|
||||
</ul>
|
||||
<p>The CP contract then needs to be extended only to verify that a state with the required hash is present as an input.
|
||||
The logic that implements measurement of the threshold, different signing combinations that may be allowed etc can then
|
||||
be implemented once in a separate contract, with the controlling data being held in the named state.</p>
|
||||
<p>Future versions of the prototype will explore these concepts in more depth.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user