@ocap/client 1.25.3 → 1.25.4

package/docs/api-reference-low-level-api.md

@@ -0,0 +1,228 @@
+# Low-level API
+
+The Low-level API provides granular control over the entire transaction lifecycle. Unlike the [High-level API](./api-reference-transaction-helpers.md) which abstracts away the details, these methods allow you to manually construct, encode, sign, and send transactions. This is ideal for advanced scenarios, such as multi-signature workflows where different parties need to sign a transaction before it's broadcasted.
+
+This API is organized into four main groups of methods, each corresponding to a stage in the transaction lifecycle:
+
+1.  **Encode**: Prepare a transaction and serialize it into a binary buffer.
+2.  **Sign**: Add a digital signature to an encoded transaction.
+3.  **Multi-sign**: Add multiple digital signatures to a transaction.
+4.  **Send**: Broadcast a signed transaction to the blockchain.
+
+## Encoding Transactions
+
+Encoding is the first step in creating a transaction. The `encode[Type]Tx` methods take the core transaction data (`itx`) and wrap it in a standard transaction structure, adding necessary details like the `chainId` and `nonce`. The result is a human-readable transaction object and a binary buffer ready for signing.
+
+There is an `encode` method for every transaction type supported by the chain. You can get a full list by calling `client.getTxEncodeMethods()`.
+
+### `encode[Type]Tx(payload)`
+
+Encodes a transaction without signing it.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true">
+    <x-field-desc markdown>The transaction data object.</x-field-desc>
+    <x-field data-name="itx" data-type="object" data-required="true" data-desc="The inner transaction object specific to the transaction type."></x-field>
+    <x-field data-name="from" data-type="string" data-required="false" data-desc="Sender's address. If not provided, it's derived from the wallet."></x-field>
+    <x-field data-name="nonce" data-type="number" data-required="false" data-desc="Transaction nonce. Defaults to `Date.now()` if not set."></x-field>
+    <x-field data-name="chainId" data-type="string" data-required="false" data-desc="The chain ID. Fetched from the connected node if not provided."></x-field>
+  </x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet object used to derive the sender's address and public key."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The address of the account delegating permissions, if applicable."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="Promise<object>" data-type="Promise<object>" data-desc="A promise that resolves to an object containing the encoded transaction.">
+  <x-field data-name="object" data-type="object" data-desc="The human-readable transaction object."></x-field>
+  <x-field data-name="buffer" data-type="Buffer" data-desc="The serialized transaction binary buffer, ready for signing."></x-field>
+</x-field>
+
+**Example**
+
+```javascript TransferV2Tx icon=logos:javascript
+const { encodeTransferV2Tx } = client;
+const senderWallet = fromRandom();
+const receiverAddress = 'z1...';
+
+const { object, buffer } = await encodeTransferV2Tx({
+  tx: {
+    itx: {
+      to: receiverAddress,
+      value: await client.fromTokenToUnit(10), // Transfer 10 native tokens
+    },
+  },
+  wallet: senderWallet,
+});
+
+console.log('Encoded TX Object:', object);
+console.log('Buffer to Sign:', buffer.toString('hex'));
+```
+
+## Signing Transactions
+
+The `sign[Type]Tx` methods build on the encoding step by adding a digital signature. These methods encode the transaction and then use the provided wallet to sign the resulting binary buffer.
+
+You can get a full list of available signing methods by calling `client.getTxSignMethods()`.
+
+### `sign[Type]Tx(payload)`
+
+Encodes and signs a transaction.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="The transaction data object, same as for encoding."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet used to sign the transaction."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The address of the delegator, if applicable."></x-field>
+  <x-field data-name="encoding" data-type="string" data-required="false" data-desc="Optional encoding for the output ('base16', 'hex', 'base58', 'base64'). If omitted, returns the transaction object."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="Promise<object|string>" data-type="Promise<object|string>" data-desc="A promise that resolves to the signed transaction object, or an encoded string if `encoding` is specified."></x-field>
+
+**Example**
+
+```javascript TransferV2Tx icon=logos:javascript
+const { signTransferV2Tx } = client;
+const senderWallet = fromRandom();
+const receiverAddress = 'z1...';
+
+const signedTx = await signTransferV2Tx({
+  tx: {
+    itx: {
+      to: receiverAddress,
+      value: await client.fromTokenToUnit(10),
+    },
+  },
+  wallet: senderWallet,
+});
+
+console.log('Signed TX:', signedTx);
+```
+
+## Sending Transactions
+
+The `send[Type]Tx` methods are responsible for broadcasting a transaction to the blockchain. These methods can perform the signing step implicitly if an unsigned transaction and a wallet are provided, or they can send a transaction that has already been signed.
+
+A full list of send methods is available via `client.getTxSendMethods()`.
+
+### `send[Type]Tx(payload)`
+
+Signs (if necessary) and sends a transaction to the chain.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="The transaction object. Can be signed or unsigned."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet to sign the transaction. Still required for identifying the sender even if the transaction is pre-signed."></x-field>
+  <x-field data-name="signature" data-type="string" data-required="false" data-desc="A pre-computed signature for the transaction. If provided, the wallet will not be used to sign again."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The address of the delegator, if applicable."></x-field>
+  <x-field data-name="commit" data-type="boolean" data-default="false" data-required="false" data-desc="Whether to wait for the transaction to be committed to a block before resolving."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="Promise<string>" data-type="Promise<string>" data-desc="A promise that resolves to the transaction hash."></x-field>
+
+**Example: Auto-Signing**
+
+```javascript TransferV2Tx icon=logos:javascript
+const { sendTransferV2Tx } = client;
+const senderWallet = fromRandom();
+const receiverAddress = 'z1...';
+
+// The client will sign this transaction using senderWallet before sending.
+const txHash = await sendTransferV2Tx({
+  tx: {
+    itx: {
+      to: receiverAddress,
+      value: await client.fromTokenToUnit(10),
+    },
+  },
+  wallet: senderWallet,
+});
+
+console.log('Transaction sent with hash:', txHash);
+```
+
+**Example: Sending a Pre-Signed Transaction**
+
+```javascript TransferV2Tx icon=logos:javascript
+// Assume signedTx is from the sign[Type]Tx example
+const { sendTransferV2Tx } = client;
+
+const txHash = await sendTransferV2Tx({
+  tx: signedTx, // Pass the entire signed transaction object
+  wallet: senderWallet,
+});
+
+console.log('Pre-signed transaction sent with hash:', txHash);
+```
+
+## Multi-Signature Transactions
+
+For workflows requiring multiple signatures (like an atomic swap), the `multiSign[Type]Tx` methods are used. The process involves one party signing the transaction first (using a standard `sign[Type]Tx` method), and subsequent parties adding their signatures using the corresponding `multiSign[Type]Tx` method.
+
+You can get a list of transactions that support multiple signatures via `client.getTxMultiSignMethods()`.
+
+### `multiSign[Type]Tx(payload)`
+
+Adds a signature to a transaction that already has one or more signatures.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="The transaction object, which should already contain at least one signature."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the current signer."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The address of the delegator for the current signer, if applicable."></x-field>
+  <x-field data-name="data" data-type="any" data-required="false" data-desc="Optional data to include with the signature."></x-field>
+  <x-field data-name="encoding" data-type="string" data-required="false" data-desc="Optional encoding for the output ('base16', 'hex', 'base58', 'base64')."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="Promise<object|string>" data-type="Promise<object|string>" data-desc="A promise that resolves to the transaction object with the new signature added."></x-field>
+
+**Example: Atomic Swap (`ExchangeV2Tx`)**
+
+```javascript ExchangeV2Tx icon=logos:javascript
+// Wallets for two parties
+const aliceWallet = fromRandom();
+const bobWallet = fromRandom();
+
+// 1. Alice prepares and signs the initial exchange transaction
+const exchangeTx = {
+  itx: {
+    to: bobWallet.address,
+    sender: {
+      value: await client.fromTokenToUnit(10), // Alice offers 10 tokens
+    },
+    receiver: {
+      value: await client.fromTokenToUnit(5), // Alice demands 5 tokens
+    },
+  },
+};
+
+const signedByAlice = await client.signExchangeV2Tx({
+  tx: exchangeTx,
+  wallet: aliceWallet,
+});
+
+// 2. Alice sends `signedByAlice` to Bob. Bob adds his signature.
+const signedByBoth = await client.multiSignExchangeV2Tx({
+  tx: signedByAlice,
+  wallet: bobWallet,
+});
+
+// 3. Bob sends `signedByBoth` back to Alice. Alice sends the final transaction.
+const txHash = await client.sendExchangeV2Tx({
+  tx: signedByBoth,
+  wallet: aliceWallet, // The sender wallet is used to submit
+});
+
+console.log('Atomic swap transaction sent:', txHash);
+```

package/docs/api-reference-low-level-api.zh.md

@@ -0,0 +1,228 @@
+# 底层 API
+
+底层 API 提供了对整个交易生命周期的精细控制。与抽象掉细节的 [高级 API](./api-reference-transaction-helpers.md) 不同，这些方法允许您手动构建、编码、签名和发送交易。这对于高级场景非常理想，例如多重签名工作流，其中不同方需要在广播交易前对其进行签名。
+
+此 API 分为四个主要方法组，每个方法组对应交易生命周期的一个阶段：
+
+1.  **编码**：准备一个交易并将其序列化为二进制缓冲区。
+2.  **签名**：向已编码的交易添加数字签名。
+3.  **多重签名**：向交易添加多个数字签名。
+4.  **发送**：将已签名的交易广播到区块链。
+
+## 编码交易
+
+编码是创建交易的第一步。`encode[Type]Tx` 方法接收核心交易数据 (`itx`) 并将其包装在标准交易结构中，添加 `chainId` 和 `nonce` 等必要细节。结果是一个人类可读的交易对象和一个可供签名的二进制缓冲区。
+
+链支持的每种交易类型都有一个 `encode` 方法。您可以通过调用 `client.getTxEncodeMethods()` 获取完整列表。
+
+### `encode[Type]Tx(payload)`
+
+编码一个交易，但不进行签名。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true">
+    <x-field-desc markdown>交易数据对象。</x-field-desc>
+    <x-field data-name="itx" data-type="object" data-required="true" data-desc="特定于交易类型的内部交易对象。"></x-field>
+    <x-field data-name="from" data-type="string" data-required="false" data-desc="发送方地址。如果未提供，则从钱包中派生。"></x-field>
+    <x-field data-name="nonce" data-type="number" data-required="false" data-desc="交易 nonce。如果未设置，默认为 `Date.now()`。"></x-field>
+    <x-field data-name="chainId" data-type="string" data-required="false" data-desc="链 ID。如果未提供，则从连接的节点获取。"></x-field>
+  </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-required="false" data-desc="如果适用，委托权限的账户地址。"></x-field>
+</x-field-group>
+
+**返回值**
+
+<x-field data-name="Promise<object>" data-type="Promise<object>" data-desc="一个解析为包含已编码交易的对象的 Promise。">
+  <x-field data-name="object" data-type="object" data-desc="人类可读的交易对象。"></x-field>
+  <x-field data-name="buffer" data-type="Buffer" data-desc="序列化后的交易二进制缓冲区，可供签名。"></x-field>
+</x-field>
+
+**示例**
+
+```javascript TransferV2Tx icon=logos:javascript
+const { encodeTransferV2Tx } = client;
+const senderWallet = fromRandom();
+const receiverAddress = 'z1...';
+
+const { object, buffer } = await encodeTransferV2Tx({
+  tx: {
+    itx: {
+      to: receiverAddress,
+      value: await client.fromTokenToUnit(10), // 转移 10 个原生代币
+    },
+  },
+  wallet: senderWallet,
+});
+
+console.log('已编码的交易对象:', object);
+console.log('待签名的缓冲区:', buffer.toString('hex'));
+```
+
+## 签名交易
+
+`sign[Type]Tx` 方法在编码步骤的基础上添加了数字签名。这些方法会对交易进行编码，然后使用提供的钱包对生成的二进制缓冲区进行签名。
+
+您可以通过调用 `client.getTxSignMethods()` 获取所有可用的签名方法列表。
+
+### `sign[Type]Tx(payload)`
+
+对交易进行编码和签名。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tx" 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="delegator" data-type="string" data-required="false" data-desc="如果适用，委托人的地址。"></x-field>
+  <x-field data-name="encoding" data-type="string" data-required="false" data-desc="输出的可选编码（'base16'、'hex'、'base58'、'base64'）。如果省略，则返回交易对象。"></x-field>
+</x-field-group>
+
+**返回值**
+
+<x-field data-name="Promise<object|string>" data-type="Promise<object|string>" data-desc="一个解析为已签名交易对象或编码字符串（如果指定了 `encoding`）的 Promise。"></x-field>
+
+**示例**
+
+```javascript TransferV2Tx icon=logos:javascript
+const { signTransferV2Tx } = client;
+const senderWallet = fromRandom();
+const receiverAddress = 'z1...';
+
+const signedTx = await signTransferV2Tx({
+  tx: {
+    itx: {
+      to: receiverAddress,
+      value: await client.fromTokenToUnit(10),
+    },
+  },
+  wallet: senderWallet,
+});
+
+console.log('已签名的交易:', signedTx);
+```
+
+## 发送交易
+
+`send[Type]Tx` 方法负责将交易广播到区块链。如果提供了未签名的交易和钱包，这些方法可以隐式执行签名步骤，也可以发送已经签名的交易。
+
+通过 `client.getTxSendMethods()` 可以获取完整的发送方法列表。
+
+### `send[Type]Tx(payload)`
+
+签名（如果需要）并将交易发送到链上。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tx" 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="signature" data-type="string" data-required="false" data-desc="交易的预计算签名。如果提供，将不会再使用钱包进行签名。"></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="如果适用，委托人的地址。"></x-field>
+  <x-field data-name="commit" data-type="boolean" data-default="false" data-required="false" data-desc="在解析前是否等待交易被提交到区块。"></x-field>
+</x-field-group>
+
+**返回值**
+
+<x-field data-name="Promise<string>" data-type="Promise<string>" data-desc="一个解析为交易哈希的 Promise。"></x-field>
+
+**示例：自动签名**
+
+```javascript TransferV2Tx icon=logos:javascript
+const { sendTransferV2Tx } = client;
+const senderWallet = fromRandom();
+const receiverAddress = 'z1...';
+
+// 客户端将在发送前使用 senderWallet 签署此交易。
+const txHash = await sendTransferV2Tx({
+  tx: {
+    itx: {
+      to: receiverAddress,
+      value: await client.fromTokenToUnit(10),
+    },
+  },
+  wallet: senderWallet,
+});
+
+console.log('交易已发送，哈希值为:', txHash);
+```
+
+**示例：发送预签名交易**
+
+```javascript TransferV2Tx icon=logos:javascript
+// 假设 signedTx 来自 sign[Type]Tx 示例
+const { sendTransferV2Tx } = client;
+
+const txHash = await sendTransferV2Tx({
+  tx: signedTx, // 传递整个已签名的交易对象
+  wallet: senderWallet,
+});
+
+console.log('预签名交易已发送，哈希值为:', txHash);
+```
+
+## 多重签名交易
+
+对于需要多个签名（如原子交换）的工作流，使用 `multiSign[Type]Tx` 方法。该过程涉及一方首先签署交易（使用标准的 `sign[Type]Tx` 方法），然后后续各方使用相应的 `multiSign[Type]Tx` 方法添加他们的签名。
+
+您可以通过 `client.getTxMultiSignMethods()` 获取支持多重签名的交易列表。
+
+### `multiSign[Type]Tx(payload)`
+
+向已经有一个或多个签名的交易添加签名。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tx" 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="delegator" data-type="string" data-required="false" data-desc="如果适用，当前签名者的委托人地址。"></x-field>
+  <x-field data-name="data" data-type="any" data-required="false" data-desc="签名中包含的可选数据。"></x-field>
+  <x-field data-name="encoding" data-type="string" data-required="false" data-desc="输出的可选编码（'base16'、'hex'、'base58'、'base64'）。"></x-field>
+</x-field-group>
+
+**返回值**
+
+<x-field data-name="Promise<object|string>" data-type="Promise<object|string>" data-desc="一个解析为已添加新签名的交易对象的 Promise。"></x-field>
+
+**示例：原子交换（`ExchangeV2Tx`）**
+
+```javascript ExchangeV2Tx icon=logos:javascript
+// 两方的钱包
+const aliceWallet = fromRandom();
+const bobWallet = fromRandom();
+
+// 1. Alice 准备并签署初始交换交易
+const exchangeTx = {
+  itx: {
+    to: bobWallet.address,
+    sender: {
+      value: await client.fromTokenToUnit(10), // Alice 提供 10 个代币
+    },
+    receiver: {
+      value: await client.fromTokenToUnit(5), // Alice 要求 5 个代币
+    },
+  },
+};
+
+const signedByAlice = await client.signExchangeV2Tx({
+  tx: exchangeTx,
+  wallet: aliceWallet,
+});
+
+// 2. Alice 将 `signedByAlice` 发送给 Bob。Bob 添加他的签名。
+const signedByBoth = await client.multiSignExchangeV2Tx({
+  tx: signedByAlice,
+  wallet: bobWallet,
+});
+
+// 3. Bob 将 `signedByBoth` 发回给 Alice。Alice 发送最终交易。
+const txHash = await client.sendExchangeV2Tx({
+  tx: signedByBoth,
+  wallet: aliceWallet, // 发送方钱包用于提交
+});
+
+console.log('原子交换交易已发送:', txHash);
+```