Scaffolded Go 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 Go Chaincode Project.

Reference:

• Model
• Controller
  • Automatically Generated Token Methods
  • Custom Methods
• Token SDK Methods

Model

Transparent Persistence Capability, or simplified ORM, is captured in the OchainModel class.

package src
type Digicur struct {
    AssetType               string                 `json:"AssetType" final:"otoken"`
    Token_id                string                 `json:"Token_id" id:"true" mandatory:"true" validate:"regexp=^[A-Za-z0-9][A-Za-z0-9_-]*$,max=16"`
    Token_name              string                 `json:"Token_name" final:"digicur"`
    Token_desc              string                 `json:"Token_desc" validate:"max=256"`
    Token_type              string                 `json:"Token_type" final:"fungible" validate:"regexp=^fungible$"`
    Behavior                []string               `json:"Behavior" final:"[\"divisible\",\"mintable\",\"transferable\",\"burnable\",\"holdable\",\"roles\"]"`
    Roles                   map[string]interface{} `json:"Roles" final:"{\"minter_role_name\":\"minter\",\"burner_role_name\":\"burner\",\"notary_role_name\":\"notary\"}"`
    Mintable                map[string]interface{} `json:"Mintable" final:"{\"Max_mint_quantity\":20000}"`
    Divisible               map[string]interface{} `json:"Divisible" final:"{\"Decimal\":1}"`
    Token_to_currency_ratio int                    `json:"Token_to_currency_ratio" validate:"int"`
    Currency_representation string                 `json:"Currency_representation" validate:"string"`
    Metadata                interface{}            `json:"Metadata,omitempty"`
}

Controller

There is only one main controller.

type Controller struct {
    Ctx trxcontext.TrxContext
}

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

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

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.

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: []map[string]interface{})

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.

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 be public to be invokable. Public method names begin with an upper case character. Method names that begin with a lower case character are private.

• Access Control Management
• Token Configuration Management
• Account Management
• Role Management
• Transaction History Management
• Token Behavior Management
  • Mintable Behavior
  • Transferable Behavior
  • Holdable Behavior
  • Burnable Behavior

Methods for Access Control Management

AddTokenAdmin

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

func (t *Controller) AddTokenAdmin(org_id string, user_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Admin.AddAdmin", "TOKEN")
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Admin.AddTokenAdmin(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 Token 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.

func (t *Controller) RemoveTokenAdmin(org_id string, user_id string) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Admin.RemoveAdmin", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.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":"Successfuly 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.

func (t *Controller) IsTokenAdmin(org_id string, user_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Admin.IsTokenAdmin", "TOKEN", map[string]string{"org_id": org_id, "user_id": user_id})
      if err != nil || !auth {
            return false, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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.

Return Value Example:

{"result":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 Org Admin of the chaincode.

func (t *Controller) GetAllTokenAdmins() (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Admin.GetAllAdmins", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.Admin.GetAllAdmins()
}

Parameters:

• none

Returns:

• On success, a JSON list of admins that includes OrgId and UserId objects.

Return Value Example:

{"admins":[{"OrgId":"Org1MSP","UserId":"admin"},{"OrgId":"Org1MSP","UserId":"user2"}]}

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 by an Org Admin of the specified organization.

func (t *Controller) AddOrgAdmin(org_id string, user_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Admin.AddOrgAdmin", "TOKEN", map[string]string{"org_id": org_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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 an organization. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization.

func (t *Controller) RemoveOrgAdmin(org_id string, user_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Admin.RemoveOrgAdmin", "TOKEN", map[string]string{"org_id": org_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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 any Org Admin.

func (t *Controller) GetOrgAdmins() (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Admin.GetOrgAdmins", "TOKEN")
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Admin.GetAllOrgAdmins()
}

Parameters:

• none

Returns:

• On success, a JSON list that includes OrgId and UserId objects.

Return Value Example:

{
    "admins": [
        {
            "OrgId": "Org1MSP",
            "UserId": "orgadmin"
        },
        {
            "OrgId": "Org1MSP",
            "UserId": "orgadmin1"
        },
        {
            "OrgId": "Org1MSP",
            "UserId": "orgadmin2"
        }
    ]
}

Methods for Token Configuration Management

Init

This method is called when the chaincode is deployed. 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 AddTokenAdmin and RemoveTokenAdmin methods.

func (t *Controller) Init(adminList []admin.TokenAdminAsset) (interface{}, error) {
    list, err := t.Ctx.Admin.InitAdmin(adminList)
    if err != nil {
        return nil, fmt.Errorf("initializing admin list failed %s", err.Error())
    }
    return list, nil
}

Parameters:

• adminList array – An array of {user_id, org_id} information that specifies the list of token admins. The adminList array is a mandatory parameter.

Parameter example, Mac OSX and Linux CLI:

'[{"user_id":"userid", "org_id":"OrgMSPId"}]'

Parameter example, Microsoft Windows CLI:

"[{\"user_id\":\"userid\", \"org_id\":\"OrgMSPId\"}]"

Parameter example, Oracle Blockchain Platform console:

["[{\"user_id\":\"userid\", \"org_id\":\"OrgMSPId\"}]"]

Initialize<Token Name>Token

This method creates a token and initializes the token properties. The asset and its properties are saved in the state database. This method can be invoked only by a Token Admin of the chaincode.

func (t *Controller) InitializeDigicurToken(asset Digicur) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.Save", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    return t.Ctx.Token.Save(&asset)
}

Parameters:

• asset <Token Class> – The token asset is passed as the parameter to this method. The properties of the token asset are described in the model file.

Returns:

• On success, a JSON representation of the token asset that was created.

Return Value Example:

{
    "AssetType": "otoken",
    "Token_id": "digiCurr101",
    "Token_name": "digicur",
    "Token_desc": "",
    "Token_type": "fungible",
    "Behavior": ["divisible", "mintable", "transferable", "burnable", "roles"],
    "Roles": {
        "minter_role_name": "minter"
    },
    "Mintable": {
        "Max_mint_quantity": 1000
    },
    "Divisible": {
        "Decimal": 2
    },
    "Currency_name": "",
    "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.

func (t *Controller) UpdateDigicurToken(asset Digicur) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.Update", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    return t.Ctx.Token.Update(&asset)
}

Parameters:

• asset <Token Class> – The token asset is passed as the parameter to this method. The properties of the token asset are described in the model file.

Returns:

• On success, an updated JSON representation of the token asset.

Return Value Example:

{
    "AssetType": "otoken",
    "Token_id": "digiCurr101",
    "Token_name": "digicur",
    "Token_desc": "Digital Currency equiv of dollar",
    "Token_type": "fungible",
    "Behavior": ["divisible", "mintable", "transferable", "burnable", "roles"],
    "Roles": {
        "minter_role_name": "minter"
    },
    "Mintable": {
        "Max_mint_quantity": 1000
    },
    "Divisible": {
        "Decimal": 2
    },
    "Currency_name": "",
    "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.

func (t *Controller) GetTokenDecimals(token_id string) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.GetTokenDecimals", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    tokenDecimal, err := t.Ctx.Token.GetTokenDecimals(token_id)
    if err != nil {
        return nil, fmt.Errorf("Error in GetTokenDecimals %s", err.Error())
    }
    response := make(map[string]interface{})
    response["msg"] = fmt.Sprintf("Token Id: %s has %d decimal places.", token_id, tokenDecimal)
    return response, nil
}

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 Org Admin of the chaincode.

func (t *Controller) GetTokenById(token_id string) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.Get", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    tokenAsset, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    return tokenAsset.Interface(), err
}

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",
    "Behavior": [
        "divisible",
        "mintable",
        "transferable",
        "burnable",
        "roles"
    ],
    "Roles": {
        "minter_role_name": "minter"
    },
    "Mintable": {
        "Max_mint_quantity": 1000
    },
    "Divisible": {
        "Decimal": 2
    },
    "Currency_name": "",
    "Token_to_currency_ratio": 1
}

GetTokenHistory

This method returns the token history for a specified token ID. Any user can call this method.

func (t *Controller) GetTokenHistory(token_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Token.GetTokenHistory", "TOKEN")
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Token.History(token_id)
}

Parameters:

• tokenId: string – The ID of the token.

Returns:

• On success, a JSON object that represents the token history.

Return Value Example:

[
    {
        "IsDelete": "false",
        "Timestamp": "2023-09-01T16:46:33Z",
        "TxId": "12333b8a4f63aa9b3a34072efcbd7df546c6d1e7d82a7a9596e899383656d6f7",
        "Value": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "Currency_name1": "",
            "Divisible": {
                "Decimal": 2
            },
            "Mintable": {
                "Max_mint_quantity": 1000
            },
            "Roles": {
                "minter_role_name": "minter"
            },
            "Token_desc": "updated description",
            "Token_id": "token",
            "Token_name": "fiatmoneytok",
            "Token_to_currency_ratio": 0,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    },
    {
        "IsDelete": "false",
        "Timestamp": "2023-09-01T16:04:25Z",
        "TxId": "99702e2dad7554a5ee4716a0d01d3e394cbce39bea8bade265d8911f30ebad0b",
        "Value": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "Currency_name1": "",
            "Divisible": {
                "Decimal": 2
            },
            "Mintable": {
                "Max_mint_quantity": 1000
            },
            "Roles": {
                "minter_role_name": "minter"
            },
            "Token_desc": "",
            "Token_id": "token",
            "Token_name": "fiatmoneytok",
            "Token_to_currency_ratio": 0,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    }
]

GetAllTokens

This method returns all tokens that are stored in the state database. This method can be called only by a Token Admin or Org Admin of the chaincode.

func (t *Controller) GetAllTokens() (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.GetAllTokens", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.Token.GetAllTokens()
}

Parameters:

• none

Returns:

• On success, a JSON object that represents all token assets.

Return Value Example:

"payload": [
    {
        "key": "t1",
        "valueJson": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "holdable",
                "burnable",
                "roles"
            ],
            "Currency_name": "Currency_name value",
            "Divisible": {
                "Decimal": 8
            },
            "Mintable": {
                "Max_mint_quantity": 10000
            },
            "Roles": {
                "burner_role_name": "burner",
                "minter_role_name": "minter",
                "notary_role_name": "notary"
            },
            "Token_desc": "Token_desc value",
            "Token_id": "t1",
            "Token_name": "obptok",
            "Token_to_currency_ratio": 2,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    }
]

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.

func (t *Controller) GetTokensByName(token_name string) (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.GetTokensByName", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.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.

Return Value Example:

"payload": [
    {
        "key": "t1",
        "valueJson": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "holdable",
                "burnable",
                "roles"
            ],
            "Currency_name": "Currency_name value",
            "Divisible": {
                "Decimal": 8
            },
            "Mintable": {
                "Max_mint_quantity": 10000
            },
            "Roles": {
                "burner_role_name": "burner",
                "minter_role_name": "minter",
                "notary_role_name": "notary"
            },
            "Token_desc": "Token_desc value",
            "Token_id": "t1",
            "Token_name": "obptok",
            "Token_to_currency_ratio": 999,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    },
    {
        "key": "obp2",
        "valueJson": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "holdable",
                "burnable",
                "roles"
            ],
            "Currency_name": "",
            "Divisible": {
                "Decimal": 8
            },
            "Mintable": {
                "Max_mint_quantity": 10000
            },
            "Roles": {
                "burner_role_name": "burner",
                "minter_role_name": "minter",
                "notary_role_name": "notary"
            },
            "Token_desc": "",
            "Token_id": "obp2",
            "Token_name": "obptok",
            "Token_to_currency_ratio": 0,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    }
]

Methods for Account Management

CreateAccount

This method creates an account for a specified user and token. An account must be created for any user who will have tokens at any point. Accounts track balances, on-hold balances, and transation 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 an Org Admin of the specified organization.

unc (t *Controller) CreateAccount(org_id string, user_id string, token_type string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.CreateAccount", "TOKEN", map[string]string{"org_id": org_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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",
   "AccountId":"oaccount~a73085a385bc96c4a45aa2dff032e7dede82c0664dee5f396b7c5854eeafd4bd",
   "BapAccountVersion": 0,
   "UserId":"user1",
   "OrgId":"Org1MSP",
   "AccountType":"fungible",
   "TokenId":"",
   "TokenName":"",
   "Balance":0,
   "BalanceOnHold":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.

func (t *Controller) AssociateTokenToAccount(account_id string, token_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.AssociateToken", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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", 
"AccountId":"oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb", 
"BapAccountVersion": 0,
"UserId":"admin", 
"OrgId":"Org1MSP", 
"AccountType":"fungible", 
"TokenId":"token1", 
"TokenName":"loyaltok", 
"Balance":0, 
"BalanceOnHold":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.

func (t *Controller) GetAccount(token_id string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAccount", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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:
• AccountId – The ID of the user account.
• UserId – The user name or email ID of the user.
• OrgId – The membership service provider (MSP) ID of the user in the current organization.
• TokenId – The ID of the token.
• Balance – The current balance of the account.
• BalanceOnHold – 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:

{
  "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
  "AssetType": "oaccount",
  "Balance": 95,
  "BalanceOnHold": 0,
  "BapAccountVersion": 8,
  "OrgId": "appdev",
  "Status": "active",
  "TokenId": "obp1",
  "TokenName": "obptok",
  "TokenType": "fungible",
  "UserId": "idcqa"
}

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.

func (t *Controller) GetAccountHistory(token_id string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.History", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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:
• TxId – The transaction ID of the transaction as returned by the ledger.
• Timestamp – The time of the transaction.
• IsDelete – A Boolean value that indicates whether the record is deleted.
• Value – A JSON string of the account object. The BapAccountVersion parameter is defined in the account object for internal use.

Return Value Example:

[
  {
      "IsDelete": "false",
      "Timestamp": "2023-08-28T19:31:15Z",
      "TxId": "adde470a63860ec1013bd5c5987e8a506a48942a91b0f39fc8e561374042bd27",
      "Value": {
          "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
          "AssetType": "oaccount",
          "Balance": 100,
          "BalanceOnHold": 0,
          "BapAccountVersion": 1,
          "OrgId": "Org1MSP",
          "TokenId": "t1",
          "TokenName": "obptok",
          "TokenType": "fungible",
          "UserId": "idcqa"
      }
  },
  {
      "IsDelete": "false",
      "Timestamp": "2023-08-28T19:30:23Z",
      "TxId": "8fbeda2ba60ba175091faae5ae369247775f2cba45c4d6d1ead6f0b05be84743",
      "Value": {
          "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
          "AssetType": "oaccount",
          "Balance": 0,
          "BalanceOnHold": 0,
          "BapAccountVersion": 0,
          "OrgId": "Org1MSP",
          "TokenId": "t1",
          "TokenName": "obptok",
          "TokenType": "fungible",
          "UserId": "idcqa"
      }
  },
  {
      "IsDelete": "false",
      "Timestamp": "2023-08-28T19:29:54Z",
      "TxId": "19bb296ae71709e91b097ba5d9ebd7f7522095880382fbf5913334a46a6026aa",
      "Value": {
          "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
          "AssetType": "oaccount",
          "Balance": 0,
          "BalanceOnHold": 0,
          "BapAccountVersion": 0,
          "OrgId": "Org1MSP",
          "TokenId": "",
          "TokenName": "",
          "TokenType": "fungible",
          "UserId": "idcqa"
      }
  }
]

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.

func (t *Controller) GetAccountOnHoldBalance(token_id string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAccountOnHoldBalance", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      response, err := t.Ctx.Account.GetAccountOnHoldBalance(account_id)
      return response, err
}

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:

{
    "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 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.

func (t *Controller) GetAllAccounts() (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAllAccounts", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.Account.GetAllAccounts()
}

Parameters:

• none

Returns:

• On success, a JSON array of all accounts.

Return Value Example:

[
    {
        "key": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
        "valueJson": {
            "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
            "AssetType": "oaccount",
            "Balance": 100,
            "BalanceOnHold": 0,
            "BapAccountVersion": 1,
            "OrgId": "appdev",
            "TokenId": "t1",
            "TokenName": "obptok",
            "TokenType": "fungible",
            "UserId": "idcqa"
        }
    }
]

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.

func (t *Controller) GetUserByAccountId(account_id string) (interface{}, error) {
    return t.Ctx.Account.GetUserByAccountById(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:

{"org_id":"Org1MSP","token_id":"digiCurr101","user_id":"user1"}

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.

func (t *Controller) GetAccountBalance(token_id string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAccountBalance", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      response, err := t.Ctx.Account.GetAccountBalance(account_id)
      return response, err
}

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 of oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f 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.

func (t *Controller) GetAllOrgAccounts(org_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAllOrgAccounts", "TOKEN", map[string]string{"org_id": org_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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": {
            "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
            "AssetType": "oaccount",
            "Balance": 0,
            "BalanceOnHold": 0,
            "BapAccountVersion": 0,
            "OrgId": "appdev",
            "TokenId": "token",
            "TokenName": "fiatmoneytok",
            "TokenType": "fungible",
            "UserId": "idcqa"
        }
    },
    {
        "key": "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850",
        "valueJson": {
            "AccountId": "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850",
            "AssetType": "oaccount",
            "Balance": 0,
            "BalanceOnHold": 0,
            "BapAccountVersion": 0,
            "OrgId": "appdev",
            "TokenId": "token",
            "TokenName": "fiatmoneytok",
            "TokenType": "fungible",
            "UserId": "example_minter"
        }
    }
]

Methods for Role Management

AddRole

This method adds a role to a specified user and token. This method can be called only by a Token Admin of the chaincode or by an Org Admin of the specified organization who also has the specified role.

func (t *Controller) AddRole(token_id string, user_role string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      tokenAssetValue, err := t.getTokenObject(token_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Token.AddRoleMember", "TOKEN", map[string]string{"org_id": org_id, "token_id": token_id, "role": user_role})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Token.AddRoleMember(user_role, account_id, tokenAssetValue.Interface())
}

Parameters:

• token_id string – The ID of the token.
• user_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 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 an Org Admin of the specified organization who also has the specified role.

func (t *Controller) RemoveRole(token_id string, user_role string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      tokenAssetValue, err := t.getTokenObject(token_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Token.RemoveRoleMember", "TOKEN", map[string]string{"org_id": org_id, "token_id": token_id, "role": user_role})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Token.RemoveRoleMember(user_role, account_id, tokenAssetValue.Interface())
}

Parameters:

• token_id string – The ID of the token.
• user_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 member_id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1) from role minter"}

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.

func (t *Controller) GetAccountsByRole(token_id string, user_role string) (interface{}, error) {
    auth, err:= t.Ctx.Auth.CheckAuthorization("Role.GetAccountsByRole", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    return t.Ctx.Role.GetAccountsByRole(token_id, user_role)
}

Parameters:

• token_id string – The ID of the token.
• user_role string – The name of the role to search for.

Returns:

• On success, a JSON array of account IDs.

Return Value Example:

{
    "accounts": [
        "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4"
    ]
}

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 a Token Admin of the chaincode, an Org Admin of the specified organization, or by the Account Owner specified in the parameters.

func (t *Controller) GetAccountsByUser(org_id string, user_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAccountsByUser", "TOKEN", map[string]string{"org_id": org_id, "user_id": user_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4"
    ]
}

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 or by the Account Owner specified in the parameters.

func (t *Controller) GetUsersByRole(token_id string, user_role string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Role.GetUsersByRole", "TOKEN")
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Role.GetUsersByRole(token_id, user_role)
}

Parameters:

• token_id string – The ID of the token.
• user_role string – The name of the role to search for.

Returns:

• On success, a JSON array of the user objects (org_id and user_id).

Return Value Example:

{"Users":[{"org_id":"Org1MSP","token_id":"digiCurr101","user_id":"user1"}]}

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

func (t *Controller) IsInRole(token_id string, org_id string, user_id string, user_role string) (interface{}, error) {
      tokenAssetValue, err := t.getTokenObject(token_id)
      if err != nil {
            return nil, err
      }
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Token.IsInRole", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      result, err := t.Ctx.Token.IsInRole(user_role, account_id, tokenAssetValue.Interface())
      if err != nil {
            return nil, fmt.Errorf("error in IsInRole %s", err.Error())
      }
      response := make(map[string]interface{})
      response["result"] = result
      return response, nil
}

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.
• 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}

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.

func (t *Controller) GetOrgUsersByRole(token_id string, user_role string, org_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Role.GetOrgUsersByRole", "TOKEN", map[string]string{"org_id": org_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Role.GetOrgUsersByRole(token_id, user_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": [
        {
            "org_id": "Org1MSP",
            "token_id": "token",
            "user_id": "admin"
        },
        {
            "org_id": "Org1MSP",
            "token_id": "token",
            "user_id": "orgAdmin"
        }
    ]
}

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.

func (t *Controller) GetOrgAccountsByRole(token_id string, user_role string, org_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Role.GetOrgAccountsByRole", "TOKEN", map[string]string{"org_id": org_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Role.GetOrgAccountsByRole(token_id, user_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"
    ]
}

Methods for Transaction History Management

GetAccountTransactionHistory

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

func (t *Controller) GetAccountTransactionHistory(token_id string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAccountTransactionHistory", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }

      transactionArray, err := t.Ctx.Account.GetAccountTransactionHistory(account_id, org_id, user_id)
      return transactionArray, err
}

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:
• balance – The account balance.
• holding_id – The ID of a holding account.
• onhold_balance – The on-hold balance.
• timestamp – The time of the transaction.
• token_id – The ID of the token.
• transacted_account – The account with which the transaction took place.
• transacted_amount – The amount of the transaction.
• transaction_id – The ID of the transaction.
• transaction_type – The type of transaction.

Return Value Example:

[{
    "balance": 199,
    "onhold_balance": 0,
    "timestamp": "2021-08-16T17:42:32.905+05:30",
    "token_id": "digiCurr101",
    "transacted_account": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "transacted_amount": 1,
    "transaction_id": "otransaction~c8a9fa001aba6e0d8391b034655889df47eb5103713840b999a4ab41f5e57b38",
    "transaction_type": "DEBIT"
}, {
    "balance": 200,
    "onhold_balance": 0,
    "timestamp": "2021-08-16T17:41:59.262+05:30",
    "token_id": "digiCurr101",
    "transacted_account": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "transacted_amount": 100,
    "transaction_id": "otransaction~65a0bf8ae8108baa7495fbab91c205651c055e9f480f6808753287173026aa69",
    "transaction_type": "MINT"
}]

GetAccountTransactionHistoryWithFilters

This method returns an array of account transaction history details for a specified user and token. This method can be called only by the Token Admin of the chaincode, an Org Admin of the specified organization, or the AccountOwner of the account. This method can only be called when connected to the remote Oracle Blockchain Platform network.

func (t *Controller) GetAccountTransactionHistoryWithFilters(token_id string, org_id string, user_id string, filters ...account.AccountHistoryFilters) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetAccountTransactionHistoryWithFilters", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }

      // sample format of filter: []string{"3", "", "2022-01-16T15:16:36+00:00", "2022-01-17T15:16:36+00:00"}
      transactionArray, err := t.Ctx.Account.GetAccountTransactionHistoryWithFilters(account_id, org_id, user_id, filters...)
      return transactionArray, err
}

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~3f9c306b0ef6994885939c1a6eb5f063b06617ecb932d4a043f323ba53d55f9f",
    "transacted_amount": 200,
    "timestamp": "2022-02-15T18:27:13.000Z",
    "token_id": "token1",
    "transacted_account": "oaccount~obptok~26e046c8ba8b98da2cdabb78113d67200581ea3d4eea5aa324
1abd3598e05d05",
    "transaction_type": "DEBIT",
    "balance": 9200,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~f1d37c3abd5c85c0a399f246d8eb68257c49ab4fe4cdfd3501908583c51c421e",
    "transacted_amount": 200,
    "timestamp": "2022-02-15T18:27:02.000Z",
    "token_id": "token1",
    "transaction_type": "BULKTRANSFER",
    "number_of_sub_transactions": 2,
    "balance": 9600,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b",
    "transacted_amount": 200,
    "timestamp": "2022-02-15T18:26:57.000Z",
    "token_id": "token1",
    "transaction_type": "BULKTRANSFER",
    "number_of_sub_transactions": 2,
    "balance": 9800,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~07331a1f7be99d6750973674a783da9ec9ca17df23747cdf52d388865d93f9a",
    "transacted_amount": 10000,
    "timestamp": "2022-02-15T18:26:30.000Z",
    "token_id": "token1",
    "transacted_account": "oaccount~obptok~88b62f329f20fffc6fc9231cb51019a5e9550c78b657123d140897
62397d2b55",
    "transaction_type": "MINT",
    "balance": 10000,
    "onhold_balance": 0
  }
]

GetSubTransactionsById

This method returns an array of subtransaction history details for a specified transaction.

func (t *Controller) GetSubTransactionsById(transaction_id string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetSubTransactionsById", "TOKEN", map[string]string{"transaction_id": transaction_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Account.GetSubTransactionsById(transaction_id)
}

Parameters:

• transaction_id string – The ID of the transaction.

Example:

ochain invoke GetAccountSubTransactionHistory 'otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b'

[
  {
    "transaction_id": "otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b~c4ca4238a0b923820dcc509a6f75849b",
    "transacted_amount": 100,
    "timestamp": "2022-02-15T18:26:57.000Z",
    "token_id": "token1",
    "transacted_account": "oaccount~obptok~6600eb38d365552b76f41d4186acece104f31eae331a440f963e6fa75b62ff21",
    "transaction_type": "DEBIT",
    "balance": 9900,
    "onhold_balance": 0
  },
  {
    "transaction_id": "otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b~c81e728d9d4c2f636f067f89cc14862c",
    "transacted_amount": 100,
    "timestamp": "2022-02-15T18:26:57.000Z",
    "token_id": "token1",
    "transacted_account": "oaccount~obptok~26e046c8ba8b98da2cdabb78113d67200581ea3d4eea5aa3241abd3598e05d05",
    "transaction_type": "DEBIT",
    "balance": 9800,
    "onhold_balance": 0
  }
]

GetSubTransactionsByIdWithFilters

This method returns an array of subtransaction history details for a specified transaction.

func (t *Controller) GetSubTransactionsByIdWithFilters(transaction_id string, filters ...account.SubTransactionFilters) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetSubTransactionsByIdWithFilters", "TOKEN", map[string]string{"transaction_id": transaction_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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.

Example:

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

[
{
"transaction_id": "otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b~c4ca4238a0b923820dcc509a6f75849b",
"transacted_amount": 100,
"timestamp": "2022-02-15T18:26:57.000Z",
"token_id": "token1",
"transacted_account": "oaccount~obptok~6600eb38d365552b76f41d4186acece104f31eae331a440f963e6fa75b62ff21",
"transaction_type": "DEBIT",
"balance": 9900,
"onhold_balance": 0
},
{
"transaction_id": "otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b~c81e728d9d4c2f636f067f89cc14862c",
"transacted_amount": 100,
"timestamp": "2022-02-15T18:26:57.000Z",
"token_id": "token1",
"transacted_account": "oaccount~obptok~26e046c8ba8b98da2cdabb78113d67200581ea3d4eea5aa3241abd3598e05d05",
"transaction_type": "DEBIT",
"balance": 9800,
"onhold_balance": 0
}
]

GetTransactionById

This method returns the history of a Transaction asset.

func (t *Controller) GetTransactionById(transaction_id string) (interface{}, error) {
    return t.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:

{
    "history": [
        {
            "IsDelete": "false",
            "Timestamp": "2021-08-16 20:19:05.028 +0530 IST",
            "TxId": "67042154a6853011d111b13f73943f06d2a6ae3cfb9a84cb104482c359eb2220",
            "Value": {
                "Amount": 3,
                "AssetType": "otransaction",
                "FromAccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                "HoldingId": "ohold~digicur~digiCurr101~op2",
                "NumberOfSubTransactions": 0,
                "Timestamp": "2021-08-16T20:19:05+05:30",
                "ToAccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                "TokenId": "digiCurr101",
                "TransactionId": "otransaction~67042154a6853011d111b13f73943f06d2a6ae3cfb9a84cb104482c359eb2220",
                "TransactionType": "RELEASEHOLD"
            }
        }
    ],
    "transaction_id": "otransaction~67042154a6853011d111b13f73943f06d2a6ae3cfb9a84cb104482c359eb2220"
}

DeleteHistoricalTransactions

This method deletes older transactions from the state database.

func (t *Controller) DeleteHistoricalTransactions(timestamp string) (interface{}, error) {
      auth, err := t.Ctx.Auth.CheckAuthorization("Transaction.DeleteHistoricalTransactions", "TOKEN")
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.Ctx.Transaction.DeleteHistoricalTransactions(timestamp)
}

Parameters:

• timestamp string – A time stamp that indicates when to delete transactions. Transaction assets that are older than the specified time will be deleted.

Methods for Token Behavior Management - Mintable Behavior

IssueTokens

This method mints tokens, which are then owned by the caller of the method. The caller must have an account and the minter role. The number of tokens that can be minted is limited by the max_mint_quantity property of mintable behavior in the specification file. If the max_mint_quantity property is not specified, an unlimited number of tokens can be minted. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. This method can be called only by the AccountOwner of the account with the minter role.

func (t *Controller) IssueTokens(token_id string, quantity float64) (interface{}, error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    return t.Ctx.Token.Mint(quantity, tokenAssetValue.Interface())
}

Parameters:

• token_id string – The ID of the token.
• quantity float64 – The number of tokens to mint.

Returns:

• On success, a message with account details.

Return Value Example:

{"msg":"Successfully minted 100 tokens to account oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (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 Org Admin of the chaincode.

func (t *Controller) GetTotalMintedTokens(token_id string) (interface{}, error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.GetTotalMintedTokens", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    return t.Ctx.Token.GetTotalMintedTokens(tokenAssetValue.Interface())
}

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 amount for token with id digiCurr101 is 1000","quantity":1000}

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 Org Admin of the chaincode.

func (t *Controller) GetNetTokens(token_id string) (interface{}, error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    auth, err := t.Ctx.Auth.CheckAuthorization("Token.GetNetTokens", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    return t.Ctx.Token.GetNetTokens(tokenAssetValue.Interface())
}

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 minted amount for token with id digiCurr101 is 1000","quantity":1000}

Methods for Token Behavior Management - Transferable Behavior

TransferTokens

This method transfers tokens from the caller to a specified account. The caller of the method must have an account. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. This method can be called only by the AccountOwner of the account.

func (t *Controller) TransferTokens(token_id string, to_org_id string, to_user_id string, quantity float64) (interface{}, error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    to_account_id, err := t.Ctx.Account.GenerateAccountId(token_id, to_org_id, to_user_id)
    if err != nil {
        return nil, err
    }
    return t.Ctx.Token.Transfer(to_account_id, quantity, tokenAssetValue.Interface())
}

Parameters:

• token_id string – The ID of the token.
• 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.
• quantity float64 – The number of tokens to transfer.

Returns:

• On success, a message with details for both accounts.

Return Value Example:

{"msg":"successfully transferred 1 tokens from account oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1) to account oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (org_id : Org1MSP, user_id : admin)"}

BulkTransferTokens

This method is used to perform bulk transfer of tokens from the caller account to the accounts that are specified in the flow object. The quantities must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file.The caller of this method must have an account already created. This method can be called only by the AccountOwner of the account.

func (t *Controller) BulkTransferTokens(token_id string, flow[]map[string]interface{}) (interface{}, error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    return t.Ctx.Token.BulkTransfer(flow, tokenAssetValue.Interface())
}

Parameters:

• token_id string – The ID of the token.
• flow[]map[string]interface{} – An array of JSON objects that specify receiver details and quantities.
  • 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.
  • quantity float64 – The number of tokens to transfer.
  For example:

  [{
  	"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:

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

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.

func (t *Controller) HoldTokens(token_id string, operation_id string, to_org_id string, to_user_id string, notary_org_id string, notary_user_id string, quantity float64, TimeToExpiration string) (interface{}, error) {
      tokenAssetValue, err := t.getTokenObject(token_id)
      if err != nil {
            return nil, err
      }
      notary_account_id, err := t.Ctx.Account.GenerateAccountId(token_id, notary_org_id, notary_user_id)
      if err != nil {
            return nil, fmt.Errorf("error in getting notary account id from org_id: %s and user_id: %s with token_id: %s, error %s ", notary_org_id, notary_user_id, token_id, err.Error())
      }
      to_account_id, err := t.Ctx.Account.GenerateAccountId(token_id, to_org_id, to_user_id)
      if err != nil {
            return nil, fmt.Errorf("error in getting to_account id from org_id: %s and user_id: %s with token_id: %s, error %s ", to_org_id, to_user_id, token_id, err.Error())
      }
      return t.Ctx.Token.Hold(operation_id, to_account_id, notary_account_id, quantity, TimeToExpiration, tokenAssetValue.Interface())
}

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 float64 – 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~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1) is successfully holding 2 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. The hold can only be completed by the notary.

func (t *Controller) ExecuteHoldTokens(token_id string, operation_id string, quantity float64) (interface{} error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    return t.Ctx.Token.ExecuteHold(operation_id, quantity, tokenAssetValue.Interface())
}

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 float64 – 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~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1) has successfully executed '1' tokens(digiCurr101) from the hold with Operation Id 'op1'"}

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 Account Owner ID with the notary role within the specified time limit or by the payer, payee, or notary after the specified time limit.

func (t *Controller) ReleaseHoldTokens(token_id string, operation_id string) (interface{} error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    return t.Ctx.Token.ReleaseHold(operation_id, tokenAssetValue.Interface())
}

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 '3' tokens from Operation Id 'op2' to Account Id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (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 the Token Admin of the chaincode, an Org Admin of the specified organization, or the Account Owner of the account.

func (t *Controller) GetOnHoldIds(token_id string, org_id string, user_id string) (interface{}, error) {
      account_id, err := t.Ctx.Account.GenerateAccountId(token_id, org_id, user_id)
      if err != nil {
            return nil, err
      }
      auth, err := t.Ctx.Auth.CheckAuthorization("Account.GetOnHoldIds", "TOKEN", map[string]string{"account_id": account_id})
      if err != nil && !auth {
            return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
      }
      return t.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. A holding ID is a concatenation of the ohold asset type, the name of the token, the token ID, and the operation ID.

Return Value Example:

{"holding_ids":["ohold~loyaltok123~t1~op1"],"msg":"Holding Ids are: [ohold~loyaltok123~t1~op1]"}

GetOnHoldDetailsWithOperationId

This method returns the on-hold transaction details for a specified operation ID and token. This method can be invoked by anyone.

func (t *Controller) GetOnHoldDetailsWithOperationId(token_id string, operation_id string) (interface{} error) {
    return t.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:
• HoldingId – The holding ID of the transaction.
• OperationId – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
• FromAccountId – The account ID of the current owner of the on-hold tokens.
• ToAccountId – The account ID of the receiver.
• NotaryAccountId – The account ID of the notary.
• TokenId – The ID of the saved token.
• Quantity – The amount of tokens that are on hold for the holding ID.
• TimeToExpiration – The duration until the hold expires.

Return Value Example:

{
    "AssetType": "ohold",
    "HoldingId": "ohold~digicur~digiCurr101~op1",
    "OperationId": "op1",
    "TokenName": "digicur",
    "FromAccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "ToAccountId": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
    "NotaryAccountId": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
    "TokenId": "digiCurr101",
    "Quantity": 2,
    "TimeToExpiration": "0"
}

GetOnHoldBalanceWithOperationId

This method returns the on-hold balance for a specified operation ID and token. This method can be invoked by anyone.

func (t *Controller) GetOnHoldBalanceWithOperationId(token_id string, operation_id string) (interface{} error) {
    return t.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:

{
	"holding_balance": 10,
	"msg": "Current Holding Balance of OperationId opr_121 for token digiCurr101 is : 10"
}

Methods for Token Behavior Management - Burnable Behavior

BurnTokens

This method deactivates, or burns, tokens from the transaction caller's account. The caller of this method must have an account and the burner role. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file. This method can be called by the Account Owner of the account with the burner role.

func (t *Controller) BurnTokens(token_id string, quantity float64) (interface{} error) {
    tokenAssetValue, err := t.getTokenObject(token_id)
    if err != nil {
        return nil, err
    }
    return t.Ctx.Token.Burn(quantity, tokenAssetValue.Interface())
}

Parameters:

• token_id string – The ID of the token.
• quantity float64 – 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 1 tokens from account id: oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e (org_id : Org1MSP, user_id : user2)"}

Custom Methods

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

Make sure to track the return value when you use the token SDK methods. Also, 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.

func (t *Controller) BuyTicket(TokenId string, SellerOrgId string, SellerUserId string) (interface{}, error){
	token, err := t.Ctx.Token.Get(TokenId)
	if err != nil {
		return nil, err
	}
	
	/**
	* The following method t.Ctx.Account.GenerateAccountId(TokenId, SellerOrgId, SellerUserId) generates account id of the seller
	*/
	sellerAccountId, err := t.Ctx.Account.GenerateAccountId(TokenId, SellerOrgId, SellerUserId)
    if err != nil {
		return nil, err
	}   

	/**
	* The following method t.Ctx.Token.Transfer(sellerAccountId, 20, token) transfers the quantity 20 from caller's
	* account & to seller's account.
	*/
    transaction, err := t.Ctx.Token.Transfer(sellerAccountId, 20, token)
    if err != nil {
		return nil, err
	}
    return transaction, nil
}

Token SDK Methods

• Access Control Management
• Token Configuration Management
• Account Management
• Role Management
• Transaction History Management
• Token Behavior Management
  • Mintable Behavior
  • Transferable Behavior
  • Holdable Behavior
  • Burnable Behavior

Methods for Access Control Management

The token SDK provides an access control function. Some methods can be called only by a Token Admin, Org Admin or AccountOwner of the token. You can use this feature to ensure that operations are carried out only by the intended users. Any unauthorized access results in an error. To use the access control function, import the Authorization class from the ../lib/auth module.

import { Authorization } from '../lib/auth';

AddAdmin

This method adds a user as a Token Admin of the token chaincode.

Ctx.AddAdmin(org_id string, user_id string) (interface{}, error)

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 success message and details for the Token Admin user that was added. On error, a non-nil error object containing an error message.

Return Value Example:

{"msg":"Successfully added Admin (Org_Id: Org1MSP, User_Id: user2)"}

RemoveAdmin

This method removes a user as a Token Admin of the token chaincode.

Ctx.RemoveAdmin(org_id string, user_id string) (interface{}, error)

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 success message and details for the Token Admin user that was removed. On error, a non-nil error object containing an error message.

Return Value Example:

{"msg":"Successfuly removed Admin (Org_Id Org1MSP User_Id user1)"}

GetAllAdmins

This method returns a list of all users who are a Token Admin of the token chaincode.

Ctx.GetAllAdmins() (interface{}, error)

Parameters:

• none

Returns:

• On success, a list of all users who are a Token Admin of the token chaincode. On error, a non-nil error object containing an error message.

Return Value Example:

[{"OrgId":"Org1MSP","UserId":"admin"},{"OrgId":"Org1MSP","UserId":"user1"}]

GetAllAdminUsers

This method returns a list of all users who are a Token Admin of the token chaincode.

Ctx.Admin.GetAllAdminUsers() (interface{}, error) 

Parameters:

• none

Returns:

• On success, a list of all users who are a Token Admin of the token chaincode in map[string]interface{} form. On error, a non-nil error object containing an error message.

Return Value Example:

{"admins":[{"OrgId":"Org1MSP","UserId":"admin"},{"OrgId":"Org1MSP","UserId":"user1"}]}

CheckAuthorization

Use this method to add access control to your chaincode. Many of the automatically generated token methods use access control. The mapping between the SDK receiver and the methods which have access control is described in the oChainUtil.go 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.

var t TokenAccess
      var r RoleAccess
      var a AccountAccess
      var as AccountStatusAccess
      var h HoldAccess
      var ad AdminAccess
      var trx TransactionAccess
      var tc TokenConversionAccess
      var auth AuthAccess

      auth.IsTokenAdmin = []string{"Admin", "MultipleAccountOwner"}

      trx.DeleteHistoricalTransactions = []string{"Admin"}
      ad.AddAdmin = []string{"Admin"}
      ad.RemoveAdmin = []string{"Admin"}
      ad.GetAllAdmins = []string{"Admin", "OrgAdmin"}
      ad.AddOrgAdmin = []string{"Admin", "OrgAdminOrgIdCheck"}
      ad.RemoveOrgAdmin = []string{"Admin", "OrgAdminOrgIdCheck"}
      ad.GetOrgAdmins = []string{"Admin", "OrgAdmin"}
      ad.IsTokenAdmin = []string{"Admin", "MultipleAccountOwner", "OrgAdmin"}
      t.Save = []string{"Admin"}
      t.GetAllTokens = []string{"Admin", "OrgAdmin"}
      t.Update = []string{"Admin"}
      t.GetTokenDecimals = []string{"Admin", "OrgAdmin"}
      t.GetTokensByName = []string{"Admin", "OrgAdmin"}
      t.AddRoleMember = []string{"Admin", "OrgAdminRoleCheck"}
      t.RemoveRoleMember = []string{"Admin", "OrgAdminRoleCheck"}
      t.IsInRole = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      t.GetTotalMintedTokens = []string{"Admin", "OrgAdmin"}
      t.GetNetTokens = []string{"Admin", "OrgAdmin"}
      t.Get = []string{"Admin", "OrgAdmin"}
      t.GetTokenHistory = []string{"Admin", "OrgAdmin"}
      a.CreateAccount = []string{"Admin", "OrgAdminOrgIdCheck"}
      a.AssociateToken = []string{"Admin", "OrgAdminAccountIdCheck"}
      a.GetAllAccounts = []string{"Admin"}
      a.GetAllOrgAccounts = []string{"Admin", "OrgAdminOrgIdCheck"}
      a.GetAccount = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      a.History = []string{"Admin", "AccountOwner"}
      a.GetAccountTransactionHistory = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      a.GetAccountTransactionHistoryWithFilters = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      a.GetSubTransactionsById = []string{"Admin", "TransactionInvoker"}
      a.GetSubTransactionsByIdWithFilters = []string{"Admin", "TransactionInvoker"}
      a.GetAccountBalance = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      a.GetAccountOnHoldBalance = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      a.GetOnHoldIds = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      a.GetAccountsByUser = []string{"Admin", "OrgAdminOrgIdCheck", "MultipleAccountOwner"}

      as.Get = []string{"Admin", "OrgAdminAccountIdCheck", "AccountOwner"}
      as.ActivateAccount = []string{"Admin", "OrgAdminOrgIdCheck"}
      as.SuspendAccount = []string{"Admin", "OrgAdminOrgIdCheck"}
      as.DeleteAccount = []string{"Admin", "OrgAdminOrgIdCheck"}

      r.GetAccountsByRole = []string{"Admin"}
      r.GetUsersByRole = []string{"Admin"}
      r.GetOrgAccountsByRole = []string{"Admin", "OrgAdminOrgIdCheck"}
      r.GetOrgUsersByRole = []string{"Admin", "OrgAdminOrgIdCheck"}

      tc.InitializeExchangePoolUser = []string{"Admin"}
      tc.AddConversionRate = []string{"Admin"}
      tc.UpdateConversionRate = []string{"Admin"}
      tc.GetConversionRate = []string{"Admin", "OrgAdmin", "AnyAccountOwner"}
      tc.GetConversionRateHistory = []string{"Admin", "OrgAdmin", "AnyAccountOwner"}
      tc.TokenConversion = []string{"Admin", "AnyAccountOwner"}
      tc.GetExchangePoolUser = []string{"Admin"}

Ctx.Auth.CheckAuthorization(classFuncName string, args ...string) (bool, error)

Parameters:

• classFuncName string – The map value between the receivers and methods as described in the oChainUtil.go file.
• args – A variable argument, where args[0] is the constant TOKEN and args[1] is the account_id argument, if required.

Returns:

• A Boolean response and an error message if an error is encountered.

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()  (bool, error)

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.

Return Value Example:

{"result":false}

AddOrgAdmin

This method adds a user as an Org Admin of the organization.

Ctx.Admin.AddOrgAdmin(org_id, user_id) (interface{}, error)

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 an organization.

Ctx.Admin.RemoveOrgAdmin(org_id, user_id) (interface{}, error)

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() (interface{}, error)

Parameters:

• none

Returns:

• On success, a JSON list that includes OrgId and UserId objects.

Return Value Example:

{
    "admins": [
        {
            "OrgId": "Org1MSP",
            "UserId": "orgadmin"
        },
        {
            "OrgId": "Org1MSP",
            "UserId": "orgadmin1"
        },
        {
            "OrgId": "Org1MSP",
            "UserId": "orgadmin2"
        }
    ]
}

Methods for Token Configuration Management

GetTokenDecimals

This method returns the number of decimal places available for a fractional token. If the divisible behavior is not specified, then the default value is 0.

Ctx.Token.GetTokenDecimals(token_id string) (int, error)

Parameters:

• none

Returns:

• On success, the decimal places of the token, in the number data type. On error, a non-nil error object containing an error message.

Return Value Example:

1

GetAllTokens

This method returns all of the token assets that are 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()  (interface{}, error)

Parameters:

• none

Returns:

• On success, an array of a map of all token assets. On error, a non-nil error object containing an error message.

Return Value Example:

"payload": [
    {
        "key": "t1",
        "valueJson": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "holdable",
                "burnable",
                "roles"
            ],
            "Currency_name": "Currency_name value",
            "Divisible": {
                "Decimal": 8
            },
            "Mintable": {
                "Max_mint_quantity": 10000
            },
            "Roles": {
                "burner_role_name": "burner",
                "minter_role_name": "minter",
                "notary_role_name": "notary"
            },
            "Token_desc": "Token_desc value",
            "Token_id": "t1",
            "Token_name": "obptok",
            "Token_to_currency_ratio": 999,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    }
]

GetTokensByName

This method returns all of 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) (interface{}, error)

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 a map of all of the token assets of the specified name.

Return Value Example:

"payload": [
    {
        "key": "t1",
        "valueJson": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "holdable",
                "burnable",
                "roles"
            ],
            "Currency_name": "Currency_name value",
            "Divisible": {
                "Decimal": 8
            },
            "Mintable": {
                "Max_mint_quantity": 10000
            },
            "Roles": {
                "burner_role_name": "burner",
                "minter_role_name": "minter",
                "notary_role_name": "notary"
            },
            "Token_desc": "Token_desc value",
            "Token_id": "t1",
            "Token_name": "obptok",
            "Token_to_currency_ratio": 999,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    },
    {
        "key": "obp2",
        "valueJson": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "holdable",
                "burnable",
                "roles"
            ],
            "Currency_name": "",
            "Divisible": {
                "Decimal": 8
            },
            "Mintable": {
                "Max_mint_quantity": 10000
            },
            "Roles": {
                "burner_role_name": "burner",
                "minter_role_name": "minter",
                "notary_role_name": "notary"
            },
            "Token_desc": "",
            "Token_id": "obp2",
            "Token_name": "obptok",
            "Token_to_currency_ratio": 0,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    }
]

Get

This method returns a token object if it is present in the state database. This method can be called only by a Token Admin of the token chaincode.

Ctx.Get(Id string, result ...interface{}) (interface{}, error)

Parameters:

• token_id: string – The ID of the token to return.
• result – A variable argument, where the first argument result[0] is a reference of an empty Token object of the required type.

Returns:

• On success, a map with the token asset data. The variable argument result[0] contains the token data. On error, a non-nil error object containing an error message.

Return Value Example:

{
    "AssetType": "otoken",
    "Token_id": "digiCurr101",
    "Token_name": "digicur",
    "Token_desc": "Digital Currency equiv of dollar",
    "Token_type": "fungible",
    "Behavior": ["divisible", "mintable", "transferable", "burnable", "holdable", "roles"],
    "Roles": {
        "burner_role_name": "burner",
        "minter_role_name": "minter",
        "notary_role_name": "notary"
    },
    "Mintable": {
        "Max_mint_quantity": 20000
    },
    "Divisible": {
        "Decimal": 1
    },
    "Token_to_currency_ratio": 1,
    "Currency_representation": "DOLLAR"
}

IsTokenType

This method tests whether a token asset exists for a specified token ID.

Ctx.Model.IsTokenType(token_id: string) error

Parameters:

• token_id: string – The ID of the token to check.

Returns:

• If a token asset exists with the specified ID, a nil error. Otherwise, a non-nil error object containing an error message.

Return Value Example:

nil

Save

This method creates a token and saves its properties in the state database.

Ctx.Token.Save(args ...interface{}) (interface{}, error)

Parameters:

• token_id: string – The ID of the token to return.
• args – A variable argument, where the first argument args[0] is a reference of the token struct data of the required type to add to the ledger.

Returns:

• On success, an interface{} object with details about the token that was saved to the state database. On error, a non-nil error object containing an error message.

Return Value Example:

{
    "AssetType": "otoken",
    "Token_id": "digiCurr101",
    "Token_name": "digicur",
    "Token_desc": "",
    "Token_type": "fungible",
    "Behavior": ["divisible", "mintable", "transferable", "burnable", "roles"],
    "Roles": {
        "minter_role_name": "minter"
    },
    "Mintable": {
        "Max_mint_quantity": 1000
    },
    "Divisible": {
        "Decimal": 2
    },
    "Currency_name": "",
    "Token_to_currency_ratio": 1
}

Update

This method updates token properties. After a token asset is created, you can update only the token_desc value and its custom properties.

Ctx.Token.Update(args ...interface{}) (interface{}, error)

Parameters:

• An asset that contains a reference to the token struct data of required type to update in the ledger.

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",
    "Behavior": ["divisible", "mintable", "transferable", "burnable", "roles"],
    "Roles": {
        "minter_role_name": "minter"
    },
    "Mintable": {
        "Max_mint_quantity": 1000
    },
    "Divisible": {
        "Decimal": 2
    },
    "Currency_name": "",
    "Token_to_currency_ratio": 1
}

GetByRange

This method calls the fabric getStateByRange method internally. Even though any asset with the given ID is returned from the ledger, this method casts the asset into the caller Asset type.

Ctx.Token.GetByRange(startId string, endId string, asset ...interface{}) ([]map[string]interface{}, error)

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.
• asset[0] – An empty slice of the token of the required type. If the method runs successfully, this contains the requested result.

Returns:

• On success, a slice of maps containing the token asset details for tokens where the token_id value is in the specified range. On error, a non-nil error object containing an error message.

Return Value Example:

[{
    "Key": "oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
    "Record": {
        "AccountId": "oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
        "AssetType": "oaccount",
        "Balance": 99,
        "BalanceOnHold": 1,
        "BapAccountVersion": 0,
        "OrgId": "Org1MSP",
        "TokenId": "t1",
        "TokenName": "loyaltok123",
        "UserId": "u1"
    }
}, {
    "Key": "oaccount~loyaltok123~ac30c5ca924a2c7def61acf596d91e0cca70bc8cd233179df4efb2791b56336b",
    "Record": {
        "AccountId": "oaccount~loyaltok123~ac30c5ca924a2c7def61acf596d91e0cca70bc8cd233179df4efb2791b56336b",
        "AssetType": "oaccount",
        "Balance": 0,
        "BalanceOnHold": 0,
        "BapAccountVersion": 0,
        "OrgId": "Org1MSP",
        "TokenId": "t1",
        "TokenName": "loyaltok123",
        "UserId": "u2"
    }
}, {
    "Key": "oaccount~loyaltok123~aef96c40d99e09ef17f9bdda7038e8fbe829a327bae2b4d8d9fcf752190f3ff0",
    "Record": {
        "AccountId": "oaccount~loyaltok123~aef96c40d99e09ef17f9bdda7038e8fbe829a327bae2b4d8d9fcf752190f3ff0",
        "AssetType": "oaccount",
        "Balance": 0,
        "BapAccountVersion": 0,
        "BalanceOnHold": 0,
        "OrgId": "Org1MSP",
        "TokenId": "t1",
        "TokenName": "loyaltok123",
        "UserId": "admin"
    }
}, {
    "Key": "oadmin~Org1MSP~admin",
    "Record": {
        "AssetType": "oadmin",
        "Key": "oadmin~Org1MSP~admin",
        "OrgId": "Org1MSP",
        "UserId": "admin"
    }
}, {
    "Key": "ohold~loyaltok123~t1~op1",
    "Record": {
        "AssetType": "ohold",
        "FromAccountId": "oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
        "HoldingId": "ohold~loyaltok123~t1~op1",
        "NotaryAccountId": "oaccount~loyaltok123~ac30c5ca924a2c7def61acf596d91e0cca70bc8cd233179df4efb2791b56336b",
        "OperationId": "op1",
        "Quantity": 1,
        "TimeToExpiration": "0",
        "ToAccountId": "oaccount~loyaltok123~aef96c40d99e09ef17f9bdda7038e8fbe829a327bae2b4d8d9fcf752190f3ff0",
        "TokenId": "t1",
        "TokenName": "loyaltok123"
    }
}, {
    "Key": "ometadata~loyaltok123~t1",
    "Record": {
        "AssetType": "ometadata",
        "Metadata_id": "ometadata~loyaltok123~t1",
        "Token_id": "t1",
        "Token_name": "loyaltok123",
        "Total_minted_amount": 100,
        "Total_supply": 100
    }
}, {
    "Key": "orole~t1~minter~oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
    "Record": {
        "AccountID": "oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
        "AssetType": "orole",
        "Key": "orole~t1~minter~oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
        "RoleName": "minter",
        "TokenId": "t1"
    }
}, {
    "Key": "otransaction~4a774f6493f6521cab9eda96822cb3bb4103c0738ee2dbb9a193b868ace36fa5",
    "Record": {
        "Amount": 100,
        "AssetType": "otransaction",
        "FromAccountId": "",
        "HoldingId": "",
        "NumberOfSubTransactions": 0,
        "Timestamp": "2021-08-25T23:04:42+05:30",
        "ToAccountId": "oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
        "TokenId": "t1",
        "TransactionId": "otransaction~4a774f6493f6521cab9eda96822cb3bb4103c0738ee2dbb9a193b868ace36fa5",
        "TransactionType": "MINT"
    }
}, {
    "Key": "otransaction~69f3cefbcb64b73f01a0eadff87169f456873ccebe61ca8da3eef3f465f0c129",
    "Record": {
        "Amount": 1,
        "AssetType": "otransaction",
        "FromAccountId": "oaccount~loyaltok123~a4bd3d8abfb1708198971311df77bb527233bcf9121ff95b0526bc056c4b8974",
        "HoldingId": "ohold~loyaltok123~t1~op1",
        "NumberOfSubTransactions": 0,
        "Timestamp": "2021-08-25T23:06:13+05:30",
        "ToAccountId": "oaccount~loyaltok123~aef96c40d99e09ef17f9bdda7038e8fbe829a327bae2b4d8d9fcf752190f3ff0",
        "TokenId": "t1",
        "TransactionId": "otransaction~69f3cefbcb64b73f01a0eadff87169f456873ccebe61ca8da3eef3f465f0c129",
        "TransactionType": "ONHOLD"
    }
}, {
    "Key": "t1",
    "Record": {
        "AssetType": "otoken",
        "Behavior": ["divisible", "mintable", "transferable", "burnable", "holdable", "roles"],
        "Currency_Name": "a",
        "Divisible": {
            "Decimal": 2
        },
        "Effective_From_Date": "2020-09-09T00:00:00Z",
        "Mintable": {
            "Max_mint_quantity": 10000
        },
        "Roles": {
            "minter_role_name": "minter"
        },
        "Token_To_Currency_Ratio": 1,
        "Token_desc": "",
        "Token_id": "t1",
        "Token_name": "loyaltok123",
        "Token_type": "fungible"
    }
}]

History

This method returns the token history for a specified token ID.

Ctx.Token.History(tokenId string) (interface{}, error)

Parameters:

• tokenId: string – The ID of the token.

Returns:

• On success, a JSON array that represents the token history.

Return Value Example:

[
    {
        "IsDelete": "false",
        "Timestamp": "2023-09-01T16:46:33Z",
        "TxId": "12333b8a4f63aa9b3a34072efcbd7df546c6d1e7d82a7a9596e899383656d6f7",
        "Value": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "Currency_name1": "",
            "Divisible": {
                "Decimal": 2
            },
            "Mintable": {
                "Max_mint_quantity": 1000
            },
            "Roles": {
                "minter_role_name": "minter"
            },
            "Token_desc": "updated description",
            "Token_id": "token",
            "Token_name": "fiatmoneytok",
            "Token_to_currency_ratio": 0,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    },
    {
        "IsDelete": "false",
        "Timestamp": "2023-09-01T16:04:25Z",
        "TxId": "99702e2dad7554a5ee4716a0d01d3e394cbce39bea8bade265d8911f30ebad0b",
        "Value": {
            "AssetType": "otoken",
            "Behavior": [
                "divisible",
                "mintable",
                "transferable",
                "burnable",
                "roles"
            ],
            "Currency_name1": "",
            "Divisible": {
                "Decimal": 2
            },
            "Mintable": {
                "Max_mint_quantity": 1000
            },
            "Roles": {
                "minter_role_name": "minter"
            },
            "Token_desc": "",
            "Token_id": "token",
            "Token_name": "fiatmoneytok",
            "Token_to_currency_ratio": 0,
            "Token_type": "fungible",
            "Token_unit": "fractional"
        }
    }
]

Methods for Account Management

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) (string, error)

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, 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.

t.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 account object that was created. On error, a rejection with an error message.

Return Value Example:

{
 "AssetType":"oaccount",
"AccountId":"oaccount~a73085a385bc96c4a45aa2dff032e7dede82c0664dee5f396b7c5854eeafd4bd",
   "UserId":"user1",
   "OrgId":"Org1MSP",
   "BapAccountVersion": 0,
   "AccountType":"fungible",
   "TokenId":"",
   "TokenName":"",
   "Balance":0,
   "BalanceOnHold":0
}

AssociateToken

This method associates a fungible token with an account. This method can be called only by a Token Admin of the chaincode.

t.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.

Return Value Example:

{ 
"AssetType":"oaccount", 
"AccountId":"oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb", 
"BapAccountVersion": 0,
"UserId":"admin", 
"OrgId":"Org1MSP", 
"AccountType":"fungible", 
"TokenId":"token1", 
"TokenName":"loyaltok", 
"Balance":0, 
"BalanceOnHold":0 
}

GetAccountWithStatus

This method returns account details for a specified account, including account status.

Ctx.Account.GetAccountWithStatus(account_id string) (interface{}, error)

Parameters:

• account_id: string – The ID of the account.

Returns:

• On success, the requested account details. On error, a rejection with an error message.

Return Value Example:

{
  "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
  "AssetType": "oaccount",
  "Balance": 95,
  "BalanceOnHold": 0,
  "BapAccountVersion": 8,
  "OrgId": "appdev",
  "Status": "active",
  "TokenId": "obp1",
  "TokenName": "obptok",
  "TokenType": "fungible",
  "UserId": "idcqa"
}

GetAccount

This method returns account details for a specified account.

Ctx.Account.GetAccount(account_id string) (Account, error)

Parameters:

• account_id: string – The ID of the account.

Returns:

• On success, the requested account details. On error, a rejection with an error message.

Return Value Example:

{
    "AssetType": "oaccount",
    "BapAccountVersion": 0,
    "AccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "UserId": "user1",
    "OrgId": "Org1MSP",
    "TokenId": "digiCurr101",
    "TokenName": "digicur",
    "Balance": 0,
    "BalanceOnHold": 0
}

GetAccountHistory

This method returns an array of the account history details for a specified account.

Ctx.Account.History(account_id string) ([]interface{}, error)

Parameters:

• account_id: string – The ID of the account.

Returns:

• On success, a map[string]interface{} array that contains the account history details. The account data is shown under the Value key in the map. On error, a non-nil error object containing an error message. The return value is the same as the "GetAccountHistory" method.

Return Value Example:

[
  {
      "IsDelete": "false",
      "Timestamp": "2023-08-28T19:31:15Z",
      "TxId": "adde470a63860ec1013bd5c5987e8a506a48942a91b0f39fc8e561374042bd27",
      "Value": {
          "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
          "AssetType": "oaccount",
          "Balance": 100,
          "BalanceOnHold": 0,
          "BapAccountVersion": 1,
          "OrgId": "Org1MSP",
          "TokenId": "t1",
          "TokenName": "obptok",
          "TokenType": "fungible",
          "UserId": "idcqa"
      }
  },
  {
      "IsDelete": "false",
      "Timestamp": "2023-08-28T19:30:23Z",
      "TxId": "8fbeda2ba60ba175091faae5ae369247775f2cba45c4d6d1ead6f0b05be84743",
      "Value": {
          "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
          "AssetType": "oaccount",
          "Balance": 0,
          "BalanceOnHold": 0,
          "BapAccountVersion": 0,
          "OrgId": "Org1MSP",
          "TokenId": "t1",
          "TokenName": "obptok",
          "TokenType": "fungible",
          "UserId": "idcqa"
      }
  },
  {
      "IsDelete": "false",
      "Timestamp": "2023-08-28T19:29:54Z",
      "TxId": "19bb296ae71709e91b097ba5d9ebd7f7522095880382fbf5913334a46a6026aa",
      "Value": {
          "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
          "AssetType": "oaccount",
          "Balance": 0,
          "BalanceOnHold": 0,
          "BapAccountVersion": 0,
          "OrgId": "Org1MSP",
          "TokenId": "",
          "TokenName": "",
          "TokenType": "fungible",
          "UserId": "idcqa"
      }
  }
]

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 object with the current on-hold balance and a success message. On error, a non-nil error object containing 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.func (t *Controller) GetAllAccounts() (interface{}, error)

Parameters:

• none

Returns:

• On success, a JSON array that lists all accounts.

Return Value Example:

"payload": [
    {
        "key": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
        "valueJson": {
            "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
            "AssetType": "oaccount",
            "Balance": 100,
            "BalanceOnHold": 0,
            "BapAccountVersion": 1,
            "OrgId": "appdev",
            "TokenId": "t1",
            "TokenName": "obptok",
            "TokenType": "fungible",
            "UserId": "idcqa"
        }
    }
]

GetUserByAccountId

This method returns the user details for a specified account.

Ctx.Account.GetUserByAccountById(account_id string) (interface{}, error)

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 non-nil error object containing an error message.

Return Value Example:

{
   "org_id":"Org1MSP",
   "token_id":"digiCurr101",
   "user_id":"user1"
}

GetAccountBalance

This method returns the account balance for a specified account.

Ctx.GetAccountBalance(token_id string, org_id string, user_id string) (interface{}, error)

Parameters:

• account_id: string – The ID of the account.

Returns:

• On success, an interface with a message string and the current balance. On error, a non-nil error object containing an error message.

Return Value Example:

{
    "msg": "Current Balance of +p2uaMTsU9D74l9XpHQ2c55ic/2gbO4NZITC4Zq4P8E= 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) (interface{}, error)

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": {
            "AccountId": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
            "AssetType": "oaccount",
            "Balance": 0,
            "BalanceOnHold": 0,
            "BapAccountVersion": 0,
            "OrgId": "appdev",
            "TokenId": "token",
            "TokenName": "fiatmoneytok",
            "TokenType": "fungible",
            "UserId": "idcqa"
        }
    },
    {
        "key": "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850",
        "valueJson": {
            "AccountId": "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850",
            "AssetType": "oaccount",
            "Balance": 0,
            "BalanceOnHold": 0,
            "BapAccountVersion": 0,
            "OrgId": "appdev",
            "TokenId": "token",
            "TokenName": "fiatmoneytok",
            "TokenType": "fungible",
            "UserId": "example_minter"
        }
    }
]

Methods for Role Management

AddRoleMember

This method adds a role to a specified user and token.

Ctx.Token.AddRoleMember(role string, account_id string, tokenAsset interface{}) (interface{}, error)

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.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, it returns a map with a success message indicating the addition of the role to the account.. On error, a non-nil error object containing 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, tokenAsset interface{}) (interface{}, error)

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.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, it returns a map with a success message indicating the removal of the role from the account.. On error, a non-nil error object containing 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, user_role string) (interface{}, error)

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. On error, a non-nil error object containing an error message.

Return Value Example:

{"accounts":["oaccount~obptok~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f"]}

GetUsersByRole

This method returns a list of all users for a specified role and token.

Ctx.Role.GetUsersByRole(token_id string, user_role string) (interface{}, error)

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 user objects. On error, a non-nil error object containing 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, tokenAsset interface{}) (bool, error)

Parameters:

• role: string – The name of the role to check.
• account_id: number – The account ID to check.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, it returns a map with a success message indicating the removal of the role from the account.. On error, a non-nil error object containing an error message.

Return Value Example:

{
    "result": false
}

RoleCheck

This method checks if the provided account ID is a member of any role.

Ctx.Token.RoleCheck(account_id string, tokenAsset interface{}) (bool, error)

Parameters:

• account_id: string – The account ID to check.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• If the specified account has any role, a success message and the Boolean value true. Otherwise, the Boolean value false. On error, a non-nil error object containing an error message.

Return Value Example:

{ result: true }

GetOrgUsersByRole

This method returns information about all users that have a specified role in a specified organization.

Ctx.Role.GetOrgUsersByRole(token_id string, user_role string, org_id string) (interface{}, error)

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": [
        {
            "org_id": "Org1MSP",
            "token_id": "token",
            "user_id": "admin"
        },
        {
            "org_id": "Org1MSP",
            "token_id": "token",
            "user_id": "orgAdmin"
        }
    ]
}

GetOrgAccountsByRole

This method returns information about all accounts that have a specified role in a specified organization.

Ctx.Role.GetOrgAccountsByRole(token_id string, user_role string, org_id string) (interface{}, error)

Parameters:

• token_id: string – The ID of the token.
• role: string – The name of the role to check for.
• org_id: string – The membership service provider (MSP) ID of the organization.

Returns:

• On success, a list of all accounts with the specified role in the specified organization.

Return Value Example:

{
    "accounts": [
        "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
         "oaccount~9c650574af9025a6106c8d12a801b079eda9ae2e3399fc2fbd5bd683d738a850"
    ]
}

Methods for Transaction History Management

GetAccountTransactionHistory

This method returns an array of the transaction history details for a specified account.

Ctx.Account.GetAccountTransactionHistory(account_id string) (interface{}, error)

Parameters:

• account_id: string – The ID of the account.

Returns:

• The return value is the same as the "GetAccountTransactionHistory" method.
• On success, an array of JSON account transaction objects.
• On error, a non-nil error object containing an error message.

Return Value Example:

[
  {
      "NumberOfSubTransactions": 2,
      "balance": 160,
      "onhold_balance": 0,
      "timestamp": "2023-09-06T06:51:48Z",
      "token_id": "t1",
      "transacted_amount": 20,
      "transaction_id": "otransaction~bd3e8d7d0bcdbed0469a2fccfe95f7ebbeb1987d8385bccf5c84bf80251e748c",
      "transaction_type": "BULKTRANSFER"
  },
  {
      "balance": 180,
      "onhold_balance": 0,
      "timestamp": "2023-09-06T06:47:14Z",
      "token_id": "t1",
      "transacted_account": "oaccount~692a7465c01e36b694cb8ae86e6c6584240aa1f865fde54f95f32429eadd4097",
      "transacted_amount": 10,
      "transaction_id": "otransaction~250996f1df6a36a1b647f522efcaaf48fd70452d711c247fc4cd475b8e752b08",
      "transaction_type": "DEBIT"
  },
  {
      "balance": 190,
      "onhold_balance": 0,
      "timestamp": "2023-09-06T06:47:08Z",
      "token_id": "t1",
      "transacted_account": "oaccount~bb5a0b57d895327c8a8cd1f267310cbf3ae542bc854fab8188b5083a969d72fb",
      "transacted_amount": 10,
      "transaction_id": "otransaction~664325a25ae6b19b23693c66f83811184e0a78fabb49122359a2dbf209f32976",
      "transaction_type": "DEBIT"
  },
  {
      "balance": 200,
      "onhold_balance": 0,
      "timestamp": "2023-09-06T06:46:46Z",
      "token_id": "t1",
      "transacted_account": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
      "transacted_amount": 100,
      "transaction_id": "otransaction~7f49564b1eb61d4c8be0ef61cd5e635b533ca533907944e4ec500f390237fd6b",
      "transaction_type": "MINT"
  },
  {
      "balance": 100,
      "onhold_balance": 0,
      "timestamp": "2023-08-28T19:31:15Z",
      "token_id": "t1",
      "transacted_account": "oaccount~2de8db6b91964f8c9009136831126d3cfa94e1d00c4285c1ea3e6d1f36479ed4",
      "transacted_amount": 100,
      "transaction_id": "otransaction~adde470a63860ec1013bd5c5987e8a506a48942a91b0f39fc8e561374042bd27",
      "transaction_type": "MINT"
  }
]

GetAccountTransactionHistoryWithFilters

This method returns an array of the transaction history details for a specified transaction. This method can only be called when connected to the remote Oracle Blockchain Platform network.

t.Ctx.Account.GetAccountTransactionHistoryWithFilters (transaction_id: string, filters?: SubTransactionFilters)

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.

Example:

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

[
    {
        "balance": 90,
        "onhold_balance": 0,
        "timestamp": "2022-04-20T19:43:36Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~7a4d67118e623a876b77c67e76b819269a8d4a509aece5d2263fb274a9beb3b8",
        "transacted_amount": 5,
        "transaction_id": "otransaction~dd9986d3686e52264935558e42026fbf8a9af48b06a3256a58b453f5ada4e636",
        "transaction_type": "DEBIT"
    },
    {
        "balance": 95,
        "onhold_balance": 0,
        "timestamp": "2022-04-20T19:43:22Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~0642308fc4c514c257ebf04326c63f990e2531bfd59d0b952056094da61e04ab",
        "transacted_amount": 5,
        "transaction_id": "otransaction~5e53424de3d691cf6b2a55ea3dc478c555d8784111c11847e594194d6c2e7755",
        "transaction_type": "DEBIT"
    },
    {
        "balance": 100,
        "onhold_balance": 0,
        "timestamp": "2022-04-20T19:42:54Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~b63935592a702d30bedb87ae97b9b1ba7d0f346716adc4f5a4192220bf410d4e",
        "transacted_amount": 100,
        "transaction_id": "otransaction~94c467825ce9f66cc69958d38b169022a69eebc66b75b7d6e0b0585af2c3c228",
        "transaction_type": "MINT"
    }
]

GetSubTransactionsById

This method returns an array of the transaction history details for a specified transaction.

t.Ctx.Account.GetSubTransactionsById(transaction_id string)

Parameters:

• transaction_id: string – The ID of the transaction.

Example:

ochain invoke GetSubTransactionsById 'otransaction~21972b4d206bd52ea77924efb259c67217edb23b4386580d1bee696f6f864b9b'

[
    {
        "balance": 80,
        "onhold_balance": 0,
        "timestamp": "2022-04-21T05:02:33Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~7a4d67118e623a876b77c67e76b819269a8d4a509aece5d2263fb274a9beb3b8",
        "transacted_amount": 5,
        "transaction_id": "otransaction~33de5d63058d5e9abc011bc850878dfb7ac3080495729aed345c45b2f21735fa~c81e728d9d4c2f636f067f89cc14862c",
        "transaction_type": "DEBIT"
    },
    {
        "balance": 85,
        "onhold_balance": 0,
        "timestamp": "2022-04-21T05:02:33Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~0642308fc4c514c257ebf04326c63f990e2531bfd59d0b952056094da61e04ab",
        "transacted_amount": 5,
        "transaction_id": "otransaction~33de5d63058d5e9abc011bc850878dfb7ac3080495729aed345c45b2f21735fa~c4ca4238a0b923820dcc509a6f75849b",
        "transaction_type": "DEBIT"
    }
]

GetSubTransactionsByIdWithFilters

This method returns an array of the transaction history details for a specified transaction.

t.Ctx.Account.GetSubTransactionsByIdWithFilters(transaction_id string, filters ...SubTransactionFilters)

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.

Example:

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

[
    {
        "balance": 80,
        "onhold_balance": 0,
        "timestamp": "2022-04-21T05:02:33Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~7a4d67118e623a876b77c67e76b819269a8d4a509aece5d2263fb274a9beb3b8",
        "transacted_amount": 5,
        "transaction_id": "otransaction~33de5d63058d5e9abc011bc850878dfb7ac3080495729aed345c45b2f21735fa~c81e728d9d4c2f636f067f89cc14862c",
        "transaction_type": "DEBIT"
    },
    {
        "balance": 85,
        "onhold_balance": 0,
        "timestamp": "2022-04-21T05:02:33Z",
        "token_id": "tokenId",
        "transacted_account": "oaccount~0642308fc4c514c257ebf04326c63f990e2531bfd59d0b952056094da61e04ab",
        "transacted_amount": 5,
        "transaction_id": "otransaction~33de5d63058d5e9abc011bc850878dfb7ac3080495729aed345c45b2f21735fa~c4ca4238a0b923820dcc509a6f75849b",
        "transaction_type": "DEBIT"
    }
]

GetTransactionById

This method returns the history of a Transaction asset.

t.Ctx.Transaction.GetTransactionById(transaction_id string)

Parameters:

• transaction_id string – The ID of the transaction asset.

Return Value Example:

{
    "history": [
        {
            "IsDelete": "false",
            "Timestamp": "2021-08-16 20:19:05.028 +0530 IST",
            "TxId": "67042154a6853011d111b13f73943f06d2a6ae3cfb9a84cb104482c359eb2220",
            "Value": {
                "Amount": 3,
                "AssetType": "otransaction",
                "FromAccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                "HoldingId": "ohold~digicur~digiCurr101~op2",
                "NumberOfSubTransactions": 0,
                "Timestamp": "2021-08-16T20:19:05+05:30",
                "ToAccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
                "TokenId": "digiCurr101",
                "TransactionId": "otransaction~67042154a6853011d111b13f73943f06d2a6ae3cfb9a84cb104482c359eb2220",
                "TransactionType": "RELEASEHOLD"
            }
        }
    ],
    "transaction_id": "otransaction~67042154a6853011d111b13f73943f06d2a6ae3cfb9a84cb104482c359eb2220"
}

DeleteHistoricalTransactions

This method deletes older transactions from the state database.

func (t *Controller) DeleteHistoricalTransactions(timestamp string) (interface{}, error)

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:2021-08-18T05:43:30Z",
    "transactions": [
        "otransaction~57d81f681aa215bb73d6c017d16be8b283d3fcb50051c85891a97d1d407fc342"
    ]
}

Methods for Token Behavior Management - Mintable Behavior

Mint

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.

Ctx.Token.Mint(quantity float64, tokenAsset interface{}) (interface{}, error)

Parameters:

• quantity: number – The number of tokens to mint.
• tokenAsset – The reference to the token asset to mint.

Returns:

• On success, a success message. On error, a non-nil error object containing 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(tokenAsset interface{}) (map[string]interface{}, error)

Parameters:

• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message and a map of total minted tokens in the number data type. On error, a non-nil error object containing an error message.

Return Value Example:

{"msg":"total minted amount for token with id digiCurr101 is 0","quantity":0}

GetNetTokens

This method returns the net quantity of tokens that are available in the system for a specified token. 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(tokenAsset interface{}) (map[string]interface{}, error)

Parameters:

• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message and a map of the net quantity of tokens in the number data type. On error, an error message.

Return Value Example:

{"msg":"net minted amount for token with id digiCurr101 is 0","quantity":0}

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_id string) (float64, error)

Parameters:

• token_id: string – The token ID to check.

Returns:

• On success, the maximum mintable quantity of the token, in the number data type. On error, a non-nil error object containing an error message.

Return Value Example:

20000

Methods for Token Behavior Management - Transferable Behavior

Transfer

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.

Ctx.Token.Transfer(to_account_id string, quantity float64, tokenAsset interface{}) (interface{}, error)

Parameters:

• to_account_id: string – The account ID to receive the tokens.
• quantity: number – The total number of tokens to transfer.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message. On error, a non-nil error object containing an error message. The return value is the same as the "TransferTokens" method.

Return Value Example:

{     "msg":"Successfully transferred 50 tokens from account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP,  User-Id: admin) to account id: oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (Org-Id: Org1MSP, User-Id: user1)"
}

BulkTransfer

This method is used to perform bulk transfer of tokens from the caller account to the accounts that are specified in the flow object. The caller of this method must have an account already created.

Ctx.Token.BulkTransfer(flow []map[string]interface{}, tokenAsset interface{}) (interface{}, error)

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

• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message that includes the number of tokens transferred. On error, a non-nil error object containing an error message.

Return Value Example:

{
    "from_account_id": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "msg": "Successfully transferred 2 tokens from Account Id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (Org-Id: Org1MSP, User-Id: user1)",
    "sub_transactions": [
        {
            "amount": 1,
            "to_account_id": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e"
        },
        {
            "amount": 1,
            "to_account_id": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df"
        }
    ]
}

Methods for Token Behavior Management - Holdable Behavior

Hold

This method creates a hold on behalf of the owner of the tokens with the to_account_id account. A notary account is specified, which is responsible to either complete or release the hold. When the hold is created, the specified token balance from the payer is put on hold. A held balance cannot be transferred until the hold is either completed or released. The caller of this method must have an account already created.

Ctx.Token.Hold(operation_id string, to_account_id string, notary_account_id string, quantity float64, TimeToExpiration string, tokenAsset)) (interface{}, error)

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.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message. On error, a non-nil error object containing 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.

Ctx.Token.ExecuteHold(operation_id string, quantity float64, tokenAsset interface{}) (interface{}, error)

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 put on hold.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message. On error, a non-nil error object containing an error message.

Return Value Example:

{"msg":"Account Id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1) has successfully executed '1' tokens(digiCurr101) from the hold with Operation Id 'op1'"}

ReleaseHold

This method releases a hold on tokens. The transfer is not completed and all held tokens are available again to the original owner. This method can be called by the Account Owner ID with the notary role within the specified time limit or by the payer, payee, or notary after the specified time limit.

Ctx.Token.ReleaseHold(operation_id string, tokenAsset interface{}) (interface{}, error)

Parameters:

• operation_id: string – A unique ID to identify the hold operation. Typically this ID is passed by the client application.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message. On error, a non-nil error object containing an error message.

Return Value Example:

{"msg":"Successfully released '3' tokens from Operation Id 'op2' to Account Id oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f (org_id : Org1MSP, user_id : user1)"}

GetOnHoldIds

This method returns a list of all the holding IDs for a specified user and token.

Ctx.Account.GetOnHoldIDs(account_id string) (map[string]interface{}, error)

Parameters:

• token_id – The ID of the token.
• org_id – The membership service provider (MSP) ID of the user in the current network organization.
• user_id – The user name or email ID of the user.

Returns:

• On success, a JSON object with the list of holding IDs. A holding ID is formed by concatenating the asset type (ohold), the token name, the token ID, and the operation ID.

Return Value Example:

{"holding_ids":["ohold~loyaltok123~t1~op1"],"msg":"Holding Ids are: [ohold~loyaltok123~t1~op1]"}

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) (Hold, error)

Parameters:

• token_id: string – The ID of the token.
• operation_id: string – A unique ID that identifies the hold operation. Typically this ID is passed by the client application.

Returns:

• The return value is the same as the "GetOnHoldDetailsWithOperationId" method.
• On success, a promise object that includes the on-hold transaction details for the specified operation ID and token. The hold object 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 non-nil error object containing an error message.

Return Value Example:

{
    "AssetType": "ohold",
    "HoldingId": "ohold~digicur~digiCurr101~op1",
    "OperationId": "op1",
    "TokenName": "digicur",
    "FromAccountId": "oaccount~digicur~b4f45440aa2a7942db64443d047027e9d714d62cba5c3d546d64f368642f622f",
    "ToAccountId": "oaccount~digicur~38848e87296d67c8a90918f78cf55f9c9baab2cdc8c928535471aaa1210c706e",
    "NotaryAccountId": "oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df",
    "TokenId": "digiCurr101",
    "Quantity": 2,
    "TimeToExpiration": "0"
}

GetOnHoldBalanceWithOperationID

This method returns the on-hold balance for a specified operation ID and token..

Ctx.Hold.GetOnHoldBalanceWithOperationID(token_id string, operation_id string) (map[string]interface{}, error)

Parameters:

• token_id: string – The ID of the token.
• operation_id: string – A unique ID that identifies the hold operation. Typically this ID is passed by the client application.

Returns:

• On success, the on-hold balance of the specified operation ID and token. On error, a non-nil error object containing an error message.

Return Value Example:

{
    "holding_balance": 10,
    "msg": "Current Holding Balance of OperationId opr_121 for token digiCurr101 is : 10"
}

Methods for Token Behavior Management - Burnable Behavior

Burn

This method deactivates, or burns, tokens from the transaction caller's account. The caller of this method must have an account and the burner role. The quantity must be within the decimal values specified by the decimal parameter of the divisible behavior in the specification file.

Ctx.Token.Burn(quantity float64 , tokenAsset interface{}) (interface{}, error)

Parameters:

• quantity: number – The total number of tokens to burn.
• tokenAsset – The tokenAsset argument contains the reference of the token data to operate on.

Returns:

• On success, a success message. On error, a non-nil error object containing an error message.

Return Value Example:

{
 "msg":"Successfully burned 10 tokens from account id: oaccount~digicur~682bb71de419602af74e3f226345ae308445ca51010737900c1d85f0376152df (Org-Id: Org1MSP, User-Id: admin)"
}