Introduction to Token SDK in Corda

July 16, 2019

Tokens have been very prevalent in the blockchain world and have been widely used for the transfer of value within blockchain networks. The Corda token SDK offers a variety of features for creating and managing tokens in CorDapps.

Token Types in Corda

Corda Token Type Hierarchy

Tokens in Corda come in two different flavors:

  1. Fixed Token Types which remain constant and doesn’t change over time, like a currency. Any class representing a fixed token type must implement the TokenType interface.
  2. Evolvable Token Types which have the tendency to change over time. Any class representing an evolvable token must extend the EvolvableTokenType class.

The TokenType interface is the base type for all tokens in Corda. It implements the TokenizableAssetInfo interface (defined in corda-core) which is used to define a nominal display unit size of a single token. TokenizableAssetInfo is used by the Amount class (in corda-core) to convert asset amount to tokens represented by Amount objects.

Evolvable tokens don’t implement the TokenType interface directly, instead, they do so via a TokenPointer. Since they can evolve over time EvolvableTokenType is modeled as a LinearState i.e. it extends the LinerState interface. It doesn’t make sense to inline the LinearState with the token, hence the token includes a pointer to the LinearState called TokenPointer. This way the Token can evolve independently of who owns some amount of the token as the data is held separately.

IssuedTokenType is a wrapper class which contains a token type and the issuing party of the token. This is used while issuing tokens.

Creating Tokens in Corda

FixedToken

All fixed tokens must implement the TokenType interface. Shown below is a sample implementation of a fixed token in Corda. All it really needs is a token identifier and the fractional amount allowed for the token.

Creating an instance of the fixed token type is as simple as creating an object in Java. So our token below has an identifier ASHUCOIN as can have up to 4 decimal places eg: 5000.0001.

MyFixedToken myFixedToken = new MyFixedToken("ASHUCOIN", 4);

Evolvable Token

A class implementing an evolvable token must extend the EvolvableTokenType class. Shown below is an example of an evolvable token. As mentioned earlier EvolvableTokenType extend LinearState hence we have a linearId to keep track of the changes to the state over time. We also have a set of maintainers who would be informed on any state update.

Creating an instance to the evolvable token is similar to creating an object in Java, just like the case for fixed token.

However, since we have multiple maintainers and potential observers of an evolvable token the state information needs to be shared across these parties. The Token SDK provides the CreateEvolvableToken flow which can be used to do so.

Issuing Tokens in Corda

Tokens can either be fungible or non-fungible. Fungible tokens are those which can be split and merged like money, stocks, etc. Non-Fungible token cannot be split and merged which means they are unique, non-fungible tokens can be used to represent things like title deeds, loans, etc.

When we issue tokens in Corda we issue either a fungible or a non-fungible token. Corda provides the FungibleToken and NonFungibleToken class which can be used by developers to issue tokens.

Token state Hierarchy in Corda

FungibleToken and NonFungible tokens are modeled as states in Corda, (they extend the AbstractToken class which implements the ContractState interface) and are stored in the vault.

Issuing Non-Fungible Tokens

To create an instance of NonFungibleToken we first need an instance of IssuedTokenType. As discussed before IssuedTokenType is a wrapper containing a TokenType and an issuer. Shown below is how to create an instance of IssuedTokenType.

Creating an IssuedTokenType instance for an evolvable token type is a little more complex since EvolvableTokenType is not directly a TokenType and thus we need to use a TokenPointer.

Once we have the instance of IssuedTokenTye for our fixed/ evolvable token, issuing the token is straight forward. We just need to create an instance of NonFungibleToken class and use the IssueTokens flow provided by TokenSDK to issue the token as shown below.

NonFungibleToken takes these parameters in its constructor: the issuedTokenType, the recipient party, linearId, and a secure hash of the jar which implements the token type (a helper function is provided to retrieve this).

Issuing Fungible Tokens

Issuing a fungible token is somewhat similar to NonFungible Token other than the fact that a fungible token has the amount property, allowing it to be split and combined. Unlike non-fungible token, a fungible token is not unique, a different amount of it can be owned by multiple holders. However, the basic steps of issuing the fungible tokens still remain the same, we first need to create an instance of IssuedTokenType, then use it to create an instance of FungibleToken and then call the IssueTokens flow to issue it to the holder.

Issuing evolvable fungible tokens are also pretty similar to the above and I will leave it to you to try and explore.

I hope this post gives you a good basic understanding of the Token SDK in Corda. To start developing your own tokens in Corda you can use the token-template as a starting point, it is available in both Java and Kotlin.

Thanks for your interest in Corda. You may consider joining us in our public slack channel if you have questions or are interested in learning more about Corda.

— Ashutosh Meher, Developer Relations at R3


Introduction to Token SDK in Corda was originally published in Corda on Medium, where people are continuing the conversation by highlighting and responding to this story.