@ocap/client 1.25.3 → 1.25.5

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

@@ -0,0 +1,255 @@
+# 管理資產 (NFT)
+
+本指南提供了使用 OCAP Client 管理非同質化代幣 (NFT)（也稱為資產）整個生命週期的完整演練。您將學習如何從頭開始創建新資產、更新其屬性、建立資產工廠以進行標準化鑄造，以及從該工廠獲取新資產。
+
+## 創建新資產
+
+您可以使用 `createAsset` 方法在區塊鏈上創建一個獨一無二的獨立資產。每個資產都會被分配一個根據其初始屬性派生而來的唯一鏈上地址。
+
+```javascript icon=logos:javascript
+const { wallet } = getWallet(); // 使用者的錢包物件
+
+async function createNewAsset() {
+  try {
+    const [hash, address] = await client.createAsset({
+      moniker: '我的獨特數位藝術品',
+      data: {
+        typeUrl: 'json',
+        value: { 
+          description: '由藝術家 X 創作的獨一無二的作品。',
+          imageUrl: 'https://example.com/path/to/image.png',
+        },
+      },
+      readonly: true,
+      transferrable: true,
+      wallet: wallet,
+    });
+
+    console.log(`資產創建交易已發送：${hash}`);
+    console.log(`新資產地址：${address}`);
+    return address;
+  } catch (error) {
+    console.error('創建資產時出錯：', error);
+  }
+}
+
+createNewAsset();
+```
+
+### 參數
+
+<x-field-group>
+  <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="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>
+  <x-field data-name="tags" data-type="string[]" data-default="[]" data-required="false" data-desc="用於對資產進行分類的字串陣列。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="資產初始擁有者的錢包物件。"></x-field>
+  <x-field data-name="delegator" data-type="string" data-default="''" data-required="false" data-desc="透過委託授權此交易的帳戶地址。"></x-field>
+</x-field-group>
+
+### 返回值
+
+一個 `Promise`，會解析為一個包含交易雜湊值和新資產鏈上地址的陣列。
+
+<x-field data-name="response" data-type="Promise<[string, string]>" data-desc="[transactionHash, assetAddress]"></x-field>
+
+---
+
+## 更新現有資產
+
+如果資產在創建時設定了 `readonly: false`，您可以使用 `updateAsset` 方法修改其 `moniker` 和 `data` 欄位。資產透過其唯一地址進行標識。
+
+```javascript icon=logos:javascript
+const { wallet } = getWallet(); // 使用者的錢包物件
+const assetAddress = 'z362...'; // 要更新的資產地址
+
+async function updateExistingAsset() {
+  try {
+    const hash = await client.updateAsset({
+      address: assetAddress,
+      moniker: '我更新後的數位藝術品',
+      data: {
+        typeUrl: 'json',
+        value: { 
+          description: '我的獨特作品的更新描述。',
+          imageUrl: 'https://example.com/path/to/new_image.png',
+        },
+      },
+      wallet: wallet,
+    });
+
+    console.log(`資產更新交易已發送：${hash}`);
+  } catch (error) {
+    console.error('更新資產時出錯：', error);
+  }
+}
+
+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-group>
+
+### 返回值
+
+一個 `Promise`，會解析為交易雜湊值。
+
+<x-field data-name="response" data-type="Promise<string>" data-desc="transactionHash"></x-field>
+
+---
+
+## 創建資產工廠
+
+資產工廠是用於創建多個相似資產的範本。它定義了鑄造新資產的結構、規則和邏輯，這比單獨創建每個資產更有效率。這非常適合用於發行活動門票、證書或收藏品等用例。
+
+```javascript icon=logos:javascript
+const { wallet } = getWallet(); // 工廠擁有者的錢包
+
+const factoryDefinition = {
+  name: '會議門票工廠',
+  description: '為 2024 年技術大會鑄造門票。',
+  limit: 1000, // 最多可鑄造 1000 張門票
+  input: {
+    // 定義鑄造資產所需的資料
+    type: 'object',
+    properties: {
+      attendeeName: { type: 'string' },
+      ticketType: { type: 'string', enum: ['General', 'VIP'] },
+    },
+  },
+  output: {
+    // 定義鑄造資產的結構
+    moniker: '{{attendeeName}} 的門票',
+    description: '2024 年技術大會的 {{ticketType}} 入場券。',
+    transferrable: false, // 門票不可轉讓
+  },
+  hooks: [],
+};
+
+async function createFactory() {
+  try {
+    const [hash, factoryAddress] = await client.createAssetFactory({
+      factory: factoryDefinition,
+      wallet: wallet,
+    });
+
+    console.log(`工廠創建交易已發送：${hash}`);
+    console.log(`新工廠地址：${factoryAddress}`);
+  } catch (error) {
+    console.error('創建資產工廠時出錯：', error);
+  }
+}
+
+createFactory();
+```
+
+### 參數
+
+<x-field-group>
+  <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="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="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>
+</x-field-group>
+
+
+### 返回值
+
+一個 `Promise`，會解析為一個包含交易雜湊值和新工廠鏈上地址的陣列。
+
+<x-field data-name="response" data-type="Promise<[string, string]>" data-desc="[transactionHash, factoryAddress]"></x-field>
+
+---
+
+## 從工廠獲取資產
+
+從工廠獲取資產是一個兩步驟的過程。首先，您需要準備鑄造資料，這讓您可以預覽將要創建的資產。其次，您將交易提交到區塊鏈以正式獲取資產。
+
+這種分離很有用，因為它允許應用程式在使用者簽署並提交最終交易之前，向他們展示即將收到的內容。
+
+### 步驟 1：準備資產資料
+
+`preMintAsset` 方法接收工廠地址和使用者提供的輸入，以生成最終的資產資料。此過程在鏈下進行，不需要交易。
+
+```javascript icon=logos:javascript
+const factoryAddress = 'z2...'; // 先前創建的工廠地址
+const { wallet: issuerWallet } = getIssuerWallet(); // 工廠擁有者或受信任的發行者
+const { wallet: userWallet } = getUserWallet(); // 將擁有新資產的使用者
+
+async function prepareAssetForMinting() {
+  try {
+    const mintingData = await client.preMintAsset({
+      factory: factoryAddress,
+      inputs: {
+        attendeeName: 'John Doe',
+        ticketType: 'VIP',
+      },
+      owner: userWallet.address,
+      wallet: issuerWallet,
+    });
+
+    console.log('準備好用於鑄造的資產資料：', mintingData);
+    return mintingData;
+  } catch (error) {
+    console.error('準備資產時出錯：', error);
+  }
+}
+```
+
+### 步驟 2：發送交易
+
+一旦鑄造資料準備就緒，使用者（即未來的資產擁有者）便簽署並發送 `acquireAsset` 交易。來自 `preMintAsset` 的 `itx` 物件將被用作負載。
+
+```javascript icon=logos:javascript
+async function acquireNewAsset() {
+  // 首先，從步驟 1 獲取鑄造資料
+  const itx = await prepareAssetForMinting();
+  if (!itx) return;
+
+  try {
+    const hash = await client.acquireAsset({
+      itx: itx,
+      wallet: userWallet, // 使用者的錢包簽署此交易
+    });
+
+    console.log(`資產獲取交易已發送：${hash}`);
+    console.log(`新資產將可在以下地址取得：${itx.address}`);
+  } catch (error) {
+    console.error('獲取資產時出錯：', error);
+  }
+}
+
+acquireNewAsset();
+```
+
+### `acquireAsset` 的參數
+
+<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 data-name="delegator" data-type="string" data-default="''" data-required="false" data-desc="透過委託授權此交易的帳戶地址。"></x-field>
+</x-field-group>
+
+### 返回值
+
+一個 `Promise`，會解析為 `acquireAsset` 操作的交易雜湊值。
+
+<x-field data-name="response" data-type="Promise<string>" data-desc="transactionHash"></x-field>

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

@@ -0,0 +1,255 @@
+# 管理资产 (NFT)
+
+本指南全面介绍了如何使用 OCAP Client 管理非同质化代币（NFT）（也称为资产）的整个生命周期。你将学习如何从头开始创建新资产、更新其属性、建立用于标准化铸造的资产工厂，以及从该工厂获取新资产。
+
+## 创建新资产
+
+你可以使用 `createAsset` 方法在区块链上创建一个独特的、独立的资产。每个资产都会根据其初始属性派生出一个唯一的链上地址。
+
+```javascript icon=logos:javascript
+const { wallet } = getWallet(); // 用户钱包对象
+
+async function createNewAsset() {
+  try {
+    const [hash, address] = await client.createAsset({
+      moniker: '我的独特数字艺术品',
+      data: {
+        typeUrl: 'json',
+        value: { 
+          description: '由艺术家 X 创作的独一无二的作品。',
+          imageUrl: 'https://example.com/path/to/image.png',
+        },
+      },
+      readonly: true,
+      transferrable: true,
+      wallet: wallet,
+    });
+
+    console.log(`资产创建交易已发送: ${hash}`);
+    console.log(`新资产地址: ${address}`);
+    return address;
+  } catch (error) {
+    console.error('创建资产时出错:', error);
+  }
+}
+
+createNewAsset();
+```
+
+### 参数
+
+<x-field-group>
+  <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="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>
+  <x-field data-name="tags" data-type="string[]" data-default="[]" data-required="false" data-desc="用于对资产进行分类的字符串数组。" ></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="资产初始所有者的钱包对象。" ></x-field>
+  <x-field data-name="delegator" data-type="string" data-default="''" data-required="false" data-desc="通过委托授权此交易的账户地址。" ></x-field>
+</x-field-group>
+
+### 返回值
+
+一个 `Promise`，它会解析为一个包含交易哈希和新资产链上地址的数组。
+
+<x-field data-name="response" data-type="Promise<[string, string]>" data-desc="[transactionHash, assetAddress]"></x-field>
+
+---
+
+## 更新现有资产
+
+如果资产创建时设置了 `readonly: false`，你可以使用 `updateAsset` 方法修改其 `moniker` 和 `data` 字段。资产通过其唯一地址进行识别。
+
+```javascript icon=logos:javascript
+const { wallet } = getWallet(); // 用户钱包对象
+const assetAddress = 'z362...'; // 要更新的资产地址
+
+async function updateExistingAsset() {
+  try {
+    const hash = await client.updateAsset({
+      address: assetAddress,
+      moniker: '我更新后的数字艺术品',
+      data: {
+        typeUrl: 'json',
+        value: { 
+          description: '我的独特作品的更新描述。',
+          imageUrl: 'https://example.com/path/to/new_image.png',
+        },
+      },
+      wallet: wallet,
+    });
+
+    console.log(`资产更新交易已发送: ${hash}`);
+  } catch (error) {
+    console.error('更新资产时出错:', error);
+  }
+}
+
+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-group>
+
+### 返回值
+
+一个 `Promise`，它会解析为交易哈希。
+
+<x-field data-name="response" data-type="Promise<string>" data-desc="transactionHash"></x-field>
+
+---
+
+## 创建资产工厂
+
+资产工厂是用于创建多个相似资产的模板。它定义了铸造新资产的结构、规则和逻辑，比单独创建每个资产更高效。这对于发行活动门票、证书或收藏品等用例非常理想。
+
+```javascript icon=logos:javascript
+const { wallet } = getWallet(); // 工厂所有者的钱包
+
+const factoryDefinition = {
+  name: '会议门票工厂',
+  description: '铸造 2024 年技术大会的门票。',
+  limit: 1000, // 最多可铸造 1000 张门票
+  input: {
+    // 定义铸造资产所需的数据
+    type: 'object',
+    properties: {
+      attendeeName: { type: 'string' },
+      ticketType: { type: 'string', enum: ['General', 'VIP'] },
+    },
+  },
+  output: {
+    // 定义铸造资产的结构
+    moniker: '{{attendeeName}}的门票',
+    description: '2024 年技术大会的{{ticketType}}门票。',
+    transferrable: false, // 门票不可转让
+  },
+  hooks: [],
+};
+
+async function createFactory() {
+  try {
+    const [hash, factoryAddress] = await client.createAssetFactory({
+      factory: factoryDefinition,
+      wallet: wallet,
+    });
+
+    console.log(`工厂创建交易已发送: ${hash}`);
+    console.log(`新工厂地址: ${factoryAddress}`);
+  } catch (error) {
+    console.error('创建资产工厂时出错:', error);
+  }
+}
+
+createFactory();
+```
+
+### 参数
+
+<x-field-group>
+  <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="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="在铸造过程中执行的钩子列表。" ></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>
+</x-field-group>
+
+
+### 返回值
+
+一个 `Promise`，它会解析为一个包含交易哈希和新工厂链上地址的数组。
+
+<x-field data-name="response" data-type="Promise<[string, string]>" data-desc="[transactionHash, factoryAddress]"></x-field>
+
+---
+
+## 从工厂获取资产
+
+从工厂获取资产是一个两步过程。首先，你准备铸造数据，这可以让你预览将要创建的资产。其次，你将交易提交到区块链以正式获取资产。
+
+这种分离很有用，因为它允许应用程序在用户签署并提交最终交易之前，向用户展示他们将要收到的东西。
+
+### 步骤 1：准备资产数据
+
+`preMintAsset` 方法接收工厂地址和用户提供的输入，以生成最终的资产数据。此过程在链下发生，不需要交易。
+
+```javascript icon=logos:javascript
+const factoryAddress = 'z2...'; // 先前创建的工厂的地址
+const { wallet: issuerWallet } = getIssuerWallet(); // 工厂所有者或受信任的发行人
+const { wallet: userWallet } = getUserWallet(); // 将拥有新资产的用户
+
+async function prepareAssetForMinting() {
+  try {
+    const mintingData = await client.preMintAsset({
+      factory: factoryAddress,
+      inputs: {
+        attendeeName: 'John Doe',
+        ticketType: 'VIP',
+      },
+      owner: userWallet.address,
+      wallet: issuerWallet,
+    });
+
+    console.log('已准备好用于铸造的资产数据:', mintingData);
+    return mintingData;
+  } catch (error) {
+    console.error('准备资产时出错:', error);
+  }
+}
+```
+
+### 步骤 2：发送交易
+
+一旦铸造数据准备好，用户（未来的资产所有者）签署并发送 `acquireAsset` 交易。来自 `preMintAsset` 的 `itx` 对象被用作有效负载。
+
+```javascript icon=logos:javascript
+async function acquireNewAsset() {
+  // 首先，从步骤 1 获取铸造数据
+  const itx = await prepareAssetForMinting();
+  if (!itx) return;
+
+  try {
+    const hash = await client.acquireAsset({
+      itx: itx,
+      wallet: userWallet, // 用户的钱包签署交易
+    });
+
+    console.log(`资产获取交易已发送: ${hash}`);
+    console.log(`新资产将在以下地址可用: ${itx.address}`);
+  } catch (error) {
+    console.error('获取资产时出错:', error);
+  }
+}
+
+acquireNewAsset();
+```
+
+### `acquireAsset` 的参数
+
+<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 data-name="delegator" data-type="string" data-default="''" data-required="false" data-desc="通过委托授权此交易的账户地址。" ></x-field>
+</x-field-group>
+
+### 返回值
+
+一个 `Promise`，它会解析为 `acquireAsset` 操作的交易哈希。
+
+<x-field data-name="response" data-type="Promise<string>" data-desc="transactionHash"></x-field>