mirror of
https://github.com/corda/corda.git
synced 2024-12-24 15:16:45 +00:00
75 lines
3.8 KiB
ReStructuredText
75 lines
3.8 KiB
ReStructuredText
|
Upgrading CorDapps on a node
|
||
|
|
============================
|
||
|
|
|
||
|
|
In order to upgrade a CorDapp on a node to a new version, it needs to be determined whether any backwards compatible
|
||
|
|
changes have been made. These could range from database changes, to changes in the protocol.
|
||
|
|
|
||
|
|
For developer information on upgrading CorDapps, see :doc:`upgrading-cordapps`.
|
||
|
|
|
||
|
|
CorDapps must ship with database migration scripts or clear documentation about how to update the database to be compatible with the new version.
|
||
|
|
|
||
|
|
|
||
|
|
Flow upgrades
|
||
|
|
~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
If any backwards-incompatible changes have been made (see :ref:`upgrading-cordapps-backwards-incompatible-flow-changes`
|
||
|
|
for more information), the upgrade method detailed below will need to be followed. Otherwise the CorDapp JAR can just
|
||
|
|
be replaced with the new version.
|
||
|
|
|
||
|
|
Contract and State upgrades
|
||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
There are two types of contract/state upgrade:
|
||
|
|
|
||
|
|
1. *Implicit:* By allowing multiple implementations of the contract ahead of time, using constraints. See
|
||
|
|
:doc:`api-contract-constraints` to learn more.
|
||
|
|
2. *Explicit:* By creating a special *contract upgrade transaction* and getting all participants of a state to sign it using the
|
||
|
|
contract upgrade flows.
|
||
|
|
|
||
|
|
This documentation only considers the *explicit* type of upgrade, as implicit contract upgrades are handled by the application.
|
||
|
|
|
||
|
|
In an explicit upgrade contracts and states can be changed in arbitrary ways, if and only if all of the state's participants
|
||
|
|
agree to the proposed upgrade. The following combinations of upgrades are possible:
|
||
|
|
|
||
|
|
* A contract is upgraded while the state definition remains the same.
|
||
|
|
* A state is upgraded while the contract stays the same.
|
||
|
|
* The state and the contract are updated simultaneously.
|
||
|
|
|
||
|
|
Running the upgrade
|
||
|
|
~~~~~~~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
If a contract or state requires an explicit upgrade then all states will need updating to the new contract at a time agreed
|
||
|
|
by all participants. The updated CorDapp JAR needs to be distributed to all relevant parties in advance of the changeover
|
||
|
|
time.
|
||
|
|
|
||
|
|
In order to perform the upgrade, follow the following steps:
|
||
|
|
|
||
|
|
* If required, do a flow drain to avoid the definition of states or contracts changing whilst a flow is in progress (see :ref:`upgrading-cordapps-flow-drains` for more information)
|
||
|
|
|
||
|
|
* By RPC using the ``setFlowsDrainingModeEnabled`` method with the parameter ``true``
|
||
|
|
* Via the shell by issuing the following command ``run setFlowsDrainingModeEnabled enabled: true``
|
||
|
|
|
||
|
|
* Check that all the flows have completed
|
||
|
|
|
||
|
|
* By RPC using the ``stateMachinesSnapshot`` method and checking that there are no results
|
||
|
|
* Via the shell by issuing the following command ``run stateMachinesSnapshot``
|
||
|
|
|
||
|
|
* Once all flows have completed, stop the node
|
||
|
|
* Replace the existing JAR with the new one
|
||
|
|
* Make any database changes required to any custom vault tables for the upgraded CorDapp,
|
||
|
|
following the database upgrade steps in :doc:`node-operations-cordapp-deployment`.
|
||
|
|
The database update for a CorDapp upgrade follows the same steps as database setup for a new CorDapp.
|
||
|
|
|
||
|
|
* Restart the node
|
||
|
|
* If you drained the node prior to upgrading, switch off flow draining mode to allow the node to continue to receive requests
|
||
|
|
|
||
|
|
* By RPC using the ``setFlowsDrainingModeEnabled`` method with the parameter ``false``
|
||
|
|
* Via the shell by issuing the following command ``run setFlowsDrainingModeEnabled enabled: false``
|
||
|
|
|
||
|
|
* Run the contract upgrade authorisation flow (``ContractUpgradeFlow$Initiate``) for each state that requires updating on every node.
|
||
|
|
|
||
|
|
* You can do this manually via RPC but for anything more than a couple of states it is assumed that a script will be
|
||
|
|
provided by the CorDapp developer to query the vault and run this for all states
|
||
|
|
* The contract upgrade initiate flow only needs to be run on one of the participants for each state. The flow will
|
||
|
|
automatically upgrade the state on all participants.
|