Child Start Block Parameter

[alphak3y]

Summary

This PR adds support for specifying a custom start block when indexing child contracts created by a factory pattern. Previously, child contracts were always indexed starting from the block where the factory event was emitted. This change allows backfilling events from child contracts that occurred before the factory event.

Motivation

In some use cases, a factory contract may emit events about child contracts that were created earlier, or you may want to index child contract events from a specific historical block regardless of when the factory event occurred. This was previously not possible with Ponder's factory pattern.

New Features

1. childStartBlock - Static Start Block

Specify a fixed block number to start indexing all child contract events from:

export default createConfig({
contracts: {
ChildContract: {
abi: childAbi,
address: factory({
address: "0xFactoryAddress",
event: parseAbiEvent("event ChildCreated(address indexed child)"),
parameter: "child",
childStartBlock: 14645816, // All children indexed from this block
}),
network: "mainnet",
},
},
});### 2. startBlockParameter - Dynamic Start Block from Event

Extract the start block dynamically from a parameter in the factory event:

export default createConfig({
contracts: {
ChildContract: {
abi: childAbi,
address: factory({
address: "0xFactoryAddress",
event: parseAbiEvent("event ChildCreated(address indexed child, uint256 indexed startBlock)"),
parameter: "child",
startBlockParameter: "startBlock", // Start block extracted from event
}),
network: "mainnet",
},
},
});## Implementation Details

Files Changed

• packages/core/src/config/address.ts - Added childStartBlock and startBlockParameter to the public Factory type
• packages/core/src/internal/types.ts - Added childStartBlock and childStartBlockLocation to internal LogFactory type
• packages/core/src/build/factory.ts - Updated buildLogFactory to process the new options and compute parameter locations
• packages/core/src/build/config.ts - Pass new options through config building
• packages/core/src/runtime/filter.ts - Added getChildStartBlock() helper function for extracting start blocks
• packages/core/src/sync-historical/index.ts - Updated historical sync to use custom start blocks for backfilling
• packages/core/src/sync-realtime/index.ts - Updated realtime sync to track start blocks per child address

Tests Added

• buildLogFactory with childStartBlock static value
• buildLogFactory with startBlockParameter from indexed topic
• buildLogFactory with startBlockParameter from data offset
• buildLogFactory with startBlockParameter extracts from chainId
• buildLogFactory throws if startBlockParameter not found
• getChildStartBlock() returns undefined when no config
• getChildStartBlock() returns static childStartBlock
• getChildStartBlock() extracts from topic
• getChildStartBlock() extracts from data offset
• getChildStartBlock() static childStartBlock takes precedence over location

Breaking Changes

None. The new options are fully optional and existing factory configurations continue to work unchanged.

Testing

• ✅ All 311 core package tests pass
• ✅ Build succeeds