services: add statefetcher service for NeoFS-based state sync

Close #3793

Signed-off-by: Ekaterina Pavlova <[email protected]>

Author: AliceInHunterland

cli/util/upload_state.go

@@ -64,39 +64,39 @@ func uploadState(ctx *cli.Context) error {
 	if chain.GetConfig().Ledger.KeepOnlyLatestState || chain.GetConfig().Ledger.RemoveUntraceableBlocks {
 		return cli.Exit("only full-state node is supported: disable KeepOnlyLatestState and RemoveUntraceableBlocks", 1)
 	}
-	syncInterval := cfg.ProtocolConfiguration.StateSyncInterval
-	if syncInterval == 0 {
-		syncInterval = core.DefaultStateSyncInterval
+	syncInterval := cfg.ApplicationConfiguration.NeoFSStateFetcher.StateInterval
+	if syncInterval <= 0 {
+		syncInterval = uint32(neofs.DefaultStateInterval)
 	}
 
 	containerID, err := getContainer(ctx, p, strconv.Itoa(int(chain.GetConfig().Magic)), maxRetries, debug)
 	if err != nil {
 		return cli.Exit(err, 1)
 	}
 
-	stateObjCount, err := searchStateIndex(ctx, p, containerID, acc.PrivateKey(), attr, syncInterval, maxRetries, debug)
+	stateObjCount, err := searchStateIndex(ctx, p, containerID, acc.PrivateKey(), attr, int(syncInterval), maxRetries, debug)
 	if err != nil {
 		return cli.Exit(fmt.Sprintf("failed searching existing states: %v", err), 1)
 	}
 	stateModule := chain.GetStateModule()
-	currentHeight := int(stateModule.CurrentLocalHeight())
+	currentHeight := stateModule.CurrentLocalHeight()
 	currentStateIndex := currentHeight / syncInterval
 	if currentStateIndex < stateObjCount {
 		log.Info("no new states to upload",
-			zap.Int("number of uploaded state objects", stateObjCount),
-			zap.Int("latest state is uploaded for block", (stateObjCount-1)*syncInterval),
-			zap.Int("current height", currentHeight),
-			zap.Int("StateSyncInterval", syncInterval))
+			zap.Uint32("number of uploaded state objects", stateObjCount),
+			zap.Uint32("latest state is uploaded for block", (stateObjCount-1)*syncInterval),
+			zap.Uint32("current height", currentHeight),
+			zap.Uint32("StateSyncInterval", syncInterval))
 		return nil
 	}
 	log.Info("starting uploading",
-		zap.Int("number of uploaded state objects", stateObjCount),
-		zap.Int("next state to upload for block", stateObjCount*syncInterval),
-		zap.Int("current height", currentHeight),
-		zap.Int("StateSyncInterval", syncInterval),
-		zap.Int("number of states to upload", currentStateIndex-stateObjCount))
+		zap.Uint32("number of uploaded state objects", stateObjCount),
+		zap.Uint32("next state to upload for block", stateObjCount*syncInterval),
+		zap.Uint32("current height", currentHeight),
+		zap.Uint32("StateSyncInterval", syncInterval),
+		zap.Uint32("number of states to upload", currentStateIndex-stateObjCount))
 	for state := stateObjCount; state <= currentStateIndex; state++ {
-		height := uint32(state * syncInterval)
+		height := state * syncInterval
 		stateRoot, err := stateModule.GetStateRoot(height)
 		if err != nil {
 			return cli.Exit(fmt.Sprintf("failed to get state root for height %d: %v", height, err), 1)
@@ -113,7 +113,7 @@ func uploadState(ctx *cli.Context) error {
 				*object.NewAttribute(attr, strconv.Itoa(int(height))),
 				*object.NewAttribute("Timestamp", strconv.FormatInt(time.Now().Unix(), 10)),
 				*object.NewAttribute("StateRoot", stateRoot.Root.StringLE()),
-				*object.NewAttribute("StateSyncInterval", strconv.Itoa(syncInterval)),
+				*object.NewAttribute("StateSyncInterval", strconv.Itoa(int(syncInterval))),
 				*object.NewAttribute("BlockTime", strconv.FormatUint(h.Timestamp, 10)),
 			}
 		)
@@ -157,11 +157,11 @@ func uploadState(ctx *cli.Context) error {
 
 func searchStateIndex(ctx *cli.Context, p neofs.PoolWrapper, containerID cid.ID, privKeys *keys.PrivateKey,
 	attributeKey string, syncInterval int, maxRetries uint, debug bool,
-) (int, error) {
+) (uint32, error) {
 	var (
 		doneCh   = make(chan struct{})
 		errCh    = make(chan error)
-		objCount = 0
+		objCount = uint32(0)
 	)
 
 	go func() {

docs/neofs-blockstorage.md

@@ -26,6 +26,29 @@ following attributes:
  - the number of OIDs included into index file (`IndexSize:128000`)
  - second-precision index file uploading timestamp (`Timestamp:1627894840`)
 
+### State storage schema
+
+A single NeoFS container is used to store state objects. Each container
+has network magic attribute (`Magic:56753`). Each state is stored in a binary
+form as a separate object with a unique OID and a set of attributes:
+- state object identifier with state index value (`State:1`)
+- block hash in the LE form (`StateSyncInterval:5412a781caf278c0736556c0e544c7cfdbb6e3c62ae221ef53646be89364566b`)
+- previous block hash in the LE form (`StateRoot:3654a054d82a8178c7dfacecc2c57282e23468a42ee407f14506368afe22d929`)
+- millisecond-precision block creation timestamp (`BlockTime:1627894840919`)
+- second-precision block uploading timestamp (`Timestamp:1627894840`)
+
+The binary form of the state object contains:
+
+```
+1 byte: Version (0)
+4 bytes: Network magic (uint32)
+4 bytes: Block height (uint32)
+32 bytes: State root (Uint256)
+Variable-length sequence of contract storage key-value pairs, each encoded as:
+    Variable-length key (varbytes)
+    Variable-length value (varbytes)
+```
+
 ### NeoFS BlockFetcher
 
 NeoFS BlockFetcher service is designed as an alternative to P2P synchronisation
@@ -103,6 +126,35 @@ supported yet by this command. Please, add a comment to the
 [#3744](https://github.com/nspcc-dev/neo-go/issues/3744) issue if you need this
 functionality.
 
+### NeoFS StateFetcher
+
+NeoFS StateFetcher service enables state synchronization for non-archival nodes
+by fetching contract storage key-value pairs from a trusted NeoFS container. 
+It serves as an alternative to P2P-based MPT node synchronization, integrating 
+with the `statesync` module. If storage-based synchronization fails to complete
+(e.g., due to an incorrect state root or insufficient data), the `statesync` 
+module falls back to requesting MPT nodes via P2P to ensure synchronization.
+
+#### Operation flow
+
+1. **State Object Search**:
+   Searches the NeoFS container for objects with the configured `StateAttribute`
+   (e.g., `State`), filtering by block height aligned with `StateInterval`
+   (e.g., heights 0, 40000, 80000).
+2. **Storage Data Fetching**:
+   Fetches contract storage key-value pairs from the identified state object.
+3. **State Synchronization**:
+   Passes key-value pairs to the `statesync` module, along with the synchronization
+   height and expected state root. The `statesync` module builds a local MPT trie,
+   flushing batches of up to 1000 pairs to storage. If the trie’s state root matches
+   the expected root at height P, synchronization completes, and an atomic state 
+   jump occurs. If synchronization fails (e.g., wrong state root or incomplete data),
+   `statesync` requests MPT nodes via P2P to complete the process.
+
+Once state object available in the NeoFS container are processed, the service
+shuts down automatically.
+
+
 ### NeoFS state uploading command
 The `util upload-state` command is used to start a node, traverse the MPT over the 
 smart contract storage, and upload MPT nodes to a NeoFS container at every 

docs/node-configuration.md

@@ -24,6 +24,7 @@ node-related settings described in the table below.
 | LogPath | `string` | "", so only console logging | File path where to store node logs. |
 | LogTimestamp | `bool` | Defined by TTY probe on stdout channel.  | Defines whether to enable timestamp logging. If not set, then timestamp logging enabled iff the program is running in TTY (but this behaviour may be overriden by `--force-timestamp-logs` CLI flag if specified). Note that this option, if combined with `LogEncoding: "json"`, can't completely disable timestamp logging. |
 | NeoFSBlockFetcher | [NeoFS BlockFetcher Configuration](#NeoFS-BlockFetcher-Configuration) | | NeoFS BlockFetcher module configuration. See the [NeoFS BlockFetcher Configuration](#NeoFS-BlockFetcher-Configuration) section for details. |
+| NeoFSStateFetcher | [NeoFS StateFetcher Configuration](#NeoFS-StateFetcher-Configuration) | | NeoFS StateFetcher module configuration. See the [NeoFS StateFetcher Configuration](#NeoFS-StateFetcher-Configuration) section for details. |
 | Oracle | [Oracle Configuration](#Oracle-Configuration) | | Oracle module configuration. See the [Oracle Configuration](#Oracle-Configuration) section for details. |
 | P2P | [P2P Configuration](#P2P-Configuration) | | Configuration values for P2P network interaction. See the [P2P Configuration](#P2P-Configuration) section for details. |
 | P2PNotary | [P2P Notary Configuration](#P2P-Notary-Configuration) | | P2P Notary module configuration. See the [P2P Notary Configuration](#P2P-Notary-Configuration) section for details. |
@@ -216,6 +217,44 @@ where:
   setting depends on the NeoFS block storage configuration and is applicable only if
   `SkipIndexFilesSearch` is set to `false`. It's set to 128000 by default.
 
+### NeoFS StateFetcher Configuration
+
+`NeoFSStateFetcher` configuration section contains settings for NeoFS
+StateFetcher module and has the following structure:
+```
+  NeoFSStateFetcher:
+    Enabled: true
+    UnlockWallet:
+      Path: "./wallet.json"
+      Password: "pass"
+    Addresses:
+      - st1.storage.fs.neo.org:8080
+      - st2.storage.fs.neo.org:8080
+      - st3.storage.fs.neo.org:8080
+      - st4.storage.fs.neo.org:8080
+    Timeout: 10m
+    ContainerID: "7a1cn9LNmAcHjESKWxRGG7RSZ55YHJF6z2xDLTCuTZ6c"
+    StateAttribute: "Block"
+    StateInterval: 40000
+```
+where:
+- `Enabled` enables NeoFS StateFetcher module.
+- `UnlockWallet` contains wallet settings to retrieve account to sign requests to
+  NeoFS. Without this setting, the module will use randomly generated private key.
+  For configuration details see [Unlock Wallet Configuration](#Unlock-Wallet-Configuration)
+- `Addresses` is a list of NeoFS storage nodes addresses. This parameter is required.
+- `Timeout` is a timeout for a single request to NeoFS storage node (10 minutes by
+  default).
+- `ContainerID` is a container ID to fetch blocks from. This parameter is required.
+- `StateAttribute` is an attribute name of NeoFS object that contains state
+  data. It's set to `State` by default.
+- `StateInterval` specifies the block height interval between consecutive state 
+  objects in the NeoFS container. By default, it's set to 40000.
+
+If `NeoFSStateFetcher` section is not specified and `NeoFSStateSyncExtensions` is
+`true`, then [NeoFS StateFetcher Configuration](#NeoFS-StateFetcher-Configuration)
+module configuration will be used.
+
 ### Metrics Services Configuration
 
 Metrics services configuration describes options for metrics services (pprof,
@@ -419,6 +458,7 @@ protocol-related settings described in the table below.
 | P2PNotaryRequestPayloadPoolSize | `int` | `1000` | Size of the node's P2P Notary request payloads memory pool where P2P Notary requests are stored before main or fallback transaction is completed and added to the chain.<br>This option is valid only if `P2PSigExtensions` are enabled. | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
 | P2PSigExtensions | `bool` | `false` | Enables following additional Notary service related logic:<br>• Transaction attribute `NotaryAssisted`<br>• Network payload of the `P2PNotaryRequest` type<br>• Native `Notary` contract<br>• Notary node module | Not supported by the C# node, thus may affect heterogeneous networks functionality. |
 | P2PStateExchangeExtensions | `bool` | `false` | Enables the following P2P MPT state data exchange logic: <br>• `StateSyncInterval` protocol setting <br>• P2P commands `GetMPTDataCMD` and `MPTDataCMD` | Not supported by the C# node, thus may affect heterogeneous networks functionality. Can be supported either on MPT-complete node (`KeepOnlyLatestState`=`false`) or on light GC-enabled node (`RemoveUntraceableBlocks=true`) in which case `KeepOnlyLatestState` setting doesn't change the behavior, an appropriate set of MPTs is always stored (see `RemoveUntraceableBlocks`). |
+| NeoFSStateSyncExtensions | `bool` | `false` | Enables the NeoFS state data exchange | Not supported by the C# node, thus may affect heterogeneous networks functionality. Can be supported either on MPT-complete node (`KeepOnlyLatestState`=`false`) or on light GC-enabled node (`RemoveUntraceableBlocks=true`) in which case `KeepOnlyLatestState` setting doesn't change the behavior, an appropriate set of MPTs is always stored (see `RemoveUntraceableBlocks`). |
 | ReservedAttributes | `bool` | `false` | Allows to have reserved attributes range for experimental or private purposes. |
 | SeedList | `[]string` | [] | List of initial nodes addresses used to establish connectivity. |
 | StandbyCommittee | `[]string` | [] | List of public keys of standby committee validators are chosen from. | The list of keys is not required to be sorted, but it must be exactly the same within the configuration files of all the nodes in the network. |

internal/fakechain/fakechain.go

@@ -428,6 +428,11 @@ func (s *FakeStateSync) AddMPTNodes(nodes [][]byte) error {
 	panic("TODO")
 }
 
+// AddContractStorageData implements the StateSync interface.
+func (s *FakeStateSync) AddContractStorageData(key string, value []byte, syncHeight uint32, expectedRoot util.Uint256) error {
+	panic("TODO")
+}
+
 // BlockHeight implements the StateSync interface.
 func (s *FakeStateSync) BlockHeight() uint32 {
 	return 0
@@ -460,6 +465,11 @@ func (s *FakeStateSync) NeedMPTNodes() bool {
 	panic("TODO")
 }
 
+// NeedContractStorageData implements the StateSync interface.
+func (s *FakeStateSync) NeedContractStorageData() bool {
+	panic("TODO")
+}
+
 // Traverse implements the StateSync interface.
 func (s *FakeStateSync) Traverse(root util.Uint256, process func(node mpt.Node, nodeBytes []byte) bool) error {
 	if s.TraverseFunc != nil {

pkg/config/application_config.go

@@ -29,6 +29,7 @@ type ApplicationConfiguration struct {
 	P2PNotary         P2PNotary           `yaml:"P2PNotary"`
 	StateRoot         StateRoot           `yaml:"StateRoot"`
 	NeoFSBlockFetcher NeoFSBlockFetcher   `yaml:"NeoFSBlockFetcher"`
+	NeoFSStateFetcher NeoFSStateFetcher   `yaml:"NeoFSStateFetcher"`
 }
 
 // EqualsButServices returns true when the o is the same as a except for services
@@ -149,6 +150,13 @@ func (a *ApplicationConfiguration) Validate() error {
 	if err := a.NeoFSBlockFetcher.Validate(); err != nil {
 		return fmt.Errorf("invalid NeoFSBlockFetcher config: %w", err)
 	}
+	// if NeoFSService configuration is omitted the NeoFSBlockFetcher.NeoFSService will be used.
+	if a.NeoFSStateFetcher.NeoFSService.Enabled && a.NeoFSStateFetcher.NeoFSService.ContainerID == "" {
+		a.NeoFSStateFetcher.NeoFSService = a.NeoFSBlockFetcher.NeoFSService
+	}
+	if err := a.NeoFSStateFetcher.Validate(); err != nil {
+		return fmt.Errorf("invalid NeoFSStateFetcher config: %w", err)
+	}
 	if err := a.RPC.Validate(); err != nil {
 		return fmt.Errorf("invalid RPC config: %w", err)
 	}

pkg/config/application_config_test.go

@@ -148,10 +148,11 @@ func TestApplicationConfiguration_Validate(t *testing.T) {
 		{
 			cfg: ApplicationConfiguration{
 				NeoFSBlockFetcher: NeoFSBlockFetcher{
-					InternalService:        InternalService{Enabled: true},
-					Timeout:                time.Second,
-					ContainerID:            validContainerID,
-					Addresses:              []string{"127.0.0.1"},
+					NeoFSService: NeoFSService{
+						InternalService: InternalService{Enabled: true},
+						Timeout:         time.Second,
+						ContainerID:     validContainerID,
+						Addresses:       []string{"127.0.0.1"}},
 					OIDBatchSize:           10,
 					BQueueSize:             20,
 					SkipIndexFilesSearch:   true,
@@ -163,12 +164,13 @@ func TestApplicationConfiguration_Validate(t *testing.T) {
 		{
 			cfg: ApplicationConfiguration{
 				NeoFSBlockFetcher: NeoFSBlockFetcher{
-					InternalService: InternalService{Enabled: true},
-					Timeout:         time.Second,
-					ContainerID:     "",
-					Addresses:       []string{"127.0.0.1"},
-					OIDBatchSize:    10,
-					BQueueSize:      20,
+					NeoFSService: NeoFSService{
+						InternalService: InternalService{Enabled: true},
+						Timeout:         time.Second,
+						ContainerID:     "",
+						Addresses:       []string{"127.0.0.1"}},
+					OIDBatchSize: 10,
+					BQueueSize:   20,
 				},
 			},
 			shouldFail: true,
@@ -177,12 +179,13 @@ func TestApplicationConfiguration_Validate(t *testing.T) {
 		{
 			cfg: ApplicationConfiguration{
 				NeoFSBlockFetcher: NeoFSBlockFetcher{
-					InternalService: InternalService{Enabled: true},
-					Timeout:         time.Second,
-					ContainerID:     invalidContainerID,
-					Addresses:       []string{"127.0.0.1"},
-					OIDBatchSize:    10,
-					BQueueSize:      20,
+					NeoFSService: NeoFSService{
+						InternalService: InternalService{Enabled: true},
+						Timeout:         time.Second,
+						ContainerID:     invalidContainerID,
+						Addresses:       []string{"127.0.0.1"}},
+					OIDBatchSize: 10,
+					BQueueSize:   20,
 				},
 			},
 			shouldFail: true,
@@ -191,12 +194,13 @@ func TestApplicationConfiguration_Validate(t *testing.T) {
 		{
 			cfg: ApplicationConfiguration{
 				NeoFSBlockFetcher: NeoFSBlockFetcher{
-					InternalService: InternalService{Enabled: true},
-					Timeout:         time.Second,
-					ContainerID:     validContainerID,
-					Addresses:       []string{},
-					OIDBatchSize:    10,
-					BQueueSize:      20,
+					NeoFSService: NeoFSService{
+						InternalService: InternalService{Enabled: true},
+						Timeout:         time.Second,
+						ContainerID:     validContainerID,
+						Addresses:       []string{}},
+					OIDBatchSize: 10,
+					BQueueSize:   20,
 				},
 			},
 			shouldFail: true,
@@ -205,12 +209,13 @@ func TestApplicationConfiguration_Validate(t *testing.T) {
 		{
 			cfg: ApplicationConfiguration{
 				NeoFSBlockFetcher: NeoFSBlockFetcher{
-					InternalService: InternalService{Enabled: true},
-					Timeout:         time.Second,
-					ContainerID:     validContainerID,
-					Addresses:       []string{"127.0.0.1"},
-					OIDBatchSize:    10,
-					BQueueSize:      5,
+					NeoFSService: NeoFSService{
+						InternalService: InternalService{Enabled: true},
+						Timeout:         time.Second,
+						ContainerID:     validContainerID,
+						Addresses:       []string{"127.0.0.1"}},
+					OIDBatchSize: 10,
+					BQueueSize:   5,
 				},
 			},
 			shouldFail: true,