How to Equip Your Existing CorDapp with Tokens SDK

As more and more industry incumbents are gearing up towards digitalization and tokenization, we, as Corda developers, should also prepare ourselves for the new breakthrough. In this article, I will guide you through the steps to upgrade your existing CorDapp to a Token app via Corda Tokens SDK. Some Basic information if you have not heard about the Tokens SDK: Introduction information on the Tokens SDK, SDK technical break down.

Design & Planning

For simplicity purposes, we will walk through the steps with our signature Yo-Cordapp. which sends a single state to the counterparty. We will implement a couple of modifications:

1. Add an evolvable non-fungible token to the App (as which normally represents non-fungible tokenized asset)
2. Add an evolvable fungible token to the App (as which normally represents fungible asset such as stock)

Step One: Add dependencies

We will add the dependencies for Tokens SDK at each of the build.gradle at the project level, at the workflow folder, and the contract folder.

For project level build.gradle, under the buildscript.ext section add:

//Tokens        
tokens_release_group = 'com.r3.corda.lib.tokens'        tokens_release_version = '1.2'

Under the allprojects.repositories section add:

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

Under both the dependencies section and the deployNodes nodeDefaults section add:

// Token SDK dependencies.    
cordapp "$tokens_release_group:tokens-contracts:$tokens_release_version"    
cordapp "$tokens_release_group:tokens-workflows:$tokens_release_version"

Navigate to the workflow build.gradle, under the dependencies section add:

// Token SDK dependencies.
cordaCompile "$tokens_release_group:tokens-workflows:$tokens_release_version"

Navigate to the Contract build.gradle, under the dependencies section add:

// Token SDK dependencies.
cordaCompile "$tokens_release_group:tokens-contracts:$tokens_release_version"

Step Two: Define the TokenState

In our previous Tokens SDK introductory article/videos, we explained that every token that carries evolvable attributes would have a Corda State as the underlying token classifier.

We will define two States:

• YoTokenFungibleState
• YoTokenNonFungibleState

They are virtually the same, the only difference is that each of them carries a different string to help us distinguish them when we query the tokens.

Step Three: Create a Token Contract.

After defining the underlying token classifiers, the next step is to write the Contracts for these states. (As we recall, every Corda State is pegged with one Contract to verify any transaction that carries the state.) However, token Contracts are a bit different than normal contracts. We will not define any Commands for the state because all of the transaction regarding the Token State is pre-defined in the Tokens SDK, we will define two extra checks for creating and updating the token States. These two methods will behave just like the verify() method, which will be called during a transaction. These two methods will get called automatically when the State is created and updated.

This is the code for the YoFungibleTokenContract file, the Contract for the nonfungibleToken would be almost identical. The reason we are not implementing the additional checks is that YoState carries very minimal information, which we do not have any field needs to be verified. An example of additional checks for the Token State would look like this.

Step Four: Add Token Logic in the Flows

We will create 2 new flows to demonstrate the creation and issuance of the two different tokens.

• CreateAndIssueFungibleYoToken
• CreateAndIssueNonFungibleYoToken

Token issuance flow is similar to any of the traditional flows in the way that it creates the state and send it via transaction. In a token flow, we will need to create the token classifier state and then issue the actual token with the classifier. For example in this CreateAndIssueFungibleYoToken flow here:

The CreateAndIssueNonFungibleYo flow is similar to to the createAndIssueFungibleYo flow. The code can be found here.

We will continue to upgrade, implementing another flow that moves the Token around.

As of now, we have complete the steps to upgrade a simple CorDapp to a Token capable CorDapp.

Running the Token equipped YoCorDapp:

For demo purposes, we will add another node to the bootstrapper network to distinguish the issuance of the two different tokens. Navigate to the project level build.gradle, under the deployNodes task, add another node attribute at the bottom:

node {
    name "O=PartyC,L=San Diego,C=US"
    p2pPort 10011
    rpcSettings {
        address("localhost:10012")
        adminAddress("localhost:10052")
    }
    rpcUsers = [[ user: "user1", "password": "test", "permissions": ["ALL"]]]
}

Build the project and run it by:

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

At PartyA, issue the FungibleYo Token to PartyB, and issue the NonFungibleYo Token to PartyC.

flow start CreateAndIssueFungibleYo target: PartyB, issueVol: 200
flow start CreateAndIssueNonFungibleYo target: PartyC

At PartyB, query the Fungible Tokens:

run vaultQuery contractStateType: com.r3.corda.lib.tokens.contracts.states.FungibleToken

At PartyC, query the Non-Fungible Tokens:

run vaultQuery contractStateType: com.r3.corda.lib.tokens.contracts.states.NonFungibleToken

Move some of the Fungible tokens from PartyB to PartyC, run the following command at PartyB (The tokenId can be found in the previous Fungible Token query)

flow start MoveFungibleInitiator tokenId: <xxx-xxx-xxx-xxxx>, quantity: 15, recipient: PartyC

Now run the fungible token query at PartyC’s terminal we should see the 15 Fungible Yo Tokens were given by PartyB.

Ending Notes:

Tokens SDK, unlike the Account Library, does not necessarily require structural changes of the existing CorDapp. The token system is more like an add-on to the existing app. From the Token Classifier State to the Contracts and to flow modification, most of them are adding to the existing code, rather than changing it. As a result, Tokens SDK is very easy to implement.

Full implementation is here

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.