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 才能呼叫此方法。

func (t *Controller) AddTokenSysRole(role string, orgId string, userId string) (interface{}, error) {
    accountId, err := t.Ctx.ERC721Account.GenerateAccountId(orgId, userId)
    if err != nil {
        return nil, err
    }
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.AddTokenSysRole", "TOKEN", map[string]string{"accountId": accountId})
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.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 才能呼叫此方法。

func (t *Controller) IsInTokenSysRole(orgId string, userId string, role string) (interface{}, error) {
    accountId, err := t.Ctx.ERC721Account.GenerateAccountId(orgId, userId)
    if err != nil {
        return nil, err
    }
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.IsInTokenSysRole", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.ERC721Token.IsInTokenSysRoleMember(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 才能呼叫此方法。

func (t *Controller) RemoveTokenSysRole(role string, orgId string, userId string) (interface{}, error) {
    accountId, err := t.Ctx.ERC721Account.GenerateAccountId(orgId, userId)
    if err != nil {
        return nil, err
    }
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.RemoveTokenSysRole", "TOKEN", map[string]string{"accountId": accountId})
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.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 才能呼叫此方法。

func (t *Controller) TransferTokenSysRole(role string, fromOrgId string, fromUserId string, toOrgId string, toUserId string) (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.TransferTokenSysRole", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller %s", err.Error())
    }
    fromAccountId, err := t.Ctx.ERC721Account.GenerateAccountId(fromOrgId, fromUserId)
    if err != nil {
        return nil, fmt.Errorf("error in TransferTokenSysRole. Error: %s", err)
    }
    toAccountId, err := t.Ctx.ERC721Account.GenerateAccountId(toOrgId, toUserId)
    if err != nil {
        return nil, fmt.Errorf("error in TransferTokenSysRole. Error: %s", err)
    }
    return t.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 才能呼叫此方法。

func (t *Controller) GetAccountsByTokenSysRole(role string) (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.GetAccountsByTokenSysRole", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.ERC721Token.GetAccountsByTokenSysRole(role)
}

參數：

role: string – TokenSys 角色的名稱。

傳回值：

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

傳回值範例：

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

GetUsersByTokenSysRole

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

func (t *Controller) GetUsersByTokenSysRole(role string) (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.GetUsersByTokenSysRole", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.ERC721Token.GetUsersByTokenSysRole(role)
}

參數：

role: string – TokenSys 角色的名稱。

傳回值：

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

傳回值範例：

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

NFT 鎖定方法

基本
數位資產

LockNFT

這個方法會鎖定指定的不可執行記號。若要鎖定記號，必須要有具備 TokenSys vault 角色的使用者 (作為保存庫管理程式)。這個方法只有記號的擁有者才能呼叫。

func (t *Controller) LockNFT(tokenId string) (interface{}, error) {
    return t.Ctx.ERC721Token.LockNFT(tokenId)
}

參數：

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

傳回值：

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

傳回值範例：

{
   "AssetType":"otoken",
   "Behavior":[
      "indivisible",
      "singleton",
      "mintable",
      "transferable",
      "lockable",
      "burnable",
      "roles"
   ],
   "CreatedBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
   "CreationDate":"2023-10-20T12:39:50Z",
   "IsBurned":false,
   "IsLocked":true,
   "Mintable":{
      "Max_mint_quantity":20000
   },
   "On_sale_flag":false,
   "Owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
   "Price":120,
   "Roles":{
      "minter_role_name":"minter"
   },
   "Symbol":"ART",
   "TokenDesc":"",
   "TokenId":"token1",
   "TokenMetadata":{
      "Description":"",
      "Image":"",
      "Painter_name":"",
      "Painting_name":""
   },
   "TokenName":"artcollection",
   "TokenStandard":"erc721+",
   "TokenType":"nonfungible",
   "TokenUnit":"whole",
   "TokenUri":"token1.example.com"
}

IsNFTLocked

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

func (t *Controller) IsNFTLocked(tokenId string) (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.IsNFTLocked", "TOKEN", map[string]string{"tokenId": tokenId})
    if err != nil && !auth {
        isCallerTokenSysRoleHolder, error := t.Ctx.ERC721Token.IsCallerTokenSysRoleHolder(constants.Vault)
        if error != nil {
            return nil, error
        }
        if !isCallerTokenSysRoleHolder {
            return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
        }
    }
    return t.Ctx.ERC721Token.IsNFTLocked(tokenId)
}

參數：

tokenID: string – 記號的 ID。

傳回值：

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

傳回值範例：

{
   "isNFTLocked":true
}

GetAllLockedNFTs

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

func (t *Controller) GetAllLockedNFTs() (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.GetAllLockedNFTs", "TOKEN")
    if err != nil && !auth {
        isCallerTokenSysRoleHolder, error := t.Ctx.ERC721Token.IsCallerTokenSysRoleHolder(constants.Vault)
        if error != nil {
            return nil, error
        }
        if !isCallerTokenSysRoleHolder {
            return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
        }
    }
    return t.Ctx.ERC721Token.GetAllLockedNFTs()
}

參數：

無。

傳回值：

成功時，鎖定的不可執行變數替代字物件陣列。

傳回值範例：

[
   {
      "key":"token1",
      "valueJson":{
         "AssetType":"otoken",
         "Behavior":[
            "indivisible",
            "singleton",
            "mintable",
            "transferable",
            "lockable",
            "burnable",
            "roles"
         ],
         "CreatedBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "CreationDate":"2023-10-20T12:39:50Z",
         "IsBurned":false,
         "IsLocked":true,
         "Mintable":{
            "Max_mint_quantity":20000
         },
         "On_sale_flag":false,
         "Owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "Price":120,
         "Roles":{
            "minter_role_name":"minter"
         },
         "Symbol":"ART",
         "TokenDesc":"",
         "TokenId":"token1",
         "TokenMetadata":{
            "Description":"",
            "Image":"",
            "Painter_name":"",
            "Painting_name":""
         },
         "TokenName":"artcollection",
         "TokenStandard":"erc721+",
         "TokenType":"nonfungible",
         "TokenUnit":"whole",
         "TokenUri":"token1.example.com"
      }
   }
]

GetAllLockedNFTsByOrg

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

func (t *Controller) GetLockedNFTsByOrg(orgId string, userId ...string) (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.GetLockedNFTsByOrg", "TOKEN")
    if err != nil && !auth {
        isCallerTokenSysRoleHolder, error := t.Ctx.ERC721Token.IsCallerTokenSysRoleHolder(constants.Vault)
        if error != nil {
            return nil, error
        }
        if !isCallerTokenSysRoleHolder {
            return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
        }
    }
    return t.Ctx.ERC721Token.GetLockedNFTsByOrg(orgId, userId...)
}

參數：

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

傳回值：

成功時，鎖定的不可執行變數替代字物件陣列。

傳回值範例：

[
   {
      "key":"token1",
      "valueJson":{
         "AssetType":"otoken",
         "Behavior":[
            "indivisible",
            "singleton",
            "mintable",
            "transferable",
            "lockable",
            "burnable",
            "roles"
         ],
         "CreatedBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "CreationDate":"2023-10-20T12:39:50Z",
         "IsBurned":false,
         "IsLocked":true,
         "Mintable":{
            "Max_mint_quantity":20000
         },
         "On_sale_flag":false,
         "Owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "Price":120,
         "Roles":{
            "minter_role_name":"minter"
         },
         "Symbol":"ART",
         "TokenDesc":"",
         "TokenId":"token1",
         "TokenMetadata":{
            "Description":"",
            "Image":"",
            "Painter_name":"",
            "Painting_name":""
         },
         "TokenName":"artcollection",
         "TokenStandard":"erc721+",
         "TokenType":"nonfungible",
         "TokenUnit":"whole",
         "TokenUri":"token1.example.com"
      }
   }
]

LockNFT

func (t *Controller) LockNFT(tokenId float64) (interface{}, error) {
	// Convert tokenIds first
	tokenIdStr, err := util.ConvertFloat64ToString(tokenId)
	if err != nil {
		return nil, err
	}
	return t.Ctx.ERC721Token.LockNFT(tokenIdStr)
}

參數：

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

傳回值：

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

傳回值範例：

{
   "AssetType":"otoken",
   "Behavior":[
      "indivisible",
      "singleton",
      "mintable",
      "transferable",
      "lockable",
      "burnable",
      "roles"
   ],
   "CreatedBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
   "CreationDate":"2023-10-20T12:39:50Z",
   "IsBurned":false,
   "IsLocked":true,
   "Mintable":{
      "Max_mint_quantity":20000
   },
   "On_sale_flag":false,
   "Owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
   "Price":120,
   "Roles":{
      "minter_role_name":"minter"
   },
   "Symbol":"ART",
   "TokenDesc":"",
   "TokenId":"23",
   "TokenMetadata":{
      "Description":"",
      "Image":"",
      "Painter_name":"",
      "Painting_name":""
   },
   "TokenName":"artcollection",
   "TokenStandard":"erc721+",
   "TokenType":"nonfungible",
   "TokenUnit":"whole",
   "TokenUri":"token1.example.com"
}

IsNFTLocked

func (t *Controller) IsNFTLocked(tokenId float64) (interface{}, error) {
	// Convert tokenIds first
	tokenIdStr, err := util.ConvertFloat64ToString(tokenId)
	if err != nil {
		return nil, err
	}
	auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.IsNFTLocked", "TOKEN", map[string]string{"tokenId": tokenIdStr})
	if err != nil && !auth {
		isCallerTokenSysRoleHolder, error := t.Ctx.ERC721Token.IsCallerTokenSysRoleHolder(constants.Vault)
		if error != nil {
			return nil, error
		}
		if !isCallerTokenSysRoleHolder {
			return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
		}
	}
	return t.Ctx.ERC721Token.IsNFTLocked(tokenIdStr)
}

參數：

tokenID: float64 – 記號的 ID。

傳回值：

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

傳回值範例：

{
   "isNFTLocked":true
}

GetAllLockedNFTs

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

func (t *Controller) GetAllLockedNFTs() (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.GetAllLockedNFTs", "TOKEN")
    if err != nil && !auth {
        isCallerTokenSysRoleHolder, error := t.Ctx.ERC721Token.IsCallerTokenSysRoleHolder(constants.Vault)
        if error != nil {
            return nil, error
        }
        if !isCallerTokenSysRoleHolder {
            return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
        }
    }
    return t.Ctx.ERC721Token.GetAllLockedNFTs()
}

參數：

無。

傳回值：

成功時，鎖定的不可執行變數替代字物件陣列。

傳回值範例：

[
   {
      "key":"23",
      "valueJson":{
         "AssetType":"otoken",
         "Behavior":[
            "indivisible",
            "singleton",
            "mintable",
            "transferable",
            "lockable",
            "burnable",
            "roles"
         ],
         "CreatedBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "CreationDate":"2023-10-20T12:39:50Z",
         "IsBurned":false,
         "IsLocked":true,
         "Mintable":{
            "Max_mint_quantity":20000
         },
         "On_sale_flag":false,
         "Owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "Price":120,
         "Roles":{
            "minter_role_name":"minter"
         },
         "Symbol":"ART",
         "TokenDesc":"",
         "TokenId":"23",
         "TokenMetadata":{
            "Description":"",
            "Image":"",
            "Painter_name":"",
            "Painting_name":""
         },
         "TokenName":"artcollection",
         "TokenStandard":"erc721+",
         "TokenType":"nonfungible",
         "TokenUnit":"whole",
         "TokenUri":"token1.example.com"
      }
   }
]

GetAllLockedNFTsByOrg

func (t *Controller) GetLockedNFTsByOrg(orgId string, userId ...string) (interface{}, error) {
    auth, err := t.Ctx.ERC721Auth.CheckAuthorization("ERC721TOKEN.GetLockedNFTsByOrg", "TOKEN")
    if err != nil && !auth {
        isCallerTokenSysRoleHolder, error := t.Ctx.ERC721Token.IsCallerTokenSysRoleHolder(constants.Vault)
        if error != nil {
            return nil, error
        }
        if !isCallerTokenSysRoleHolder {
            return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
        }
    }
    return t.Ctx.ERC721Token.GetLockedNFTsByOrg(orgId, userId...)
}

參數：

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

傳回值：

成功時，鎖定的不可執行變數替代字物件陣列。

傳回值範例：

[
   {
      "key":"23",
      "valueJson":{
         "AssetType":"otoken",
         "Behavior":[
            "indivisible",
            "singleton",
            "mintable",
            "transferable",
            "lockable",
            "burnable",
            "roles"
         ],
         "CreatedBy":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "CreationDate":"2023-10-20T12:39:50Z",
         "IsBurned":false,
         "IsLocked":true,
         "Mintable":{
            "Max_mint_quantity":20000
         },
         "On_sale_flag":false,
         "Owner":"oaccount~208e3345ac84b4849f0d2648b2f2f018019886a1230f99304ebff1b6a7733463",
         "Price":120,
         "Roles":{
            "minter_role_name":"minter"
         },
         "Symbol":"ART",
         "TokenDesc":"",
         "TokenId":"23",
         "TokenMetadata":{
            "Description":"",
            "Image":"",
            "Painter_name":"",
            "Painting_name":""
         },
         "TokenName":"artcollection",
         "TokenStandard":"erc721+",
         "TokenType":"nonfungible",
         "TokenUnit":"whole",
         "TokenUri":"token1.example.com"
      }
   }
]