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 Account Status

TypeScript Methods for Token Account Status

Blockchain App Builder automatically generates methods that you can use to manage account status for fungible tokens that use the Token Taxonomy Framework standard.

You can use the following methods to put token user accounts in the active, suspended, or deleted states.

When an account is suspended, the account user cannot complete any write operations, which include minting, burning, transferring, and holding tokens. Additionally, other users cannot transfer tokens to or hold tokens in a suspended account. A suspended account can still complete read operations.

An account with a non-zero token balance cannot be deleted. You must transfer or burn all tokens in an account before you can delete the account. After an account is in the deleted state, the account state cannot be changed back to active or suspended.

Automatically Generated Account Status Methods

Blockchain App Builder automatically generates methods to manage token account status. Controller methods must have a @Validator(...params) decorator to be invokable.

getAccountStatus
This method gets the current status of the 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. This method also supports data migration for existing chaincode that is upgraded to a newer version. 
@Validator(yup.string(), yup.string(), yup.string())
  public async getAccountStatus(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_STATUS.get", "TOKEN", { account_id });
    try {
      return await this.Ctx.AccountStatus.getAccountStatus(account_id);
    } catch (err) {
      return await this.Ctx.AccountStatus.getDefaultAccountStatus(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 message that includes details of the token account status.
Return Value Example:
{
    "assetType": "oaccountStatus",
    "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
    "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
    "status": "active"
}
getAccountStatusHistory
This method gets the history of the account status. 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 getAccountStatusHistory(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.Account.getAccount(account_id);
    await this.Ctx.Auth.checkAuthorization("ACCOUNT_STATUS.history", "TOKEN", { account_id });
    const status_id = await this.Ctx.AccountStatus.generateAccountStatusId(account_id);
    let account_status_history: any;
    try {
      account_status_history = await this.Ctx.AccountStatus.history(status_id);
    } catch (err) {
      return [];
    }
    return account_status_history;
  }
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 message that includes details of the account status history.
Return Value Example:
[
  {
    "trxId": "d5c6d6f601257ba9b6edaf5b7660f00adc13c37d5321b8f7d3a35afab2e93e63",
    "timeStamp": "2022-12-02T10:39:14.000Z",
    "value": {
      "assetType": "oaccountStatus",
      "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
      "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
      "status": "suspended"
    }
  },
  {
    "trxId": "e6c850cfa084dc20ad95fb2bb8165eef3a3bd62a0ac867cccee57c2003125183",
    "timeStamp": "2022-12-02T10:37:50.000Z",
    "value": {
      "assetType": "oaccountStatus",
      "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
      "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
      "status": "active"
    }
  }
]
activateAccount
This method activates a token account. This method can be called only by a Token Admin of the chaincode or an Org Admin of the specified organization. Deleted accounts cannot be activated. 
@Validator(yup.string(), yup.string(), yup.string())
  public async activateAccount(token_id: string, org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT_STATUS.activateAccount", "TOKEN", { org_id });
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    return await this.Ctx.Account.activateAccount(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON representation of the account status object for the specified token account.
Return Value Example:
{
  "assetType": "oaccountStatus",
  "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
  "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
  "status": "active"
}
suspendAccount
This method suspends a token account. This method can be called only by a Token Admin of the chaincode or an Org Admin of the specified organization. After an account is suspended, you cannot complete any operations that update the account. A deleted account cannot be suspended. 
@Validator(yup.string(), yup.string(), yup.string())
  public async suspendAccount(token_id: string, org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT_STATUS.suspendAccount", "TOKEN", { org_id });
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    return await this.Ctx.Account.suspendAccount(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON representation of the account status object for the specified token account.
Return Value Example:
{
    "assetType": "oaccountStatus",
    "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
    "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
    "status": "suspended"
}
deleteAccount
This method deletes a token account. This method can be called only by a Token Admin of the chaincode or an Org Admin of the specified organization. After an account is deleted, you cannot complete any operations that update the account. The deleted account is in a final state and cannot be changed to any other state. To delete an account, the account balance and the on-hold balance must be zero. 
@Validator(yup.string(), yup.string(), yup.string())
  public async deleteAccount(token_id: string, org_id: string, user_id: string) {
    await this.Ctx.Auth.checkAuthorization("ACCOUNT_STATUS.deleteAccount", "TOKEN", { org_id });
    const account_id = await this.Ctx.Account.generateAccountId(token_id, org_id, user_id);
    return await this.Ctx.Account.deleteAccount(account_id);
  }
Parameters:
  • token_id: string – The ID of the token.
  • org_id: string – The membership service provider (MSP) ID of the user in the current organization.
  • user_id: string – The user name or email ID of the user.
Returns:
  • On success, a JSON representation of the account status object for the specified token account.
Return Value Example:
{
  "assetType": "oaccountStatus",
  "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
  "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
  "status": "deleted"
}

Account Status SDK Methods

getAccountStatus
This method gets the current status of the token account.
Ctx.AccountStatus.getAccountStatus(account_id: string)
Parameters:
  • account_id: string – The ID of the token account.
Returns:
  • On success, a JSON representation of the account status object.
Return Value Example:
{
    "assetType": "oaccountStatus",
    "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
    "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
    "status": "active"
}
saveAccountStatus
This method saves the status object (if a status object is not present) for the token account, and sets the status to the specified value.
Ctx.AccountStatus.saveAccountStatus(account_id: string, status: AccountStatus)
Parameters:
  • account_id: string – The ID of the token account.
  • status: AccountStatus – The status to set for the specified account.

    AccountStatus is an enum type which must be active, suspended, or deleted.

Returns:
  • On success, a JSON representation of the account status object.
Return Value Example:
{
    "assetType": "oaccountStatus",
    "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
    "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
    "status": "active"
}
getAccountStatusHistory
This method gets the history of the account status.
Ctx.AccountStatus.history(status_id: string)
Parameters:
  • status_id: string – The ID of the account status object.
Returns:
  • On success, a JSON representation of the account status history.
Return Value Example:
[
  {
    "trxId": "d5c6d6f601257ba9b6edaf5b7660f00adc13c37d5321b8f7d3a35afab2e93e63",
    "timeStamp": "2022-12-02T10:39:14.000Z",
    "value": {
      "assetType": "oaccountStatus",
      "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
      "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
      "status": "suspended"
    }
  },
  {
    "trxId": "e6c850cfa084dc20ad95fb2bb8165eef3a3bd62a0ac867cccee57c2003125183",
    "timeStamp": "2022-12-02T10:37:50.000Z",
    "value": {
      "assetType": "oaccountStatus",
      "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
      "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
      "status": "active"
    }
  }
]
activateAccount
This method activates a token account.
Ctx.Account.activateAccount(account_id: string)
Parameters:
  • account_id: string – The ID of the token account.
Returns:
  • On success, a JSON representation of the account status object for the specified token account.
Return Value Example:
{
  "assetType": "oaccountStatus",
  "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
  "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
  "status": "active"
}
suspendAccount
This method suspends a token account.
Ctx.Account.suspendAccount(account_id: string)
Parameters:
  • account_id: string – The ID of the token account.
Returns:
  • On success, a JSON representation of the account status object for the specified token account.
Return Value Example:
{
    "assetType": "oaccountStatus",
    "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
    "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
    "status": "suspended"
}
deleteAccount
This method deletes a token account.
Ctx.Account.deleteAccount(account_id: string)
Parameters:
  • account_id: string – The ID of the token account.
Returns:
  • On success, a JSON representation of the account status object for the specified token account.
Return Value Example:
{
  "assetType": "oaccountStatus",
  "status_id": "oaccountStatus~5a0b0d8b1c6433af9fedfe0d9e6580e7cf6b6bb62a0de6267aaf79f79d5e96d7",
  "account_id": "oaccount~1c568151c4acbcd1bd265c766c677145760a61c47fc8a3ba681a4cfbe287f9c1",
  "status": "deleted"
}