TypeScript ERC-721 NFT 鎖定的方法

Blockchain App Builder 會自動產生方法，您可以用來鎖定使用擴充 ERC-721 標準的不可行記號。

鎖定的權杖無法燒錄或傳輸給其他使用者。會保留所有其他特性，例如記號的狀態、擁有者和歷史記錄。將記號傳輸至另一個區塊鏈網路 (例如乙太網路或多邊形) 時，您可以使用 NFT 鎖定功能。

在鎖定 NFT 之前，您必須將 Vault 管理者角色指定給使用者。Vault 管理員是一種特殊類型的角色，即 TokenSys 角色。TokenSys 角色不同於資產型角色，例如燃燒器、礦工和公證人，以及管理角色 (例如 Token Admin 和 Org Admin)。目前 Blockchain App Builder 支援 vault TokenSys 角色。具有鏈碼 vault 角色的單一使用者是鏈碼的保存庫管理者，可以管理鎖定的 NFT。

使用 NFT 鎖定功能的一般流程如下。

建立具有可鎖定行為的不可行記號。
使用 addTokenSysRole 方法，將 vault 角色提供給 Vault 管理員使用者。
呼叫 lockNFT 方法來鎖定變數替代字 ID 所指定的不可行變數替代字。

TokenSys 角色管理方法

addTokenSysRole

此方法會將 TokenSys 角色新增至指定的使用者。此方法只能由鏈碼的 Token Admin 呼叫。

@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);
}

參數：

role: string – 要提供給使用者的 TokenSys 角色名稱。
orgId: string – 目前組織中使用者的成員身分服務提供者 (MSP) ID。
userId: string – 使用者的使用者名稱或電子郵件 ID。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

{
    "msg": "Successfully added role 'vault' to Account Id: oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba (Org-Id: Org1MSP, User-Id: user1)"
}

isInTokenSysRole

此方法會傳回布林值，指示使用者是否具有指定的 TokenSys 角色。此方法只能由鏈碼的 Token Admin 呼叫。

@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);
}

參數：

role: string – 要檢查的 TokenSys 角色名稱。
orgId: string – 目前組織中使用者的成員身分服務提供者 (MSP) ID。
userId: string – 使用者的使用者名稱或電子郵件 ID。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

{
    "result": true,
    "msg": "Account Id oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba (Org-Id: Org1MSP, User-Id: user1) has vault role"
}

removeTokenSysRole

此方法會從指定的使用者移除 TokenSys 角色。此方法只能由鏈碼的 Token Admin 呼叫。

@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);
}

參數：

role: string – 要移除的 TokenSys 角色名稱。
orgId: string – 目前組織中使用者的成員身分服務提供者 (MSP) ID。
userId: string – 使用者的使用者名稱或電子郵件 ID。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

{
    "msg": "Successfully removed role 'vault' from Account Id: oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba (Org-Id: Org1MSP, User-Id: user1)"
}

transferTokenSysRole

此方法會將 TokenSys 角色從使用者傳輸給其他使用者。此方法只能由鏈碼的 Token Admin 呼叫。

@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);
}

參數：

role: string – 要傳輸之 TokenSys 角色的名稱。
fromOrgId: string – 要從中轉移 TokenSys 角色之使用者的成員身分服務提供者 (MSP) ID。
fromUserId: string – 要從中轉移 TokenSys 角色的使用者名稱或電子郵件 ID。
toOrgId: string – 要將 TokenSys 角色傳輸至之使用者的成員身分服務提供者 (MSP) ID。
toUserId: string – 要將 TokenSys 角色轉移給使用者的使用者名稱或電子郵件 ID。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

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

此方法會傳回指定之 TokenSys 角色的所有帳戶 ID 清單。此方法只能由鏈碼的 Token Admin 呼叫。

@GetMethod()
@Validator(yup.string())
public async getAccountsByTokenSysRole(role: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.getAccountsByTokenSysRole", "TOKEN");
    return await this.Ctx.ERC721Token.getAccountsByTokenSysRole(role);
}

參數：

role: string – TokenSys 角色的名稱。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

{
    "accountIds": [
        "oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba"
    ]
}

getUsersByTokenSysRole

此方法會傳回具有指定 TokenSys 角色之所有使用者的使用者資訊。此方法只能由鏈碼的 Token Admin 呼叫。

@GetMethod()
@Validator(yup.string())
public async getUsersByTokenSysRole(role: string) {
    await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.getUsersByTokenSysRole", "TOKEN");
    return await this.Ctx.ERC721Token.getUsersByTokenSysRole(role);
}

參數：

role: string – TokenSys 角色的名稱。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

 "users":[
      {
         "accountId":"oaccount~bf07f584a94be44781e49d9101bfaf58c6fbbe77a4dfebdb83c874c2caf03eba",
         "orgId":"Org1MSP",
         "userId":"user1"
      }
   ]
}

NFT 鎖定方法

lockNFT

此方法會鎖定指定的不可見變數替代字。若要鎖定記號，必須要有一個具備 TokenSys vault 角色的使用者，而該角色是作為 Vault 管理員。只有記號的擁有者才能呼叫此方法。

@Validator(yup.string())
public async lockNFT(tokenId: string) {
    return await this.Ctx.ERC721Token.lockNFT(tokenId);
}

參數：

tokenID: string – 要鎖定之記號的 ID。

傳回值：

成功時，記號物件的 JSON 表示法。

傳回值範例：

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

此方法會傳回布林值，指示指定的記號是否被鎖定。只有記號擁有者、保存庫管理員 (具備 TokenSys vault 角色的使用者) 或鏈碼的 Token Admin 才能呼叫此方法。

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

參數：

tokenID: string – 記號的 ID。

傳回值：

成功時，會顯示包含作業相關詳細資訊的訊息。

傳回值範例：

{
   "isNFTLocked":true
}

getAllLockedNFTs

此方法會傳回所有鎖定之不可行記號的清單。保存庫管理程式 (具備 TokenSys vault 角色的使用者) 或鏈碼的 Token Admin 才能呼叫此方法。

@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();
}

參數：

無。

傳回值：

成功時，鎖定的不可行記號物件陣列。

傳回值範例：

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

此方法會傳回指定組織的所有鎖定不可行記號清單，以及選擇性地傳回指定的使用者。保存庫管理程式 (具備 TokenSys vault 角色的使用者) 或鏈碼的 Token Admin 才能呼叫此方法。

@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);
}

參數：

orgId: string – 目前組織中使用者的成員身分服務提供者 (MSP) ID。
userId: string – 使用者的使用者名稱或電子郵件 ID (選擇性)。

傳回值：

成功時，鎖定的不可行記號物件陣列。

傳回值範例：

[
   {
      "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
      }
   }
]