Tokenization Support Using Blockchain App Builder

Tokenization

Tokenization is a process where physical or digital assets are represented by tokens, which can be transferred, tracked, and stored on a blockchain. By representing assets as tokens, you can use the blockchain ledger to establish the state and ownership of an asset, and use standard blockchain platform functions to transfer ownership of an asset.

Blockchain App Builder includes tokenization support: token classes and methods are automatically generated, and additional token methods are provided so that developers can create complex business logic for tokens. The automatically generated project contains token lifecycle classes and functions, CRUD methods, and additional token SDK methods, and supports automatic validation of arguments, marshalling/unmarshalling, and transparent persistence capability. You can use these controller methods to initialize tokens, control access, set up accounts, manage roles, and manage the life cycle of tokens.

The following diagram shows the token architecture implemented by Blockchain App Builder, including the token API and token SDK. Token architecture diagram

Automatically Generated Token API: Blockchain App Builder automatically generates methods to support tokens and token life cycles. You can use these methods to initialize tokens, manage roles and accounts, and complete other token lifecycle tasks without any additional coding.
Token SDK: The Token SDK includes methods that help you develop complex business logic for token applications.
Multiversion Concurrency Control (MVCC) Optimization: The MVCC optimization for token chaincode can reduce errors for transfer, mint, burn, and hold operations.

Tokens and the Account/Balance Model

Blockchain App Builder supports fungible and non-fungible tokens. Fungible tokens have an interchangeable value. Any quantity of fungible tokens has the same value as any other equal quantity of the same class of token. Non-fungible tokens are unique. Tokens can also be either whole or fractional. Fractional tokens can be subdivided into smaller parts, based on a specified number of decimal places.

Tokens can also be described by behaviors. Supported behaviors for fungible tokens include: mintable, transferable, divisible, holdable, burnable, and roles (minter, burner, and holder). Supported behaviors for non-fungible tokens include: mintable, transferable, singleton, indivisible, burnable, and roles (minter and burner).

The tokenization feature uses an account/balance model to represent tokenized assets as balances in an account. Accounts are similar to typical banking accounts, where deposits and transfers and other state transitions affect the balance of an account. The balance of every account is tracked globally, to ensure that transaction amounts are valid. The on-hold balance (for fungible tokens) and transaction history are also tracked.

Any user who possesses tokens or completes token-related operations at any point must have an account on the network. Every account is identified by a unique ID (account_id). The account ID is created by combining a user name or email ID (user_id) of the instance owner or the user who is logged in to the instance with the membership service provider ID (org_id) of the user in the current network organization. Ready-to-use methods are provided for account creation. Because the account ID includes the organization ID, users can be supported across multiple organizations.

Token Standards

Blockchain App Builder extends the standards and classifications of the Token Taxonomy Framework, the ERC-721 standard, and the ERC-1155 standard to define the anatomy and behavior of tokens. ERC-1155 is a standard that supports both fungible and non-fungible tokens (NFTs). ERC-721 is a standard for NFTs. The Token Taxonomy Framework was developed by the Token Taxonomy Initiative. For more information, see Token Taxonomy Framework.

The following table describes the token types that Blockchain App Builder supports:

Standard	Supported Token Types
Token Taxonomy Framework	fractional fungible tokens
ERC-721	whole non-fungible tokens
ERC-1155	whole fungible tokens fractional fungible tokens whole non-fungible tokens fractional non-fungible tokens

Tokenization Flow

Because Blockchain App Builder supports tokenization by extending the input specification file syntax, you create token-specific projects the same way that you create other projects, either by using the CLI or in Visual Studio Code. For more information, see Input Specification File.

A typical tokenization flow follows these basic steps:

Decide which token standard to use.
Decide what token behaviors to specify (mintable, transferable, divisible, indivisible, singleton, holdable, burnable, and roles).
Define the token asset and its properties in the input specification file.
Scaffold the chaincode project from the input specification file. This creates a scaffolded project, including a model that contains the token asset definition and its properties and a controller that contains the token's behavior and methods.
Deploy and test the chaincode project.

After you deploy a token-based project, the typical flow for creating tokens and completing lifecycle operations follows these steps:

A token chaincode is deployed, and the users in the list passed to the initialization method become Token Admin users of the chaincode.
A tokenized asset is initialized, which creates the token_id, a unique identifier for that particular instance of token.
Accounts must be created for every user who will possess tokens or complete token-related operations.
If the roles behavior is specified for the token, then roles must be added to users before they can complete token-related operations.
Token life cycle methods can then be used, based on the behaviors that were specified for the token asset. For example, you can call a method to mint tokens for an account.

Access Control

Tokenization support includes an access control feature that supports both role-based and ownership-based control mechanisms. With role-based control, users can call specific methods with an associated role such as

Token
                    Admin

or Token Minter. With ownership-based control, you can restrict users from accessing assets that they do not own. With ownership-based access control, specific methods can be called by the users who own the assets, such as the Token Owner or

Account
                    Owner

. For specific information on access control for methods, see the individual entries for the methods documented in the following topics:

Role-based access control supports the following personas:

Token Admin: Token Admin users can be assigned when a token chaincode is deployed. The Token Admin user information is saved in the state database. A Token Admin user can grant and remove Token Admin privileges for other users. A Token Admin user cannot remove their own Token Admin privileges. A Token Admin user can assign the Org Admin, minter, burner, or notary role to any user.
Org Admin: The extended Token Taxonomy Framework methods support the Org Admin role. A Token Admin user can assign the Org Admin role to any user. Org Admin users have administrative privileges, but only within their organization. They can create accounts or see account balances, but only for users in their organization. Org Admin users who have a minter, burner, or notary role can assign that role to other users in their organization.
Token Minter: A user who is assigned the minter role is a Token Minter, and can mint tokens.
Token Burner: A user who is assigned the burner role is a Token Burner, and can burn tokens.
Token Notary: A user who is assigned the notary role is a Token Notary. A Token Notary acts as a third party in transactions between payers and payees. A Token Notary can either trigger the completion of a token transfer from a payer to a payee, or can instead return the tokens to the payer's account.
Vault Manager: A user who is assigned the vault role is the Vault Manager. The Vault Manager can unlock a locked NFT. The vault role is applicable only for the extended ERC-721 and ERC-1155 standards. Assigning the vault role to a user is a prerequisite for locking NFTs. Only one user per chaincode can be assigned the vault role.

Ownership-based access control supports the following personas:

Account Owner: Any user that has an account is an Account Owner.
Token Owner: Any user that currently owns a non-fungible token is the Token Owner of that token.

Role-based access control and ownership-based access control are also combined in some methods. For example, role-based access control lets a user with the minter role create tokens. With ownership-based access control, a non-fungible token owner can modify the custom properties of a token, but cannot modify the token metadata. When a user with the minter role creates a non-fungible token (NFT), they become the owner of the NFT. As the owner of that NFT, they can modify the custom properties (for an art collection token, the token price is a custom property). After the token creator transfers the NFT to another user, the second user becomes the owner, and the user who created the token is no longer the owner of the token. Because of ownership-based access control, the new owner can now update a custom property value, but the previous owner no longer can. Because of role-based access control, the previous owner can still mint an NFT, but the new user cannot.

You can also write your own access control functions, or disable access control. The automatically generated code that controls access is shown in the following examples.

TypeScript:

await this.Ctx.<Token Standard>Auth.checkAuthorization(...)

Go:

auth, err := t.Ctx.<Token Standard>Auth.CheckAuthorization(...)

Note:

To remove the automatically generated access control function, remove the previous line of code from your TypeScript or Go project.

MVCC Optimization

Hyperledger Fabric databases use multi-version concurrency control (MVCC) to avoid double-spending and data inconsistency. When the same state is updated, a new version of the record overwrites the old version. If there are concurrent requests to update the same key in a block, an MVCC_READ_CONFLICT error might be generated.

To reduce MVCC errors for transfer, mint, burn, and hold operations, you can enable the MVCC optimization for token chaincode. This optimization works on Oracle Blockchain Platform only. By default, the optimization is disabled. To enable the optimization, complete the applicable following step.

CLI: Specify the Boolean -m or --enable_mvcc_optimization parameter with the ochain init command. By default, the parameter is set to false. To enable the optimization, add -m true to the ochain init command line.
Visual Studio Code: When you create a chaincode, select Enable MVCC optimization on the Create Chaincode window.

To use the optimization with chaincode created in previous versions of Blockchain App Builder, complete the following steps:

After you install the latest version of Blockchain App Builder, upgrade the chaincode as described in Upgrading Chaincode Projects in the CLI and Upgrading Chaincode Projects in Visual Studio Code.
Edit the .ochain.json file in the root folder of the chaincode to set enableMvccOptimization to true.
Synchronize the chaincode, which adds the optimization and creates two new folders in the root folder of the the chaincode: statedb and tokens. For more information about synchronization, see Synchronize Specification File Changes With Generated Source Code and Synchronize Specification File Changes With Generated Source Code.

Other methods to work around MVCC_READ_CONFLICT errors including having the client application retry requests when this error is generated, or using a queue to capture concurrent requests before they are sent to the blockchain network. For more information, see Read-Write set semantics in the Hyperledger Fabric documentation.

Note:

The MVCC optimization does not work on hybrid networks that include both Oracle Blockchain Platform and Hyperledger Fabric peers, or for testing on a local Hyperledger Fabric network. Do not enable the MVCC optimization on hybrid networks, as this might lead to inconsistencies between peers.