From 9f417b517214af36e139e266207d844d53f1dac0 Mon Sep 17 00:00:00 2001 From: bastienrp Date: Fri, 28 Aug 2026 08:30:43 +0700 Subject: [PATCH 1/2] fix: enterprise sdk on mainnet --- docs/pages/en/explanation/enterprise-sdk.mdx | 10 +++---- .../guaranteed-relayed-transactions.mdx | 8 +++--- .../pages/en/how-to/relay-with-gas-waiver.mdx | 10 +++---- .../how-to/send-guaranteed-transactions.mdx | 10 +++---- docs/pages/en/reference/enterprise-sdk.mdx | 28 +++++++++++-------- 5 files changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/pages/en/explanation/enterprise-sdk.mdx b/docs/pages/en/explanation/enterprise-sdk.mdx index 01045da..f77d007 100644 --- a/docs/pages/en/explanation/enterprise-sdk.mdx +++ b/docs/pages/en/explanation/enterprise-sdk.mdx @@ -9,11 +9,11 @@ diataxis: "explanation" `@stablechain/enterprise` is a server-side TypeScript client for Stable's enterprise transaction rails. It signs and relays two kinds of privileged transactions: gas-waived transactions, where you sponsor a user's gas, and guaranteed-blockspace transactions, which land in a reserved Enterprise lane. You can enable either rail, or both, on one client. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") }, }); @@ -36,11 +36,11 @@ The SDK exposes three features, one per module. Each is optional and independent Every feature offers the same four methods: `send` and `sendBatch` for the custodial path where the SDK signs, and `relay` and `relayBatch` for the non-custodial path where the user signs elsewhere and hands you only the signed hex. -The SDK is published on npm as [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise) and requires `viem >= 2.0.0` as a peer dependency. +The SDK is published on npm as [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise), currently at version 1.0.0, and requires `viem >= 2.0.0` as a peer dependency. ## Access -The Enterprise SDK is currently available on Stable Testnet only. +The Enterprise SDK is available on Stable Mainnet and Stable Testnet. Pass `stable` for mainnet or `stableTestnet` for testnet as the client's `chain`; both are re-exported by the package. Both rails are gated. Gas waiver requires a governance-registered waiver key, and guaranteed blockspace requires an Enterprise RPC gateway API key. To integrate, [contact Stable](https://discord.gg/stablexyz) to get access. Stable provisions the waiver key and the gateway endpoint you need. @@ -68,4 +68,4 @@ Reach for the Enterprise SDK when you operate a backend and want to sponsor user - [**Install from npm**](https://www.npmjs.com/package/@stablechain/enterprise): View the package on npmjs.com and check the latest version. - [**Gas waiver protocol**](/en/reference/gas-waiver-api): Transaction formats, marker routing, and governance controls. - [**Stable SDK**](/en/explanation/sdk-overview): The general-purpose client for transfers, bridging, swaps, and yield. -- [**Connect to Stable**](/en/reference/connect): Chain IDs, RPC endpoints, and explorers for testnet. +- [**Connect to Stable**](/en/reference/connect): Chain IDs, RPC endpoints, and explorers for mainnet and testnet. diff --git a/docs/pages/en/how-to/guaranteed-relayed-transactions.mdx b/docs/pages/en/how-to/guaranteed-relayed-transactions.mdx index 007be0e..0023375 100644 --- a/docs/pages/en/how-to/guaranteed-relayed-transactions.mdx +++ b/docs/pages/en/how-to/guaranteed-relayed-transactions.mdx @@ -13,7 +13,7 @@ The `guaranteedWaiver` module handles both sides. The user signs an inner `0x3F` ## Prerequisites - Node.js 20 or later, and `@stablechain/enterprise` plus `viem` installed. See the [Enterprise SDK reference](/en/reference/enterprise-sdk#install). -- A governance-registered waiver key and an Enterprise RPC gateway API key. The Enterprise SDK is testnet only for now, and access is on request: [contact Stable](https://discord.gg/stablexyz) to get both. +- A governance-registered waiver key and an Enterprise RPC gateway API key. The Enterprise SDK runs on Stable Mainnet and Stable Testnet, and access is on request: [contact Stable](https://discord.gg/stablexyz) to get both. :::warning This is a server-side library. Keep the waiver key and the Enterprise RPC gateway URL on your backend: the gateway URL embeds your API key. @@ -24,11 +24,11 @@ This is a server-side library. Keep the waiver key and the Enterprise RPC gatewa Pass `guaranteedWaiver` and `enterpriseRpcEndpoints` to `createStableEnterprise`. The module takes the whitelisted waiver key (which signs the outer wrapper) plus the Enterprise lane. It also accepts the same `allowedTargets`, `maxGasLimit`, and `maxDataLength` policy limits as `gasWaiver`. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions guaranteedWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`), @@ -89,7 +89,7 @@ For a non-custodial flow, the user signs the inner `0x3F` CustomTx in their own import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; // on the user's side — buildGuaranteedTx signs through a Signer; toSigner adapts a viem account -const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { +const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, { to: recipient, gas: 100_000n, gasFeeCap: 0n, // waived diff --git a/docs/pages/en/how-to/relay-with-gas-waiver.mdx b/docs/pages/en/how-to/relay-with-gas-waiver.mdx index c1b34aa..a41b82d 100644 --- a/docs/pages/en/how-to/relay-with-gas-waiver.mdx +++ b/docs/pages/en/how-to/relay-with-gas-waiver.mdx @@ -13,7 +13,7 @@ Every method returns `H_inner`, the hash of the user's transaction, not the wrap ## Prerequisites - Node.js 20 or later, and `@stablechain/enterprise` plus `viem` installed. See the [Enterprise SDK reference](/en/reference/enterprise-sdk#install). -- A governance-registered waiver key. The Enterprise SDK is testnet only for now, and access is gated: [contact Stable](https://discord.gg/stablexyz) to get a whitelisted waiver key. +- A governance-registered waiver key. The Enterprise SDK runs on Stable Mainnet and Stable Testnet, and access is gated: [contact Stable](https://discord.gg/stablexyz) to get a whitelisted waiver key. :::warning This is a server-side library that signs with private keys. Never run it in a browser. Keep the waiver key on your backend. @@ -24,11 +24,11 @@ This is a server-side library that signs with private keys. Never run it in a br Pass `gasWaiver: { account }` to `createStableEnterprise`, where `account` is your whitelisted waiver key. The module is present on the client only when you configure it. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`) }, }); @@ -90,7 +90,7 @@ Restrict what the waiver key may sponsor by adding policy limits to the config. ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`), maxGasLimit: 500_000n, @@ -112,7 +112,7 @@ For a non-custodial flow, the user signs the InnerTx in their own environment an import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise"; // on the user's side — buildWaiverInnerTx signs through a Signer; toSigner adapts a viem account -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to: token, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to: token, data, gas: 150_000n, nonce }); // on your backend const { txHash } = await gw.relay(signed); diff --git a/docs/pages/en/how-to/send-guaranteed-transactions.mdx b/docs/pages/en/how-to/send-guaranteed-transactions.mdx index 6da305c..5debec9 100644 --- a/docs/pages/en/how-to/send-guaranteed-transactions.mdx +++ b/docs/pages/en/how-to/send-guaranteed-transactions.mdx @@ -13,7 +13,7 @@ You can combine this with gas waiver to get [guaranteed relayed transactions](/e ## Prerequisites - Node.js 20 or later, and `@stablechain/enterprise` plus `viem` installed. See the [Enterprise SDK reference](/en/reference/enterprise-sdk#install). -- An Enterprise RPC gateway API key. The Enterprise SDK is testnet only for now, and access is gated: [contact Stable](https://discord.gg/stablexyz) to get a gateway endpoint. +- An Enterprise RPC gateway API key. The Enterprise SDK runs on Stable Mainnet and Stable Testnet, and access is gated: [contact Stable](https://discord.gg/stablexyz) to get a gateway endpoint. - A funded signer, since a GuaranteedTx pays its own gas. :::warning @@ -25,11 +25,11 @@ This is a server-side library. Keep the Enterprise RPC gateway URL on your backe Pass `guaranteedBlock` and `enterpriseRpcEndpoints` to `createStableEnterprise`. The gateway is the only endpoint that admits `0x3F` GuaranteedTxs, and it holds your API key. An invalid `laneId` is rejected up front. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions guaranteedBlock: { account: privateKeyToAccount(process.env.SIGNER_PRIVATE_KEY as `0x${string}`), // must be funded @@ -51,7 +51,7 @@ Call `send` with the signer and the varying fields. The 1559 fee fields are requ ```ts import { createPublicClient, http } from "viem"; -const publicClient = createPublicClient({ chain: stableTestnet, transport: http() }); +const publicClient = createPublicClient({ chain: stable, transport: http() }); const gasPrice = await publicClient.getGasPrice(); const { txHash } = await gb.send(signer, { @@ -98,7 +98,7 @@ For a non-custodial flow, build and sign the GuaranteedTx elsewhere with `buildG ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signed = await buildGuaranteedTx(toSigner(signer), stableTestnet.id, { +const signed = await buildGuaranteedTx(toSigner(signer), stable.id, { to: recipient, gas: 21_000n, gasFeeCap, diff --git a/docs/pages/en/reference/enterprise-sdk.mdx b/docs/pages/en/reference/enterprise-sdk.mdx index 9d6954f..f21ad17 100644 --- a/docs/pages/en/reference/enterprise-sdk.mdx +++ b/docs/pages/en/reference/enterprise-sdk.mdx @@ -9,7 +9,7 @@ diataxis: "reference" Full surface of `@stablechain/enterprise`. This covers the client from [`createStableEnterprise`](#createstableenterpriseconfig), its three features ([relay with gas waiver](#relay-with-gas-waiver), [guaranteed blockspace](#guaranteed-blockspace), and [guaranteed relay transactions](#guaranteed-relay-transactions)), the low-level build helpers, and the shared result and error types. For what these rails are, see [Stable Enterprise SDK](/en/explanation/enterprise-sdk), [Gas waiver](/en/explanation/gas-waiver), and [Guaranteed blockspace](/en/explanation/guaranteed-blockspace). :::note -The Enterprise SDK is available on Stable Testnet only for now, and access is on request. To integrate, [contact Stable](https://discord.gg/stablexyz) to get a governance-registered waiver key and an Enterprise RPC gateway API key. +The Enterprise SDK is available on Stable Mainnet and Stable Testnet, and access is on request. To integrate, [contact Stable](https://discord.gg/stablexyz) to get a governance-registered waiver key and an Enterprise RPC gateway API key. ::: :::warning @@ -28,16 +28,20 @@ added 2 packages, audited 3 packages in 2s `viem >= 2.0.0` is a peer dependency. The package is published as [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise) and re-exports `stable` and `stableTestnet` from `viem/chains`, so you don't import them separately. +:::note +The current release is version 1.0.0. Run `npm ls @stablechain/enterprise` to check what you have. +::: + ## `createStableEnterprise(config)` Construct a `StableEnterpriseClient`. Each module is present only when you configure it, so null-check it before use. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") }, }); ``` @@ -70,14 +74,14 @@ npm install @aws-sdk/client-kms ``` ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { awsKmsSigner } from "@stablechain/enterprise/aws-kms"; // the KMS key must be ECC_SECG_P256K1 (secp256k1); the SDK derives the address from it const signer = await awsKmsSigner({ keyId: process.env.AWS_KMS_KEY_ID }); const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { signer }, // custody-grade waiver key, in place of `account` }); ``` @@ -102,7 +106,7 @@ Enable it with `gasWaiver` in the config: ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY"), // optional per-partner policy limits @@ -164,7 +168,7 @@ Relay a pre-signed zero-gas InnerTx. Use this for the non-custodial flow where t ```ts import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise"; -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce }); const { txHash } = await gw.relay(signed); ``` @@ -192,7 +196,7 @@ Enable it with `guaranteedBlock` plus `enterpriseRpcEndpoints`: ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions guaranteedBlock: { account: privateKeyToAccount("0xFUNDED_SIGNER_KEY"), @@ -255,7 +259,7 @@ Relay a pre-signed GuaranteedTx, or a batch of them. Build and sign the transact ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signed = await buildGuaranteedTx(toSigner(signer), stableTestnet.id, { +const signed = await buildGuaranteedTx(toSigner(signer), stable.id, { to, gas: 21_000n, gasFeeCap, @@ -278,7 +282,7 @@ Enable it with `guaranteedWaiver` plus `enterpriseRpcEndpoints`: ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions guaranteedWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY"), @@ -324,7 +328,7 @@ For the non-custodial flow, the user signs the inner `0x3F` CustomTx with [`buil ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { +const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, { to, gas: 100_000n, gasFeeCap: 0n, // waived @@ -348,7 +352,7 @@ Low-level signers for the non-custodial `relay` paths. Each returns a signed tra Sign a waiver-ready InnerTx with the waiver invariants baked in: `gasPrice: 0`, legacy type, and the given `chainId`. `req` is a [`WaiverInnerTx`](#waiverinnertx) plus a required `nonce`. ```ts -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce }); ``` ### `buildGuaranteedTx(signer, chainId, req)` From 24629bd43ffe553d4ecbd2c042c408938a710d2a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 28 Aug 2026 01:33:55 +0000 Subject: [PATCH 2/2] i18n: auto-translate cn/ko for changed en content --- docs/pages/cn/explanation/enterprise-sdk.mdx | 53 ++-- .../guaranteed-relayed-transactions.mdx | 52 ++-- .../pages/cn/how-to/relay-with-gas-waiver.mdx | 66 ++--- .../how-to/send-guaranteed-transactions.mdx | 54 ++-- docs/pages/cn/reference/enterprise-sdk.mdx | 224 +++++++++-------- docs/pages/ko/explanation/enterprise-sdk.mdx | 53 ++-- .../guaranteed-relayed-transactions.mdx | 66 ++--- .../pages/ko/how-to/relay-with-gas-waiver.mdx | 54 ++-- .../how-to/send-guaranteed-transactions.mdx | 58 ++--- docs/pages/ko/reference/enterprise-sdk.mdx | 234 +++++++++--------- 10 files changed, 464 insertions(+), 450 deletions(-) diff --git a/docs/pages/cn/explanation/enterprise-sdk.mdx b/docs/pages/cn/explanation/enterprise-sdk.mdx index 7ab51a8..890694d 100644 --- a/docs/pages/cn/explanation/enterprise-sdk.mdx +++ b/docs/pages/cn/explanation/enterprise-sdk.mdx @@ -1,21 +1,21 @@ --- source_path: explanation/enterprise-sdk.mdx -source_sha: a632f3be5fbff966d9da230ec302b4ce4e6773f2 +source_sha: f77d007a45637d9c809cdfbe39f1d41190453c40 title: "Stable Enterprise SDK" -description: "使用类型化的 @stablechain/enterprise SDK 从后端中继免 gas 和保证区块空间的交易。" +description: "通过类型化的 @stablechain/enterprise SDK，从您的后端中继免 Gas 费和有保证区块空间的交易。" diataxis: "explanation" --- # Stable Enterprise SDK -`@stablechain/enterprise` 是 Stable 企业交易通道的服务器端 TypeScript 客户端。它会签署并中继两种特权交易：免 gas 交易（由您来支付用户的 gas）和保证区块空间交易（在保留的企业通道中处理）。您可以在一个客户端上启用其中一个或两个通道。 +`@stablechain/enterprise` 是 Stable 企业交易轨道的服务器端 TypeScript 客户端。它签署并中继两种特权交易：免 Gas 费交易，即您为用户的 Gas 费买单；以及有保证区块空间交易，它们落在预留的企业通道中。您可以在一个客户端上启用任一或两种轨道。 ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") }, }); @@ -26,45 +26,48 @@ const { txHash } = await enterprise.gasWaiver.send(user, { to: token, data }); txHash: 0x8f3a...2d41 ``` -此调用返回 `H_inner`，即用户交易的哈希，而不是承载它的包装器交易的哈希。 +此调用返回 `H_inner`，即用户交易的哈希，而不是承载它的封装交易。 -## SDK 的作用 +## SDK 的功能 -SDK 暴露了三个功能，每个模块一个。每个功能都是可选的、独立配置的，并且都带有自己的签名账户，以便您可以使用单独的密钥。 +SDK 提供了三个功能，每个模块一个。每个功能都是可选的，可以独立配置，并且每个功能都有自己的签名账户，因此您可以使用单独的密钥。 -- **免 gas 中继** (`gasWaiver`)：构建、签署并中继免 gas 交易。一个白名单中的免 gas 账户会封装用户的零 gas 交易，这样用户就可以在不持有任何 USDT0 的情况下进行交易。请参阅[免 gas](/cn/explanation/gas-waiver)。 -- **保证区块空间** (`guaranteedBlock`)：通过企业 RPC 网关中继交易，使其落在保留的企业通道区块空间中。与免 gas 不同，签名者支付自己的 gas。请参阅[保证区块空间](/cn/explanation/guaranteed-blockspace)。 -- **保证中继交易** (`guaranteedWaiver`)：两者结合。一种通过保证区块空间路由的免 gas 交易，这样用户就不需要余额，并且交易仍然落在企业通道中。 +- **免 Gas 中继** (`gasWaiver`)：构建、签署和中继免 Gas 费交易。一个白名单的豁免账户封装用户的零 Gas 交易，以便用户在不持有任何 USDT0 的情况下进行交易。请参阅[免 Gas 费](/cn/explanation/gas-waiver)。 +- **有保证的区块空间** (`guaranteedBlock`)：通过企业 RPC 网关中继交易，使其落在预留的企业通道区块空间中。与免 Gas 费不同，签名者支付自己的 Gas 费。请参阅[有保证的区块空间](/cn/explanation/guaranteed-blockspace)。 +- **有保证的中继交易** (`guaranteedWaiver`)：两者结合。通过有保证的区块空间路由的免 Gas 费交易，因此用户不需要余额，并且交易仍落在企业通道中。 -每个功能都提供相同的四种方法：`send` 和 `sendBatch` 用于 SDK 签名的托管路径，以及 `relay` 和 `relayBatch` 用于用户在其他地方签名并只向您提供签名十六进制的非托管路径。 +每个功能都提供相同的四种方法：`send` 和 `sendBatch` 用于 SDK 签名的托管路径，以及 `relay` 和 `relayBatch` 用于用户在其他地方签名并仅向您提供已签名十六进制的非托管路径。 -## 访问权限 +SDK 在 npm 上发布为 [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise)，当前版本为 1.0.0，并且需要 `viem >= 2.0.0` 作为对等依赖项。 -企业 SDK 目前仅在 Stable Testnet 上可用。 +## 访问 -这两个通道都是受限的。免 gas 需要治理注册的免 gas 密钥，而保证区块空间需要企业 RPC 网关 API 密钥。要进行集成，请[联系 Stable](https://discord.gg/stablexyz) 以获取访问权限。Stable 会为您提供所需的免 gas 密钥和网关端点。 +企业版 SDK 可在 Stable 主网和 Stable 测试网上使用。将 `stable` 用于主网，或将 `stableTestnet` 用于测试网，作为客户端的 `chain`；两者都由包重新导出。 + +这两个轨道都是受限的。免 Gas 费需要治理注册的豁免密钥，而保证区块空间需要企业 RPC 网关 API 密钥。要进行集成，请[联系 Stable](https://discord.gg/stablexyz) 以获取访问权限。Stable 会提供您需要的豁免密钥和网关端点。 ## 仅限服务器端 :::warning -企业 SDK 是一个无状态的服务器端库，使用私钥进行签名。切勿在浏览器中运行它。请将免 gas 密钥和企业 RPC 网关 URL 保留在您的后端。 +企业版 SDK 是一个无状态的服务器端库，它使用私钥进行签名。切勿在浏览器中运行它。将豁免密钥和企业 RPC 网关 URL 保留在您的后端。 ::: -免 gas 密钥是一个列入白名单的、经过治理注册的账户：任何持有它的人都可以根据您的策略支付 gas。企业 RPC 网关 URL 嵌入了您的 API 密钥。请将两者都视为秘密。为了使免 gas 密钥不被泄露，请使用 AWS KMS 等托管签名服务对其进行备份。请参阅[签名密钥和托管](/cn/reference/enterprise-sdk#signing-keys-and-custody)。 +豁免密钥是经过白名单的、经过治理注册的账户：任何持有它的人都可以根据您的策略赞助 Gas 费。企业 RPC 网关 URL 嵌入了您的 API 密钥。请将两者都视为秘密。为了使豁免密钥脱离进程，请使用 AWS KMS 等托管签名器对其进行备份。请参阅[签名密钥和托管](/cn/reference/enterprise-sdk#signing-keys-and-custody)。 -## 何时使用 +## 何时使用它 -当您运营后端并希望为用户支付 gas 或为自己的流量保证交易包含时，请使用企业 SDK。对于后端或浏览器中的日常转账、桥接、兑换和金库收益，请改用通用[Stable SDK](/cn/explanation/sdk-overview)。 +当您操作后端并希望为用户提供 Gas 费或保证您自己的流量包含在内时，请使用企业版 SDK。对于日常转账、桥接、兑换以及来自后端或浏览器的金库收益，请改用通用的 [Stable SDK](/cn/explanation/sdk-overview)。 ## 从这里开始 -- [**免 gas 中继**](/cn/how-to/relay-with-gas-waiver)：为用户支付 gas，这样他们就可以在不持有 USDT0 的情况下进行交易。 -- [**发送保证交易**](/cn/how-to/send-guaranteed-transactions)：将交易落在保留的企业通道区块空间中。 -- [**保证中继交易**](/cn/how-to/guaranteed-relayed-transactions)：结合这两个通道：企业通道中的免 gas 交易。 -- [**企业 SDK 参考**](/cn/reference/enterprise-sdk)：每个模块、方法、配置选项和错误类。 +- [**免 Gas 中继**](/cn/how-to/relay-with-gas-waiver)：为用户提供 Gas 费，以便他们在不持有 USDT0 的情况下进行交易。 +- [**发送有保证的交易**](/cn/how-to/send-guaranteed-transactions)：将交易放入预留的企业通道区块空间。 +- [**有保证的中继交易**](/cn/how-to/guaranteed-relayed-transactions)：结合两种轨道：企业通道中的免 Gas 费交易。 +- [**企业版 SDK 参考**](/cn/reference/enterprise-sdk)：每个模块、方法、配置选项和错误类。 ## 下一步建议 -- [**免 gas 协议**](/cn/reference/gas-waiver-api)：交易格式、标记路由和治理控制。 +- [**从 npm 安装**](https://www.npmjs.com/package/@stablechain/enterprise)：在 npmjs.com 上查看包并检查最新版本。 +- [**免 Gas 费协议**](/cn/reference/gas-waiver-api)：交易格式、标记路由和治理控制。 - [**Stable SDK**](/cn/explanation/sdk-overview)：用于转账、桥接、兑换和收益的通用客户端。 -- [**连接 Stable**](/cn/reference/connect)：测试网的链 ID、RPC 端点和浏览器。 +- [**连接到 Stable**](/cn/reference/connect)：主网和测试网的链 ID、RPC 端点和浏览器。 diff --git a/docs/pages/cn/how-to/guaranteed-relayed-transactions.mdx b/docs/pages/cn/how-to/guaranteed-relayed-transactions.mdx index efd32f8..d2f8002 100644 --- a/docs/pages/cn/how-to/guaranteed-relayed-transactions.mdx +++ b/docs/pages/cn/how-to/guaranteed-relayed-transactions.mdx @@ -1,36 +1,36 @@ --- source_path: how-to/guaranteed-relayed-transactions.mdx -source_sha: 007be0e546cc1251771678ee74523b6a79a2d76d -title: "保证中继交易" -description: "通过 Enterprise SDK 经由保证的区块空间中继免 gas 交易，这样用户无需余额也能进入 Enterprise 通道。" +source_sha: 00233758654be019d706aca71cc6537d441cd552 +title: "有保障的中继交易" +description: "通过 Enterprise SDK 提供的有保障区块空间中继免燃料费交易，这样用户无需余额即可进入企业通道。" diataxis: "how-to" --- -# 保证中继交易 +# 有保障的中继交易 -将 Stable 企业级网络与 `@stablechain/enterprise` 结合使用。保证中继交易是[免 gas 交易](/cn/how-to/relay-with-gas-waiver)，其通过[保证的区块空间](/cn/how-to/send-guaranteed-transactions)进行路由：免除交易费的功能支付 gas 费，因此用户无需余额和费用字段，交易仍会进入预留的 Enterprise 通道。 +将 Stable Enterprise 的两种功能与 `@stablechain/enterprise` 结合使用。有保障的中继交易是 [免燃料费交易](/cn/how-to/relay-with-gas-waiver)，它通过[有保障的区块空间](/cn/how-to/send-guaranteed-transactions)进行路由：免除燃料费赞助燃料，因此用户无需余额和燃料费字段，交易仍能进入预留的企业通道。 -`guaranteedWaiver` 模块同时处理这两个方面。用户签署内部的 `0x3F` CustomTx，白名单中的免除交易费账户将其包装在一个共享相同 Enterprise `nonceKey` 的外部 `0x3F` CustomTx 中，并通过 Enterprise RPC 网关广播。每个方法都返回 `H_inner`，即用户的交易哈希。 +`guaranteedWaiver` 模块处理两方面。用户签署内部 `0x3F` CustomTx，白名单中的免燃料费账户将其包装在一个外部 `0x3F` CustomTx 中，共享相同的 Enterprise `nonceKey`，并通过 Enterprise RPC 网关广播。每个方法都返回 `H_inner`，即用户的交易哈希。 -## 前提条件 +## 先决条件 -- Node.js 20 或更高版本，并安装 `@stablechain/enterprise` 和 `viem`。请参阅 [Enterprise SDK 参考](/cn/reference/enterprise-sdk#install)。 -- 一个在治理层注册的免除交易费密钥和一个 Enterprise RPC 网关 API 密钥。Enterprise SDK 目前仅支持测试网，并且需要申请访问权限：[联系 Stable](https://discord.gg/stablexyz) 以获取这两项。 +- Node.js 20 或更高版本，并安装了 `@stablechain/enterprise` 和 `viem`。请参阅 [Enterprise SDK 参考](/cn/reference/enterprise-sdk#install)。 +- 一个治理注册的免燃料费密钥和一个 Enterprise RPC 网关 API 密钥。Enterprise SDK 在 Stable 主网和 Stable 测试网上运行，访问权限需要申请：[联系 Stable](https://discord.gg/stablexyz) 以获取两者。 :::warning -这是一个服务器端库。请将免除交易费密钥和 Enterprise RPC 网关 URL 保留在您的后端：网关 URL 嵌入了您的 API 密钥。 +这是一个服务器端库。将免燃料费密钥和 Enterprise RPC 网关 URL 保存在后端：网关 URL 嵌入了您的 API 密钥。 ::: -## 1. 使用保证免除交易费模块创建客户端 +## 1. 创建一个包含有保障免燃料费模块的客户端 -将 `guaranteedWaiver` 和 `enterpriseRpcEndpoints` 传递给 `createStableEnterprise`。该模块接收白名单中的免除交易费密钥 (用于签署外部包装器) 和 Enterprise 通道。它还接受与 `gasWaiver` 相同的 `allowedTargets`、`maxGasLimit` 和 `maxDataLength` 策略限制。 +将 `guaranteedWaiver` 和 `enterpriseRpcEndpoints` 传递给 `createStableEnterprise`。该模块接受白名单中的免燃料费密钥（用于签署外部包装器）和 Enterprise 通道。它还接受与 `gasWaiver` 相同的 `allowedTargets`、`maxGasLimit` 和 `maxDataLength` 策略限制。 ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions guaranteedWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`), @@ -46,12 +46,12 @@ StableEnterpriseClient { gasWaiver: undefined, guaranteedBlock: undefined, guara ``` :::tip -要将免除交易费密钥保留在托管后端中，请传递 `signer` 而不是 `account`。`@stablechain/enterprise/aws-kms` 中的 `awsKmsSigner` 支持 AWS KMS。请参阅[签名密钥和托管](/cn/reference/enterprise-sdk#signing-keys-and-custody)。 +要将免燃料费密钥保存在托管后端，请传递 `signer` 而不是 `account`。`@stablechain/enterprise/aws-kms` 中的 `awsKmsSigner` 使用 AWS KMS 支持它。请参阅[签名密钥和托管](/cn/reference/enterprise-sdk#signing-keys-and-custody)。 ::: -## 2. 中继单个交易 +## 2. 中继单笔交易 -使用用户账户和变化的字段调用 `send`。由于免除了 gas 费，用户不需要余额和费用字段。内部的 `0x3F` CustomTx、其 Enterprise `nonceKey` 和 2D nonce (从网关发现) 都会为您处理。 +使用用户的账户和变化的字段调用 `send`。燃料费被免除，因此用户不需要余额和燃料费字段。内部的 `0x3F` CustomTx、其 Enterprise `nonceKey` 和 2D 随机数（从网关发现）都会为您处理。 ```ts const user = privateKeyToAccount(process.env.USER_PRIVATE_KEY as `0x${string}`); @@ -64,11 +64,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -`gas` 默认为共享的内部 gas 默认值；仅在覆盖时传递。允许价值转移，因此您也可以传递 `value`。 +`gas` 默认为共享的内部燃料默认值；仅在需要覆盖时才传递它。允许价值转移，因此您也可以传递 `value`。 ## 3. 中继批次交易 -调用 `sendBatch` 中继来自一个用户的多笔交易。内部 nonce 会从发现的基本 nonce 自动排序，并且您会按照输入顺序获得每个输入的单个结果。失败会导致其后续交易无法进行。 +调用 `sendBatch` 中继来自一个用户的多笔交易。内部随机数从发现的基数自动排序，您会按输入顺序获得每个输入的结果。失败会影响其后续交易。 ```ts const results = await gw.sendBatch(user, [{ to: a }, { to: b }]); @@ -85,13 +85,13 @@ for (const r of results) { ## 4. 中继预签名交易 -对于非托管流程，用户在其自己的环境中签署内部 `0x3F` CustomTx，并只向您提供签名的十六进制数据。使用 `buildGuaranteedTx` 构建它，其中 Enterprise nonce 密钥使用 `nonceKeyForLane`，费用为零 (gas 已免除)。您的后端会使用免除交易费密钥对其进行封装，并使用 `relay` 进行中继。 +对于非托管流程，用户在其自己的环境中签署内部 `0x3F` CustomTx，并只向您提供签名的十六进制数据。使用 `buildGuaranteedTx` 构建它，使用 `nonceKeyForLane` 获取 Enterprise 随机数密钥和零费用（燃料费被免除）。您的后端使用免燃料费密钥包装它，并使用 `relay` 中继它。 ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; // on the user's side — buildGuaranteedTx signs through a Signer; toSigner adapts a viem account -const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { +const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, { to: recipient, gas: 100_000n, gasFeeCap: 0n, // waived @@ -109,11 +109,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -对于多个预签名交易，请使用 `relayBatch`。 +对于多笔预签名交易，请使用 `relayBatch`。 ## 处理拒绝 -`send` 和 `relay` 在拒绝时会抛出 `StableEnterpriseRelayError`。由于此流程通过网关路由，因此网关代码 (如 `GATEWAY_UNAUTHORIZED` 和 `QUOTA_EXCEEDED`) 以及免除交易费策略代码 (如 `TARGET_NOT_ALLOWED`) 都适用。 +`send` 和 `relay` 在拒绝时会抛出 `StableEnterpriseRelayError`。由于此流程通过网关路由，因此 `GATEWAY_UNAUTHORIZED` 和 `QUOTA_EXCEEDED` 等网关代码以及 `TARGET_NOT_ALLOWED` 等免燃料费策略代码都适用。 ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -134,8 +134,8 @@ StableEnterpriseRelayError: relay failed [GATEWAY_UNAUTHORIZED]: invalid api key 请参阅完整的 [`ErrorCode`](/cn/reference/enterprise-sdk#errorcode) 表，了解所有拒绝原因。 -## 接下来去哪里 +## 下一步 -- [**使用免 gas 功能中继**](/cn/how-to/relay-with-gas-waiver)：为用户支付 gas 费，无需保证通道。 -- [**发送保证交易**](/cn/how-to/send-guaranteed-transactions)：单独使用保证区块空间，由签署者支付 gas 费。 +- [**免燃料费中继**](/cn/how-to/relay-with-gas-waiver)：为用户赞助燃料费，而无需有保障的通道。 +- [**发送有保障的交易**](/cn/how-to/send-guaranteed-transactions)：单独使用有保障的区块空间，由签名者支付燃料费。 - [**Enterprise SDK 参考**](/cn/reference/enterprise-sdk#guaranteed-relay-transactions)：所有方法、配置选项和错误类的完整说明。 diff --git a/docs/pages/cn/how-to/relay-with-gas-waiver.mdx b/docs/pages/cn/how-to/relay-with-gas-waiver.mdx index a68208c..c88b5db 100644 --- a/docs/pages/cn/how-to/relay-with-gas-waiver.mdx +++ b/docs/pages/cn/how-to/relay-with-gas-waiver.mdx @@ -1,36 +1,36 @@ --- source_path: how-to/relay-with-gas-waiver.mdx -source_sha: c1b34aab292d8e9623b59810cd6b668468e834ce -title: "使用 Gas 代付中继交易" -description: "使用 Enterprise SDK 赞助用户的 gas：中继零 gas 交易、批量中继、强制执行策略限制以及中继预签名交易。" +source_sha: a41b82da40c922244690f2e8e05d8f9ad1f34a99 +title: "使用 Gas 代付中继" +description: "通过 Enterprise SDK 赞助用户的 gas：中继零 gas 交易、批量中继、强制执行策略限制以及中继预签名交易。" diataxis: "how-to" --- -# 使用 Gas 代付中继交易 +# 使用 Gas 代付中继 -使用 `@stablechain/enterprise` 赞助用户的 gas 费用。白名单代付账户会包装用户的零 gas 交易 (InnerTx) 并广播它，因此用户无需持有任何 USDT0 即可进行交易。`gasWaiver` 模块在一个调用中构建、签名和中继，因此您每个操作只需调用一个方法。 +使用 `@stablechain/enterprise` 赞助您用户的 gas。白名单中的代付账户会包装用户的零 gas 交易（内部交易），并将其广播，这样用户就可以在不持有任何 USDT0 的情况下进行交易。`gasWaiver` 模块在一个调用中构建、签名和中继，因此您每个操作只需调用一个方法。 -每个方法都返回 `H_inner`，即用户交易的哈希，而不是承载它的包装器。 +每个方法都返回 `H_inner`，即用户交易的哈希，而不是携带它的包装器。 ## 先决条件 - Node.js 20 或更高版本，并安装了 `@stablechain/enterprise` 和 `viem`。请参阅 [Enterprise SDK 参考](/cn/reference/enterprise-sdk#install)。 -- 治理注册的代付密钥。Enterprise SDK 目前仅限测试网，并且访问受限：[联系 Stable](https://discord.gg/stablexyz) 获取白名单代付密钥。 +- 治理注册的代付密钥。Enterprise SDK 在 Stable 主网和 Stable 测试网上运行，访问受限：[联系 Stable](https://discord.gg/stablexyz) 获取白名单代付密钥。 :::warning -这是一个使用私钥进行签名的服务器端库。切勿在浏览器中运行它。将代付密钥保存在您的后端。 +这是一个使用私钥进行签名的服务器端库。切勿在浏览器中运行它。请将代付密钥保存在您的后端。 ::: -## 1. 使用 gas 代付模块创建客户端 +## 1. 使用 Gas 代付模块创建客户端 -将 `gasWaiver: { account }` 传递给 `createStableEnterprise`，其中 `account` 是您的白名单代付密钥。仅在您配置后，模块才会在客户端上出现。 +将 `gasWaiver: { account }` 传递给 `createStableEnterprise`，其中 `account` 是您的白名单代付密钥。只有在配置后，模块才会在客户端上出现。 ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`) }, }); @@ -41,15 +41,15 @@ const gw = enterprise.gasWaiver; StableEnterpriseClient { gasWaiver, guaranteedBlock: undefined, guaranteedWaiver: undefined } ``` -`rpcEndpoints` 选项是可选的。如果未设置，客户端将使用链的内置 RPC。 +`rpcEndpoints` 选项是可选的。如果不设置，客户端将使用链的内置 RPC。 :::tip -要将代付密钥保存在托管后端中，请传递 `signer` 而不是 `account`。`@stablechain/enterprise/aws-kms` 中的 `awsKmsSigner` 支持 AWS KMS。请参阅[签名密钥和托管](/cn/reference/enterprise-sdk#signing-keys-and-custody)。 +要将代付密钥保存在托管后端中，请传递 `signer` 而不是 `account`。来自 `@stablechain/enterprise/aws-kms` 的 `awsKmsSigner` 支持 AWS KMS。请参阅[签名密钥和托管](/cn/reference/enterprise-sdk#signing-keys-and-custody)。 ::: ## 2. 中继单个交易 -使用用户帐户和变化的字段调用 `send`。`gasPrice: 0`、旧版类型、`chainId` 和待处理 Nonce 都已为您处理，因此您只需传递 `to`，以及可选的 `data`、`value` 和 `gas`。 +使用用户账户和变化的字段调用 `send`。`gasPrice: 0`、遗留类型、`chainId` 和待处理 nonce 都已为您处理，因此您只需传递 `to`，以及可选的 `data`、`value` 和 `gas`。 ```ts const user = privateKeyToAccount(process.env.USER_PRIVATE_KEY as `0x${string}`); @@ -62,11 +62,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -用户不需要 USDT0：代付账户会赞助 gas。`gas` 默认为 `150_000n` (`DEFAULT_INNER_GAS`)，足以覆盖代币转账或批准。对于更复杂的调用，请传递显式的 `gas`。 +用户不需要 USDT0：代付账户赞助 gas。`gas` 默认为 `150_000n` (`DEFAULT_INNER_GAS`)，足以覆盖代币转账或批准。对于更繁重的调用，请传递明确的 `gas`。 -## 3. 批量中继 +## 3. 中继批处理 -调用 `sendBatch` 从一个账户中继多笔交易。Nonce 会根据账户的待处理 Nonce 自动排序，并且您会按输入顺序获得每个输入的结果。 +调用 `sendBatch` 中继来自一个账户的多个交易。Nonce 会从账户的待处理 nonce 自动排序，并且您会按照输入顺序获得每个输入的单个结果。 ```ts const results = await gw.sendBatch(user, [ @@ -84,37 +84,37 @@ for (const r of results) { [1] ✔ 0x2b7c...9e04 ``` -批量处理报告每个项目的失败 `result.error` 而不是抛出异常，因此一个糟糕的交易不会影响其余交易。 +批处理会根据 `result.error` 报告每个项目的失败，而不是抛出异常，因此一个糟糕的交易不会导致其余交易失败。 ## 4. 执行每个合作伙伴的策略限制 -通过向配置添加策略限制来限制代付密钥可以赞助的内容。违反限制的 InnerTx 在广播前将被拒绝。 +通过在配置中添加策略限制来限制代付密钥可以赞助的内容。违反限制的内部交易会在广播前被拒绝。 ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`), maxGasLimit: 500_000n, maxDataLength: 4_096, allowedTargets: [ - { address: token, selectors: ["0xa9059cbb"] }, // ERC-20 transfer only + { address: token, selectors: ["0xa9059cbb"] }, // 仅限 ERC-20 传输 ], }, }); ``` -针对 `allowedTargets` 之外的合约的交易将失败并显示 `TARGET_NOT_ALLOWED`；超过 `maxGasLimit` 的交易将失败并显示 `GAS_LIMIT_EXCEEDED`。使用 `"*"` 作为 `address` 允许任何合约，并省略 `selectors` 允许任何方法。 +目标合约不在 `allowedTargets` 中的交易将因 `TARGET_NOT_ALLOWED` 而失败；超过 `maxGasLimit` 的交易将因 `GAS_LIMIT_EXCEEDED` 而失败。使用 `"*"` 作为 `address` 允许任何合约，省略 `selectors` 允许任何方法。 ## 5. 中继预签名交易 -对于非托管流程，用户在其自己的环境中签署 InnerTx 并仅将签名十六进制传递给您，因此您永远不会看到他们的密钥。使用 `buildWaiverInnerTx` 构建它，然后使用 `relay` 中继它。 +对于非托管流程，用户在其自己的环境中签署内部交易，并只将签名的十六进制字符串交给您，因此您永远不会看到他们的密钥。使用 `buildWaiverInnerTx` 构建它，然后使用 `relay` 中继它。 ```ts import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise"; // 在用户端 — buildWaiverInnerTx 通过 Signer 签名；toSigner 适配 viem 账户 -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to: token, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to: token, data, gas: 150_000n, nonce }); // 在您的后端 const { txHash } = await gw.relay(signed); @@ -125,11 +125,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -对于多个预签名交易，请使用 `relayBatch`，它像 `sendBatch` 一样为每个输入返回一个结果。 +对于多个预签名交易，请使用 `relayBatch`，它会像 `sendBatch` 一样为每个输入返回一个结果。 ## 处理拒绝 -`send` 和 `relay` 在拒绝时会抛出 `StableEnterpriseRelayError`，并带有您可以分支的 `code`。 +`send` 和 `relay` 在拒绝时会抛出 `StableEnterpriseRelayError`，其中包含一个您可以进行分支判断的 `code`。 ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -138,7 +138,7 @@ try { await gw.send(user, { to: token, data }); } catch (err) { if (err instanceof StableEnterpriseRelayError && err.code === "TARGET_NOT_ALLOWED") { - // InnerTx 目标不在配置的白名单中 + // 内部交易目标不在配置的允许列表中 } throw err; } @@ -148,10 +148,10 @@ try { StableEnterpriseRelayError: relay failed [TARGET_NOT_ALLOWED]: target 0x... not allowed ``` -请参阅完整的 [`ErrorCode`](/cn/reference/enterprise-sdk#errorcode) 表格以了解所有拒绝原因。 +有关所有拒绝原因的完整信息，请参阅完整的 [`ErrorCode`](/cn/reference/enterprise-sdk#errorcode) 表。 -## 下一步 +## 后续步骤 -- [**发送保证交易**](/cn/how-to/send-guaranteed-transactions)：在保留的 Enterprise 通道区块空间中进行交易，并将其与 gas 代付结合使用。 -- [**Enterprise SDK 参考**](/cn/reference/enterprise-sdk#relay-with-gas-waiver)：每个方法、配置选项和错误类的完整说明。 -- [**Gas 代付**](/cn/explanation/gas-waiver)：协议级别的零 gas 交易工作原理。 +- [**发送保证交易**](/cn/how-to/send-guaranteed-transactions)：在保留的 Enterprise 通道区块空间中发送交易，并结合 Gas 代付。 +- [**Enterprise SDK 参考**](/cn/reference/enterprise-sdk#relay-with-gas-waiver)：所有方法、配置选项和错误类的完整信息。 +- [**Gas 代付**](/cn/explanation/gas-waiver)：零 gas 交易在协议层如何工作。 diff --git a/docs/pages/cn/how-to/send-guaranteed-transactions.mdx b/docs/pages/cn/how-to/send-guaranteed-transactions.mdx index 805ce1d..d85131c 100644 --- a/docs/pages/cn/how-to/send-guaranteed-transactions.mdx +++ b/docs/pages/cn/how-to/send-guaranteed-transactions.mdx @@ -1,37 +1,37 @@ --- source_path: how-to/send-guaranteed-transactions.mdx -source_sha: 6da305c74e7ddb43f31a4ed11e7f4d5313f0cabe -title: "发送担保交易" -description: "使用 Enterprise SDK 在预留的 Enterprise-lane 区块空间中执行交易，并将担保区块空间与免燃气费结合起来，实现无燃气转发。" +source_sha: 5debec9526aaf679f040bd9a03213935283d5a36 +title: "发送保障交易" +description: "使用 Enterprise SDK 在预留的企业通道区块空间中落地交易，并将保障区块空间与免 Gas 费结合，以实现免 Gas 转发交易。" diataxis: "how-to" --- -# 发送担保交易 +# 发送保障交易 -使用 `@stablechain/enterprise` 通过预留的 Enterprise-lane 区块空间路由交易。`guaranteedBlock` 模块通过 Enterprise RPC 网关转发 GuaranteedTx (一种 `0x3F` 类型的 CustomTx)，使其进入为企业工作负载预留的容量中。与免燃气费不同，签名者需要支付自己的燃气费，因此必须有足够的资金。 +使用 `@stablechain/enterprise` 通过预留的企业通道区块空间路由交易。`guaranteedBlock` 模块通过 Enterprise RPC 网关转发 GuaranteedTx (一种 `0x3F` 类型 CustomTx)，使其落地在为企业工作负载预留的容量中。与免 Gas 费不同，签名者需要支付自己的 Gas 费，因此必须有足够的资金。 -您可以将其与免燃气费结合使用，以获得[担保转发交易](/cn/how-to/guaranteed-relayed-transactions)：免燃气费交易仍能进入企业通道。 +您可以将此功能与免 Gas 费结合使用，以获得[保障转发交易](/cn/how-to/guaranteed-relayed-transactions)：即免 Gas 费交易仍能在企业通道中落地。 ## 先决条件 -- Node.js 20 或更高版本，并安装 `@stablechain/enterprise` 和 `viem`。请参阅 [Enterprise SDK 参考](/cn/reference/enterprise-sdk#install)。 -- Enterprise RPC 网关 API 密钥。Enterprise SDK 目前仅支持测试网，并且访问受限：[联系 Stable](https://discord.gg/stablexyz) 获取网关端点。 -- 一个有资金的签名者，因为 GuaranteedTx 需要支付自己的燃气费。 +- Node.js 20 或更高版本，并安装了 `@stablechain/enterprise` 和 `viem`。请参阅 [Enterprise SDK 参考](/cn/reference/enterprise-sdk#install)。 +- 一个 Enterprise RPC 网关 API 密钥。Enterprise SDK 在 Stable 主网和 Stable 测试网上运行，并且访问受限：请[联系 Stable](https://discord.gg/stablexyz) 获取网关端点。 +- 一个资金充足的签名者，因为 GuaranteedTx 需要支付自己的 Gas 费。 :::warning -这是一个服务器端库。将 Enterprise RPC 网关 URL 保留在您的后端：它嵌入了您的 API 密钥。 +这是一个服务器端库。请将 Enterprise RPC 网关 URL 保留在您的后端：它嵌入了您的 API 密钥。 ::: -## 1. 使用担保区块空间模块创建客户端 +## 1. 使用保障区块空间模块创建客户端 -将 `guaranteedBlock` 和 `enterpriseRpcEndpoints` 传递给 `createStableEnterprise`。网关是唯一接受 `0x3F` GuaranteedTxs 的端点，并且它包含您的 API 密钥。无效的 `laneId` 会被提前拒绝。 +将 `guaranteedBlock` 和 `enterpriseRpcEndpoints` 传递给 `createStableEnterprise`。网关是唯一接受 `0x3F` GuaranteedTx 的端点，并且它持有您的 API 密钥。无效的 `laneId` 会立即被拒绝。 ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions guaranteedBlock: { account: privateKeyToAccount(process.env.SIGNER_PRIVATE_KEY as `0x${string}`), // must be funded @@ -48,12 +48,12 @@ StableEnterpriseClient { gasWaiver: undefined, guaranteedBlock, guaranteedWaiver ## 2. 发送单笔交易 -使用签名者和可变字段调用 `send`。1559 费用字段是必需的，因为签名者需要支付燃气费。`chainId`、Enterprise `nonceKey` 和 2D nonce（从网关中发现）已为您处理。 +使用签名者和可变字段调用 `send`。由于签名者支付 Gas 费，因此 1559 费用字段是必需的。`chainId`、企业 `nonceKey` 和 2D nonce（从网关发现）会为您处理。 ```ts import { createPublicClient, http } from "viem"; -const publicClient = createPublicClient({ chain: stableTestnet, transport: http() }); +const publicClient = createPublicClient({ chain: stable, transport: http() }); const gasPrice = await publicClient.getGasPrice(); const { txHash } = await gb.send(signer, { @@ -69,13 +69,13 @@ console.log("Guaranteed tx:", txHash); Guaranteed tx: 0xabcd...7890 ``` -`gasFeeCap` 是每单位燃气的最大总费用（EIP-1559 `maxFeePerGas`），`gasTipCap` 是每单位燃气的最大优先费用（`maxPriorityFeePerGas`）。如上所示，将 `gasTipCap` 设置为当前燃气价格并将 `gasFeeCap` 设置为其两倍是一个安全的默认值。 +`gasFeeCap` 是每 Gas 的最大总费用（EIP-1559 `maxFeePerGas`），`gasTipCap` 是每 Gas 的最大优先级费用（`maxPriorityFeePerGas`）。将 `gasTipCap` 设置为当前 Gas 价格，并将 `gasFeeCap` 设置为它的两倍（如上所示）是一个安全的默认值。 -签名者支付燃气费，因此请在转发前确认其持有余额。来自零余额账户的 GuaranteedTx 会失败。 +签名者支付 Gas 费，因此在转发之前请确认它持有余额。来自零余额账户的 GuaranteedTx 会失败。 ## 3. 发送批处理 -调用 `sendBatch` 发送多笔交易。Nonce 会从发现的基础自动排序，并且您会按输入顺序获得每个输入的一个结果。失败会使其后续交易受阻。 +调用 `sendBatch` 发送多笔交易。Nonce 会从发现的基础自动排序，并且您会得到每个输入的单个结果，按输入顺序排列。一个失败会使其后续交易受阻。 ```ts const results = await gb.sendBatch(signer, [ @@ -95,12 +95,12 @@ for (const r of results) { ## 4. 发送预签名交易 -对于非托管流程，使用 `buildGuaranteedTx` 在其他地方构建并签署 GuaranteedTx，然后只将签署的十六进制数据交给操作员。Enterprise nonce 密钥来自 `nonceKeyForLane`。 +对于非托管流程，使用 `buildGuaranteedTx` 在其他地方构建并签署 GuaranteedTx，然后只将签名后的十六进制字符串交给操作员。企业 Nonce 密钥来自 `nonceKeyForLane`。 ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signed = await buildGuaranteedTx(toSigner(signer), stableTestnet.id, { +const signed = await buildGuaranteedTx(toSigner(signer), stable.id, { to: recipient, gas: 21_000n, gasFeeCap, @@ -119,13 +119,13 @@ Guaranteed tx: 0xabcd...7890 对于多笔预签名交易，请使用 `relayBatch`。 -## 与免燃气费结合 +## 与免 Gas 费结合 -要免除用户的燃气费并仍进入 Enterprise 通道，请使用 `guaranteedWaiver` 模块组合两个轨道。用户无需余额和费用字段，并且交易通过相同的网关进行路由。请参阅[担保转发交易](/cn/how-to/guaranteed-relayed-transactions)。 +要免除用户的 Gas 费并仍能落地在企业通道中，请使用 `guaranteedWaiver` 模块组合这两个机制。用户无需余额和费用字段，并且交易会通过相同的网关进行路由。请参阅[保障转发交易](/cn/how-to/guaranteed-relayed-transactions)。 ## 处理拒绝 -`send` 和 `relay` 在拒绝时会抛出 `StableEnterpriseRelayError`。网关特定的错误代码包括 `GATEWAY_UNAUTHORIZED`（API 密钥缺失或无效）和 `QUOTA_EXCEEDED`（网关燃气配额已用尽）。 +`send` 和 `relay` 在被拒绝时会抛出 `StableEnterpriseRelayError`。网关特定的代码包括 `GATEWAY_UNAUTHORIZED`（API 密钥缺失或无效）和 `QUOTA_EXCEEDED`（网关 Gas 配额已用尽）。 ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -144,8 +144,8 @@ try { StableEnterpriseRelayError: relay failed [GATEWAY_UNAUTHORIZED]: invalid api key ``` -## 下一步 +## 接下来去哪里 -- [**担保转发交易**](/cn/how-to/guaranteed-relayed-transactions)：一次调用即可免除用户的燃气费并进入 Enterprise 通道。 -- [**免燃气费转发**](/cn/how-to/relay-with-gas-waiver)：为用户的燃气费提供赞助，以便他们在不持有 USDT0 的情况下进行交易。 +- [**保障转发交易**](/cn/how-to/guaranteed-relayed-transactions)：一键免除用户 Gas 费并落地在企业通道中。 +- [**使用免 Gas 费转发**](/cn/how-to/relay-with-gas-waiver)：为用户提供 Gas 赞助，以便他们在不持有 USDT0 的情况下进行交易。 - [**Enterprise SDK 参考**](/cn/reference/enterprise-sdk#guaranteed-blockspace)：所有方法、配置选项和错误类的完整说明。 diff --git a/docs/pages/cn/reference/enterprise-sdk.mdx b/docs/pages/cn/reference/enterprise-sdk.mdx index b860a60..6bbc13f 100644 --- a/docs/pages/cn/reference/enterprise-sdk.mdx +++ b/docs/pages/cn/reference/enterprise-sdk.mdx @@ -1,21 +1,21 @@ --- source_path: reference/enterprise-sdk.mdx -source_sha: d0bc44dc34b19b1a7f7cadeda2ceaa68d296220a -title: "企业级SDK参考" -description: "@stablechain/enterprise 的完整参考：createStableEnterprise、免Gas模块和保证区块空间模块、构建助手以及错误类。" +source_sha: f21ad17590422b54220c7795392ff9eb1917f886 +title: "企业版SDK参考" +description: "@stablechain/enterprise 的完整参考：createStableEnterprise、免燃气费和保证区块空间模块、构建辅助函数以及错误类。" diataxis: "reference" --- -# 企业级SDK参考 +# 企业版SDK参考 -`@stablechain/enterprise` 的完整表面。这涵盖了从 [`createStableEnterprise`](#createstableenterpriseconfig) 客户端开始，其三个功能（[免Gas中继](#relay-with-gas-waiver)、[保证区块空间](#guaranteed-blockspace) 和 [保证中继交易](#guaranteed-relay-transactions)），低级别的构建助手，以及共享结果和错误类型。有关这些原理，请参阅[Stable企业级SDK](/cn/explanation/enterprise-sdk)、[免Gas](/cn/explanation/gas-waiver) 和 [保证区块空间](/cn/explanation/guaranteed-blockspace)。 +`@stablechain/enterprise` 的完整概览。这涵盖了客户端从 [`createStableEnterprise`](#createstableenterpriseconfig) 到其三个特性（[免燃气费中继](#relay-with-gas-waiver)、[保证区块空间](#guaranteed-blockspace)和[保证中继交易](#guaranteed-relay-transactions)）、低级构建辅助函数以及共享结果和错误类型。有关这些概念的解释，请参阅[Stable企业版SDK](/cn/explanation/enterprise-sdk)、[免燃气费](/cn/explanation/gas-waiver)和[保证区块空间](/cn/explanation/guaranteed-blockspace)。 :::note -企业级SDK目前仅在Stable测试网上可用，并且需要申请才能访问。要进行集成，请[联系Stable](https://discord.gg/stablexyz)以获取政fu注册的豁免密钥和企业级RPC网关API密钥。 +企业版SDK可在Stable主网和Stable测试网上使用，并且需要申请才能访问。要进行集成，请[联系Stable](https://discord.gg/stablexyz)以获取治理注册的免燃气费密钥和企业版RPC网关API密钥。 ::: :::warning -这是一个使用私钥进行签名的服务器端库。切勿在浏览器中运行。请将豁免密钥和企业级RPC网关URL保留在您的后端。 +这是一个使用私钥进行签名的服务器端库。切勿在浏览器中运行它。将免燃气费密钥和企业版RPC网关URL保存在您的后端。 ::: ## 安装 @@ -28,18 +28,22 @@ npm install @stablechain/enterprise viem added 2 packages, audited 3 packages in 2s ``` -`viem >= 2.0.0` 是一个对等依赖项。此包重新导出了 `viem/chains` 中的 `stable` 和 `stableTestnet`，因此您无需单独导入它们。 +`viem >= 2.0.0` 是一个对等依赖项。该包以 [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise) 的形式发布，并重新导出 `viem/chains` 中的 `stable` 和 `stableTestnet`，因此您无需单独导入它们。 + +:::note +当前版本是1.0.0。运行 `npm ls @stablechain/enterprise` 以检查您拥有的版本。 +::: ## `createStableEnterprise(config)` 构造一个 `StableEnterpriseClient`。每个模块仅在您配置它时才存在，因此在使用前请进行空值检查。 ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") }, }); ``` @@ -52,39 +56,39 @@ StableEnterpriseClient { gasWaiver, guaranteedBlock: undefined, guaranteedWaiver | **字段** | **类型** | **默认值** | **描述** | | :--- | :--- | :--- | :--- | -| `chain` | `StableChain` | | 目标链。传递 `stable` 或 `stableTestnet`（由包重新导出）。必填。 | +| `chain` | `StableChain` | | 目标链。传递 `stable` 或 `stableTestnet`（由包重新导出）。必填。 | | `rpcEndpoints` | `string[]?` | 链的内置RPC | 一个或多个Stable RPC端点，在失败时按顺序尝试。仅在指向私有端点时才覆盖。 | -| `enterpriseRpcEndpoints` | `string[]?` | | 一个或多个企业级RPC网关端点，在失败时按顺序尝试。`guaranteedBlock` 和 `guaranteedWaiver` 必填。 | +| `enterpriseRpcEndpoints` | `string[]?` | | 一个或多个企业版RPC网关端点，在失败时按顺序尝试。`guaranteedBlock` 和 `guaranteedWaiver` 必填。 | | `batchSizeLimit` | `number?` | `100` | 每个批处理RPC调用的最大交易数量。 | -| `signer` | `Signer?` | | 当模块没有自己的密钥时，免Gas模块（`gasWaiver`，`guaranteedWaiver`）的默认签名者。设置一次以通过单个托管后端驱动两者。请参阅[签名密钥和托管](#signing-keys-and-custody)。 | -| `gasWaiver` | `GasWaiverConfig?` | | 启用[免Gas中继](#relay-with-gas-waiver)。 | -| `guaranteedBlock` | `GuaranteedBlockConfig?` | | 启用[保证区块空间](#guaranteed-blockspace)。 | -| `guaranteedWaiver` | `GuaranteedWaiverConfig?` | | 启用[保证中继交易](#guaranteed-relay-transactions)。 | +| `signer` | `Signer?` | | 免燃气费模块（`gasWaiver`、`guaranteedWaiver`）的默认签名者，当模块没有自己的密钥时。设置一次以通过单个托管后端驱动两者。请参阅[签名密钥和托管](#signing-keys-and-custody)。 | +| `gasWaiver` | `GasWaiverConfig?` | | 启用[免燃气费中继](#relay-with-gas-waiver)。 | +| `guaranteedBlock` | `GuaranteedBlockConfig?` | | 启用[保证区块空间](#guaranteed-blockspace)。 | +| `guaranteedWaiver` | `GuaranteedWaiverConfig?` | | 启用[保证中继交易](#guaranteed-relay-transactions)。 | ### 签名密钥和托管 -持有豁免密钥的模块（`gasWaiver` 和 `guaranteedWaiver`）按顺序解析它：模块自己的 `signer`，然后是它的 `account`（一个进程内的viem密钥），然后是客户端配置中的顶层 [`signer`](#stableenterpriseconfig)，然后是 `STABLE_ENTERPRISE_PRIVATE_KEY` 环境变量。设置顶层 `signer` 一次，即可通过单个托管后端驱动两个豁免模块。`guaranteedBlock` 使用其自身资助的 `account` 进行签名。 +持有免燃气费密钥的模块（`gasWaiver` 和 `guaranteedWaiver`）按顺序解析它：模块自己的 `signer`，然后是其 `account`（一个进程内 viem 密钥），然后是客户端配置上的顶级 [`signer`](#stableenterpriseconfig)，然后是 `STABLE_ENTERPRISE_PRIVATE_KEY` 环境变量。设置顶级 `signer` 一次，以通过单个托管后端驱动两个免燃气费模块。`guaranteedBlock` 使用其自己的已拨款 `account` 进行签名。 -`Signer` 对 32 字节的摘要进行签名，因此密钥从不离开托管后端。对于AWS KMS，请使用 `awsKmsSigner`；要适配viem账户，请使用 `toSigner(account)`；对于进程内密钥，请使用 `privateKeySigner(key)` / `envSigner()`。传递给模块 `send` / `sendBatch` 的每次调用发送者也可以是viem账户或 `Signer`，因此KMS/HSM密钥可以签署内部交易而无需降级到 `relay`。 +`Signer` 签署一个 32 字节的摘要，因此密钥永远不会离开托管后端。使用 `awsKmsSigner` 用于 AWS KMS，`toSigner(account)` 用于适配 viem 账户，或者 `privateKeySigner(key)` / `envSigner()` 用于进程内密钥。传递给模块的 `send` / `sendBatch` 的每次调用发送者也可以是 viem 账户或 `Signer`，因此 KMS/HSM 密钥可以在不降级到 `relay` 的情况下签署内部交易。 ```bash npm install @aws-sdk/client-kms ``` ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { awsKmsSigner } from "@stablechain/enterprise/aws-kms"; -// KMS密钥必须是ECC_SECG_P256K1 (secp256k1)；SDK会从它派生地址 +// KMS 密钥必须是 ECC_SECG_P256K1 (secp256k1)；SDK 从中派生地址 const signer = await awsKmsSigner({ keyId: process.env.AWS_KMS_KEY_ID }); const enterprise = createStableEnterprise({ - chain: stableTestnet, - gasWaiver: { signer }, // 代替 `account` 的托管级免Gas密钥 + chain: stable, + gasWaiver: { signer }, // 托管级别的免燃气费密钥，代替 `account` }); ``` -`awsKmsSigner` 在 `@stablechain/enterprise/aws-kms` 子路径中提供，因此 `@aws-sdk/client-kms` 仍然是一个可选的对等依赖项，不属于核心安装。 +`awsKmsSigner` 在 `@stablechain/enterprise/aws-kms` 子路径中提供，因此 `@aws-sdk/client-kms` 仍然是一个可选的对等依赖项，不在核心安装中。 ### `StableEnterpriseClient` @@ -96,18 +100,18 @@ interface StableEnterpriseClient { } ``` -## 免Gas中继 +## 免燃气费中继 -`gasWaiver` 模块中继免Gas交易。一个白名单豁免账户将用户的零Gas交易（InnerTx）包装成WaiverTx并进行广播。用户不需要USDT0。每个方法都返回 `H_inner`，即InnerTx哈希，而不是包装器哈希。 +`gasWaiver` 模块中继免燃气费交易。列入白名单的免燃气费账户将用户的零燃气费交易 (InnerTx) 封装到 WaiverTx 中并广播。用户无需USDT0。每个方法都返回 `H_inner`，即 InnerTx 的哈希值，而不是封装哈希值。 -在配置中通过 `gasWaiver` 启用它： +在配置中启用 `gasWaiver`： ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY"), - // 可选的每个合作伙伴策略限制 + // 可选的每个合作伙伴的策略限制 maxGasLimit: 500_000n, allowedTargets: [{ address: "0xToken", selectors: ["0xa9059cbb"] }], }, @@ -122,15 +126,15 @@ const gw = enterprise.gasWaiver; | **字段** | **类型** | **描述** | | :--- | :--- | :--- | -| `signer` | `Signer?` | 作为托管签名者（AWS KMS, HSM）的白名单、政fu注册豁免密钥。请参阅[签名密钥和托管](#signing-keys-and-custody)。优先于 `account`。 | -| `account` | `LocalAccount?` | 作为进程内viem账户的豁免密钥。当两者都未设置时，回退到 `STABLE_ENTERPRISE_PRIVATE_KEY`。 | +| `signer` | `Signer?` | 列入白名单的、治理注册的免燃气费密钥作为托管签名者（AWS KMS、HSM）。请参阅[签名密钥和托管](#signing-keys-and-custody)。优先于 `account`。 | +| `account` | `LocalAccount?` | 免燃气费密钥作为进程内viem账户。如果两者都未设置，则回退到 `STABLE_ENTERPRISE_PRIVATE_KEY`。 | | `maxGasLimit` | `bigint?` | 继承自 `ValidationLimits`。 | | `maxDataLength` | `number?` | 继承自 `ValidationLimits`。 | | `allowedTargets` | `AllowedTarget[]?` | 继承自 `ValidationLimits`。 | ### `send(account, tx)` -构建、签名并中继一个`account`的InnerTx，一步到位。`gasPrice: 0`、遗留类型、`chainId`和待处理的nonce都为您处理。拒绝时抛出`StableEnterpriseRelayError`。 +在一个调用中从 `account` 构建、签名和中继一个 InnerTx。`gasPrice: 0`、旧版类型、`chainId` 和待处理 nonce 都为您处理。如果拒绝，则抛出 `StableEnterpriseRelayError`。 ```ts const { txHash } = await gw.send(user, { to: token, data, gas: 150_000n }); @@ -144,7 +148,7 @@ const { txHash } = await gw.send(user, { to: token, data, gas: 150_000n }); ### `sendBatch(account, txs)` -从一个`account`构建、签名并中继多个InnerTx。nonce从账户的待处理nonce开始自动排序。返回每个输入的结g果，按顺序。 +从一个 `account` 构建、签名和中继多个 InnerTx。Nonce 从账户的待处理 nonce 自动排序。每个输入返回一个结果，按顺序。 ```ts const results = await gw.sendBatch(user, [ @@ -157,16 +161,16 @@ const results = await gw.sendBatch(user, [ [ { index: 0, success: true, txHash: "0x..." }, { index: 1, success: true, txHash: "0x..." } ] ``` -`txs` 是一个[`WaiverInnerTx`](#waiverinnertx)的只读数组。返回[`BatchResultItem[]`](#batchresultitem)。 +`txs` 是一个只读的 [`WaiverInnerTx`](#waiverinnertx) 数组。返回 [`BatchResultItem[]`](#batchresultitem)。 ### `relay(signedInnerTxHex)` -中继一个预签名的零Gas InnerTx。这用于非托管流程，其中用户在自己的环境中签名并只向您提供签名的十六进制数据，以便豁免操作员从不看到用户的密钥。使用 [`buildWaiverInnerTx`](#buildwaiverinnertxsigner-chainid-req) 构建一个。拒绝时抛出。 +中继一个预签名的零燃气费 InnerTx。这用于非托管流程，用户在其自己的环境中签名并只向您提供签名的十六进制，因此免燃气费操作员永远不会看到用户的密钥。使用 [`buildWaiverInnerTx`](#buildwaiverinnertxsigner-chainid-req) 构建一个。如果拒绝，则抛出错误。 ```ts import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise"; -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce }); const { txHash } = await gw.relay(signed); ``` @@ -176,7 +180,7 @@ const { txHash } = await gw.relay(signed); ### `relayBatch(signedInnerTxHexes)` -中继一批预签名的 InnerTx。为每个输入按顺序返回一个 [`BatchResultItem`](#batchresultitem)。 +中继一批预签名的 InnerTx。按顺序返回每个输入的 [`BatchResultItem`](#batchresultitem)。 ```ts const results = await gw.relayBatch([signed0, signed1]); @@ -188,13 +192,13 @@ const results = await gw.relayBatch([signed0, signed1]); ## 保证区块空间 -`guaranteedBlock` 模块通过企业级 RPC 网关中继 GuaranteedTx（类型为 `0x3F` CustomTx），以便它们落在预留的企业专用区块空间中。与免Gas不同，签名者需要支付自己的Gas并必须有资金。每笔交易都带有与企业通道相关联的二维 Nonce，并且只能通过网关进行广播。 +`guaranteedBlock` 模块通过企业版 RPC 网关中继 GuaranteedTx（类型 `0x3F` CustomTx），以便它们落在预留的企业版通道区块空间中。与免燃气费不同，签名者支付自己的燃气费并且必须有资金。每笔交易都带有与企业版通道关联的二维 nonce，并且广播仅通过网关进行。 通过 `guaranteedBlock` 和 `enterpriseRpcEndpoints` 启用它： ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable 提供的网关 URL guaranteedBlock: { account: privateKeyToAccount("0xFUNDED_SIGNER_KEY"), @@ -209,12 +213,12 @@ const gb = enterprise.guaranteedBlock; | **字段** | **类型** | **描述** | | :--- | :--- | :--- | -| `account` | `LocalAccount` | 签署每笔 GuaranteedTx 并支付其 Gas 的有资金账户。 | -| `laneId` | `bigint` | 企业通道ID。必须在 `[0, ENTERPRISE_MASK - 1]` 范围内。无效的ID将立即被拒绝。 | +| `account` | `LocalAccount` | 签署每笔 GuaranteedTx 并支付其燃气费的已拨款账户。 | +| `laneId` | `bigint` | 企业版通道ID。必须在 `[0, ENTERPRISE_MASK - 1]` 范围内。无效ID将提前被拒绝。 | ### `send(account, tx)` -构建、签名并中继一个 GuaranteedTx。因为签名者要支付 Gas，所以需要 1559 费用字段。`chainId`、企业 `nonceKey` 和二维 Nonce（从网关发现）都会为您处理。 +构建、签名和中继一笔 GuaranteedTx。需要 1559 费用字段，因为签名者支付燃气费。`chainId`、企业版 `nonceKey` 和二维 nonce（从网关发现）都为您处理。 ```ts const gasPrice = await publicClient.getGasPrice(); @@ -235,7 +239,7 @@ const { txHash } = await gb.send(signer, { ### `sendBatch(account, txs)` -构建、签名并中继若干 GuaranteedTx。随机数从发现的基本值自动排序。失败会影响其后续结果。 +构建、签名并中继多个 GuaranteedTx。Nonce 从发现的基础自动排序。一次失败会影响其后续交易。 ```ts const results = await gb.sendBatch(signer, [ @@ -252,17 +256,17 @@ const results = await gb.sendBatch(signer, [ ### `relay(signedTx)` / `relayBatch(signedTxs)` -中继一个预签名的 GuaranteedTx，或批量中继。使用 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req) 和 [`nonceKeyForLane`](#noncekeyforlanelaneid) 对企业级 Nonce 密钥在其他地方构建和签名交易，然后只将签名的十六进制数据交给操作员。 +中继预签名的 GuaranteedTx，或批量中继。使用 [`nonceKeyForLane`](#noncekeyforlanelaneid) 作为企业版 nonce 密钥，在其他地方使用 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req) 构建并签名交易，然后只将签名的十六进制交给操作员。 ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signed = await buildGuaranteedTx(toSigner(signer), stableTestnet.id, { +const signed = await buildGuaranteedTx(toSigner(signer), stable.id, { to, gas: 21_000n, gasFeeCap, gasTipCap, - nonce, // 账户当前的 2D-通道 nonce + nonce, // 账户当前的二维通道 nonce nonceKey: nonceKeyForLane(0n), }); const { txHash } = await gb.relay(signed); @@ -274,13 +278,13 @@ const { txHash } = await gb.relay(signed); ## 保证中继交易 -`guaranteedWaiver` 模块结合了上述两种机制：通过保证区块空间路由的免Gas交易。内部和外部交易都是 `0x3F` 定制交易，共享一个企业 `nonceKey`，因此它像 `guaranteedBlock` 一样通过网关广播。免Gas方赞助 Gas，因此用户不需要余额和费用字段，就像 `gasWaiver` 一样。每个方法都返回 `H_inner`。 +`guaranteedWaiver` 模块结合了上述两个功能：通过保证区块空间路由的免燃气费交易。内部和外部交易都是 `0x3F` CustomTx，共享一个企业版 `nonceKey`，因此它像 `guaranteedBlock` 一样通过网关广播。免燃气费发起者承担燃气费，因此用户不需要余额和费用字段，就像 `gasWaiver` 一样。每个方法都返回 `H_inner`。 通过 `guaranteedWaiver` 和 `enterpriseRpcEndpoints` 启用它： ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable 提供的网关 URL guaranteedWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY"), @@ -293,23 +297,23 @@ const gw = enterprise.guaranteedWaiver; ### `GuaranteedWaiverConfig` -扩展 [`ValidationLimits`](#validationlimits) 和 [`SignerSource`](#signersource)。它外部包装豁免密钥的方式与 `GasWaiverConfig` 完全相同（`signer`，然后是 `account`，然后是环境变量），并接受相同的 `maxGasLimit`、`maxDataLength` 和 `allowedTargets` 策略控制。 +扩展 [`ValidationLimits`](#validationlimits) 和 [`SignerSource`](#signersource)。它与 `GasWaiverConfig` 完全一样地获取外部包装器的免燃气费密钥（`signer`，然后是 `account`，然后是环境变量），并接受相同的 `maxGasLimit`、`maxDataLength` 和 `allowedTargets` 策略控制。 | **字段** | **类型** | **描述** | | :--- | :--- | :--- | -| `signer` | `Signer?` | 作为托管签名者（签署外部包装器）的白名单豁免密钥。优先于 `account`。请参阅[签名密钥和托管](#signing-keys-and-custody)。 | -| `account` | `LocalAccount?` | 作为进程内viem账户的豁免密钥。当两者都未设置时，回退到 `STABLE_ENTERPRISE_PRIVATE_KEY`。 | -| `laneId` | `bigint` | 企业通道ID。必须在 `[0, ENTERPRISE_MASK - 1]` 范围内。 | +| `signer` | `Signer?` | 列入白名单的免燃气费密钥（签署外部包装器）作为托管签名者。优先于 `account`。请参阅[签名密钥和托管](#signing-keys-and-custody)。 | +| `account` | `LocalAccount?` | 免燃气费密钥作为进程内viem账户。如果两者都未设置，则回退到 `STABLE_ENTERPRISE_PRIVATE_KEY`。 | +| `laneId` | `bigint` | 企业版通道ID。必须在 `[0, ENTERPRISE_MASK - 1]` 范围内。 | ### `send(user, tx)` / `sendBatch(user, txs)` -从`user`构建并签署内部`0x3F` CustomTx，用免Gas密钥包装，然后中继。由于Gas已免除，无需费用字段。内部2D nonce从网关发现，批次将从该基础自动排序。 +从 `user` 构建并签名内部 `0x3F` CustomTx，用免燃气费密钥包装，然后中继。由于燃气费已免除，因此不需要费用字段。内部二维 nonce 从网关发现，并且批处理从该基础自动排序。 ```ts // 单个 const { txHash } = await gw.send(user, { to: recipient }); -// 批次 +// 批处理 const results = await gw.sendBatch(user, [{ to: a }, { to: b }]); ``` @@ -317,24 +321,24 @@ const results = await gw.sendBatch(user, [{ to: a }, { to: b }]); { txHash: "0x8f3a...2d41" } ``` -`tx` 参数是一个 [`GuaranteedWaiverTxRequest`](#guaranteedwaivertxrequest) 加上一个可选的 `nonce`。`send` 返回 [`RelayResult`](#relayresult)；`sendBatch` 返回 [`BatchResultItem[]`](#batchresultitem)。 +`tx` 参数是 [`GuaranteedWaiverTxRequest`](#guaranteedwaivertxrequest) 加上一个可选的 `nonce`。`send` 返回 [`RelayResult`](#relayresult)；`sendBatch` 返回 [`BatchResultItem[]`](#batchresultitem)。 ### `relay(signedInnerTx)` / `relayBatch(signedInnerTxs)` -对于非托管流程，用户使用 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req) 签署内部 `0x3F` CustomTx（费用为 `0n`，使用 `nonceKeyForLane(laneId)`），并只将签名的十六进制数据交给操作员。操作员用豁免密钥包装并中继。 +对于非托管流程，用户使用 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req) 签名内部 `0x3F` CustomTx（费用为 `0n`，使用 `nonceKeyForLane(laneId)`），并只将签名的十六进制交给操作员。操作员用免燃气费密钥包装并中继。 ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { +const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, { to, gas: 100_000n, - gasFeeCap: 0n, // 已豁免 + gasFeeCap: 0n, // 已免除 gasTipCap: 0n, nonce, nonceKey: nonceKeyForLane(0n), }); -const { txHash } = await gw.relay(signedInner); // 豁免包装 + 广播 → H_inner +const { txHash } = await gw.relay(signedInner); // 免燃气费包装 + 广播 → H_inner ``` ```text @@ -343,27 +347,27 @@ const { txHash } = await gw.relay(signedInner); // 豁免包装 + 广播 → H_i ## 构建辅助函数 -用于非托管 `relay` 路径的低级签名者。每个签名者都以 `Hex` 形式返回一个已签名交易，不进行 nonce 获取或费用估算。第一个参数是一个 [`Signer`](#signing-keys-and-custody)：用 `toSigner(account)` 包装一个 viem 账户，或者传递一个托管签名者（例如 `awsKmsSigner`）。 +用于非托管 `relay` 路径的低级签名者。每个都以 `Hex` 形式返回一个已签名的交易，没有 nonce 获取或费用估算。第一个参数是 [`Signer`](#signing-keys-and-custody)：用 `toSigner(account)` 包装一个 viem 账户，或传递一个托管签名者，例如 `awsKmsSigner`。 ### `buildWaiverInnerTx(signer, chainId, req)` -使用预设的免Gas规则签名豁免版内部交易：`gasPrice: 0`、旧版类型和给定的 `chainId`。`req` 是 [`WaiverInnerTx`](#waiverinnertx) 加上一个必需的 `nonce`。 +使用预设的免燃气费不变量（`gasPrice: 0`、旧版类型和给定的 `chainId`）签署一个免燃气费就绪的 InnerTx。`req` 是一个 [`WaiverInnerTx`](#waiverinnertx) 加上一个必需的 `nonce`。 ```ts -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce }); ``` ### `buildGuaranteedTx(signer, chainId, req)` -构建并签名一个 GuaranteedTx (`0x3F` CustomTx)。`req` 是一个 [`GuaranteedTxRequest`](#guaranteedtxrequest) 加上一个必需的 `nonce` 和 `nonceKey`。 +构建并签署一个 GuaranteedTx (`0x3F` CustomTx)。`req` 是一个 [`GuaranteedTxRequest`](#guaranteedtxrequest) 加上一个必需的 `nonce` 和 `nonceKey`。 ### `buildGuaranteedWaiverTx(...)` -将预签名的内部交易包装到外部 `0x3F` 免Gas自定义交易中。供 `guaranteedWaiver.relay` 内部使用；为高级流程导出。 +将预签名的内部交易包装到外部 `0x3F` 免燃气费 CustomTx 中。由 `guaranteedWaiver.relay` 内部使用；为高级流程导出。 ### `nonceKeyForLane(laneId)` -返回 `laneId` 对应的企业 `nonceKey`，供 `buildGuaranteedTx` 使用。 +返回用于 `buildGuaranteedTx` 的通道 ID 的企业版 `nonceKey`。 ```ts import { nonceKeyForLane } from "@stablechain/enterprise"; @@ -375,16 +379,16 @@ const nonceKey = nonceKeyForLane(0n); ### `SignerSource` -免Gas模块（`gasWaiver`、`guaranteedWaiver`）接受的签名密钥字段。按顺序解析：`signer`，然后是 `account`，然后是客户端的顶级 [`signer`](#stableenterpriseconfig)，然后是 `STABLE_ENTERPRISE_PRIVATE_KEY` 环境变量。请参阅[签名密钥和 custod](#signing-keys-and-custody)。 +免燃气费模块 (`gasWaiver`, `guaranteedWaiver`) 接受的签名密钥字段。按顺序解析：`signer`，然后是 `account`，然后是客户端的顶级 [`signer`](#stableenterpriseconfig)，然后是 `STABLE_ENTERPRISE_PRIVATE_KEY` 环境变量。请参阅[签名密钥和托管](#signing-keys-and-custody)。 | **字段** | **类型** | **描述** | | :--- | :--- | :--- | -| `signer` | `Signer?` | 托管级签名者（AWS KMS、HSM 或 `privateKeySigner`）。优先于 `account`。 | -| `account` | `LocalAccount?` | 进程内viem账户，通过 `toSigner` 适配为 `Signer`。 | +| `signer` | `Signer?` | 托管级别的签名者（AWS KMS、HSM 或 `privateKeySigner`）。优先于 `account`。 | +| `account` | `LocalAccount?` | 一个进程内 viem 账户，通过 `toSigner` 适配为 `Signer`。 | ### `Signer` -一个可插拔的签名器，SDK 通过它对 32 字节的摘要进行签名，因此密钥永远不会离开托管后端。可以使用 `awsKmsSigner`、`toSigner`、`privateKeySigner` 或 `envSigner` 来构造一个签名器。 +一个可插拔的签名者，SDK 通过它签署 32 字节的摘要，因此密钥永远不会离开托管后端。可以使用 `awsKmsSigner`、`toSigner`、`privateKeySigner` 或 `envSigner` 构造一个。 ```ts interface Signer { @@ -397,30 +401,30 @@ interface Signer { | :--- | :--- | :--- | | `awsKmsSigner({ keyId, client? })` | `@stablechain/enterprise/aws-kms` | 由 AWS KMS `ECC_SECG_P256K1` 密钥支持的签名者。返回 `Promise`。 | | `toSigner(account)` | `@stablechain/enterprise` | 将 viem `LocalAccount` 适配为 `Signer`。 | -| `privateKeySigner(key)` | `@stablechain/enterprise` | 包装进程中持有的原始私钥的签名者。 | +| `privateKeySigner(key)` | `@stablechain/enterprise` | 包装进程中原始私钥的签名者。 | | `envSigner(varName?)` | `@stablechain/enterprise` | 从 `STABLE_ENTERPRISE_PRIVATE_KEY`（或 `varName`）读取密钥的签名者。 | ### `WaiverInnerTx` -每次调用都会变化的 InnerTx 字段。 +每个调用不同的 InnerTx 字段。 | **字段** | **类型** | **默认值** | **描述** | | :--- | :--- | :--- | :--- | -| `to` | `Address` | | 目标地址：用于ERC-20转账的代币合约，用于原生代币的接收方。 | -| `gas` | `bigint?` | `DEFAULT_INNER_GAS` (`150_000n`) | Gas限制。由于 `gasPrice` 为 0，高限制也是免费的。 | +| `to` | `Address` | | 目标地址：ERC-20 转账的代币合约，原生代币的接收者。 | +| `gas` | `bigint?` | `DEFAULT_INNER_GAS` (`150_000n`) | 燃气限额。因为 `gasPrice` 为 0，所以慷慨的限额是免费的。 | | `data` | `Hex?` | `"0x"` | 调用数据。 | -| `value` | `bigint?` | `0n` | 发送的原生价值。 | +| `value` | `bigint?` | `0n` | 要发送的原生代币值。 | ### `GuaranteedTxRequest` | **字段** | **类型** | **默认值** | **描述** | | :--- | :--- | :--- | :--- | -| `to` | `Address?` | | 目标地址。 | -| `gas` | `bigint` | | Gas限制。必填。 | -| `gasFeeCap` | `bigint` | | `maxFeePerGas`。必填。 | -| `gasTipCap` | `bigint` | | `maxPriorityFeePerGas`。必填。 | +| `to` | `Address?` | | 目标地址。 | +| `gas` | `bigint` | | 燃气限额。必填。 | +| `gasFeeCap` | `bigint` | | `maxFeePerGas`。必填。 | +| `gasTipCap` | `bigint` | | `maxPriorityFeePerGas`。必填。 | | `data` | `Hex?` | `"0x"` | 调用数据。 | -| `value` | `bigint?` | `0n` | 发送的原生价值。 | +| `value` | `bigint?` | `0n` | 要发送的原生代币值。 | ### `GuaranteedWaiverTxRequest` @@ -428,56 +432,56 @@ interface Signer { | **字段** | **类型** | **默认值** | **描述** | | :--- | :--- | :--- | :--- | -| `to` | `Address` | | 目标地址。 | -| `gas` | `bigint?` | 共享内部Gas默认值 | Gas限制。 | +| `to` | `Address` | | 目标地址。 | +| `gas` | `bigint?` | 共享的内部燃气默认值 | 燃气限额。 | | `data` | `Hex?` | `"0x"` | 调用数据。 | -| `value` | `bigint?` | `0n` | 发送的原生价值。免Gas允许价值转移。 | +| `value` | `bigint?` | `0n` | 要发送的原生值。免燃气费允许进行值转移。 | ### `ValidationLimits` -`gasWaiver` 和 `guaranteedWaiver` 对每个 InnerTx 应用的按合作伙伴策略。 +应用于 `gasWaiver` 和 `guaranteedWaiver` 的每个 InnerTx 的合作伙伴策略。 | **字段** | **类型** | **默认值** | **描述** | | :--- | :--- | :--- | :--- | -| `maxGasLimit` | `bigint?` | `10_000_000n` | InnerTx 的最大 Gas 限制。超过此值将导致 `GAS_LIMIT_EXCEEDED` 错误。 | -| `maxDataLength` | `number?` | `131_072` (128 KB) | 调用数据的最大大小（字节）。超过此值将导致 `DATA_TOO_LARGE` 错误。 | -| `allowedTargets` | `AllowedTarget[]?` | | 免Gas方可能赞助的合约和方法的白名单。设置后，不在列表中的目标将导致 `TARGET_NOT_ALLOWED` 错误。 | +| `maxGasLimit` | `bigint?` | `10_000_000n` | InnerTx 的最大燃气限额。超出此限额将导致 `GAS_LIMIT_EXCEEDED` 错误。 | +| `maxDataLength` | `number?` | `131_072` (128 KB) | 调用数据的最大字节大小。超出此限额将导致 `DATA_TOO_LARGE` 错误。 | +| `allowedTargets` | `AllowedTarget[]?` | | 免燃气费可能赞助的合约和方法的允许列表。如果设置，则不在列表中的目标将导致 `TARGET_NOT_ALLOWED` 错误。 | ### `AllowedTarget` | **字段** | **类型** | **描述** | | :--- | :--- | :--- | -| `address` | `Address \| "*"` | InnerTx 可以调用的合约，或 `"*"` 表示匹配任何合约。 | +| `address` | `Address \| "*"` | InnerTx 可能调用的合约，或 `"*"` 以匹配任何合约。 | | `selectors` | `Hex[]?` | 允许的 4 字节方法选择器（例如，ERC-20 `transfer` 的 `"0xa9059cbb"`）。省略或留空以允许 `address` 上的任何方法。 | ### `RelayResult` ```ts interface RelayResult { - txHash: Hash; // 免Gas是 H_inner，独立保证区块是 GuaranteedTx hash + txHash: Hash; // 对于免燃气费是 H_inner，对于独立的保证区块是 GuaranteedTx 哈希 } ``` ### `BatchResultItem` -批次中每个输入一个条目，按输入顺序排列。批次会报告每个项目的结g果，而不是抛出异常。 +批处理中每个输入的条目，按输入顺序。批处理不会抛出错误，而是报告每个项目的结果。 | **字段** | **类型** | **描述** | | :--- | :--- | :--- | -| `index` | `number` | 零基位置，与输入数组匹配。 | +| `index` | `number` | 与输入数组匹配的从零开始的位置。 | | `success` | `boolean` | 此项目是否已中继。 | | `txHash` | `Hash?` | 成功时存在：内部交易哈希。 | | `error` | `{ code: ErrorCode; message: string }?` | 失败时存在。 | ## 错误 -单个交易方法 (`send`, `relay`) 在拒绝时抛出异常。批量方法在 [`BatchResultItem.error`](#batchresultitem) 中报告每个项目的失败。所有错误类都扩展自 `StableEnterpriseError`。 +单交易方法 (`send`, `relay`) 在拒绝时抛出错误。批处理方法则在 [`BatchResultItem.error`](#batchresultitem) 中报告每项失败。所有错误类都继承自 `StableEnterpriseError`。 | **类** | **抛出条件** | **有用字段** | | :--- | :--- | :--- | -| `StableEnterpriseError` | 所有SDK错误的基础类。 | `message` | -| `StableEnterpriseRelayError` | 交易在RPC或中继层被拒绝。 | `code` | -| `WaiverValidationError` | InnerTx在广播前未能通过策略检查（gas、数据大小或目标白名单）。 | `code` | +| `StableEnterpriseError` | 所有 SDK 错误的基类。 | `message` | +| `StableEnterpriseRelayError` | 交易在 RPC 或中继层被拒绝。 | `code` | +| `WaiverValidationError` | InnerTx 在广播前未通过策略检查（燃气费、数据大小或目标允许列表）。 | `code` | ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -486,7 +490,7 @@ try { await gw.send(user, { to: token, data }); } catch (err) { if (err instanceof StableEnterpriseRelayError && err.code === "TARGET_NOT_ALLOWED") { - // InnerTx 目标不在配置的白名单中 + // InnerTx 目标不在配置的允许列表中 } throw err; } @@ -498,33 +502,33 @@ StableEnterpriseRelayError: relay failed [TARGET_NOT_ALLOWED]: target 0x... not ### `ErrorCode` -抛出错误或 `BatchResultItem.error` 上的 `code` 之一是： +抛出的错误或 `BatchResultItem.error` 上的 `code` 是以下之一： | **代码** | **含义** | | :--- | :--- | -| `UNKNOWN_ERROR` | 没有特定代码时的备用代码。 | -| `BROADCAST_FAILED` | 在RPC层广播被拒绝，或网关中继失败。 | -| `INVALID_TRANSACTION` | InnerTx解码或解析失败。 | +| `UNKNOWN_ERROR` | 没有特定代码时的回退。 | +| `BROADCAST_FAILED` | 广播在 RPC 层被拒绝，或者网关中继失败。 | +| `INVALID_TRANSACTION` | InnerTx 解码或解析失败。 | | `INVALID_SIGNATURE` | 签名验证失败。 | -| `UNSUPPORTED_TX_TYPE` | InnerTx类型不是legacy、eip2930或eip1559。 | +| `UNSUPPORTED_TX_TYPE` | InnerTx 类型不是 legacy、eip2930 或 eip1559。 | | `WRONG_CHAIN_ID` | InnerTx `chainId` 缺失或与目标链不匹配。 | -| `NON_ZERO_GAS_PRICE` | InnerTx带有非零gas price（免Gas时必须为零）。 | -| `GAS_LIMIT_EXCEEDED` | InnerTx 的 Gas 限制超过 `maxGasLimit`。 | +| `NON_ZERO_GAS_PRICE` | InnerTx 带有非零燃气价格（对于免燃气费必须为零）。 | +| `GAS_LIMIT_EXCEEDED` | InnerTx 燃气限制超过 `maxGasLimit`。 | | `DATA_TOO_LARGE` | InnerTx 调用数据超过 `maxDataLength`。 | | `TARGET_NOT_ALLOWED` | InnerTx 目标不在 `allowedTargets` 中。 | -| `GATEWAY_UNAUTHORIZED` | 企业级RPC网关拒绝了API密钥（缺失、无效或过期）。 | -| `QUOTA_EXCEEDED` | 企业级RPC网关Gas配额已用尽。 | +| `GATEWAY_UNAUTHORIZED` | 企业版 RPC 网关拒绝了 API 密钥（缺失、无效或过期）。 | +| `QUOTA_EXCEEDED` | 企业版 RPC 网关燃气配额已用尽。 | ## 常量 -| **常数** | **类型** | **描述** | +| **常量** | **类型** | **描述** | | :--- | :--- | :--- | -| `DEFAULT_INNER_GAS` | `bigint` | 当省略 `gas` 时，默认的 InnerTx Gas 限制 (`150_000n`)。 | -| `ENTERPRISE_FLAG` | `bigint` | 设置在通道 `nonceKey` 上的企业位。 | +| `DEFAULT_INNER_GAS` | `bigint` | 当 `gas` 被省略时，InnerTx 的默认燃气限额 (`150_000n`)。 | +| `ENTERPRISE_FLAG` | `bigint` | 在通道的 `nonceKey` 上设置的企业版位。 | | `ENTERPRISE_MASK` | `bigint` | 通道 ID 的上限：`laneId` 必须在 `[0, ENTERPRISE_MASK - 1]` 范围内。 | -## 接下来推荐 +## 下一步建议 -- [**Stable 企业级 SDK**](/cn/explanation/enterprise-sdk)：详细了解这些机制及其使用场景。 -- [**免Gas协议**](/cn/reference/gas-waiver-api)：交易格式、标记路由和政fu控制。 -- [**保证区块空间**](/cn/explanation/guaranteed-blockspace)：Stable 如何为企业工作负载预留区块容量。 +- [**Stable企业版SDK**](/cn/explanation/enterprise-sdk): 了解其功能和使用场景。 +- [**免燃气费协议**](/cn/reference/gas-waiver-api): 交易格式、标记路由和治理控制。 +- [**保证区块空间**](/cn/explanation/guaranteed-blockspace): Stable 如何为企业工作负载保留区块容量。 diff --git a/docs/pages/ko/explanation/enterprise-sdk.mdx b/docs/pages/ko/explanation/enterprise-sdk.mdx index 495808d..0f9a1b7 100644 --- a/docs/pages/ko/explanation/enterprise-sdk.mdx +++ b/docs/pages/ko/explanation/enterprise-sdk.mdx @@ -1,21 +1,21 @@ --- source_path: explanation/enterprise-sdk.mdx -source_sha: a632f3be5fbff966d9da230ec302b4ce4e6773f2 -title: "Stable Enterprise SDK" -description: "유형화된 @stablechain/enterprise SDK를 사용하여 백엔드에서 가스 면제 및 블록 공간 보장 트랜잭션을 릴레이합니다." +source_sha: f77d007a45637d9c809cdfbe39f1d41190453c40 +title: "Stable 엔터프라이즈 SDK" +description: "유형화된 @stablechain/enterprise SDK를 사용하여 백엔드에서 가스 면제 및 보장된 블록 공간 트랜잭션을 릴레이합니다." diataxis: "explanation" --- -# Stable Enterprise SDK +# Stable 엔터프라이즈 SDK -`@stablechain/enterprise`는 Stable의 엔터프라이즈 트랜잭션 레일을 위한 서버 측 TypeScript 클라이언트입니다. 사용자의 가스를 후원하는 가스 면제 트랜잭션과 예약된 엔터프라이즈 레인에 포함되는 블록 공간 보장 트랜잭션의 두 가지 종류의 특권 트랜잭션을 서명하고 릴레이합니다. 하나의 클라이언트에서 두 레일 중 하나 또는 둘 다를 활성화할 수 있습니다. +`@stablechain/enterprise`는 Stable의 엔터프라이즈 트랜잭션 레일을 위한 서버 측 TypeScript 클라이언트입니다. 가스 면제 트랜잭션(사용자의 가스를 후원)과 보장된 블록 공간 트랜잭션(예약된 엔터프라이즈 레인에 포함)의 두 가지 유형의 특권 트랜잭션을 서명하고 릴레이합니다. 한 클라이언트에서 두 레일 중 하나 또는 둘 다를 활성화할 수 있습니다. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") }, }); @@ -26,45 +26,48 @@ const { txHash } = await enterprise.gasWaiver.send(user, { to: token, data }); txHash: 0x8f3a...2d41 ``` -호출은 사용자의 트랜잭션 해시인 `H_inner`를 반환하며, 이를 전달한 래퍼 트랜잭션은 반환하지 않습니다. +호출은 래퍼 트랜잭션이 아닌 사용자 트랜잭션의 해시인 `H_inner`를 반환합니다. ## SDK의 기능 -SDK는 모듈당 하나의 기능을 노출합니다. 각 기능은 선택 사항이며 독립적으로 구성되며, 각각 고유한 서명 계정을 가지고 있으므로 별도의 키를 사용할 수 있습니다. +SDK는 모듈당 하나씩 세 가지 기능을 노출합니다. 각 기능은 선택 사항이며 독립적으로 구성되며, 각 기능에는 자체 서명 계정이 있어 별도의 키를 사용할 수 있습니다. -- **가스 면제 릴레이** (`gasWaiver`): 가스 면제 트랜잭션을 구축하고 서명하며 릴레이합니다. 화이트리스트에 등록된 면제 계정이 사용자의 제로 가스 트랜잭션을 래핑하여 사용자가 USDT0를 보유하지 않고도 트랜잭션을 할 수 있도록 합니다. [가스 면제](/ko/explanation/gas-waiver)를 참조하십시오. -- **블록 공간 보장** (`guaranteedBlock`): 엔터프라이즈 RPC 게이트웨이를 통해 트랜잭션을 릴레이하여 예약된 엔터프라이즈 레인 블록 공간에 포함되도록 합니다. 가스 면제와 달리 서명자는 자체 가스를 지불합니다. [블록 공간 보장](/ko/explanation/guaranteed-blockspace)을 참조하십시오. -- **보장된 릴레이 트랜잭션** (`guaranteedWaiver`): 두 가지를 모두 결합합니다. 블록 공간 보장을 통해 라우팅된 가스 면제 트랜잭션이므로 사용자는 잔고가 필요 없으며 트랜잭션은 여전히 엔터프라이즈 레인에 포함됩니다. +- **가스 면제 릴레이** (`gasWaiver`): 가스 면제 트랜잭션을 구축하고 서명하며 릴레이합니다. 화이트리스트에 등록된 면제 계정은 사용자의 제로 가스 트랜잭션을 래핑하여 사용자가 USDT0를 보유하지 않고도 트랜잭션을 수행할 수 있도록 합니다. [가스 면제](/ko/explanation/gas-waiver)를 참조하세요. +- **보장된 블록 공간** (`guaranteedBlock`): 엔터프라이즈 RPC 게이트웨이를 통해 트랜잭션을 릴레이하여 예약된 엔터프라이즈 레인 블록 공간에 포함되도록 합니다. 가스 면제와 달리 서명자는 자체 가스를 지불합니다. [보장된 블록 공간](/ko/explanation/guaranteed-blockspace)을 참조하세요. +- **보장된 릴레이 트랜잭션** (`guaranteedWaiver`): 두 가지를 모두 결합합니다. 엔터프라이즈 블록 공간을 통해 라우팅되는 가스 면제 트랜잭션이므로 사용자는 잔액이 필요 없으며 트랜잭션은 여전히 엔터프라이즈 레인에 포함됩니다. -모든 기능은 동일한 네 가지 메서드를 제공합니다. SDK가 서명하는 관리 경로의 `send` 및 `sendBatch`, 그리고 사용자가 다른 곳에서 서명하고 서명된 헥스만 전달하는 비관리 경로의 `relay` 및 `relayBatch`입니다. +모든 기능은 동일한 네 가지 메서드를 제공합니다. SDK가 서명하는 커스터디 경로의 경우 `send` 및 `sendBatch`를, 사용자가 다른 곳에서 서명하고 서명된 헥스만 전달하는 비커스터디 경로의 경우 `relay` 및 `relayBatch`를 제공합니다. + +SDK는 npm에 [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise)로 게시되어 있으며 현재 버전 1.0.0이며, 피어 종속성으로 `viem >= 2.0.0`이 필요합니다. ## 액세스 -엔터프라이즈 SDK는 현재 Stable 테스트넷에서만 사용할 수 있습니다. +엔터프라이즈 SDK는 Stable 메인넷 및 Stable 테스트넷에서 사용할 수 있습니다. 클라이언트의 `chain`으로 메인넷의 경우 `stable`을, 테스트넷의 경우 `stableTestnet`을 전달합니다. 둘 다 패키지에서 다시 내보내집니다. -두 레일 모두 게이트로 보호됩니다. 가스 면제에는 거버넌스에 등록된 면제 키가 필요하며, 블록 공간 보장에는 엔터프라이즈 RPC 게이트웨이 API 키가 필요합니다. 통합하려면 [Stable에 문의](https://discord.gg/stablexyz)하여 액세스 권한을 얻으십시오. Stable은 필요한 면제 키와 게이트웨이 엔드포인트를 제공합니다. +두 레일 모두 게이트로 보호됩니다. 가스 면제는 거버넌스에 등록된 면제 키를 필요로 하며, 보장된 블록 공간은 엔터프라이즈 RPC 게이트웨이 API 키를 필요로 합니다. 통합하려면 [Stable에 문의](https://discord.gg/stablexyz)하여 액세스 권한을 얻으세요. Stable은 필요한 면제 키와 게이트웨이 엔드포인트를 제공합니다. ## 서버 측 전용 :::warning -엔터프라이즈 SDK는 개인 키로 서명하는 상태 비저장 서버 측 라이브러리입니다. 브라우저에서 실행하지 마십시오. 면제 키와 엔터프라이즈 RPC 게이트웨이 URL을 백엔드에 보관하십시오. +엔터프라이즈 SDK는 개인 키로 서명하는 스테이트리스 서버 측 라이브러리입니다. 브라우저에서 실행하지 마세요. 면제 키와 엔터프라이즈 RPC 게이트웨이 URL을 백엔드에 보관하세요. ::: -면제 키는 화이트리스트에 등록된 거버넌스 등록 계정입니다. 이를 소유한 누구든지 귀하의 정책에 따라 가스를 후원할 수 있습니다. 엔터프라이즈 RPC 게이트웨이 URL에는 API 키가 포함되어 있습니다. 둘 다 비밀로 취급하십시오. 면제 키를 프로세스 외부에서 유지하려면 AWS KMS와 같은 보관 서명자로 백업하십시오. [서명 키 및 보관](/ko/reference/enterprise-sdk#signing-keys-and-custody)을 참조하십시오. +면제 키는 화이트리스트에 등록된 거버넌스 등록 계정입니다. 이를 보유한 누구든지 귀하의 정책에 따라 가스를 후원할 수 있습니다. 엔터프라이즈 RPC 게이트웨이 URL에는 API 키가 포함되어 있습니다. 둘 다 비밀로 취급하세요. 면제 키를 프로세스 외부에서 유지하려면 AWS KMS와 같은 커스터디 서명자로 백업하세요. [서명 키 및 커스터디](/ko/reference/enterprise-sdk#signing-keys-and-custody)를 참조하세요. ## 언제 사용해야 할까요? -백엔드를 운영하고 사용자의 가스를 후원하거나 자체 트래픽에 대한 포함을 보장하려는 경우 엔터프라이즈 SDK를 사용하십시오. 백엔드 또는 브라우저에서 일상적인 송금, 브리지, 스왑 및 볼트 수익을 위해서는 범용 [Stable SDK](/ko/explanation/sdk-overview)를 대신 사용하십시오. +백엔드를 운영하고 사용자 가스를 후원하거나 자체 트래픽에 대한 포함을 보장하려는 경우 엔터프라이즈 SDK를 사용하세요. 백엔드 또는 브라우저에서 일상적인 전송, 브릿지, 스왑 및 볼트 수익의 경우 범용 [Stable SDK](/ko/explanation/sdk-overview)를 대신 사용하세요. -## 여기서 시작하세요 +## 여기서 시작 -- [**가스 면제 릴레이**](/ko/how-to/relay-with-gas-waiver): 사용자가 USDT0를 보유하지 않고도 트랙잭션을 할 수 있도록 가스를 후원합니다. -- [**보장된 트랜잭션 보내기**](/ko/how-to/send-guaranteed-transactions): 예약된 엔터프라이즈 레인 블록 공간에 트랜잭션을 포함시킵니다. -- [**보장된 릴레이 트랜잭션**](/ko/how-to/guaranteed-relayed-transactions): 두 레일을 모두 결합합니다: 엔터프라이즈 레인의 가스 면제 트랜잭션. -- [**엔터프라이즈 SDK 참조**](/ko/reference/enterprise-sdk): 모든 모듈, 메서드, 구성 옵션 및 오류 클래스. +- [**가스 면제로 릴레이**](/ko/how-to/relay-with-gas-waiver): 사용자의 가스를 후원하여 USDT0를 보유하지 않고도 트랜잭션을 수행할 수 있도록 합니다. +- [**보장된 트랜잭션 전송**](/ko/how-to/send-guaranteed-transactions): 예약된 엔터프라이즈 레인 블록 공간에 트랜잭션을 포함합니다. +- [**보장된 릴레이 트랜잭션**](/ko/how-to/guaranteed-relayed-transactions): 두 레일을 모두 결합합니다. 엔터프라이즈 레인의 가스 면제 트랜잭션입니다. +- [**엔터프라이즈 SDK 참조**](/ko/reference/enterprise-sdk): 모든 모듈, 메서드, 구성 옵션 및 오류 클래스입니다. ## 다음 권장 사항 +- [**npm에서 설치**](https://www.npmjs.com/package/@stablechain/enterprise): npmjs.com에서 패키지를 보고 최신 버전을 확인합니다. - [**가스 면제 프로토콜**](/ko/reference/gas-waiver-api): 트랜잭션 형식, 마커 라우팅 및 거버넌스 제어. -- [**Stable SDK**](/ko/explanation/sdk-overview): 송금, 브리징, 스왑 및 수익을 위한 범용 클라이언트. -- [**Stable에 연결**](/ko/reference/connect): 테스트넷의 체인 ID, RPC 엔드포인트 및 익스플로러. +- [**Stable SDK**](/ko/explanation/sdk-overview): 전송, 브릿징, 스왑 및 수익을 위한 범용 클라이언트. +- [**Stable에 연결**](/ko/reference/connect): 메인넷 및 테스트넷의 체인 ID, RPC 엔드포인트 및 탐색기. diff --git a/docs/pages/ko/how-to/guaranteed-relayed-transactions.mdx b/docs/pages/ko/how-to/guaranteed-relayed-transactions.mdx index 70eba20..963a2e9 100644 --- a/docs/pages/ko/how-to/guaranteed-relayed-transactions.mdx +++ b/docs/pages/ko/how-to/guaranteed-relayed-transactions.mdx @@ -1,37 +1,37 @@ --- source_path: how-to/guaranteed-relayed-transactions.mdx -source_sha: 007be0e546cc1251771678ee74523b6a79a2d76d -title: "보장된 중계 트랜잭션" -description: "Enterprise SDK를 사용하여 보장된 블록 공간을 통해 가스 면제 트랜잭션을 중계하여 사용자가 잔액 없이도 Enterprise 레인에 진입할 수 있도록 합니다." +source_sha: 00233758654be019d706aca71cc6537d441cd552 +title: "보장된 릴레이 트랜잭션" +description: "Enterprise SDK를 사용하여 보장된 블록 공간을 통해 가스가 면제된 트랜잭션을 릴레이하므로, 사용자는 잔액이 없어도 Enterprise 레인에 접근할 수 있습니다." diataxis: "how-to" --- -# 보장된 중계 트랜잭션 +# 보장된 릴레이 트랜잭션 -`@stablechain/enterprise`를 사용하여 두 가지 Enterprise 레일을 모두 결합합니다. 보장된 중계 트랜잭션은 [가스 면제 트랜잭션](/ko/how-to/relay-with-gas-waiver)을 [보장된 블록 공간](/ko/how-to/send-guaranteed-transactions)을 통해 라우팅하는 것입니다. 즉, 면제가 가스를 지원하므로 사용자는 잔액이나 수수료 필드가 필요 없으며 트랜잭션은 예약된 Enterprise 레인에 진입합니다. +`@stablechain/enterprise`와 함께 두 가지 Enterprise 레일을 결합합니다. 보장된 릴레이 트랜잭션은 [가스 면제 트랜잭션](/ko/how-to/relay-with-gas-waiver)을 [보장된 블록 공간](/ko/how-to/send-guaranteed-transactions)을 통해 라우팅하는 것입니다. 즉, 면제 기능이 가스를 후원하므로 사용자는 잔액이나 수수료 필드가 필요 없으며, 트랜잭션은 예약된 Enterprise 레인으로 전달됩니다. -`guaranteedWaiver` 모듈은 양측을 모두 처리합니다. 사용자는 내부 `0x3F` CustomTx에 서명하고, 화이트리스트에 등록된 면제 계정은 동일한 Enterprise `nonceKey`를 공유하는 외부 `0x3F` CustomTx로 래핑하고, Enterprise RPC 게이트웨이를 통해 브로드캐스트합니다. 모든 메소드는 사용자의 트랜잭션 해시인 `H_inner`를 반환합니다. +`guaranteedWaiver` 모듈은 양쪽을 모두 처리합니다. 사용자는 내부 `0x3F` CustomTx에 서명하고, 화이트리스트에 등록된 면제 계정은 동일한 Enterprise `nonceKey`를 공유하는 외부 `0x3F` CustomTx로 이를 래핑한 후, Enterprise RPC 게이트웨이를 통해 브로드캐스트합니다. 모든 메서드는 사용자 트랜잭션 해시인 `H_inner`를 반환합니다. ## 전제 조건 -- Node.js 20 이상, 그리고 `@stablechain/enterprise` 및 `viem` 설치. [Enterprise SDK 참조](/ko/reference/enterprise-sdk#install)를 참조하세요. -- 거버넌스에 등록된 면제 키와 Enterprise RPC 게이트웨이 API 키. Enterprise SDK는 현재 테스트넷 전용이며 요청 시 액세스가 가능합니다. 둘 다 얻으려면 [Stable에 문의](https://discord.gg/stablexyz)하세요. +- Node.js 20 이상, 그리고 `@stablechain/enterprise` 및 `viem`이 설치되어 있어야 합니다. [Enterprise SDK 참조](/ko/reference/enterprise-sdk#install)를 참조하세요. +- 거버넌스에 등록된 면제 키와 Enterprise RPC 게이트웨이 API 키가 필요합니다. Enterprise SDK는 Stable Mainnet 및 Stable Testnet에서 실행되며, 접근은 요청 시 가능합니다. 둘 다 얻으려면 [Stable에 문의](https://discord.gg/stablexyz)하세요. :::warning -이것은 서버 측 라이브러리입니다. 면제 키와 Enterprise RPC 게이트웨이 URL을 백엔드에 보관하세요. 게이트웨이 URL에 API 키가 포함되어 있습니다. +이것은 서버 측 라이브러리입니다. 면제 키와 Enterprise RPC 게이트웨이 URL을 백엔드에 보관하세요. 게이트웨이 URL에는 API 키가 포함되어 있습니다. ::: -## 1. 보장된 면제 모듈로 클라이언트 생성 +## 1. 보장된 면제 모듈을 사용하여 클라이언트 생성 -`guaranteedWaiver`와 `enterpriseRpcEndpoints`를 `createStableEnterprise`에 전달합니다. 이 모듈은 화이트리스트에 등록된 면제 키(외부 래퍼에 서명)와 Enterprise 레인을 사용합니다. 또한 `gasWaiver`와 동일한 `allowedTargets`, `maxGasLimit`, `maxDataLength` 정책 제한을 허용합니다. +`guaranteedWaiver` 및 `enterpriseRpcEndpoints`를 `createStableEnterprise`에 전달합니다. 이 모듈은 화이트리스트에 등록된 면제 키(외부 래퍼에 서명)와 Enterprise 레인을 사용합니다. 또한 `gasWaiver`와 동일한 `allowedTargets`, `maxGasLimit`, `maxDataLength` 정책 제한도 허용합니다. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, - enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable에서 제공하는 게이트웨이 URL + chain: stable, + enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable이 제공하는 게이트웨이 URL guaranteedWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`), laneId: 0n, // Enterprise 레인 @@ -46,12 +46,12 @@ StableEnterpriseClient { gasWaiver: undefined, guaranteedBlock: undefined, guara ``` :::tip -면제 키를 보관 백엔드에 유지하려면 `account` 대신 `signer`를 전달하세요. `@stablechain/enterprise/aws-kms`의 `awsKmsSigner`는 AWS KMS로 이를 지원합니다. [서명 키 및 보관](/ko/reference/enterprise-sdk#signing-keys-and-custody)을 참조하세요. +보증 키를 커스터디 백엔드에 보관하려면 `account` 대신 `signer`를 전달하세요. `@stablechain/enterprise/aws-kms`의 `awsKmsSigner`는 AWS KMS로 이를 지원합니다. [서명 키 및 커스터디](/ko/reference/enterprise-sdk#signing-keys-and-custody)를 참조하세요. ::: -## 2. 단일 트랜잭션 중계 +## 2. 단일 트랜잭션 릴레이 -사용자의 계정과 변경되는 필드를 사용하여 `send`를 호출합니다. 가스는 면제되므로 사용자는 잔액이나 수수료 필드가 필요 없습니다. 내부 `0x3F` CustomTx, 해당 Enterprise `nonceKey`, 그리고 (게이트웨이에서 발견된) 2D nonce는 자동으로 처리됩니다. +사용자의 계정과 변경되는 필드를 사용하여 `send`를 호출합니다. 가스가 면제되므로 사용자는 잔액이나 수수료 필드가 필요 없습니다. 내부 `0x3F` CustomTx, 해당 Enterprise `nonceKey`, 그리고 (게이트웨이에서 발견된) 2D 논스는 자동으로 처리됩니다. ```ts const user = privateKeyToAccount(process.env.USER_PRIVATE_KEY as `0x${string}`); @@ -64,11 +64,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -`gas`는 공유된 내부 가스 기본값으로 설정됩니다. 재정의하려면 필요할 때만 전달하세요. 값 전송이 허용되므로 `value`도 전달할 수 있습니다. +`gas`는 공유된 내부 가스 기본값으로 설정됩니다. 이를 재정의하려면 `gas`를 전달합니다. 값 전송이 허용되므로 `value`도 전달할 수 있습니다. -## 3. 배치 중계 +## 3. 배치 릴레이 -단일 사용자로부터 여러 트랜잭션을 중계하려면 `sendBatch`를 호출합니다. 내부 nonce는 발견된 기준에서 자동으로 순차적으로 생성되며, 입력 순서대로 입력당 하나의 결과를 얻습니다. 실패는 후속 항목을 중단시킵니다. +한 사용자로부터 여러 트랜잭션을 릴레이하려면 `sendBatch`를 호출합니다. 내부 논스는 발견된 기본값에서 자동으로 순서가 지정되며, 입력 순서대로 입력당 하나의 결과를 얻습니다. 실패하면 후속 작업이 중단됩니다. ```ts const results = await gw.sendBatch(user, [{ to: a }, { to: b }]); @@ -83,25 +83,25 @@ for (const r of results) { [1] ✔ 0x2b7c...9e04 ``` -## 4. 사전 서명된 트랜잭션 중계 +## 4. 사전 서명된 트랜잭션 릴레이 -비수탁형 흐름의 경우, 사용자는 자신의 환경에서 내부 `0x3F` CustomTx에 서명하고 서명된 헥스만 전달합니다. Enterprise nonce 키에는 `nonceKeyForLane`을 사용하고 수수료는 0으로(가스 면제) 설정하여 `buildGuaranteedTx`로 빌드합니다. 백엔드는 이를 면제 키로 래핑하고 `relay`로 중계합니다. +비수탁 흐름의 경우, 사용자는 자신의 환경에서 내부 `0x3F` CustomTx에 서명하고 서명된 헥스만 전달합니다. `buildGuaranteedTx`를 사용하여 이를 구성하고, Enterprise 논스 키에는 `nonceKeyForLane`을 사용하며 수수료는 0으로 설정합니다(가스는 면제됩니다). 백엔드는 이를 면제 키로 래핑하고 `relay`를 사용하여 릴레이합니다. ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -// 사용자의 측면 - buildGuaranteedTx는 Signer를 통해 서명합니다. toSigner는 viem 계정을 조정합니다. -const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { +// 사용자 측 — buildGuaranteedTx는 Signer를 통해 서명합니다. toSigner는 viem 계정을 조정합니다. +const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, { to: recipient, gas: 100_000n, - gasFeeCap: 0n, // 면제 + gasFeeCap: 0n, // 면제됨 gasTipCap: 0n, - nonce, // 사용자의 현재 2D-레인 nonce + nonce, // 사용자의 현재 2D-레인 논스 nonceKey: nonceKeyForLane(0n), // Enterprise 레인 0 }); // 백엔드에서 -const { txHash } = await gw.relay(signedInner); // waiver는 래핑 + 브로드캐스트 → H_inner +const { txHash } = await gw.relay(signedInner); // 면제 래핑 + 브로드캐스트 → H_inner console.log("H_inner:", txHash); ``` @@ -109,11 +109,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -여러 사전 서명된 트랜잭션의 경우 `relayBatch`를 사용합니다. +여러 개의 사전 서명된 트랜잭션에는 `relayBatch`를 사용하세요. -## 거부 처리 +## 거절 처리 -`send` 및 `relay`는 거부 시 `StableEnterpriseRelayError`를 throw합니다. 이 흐름은 게이트웨이를 통해 라우팅되므로 `GATEWAY_UNAUTHORIZED` 및 `QUOTA_EXCEEDED`와 같은 게이트웨이 코드는 `TARGET_NOT_ALLOWED`와 같은 면제 정책 코드와 함께 적용됩니다. +`send` 및 `relay`는 거절 시 `StableEnterpriseRelayError`를 발생시킵니다. 이 흐름은 게이트웨이를 통해 라우팅되므로 `GATEWAY_UNAUTHORIZED` 및 `QUOTA_EXCEEDED`와 같은 게이트웨이 코드와 `TARGET_NOT_ALLOWED`와 같은 면제 정책 코드가 적용됩니다. ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -132,10 +132,10 @@ try { StableEnterpriseRelayError: relay failed [GATEWAY_UNAUTHORIZED]: invalid api key ``` -모든 거부 이유에 대한 전체 [`ErrorCode`](/ko/reference/enterprise-sdk#errorcode) 표를 참조하세요. +모든 거절 이유에 대한 전체 [`ErrorCode`](/ko/reference/enterprise-sdk#errorcode) 표를 참조하세요. ## 다음 단계 -- [**가스 면제로 중계**](/ko/how-to/relay-with-gas-waiver): 보장된 레인 없이 사용자의 가스를 지원합니다. +- [**가스 면제 릴레이**](/ko/how-to/relay-with-gas-waiver): 보장된 레인 없이 사용자의 가스를 후원합니다. - [**보장된 트랜잭션 전송**](/ko/how-to/send-guaranteed-transactions): 서명자가 가스를 지불하는 경우, 보장된 블록 공간을 단독으로 사용합니다. -- [**Enterprise SDK 참조**](/ko/reference/enterprise-sdk#guaranteed-relay-transactions): 모든 메소드, 구성 옵션 및 오류 클래스에 대한 전체 설명입니다. +- [**Enterprise SDK 참조**](/ko/reference/enterprise-sdk#guaranteed-relay-transactions): 모든 메서드, 구성 옵션 및 오류 클래스에 대한 전체 설명입니다. diff --git a/docs/pages/ko/how-to/relay-with-gas-waiver.mdx b/docs/pages/ko/how-to/relay-with-gas-waiver.mdx index 8ecef5c..6ddcff9 100644 --- a/docs/pages/ko/how-to/relay-with-gas-waiver.mdx +++ b/docs/pages/ko/how-to/relay-with-gas-waiver.mdx @@ -1,21 +1,21 @@ --- source_path: how-to/relay-with-gas-waiver.mdx -source_sha: c1b34aab292d8e9623b59810cd6b668468e834ce +source_sha: a41b82da40c922244690f2e8e05d8f9ad1f34a99 title: "가스 면제 릴레이" -description: "Enterprise SDK로 사용자의 가스를 후원하세요: 제로 가스 트랜잭션을 릴레이하고, 릴레이를 일괄 처리하고, 정책 제한을 적용하고, 사전 서명된 트랜잭션을 릴레이합니다." +description: "Enterprise SDK로 사용자 가스 지원: 제로 가스 트랜잭션 릴레이, 배치 릴레이, 정책 제한 적용, 미리 서명된 트랜잭션 릴레이." diataxis: "how-to" --- # 가스 면제 릴레이 -`@stablechain/enterprise`로 사용자의 가스를 후원하세요. 화이트리스트에 등록된 면제 계정은 사용자의 제로 가스 트랜잭션(InnerTx)을 래핑하여 브로드캐스트하므로, 사용자는 USDT0를 보유하지 않고도 트랜잭션을 수행할 수 있습니다. `gasWaiver` 모듈은 한 번의 호출로 빌드, 서명 및 릴레이를 수행하므로, 각 작업당 하나의 메서드를 호출합니다. +`@stablechain/enterprise`로 사용자 가스를 지원하세요. 화이트리스트에 등록된 면제 계정은 사용자의 제로 가스 트랜잭션(InnerTx)을 래핑하고 브로드캐스트하여 사용자가 USDT0를 보유하지 않고도 트랜잭션을 수행할 수 있도록 합니다. `gasWaiver` 모듈은 빌드, 서명 및 릴레이를 한 번의 호출로 처리하므로 작업당 하나의 메서드를 호출합니다. -모든 메서드는 트랜잭션을 담고 있는 래퍼가 아닌, 사용자 트랜잭션의 해시인 `H_inner`를 반환합니다. +모든 메서드는 트랜잭션을 전달한 래퍼가 아닌, 사용자 트랜잭션의 해시인 `H_inner`를 반환합니다. ## 전제 조건 -- Node.js 20 이상, 그리고 `@stablechain/enterprise`와 `viem`이 설치되어 있어야 합니다. [Enterprise SDK 참조](/ko/reference/enterprise-sdk#install)를 참조하세요. -- 거버넌스에 등록된 면제 키. Enterprise SDK는 현재 테스트넷 전용이며 접근이 제한되어 있습니다: 화이트리스트에 등록된 면제 키를 받으려면 [Stable에 문의](https://discord.gg/stablexyz)하세요. +- Node.js 20 이상, `@stablechain/enterprise` 및 `viem` 설치. [Enterprise SDK 참조](/ko/reference/enterprise-sdk#install)를 참조하세요. +- 거버넌스에 등록된 면제 키. Enterprise SDK는 Stable Mainnet 및 Stable Testnet에서 실행되며 액세스는 제한됩니다. 화이트리스트에 등록된 면제 키를 얻으려면 [Stable에 문의](https://discord.gg/stablexyz)하세요. :::warning 이것은 개인 키로 서명하는 서버 측 라이브러리입니다. 브라우저에서 실행하지 마십시오. 면제 키는 백엔드에 보관하십시오. @@ -23,14 +23,14 @@ diataxis: "how-to" ## 1. 가스 면제 모듈로 클라이언트 생성 -`gasWaiver: { account }`를 `createStableEnterprise`에 전달합니다. 여기서 `account`는 화이트리스트에 등록된 면제 키입니다. 모듈은 클라이언트에 구성해야만 존재합니다. +`createStableEnterprise`에 `gasWaiver: { account }`를 전달합니다. 여기서 `account`는 화이트리스트에 등록된 면제 키입니다. 모듈은 구성할 때만 클라이언트에 존재합니다. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`) }, }); @@ -49,7 +49,7 @@ StableEnterpriseClient { gasWaiver, guaranteedBlock: undefined, guaranteedWaiver ## 2. 단일 트랜잭션 릴레이 -사용자 계정 및 변경되는 필드와 함께 `send`를 호출합니다. `gasPrice: 0`, 레거시 유형, `chainId`, 보류 중인 논스가 자동으로 처리되므로, `to`만 전달하고 선택적으로 `data`, `value`, `gas`를 전달하면 됩니다. +사용자 계정과 변경되는 필드를 사용하여 `send`를 호출합니다. `gasPrice: 0`, 레거시 유형, `chainId` 및 보류 중인 nonce는 자동으로 처리되므로 `to`만 전달하고 선택적으로 `data`, `value`, `gas`를 전달합니다. ```ts const user = privateKeyToAccount(process.env.USER_PRIVATE_KEY as `0x${string}`); @@ -62,11 +62,11 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -사용자는 USDT0가 필요하지 않습니다: 면제 계정이 가스를 후원합니다. `gas`는 토큰 전송 또는 승인을 포함하는 `150_000n` (`DEFAULT_INNER_GAS`)으로 기본 설정됩니다. 더 많은 가스가 필요한 호출의 경우 명시적인 `gas`를 전달하세요. +사용자는 USDT0가 필요하지 않습니다. 면제 계정이 가스를 지원합니다. `gas`는 토큰 전송 또는 승인을 처리하는 `150_000n`(`DEFAULT_INNER_GAS`)으로 기본 설정됩니다. 더 많은 호출에는 명시적인 `gas`를 전달하세요. ## 3. 배치 릴레이 -단일 계정에서 여러 트랜잭션을 릴레이하려면 `sendBatch`를 호출합니다. 논스는 계정의 보류 중인 논스에서 자동으로 순서가 지정되며, 입력 순서대로 각 입력당 하나의 결과를 얻습니다. +`sendBatch`를 호출하여 하나의 계정에서 여러 트랜잭션을 릴레이합니다. Nonce는 계정의 보류 중인 nonce에서 자동으로 순서가 지정되며, 입력 순서대로 입력당 하나의 결과를 얻습니다. ```ts const results = await gw.sendBatch(user, [ @@ -84,39 +84,39 @@ for (const r of results) { [1] ✔ 0x2b7c...9e04 ``` -배치는 실패를 throw하는 대신 `result.error`에 항목별로 보고하므로, 하나의 잘못된 트랜잭션으로 인해 나머지가 모두 실패하지 않습니다. +배치는 예외를 던지는 대신 `result.error`의 항목별로 실패를 보고하므로 하나의 잘못된 트랜잭션이 나머지를 망치지 않습니다. ## 4. 파트너별 정책 제한 적용 -설정에 정책 제한을 추가하여 면제 키가 후원할 수 있는 대상을 제한합니다. 제한을 위반하는 InnerTx는 방송 전에 거부됩니다. +구성 파일에 정책 제한을 추가하여 면제 키가 지원할 수 있는 대상을 제한합니다. 제한을 위반하는 InnerTx는 브로드캐스트되기 전에 거부됩니다. ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`), maxGasLimit: 500_000n, maxDataLength: 4_096, allowedTargets: [ - { address: token, selectors: ["0xa9059cbb"] }, // ERC-20 전송만 허용 + { address: token, selectors: ["0xa9059cbb"] }, // ERC-20 transfer only ], }, }); ``` -`allowedTargets` 외부에 있는 계약으로의 트랜잭션은 `TARGET_NOT_ALLOWED` 오류와 함께 실패하며, `maxGasLimit`을 초과하는 트랜잭션은 `GAS_LIMIT_EXCEEDED` 오류와 함께 실패합니다. `address`로 `"*"`를 사용하여 모든 계약을 허용하고, `selectors`를 생략하여 모든 메서드를 허용할 수 있습니다. +`allowedTargets` 외부의 컨트랙트로의 트랜잭션은 `TARGET_NOT_ALLOWED` 오류로 실패하고, `maxGasLimit`을 초과하는 트랜잭션은 `GAS_LIMIT_EXCEEDED` 오류로 실패합니다. `address`에 `"*"`를 사용하여 모든 컨트랙트를 허용하고, `selectors`를 생략하여 모든 메서드를 허용할 수 있습니다. -## 5. 사전 서명된 트랜잭션 릴레이 +## 5. 미리 서명된 트랜잭션 릴레이 -비수탁형 흐름의 경우, 사용자는 자신의 환경에서 InnerTx를 서명하고 서명된 헥스만 전달하므로, 사용자의 키를 볼 필요가 없습니다. `buildWaiverInnerTx`로 빌드한 다음, `relay`로 릴레이합니다. +비관리 흐름의 경우, 사용자는 자신의 환경에서 InnerTx에 서명하고 서명된 hex만 제공하므로 사용자의 키를 볼 필요가 없습니다. `buildWaiverInnerTx`로 빌드한 다음 `relay`로 릴레이합니다. ```ts import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise"; -// 사용자 측에서 — buildWaiverInnerTx는 Signer를 통해 서명하며; toSigner는 viem 계정을 적용합니다. -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to: token, data, gas: 150_000n, nonce }); +// on the user's side — buildWaiverInnerTx signs through a Signer; toSigner adapts a viem account +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to: token, data, gas: 150_000n, nonce }); -// 백엔드에서 +// on your backend const { txHash } = await gw.relay(signed); console.log("H_inner:", txHash); ``` @@ -125,7 +125,7 @@ console.log("H_inner:", txHash); H_inner: 0x8f3a...2d41 ``` -여러 개의 사전 서명된 트랜잭션의 경우, `relayBatch`를 사용하세요. 이는 `sendBatch`와 같이 입력당 하나의 결과를 반환합니다. +여러 개의 미리 서명된 트랜잭션의 경우, `sendBatch`와 같이 입력당 하나의 결과를 반환하는 `relayBatch`를 사용하세요. ## 거부 처리 @@ -138,7 +138,7 @@ try { await gw.send(user, { to: token, data }); } catch (err) { if (err instanceof StableEnterpriseRelayError && err.code === "TARGET_NOT_ALLOWED") { - // InnerTx 대상이 구성된 허용 목록 외부에 있습니다. + // the InnerTx target is outside the configured allowlist } throw err; } @@ -148,10 +148,10 @@ try { StableEnterpriseRelayError: relay failed [TARGET_NOT_ALLOWED]: target 0x... not allowed ``` -모든 거부 이유에 대한 전체 [`ErrorCode`](/ko/reference/enterprise-sdk#errorcode) 테이블을 참조하세요. +모든 거부 사유에 대한 전체 [`ErrorCode`](/ko/reference/enterprise-sdk#errorcode) 표를 참조하세요. ## 다음 단계 -- [**보장된 트랜잭션 전송**](/ko/how-to/send-guaranteed-transactions): 예약된 엔터프라이즈 레인 블록 공간에 트랜잭션을 전송하고, 이를 가스 면제와 결합합니다. -- [**Enterprise SDK 참조**](/ko/reference/enterprise-sdk#relay-with-gas-waiver): 모든 메서드, 구성 옵션 및 오류 클래스의 전체 목록입니다. +- [**보장된 트랜잭션 전송**](/ko/how-to/send-guaranteed-transactions): 예약된 엔터프라이즈 레인 블록스페이스에 트랜잭션을 전송하고 가스 면제와 결합합니다. +- [**Enterprise SDK 참조**](/ko/reference/enterprise-sdk#relay-with-gas-waiver): 모든 메서드, 구성 옵션 및 오류 클래스에 대한 자세한 설명입니다. - [**가스 면제**](/ko/explanation/gas-waiver): 프로토콜 수준에서 제로 가스 트랜잭션이 작동하는 방식. diff --git a/docs/pages/ko/how-to/send-guaranteed-transactions.mdx b/docs/pages/ko/how-to/send-guaranteed-transactions.mdx index 4ae6f08..85f441c 100644 --- a/docs/pages/ko/how-to/send-guaranteed-transactions.mdx +++ b/docs/pages/ko/how-to/send-guaranteed-transactions.mdx @@ -1,41 +1,41 @@ --- source_path: how-to/send-guaranteed-transactions.mdx -source_sha: 6da305c74e7ddb43f31a4ed11e7f4d5313f0cabe +source_sha: 5debec9526aaf679f040bd9a03213935283d5a36 title: "보장된 트랜잭션 전송" -description: "Enterprise SDK를 사용하여 예약된 Enterprise 레인 블록스페이스에 트랜잭션을 전송하고, 보장된 블록스페이스와 가스 면제를 결합하여 가스 없이 트랜잭션을 릴레이합니다." +description: "Enterprise SDK를 사용하여 예약된 엔터프라이즈 레인 블록스페이스에 트랜잭션을 전송하고, 보장된 블록스페이스와 가스 면제를 결합하여 가스 없이 릴레이합니다." diataxis: "how-to" --- # 보장된 트랜잭션 전송 -`@stablechain/enterprise`를 사용하여 예약된 Enterprise 레인 블록스페이스를 통해 트랜잭션을 라우팅하세요. `guaranteedBlock` 모듈은 GuaranteedTx (0x3F 유형 CustomTx)를 Enterprise RPC 게이트웨이를 통해 릴레이하여 기업 워크로드용으로 예약된 용량에 들어가게 합니다. 가스 면제와 달리 서명자는 자체 가스를 지불해야 하므로 자금이 필요합니다. +`@stablechain/enterprise`를 사용하여 예약된 엔터프라이즈 레인 블록스페이스를 통해 트랜잭션을 라우팅합니다. `guaranteedBlock` 모듈은 GuaranteedTx(유형 `0x3F` CustomTx)를 Enterprise RPC 게이트웨이를 통해 릴레이하여 엔터프라이즈 워크로드용으로 예약된 용량에 도착하도록 합니다. 가스 면제와 달리 서명자는 자체 가스를 지불하므로 자금이 있어야 합니다. -이를 가스 면제와 결합하여 [보장된 릴레이 트랜잭션](/ko/how-to/guaranteed-relayed-transactions)을 얻을 수 있습니다. 이는 Enterprise 레인에 들어가는 가스 면제 트랜잭션입니다. +이를 가스 면제와 결합하여 [보장된 릴레이 트랜잭션](/ko/how-to/guaranteed-relayed-transactions)을 얻을 수 있습니다. 즉, 가스 면제 트랜잭션이 여전히 엔터프라이즈 레인에 도착합니다. ## 전제 조건 -- Node.js 20 이상, 그리고 `@stablechain/enterprise` 및 `viem`이 설치되어 있어야 합니다. [Enterprise SDK 참조](/ko/reference/enterprise-sdk#install)를 확인하세요. -- Enterprise RPC 게이트웨이 API 키. Enterprise SDK는 현재 테스트넷 전용이며 접근이 제한되어 있습니다. 게이트웨이 엔드포인트를 얻으려면 [Stable에 문의하세요](https://discord.gg/stablexyz). -- GuaranteedTx는 자체 가스를 지불하므로 자금이 충분한 서명자가 필요합니다. +- Node.js 20 이상, `@stablechain/enterprise` 및 `viem`이 설치되어 있어야 합니다. [Enterprise SDK 참조](/ko/reference/enterprise-sdk#install)를 참조하십시오. +- Enterprise RPC 게이트웨이 API 키. Enterprise SDK는 Stable Mainnet 및 Stable Testnet에서 실행되며 액세스가 제한됩니다. 게이트웨이 엔드포인트를 얻으려면 [Stable에 문의](https://discord.gg/stablexyz)하십시오. +- GuaranteedTx는 자체 가스를 지불하므로 자금이 있는 서명자가 필요합니다. :::warning -이것은 서버 측 라이브러리입니다. Enterprise RPC 게이트웨이 URL을 백엔드에 유지하세요. API 키가 포함되어 있습니다. +이것은 서버 측 라이브러리입니다. Enterprise RPC 게이트웨이 URL을 백엔드에 보관하십시오. API 키가 포함되어 있습니다. ::: -## 1. guaranteed blockspace 모듈로 클라이언트 생성 +## 1. 보장된 블록스페이스 모듈로 클라이언트 생성 -`guaranteedBlock` 및 `enterpriseRpcEndpoints`를 `createStableEnterprise`에 전달합니다. 게이트웨이는 `0x3F` GuaranteedTx를 허용하는 유일한 엔드포인트이며, API 키를 보유합니다. 유효하지 않은 `laneId`는 즉시 거부됩니다. +`guaranteedBlock` 및 `enterpriseRpcEndpoints`를 `createStableEnterprise`에 전달합니다. 게이트웨이는 `0x3F` GuaranteedTx를 허용하는 유일한 엔드포인트이며, API 키를 보유합니다. 잘못된 `laneId`는 즉시 거부됩니다. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, - enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable이 제공하는 게이트웨이 URL + chain: stable, + enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable에서 제공하는 게이트웨이 URL guaranteedBlock: { - account: privateKeyToAccount(process.env.SIGNER_PRIVATE_KEY as `0x${string}`), // 자금이 충분해야 함 - laneId: 0n, // Enterprise 레인 + account: privateKeyToAccount(process.env.SIGNER_PRIVATE_KEY as `0x${string}`), // 자금이 있어야 함 + laneId: 0n, // 엔터프라이즈 레인 }, }); @@ -48,12 +48,12 @@ StableEnterpriseClient { gasWaiver: undefined, guaranteedBlock, guaranteedWaiver ## 2. 단일 트랜잭션 전송 -서명자와 다양한 필드를 사용하여 `send`를 호출합니다. 서명자가 가스를 지불하므로 1559 수수료 필드가 필요합니다. `chainId`, Enterprise `nonceKey`, 그리고 2D 논스(게이트웨이에서 발견됨)는 자동으로 처리됩니다. +서명자와 다양한 필드를 사용하여 `send`를 호출합니다. 서명자가 가스를 지불하므로 1559 수수료 필드가 필요합니다. `chainId`, Enterprise `nonceKey`, 그리고 2D 논스(게이트웨이에서 발견)는 자동으로 처리됩니다. ```ts import { createPublicClient, http } from "viem"; -const publicClient = createPublicClient({ chain: stableTestnet, transport: http() }); +const publicClient = createPublicClient({ chain: stable, transport: http() }); const gasPrice = await publicClient.getGasPrice(); const { txHash } = await gb.send(signer, { @@ -69,13 +69,13 @@ console.log("Guaranteed tx:", txHash); Guaranteed tx: 0xabcd...7890 ``` -`gasFeeCap`은 가스당 최대 총 수수료(EIP-1559 `maxFeePerGas`)이며, `gasTipCap`은 가스당 최대 우선순위 수수료(`maxPriorityFeePerGas`)입니다. 위와 같이 `gasTipCap`을 현재 가스 가격으로 설정하고 `gasFeeCap`을 그 두 배로 설정하는 것이 안전한 기본값입니다. +`gasFeeCap`은 가스당 최대 총 수수료(EIP-1559 `maxFeePerGas`)이고 `gasTipCap`은 가스당 최대 우선 순위 수수료(`maxPriorityFeePerGas`)입니다. 위와 같이 `gasTipCap`을 현재 가스 가격으로 설정하고 `gasFeeCap`을 두 배로 설정하는 것이 안전한 기본값입니다. -서명자가 가스를 지불하므로 릴레이하기 전에 잔액이 있는지 확인하십시오. 잔액이 없는 계정에서 GuaranteedTx를 보내면 실패합니다. +서명자가 가스를 지불하므로 릴레이하기 전에 잔액이 있는지 확인하십시오. 잔액이 0인 계정에서 보증된 트랜잭션은 실패합니다. -## 3. 일괄 전송 +## 3. 배치 전송 -여러 트랜잭션을 보내려면 `sendBatch`를 호출합니다. 논스는 발견된 기본값에서 자동으로 순서가 지정되며, 입력 순서대로 입력당 하나의 결과가 나옵니다. 하나의 실패는 후속 트랜잭션에 영향을 미칩니다. +`sendBatch`를 호출하여 여러 트랜잭션을 보냅니다. 논스는 발견된 기반에서 자동 순서 지정되며, 입력 순서대로 입력당 하나의 결과를 얻습니다. 실패는 후속 항목을 좌초시킵니다. ```ts const results = await gb.sendBatch(signer, [ @@ -95,18 +95,18 @@ for (const r of results) { ## 4. 사전 서명된 트랜잭션 전송 -비수탁형 흐름의 경우 `buildGuaranteedTx`를 사용하여 다른 곳에서 GuaranteedTx를 빌드하고 서명한 다음, 운영자에게 서명된 hex만 전달합니다. Enterprise 논스 키는 `nonceKeyForLane`에서 가져옵니다. +비수탁 흐름의 경우, `buildGuaranteedTx`를 사용하여 다른 곳에서 GuaranteedTx를 빌드하고 서명한 다음, 서명된 헥스만 운영자에게 전달합니다. Enterprise 논스 키는 `nonceKeyForLane`에서 가져옵니다. ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signed = await buildGuaranteedTx(toSigner(signer), stableTestnet.id, { +const signed = await buildGuaranteedTx(toSigner(signer), stable.id, { to: recipient, gas: 21_000n, gasFeeCap, gasTipCap, nonce, // 계정의 현재 2D-레인 논스 - nonceKey: nonceKeyForLane(0n), // Enterprise 레인 0 + nonceKey: nonceKeyForLane(0n), // 엔터프라이즈 레인 0 }); const { txHash } = await gb.relay(signed); @@ -117,15 +117,15 @@ console.log("Guaranteed tx:", txHash); Guaranteed tx: 0xabcd...7890 ``` -사전 서명된 여러 트랜잭션의 경우 `relayBatch`를 사용합니다. +여러 사전 서명된 트랜잭션의 경우 `relayBatch`를 사용합니다. ## 가스 면제와 결합 -사용자의 가스를 면제하고 여전히 Enterprise 레인에 들어가려면 `guaranteedWaiver` 모듈로 두 레일을 구성합니다. 사용자는 잔액이나 수수료 필드가 필요 없으며 트랜잭션은 동일한 게이트웨이를 통해 라우팅됩니다. [보장된 릴레이 트랜잭션](/ko/how-to/guaranteed-relayed-transactions)을 참조하세요. +사용자의 가스를 면제하고 엔터프라이즈 레인에 도달하려면 `guaranteedWaiver` 모듈로 두 레일을 모두 구성하십시오. 사용자는 잔액이나 수수료 필드가 필요 없으며, 트랜잭션은 동일한 게이트웨이를 통해 라우팅됩니다. [보장된 릴레이 트랜잭션](/ko/how-to/guaranteed-relayed-transactions)을 참조하십시오. ## 거부 처리 -`send` 및 `relay`는 거부 시 `StableEnterpriseRelayError`를 발생시킵니다. 게이트웨이별 코드에는 `GATEWAY_UNAUTHORIZED`(누락되거나 유효하지 않은 API 키) 및 `QUOTA_EXCEEDED`(게이트웨이 가스 할당량 소진)가 있습니다. +`send` 및 `relay`는 거부 시 `StableEnterpriseRelayError`를 발생시킵니다. 게이트웨이별 코드에는 `GATEWAY_UNAUTHORIZED`(누락되었거나 유효하지 않은 API 키) 및 `QUOTA_EXCEEDED`(게이트웨이 가스 할당량 초과)가 포함됩니다. ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -146,6 +146,6 @@ StableEnterpriseRelayError: relay failed [GATEWAY_UNAUTHORIZED]: invalid api key ## 다음 단계 -- [**보장된 릴레이 트랜잭션**](/ko/how-to/guaranteed-relayed-transactions): 한 번의 호출로 사용자의 가스를 면제하고 Enterprise 레인에 진입합니다. -- [**가스 면제로 릴레이**](/ko/how-to/relay-with-gas-waiver): 사용자의 가스를 후원하여 USDT0 없이 트랜잭션을 처리하게 합니다. +- [**보장된 릴레이 트랜잭션**](/ko/how-to/guaranteed-relayed-transactions): 한 번의 호출로 사용자의 가스를 면제하고 엔터프라이즈 레인에 도달합니다. +- [**가스 면제로 릴레이**](/ko/how-to/relay-with-gas-waiver): 사용자의 가스를 후원하여 USDT0를 보유하지 않고도 트랜잭션을 처리합니다. - [**Enterprise SDK 참조**](/ko/reference/enterprise-sdk#guaranteed-blockspace): 모든 메서드, 구성 옵션 및 오류 클래스에 대한 전체 설명입니다. diff --git a/docs/pages/ko/reference/enterprise-sdk.mdx b/docs/pages/ko/reference/enterprise-sdk.mdx index c0be8c3..bade7aa 100644 --- a/docs/pages/ko/reference/enterprise-sdk.mdx +++ b/docs/pages/ko/reference/enterprise-sdk.mdx @@ -1,21 +1,21 @@ --- source_path: reference/enterprise-sdk.mdx -source_sha: d0bc44dc34b19b1a7f7cadeda2ceaa68d296220a -title: "엔터프라이즈 SDK 레퍼런스" -description: "@stablechain/enterprise에 대한 완벽한 레퍼런스: createStableEnterprise, 가스 면제 및 보장된 블록스페이스 모듈, 빌드 헬퍼, 그리고 오류 클래스." +source_sha: f21ad17590422b54220c7795392ff9eb1917f886 +title: "Enterprise SDK 레퍼런스" +description: "@stablechain/enterprise에 대한 완벽한 레퍼런스: createStableEnterprise, 가스 면제 및 보장된 블록 공간 모듈, 빌드 헬퍼, 그리고 오류 클래스." diataxis: "reference" --- -# 엔터프라이즈 SDK 레퍼런스 +# Enterprise SDK 레퍼런스 -`@stablechain/enterprise`의 완전한 표면입니다. 여기에는 [`createStableEnterprise`](#createstableenterpriseconfig)로부터의 클라이언트, 세 가지 기능([가스 면제 릴레이](#relay-with-gas-waiver), [보장된 블록스페이스](#guaranteed-blockspace), [보장된 릴레이 트랜잭션](#guaranteed-relay-transactions)), 하위 수준 빌드 헬퍼, 그리고 공유 결과 및 오류 유형이 포함됩니다. 이러한 레일이 무엇인지는 [Stable 엔터프라이즈 SDK](/ko/explanation/enterprise-sdk), [가스 면제](/ko/explanation/gas-waiver), 그리고 [보장된 블록스페이스](/ko/explanation/guaranteed-blockspace)를 참조하십시오. +`@stablechain/enterprise`의 전체 표면입니다. 여기에는 [`createStableEnterprise`](#createstableenterpriseconfig) 클라이언트, 세 가지 기능([가스 면제 릴레이](#relay-with-gas-waiver), [보장된 블록 공간](#guaranteed-blockspace), [보장된 릴레이 트랜잭션](#guaranteed-relay-transactions)), 저수준 빌드 헬퍼, 공유 결과 및 오류 유형이 포함됩니다. 이러한 레일이 무엇인지는 [Stable Enterprise SDK](/ko/explanation/enterprise-sdk), [가스 면제](/ko/explanation/gas-waiver), [보장된 블록 공간](/ko/explanation/guaranteed-blockspace)을 참조하십시오. :::note -엔터프라이즈 SDK는 현재 Stable 테스트넷에서만 사용할 수 있으며, 액세스는 요청 시에 제공됩니다. 통합하려면 [Stable에 문의](https://discord.gg/stablexyz)하여 거버넌스에 등록된 면제 키와 엔터프라이즈 RPC 게이트웨이 API 키를 받으세요. +Enterprise SDK는 Stable Mainnet 및 Stable Testnet에서 사용할 수 있으며, 요청 시 액세스할 수 있습니다. 통합하려면 [Stable에 문의](https://discord.gg/stablexyz)하여 거버넌스에 등록된 면제 키와 Enterprise RPC 게이트웨이 API 키를 받으십시오. ::: :::warning -이것은 개인 키로 서명하는 서버 측 라이브러리입니다. 브라우저에서 절대 실행하지 마세요. 면제 키와 엔터프라이즈 RPC 게이트웨이 URL은 백엔드에 보관하십시오. +이것은 개인 키로 서명하는 서버 측 라이브러리입니다. 브라우저에서 실행하지 마십시오. 면제 키와 Enterprise RPC 게이트웨이 URL을 백엔드에 보관하십시오. ::: ## 설치 @@ -28,18 +28,22 @@ npm install @stablechain/enterprise viem added 2 packages, audited 3 packages in 2s ``` -`viem >= 2.0.0`은 피어 종속성입니다. 이 패키지는 `viem/chains`에서 `stable` 및 `stableTestnet`을 다시 내보내므로 별도로 가져올 필요가 없습니다. +`viem >= 2.0.0`은 피어 의존성입니다. 패키지는 [`@stablechain/enterprise`](https://www.npmjs.com/package/@stablechain/enterprise)로 게시되며 `viem/chains`에서 `stable` 및 `stableTestnet`을 다시 내보내므로 별도로 가져올 필요가 없습니다. + +:::note +현재 릴리스는 버전 1.0.0입니다. `npm ls @stablechain/enterprise`를 실행하여 현재 버전을 확인하십시오. +::: ## `createStableEnterprise(config)` -`StableEnterpriseClient`를 생성합니다. 각 모듈은 구성할 때만 존재하므로 사용하기 전에 널 체크를 하세요. +`StableEnterpriseClient`를 구성합니다. 각 모듈은 구성할 때만 존재하므로 사용하기 전에 null 검사를 수행하십시오. ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { privateKeyToAccount } from "viem/accounts"; const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") }, }); ``` @@ -52,39 +56,39 @@ StableEnterpriseClient { gasWaiver, guaranteedBlock: undefined, guaranteedWaiver | **필드** | **유형** | **기본값** | **설명** | | :--- | :--- | :--- | :--- | -| `chain` | `StableChain` | | 대상 체인. `stable` 또는 `stableTestnet`을 전달합니다(패키지에서 다시 내보냄). 필수. | -| `rpcEndpoints` | `string[]?` | 체인의 내장 RPC | 하나 이상의 Stable RPC 엔드포인트이며, 실패 시 순서대로 시도됩니다. 개인 엔드포인트를 가리키도록만 오버라이드합니다. | -| `enterpriseRpcEndpoints` | `string[]?` | | 하나 이상의 엔터프라이즈 RPC 게이트웨이 엔드포인트이며, 실패 시 순서대로 시도됩니다. `guaranteedBlock` 및 `guaranteedWaiver`에 필요합니다. | -| `batchSizeLimit` | `number?` | `100` | 배치된 RPC 호출당 최대 트랜잭션 수. | -| `signer` | `Signer?` | | 모듈 자체에 키가 없을 때 면제 모듈(`gasWaiver`, `guaranteedWaiver`)의 기본 서명자입니다. 단일 커스터디 백엔드에서 둘 다 구동하려면 한 번 설정합니다. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. | -| `gasWaiver` | `GasWaiverConfig?` | | [가스 면제 릴레이](#relay-with-gas-waiver)를 활성화합니다. | -| `guaranteedBlock` | `GuaranteedBlockConfig?` | | [보장된 블록스페이스](#guaranteed-blockspace)를 활성화합니다. | -| `guaranteedWaiver` | `GuaranteedWaiverConfig?` | | [보장된 릴레이 트랜잭션](#guaranteed-relay-transactions)을 활성화합니다. | +| `chain` | `StableChain` | | 대상 체인. `stable` 또는 `stableTestnet` (패키지에서 다시 내보내짐)을 전달합니다. 필수입니다. | +| `rpcEndpoints` | `string[]?` | 체인의 내장 RPC | 하나 이상의 Stable RPC 엔드포인트이며, 실패 시 순서대로 시도됩니다. 개인 엔드포인트를 가리키는 경우에만 재정의하십시오. | +| `enterpriseRpcEndpoints` | `string[]?` | | 하나 이상의 Enterprise RPC 게이트웨이 엔드포인트이며, 실패 시 순서대로 시도됩니다. `guaranteedBlock` 및 `guaranteedWaiver`에 필수입니다. | +| `batchSizeLimit` | `number?` | `100` | 일괄 RPC 호출당 최대 트랜잭션 수. | +| `signer` | `Signer?` | | 모듈에 자체 키가 없는 경우 면제 모듈(`gasWaiver`, `guaranteedWaiver`)의 기본 서명자입니다. 단일 커스터디 백엔드에서 둘 다 구동하려면 한 번 설정하십시오. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. | +| `gasWaiver` | `GasWaiverConfig?` | | [가스 면제 릴레이](#relay-with-gas-waiver)를 활성화합니다. | +| `guaranteedBlock` | `GuaranteedBlockConfig?` | | [보장된 블록 공간](#guaranteed-blockspace)을 활성화합니다. | +| `guaranteedWaiver` | `GuaranteedWaiverConfig?` | | [보장된 릴레이 트랜잭션](#guaranteed-relay-transactions)을 활성화합니다. | ### 서명 키 및 커스터디 -면제 키를 보유하는 모듈(`gasWaiver` 및 `guaranteedWaiver`)은 순서대로 이를 해결합니다: 모듈 자체의 `signer`, 그 다음 해당 `account`(인 프로세스 viem 키), 그 다음 클라이언트 구성의 최상위 [`signer`](#stableenterpriseconfig), 그 다음 `STABLE_ENTERPRISE_PRIVATE_KEY` 환경 변수. 단일 커스터디 백엔드에서 두 면제 모듈을 모두 구동하려면 최상위 `signer`를 한 번 설정합니다. `guaranteedBlock`은 자체 자금 조달된 `account`로 서명합니다. +면제 키를 보유하는 모듈(`gasWaiver` 및 `guaranteedWaiver`)은 순서대로 키를 확인합니다. 모듈 자체의 `signer`, 그 다음 `account`(인 프로세스 viem 키), 그 다음 클라이언트 구성의 최상위 [`signer`](#stableenterpriseconfig), 그 다음 `STABLE_ENTERPRISE_PRIVATE_KEY` 환경 변수입니다. 단일 커스터디 백엔드에서 두 면제 모듈을 구동하려면 최상위 `signer`를 한 번 설정하십시오. `guaranteedBlock`은 자체 자금이 있는 `account`로 서명합니다. -`Signer`는 32바이트 다이제스트에 서명하므로, 키는 커스터디 백엔드를 떠나지 않습니다. AWS KMS의 경우 `awsKmsSigner`를 사용하고, viem 계정을 적용하기 위해 `toSigner(account)`를 사용하거나, 인 프로세스 키의 경우 `privateKeySigner(key)` / `envSigner()`를 사용합니다. 모듈의 `send` / `sendBatch`에 전달되는 호출당 발신자도 viem 계정 또는 `Signer`일 수 있으므로, KMS/HSM 키는 `relay`로 떨어뜨리지 않고 내부 트랜잭션에 서명할 수 있습니다. +`Signer`는 32바이트 다이제스트에 서명하므로 키는 커스터디 백엔드를 벗어나지 않습니다. AWS KMS의 경우 `awsKmsSigner`를 사용하고, viem 계정을 적용하려면 `toSigner(account)`를 사용하고, 인 프로세스 키의 경우 `privateKeySigner(key)` / `envSigner()`를 사용하십시오. 모듈의 `send` / `sendBatch`에 전달되는 호출별 발신자는 viem 계정이거나 `Signer`일 수 있으므로 KMS/HSM 키는 `relay`로 떨어뜨리지 않고 내부 트랜잭션에 서명할 수 있습니다. ```bash npm install @aws-sdk/client-kms ``` ```ts -import { createStableEnterprise, stableTestnet } from "@stablechain/enterprise"; +import { createStableEnterprise, stable } from "@stablechain/enterprise"; import { awsKmsSigner } from "@stablechain/enterprise/aws-kms"; -// KMS 키는 ECC_SECG_P256K1(secp256k1)이어야 합니다. SDK는 그로부터 주소를 파생합니다. +// KMS 키는 ECC_SECG_P256K1(secp256k1)이어야 합니다. SDK는 여기에서 주소를 파생합니다. const signer = await awsKmsSigner({ keyId: process.env.AWS_KMS_KEY_ID }); const enterprise = createStableEnterprise({ - chain: stableTestnet, - gasWaiver: { signer }, // 'account' 대신 커스터디 등급의 면제 키 + chain: stable, + gasWaiver: { signer }, // 'account' 대신 커스터디 등급 면제 키 }); ``` -`awsKmsSigner`는 `@stablechain/enterprise/aws-kms` 하위 경로에서 제공되므로 `@aws-sdk/client-kms`는 코어 설치에서 제외되는 선택적 피어 종속성으로 유지됩니다. +`awsKmsSigner`는 `@stablechain/enterprise/aws-kms` 하위 경로에 포함되어 `@aws-sdk/client-kms`가 코어 설치 외부에 선택적 피어 의존성으로 유지됩니다. ### `StableEnterpriseClient` @@ -98,13 +102,13 @@ interface StableEnterpriseClient { ## 가스 면제 릴레이 -`gasWaiver` 모듈은 가스 면제 트랜잭션을 릴레이합니다. 화이트리스트된 면제 계정은 사용자의 제로 가스 트랜잭션(InnerTx)을 WaiverTx로 래핑하고 이를 브로드캐스트합니다. 사용자는 USDT0가 필요하지 않습니다. 모든 메서드는 래퍼 해시가 아닌 InnerTx 해시인 `H_inner`를 반환합니다. +`gasWaiver` 모듈은 가스 면제 트랜잭션을 릴레이합니다. 화이트리스트에 등록된 면제 계정은 사용자의 제로 가스 트랜잭션(InnerTx)을 WaiverTx로 래핑하고 브로드캐스트합니다. 사용자는 USDT0가 필요하지 않습니다. 모든 메서드는 래퍼 해시가 아닌 InnerTx 해시인 `H_inner`를 반환합니다. -구성에서 `gasWaiver`로 활성화합니다. +구성에서 `gasWaiver`를 사용하여 활성화하십시오. ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, + chain: stable, gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY"), // 선택적 파트너별 정책 제한 @@ -122,15 +126,15 @@ const gw = enterprise.gasWaiver; | **필드** | **유형** | **설명** | | :--- | :--- | :--- | -| `signer` | `Signer?` | 커스터디 서명자(AWS KMS, HSM)로 화이트리스트에 등록된 거버넌스 등록 면제 키. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. `account`보다 우선합니다. | -| `account` | `LocalAccount?` | 인 프로세스 viem 계정으로서의 면제 키. 둘 다 설정되지 않은 경우 `STABLE_ENTERPRISE_PRIVATE_KEY`로 폴백됩니다. | -| `maxGasLimit` | `bigint?` | `ValidationLimits`에서 상속됨. | -| `maxDataLength` | `number?` | `ValidationLimits`에서 상속됨. | -| `allowedTargets` | `AllowedTarget[]?` | `ValidationLimits`에서 상속됨. | +| `signer` | `Signer?` | 커스터디 서명자(AWS KMS, HSM)로서 화이트리스트에 등록된 거버넌스 등록 면제 키입니다. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. `account`보다 우선합니다. | +| `account` | `LocalAccount?` | 인 프로세스 viem 계정으로서 면제 키입니다. 둘 다 설정되지 않은 경우 `STABLE_ENTERPRISE_PRIVATE_KEY`로 대체됩니다. | +| `maxGasLimit` | `bigint?` | `ValidationLimits`에서 상속됩니다. | +| `maxDataLength` | `number?` | `ValidationLimits`에서 상속됩니다. | +| `allowedTargets` | `AllowedTarget[]?` | `ValidationLimits`에서 상속됩니다. | ### `send(account, tx)` -`account`로부터 하나의 InnerTx를 한 번의 호출로 빌드, 서명 및 릴레이합니다. `gasPrice: 0`, 레거시 유형, `chainId`, 그리고 보류 중인 nonce는 자동으로 처리됩니다. 거부 시 `StableEnterpriseRelayError`를 throw 합니다. +`account`에서 하나의 InnerTx를 한 번의 호출로 빌드, 서명 및 릴레이합니다. `gasPrice: 0`, 레거시 유형, `chainId` 및 보류 중인 논스가 자동으로 처리됩니다. 거부 시 `StableEnterpriseRelayError`를 throw합니다. ```ts const { txHash } = await gw.send(user, { to: token, data, gas: 150_000n }); @@ -144,7 +148,7 @@ const { txHash } = await gw.send(user, { to: token, data, gas: 150_000n }); ### `sendBatch(account, txs)` -하나의 `account`에서 여러 InnerTx를 빌드, 서명 및 릴레이합니다. nonce는 계정의 보류 중인 nonce를 기준으로 자동 시퀀싱됩니다. 입력 순서대로 각 입력에 대한 결과를 하나씩 반환합니다. +하나의 `account`에서 여러 InnerTx를 빌드, 서명 및 릴레이합니다. 논스는 계정의 보류 중인 논스에서 자동으로 순서가 지정됩니다. 입력 순서대로 각 입력에 대한 하나의 결과를 반환합니다. ```ts const results = await gw.sendBatch(user, [ @@ -161,12 +165,12 @@ const results = await gw.sendBatch(user, [ ### `relay(signedInnerTxHex)` -미리 서명된 제로 가스 InnerTx를 릴레이합니다. 사용자가 자신의 환경에서 서명하고 서명된 헥스만 전달하는 비관리형 흐름에 사용하므로, 면제 운영자는 사용자의 키를 보지 않습니다. [`buildWaiverInnerTx`](#buildwaiverinnertxsigner-chainid-req)로 빌드합니다. 거부 시 예외를 발생시킵니다. +사전 서명된 제로 가스 InnerTx를 릴레이합니다. 사용자가 자신의 환경에서 서명하고 서명된 헥스만 전달하므로 면제 운영자가 사용자의 키를 볼 수 없는 비보관 흐름에 사용하십시오. [`buildWaiverInnerTx`](#buildwaiverinnertxsigner-chainid-req)로 빌드합니다. 거부 시 throw합니다. ```ts import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise"; -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce }); const { txHash } = await gw.relay(signed); ``` @@ -176,7 +180,7 @@ const { txHash } = await gw.relay(signed); ### `relayBatch(signedInnerTxHexes)` -미리 서명된 InnerTx의 배치를 릴레이합니다. 입력 순서대로 각 입력에 대한 [`BatchResultItem`](#batchresultitem)을 하나씩 반환합니다. +사전 서명된 InnerTx의 배치를 릴레이합니다. 입력 순서대로 각 입력에 대한 하나의 [`BatchResultItem`](#batchresultitem)을 반환합니다. ```ts const results = await gw.relayBatch([signed0, signed1]); @@ -186,16 +190,16 @@ const results = await gw.relayBatch([signed0, signed1]); [ { index: 0, success: true, txHash: "0x..." }, { index: 1, success: false, error: { code: "TARGET_NOT_ALLOWED", message: "..." } } ] ``` -## 보장된 블록스페이스 +## 보장된 블록 공간 -`guaranteedBlock` 모듈은 엔터프라이즈 RPC 게이트웨이를 통해 GuaranteedTx(유형 `0x3F` CustomTx)를 릴레이하여 예약된 엔터프라이즈 레인 블록스페이스에 도달하도록 합니다. 가스 면제와 달리, 서명자는 자신의 가스를 지불하며 자금이 있어야 합니다. 각 트랜잭션은 엔터프라이즈 레인에 키가 지정된 2D 논스를 포함하며, 브로드캐스팅은 게이트웨이를 통해서만 이루어집니다. +`guaranteedBlock` 모듈은 Enterprise RPC 게이트웨이를 통해 GuaranteedTx(유형 `0x3F` CustomTx)를 릴레이하여 예약된 Enterprise 레인 블록 공간에 배치합니다. 가스 면제와 달리 서명자는 자체 가스를 지불하며 자금이 있어야 합니다. 각 트랜잭션은 Enterprise 레인에 키가 지정된 2D 논스를 전달하며, 브로드캐스팅은 게이트웨이를 통해서만 이루어집니다. -`guaranteedBlock`과 `enterpriseRpcEndpoints`로 활성화합니다. +`guaranteedBlock`과 `enterpriseRpcEndpoints`를 사용하여 활성화하십시오. ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, - enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable에서 제공하는 게이트웨이 URL + chain: stable, + enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable이 제공하는 게이트웨이 URL guaranteedBlock: { account: privateKeyToAccount("0xFUNDED_SIGNER_KEY"), laneId: 0n, @@ -210,11 +214,11 @@ const gb = enterprise.guaranteedBlock; | **필드** | **유형** | **설명** | | :--- | :--- | :--- | | `account` | `LocalAccount` | 각 GuaranteedTx에 서명하고 가스를 지불하는 자금이 있는 계정. | -| `laneId` | `bigint` | 엔터프라이즈 레인 ID. `[0, ENTERPRISE_MASK - 1]` 범위 내에 있어야 합니다. 유효하지 않은 ID는 즉시 거부됩니다. | +| `laneId` | `bigint` | Enterprise 레인 ID입니다. `[0, ENTERPRISE_MASK - 1]` 범위에 있어야 합니다. 잘못된 ID는 미리 거부됩니다. | ### `send(account, tx)` -하나의 GuaranteedTx를 빌드, 서명 및 릴레이합니다. 서명자가 가스를 지불하므로 1559 수수료 필드가 필요합니다. `chainId`, 엔터프라이즈 `nonceKey`, 그리고 게이트웨이에서 검색된 2D nonce는 자동으로 처리됩니다. +하나의 GuaranteedTx를 빌드, 서명 및 릴레이합니다. 서명자가 가스를 지불하므로 1559 수수료 필드는 필수입니다. `chainId`, Enterprise `nonceKey` 및 2D 논스(게이트웨이에서 검색됨)는 자동으로 처리됩니다. ```ts const gasPrice = await publicClient.getGasPrice(); @@ -231,11 +235,11 @@ const { txHash } = await gb.send(signer, { { txHash: "0xabcd...7890" } ``` -`tx` 인수는 [`GuaranteedTxRequest`](#guaranteedtxrequest)에 선택적 `nonce`가 추가된 것입니다. [`RelayResult`](#relayresult)를 반환합니다. +`tx` 인수는 [`GuaranteedTxRequest`](#guaranteedtxrequest)와 선택적 `nonce`입니다. [`RelayResult`](#relayresult)를 반환합니다. ### `sendBatch(account, txs)` -여러 GuaranteedTx를 빌드, 서명 및 릴레이합니다. 논스는 검색된 기본값에서 자동으로 시퀀싱됩니다. 실패는 후속 작업에 영향을 미칩니다. +여러 GuaranteedTx를 빌드, 서명 및 릴레이합니다. 논스는 검색된 기본에서 자동으로 순서가 지정됩니다. 실패는 후속 항목을 좌초시킵니다. ```ts const results = await gb.sendBatch(signer, [ @@ -252,17 +256,17 @@ const results = await gb.sendBatch(signer, [ ### `relay(signedTx)` / `relayBatch(signedTxs)` -미리 서명된 GuaranteedTx 또는 배치로 릴레이합니다. 엔터프라이즈 nonce 키에는 [`nonceKeyForLane`](#noncekeyforlanelaneid)을 사용하여 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req)로 트랜잭션을 다른 곳에서 빌드하고 서명한 다음, 서명된 헥스만 운영자에게 전달합니다. +사전 서명된 GuaranteedTx 또는 그 배치를 릴레이합니다. Enterprise 논스 키에 [`nonceKeyForLane`](#noncekeyforlanelaneid)을 사용하여 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req)로 트랜잭션을 다른 곳에서 빌드하고 서명한 다음 운영자에게 서명된 헥스만 전달합니다. ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signed = await buildGuaranteedTx(toSigner(signer), stableTestnet.id, { +const signed = await buildGuaranteedTx(toSigner(signer), stable.id, { to, gas: 21_000n, gasFeeCap, gasTipCap, - nonce, // 계정의 현재 2D 레인 nonce + nonce, // 계정의 현재 2D 레인 논스 nonceKey: nonceKeyForLane(0n), }); const { txHash } = await gb.relay(signed); @@ -274,14 +278,14 @@ const { txHash } = await gb.relay(signed); ## 보장된 릴레이 트랜잭션 -`guaranteedWaiver` 모듈은 위 두 가지 레일을 결합합니다: 보장된 블록스페이스를 통해 라우팅되는 가스 면제 트랜잭션. 내부 및 외부 트랜잭션 모두 하나의 엔터프라이즈 `nonceKey`를 공유하는 `0x3F` CustomTx이므로, `guaranteedBlock`처럼 게이트웨이를 통해 브로드캐스트됩니다. 면제는 가스를 지원하므로, `gasWaiver`처럼 사용자는 잔액이나 수수료 필드가 필요하지 않습니다. 모든 메서드는 `H_inner`를 반환합니다. +`guaranteedWaiver` 모듈은 위 두 레일을 결합합니다. 가스 면제 트랜잭션이 보장된 블록 공간을 통해 라우팅됩니다. 내부 및 외부 트랜잭션 모두 하나의 Enterprise `nonceKey`를 공유하는 `0x3F` CustomTx이므로 `guaranteedBlock`처럼 게이트웨이를 통해 브로드캐스트됩니다. 면제는 가스를 후원하므로 사용자는 `gasWaiver`처럼 잔액이나 수수료 필드가 필요하지 않습니다. 모든 메서드는 `H_inner`를 반환합니다. -`guaranteedWaiver`와 `enterpriseRpcEndpoints`로 활성화합니다. +`guaranteedWaiver`와 `enterpriseRpcEndpoints`를 사용하여 활성화하십시오. ```ts const enterprise = createStableEnterprise({ - chain: stableTestnet, - enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable에서 제공하는 게이트웨이 URL + chain: stable, + enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable이 제공하는 게이트웨이 URL guaranteedWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY"), laneId: 0n, @@ -293,17 +297,17 @@ const gw = enterprise.guaranteedWaiver; ### `GuaranteedWaiverConfig` -[`ValidationLimits`](#validationlimits) 및 [`SignerSource`](#signersource)를 확장합니다. 이는 `GasWaiverConfig`와 동일하게 외부 래퍼 면제 키를 소싱하며(`signer`, 그 다음 `account`, 그 다음 env 변수), 동일한 `maxGasLimit`, `maxDataLength`, `allowedTargets` 정책 컨트롤을 허용합니다. +[`ValidationLimits`](#validationlimits) 및 [`SignerSource`](#signersource)를 확장합니다. `GasWaiverConfig`와 동일하게 외부 래퍼 면제 키를 소싱(`signer`, 그 다음 `account`, 그 다음 환경 변수)하며 동일한 `maxGasLimit`, `maxDataLength` 및 `allowedTargets` 정책 제어를 허용합니다. | **필드** | **유형** | **설명** | | :--- | :--- | :--- | -| `signer` | `Signer?` | 커스터디 서명자로서의 화이트리스트된 면제 키(외부 래퍼에 서명). `account`보다 우선합니다. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. | -| `account` | `LocalAccount?` | 인 프로세스 viem 계정으로서의 면제 키. 둘 다 설정되지 않은 경우 `STABLE_ENTERPRISE_PRIVATE_KEY`로 폴백됩니다. | -| `laneId` | `bigint` | 엔터프라이즈 레인 ID. `[0, ENTERPRISE_MASK - 1]` 범위 내에 있어야 합니다. | +| `signer` | `Signer?` | 커스터디 서명자로서 화이트리스트에 등록된 면제 키(외부 래퍼에 서명). `account`보다 우선합니다. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. | +| `account` | `LocalAccount?` | 인 프로세스 viem 계정으로서 면제 키입니다. 둘 다 설정되지 않은 경우 `STABLE_ENTERPRISE_PRIVATE_KEY`로 대체됩니다. | +| `laneId` | `bigint` | Enterprise 레인 ID입니다. `[0, ENTERPRISE_MASK - 1]` 범위에 있어야 합니다. | ### `send(user, tx)` / `sendBatch(user, txs)` -`user`로부터 내부 `0x3F` CustomTx를 빌드하고 서명한 다음, 면제 키로 래핑하고 릴레이합니다. 가스가 면제되므로 수수료 필드는 필요하지 않습니다. 내부 2D 논스는 게이트웨이에서 검색되며, 배치는 해당 베이스에서 자동으로 시퀀싱됩니다. +`user`로부터 내부 `0x3F` CustomTx를 빌드하고 서명한 다음, 면제 키로 래핑하여 릴레이합니다. 가스가 면제되므로 수수료 필드가 필요하지 않습니다. 내부 2D 논스는 게이트웨이에서 검색되며, 배치는 해당 기본에서 자동으로 순서가 지정됩니다. ```ts // 단일 @@ -317,16 +321,16 @@ const results = await gw.sendBatch(user, [{ to: a }, { to: b }]); { txHash: "0x8f3a...2d41" } ``` -`tx` 인수는 [`GuaranteedWaiverTxRequest`](#guaranteedwaivertxrequest)에 선택적 `nonce`가 추가된 것입니다. `send`는 [`RelayResult`](#relayresult)를 반환하고, `sendBatch`는 [`BatchResultItem[]`](#batchresultitem)를 반환합니다. +`tx` 인수는 [`GuaranteedWaiverTxRequest`](#guaranteedwaivertxrequest)와 선택적 `nonce`입니다. `send`는 [`RelayResult`](#relayresult)를 반환하고, `sendBatch`는 [`BatchResultItem[]`](#batchresultitem)를 반환합니다. ### `relay(signedInnerTx)` / `relayBatch(signedInnerTxs)` -비관리형 흐름의 경우, 사용자는 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req)를 사용하여 내부 `0x3F` CustomTx에 서명하고(수수료 `0n`, `nonceKeyForLane(laneId)` 사용), 서명된 헥스만 운영자에게 전달합니다. 운영자는 이를 면제 키로 래핑하고 릴레이합니다. +비보관 흐름의 경우, 사용자는 [`buildGuaranteedTx`](#buildguaranteedtxsigner-chainid-req) (수수료 `0n`, `nonceKeyForLane(laneId)` 사용)로 내부 `0x3F` CustomTx에 서명하고 서명된 헥스만 운영자에게 전달합니다. 운영자는 면제 키로 이를 래핑하고 릴레이합니다. ```ts import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise"; -const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { +const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, { to, gas: 100_000n, gasFeeCap: 0n, // 면제됨 @@ -334,7 +338,7 @@ const signedInner = await buildGuaranteedTx(toSigner(user), stableTestnet.id, { nonce, nonceKey: nonceKeyForLane(0n), }); -const { txHash } = await gw.relay(signedInner); // 면제 래핑 + 브로드캐스트 → H_inner +const { txHash } = await gw.relay(signedInner); // 면제가 래핑 + 브로드캐스트 → H_inner ``` ```text @@ -343,27 +347,27 @@ const { txHash } = await gw.relay(signedInner); // 면제 래핑 + 브로드캐 ## 빌드 헬퍼 -비관리형 `relay` 경로를 위한 하위 수준 서명자입니다. 각 서명자는 서명된 트랜잭션을 `Hex`로 반환하며, 논스 가져오기 또는 수수료 추정은 없습니다. 첫 번째 인수는 [`Signer`](#signing-keys-and-custody)입니다: `toSigner(account)`로 viem 계정을 래핑하거나 `awsKmsSigner`와 같은 커스터디 서명자를 전달합니다. +비보관 `relay` 경로를 위한 저수준 서명자입니다. 각각은 논스 가져오기 또는 수수료 추정 없이 서명된 트랜잭션을 `Hex`로 반환합니다. 첫 번째 인수는 [`Signer`](#signing-keys-and-custody)입니다. viem 계정을 `toSigner(account)`로 래핑하거나 `awsKmsSigner`와 같은 커스터디 서명자를 전달합니다. ### `buildWaiverInnerTx(signer, chainId, req)` -면제 준비된 InnerTx에 서명합니다. 면제 불변값이 내장되어 있습니다: `gasPrice: 0`, 레거시 유형, 그리고 주어진 `chainId`. `req`는 필수 `nonce`가 포함된 [`WaiverInnerTx`](#waiverinnertx)입니다. +`gasPrice: 0`, 레거시 유형 및 지정된 `chainId`와 같이 면제 불변값이 포함된 면제 준비 InnerTx에 서명합니다. `req`는 [`WaiverInnerTx`](#waiverinnertx)와 필수 `nonce`입니다. ```ts -const signed = await buildWaiverInnerTx(toSigner(user), stableTestnet.id, { to, data, gas: 150_000n, nonce }); +const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce }); ``` ### `buildGuaranteedTx(signer, chainId, req)` -GuaranteedTx(`0x3F` CustomTx)를 빌드하고 서명합니다. `req`는 필수 `nonce` 및 `nonceKey`가 포함된 [`GuaranteedTxRequest`](#guaranteedtxrequest)입니다. +GuaranteedTx(`0x3F` CustomTx)를 빌드하고 서명합니다. `req`는 [`GuaranteedTxRequest`](#guaranteedtxrequest)와 필수 `nonce` 및 `nonceKey`입니다. ### `buildGuaranteedWaiverTx(...)` -미리 서명된 내부 트랜잭션을 외부 `0x3F` 면제 CustomTx로 래핑합니다. `guaranteedWaiver.relay`에서 내부적으로 사용됩니다. 고급 흐름을 위해 내보내집니다. +사전 서명된 내부를 외부 `0x3F` 면제 CustomTx로 래핑합니다. `guaranteedWaiver.relay`에서 내부적으로 사용됩니다. 고급 흐름을 위해 내보냅니다. ### `nonceKeyForLane(laneId)` -`buildGuaranteedTx`에서 사용하기 위해 레인 ID에 대한 엔터프라이즈 `nonceKey`를 반환합니다. +`buildGuaranteedTx`에서 사용하기 위해 레인 ID에 대한 Enterprise `nonceKey`를 반환합니다. ```ts import { nonceKeyForLane } from "@stablechain/enterprise"; @@ -371,20 +375,20 @@ import { nonceKeyForLane } from "@stablechain/enterprise"; const nonceKey = nonceKeyForLane(0n); ``` -## 타입 +## 유형 ### `SignerSource` -면제 모듈(`gasWaiver`, `guaranteedWaiver`)이 허용하는 서명 키 필드입니다. 순서대로 해결됩니다: `signer`, 그 다음 `account`, 그 다음 클라이언트의 최상위 [`signer`](#stableenterpriseconfig), 그 다음 `STABLE_ENTERPRISE_PRIVATE_KEY` 환경 변수. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. +면제 모듈(`gasWaiver`, `guaranteedWaiver`)이 허용하는 서명 키 필드입니다. `signer`, 그 다음 `account`, 그 다음 클라이언트의 최상위 [`signer`](#stableenterpriseconfig), 그 다음 `STABLE_ENTERPRISE_PRIVATE_KEY` 환경 변수 순으로 확인됩니다. [서명 키 및 커스터디](#signing-keys-and-custody)를 참조하십시오. | **필드** | **유형** | **설명** | | :--- | :--- | :--- | -| `signer` | `Signer?` | 커스터디 등급의 서명자 (AWS KMS, HSM 또는 `privateKeySigner`). `account`보다 우선합니다. | -| `account` | `LocalAccount?` | `toSigner`를 통해 `Signer`로 변환된 인 프로세스 viem 계정. | +| `signer` | `Signer?` | 커스터디 등급 서명자(AWS KMS, HSM 또는 `privateKeySigner`). `account`보다 우선합니다. | +| `account` | `LocalAccount?` | `toSigner`를 통해 `Signer`에 적용된 인 프로세스 viem 계정. | ### `Signer` -SDK가 32바이트 다이제스트에 서명하는 플러그형 서명자이므로, 키는 커스터디 백엔드를 떠나지 않습니다. `awsKmsSigner`, `toSigner`, `privateKeySigner` 또는 `envSigner`로 하나를 구성합니다. +키가 커스터디 백엔드를 벗어나지 않도록 SDK가 32바이트 다이제스트를 통해 서명하는 플러그형 서명자입니다. `awsKmsSigner`, `toSigner`, `privateKeySigner` 또는 `envSigner`로 구성하십시오. ```ts interface Signer { @@ -395,32 +399,32 @@ interface Signer { | **헬퍼** | **가져오기** | **설명** | | :--- | :--- | :--- | -| `awsKmsSigner({ keyId, client? })` | `@stablechain/enterprise/aws-kms` | AWS KMS `ECC_SECG_P256K1` 키로 지원되는 서명자. `Promise`를 반환합니다. | -| `toSigner(account)` | `@stablechain/enterprise` | `LocalAccount` viem 계정을 `Signer`로 적용합니다. | -| `privateKeySigner(key)` | `@stablechain/enterprise` | 프로세스 내에서 유지되는 원시 개인 키를 래핑하는 서명자입니다. | -| `envSigner(varName?)` | `@stablechain/enterprise` | `STABLE_ENTERPRISE_PRIVATE_KEY`(또는 `varName`)에서 키를 읽는 서명자입니다. | +| `awsKmsSigner({ keyId, client? })` | `@stablechain/enterprise/aws-kms` | AWS KMS `ECC_SECG_P256K1` 키로 지원되는 서명자입니다. `Promise`를 반환합니다. | +| `toSigner(account)` | `@stablechain/enterprise` | viem `LocalAccount`를 `Signer`로 적용합니다. | +| `privateKeySigner(key)` | `@stablechain/enterprise` | 프로세스에 보관된 원시 개인 키를 래핑하는 서명자입니다. | +| `envSigner(varName?)` | `@stablechain/enterprise` | `STABLE_ENTERPRISE_PRIVATE_KEY` (또는 `varName`)에서 키를 읽는 서명자입니다. | ### `WaiverInnerTx` -호출마다 달라지는 InnerTx의 필드입니다. +호출당 변경되는 InnerTx의 필드입니다. | **필드** | **유형** | **기본값** | **설명** | | :--- | :--- | :--- | :--- | -| `to` | `Address` | | 대상 주소: ERC-20 전송을 위한 토큰 계약, 네이티브 전송을 위한 수신자. | -| `gas` | `bigint?` | `DEFAULT_INNER_GAS` (`150_000n`) | 가스 한도. `gasPrice`가 0이므로, 넉넉한 한도는 무료입니다. | -| `data` | `Hex?` | `"0x"` | Calldata. | -| `value` | `bigint?` | `0n` | 보낼 네이티브 값. | +| `to` | `Address` | | 대상 주소: ERC-20 전송의 토큰 계약, 네이티브의 수신자. | +| `gas` | `bigint?` | `DEFAULT_INNER_GAS` (`150_000n`) | 가스 한도. `gasPrice`가 0이므로 관대한 한도는 무료입니다. | +| `data` | `Hex?` | `"0x"` | 콜데이터. | +| `value` | `bigint?` | `0n` | 전송할 네이티브 값. | ### `GuaranteedTxRequest` | **필드** | **유형** | **기본값** | **설명** | | :--- | :--- | :--- | :--- | -| `to` | `Address?` | | 대상 주소. | -| `gas` | `bigint` | | 가스 한도. 필수. | -| `gasFeeCap` | `bigint` | | `maxFeePerGas`. 필수. | -| `gasTipCap` | `bigint` | | `maxPriorityFeePerGas`. 필수. | -| `data` | `Hex?` | `"0x"` | Calldata. | -| `value` | `bigint?` | `0n` | 보낼 네이티브 값. | +| `to` | `Address?` | | 대상 주소. | +| `gas` | `bigint` | | 가스 한도. 필수입니다. | +| `gasFeeCap` | `bigint` | | `maxFeePerGas`. 필수입니다. | +| `gasTipCap` | `bigint` | | `maxPriorityFeePerGas`. 필수입니다. | +| `data` | `Hex?` | `"0x"` | 콜데이터. | +| `value` | `bigint?` | `0n` | 전송할 네이티브 값. | ### `GuaranteedWaiverTxRequest` @@ -428,10 +432,10 @@ interface Signer { | **필드** | **유형** | **기본값** | **설명** | | :--- | :--- | :--- | :--- | -| `to` | `Address` | | 대상 주소. | +| `to` | `Address` | | 대상 주소. | | `gas` | `bigint?` | 공유 내부 가스 기본값 | 가스 한도. | -| `data` | `Hex?` | `"0x"` | Calldata. | -| `value` | `bigint?` | `0n` | 보낼 네이티브 값. 면제를 위해 값 전송이 허용됩니다. | +| `data` | `Hex?` | `"0x"` | 콜데이터. | +| `value` | `bigint?` | `0n` | 전송할 네이티브 값. 면제 시 값 전송이 허용됩니다. | ### `ValidationLimits` @@ -439,16 +443,16 @@ interface Signer { | **필드** | **유형** | **기본값** | **설명** | | :--- | :--- | :--- | :--- | -| `maxGasLimit` | `bigint?` | `10_000_000n` | InnerTx의 최대 가스 한도. 이를 초과하면 `GAS_LIMIT_EXCEEDED`로 실패합니다. | -| `maxDataLength` | `number?` | `131_072` (128 KB) | 바이트 단위의 최대 calldata 크기. 이를 초과하면 `DATA_TOO_LARGE`로 실패합니다. | -| `allowedTargets` | `AllowedTarget[]?` | | 면제를 후원할 수 있는 계약 및 메서드의 허용 목록. 설정된 경우, 목록에 없는 대상은 `TARGET_NOT_ALLOWED`로 실패합니다. | +| `maxGasLimit` | `bigint?` | `10_000_000n` | InnerTx의 최대 가스 한도. 초과하면 `GAS_LIMIT_EXCEEDED`로 실패합니다. | +| `maxDataLength` | `number?` | `131_072` (128 KB) | 바이트 단위의 최대 콜데이터 크기. 초과하면 `DATA_TOO_LARGE`로 실패합니다. | +| `allowedTargets` | `AllowedTarget[]?` | | 면제가 후원할 수 있는 계약 및 메서드의 허용 목록. 설정된 경우 목록 외의 대상은 `TARGET_NOT_ALLOWED`로 실패합니다. | ### `AllowedTarget` | **필드** | **유형** | **설명** | | :--- | :--- | :--- | -| `address` | `Address \| "*"` | InnerTx가 호출할 수 있는 계약, 또는 모든 계약과 일치하는 `"*"`입니다. | -| `selectors` | `Hex[]?` | 허용된 4바이트 메서드 선택자(예: ERC-20 `transfer`의 `"0xa9059cbb"`). `address`에서 모든 메서드를 허용하려면 생략하거나 비워 둡니다. | +| `address` | `Address \| "*"` | InnerTx가 호출할 수 있는 계약 또는 모든 계약과 일치하는 `"*"`입니다. | +| `selectors` | `Hex[]?` | 허용된 4바이트 메서드 선택기(예: ERC-20 `transfer`의 `"0xa9059cbb"`). `address`의 모든 메서드를 허용하려면 생략하거나 비워두십시오. | ### `RelayResult` @@ -460,7 +464,7 @@ interface RelayResult { ### `BatchResultItem` -배치에서 입력당 하나씩, 입력 순서대로 항목. 예외를 던지는 대신, 배치는 항목별 결과를 [`BatchResultItem.error`](#batchresultitem)로 표시합니다. +입력 순서대로 배치된 각 입력당 하나의 항목입니다. throw하는 대신 배치는 항목별 결과를 표시합니다. | **필드** | **유형** | **설명** | | :--- | :--- | :--- | @@ -471,13 +475,13 @@ interface RelayResult { ## 오류 -단일 트랜잭션 메서드(`send`, `relay`)는 거부 시 예외를 발생시킵니다. 배치 메서드는 대신 [`BatchResultItem.error`](#batchresultitem)에서 항목별 실패를 보고합니다. 모든 오류 클래스는 `StableEnterpriseError`를 확장합니다. +단일 트랜잭션 메서드(`send`, `relay`)는 거부 시 throw합니다. 배치 메서드는 대신 [`BatchResultItem.error`](#batchresultitem)에서 항목별 실패를 보고합니다. 모든 오류 클래스는 `StableEnterpriseError`를 확장합니다. | **클래스** | **발생 시점** | **유용한 필드** | | :--- | :--- | :--- | | `StableEnterpriseError` | 모든 SDK 오류의 기본 클래스. | `message` | -| `StableEnterpriseRelayError` | RPC 또는 릴레이 레이어에서 트랜잭션이 거부될 때. | `code` | -| `WaiverValidationError` | InnerTx가 브로드캐스트 전에 정책 검사(가스, 데이터 크기 또는 대상 허용 목록)에 실패하는 경우. | `code` | +| `StableEnterpriseRelayError` | 트랜잭션이 RPC 또는 릴레이 계층에서 거부되었습니다. | `code` | +| `WaiverValidationError` | InnerTx가 브로드캐스트 전에 정책 확인(가스, 데이터 크기 또는 대상 허용 목록)에 실패했습니다. | `code` | ```ts import { StableEnterpriseRelayError } from "@stablechain/enterprise"; @@ -486,7 +490,7 @@ try { await gw.send(user, { to: token, data }); } catch (err) { if (err instanceof StableEnterpriseRelayError && err.code === "TARGET_NOT_ALLOWED") { - // InnerTx 대상이 구성된 허용 목록 외부에 있습니다 + // InnerTx 대상이 구성된 허용 목록 밖에 있습니다. } throw err; } @@ -498,33 +502,33 @@ StableEnterpriseRelayError: relay failed [TARGET_NOT_ALLOWED]: target 0x... not ### `ErrorCode` -던진 오류 또는 `BatchResultItem.error`의 `code`는 다음 중 하나입니다. +throw된 오류 또는 `BatchResultItem.error`의 `code`는 다음 중 하나입니다. | **코드** | **의미** | | :--- | :--- | -| `UNKNOWN_ERROR` | 특정 코드를 사용할 수 없을 때의 폴백. | +| `UNKNOWN_ERROR` | 특정 코드를 사용할 수 없을 때의 대체. | | `BROADCAST_FAILED` | RPC 계층에서 브로드캐스트가 거부되거나 게이트웨이가 릴레이에 실패했습니다. | -| `INVALID_TRANSACTION` | InnerTx가 디코딩 또는 파싱에 실패했습니다. | +| `INVALID_TRANSACTION` | InnerTx 디코딩 또는 파싱에 실패했습니다. | | `INVALID_SIGNATURE` | 서명 확인에 실패했습니다. | | `UNSUPPORTED_TX_TYPE` | InnerTx 유형이 레거시, eip2930 또는 eip1559가 아닙니다. | | `WRONG_CHAIN_ID` | InnerTx `chainId`가 없거나 대상 체인과 일치하지 않습니다. | -| `NON_ZERO_GAS_PRICE` | InnerTx는 0이 아닌 가스 가격을 가집니다(면제의 경우 0이어야 함). | +| `NON_ZERO_GAS_PRICE` | InnerTx에 0이 아닌 가스 가격이 있습니다 (면제의 경우 0이어야 함). | | `GAS_LIMIT_EXCEEDED` | InnerTx 가스 한도가 `maxGasLimit`을 초과합니다. | -| `DATA_TOO_LARGE` | InnerTx calldata가 `maxDataLength`를 초과합니다. | +| `DATA_TOO_LARGE` | InnerTx 콜데이터가 `maxDataLength`를 초과합니다. | | `TARGET_NOT_ALLOWED` | InnerTx 대상이 `allowedTargets`에 없습니다. | -| `GATEWAY_UNAUTHORIZED` | 엔터프라이즈 RPC 게이트웨이가 API 키를 거부했습니다(누락, 유효하지 않거나 만료됨). | -| `QUOTA_EXCEEDED` | 엔터프라이즈 RPC 게이트웨이 가스 할당량이 소진되었습니다. | +| `GATEWAY_UNAUTHORIZED` | Enterprise RPC 게이트웨이가 API 키를 거부했습니다 (누락, 유효하지 않거나 만료됨). | +| `QUOTA_EXCEEDED` | Enterprise RPC 게이트웨이 가스 할당량이 소진되었습니다. | ## 상수 | **상수** | **유형** | **설명** | | :--- | :--- | :--- | -| `DEFAULT_INNER_GAS` | `bigint` | `gas`가 생략될 때의 기본 InnerTx 가스 한도(`150_000n`). | -| `ENTERPRISE_FLAG` | `bigint` | 레인의 `nonceKey`에 설정된 엔터프라이즈 비트. | -| `ENTERPRISE_MASK` | `bigint` | 레인 ID의 상한: `laneId`는 `[0, ENTERPRISE_MASK - 1]` 범위 내에 있어야 합니다. | +| `DEFAULT_INNER_GAS` | `bigint` | `gas`가 생략되었을 때의 기본 InnerTx 가스 한도 (`150_000n`). | +| `ENTERPRISE_FLAG` | `bigint` | 레인의 `nonceKey`에 설정된 Enterprise 비트. | +| `ENTERPRISE_MASK` | `bigint` | 레인 ID의 상한: `laneId`는 `[0, ENTERPRISE_MASK - 1]` 범위에 있어야 합니다. | ## 다음 권장 사항 -- [**Stable 엔터프라이즈 SDK**](/ko/explanation/enterprise-sdk): 레일이 무엇이며 언제 사용해야 하는지. +- [**Stable Enterprise SDK**](/ko/explanation/enterprise-sdk): 레일이 무엇이며 언제 사용해야 하는지. - [**가스 면제 프로토콜**](/ko/reference/gas-waiver-api): 트랜잭션 형식, 마커 라우팅 및 거버넌스 제어. -- [**보장된 블록스페이스**](/ko/explanation/guaranteed-blockspace): Stable이 엔터프라이즈 워크로드에 대한 블록 용량을 예약하는 방법. +- [**보장된 블록 공간**](/ko/explanation/guaranteed-blockspace): Stable이 엔터프라이즈 워크로드를 위해 블록 용량을 예약하는 방법.