有保障的中继交易

将 Stable Enterprise 的两种功能与 @stablechain/enterprise 结合使用。有保障的中继交易是免燃料费交易，它通过有保障的区块空间进行路由：免除燃料费赞助燃料，因此用户无需余额和燃料费字段，交易仍能进入预留的企业通道。

guaranteedWaiver 模块处理两方面。用户签署内部 0x3F CustomTx，白名单中的免燃料费账户将其包装在一个外部 0x3F CustomTx 中，共享相同的 Enterprise nonceKey，并通过 Enterprise RPC 网关广播。每个方法都返回 H_inner，即用户的交易哈希。

先决条件

Node.js 20 或更高版本，并安装了 @stablechain/enterprise 和 viem。请参阅 Enterprise SDK 参考。
一个治理注册的免燃料费密钥和一个 Enterprise RPC 网关 API 密钥。Enterprise SDK 在 Stable 主网和 Stable 测试网上运行，访问权限需要申请：联系 Stable 以获取两者。

1. 创建一个包含有保障免燃料费模块的客户端

将 guaranteedWaiver 和 enterpriseRpcEndpoints 传递给 createStableEnterprise。该模块接受白名单中的免燃料费密钥（用于签署外部包装器）和 Enterprise 通道。它还接受与 gasWaiver 相同的 allowedTargets、maxGasLimit 和 maxDataLength 策略限制。

import { createStableEnterprise, stable } from "@stablechain/enterprise";
import { privateKeyToAccount } from "viem/accounts";
 
const enterprise = createStableEnterprise({
  chain: stable,
  enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // the gateway URL Stable provisions
  guaranteedWaiver: {
    account: privateKeyToAccount(process.env.WAIVER_PRIVATE_KEY as `0x${string}`),
    laneId: 0n, // Enterprise lane
  },
});
 
const gw = enterprise.guaranteedWaiver;

StableEnterpriseClient { gasWaiver: undefined, guaranteedBlock: undefined, guaranteedWaiver }

2. 中继单笔交易

使用用户的账户和变化的字段调用 send。燃料费被免除，因此用户不需要余额和燃料费字段。内部的 0x3F CustomTx、其 Enterprise nonceKey 和 2D 随机数（从网关发现）都会为您处理。

const user = privateKeyToAccount(process.env.USER_PRIVATE_KEY as `0x${string}`);
 
const { txHash } = await gw.send(user, { to: recipient });
console.log("H_inner:", txHash);

H_inner: 0x8f3a...2d41

gas 默认为共享的内部燃料默认值；仅在需要覆盖时才传递它。允许价值转移，因此您也可以传递 value。

3. 中继批次交易

调用 sendBatch 中继来自一个用户的多笔交易。内部随机数从发现的基数自动排序，您会按输入顺序获得每个输入的结果。失败会影响其后续交易。

const results = await gw.sendBatch(user, [{ to: a }, { to: b }]);
 
for (const r of results) {
  console.log(r.success ? `[${r.index}] ✔ ${r.txHash}` : `[${r.index}] ✖ ${r.error?.code}`);
}

[0] ✔ 0x8f3a...2d41
[1] ✔ 0x2b7c...9e04

4. 中继预签名交易

对于非托管流程，用户在其自己的环境中签署内部 0x3F CustomTx，并只向您提供签名的十六进制数据。使用 buildGuaranteedTx 构建它，使用 nonceKeyForLane 获取 Enterprise 随机数密钥和零费用（燃料费被免除）。您的后端使用免燃料费密钥包装它，并使用 relay 中继它。

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), stable.id, {
  to: recipient,
  gas: 100_000n,
  gasFeeCap: 0n, // waived
  gasTipCap: 0n,
  nonce, // the user's current 2D-lane nonce
  nonceKey: nonceKeyForLane(0n), // Enterprise lane 0
});
 
// on your backend
const { txHash } = await gw.relay(signedInner); // waiver wraps + broadcasts → H_inner
console.log("H_inner:", txHash);

H_inner: 0x8f3a...2d41

对于多笔预签名交易，请使用 relayBatch。

处理拒绝

send 和 relay 在拒绝时会抛出 StableEnterpriseRelayError。由于此流程通过网关路由，因此 GATEWAY_UNAUTHORIZED 和 QUOTA_EXCEEDED 等网关代码以及 TARGET_NOT_ALLOWED 等免燃料费策略代码都适用。

import { StableEnterpriseRelayError } from "@stablechain/enterprise";
 
try {
  await gw.send(user, { to: recipient });
} catch (err) {
  if (err instanceof StableEnterpriseRelayError && err.code === "GATEWAY_UNAUTHORIZED") {
    // the Enterprise RPC gateway rejected the API key
  }
  throw err;
}

StableEnterpriseRelayError: relay failed [GATEWAY_UNAUTHORIZED]: invalid api key

请参阅完整的 ErrorCode 表，了解所有拒绝原因。

下一步

免燃料费中继：为用户赞助燃料费，而无需有保障的通道。
发送有保障的交易：单独使用有保障的区块空间，由签名者支付燃料费。
Enterprise SDK 参考：所有方法、配置选项和错误类的完整说明。