Simplex Block Builder Component (#4159)

Author: samliok

go.mod

@@ -88,7 +88,7 @@ require (
 	github.com/Microsoft/go-winio v0.6.1 // indirect
 	github.com/VictoriaMetrics/fastcache v1.12.1 // indirect
 	github.com/ava-labs/firewood-go-ethhash/ffi v0.0.12 // indirect
-	github.com/ava-labs/simplex v0.0.0-20250819180907-c9b5ae6aad19
+	github.com/ava-labs/simplex v0.0.0-20250919142550-9cdfff10fd19
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bits-and-blooms/bitset v1.10.0 // indirect
 	github.com/btcsuite/btcd/btcec/v2 v2.3.2 // indirect

go.sum

@@ -78,8 +78,8 @@ github.com/ava-labs/ledger-avalanche/go v0.0.0-20241009183145-e6f90a8a1a60 h1:EL
 github.com/ava-labs/ledger-avalanche/go v0.0.0-20241009183145-e6f90a8a1a60/go.mod h1:/7qKobTfbzBu7eSTVaXMTr56yTYk4j2Px6/8G+idxHo=
 github.com/ava-labs/libevm v1.13.14-0.3.0.rc.6 h1:tyM659nDOknwTeU4A0fUVsGNIU7k0v738wYN92nqs/Y=
 github.com/ava-labs/libevm v1.13.14-0.3.0.rc.6/go.mod h1:zP/DOcABRWargBmUWv1jXplyWNcfmBy9cxr0lw3LW3g=
-github.com/ava-labs/simplex v0.0.0-20250819180907-c9b5ae6aad19 h1:dtsx6DJw6wWkrMwDIcSUVJ9lXMeckgI5oZ7fJbAi23c=
-github.com/ava-labs/simplex v0.0.0-20250819180907-c9b5ae6aad19/go.mod h1:GVzumIo3zR23/qGRN2AdnVkIPHcKMq/D89EGWZfMGQ0=
+github.com/ava-labs/simplex v0.0.0-20250919142550-9cdfff10fd19 h1:S6oFasZsplNmw8B2S8cMJQMa62nT5ZKGzZRdCpd+5qQ=
+github.com/ava-labs/simplex v0.0.0-20250919142550-9cdfff10fd19/go.mod h1:GVzumIo3zR23/qGRN2AdnVkIPHcKMq/D89EGWZfMGQ0=
 github.com/aymerick/raymond v2.0.3-0.20180322193309-b565731e1464+incompatible/go.mod h1:osfaiScAUVup+UC9Nfq76eWqDhXlp+4UYaA8uhTBO6g=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=

simplex/block.go

@@ -41,6 +41,20 @@ type Block struct {
 	blockTracker *blockTracker
 }
 
+func newBlock(metadata simplex.ProtocolMetadata, vmBlock snowman.Block, blockTracker *blockTracker) (*Block, error) {
+	block := &Block{
+		metadata:     metadata,
+		vmBlock:      vmBlock,
+		blockTracker: blockTracker,
+	}
+	bytes, err := block.Bytes()
+	if err != nil {
+		return nil, fmt.Errorf("failed to serialize block: %w", err)
+	}
+	block.digest = computeDigest(bytes)
+	return block, nil
+}
+
 // CanotoSimplexBlock is the Canoto representation of a block
 type canotoSimplexBlock struct {
 	Metadata   []byte `canoto:"bytes,1"`

simplex/block_builder.go

@@ -0,0 +1,98 @@
+// Copyright (C) 2019-2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package simplex
+
+import (
+	"context"
+	"time"
+
+	"github.com/ava-labs/simplex"
+	"go.uber.org/zap"
+
+	"github.com/ava-labs/avalanchego/snow/engine/common"
+	"github.com/ava-labs/avalanchego/snow/engine/snowman/block"
+	"github.com/ava-labs/avalanchego/utils/logging"
+)
+
+var _ simplex.BlockBuilder = (*BlockBuilder)(nil)
+
+type BlockBuilder struct {
+	log          logging.Logger
+	vm           block.ChainVM
+	blockTracker *blockTracker
+}
+
+const (
+	maxBackoff  = 5 * time.Second
+	initBackoff = 10 * time.Millisecond
+)
+
+// BuildBlock continuously tries to build a block until the context is cancelled. If there are no blocks to be built, it will wait for an event from the VM.
+// It returns false if the context was cancelled, otherwise it returns the built block and true.
+func (b *BlockBuilder) BuildBlock(ctx context.Context, metadata simplex.ProtocolMetadata) (simplex.VerifiedBlock, bool) {
+	for curWait := initBackoff; ; curWait = backoff(ctx, curWait) {
+		if ctx.Err() != nil {
+			b.log.Debug("Context cancelled, stopping block building", zap.Error(ctx.Err()))
+			return nil, false
+		}
+
+		err := b.waitForPendingBlock(ctx)
+		if err != nil {
+			b.log.Debug("Error waiting for incoming block", zap.Error(err))
+			continue
+		}
+		vmBlock, err := b.vm.BuildBlock(ctx)
+		if err != nil {
+			b.log.Info("Error building block", zap.Error(err))
+			continue
+		}
+		simplexBlock, err := newBlock(metadata, vmBlock, b.blockTracker)
+		if err != nil {
+			b.log.Error("Error creating simplex block from built block", zap.Error(err))
+			return nil, false
+		}
+		curWait = initBackoff // Reset backoff after a successful block build
+		verifiedBlock, err := simplexBlock.Verify(ctx)
+		if err != nil {
+			b.log.Warn("Error verifying block we built ourselves", zap.Error(err))
+			continue
+		}
+
+		return verifiedBlock, true
+	}
+}
+
+// WaitForPendingBlock blocks until a new block is ready to be built from the VM, or until the
+// context is cancelled.
+func (b *BlockBuilder) WaitForPendingBlock(ctx context.Context) {
+	err := b.waitForPendingBlock(ctx)
+	if err != nil {
+		b.log.Debug("Error waiting for incoming block", zap.Error(err))
+	}
+}
+
+func (b *BlockBuilder) waitForPendingBlock(ctx context.Context) error {
+	for curBackoff := initBackoff; ; curBackoff = backoff(ctx, curBackoff) {
+		msg, err := b.vm.WaitForEvent(ctx)
+		if err != nil {
+			return err
+		}
+		if msg == common.PendingTxs {
+			return nil
+		}
+		b.log.Warn("Received unexpected message", zap.Stringer("message", msg))
+	}
+}
+
+// backoff waits for `backoff` duration before returning the next backoff duration.
+// It doubles the backoff duration each time it is called, up to a maximum of `maxBackoff`.
+func backoff(ctx context.Context, backoff time.Duration) time.Duration {
+	select {
+	case <-ctx.Done():
+		return 0
+	case <-time.After(backoff):
+	}
+
+	return min(maxBackoff, 2*backoff) // exponential backoff
+}

simplex/block_builder_test.go

@@ -0,0 +1,217 @@
+// Copyright (C) 2019-2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package simplex
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/ava-labs/simplex"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ava-labs/avalanchego/snow/consensus/snowman"
+	"github.com/ava-labs/avalanchego/snow/engine/common"
+	"github.com/ava-labs/avalanchego/utils/logging"
+)
+
+func TestBlockBuilder(t *testing.T) {
+	ctx := context.Background()
+	genesis := newTestBlock(t, newBlockConfig{})
+	child := newTestBlock(t, newBlockConfig{
+		prev: genesis,
+	})
+
+	tests := []struct {
+		name          string
+		block         snowman.Block
+		shouldBuild   bool
+		expectedBlock simplex.VerifiedBlock
+		vmBlockBuildF func(ctx context.Context) (snowman.Block, error)
+	}{
+		{
+			name:          "build block successfully",
+			block:         child.vmBlock,
+			shouldBuild:   true,
+			expectedBlock: child,
+			vmBlockBuildF: func(_ context.Context) (snowman.Block, error) {
+				return child.vmBlock, nil
+			},
+		},
+		{
+			name:        "fail to build block",
+			block:       nil,
+			shouldBuild: false,
+			vmBlockBuildF: func(_ context.Context) (snowman.Block, error) {
+				return nil, errors.New("failed to build block")
+			},
+		},
+		{
+			name:  "fail to verify block",
+			block: nil,
+			vmBlockBuildF: func(_ context.Context) (snowman.Block, error) {
+				b := newTestBlock(t, newBlockConfig{
+					prev: genesis,
+				})
+				b.vmBlock.(*wrappedBlock).VerifyV = errors.New("verification failed")
+				return b.vmBlock, nil
+			},
+			shouldBuild: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			count := 0
+			vm := newTestVM()
+
+			vm.WaitForEventF = func(_ context.Context) (common.Message, error) {
+				count++
+				return common.PendingTxs, nil
+			}
+			vm.BuildBlockF = tt.vmBlockBuildF
+
+			bb := &BlockBuilder{
+				log:          logging.NoLog{},
+				vm:           vm,
+				blockTracker: genesis.blockTracker,
+			}
+
+			timeoutCtx, cancelCtx := context.WithTimeout(ctx, 100*time.Millisecond)
+			defer cancelCtx()
+
+			block, built := bb.BuildBlock(timeoutCtx, child.BlockHeader().ProtocolMetadata)
+			require.Equal(t, tt.shouldBuild, built)
+			require.Equal(t, tt.expectedBlock, block)
+			if tt.expectedBlock == nil {
+				require.Greater(t, count, 1)
+			}
+		})
+	}
+}
+
+func TestBlockBuilderCancelContext(t *testing.T) {
+	ctx := context.Background()
+	vm := newTestVM()
+	genesis := newTestBlock(t, newBlockConfig{})
+	child := newTestBlock(t, newBlockConfig{
+		prev: genesis,
+	})
+	vm.WaitForEventF = func(ctx context.Context) (common.Message, error) {
+		<-ctx.Done()
+		return 0, ctx.Err()
+	}
+
+	bb := &BlockBuilder{
+		log:          logging.NoLog{},
+		vm:           vm,
+		blockTracker: genesis.blockTracker,
+	}
+
+	timeoutCtx, cancelCtx := context.WithTimeout(ctx, 100*time.Millisecond)
+	defer cancelCtx()
+
+	_, built := bb.BuildBlock(timeoutCtx, child.BlockHeader().ProtocolMetadata)
+	require.False(t, built, "Block should not be built when context is cancelled")
+}
+
+func TestWaitForPendingBlock(t *testing.T) {
+	ctx := context.Background()
+	vm := newTestVM()
+	genesis := newTestBlock(t, newBlockConfig{})
+	count := 0
+	vm.WaitForEventF = func(_ context.Context) (common.Message, error) {
+		if count == 0 {
+			count++
+			return common.StateSyncDone, nil
+		}
+		return common.PendingTxs, nil
+	}
+
+	bb := &BlockBuilder{
+		log:          logging.NoLog{},
+		vm:           vm,
+		blockTracker: genesis.blockTracker,
+	}
+
+	bb.WaitForPendingBlock(ctx)
+	require.Equal(t, 1, count)
+}
+
+func TestBlockBuildingExponentialBackoff(t *testing.T) {
+	ctx := context.Background()
+	vm := newTestVM()
+	genesis := newTestBlock(t, newBlockConfig{})
+	child := newTestBlock(t, newBlockConfig{
+		prev: genesis,
+	})
+	const (
+		failedAttempts       = 7
+		minimumExpectedDelay = initBackoff * (1<<failedAttempts - 1)
+	)
+
+	vm.WaitForEventF = func(_ context.Context) (common.Message, error) {
+		return common.PendingTxs, nil
+	}
+
+	count := 0
+	vm.BuildBlockF = func(_ context.Context) (snowman.Block, error) {
+		if count < failedAttempts {
+			count++
+			return nil, errors.New("failed to build block")
+		}
+
+		// on the 8th try, return the block successfully
+		return child.vmBlock, nil
+	}
+
+	bb := &BlockBuilder{
+		log:          logging.NoLog{},
+		vm:           vm,
+		blockTracker: genesis.blockTracker,
+	}
+
+	start := time.Now()
+	block, built := bb.BuildBlock(ctx, child.BlockHeader().ProtocolMetadata)
+	endTime := time.Since(start)
+
+	require.True(t, built)
+	require.Equal(t, child.BlockHeader(), block.BlockHeader())
+
+	// 10, 20, 40, 80, 160, 320, 640 = 1270ms
+	require.GreaterOrEqual(t, endTime, minimumExpectedDelay)
+}
+
+func TestWaitForPendingBlockBackoff(t *testing.T) {
+	ctx := context.Background()
+	vm := newTestVM()
+	const (
+		failedAttempts       = 7
+		minimumExpectedDelay = initBackoff * (1<<failedAttempts - 1)
+	)
+
+	count := 0
+	vm.WaitForEventF = func(_ context.Context) (common.Message, error) {
+		if count < failedAttempts {
+			count++
+			return common.StateSyncDone, nil
+		}
+
+		return common.PendingTxs, nil
+	}
+
+	bb := &BlockBuilder{
+		log:          logging.NoLog{},
+		vm:           vm,
+		blockTracker: nil,
+	}
+
+	start := time.Now()
+	bb.WaitForPendingBlock(ctx)
+	endTime := time.Since(start)
+
+	// 10, 20, 40, 80, 160, 320, 640 = 1270ms
+	require.GreaterOrEqual(t, endTime, minimumExpectedDelay)
+}