# @canton-network/core-acs-reader 中文文档

规范地址：https://npmcn.com/package/%40canton-network/core-acs-reader/

版本：1\.25\.0
npm 元数据更新时间：2026-11-05T21:16:53.591Z
中文译文更新时间：2026-11-09T01:18:14.441Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40canton-network/core-acs-reader
原文对照：https://npmcn.com/package/%40canton-network/core-acs-reader/?lang=original
项目主页：https://github.com/canton-network/wallet/tree/main/core/acs-reader#readme
源码仓库：https://github.com/canton-network/wallet

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

- 包体积（解压后）：280 kB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-03-03T17:22:21.601Z
- 最新版本发布：2026-11-05T21:16:53.413Z
- 近 30 天下载量：321096（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

从Canton分类账中获取主动合同集数据的阅读器,为特定过滤器提供检索和处理主动合同信息的功能.

## 安装

```sh
npm install @canton-network/core-acs-reader
```

也可以使用：`pnpm add @canton-network/core-acs-reader`、`yarn add @canton-network/core-acs-reader`、`bun add @canton-network/core-acs-reader`

## README

# @ canton- network/ 核心读取器

## 概览

ACS阅读器总结了从Canton分类账中查询和管理现行合同的复杂性. 它既提供标准访问模式,也提供分层访问模式,具有智能缓存,以尽量减少网络间接费用并改进应用性能.

## 安装

```bash
pnpm add @canton-network/core-acs-reader
```

## 快速启动

```typescript
import { ACSReader } from '@canton-network/core-acs-reader'
import { ledgerProvider } from './your-ledger-setup'

// Initialize the reader
const reader = new ACSReader(ledgerProvider)

// Read active contracts with filtering
const contracts = await reader.read({
    templateIds: ['templateId'],
    parties: ['partyId'],
    offset: 0,
})

// Get JavaScript contract objects (convenience method)
const jsContracts = await reader.readJsContracts({
    templateIds: ['templateId'],
    parties: ['partyId'],
})
```

## 核心概念

### ACS 读取器

这个 `ACSReader` 类是查询活动合同的主要接口。 它维持内部缓存,并提供原始和已处理的合同数据方法.

### 选项

**标准选项** (单位:千美元)`AcsOptions`:

-   `offset`: 编辑器被从查询( 如果省略, 自动解决)
-   `templateIds`: 要过滤的模板标识组
-   `interfaceIds`: 要过滤的接口 ID 阵列
-   `parties`: 需要过滤的政党身份序列
-   `filterByParty`: 启用基于党派的过滤
-   `limit`: 要返回的最大结果数
-   `continueUntilCompletion`: 继续取取直到所有数据被取回

**已放置选项** (单位:千美元)`PaginatedAcsOptions`: 与标准选项相同,加:

-   `pageToken`: 用于获取特定页面
-   `maxPageSize`: 每页合同的最大数目

### 快取配置

配置缓存行为 `ACSCacheCollectionOptions`数字 :

```typescript
const reader = new ACSReader(ledgerProvider, {
    maxEventsBeforePrune: 1000, // Events before compaction
    safeOffsetDeltaForPrune: 100, // Offset window to preserve
})
```

## 用法实例

### 基本合同检索

```typescript
const reader = new ACSReader(ledgerProvider)

// Fetch all active contracts
const allContracts = await reader.read({})

// Filter by template ID
const tokenContracts = await reader.read({
    templateIds: ['templateId'],
})

// Filter by multiple parties
const partyContracts = await reader.read({
    parties: ['partyId', 'partyId2'],
    filterByParty: true,
})
```

### 与 JavaScript 合同合作

这个 `readJsContracts` 方法以更方便使用的格式返回合同数据:

```typescript
const jsContracts = await reader.readJsContracts({
    templateIds: ['templateId'],
    parties: ['partyId'],
})

// Each contract includes:
// - All fields from createdEvent
// - synchronizerId
jsContracts.forEach((contract) => {
    console.log(contract.contractId, contract.templateId)
    console.log(contract.createArgument)
})
```

### 预留访问

对于大型数据集,请使用相接读取器:

```typescript
const reader = new ACSReader(ledgerProvider)

// Fetch first page
const firstPage = await reader.paginated.read({
    templateIds: ['templateId'],
    maxPageSize: 100,
})

// Fetch next page using token
const nextPage = await reader.paginated.read({
    templateIds: ['templateId'],
    pageToken: firstPage.nextPageToken,
    maxPageSize: 100,
})

// Or fetch all pages at once
const allPages = await reader.paginated.read({
    templateIds: ['templateId'],
    continueUntilCompletion: true,
})
```

### 原始数据访问

获取原始合同答复而无需缓存:

```typescript
const reader = new ACSReader(ledgerProvider)

// Standard raw access
const rawContracts = await reader.raw.read({
    templateIds: ['templateId'],
})

// Paginated raw access
const rawPage = await reader.paginated.raw.read({
    templateIds: ['templateId'],
    maxPageSize: 100,
})
```

### 持续获取

在一个呼叫中获取所有可用的数据 :

```typescript
const contracts = await reader.read({
    templateIds: ['templateId'],
    continueUntilCompletion: true,
    limit: 200, // Batch size for each query
})
```

## API 参考

### `ACSReader`

阅读现行合同的主要课程.

#### 构造器

```typescript
new ACSReader(
  ledger: AbstractLedgerProvider,
  cacheOptions?: ACSCacheCollectionOptions
)
```

## 配置

### 缓存选项( 不适用于页形模式)

```typescript
interface ACSCacheCollectionOptions {
    // Compact history after this many events
    maxEventsBeforePrune?: number

    // Preserve events within this offset window
    safeOffsetDeltaForPrune?: number
}
```

-   设定 `maxEventsBeforePrune` 改为 `0` 用于立即收缩(单调增减效率)
-   设定 `safeOffsetDeltaForPrune` 改为 `0` 以压缩当前窗口外的所有内容

## 最佳做法

1.  **重新使用阅读器实例**: 创建一个读取器实例并重新使用,以便从缓存中受益
2.  **提前过滤**: 应用模板和政党过滤器以减少数据传输和处理
3.  **使用旁观**: 对于大型数据集,使用相接访问控制内存使用
4.  **配置缓存**: 基于查询模式的 Tune 缓存设置
5.  **处理偏移**:让读者自动解决抵消,除非您需要特定的时间点

## 常见问题

### @canton-network/core-acs-reader 是什么？

从Canton分类账中获取主动合同集数据的阅读器,为特定过滤器提供检索和处理主动合同信息的功能\.

### 如何安装 @canton-network/core-acs-reader？

在项目目录运行 npm install @canton-network/core-acs-reader，或使用 pnpm add / yarn add / bun add。

### @canton-network/core-acs-reader 支持 TypeScript 吗？

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

### @canton-network/core-acs-reader 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @canton-network/core-acs-reader 可以商用吗？

@canton-network/core-acs-reader 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @canton-network/core-acs-reader 的下载量有多少？

根据 npm 官方下载统计，@canton-network/core-acs-reader 在 2026/10/09 – 2026/11/07 这 30 天内被下载 321,096 次，日均约 10,703 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canton-network/core-acs-reader 还在维护吗？

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