Enterprise SDK 레퍼런스

@stablechain/enterprise의 전체 표면입니다. 여기에는 createStableEnterprise 클라이언트, 세 가지 기능(가스 면제 릴레이, 보장된 블록 공간, 보장된 릴레이 트랜잭션), 저수준 빌드 헬퍼, 공유 결과 및 오류 유형이 포함됩니다. 이러한 레일이 무엇인지는 Stable Enterprise SDK, 가스 면제, 보장된 블록 공간을 참조하십시오.

설치

npm install @stablechain/enterprise viem

added 2 packages, audited 3 packages in 2s

viem >= 2.0.0은 피어 의존성입니다. 패키지는 @stablechain/enterprise로 게시되며 viem/chains에서 stable 및 stableTestnet을 다시 내보내므로 별도로 가져올 필요가 없습니다.

createStableEnterprise(config)

StableEnterpriseClient를 구성합니다. 각 모듈은 구성할 때만 존재하므로 사용하기 전에 null 검사를 수행하십시오.

import { createStableEnterprise, stable } from "@stablechain/enterprise";
import { privateKeyToAccount } from "viem/accounts";
 
const enterprise = createStableEnterprise({
  chain: stable,
  gasWaiver: { account: privateKeyToAccount("0xYOUR_WAIVER_KEY") },
});

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

StableEnterpriseConfig

서명 키 및 커스터디

면제 키를 보유하는 모듈(gasWaiver 및 guaranteedWaiver)은 순서대로 키를 확인합니다. 모듈 자체의 signer, 그 다음 account(인 프로세스 viem 키), 그 다음 클라이언트 구성의 최상위 signer, 그 다음 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로 떨어뜨리지 않고 내부 트랜잭션에 서명할 수 있습니다.

npm install @aws-sdk/client-kms

import { createStableEnterprise, stable } from "@stablechain/enterprise";
import { awsKmsSigner } from "@stablechain/enterprise/aws-kms";
 
// KMS 키는 ECC_SECG_P256K1(secp256k1)이어야 합니다. SDK는 여기에서 주소를 파생합니다.
const signer = await awsKmsSigner({ keyId: process.env.AWS_KMS_KEY_ID });
 
const enterprise = createStableEnterprise({
  chain: stable,
  gasWaiver: { signer }, // 'account' 대신 커스터디 등급 면제 키
});

awsKmsSigner는 @stablechain/enterprise/aws-kms 하위 경로에 포함되어 @aws-sdk/client-kms가 코어 설치 외부에 선택적 피어 의존성으로 유지됩니다.

StableEnterpriseClient

interface StableEnterpriseClient {
  gasWaiver?: GasWaiverClient;
  guaranteedBlock?: GuaranteedBlockClient;
  guaranteedWaiver?: GuaranteedWaiverClient;
}

가스 면제 릴레이

gasWaiver 모듈은 가스 면제 트랜잭션을 릴레이합니다. 화이트리스트에 등록된 면제 계정은 사용자의 제로 가스 트랜잭션(InnerTx)을 WaiverTx로 래핑하고 브로드캐스트합니다. 사용자는 USDT0가 필요하지 않습니다. 모든 메서드는 래퍼 해시가 아닌 InnerTx 해시인 H_inner를 반환합니다.

구성에서 gasWaiver를 사용하여 활성화하십시오.

const enterprise = createStableEnterprise({
  chain: stable,
  gasWaiver: {
    account: privateKeyToAccount("0xYOUR_WAIVER_KEY"),
    // 선택적 파트너별 정책 제한
    maxGasLimit: 500_000n,
    allowedTargets: [{ address: "0xToken", selectors: ["0xa9059cbb"] }],
  },
});
 
const gw = enterprise.gasWaiver;

GasWaiverConfig

ValidationLimits 및 SignerSource를 확장합니다.

send(account, tx)

account에서 하나의 InnerTx를 한 번의 호출로 빌드, 서명 및 릴레이합니다. gasPrice: 0, 레거시 유형, chainId 및 보류 중인 논스가 자동으로 처리됩니다. 거부 시 StableEnterpriseRelayError를 throw합니다.

const { txHash } = await gw.send(user, { to: token, data, gas: 150_000n });

{ txHash: "0x8f3a...2d41" }

tx 인수는 WaiverInnerTx와 선택적 nonce입니다. RelayResult를 반환합니다.

sendBatch(account, txs)

하나의 account에서 여러 InnerTx를 빌드, 서명 및 릴레이합니다. 논스는 계정의 보류 중인 논스에서 자동으로 순서가 지정됩니다. 입력 순서대로 각 입력에 대한 하나의 결과를 반환합니다.

const results = await gw.sendBatch(user, [
  { to: token, data: dataA, gas: 150_000n },
  { to: token, data: dataB, gas: 150_000n },
]);

[ { index: 0, success: true, txHash: "0x..." }, { index: 1, success: true, txHash: "0x..." } ]

txs는 WaiverInnerTx의 읽기 전용 배열입니다. BatchResultItem[]를 반환합니다.

relay(signedInnerTxHex)

사전 서명된 제로 가스 InnerTx를 릴레이합니다. 사용자가 자신의 환경에서 서명하고 서명된 헥스만 전달하므로 면제 운영자가 사용자의 키를 볼 수 없는 비보관 흐름에 사용하십시오. buildWaiverInnerTx로 빌드합니다. 거부 시 throw합니다.

import { buildWaiverInnerTx, toSigner } from "@stablechain/enterprise";
 
const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce });
const { txHash } = await gw.relay(signed);

{ txHash: "0x8f3a...2d41" }

relayBatch(signedInnerTxHexes)

사전 서명된 InnerTx의 배치를 릴레이합니다. 입력 순서대로 각 입력에 대한 하나의 BatchResultItem을 반환합니다.

const results = await gw.relayBatch([signed0, signed1]);

[ { index: 0, success: true, txHash: "0x..." }, { index: 1, success: false, error: { code: "TARGET_NOT_ALLOWED", message: "..." } } ]

보장된 블록 공간

guaranteedBlock 모듈은 Enterprise RPC 게이트웨이를 통해 GuaranteedTx(유형 0x3F CustomTx)를 릴레이하여 예약된 Enterprise 레인 블록 공간에 배치합니다. 가스 면제와 달리 서명자는 자체 가스를 지불하며 자금이 있어야 합니다. 각 트랜잭션은 Enterprise 레인에 키가 지정된 2D 논스를 전달하며, 브로드캐스팅은 게이트웨이를 통해서만 이루어집니다.

guaranteedBlock과 enterpriseRpcEndpoints를 사용하여 활성화하십시오.

const enterprise = createStableEnterprise({
  chain: stable,
  enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable이 제공하는 게이트웨이 URL
  guaranteedBlock: {
    account: privateKeyToAccount("0xFUNDED_SIGNER_KEY"),
    laneId: 0n,
  },
});
 
const gb = enterprise.guaranteedBlock;

GuaranteedBlockConfig

send(account, tx)

하나의 GuaranteedTx를 빌드, 서명 및 릴레이합니다. 서명자가 가스를 지불하므로 1559 수수료 필드는 필수입니다. chainId, Enterprise nonceKey 및 2D 논스(게이트웨이에서 검색됨)는 자동으로 처리됩니다.

const gasPrice = await publicClient.getGasPrice();
 
const { txHash } = await gb.send(signer, {
  to: recipient,
  gas: 21_000n,
  gasFeeCap: gasPrice * 2n,
  gasTipCap: gasPrice,
});

{ txHash: "0xabcd...7890" }

tx 인수는 GuaranteedTxRequest와 선택적 nonce입니다. RelayResult를 반환합니다.

sendBatch(account, txs)

여러 GuaranteedTx를 빌드, 서명 및 릴레이합니다. 논스는 검색된 기본에서 자동으로 순서가 지정됩니다. 실패는 후속 항목을 좌초시킵니다.

const results = await gb.sendBatch(signer, [
  { to: a, gas: 21_000n, gasFeeCap: gasPrice * 2n, gasTipCap: gasPrice },
  { to: b, gas: 21_000n, gasFeeCap: gasPrice * 2n, gasTipCap: gasPrice },
]);

[ { index: 0, success: true, txHash: "0x..." }, { index: 1, success: true, txHash: "0x..." } ]

BatchResultItem[]를 반환합니다.

relay(signedTx) / relayBatch(signedTxs)

사전 서명된 GuaranteedTx 또는 그 배치를 릴레이합니다. Enterprise 논스 키에 nonceKeyForLane을 사용하여 buildGuaranteedTx로 트랜잭션을 다른 곳에서 빌드하고 서명한 다음 운영자에게 서명된 헥스만 전달합니다.

import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise";
 
const signed = await buildGuaranteedTx(toSigner(signer), stable.id, {
  to,
  gas: 21_000n,
  gasFeeCap,
  gasTipCap,
  nonce, // 계정의 현재 2D 레인 논스
  nonceKey: nonceKeyForLane(0n),
});
const { txHash } = await gb.relay(signed);

{ txHash: "0xabcd...7890" }

보장된 릴레이 트랜잭션

guaranteedWaiver 모듈은 위 두 레일을 결합합니다. 가스 면제 트랜잭션이 보장된 블록 공간을 통해 라우팅됩니다. 내부 및 외부 트랜잭션 모두 하나의 Enterprise nonceKey를 공유하는 0x3F CustomTx이므로 guaranteedBlock처럼 게이트웨이를 통해 브로드캐스트됩니다. 면제는 가스를 후원하므로 사용자는 gasWaiver처럼 잔액이나 수수료 필드가 필요하지 않습니다. 모든 메서드는 H_inner를 반환합니다.

guaranteedWaiver와 enterpriseRpcEndpoints를 사용하여 활성화하십시오.

const enterprise = createStableEnterprise({
  chain: stable,
  enterpriseRpcEndpoints: [process.env.ENTERPRISE_RPC_URL], // Stable이 제공하는 게이트웨이 URL
  guaranteedWaiver: {
    account: privateKeyToAccount("0xYOUR_WAIVER_KEY"),
    laneId: 0n,
  },
});
 
const gw = enterprise.guaranteedWaiver;

GuaranteedWaiverConfig

ValidationLimits 및 SignerSource를 확장합니다. GasWaiverConfig와 동일하게 외부 래퍼 면제 키를 소싱(signer, 그 다음 account, 그 다음 환경 변수)하며 동일한 maxGasLimit, maxDataLength 및 allowedTargets 정책 제어를 허용합니다.

send(user, tx) / sendBatch(user, txs)

user로부터 내부 0x3F CustomTx를 빌드하고 서명한 다음, 면제 키로 래핑하여 릴레이합니다. 가스가 면제되므로 수수료 필드가 필요하지 않습니다. 내부 2D 논스는 게이트웨이에서 검색되며, 배치는 해당 기본에서 자동으로 순서가 지정됩니다.

// 단일
const { txHash } = await gw.send(user, { to: recipient });
 
// 배치
const results = await gw.sendBatch(user, [{ to: a }, { to: b }]);

{ txHash: "0x8f3a...2d41" }

tx 인수는 GuaranteedWaiverTxRequest와 선택적 nonce입니다. send는 RelayResult를 반환하고, sendBatch는 BatchResultItem[]를 반환합니다.

relay(signedInnerTx) / relayBatch(signedInnerTxs)

비보관 흐름의 경우, 사용자는 buildGuaranteedTx (수수료 0n, nonceKeyForLane(laneId) 사용)로 내부 0x3F CustomTx에 서명하고 서명된 헥스만 운영자에게 전달합니다. 운영자는 면제 키로 이를 래핑하고 릴레이합니다.

import { buildGuaranteedTx, nonceKeyForLane, toSigner } from "@stablechain/enterprise";
 
const signedInner = await buildGuaranteedTx(toSigner(user), stable.id, {
  to,
  gas: 100_000n,
  gasFeeCap: 0n, // 면제됨
  gasTipCap: 0n,
  nonce,
  nonceKey: nonceKeyForLane(0n),
});
const { txHash } = await gw.relay(signedInner); // 면제가 래핑 + 브로드캐스트 → H_inner

{ txHash: "0x8f3a...2d41" }

빌드 헬퍼

비보관 relay 경로를 위한 저수준 서명자입니다. 각각은 논스 가져오기 또는 수수료 추정 없이 서명된 트랜잭션을 Hex로 반환합니다. 첫 번째 인수는 Signer입니다. viem 계정을 toSigner(account)로 래핑하거나 awsKmsSigner와 같은 커스터디 서명자를 전달합니다.

buildWaiverInnerTx(signer, chainId, req)

gasPrice: 0, 레거시 유형 및 지정된 chainId와 같이 면제 불변값이 포함된 면제 준비 InnerTx에 서명합니다. req는 WaiverInnerTx와 필수 nonce입니다.

const signed = await buildWaiverInnerTx(toSigner(user), stable.id, { to, data, gas: 150_000n, nonce });

buildGuaranteedTx(signer, chainId, req)

GuaranteedTx(0x3F CustomTx)를 빌드하고 서명합니다. req는 GuaranteedTxRequest와 필수 nonce 및 nonceKey입니다.

buildGuaranteedWaiverTx(...)

사전 서명된 내부를 외부 0x3F 면제 CustomTx로 래핑합니다. guaranteedWaiver.relay에서 내부적으로 사용됩니다. 고급 흐름을 위해 내보냅니다.

nonceKeyForLane(laneId)

buildGuaranteedTx에서 사용하기 위해 레인 ID에 대한 Enterprise nonceKey를 반환합니다.

import { nonceKeyForLane } from "@stablechain/enterprise";
 
const nonceKey = nonceKeyForLane(0n);

유형

SignerSource

면제 모듈(gasWaiver, guaranteedWaiver)이 허용하는 서명 키 필드입니다. signer, 그 다음 account, 그 다음 클라이언트의 최상위 signer, 그 다음 STABLE_ENTERPRISE_PRIVATE_KEY 환경 변수 순으로 확인됩니다. 서명 키 및 커스터디를 참조하십시오.

Signer

키가 커스터디 백엔드를 벗어나지 않도록 SDK가 32바이트 다이제스트를 통해 서명하는 플러그형 서명자입니다. awsKmsSigner, toSigner, privateKeySigner 또는 envSigner로 구성하십시오.

interface Signer {
  readonly address: Address;
  signDigest(hash: Hex): Promise<Hex>;
}

WaiverInnerTx

호출당 변경되는 InnerTx의 필드입니다.

GuaranteedTxRequest

GuaranteedWaiverTxRequest

수수료 필드는 항상 0이므로 여기서는 생략됩니다.

ValidationLimits

gasWaiver 및 guaranteedWaiver에 의해 각 InnerTx에 적용되는 파트너별 정책입니다.

AllowedTarget

RelayResult

interface RelayResult {
  txHash: Hash; // 면제의 경우 H_inner, 독립형 보장 블록의 경우 GuaranteedTx 해시
}

BatchResultItem

입력 순서대로 배치된 각 입력당 하나의 항목입니다. throw하는 대신 배치는 항목별 결과를 표시합니다.

오류

단일 트랜잭션 메서드(send, relay)는 거부 시 throw합니다. 배치 메서드는 대신 BatchResultItem.error에서 항목별 실패를 보고합니다. 모든 오류 클래스는 StableEnterpriseError를 확장합니다.

import { StableEnterpriseRelayError } from "@stablechain/enterprise";
 
try {
  await gw.send(user, { to: token, data });
} catch (err) {
  if (err instanceof StableEnterpriseRelayError && err.code === "TARGET_NOT_ALLOWED") {
    // InnerTx 대상이 구성된 허용 목록 밖에 있습니다.
  }
  throw err;
}

StableEnterpriseRelayError: relay failed [TARGET_NOT_ALLOWED]: target 0x... not allowed

ErrorCode

throw된 오류 또는 BatchResultItem.error의 code는 다음 중 하나입니다.

상수

다음 권장 사항

• Stable Enterprise SDK: 레일이 무엇이며 언제 사용해야 하는지.
• 가스 면제 프로토콜: 트랜잭션 형식, 마커 라우팅 및 거버넌스 제어.
• 보장된 블록 공간: Stable이 엔터프라이즈 워크로드를 위해 블록 용량을 예약하는 방법.