@secondlayer/subgraphs

Declares a schema you can hoist out of defineSubgraph() and reuse.

It keeps the schema's literal types, so table names and row columns stay checked in helpers typed TypedSubgraphContext<typeof schema>. as const alone does not work: it produces readonly arrays that a mutable uniqueKeys rejects, and a bare literal widens type to string.

Declares a subgraph and keeps its source and schema literal types.

Handlers are typed per source, and the schema drives query-client inference. It returns its argument unchanged.

Lists the fields each source filter type accepts.

The list is derived from SubgraphFilterSchema. Agent-facing surfaces such as the MCP filters reference used to keep a parallel copy by hand; deriving it means adding a field to a filter can never leave the documentation behind.

Validates a subgraph definition and returns the parsed result.

It throws when the definition is invalid.

Camelizes object keys recursively, the way print payloads are.

It uses the print-payload helper, not ABI toCamelCase, which strips -STX and prefixes leading digits.

Infers per-topic field schemas from sampled print events. Counts and height bounds cover ALL rows of a topic (cheap); only a bounded subset is deserialized for typing. Rows with missing/undecodable hex still count but contribute nothing to typing.

Reads a contract's read-only functions at the block being processed.

Results are untyped here. Call it through readContractAt to get typed results from the contract's ABI.

Queues a new row for a table.

Writes are batched and applied together when the block commits. _block_height and _tx_id are filled in for you.

Queues an update to the rows matching where.

set holds only the columns to change.

Inserts a row, or updates the one with the same key.

key should match a uniqueKeys constraint of the table. Without one the write falls back to a lookup first and logs a warning.

Queues deletion of the rows matching where.

Adds signed deltas to a counter row, creating it if missing.

It compiles to INSERT … ON CONFLICT (key) DO UPDATE SET col = COALESCE(col,0) + delta. Deltas commute, so it is the reorg-safe way to keep running totals such as per-cycle aggregates and balances. It needs a uniqueKeys constraint matching key, and deltas may be number or bigint.

Returns the first row matching where, or null.

Reads see the writes queued earlier in the same block, and rows come back in insertion order.

Returns every row matching where, in insertion order.

Reads see the writes queued earlier in the same block.

Reads a contract's read-only functions from a handler, with typed results.

Pass ctx, the contract id and its ABI. Every call is pinned to the block being processed. Set options.cache to "contract-constant" to fetch a value once per contract instead of once per block.

Generates PostgreSQL DDL statements for a subgraph definition. Creates a dedicated schema subgraph_<name> with one table per schema entry, each with auto-columns and indexes.

Generates a Prisma schema for a subgraph's tables.

Set modelsOnly to emit just the model blocks, to compose with your own schema.

Generates Drizzle table definitions for a subgraph's tables.

Generates Kysely table interfaces for a subgraph's tables.

Generates a typed schema for Index tables.

target picks Prisma, Kysely, Drizzle or JSON Schema. Use tables to limit the output. Prisma omits tables with no read-set key.

Convert a subgraph name to its PostgreSQL schema name.

Deploys a subgraph schema to the database.

A new subgraph gets its schema and tables created and registered. The same schema hash only updates the handler path. An additive change adds columns and tables in place, and a breaking change reindexes by dropping and recreating the tables.

Compare two multi-table subgraph schemas and return differences.

Index-only changes (indexed/search flags, composite indexes) are reported separately from data-shape changes: an index never requires a rebuild, so it must never land in changed/breaking — flipping indexed: true on a populated column used to cost a full reindex.

Tells whether a schema diff is breaking, with the reasons.

Breaking means removed tables, removed columns, changed column types or removed uniqueKeys, which handler upserts conflict on. Index-flag and composite-index changes are never breaking.

Render the DDL a deploy would run, without executing. Powers --dry-run: the user reviews exactly what a deploy does first.

Tells whether a subgraph can skip blocks without its events.

Sparse scanning is sound only when every source is an event-type filter. A contract_call or contract_deploy source matches transactions, which the event probe cannot see.

Tells whether a subgraph's sources can be read from the Streams index.

Every source must be a known event-type, contract_call or contract_deploy filter, and array-style sources never qualify because they leak the unreconstructable _eventId. Trait scope is allowed: trait resolution reads the contract registry on the platform database, which the processor always holds. Everything else stays on the database tap.

Lists the event types and contract scopes a subgraph's filters match.

Each target is a decoded event type with an optional contract scope. One function feeds both the sparse probe and the event walks, so a new contract-pinning filter field is added here once.

Per event type: if ANY filter for it is unscoped, a single unscoped target covers everything (today's behavior); otherwise one target per distinct pinned contract.

Content hash over everything that shapes a subgraph's rows. Unlike schema_hash, it changes with the handler, startBlock and runtime, so two deploys with the same pin produce the same rows from the same chain.

Derive how far a subgraph's rows can be checked. Level = the highest any source or handler read needs. reasons lists everything standing between the subgraph and checkable rows; a state subgraph with any reason is refused at deploy, so every stored state row has none. Never configured, never a flag.

Formats a handler finding as file:line:column name: reason.

Tells whether a deploy must be refused for breaking determinism.

It is refused when the sources are provable (state), so the determinism contract is enforced, and the scan broke it.

Loads a bundled handler into a fresh deterministic realm.

The bundle is ESM, as stored in handler_code. The returned definition has every handler wrapped to receive the deterministicContext facade.

Checks a served pin against the served bundle.

The preimage must hash to the pin, and name this handler code, this schema and this startBlock. A runtime other than this package's is only a note, since rows can still match.

The replay loop over an injected verifier.

Lists the contracts a state subgraph's writes come from.

It returns an error when a source does not fix one, because completeness would then need every contract's writes.

Verifies every block in a range and recomputes the subgraph's tables.

The range is [from, to], and blocks are verified from the checkpoint.

Compares replayed tables with the served ones over a block range.

Rows are matched on _block_height within [from, to]. Keyed tables, by their first uniqueKeys tuple, compare row by row, and unkeyed tables compare as multisets.

Builds a handler-shaped event for a source, typed by that source's filter.

data supplies the decoded, camelCased fields the runtime would have produced. Transaction metadata is filled in.

Build a typed event payload based on the source filter type. Returns the payload the handler will receive.

Builds an in-memory context for a subgraph's schema.

It is the real handler context with its row store swapped for memory, so reads see earlier writes. Use ctx.rows(table) to inspect what a handler wrote.

Run handlers against pre-built sample payloads in memory (no Index, no Postgres). Deploy uses this with print-schema dummy events to refuse EMPTY_MAPPING before DDL apply.

Apply local handlers to Index rows in memory. Fail-closed: matched events with zero written rows is EMPTY_MAPPING (the bns-names field-mapping shape).

Map an Index contract-call row onto the ContractCallEvent handler shape.

Map an Index event row onto the payload shape a handler expects.