add --payloadless flag

Author: zhangchiqing

cmd/execution_builder.go

@@ -48,6 +48,7 @@ import (
 	"github.com/onflow/flow-go/engine/execution/checker"
 	"github.com/onflow/flow-go/engine/execution/computation"
 	"github.com/onflow/flow-go/engine/execution/computation/committer"
+	"github.com/onflow/flow-go/engine/execution/computation/computer"
 	txmetrics "github.com/onflow/flow-go/engine/execution/computation/metrics"
 	"github.com/onflow/flow-go/engine/execution/ingestion"
 	"github.com/onflow/flow-go/engine/execution/ingestion/fetcher"
@@ -64,6 +65,7 @@ import (
 	"github.com/onflow/flow-go/fvm/storage/snapshot"
 	"github.com/onflow/flow-go/fvm/systemcontracts"
 	"github.com/onflow/flow-go/ledger"
+	"github.com/onflow/flow-go/ledger/complete"
 	"github.com/onflow/flow-go/ledger/complete/wal"
 	ledgerfactory "github.com/onflow/flow-go/ledger/factory"
 	modelbootstrap "github.com/onflow/flow-go/model/bootstrap"
@@ -125,12 +127,13 @@ type ExecutionNode struct {
 
 	ingestionUnit *engine.Unit
 
-	collector      *metrics.ExecutionCollector
-	executionState state.ExecutionState
-	followerState  protocol.FollowerState
-	committee      hotstuff.DynamicCommittee
-	ledgerStorage  ledger.Ledger
-	registerStore  *storehouse.RegisterStore
+	collector         *metrics.ExecutionCollector
+	executionState    state.ExecutionState
+	followerState     protocol.FollowerState
+	committee         hotstuff.DynamicCommittee
+	ledgerStorage     ledger.Ledger            // set iff !exeConf.payloadless
+	payloadlessLedger ledger.PayloadlessLedger // set iff exeConf.payloadless
+	registerStore     *storehouse.RegisterStore
 
 	// storage
 	events          storageerr.Events
@@ -626,7 +629,16 @@ func (exeNode *ExecutionNode) LoadProviderEngine(
 			})
 	}
 
-	ledgerViewCommitter := committer.NewLedgerViewCommitter(exeNode.ledgerStorage, node.Tracer)
+	var ledgerViewCommitter computer.ViewCommitter
+	if exeNode.exeConf.payloadless {
+		ledgerViewCommitter = committer.NewPayloadlessLedgerViewCommitter(
+			exeNode.payloadlessLedger,
+			node.Tracer,
+			complete.DefaultPathFinderVersion,
+		)
+	} else {
+		ledgerViewCommitter = committer.NewLedgerViewCommitter(exeNode.ledgerStorage, node.Tracer)
+	}
 	exeNode.exeConf.computationConfig.TokenTrackingEnabled = exeNode.exeConf.tokenTrackingEnabled
 	manager, err := computation.New(
 		node.Logger,
@@ -801,8 +813,21 @@ func (exeNode *ExecutionNode) LoadExecutionState(
 
 	// migrate execution data for last sealed and executed block
 
+	// In full mode, both args are the same *complete.Ledger; in payloadless
+	// mode the first is the payloadless ledger (narrow LedgerStateChecker)
+	// and the snapshot-source slot is nil because storehouse is required.
+	var stateChecker state.LedgerStateChecker
+	var snapshotLedger ledger.Ledger
+	if exeNode.exeConf.payloadless {
+		stateChecker = exeNode.payloadlessLedger
+		snapshotLedger = nil
+	} else {
+		stateChecker = exeNode.ledgerStorage
+		snapshotLedger = exeNode.ledgerStorage
+	}
 	exeNode.executionState = state.NewExecutionState(
-		exeNode.ledgerStorage,
+		stateChecker,
+		snapshotLedger,
 		exeNode.commits,
 		node.Storage.Blocks,
 		node.Storage.Headers,
@@ -916,7 +941,41 @@ func (exeNode *ExecutionNode) LoadExecutionStateLedger(
 	module.ReadyDoneAware,
 	error,
 ) {
-	// Create ledger using factory
+	if exeNode.exeConf.payloadless {
+		// Payloadless mode. ValidateFlags enforces --enable-storehouse,
+		// so the storehouse is the value source for reads.
+		//
+		// The factory call mirrors the full-mode call below: same Config,
+		// same triggerCheckpoint. Today the factory body is a placeholder
+		// (no WAL, no checkpoint load) — see TODOs at
+		// ledgerfactory.NewPayloadlessLedger. When the WAL/checkpoint
+		// pieces land, only the factory body changes; this call site stays
+		// the same.
+		pl, err := ledgerfactory.NewPayloadlessLedger(ledgerfactory.Config{
+			LedgerServiceAddr:     exeNode.exeConf.ledgerServiceAddr,
+			LedgerMaxRequestSize:  exeNode.exeConf.ledgerMaxRequestSize,
+			LedgerMaxResponseSize: exeNode.exeConf.ledgerMaxResponseSize,
+			Triedir:               exeNode.exeConf.triedir,
+			MTrieCacheSize:        exeNode.exeConf.mTrieCacheSize,
+			CheckpointDistance:    exeNode.exeConf.checkpointDistance,
+			CheckpointsToKeep:     exeNode.exeConf.checkpointsToKeep,
+			MetricsRegisterer:     node.MetricsRegisterer,
+			WALMetrics:            exeNode.collector,
+			LedgerMetrics:         exeNode.collector,
+			Logger:                node.Logger,
+		}, exeNode.toTriggerCheckpoint)
+		if err != nil {
+			return nil, fmt.Errorf("could not create payloadless ledger: %w", err)
+		}
+		exeNode.payloadlessLedger = pl
+		// exeNode.ledgerStorage stays nil in payloadless mode; the
+		// LedgerStateChecker slot in state.NewExecutionState receives the
+		// payloadless ledger directly, and the snapshotLedger slot stays
+		// nil because the storehouse is the value source.
+		return pl, nil
+	}
+
+	// Full mode (default): WAL-backed ledger via the factory.
 	ledgerStorage, err := ledgerfactory.NewLedger(ledgerfactory.Config{
 		LedgerServiceAddr:     exeNode.exeConf.ledgerServiceAddr,
 		LedgerMaxRequestSize:  exeNode.exeConf.ledgerMaxRequestSize,
@@ -939,6 +998,7 @@ func (exeNode *ExecutionNode) LoadExecutionStateLedger(
 	return exeNode.ledgerStorage, nil
 }
 
+
 func (exeNode *ExecutionNode) LoadExecutionDataPruner(
 	node *NodeConfig,
 ) (

cmd/execution_config.go

@@ -74,6 +74,7 @@ type ExecutionConfig struct {
 	// file descriptors causing connection failures.
 	onflowOnlyLNs                      bool
 	enableStorehouse                   bool
+	payloadless                        bool
 	enableBackgroundStorehouseIndexing bool
 	backgroundIndexerHeightsPerSecond  uint64
 	enableChecker                      bool
@@ -154,6 +155,9 @@ func (exeConf *ExecutionConfig) SetupFlags(flags *pflag.FlagSet) {
 
 	flags.BoolVar(&exeConf.onflowOnlyLNs, "temp-onflow-only-lns", false, "do not use unless required. forces node to only request collections from onflow collection nodes")
 	flags.BoolVar(&exeConf.enableStorehouse, "enable-storehouse", false, "enable storehouse to store registers on disk, default is false")
+	flags.BoolVar(&exeConf.payloadless, "payloadless", false,
+		"run the execution node with a payloadless ledger that stores only leaf hashes; "+
+			"register values are read from the storehouse during execution. requires --enable-storehouse.")
 	flags.BoolVar(&exeConf.enableBackgroundStorehouseIndexing, "enable-background-storehouse-indexing", false, "enable background indexing of storehouse data while storehouse is disabled to eliminate downtime when enabling it. default: false.")
 	flags.Uint64Var(&exeConf.backgroundIndexerHeightsPerSecond, "background-indexer-heights-per-second", storehouse.DefaultHeightsPerSecond, fmt.Sprintf("rate limit for background indexer in heights per second. 0 means no rate limiting. default: %v", storehouse.DefaultHeightsPerSecond))
 	flags.BoolVar(&exeConf.enableChecker, "enable-checker", true, "enable checker to check the correctness of the execution result, default is true")
@@ -198,5 +202,13 @@ func (exeConf *ExecutionConfig) ValidateFlags() error {
 	if exeConf.enableStorehouse {
 		exeConf.enableBackgroundStorehouseIndexing = false
 	}
+	// Payloadless requires storehouse: the payloadless ledger does not retain
+	// register values; the storehouse is the only available value source for
+	// both proof reconstruction and snapshot reads.
+	if exeConf.payloadless && !exeConf.enableStorehouse {
+		return errors.New("--payloadless requires --enable-storehouse: " +
+			"the payloadless ledger does not store register values; " +
+			"the storehouse must provide them at execution time")
+	}
 	return nil
 }

cmd/util/cmd/rollback-executed-height/cmd/rollback_executed_height_test.go

@@ -67,6 +67,7 @@ func TestReExecuteBlock(t *testing.T) {
 
 		// create execution state module
 		es := state.NewExecutionState(
+			nil,
 			nil,
 			commits,
 			nil,
@@ -229,6 +230,7 @@ func TestReExecuteBlockWithDifferentResult(t *testing.T) {
 
 		// create execution state module
 		es := state.NewExecutionState(
+			nil,
 			nil,
 			commits,
 			nil,

engine/execution/state/state.go

@@ -93,9 +93,18 @@ type ExecutionState interface {
 	GetHighestFinalizedExecuted() (uint64, error)
 }
 
+// LedgerStateChecker is the minimum ledger-side contract the execution state
+// always needs, regardless of register-store mode: a way to check whether a
+// given state commitment exists in the underlying trie. Both ledger.Ledger
+// and ledger.PayloadlessLedger satisfy this interface, which is how the
+// execution state can be backed by either.
+type LedgerStateChecker interface {
+	HasState(state ledger.State) bool
+}
+
 type state struct {
 	tracer             module.Tracer
-	ls                 ledger.Ledger
+	ls                 LedgerStateChecker
 	commits            storage.Commits
 	blocks             storage.Blocks
 	headers            storage.Headers
@@ -109,15 +118,22 @@ type state struct {
 	getLatestFinalized func() (uint64, error)
 	lockManager        lockctx.Manager
 
-	registerStore execution.RegisterStore
-	// when it is true, registers are stored in both register store and ledger
-	// and register queries will send to the register store instead of ledger
+	// snapshotLedger and registerStore are needed by the NewStorageSnapshot method,
+	// when enableRegisterStore == false, registerStore is nil, snapshotLedger is used to read register values
+	// when enableRegisterStore == true, 	snapshotLedger is nil, registerStore is used to read register values
+	// note:
+	// in payloadless ledger mode, enableRegisterStore must be true, therefore snapshotLedger is not needed and
+	// registerStore is used to read register values
 	enableRegisterStore bool
+	snapshotLedger      ledger.Ledger
+	registerStore       execution.RegisterStore
 }
 
-// NewExecutionState returns a new execution state access layer for the given ledger storage.
+// NewExecutionState returns a new execution state access layer for the given
+// ledger storage.
 func NewExecutionState(
-	ls ledger.Ledger,
+	ls LedgerStateChecker,
+	snapshotLedger ledger.Ledger,
 	commits storage.Commits,
 	blocks storage.Blocks,
 	headers storage.Headers,
@@ -137,6 +153,7 @@ func NewExecutionState(
 	return &state{
 		tracer:              tracer,
 		ls:                  ls,
+		snapshotLedger:      snapshotLedger,
 		commits:             commits,
 		blocks:              blocks,
 		headers:             headers,
@@ -262,7 +279,7 @@ func (s *state) NewStorageSnapshot(
 	if s.enableRegisterStore {
 		return storehouse.NewBlockEndStateSnapshot(s.registerStore, blockID, height)
 	}
-	return NewLedgerStorageSnapshot(s.ls, commitment)
+	return NewLedgerStorageSnapshot(s.snapshotLedger, commitment)
 }
 
 func (s *state) CreateStorageSnapshot(

engine/execution/state/state_storehouse_test.go

@@ -96,7 +96,7 @@ func prepareStorehouseTest(f func(t *testing.T, es state.ExecutionState, l *ledg
 				}
 
 				es := state.NewExecutionState(
-					ls, stateCommitments, blocks, headers, chunkDataPacks, results, myReceipts, events, serviceEvents, txResults, pebbleimpl.ToDB(pebbleDB),
+					ls, ls, stateCommitments, blocks, headers, chunkDataPacks, results, myReceipts, events, serviceEvents, txResults, pebbleimpl.ToDB(pebbleDB),
 					getLatestFinalized,
 					trace.NewNoopTracer(),
 					rs,

engine/execution/state/state_test.go

@@ -54,7 +54,7 @@ func prepareTest(f func(t *testing.T, es state.ExecutionState, l *ledger.Ledger,
 
 			db := pebbleimpl.ToDB(pebbleDB)
 			es := state.NewExecutionState(
-				ls, stateCommitments, blocks, headers, chunkDataPacks, results, myReceipts, events, serviceEvents, txResults, db, getLatestFinalized, trace.NewNoopTracer(),
+				ls, ls, stateCommitments, blocks, headers, chunkDataPacks, results, myReceipts, events, serviceEvents, txResults, db, getLatestFinalized, trace.NewNoopTracer(),
 				nil,
 				false,
 				lockManager,

engine/testutil/nodes.go

@@ -676,7 +676,7 @@ func ExecutionNode(t *testing.T, hub *stub.Hub, identity bootstrap.NodeInfo, ide
 	}
 
 	execState := executionState.NewExecutionState(
-		ls, commitsStorage, node.Blocks, node.Headers, chunkDataPackStorage, results, myReceipts, eventsStorage, serviceEventsStorage, txResultStorage, db, getLatestFinalized, node.Tracer,
+		ls, ls, commitsStorage, node.Blocks, node.Headers, chunkDataPackStorage, results, myReceipts, eventsStorage, serviceEventsStorage, txResultStorage, db, getLatestFinalized, node.Tracer,
 		// TODO: test with register store
 		registerStore,
 		storehouseEnabled,

ledger/factory/factory.go

@@ -115,3 +115,51 @@ func newLocalLedger(config Config, triggerCheckpoint *atomic.Bool) (ledger.Ledge
 
 	return ledgerStorage, nil
 }
+
+// NewPayloadlessLedger creates a payloadless ledger instance.
+//
+// This is the payloadless-mode counterpart of [NewLedger]. It mirrors that
+// function's signature so call sites in cmd/execution_builder.go can switch
+// between the two without changing how config is plumbed. The argument types
+// are deliberately identical (same Config struct, same triggerCheckpoint).
+//
+// TODO: payloadless WAL is not implemented yet. This factory currently
+// returns an in-memory payloadless ledger that does not persist updates to
+// a WAL. config.Triedir, config.CheckpointDistance, config.CheckpointsToKeep
+// and triggerCheckpoint are accepted for API parity but ignored.
+//
+// TODO: payloadless checkpoint loading is not implemented yet. The factory
+// does not read any checkpoint file at boot, so the trie starts empty on
+// every startup. To make payloadless nodes survive a restart, one of the
+// following must land:
+//
+//	1. A native payloadless checkpoint format with its own writer, reader,
+//	   and bootstrap path.
+//	2. A conversion path that reads the existing full V6 mtrie checkpoint
+//	   (the format LoadBootstrapper copies into triedir) and ingests its
+//	   (path, value) pairs into the payloadless trie at boot. This unblocks
+//	   payloadless boot from existing on-disk state without committing to a
+//	   payloadless checkpoint format.
+//
+// Until one of those is in place, --payloadless mode is suitable for
+// short-lived experimental nodes only; the trie has no state on first boot
+// and loses all state on restart.
+//
+// TODO: remote payloadless ledger client. When config.LedgerServiceAddr is
+// set, this factory should construct a remote.PayloadlessClient (Spec 004).
+// For now config.LedgerServiceAddr is ignored.
+func NewPayloadlessLedger(config Config, triggerCheckpoint *atomic.Bool) (ledger.PayloadlessLedger, error) {
+	_ = triggerCheckpoint // TODO: drive payloadless checkpoint generation once a format exists
+
+	config.Logger.Warn().
+		Str("triedir", config.Triedir).
+		Msg("payloadless ledger has no WAL or checkpoint support yet; " +
+			"trie state will not survive restart and will not be loaded from disk")
+
+	return complete.NewPayloadlessLedger(
+		int(config.MTrieCacheSize),
+		config.LedgerMetrics,
+		config.Logger.With().Str("subcomponent", "ledger").Logger(),
+		complete.DefaultPathFinderVersion,
+	)
+}