@ canton- network/ 核心读取器

概览

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

安装

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

快速启动

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数字 :

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

用法实例

基本合同检索

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 方法以更方便使用的格式返回合同数据:

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)
})

预留访问

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

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,
})

原始数据访问

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

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,
})

持续获取

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

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

API 参考

ACSReader

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

构造器

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

配置

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

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. 处理偏移:让读者自动解决抵消,除非您需要特定的时间点