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

TypeScript Methods for Token Conversion

Blockchain App Builder automatically generates methods that you can use to convert fungible tokens that use the Token Taxonomy Framework standard.

The token conversion methods include the concept of the exchange pool. The exchange pool account is funded by other token accounts. When you mint tokens, you can specify that a percentage of the minted tokens are transferred to the exchange pool account.

Token Conversion Process

A typical flow for converting tokens follows these steps:
  1. Call the initializeExchangePoolUser method to initialize the exchange pool user.
  2. Call the createExchangePoolAccounts method to create exchange pool accounts. Create an exchange pool account for every type of fungible token that you want to convert from or convert to.
  3. Call the addConversionRate method to set the conversion rate for each pair of tokens that you want to convert between.
  4. Fund the exchange pool token accounts in one of the following ways:
    • Transfer tokens to the exchange pool token accounts using the standard transfer methods.
    • Call the mintWithFundingExchangePoolToken method when minting tokens, which can transfer a percentage of minted tokens to an exchange pool account.
  5. Call the tokenConversion method to convert between two fungible tokens. A single user can convert tokens between two of their token accounts, or a pair of users can directly convert tokens from one account to another.
  6. The exchange pool user can view the exchange pool account balances and account transactions.
    • Call the getAccount method to view the balances of each of the exchange pool token accounts.
    • Call the getAccountTransactionHistory and getAccountTransactionHistoryWithFilters methods to view account transactions for each of the exchange pool token accounts.

Automatically Generated Token Conversion Methods

Blockchain App Builder automatically generates methods to convert between different types of fungible tokens. Controller methods must have a @Validator(...params) decorator to be invokable.

initializeExchangePoolUser
This method initializes the exchange pool user, which is a one-time activity. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string())
public async initializeExchangePoolUser(org_id: string, user_id: string){
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.initializeExchangePoolUser', 'TOKEN');
    return await this.Ctx.TokenConvertor.initializeExchangePoolUser(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 exchange pool user.
Return Value Example:
{
    "assetType": "oconversion",
    "convertor_id": "bcb1f3b1442c625d3ce205660c5e717c5858a1fe1e12c325df799a851ceaa09b",
    "org_id": "Org1MSP",
    "user_id": "exchangepooluser"
}
createExchangePoolAccounts
This method creates exchange pool token accounts for a given array of token IDs. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.array().of(yup.string()))
public async createExchangePoolAccounts(token_ids: string[]){
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.initializeExchangePoolUser', 'TOKEN');
    return await this.Ctx.TokenConvertor.createExchangePoolAccounts(token_ids);
}
Parameters:
  • token_ids: string [] – An array of token IDs.
Returns:
  • On success, a list of objects that includes details of the exchange pool accounts that were created.
Return Value Example:
[
  {
    "account_id": "oaccount~cc9d84f6d4a5976532493ef5200c9603e138adc35166ffd5fd1aad9c1647f034",
    "token_id": "USD",
    "status": "created"
  },
  {
    "account_id": "oaccount~3d4933111ec8bd6cc1ebb43f2b2c390deb929cfa534f9c6ada8e63bac04a13c0",
    "token_id": "INR",
    "status": "created"
  }
]
addConversionRate
This method adds a conversion rate for a pair of tokens. The token conversion rate can be specified up to eight decimal places. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string(), yup.number())
public async addConversionRate(from_token_id:string , to_token_id:string, token_conversion_rate: number) {
   await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.addConversionRate', 'TOKEN');
   return await this.Ctx.TokenConvertor.addConversionToken(from_token_id,to_token_id,token_conversion_rate);
}
Parameters:
  • from_token_id: string – The ID of the token to convert from.
  • to_token_id: string – The ID of the token to convert to.
  • token_conversion_rate: number – The rate at which to convert from_token_id token to the to_token_id token.
Returns:
  • On success, a JSON representation of the conversion rate object.
Return Value Example:
{
  "assetType": "oconversionRate",
  "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
  "from_token_id": "USD",
  "to_token_id": "INR",
  "conversion_rate": 10
}
getConversionRate
This method gets the current conversion rate for a pair of tokens. This method can be called by the Token Admin of the chaincode, any Org Admin, and by any token account owner. 
@Validator(yup.string(), yup.string())
public async getConversionRate(from_token_id:string , to_token_id:string) {
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.getConversionRate', 'TOKEN');
    const conversion_rate_id = await this.Ctx.TokenConversionRate.getConversionRateId(from_token_id, to_token_id);
    return await this.Ctx.TokenConversionRate.get(conversion_rate_id);
}
Parameters:
  • from_token_id: string – The ID of the token to convert from.
  • to_token_id: string – The ID of the token to convert to.
Returns:
  • On success, a JSON representation of the conversion rate object.
Return Value Example:
{
  "assetType": "oconversionRate",
  "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
  "from_token_id": "USD",
  "to_token_id": "INR",
  "conversion_rate": 10
}
updateConversionRate
This method updates the current conversion rate for a pair of tokens. The token conversion rate can be specified up to eight decimal places. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string(), yup.number())
public async updateConversionRate(from_token_id:string , to_token_id:string, token_conversion_rate: number) {
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.updateConversionRate', 'TOKEN');
    return await this.Ctx.TokenConvertor.updateTokenConversionRate(from_token_id,to_token_id,token_conversion_rate);
}
Parameters:
  • from_token_id: string – The ID of the token to convert from.
  • to_token_id: string – The ID of the token to convert to.
  • token_conversion_rate: number – The rate at which to convert from_token_id token to the to_token_id token.
Returns:
  • On success, a JSON representation of the updated conversion rate object.
Return Value Example:
{
  "assetType": "oconversionRate",
  "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
  "from_token_id": "USD",
  "to_token_id": "INR",
  "conversion_rate": 20
}
mintWithFundingExchangePool
This method mints tokens in the caller's account based on the specified token ID and quantity. A percentage of tokens from the minted quantity is then transferred to the exchange pool token account.
@Validator(yup.string(), yup.number(), yup.number())
public async mintWithFundingExchangePool(token_id: string, token_quantity: number, percentage_token_to_exchange_pool: number) {
    return await this.Ctx.TokenConvertor.mintWithFundingExchangePool(token_id, token_quantity, percentage_token_to_exchange_pool);
}
Parameters:
  • token_id: string – The ID of the token to mint.
  • token_quantity: number – The total number of tokens to mint.
  • percentage_token_to_exchange_pool: number – The percentage of minted tokens to transfer to the exchange pool token account.
Returns:
  • On success, a message that indicates that minting and funding the exchange pool were successful.
Return Value Example:
{
    "msg": "Successfully minted 100 tokens to Account Id: oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb (Org-Id: Org1MSP, User-Id: admin) and Successfully transfered 20 tokens to exchange pool Account with Account Id: oaccount~cc9d84f6d4a5976532493ef5200c9603e138adc35166ffd5fd1aad9c1647f034 (Org-Id: Org1MSP, User-Id: exchangepooluser) "
}
tokenConversion
This method converts tokens from the caller's account to the account specified by the to_token_id, to_org_id and to_user_id values. This method can be called by the Token Admin of the chaincode and by any token account owner. An exchange pool user cannot call this method. 
@Validator(yup.string(),yup.string(),yup.string(),yup.string(),yup.number())
public async tokenConversion(from_token_id:string, to_token_id:string, to_org_id:string, to_user_id:string, token_quantity:number){
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.tokenConversion', 'TOKEN');
    return await this.Ctx.TokenConvertor.tokenConversion(from_token_id,to_token_id,to_org_id,to_user_id,token_quantity);
}
Parameters:
  • from_token_id: string – The ID of the token to convert from.
  • to_token_id: string – The ID of the token to convert to.
  • to_org_id: string – The membership service provider (MSP) ID of the user in the current organization to receive the tokens.
  • to_user_id: string – The user name or email ID of the user to receive the tokens.
  • token_quantity: number – The total number of tokens to transfer.
Returns:
  • On success, a message that indicates the token conversion was successful.
Return Value Example:
{
    "msg": "Succesfully converted 5 of tokens with tokenId: [USD] from AccountId: oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb (Org-Id: Org1MSP, User-Id: admin) to 100 of tokens with tokenId: [INR] to AccountId: oaccount~25e2e66718b6dbb59aea9c32acebec60e09d912b2578d4933d377ae5d0628f1e (Org-Id: Org1MSP, User-Id: user) as per the conversion rate of 20"
}
getConversionHistory
This method returns the token conversion history for a specified token account. This method can be called by the Token Admin of the chaincode, an Org Admin of the specified organization, or by the token account owner. 
@Validator(yup.string(), yup.string(), yup.string())
  public async getConversionHistory(token_id: string, org_id: string, user_id: string) {
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT.getConversionHistory", "TOKEN", { account_id });
    return await this.Ctx.Account.getTokenConversionHistory(account_id, org_id, user_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 object with conversion history details.
Return Value Example:
[
  {
    "transaction_id": "otransaction~34edd19e03ec8bbbc77bc3372081410a824a5c10f9aa522b3a6390d7e8cb11cf",
    "from_account_id": "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
    "to_account_id": "oaccount~25e2e66718b6dbb59aea9c32acebec60e09d912b2578d4933d377ae5d0628f1e",
    "transacted_amount": 5,
    "converted_amount": 100,
    "conversion_rate": "20",
    "from_token_id": "USD",
    "to_token_id": "INR",
    "balance": 75,
    "onhold_balance": 0,
    "timestamp": "2022-11-30T11:03:20.000Z",
    "transaction_type": "TOKEN_CONVERSION_DEBIT"
  }
]
getConversionRateHistory
This method returns the token conversion rate history for a pair of tokens. This method can be called by the Token Admin of the chaincode, any Org Admin, and by any token account owner. 
@Validator(yup.string(), yup.string())
public async getConversionRateHistory(from_token_id:string , to_token_id:string) {
    const conversion_rate_id = await this.Ctx.TokenConversionRate.getConversionRateId(from_token_id,to_token_id);
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.getConversionRateHistory', 'TOKEN');  
    return await this.Ctx.TokenConversionRate.history(conversion_rate_id);
}
Parameters:
  • from_token_id: string – The ID of the token to convert from, for the purpose of calculating the conversion rate.
  • to_token_id: string – The ID of the token to convert to, for the purpose of calculating the conversion rate.
Returns:
  • On success, a JSON object with conversion rate history details.
Return Value Example:
 [
  {
    "trxId": "0b1ba7bc2620e1438b6580365e5c0ab852247ccfa5a3eb2157d3baca02c0e521",
    "timeStamp": "2022-11-30T10:23:38.000Z",
    "value": {
      "assetType": "oconversionRate",
      "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
      "from_token_id": "USD",
      "to_token_id": "INR",
      "conversion_rate": 20
    }
  },
  {
    "trxId": "36fc40ddb3d8308ee7e156af700da131d78d941fe390fc57985b7589e7035d5c",
    "timeStamp": "2022-11-30T10:13:18.000Z",
    "value": {
      "assetType": "oconversionRate",
      "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
      "from_token_id": "USD",
      "to_token_id": "INR",
      "conversion_rate": 10
    }
  }
]
getExchangePoolUser
This method returns the org_id and user_id values for the exchange pool user. This method can be called only by a Token Admin of the chaincode. 
@Validator()
public async getExchangePoolUser() {
    await this.Ctx.Auth.checkAuthorization('TOKEN_CONVERSION.getExchangePoolUser', 'TOKEN');
    return await this.Ctx.TokenConvertor.getExchangePoolUser();
}
Parameters:
  • none
Returns:
  • On success, a message with information about the exchange pool user.
Return Value Example:
{
   "assetType": "oconversion",
   "convertor_id": "bcb1f3b1442c625d3ce205660c5e717c5858a1fe1e12c325df799a851ceaa09b",
   "org_id": "Org1MSP",
   "user_id": "exchangepooluser"
}

Token Conversion SDK Methods

initializeExchangePoolUser
This method initializes the exchange pool user, which is a one-time activity. This method can be called only by a Token Admin of the chaincode. 
Ctx.TokenConvertor.initializeExchangePoolUser(orgId: string, userId: string)
Parameters:
  • orgId: string – The membership service provider (MSP) ID of the user in the current organization.
  • userId: string – The user name or email ID of the user.
Returns:
  • On success, a message that includes details of the exchange pool user.
Return Value Example:
{
    "assetType": "oconversion",
    "convertor_id": "bcb1f3b1442c625d3ce205660c5e717c5858a1fe1e12c325df799a851ceaa09b",
    "org_id": "Org1MSP",
    "user_id": "exchangepooluser"
}
createExchangePoolAccounts
This method creates exchange pool token accounts for a given array of token IDs. This method can be called only by a Token Admin of the chaincode. 
Ctx.TokenConvertor.createExchangePoolAccounts(token_ids: string[])
Parameters:
  • token_ids: string [] – An array of token IDs.
Returns:
  • On success, a list of objects that includes details of the exchange pool accounts that were created.
Return Value Example:
[
  {
    "account_id": "oaccount~cc9d84f6d4a5976532493ef5200c9603e138adc35166ffd5fd1aad9c1647f034",
    "token_id": "USD",
    "status": "created"
  },
  {
    "account_id": "oaccount~3d4933111ec8bd6cc1ebb43f2b2c390deb929cfa534f9c6ada8e63bac04a13c0",
    "token_id": "INR",
    "status": "created"
  }
]
addConversionToken
This method adds tokens with a new conversion rate for a specified token. The token conversion rate can be specified up to eight decimal places. This method can be called only by a Token Admin of the chaincode. 
Ctx.TokenConvertor.addConversionToken(fromTokenId: string, toTokenId: string, tokenConversionRate: number)
Parameters:
  • fromTokenId: string – The ID of the token to convert from.
  • toTokenId: string – The ID of the token to convert to.
  • tokenConversionRate: number – The rate at which to convert from_token_id token to the to_token_id token.
Returns:
  • On success, a JSON representation of the conversion rate object.
Return Value Example:
{
  "assetType": "oconversionRate",
  "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
  "from_token_id": "USD",
  "to_token_id": "INR",
  "conversion_rate": 10
}
get
This method gets the current conversion rate for a pair of tokens. This method can be called by the Token Admin of the chaincode and by any token account owner. 
Ctx.TokenConversionRate.get(id: string)
Parameters:
  • id: string – The ID of the token conversion rate object.
Returns:
  • On success, a JSON representation of the conversion rate object.
Return Value Example:
{
  "assetType": "oconversionRate",
  "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
  "from_token_id": "USD",
  "to_token_id": "INR",
  "conversion_rate": 10
}
updateTokenConversionRate
This method updates the current conversion rate for a pair of tokens. The token conversion rate can be specified up to eight decimal places. This method can be called only by a Token Admin of the chaincode. 
Ctx.TokenConvertor.updateTokenConversionRate(fromTokenId: string, toTokenId: string, tokenConversionRate: number)
Parameters:
  • from_token_id: string – The ID of the token to convert from.
  • to_token_id: string – The ID of the token to convert to.
  • token_conversion_rate: number – The rate at which to convert from_token_id token to the to_token_id token.
Returns:
  • On success, a JSON representation of the updated conversion rate object.
Return Value Example:
{
  "assetType": "oconversionRate",
  "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
  "from_token_id": "USD",
  "to_token_id": "INR",
  "conversion_rate": 20
}
mintWithFundingExchangePool
This method mints tokens in the caller's account based on the specified token ID and quantity. A percentage of tokens from the minted quantity is then transferred to the exchange pool token account.
Ctx.TokenConvertor.mintWithFundingExchangePool(tokenId: string, tokenQuantity: number, percentageTokenToExchangePool: number)
Parameters:
  • token_id: string – The ID of the token to mint.
  • token_quantity: number – The total number of tokens to mint.
  • percentage_token_to_exchange_pool: number – The percentage of minted tokens to transfer to the exchange pool token account.
Returns:
  • On success, a message that indicates that minting and funding the exchange pool were successful.
Return Value Example:
{
    "msg": "Successfully minted 100 tokens to Account Id: oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb (Org-Id: Org1MSP, User-Id: admin) and Successfully transfered 20 tokens to exchange pool Account with Account Id: oaccount~cc9d84f6d4a5976532493ef5200c9603e138adc35166ffd5fd1aad9c1647f034 (Org-Id: Org1MSP, User-Id: exchangepooluser) "
}
tokenConversion
This method converts tokens from the caller's account to the account specified by the to_token_id, to_org_id, and to_user_id values. This method can be called by the Token Admin of the chaincode and by any token account owner. An exchange pool user cannot call this method. 
Ctx.TokenConvertor.tokenConversion(fromTokenId: string, toTokenId: string, toOrgId: string, toUserId: string, tokenQuantity: number)
Parameters:
  • from_token_id: string – The ID of the token to convert from.
  • to_token_id: string – The ID of the token to convert to.
  • to_org_id: string – The membership service provider (MSP) ID of the user in the current organization to receive the tokens.
  • to_user_id: string – The user name or email ID of the user to receive the tokens.
Returns:
  • On success, a message that indicates the token conversion was successful.
Return Value Example:
{
    "msg": "Succesfully converted 5 of tokens with tokenId: [USD] from AccountId: oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb (Org-Id: Org1MSP, User-Id: admin) to 100 of tokens with tokenId: [INR] to AccountId: oaccount~25e2e66718b6dbb59aea9c32acebec60e09d912b2578d4933d377ae5d0628f1e (Org-Id: Org1MSP, User-Id: user) as per the conversion rate of 20"
}
getTokenConversionHistory
This method returns the token conversion history for a specified token account. This method can be called by the Token Admin of the chaincode, an Org Admin of the specified organization, and by the token account owner. 
Ctx.Account.getTokenConversionHistory(account_id: string, org_id: string, user_id: string)
Parameters:
  • account_id: string – The ID of the fungible token account.
  • 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 object with conversion history details.
Return Value Example:
[
  {
    "transaction_id": "otransaction~34edd19e03ec8bbbc77bc3372081410a824a5c10f9aa522b3a6390d7e8cb11cf",
    "from_account_id": "oaccount~abc74791148b761352b98df58035601b6f5480448ac2b4a3a7eb54bdbebf48eb",
    "to_account_id": "oaccount~25e2e66718b6dbb59aea9c32acebec60e09d912b2578d4933d377ae5d0628f1e",
    "transacted_amount": 5,
    "converted_amount": 100,
    "conversion_rate": "20",
    "from_token_id": "USD",
    "to_token_id": "INR",
    "balance": 75,
    "onhold_balance": 0,
    "timestamp": "2022-11-30T11:03:20.000Z",
    "transaction_type": "TOKEN_CONVERSION_DEBIT"
  }
]
history
This method returns the token conversion rate history for a pair of tokens. This method can be called by the Token Admin of the chaincode, any Org Admin, and by any token account owner. 
Ctx.TokenConversionRate.history(conversion_rate_id: string)
Parameters:
  • conversion_rate_id: string – The ID of the conversion rate object.
Returns:
  • On success, a JSON object with conversion rate history details.
Return Value Example:
 [
  {
    "trxId": "0b1ba7bc2620e1438b6580365e5c0ab852247ccfa5a3eb2157d3baca02c0e521",
    "timeStamp": "2022-11-30T10:23:38.000Z",
    "value": {
      "assetType": "oconversionRate",
      "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
      "from_token_id": "USD",
      "to_token_id": "INR",
      "conversion_rate": 20
    }
  },
  {
    "trxId": "36fc40ddb3d8308ee7e156af700da131d78d941fe390fc57985b7589e7035d5c",
    "timeStamp": "2022-11-30T10:13:18.000Z",
    "value": {
      "assetType": "oconversionRate",
      "conversion_rate_id": "oconversionRate~91c7eeb0614e7a50b1d5ecad559fcbc80b94034648bf405c9491dacf8d57873b",
      "from_token_id": "USD",
      "to_token_id": "INR",
      "conversion_rate": 10
    }
  }
]
getExchangePoolUser
This method returns the OrgId and UserId values for the exchange pool user. This method can be called only by a Token Admin of the chaincode. 
Ctx.TokenConvertor.getExchangePoolUser()
Parameters:
  • none
Returns:
  • On success, a message with information about the exchange pool user.
Return Value Example:
{
   "assetType": "oconversion",
   "convertor_id": "bcb1f3b1442c625d3ce205660c5e717c5858a1fe1e12c325df799a851ceaa09b",
   "org_id": "Org1MSP",
   "user_id": "exchangepooluser"
}