TypeScript ERC-721 NFT 锁定方法

Blockchain App Builder 自动生成方法，可用于锁定使用扩展 ERC-721 标准的非同质代币。

锁定的令牌无法刻录或传输给其他用户。所有其他属性（例如令牌的状态、所有者和历史记录）都将保留。将令牌传输到另一个区块链网络（如以太坊或多边形）时，可以使用 NFT 锁定功能。

必须先将 Vault 管理器角色分配给用户，然后才能锁定 NFT。Vault 管理器是一种特殊类型的角色，即 TokenSys 角色。TokenSys 角色与基于资产的角色（如刻录器、矿工和公证人）以及管理角色（如 Token Admin 和 Org Admin）不同。当前，区块链应用构建器支持 vault TokenSys 角色。链代码具有 vault 角色的单个用户是链代码的 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- 当前组织中用户的成员服务提供商 (membership service provider，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- 当前组织中用户的成员服务提供商 (membership service provider，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- 当前组织中用户的成员服务提供商 (membership service provider，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 角色的用户的成员资格服务提供商 (membership service provider，MSP) ID。
fromUserId: string- 要从中传输 TokenSys 角色的用户的用户名或电子邮件 ID。
toOrgId: string- 要将 TokenSys 角色转移到的用户的成员服务提供商 (membership service provider，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

此方法返回布尔值以指示指定的标记是否已锁定。此方法只能由令牌所有者、 Vault 管理器（具有 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- 当前组织中用户的成员服务提供商 (membership service provider，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

此方法返回所有锁定的不可换代币的列表。此方法只能由 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":"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- 当前组织中用户的成员服务提供商 (membership service provider，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
      }
   }
]