ERC-20 Token Contract APIs

You can use the following methods related to token functionality in ERC-20 token contracts.

Token Configuration Methods

__ERC20Token_init

This method is called when a token contract is deployed. This method can be called only by a Token Admin.

Parameters:

• name: string – The name of the token.
• symbol: string – The symbol of the token.

initializeERC20Token

This method initializes an ERC-20 token. This method can be called only by a Token Admin.

Parameters:

• token: ERC20Token – The structure defining the ERC-20 token, as shown in the following example.

  {
      "tokenId": "WCBDC-100",
      "tokenName": "wholesale cbdc",
      "tokenDesc": "this is wcbdc contract",
      "tokenStandard": "ttf+",
      "tokenType": "fungible",
      "tokenUnit": "fractional",
      "behaviors": ["mintable", "burnable", "transferable", "roles", "holdable", "pausable"],
      "decimals": 2,
      "mintable": { "maxMintQuantity": 1000000, "mintApprovalRequired": false },
      "burnable": { "burnApprovalRequired": false }
  }

getToken

This method gets an ERC-20 token. This method can be called only by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

Parameters:

• None

Return Value Example:

{
    "tokenId": "WCBDC-100",
    "tokenName": "wholesale cbdc",
    "tokenDesc": "this is wcbdc contract",
    "tokenStandard": "ttf+",
    "tokenType": "fungible",
    "tokenUnit": "fractional",
    "behaviors": ["mintable", "burnable", "transferable", "roles", "holdable", "pausable"],
    "decimals": 2,
    "mintable": { "maxMintQuantity": 1000000, "mintApprovalRequired": false },
    "burnable": { "burnApprovalRequired": false }
}

decimals

This method returns the number of decimals places that were configured for a token. This method can be called only by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

Parameters:

• None

Returns:

• A uint8 value indicating the number of decimal places.

cap

This method returns the cap value (the maximum total supply) for an ERC-20 token. This method can be called only by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

Parameters:

• None

Returns:

• A uint256 value indicating the cap value.

balanceOf

This method returns the current token balance for a specified user. This method can be called only by a Token Admin or Token Auditor, or the Org Admin or Org Auditor of the specified organization.

Parameters:

• userAddress: string – The wallet address of the user, which must not be zero.

Returns:

• A uint256 value indicating the current balance.

Token Behavior Methods - Mintable Behavior

mint

This method mints ERC-20 tokens. This method can be called by any user with the minter role.

Parameters:

• to: string – The wallet address of the user the tokens are being minted for, which must not be zero.
• value: uint256 – The quantity of tokens to mint.

requestMint

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

Parameters:

• notary: string – The wallet address of the notary user, which must not be zero.
• amount: uint256 – The quantity of tokens to mint.
• expiration: uint256 – The expiration time of the request in epoch format.
• opId: string – The operation ID of the request.
• info_details: JSON – An object specifying the category (category) and description (description) of the request.

  You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

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

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

approveMint

This method can be called by an approver with the notary role to approve a mint request for ERC-20 tokens.

Parameters:

• opId: string – The operation ID of the mint request.

rejectMint

This method can be called by an approver with the notary role to reject a mint request for ERC-20 tokens.

Parameters:

• opId: string – The operation ID of the mint request.

Token Behavior Methods - Burnable Behavior

burn

This method burns ERC-20 tokens. This method can be called by any user with the burner role.

Parameters:

• account: string – The wallet address of the user the tokens are being burned for, which must not be zero.
• value: uint256 – The quantity of tokens to burn.

burnFrom

This method can be called by any user with a delegated allowance.

Parameters:

• account: string – The wallet address of the account to burn tokens from, which must not be zero.
• value: uint256 – The quantity of tokens to burn.

requestBurn

This method can be called by any user with a burner role to approve a burn request for ERC-20 tokens.

Parameters:

• notary: string – The wallet address of the notary user, which must not be zero.
• amount: uint256 – The quantity of tokens to burn.
• expiration: uint256 – The expiration time of the request in epoch format.
• opId: string – The operation ID of the request.
• info_details: JSON – An object specifying the category (category) and description (description) of the request.

  You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

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

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

approveBurn

This method can be called by an approver with the notary role to approve a burn request for ERC-20 tokens.

Parameters:

• opId: string – The operation ID of the burn request.

rejectBurn

This method can be called by an approver with the notary role to reject a burn request for ERC-20 tokens.

Parameters:

• opId: string – The operation ID of the burn request.

Token Behavior Methods - Transferable Behavior

transfer

This method can be called by any user with tokens to transfer them to another user.

Parameters:

• to: string – The wallet address of the receiver, which must not be zero.
• value: uint256 – The quantity of tokens to transfer.

batchTransfer

This method can be called by any user with tokens to transfer them in batches to other users.

Parameters:

• toList: string[] – A list of wallet addresses of the receivers.
• amounts: uint256[] – A list of the quantity of tokens to transfer.

Token Behavior Methods - Delegable Behavior

allowance

This method can be called by any user who owns tokens to delegate another user to spend them.

Parameters:

• owner: string – The wallet address of the token owner, which must not be zero.
• spender: string – The wallet address of the token spender, which must not be zero.

Returns:

• A uint256 value of the amount of tokens delegated to be spent.

approve

This method can be called by any user who owns tokens to set the amount that a delegated spender can spend.

Parameters:

• spender: string – The wallet address of the token spender, which must not be zero.
• value: uint256 – The amount of tokens that the spender is allowed to spend.

transferFrom

This method can be called by a user with a delegated allowance to transfer tokens to another user.

Parameters:

• from: string – The wallet address of the sender, which must not be zero.
• to: string – The wallet address of the receiver, which must not be zero.
• value: uint256 – The quantity of tokens to transfer.

Token Behavior Methods - Pausable Behavior

paused

This method checks whether a contract is paused. This method can be called only by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

Parameters:

• None

pause

This method pauses a contract. This method can be called only by a Token Admin.

Parameters:

• None

unpause

This method starts a paused contract. This method can be called only by a Token Admin.

Parameters:

• None

Token Behavior Methods - Holdable Behavior

hold

This method can be called by any user with tokens to request a token transfer.

Parameters:

• to: string – The wallet address of the receiver, which must not be zero.
• notary: string – The wallet address of the notary user, which must not be zero.
• amount: uint256 – The quantity of tokens to transfer.
• expiration: uint256 – The expiration time of the request in epoch format.
• opId: string – The operation ID of the request.
• holdType: string – The type of hold. For example, transfer.
• info_details: JSON – An object specifying the category (category) and description (description) of the request.

  You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

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

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

holdFrom

This method can be called by a delegated user with an allowance to hold tokens from another user's wallet address. This method requires the delegable behavior.

Parameters:

• fromAccount: string – The wallet address of the user whose tokens will be held, which must not be zero.
• toAccount: string – The wallet address of the receiver, which must not be zero.
• notary: string – The wallet address of the notary user, which must not be zero.
• amount: uint256 – The quantity of tokens to transfer.
• expiration: uint256 – The expiration time of the request in epoch format.
• opId: string – The operation ID of the request.
• holdType: string – The type of hold. For example, transfer.
• info_details: JSON – An object specifying the category (category) and description (description) of the request.

  You specify the info_details parameter in a different format if you are using Visual Studio Code versus the CLI or a Postman collection.

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

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

executeHold

This method can be called by an approver with the notary role to approve a hold request.

Parameters:

• amount: uint256 – The quantity of tokens to approve for transfer.
• opId: string – The operation ID of the hold request.

releaseHold

This method can be called by an approver with the notary role to reject a hold request.

Parameters:

• opId: string – The operation ID of the hold request.

updateNotary

This method can be called by an approver with the notary role to update the notary for a specified request.

Parameters:

• opId: string – The operation ID of the hold request.
• newNotary: string – The wallet address of the new notary user, which must not be zero.

getOnHoldBalanceWithOperationId

This method gets the hold balance for a specified operation ID. This method can be called only by a Token Admin or Token Auditor, Org Admin or Org Auditor of the specified organization, or by a transaction participant (sender, recipient, notary).

Parameters:

• opId: string – The operation ID of the hold request.

Returns:

• A uint256 value of the hold balance.

getOnHoldDetailsWithOperationId

This method gets the hold details for a specified operation ID. This method can be called only by a Token Admin or Token Auditor, Org Admin or Org Auditor of the specified organization, or by a transaction participant (sender, recipient, notary).

Parameters:

• opId: string – The operation ID of the hold request.

Returns:

• A hold object, with the following information.
  • to: address – The wallet address of the receiver.
  • notary: address – The wallet address of the notary.
  • amount: uint256 – The quantity of tokens to be transferred.
  • expiration: uint256 – The expiration time for the request, in epoch format.
  • opId: string – The operation ID of the request.
  • holdType: string – The hold type; for example, transfer.
  • info: infoDetails – An object specifying the category (category) and description (description) of the request.

getAccountOnHoldBalance

This method gets the hold balance for a specified account. This method can be called only by a Token Admin or Token Auditor, Org Admin or Org Auditor of the specified organization, or by a transaction participant (sender, recipient, notary).

Parameters:

• account: string – The wallet address of the account to check, which must not be zero.

Returns:

• A uint256 value of the hold balance.

Token Behavior Methods - Multi-Level Approval Behavior

createOrupdateAccountPolicy

This method can be called by a Token Admin or Org Admin to create or update a policy for a specified account.

Parameters:

• accountPolicyId – The system generates this ID from the specified orgId and userId fields. You do not provide this field manually.
• orgId – The membership service provider (MSP) ID of the user to create the policy for.
• userId – The user name or email ID of the user to create the policy for.
• kycCompliance – A string value (true or false) that indicates whether the account satisfies KYC (Know Your Customer) requirements.
• amlCompliance – A string value (true or false) that indicates whether the account satisfies AML (Anti-Money Laundering) requirements.
• riskScore – The risk score associated with the account, which is used for compliance evaluation.
• restrictionFlag – A string value (true or false) that indicates whether the account is subject to restricted transfers. If set to true, direct transfers follow the transfer restriction bucket limits and hold transfers follow the lowest approval-policy threshold.

getAccountPolicyById

This method gets account policy details for a specified policy ID. This method can be called by a Token Admin or Token Auditor, or Org Admin or Org Auditor of the organization whose account policy will be fetched.

Parameters:

• accountPolicyId: string – The unique account policy ID.

Returns:

• accountPolicyId – The system generates this ID from the specified orgId and userId fields. You do not provide this field manually.
• orgId – The membership service provider (MSP) ID of the user.
• userId – The user name or email ID of the user.
• kycCompliance – A string value (true or false) that indicates whether the account satisfies KYC (Know Your Customer) requirements.
• amlCompliance – A string value (true or false) that indicates whether the account satisfies AML (Anti-Money Laundering) requirements.
• riskScore – The risk score associated with the account, which is used for compliance evaluation.
• restrictionFlag – A string value (true or false) that indicates whether the account is subject to restricted transfers. If set to true, direct transfers follow the transfer restriction bucket limits and hold transfers follow the lowest approval-policy threshold.

getAccountPolicyById

This method gets account policy details for a specified user. This method can be called by any user.

Parameters:

• who: address – The wallet address of the user.

Returns:

• The accountPolicyId string.

deleteAccountPolicyById

This method deletes a policy for a specified policy ID. This method can be called by a Token Admin, or Org Admin of the organization that includes the user whose account policy will be deleted.

Parameters:

• accountPolicyId – The unique account policy ID.

Returns:

• The accountPolicyId string.

createOrupdateApprovalPolicy

This method can be called by a Token Admin.

Parameters:

• approvalPolicyId – The system generates this ID. You do not provide this field manually.
• transactionLowerLimit – The minimum transaction amount the approval policy applies to.
• transactionUpperLimit – The maximum transaction amount the approval policy applies to.
• numberOfApprovalsRequired – The total number of approvals needed before the transaction can be completed.
• approverDetails – A list of approvers along with their assigned approval sequence, which defines the mandatory order for approvals.
• version – The approval policy version. Use 0 when creating a fresh policy.
• status – Active or inactive.

getApprovalPolicyById

This method gets approval policy details for a specified policy ID. This method can be called by a Token Admin or Token Auditor.

Parameters:

• approvalPolicyId: string – The unique approval policy ID.

Returns:

• approvalPolicyId – The system generates this ID.
• transactionLowerLimit – The minimum transaction amount the approval policy applies to.
• transactionUpperLimit – The maximum transaction amount the approval policy applies to.
• numberOfApprovalsRequired – The total number of approvals needed before the transaction can be completed.
• approverDetails – A list of approvers along with their assigned approval sequence, which defines the mandatory order for approvals.
• version – The approval policy version.
• status – Active or inactive.

deleteApprovalPolicy

This method deletes a policy for a specified policy ID. This method can be called by a Token Admin.

Parameters:

• approvalPolicyId: string – The unique approval policy ID.

getApprovalTransactionsById

This method gets the on-hold balance for a specified account. This method can be called by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

Parameters:

• opId: string – The operation ID for the hold request.

Returns:

• An approvalTransactions object.

Return Value Example:

{
"approvalTransactionId": "",
"approvalPolicyId": "",
"approvalPolicyVersion": "",
"fromAccount": "",
"toAccount": "",
"totalApprovals": "",
"numberaOfApprovalsRequired": "",
"status": "",
"approverDetails": ""
}

getApprovalStatusByOperationId

This method gets approval details for a specified hold request. This method can be called by a Token Admin, Token Auditor, Org Admin, or Org Auditor.

Parameters:

• opId: string – The operation ID for the hold request.

Return Value Example:

{
"approvalWorkflowExists": "",
"activePolicyFound": "",
"receivedApprovals": "",
"requiredApprovals": "",
"approvalRequirementMet": "",
"nextApprovalSequence": "",
"nextApprover": "",
"workflowStatus": "",
"approvalPolicyId": "",
"approvalPolicyVersion": ""
}

approveTransaction

An approver can use this method to approve a hold transaction.

Parameters:

• opId: string – The operation ID for the hold request.
• amount: uint256 – The amount to approve.

rejectTransaction

A notary can use this method to reject a hold transaction.

Parameters:

• opId: string – The operation ID for the hold request.

getTransferRestriction

This method returns the current transfer restriction configuration, including the lower and upper transaction limits. This method can be called by a Token Admin or Token Auditor.

Parameters:

• account: address – The wallet address of the user to check the on-hold balance for. The address must not be zero.

Returns:

• A transferRestriction object.

Return Value Example:

transactionLowerLimit: 0transactionUpperLimit: 100

setOrupdateTransferRestriction

This method updates the transfer restriction configuration by setting new lower and upper transaction limits. This method can be called by a Token Admin.

Parameters:

• transactionLowerLimit: uint256 – The minimum allowed transaction amount.
• transactionUpperLimit: uint256 – The maximum allowed transaction amount.

Context Management Methods

setTokenContext

This method sets the token contract address for the account contract. This method can be called only by a Token Admin.

Parameters:

• tokenAddress: address – The contract address of the deployed token, which must not be zero.

getTokenContext

This method gets the token contract address for the account contract. This method can be called by any user.

Parameters:

• None

Returns

• The token contract address

setGovernanceContext

This method sets the governance contract to use to manage the governance life cycle for the account contract. This method can be called only by a Token Admin.

Parameters:

• uuid: string – The unique ID set by the digital assets Token Admin before contract deployment.
• governance: address – The contract address of the deployed governance contract, which must not be zero.

getGovernanceContext

This method gets the govnerance context details. This method can be called by any user.

Parameters:

• None

Returns

• A governanceContext object.

Return Value Example:

{
    "governanceUUID": "abc-def",
    "governance": "0x0000000",
	"deploymentActive": "true"
}

isDeploymentActive

This method checks whether the deployment is active. This method can be called by any user.

Parameters:

• None

Returns:

• A Boolean value (true or false) indicating whether the deployment is active.