TypeScript ERC-721 NFT 鎖定方法

Blockchain App Builder 會自動產生方法，您可以用來鎖定使用延伸 ERC-721 標準的不可行權杖。

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

您必須先將 Vault 管理者角色指派給使用者，才能鎖定 NFT。保存庫管理員是一種特殊類型的角色，即 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 角色的使用者，該角色可作為保存庫管理員。此方法只能由記號的擁有者呼叫。

@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

此方法會傳回所有鎖定的不可行記號清單。此方法只能由 Vault 管理程式 (具有 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

此方法會傳回指定組織和指定之使用者的所有已鎖定非功能記號清單。此方法只能由 Vault 管理程式 (具有 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
      }
   }
]