blockchain

package
v0.15.7 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2025 License: Apache-2.0 Imports: 15 Imported by: 4

Documentation

Index

Constants

View Source 
const AggregatedBloomFilterCacheSize = 16

NOTE(Ege): consider making it configurable

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 = errors.New("block's parent hash does not match head block hash")

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 *utils.Network) *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) EventFilter added in v0.3.1 

func (b *Blockchain) EventFilter(from *felt.Felt, keys [][]felt.Felt, pendingBlockFn func() *core.Block) (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.Class,
	sign utils.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) 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 *common.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() *utils.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.

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.Class,
) (*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.Class,
	sign utils.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) StateCommitment 

func (b *Blockchain) StateCommitment() (*felt.Felt, error)

StateCommitment returns the latest block state commitment. If blockchain is empty zero felt is returned.

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.Class,
) 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.Class,
) error

func (*Blockchain) SubscribeL1Head added in v0.13.0 

func (b *Blockchain) SubscribeL1Head() L1HeadSubscription

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

func (b *Blockchain) VerifyBlock(block *core.Block) error

VerifyBlock assumes the block has already been sanity-checked.

func (*Blockchain) WithListener added in v0.7.4 

func (b *Blockchain) WithListener(listener EventListener) *Blockchain

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) 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(contractAddress *felt.Felt, keys [][]felt.Felt) EventMatcher

func (*EventMatcher) AppendBlockEvents added in v0.13.2 

func (e *EventMatcher) AppendBlockEvents(matchedEventsSofar []*FilteredEvent, header *core.Header, receipts []*core.TransactionReceipt,
	skippedEvents uint64, chunkSize uint64,
) ([]*FilteredEvent, uint64, error)

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
	EventIndex      int
}

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 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)
	BlockHeaderByHash(hash *felt.Felt) (header *core.Header, err error)

	TransactionByHash(hash *felt.Felt) (transaction core.Transaction, err error)
	TransactionByBlockNumberAndIndex(blockNumber, index uint64) (transaction core.Transaction, err error)
	Receipt(hash *felt.Felt) (receipt *core.TransactionReceipt, blockHash *felt.Felt, blockNumber uint64, err error)
	StateUpdateByNumber(number uint64) (update *core.StateUpdate, err error)
	StateUpdateByHash(hash *felt.Felt) (update *core.StateUpdate, err error)
	L1HandlerTxnHash(msgHash *common.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(from *felt.Felt, keys [][]felt.Felt, pendingBlockFn func() *core.Block) (EventFilterer, error)

	Network() *utils.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 struct {
	BlockCommitments *core.BlockCommitments
	ConcatCount      felt.Felt
}

type StateCloser added in v0.3.0 

type StateCloser = func() error

Source Files

View all Source files

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.