Documentation
¶
Index ¶
Constants ¶
const DefaultBlockCapacity = 256
Variables ¶
var ErrTargetNotFound = errors.New("transaction trace target not found")
Functions ¶
func OffsetExecutionError ¶ added in v0.17.0
OffsetExecutionError converts a vm.TransactionExecutionError index from suffix-relative to block-relative.
Types ¶
type BlockTrace ¶
type BlockTrace struct {
Complete bool
Source Source
Traces []TransactionTrace
InitialReads *vm.InitialReads
}
BlockTrace holds version-neutral traces in block order; published data is read-only. InitialReads is nil when uncollected or unavailable (Feeder).
func FromFeeder ¶
func FromFeeder( kinds []vm.TransactionType, receipts []*core.TransactionReceipt, source *starknet.BlockTrace, ) (*BlockTrace, error)
FromFeeder pairs source traces with supplied types and receipt gas.
func FromVM ¶
func FromVM( transactions []core.Transaction, result *vm.ExecutionResults, initialReads bool, ) (*BlockTrace, error)
FromVM retains traces and gas. Requested initial reads must be non-nil, even for empty blocks. For range execution, use BlockTrace.Combine before publication.
func (*BlockTrace) Combine ¶ added in v0.17.0
func (b *BlockTrace) Combine(r *Range) (*BlockTrace, error)
Combine prepends the range's cached prefix to b's executed suffix and returns b.
Parameters:
- r: the non-nil range used to execute transactions[r.Start:r.End].
The receiver is marked complete only if the range reaches the block's end.
func (*BlockTrace) Covers ¶
func (b *BlockTrace) Covers(initialReads bool) bool
Covers checks requested read coverage, allowing unavailable feeder reads. It also requires complete block coverage.
func (*BlockTrace) CoversTarget ¶ added in v0.17.0
func (b *BlockTrace) CoversTarget(target *TransactionTarget, initialReads bool) bool
CoversTarget checks coverage through the requested transaction and requested initial reads. The target must be non-nil. Use BlockTrace.Covers for whole-block coverage.
func (*BlockTrace) ValidTarget ¶ added in v0.17.0
func (b *BlockTrace) ValidTarget(target *TransactionTarget) bool
ValidTarget reports whether the target index identifies a trace with the requested hash.
type Cache ¶
type Cache[K comparable, V any] struct { // contains filtered or unexported fields }
Cache shares immutable results across requests, using a Lease to coordinate one producer per key while keeping existing results available to readers. See the usage example in Cache.Acquire.
func (*Cache[K, V]) Acquire ¶
func (c *Cache[K, V]) Acquire( ctx context.Context, key *K, accepts func(V) bool, ) (V, *Lease[K, V], error)
Acquire returns a cached value, grants a lease, or waits.
Parameters:
- ctx: controls cancellation while waiting for another lease to be released.
- key: identifies the cached value; must be non-nil.
- accepts: a brief, read-only function that reports whether the cached value satisfies this request. Returning true accepts the value without a lease; returning false requests a replacement lease or waits for the current owner. If accepts is nil, any cached value is accepted. It must not call back into this cache.
Outcomes:
- A cached value exists and accepts is nil or returns true: return it without a lease.
- No cached value and no lease exists: return a lease with the zero value.
- accepts returns false and no lease exists: return a lease with the cached value.
- A lease exists and no cached value meets the request: wait for its release and retry.
Caller responsibilities:
- Cached values aren't deep-copied (as traces can be very large); callers must not mutate shared data they reference.
- Call Lease.Release to relinquish ownership without changing the cached value, or Lease.Publish to store a value and release ownership.
Example usage:
cached, lease, err := cache.Acquire(ctx, &key, accepts)
if err != nil {
return nil, err
}
if lease == nil {
return cached, nil
}
defer lease.Release()
// buildValue must leave shared cached data unchanged.
result, err := buildValue(cached)
if err != nil {
return nil, err
}
lease.Publish(result)
return result, nil
type Lease ¶
type Lease[K comparable, V any] struct { // contains filtered or unexported fields }
Lease represents a caller's exclusive right to produce and publish a result for one Cache key. It coordinates replacement of the cached value without blocking requests that the existing value already satisfies. See the usage example in Cache.Acquire.
type Range ¶ added in v0.17.0
Range lets RPC handlers extend a cached BlockTrace without re-executing its transactions. Cached vm.StateDiff values provide the checkpoint the VM needs to continue. The handler owns execution, state-reader lifetime, and cache publication.
Lifecycle: A handler uses it when Cache.Acquire grants a lease for an unsatisfied request:
- Plan the work with PlanRange for the requested transaction or block.
- Prepare the starting state with Range.ResumeState.
- Execute transactions[Start:End] against that state. Use OffsetExecutionError with Start when reporting VM errors to the RPC caller.
- Package the suffix with FromVM and call BlockTrace.Combine with the range.
- Call Lease.Publish on success, or Lease.Release on failure.
Example Workflow: A six-transaction block has two traces cached. A request arrives for transaction 4:
- Work needed: transactions [2, 5).
- Starting state: if the cached transactions changed a nonce from 6 to 7 to 8, the VM starts with nonce 8.
- Result: the cache now covers transactions 0 through 4. A later request can extend it to include transaction 5.
See Cache for the mutability contract for published traces.
func PlanRange ¶ added in v0.17.0
func PlanRange( cached *BlockTrace, transactions []core.Transaction, target *TransactionTarget, initialReads bool, ) (Range, error)
PlanRange determines which block transactions need execution. The returned range uses an inclusive Start and exclusive End.
Parameters:
- cached: the block trace returned alongside the lease by Cache.Acquire.
- transactions: the full ordered transaction list loaded for the block, including transactions already covered by cached.
- target: the requested transaction's index and hash, assembled by the RPC handler. Nil requests execution through the block's end.
- initialReads: when true, the entire block must be replayed from the beginning. The target must be nil or the last transaction. Request initial reads from the VM and pass true to FromVM.
func (*Range) ResumeState ¶ added in v0.17.0
func (r *Range) ResumeState( parent core.StateReader, classes core.StateReader, blockNumber uint64, ) (core.StateReader, error)
ResumeState provides the VM's starting state for this range. Reconstructs the state after the cached prefix so that the VM can execute the remaining transactions without replaying that prefix.
Parameters:
- parent: the state reader for the state immediately before the block.
- classes: the state reader used to load classes declared in the cached prefix, typically the chain's head state.
- blockNumber: the number of the block being traced.
type TransactionTarget ¶ added in v0.17.0
type TransactionTarget struct {
Index uint64
Hash *felt.TransactionHash
}
TransactionTarget identifies the transaction to trace. A nil target requests a full block trace.
type TransactionTrace ¶
type TransactionTrace struct {
Hash felt.Felt
Type vm.TransactionType // Set by [FromFeeder]; VM traces carry their own type.
Gas core.GasConsumed
// contains filtered or unexported fields
}
TransactionTrace holds one source trace and its RPC adaptation metadata.
func (*TransactionTrace) FeederTrace ¶
func (t *TransactionTrace) FeederTrace() *starknet.TransactionTrace
func (*TransactionTrace) VMTrace ¶
func (t *TransactionTrace) VMTrace() *vm.TransactionTrace
Source Files