1. Using Oracle Blockchain Platform
  2. Build Chaincodes with Low-Code Blockchain App Builder
  3. Tokenization Support Using Blockchain App Builder
  4. Token Taxonomy Framework
  5. Scaffolded TypeScript Project for Token Taxonomy Framework

Scaffolded TypeScript Project for Token Taxonomy Framework

Blockchain App Builder takes the input from your token specification file and generates a fully-functional scaffolded chaincode project.

The project automatically generates token lifecycle classes and functions, including CRUD and non-CRUD methods. Validation of arguments, marshalling/unmarshalling, and transparent persistence capability are all supported automatically.

For information on the scaffolded project and methods that are not directly related to tokens, see Scaffolded TypeScript Chaincode Project.

Reference:

Model

Every tokenized model class extends the Token class, which in turn extends the OchainModel class. The Token class is imported from ../lib/token. Transparent Persistence Capability, or simplified ORM, is captured in the OchainModel class. 

import * as yup from 'yup';
import { Id, Mandatory, Validate, ReadOnly } from '../lib/decorators';
import { Token } from '../lib/token';
 
@Id('token_id')
export class Digicur extends Token<Digicur> {
 
    public readonly assetType = 'otoken';
 
    @Mandatory()
    @Validate(yup.string().required().matches(/^[A-Za-z0-9][A-Za-z0-9_-]*$/).max(16))
    public token_id: string;
 
    @ReadOnly('digicur')
    public token_name: string;
 
    @Validate(yup.string().trim().max(256))
    public token_desc: string;
 
    @ReadOnly('fungible')
    public token_type: string;
 
    @ReadOnly(["divisible","mintable","transferable","burnable","holdable","roles"])
    public behaviors: string[];
 
    @ReadOnly({minter_role_name: "minter", burner_role_name: "burner", notary_role_name: "notary"})
    public roles: object;
 
    @ReadOnly({max_mint_quantity: 20000})
    public mintable: object;
 
    @ReadOnly({decimal: 1})
    public divisible: object;
 
    @Validate(yup.number())
    public token_to_currency_ratio: number;
 
    @Validate(yup.string())
    public currency_representation: string;
 
}

Controller

The main controller class extends the OchainController class. There is only one main controller. 

export class DigiCurrCCController extends OchainController{

You can create any number of classes, functions, or files, but only those methods that are defined within the main controller class are invokable. The other methods are hidden.

You can use the token SDK methods to write custom methods for your business application.

Automatically Generated Token Methods

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. Controller methods must have a @Validator(...params) decorator to be invokable.

Methods for Access Control Management

addTokenAdmin
This method adds a user as a Token Admin of the chaincode. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string())
public async addTokenAdmin(org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization('ADMIN.addAdmin', 'TOKEN');
    return await this.Ctx.Admin.addAdmin(org_id, user_id);
}
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the user who was added as a Token Admin of the chaincode.
Return Value Example:
{"msg":"Successfully added Admin (Org_Id: Org1MSP, User_Id: User1)"}
removeTokenAdmin
This method removes a user as a Token Admin of the chaincode. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string())
public async removeTokenAdmin(org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization('ADMIN.removeAdmin', 'TOKEN');
    return await this.Ctx.Admin.removeAdmin(org_id, user_id);
}
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the user who was removed as a Token Admin of the chaincode.
Return Value Example:
{"msg": "Successfully removed Admin (Org_Id: Org1MSP, User_Id: User1)"}
isTokenAdmin
This method returns the Boolean value true if the caller of the function is a Token Admin, otherwise it returns false. A Token Admin or Org Admin can call this function on any other user in the blockchain network. Other users can call this method only on their own accounts. 
@Validator(yup.string(), yup.string())
  public async isTokenAdmin(org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ADMIN.isUserTokenAdmin", "TOKEN");
    return await this.Ctx.Auth.isUserTokenAdmin(org_id, user_id);
  }
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • The method returns true if the caller is a Token Admin, otherwise it returns false.
getAllTokenAdmins
This method returns a list of all users who are a Token Admin of the chaincode. This method can be called only by the Token Admin or any Org Admin of the chaincode. 
@Validator()
public async getAllTokenAdmins() {
    await this.Ctx.Auth.checkAuthorization('ADMIN.getAllAdmins', 'TOKEN');
    return await this.Ctx.Admin.getAllAdmins();
}
Parameters:
  • none
Returns:
  • On success, an admins array in JSON format that contains orgId and userId objects.
Return Value Example:
{"admins":[{"org_id":"Org1MSP","user_id":"admin"}]}
addOrgAdmin
This method adds a user as an Org Admin of the organization. This method can be called only by a Token Admin of the chaincode or an Org Admin of the specified organization. 
@Validator(yup.string(), yup.string())
  public async addOrgAdmin(org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ADMIN.addOrgAdmin", "TOKEN", { org_id });
    return await this.Ctx.Admin.addOrgAdmin(org_id, user_id);
  }
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the user who was added as an Org Admin of the organization.
Return Value Example:
{
    "msg": "Successfully added Org Admin (Org_Id: Org1MSP, User_Id: orgAdmin)"
}
removeOrgAdmin
This method removes a user as an Org Admin of the organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization. 
@Validator(yup.string(), yup.string())
  public async removeOrgAdmin(org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ADMIN.removeOrgAdmin", "TOKEN", { org_id });
    return await this.Ctx.Admin.removeOrgAdmin(org_id, user_id);
  }
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the user who was removed as an Org Admin of the organization.
Return Value Example:
{
  "msg": "Successfully removed Org Admin (Org_Id Org1MSP User_Id orgAdmin)"
}
getOrgAdmins
This method returns a list of all users who are an Org Admin of an organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of any organization. 
  @Validator()
  public async getOrgAdmins() {
    await this.Ctx.Auth.checkAuthorization("ADMIN.getOrgAdmins", "TOKEN");
    return await this.Ctx.Admin.getAllOrgAdmins();
  }
Parameters:
  • none
Returns:
  • On success, an array in JSON format that contains orgId and userId objects.
Return Value Example:
{
    "admins": [
        {
            "org_id": "Org1MSP",
            "user_id": "orgadmin"
        },
        {
            "org_id": "Org1MSP",
            "user_id": "orgadmin1"
        },
        {
            "org_id": "Org1MSP",
            "user_id": "orgadmin2"
        }
    ]
}

Methods for Token Configuration Management

init
This method is called when the chaincode is deployed or upgraded. Every Token Admin is identified by the user_id and org_id information in the mandatory adminList parameter. The user_id is the user name or email ID of the instance owner or the user who is logged in to the instance. The org_id is the membership service provider (MSP) ID of the user in the current network organization.
Any Token Admin user can add and remove other Token Admin users by calling the addAdmin and removeAdmin methods. 
public async init(adminList: TokenAdminAsset[]) {
    await this.Ctx.Admin.initAdmin(adminList);
    return;
}
Parameters:
  • adminList array – An array of {user_id, org_id} information that specifies the list of token admins. The adminList array is a mandatory parameter.
Parameter example, Mac OSX and Linux CLI:
'[{"user_id":"userid", "org_id":"OrgMSPId"}]'
Parameter example, Microsoft Windows CLI:
"[{\"user_id\":\"userid\", \"org_id\":\"OrgMSPId\"}]"
Parameter example, Oracle Blockchain Platform console:
["[{\"user_id\":\"userid\", \"org_id\":\"OrgMSPId\"}]"]
initialize<Token Name>Token
This method creates a token and initializes the token properties. The asset and its properties are saved in the state database. This method can be invoked only by a Token Admin of the chaincode. 
@Validator(Digicur)
    public async initializeDigicurToken(token_asset: Digicur) {
        await this.Ctx.Auth.checkAuthorization('TOKEN.save', 'TOKEN');
        return await this.Ctx.Token.save(token_asset)
    }
Parameters:
  • asset: <Token Class> – The token asset is passed as the parameter to this method. The properties of the token asset are described in the model file.
Returns:
  • On success, a JSON representation of the token asset that was created.
Return Value Example:
{
    "assetType": "otoken",
    "token_id": "digiCurr101",
    "token_name": "digicur",
    "token_type": "fungible",
    "behaviors": [
        "divisible",
        "mintable",
        "transferable",
        "burnable",
        "roles"
    ],
    "roles": {
        "minter_role_name": "minter"
    },
    "mintable": {
        "max_mint_quantity": 1000
    },
    "divisible": {
        "decimal": 2
    },
    "currency_name": "DOLLAR",
    "token_to_currency_ratio": 1
}
update<Token Name>Token
This method updates token properties. After a token asset is created, only the token_desc property and custom properties can be updated. This method can be called only by a Token Admin of the chaincode. 
@Validator(Digicur)
public async updateDigicurToken(token_asset: Digicur) {
    await this.Ctx.Auth.checkAuthorization('TOKEN.update', 'TOKEN');
    return await this.Ctx.Token.update(token_asset);
}
Parameters:
  • asset: <Token Class> – The token asset is passed as the parameter to this method. The properties of the token asset are described in the model file.
Returns:
  • On success, an updated JSON representation of the token asset.
Return Value Example:
{
    "assetType": "otoken",
    "token_id": "digiCurr101",
    "token_name": "digicur",
    "token_desc": "Digital Currency equiv of dollar",
    "token_type": "fungible",
    "behaviors": [
        "divisible",
        "mintable",
        "transferable",
        "burnable",
        "roles"
    ],
    "roles": {
        "minter_role_name": "minter"
    },
    "mintable": {
        "max_mint_quantity": 1000
    },
    "divisible": {
        "decimal": 2
    },
    "currency_name": "DOLLAR",
    "token_to_currency_ratio": 1
}
getTokenDecimals
This method returns the number of decimal places that were configured for a fractional token. If the divisible behavior was not specified for the token, then the default value is 0. This method can be called only by a Token Admin or Org Admin of the chaincode. 
@Validator(yup.string())
public async getTokenDecimals(token_id: string) {
    const token_asset = await this.getTokenObject(token_id);
    await this.Ctx.Auth.checkAuthorization('TOKEN.getDecimals', 'TOKEN');
    return {
        msg: `Token Id: ${token_id} has ${this.Ctx.Token.getDecimals(token_asset)} decimal places.`
    };
}
Parameters:
  • token_id: string – The ID of the token.
Returns:
  • On success, a JSON string showing the number of token decimal places.
Return Value Example:
{"msg":"Token Id: digiCurr101 has 1 decimal places."}
getTokenById
This method returns a token object if it is present in the state database. This method can be called only by a Token Admin or an Org Admin of the chaincode. 
@Validator(yup.string())
public async getTokenById(token_id: string) {
    await this.Ctx.Auth.checkAuthorization('TOKEN.get', 'TOKEN');
    const token = await this.getTokenObject(token_id);
    return token;
}
Parameters:
  • token_id: string – The ID of the token.
Returns:
  • On success, a JSON object that represents the token asset.
Return Value Example:
{
    "assetType": "otoken",
    "token_id": "digiCurr101",
    "token_name": "digicur",
    "token_desc": "Digital Currency equiv of dollar",
    "token_type": "fungible",
    "behaviors": [
        "divisible",
        "mintable",
        "transferable",
        "burnable",
        "roles"
    ],
    "roles": {
        "minter_role_name": "minter"
        "burner_role_name": "burner",
        "notary_role_name": "notary"
    },
    "mintable": {
        "max_mint_quantity": 2000
    },
    "divisible": {
        "decimal": 1
    },
    "currency_name": "DOLLAR",
    "token_to_currency_ratio": 1
}
getTokenHistory
This method returns the token history for a specified token ID. Any user can call this method.
  @Validator(yup.string())
  public async getTokenHistory(tokenId: string) {
    await this.Ctx.Auth.checkAuthorization("TOKEN.getTokenHistory", "TOKEN");
    return await this.Ctx.Token.history(tokenId);
  }
Parameters:
  • tokenId: string – The ID of the token.
Returns:
  • On success, a JSON object that represents the token history.
Return Value Example:

[
    {
        "trxId": "0d75f09446a60088afb948c6aca046e261fddcd43df416076201cdc5565f1a35",
        "timeStamp": "2023-09-01T16:48:41.000Z",
        "value": {
            "assetType": "otoken",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "token_desc": "updatedDesc",
            "token_standard": "ttf+",
            "token_type": "fungible",
            "token_unit": "fractional",
            "behaviors": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "roles": {
                "minter_role_name": "minter"
            },
            "mintable": {
                "max_mint_quantity": 1000
            },
            "divisible": {
                "decimal": 2
            }
        }
    },
    {
        "trxId": "3666344878b043b65d5b821cc79c042ba52aec467618800df5cf14eac69f72fa",
        "timeStamp": "2023-08-31T20:24:55.000Z",
        "value": {
            "assetType": "otoken",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "token_standard": "ttf+",
            "token_type": "fungible",
            "token_unit": "fractional",
            "behaviors": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "roles": {
                "minter_role_name": "minter"
            },
            "mintable": {
                "max_mint_quantity": 1000
            },
            "divisible": {
                "decimal": 2
            }
        }
    }
]
getAllTokens
This method returns all tokens that are stored in the state database. This method can be called only by a Token Admin or an Org Admin of the chaincode. This method uses Berkeley DB SQL rich queries and can only be called when connected to the remote Oracle Blockchain Platform network. 
@Validator()
public async getAllTokens() {
    await this.Ctx.Auth.checkAuthorization('TOKEN.getAllTokens', 'TOKEN');
    return await this.Ctx.Token.getAllTokens();
}
Parameters:
  • none
Returns:
  • On success, a JSON object that represents all token assets.
getTokensByName
This method returns all token objects with a specified name. This method can be called only by a Token Admin or Org Admin of the chaincode. This method uses Berkeley DB SQL rich queries and can only be called when connected to the remote Oracle Blockchain Platform network. 
@Validator(yup.string())
public async getTokensByName(token_name: string) {
    await this.Ctx.Auth.checkAuthorization('TOKEN.getTokensByName', 'TOKEN');
    return await this.Ctx.Token.getTokensByName(token_name);
}
Parameters:
  • token_name: string – The name of the tokens to retrieve. The name corresponds to the token_name property in the specification file. The value is the class name of the token.
Returns:
  • On success, a JSON object of all token assets that match the name.

Methods for Account Management

createAccount
This method creates an account for a specified user and token. An account must be created for any user who will have tokens at any point. Accounts track balances, on-hold balances, and transaction history. An account ID is an alphanumeric set of characters, prefixed with oaccount~<token asset name>~ and followed by a hash of the user name or email ID (user_id) of the instance owner or the user who is logged in to the instance, the membership service provider ID (org_id) of the user in the current network organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization. 
  @Validator(yup.string(), yup.string(), yup.string())
  public async createAccount(org_id: string, user_id: string, token_type: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.createAccount", "TOKEN", { org_id });
    return await this.Ctx.Account.createAccount(org_id, user_id, token_type);
  }
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
  • token_type: string – The type of the token, which must be fungible.
Returns:
  • On success, a JSON object of the account that was created. The bapAccountVersion parameter is defined in the account object for internal use.
Return Value Example:
{
  "assetType": "oaccount",
  "account_id": "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
  "bapAccountVersion": 0,
  "user_id": "admin",
  "org_id": "Org1MSP",
  "token_type": "fungible",
  "token_id": "",
  "token_name": "",
  "balance": 0,
  "onhold_balance": 0
}
associateTokenToAccount
This method associates a fungible token with an account. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the relevant organization. 
  @Validator(yup.string(), yup.string())
  public async associateTokenToAccount(account_id: string, token_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.associateToken", "TOKEN", { account_id });
    return await this.Ctx.Account.associateToken(account_id, token_id);
  }
Parameters:
  • account_id: string – The ID of the account.
  • token_id: string – The ID of the token.
Returns:
  • On success, a JSON object of the updated account. The bapAccountVersion parameter is defined in the account object for internal use.
Return Value Example:
{
    "assetType": "oaccount",
    "account_id": "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
    "bapAccountVersion": 0,
    "user_id": "admin",
    "org_id": "Org1MSP",
    "token_type": "fungible",
    "token_id": "fungible",
    "token_name": "fiatmoneytok",
    "balance": 0,
    "onhold_balance": 0
}
getAccount
This method returns account details for a specified user and token. This method can be called only by a Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. 
@Validator(yup.string(), yup.string(), yup.string())
public async getAccount(token_id: string, org_id: string, user_id: string) {
  const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
  await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAccount", "TOKEN", { account_id });
  return await this.Ctx.Account.getAccountWithStatus(account_id);
}
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON account object that includes the following properties:
  • account_id – The ID of the user account.
  • user_id – The user name or email ID of the user.
  • org_id – The membership service provider (MSP) ID of the user in the current organization.
  • token_id – The ID of the token.
  • token_name – The name of the token.
  • balance – The current balance of the account.
  • onhold_balance – The current on-hold balance of the account.
  • bapAccountVersion – An account object parameter for internal use.
  • status – The current status of the user account.
Return Value Example:
{
  "bapAccountVersion": 0,
  "assetType": "oaccount",
  "status": "active",
  "account_id": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
  "user_id": "idcqa",
  "org_id": "appdev",
  "token_type": "fungible",
  "token_id": "t1",
  "token_name": "obptok",
  "balance": 0,
  "onhold_balance": 0
}
getAccountHistory
This method returns account history details for a specified user and token. This method can be called only by a Token Admin of the chaincode or the AccountOwner of the account. 
  @Validator(yup.string(), yup.string(), yup.string())
  public async getAccountHistory(token_id: string, org_id: string, user_id: string) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.history", "TOKEN", { account_id });
    return await this.Ctx.Account.history(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, an array of JSON account objects that includes the following properties:
  • trxId – The transaction ID of the transaction as returned by the ledger.
  • timeStamp – The time of the transaction.
  • value – A JSON string of the account object.
Return Value Example:
[
    {
      "trxId":"2gsdh17fff222467e5667be042e33ce18e804b3e065cca15de306f837e416d7c3e",
      "timeStamp":1629718288,
      "value":{
         "assetType":"oaccount",
         "account_id":"oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
         "user_id":"user1",
         "org_id":"Org1MSP",
         "token_id":"digiCurr101",
         "token_name":"digicur",
         "balance":100,
         "onhold_balance":0,
         "bapAccountVersion": 1
   },
   {
      "trxId":"9fd07fff222467e5667be042e33ce18e804b3e065cca15de306f837e416d7c3e",
      "timeStamp":1629718288,
      "value":{
         "assetType":"oaccount",
         "account_id":"oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
         "user_id":"user1",
         "org_id":"Org1MSP",
         "token_id":"digiCurr101",
         "token_name":"digicur",
         "balance":0,
         "onhold_balance":0,
         "bapAccountVersion": 0
      }
   }
]
getAccountOnHoldBalance
This method returns the current on-hold balance for a specified account and token. This method can be called only by a Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. 
  @Validator(yup.string(), yup.string(), yup.string())
  public async getAccountOnHoldBalance(token_id: string, org_id: string, user_id: string) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAccountOnHoldBalance", "TOKEN", { account_id });
    return await this.Ctx.Account.getAccountOnHoldBalance(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON representation of the current on-hold balance.
Return Value Example:
{"msg":"Total Holding Balance is: 0","holding_balance":0}
getAllAccounts
This method returns a list of all accounts. This method can be called only by a Token Admin of the chaincode. This method uses Berkeley DB SQL rich queries and can only be called when connected to the remote Oracle Blockchain Platform network. 
@Validator()
public async getAllAccounts() {
    await this.Ctx.Auth.checkAuthorization('ACCOUNT.getAllAccounts', 'TOKEN');
    return await this.Ctx.Account.getAllAccounts();
}
Parameters:
  • none
Returns:
  • On success, a JSON array of all accounts.
getUserByAccountId
This method returns user details (org_id and user_id) for a specified account. This method can be called by any user of the chaincode. 
@Validator(yup.string())
public async getUserByAccountId(account_id: string) {
    return await this.Ctx.Account.getUserByAccountId(account_id);
}
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a JSON object of the user details (org_id, token_id, and user_id).
Return Value Example:
{
    "token_id": "digiCurr101",
    "user_id": "user1",
    "org_id": "Org1MSP"
}
getAccountBalance
This method returns the current balance for a specified account and token. This method can be called only by a Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. 
  @Validator(yup.string(), yup.string(), yup.string())
  public async getAccountBalance(token_id: string, org_id: string, user_id: string) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAccountBalance", "TOKEN", { account_id });
    return await this.Ctx.Account.getAccountBalance(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON representation of the current account balance.
Return Value Example:
{"msg":"Current Balance is: 0","user_balance":0}
getAllOrgAccounts
This method returns a list of all token accounts that belong to a specified organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization. 
  @Validator(yup.string())
  public async getAllOrgAccounts(org_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAllOrgAccounts", "TOKEN", { org_id });
    return await this.Ctx.Account.getAllOrgAccounts(org_id);
  }
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the organization.
Returns:
  • On success, a list of all accounts for the specified organization.
Return Value Example:
[
    {
        "key": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
        "valueJson": {
            "bapAccountVersion": 0,
            "assetType": "oaccount",
            "account_id": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
            "user_id": "idcqa",
            "org_id": "appdev",
            "token_type": "fungible",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "balance": 0,
            "onhold_balance": 0
        }
    },
    {
        "key": "oaccount~620fcf5deb5fd5a65c0b5b10fda129de0f629ccd232c5891c130e24a574df50a",
        "valueJson": {
            "bapAccountVersion": 0,
            "assetType": "oaccount",
            "account_id": "oaccount~620fcf5deb5fd5a65c0b5b10fda129de0f629ccd232c5891c130e24a574df50a",
            "user_id": "example_minter",
            "org_id": "appdev",
            "token_type": "fungible",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "balance": 0,
            "onhold_balance": 0
        }
    }
]

Methods for Role Management

addRole
This method adds a role to a specified user and token. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization who also holds the specified role. 
  @Validator(yup.string(), yup.string(), yup.string(), yup.string())
  public async addRole(token_id: string, role: string, org_id: string, user_id: string) {
    const token_asset = await this.getTokenObject(token_id);
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("TOKEN.addRoleMember", "TOKEN", { token_id, org_id, role });
    return await this.Ctx.Token.addRoleMember(role, account_id, token_asset);
  }
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to add to the specified user. The mintable and burnable behaviors correspond to the minter_role_name and burner_role_name properties of the specification file. Similarly, the notary role corresponds to the notary_role_name property of the specification file.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message with account details.
Return Value Example:
{"msg":"Successfully added role 'minter' to Account Id: oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (Org-Id: Org1MSP, User-Id: user1)"}
removeRole
This method removes a role from a specified user and token. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization who also holds the specified role. 
  @Validator(yup.string(), yup.string(), yup.string(), yup.string())
  public async removeRole(token_id: string, role: string, org_id: string, user_id: string) {
    const token_asset = await this.getTokenObject(token_id);
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("TOKEN.removeRoleMember", "TOKEN", { token_id, org_id, role });
    return await this.Ctx.Token.removeRoleMember(role, account_id, token_asset);
  }
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to remove from the specified user. The mintable and burnable behaviors correspond to the minter_role_name and burner_role_name properties of the specification file. Similarly, the notary role corresponds to the notary_role_name property of the specification file.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message with account details.
Return Value Example:
{"msg":"Successfully removed role 'minter' from Account Id: oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (Org-Id: Org1MSP, User-Id: user1)"}
getAccountsByRole
This method returns a list of all account IDs for a specified role and token. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string())
public async getAccountsByRole(token_id: string, role: string) {
   await this.Ctx.Auth.checkAuthorization('ROLE.getAccountsByRole', 'TOKEN');
   return await this.Ctx.Role.getAccountsByRole(token_id, role);
}
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to search for.
Returns:
  • On success, a JSON array of account IDs.
Return Value Example:
{"accounts":["oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f"]}
getAccountsByUser
This method returns a list of all account IDs for a specified organization ID and user ID. This method can be called only by the Token Admin of the chaincode, by the Org Admin of the specified organization, or by the Account Owner specified in the parameters. 
  @Validator(yup.string(), yup.string())
  public async getAccountsByUser(org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAccountsByUser", "TOKEN", { org_id, user_id });
    return await this.Ctx.Account.getAccountsByUser(org_id, user_id);
  }
Parameters:
  • org_id string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id string – The user name or email ID of the user.
Returns:
  • On success, a JSON array of account IDs.
Return Value Example:
{"accounts":["oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f"]}
getUsersByRole
This method returns a list of all users for a specified role and token. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string())
public async getUsersByRole(token_id: string, role: string) {
    await this.Ctx.Auth.checkAuthorization('ROLE.getUsersByRole', 'TOKEN');
    return await this.Ctx.Role.getUsersByRole(token_id, role);
}
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to search for.
Returns:
  • On success, a JSON array of the user objects (org_id, token_id, and user_id).
Return Value Example:
{"users":[{"token_id":"digiCurr101","user_id":"user1","org_id":"Org1MSP"}]}
isInRole
This method returns a Boolean value to indicate if a user and token has a specified role. This method can be called only by a Token Admin of the chaincode, the AccountOwner of the account, or an Org Admin of the specified organization. 
  @Validator(yup.string(), yup.string(), yup.string(), yup.string())
  public async isInRole(token_id: string, org_id: string, user_id: string, role: string) {
    const token_asset = await this.getTokenObject(token_id);
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("TOKEN.isInRole", "TOKEN", { account_id });
    return { result: await this.Ctx.Token.isInRole(role, account_id, token_asset) };
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
  • role: string – The name of the role to search for.
Returns:
  • On success, a JSON string of the Boolean result.
Return Value Example:
{"result":"false"}
getOrgAccountsByRole
This method returns information about all accounts that have a specified role in a specified organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization. 
   @Validator(yup.string(), yup.string(), yup.string())
  public async getOrgAccountsByRole(token_id: string, role: string, org_id: string) {
    await this.Ctx.Auth.checkAuthorization("ROLE.getOrgAccountsByRole", "TOKEN", { org_id });
    return await this.Ctx.Role.getOrgAccountsByRole(token_id, role, org_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to check for.
  • org_id: string – The membership service provider (MSP) ID of the organization.
Returns:
  • On success, a list of all accounts with the specified role in the specified organization.
Return Value Example:
{
    "accounts": [
        "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
        "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850"
    ]
}
getOrgUsersByRole
This method returns information about all users that have a specified role in a specified organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization. 
  @Validator(yup.string(), yup.string(), yup.string())
  public async getOrgUsersByRole(token_id: string, role: string, org_id: string) {
    await this.Ctx.Auth.checkAuthorization("ROLE.getOrgUsersByRole", "TOKEN", { org_id });
    return await this.Ctx.Role.getOrgUsersByRole(token_id, role, org_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to check for.
  • org_id: string – The membership service provider (MSP) ID of the organization.
Returns:
  • On success, a list of all users with the specified role in the specified organization.
Return Value Example:
{
    "users": [
        {
            "token_id": "token",
            "user_id": "admin",
            "org_id": "Org1MSP"
        },
        {
            "token_id": "token",
            "user_id": "orgAdmin",
            "org_id": "Org1MSP"
        }
    ]
}

Methods for Transaction History Management

getAccountTransactionHistory
This method returns an array of account transaction history details for a specified user and token. This method can be called only by the Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. 
 @Validator(yup.string(), yup.string(), yup.string())
  public async getAccountTransactionHistory(token_id: string, org_id: string, user_id: string) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAccountTransactionHistory", "TOKEN", { account_id });
    return await this.Ctx.Account.getAccountTransactionHistory(account_id, org_id, user_id.toLowerCase());
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, an array of JSON account transaction objects that includes the following properties:
  • transaction_id – The ID of the transaction.
  • transacted_account – The account with which the transaction took place.
  • transaction_type – The type of transaction.
  • transacted_amount – The amount of the transaction.
  • timestamp – The time of the transaction.
  • balance – The account balance at the time of the transaction.
  • onhold_balance – The on-hold balance at the time of the transaction.
  • token_id – The ID of the token.
  • holding_id – A unique identifier returned by the holdTokens method.
Return Value Example:
[
    {
        "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
        "transacted_amount": 20,
        "timestamp": "2021-08-17T06:04:24.000Z",
        "balance": 930,
        "onhold_balance": 0,
        "token_id": "digiCurr101",
        "transaction_type": "BULKTRANSFER",
        "sub_transactions": [
            {
                "transacted_account": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                "transaction_type": "DEBIT",
                "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c4ca4238a0b923820dcc509a6f75849b",
                "transacted_amount": 10
            },
            {
                "transacted_account": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
                "transaction_type": "DEBIT",
                "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c81e728d9d4c2f636f067f89cc14862c",
                "transacted_amount": 10
            }
        ]
    },
    {
        "transaction_id": "otransaction~757864d5369bd0539d044caeb3bb4898db310fd7aa740f45a9938771903d43da",
        "transacted_amount": 50,
        "timestamp": "2021-08-17T06:02:44.000Z",
        "balance": 950,
        "onhold_balance": 0,
        "token_id": "digiCurr101",
        "transacted_account": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
        "transaction_type": "DEBIT"
    }
]
getAccountTransactionHistoryWithFilters
This method returns an array of account transaction history details for a specified user and token. This method can be called only by the Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. This method can only be called when connected to the remote Oracle Blockchain Platform network. 
  @Validator(yup.string(), yup.string(), yup.string(), yup.object().nullable())
  public async getAccountTransactionHistoryWithFilters(token_id: string, org_id: string, user_id: string, filters?: Filters) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getAccountTransactionHistoryWithFilters", "TOKEN", { account_id });
    return await this.Ctx.Account.getAccountTransactionHistoryWithFilters(account_id, org_id, user_id.toLowerCase(), filters);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
  • filters: string – An optional parameter. If empty, all records are returned. The PageSize property determines the number of records to return. If PageSize is 0, the default page size is 20. The Bookmark property determines the starting index of the records to return. For more information, see the Hyperledger Fabric documentation. The StartTime and EndTime properties must be specified in RFC-3339 format.
Example:

ochain invoke GetAccountTransactionHistoryWithFilters 'token1' 'appbuilder12' 'user_minter' '{"PageSize":10,"Bookmark":"1","StartTime":"2022-01-25T17:41:42Z","EndTime":"2022-01-25T17:59:10Z"}'

[
  {
    "transaction_id": "otransaction~672897b5a4fa78b421c000e4d6d4f71f3d46529bfbb5b4be10bf5471dc35ce89",
    "transacted_amount": 5,
    "timestamp": "2022-04-20T15:46:04.000Z",
    "token_id": "tokenId",
    "transacted_account": "oaccount~16c38d804413ebabf416360d374f76c973d4e71c74adfde73cc40c7c274883b8",
    "transaction_type": "DEBIT",
    "balance": 90,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~467bb67a33aaffca4487f33dcd46c9844efdb5421a2e7b6aa2d53152eb2c6d85",
    "transacted_amount": 5,
    "timestamp": "2022-04-20T15:45:47.000Z",
    "token_id": "tokenId",
    "transacted_account": "oaccount~fbf95683b21bbc91a22205819ac1e2e9c90355d536821ed3fe22b7d23915c248",
    "transaction_type": "DEBIT",
    "balance": 95,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~c6d56ce54a9bbe24597d1d10448e39316dc6f16328bf3c5b0c8ef10e1dfeb397",
    "transacted_amount": 100,
    "timestamp": "2022-04-20T15:44:26.000Z",
    "token_id": "tokenId",
    "transacted_account": "oaccount~deb5fb0906c40506f6c2d00c573b774e01a53dd91499e651d92ac4778b6add6a",
    "transaction_type": "MINT",
    "balance": 100,
    "onhold_balance": 0
  }
]
getSubTransactionById
This method returns an array of account transaction history details for a specified user and token. This method can be called only by the Token Admin of the chaincode or the AccountOwner of the account. 
  @Validator(yup.string())
  public async getSubTransactionsById(transaction_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getSubTransactionsById", "TOKEN", { transaction_id });
    return await this.Ctx.Account.getSubTransactionsById(transaction_id);
  }
Parameters:
  • transaction_id: string – The ID of the bulk transfer transaction.
Returns:
  • An array of account subtransaction objects in JSON format for a specified bulk transfer transaction ID.
Example:

ochain invoke GetAccountSubTransactionHistory 'otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b'

[
    {
        "transacted_account": "oaccount~16c38d804413ebabf416360d374f76c973d4e71c74adfde73cc40c7c274883b8",
        "transaction_type": "DEBIT",
        "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c81e728d9d4c2f636f067f89cc14862c",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:52:21.000Z",
        "token_id": "token1",
        "balance": 80,
        "onhold_balance": 0
    },
    {
        "transacted_account": "oaccount~fbf95683b21bbc91a22205819ac1e2e9c90355d536821ed3fe22b7d23915c248",
        "transaction_type": "DEBIT",
        "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c4ca4238a0b923820dcc509a6f75849b",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:52:21.000Z",
        "token_id": "token1",
        "balance": 85,
        "onhold_balance": 0
    }
]
getSubTransactionsByIdWithFilters
This method returns an array of account subtransaction history details for a specified transaction.
  @Validator(yup.string(), yup.object().nullable())
  public async getSubTransactionsByIdWithFilters(transaction_id: string, filters?: SubTransactionFilters) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getSubTransactionsByIdWithFilters", "TOKEN", { transaction_id });
    return await this.Ctx.Account.getSubTransactionsByIdWithFilters(transaction_id, filters);
  }
Parameters:
  • transaction_id: string – The ID of the transaction.
  • filters: string – An optional parameter. If empty, all records are returned. The PageSize property determines the number of records to return. If PageSize is 0, the default page size is 20. The Bookmark property determines the starting index of the records to return. For more information, see the Hyperledger Fabric documentation. The StartTime and EndTime properties must be specified in RFC-3339 format.
Returns:
  • An array of account subtransaction objects in JSON format for a specified bulk transfer transaction ID.
Example:

ochain invoke GetAccountSubTransactionHistoryWithFilters 'otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b' '{"PageSize":10,"Bookmark":"1"}'

[
  {
    "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c81e728d9d4c2f636f067f89cc14862c",
    "transacted_amount": 5,
    "timestamp": "2022-04-20T15:52:21.000Z",
    "token_id": "tokenId",
    "transacted_account": "oaccount~16c38d804413ebabf416360d374f76c973d4e71c74adfde73cc40c7c274883b8",
    "transaction_type": "DEBIT",
    "balance": 80,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c4ca4238a0b923820dcc509a6f75849b",
    "transacted_amount": 5,
    "timestamp": "2022-04-20T15:52:21.000Z",
    "token_id": "tokenId",
    "transacted_account": "oaccount~fbf95683b21bbc91a22205819ac1e2e9c90355d536821ed3fe22b7d23915c248",
    "transaction_type": "DEBIT",
    "balance": 85,
    "onhold_balance": 0
  }
]
getTransactionById
This method returns the history of a Transaction asset. 
@Validator(yup.string())
    public async getTransactionById(transaction_id: string) {
        return await this.Ctx.Transaction.getTransactionById(transaction_id);
    }
Parameters:
  • transaction_id string – The ID of the transaction asset.
Returns:
  • On success, an JSON array of the history for the transaction.
Return Value Example:
{
    "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
    "history": [
        {
            "trxId": "68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
            "timeStamp": 1629180264,
            "value": {
                "assetType": "otransaction",
                "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
                "token_id": "digiCurr101",
                "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
                "to_account_id": "",
                "transaction_type": "BULKTRANSFER",
                "amount": 20,
                "timestamp": "2021-08-17T06:04:24.000Z",
                "number_of_sub_transactions": 2,
                "holding_id": ""
            }
        }
    ],
    "sub_transactions": [
        {
            "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c4ca4238a0b923820dcc509a6f75849b",
            "history": [
                {
                    "trxId": "68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
                    "timeStamp": 1629180264,
                    "value": {
                        "assetType": "otransaction",
                        "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c4ca4238a0b923820dcc509a6f75849b",
                        "token_id": "digiCurr101",
                        "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
                        "to_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                        "transaction_type": "TRANSFER",
                        "amount": 10,
                        "timestamp": "2021-08-17T06:04:24.000Z",
                        "number_of_sub_transactions": 0,
                        "holding_id": ""
                    }
                }
            ]
        },
        {
            "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c81e728d9d4c2f636f067f89cc14862c",
            "history": [
                {
                    "trxId": "68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
                    "timeStamp": 1629180264,
                    "value": {
                        "assetType": "otransaction",
                        "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c81e728d9d4c2f636f067f89cc14862c",
                        "token_id": "digiCurr101",
                        "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
                        "to_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
                        "transaction_type": "TRANSFER",
                        "amount": 10,
                        "timestamp": "2021-08-17T06:04:24.000Z",
                        "number_of_sub_transactions": 0,
                        "holding_id": ""
                    }
                }
            ]
        }
    ]
}
deleteHistoricalTransactions
This method deletes older transactions from the state database.
@Validator(yup.date())
    public async deleteHistoricalTransactions(time_to_expiration: Date) {
        await this.Ctx.Auth.checkAuthorization('TRANSACTION.deleteTransactions', 'TOKEN');
        return await this.Ctx.Transaction.deleteTransactions(time_to_expiration);
    }
Parameters:
  • time_to_expiration Date – A time stamp that indicates when to delete transactions. Transaction assets that are older than the specified time will be deleted.
Return Value Example:
"payload": {
    "msg": "Successfuly deleted transaction older than date: Thu Aug 19 2021 11:19:36 GMT+0000 (Coordinated Universal Time).",
    "transactions": [
        "otransaction~ec3366dd48b4ce2838f820f2f138648e6e55a07226713e59b411ff31b0d21058"
    ]
}

Methods for Token Behavior Management - Mintable Behavior

issueTokens
This method mints tokens, which are then owned by the caller of the method. The caller must have an account and the minter role. The number of tokens that can be minted is limited by the max_mint_quantity property of mintable behavior in the specification file. If the max_mint_quantity property is not specified, an unlimited number of tokens can be minted. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. This method can be called only by the AccountOwner of the account with the minter role. 
@Validator(yup.string(), yup.number().positive())
public async issueTokens(token_id: string, quantity: number) {
    const token_asset = await this.getTokenObject(token_id);
    return await this.Ctx.Token.mint(quantity, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • quantity – The number of tokens to mint.
Returns:
  • On success, a message with account details.
Return Value Example:
{
    "msg": "Successfully minted 1000 tokens to Account Id: \
oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: user1)  ",
}
getTotalMintedTokens
This method returns the total number of minted tokens for a specified token. This method can be called only by a Token Admin or any Org Admin of the chaincode. 
@Validator(yup.string())
 public async getTotalMintedTokens(token_id: string) {
     const token_asset = await this.getTokenObject(token_id);
     await this.Ctx.Auth.checkAuthorization('TOKEN.getTotalMintedTokens', 'TOKEN');
     const totalMintedTokens = await this.Ctx.Token.getTotalMintedTokens(token_asset);
     return {
         msg: `Total minted token for Token Id: ${token_id} is ${totalMintedTokens} tokens.`,
         quantity: totalMintedTokens
     };
 }
Parameters:
  • token_id: string – The ID of the token.
Returns:
  • On success, a JSON string indicating the total number of tokens.
Return Value Example:
{"msg":"Total minted token for Token Id: digiCurr101 is 100 tokens.","quantity":100}
getNetTokens
This method returns the total net number of tokens available in the system for a specified token. The net token total is the amount of tokens remaining after tokens are burned. In equation form: net tokens = total minted tokens - total burned tokens. If no tokens are burned, then the number of net tokens is equal to the total minted tokens. This method can be called only by a Token Admin or any Org Admin of the chaincode. 
@Validator(yup.string())
public async getNetTokens(token_id: string) {
	const token_asset = await this.getTokenObject(token_id);
	await this.Ctx.Auth.checkAuthorization('TOKEN.getNetTokens', 'TOKEN');
	const netTokens = await this.Ctx.Token.getNetTokens(token_asset);
	return {
		msg: `Net supply of token for Token Id: ${token_id} is ${netTokens} tokens.`,
		quantity: netTokens
	};
}
Parameters:
  • token_id: string – The ID of the token.
Returns:
  • On success, a JSON string indicating the net number of tokens.
Return Value Example:
{"msg":"Net supply of token for Token Id: digiCurr101 is 0 tokens.","quantity":0}

Methods for Token Behavior Management - Transferable Behavior

transferTokens
This method transfers tokens from the caller to a specified account. The caller of the method must have an account. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. This method can be called only by the AccountOwner of the account. 
@Validator(yup.string(), yup.string(), yup.string(), yup.number().positive())
public async transferTokens(token_id: string, to_org_id: string, to_user_id: string, quantity: number) {
   const token_asset = await this.getTokenObject(token_id);
   const to_account_id = await this.Ctx.Account.generateAccountId(token_id, to_org_id, to_user_id);
   return await this.Ctx.Token.transfer(to_account_id, quantity, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • to_org_id: string – The membership service provider (MSP) ID of the receiver (payee) in the current organization.
  • to_user_id: string – The user name or email ID of the receiver.
  • quantity: number – The number of tokens to transfer.
Returns:
  • On success, a message with details for both payer and payee accounts.
Return Value Example:
{
    "msg": "Successfully transferred 400 tokens from account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: user1) to account id: oaccount~digicur~682bb71de419602af74e3f226345ef308445ca51010737900c112435f676152df (Org-Id: Org1MSP, User-Id: user2) ",
}
bulkTransferTokens
This method is used to perform bulk transfer of tokens from the caller account to the accounts that are specified in the flow object. The quantities must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file.The caller of this method must have an account already created. This method can be called only by the AccountOwner of the account. 
@Validator(yup.string(), yup.array().of(yup.object()))
public async bulkTransferTokens(token_id: string, flow: object[]) {
     const token_asset = await this.getTokenObject(token_id);
     return await this.Ctx.Token.bulkTransfer(flow, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • flow : object[] – An array of JSON objects that specify receivers and quantities.
    [{
	"to_org_id": "Org1MSP",
	"to_user_id": "user1",
	"quantity": 10
}, {
	"to_org_id": "Org1MSP",
	"to_user_id": "user2",
	"quantity": 10
}]
    • to_orgId: string – The membership service provider (MSP) ID of the receiver in the current organization.
    • userId: string – The user name or email ID of the receiver.
    • quantity: number – The number of tokens to transfer.
Returns:
  • A message indicating success.
Return Value Example:
{
    "msg": "Successfully transferred 20 tokens from Account Id           'oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df' (Org-Id: Org1MSP, User-Id: admin).",
    "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
    "sub_transactions": [
        {
            "to_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
            "amount": 10
        },
        {
            "to_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
            "amount": 10
        }
    ]
}

Methods for Token Behavior Management - Holdable Behavior

holdTokens
This method creates a hold on behalf of the owner of the tokens with the to_account_id account. A notary account is specified, which is responsible to either complete or release the hold. When the hold is created, the specified token balance from the payer is put on hold. A held balance cannot be transferred until the hold is either completed or released. The caller of this method must have an account already created. This method can be called only by the AccountOwner of the account. 
@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.string(), yup.string(), yup.number().positive(), yup.date())
public async holdTokens(
    token_id: string,
    operation_id: string,
    to_org_id: string,
    to_user_id: string,
    notary_org_id: string,
    notary_user_id: string,
    quantity: number,
    time_to_expiration: Date
) {
    const token_asset = await this.getTokenObject(token_id);
    const to_account_id = await this.Ctx.Account.generateAccountId(token_id, to_org_id, to_user_id);
    const notary_account_id = await this.Ctx.Account.generateAccountId(token_id, notary_org_id, notary_user_id);
    return await this.Ctx.Token.hold(operation_id, to_account_id, notary_account_id, quantity, time_to_expiration, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
  • to_org_id: string – The membership service provider (MSP) ID of the receiver in the current organization.
  • to_user_id: string – The user name or email ID of the receiver.
  • notary_org_id: string – The membership service provider (MSP) ID of the notary in the current organization.
  • notary_user_id: string – The user name or email ID of the notary.
  • quantity: number – The number of tokens to put on hold.
  • time_to_expiration – The time when the hold expires. Specify 0 for a permanent hold. Otherwise use the RFC-3339 format. For example, 2021-06-02T12:46:06Z.
Returns:
  • On success, a message with the caller's account and hold details.
Return Value Example:
{
  "msg":"AccountId oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP , User-Id: admin) is   successfully holding 10 tokens"
}
executeHoldTokens
This method completes a hold on a token. A quantity of tokens previously held by a token owner is transferred to a receiver. If the quantity value is less than the actual hold value, then the remaining amount is available again to the original owner of the tokens. This method can be called only by the AccountOwner ID with the notary role for the specified operation ID. The hold can only be completed by the notary. 
@Validator(yup.string(), yup.string(), yup.number().positive())
public async executeHoldTokens(token_id: string, operation_id: string, quantity: number) {
    const token_asset = await this.getTokenObject(token_id);
    return await this.Ctx.Token.executeHold(operation_id, quantity, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
  • quantity: number – The number of on-hold tokens to transfer.
Returns:
  • On success, a message with the caller's account ID and the quantity of the transaction.
Return Value Example:
{
 "msg":"Account Id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: admin) is successfully executed '10' tokens from Operation Id 'opr_121'."
}
releaseHoldTokens
This method releases a hold on tokens. The transfer is not completed and all held tokens are available again to the original owner. This method can be called by the AccountOwner ID with the notary role within the specified time limit or by the payer, payee, or notary after the specified time limit. 
@Validator(yup.string(), yup.string())
public async releaseHoldTokens(token_id: string, operation_id: string) {
    const token_asset = await this.getTokenObject(token_id);
    return await this.Ctx.Token.releaseHold(operation_id, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
Returns:
  • On success, a message indicating that the hold was released.
Return Value Example:
{
 "msg":"Successfully released '10' tokens from Operation Id 'opr_121' to Account Id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: user1)."
}
getOnHoldIds
This method returns a list of all of the holding IDs for a specified account. This method can be called by a Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. 
  @Validator(yup.string(), yup.string(), yup.string())
  public async getOnHoldIds(token_id: string, org_id: string, user_id: string) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getOnHoldIds", "TOKEN", { account_id });
    return await this.Ctx.Account.getOnHoldIds(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON list of holding IDs.
Return Value Example:
{"msg":"Holding Ids are: ohold~digicur~digiCurr101~opr_121","holding_ids":["ohold~digicur~digiCurr101~opr_121"]}
getOnHoldDetailsWithOperationId
This method returns the on-hold transaction details for a specified operation ID and token. This method can be invoked by anyone.
@Validator(yup.string(), yup.string())
public async getOnHoldDetailsWithOperationId(token_id: string, operation_id: string) {
    return await this.Ctx.Hold.getOnHoldDetailsWithOperationId(token_id, operation_id);
}
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
Returns:
  • On success, a JSON hold object that includes the following properties:
  • holding_id – The holding ID of the transaction.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
  • from_account_id – The account ID of the current owner of the on-hold tokens.
  • to_account_id – The account ID of the receiver.
  • notary_account_id – The account ID of the notary.
  • token_id: string – The ID of the saved token.
  • quantity – The amount of tokens that are on hold for the holding ID.
  • time_to_expiration – The duration until the hold expires.
Return Value Example:
{
    "assetType": "ohold",
    "holding_id": "ohold~digicur~digiCurr101~opr_121",
    "operation_id": "opr_121",
    "token_name": "digicur",
    "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
    "to_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "notary_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
    "token_id": "digiCurr101",
    "quantity": 10,
    "time_to_expiration": "2022-08-01T18:30:00.000Z"
}
getOnHoldBalanceWithOperationId
This method returns the on-hold balance for a specified operation ID and token. This method can be invoked by anyone.
@Validator(yup.string(), yup.string())
public async getOnHoldBalanceWithOperationId(token_id: string, operation_id: string) {
    return await this.Ctx.Hold.getOnHoldBalanceWithOperationId(token_id, operation_id);
}
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
Returns:
  • On success, a JSON string indicating the holding balance.
Return Value Example:
{
	"msg": "Current Holding Balance of Operation 'opr_121' for token 'digiCurr101' is: 10",
	"holding_balance": 10
}

Methods for Token Behavior Management - Burnable Behavior

burnTokens
This method deactivates, or burns, tokens from the transaction caller's account. The caller of this method must have an account and the burner role. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. This method can be called by the AccountOwner of the account with the burner role. 
@Validator(yup.string(), yup.number().positive())
public async burnTokens(token_id: string, quantity: number) {
    const token_asset = await this.getTokenObject(token_id);
    return await this.Ctx.Token.burn(quantity, token_asset);
}
Parameters:
  • token_id: string – The ID of the token.
  • quantity – The number of tokens to burn.
Returns:
  • On success, a success message with the quantity of tokens burned and the account ID.
Return Value Example:
{
    "msg": "Successfully burned 10 tokens from account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: admin)"
}

Custom Methods

You can use the token SDK methods to write custom methods for your business application.

To avoid double-spending, do not combine multiple async functions that operate on the same key-value pairs in the state database. Instead, use the bulkTransferTokens method to make multiple transfers in one method.

The following example shows how to use token SDK methods in custom methods. When the buyTicket method is called, it transfers 20 tokens from the caller's account to the seller's account, and returns the transaction message of the transfer. 

@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.string())
public async buyTicket(token_id: string, seller_org_id: string, seller_user_id: string) {
	const token = await this.getTokenObject(token_id);

	/**
	* The following method this.Ctx.Account.generateAccountId(token_id, seller_org_id, seller_user_id) generates account id of the seller.
	*/
	const seller_account_id = await this.Ctx.Account.generateAccountId(token_id, seller_org_id, seller_user_id);

	/**
	* The following method this.Ctx.Token.transfer(seller_account_id, 20, token) transfers the quantity 20 from caller's
	* account & to seller's account.
	*/
	const transaction = await this.Ctx.Token.transfer(seller_account_id, 20, token);

	return transaction;
}

If you use more than one token SDK method in a custom method, do not use methods that will affect the same key-value pairs in the state database. The following example shows the incorrect way to make multiple transfers:

@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.string())
public async sendTokens(token_id: string, user1_org_id: string, user1_user_id: string, user2_org_id: string, user2_user_id: string) {
    const token = await this.getTokenObject(token_id);
    const user1_account_id = await Account.generateAccountId(token_id, user1_org_id, user1_user_id);
    const user2_account_id = await Account.generateAccountId(token_id, user2_org_id, user2_user_id);
    await token.transfer(user1_account_id, 20);
    await token.transfer(user2_account_id, 30);
}

Instead, use the bulkTransferTokens method to transfer to multiple accounts from the caller's account, as shown in the following code snippet. 

bulkTransferTokens(token_id: string, flow: object[])

Note:

If you use more than one token SDK method in a custom method that might affect the same key-value pairs in the state database, enable the MVCC optimization for token chaincodes. For more information, see MVCC Optimization.

Token SDK Methods

Methods for Access Control Management

The token SDK provides an access control function. Some methods can be called only by a Token Admin, Org Admin, or AccountOwner of the token. You can use this feature to ensure that operations are carried out only by the intended users. Any unauthorized access results in an error. To use the access control function, import the Authorization class from the ../lib/auth module.
import { Authorization } from '../lib/auth';
addAdmin
This method adds a user as a Token Admin of the token chaincode. 
Ctx.Admin.addAdmin(org_id: string, user_id: string)
Parameters:
  • user_id – The user name or email ID of the user.
  • org_id – The membership service provider (MSP) ID of the user in the current network organization.
Returns:
  • On success, a promise message with a JSON object that lists details for the user added as a Token Admin of the token chaincode. On error, a rejection with an error message.
Return Value Example:
{
    "msg": "Successfully added Admin (Org_Id: Org1MSP, User_Id: user1)"
}
removeAdmin
This method removes a user as a Token Admin of the token chaincode. 
Ctx.Admin.removeAdmin(org_id: string, user_id: string)
Parameters:
  • user_id – The user name or email ID of the user.
  • org_id – The membership service provider (MSP) ID of the user in the current network organization.
Returns:
  • On success, a promise message with a JSON object that lists details for the user who is no longer a Token Admin of the token chaincode. On error, a rejection with an error message.
Return Value Example:
{
    "msg": "Successfully removed Admin (Org_Id: Org1MSP, User_Id: user1)"
}
getAllAdmins
This method returns a list of all users who are a Token Admin of the token chaincode. 
Ctx.Admin.getAllAdmins()
Parameters:
  • none
Returns:
  • On success, a promise with a JSON object that lists details for all users who are a Token Admin of the token chaincode. On error, a rejection with an error message.
Return Value Example:
{
    "admins": [
        {
            "orgId": "Org1MSP",
            "userId": "admin"
        }
    ]
}
checkAuthorization
Use this method to add an access control check to an operation. Certain token methods can be run only by a Token Admin or AccountOwner of the token or by the MultipleAccountOwner for users with multiple accounts. The access control mapping is described in the ../lib/constant.ts file. You can modify access control by editing the ../lib/constant.ts file. To use your own access control or to disable access control, remove the access control code from the automatically generated controller methods and custom methods.
export const TOKENACCESS = {
  ADMIN: {
    isUserTokenAdmin: ["Admin", "OrgAdmin"],
    addTokenAdmin: ["Admin"],
    removeTokenAdmin: ["Admin"],
    getAllAdmins: ["Admin", "OrgAdmin"],
    addOrgAdmin: ["Admin", "OrgAdminForOrgId"],
    removeOrgAdmin: ["Admin", "OrgAdminForOrgId"],
    getOrgAdmins: ["Admin", "OrgAdmin"],
  },
  TOKEN: {
    save: ["Admin"],
    getAllTokens: ["Admin", "OrgAdmin"],
    get: ["Admin", "OrgAdmin"],
    update: ["Admin"],
    getDecimals: ["Admin", "OrgAdmin"],
    getTokensByName: ["Admin", "OrgAdmin"],
    addRoleMember: ["Admin", "OrgAdminRoleCheck"],
    removeRoleMember: ["Admin", "OrgAdminRoleCheck"],
    isInRole: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    getTotalMintedTokens: ["Admin", "OrgAdmin"],
    getNetTokens: ["Admin", "OrgAdmin"],
    getTokenHistory: ["Admin", "OrgAdmin"],
  },
  ROLE: {
    getAccountsByRole: ["Admin"],
    getOrgAccountsByRole: ["Admin", "OrgAdminForOrgId"],
    getUsersByRole: ["Admin"],
    getOrgUsersByRole: ["Admin", "OrgAdminForOrgId"],
  },
  TRANSACTION: {
    deleteTransactions: ["Admin"],
  },ACCOUNT: {
    createAccount: ["Admin", "OrgAdminForOrgId"],
    associateToken: ["Admin", "OrgAdminForAccountId"],
    getAllAccounts: ["Admin"],
    getAllOrgAccounts: ["Admin", "OrgAdminForOrgId"],
    getAccountsByUser: ["Admin", "OrgAdminForOrgId", "MultipleAccountOwner"],
    getAccount: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    history: ["Admin", "AccountOwner"],
    getAccountTransactionHistory: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    getAccountTransactionHistoryWithFilters: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    getSubTransactionsById: ["Admin", "TransactionInvoker"],
    getSubTransactionsByIdWithFilters: ["Admin", "TransactionInvoker"],
    getAccountBalance: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    getAccountOnHoldBalance: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    getOnHoldIds: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    getConversionHistory: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
  },
  ACCOUNT_STATUS: {
    get: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    history: ["Admin", "OrgAdminForAccountId", "AccountOwner"],
    activateAccount: ["Admin", "OrgAdminForOrgId"],
    suspendAccount: ["Admin", "OrgAdminForOrgId"],
    deleteAccount: ["Admin", "OrgAdminForOrgId"],
  },
  TOKEN_CONVERSION: {
    initializeExchangePoolUser: ["Admin"],
    addConversionRate: ["Admin"],
    updateConversionRate: ["Admin"],
    getConversionRate: ["Admin", "OrgAdmin", "AnyAccountOwner"],
    getConversionRateHistory: ["Admin", "OrgAdmin", "AnyAccountOwner"],
    tokenConversion: ["Admin", "AnyAccountOwner"],
    getExchangePoolUser: ["Admin"],
  },
}
await this.Ctx.Auth.checkAuthorization(<parameters>);
Parameters:
  • classFuncName: string – The map value between the class and methods as described in the ../lib/constant.ts file.
  • ...args – A variable argument where args[0] takes the constant 'TOKEN' and args[1] takes the account_id to add an access control check for an AccountOwner. To add an access control check for a MultipleAccountOwner, args[1] takes the org_id and args[2] takes the user_id.
Returns:
  • On success, a promise. On error, a rejection with an error message.
isUserTokenAdmin
This method returns the Boolean value true if the caller of the function is a Token Admin. Otherwise the method returns false. 
Ctx.Auth.isUserTokenAdmin()
Parameters:
  • user_id – The user name or email ID of the user.
  • org_id – The membership service provider (MSP) ID of the user in the current network organization.
Returns:
  • A Boolean response and an error message if an error is encountered.
addOrgAdmin
This method adds a user as an Org Admin of the organization. 
Ctx.Admin.addOrgAdmin(org_id, user_id)
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the user who was added as an Org Admin of the organization.
Return Value Example:
{
    "msg": "Successfully added Org Admin (Org_Id: Org1MSP, User_Id: orgAdmin)"
}
removeOrgAdmin
This method removes a user as an Org Admin of the organization. 
Ctx.Admin.removeOrgAdmin(org_id, user_id)
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the user who was removed as an Org Admin of the organization.
Return Value Example:
{
  "msg": "Successfully removed Org Admin (Org_Id Org1MSP User_Id orgAdmin)"
}
getOrgAdmins
This method returns a list of all users who are an Org Admin of an organization. 
Ctx.Admin.getAllOrgAdmins()
Parameters:
  • none
Returns:
  • On success, an array in JSON format that contains orgId and userId objects.
Return Value Example:
{
    "admins": [
        {
            "org_id": "Org1MSP",
            "user_id": "orgadmin"
        },
        {
            "org_id": "Org1MSP",
            "user_id": "orgadmin1"
        },
        {
            "org_id": "Org1MSP",
            "user_id": "orgadmin2"
        }
    ]
}

Methods for Token Configuration Management

getTokenDecimals
This method returns the number of decimal places available for a fractional token. If the divisible behavior is not specified, then the default value is 0. 
Ctx.Token.getTokenDecimals(token_id: string)
Parameters:
  • token_id: string – The ID of the token.
Returns:
  • On success, the decimal places of the token, in the number data type. On error, it returns with an error message.
Return Value Example:
1
getAllTokens
This method returns all the token assets saved in the state database. This method uses Berkeley DB SQL rich queries and can only be called when connected to the remote Oracle Blockchain Platform network.
Ctx.Token.getAllTokens()
Parameters:
  • none
Returns:
  • On success, it returns a promise with all the token assets. On error, it returns an error message.
Return Value Example:
{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "98e0a0a115803d25b843d630e6b23c435a192a03eb0a301fc9375f05da49a8b2",
        "payload": [
            {
                "key": "token1",
                "valueJson": {
                    "assetType": "otoken",
                    "token_id": "token1",
                    "token_name": "vtok",
                    "token_type": "fungible",
                    "behaviours": [
                        "divisible",
                        "mintable",
                        "transferable",
                        "burnable",
                        "holdable",
                        "roles"
                    ],
                    "roles": {
                        "burner_role_name": "burner",
                        "notary_role_name": "notary"
                    },
                    "mintable": {
                        "max_mint_quantity": 0
                    },
                    "divisible": {
                        "decimal": 1
                    }
                }
            }
        ],
        "encode": "JSON"
    }
}
getTokensByName
This method returns all the token assets with the specified name. This method uses Berkeley DB SQL rich queries and can only be called when connected to the remote Oracle Blockchain Platform network.
Ctx.Token.getTokensByName(token_name: string)
Parameters:
  • token_name: string – The name of the token, which corresponds to the Token_name property of the model. The value is the class name of the token.
Returns:
  • It returns an array of all of the token assets of the specified name, in JSON format.
Return Value Example:
{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "98e0a0a115803d25b843d630e6b23c435a192a03eb0a301fc9375f05da49a8b2",
        "payload": [
            {
                "key": "token1",
                "valueJson": {
                    "assetType": "otoken",
                    "token_id": "token1",
                    "token_name": "vtok",
                    "token_type": "fungible",
                    "behaviours": [
                        "divisible",
                        "mintable",
                        "transferable",
                        "burnable",
                        "holdable",
                        "roles"
                    ],
                    "roles": {
                        "burner_role_name": "burner",
                        "notary_role_name": "notary"
                    },
                    "mintable": {
                        "max_mint_quantity": 0
                    },
                    "divisible": {
                        "decimal": 1
                    }
                }
            }
        ],
        "encode": "JSON"
    }
}
get
This method returns a token object if it is present in the state database.
Ctx.Token.get(token_id: string)
Parameters:
  • token_id: string – The ID of the token to return.
Returns:
  • On success, a promise with the JSON representation of the token. On error, a rejection with an error message.
Return Value Example:
{
    "assetType": "otoken",
    "token_id": "token1",
    "token_name": "account",
    "token_desc": "Token 1",
    "token_type": "fungible",
    "behaviors": [
        "divisible",
        "mintable",
        "transferable",
        "burnable",
        "holdable",
        "roles"
    ],
    "roles": {
        "minter_role_name": "minter",
        "burner_role_name": "burner",
        "notary_role_name": "notary"
    },
    "mintable": {
        "max_mint_quantity": 20000
    },
    "divisible": {
        "decimal": 1
    },
    "token_to_currency_ratio": 2,
    "currency_representation": "EURO"
}
isTokenType
This method indicates whether a token asset exists with the specified ID.
Ctx.Token.isTokenType(token_id: string)
Parameters:
  • token_id: string – The ID of the token to check.
Returns:
  • On success, a promise with true if a token asset exists with the specified ID. On error, a rejection with an error message.
Return Value Example:
true
save
This method creates a token and saves its properties in the state database.
Ctx.Token.save(token: <Instance of Token Class>,extraMetadata?:any)
Parameters:
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise message with token details. On error, a rejection with an error message.
Return Value Example:
{
   "assetType":"otoken",
   "token_id":"digiCurr101",
   "token_name":"digicur",
   "token_type":"fungible",
   "behaviors":[
      "divisible",
      "mintable",
      "transferable",
      "burnable",
      "roles"
   ],
   "roles":{
      "minter_role_name":"minter"
   },
   "mintable":{
      "max_mint_quantity":1000
   },
   "divisible":{
      "decimal":2
   },
   "currency_name":"DOLLAR",
   "token_to_currency_ratio":1
}
update
This method updates token properties. After a token asset is created, you update only the token_desc value and its custom properties. 
Ctx.Token.update(token: <Instance of Token Class>)
Parameters:
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise message with token details. On error, a rejection with an error message.
Return Value Example:
{
   "assetType":"otoken",
   "token_id":"digiCurr101",
   "token_name":"digicur",
   "token_desc":"Digital Currency equiv of dollar",
   "token_type":"fungible",
   "behaviors":[
      "divisible",
      "mintable",
      "transferable",
      "burnable",
      "roles"
   ],
   "roles":{
      "minter_role_name":"minter"
   },
   "mintable":{
      "max_mint_quantity":1000
   },
   "divisible":{
      "decimal":2
   },
   "currency_name":"DOLLAR",
   "token_to_currency_ratio":1
}
getByRange
This method calls the fabric getStateByRange method internally. Even though any asset with the given ID is returned from the ledger, this method casts the asset into the caller Asset type. 
<Token ClassCtx.Token.getByRange(start_token_id: string, end_token_id: string, token_class_reference?: <Instance of Token Class> )
Parameters:
  • startId: string – The starting key of the range. This key is included in the range.
  • endId: string – The end key of the range. This key is excluded from the range.
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise with an array of <Token Class>. On error, a rejection with an error message.
Example:
@validator(yup.string(), yup.string())
public async getDigiCurrGetByRange(start_token_id: string, end_token_id: string) {
   return await this.Ctx.Token.getByRange(start_token_id, end_token_id, DigiCurr);
}
Return Value Example:
[
    {
        "assetType": "otoken",
        "token_id": "token1",
        "token_name": "digicur",
        "token_desc": "Token 1",
        "token_type": "fungible",
        "behaviors": [
            "divisible",
            "mintable",
            "transferable",
            "burnable",
            "holdable",
            "roles"
        ],
        "roles": {
            "minter_role_name": "minter",
            "burner_role_name": "burner",
            "notary_role_name": "notary"
        },
        "mintable": {
            "max_mint_quantity": 20000
        },
        "divisible": {
            "decimal": 0
        },
        "token_to_currency_ratio": 1.5,
        "currency_representation": "USD"
    },
    {
        "assetType": "otoken",
        "token_id": "token2",
        "token_name": "digicur",
        "token_desc": "Token2",
        "token_type": "fungible",
        "behaviors": [
            "divisible",
            "mintable",
            "transferable",
            "burnable",
            "holdable",
            "roles"
        ],
        "roles": {
            "minter_role_name": "minter",
            "burner_role_name": "burner",
            "notary_role_name": "notary"
        },
        "mintable": {
            "max_mint_quantity": 20000
        },
        "divisible": {
            "decimal": 0
        },
        "token_to_currency_ratio": 1,
        "currency_representation": "EURO"
    }
]
history
This method returns history for the specified token.
Ctx.Token.history(tokenId)
Parameters:
  • tokenId: string – The ID of the token.
Returns:
  • On success, a promise with an array of the account history details for the specified token. On error, a rejection with an error message.
Return Value Example:
[
    {
        "trxId": "0d75f09446a60088afb948c6aca046e261fddcd43df416076201cdc5565f1a35",
        "timeStamp": "2023-09-01T16:48:41.000Z",
        "value": {
            "assetType": "otoken",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "token_desc": "updatedDesc",
            "token_standard": "ttf+",
            "token_type": "fungible",
            "token_unit": "fractional",
            "behaviors": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "roles": {
                "minter_role_name": "minter"
            },
            "mintable": {
                "max_mint_quantity": 1000
            },
            "divisible": {
                "decimal": 2
            }
        }
    },
    {
        "trxId": "3666344878b043b65d5b821cc79c042ba52aec467618800df5cf14eac69f72fa",
        "timeStamp": "2023-08-31T20:24:55.000Z",
        "value": {
            "assetType": "otoken",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "token_standard": "ttf+",
            "token_type": "fungible",
            "token_unit": "fractional",
            "behaviors": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "roles": {
                "minter_role_name": "minter"
            },
            "mintable": {
                "max_mint_quantity": 1000
            },
            "divisible": {
                "decimal": 2
            }
        }
    }
]

Methods for Account Management

getCallerAccountId
This method returns the account ID of the caller.
Ctx.Account.getCallerAccountId(token_id: string)
Parameters:
  • tokenId: string – The ID of the token.
Returns:
  • On success, a promise with the caller account ID. On error, a rejection with an error message.
Return Value Example:
oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f
generateAccountId
This method returns an account ID, which is an alphanumeric set of characters, prefixed with oaccount~<token asset name>~ and followed by a hash of the user name or email ID (user_id) of the instance owner or the user who is logged in to the instance, the membership service provider ID (org_id) of the user in the current network organization and the unique token ID (token_id). 
Ctx.Account.generateAccountId(token_id: string, org_id: string, user_id: string)
Parameters:
  • tokenId: string – The ID of the token.
  • orgId: string – The membership service provider (MSP) ID of the user in the current organization.
  • userId: string – The user name or email ID of the user.
Returns:
  • On success, a promise with the generated account ID. On error, a rejection with an error message.
Return Value Example:
oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f
createAccount
This method creates an account for a specified user and token. Every user who has tokens at any point must have an account. Accounts track a user's balance, on-hold balance, and transaction history. An account ID is an alphanumeric set of characters, prefixed with oaccount~<token asset name>~ and followed by a hash of the user name or email ID (user_id) of the instance owner or the user who is logged in to the instance, the membership service provider ID (org_id) of the user in the current network organization. This method can be called only by the Token Admin of the chaincode or by an Org Admin of the specified organization. 
this.Ctx.Account.createAccount(org_id: string, user_id: string, token_type: string)
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
  • token_type: string – The type of the token, which must be fungible.
Returns:
  • On success, the new account object in JSON format.
Return Value Example:
{
  "assetType": "oaccount",
  "bapAccountVersion": 0,
  "account_id": "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
  "user_id": "admin",
  "org_id": "Org1MSP",
  "token_type": "fungible",
  "token_id": "",
  "token_name": "",
  "balance": 0,
  "onhold_balance": 0
}
associateTokenToAccount
This method associates a fungible token with an account. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the relevant organization. 
async associateTokenToAccount(account_id: string, token_id: string)
Parameters:
  • account_id: string – The ID of the account.
  • token_id: string – The ID of the token.
Returns:
  • On success, a JSON object of the updated account.
Return Value Example:
{
    "assetType": "oaccount",
    "bapAccountVersion": 0,
    "account_id": "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
    "user_id": "admin",
    "org_id": "Org1MSP",
    "token_type": "fungible",
    "token_id": "fungible",
    "token_name": "fiatmoneytok",
    "balance": 0,
    "onhold_balance": 0
}
getAccountWithStatus
This method returns account details for a specified account, including account status.
Ctx.Account.getAccountWithStatus(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise with the account details. On error, a rejection with an error message.
Return Value Example:
{
  "bapAccountVersion": 0,
  "assetType": "oaccount",
  "status": "active",
  "account_id": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
  "user_id": "idcqa",
  "org_id": "appdev",
  "token_type": "fungible",
  "token_id": "t1",
  "token_name": "obptok",
  "balance": 0,
  "onhold_balance": 0
}
getAccount
This method returns account details for a specified account.
Ctx.Account.getAccount(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise with the account details. On error, a rejection with an error message.
Return Value Example:
{
   "assetType":"oaccount",
   "bapAccountVersion": 0,
   "account_id":"oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
   "user_id":"user1",
   "org_id":"Org1MSP",
   "token_id":"digiCurr101",
   "token_name":"digicur",
   "balance":0,
   "onhold_balance":0
}
history
This method returns an array of the account history details for a specified account.
Ctx.Account.history(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise with the array of account history details. On error, a rejection with an error message. The return value is the same as the "getAccountHistory" method.
Return Value Example:
[
    {
      "trxId":"2gsdh17fff222467e5667be042e33ce18e804b3e065cca15de306f837e416d7c3e",
      "timeStamp":1629718288,
      "value":{
         "assetType":"oaccount",
         "account_id":"oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
         "user_id":"user1",
         "org_id":"Org1MSP",
         "token_id":"digiCurr101",
         "token_name":"digicur",
         "balance":100,
         "onhold_balance":0,
         "bapAccountVersion": 1
   },
   {
      "trxId":"9fd07fff222467e5667be042e33ce18e804b3e065cca15de306f837e416d7c3e",
      "timeStamp":1629718288,
      "value":{
         "assetType":"oaccount",
         "account_id":"oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
         "user_id":"user1",
         "org_id":"Org1MSP",
         "token_id":"digiCurr101",
         "token_name":"digicur",
         "balance":0,
         "onhold_balance":0,
         "bapAccountVersion": 0
      }
   }
]
getAccountOnHoldBalance
This method returns the on-hold balance for a specified account.
Ctx.Account.getAccountOnHoldBalance(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise with a JSON object that shows the on-hold balance for the specified account. On error, a rejection with an error message.
Return Value Example:
{
   "holding_balance":0,
   "msg":"Total Holding Balance of Account Id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id: Org1MSP, user_id: user1) is 0"
}
getAllAccounts
This method returns a list of all accounts. This method uses Berkeley DB SQL rich queries and can only be called when connected to the remote Oracle Blockchain Platform network.
Ctx.Account.getAllAccounts()
Parameters:
  • none
Returns:
  • On success, a promise with a JSON object that lists all accounts. On error, a rejection with an error message.
Return Value Example:
[
           {
               "key": "oaccount~digicur~2e2ef3375ae347cbd7b4d3d7be5cece803f9c36a184aaf2b8d332c5d2dcead52",
               "valueJson": {
                   "assetType": "oaccount",
                   "account_id": "oaccount~digicur~2e2ef3375ae347cbd7b4d3d7be5cece803f9c36a184aaf2b8d332c5d2dcead52",
                   "user_id": "admin",
                   "org_id": "Org1MSP",
                   "token_id": "digiCurr101",
                   "token_name": "digicur",
                   "bapAccountVersion": 0,
                   "balance": 0,
                   "onhold_balance": 0
               }
           },
           {
               "key": "oaccount~digicur~30080c7e5ba94035af57fbbccbbb495e92515e4b2b3dbcd476eb1c0343e4da65",
               "valueJson": {
                   "assetType": "oaccount",
                   "account_id": "oaccount~digicur~30080c7e5ba94035af57fbbccbbb495e92515e4b2b3dbcd476eb1c0343e4da65",
                   "bapAccountVersion": 0,
                   "user_id": "user1",
                   "org_id": "Org1MSP",
                   "token_id": "digiCurr101",
                   "token_name": "digicur",
                   "balance": 0,
                   "onhold_balance": 0
               }
           },
           {
               "key": "oaccount~digicur~cbde438258cb01a82f71a9a9f8029243c40c6d836a505432120529c2b3c2ff0c",
               "valueJson": {
                   "assetType": "oaccount",
                   "account_id": "oaccount~digicur~cbde438258cb01a82f71a9a9f8029243c40c6d836a505432120529c2b3c2ff0c",
                   "bapAccountVersion": 0,
                   "user_id": "user2",
                   "org_id": "Org1MSP",
                   "token_id": "digiCurr101",
                   "token_name": "digicur",
                   "balance": 0,
                   "onhold_balance": 0
               }
           },
           {
               "key": "oaccount~digicur~ecbc3aefcc562d3049c988717940195b30297e95012b7824bbd33a57ca50a626",
               "valueJson": {
                   "assetType": "oaccount",
                   "account_id": "oaccount~digicur~ecbc3aefcc562d3049c988717940195b30297e95012b7824bbd33a57ca50a626",
                   "bapAccountVersion": 0,
                   "user_id": "user3",
                   "org_id": "Org1MSP",
                   "token_id": "digiCurr101",
                   "token_name": "digicur",
                   "balance": 500,
                   "onhold_balance": 0
               }
           }
       ]
getUserByAccountId
This method returns the user details for a specified account.
Ctx.Account.getUserByAccountId(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise with a JSON object that includes three properties:
    • user_id – The user name or email ID of the user.
    • org_id – The membership service provider (MSP) ID of the user in the current network organization.
    • token_id – The ID of the token.
  • On error, a rejection with an error message.
Return Value Example:
{
   "token_id": "digiCurr101",
   "user_id": "user1",
   "org_id": "Org1MSP"
}
getAccountBalance
This method returns the account balance for a specified account.
Ctx.Account.getAccountBalance(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise message with a JSON object that includes two properties:
    • msg – A message showing the current balance.
    • user_balance – The numeric value of the current balance.
  • On error, a rejection with an error message.
Return Value Example:
{
    "msg": "Current Balance is: 200",
    "user_balance": 200
}
getAllOrgAccounts
This method returns a list of all token accounts that belong to a specified organization.
Ctx.Account.getAllOrgAccounts(org_id: string)
Parameters:
  • org_id: string – The membership service provider (MSP) ID of the organization.
Returns:
  • On success, a list of all accounts for the specified organization.
Return Value Example:
[
    {
        "key": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
        "valueJson": {
            "bapAccountVersion": 0,
            "assetType": "oaccount",
            "account_id": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
            "user_id": "idcqa",
            "org_id": "appdev",
            "token_type": "fungible",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "balance": 0,
            "onhold_balance": 0
        }
    },
    {
        "key": "oaccount~620fcf5deb5fd5a65c0b5b10fda129de0f629ccd232c5891c130e24a574df50a",
        "valueJson": {
            "bapAccountVersion": 0,
            "assetType": "oaccount",
            "account_id": "oaccount~620fcf5deb5fd5a65c0b5b10fda129de0f629ccd232c5891c130e24a574df50a",
            "user_id": "example_minter",
            "org_id": "appdev",
            "token_type": "fungible",
            "token_id": "token",
            "token_name": "fiatmoneytok",
            "balance": 0,
            "onhold_balance": 0
        }
    }
]

Methods for Role Management

addRoleMember
This method adds a role to a specified user and token.
Ctx.Token.addRoleMember(role: string, account_id: string, token: <Instance of Token Class>)
Parameters:
  • role: string – The name of the role to add to the specified user. The mintable and burnable behaviors correspond to the minter_role_name and burner_role_name properties of the specification file. Similarly, the notary role corresponds to the notary_role_name property of the specification file.
  • account_id: number – The account ID to add the role to.
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
    "msg":"Successfully added role minter to oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id :          Org1MSP, user_id : user1)"
}
removeRoleMember
This method removes a role from a specified user and token.
Ctx.Token.removeRoleMember(role: string, account_id: string, token: <Instance of Token Class>)
Parameters:
  • role: string – The name of the role to remove from to the specified user. The mintable and burnable behaviors correspond to the minter_role_name and burner_role_name properties of the specification file. Similarly, the notary role corresponds to the notary_role_name property of the specification file.
  • account_id: number – The account ID to remove the role from.
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
  "msg":"successfully removed member_id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1) from role minter"
}
getAccountsByRole
This method returns a list of all accounts for a specified role and token.
Ctx.Role.getAccountsByRole(token_id: string, role: string)
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to search for.
Returns:
  • On success, a promise with a JSON object that lists all accounts for the specified role and token. On error, a rejection with an error message.
Return Value Example:
{
    "accounts": [
        "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
        "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f"
    ]
}
getAccountsByUser
This method returns a list of all account IDs for a specified user.
async getAccountsByUser(org_id: string, user_id: string)
Parameters:
  • org_id string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id string – The user name or email ID of the user.
Returns:
  • On success, a JSON array of account IDs.
Return Value Example:
{"accounts":["oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f"]}
getUsersByRole
This method returns a list of all users for a specified role and token.
Ctx.Role.getUsersByRole(token_id: string, role: string)
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to search for.
Returns:
  • On success, a promise with a JSON object that lists all users for the specified role and token. On error, a rejection with an error message.
Return Value Example:
{
   "users":[
      {
         "token_id":"digiCurr101",
         "user_id":"user1",
         "org_id":"Org1MSP"
      }
   ]
}
isInRole
This method indicates whether a user and token has a specified role.
Ctx.Token.isInRole(role: string, account_id: string, token: <Instance of Token Class>)
Parameters:
  • role: string – The name of the role to check.
  • account_id: number – The account ID to check.
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise with true if the user has the role, and false if the user does not have the role. On error, a rejection with an error message.
Return Value Example:
{"result":"true"}
roleCheck
This method checks if the provided account ID is a member of any role.
Ctx.Token.roleCheck(account_id: string, token: <Instance of Token Class>)
Parameters:
  • account_id: string – The account ID to check.
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • If the account ID is part of any role, it returns true. Otherwise, it returns false.
Return Value Example:
{ result: true }
getOrgUsersByRole
This method returns information about all users that have a specified role in a specified organization. 
Ctx.Role.getOrgUsersByRole(token_id: string, role: string, org_id: string)
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to check for.
  • org_id: string – The membership service provider (MSP) ID of the organization.
Returns:
  • On success, a list of all users with the specified role in the specified organization.
Return Value Example:
{
    "users": [
        {
            "token_id": "token",
            "user_id": "admin",
            "org_id": "Org1MSP"
        },
        {
            "token_id": "token",
            "user_id": "orgAdmin",
            "org_id": "Org1MSP"
        }
    ]
}
getOrgAccountsByRole
This method returns information about all accounts that have a specified role in a specified organization.
Ctx.Role.getOrgAccountsByRole(token_id: string, role: string, org_id: string)
Parameters:
  • token_id: string – The ID of the token.
  • role: string – The name of the role to check for.
  • org_id: string – The membership service provider (MSP) ID of the organization.
Returns:
  • On success, a list of all accounts with the specified role in the specified organization.
Return Value Example:
{
    "accounts": [
        "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
        "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850"
    ]
}

Methods for Transaction History Management

getTransactionById
This method returns the history of a Transaction asset. 
async getTransactionById(transaction_id: string)
Parameters:
  • transaction_id: string – The ID of the transaction asset.
Returns:
  • On success, the transaction asset history.
Return Value Example:
{
    "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
    "history": [
        {
            "trxId": "68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
            "timeStamp": 1629180264,
            "value": {
                "assetType": "otransaction",
                "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
                "token_id": "digiCurr101",
                "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
                "to_account_id": "",
                "transaction_type": "BULKTRANSFER",
                "amount": 20,
                "timestamp": "2021-08-17T06:04:24.000Z",
                "number_of_sub_transactions": 2,
                "holding_id": ""
            }
        }
    ],
    "sub_transactions": [
        {
            "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c4ca4238a0b923820dcc509a6f75849b",
            "history": [
                {
                    "trxId": "68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
                    "timeStamp": 1629180264,
                    "value": {
                        "assetType": "otransaction",
                        "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c4ca4238a0b923820dcc509a6f75849b",
                        "token_id": "digiCurr101",
                        "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
                        "to_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                        "transaction_type": "TRANSFER",
                        "amount": 10,
                        "timestamp": "2021-08-17T06:04:24.000Z",
                        "number_of_sub_transactions": 0,
                        "holding_id": ""
                    }
                }
            ]
        },
        {
            "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c81e728d9d4c2f636f067f89cc14862c",
            "history": [
                {
                    "trxId": "68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
                    "timeStamp": 1629180264,
                    "value": {
                        "assetType": "otransaction",
                        "transaction_id": "otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c81e728d9d4c2f636f067f89cc14862c",
                        "token_id": "digiCurr101",
                        "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
                        "to_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
                        "transaction_type": "TRANSFER",
                        "amount": 10,
                        "timestamp": "2021-08-17T06:04:24.000Z",
                        "number_of_sub_transactions": 0,
                        "holding_id": ""
                    }
                }
            ]
        }
    ]
}
deleteHistoricalTransactions
This method returns an array of the transaction history details for a specified account.
async deleteHistoricalTransactions(time_to_expiration: Date)
Parameters:
  • time_to_expiration: Date – A time stamp that indicates when to delete transactions. Transaction assets that are older than the specified time will be deleted..
Returns:
  • The return value is the same as the "getAccountTransactionHistory" method.
  • On success, a promise with the array of account transaction objects:
    • transaction_id – The ID of the transaction.
    • transacted_account – The account with which the transaction took place.
    • transaction_type – The type of transaction.
    • transacted_amount – The amount of the transaction.
    • timestamp – The time of the transaction.
    • balance – The account balance at the time of the transaction.
    • onhold_balance – The on-hold balance at the time of the transaction.
    • sub_transactions – For bulk transfers only, a list of transactions that are part of a bulk transfer.
    • holding_id – A unique identifier returned by the holdTokens method.
    • token_id – The ID of the token.
  • On error, a rejection with an error message.
Return Value Example:
"payload": {
            "msg": "Successfuly deleted transaction older than date: Thu Aug 19 2021 11:19:36 GMT+0000 (Coordinated Universal Time).",
            "transactions": [
                "otransaction~ec3366dd48b4ce2838f820f2f138648e6e55a07226713e59b411ff31b0d21058"
            ]
        }
getAccountTransactionHistory
This method returns an array of the transaction history details for a specified account.
Ctx.Account.getAccountTransactionHistory(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • The return value is the same as the "getAccountTransactionHistory" method.
  • On success, a promise with the array of account transaction objects:
    • transaction_id – The ID of the transaction.
    • transacted_account – The account with which the transaction took place.
    • transaction_type – The type of transaction.
    • transacted_amount – The amount of the transaction.
    • timestamp – The time of the transaction.
    • balance – The account balance at the time of the transaction.
    • onhold_balance – The on-hold balance at the time of the transaction.
    • sub_transactions – For bulk transfers only, a list of transactions that are part of a bulk transfer.
    • holding_id – A unique identifier returned by the holdTokens method.
    • token_id – The ID of the token.
  • On error, a rejection with an error message.
Return Value Example:
[
   {
      "transaction_id":"otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775",
      "transacted_amount":20,
      "timestamp":"2021-08-17T06:04:24.000Z",
      "balance":60,
      "onhold_balance":0,
      "token_id":"digiCurr101",
      "transaction_type":"BULKTRANSFER",
      "sub_transactions":[
         {
            "transacted_account":"oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
            "transaction_type":"CREDIT",
            "transaction_id":"otransaction~68f46c90d0d8d6b93d827e6b9e0152b4845e6e42a61965e63a9bbf1d8e0fc775~c4ca4238a0b923820dcc509a6f75849b",
            "transacted_amount":10
         }
      ]
   },
   {
      "transaction_id":"otransaction~757864d5369bd0539d044caeb3bb4898db310fd7aa740f45a9938771903d43da",
      "transacted_amount":50,
      "timestamp":"2021-08-17T06:02:44.000Z",
      "balance":50,
      "onhold_balance":0,
      "token_id":"digiCurr101",
      "transacted_account":"oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
      "transaction_type":"CREDIT"
   }
]
getAccountTransactionHistoryWithFilters
This method returns an array of the transaction history details for a specified account. This method can only be called when connected to the remote Oracle Blockchain Platform network.
await this.Ctx.Account.getAccountTransactionHistoryWithFilters(account_id: string, filters?: Filters)
Parameters:
  • account_id: string – The ID of the account.
  • filters: string – An optional parameter. If empty, all records are returned. The PageSize property determines the number of records to return. If PageSize is 0, the default page size is 20. The Bookmark property determines the starting index of the records to return. For more information, see the Hyperledger Fabric documentation. The StartTime and EndTime properties must be specified in RFC-3339 format.
Example:

ochain invoke getAccountTransactionHistoryWithFilters 'token1' 'appbuilder12' 'user_minter' '{"PageSize":10,"Bookmark":"1","StartTime":"2022-01-25T17:41:42Z","EndTime":"2022-01-25T17:59:10Z"}'

[
    {
        "transaction_id": "otransaction~672897b5a4fa78b421c000e4d6d4f71f3d46529bfbb5b4be10bf5471dc35ce89",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:46:04.000Z",
        "token_id": "token1",
        "transacted_account": "oaccount~16c38d804413ebabf416360d374f76c973d4e71c74adfde73cc40c7c274883b8",
        "transaction_type": "DEBIT",
        "balance": 90,
        "onhold_balance": 0
    },
    {
        "transaction_id": "otransaction~467bb67a33aaffca4487f33dcd46c9844efdb5421a2e7b6aa2d53152eb2c6d85",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:45:47.000Z",
        "token_id": "token1",
        "transacted_account": "oaccount~fbf95683b21bbc91a22205819ac1e2e9c90355d536821ed3fe22b7d23915c248",
        "transaction_type": "DEBIT",
        "balance": 95,
        "onhold_balance": 0
    },
    {
        "transaction_id": "otransaction~c6d56ce54a9bbe24597d1d10448e39316dc6f16328bf3c5b0c8ef10e1dfeb397",
        "transacted_amount": 100,
        "timestamp": "2022-04-20T15:44:26.000Z",
        "token_id": "token1",
        "transacted_account": "oaccount~deb5fb0906c40506f6c2d00c573b774e01a53dd91499e651d92ac4778b6add6a",
        "transaction_type": "MINT",
        "balance": 100,
        "onhold_balance": 0
    }
]
getSubTransactionHistory
This method returns an array of the transaction history details for a specified transaction.
await this.Ctx.Account.getSubTransactionHistory(transaction_id)
Parameters:
  • transaction_id: string – The ID of the bulk transfer transaction.
Example:

ochain invoke GetAccountSubTransactionHistory 'otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b'

[
    {
        "transacted_account": "oaccount~16c38d804413ebabf416360d374f76c973d4e71c74adfde73cc40c7c274883b8",
        "transaction_type": "DEBIT",
        "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c81e728d9d4c2f636f067f89cc14862c",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:52:21.000Z",
        "token_id": "token1",
        "balance": 80,
        "onhold_balance": 0
    },
    {
        "transacted_account": "oaccount~fbf95683b21bbc91a22205819ac1e2e9c90355d536821ed3fe22b7d23915c248",
        "transaction_type": "DEBIT",
        "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c4ca4238a0b923820dcc509a6f75849b",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:52:21.000Z",
        "token_id": "token1",
        "balance": 85,
        "onhold_balance": 0
    }
]
getSubTransactionHistoryWithFilters
This method returns an array of the subtransaction history details for a specified transaction.
await this.Ctx.Account.getSubTransactionHistoryWithFilters(transaction_id: string, filters?: SubTransactionFilters)
Parameters:
  • transaction_id: string – The ID of the bulk transfer transaction.
  • filters: string – An optional parameter. If empty, all records are returned. The PageSize property determines the number of records to return. If PageSize is 0, the default page size is 20. The Bookmark property determines the starting index of the records to return. For more information, see the Hyperledger Fabric documentation. The StartTime and EndTime properties must be specified in RFC-3339 format.
Example:

ochain invoke GetAccountSubTransactionHistoryWithFilters 'otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b' '{"PageSize":10,"Bookmark":"1"}'

[
    {
        "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c81e728d9d4c2f636f067f89cc14862c",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:52:21.000Z",
        "token_id": "token1",
        "transacted_account": "oaccount~16c38d804413ebabf416360d374f76c973d4e71c74adfde73cc40c7c274883b8",
        "transaction_type": "DEBIT",
        "balance": 80,
        "onhold_balance": 0
    },
    {
        "transaction_id": "otransaction~6e0f8fe4a6430322170b9c619b04b6c9f1c8d257923f611b866bdf69d7fe6cb8~c4ca4238a0b923820dcc509a6f75849b",
        "transacted_amount": 5,
        "timestamp": "2022-04-20T15:52:21.000Z",
        "token_id": "token1",
        "transacted_account": "oaccount~fbf95683b21bbc91a22205819ac1e2e9c90355d536821ed3fe22b7d23915c248",
        "transaction_type": "DEBIT",
        "balance": 85,
        "onhold_balance": 0
    }
]

Token Behavior Management

The token lifecycle management methods are based on the the standards of the Token Taxonomy Framework. To use the token lifecycle methods, import the Token class from the ../lib/token module. 
import { Token } from '../lib/token';

Methods for Token Behavior Management - Mintable Behavior

mint
This method mints a quantity of tokens, which are then owned by the caller of the method. The caller must have an account and the minter role. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. 
Ctx.Token.mint(quantity: number, token: <Instance of Token Class>)
Parameters:
  • quantity: number – The total number of tokens to mint.
  • token: <Instance of Token Class> – The token asset to mint.
Returns:
  • On success, a promise with a success message and toAccount details. On error, a rejection with an error message.
Return Value Example:
{
  "msg":"Successfully minted 1000 tokens to Account Id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: admin)"
}
getTotalMintedTokens
This method returns the total number of tokens minted.
Ctx.Token.getTotalMintedTokens(token: <Instance of Token Class>)
Parameters:
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, the quantity of minted tokens, in the number data type. On error, it returns with an error message.
Return Value Example:
4000
getNetTokens
This method returns the net quantity of tokens that are available in the system. The net tokens are the amount of tokens remaining after tokens are burned. In equation form: net tokens = total minted tokens - total burned tokens. If no tokens are burned, then the number of net tokens is equal to the total minted tokens.
Ctx.Token.getNetTokens(token: <Instance of Token Class>)
Parameters:
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, the quantity of net tokens, in the number data type. On error, it returns with an error message.
Return Value Example:
2000
getMaxMintQuantity
This method returns the maximum mintable quantity for a token. If the max_mint_quantity behavior is not specified, then the default value is 0, which allows any number of tokens to be minted. 
Ctx.Token.getMaxMintQuantity(token: <Instance of Token Class>)
Parameters:
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, the maximum mintable quantity of the token, in the number data type. On error, it returns with an error message.
Return Value Example:
20000

Methods for Token Behavior Management - Transferable Behavior

transfer
This method transfers tokens from the transaction caller to the to_account_id account. The caller of this method must have an account and the quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. 
Ctx.Token.transfer(to_account_id: string, quantity: number, token: <Instance of Token Class>)
Parameters:
  • to_account_id: string – The account ID to receive the tokens.
  • quantity: number – The total number of tokens to transfer.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
 "msg":"Successfully transferred 50 tokens from account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: admin) to account id: oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (Org-Id: Org1MSP, User-Id: user1)"
}
bulkTransfer
This method is used to perform bulk transfer of tokens from the caller account to the accounts that are specified in the flow object. The caller of this method must have an account already created. 
Ctx.Token.bulkTransfer(flow: object[], token: <Instance of Token Class>)
Parameters:
  • flow: object[] – An array of JSON objects specifying the receiver details and quantity. The transfer quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. For example: 
    [{
	"to_org_id": "Org1MSP",
	"to_user_id": "user1",
	"quantity": 10
}, {
	"to_org_id": "Org1MSP",
	"to_user_id": "user2",
	"quantity": 10
}]
  • token: <Instance of Token Class> – The token asset to operate on.
Returns:
  • On success, a promise with a success message and account information. On error, a rejection with an error message.
Return Value Example:
{
    "from_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "msg": "Successfully transferred 2 tokens from Account Id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (Org-Id: Org1MSP, User-Id: user1)",
    "sub_transactions": [
        {
            "amount": 1,
            "to_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e"
        },
        {
            "amount": 1,
            "to_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df"
        }
    ]
}

Methods for Token Behavior Management - Holdable Behavior

hold
This method creates a hold on behalf of the owner of the tokens with the to_account_id account. A notary account is specified, which is responsible to either complete or release the hold. When the hold is created, the specified token balance from the payer is put on hold. A held balance cannot be transferred until the hold is either completed or released. The caller of this method must have an account already created. 
Ctx.Token.hold(operation_id: string, to_account_id: string, notary_account_id: string, quantity: number, time_to_expiration: Date, token: <Instance of Token Class>)
Parameters:
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
  • to_account_id: string – The ID of the account to receive the tokens.
  • notary__account_id: string – The ID of the notary account.
  • quantity: number – The total number of tokens to put on hold.
  • time_to_expiration: Date – The duration until the hold expires. Specify 0 for a permanent hold. Otherwise use the RFC-3339 format. For example, 2021-06-02T12.
  • token: <Instance of Token Class> – The token asset to hold.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
 "msg": "account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (org_id : Org1MSP, user_id : user1) is successfully holding 10 tokens",
}
executeHold
This method completes a hold on tokens, transferring the specified quantity of tokens previously on hold to the receiver. If the quantity value is less than the actual hold value, then the remaining amount is available again to the original owner of the tokens. This method can be called only by the AccountOwner ID with the notary role for the specified operation ID. The hold can only be completed by the notary. 
Ctx.Token.executeHold(operation_id: string, quantity: number, token: <Instance of Token Class>)
Parameters:
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
  • quantity: number – The total number of tokens to complete a hold on.
  • token: <Instance of Token Class> – The token asset to complete a hold on.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
 "msg": "user with accountId: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (org_id : Org1MSP, user_id : user1) has successfully executed 5  tokens(digiCurr101) from the hold with Operation Id opr_121",
}
releaseHold
This method releases a hold on tokens. The transfer is not completed and all held tokens are available again to the original owner. This method can be called by the AccountOwner ID with the notary role within the specified time limit or by the payer, payee, or notary after the specified time limit. 
Ctx.Token.releaseHold(operation_id: string, token: <Instance of Token Class>)
Parameters:
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
  • token: <Instance of Token Class> – The token asset to release a hold on.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
  "msg": "Successfully released 5 tokens from Operation Id opr_121 to Account Id: oaccount~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (org_id : Org1MSP, user_id : user1)",
}
getOnHoldIds
This method returns a list of all of the holding IDs for a specified account.
Ctx.Account.getOnHoldIds(account_id: string)
Parameters:
  • account_id: string – The ID of the account.
Returns:
  • On success, a promise with a JSON object that lists all holding IDs for the specified account. On error, a rejection with an error message.
Return Value Example:
{
   "msg":"Holding Ids are: ohold~digicur~digiCurr101~opr_121",
   "holding_ids":[
      "ohold~digicur~digiCurr101~opr_121"
   ]
}
getOnHoldDetailsWithOperationId
This method returns the on-hold transaction details for a specified operation ID and token.
Ctx.Hold.getOnHoldDetailsWithOperationId(token_id: string, operation_id: string)
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
Returns:
  • On success, a hold object that includes the following properties:
    • holding_id – The holding ID of the transaction.
    • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
    • from_account_id – The account ID of the current owner of the on-hold tokens.
    • to_account_id – The account ID of the receiver.
    • notary_account_id – The account ID of the notary.
    • token_id: string – The ID of the saved token.
    • quantity – The amount of tokens that are on hold for the holding ID.
    • time_to_expiration – The duration until the hold expires.
  • On error, a rejection with an error message.
Return Value Example:
{
    "assetType": "ohold",
    "holding_id": "ohold~digicur~digiCurr101~opr_121",
    "operation_id": "opr_121",
    "token_name": "digicur",
    "from_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
    "to_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "notary_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
    "token_id": "digiCurr101",
    "quantity": 10,
    "time_to_expiration": "2022-08-01T18:30:00.000Z"
}
getOnHoldBalanceWithOperationId
This method returns the on-hold balance for a specified operation ID and token. This method can be invoked by anyone.
Ctx.Hold.getOnHoldBalanceWithOperationId(token_id: string, operation_id: string)
Parameters:
  • token_id: string – The ID of the token.
  • operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
Returns:
  • On success, a promise object with the on-hold balance for the specified operation ID and token. On error, a rejection with an error message
Return Value Example:
{
    "msg": "Current Holding Balance of Operation 'op1' for token 'token1' is: 10",
    "holding_balance": 10
}

Methods for Token Behavior Management - Burnable Behavior

burn
This method deactivates, or burns, tokens from the transaction caller's account. The caller of this method must have an account and the burner role. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. 
Ctx.Token.burn(quantity: number, token: <Instance of Token Class>)
Parameters:
  • quantity: number – The total number of tokens to burn.
  • token: <Instance of Token Class> – The token asset to burn.
Returns:
  • On success, a promise with a success message. On error, a rejection with an error message.
Return Value Example:
{
 "msg":"Successfully burned 10 tokens from account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: admin)"
}