@canton-network/core-acs-reader

Overview

The ACS Reader abstracts the complexity of querying and managing active contracts from the Canton ledger. It offers both standard and paginated access patterns, with intelligent caching to minimize network overhead and improve application performance.

Installation

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

Quick Start

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

Core Concepts

ACS Reader

The ACSReader class is the primary interface for querying active contracts. It maintains an internal cache and provides methods for both raw and processed contract data.

Options

Standard Options (AcsOptions):

• offset: Ledger offset to query from (automatically resolved if omitted)
• templateIds: Array of template IDs to filter by
• interfaceIds: Array of interface IDs to filter by
• parties: Array of party IDs to filter by
• filterByParty: Enable party-based filtering
• limit: Maximum number of results to return
• continueUntilCompletion: Continue fetching until all data is retrieved

Paginated Options (PaginatedAcsOptions): Same as standard options, plus:

• pageToken: Token for fetching specific pages
• maxPageSize: Maximum number of contracts per page

Cache Configuration

Configure cache behavior with ACSCacheCollectionOptions:

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

Usage Examples

Basic Contract Retrieval

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

Working with JavaScript Contracts

The readJsContracts method returns contract data in a more accessible format:

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

Paginated Access

For large datasets, use the paginated reader:

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

Raw Data Access

Access raw contract responses without caching:

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

Continuous Fetching

Fetch all available data in a single call:

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

API Reference

ACSReader

Main class for reading active contracts.

Constructor

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

Configuration

Cache Options (not applicable for pagination mode)

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

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

• Set maxEventsBeforePrune to 0 for immediate compaction (efficient for monotonically increasing offsets)
• Set safeOffsetDeltaForPrune to 0 to compact everything outside the current window

Best Practices

1. Reuse Reader Instances: Create one reader instance and reuse it to benefit from caching
2. Filter Early: Apply template and party filters to reduce data transfer and processing
3. Use Pagination: For large datasets, use paginated access to control memory usage
4. Configure Cache: Tune cache settings based on your query patterns
5. Handle Offsets: Let the reader resolve offsets automatically unless you need specific points in time