corda/docs/source/contract-upgrade.rst

Upgrading contracts

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.

Workflow

Here's the workflow for contract upgrades:

1. Two banks, A and B negotiate a trade, off-platform
2. 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 consensus service).
3. Time passes.
4. The developer of contract X discovers a bug in the contract code, and releases a new version, contract Y. The developer will then notify all existing users (e.g. via a mailing list or CorDapp store) to stop their nodes from issuing further states with contract X.
5. Banks A and B review the new contract via standard change control processes and identify the contract states they agree to upgrade (they may decide not to upgrade some contract states as these might be needed for some other obligation contract).
6. 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.
7. One of the parties initiates (Initiator) an upgrade of state objects referring to contract X, to a new state object referring to contract Y.
8. A proposed transaction Proposal, taking in the old state and outputting the reissued version, is created and signed with the node's private key.
9. The Initiator node sends the proposed transaction, along with details of the new contract upgrade path its proposing, to all participants of the state object.
10. Each counterparty Acceptor verifies the proposal, signs or rejects the state reissuance accordingly, and sends a signature or rejection notification back to the initiating node.
11. If signatures are received from all parties, the initiating node assembles the complete signed transaction and sends it to the consensus service.

Authorising upgrade

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. The ContractUpgradeFlow is used to manage the authorisation records. The administrator can use RPC to trigger either an Authorise or Deauthorise flow.

/**
 * Authorise a contract state upgrade.
 * This will store the upgrade authorisation in persistent store, and will be queried by [ContractUpgradeFlow.Acceptor] during contract upgrade process.
 * Invoking this flow indicates the node is willing to upgrade the [StateAndRef] using the [UpgradedContract] class.
 * This method will NOT initiate the upgrade process. To start the upgrade process, see [Initiator].
 */
@StartableByRPC
class Authorise(
        val stateAndRef: StateAndRef<*>,
        private val upgradedContractClass: Class<out UpgradedContract<*, *>>
    ) : FlowLogic<Void?>()

/**
 * Deauthorise a contract state upgrade.
 * This will remove the upgrade authorisation from persistent store (and prevent any further upgrade)
 */
@StartableByRPC
class Deauthorise(
        val stateRef: StateRef
) : FlowLogic< Void?>()

Proposing an upgrade

After all parties have registered the intention of upgrading the contract state, one of the contract participants can initiate the upgrade process by triggering the Initiator contract upgrade flow. The Initiator will create a new state and sent to each participant for signatures, each of the participants (Acceptor) will verify, sign the proposal and return to the initiator. The transaction will be notarised and persisted once every participant verified and signed the upgrade proposal.

Examples

Lets assume Bank A has entered into an agreement with Bank B, and the contract is translated into contract code DummyContract with state object DummyContractState.

A 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 DummyContractV2

1. Developer will create a new contract extending the UpgradedContract class, and a new state object DummyContractV2.State referencing the new contract.

/../../test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContractV2.kt

2. Bank A will instruct its node to accept the contract upgrade to DummyContractV2 for the contract state.

val rpcClient : CordaRPCClient = << Bank A's Corda RPC Client >>
val rpcA = rpcClient.proxy()
rpcA.startFlow(ContractUpgradeFlow.Authorise(<<StateAndRef of the contract state>>, DummyContractV2::class.java))

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.

val rpcClient : CordaRPCClient = << Bank B's Corda RPC Client >>
val rpcB = rpcClient.proxy()
rpcB.startFlow({ stateAndRef, upgrade -> ContractUpgradeFlow(stateAndRef, upgrade) },
    <<StateAndRef of the contract state>>,
    DummyContractV2::class.java)

Note

See ContractUpgradeFlowTest for more detailed code examples.