<h1>Upgrading Contracts<aclass="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>
<divclass="section"id="workflow">
<h2>Workflow<aclass="headerlink"href="#workflow"title="Permalink to this headline">¶</a></h2>
<p>Here’s the workflow for contract upgrades:</p>
<olclass="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>
<olclass="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 <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">Proposal</span></code>, taking in the old state and outputting the reissued version, is created and signed with the node’s private key.</li>
<li>The node <codeclass="docutils literal"><spanclass="pre">Instigator</span></code> sends the proposed transaction, along with details of the new contract upgrade path it’s proposing, to all participants of the state object.</li>
<li>Each counterparty <codeclass="docutils literal"><spanclass="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>
<divclass="section"id="authorising-upgrade">
<h2>Authorising upgrade<aclass="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>
<spanclass="cm"> * Authorise a contract state upgrade.</span>
<spanclass="cm"> * This will store the upgrade authorisation in the vault, and will be queried by [ContractUpgradeFlow.Acceptor] during contract upgrade process.</span>
<spanclass="cm"> * Invoking this method indicate the node is willing to upgrade the [state] using the [upgradedContractClass].</span>
<spanclass="cm"> * This method will NOT initiate the upgrade process. To start the upgrade process, see [ContractUpgradeFlow.Instigator].</span>
<h2>Proposing an upgrade<aclass="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>
<divclass="section"id="examples">
<h2>Examples<aclass="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 <codeclass="docutils literal"><spanclass="pre">DummyContract</span></code> with state object <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">DummyContractV2</span></code></p>
<olclass="arabic simple">
<li>Developer will create a new contract extending the <codeclass="docutils literal"><spanclass="pre">UpgradedContract</span></code> class, and a new state object <codeclass="docutils literal"><spanclass="pre">DummyContractV2.State</span></code> referencing the new contract.</li>
<li>Bank A will instruct its node to accept the contract upgrade to <codeclass="docutils literal"><spanclass="pre">DummyContractV2</span></code> for the contract state.</li>
rpcA.authoriseContractUpgrade(<<StateAndRef of the contract state>>, 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’s node at the end of the flow.</p>
<<StateAndRef of the contract state>>,
DummyContractV2::class.java)
</pre></div>
</div>
</div>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">See <codeclass="docutils literal"><spanclass="pre">ContractUpgradeFlowTest.2</span><spanclass="pre">parties</span><spanclass="pre">contract</span><spanclass="pre">upgrade</span><spanclass="pre">using</span><spanclass="pre">RPC</span></code> for more detailed code example.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
