blockchain

package
v0.16.6-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 28, 2026 License: Apache-2.0 Imports: 19 Imported by: 4

Documentation

Index

Constants

View Source 
const AggregatedBloomFilterCacheSize = 16

NOTE(Ege): consider making it configurable

View Source 
const PreConfirmedFilterSentinel uint64 = math.MaxUint64

PreConfirmedFilterSentinel marks a filter block bound as the pre_confirmed tag.

Variables

View Source 
var (
	ErrMaxScannedBlockLimitExceed       = errors.New("max scanned blocks exceeded")
	ErrAggregatedBloomFilterFallbackNil = errors.New("aggregated bloom filter does not have fallback")
	ErrFetchedFilterBoundsMismatch      = errors.New("fetched filter bounds mismatch")
	ErrNilRunningFilter                 = errors.New("running filter is nil")
)
View Source 
var ErrParentDoesNotMatchHead = statebackend.ErrParentDoesNotMatchHead

Functions

This section is empty.

Types

type AggregatedBloomFilterCache added in v0.14.6 

type AggregatedBloomFilterCache struct {
	// contains filtered or unexported fields
}

AggregatedBloomFilterCache stores and manages LRU-cached aggregated bloom filters for block ranges, supporting fallback loading and bulk insertion. It is safe for concurrent use.

func NewAggregatedBloomCache added in v0.14.6 

func NewAggregatedBloomCache(size int) *AggregatedBloomFilterCache

NewAggregatedBloomCache creates a new LRU cache for aggregated bloom filters with the specified maximum size (number of ranges to cache).

func (*AggregatedBloomFilterCache) NewMatchedBlockIterator added in v0.14.6 

func (c *AggregatedBloomFilterCache) NewMatchedBlockIterator(
	fromBlock, toBlock uint64,
	maxScanned uint64,
	matcher *EventMatcher,
	runningFilter *core.RunningEventFilter,
) (MatchedBlockIterator, error)

NewMatchedBlockIterator constructs an iterator for block numbers within [fromBlock, toBlock] that may match the given EventMatcher. The scan can be limited to maxScanned candidate blocks. It uses cached (or fetched via fallback) AggregatedBloomFilter windows for efficiency. Returns an error if input is invalid or required state is missing.

func (*AggregatedBloomFilterCache) Reset added in v0.14.6 

func (c *AggregatedBloomFilterCache) Reset()

Reset clears the entire bloom filter cache, removing all stored filters.

func (*AggregatedBloomFilterCache) SetMany added in v0.14.6 

func (c *AggregatedBloomFilterCache) SetMany(filters []*core.AggregatedBloomFilter)

SetMany inserts multiple aggregated bloom filters into the cache. Each filter is keyed by its block range.

func (*AggregatedBloomFilterCache) WithFallback added in v0.14.6 

func (c *AggregatedBloomFilterCache) WithFallback(fallback func(EventFiltersCacheKey) (core.AggregatedBloomFilter, error))

WithFallback sets a fallback fetch function to be used if a requested AggregatedBloomFilter is not found in the cache. The provided function must return a filter matching the queried range, or an error.

type Blockchain 

type Blockchain struct {
	// contains filtered or unexported fields
}

Blockchain is responsible for keeping track of all things related to the Starknet blockchain

func New 

func New(database db.KeyValueStore, network *networks.Network, opts ...Option) *Blockchain

func (*Blockchain) BlockByHash added in v0.2.1 

func (b *Blockchain) BlockByHash(hash *felt.Felt) (*core.Block, error)

func (*Blockchain) BlockByNumber added in v0.2.1 

func (b *Blockchain) BlockByNumber(number uint64) (*core.Block, error)

func (*Blockchain) BlockCommitmentsByNumber added in v0.6.0 

func (b *Blockchain) BlockCommitmentsByNumber(blockNumber uint64) (*core.BlockCommitments, error)

func (*Blockchain) BlockHeaderByHash added in v0.2.1 

func (b *Blockchain) BlockHeaderByHash(hash *felt.Felt) (*core.Header, error)

func (*Blockchain) BlockHeaderByNumber added in v0.2.1 

func (b *Blockchain) BlockHeaderByNumber(number uint64) (*core.Header, error)

func (*Blockchain) BlockHeaderHashByNumber added in v0.16.6 

func (b *Blockchain) BlockHeaderHashByNumber(number uint64) (*felt.Felt, error)

func (*Blockchain) BlockNumberAndIndexByTxHash added in v0.15.17 

func (b *Blockchain) BlockNumberAndIndexByTxHash(
	hash *felt.TransactionHash,
) (blockNumber, txIndex uint64, returnedErr error)

BlockNumberAndIndexByTxHash gets transaction block number and index by Tx hash

func (*Blockchain) BlockNumberByHash added in v0.15.17 

func (b *Blockchain) BlockNumberByHash(hash *felt.Felt) (uint64, error)

func (*Blockchain) BlockTransactionCountByNumber added in v0.16.6 

func (b *Blockchain) BlockTransactionCountByNumber(number uint64) (uint64, error)

func (*Blockchain) EventFilter added in v0.3.1 

func (b *Blockchain) EventFilter(
	addresses []felt.Address,
	keys [][]felt.Felt,
	preConfirmedFn func() (PreConfirmedReader, error),
) (EventFilterer, error)

EventFilter returns an EventFilter object that is tied to a snapshot of the blockchain

func (*Blockchain) Finalise added in v0.14.4 

func (b *Blockchain) Finalise(
	block *core.Block,
	stateUpdate *core.StateUpdate,
	newClasses map[felt.Felt]core.ClassDefinition,
	sign core.BlockSignFunc,
) error

Finalise checks the block correctness and appends it to the chain

func (*Blockchain) GetReverseStateDiff added in v0.12.3 

func (b *Blockchain) GetReverseStateDiff() (core.StateDiff, error)

func (*Blockchain) GlobalStateRootByBlockNumber added in v0.16.6 

func (b *Blockchain) GlobalStateRootByBlockNumber(number uint64) (*felt.Felt, error)

func (*Blockchain) Head 

func (b *Blockchain) Head() (*core.Block, error)

func (*Blockchain) HeadState added in v0.3.0 

func (b *Blockchain) HeadState() (core.StateReader, StateCloser, error)

HeadState returns a StateReader that provides a stable view to the latest state

func (*Blockchain) HeadsHeader 

func (b *Blockchain) HeadsHeader() (*core.Header, error)

func (*Blockchain) Height 

func (b *Blockchain) Height() (uint64, error)

Height returns the latest block height. If blockchain is empty nil is returned.

func (*Blockchain) L1HandlerTxnHash added in v0.13.0 

func (b *Blockchain) L1HandlerTxnHash(msgHash *eth.Hash) (felt.Felt, error)

func (*Blockchain) L1Head added in v0.4.0 

func (b *Blockchain) L1Head() (core.L1Head, error)

func (*Blockchain) Network 

func (b *Blockchain) Network() *networks.Network

func (*Blockchain) Receipt added in v0.2.1 

func (b *Blockchain) Receipt(hash *felt.Felt) (*core.TransactionReceipt, *felt.Felt, uint64, error)

Receipt gets the transaction receipt for a given transaction hash. TODO: Return TransactionReceipt instead of *TransactionReceipt.

func (*Blockchain) RevertHead added in v0.4.0 

func (b *Blockchain) RevertHead() error

RevertHead reverts the head block

func (*Blockchain) SanityCheckNewHeight 

func (b *Blockchain) SanityCheckNewHeight(block *core.Block, stateUpdate *core.StateUpdate,
	newClasses map[felt.Felt]core.ClassDefinition,
) (*core.BlockCommitments, error)

SanityCheckNewHeight checks integrity of a block and resulting state update

func (*Blockchain) SetL1Head added in v0.4.0 

func (b *Blockchain) SetL1Head(update *core.L1Head) error

func (*Blockchain) Simulate added in v0.14.6 

func (b *Blockchain) Simulate(
	block *core.Block,
	stateUpdate *core.StateUpdate,
	newClasses map[felt.Felt]core.ClassDefinition,
	sign core.BlockSignFunc,
) (SimulateResult, error)

Simulate returns what the new completed header and state update would be if the provided block was added to the chain.

func (*Blockchain) StateAtBlockHash added in v0.3.0 

func (b *Blockchain) StateAtBlockHash(

	blockHash *felt.Felt,
) (core.StateReader, StateCloser, error)

StateAtBlockHash returns a StateReader that provides a stable view to the state at the given block hash

func (*Blockchain) StateAtBlockNumber added in v0.3.0 

func (b *Blockchain) StateAtBlockNumber(
	blockNumber uint64,
) (core.StateReader, StateCloser, error)

StateAtBlockNumber returns a StateReader that provides a stable view to the state at the given block number

func (*Blockchain) StateUpdateByHash added in v0.2.1 

func (b *Blockchain) StateUpdateByHash(hash *felt.Felt) (*core.StateUpdate, error)

func (*Blockchain) StateUpdateByNumber added in v0.2.1 

func (b *Blockchain) StateUpdateByNumber(number uint64) (*core.StateUpdate, error)

func (*Blockchain) Store 

func (b *Blockchain) Store(
	block *core.Block,
	blockCommitments *core.BlockCommitments,
	stateUpdate *core.StateUpdate,
	newClasses map[felt.Felt]core.ClassDefinition,
) error

Store takes a block and state update and performs sanity checks before putting in the database.

func (*Blockchain) StoreGenesis added in v0.14.4 

func (b *Blockchain) StoreGenesis(
	diff *core.StateDiff,
	classes map[felt.Felt]core.ClassDefinition,
) error

func (*Blockchain) SubscribeL1Head added in v0.13.0 

func (b *Blockchain) SubscribeL1Head() L1HeadSubscription

func (*Blockchain) TransactionAndReceiptByBlockNumberAndIndex added in v0.16.6 

func (b *Blockchain) TransactionAndReceiptByBlockNumberAndIndex(
	blockNumber, index uint64,
) (core.Transaction, core.TransactionReceipt, *felt.Felt, error)

TransactionAndReceiptByBlockNumberAndIndex returns a transaction, its receipt and the hash of the block holding them.

func (*Blockchain) TransactionByBlockNumberAndIndex added in v0.2.1 

func (b *Blockchain) TransactionByBlockNumberAndIndex(blockNumber, index uint64) (core.Transaction, error)

TransactionByBlockNumberAndIndex gets the transaction for a given block number and index.

func (*Blockchain) TransactionByHash added in v0.2.1 

func (b *Blockchain) TransactionByHash(hash *felt.Felt) (core.Transaction, error)

TransactionByHash gets the transaction for a given hash.

func (*Blockchain) TransactionExecutionStatusByBlockNumberAndIndex added in v0.16.6 

func (b *Blockchain) TransactionExecutionStatusByBlockNumberAndIndex(
	blockNumber, index uint64,
) (core.TransactionExecutionStatus, error)

TransactionExecutionStatusByBlockNumberAndIndex returns only the status subset of a receipt.

func (*Blockchain) TransactionHashesByBlockNumber added in v0.16.6 

func (b *Blockchain) TransactionHashesByBlockNumber(number uint64) ([]felt.Felt, error)

TransactionHashesByBlockNumber returns the transaction hashes of a given block.

func (*Blockchain) TransactionsAndReceiptsByBlockNumber added in v0.16.6 

func (b *Blockchain) TransactionsAndReceiptsByBlockNumber(
	number uint64,
) ([]core.Transaction, []*core.TransactionReceipt, error)

TransactionsAndReceiptsByBlockNumber gets all transactions and receipts for a given block number

func (*Blockchain) TransactionsByBlockNumber added in v0.15.20 

func (b *Blockchain) TransactionsByBlockNumber(number uint64) ([]core.Transaction, error)

TransactionsByBlockNumber gets all transactions for a given block number

func (*Blockchain) WriteRunningEventFilter added in v0.14.6 

func (b *Blockchain) WriteRunningEventFilter() error

type ContinuationToken added in v0.3.1 

type ContinuationToken struct {
	// contains filtered or unexported fields
}

func (*ContinuationToken) FromString added in v0.3.1 

func (c *ContinuationToken) FromString(str string) error

func (*ContinuationToken) IsEmpty added in v0.15.9 

func (c *ContinuationToken) IsEmpty() bool

func (*ContinuationToken) String added in v0.3.1 

func (c *ContinuationToken) String() string

type EventFilter added in v0.3.1 

type EventFilter struct {
	// contains filtered or unexported fields
}

func (*EventFilter) Close added in v0.3.1 

func (e *EventFilter) Close() error

Close closes the underlying database transaction that provides the blockchain snapshot

func (*EventFilter) Events added in v0.3.1 

func (e *EventFilter) Events(
	cToken *ContinuationToken,
	chunkSize uint64,
) ([]FilteredEvent, ContinuationToken, error)

func (*EventFilter) SetRangeEndBlockByHash added in v0.3.1 

func (e *EventFilter) SetRangeEndBlockByHash(
	filterRange EventFilterRange,
	blockHash *felt.Felt,
) error

SetRangeEndBlockByHash sets an end of the block range by block hash

func (*EventFilter) SetRangeEndBlockByNumber added in v0.3.1 

func (e *EventFilter) SetRangeEndBlockByNumber(
	filterRange EventFilterRange,
	blockNumber uint64,
) error

SetRangeEndBlockByNumber sets an end of the block range by block number

func (*EventFilter) SetRangeEndBlockToL1Head added in v0.15.1 

func (e *EventFilter) SetRangeEndBlockToL1Head(filterRange EventFilterRange) error

SetRangeEndBlockToL1Head sets an end of the block range to latest `l1_accepted` block

func (*EventFilter) WithLimit added in v0.7.5 

func (e *EventFilter) WithLimit(limit uint) *EventFilter

WithLimit sets the limit for events scan

type EventFilterRange added in v0.3.1 

type EventFilterRange uint
const (
	EventFilterFrom EventFilterRange = iota
	EventFilterTo
)

type EventFilterer added in v0.13.0 

type EventFilterer interface {
	io.Closer

	Events(cToken *ContinuationToken, chunkSize uint64) ([]FilteredEvent, ContinuationToken, error)
	SetRangeEndBlockByNumber(filterRange EventFilterRange, blockNumber uint64) error
	SetRangeEndBlockByHash(filterRange EventFilterRange, blockHash *felt.Felt) error
	SetRangeEndBlockToL1Head(filterRange EventFilterRange) error
	WithLimit(limit uint) *EventFilter
}

type EventFiltersCacheKey added in v0.14.6 

type EventFiltersCacheKey struct {
	// contains filtered or unexported fields
}

EventFiltersCacheKey uniquely identifies a range of blocks whose aggregated bloom filter is cached. Used as the lookup key for bloom filter caches.

type EventListener added in v0.7.4 

type EventListener interface {
	OnRead(method string)
}

type EventMatcher added in v0.13.2 

type EventMatcher struct {
	// contains filtered or unexported fields
}

func NewEventMatcher added in v0.13.2 

func NewEventMatcher(contractAddresses []felt.Address, keys [][]felt.Felt) EventMatcher

func (*EventMatcher) AppendBlockEventsFromReceipts added in v0.16.6 

func (e *EventMatcher) AppendBlockEventsFromReceipts(
	matchedEventsSofar []FilteredEvent,
	blockNum uint64,
	blockHash *felt.Felt,
	receipts []*core.TransactionReceipt,
	skippedEvents uint64,
	chunkSize uint64,
) ([]FilteredEvent, uint64, error)

AppendBlockEventsFromReceipts appends the events of one block that match the filter to matchedEventsSofar, read from full receipts of any source. The caller holds the block hash, which is nil for a source that has none, so this loop takes it directly. See AppendBlockEventsFromTransactionEvents for why the loops stay separate.

func (*EventMatcher) AppendBlockEventsFromTransactionEvents added in v0.16.6 

func (e *EventMatcher) AppendBlockEventsFromTransactionEvents(
	matchedEventsSofar []FilteredEvent,
	blockNum uint64,
	blockHashFn func() (*felt.Felt, error),
	blockEvents []core.TransactionEvents,
	skippedEvents uint64,
	chunkSize uint64,
) ([]FilteredEvent, uint64, error)

AppendBlockEventsFromTransactionEvents appends the events of one block that match the filter to matchedEventsSofar. blockEvents holds the events-only projection of the block's receipts. blockHashFn gets the block hash on the first match, so a block with no match reads no header.

AppendBlockEventsFromReceipts holds the same loop for full receipts. Change both together: a shared loop needs a per-transaction call the compiler cannot inline.

func (*EventMatcher) MatchesAddress added in v0.15.20 

func (e *EventMatcher) MatchesAddress(eventFrom *felt.Felt) bool

func (*EventMatcher) MatchesEventKeys added in v0.15.2 

func (e *EventMatcher) MatchesEventKeys(eventKeys []felt.Felt) bool

func (*EventMatcher) TestBloom added in v0.13.2 

func (e *EventMatcher) TestBloom(bloomFilter *bloom.BloomFilter) bool

type FilteredEvent added in v0.3.1 

type FilteredEvent struct {
	*core.Event
	BlockNumber      uint64
	BlockHash        *felt.Felt
	TransactionHash  *felt.Felt
	TransactionIndex uint
	EventIndex       uint
}

type L1HeadSubscription added in v0.13.0 

type L1HeadSubscription struct {
	*feed.Subscription[*core.L1Head]
}

type MatchedBlockIterator added in v0.14.6 

type MatchedBlockIterator struct {
	// contains filtered or unexported fields
}

MatchedBlockIterator iterates over candidate block numbers within a block range that may match an event query, using cached (or fetched) aggregated bloom filters for efficient windowed scanning and filtering.

func (*MatchedBlockIterator) Next added in v0.14.6 

func (it *MatchedBlockIterator) Next() (uint64, bool, error)

Next advances the iterator to the next matching block number within the scanned range. Returns the next candidate block number (absolute), a boolean indicating if such exists, and any error encountered (including scan limit exhaustion or fallback fetch errors). When ok == false and error is nil, the iteration is complete.

type Option added in v0.16.0 

type Option func(*options)

Option is a functional option for configuring Blockchain options.

func WithListener added in v0.16.0 

func WithListener(listener EventListener) Option

WithListener sets the event listener for the blockchain.

func WithNewState added in v0.16.0 

func WithNewState(enabled bool) Option

WithNewState enables the new trie2-based state backend when enabled is true.

func WithRetentionFloor added in v0.16.6 

func WithRetentionFloor(floor *pruner.RetentionFloor) Option

WithRetentionFloor shares a seeded retention floor (see pruner.NewRetentionFloor) with the state backend, so retention checks skip the database. The default unseeded floor probes the database instead.

func WithRunningEventFilterInitializer added in v0.16.1 

func WithRunningEventFilterInitializer(initialize core.RunningEventFilterInitializer) Option

WithRunningEventFilterInitializer overrides the initializer used to lazily bring up the running event filter. Defaults to core.InitializeRunningEventFilter; pass pruner.InitializeRunningEventFilter on pruning nodes.

type PreConfirmedReader added in v0.16.5 

type PreConfirmedReader interface {
	Length() int
	Head() *pending.PreConfirmed
	OldestFirst() iter.Seq[*pending.PreConfirmed]
}

PreConfirmedReader is the subset of the preconfirmed.ChainReader API the blockchain's EventFilter needs. Declared here to keep blockchain free of a cyclic dependency on the sync/preconfirmed package (the poller already imports blockchain).

type Reader 

type Reader interface {
	Height() (height uint64, err error)

	Head() (head *core.Block, err error)
	L1Head() (core.L1Head, error)
	SubscribeL1Head() L1HeadSubscription
	BlockByNumber(number uint64) (block *core.Block, err error)
	BlockByHash(hash *felt.Felt) (block *core.Block, err error)

	HeadsHeader() (header *core.Header, err error)
	BlockHeaderByNumber(number uint64) (header *core.Header, err error)
	BlockHeaderHashByNumber(number uint64) (blockHash *felt.Felt, err error)
	BlockHeaderByHash(hash *felt.Felt) (header *core.Header, err error)
	BlockTransactionCountByNumber(number uint64) (count uint64, err error)

	BlockNumberByHash(hash *felt.Felt) (uint64, error)
	BlockNumberAndIndexByTxHash(
		hash *felt.TransactionHash,
	) (blockNumber uint64, index uint64, err error)

	TransactionByHash(hash *felt.Felt) (transaction core.Transaction, err error)
	TransactionByBlockNumberAndIndex(
		blockNumber, index uint64,
	) (transaction core.Transaction, err error)
	TransactionsByBlockNumber(blockNumber uint64) (transactions []core.Transaction, err error)
	TransactionsAndReceiptsByBlockNumber(blockNumber uint64) (
		transactions []core.Transaction,
		receipts []*core.TransactionReceipt,
		err error,
	)
	TransactionHashesByBlockNumber(blockNumber uint64) (hashes []felt.Felt, err error)

	Receipt(
		hash *felt.Felt,
	) (receipt *core.TransactionReceipt, blockHash *felt.Felt, blockNumber uint64, err error)
	TransactionAndReceiptByBlockNumberAndIndex(
		blockNumber, index uint64,
	) (
		transaction core.Transaction,
		receipt core.TransactionReceipt,
		blockHash *felt.Felt,
		err error,
	)
	TransactionExecutionStatusByBlockNumberAndIndex(
		blockNumber, index uint64,
	) (status core.TransactionExecutionStatus, err error)

	StateUpdateByNumber(number uint64) (update *core.StateUpdate, err error)
	StateUpdateByHash(hash *felt.Felt) (update *core.StateUpdate, err error)
	L1HandlerTxnHash(msgHash *eth.Hash) (l1HandlerTxnHash felt.Felt, err error)

	HeadState() (core.StateReader, StateCloser, error)
	StateAtBlockHash(blockHash *felt.Felt) (core.StateReader, StateCloser, error)
	StateAtBlockNumber(blockNumber uint64) (core.StateReader, StateCloser, error)

	BlockCommitmentsByNumber(blockNumber uint64) (*core.BlockCommitments, error)

	EventFilter(
		addresses []felt.Address,
		keys [][]felt.Felt,
		preConfirmedFn func() (PreConfirmedReader, error),
	) (EventFilterer, error)

	Network() *networks.Network
}

type SelectiveListener added in v0.7.4 

type SelectiveListener struct {
	OnReadCb func(method string)
}

func (*SelectiveListener) OnRead added in v0.7.4 

func (l *SelectiveListener) OnRead(method string)

type SimulateResult added in v0.14.6 

type SimulateResult = statebackend.SimulateResult

Re-export statebackend types for API compatibility.

type StateCloser added in v0.3.0 

type StateCloser = statebackend.StateCloser

Re-export statebackend types for API compatibility.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.