@ocap/client 1.25.3 → 1.25.5

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

@@ -0,0 +1,228 @@
+# 低レベルAPI
+
+低レベルAPIは、トランザクションのライフサイクル全体にわたって詳細な制御を提供します。[高レベルAPI](./api-reference-transaction-helpers.md)が詳細を抽象化するのとは異なり、これらのメソッドを使用すると、手動でトランザクションを構築、エンコード、署名、送信できます。これは、トランザクションがブロードキャストされる前に複数の当事者が署名する必要があるマルチシグネチャワークフローなど、高度なシナリオに最適です。
+
+このAPIは、トランザクションライフサイクルの各段階に対応する4つの主要なメソッドグループに分かれています。
+
+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('エンコードされたTXオブジェクト:', 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('署名済みTX:', 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)`
+
+すでに1つ以上の署名があるトランザクションに署名を追加します。
+
+**パラメーター**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="トランザクションオブジェクト。すでに少なくとも1つの署名が含まれている必要があります。"></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
+// 2つの当事者のウォレット
+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);
+```

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);
+```