Crda contracts and states upgrades questions

Question

I am going through this documentation and I have several uncertainties.

Performing explicit contract and state upgrades

1. Preserve the existing state and contract definitions
2. Write the new state and contract definitions
3. Create the new CorDapp JAR
4. Distribute the new CorDapp JAR
5. Stop the nodes
6. Re-run the network bootstrapper (only if you want to whitelist the new contract)
7. Restart the nodes
8. Authorise the upgrade
9. Perform the upgrade
10. Migrate the new upgraded state to the Signature Constraint from the zone constraint

Questions:

1. Preserve the existing state and contract definitions 2. Write the new state and contract definitions 3. Create the new CorDapp JAR

How do I do that? is it meant only to preserve jars with contracts and states on nodes, not preserving them in source code? If I do not preserve them in source code then how can I create the upgrade method?

interface UpgradedContract<in OldState : ContractState, out NewState : ContractState> : Contract {
    val legacyContract: ContractClassName
    fun upgrade(state: OldState): NewState
}

If I do not preserve old state in source code, then shoud I name the jar differently each time I need to do an upgrade? Can old jars be reoved from the node when the upgrade was completed?

6. Re-run the network bootstrapper (only if you want to whitelist the new contract) 8. Authorise the upgrade Am I right that only those 2 steps are related to Explicit contact upgrades? And If I use implicit flow with signature, then I need to skip only those two steps, while the others are still aplicable and must be performed?

9. Perform the upgrade Should this be done for each state separately by the owner of the state? In that case should I run it on each node for specific contrcats where the node is the participant of the state? (In doc it is mentioned to be run on single node - but what id=f a single node is not participant of some state)

Other questions

This section describes explicit contracts and states update. https://docs.corda.net/upgrading-cordapps.html#performing-explicit-contract-and-state-upgrades while signature constraint section (https://docs.corda.net/api-contract-constraints.html#signature-constraints) does not describe an update process for states. is it the same as for explicit upgrades with the difference only in steps 6,8 or it is somewhat completely different? Do I need to create the function transforming old states to new states in that case? if not , then how the old states will be handled by new flows?

Answer 1

I see you have many some great questions about contract upgrades. Here is an article that is written by one of our dev-relation engineers. https://medium.com/corda/contract-upgrades-and-constraints-in-corda-425055a9a47f Feel free to follow up any additional questions that you have.

If you are new to Corda, feel free to join the Corda community channels @http://slack.corda.net/

Answer 2

1. While performing legacy contract upgrades, you need both the old and new contract jars installed on your node. (present in the cordapps folder). You can create a new Gradle module say v2-contract and write the new contract in this. This is where you will write your UpgradedContract. You will need to refer to the old v1-conract jar as well as it needs to know what the old state was. To do this add a gradle dependency in v2-contract like below.

   dependencies {

   // Corda dependencies.
   cordapp project(v1_contract)
   

   }

   The old jar can be removed from the cordapps folder, once all the states have been upgraded to new v2-contract.

2. a. For HashConstraints there is no need to run the bootstrapper again. You will write the new contract by implementing UpgradedContractWithLegacyConstraint,run the jar task to build this new jar, add it to the cordapps folder, run the Authorise Flow from all nodes, run the Initiate flow from one of he node's terminal. This is the explicit way of upgrading.

b. However if you are using Whitelistzoneconstraint, you want to make sure to add the new v2-contract jar's hash to whitelist param in network param. You will need to run the network Bootstrapper to whitelist this new v2-contracts jar hash. https://docs.corda.net/network-bootstrapper.html#whitelisting-contracts. Once you do that you can either go for an explicit upgrade by implementing UpgradedContract, or you can use implicit upgrade.

c. If you are using Signature Constraints, no need to run the network Bootstrapper for the new jar, write the new v2-contract, build it using gradle jar task, replace old jar with new jar. This is the implicit way of upgrading.

9. You should run the Authorise Flow for all the participants only.

Other questions There is no explicit upgrade in Signature constraints. You need to make sure you write your state in a backward compatible way, build new jar, replace old jar with new jar. The states will refer to the new contract then.

Hope that helps. Feel free to post more questions on the above answer or ping on Slack.