1. Using Oracle Blockchain Platform
  2. Build Chaincodes with Low-Code Blockchain App Builder
  3. Tokenization Support Using Blockchain App Builder
  4. ERC-721
  5. Scaffolded TypeScript NFT Project for ERC-721
  6. TypeScript Methods for ERC-721 NFT Locking

TypeScript Methods for ERC-721 NFT Locking

Blockchain App Builder automatically generates methods that you can use to lock non-fungible tokens that use the extended ERC-721 standard.

A locked token cannot be burned or transferred to other users. All other properties, such as the token's state, owner, and history are preserved. You can use the NFT locking functionality when transferring a token to another blockchain network, such as Ethereum or Polygon.

Before you can lock NFTs, you must assign the vault manager role to a user. The vault manager is a special type of role, a TokenSys role. TokenSys roles are different from asset-based roles such as burner, minter, and notary, and from administrative roles such as Token Admin and Org Admin. Currently Blockchain App Builder supports the vault TokenSys role. The single user who has the vault role for a chaincode is the vault manager of the chaincode, and can manage locked NFTs.

The typical flow for using the NFT locking functionality follows these steps.
  • Create a non-fungible token that has the lockable behavior.
  • Use the addTokenSysRole method to give the vault role to a user, the vault manager.
  • Call the lockNFT method to lock a non-fungible token, specified by the token ID.

TokenSys Role Management Methods

addTokenSysRole
This method adds a TokenSys role to a specified user. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string(), yup.string())
public async addTokenSysRole(role: string, orgId: string, userId: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.addTokenSysRoleMember", "TOKEN");
    await this.Ctx.ERC721Auth.checkAuthorization('ERC721TOKEN.addRoleMember', 'TOKEN');
    const accountId = await this.Ctx.ERC721Account.generateAccountId(orgId, userId);
    return await this.Ctx.ERC721Token.addTokenSysRoleMember(role, accountId);
}
Parameters:
  • role: string – The name of the TokenSys role to give to the user.
  • 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 contains relevant details of the operation.
Return Value Example:
{
    "msg": "Successfully added role 'vault' to Account Id: oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba (Org-Id: Org1MSP, User-Id: user1)"
}
isInTokenSysRole
This method returns a Boolean value to indicate if a user has a specified TokenSys role. This method can be called only by a Token Admin of the chaincode. 
@GetMethod()
@Validator(yup.string(), yup.string(), yup.string())
public async isInTokenSysRole(orgId: string, userId: string, role: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.isInTokenSysRole", "TOKEN", {orgId: orgId, userId: userId });
    const accountId = await this.Ctx.ERC721Account.generateAccountId(orgId, userId);
    return await this.Ctx.ERC721Token.isInTokenSysRole(role, accountId);
}
Parameters:
  • role: string – The name of the TokenSys role to check.
  • 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 contains relevant details of the operation.
Return Value Example:
{
    "result": true,
    "msg": "Account Id oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba (Org-Id: Org1MSP, User-Id: user1) has vault role"
}
removeTokenSysRole
This method removes a TokenSys role from a specified user. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string(), yup.string())
public async removeTokenSysRole(role: string, orgId: string, userId: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.removeTokenSysRoleMember", "TOKEN");
    const accountId = await this.Ctx.ERC721Account.generateAccountId(orgId, userId);
    return await this.Ctx.ERC721Token.removeTokenSysRoleMember(role, accountId);
}
Parameters:
  • role: string – The name of the TokenSys role to remove.
  • 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 contains relevant details of the operation.
Return Value Example:
{
    "msg": "Successfully removed role 'vault' from Account Id: oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba (Org-Id: Org1MSP, User-Id: user1)"
}
transferTokenSysRole
This method transfers a TokenSys role from a user to another user. This method can be called only by a Token Admin of the chaincode. 
@Validator(yup.string(), yup.string(), yup.string(), yup.string(), yup.string())
public async transferTokenSysRole(role: string, fromOrgId: string, fromUserId: string, toOrgId: string, toUserId: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.transferTokenSysRole", "TOKEN");
    const fromAccountId = await this.Ctx.ERC721Account.generateAccountId(fromOrgId, fromUserId);
    const toAccountId = await this.Ctx.ERC721Account.generateAccountId(toOrgId, toUserId);
    return await this.Ctx.ERC721Token.transferTokenSysRole(role, fromAccountId, toAccountId);
}
Parameters:
  • role: string – The name of the TokenSys role to transfer.
  • fromOrgId: string – The membership service provider (MSP) ID of the user to transfer the TokenSys role from.
  • fromUserId: string – The user name or email ID of the user to transfer the TokenSys role from.
  • toOrgId: string – The membership service provider (MSP) ID of the user to transfer the TokenSys role to.
  • toUserId: string – The user name or email ID of the user to transfer the TokenSys role to.
Returns:
  • On success, a message that contains relevant details of the operation.
Return Value Example:
{
    "msg": "Successfully transfered role 'vault' from Account Id: ouaccount~f4e311528f03fffa7810753d643f66289ff6c9080fcf839902f28a1d3aff1789 (Org-Id: Org1MSP, User-Id: user1) to Account Id: ouaccount~ae5be2ae8f98d6d32f5d02b43877d987114e7937c7bacbc30390dcce09996a19 (Org-Id: Org1MSP, User-Id: user2)"
}
getAccountsByTokenSysRole
This method returns a list of all account IDs for a specified TokenSys role. This method can be called only by a Token Admin of the chaincode. 
@GetMethod()
@Validator(yup.string())
public async getAccountsByTokenSysRole(role: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.getAccountsByTokenSysRole", "TOKEN");
    return await this.Ctx.ERC721Token.getAccountsByTokenSysRole(role);
}
Parameters:
  • role: string – The name of the TokenSys role.
Returns:
  • On success, a message that contains relevant details of the operation.
Return Value Example:
{
    "accountIds": [
        "oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba"
    ]
}
getUsersByTokenSysRole
This method returns user information for all users with a specified TokenSys role. This method can be called only by a Token Admin of the chaincode. 
@GetMethod()
@Validator(yup.string())
public async getUsersByTokenSysRole(role: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.getUsersByTokenSysRole", "TOKEN");
    return await this.Ctx.ERC721Token.getUsersByTokenSysRole(role);
}
Parameters:
  • role: string – The name of the TokenSys role.
Returns:
  • On success, a message that contains relevant details of the operation.
Return Value Example:
 "users":[
      {
         "accountId":"oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba",
         "orgId":"Org1MSP",
         "userId":"user1"
      }
   ]
}

NFT Locking Methods

lockNFT
This method locks a specified non-fungible token. To lock a token, there must be a user with the TokenSys vault role, who acts as the vault manager. This method can be called only by the owner of the token. 
@Validator(yup.string())
public async lockNFT(tokenId: string) {
    return await this.Ctx.ERC721Token.lockNFT(tokenId);
}
Parameters:
  • tokenID: string – The ID of the token to lock.
Returns:
  • On success, a JSON representation of the token object.
Return Value Example:
{
   "assetType":"otoken",
   "tokenId":"token1",
   "tokenName":"artcollection",
   "symbol":"ART",
   "tokenStandard":"erc721+",
   "tokenType":"nonfungible",
   "tokenUnit":"whole",
   "behaviors":[
      "indivisible",
      "singleton",
      "mintable",
      "transferable",
      "lockable",
      "burnable",
      "roles"
   ],
   "roles":{
      "minter_role_name":"minter"
   },
   "mintable":{
      "max_mint_quantity":20000
   },
   "createdBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
   "creationDate":"2023-10-20T10:26:29.000Z",
   "owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
   "isBurned":false,
   "isLocked":true,
   "tokenUri":"token1.example.com",
   "price":120,
   "on_sale_flag":false
}
isNFTLocked
This method returns a Boolean value to indicate if a specified token is locked. This method can be called only by the token owner, the vault manager (the user with the TokenSys vault role), or a Token Admin of the chaincode. 
@GetMethod()
@Validator(yup.string())
public async isNFTLocked(tokenId: string) {
  try {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.isNFTLocked", "TOKEN", { tokenId });
  } catch(err) {
    const isCallerTokenSysRoleHolder = await this.Ctx.ERC721Token.isCallerTokenSysRoleHolder(TOKEN_SYS_ROLE_TYPE.VAULT);
    if(!isCallerTokenSysRoleHolder)
      throw err;
  }
  const isLocked = await this.Ctx.ERC721Token.isNFTLocked(tokenId);
  return {isLocked: isLocked}
}
Parameters:
  • tokenID: string – The ID of the token.
Returns:
  • On success, a message that contains relevant details of the operation.
Return Value Example:
{
   "isNFTLocked":true
}
getAllLockedNFTs
This method returns a list of all locked non-fungible tokens. This method can be called only by the vault manager (the user with the TokenSys vault role) or a Token Admin of the chaincode. 
@GetMethod()
@Validator()
public async getAllLockedNFTs() {
  try {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.getAllLockedNFTs", "TOKEN");
  } catch(err) {
    const isCallerTokenSysRoleHolder = await this.Ctx.ERC721Token.isCallerTokenSysRoleHolder(TOKEN_SYS_ROLE_TYPE.VAULT);
    if(!isCallerTokenSysRoleHolder)
      throw err;
  }
 return this.Ctx.ERC721Token.getAllLockedNFTs();
}
Parameters:
  • None
Returns:
  • On success, an array of the locked non-fungible token objects.
Return Value Example:
[
   {
      "key":"token1",
      "valueJson":{
         "assetType":"otoken",
         "tokenId":"token1",
         "tokenName":"artcollection",
         "symbol":"ART",
         "tokenStandard":"erc721+",
         "tokenType":"nonfungible",
         "tokenUnit":"whole",
         "behaviors":[
            "indivisible",
            "singleton",
            "mintable",
            "transferable",
            "lockable",
            "burnable",
            "roles"
         ],
         "roles":{
            "minter_role_name":"minter"
         },
         "mintable":{
            "max_mint_quantity":20000
         },
         "createdBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "creationDate":"2023-10-20T10:26:29.000Z",
         "owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "isBurned":false,
         "isLocked":true,
         "tokenUri":"token1.example.com",
         "price":120,
         "on_sale_flag":false
      }
   }
]
getAllLockedNFTsByOrg
This method returns a list of all locked non-fungible tokens for a specified organization and optionally a specified user. This method can be called only by the vault manager (the user with the TokenSys vault role) or a Token Admin of the chaincode. 
@GetMethod()
@Validator(yup.string(), yup.string())
public async getLockedNFTsByOrg(orgId: string, userId?: string) {
  try {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.getLockedNFTsByOrg", "TOKEN");
  } catch(err) {
    const isCallerTokenSysRoleHolder = await this.Ctx.ERC721Token.isCallerTokenSysRoleHolder(TOKEN_SYS_ROLE_TYPE.VAULT);
    if(!isCallerTokenSysRoleHolder)
      throw err;
  }
  return await this.Ctx.ERC721Token.getLockedNFTsByOrg(orgId, userId);
}
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 (optional).
Returns:
  • On success, an array of the locked non-fungible token objects.
Return Value Example:
[
   {
      "key":"token1",
      "valueJson":{
         "assetType":"otoken",
         "tokenId":"token1",
         "tokenName":"artcollection",
         "symbol":"ART",
         "tokenStandard":"erc721+",
         "tokenType":"nonfungible",
         "tokenUnit":"whole",
         "behaviors":[
            "indivisible",
            "singleton",
            "mintable",
            "transferable",
            "lockable",
            "burnable",
            "roles"
         ],
         "roles":{
            "minter_role_name":"minter"
         },
         "mintable":{
            "max_mint_quantity":20000
         },
         "createdBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "creationDate":"2023-10-20T10:26:29.000Z",
         "owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "isBurned":false,
         "isLocked":true,
         "tokenUri":"token1.examplecom",
         "price":120,
         "on_sale_flag":false
      }
   }
]