corda/docs/build/html/contract-upgrade.html
Clinton Alexander 9a2963bca9 Docs regen.
2017-02-22 10:59:02 +00:00

419 lines
25 KiB
HTML

<!-- 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>Upgrading Contracts &mdash; R3 Corda latest documentation</title>
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
<link rel="next" title="Integration testing" href="tutorial-integration-testing.html"/>
<link rel="prev" title="Writing a contract test" href="tutorial-test-dsl.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 class="current">
<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 current"><a class="current reference internal" href="#">Upgrading Contracts</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#workflow">Workflow</a></li>
<li class="toctree-l2"><a class="reference internal" href="#authorising-upgrade">Authorising upgrade</a></li>
<li class="toctree-l2"><a class="reference internal" href="#proposing-an-upgrade">Proposing an upgrade</a></li>
<li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</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>
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="clauses.html">Clauses</a></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>Upgrading Contracts</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/contract-upgrade.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">
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script><div class="section" id="upgrading-contracts">
<h1>Upgrading Contracts<a class="headerlink" href="#upgrading-contracts" title="Permalink to this headline"></a></h1>
<p>While every care is taken in development of contract code,
inevitably upgrades will be required to fix bugs (in either design or implementation).
Upgrades can involve a substitution of one version of the contract code for another or changing
to a different contract that understands how to migrate the existing state objects. State objects
refer to the contract code (by hash) they are intended for, and even where state objects can be used
with different contract versions, changing this value requires issuing a new state object.</p>
<div class="section" id="workflow">
<h2>Workflow<a class="headerlink" href="#workflow" title="Permalink to this headline"></a></h2>
<p>Here&#8217;s the workflow for contract upgrades:</p>
<ol class="arabic simple">
<li>Two banks, A and B negotiate a trade, off-platform</li>
<li>Banks A and B execute a protocol to construct a state object representing the trade, using contract X, and include it in a transaction (which is then signed and sent to the Uniqueness Service).</li>
<li>Time passes.</li>
</ol>
<p>4. The developer of contract X discovers a bug in the contract code, and releases a new version, contract Y.
And notify the users (e.g. via a mailing list or CorDapp store).
At this point of time all nodes should stop issuing states of contract X.</p>
<ol class="arabic simple" start="5">
<li>Banks A and B review the new contract via standard change control processes and identify the contract states they agreed to upgrade, they can decide not to upgrade some contract states as they might be needed for other obligation contract.</li>
<li>Banks A and B instruct their Corda nodes (via RPC) to be willing to upgrade state objects of contract X, to state objects for contract Y using agreed upgrade path.</li>
<li>One of the parties <code class="docutils literal"><span class="pre">Instigator</span></code> initiates an upgrade of state objects referring to contract X, to a new state object referring to contract Y.</li>
<li>A proposed transaction <code class="docutils literal"><span class="pre">Proposal</span></code>, taking in the old state and outputting the reissued version, is created and signed with the node&#8217;s private key.</li>
<li>The node <code class="docutils literal"><span class="pre">Instigator</span></code> sends the proposed transaction, along with details of the new contract upgrade path it&#8217;s proposing, to all participants of the state object.</li>
<li>Each counterparty <code class="docutils literal"><span class="pre">Acceptor</span></code> verifies the proposal, signs or rejects the state reissuance accordingly, and sends a signature or rejection notification back to the initiating node.</li>
<li>If signatures are received from all parties, the initiating node assembles the complete signed transaction and sends it to the consensus service.</li>
</ol>
</div>
<div class="section" id="authorising-upgrade">
<h2>Authorising upgrade<a class="headerlink" href="#authorising-upgrade" title="Permalink to this headline"></a></h2>
<p>Each of the participants in the upgrading contract will have to instruct their node that they are willing to upgrade the state object before the upgrade.
Currently the vault service is used to manage the authorisation records. The administrator can use RPC to perform such instructions.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm"> * Authorise a contract state upgrade.</span>
<span class="cm"> * This will store the upgrade authorisation in the vault, and will be queried by [ContractUpgradeFlow.Acceptor] during contract upgrade process.</span>
<span class="cm"> * Invoking this method indicate the node is willing to upgrade the [state] using the [upgradedContractClass].</span>
<span class="cm"> * This method will NOT initiate the upgrade process. To start the upgrade process, see [ContractUpgradeFlow.Instigator].</span>
<span class="cm"> */</span>
<span class="k">fun</span> <span class="nf">authoriseContractUpgrade</span><span class="p">(</span><span class="n">state</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;*&gt;,</span> <span class="n">upgradedContractClass</span><span class="p">:</span> <span class="n">Class</span><span class="p">&lt;</span><span class="n">UpgradedContract</span><span class="p">&lt;*,</span> <span class="p">*&gt;&gt;)</span>
<span class="cm">/**</span>
<span class="cm"> * Authorise a contract state upgrade.</span>
<span class="cm"> * This will remove the upgrade authorisation from the vault.</span>
<span class="cm"> */</span>
<span class="k">fun</span> <span class="nf">deauthoriseContractUpgrade</span><span class="p">(</span><span class="n">state</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;*&gt;)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="proposing-an-upgrade">
<h2>Proposing an upgrade<a class="headerlink" href="#proposing-an-upgrade" title="Permalink to this headline"></a></h2>
<p>After all parties have registered the intention of upgrading the contract state, one of the contract participant can initiate the upgrade process by running the contract upgrade flow.
The Instigator will create a new state and sent to each participant for signatures, each of the participants (Acceptor) will verify and sign the proposal and returns to the instigator.
The transaction will be notarised and persisted once every participant verified and signed the upgrade proposal.</p>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline"></a></h2>
<p>Lets assume Bank A has entered into an agreement with Bank B, and the contract is translated into contract code <code class="docutils literal"><span class="pre">DummyContract</span></code> with state object <code class="docutils literal"><span class="pre">DummyContractState</span></code>.</p>
<p>Few days after the exchange of contracts, the developer of the contract code discovered a bug/misrepresentation in the contract code.
Bank A and Bank B decided to upgrade the contract to <code class="docutils literal"><span class="pre">DummyContractV2</span></code></p>
<ol class="arabic simple">
<li>Developer will create a new contract extending the <code class="docutils literal"><span class="pre">UpgradedContract</span></code> class, and a new state object <code class="docutils literal"><span class="pre">DummyContractV2.State</span></code> referencing the new contract.</li>
</ol>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">DummyContractV2</span> <span class="p">:</span> <span class="n">UpgradedContract</span><span class="p">&lt;</span><span class="n">DummyContract</span><span class="p">.</span><span class="n">State</span><span class="p">,</span> <span class="n">DummyContractV2</span><span class="p">.</span><span class="n">State</span><span class="p">&gt;</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">val</span> <span class="py">legacyContract</span> <span class="p">=</span> <span class="n">DummyContract</span><span class="o">::</span><span class="k">class</span><span class="p">.</span><span class="n">java</span>
<span class="k">data</span> <span class="k">class</span> <span class="nc">State</span><span class="p">(</span><span class="k">val</span> <span class="py">magicNumber</span><span class="p">:</span> <span class="n">Int</span> <span class="p">=</span> <span class="m">0</span><span class="p">,</span> <span class="k">val</span> <span class="py">owners</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">CompositeKey</span><span class="p">&gt;)</span> <span class="p">:</span> <span class="n">ContractState</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">val</span> <span class="py">contract</span> <span class="p">=</span> <span class="n">DUMMY_V2_PROGRAM_ID</span>
<span class="k">override</span> <span class="k">val</span> <span class="py">participants</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">CompositeKey</span><span class="p">&gt;</span> <span class="p">=</span> <span class="n">owners</span>
<span class="p">}</span>
<span class="k">interface</span> <span class="nc">Commands</span> <span class="p">:</span> <span class="n">CommandData</span> <span class="p">{</span>
<span class="k">class</span> <span class="nc">Create</span> <span class="p">:</span> <span class="n">TypeOnlyCommandData</span><span class="p">(),</span> <span class="n">Commands</span>
<span class="k">class</span> <span class="nc">Move</span> <span class="p">:</span> <span class="n">TypeOnlyCommandData</span><span class="p">(),</span> <span class="n">Commands</span>
<span class="p">}</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">upgrade</span><span class="p">(</span><span class="n">state</span><span class="p">:</span> <span class="n">DummyContract</span><span class="p">.</span><span class="n">State</span><span class="p">):</span> <span class="n">DummyContractV2</span><span class="p">.</span><span class="n">State</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">DummyContractV2</span><span class="p">.</span><span class="n">State</span><span class="p">(</span><span class="n">state</span><span class="p">.</span><span class="n">magicNumber</span><span class="p">,</span> <span class="n">state</span><span class="p">.</span><span class="n">participants</span><span class="p">)</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="p">{</span>
<span class="k">if</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">any</span> <span class="p">{</span> <span class="n">it</span><span class="p">.</span><span class="n">value</span> <span class="k">is</span> <span class="n">UpgradeCommand</span> <span class="p">})</span> <span class="n">ContractUpgradeFlow</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="c1">// Other verifications.</span>
<span class="p">}</span>
<span class="c1">// The &quot;empty contract&quot;</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">&quot;&quot;</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<ol class="arabic simple" start="2">
<li>Bank A will instruct its node to accept the contract upgrade to <code class="docutils literal"><span class="pre">DummyContractV2</span></code> for the contract state.</li>
</ol>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>val rpcClient : CordaRPCClient = &lt;&lt; Bank A&#39;s Corda RPC Client &gt;&gt;
val rpcA = rpcClient.proxy()
rpcA.authoriseContractUpgrade(&lt;&lt;StateAndRef of the contract state&gt;&gt;, DummyContractV2::class.java)
</pre></div>
</div>
</div>
<p>3. Bank B now initiate the upgrade Flow, this will send a upgrade proposal to all contract participants.
Each of the participants of the contract state will sign and return the contract state upgrade proposal once they have validated and agreed with the upgrade.
The upgraded transaction state will be recorded in every participant&#8217;s node at the end of the flow.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>val rpcClient : CordaRPCClient = &lt;&lt; Bank B&#39;s Corda RPC Client &gt;&gt;
val rpcB = rpcClient.proxy()
rpcB.startFlow({ stateAndRef, upgrade -&gt; ContractUpgradeFlow.Instigator(stateAndRef, upgrade) },
&lt;&lt;StateAndRef of the contract state&gt;&gt;,
DummyContractV2::class.java)
</pre></div>
</div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">See <code class="docutils literal"><span class="pre">ContractUpgradeFlowTest.2</span> <span class="pre">parties</span> <span class="pre">contract</span> <span class="pre">upgrade</span> <span class="pre">using</span> <span class="pre">RPC</span></code> for more detailed code example.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="tutorial-integration-testing.html" class="btn btn-neutral float-right" title="Integration testing" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tutorial-test-dsl.html" class="btn btn-neutral" title="Writing a contract test" 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>