ERC-721 的鷹架式 TypeScript NFT 專案
Blockchain App Builder 會從您的 NFT 規格檔案進行輸入，並產生功能完整的鷹架式鏈碼專案。
專案會自動產生 NFT 生命週期類別和函數，包括 CRUD 和非 CRUD 方法，以及代碼化 SDK。系統會自動支援引數驗證、封送處理 (Marshall) / 取消封送處理 (unmarshal) 以及通透保存功能。
如需結構化專案和與 NFT 無直接相關之方法的相關資訊，請參閱結構化 TypeScript 鏈碼專案。
參考資料：
Model
每個記號化模型類別都會擴充 OchainModel 類別。「通透持續性功能 (Transparent Persistence Capability)」或簡化的 ORM 會擷取到 OchainModel 類別中。
import * as yup from 'yup';
import { Id, Mandatory, Validate, Default, Embedded, Derived, ReadOnly } from '../../lib/decorators';
import { OchainModel } from '../../lib/ochain-model';
import { STRATEGY } from '../../lib/utils';
import { EmbeddedModel } from '../../lib/ochain-embedded-model';
export class ArtCollectionMetadata extends EmbeddedModel<ArtCollectionMetadata> {
@Validate(yup.string())
public painting_name: string;
@Validate(yup.string())
public description: string;
@Validate(yup.string())
public image: string;
@Validate(yup.string())
public painter_name: string;
}
@Id('tokenId')
export class ArtCollection extends OchainModel<ArtCollection> {
public readonly assetType = 'otoken';
@Mandatory()
@Validate(yup.string().required().matches(/^[A-Za-z0-9][A-Za-z0-9_-]*$/).max(16))
public tokenId: string;
@ReadOnly('artcollection')
public tokenName: string;
@Validate(yup.string().trim().max(256))
public tokenDesc: string;
@ReadOnly('ART')
public symbol: string;
@ReadOnly('erc721+')
public tokenStandard: string;
@ReadOnly('nonfungible')
public tokenType: string;
@ReadOnly('whole')
public tokenUnit: string;
@ReadOnly(["indivisible","singleton","mintable","transferable","burnable","roles"])
public behaviors: string[];
@ReadOnly({minter_role_name: "minter"})
public roles: object;
@ReadOnly({max_mint_quantity: 20000})
public mintable: object;
@Validate(yup.string())
public owner: string;
@Validate(yup.string())
public createdBy: string;
@Validate(yup.string())
public transferredBy: string;
@Validate(yup.string())
public creationDate: string;
@Validate(yup.string())
public transferredDate: string;
@Validate(yup.bool())
public isBurned: boolean;
@Validate(yup.string())
public burnedBy: string;
@Validate(yup.string())
public burnedDate: string;
@Validate(yup.string().max(2000))
public tokenUri: string;
@Embedded(ArtCollectionMetadata)
public metadata: ArtCollectionMetadata;
@Validate(yup.number())
public price: number;
@Validate(yup.boolean())
public on_sale_flag: boolean;
}
控制器
main 控制器類別會擴充 OchainController 類別。只有一個主要控制器。
export class DigiCurrCCController extends OchainController{您可以建立不限數目的類別、函數或檔案，但只能呼叫在 main Controller 類別中定義的方法。其他方法則會隱藏。
您可以使用記號 SDK 方法，為您的商業應用程式撰寫自訂方法。
自動產生的 NFT 方法
Blockchain App Builder 會自動產生支援 NFT 和 NFT 生命週期的方法。您可以使用這些方法來初始化 NFT、管理角色和帳戶，以及完成其他 NFT 生命週期作業，而無需進行任何其他編碼。控制器方法必須要有 @Validator(...params) 修飾器才能呼叫。
存取控制管理方法
-
addTokenAdmin - 此方法會將使用者新增為鏈碼的
Token Admin。只有鏈碼的Token Admin才能呼叫此方法。 -
removeTokenAdmin - 此方法會移除使用者作為鏈碼的
Token Admin。只有鏈碼的Token Admin才能呼叫此方法。 -
isTokenAdmin - 如果函數的呼叫程式是
Token Admin，則此方法會傳回布林值true，否則會傳回false。Token Admin可以對區塊鏈網路中的任何其他使用者呼叫此功能。其他使用者只能在自己的帳戶上呼叫此方法。 -
getAllTokenAdmins - 此方法會傳回鏈碼為
Token Admin的所有使用者清單。只有鏈碼的Token Admin才能呼叫此方法。
權杖組態管理方法
-
init - 建立鏈碼時會呼叫這個方法。每個
Token Admin都是由adminList參數中的userId和orgId資訊來識別。userId是執行處理擁有者或登入執行處理之使用者的使用者名稱或電子郵件 ID。orgId是目前網路組織中使用者的成員服務提供者 (MSP) ID。第一次部署鏈碼時，必須輸入adminList參數。如果您要升級鏈碼，請傳送空白清單 ([])。升級時會忽略adminList參數中的任何其他資訊。 -
getAllTokens - 此方法會傳回狀態資料庫中儲存的所有記號資產。只有鏈碼的
Token Admin才能呼叫此方法。此方法使用 Berkeley DB SQL RTF 查詢，而且只能在連線至遠端 Oracle Blockchain Platform 網路時呼叫。 -
getAllTokensByUser - 此方法會傳回指定使用者擁有的所有權杖資產。此方法使用 Berkeley DB SQL RTF 查詢，而且只能在連線至遠端 Oracle Blockchain Platform 網路時呼叫。只有鏈碼的
Token Admin或帳戶擁有者才能呼叫此方法。 -
getTokenById - 如果狀態資料庫中有記號，這個方法會傳回一個記號物件。只有鏈碼的
Token Admin或記號擁有者才能呼叫此方法。 -
getTokenHistory - 這個方法會傳回所指定記號 ID 的歷史記錄。此為非同步方法。只有在連線至遠端 Oracle Blockchain Platform 網路時才能呼叫此方法。任何人都可以呼叫這個方法。
-
getTokenObject - 此公用程式方法會傳回指定記號 ID 之記號的執行處理。許多自動產生的方法都會使用此方法來擷取記號物件。您可以視需要從自訂方法呼叫此方法。當您建立記號化資產或類別時，請使用對應的
Token類別更新切換案例，以傳回正確的記號物件。在規格檔案中建立權杖化資產時，區塊鏈 App 產生器中的ochain sync命令會自動建立切換大小寫。這個方法沒有@Validator()方法修飾器，這表示這個方法不能直接呼叫，而且只能從其他方法呼叫。 -
ownerOf - 此方法會傳回所指定權杖 ID 之擁有者的帳戶 ID。任何人都可以呼叫這個方法。
-
name - 這個方法會傳回記號類別的名稱。任何人都可以呼叫這個方法。
-
symbol - 這個方法會傳回記號類別的符號。任何人都可以呼叫這個方法。
-
tokenURI - 此方法會傳回所指定記號的 URI。任何人都可以呼叫這個方法。
-
totalSupply - 此方法會傳回所提示記號的總數。只有鏈碼的
Token Admin才能呼叫此方法。 -
totalNetSupply - 此方法會傳回所提示記號的總數減去已燒記號的數目。只有鏈碼的
Token Admin才能呼叫此方法。
帳戶管理方法
-
createAccount - 這個方法會為指定的使用者與記號建立帳號。必須為任何需要記號的使用者建立帳戶。帳戶會追蹤使用者擁有的 NFT 數目。使用者必須在網路中擁有帳戶，才能完成權杖相關作業。每個使用者只能建立一個 NFT 帳戶。
帳戶 ID 是英數字元集，前面加上
oaccount~，後面接著目前網路組織中使用者之成員服務提供者 ID (orgId) 的 SHA-256 雜湊、執行處理擁有者的使用者名稱或電子郵件 ID (userId) 或登入執行處理的使用者，以及常數字串nft。只有鏈碼的Token Admin才能呼叫此方法。 -
balanceOf - 此方法會傳回指定使用者所保留的 NFT 總數。只有鏈碼的
Token Admin或帳戶擁有者才能呼叫此方法。 -
getAllAccounts - 這個方法會傳回所有帳號的清單。只有鏈碼的
Token Admin才能呼叫此方法。此方法使用 Berkeley DB SQL RTF 查詢，而且只能在連線至遠端 Oracle Blockchain Platform 網路時呼叫。 -
getAccountByUser - 此方法會傳回指定使用者的帳戶詳細資料。只有鏈碼的
Token Admin或帳戶的Account Owner才能呼叫此方法。 -
getUserByAccountId - 此方法會傳回指定帳戶的使用者詳細資料。任何使用者都可以呼叫這個方法。
-
getAccountHistory - 此方法會傳回指定使用者的帳戶歷史記錄。此為非同步方法。只有鏈碼的
Token Admin或帳戶擁有者才能呼叫此方法。
角色管理方法
-
addRole - 此方法會將角色新增至指定的使用者。只有鏈碼的
Token Admin才能呼叫此方法。 -
removeRole - 此方法會從指定的使用者移除角色。只有鏈碼的
Token Admin才能呼叫此方法。 -
getAccountsByRole - 此方法會傳回指定角色的所有帳戶 ID 清單。只有鏈碼的
Token Admin才能呼叫此方法。 -
getUsersByRole - 此方法會傳回指定角色的所有使用者清單。只有鏈碼的
Token Admin才能呼叫此方法。 -
isInRole - 此方法會傳回布林值，以指出使用者是否具有指定的角色。只有鏈碼的
Token Admin或帳戶的Account Owner才能呼叫此方法。
交易歷史記錄管理的方式
-
getAccountTransactionHistory - 此方法會傳回指定使用者的帳戶交易歷史記錄。此為非同步方法。只有鏈碼的
Token Admin或帳戶擁有者才能呼叫此方法。 -
getAccountTransactionHistoryWithFilters - 此方法會傳回依
PageSize、Bookmark、startTime和endTime篩選之指定使用者的帳戶交易歷史記錄。此為非同步方法。只有在連線至遠端 Oracle Blockchain Platform 網路時才能呼叫此方法。只有鏈碼的Token Admin或帳戶擁有者才能呼叫此方法。 -
getTransactionById - 此方法會傳回指定交易 ID 的交易記錄。此為非同步方法。只有鏈碼的
Token Admin或帳戶擁有者才能呼叫此方法。 -
deleteHistoricalTransactions - 此方法會刪除狀態資料庫中早於指定時間戳記的交易。此為非同步方法。只有鏈碼的
Token Admin才能呼叫此方法。
權杖行為管理方法 - 可變行為
-
create<Token Name>Token - 此方法會建立 (提示) NFT。資產和關聯的性質會儲存在狀態資料庫中。此交易的來電者必須有權杖帳戶。此交易的呼叫者會成為 NFT 的擁有者。如果記號規格檔案包含
behaviors的roles區段和roles的minter_role_name特性，則交易的呼叫者必須具有 minter 角色。否則，任何來電者都可以提示 NFT。 -
update<Token Name>Token - 此方法會更新記號特性。只有權杖的擁有者或建立者能夠呼叫此方法。記號資產建立之後，只有記號擁有者可以更新記號自訂特性。如果使用者同時是權杖擁有者和權杖建立者，他們也可以更新
TokenDesc特性。無法更新權杖描述資料。即使您只想更新特定特性，也必須將所有記號特性傳送給此方法。
權杖行為管理方法 - 可轉移行為
-
safeTransferFrom - 這是非同步函數。這個方法會將指定 NFT 的所有權從呼叫者轉移到另一個帳戶。此方法包含下列驗證：
- 記號存在且未燒錄。
- 寄件人帳戶與接收者帳戶已存在，且不是相同的帳戶。
- 寄件者帳戶擁有權杖。
- 函數的呼叫程式是寄件者。
-
transferFrom - 這是非同步函數。此方法會將指定 NFT 的所有權從寄件者帳戶轉移至接收者帳戶。呼叫者必須負責傳送正確的參數。任何使用者都可以呼叫此方法，而不只是記號擁有者。此方法包含下列驗證：
- 記號存在且未燒錄。
- 寄件人帳戶與接收者帳戶已存在，且不是相同的帳戶。
- 寄件者帳戶擁有權杖。
記號行為管理方法 - 可燃行為
-
burn - 此方法會停用或燒錄呼叫者帳戶中指定的 NFT。此方法的呼叫者必須有帳戶。除非記號規格檔案包含
burnable行為，否則無法燒錄記號。如果未在規格檔案的roles區段中指定burner_role_name特性，則記號的擁有者可以燒錄記號。如果在roles區段中指定了burner_role_name特性，則使用者若指定了也是記號之探勘器 (建立者) 或擁有者的燃燒器角色，即可燒錄記號。 -
burnNFT - 此方法會停用或燒錄呼叫者帳戶中指定的 NFT，並傳回記號物件和記號歷史記錄。此方法的呼叫者必須有帳戶。除非記號規格檔案包含
burnable行為，否則無法燒錄記號。如果未在規格檔案的roles區段中指定burner_role_name特性，則記號的擁有者可以燒錄記號。如果在roles區段中指定了burner_role_name特性，則使用者若指定了也是記號之探勘器 (建立者) 或擁有者的燃燒器角色，即可燒錄記號。
自訂方式
您可以使用記號 SDK 方法，為您的商業應用程式撰寫自訂方法。
下列範例顯示如何在自訂方法中使用記號 SDK 方法。呼叫 sell 方法時，會針對指定的價格張貼記號以供銷售。
@Validator(yup.string(), yup.number())
public async sell(token_id: string, selling_price: number) {
try {
const token = await this.Ctx.ERC721Token.get(token_id);
const t = new ArtCollection(token)
/** * price is a custom asset
attribute to set the price of a non-fungible token in the
marketplace */
t.price = selling_price;
/** * on_sale_flag is a
custom asset attribute that maintains non-fungible token selling status in the
marketplace */
t.on_sale_flag = true;
await this.Ctx.ERC721Token.updateToken(t);
let msg = `Token ID : '${token_id}' has been posted for selling in the marketplace'`;
return {msg}
} catch(error) {
throw new Error(error.message);
}
}NFT SDK 方法
存取控制管理方法
NFT SDK 提供存取控制功能。某些方法只能由記號的
Token Admin 或 Account Owner 呼叫。您可以使用此功能來確保只由預期的使用者執行作業。任何未授權的存取都會導致錯誤。若要使用存取控制功能，請從 ../lib/erc721-auth 模組匯入 Authorization 類別。import { ERC721Authorization } from '../lib/erc721-auth';-
addAdmin - 此方法會將使用者新增為權杖鏈碼的
Token Admin。 -
removeAdmin - 此方法會移除使用者作為記號鏈碼的
Token Admin。 -
isUserTokenAdmin - 如果函數的呼叫程式是
Token Admin，此方法會傳回布林值true。否則，方法會傳回false。這是非同步靜態函數。 -
getAllAdmins - 此方法會傳回所有
Token Admin使用者的清單。 -
checkAuthorization - 使用此方法將存取控制檢查新增至作業。這是非同步函數。大多數自動產生的方法都包括存取控制。某些記號方法只能由記號的
ERC721Admin或Account Owner執行，或由MultipleAccountOwner針對具有多個帳戶的使用者執行。checkAuthorization方法是Authorization類別的一部分，您可以透過Ctx物件存取此類別。存取控制對應在../lib/constant.ts檔案中說明，如下文所示。您可以編輯../lib/constant.ts檔案來修改存取控制。若要使用自己的存取控制或停用存取控制，請從自動產生的控制器方法和自訂方法中移除存取控制碼。export const TOKENACCESS = { ADMIN: { isUserTokenAdmin: ['Admin', 'MultipleAccountOwner'], addAdmin: ['Admin'], removeAdmin: ['Admin'], getAllAdmins: ['Admin'], }, TOKEN: { save: ['Admin'], getAllTokens: ['Admin'], get: ['Admin'], update: ['Admin'], getDecimals: ['Admin'], getTokensByName: ['Admin'], addRoleMember: ['Admin'], removeRoleMember: ['Admin'], isInRole: ['Admin', 'AccountOwner'], getTotalMintedTokens: ['Admin'], getNetTokens: ['Admin'], }, ROLE: { getAccountsByRole: ['Admin'], getUsersByRole: ['Admin'], }, TRANSACTION: { deleteTransactions: ['Admin'], }, ACCOUNT: { createAccount: ['Admin'], getAllAccounts: ['Admin'], getAccountsByUser: ['Admin', 'MultipleAccountOwner'], getAccount: ['Admin', 'AccountOwner'], history: ['Admin', 'AccountOwner'], getAccountTransactionHistory: ['Admin', 'AccountOwner'], getAccountBalance: ['Admin', 'AccountOwner'], getAccountOnHoldBalance: ['Admin', 'AccountOwner'], getOnHoldIds: ['Admin', 'AccountOwner'], }, ERC721ADMIN: { isUserTokenAdmin: ['Admin'], addAdmin: ['Admin'], removeAdmin: ['Admin'], getAllAdmins: ['Admin'], }, ERC721TOKEN: { getAllTokens: ['Admin'], getAllTokensByUser: ['Admin', 'AccountOwner'], get: ['Admin', TOKEN_OWNER], getTokensByName: ['Admin'], addRoleMember: ['Admin'], removeRoleMember: ['Admin'], isInRole: ['Admin', 'AccountOwner'], totalSupply: ['Admin'], totalNetSupply: ['Admin'], history: ['Admin'], }, ERC721ROLE: { getAccountsByRole: ['Admin'], getUsersByRole: ['Admin'], }, ERC721TRANSACTION: { deleteTransactions: ['Admin'], }, ERC721ACCOUNT: { createAccount: ['Admin'], getAllAccounts: ['Admin'], getAccountsByUser: ['Admin', 'MultipleAccountOwner'], history: ['Admin', 'AccountOwner'], getAccountTransactionHistory: ['Admin', 'AccountOwner'], getAccountTransactionHistoryWithFilters: ['Admin', 'AccountOwner'], balanceOf: ['Admin', 'MultipleAccountOwner'], } }
權杖組態管理方法
權杖組態管理方法是以 ERC-721 標準為基礎。若要使用記號組態管理方法，請從 ../lib/erc721-token 模組匯入 Token 類別。
-
createToken - 這個方法會建立一個記號，並將它的特性儲存到狀態資料庫中。只有具備 minter 角色的使用者才能呼叫此方法。這是非同步函數。
-
getAllTokens - 此方法會傳回狀態資料庫中儲存的所有記號資產。此方法使用 Berkeley DB SQL RTF 查詢，而且只能在連線至遠端 Oracle Blockchain Platform 網路時呼叫。這是非同步靜態函數。
-
getAllTokensByUser - 此方法會傳回指定帳戶 ID 擁有的所有記號。這是非同步靜態函數。
-
getTokenUri - 此方法會傳回所指定記號的 URI。這是非同步靜態函數。
-
history - 此方法會傳回指定記號的歷史記錄。這是非同步靜態函數。
-
get - 如果指定的記號物件存在於狀態資料庫中，此方法會傳回該物件。這是非同步靜態函數。
-
ownerOf - 此方法會傳回所指定記號之擁有者的帳戶 ID。這是非同步靜態函數。
-
symbol - 這個方法會傳回記號類別的符號。
-
tokenUri - 此方法會傳回所指定記號的 URI。這是非同步靜態函數。
-
totalSupply - 此方法會傳回所提示的 NFT 總數。這是非同步函數。
-
updateToken - 此方法會更新記號特性。權杖的擁有者或建立者才能呼叫此方法。記號資產建立之後，只有記號擁有者可以更新記號自訂特性。如果使用者同時是權杖擁有者和權杖建立者，他們也可以更新
TokenDesc特性。無法更新權杖描述資料。即使您只想更新特定特性，也必須將所有記號特性傳送給此方法。這是非同步函數。 -
getByRange - 此方法會在內部呼叫結構
getStateByRange方法。即使分類帳傳回任何具有指定 ID 的資產，此方法仍會將資產轉換成呼叫者資產類型。這是非同步靜態函數。@validator(yup.string(), yup.string()) public async getDigiCurrGetByRange(startId: string, endId: string) { return await this.Ctx.ERC721TOken.getByRange(startId, endId, PaintingNft); } -
isTokenType - 此方法指出具有指定 ID 的記號資產是否存在。這是非同步靜態函數。
帳戶管理方法
-
generateAccountId - 此方法會傳回帳戶 ID，此 ID 是透過串連成員服務提供者 ID (
orgId) 和使用者名稱或電子郵件 ID (userId) 所形成，然後建立 SHA-256 雜湊。 -
createAccount - 這個方法會為指定的使用者與記號建立帳號。必須為任何需要記號的使用者建立帳戶。帳戶會追蹤使用者擁有的 NFT 數目。使用者必須在網路中擁有帳戶，才能完成權杖相關作業。每個使用者只能建立一個 NFT 帳戶。
帳戶 ID 是英數字元集，前面加上
oaccount~，後面接著目前網路組織中使用者之成員服務提供者 ID (orgId) 的 SHA-256 雜湊、執行處理擁有者的使用者名稱或電子郵件 ID (userId) 或登入執行處理的使用者，以及常數字串nft。只有鏈碼的Token Admin才能呼叫此方法。 -
balanceOf - 此方法會傳回指定使用者保留的 NFT 總數。
-
getAllAccounts - 這個方法會傳回所有帳號的清單。此方法使用 Berkeley DB SQL RTF 查詢，而且只能在連線至遠端 Oracle Blockchain Platform 網路時呼叫。
-
getAccountByUser - 此方法會傳回指定帳戶的使用者詳細資料。只有鏈碼的
Token Admin或帳戶的Account Owner才能呼叫此方法。 -
getUserByAccountId - 此方法會傳回指定帳戶的使用者詳細資料。
-
history - 此方法會傳回指定帳戶的帳戶歷史記錄詳細資料陣列。
-
getAccountWithStatusByUser - 此方法會傳回指定帳戶的使用者詳細資料，包括帳戶狀態。只有鏈碼的
Token Admin或帳戶的Account Owner才能呼叫此方法。
角色管理方法
-
addRoleMember - 此方法會新增角色至指定的使用者和記號。帳戶 ID 的形成方式是建立鏈結成員服務提供者 ID (
orgId) 的 SHA-256 雜湊，以及使用者名稱或電子郵件 ID (userId)。這是非同步函數。 -
removeRoleMember - 這個方法會從指定的使用者和記號中移除角色。帳戶 ID 的形成方式是建立鏈結成員服務提供者 ID (
orgId) 的 SHA-256 雜湊，以及使用者名稱或電子郵件 ID (userId)。這是非同步函數。 -
getAccountsByRole - 此方法會傳回指定角色的所有帳戶 ID 清單。
-
getUsersByRole - 此方法會傳回指定角色的所有使用者清單。
-
isInRole - 此方法會傳回布林值，指示使用者和記號是否具有指定的角色。帳戶 ID 的形成方式是建立鏈結成員服務提供者 ID (
orgId) 的 SHA-256 雜湊，以及使用者名稱或電子郵件 ID (userId)。這是非同步函數。
交易歷史記錄管理的方式
-
getAccountTransactionHistory - 此方法會傳回指定帳戶的交易記錄詳細資料陣列。
-
getAccountTransactionHistoryWithFilters - 此方法會傳回依
PageSize、Bookmark、startTime和endTime篩選之指定使用者的帳戶交易歷史記錄。只有在連線至遠端 Oracle Blockchain Platform 網路時才能呼叫此方法。 -
getTransactionById - 此方法會傳回
Transaction資產的歷史記錄。 -
deleteHistoricalTransactions - 此方法會從狀態資料庫中刪除早於指定日期的交易。
權杖行為管理 - 可變行為
-
getMaxMintQuantity - 此方法會傳回記號的最大可移動數量。如果規格檔案中未設定
max_mint_quantity行為，則預設值為 0，且可提示不限數目的記號。 -
getTotalMintedTokens - 此方法會針對指定的記號，傳回系統中可用的記號總數。可用的記號網路數目是經過提示的記號總數減去已燒錄的記號數目。這是非同步函數。
權杖行為管理 - 可傳輸行為
-
safeTransferFrom - 這是非同步函數。這個方法會將指定 NFT 的所有權從呼叫者轉移到另一個帳戶。此方法包含下列驗證：
- 記號存在且未燒錄。
- 寄件人帳戶與接收者帳戶已存在，且不是相同的帳戶。
- 寄件者帳戶擁有權杖。
- 函數的呼叫程式是寄件者。
-
transferFrom - 這是非同步函數。此方法會將指定 NFT 的所有權從寄件者帳戶轉移至接收者帳戶。呼叫者必須負責傳送正確的參數。任何使用者都可以呼叫此方法，而不只是記號擁有者。此方法包含下列驗證：
- 記號存在且未燒錄。
- 寄件人帳戶與接收者帳戶已存在，且不是相同的帳戶。
- 寄件者帳戶擁有權杖。
權杖行為管理 - 可燒錄行為