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

Base
Digital Assets

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"
        }
    ]
}

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, Token Auditor, any Org Admin, or any Org Auditor 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 Token Auditor 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, Token Auditor, any Org Admin, or any Org Auditor.

  @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"
        }
    ]
}

addTokenAuditor

This method adds a user as a

Token
                                    Auditor

of the chaincode. This method can be called only by a Token Admin of the chaincode.

public async addTokenAuditor(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 message that includes details of the user who was added as a Token Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "cd81f6c4c9e7c18ece357dbf5c139ef66ef2d6566be3b14de5f6d0a3fd4bb2f0",
        "payload": {
            "msg": "Successfully added Token Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20009",
        "blockNumber": 196
    }
}

removeTokenAuditor

This method removes a user as a

Token
                                    Auditor

of the chaincode. This method can be called only by a Token Admin of the chaincode.

public async removeTokenAuditor(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 message that includes details of the user who was removed as a Token Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "a886a6040fbc76374a3c78c89ab0ffc9f7b8391cc5239b169bf3b878cf40c67b",
        "payload": {
            "msg": "Successfully removed Token Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20010",
        "blockNumber": 219
    }
}

getTokenAuditors

This method returns all Token Auditors of the chaincode. This method can be called only by a

Token
                                    Admin

or Token Auditor of the chaincode.

public async getTokenAuditors()

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "payload": {
            "auditors": [
                {
                    "org_id": "CB",
                    "user_id": "auditor_user_cb"
                }
            ]
        },
        "encode": "JSON"
    }
}

addOrgAuditor

This method adds a user as a

Org
                                    Auditor

of the chaincode. This method can be called only by a Token Admin or Org Admin of the chaincode.

public async addOrgAuditor(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 message that includes details of the user who was added as a Org Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "44bbad35a1478cb714e32f7cfd551897868a203520aab9cea5771d3aadc1cf03",
        "payload": {
            "msg": "Successfully added Org Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20009",
        "blockNumber": 198
    }
}

removeOrgAuditor

This method removes a user as a

Org
                                    Auditor

of the chaincode. This method can be called only by a Token Admin or Org Admin of the chaincode.

public async removeOrgAuditor(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 message that includes details of the user who was removed as a Org Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "c3bc720461004a53b37c68d4bb264858b88d980bc093a0a3ebb62a32974fb306",
        "payload": {
            "msg": "Successfully removed Org Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20010",
        "blockNumber": 221
    }
}

getOrgAuditors

This method returns all Org Auditors of the chaincode. This method can be called only by a

Token
                                    Admin

, Token Auditor,

Org
                                    Admin

, or Org Auditor.

public async getOrgAuditors()

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "payload": {
            "auditors": [
                {
                    "org_id": "FI1",
                    "user_id": "auditor_user_fi1"
                },
                {
                    "org_id": "FI2",
                    "user_id": "auditor_user_fi2"
                }
            ]
        },
        "encode": "JSON"
    }
}

Methods for Token Configuration Management

Base
Digital Assets

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, macOS 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 called 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 can vary, and are described in the token specification file. Do not include parameters that are marked as read-only in the specification file.
You specify the asset parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: Use the GUI to pass individual parameters that correspond to the token class fields.

CLI / Postman: Pass a serialized JSON string that includes the token specification fields, as shown in the following example.

"{\"token_id\":\"USD\",\"token_desc\":\"token_desc value\",\"Currency_Name\":\"Currency_Name value\"}"

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 can vary, and are described in the token specification file. Do not include parameters that are marked as read-only in the specification file.
You specify the asset parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: Use the GUI to pass individual parameters that correspond to the token class fields.

CLI / Postman: Pass a serialized JSON string that includes the token specification fields, as shown in the following example.

"{\"token_id\":\"USD\",\"token_desc\":\"token_desc value\",\"Currency_Name\":\"Currency_Name value\"}"

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.

init

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, macOS 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 called 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 can vary, and are described in the token specification file. Do not include parameters that are marked as read-only in the specification file.
You specify the asset parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: Use the GUI to pass individual parameters that correspond to the token class fields.

CLI / Postman: Pass a serialized JSON string that includes the token specification fields, as shown in the following example.

"{\"token_id\":\"USD\",\"token_desc\":\"token_desc value\",\"Currency_Name\":\"Currency_Name value\"}"

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

@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 can vary, and are described in the token specification file. Do not include parameters that are marked as read-only in the specification file.
You specify the asset parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: Use the GUI to pass individual parameters that correspond to the token class fields.

CLI / Postman: Pass a serialized JSON string that includes the token specification fields, as shown in the following example.

"{\"token_id\":\"USD\",\"token_desc\":\"token_desc value\",\"Currency_Name\":\"Currency_Name value\"}"

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

@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, Token Auditor, Org Admin, or Org Auditor.

@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. This method can be called only by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

  @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, Token Auditor, Org Admin, or Org Auditor. 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, Token Auditor, Org Admin, or Org Auditor. 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

Base
Digital Assets

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
        }
    }
]

createAccount

@Validator(yup.string(), yup.string(), yup.string(), yup.object().nullable())

public async createAccount(org_id: string, user_id: string, token_type: string, daily_limits: DailyLimits) {
await this.Ctx.Auth.checkAuthorization("ACCOUNT.createAccount", "TOKEN", { org_id });
return await this.Ctx.Account.createAccount(org_id, user_id, token_type, daily_limits);
}

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.
daily_limits: JSON – An object specifying the maximum amount of tokens that can be used in transactions daily (max_daily_amount) and the maximum number of transactions that can be completed daily (max_daily_transactions).
You specify the daily_limits parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "max_daily_amount": 1000, "max_daily_transactions": 100 }

CLI / Postman: "{\"max_daily_amount\":1000,\"max_daily_transactions\":100}"

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,
  "onhold_burn_balance": 0,
  "max_daily_amount": 1000,
  "max_daily_transactions": 100
}

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 or Token Auditor, an Org Admin or Org Auditor 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 or Token Auditor, an Org Admin or Org Auditor 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 or Token Auditor. 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 a Token Admin or Token Auditor, or by an Org Admin or Org Auditor of the specified organization.

@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 or Token Auditor, an Org Admin or Org Auditor 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 or Token Auditor, or by an Org Admin or Org Auditor 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

Base
Digital Assets

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"
        }
    ]
}

addRole

  @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

  @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 or Token Auditor.

@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 or Token Auditor, by the Org Admin or Org Auditor 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 or Token Auditor.

@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 or Token Auditor, the AccountOwner of the account, or an Org Admin or Org Auditor 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, Token Auditor, Org Admin or Org Auditor.

   @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 or Token Auditor, by an Org Admin or Org Auditor 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

Base
Digital Assets

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

  @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
  }
]

getSubTransactionsById

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"
    ]
}

getAccountTransactionHistoryWithFiltersFromRichHistDB

You can synchronize data to the rich history database and then fetch the data using chaincode API calls. This method fetches transaction history from the rich history database. Before you can use this method, you must run Oracle Autonomous Database with Oracle REST Data Services (ORDS) and OAuth enabled, as described in Oracle Database View Definitions for Wholesale CBDC in Oracle Blockchain Platform Digital Assets Edition.

@GetMethod()
@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.string(), yup.object().nullable())
public async getAccountTransactionHistoryWithFiltersFromRichHistDB(token_id: string, org_id: string, user_id: string, custom_endpoint: string, bearer_token: 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.getAccountTrxHistoryWithFiltersFromRichHistDB(account_id, org_id, user_id.toLowerCase(), custom_endpoint, bearer_token, filters);
}

Parameters:

token_id: string – The ID of the token to mint.
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.
custom_endpoint – The RESTful service endpoint of the rich history database.
bearer_token – The access authorization token for the RESTful service endpoint.
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.

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 or Token Auditor, an Org Admin or Org Auditor of the specified organization, or the AccountOwner of the account.

@GetMethod()
@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.

Return Value Example:

[
            {
                "transaction_id": "otransaction~64c5a4830949eae1424600f3d4a438c6f603a7c3ea31a68e374b899803999e22",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:37:28.000Z",
                "balance": 550,
                "onhold_balance": 10,
                "token_id": "USD",
                "category": "category value",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "REJECT_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            },
            {
                "transaction_id": "otransaction~a4537ef34a955b023b7c205b9abf06a6c79e4fdd761fb24f41b8eb34126b66c0",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:36:32.000Z",
                "balance": 550,
                "onhold_balance": 10,
                "token_id": "USD",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "APPROVE_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            },
            {
                "transaction_id": "otransaction~6237a759422bd9fb112742e8cd7e6450df5a74a32236d9b1005571afed8904a4",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:36:18.000Z",
                "balance": 540,
                "onhold_balance": 10,
                "token_id": "USD",
                "category": "category value",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "REQUEST_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            },
            {
                "transaction_id": "otransaction~06b35071415d74aa1a7c18449149c937d886cae76a832c44cf8d98e84586e76e",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:35:46.000Z",
                "balance": 540,
                "onhold_balance": 10,
                "token_id": "USD",
                "category": "category value",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "REQUEST_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            }
 ]

getAccountTransactionHistoryWithFilters

This method returns a filtered array of account transaction history details for a specified user and token. This method can be called only by the Token Admin or Token Auditor, an Org Admin or Org Auditor of the specified organization, or the AccountOwner of the account.

@GetMethod()
@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.

Return Value Example:

[
            {
                "transaction_id": "otransaction~64c5a4830949eae1424600f3d4a438c6f603a7c3ea31a68e374b899803999e22",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:37:28.000Z",
                "balance": 550,
                "onhold_balance": 10,
                "token_id": "USD",
                "category": "category value",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "REJECT_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            },
            {
                "transaction_id": "otransaction~a4537ef34a955b023b7c205b9abf06a6c79e4fdd761fb24f41b8eb34126b66c0",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:36:32.000Z",
                "balance": 550,
                "onhold_balance": 10,
                "token_id": "USD",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "APPROVE_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            },
            {
                "transaction_id": "otransaction~6237a759422bd9fb112742e8cd7e6450df5a74a32236d9b1005571afed8904a4",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:36:18.000Z",
                "balance": 540,
                "onhold_balance": 10,
                "token_id": "USD",
                "category": "category value",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "REQUEST_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            },
            {
                "transaction_id": "otransaction~06b35071415d74aa1a7c18449149c937d886cae76a832c44cf8d98e84586e76e",
                "transacted_amount": 10,
                "timestamp": "2024-12-11T13:35:46.000Z",
                "balance": 540,
                "onhold_balance": 10,
                "token_id": "USD",
                "category": "category value",
                "description": "description value",
                "transacted_account": "oaccount~9d9806fa92aa0c4fdb34eaffac6e830181b5d47e64fbce752195e83024125ca0",
                "transaction_type": "REQUEST_MINT",
                "transacted_org_id": "CB",
                "transacted_user_id'": "creator_user_cb"
            }
 ]

getSubTransactionsById

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, Token Auditor, or the AccountOwner who called the transaction.

  @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. This method can be called only by a Token Admin or Token Auditor, by an Org Admin or Org Auditor of the specified organization, or by a transaction participant (sender, recipient, or notary).

@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

Base
Digital Assets

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}

requestMint

This method can be called by a minter to send a request to the minter notary to create a specified amount of tokens.

@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.number().positive(), yup.date(), yup.object().nullable())
public async requestMint( token_id: string, operation_id: string, notary_org_id: string, notary_user_id: string, quantity: number, time_to_expiration: Date, info_details?: InfoDetails) {

const token_asset = await this.getTokenObject(token_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, null, notary_account_id, quantity, time_to_expiration, token_asset, HoldOperationType.MINT, info_details);

}

Parameters:

token_id: string – The ID of the token to mint.
operation_id: string – The unique operation ID that represents the mint request.
notary_org_id: string – The membership service provider (MSP) ID of the minter notary who will process the request.
notary_user_id: string – The user name or email ID of the minter notary who will process the request.
quantity: number – The amount of tokens to mint.
time_to_expiration – The time after which the minting request expires and is no longer valid.
info_details: JSON – An object specifying the category (category) and description (description) of the request.
You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "category": "category value", "description": "description value" }

CLI / Postman: "{\"category\":\"category value\",\"description\":\"description value\"}"

Return Value Example:

{
msg:
"AccountId oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin) has successfully submitted request to mint 100 tokens",
}

approveMint

This method can be called by a minter notary to approve a minting request.

@Validator(yup.string(), yup.string())
public async approveMint(token_id: string, operation_id: string) {
const token_asset = await this.getTokenObject(token_id);
return await this.Ctx.Token.executeHold(operation_id, token_asset);
}

Parameters:

token_id: string – The ID of the token to mint.
operation_id: string – The unique operation ID that represents the mint request.

Return Value Example:

{
msg:
"Successfully minted 100 tokens to Account Id: oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin)"
}

rejectMint

This method can be called by a minter notary to reject a minting request.

@Validator(yup.string(), yup.string())
public async rejectMint(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 to mint.
operation_id: string – The unique operation ID that represents the mint request.

Return Value Example:

{
 msg: "Successfully rejected mint request with Operation Id 'operation1' to mint 100 tokens of token id token"
}

issueTokens

This method mints tokens, which are then owned by the caller of the method.

@Validator(yup.string(), yup.number().positive(), yup.object().nullable())
public async issueTokens(token_id: string, quantity: number, info_details?: InfoDetails) {
const token_asset = await this.getTokenObject(token_id);
return await this.Ctx.Token.mint(quantity, token_asset, info_details);
}

Parameters:

token_id: string – The ID of the token.
quantity – The number of tokens to mint.
info_details: JSON – An object specifying the category (category) and description (description) of the request.
You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "category": "category value", "description": "description value" }

CLI / Postman: "{\"category\":\"category value\",\"description\":\"description value\"}"

Return Value Example:

{
msg:
"Successfully minted 100 tokens to Account Id: oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin)"
}

getTotalMintedTokens

This method returns the total number of minted tokens for a specified token. This method can be called only by a Token Admin, Token Auditor, Org Admin or Org Auditor.

@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

@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

Base
Digital Assets

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 transfers tokens in bulk 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_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.
You specify the flow parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.
Visual Studio Code:
```
[
  { "to_org_id": "Org1MSP", "to_user_id": "user1", "quantity": 10 },
  { "to_org_id": "Org1MSP", "to_user_id": "user2", "quantity": 10 }
]
```
CLI / Postman:
```
"[{ \"to_org_id\": \"Org1MSP\", \"to_user_id\": \"user1\", \"quantity\": 10 }, { \"to_org_id\": \"Org1MSP\", \"to_user_id\": \"user2\", \"quantity\": 10 }]"
```

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
        }
    ]
}

transferTokens

This method transfers tokens from the caller to a specified account.

@Validator(yup.string(), yup.string(), yup.string(), yup.number().positive(), yup.object().nullable())
public async transferTokens(token_id: string, to_org_id: string, to_user_id: string, quantity: number, info_details?: InfoDetails) {
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, info_details);
}

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.
info_details: JSON – An object specifying the category (category) and description (description) of the request.
You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "category": "category value", "description": "description value" }

CLI / Postman: "{\"category\":\"category value\",\"description\":\"description value\"}"

Return Value Example:

{
 msg: "Successfully transferred 100 tokens from account id: oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin) to account id: oaccount~7yuijg39b4e1e4136dd86a806020c97a930909325340481b8fdhjklliugbv699 (Org-Id: Org1MSP, User-Id: user)",
}

bulkTransferTokens

@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_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.
You specify the flow parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.
Visual Studio Code:
```
[
  { "to_org_id": "Org1MSP", "to_user_id": "user1", "quantity": 10 },
  { "to_org_id": "Org1MSP", "to_user_id": "user2", "quantity": 10 }
]
```
CLI / Postman:
```
"[{ \"to_org_id\": \"Org1MSP\", \"to_user_id\": \"user1\", \"quantity\": 10 }, { \"to_org_id\": \"Org1MSP\", \"to_user_id\": \"user2\", \"quantity\": 10 }]"
```

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

Base
Digital Assets

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 called 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 called 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
}

holdTokens

This method creates a hold on behalf of the owner of the tokens with the to_account_id account.

@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.string(), yup.string(), yup.number().positive(), yup.date(), yup.object().nullable())
  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, info_details?: InfoDetails) {
    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, HoldOperationType.TRANSFER, info_details);
  }

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.
info_details: JSON – An object specifying the category (category) and description (description) of the request.
You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "category": "category value", "description": "description value" }

CLI / Postman: "{\"category\":\"category value\",\"description\":\"description value\"}"

Return Value Example:

{
msg:
"AccountId oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin) is successfully holding 100 tokens",
}

executeHoldTokens

@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

@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 or Token Auditor of the chaincode, an Org Admin or Org Auditor 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 called by a Token Admin or Token Auditor of the chaincode, or by a transaction participant (sender, recipient, notary).

@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 called by a Token Admin or Token Auditor of the chaincode, or by a transaction participant (sender, recipient, notary).

@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

Base
Digital Assets

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)"
}

requestBurn

This method can be called by a burner to send a request to the burner notary to destroy a specified amount of tokens, which must be less than or equal to their available balance. When a burn request starts, the specified amount is immediately deducted from the available balance and added to the onhold_burn_balance field. If the request is approved, the tokens are burned. If the request is rejected, the tokens are returned from the onhold_burn_balance field to the available balance.

@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.number().positive(), yup.date(), yup.object().nullable())

public async requestBurn( token_id: string, operation_id: string, notary_org_id: string, notary_user_id: string, quantity: number, time_to_expiration: Date, info_details?: InfoDetails ) {

const token_asset = await this.getTokenObject(token_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, null, notary_account_id, quantity, time_to_expiration, token_asset, HoldOperationType.BURN, null, description);
}

Parameters:

token_id: string – The ID of the token to burn.
operation_id: string – The unique operation ID that represents the burn request.
notary_org_id: string – The membership service provider (MSP) ID of the burner notary who will process the request.
notary_user_id: string – The user name or email ID of the burner notary who will process the request.
quantity: number – The amount of tokens to burn.
time_to_expiration – The time after which the burning request expires and is no longer valid.
info_details: JSON – An object specifying the category (category) and description (description) of the request.
You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "category": "category value", "description": "description value" }

CLI / Postman: "{\"category\":\"category value\",\"description\":\"description value\"}"

Return Value Example:

{
msg:
"AccountId oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin) has successfully submitted request to mint 100 tokens",
}

approveBurn

This method can be called by a burner notary to approve a burning request.

@Validator(yup.string(), yup.string())
public async approveBurn(token_id: string, operation_id: string) {
const token_asset = await this.getTokenObject(token_id);
return await this.Ctx.Token.executeHold(operation_id, token_asset);
}

Parameters:

token_id: string – The ID of the token to burn.
operation_id: string – The unique operation ID that represents the burn request.

Return Value Example:

{
msg:
"Successfully burned 100 tokens from account id: oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (Org-Id: Org1MSP, User-Id: admin)"
}

rejectBurn

This method can be called by a burner notary to reject a burning request.

@Validator(yup.string(), yup.string())
public async rejectBurn(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 to burn.
operation_id: string – The unique operation ID that represents the burn request.

Return Value Example:

{
 msg: "Successfully rejected burn request with Operation Id 'operation1' to burn 100 tokens of token id token",
}

getAccountOnHoldBurnBalance

This method returns the on-hold burn balance for a specified user. This method can be called only by the Token Admin, Token Auditor, Org Admin, Org Auditor, or by the account owner.

@GetMethod()
@Validator(yup.string(), yup.string(), yup.string())
public async getAccountOnHoldBurnBalance(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.getAccountOnHoldBurnBalance", "TOKEN", { account_id });
  return await this.Ctx.Account.getAccountOnHoldBurnBalance(account_id);
}

Parameters:

token_id: string – The ID of the token to burn.
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.

Return Value Example:

{
  "msg": "Total On Hold Burning Balance is: 10",
  "onhold_burn_balance": 10
}

burnTokens

This method deactivates, or burns, tokens from the transaction caller's account.

@Validator(yup.string(), yup.number().positive(), yup.object().nullable())

public async burnTokens(token_id: string, quantity: number, info_details?: InfoDetails) {
const token_asset = await this.getTokenObject(token_id);
return await this.Ctx.Token.burn(quantity, token_asset, info_details);
}

Parameters:

token_id: string – The ID of the token.
quantity – The number of tokens to burn.
info_details: JSON – An object specifying the category (category) and description (description) of the request.
You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

Visual Studio Code: { "category": "category value", "description": "description value" }

CLI / Postman: "{\"category\":\"category value\",\"description\":\"description value\"}"

Return Value Example:

{
msg:
"Successfully burned 100 tokens from account id: oaccount~95be539b4e1e4136dd86a806020c97a930909325340481b8fd88d339874fa699 (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';

Base
Digital Assets

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)"
}

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.

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.

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"
        }
    ]
}

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)"
}

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.

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

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.

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"
        }
    ]
}

addTokenAuditor

This method adds a user as a

Token
                                    Auditor

of the chaincode.

this.Ctx.Admin.addTokenAuditor(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 Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "cd81f6c4c9e7c18ece357dbf5c139ef66ef2d6566be3b14de5f6d0a3fd4bb2f0",
        "payload": {
            "msg": "Successfully added Token Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20009",
        "blockNumber": 196
    }
}

removeTokenAuditor

This method removes a user as a

Token
                                    Auditor

of the chaincode.

this.Ctx.Admin.removeTokenAuditor(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 Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "a886a6040fbc76374a3c78c89ab0ffc9f7b8391cc5239b169bf3b878cf40c67b",
        "payload": {
            "msg": "Successfully removed Token Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20010",
        "blockNumber": 219
    }
}

getTokenAuditors

This method returns all Token Auditors of the chaincode.

this.Ctx.Admin.getAllTokenAuditors()

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "payload": {
            "auditors": [
                {
                    "org_id": "CB",
                    "user_id": "auditor_user_cb"
                }
            ]
        },
        "encode": "JSON"
    }
}

addOrgAuditor

This method adds a user as a

Org
                                    Auditor

of the chaincode.

this.Ctx.Admin.addOrgAuditor(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 Org Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "44bbad35a1478cb714e32f7cfd551897868a203520aab9cea5771d3aadc1cf03",
        "payload": {
            "msg": "Successfully added Org Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20009",
        "blockNumber": 198
    }
}

removeOrgAuditor

This method removes a user as a

Org
                                    Auditor

of the chaincode.

this.Ctx.Admin.removeOrgAuditor(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 Org Auditor of the chaincode.

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "txid": "c3bc720461004a53b37c68d4bb264858b88d980bc093a0a3ebb62a32974fb306",
        "payload": {
            "msg": "Successfully removed Org Auditor (Org_Id: CB, User_Id: cb)"
        },
        "encode": "JSON",
        "sourceURL": "cb-oabcs1-bom.blockchain.ocp.example.com:20010",
        "blockNumber": 221
    }
}

getOrgAuditors

This method returns all Org Auditors of the chaincode.

this.Ctx.Admin.getAllOrgAuditors()

Return Value Example:

{
    "returnCode": "Success",
    "error": "",
    "result": {
        "payload": {
            "auditors": [
                {
                    "org_id": "FI1",
                    "user_id": "auditor_user_fi1"
                },
                {
                    "org_id": "FI2",
                    "user_id": "auditor_user_fi2"
                }
            ]
        },
        "encode": "JSON"
    }
}

Methods for Token Configuration Management

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
}

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:

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"
}

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
            }
        }
    }
]

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"
    }
}

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

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"
    }
]

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"}

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"
    ]
}

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"
        }
    ]
}

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 }

Methods for Transaction History Management

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
    }
]

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"
            ]
        }

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:

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:

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:

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 transfers tokens in bulk 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

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

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

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)"
}