How to equip your existing CorDapp with Corda Accounts

September 15, 2020

If you have read our previous introductory articles on what is Corda Accounts library and the technical break downs of the package, now you might wonder how do you add the Accounts feature sets to your current existing CorDapp to benefit from the scalability that Corda Accounts brings. In this article, I will walk you through the necessary steps for you to do and consider when you are enhancing your CorDapp with Corda Accounts.

We will go through the Account enhancement using the one of our signature CorDapp, the Yo-CorDapp. It is a simple single state CorDapp that send a transaction from one node to another node. Let’s begin!

Pre-requisite

Clone the project and make sure your development environment is properly set up for CorDapp development. We can easily test it by building the projects and test run it with a transaction.

  • Build the project: ./gradlew clean deployNodes
  • Start the bootstrapped network: ./build/nodes/runnodes
  • Once you have started the nodes, go to PartyA and test the app by entering the command: flow start YoFlow target: PartyB

Modification Step 1: Add dependencies

Whenever you are considering using any Corda SDK features, you will need to add corresponded dependencies. Go to the project level Build.gradle under the buildscript.ext add both dependencies:

//account
accounts_release_group = 'com.r3.corda.lib.accounts'
accounts_release_version = '1.0'
//CI
confidential_id_release_group = "com.r3.corda.lib.ci"
confidential_id_release_version = "1.0"

Add the following maven path at the repository section:

maven { url 'http://ci-artifactory.corda.r3cev.com/artifactory/corda-lib' }
maven { url 'https://ci-artifactory.corda.r3cev.com/artifactory/corda' }

Move to the allprojects.repository add:

//CI dependencies
maven { url 'https://ci-artifactory.corda.r3cev.com/artifactory/corda' }
maven { url 'https://ci-artifactory.corda.r3cev.com/artifactory/corda-lib' }

continue to the dependencies section (the one in the outer level) add:

//Account & CI lib
cordapp "$confidential_id_release_group:ci-workflows:$confidential_id_release_version"
cordapp "$accounts_release_group:accounts-contracts:$accounts_release_version"
cordapp "$accounts_release_group:accounts-workflows:$accounts_release_version"

At the deployNodes section, under the nodeDefaults add:

cordapp("$confidential_id_release_group:ci-workflows:$confidential_id_release_version")
cordapp("$accounts_release_group:accounts-contracts:$accounts_release_version")
cordapp("$accounts_release_group:accounts-workflows:$accounts_release_version")

Now navigate to a different build.gradle under the workflows folder, under the dependencies, add:

//Account and CI dependencies
cordaCompile "$confidential_id_release_group:ci-workflows:$confidential_id_release_version"
cordaCompile "$accounts_release_group:accounts-workflows:$accounts_release_version"

We will add the last required dependencies to the build.gradle in the Contracts folder. Again, in the dependencies section, add:

//Account dependencies.
cordaCompile "$accounts_release_group:accounts-contracts:$accounts_release_version"

Modification Step 2: Modify the States

The first thing we need to consider is the participants of the States. In our Corda Account overview article, we mentioned that Corda accounts are simply masked confidential identities that live in the nodes. Therefore, the first thing we need to reconsider is the involving parties of the App.

In the original Yo-CorDapp, each YoState consists of three attributes, an origin party (who sends the message) and a target party (who receives the message). In our accounts enhanced modification, we will change these parties to accounts.

Modification Step 3: Modify the Contracts

What we need to look for to modify in our CorDapp are all the contract rules that relate to the node identities. We do not need to change the contract rules for the participants or signers because the accounts behave the same as the node (Both are operated via public/private key pair).

Regarding the original Yo-CorDapp, we do not need to change anything because there aren’t any contract rules regarding the node identities.

Modification Step 4: Modify the flows and helper method.

Before we modify the YoFlow, we would need to create a couple of helper methods to take care of the creation and sharing of the Accounts. You can simply mimic the code here:

  • CreateNewAccount: link
  • ShareAccountTo: link
  • A helper method that Sync the keys with the counterparty (Very important step): (sample code) This step will sync all the keymaps that relates to the transaction state to the counterparty, so when the counterparty tries to use the state in a different transaction. The counterparty node knows whose signature was on the transaction. SyncYoStateFlow

Next, we will start to modify our YoFlow. We will look at:

  1. Modifying the Constructor, so the YoFlow now take 2 different parameters (Which account am I, Which account is this YoFlow is sent to)
  2. Querying both our accounts and counterparty’s accounts.
  3. Remaking the YoState that take the accounts as parameters.
  4. Changing the command’s requires signing keys to account keys.
  5. Adding the account’s owning key when self-signing the transaction.
  6. Collecting the counterParty signature.
  7. After the FinalityFlow, syncing the state with the counterparty.
  8. Signing the transaction in the responder flow.

Full Code here

Now all the modification would be done. Let test it.

Running the Accounts equipped YoCorDapp:

Build the project and run it by:

./gradlew clean deployNodes
./build/nodes/runnodes

At PartyA, create and share the accounts:

flow start CreateNewAccount acctName: PeterLi
flow start ShareAccountTo acctNameShared: PeterLi, shareTo: PartyB

At PartyB, create and share the accounts:

flow start CreateNewAccount acctName: DavidA
flow start ShareAccountTo acctNameShared: DavidA, shareTo: PartyA

Back to PartyA to invoke a YoFlow:

flow start YoFlow whoAmI: PeterLi, whereTo: DavidA

Go to PartyB to check for the States:

run vaultQuery contractStateType: net.corda.examples.yo.states.YoState
Image for post

Peter Li is a Developer Evangelist at R3, an enterprise blockchain software firm working with a global ecosystem of more than 350 participants across multiple industries from both the private and public sectors to develop on Corda, its open-source blockchain platform, and Corda Enterprise, a commercial version of Corda for enterprise usage.

Follow us on twitter here.