Introduction to Tokens SDK in Corda

Tokens have been very prevalent in the blockchain world and have been widely used for the transfer of value within blockchain networks. The Corda Tokens 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 extend the TokenType class.
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 class 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 extend the TokenType class 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 are of type TokenType. The TokenType class has two properties, tokenIdentifier, and fractionDigits. The tokenIdentifier property is used to uniquely identify the token, it is typically a 3–4 character uppercase alphabetic string, example- USD, GBP, BTC, etc. The fractionDigits property is used to denote the number of fractional digits 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.

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

If a more complex fixed token implementation is required, the class implementing the fixed token must extend the TokenType class.

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 Tokens SDK provides the CreateEvolvableTokens flow which can be used to do so. This flow accepts an instance of TransactionState as a parameter, hence we first need to create a TransactionState object from the Evolvable token.

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 Tokens 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