TypeScript ERC-721 NFT 鎖定方法

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

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

您必須先將 Vault 管理員角色指定給使用者，才能鎖定 NFT。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 角色的使用者 (作為保存庫管理程式)。這個方法只有記號的擁有者才能呼叫。

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

lockNFT

  @Validator(yup.number())
  public async lockNFT(tokenId: number) {
    const tokenIdStr = this.Ctx.Utils.convertToString(tokenId);
    return await this.Ctx.ERC721Token.lockNFT(tokenIdStr);
  }

參數：

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

傳回值：

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

傳回值範例：

{
   "assetType":"otoken",
   "tokenId":"23",
   "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

  @GetMethod()
  @Validator(yup.number())
  public async isNFTLocked(tokenId: number) {
    const tokenIdStr = this.Ctx.Utils.convertToString(tokenId);
    try {
      await this.Ctx.ERC721Auth.checkAuthorization("ERC721TOKEN.isNFTLocked", "TOKEN", { tokenId: tokenIdStr });
    } catch (err) {
      const isCallerTokenSysRoleHolder = await this.Ctx.ERC721Token.isCallerTokenSysRoleHolder(TOKEN_SYS_ROLE_TYPE.VAULT);
      if (!isCallerTokenSysRoleHolder) throw err;
    }
    const isNFTLocked = await this.Ctx.ERC721Token.isNFTLocked(tokenIdStr);
    return { isNFTLocked };
  }

參數：

tokenID: number – 記號的 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":"23",
      "valueJson":{
         "assetType":"otoken",
         "tokenId":"23",
         "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

@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":"23",
      "valueJson":{
         "assetType":"otoken",
         "tokenId":"23",
         "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
      }
   }
]