Skip to content

fix: enterprise sdk on mainnet #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bastienrp merged 2 commits into from
Aug 28, 2026
Merged

fix: enterprise sdk on mainnet #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f417b5
fix: enterprise sdk on mainnet
bastienrp Aug 28, 2026
24629bd
i18n: auto-translate cn/ko for changed en content
github-actions[bot] Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 28 additions & 25 deletions docs/pages/cn/explanation/enterprise-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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") },
});

Expand All @@ -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 端点和浏览器。
52 changes: 26 additions & 26 deletions docs/pages/cn/how-to/guaranteed-relayed-transactions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}`),
Expand All @@ -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}`);
Expand All @@ -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 }]);
Expand All @@ -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
Expand All @@ -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";
Expand All @@ -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)：所有方法、配置选项和错误类的完整说明。
Loading
Loading