@ocap/client 1.25.6 → 1.26.0

package/docs/how-to-guides-manage-assets.zh-TW.md

@@ -1,10 +1,10 @@
 # 管理資產 (NFT)
 
-本指南提供了使用 OCAP Client 管理非同質化代幣 (NFT)（也稱為資產）整個生命週期的完整演練。您將學習如何從頭開始創建新資產、更新其屬性、建立資產工廠以進行標準化鑄造，以及從該工廠獲取新資產。
+本指南將全面介紹如何使用 OCAP Client 管理非同質化代幣 (NFT) 的整個生命週期，NFT 也稱為資產。您將學習如何從頭開始建立新資產、更新其屬性、建立資產工廠以進行標準化鑄造，以及從該工廠獲取新資產。
 
-## 創建新資產
+## 建立新資產
 
-您可以使用 `createAsset` 方法在區塊鏈上創建一個獨一無二的獨立資產。每個資產都會被分配一個根據其初始屬性派生而來的唯一鏈上地址。
+您可以使用 `createAsset` 方法在區塊鏈上建立一個獨特的獨立資產。每個資產都會被分配一個獨一無二的鏈上地址，該地址由其初始屬性衍生而來。
 
 ```javascript icon=logos:javascript
 const { wallet } = getWallet(); // 使用者的錢包物件
@@ -12,11 +12,11 @@ const { wallet } = getWallet(); // 使用者的錢包物件
 async function createNewAsset() {
   try {
     const [hash, address] = await client.createAsset({
-      moniker: '我的獨特數位藝術品',
+      moniker: 'My Unique Digital Artwork',
       data: {
         typeUrl: 'json',
         value: { 
-          description: '由藝術家 X 創作的獨一無二的作品。',
+          description: 'A one-of-a-kind piece created by Artist X.',
           imageUrl: 'https://example.com/path/to/image.png',
         },
       },
@@ -25,11 +25,11 @@ async function createNewAsset() {
       wallet: wallet,
     });
 
-    console.log(`資產創建交易已發送：${hash}`);
-    console.log(`新資產地址：${address}`);
+    console.log(`Asset creation transaction sent: ${hash}`);
+    console.log(`New asset address: ${address}`);
     return address;
   } catch (error) {
-    console.error('創建資產時出錯：', error);
+    console.error('Error creating asset:', error);
   }
 }
 
@@ -42,8 +42,8 @@ createNewAsset();
   <x-field data-name="moniker" data-type="string" data-required="true" data-desc="資產的名稱。"></x-field>
   <x-field data-name="parent" data-type="string" data-default="''" data-required="false" data-desc="父資產的地址（如果有的話）。"></x-field>
   <x-field data-name="data" data-type="object" data-required="true" data-desc="資產的資料負載，必須包含 typeUrl 和 value。"></x-field>
-  <x-field data-name="readonly" data-type="boolean" data-default="false" data-required="false" data-desc="若為 true，則資產在創建後無法更新。"></x-field>
-  <x-field data-name="transferrable" data-type="boolean" data-default="true" data-required="false" data-desc="若為 true，則資產可以轉移到另一個帳戶。"></x-field>
+  <x-field data-name="readonly" data-type="boolean" data-default="false" data-required="false" data-desc="若為 true，資產在建立後無法更新。"></x-field>
+  <x-field data-name="transferrable" data-type="boolean" data-default="true" data-required="false" data-desc="若為 true，資產可以轉移到另一個帳戶。"></x-field>
   <x-field data-name="ttl" data-type="number" data-default="0" data-required="false" data-desc="資產首次消費後的存活時間（以秒為單位）。"></x-field>
   <x-field data-name="display" data-type="object" data-required="false" data-desc="包含資產顯示資訊的物件。"></x-field>
   <x-field data-name="endpoint" data-type="object" data-required="false" data-desc="包含資產端點詳細資訊的物件。"></x-field>
@@ -62,7 +62,7 @@ createNewAsset();
 
 ## 更新現有資產
 
-如果資產在創建時設定了 `readonly: false`，您可以使用 `updateAsset` 方法修改其 `moniker` 和 `data` 欄位。資產透過其唯一地址進行標識。
+如果資產在建立時設定為 `readonly: false`，您可以使用 `updateAsset` 方法修改其 `moniker` 和 `data` 欄位。資產透過其唯一的地址來識別。
 
 ```javascript icon=logos:javascript
 const { wallet } = getWallet(); // 使用者的錢包物件
@@ -72,20 +72,20 @@ async function updateExistingAsset() {
   try {
     const hash = await client.updateAsset({
       address: assetAddress,
-      moniker: '我更新後的數位藝術品',
+      moniker: 'My Updated Digital Artwork',
       data: {
         typeUrl: 'json',
         value: { 
-          description: '我的獨特作品的更新描述。',
+          description: 'An updated description for my unique piece.',
           imageUrl: 'https://example.com/path/to/new_image.png',
         },
       },
       wallet: wallet,
     });
 
-    console.log(`資產更新交易已發送：${hash}`);
+    console.log(`Asset update transaction sent: ${hash}`);
   } catch (error) {
-    console.error('更新資產時出錯：', error);
+    console.error('Error updating asset:', error);
   }
 }
 
@@ -97,8 +97,8 @@ updateExistingAsset();
 <x-field-group>
   <x-field data-name="address" data-type="string" data-required="true" data-desc="要更新的資產的鏈上地址。"></x-field>
   <x-field data-name="moniker" data-type="string" data-required="true" data-desc="資產的新名稱。"></x-field>
-  <x-field data-name="data" data-type="object" data-required="true" data-desc="資產的更新資料負載。"></x-field>
-  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="當前資產擁有者的錢包物件。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="true" data-desc="資產更新後的資料負載。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="目前資產擁有者的錢包物件。"></x-field>
 </x-field-group>
 
 ### 返回值
@@ -109,16 +109,16 @@ updateExistingAsset();
 
 ---
 
-## 創建資產工廠
+## 建立資產工廠
 
-資產工廠是用於創建多個相似資產的範本。它定義了鑄造新資產的結構、規則和邏輯，這比單獨創建每個資產更有效率。這非常適合用於發行活動門票、證書或收藏品等用例。
+資產工廠是建立多個相似資產的範本。它定義了鑄造新資產的結構、規則和邏輯，比單獨建立每個資產更有效率。這對於發行活動門票、證書或收藏品等使用場景非常理想。
 
 ```javascript icon=logos:javascript
 const { wallet } = getWallet(); // 工廠擁有者的錢包
 
 const factoryDefinition = {
-  name: '會議門票工廠',
-  description: '為 2024 年技術大會鑄造門票。',
+  name: 'Conference Ticket Factory',
+  description: 'Mints tickets for the 2024 Tech Conference.',
   limit: 1000, // 最多可鑄造 1000 張門票
   input: {
     // 定義鑄造資產所需的資料
@@ -130,8 +130,8 @@ const factoryDefinition = {
   },
   output: {
     // 定義鑄造資產的結構
-    moniker: '{{attendeeName}} 的門票',
-    description: '2024 年技術大會的 {{ticketType}} 入場券。',
+    moniker: 'Ticket for {{attendeeName}}',
+    description: '{{ticketType}} admission for the 2024 Tech Conference.',
     transferrable: false, // 門票不可轉讓
   },
   hooks: [],
@@ -144,10 +144,10 @@ async function createFactory() {
       wallet: wallet,
     });
 
-    console.log(`工廠創建交易已發送：${hash}`);
-    console.log(`新工廠地址：${factoryAddress}`);
+    console.log(`Factory creation transaction sent: ${hash}`);
+    console.log(`New factory address: ${factoryAddress}`);
   } catch (error) {
-    console.error('創建資產工廠時出錯：', error);
+    console.error('Error creating asset factory:', error);
   }
 }
 
@@ -160,11 +160,11 @@ createFactory();
   <x-field data-name="factory" data-type="object" data-required="true" data-desc="一個定義工廠屬性和鑄造邏輯的物件。">
     <x-field data-name="name" data-type="string" data-required="true" data-desc="工廠的名稱。"></x-field>
     <x-field data-name="description" data-type="string" data-required="true" data-desc="工廠用途的描述。"></x-field>
-    <x-field data-name="limit" data-type="number" data-default="0" data-required="false" data-desc="可以從此工廠鑄造的最大資產數量。0 表示無限制。"></x-field>
+    <x-field data-name="limit" data-type="number" data-default="0" data-required="false" data-desc="可從此工廠鑄造的資產最大數量。0 表示無限制。"></x-field>
     <x-field data-name="trustedIssuers" data-type="string[]" data-required="false" data-desc="授權從此工廠鑄造的帳戶地址列表。"></x-field>
     <x-field data-name="input" data-type="object" data-required="true" data-desc="定義鑄造資產所需的輸入資料。"></x-field>
     <x-field data-name="output" data-type="object" data-required="true" data-desc="定義將被鑄造的資產的結構和屬性。"></x-field>
-    <x-field data-name="hooks" data-type="object[]" data-required="false" data-desc="在鑄造過程中要執行的一系列掛鉤 (hooks)。"></x-field>
+    <x-field data-name="hooks" data-type="object[]" data-required="false" data-desc="在鑄造過程中執行的掛鉤列表。"></x-field>
     <x-field data-name="data" data-type="object" data-required="false" data-desc="與工廠一起儲存的額外任意資料。"></x-field>
   </x-field>
   <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="工廠擁有者的錢包物件。"></x-field>
@@ -181,16 +181,16 @@ createFactory();
 
 ## 從工廠獲取資產
 
-從工廠獲取資產是一個兩步驟的過程。首先，您需要準備鑄造資料，這讓您可以預覽將要創建的資產。其次，您將交易提交到區塊鏈以正式獲取資產。
+從工廠獲取資產是一個兩步驟的過程。首先，您需要準備鑄造資料，這讓您可以預覽將要建立的資產。其次，您將交易提交到區塊鏈以正式獲取資產。
 
-這種分離很有用，因為它允許應用程式在使用者簽署並提交最終交易之前，向他們展示即將收到的內容。
+這種分離很有用，因為它允許應用程式在使用者簽署並提交最終交易之前，向使用者展示他們將要收到的內容。
 
 ### 步驟 1：準備資產資料
 
-`preMintAsset` 方法接收工廠地址和使用者提供的輸入，以生成最終的資產資料。此過程在鏈下進行，不需要交易。
+`preMintAsset` 方法會接收工廠地址和使用者提供的輸入，以產生最終的資產資料。此過程在鏈下發生，不需要交易。
 
 ```javascript icon=logos:javascript
-const factoryAddress = 'z2...'; // 先前創建的工廠地址
+const factoryAddress = 'z2...'; // 先前建立的工廠地址
 const { wallet: issuerWallet } = getIssuerWallet(); // 工廠擁有者或受信任的發行者
 const { wallet: userWallet } = getUserWallet(); // 將擁有新資產的使用者
 
@@ -206,17 +206,17 @@ async function prepareAssetForMinting() {
       wallet: issuerWallet,
     });
 
-    console.log('準備好用於鑄造的資產資料：', mintingData);
+    console.log('Prepared asset data for minting:', mintingData);
     return mintingData;
   } catch (error) {
-    console.error('準備資產時出錯：', error);
+    console.error('Error preparing asset:', error);
   }
 }
 ```
 
 ### 步驟 2：發送交易
 
-一旦鑄造資料準備就緒，使用者（即未來的資產擁有者）便簽署並發送 `acquireAsset` 交易。來自 `preMintAsset` 的 `itx` 物件將被用作負載。
+一旦鑄造資料準備好，使用者（未來的資產擁有者）簽署並發送 `acquireAsset` 交易。來自 `preMintAsset` 的 `itx` 物件將用作負載。
 
 ```javascript icon=logos:javascript
 async function acquireNewAsset() {
@@ -227,13 +227,13 @@ async function acquireNewAsset() {
   try {
     const hash = await client.acquireAsset({
       itx: itx,
-      wallet: userWallet, // 使用者的錢包簽署此交易
+      wallet: userWallet, // 使用者的錢包簽署交易
     });
 
-    console.log(`資產獲取交易已發送：${hash}`);
-    console.log(`新資產將可在以下地址取得：${itx.address}`);
+    console.log(`Asset acquisition transaction sent: ${hash}`);
+    console.log(`New asset will be available at address: ${itx.address}`);
   } catch (error) {
-    console.error('獲取資產時出錯：', error);
+    console.error('Error acquiring asset:', error);
   }
 }
 
@@ -252,4 +252,81 @@ acquireNewAsset();
 
 一個 `Promise`，會解析為 `acquireAsset` 操作的交易雜湊值。
 
+<x-field data-name="response" data-type="Promise<string>" data-desc="transactionHash"></x-field>
+
+---
+
+## 從工廠鑄造資產
+
+除了由使用者主導的 `acquireAsset` 流程外，授權的發行者（如工廠擁有者或受信任的發行者）也可以鑄造資產並將其直接發送到使用者的帳戶。此過程同樣使用 `preMintAsset` 來準備資料，但最終的交易是 `mintAsset`，由發行者簽署。
+
+此流程適用於空投、頒發證書或任何接收使用者無需發起最終交易的情況。
+
+### 步驟 1：準備資產資料
+
+此步驟與獲取流程相同。發行者呼叫 `preMintAsset` 在鏈下產生交易負載（`itx`）。
+
+```javascript icon=logos:javascript
+const factoryAddress = 'z2...'; // 工廠地址
+const { wallet: issuerWallet } = getIssuerWallet(); // 工廠擁有者或受信任的發行者
+const userAddress = 'z1...'; // 將接收資產的使用者地址
+
+async function prepareAssetForMinting() {
+  try {
+    const mintingData = await client.preMintAsset({
+      factory: factoryAddress,
+      inputs: {
+        attendeeName: 'Jane Smith',
+        ticketType: 'General',
+      },
+      owner: userAddress,
+      wallet: issuerWallet, // 此處使用發行者的錢包
+    });
+
+    console.log('Prepared asset data for minting:', mintingData);
+    return mintingData;
+  } catch (error) {
+    console.error('Error preparing asset:', error);
+  }
+}
+```
+
+### 步驟 2：發送鑄造交易
+
+發行者使用準備好的 `itx` 物件呼叫 `mintAsset`。交易由發行者的錢包簽署，新建立的資產將分配給上一步驟中指定的所有者。
+
+```javascript icon=logos:javascript
+async function mintNewAsset() {
+  // 首先，從步驟 1 獲取鑄造資料
+  const itx = await prepareAssetForMinting();
+  if (!itx) return;
+
+  try {
+    // 發行者的錢包簽署交易
+    const hash = await client.mintAsset({
+      itx: itx,
+      wallet: issuerWallet,
+    });
+
+    console.log(`Asset minting transaction sent: ${hash}`);
+    console.log(`New asset for ${userAddress} will be available at address: ${itx.address}`);
+  } catch (error) {
+    console.error('Error minting asset:', error);
+  }
+}
+
+mintNewAsset();
+```
+
+### `mintAsset` 的參數
+
+<x-field-group>
+  <x-field data-name="itx" data-type="object" data-required="true" data-desc="從 `preMintAsset` 方法返回的內部交易物件。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="正在鑄造資產的發行者的錢包。"></x-field>
+</x-field-group>
+
+### 返回值
+
+一個 `Promise`，會解析為 `mintAsset` 操作的交易雜湊值。
+
 <x-field data-name="response" data-type="Promise<string>" data-desc="transactionHash"></x-field>