# @epoch-protocol/epoch-intents-sdk 中文文档

规范地址：https://npmcn.com/package/%40epoch-protocol/epoch-intents-sdk/

版本：2\.2\.0
npm 元数据更新时间：2026-10-27T15:26:56.610Z
中文译文更新时间：2026-11-13T19:51:18.083Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40epoch-protocol/epoch-intents-sdk
原文对照：https://npmcn.com/package/%40epoch-protocol/epoch-intents-sdk/?lang=original
项目主页：https://github.com/epochprotocol/smallocator#readme
源码仓库：https://github.com/epochprotocol/smallocator

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：424 kB，90 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：viem ^2\.x
- 首次发布：2026-01-16T13:01:52.202Z
- 最新版本发布：2026-10-27T15:26:56.413Z
- 近 30 天下载量：29607（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 55 个）

## 中文简介

Epoch Intents 协议的脚本 SDK 类型

## 安装

```sh
npm install @epoch-protocol/epoch-intents-sdk
```

也可以使用：`pnpm add @epoch-protocol/epoch-intents-sdk`、`yarn add @epoch-protocol/epoch-intents-sdk`、`bun add @epoch-protocol/epoch-intents-sdk`

## README

# 压缩 SDK

用于与"契约"协议互动的TypeScript SDK,为存款,注册和分配操作提供易用的方法.

## 安装

```bash
npm install @epoch-protocol/epoch-intents-sdk
```

## 快速启动

```typescript
import { CompactSDK } from "@epoch-protocol/epoch-intents-sdk";
import { createWalletClient, createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

// Initialize clients
const walletClient = createWalletClient({
  chain: mainnet,
  transport: http(),
  // ... your wallet configuration
});

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// Initialize SDK
const sdk = new CompactSDK({
  apiBaseUrl: "http://localhost:3000", // Your allocator API URL
  walletClient,
  publicClient,
});

// Deposit and register a compact
const result = await sdk.depositAndRegister({
  tokenType: "erc20",
  tokenAddress: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  amount: "100",
  allocatorAddress: "0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sponsorAddress: "0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  expiresInSeconds: 600, // 10 minutes
});

console.log("Transaction hash:", result.hash);
console.log("Receipt:", result.receipt);
```

## API 参考

### 压缩SDK

与"契约"协议互动的主要SDK类.

#### 构造器

```typescript
new CompactSDK(config: CompactSDKConfig)
```

**参数:**

-   `config.apiBaseUrl` - 分配器的基址 API
-   `config.walletClient` - Viem 钱包客户端,用于签名交易
-   `config.publicClient` - Viem 读取区块链状态的公共客户端

#### 方法

### 存款和注册人

交存证书并登记一份链上契约.

```typescript
async depositAndRegister(params: DepositAndRegisterParams): Promise<DepositResult>
```

**参数:**

-   `params.tokenType` - 随便 `'native'` 或者说 `'erc20'`
-   `params.tokenAddress` - Token合同地址(ERC20所需)
-   `params.amount` - 作为字符串存入的金额
-   `params.allocatorAddress` - 分配者的地址
-   `params.sponsorAddress` - 提案国的地址
-   `params.expiresInSeconds` - 过期时间以秒计(默认:600)
-   `params.witnessData` - 可选证人/任务数据

**回返情况:**

-   `DepositResult` - 交易散列和收款

**示例**

```typescript
const result = await sdk.depositAndRegister({
  tokenType: "erc20",
  tokenAddress: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  amount: "100",
  allocatorAddress: "0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sponsorAddress: "0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  witnessData: {
    tokenIn: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
    tokenInAmount: "100",
    tokenOut: "0xD3e99a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
    minTokenOut: "95",
    destinationChainId: 1,
    protocolHashIdentifier:
      "0x0000000000000000000000000000000000000000000000000000000000000000",
    recipient: "0x0000000000000000000000000000000000000000",
  },
});
```

### 存款登记和创建分配

在一个操作中进行存款、登记和创建分配.

```typescript
async depositRegisterAndCreateAllocation(params: DepositRegisterAndCreateAllocationParams): Promise<AllocationResult>
```

**参数:**

-   所有参数来自 `depositAndRegister`
-   `params.sessionToken` - API 认证的会话令牌
-   `params.sponsorSignature` - 可选担保人签名

**回返情况:**

-   `AllocationResult` - 存款结果和拨款答复

**示例**

```typescript
const result = await sdk.depositRegisterAndCreateAllocation({
  tokenType: "erc20",
  tokenAddress: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  amount: "100",
  allocatorAddress: "0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sponsorAddress: "0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sessionToken: "your-session-token",
  witnessData: {
    tokenIn: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
    tokenInAmount: "100",
    tokenOut: "0xD3e99a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
    minTokenOut: "95",
    destinationChainId: 1,
  },
});

console.log("Deposit hash:", result.depositResult.hash);
console.log("Allocation hash:", result.allocationResponse.hash);
```

### 获得健康检查

从分配器API那里获取健康检查信息.

```typescript
async getHealthCheck(): Promise<HealthCheckResponse>
```

**回返情况:**

-   `HealthCheckResponse` - API 健康状况和配置

## 类型

### 存款和注册人Params

```typescript
interface DepositAndRegisterParams {
  tokenType: "native" | "erc20";
  tokenAddress?: Address; // Required for ERC20
  amount: string;
  allocatorAddress: Address;
  sponsorAddress: Address;
  expiresInSeconds?: number; // Default: 600
  witnessData?: {
    tokenIn: Address;
    tokenInAmount: string;
    tokenOut: Address;
    minTokenOut: string;
    destinationChainId: number;
    protocolHashIdentifier?: Hex;
    recipient?: Address;
  };
}
```

### 交存结果

```typescript
interface DepositResult {
  hash: Hash;
  receipt: {
    status: "success" | "reverted";
    transactionHash: Hash;
    blockNumber: bigint;
    gasUsed: bigint;
  };
}
```

### 分配结果

```typescript
interface AllocationResult {
  depositResult: DepositResult;
  allocationResponse: {
    hash: string;
    signature: string;
    digest: string;
  };
}
```

## 处理错误

SDK为不同的故障情况提供了特定的出错类型:

```typescript
import {
  CompactSDKError,
  TransactionError,
  APIError,
} from "@epoch-protocol/epoch-intents-sdk";

try {
  const result = await sdk.depositAndRegister(params);
} catch (error) {
  if (error instanceof TransactionError) {
    console.error("Transaction failed:", error.message);
    console.error("Transaction hash:", error.txHash);
  } else if (error instanceof APIError) {
    console.error("API error:", error.message);
    console.error("Status:", error.status);
  } else if (error instanceof CompactSDKError) {
    console.error("SDK error:", error.message);
  }
}
```

## 高级使用

### 自定义目击数据

对于复杂的分配方案,您可以提供自定义的目击数据:

```typescript
const result = await sdk.depositRegisterAndCreateAllocation({
  tokenType: "erc20",
  tokenAddress: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  amount: "1000",
  allocatorAddress: "0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sponsorAddress: "0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sessionToken: "session-token",
  witnessData: {
    tokenIn: "0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
    tokenInAmount: "1000",
    tokenOut: "0xD3e99a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
    minTokenOut: "950",
    destinationChainId: 10, // Optimism
    protocolHashIdentifier:
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    recipient: "0x0000000000000000000000000000000000000000",
  },
});
```

### 原始托肯存款

土生土长矿床:

```typescript
const result = await sdk.depositAndRegister({
  tokenType: "native",
  amount: "1.5", // ETH amount
  allocatorAddress: "0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
  sponsorAddress: "0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C",
});
```

## 测试

SDK包括了综合测试文件 `test/` 文件夹 :

-   `test/test.ts` - 基本测试套房
-   `test/test-runner.ts` - 高级测试跑道
-   `test/integration-example.ts` - 简单整合实例
-   `test/test-config.ts` - 测试配置
-   `test/TESTING.md` - 测试文件

以 :

```bash
pnpm test
pnpm test:runner
pnpm example
```

## 所需资源

-   节点.js 18+
-   类型脚本 5.0+
-   维埃姆 2.x

## 许可证

麻省理工学院

## 常见问题

### @epoch-protocol/epoch-intents-sdk 是什么？

Epoch Intents 协议的脚本 SDK 类型

### 如何安装 @epoch-protocol/epoch-intents-sdk？

在项目目录运行 npm install @epoch-protocol/epoch-intents-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @epoch-protocol/epoch-intents-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @epoch-protocol/epoch-intents-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @epoch-protocol/epoch-intents-sdk 可以商用吗？

@epoch-protocol/epoch-intents-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @epoch-protocol/epoch-intents-sdk 的下载量有多少？

根据 npm 官方下载统计，@epoch-protocol/epoch-intents-sdk 在 2026/10/14 – 2026/11/12 这 30 天内被下载 29,607 次，日均约 987 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @epoch-protocol/epoch-intents-sdk 还在维护吗？

最新版本 2\.2\.0 发布于 2026/10/27（17 天前）；至今共发布 55 个版本，其中过去 12 个月发布了 55 个；首次发布于 2026/01/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。