corda/docs/source/upgrade-notes.rst

Upgrading a CorDapp to a new platform version

These notes provide instructions for upgrading your CorDapps from previous versions, starting with the upgrade from our first public Beta (Milestone 12 <changelog_m12>), to V1.0 <changelog_v1>.

General rules

Always remember to update the version identifiers in your project gradle file. For example, Corda V1.0 uses:

ext.corda_release_version = '1.0.0'
ext.corda_release_distribution = 'net.corda'
ext.corda_gradle_plugins_version = '1.0.0'

It may be necessary to update the version of major dependencies. Corda V1.0 uses:

ext.kotlin_version = '1.1.4'
ext.quasar_version = '0.7.9'
ext.junit_version = '4.12'

Please consult the relevant release notes of the release in question. If not specified, you may assume the versions you are currently using are still in force.

We also strongly recommend cross referencing with the changelog to confirm changes.

V1.0 and V2.0 to R3 Corda V3.0 Developer Preview

Build

• Update the version identifiers in your project gradle file(s):

ext.corda_release_version = 'R3.CORDA-3.0.0-DEV-PREVIEW'    // "CORDA-3.0.0-DEV-PREVIEW" (Open Source)
ext.corda_gradle_plugins_version = '3.0.3'

• Add a new release identifier to specify the R3 release of corda:

ext.corda_release_distribution = 'com.r3.corda'             // "net.corda" for Corda (Open Source)

• Add an additional repository entry to point to the location of the R3 Corda distribution:

repositories {
    maven {
        credentials {
            username "r3-corda-dev-preview"
            password "XXXXX"
        }
        url 'https://ci-artifactory.corda.r3cev.com/artifactory/r3-corda-releases'
    }
}

• Corda plugins have been modularised further so the following additional gradle entries are necessary:

dependencies {
    classpath "net.corda.plugins:cordapp:$corda_gradle_plugins_version"
}

apply plugin: 'net.corda.plugins.cordapp'

The plugin needs to be applied in all gradle build files where there is a dependency on Corda using any of:
cordaCompile, cordaRuntime, cordapp

• Corda Gradle plugins require Gradle version 4.1 or above
• All gradle compile, test, and run-time dependencies (except gradle plugins) to Corda artifacts should now use the corda_release_distribution variable (was previously hardcoded to use net.corda):

dependencies {

    // Corda integration dependencies
    cordaCompile "$corda_release_distribution:corda-core:$corda_release_version"
    cordaCompile "$corda_release_distribution:corda-finance:$corda_release_version"
    cordaCompile "$corda_release_distribution:corda-jackson:$corda_release_version"
    cordaCompile "$corda_release_distribution:corda-rpc:$corda_release_version"
    cordaCompile "$corda_release_distribution:corda-node-api:$corda_release_version"
    cordaCompile "$corda_release_distribution:corda-webserver-impl:$corda_release_version"
    cordaRuntime "$corda_release_distribution:corda:$corda_release_version"
    cordaRuntime "$corda_release_distribution:corda-webserver:$corda_release_version"

    testCompile "$corda_release_distribution:corda-node-driver:$corda_release_version"
}

• For existing contract ORM schemas that extend from CommonSchemaV1.LinearState or CommonSchemaV1.FungibleState, you will need to explicitly map the participants collection to a database table. Previously this mapping was done in the superclass, but that makes it impossible to properly configure the table name. The required change is to add the override var participants: MutableSet<AbstractParty>? = null field to your class, and add JPA mappings. For ex., see this example:

@Entity
@Table(name = "cash_states_v2",
        indexes = arrayOf(Index(name = "ccy_code_idx2", columnList = "ccy_code")))
class PersistentCashState(

        @ElementCollection
        @Column(name = "participants")
        @CollectionTable(name="cash_states_v2_participants", joinColumns = arrayOf(
                JoinColumn(name = "output_index", referencedColumnName = "output_index"),
                JoinColumn(name = "transaction_id", referencedColumnName = "transaction_id")))
        override var participants: MutableSet<AbstractParty>? = null,

Configuration

Applies to both gradle deployNodes tasks and/or corda node configuration (node.conf).

• Remove any references to networkMap.

networkMap "O=Agent,L=Dallas,C=US"

• Remove any references to advertisedServices (including notaries).

advertisedServices = ["corda.notary.validating"]

• Add an explicit notary definition in the Notary node configuration only:

notary = [validating : true]

• For existing contract ORM schemas that extend from CommonSchemaV1.LinearState or CommonSchemaV1.FungibleState, you will need to explicitly map the participants collection to a database table. Previously this mapping was done in the superclass, but that makes it impossible to properly configure the table name. The required change is to add the override var participants: MutableSet<AbstractParty>? = null field to your class, and add JPA mappings. For ex., see this example:

@Entity
@Table(name = "cash_states_v2",
        indexes = arrayOf(Index(name = "ccy_code_idx2", columnList = "ccy_code")))
class PersistentCashState(

        @ElementCollection
        @Column(name = "participants")
        @CollectionTable(name="cash_states_v2_participants", joinColumns = arrayOf(
                JoinColumn(name = "output_index", referencedColumnName = "output_index"),
                JoinColumn(name = "transaction_id", referencedColumnName = "transaction_id")))
        override var participants: MutableSet<AbstractParty>? = null,

Testing

Contract tests

• You must now create a MockServices object.

  MockServices provides a mock identity, key and storage service. MockServices takes as its first argument a list of the CorDapp packages to scan:

  private val ledgerServices = MockServices(listOf("net.corda.examples.obligation", "net.corda.testing.contracts"))

  MockServices replaces the use of setCordappPackages and unsetCordappPackages.

• ledger is now defined as a MockServices method. This means that:

  ledger {

  Becomes:

  ledgerServices.ledger {

• Within a mock ledger transaction, ContractState instances are passed to input and output as objects rather than lambdas. For example:

  ledgerServices.ledger {
      transaction {
          input(OBLIGATION_CONTRACT_ID, DummyState())
          output(OBLIGATION_CONTRACT_ID, oneDollarObligation)
      }
  }

• Within a mock ledger transaction, CommandData instances are passed to input and output as objects rather than lambdas, and the public keys must be passed as a list if there is more than one. For example:

  ledgerServices.ledger {
      transaction {
          command(alice.publicKey, ObligationContract.Commands.Issue())
          command(listOf(alice.publicKey, bob.publicKey), ObligationContract.Commands.Issue())
      }
  }

• The predefined test identities (e.g. ALICE and MINI_CORP) have been removed.

  You must now define the test identities explicitly. For example:

  val alice = TestIdentity(CordaX500Name(organisation = "Alice", locality = "TestLand", country = "GB"))

  TestIdentity exposes methods to get the name, keyPair, publicKey, party and identity of the underlying TestIdentity

• Explicit invocation of transaction transformation (ie. using TransactionBuilder) requires serialization engine to be initialized. In unit test this can be achieved by using the following jUnit rule:

  @Rule
  @JvmField
  val testSerialization = SerializationEnvironmentRule()

Flow tests

• The registration mechanism for CorDapps in MockNetwork unit tests has changed.

  It is now done via the cordappPackages constructor parameter of MockNetwork. This takes a list of String values which should be the package names of the CorDapps containing the contract verification code you wish to load. The unsetCordappPackages method is now redundant and has been removed.

• Creation of Notaries in MockNetwork unit tests has changed.

  Previously the API call createNotaryNode(legalName = CordaX500ame(...)) would be used to create a notary:

  val notary = mockNetwork.createNotaryNode(legalName = CordaX500Name("Notary", "London", "UK"))

  Notaries are now defined as part of MockNetwork creation using notarySpecs, as in the following example:

  mockNetwork = MockNetwork(notarySpecs = listOf(MockNetwork.NotarySpec(CordaX500Name("Notary","London","UK"))))

• A notary is no longer specified when creating a standard node using the createPartyNode API call.

  Previously:

  mockNetwork.createPartyNode(notary.network.myAddress, CordaX500Name("Node", "Madrid", "ES"))

  Becomes:

  mockNetwork.createPartyNode(CordaX500Name("Node", "Madrid", "ES"))

• Utility node creation API method createSomeNodes(...) has been removed, and nodes must be created individually.

  Previously:

  MockNetwork.BasketOfNodes nodes = net.createSomeNodes(3);
  nodeA = nodes.getPartyNodes().get(0);
  nodeB = nodes.getPartyNodes().get(1);
  nodeC = nodes.getPartyNodes().get(2);

  Becomes:

  nodeA = net.createNode(new MockNodeParameters());
  nodeB = net.createNode(new MockNodeParameters());
  nodeC = net.createNode(new MockNodeParameters());
  List<StartedNode<MockNode>> nodes = Arrays.asList(nodeA, nodeB, nodeC);

• Flow framework instantiation of a flow has a slight variation in start syntax:

  Previously:

  CordaFuture<SignedTransaction> future = nodeA.getServices().startFlow(flow).getResultFuture();

  Becomes:

  CordaFuture<SignedTransaction> future = startFlow(nodeA.getServices(), flow).getResultFuture();

• StartedNodeServices.startFlow must now be imported from net.corda.testing.node

• Do not use node.internals to register flows:

  Previous code would often look as follows:

  protected fun registerFlowsAndServices(node: StartedNode<MockNetwork.MockNode>) {
      val mockNode = node.internals
      mockNode.registerInitiatedFlow(MyCustomFlow::class.java)
  }

  Becomes:

  protected fun registerFlowsAndServices(mockNode: StartedNode<MockNetwork.MockNode>) {
      mockNode.registerInitiatedFlow(MyCustomFlow::class.java)
  }

• Do not use node.internals to register Corda services

  Previously:

  node.internals.installCordaService(CustomService::class.java)

  Becomes:

  node.services.cordaService(CustomService::class.java)

Better yet, use node factory to organize both register flows and services, for example, create class as follows:

class PrimesOracleNode(args: MockNodeArgs) : MockNetwork.MockNode(args) {

override fun start() = super.start().apply {

registerInitiatedFlow(QueryHandler::class.java) registerInitiatedFlow(SignHandler::class.java) services.cordaService(net.corda.examples.oracle.service.service.Oracle::class.java)

}

and then pass it to createNode:

val oracle = mockNet.createNode(MockNodeParameters(legalName = CordaX500Name("Oracle", "New York", "US")), ::PrimesOracleNode)

Node driver

• User has been moved from net.corda.nodeapi.User to net.corda.nodeapi.internal.config.User

• Notaries are defined by passing a list of NotarySpec objects to driver using the notarySpecs argument, instead of being defined manually in the driver block.

  notarySpecs defaults to providing a single validating notary

• The waitForAllNodesToFinish function has been removed. It has been replaced with a waitForAllNodesToFinish argument to driver

• No longer specify advertised services to the DriverDSL when starting nodes:

  Previously:

  driver {
      startNode(providedName = CordaX500Name("Controller", "London", "GB"), advertisedServices = setOf(ServiceInfo(ValidatingNotaryService.type)))

  Becomes:

  driver {
      startNode(providedName = CordaX500Name("Controller", "London", "GB")),

Finance

• CASH_PROGRAM_ID has been moved to Cash.PROGRAM_ID, where Cash is defined in the import net.corda.finance.contracts.asset package

V1.0 to V2.0

You only need to update the corda_release_version identifier in your project gradle file. The corda_gradle_plugins_version should remain at 1.0.0:

ext.corda_release_version = '2.0.0'
ext.corda_gradle_plugins_version = '1.0.0'

Public Beta (M12) to V1.0

From Milestone 14 <changelog_m14>

Build

• MockNetwork has moved.

  A new test driver module dependency needs to be including in your project: corda-node-driver. To continue using the mock network for testing, add the following entry to your gradle build file:

testCompile "$corda_release_distribution:corda-node-driver:$corda_release_version"

Note

you may only need testCompile "$corda_release_distribution:corda-test-utils:$corda_release_version" if not using the Driver DSL.

Configuration

• CordaPluginRegistry has been removed. The one remaining configuration item customizeSerialisation, which defined a optional whitelist of types for use in object serialization, has been replaced with the SerializationWhitelist interface which should be implemented to define a list of equivalent whitelisted classes. You will need to rename your services resource file to the new class name: 'resources/META-INF/services/net.corda.core.node.CordaPluginRegistry' becomes 'resources/META-INF/services/net.corda.core.serialization.SerializationWhitelist' An associated property on MockNode was renamed from testPluginRegistries to testSerializationWhitelists. In general, the @CordaSerializable annotation is the preferred method for whitelisting as described in serialization

Missing imports

Use the automatic imports feature of IntelliJ to intelligently resolve the new imports.

• Missing imports for contract types.

  CommercialPaper and Cash are now contained within the finance module, as are associated helpers functions. For example: import net.corda.contracts.ICommercialPaperState becomes import net.corda.finance.contracts.ICommercialPaperState

  import net.corda.contracts.asset.sumCashBy becomes import net.corda.finance.utils.sumCashBy

  import net.corda.core.contracts.DOLLARS becomes import net.corda.finance.DOLLARS

  import net.corda.core.contracts.issued by becomes import net.corda.finance.issued by

  import net.corda.contracts.asset.Cash becomes import net.corda.finance.contracts.asset.Cash

• Missing imports for utility functions.

  Many common types and helper methods have been consolidated into net.corda.core.utilities package. For example: import net.corda.core.crypto.commonName becomes import net.corda.core.utilities.commonName

  import net.corda.core.crypto.toBase58String becomes import net.corda.core.utilities.toBase58String

  import net.corda.core.getOrThrow becomes import net.corda.core.utilities.getOrThrow

• Missing flow imports.

  In general all reusable library flows are contained within the core API net.corda.core.flows package. Financial domain library flows are contained within the finance module net.corda.finance.flows package. Other flows that have moved include:

  import net.corda.core.flows.ResolveTransactionsFlow becomes import net.corda.core.internal.ResolveTransactionsFlow

Core data structures

• Missing Contract override.

  The contract interace attribute legalContractReference has been removed, and replaced by the optional annotation @LegalProseReference(uri = "<URI>")

• Unresolved reference.

  Calls to AuthenticatedObject are replaced by CommandWithParties

• Overrides nothing: isRelevant in LinearState.

  Removed the concept of relevancy from LinearState. A ContractState's relevance to the vault is now resolved internally; the vault will process any transaction from a flow which is not derived from transaction resolution verification. The notion of relevancy is subject to further improvements to enable a developer to control what state the vault thinks are relevant.

• Calls to txBuilder.toLedgerTransaction() now requires a serviceHub parameter.

  Used by the new Contract Constraints functionality to validate and resolve attachments.

Flow framework

• Flow session deprecations

  FlowLogic communication has been upgraded to use functions on FlowSession as the base for communication between nodes.

  • Calls to send(), receive() and sendAndReceive() on FlowLogic should be replaced with calls to the function of the same name on FlowSession. Note that the replacement functions do not take in a destination parameter, as this is defined in the session.
  • Initiated flows now take in a FlowSession instead of Party in their constructor. If you need to access the counterparty identity, it is in the counterparty property of the flow session.

  See FlowSession for step by step instructions on porting existing flows to use the new mechanism.

• FinalityFlow now returns a single SignedTransaction, instead of a List<SignedTransaction>

• TransactionKeyFlow renamed to SwapIdentitiesFlow

  Note that SwapIdentitiesFlow must be imported from the confidential-identities* package ''net.corda.confidential''

Node services (ServiceHub)

• VaultQueryService: unresolved reference to vaultQueryService.

  Replace all references to <services>.vaultQueryService with <services>.vaultService. Previously there were two vault APIs. Now there is a single unified API with the same functions: VaultService.

• serviceHub.myInfo.legalIdentity no longer exists; use the ourIdentity property of the flow instead.

  FlowLogic.ourIdentity has been introduced as a shortcut for retrieving our identity in a flow

• getAnyNotary is gone - use serviceHub.networkMapCache.notaryIdentities[0] instead

  Note: ongoing work to support multiple notary identities is still in progress.

• ServiceHub.networkMapUpdates is replaced by ServiceHub.networkMapFeed

• ServiceHub.partyFromX500Name is replaced by ServiceHub.wellKnownPartyFromX500Name Note: A "well known" party is one that isn't anonymous and this change was motivated by the confidential identities work.

RPC Client

• Missing API methods on CordaRPCOps interface.

  • Calls to verifiedTransactionsFeed() and verifiedTransactions() have been replaced with: internalVerifiedTransactionsSnapshot() and internalVerifiedTransactionsFeed() respectively

    This is in preparation for the planned integration of Intel SGX™, which will encrypt the transactions feed. Apps that use this API will not work on encrypted ledgers: you should probably be using the vault query API instead.

  • Accessing the networkMapCache via services.nodeInfo().legalIdentities returns a list of identities. The first element in the list is the Party object referring to a node's single identity.

    This is in preparation for allowing a node to host multiple separate identities in future.

Testing

Please note that Clauses have been removed completely as of V1.0. We will be revisiting this capability in a future release.

• CorDapps must be explicitly registered in MockNetwork unit tests.

  This is done by calling setCordappPackages, an extension helper function in the net.corda.testing package, on the first line of your @Before method. This takes a variable number of String arguments which should be the package names of the CorDapps containing the contract verification code you wish to load. You should unset CorDapp packages in your @After method by using unsetCordappPackages() after stopNodes().

• CorDapps must be explicitly registered in DriverDSL and RPCDriverDSL integration tests.

  Similarly, you must also register package names of the CorDapps containing the contract verification code you wish to load using the extraCordappPackagesToScan: List<String> constructor parameter of the driver DSL.

Finance

• FungibleAsset interface simplification.

  The FungibleAsset interface has been made simpler. The Commands grouping interface that included the Move, Issue and Exit interfaces have all been removed, while the move function has been renamed to withNewOwnerAndAmount to be consistent with the withNewOwner function of the OwnableState.

  The following errors may be reported:

  • override nothing (FungibleAsset): move
  • not a subtype of overridden FungibleAsset: withNewOwner
  • no longer need to override override val contractHash: SecureHash? = null
  • need to override override val contract: Class<out Contract>? = null

Miscellaneous

• args[0].parseNetworkHostAndPort() becomes NetworkHostAndPort.parse(args[0])

• There is no longer a NodeInfo.advertisedServices property.

  The concept of advertised services has been removed from Corda. This is because it was vaguely defined and real world apps would not typically select random, unknown counterparties from the network map based on self-declared capabilities. We will introduce a replacement for this functionality, business networks, in a future release.

  For now, your should retrieve the service by legal name using NetworkMapCache.getNodeByLegalName.

Gotchas

• Beware to use the correct identity when issuing cash:

  The 3rd parameter to CashIssueFlow should be the ** notary ** (not the ** node identity **)

From Milestone 13 <changelog_m13>

Core data structures

• TransactionBuilder changes.

  Use convenience class StateAndContract instead of TransactionBuilder.withItems() for passing around a state and its contract.

• Transaction building DSL changes:

  • now need to explicitly pass the ContractClassName into all inputs and outputs.
  • ContractClassName refers to the class containing the “verifier” method.

• Contract verify method signature change.

  override fun verify(tx: TransactionForContract) becomes override fun verify(tx: LedgerTransaction)

• No longer need to override Contract contract() function.

Node services (ServiceHub)

• ServiceHub API method changes.

  services.networkMapUpdates().justSnapshot becomes services.networkMapSnapshot()

Configuration

• No longer need to define CordaPluginRegistry and configure requiredSchemas

  Custom contract schemas are automatically detected at startup time by class path scanning. For testing purposes, use the SchemaService method to register new custom schemas: eg. services.schemaService.registerCustomSchemas(setOf(YoSchemaV1))

Identity

• Party names are now CordaX500Name, not X500Name

  CordaX500Name specifies a predefined set of mandatory (organisation, locality, country) and optional fields (commonName, organisationUnit, state) with validation checking. Use new builder CordaX500Name.build(X500Name(target)) or, preferably, explicitly define X500Name parameters using CordaX500Name constructor.

Testing

• MockNetwork Testing.

  Mock nodes in node tests are now of type StartedNode<MockNode>, rather than MockNode MockNetwork now returns a BasketOf(<StartedNode<MockNode>>) Must call internals on StartedNode to get MockNode: a = nodes.partyNodes[0].internals b = nodes.partyNodes[1].internals

• Host and Port change.

  Use string helper function parseNetworkHostAndPort() to parse a URL on startup.

  eg. val hostAndPort = args[0].parseNetworkHostAndPort()

• The node driver parameters for starting a node have been reordered, and the node’s name needs to be given as an CordaX500Name, instead of using getX509Name

From Milestone 12 (First Public Beta) <changelog_m12>

Core data structures

• Transaction building

  You no longer need to specify the type of a TransactionBuilder as TransactionType.General TransactionType.General.Builder(notary) becomes TransactionBuilder(notary)

Build

• Gradle dependency reference changes.

  Module name has changed to include corda in the artifacts jar name:

compile "$corda_release_distribution:core:$corda_release_version" -> compile "$corda_release_distribution:corda-core:$corda_release_version"
compile "$corda_release_distribution:finance:$corda_release_version" -> compile "$corda_release_distribution:corda-finance:$corda_release_version"
compile "$corda_release_distribution:jackson:$corda_release_version" -> compile "$corda_release_distribution:corda-jackson:$corda_release_version"
compile "$corda_release_distribution:node:$corda_release_version" -> compile "$corda_release_distribution:corda-node:$corda_release_version"
compile "$corda_release_distribution:rpc:$corda_release_version" -> compile "$corda_release_distribution:corda-rpc:$corda_release_version"

Node services (ServiceHub)

• ServiceHub API changes.

  services.networkMapUpdates() becomes services.networkMapFeed() services.getCashBalances() becomes a helper method within the finance module contracts package: net.corda.finance.contracts.getCashBalances

Finance

• Financial asset contracts (Cash, CommercialPaper, Obligations) are now a standalone CorDapp within the finance module.

  Need to import from respective package within finance module:

  eg. net.corda.finance.contracts.asset.Cash

  Likewise, need to import associated asset flows from respective package within finance module:

  eg. net.corda.finance.flows.CashIssueFlow

  net.corda.finance.flows.CashIssueAndPaymentFlow net.corda.finance.flows.CashExitFlow

• Moved finance gradle project files into a net.corda.finance package namespace.

  This may require adjusting imports of Cash flow references and also of StartFlow permission in gradle.build files. Associated flows (Cash*Flow, TwoPartyTradeFlow, TwoPartyDealFlow) must now be imported from this package.