feat: blocks package (#18)

Introduces the `blocks.Block` type (and associated helpers), which
satisfies the `adaptor.BlockProperties` interface introduced in #7.
While the motivation of specific functionality may not be clear in
isolation, context can be garnered from the prototype code (f79aff0)
and how it uses this package in `saexec` and the primary SAE
implementation.

---------

Signed-off-by: Arran Schlosberg <[email protected]>
Co-authored-by: Stephen Buttolph <[email protected]>

Author: ARR4N

.envrc

@@ -0,0 +1,2 @@
+export GOROOT="$(go1.24.7 env GOROOT)"
+PATH_add "$(go1.24.7 env GOROOT)/bin"

.github/workflows/lint.yml

@@ -36,7 +36,7 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v6
         with:
-          version: v1.63.3
+          version: v1.64.8
 
   yamllint:
     runs-on: ubuntu-latest

.golangci.yml

@@ -82,6 +82,11 @@ linters-settings:
         severity: warning
         disabled: false
 
+  testifylint:
+    enable-all: true
+    disable:
+      - require-error # Blanket usage of require over assert is an anti-pattern
+
 issues:
   include:
     # Many of the default exclusions are because, verbatim "Annoying issue",

blocks/block.go

@@ -0,0 +1,116 @@
+// Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+// Package blocks defines [Streaming Asynchronous Execution] (SAE) blocks.
+//
+// [Streaming Asynchronous Execution]: https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/194-streaming-asynchronous-execution
+package blocks
+
+import (
+	"errors"
+	"fmt"
+	"runtime"
+	"sync/atomic"
+
+	"github.com/ava-labs/avalanchego/utils/logging"
+	"github.com/ava-labs/libevm/core/types"
+	"go.uber.org/zap"
+)
+
+// A Block extends a [types.Block] to track SAE-defined concepts of async
+// execution and settlement. It MUST be constructed with [New].
+type Block struct {
+	b *types.Block
+	// Invariant: ancestry is non-nil and contains non-nil pointers i.f.f. the
+	// block hasn't itself been settled. A synchronous block (e.g. SAE genesis
+	// or the last pre-SAE block) is always considered settled.
+	//
+	// Rationale: the ancestral pointers form a linked list that would prevent
+	// garbage collection if not severed. Once a block is settled there is no
+	// need to inspect its history so we sacrifice the ancestors to the GC
+	// Overlord as a sign of our unwavering fealty. See [InMemoryBlockCount] for
+	// observability.
+	ancestry atomic.Pointer[ancestry]
+	// Only the genesis block or the last pre-SAE block is synchronous. These
+	// are self-settling by definition so their `ancestry` MUST be nil.
+	synchronous bool
+	// Non-nil i.f.f. [Block.MarkExecuted] or [Block.ResotrePostExecutionState]
+	// have returned without error.
+	execution atomic.Pointer[executionResults]
+
+	// Allows this block to be ruled out as able to be settled at a particular
+	// time (i.e. if this field is >= said time). The pointer MAY be nil if
+	// execution is yet to commence. For more details, see
+	// [Block.SetInterimExecutionTime for setting and [LastToSettleAt] for
+	// usage.
+	executionExceededSecond atomic.Pointer[uint64]
+
+	executed chan struct{} // closed after `execution` is set
+	settled  chan struct{} // closed after `ancestry` is cleared
+
+	log logging.Logger
+}
+
+var inMemoryBlockCount atomic.Int64
+
+// InMemoryBlockCount returns the number of blocks created with [New] that are
+// yet to have their GC finalizers run.
+func InMemoryBlockCount() int64 {
+	return inMemoryBlockCount.Load()
+}
+
+// New constructs a new Block.
+func New(eth *types.Block, parent, lastSettled *Block, log logging.Logger) (*Block, error) {
+	b := &Block{
+		b:        eth,
+		executed: make(chan struct{}),
+		settled:  make(chan struct{}),
+	}
+
+	inMemoryBlockCount.Add(1)
+	runtime.AddCleanup(b, func(struct{}) {
+		inMemoryBlockCount.Add(-1)
+	}, struct{}{})
+
+	if err := b.setAncestors(parent, lastSettled); err != nil {
+		return nil, err
+	}
+	b.log = log.With(
+		zap.Uint64("height", b.Height()),
+		zap.Stringer("hash", b.Hash()),
+	)
+	return b, nil
+}
+
+var (
+	errParentHashMismatch = errors.New("block-parent hash mismatch")
+	errHashMismatch       = errors.New("block hash mismatch")
+)
+
+func (b *Block) setAncestors(parent, lastSettled *Block) error {
+	if parent != nil {
+		if got, want := parent.Hash(), b.ParentHash(); got != want {
+			return fmt.Errorf("%w: constructing Block with parent hash %v; expecting %v", errParentHashMismatch, got, want)
+		}
+	}
+	b.ancestry.Store(&ancestry{
+		parent:      parent,
+		lastSettled: lastSettled,
+	})
+	return nil
+}
+
+// CopyAncestorsFrom populates the [Block.ParentBlock] and [Block.LastSettled]
+// values, typically only required during database recovery. The source block
+// MUST have the same hash as b.
+//
+// Although the individual ancestral blocks are shallow copied, calling
+// [Block.MarkSettled] on either the source or destination will NOT clear the
+// pointers of the other.
+func (b *Block) CopyAncestorsFrom(c *Block) error {
+	if from, to := c.Hash(), b.Hash(); from != to {
+		return fmt.Errorf("%w: copying internals from block %#x to %#x", errHashMismatch, from, to)
+	}
+	a := c.ancestry.Load()
+	return b.setAncestors(a.parent, a.lastSettled)
+}

blocks/block_test.go

@@ -0,0 +1,110 @@
+// Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package blocks
+
+import (
+	"math/big"
+	"testing"
+
+	"github.com/ava-labs/avalanchego/utils/logging"
+	"github.com/ava-labs/libevm/core/types"
+	"github.com/google/go-cmp/cmp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ava-labs/strevm/saetest"
+)
+
+func newEthBlock(num, time uint64, parent *types.Block) *types.Block {
+	hdr := &types.Header{
+		Number: new(big.Int).SetUint64(num),
+		Time:   time,
+	}
+	if parent != nil {
+		hdr.ParentHash = parent.Hash()
+	}
+	return types.NewBlockWithHeader(hdr)
+}
+
+func newBlock(tb testing.TB, eth *types.Block, parent, lastSettled *Block) *Block {
+	tb.Helper()
+	b, err := New(eth, parent, lastSettled, saetest.NewTBLogger(tb, logging.Warn))
+	require.NoError(tb, err, "New()")
+	return b
+}
+
+func newChain(tb testing.TB, startHeight, total uint64, lastSettledAtHeight map[uint64]uint64) []*Block {
+	tb.Helper()
+
+	var (
+		ethParent *types.Block
+		parent    *Block
+		blocks    []*Block
+	)
+	byNum := make(map[uint64]*Block)
+
+	for i := range total {
+		n := startHeight + i
+
+		var (
+			settle      *Block
+			synchronous bool
+		)
+		if s, ok := lastSettledAtHeight[n]; ok {
+			if s == n {
+				require.Zero(tb, s, "Only genesis block is self-settling")
+				synchronous = true
+			} else {
+				require.Less(tb, s, n, "Last-settled height MUST be <= current height")
+				settle = byNum[s]
+			}
+		}
+
+		b := newBlock(tb, newEthBlock(n, n /*time*/, ethParent), parent, settle)
+		byNum[n] = b
+		blocks = append(blocks, b)
+		if synchronous {
+			require.NoError(tb, b.MarkSynchronous(), "MarkSynchronous()")
+		}
+
+		parent = byNum[n]
+		ethParent = parent.EthBlock()
+	}
+
+	return blocks
+}
+
+func TestSetAncestors(t *testing.T) {
+	parent := newBlock(t, newEthBlock(5, 5, nil), nil, nil)
+	lastSettled := newBlock(t, newEthBlock(3, 0, nil), nil, nil)
+	child := newEthBlock(6, 6, parent.EthBlock())
+
+	t.Run("incorrect_parent", func(t *testing.T) {
+		// Note that the arguments to [New] are inverted.
+		_, err := New(child, lastSettled, parent, logging.NoLog{})
+		require.ErrorIs(t, err, errParentHashMismatch, "New() with inverted parent and last-settled blocks")
+	})
+
+	source := newBlock(t, child, parent, lastSettled)
+	dest := newBlock(t, child, nil, nil)
+
+	t.Run("destination_before_copy", func(t *testing.T) {
+		assert.Nilf(t, dest.ParentBlock(), "%T.ParentBlock()", dest)
+		assert.Nilf(t, dest.LastSettled(), "%T.LastSettled()", dest)
+	})
+	if t.Failed() {
+		t.FailNow()
+	}
+
+	require.NoError(t, dest.CopyAncestorsFrom(source), "CopyAncestorsFrom()")
+	if diff := cmp.Diff(source, dest, CmpOpt()); diff != "" {
+		t.Errorf("After %T.CopyAncestorsFrom(); diff (-want +got):\n%s", dest, diff)
+	}
+
+	t.Run("incompatible_destination_block", func(t *testing.T) {
+		ethB := newEthBlock(dest.Height()+1 /*mismatch*/, dest.BuildTime(), parent.EthBlock())
+		dest := newBlock(t, ethB, nil, nil)
+		require.ErrorIs(t, dest.CopyAncestorsFrom(source), errHashMismatch)
+	})
+}

blocks/cmpopt.go

@@ -0,0 +1,50 @@
+// Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+//go:build !prod && !nocmpopts
+
+package blocks
+
+import (
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/ava-labs/strevm/cmputils"
+	"github.com/ava-labs/strevm/saetest"
+)
+
+// CmpOpt returns a configuration for [cmp.Diff] to compare [Block] instances in
+// tests.
+func CmpOpt() cmp.Option {
+	return cmp.Comparer((*Block).equalForTests)
+}
+
+func (b *Block) equalForTests(c *Block) bool {
+	fn := cmputils.WithNilCheck(func(b, c *Block) bool {
+		return true &&
+			b.Hash() == c.Hash() &&
+			b.ancestry.Load().equalForTests(c.ancestry.Load()) &&
+			b.execution.Load().equalForTests(c.execution.Load())
+	})
+	return fn(b, c)
+}
+
+func (a *ancestry) equalForTests(b *ancestry) bool {
+	fn := cmputils.WithNilCheck(func(a, b *ancestry) bool {
+		return true &&
+			a.parent.equalForTests(b.parent) &&
+			a.lastSettled.equalForTests(b.lastSettled)
+	})
+	return fn(a, b)
+}
+
+func (e *executionResults) equalForTests(f *executionResults) bool {
+	fn := cmputils.WithNilCheck(func(e, f *executionResults) bool {
+		return true &&
+			e.byGas.Rate() == f.byGas.Rate() &&
+			e.byGas.Compare(f.byGas.Time) == 0 && // N.B. Compare is only valid if rates are equal
+			e.receiptRoot == f.receiptRoot &&
+			saetest.MerkleRootsEqual(e.receipts, f.receipts) &&
+			e.stateRootPost == f.stateRootPost
+	})
+	return fn(e, f)
+}