> For the complete documentation index, see [llms.txt](https://aurora-21.gitbook.io/aurora-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aurora-21.gitbook.io/aurora-docs/ji-shu-jia-gou/nft-ji-shu-dui-die.md).

# NFT技術堆疊

Aurora 數字黃金平台採用了 **五級節點 NFT 化設計架構**，將不同等級的節點以 NFT 的形式表示，分別為：**Bronze（青銅）節點**、**Silver（白銀）節點**、**Golden（黃金）節點**、**Diamond（鑽石）節點**、以及**Genesis（創世）節點**。這種分級架構體現了由低至高的節點權限和稀缺性，各級別在**節點運營權限**與**稀有度**上逐級遞增。節點等級越高，其對應的權益（例如收益分潤比例、治理影響力等）也越豐富。

為了強調不同級別節點的**獨特身份與品牌形象**，Aurora 為每一級節點都設計了對應的 **NFT 視覺化形象**。這些節點 NFT 具有明確的主題色調和圖騰符號，使持有者和社群成員能直觀辨識節點等級。此外，節點 NFT 透過區塊鏈上的唯一 ID 和元數據記錄，確保每個節點的**身份不可篡改**且**公開透明**。以下分別介紹各級節點 NFT 的定位：

<div><figure><img src="/files/etUfdarnww5l3KgOxbr6" alt=""><figcaption></figcaption></figure> <figure><img src="/files/0bc8pjHNcYoE3RYupGbJ" alt=""><figcaption></figcaption></figure> <figure><img src="/files/2qrjgn1FShbbBbsZt3Rf" alt=""><figcaption></figcaption></figure> <figure><img src="/files/aFLwf6WVeopWZtBcfI8j" alt=""><figcaption></figcaption></figure> <figure><img src="/files/syQUdsPh7m8zKeTKWMCl" alt=""><figcaption></figcaption></figure></div>

Aurora 黃金 NFT 的智慧合約將基於以太坊 ERC-721 標準，並復用成熟的 OpenZeppelin 合約庫以確保安全可靠。核心的合約繼承關係與組成包括：

**ERC721** – OpenZeppelin 提供的 ERC721 實作，包含 NFT 的基本功能（代幣鑄造、轉移、查詢等）。ERC721 是 NFT 的基礎，實作了 IERC721 介面，是所有非同質化代幣合約的核心父類。

**ERC721URIStorage** – ERC721 的中繼資料擴充，允許為每個代幣儲存獨立的 URI。透過繼承該合約，可以使用 `_setTokenURI(tokenId, uri)` 為每個 NFT 設定中繼資料連結，並覆寫 `tokenURI` 函式。這對於黃金 NFT 很有用，可以為每個實體黃金對應的 NFT 設定指向特定中繼資料 JSON 的 URI。

**Ownable** – OpenZeppelin 的 Ownable 合約，提供所有者權限控制。繼承 Ownable 可以使用 `onlyOwner` 修飾符限制關鍵函式（如鑄造）的呼叫權限。部署合約的帳號預設為 owner，用於管理 NFT 的鑄造與重要設定。在 Aurora 黃金 NFT 中，可用 Ownable 確保只有授權方（如平台多簽帳戶）才能鑄造新 NFT。

**Counters** – OpenZeppelin 的計數器函式庫，用於生成連續的 tokenId。Counters 可以安全地自增 ID，避免重複。合約中通常宣告 `Counters.Counter private _tokenIds;`，在每次 mint 時呼叫 `_tokenIds.increment()` 生成新的 tokenId。如此每個黃金 NFT 都擁有唯一 ID。

**AccessControl（可選）** – 基於角色的存取控制機制。相較於 Ownable 只能有單一管理員，AccessControl 允許定義多種角色（如 MINTER\_ROLE、UPDATER\_ROLE、PAUSER\_ROLE 等）並授權給不同地址。在大型平台中可採用 AccessControl 實現更細粒度的權限管理，例如賦予「鑄造者」與「資料更新者」等角色，不同角色僅能執行其權限範圍內的操作。

**ERC721Enumerable（可選）** – ERC721 的可列舉擴充。繼承 ERC721Enumerable 可追蹤所有 token 的總量（totalSupply），以及依索引列舉每個持有人擁有的 NFT。若需要對所有黃金 NFT 進行索引、批次查詢或與前端互動顯示庫存，Enumerable 介面會很有幫助。然而，其維護額外清單會增加 gas 開銷，在 NFT 數量龐大時需權衡取捨。

**Pausable（可選）** – OpenZeppelin 提供的暫停機制。透過引入 Pausable 合約或直接使用 ERC721Pausable 擴充，可在緊急情況下暫停 NFT 合約的部分功能。例如偵測到系統異常或安全漏洞時，管理員（如擁有 PAUSER\_ROLE 的多簽帳戶）可暫停所有轉移與鑄造操作，以避免損失擴大。恢復正常後可解除暫停。

**ERC721Burnable（可選）** – 提供代幣銷毀功能的擴充。對於黃金 NFT，當對應的實體黃金被提取或銷毀時，可能需要銷毀 NFT 以更新鏈上狀態。繼承 ERC721Burnable 可允許持有人或授權帳戶呼叫 `burn(tokenId)` 銷毀 NFT。需注意銷毀後 NFT 不可復原，應在多簽授權下審慎執行。

以上結構確保合約具備完整的 ERC721 功能，並方便中繼資料管理與權限控制。其中 ERC721、ERC721URIStorage、Ownable、Counters 為基礎組合；依需求亦可引入可暫停與可列舉等特性以增強安全性與可擴充性。

<figure><img src="/files/bwnsKNJ5S7InkUYchs5z" alt=""><figcaption></figcaption></figure>

#### 實作方法

在合約實作過程中，需要撰寫或覆寫部分關鍵函式以滿足黃金 NFT 的業務需求：

**mintNFT(address to, string memory uri)**：自訂鑄造函式，用於建立新的黃金 NFT 並分配給地址 `to`。典型實作為先生成新的 tokenId（使用 Counters 自增或類似機制），再呼叫 `_mint(to, tokenId)` 鑄造 NFT，最後呼叫 `_setTokenURI(tokenId, uri)` 將對應的中繼資料 URI 綁定至該 token。基於安全性考量，此函式應僅限具備特定權限的帳戶呼叫（例如使用 `onlyOwner` 或 `onlyRole(MINTER_ROLE)` 修飾）。範例程式碼如下（省略權限控制邏輯）：

```solidity
function mintNFT(address to, string memory tokenURI) public onlyOwner {
    uint256 tokenId = _tokenIds.current();
    _tokenIds.increment();
    _mint(to, tokenId);
    _setTokenURI(tokenId, tokenURI);
}
```

上述流程確保每鑄造一個 NFT，便會建立一個新的唯一 ID，並將事先準備好的中繼資料 URI 與其關聯。如此，每個 NFT 代表特定實體黃金，並擁有獨立的中繼資料描述。

**tokenURI(uint256 tokenId)**：回傳指定 NFT 的中繼資料 URI。ERC721 標準定義了 `tokenURI` 用於提供鏈上儲存的中繼資料連結。預設情況下，OpenZeppelin 的 ERC721 實作會將 `_baseURI()` 與 tokenId 串接得到完整 URI。若使用 ERC721URIStorage 擴充，`tokenURI` 函式已在擴充中被覆寫為從內部映射 `_tokenURIs` 取得每個 token 的 URI。開發者可依需求選擇實作方式：

* 若所有 NFT 共用相同的基礎 URI 路徑（例如皆託管於同一 IPFS 資料夾或 HTTP 伺服器路徑），可實作 `_baseURI()` 回傳該基礎路徑。如此 `tokenURI` 會自動回傳 `baseURI + tokenId` 形式的連結。需注意預設 `_baseURI` 在 ERC721 中回傳空字串，必須在合約中 override 提供實際位址。
* 若每個 NFT 的中繼資料 URI 差異較大或不規則（如儲存在不同位址），則採用 ERC721URIStorage，在鑄造時透過 `_setTokenURI` 為每個 tokenId 個別設定 URI。
* 開發者亦可選擇覆寫 `tokenURI` 函式，自訂回傳邏輯，例如結合動態資料，或直接回傳 Base64 編碼的 JSON data URI 以實現鏈上中繼資料。

**\_setTokenURI(uint256 tokenId, string memory uri)**：將特定 token 的中繼資料 URI 儲存在合約中，該函式由 ERC721URIStorage 提供。通常在 `mintNFT` 中緊接 `_mint` 後呼叫，用於登記 NFT 的中繼資料位置。對於 Aurora 黃金 NFT，每次鑄造時會呼叫 `_setTokenURI` 綁定包含該黃金資產資訊的 JSON 檔案位址。後續若需更新 NFT 的中繼資料（如動態欄位變化），亦可在具備權限的前提下呼叫 `_setTokenURI` 修改 URI 指向新版 JSON。

**\_baseURI()**：ERC721 合約中的內部函式，可選擇性覆寫。其用於回傳中繼資料 URI 的基礎部分。若 Aurora 黃金 NFT 採用統一的 URI 前綴（例如所有中繼資料 JSON 儲存在 IPFS 同一目錄或統一網域），可設定一個私有變數儲存 baseURI，並 override `_baseURI()` 回傳該變數。如此在呼叫 `tokenURI(tokenId)` 時，會自動將 tokenId 附加於 baseURI 後形成完整連結。

**其他函式與覆寫**：

* **核准與轉移**：ERC721 已內建標準的轉移與授權函式（`transferFrom`、`safeTransferFrom`、`approve`、`setApprovalForAll` 等），通常無需重寫。但在 Aurora 黃金 NFT 情境下，可能需限制轉移條件（例如僅在資產處於特定狀態時允許轉移），可透過覆寫 `_beforeTokenTransfer` 鉤子實現檢查。
* **\_beforeTokenTransfer(address from, address to, uint256 tokenId, uint256 batchSize)**：OpenZeppelin ERC721 提供的鉤子，於每次轉移、鑄造、銷毀時觸發。若合約繼承 ERC721Pausable 或 ERC721Enumerable 等擴充，需同時呼叫各父類的 `_beforeTokenTransfer` 以確保暫停與列舉功能正常運作。
* **銷毀函式**：若引入 ERC721Burnable 擴充，合約將提供 `burn(tokenId)` 供 NFT 持有人或授權人銷毀 NFT。當實體黃金被提取銷毀時，可由具權限帳戶呼叫 burn 移除對應 NFT，並配合鏈下紀錄標示該 NFT 作廢。
* **supportsInterface(bytes4 interfaceId)**：若合約繼承多個父類（如 ERC721、ERC721Enumerable、AccessControl），需適當 override `supportsInterface` 宣告支援的介面 ID，以確保 ERC165 查詢正確。

#### 中繼資料綁定

**靜態中繼資料映射**：每個黃金 NFT 在鑄造時需綁定與實體黃金對應的靜態資訊，如產地、批次、規格等。這些資料通常於實物入庫時即確定，適合作為 NFT 中繼資料的固定屬性。ERC721 中繼資料規範採用 JSON 格式，包含 name、description、image、attributes 等欄位。例如：

```json
{
  "name": "Aurora Gold #0001",
  "description": "Aurora 平台託管的實體黃金憑證 NFT，代表一根 1kg Au99.99 金條。",
  "image": "ipfs://.../gold_bar.png",
  "attributes": [
    { "trait_type": "Origin", "value": "South Africa" },
    { "trait_type": "Batch", "value": "2023-07-AU-001" },
    { "trait_type": "Weight", "value": "1000g" },
    { "trait_type": "Purity", "value": "99.99%" }
  ]
}
```

上述 JSON 展示了靜態中繼資料範例。一旦這些資訊隨 NFT 鑄造寫入鏈下 JSON 並關聯至 NFT，便保持不變，確保憑證資訊的完整性與不可竄改性。

**動態資料映射**：部分與黃金相關的資料會隨時間變化，例如託管狀態與庫存數量。可透過更新中繼資料或鏈上狀態映射反映最新狀況：

* 作為中繼資料屬性：更新 JSON 中 attributes 的 value，必要時更換 tokenURI。
* 鏈上儲存映射：於合約內維護狀態映射，並由前端或動態 tokenURI 組合顯示。
* 動態 NFT 標準：可搭配 EIP-4906 的 MetadataUpdate 事件通知前端刷新。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aurora-21.gitbook.io/aurora-docs/ji-shu-jia-gou/nft-ji-shu-dui-die.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.