Fix stale API state after consensus sync fork-and-swap

Introduce StateDbRef, a thread-safe IStateDatabase wrapper with a
mutable inner reference.  All consumers (REST API, faucet, consensus)
now share the same StateDbRef instance so that when NodeCoordinator
replaces canonical state after a successful sync, every reader
immediately sees the updated accounts and balances.

Previously the API closures captured the original stateDb reference,
which became stale after HandleSyncResponse replaced _stateDb with a
forked copy — causing GET /v1/accounts/{address} to return 404 for
accounts that received funds via synced blocks.

Author: 0xZunia

src/node/Basalt.Node/NodeCoordinator.cs

@@ -27,8 +27,9 @@ public sealed class NodeCoordinator : IAsyncDisposable
     private readonly ChainParameters _chainParams;
     private readonly ChainManager _chainManager;
     private readonly Mempool _mempool;
-    // N-05: Non-readonly to allow fork-and-swap during sync
-    private IStateDatabase _stateDb;
+    // N-05: StateDbRef allows fork-and-swap during sync while keeping the
+    // API layer (which shares this reference) in sync with canonical state.
+    private readonly StateDbRef _stateDb;
     private readonly TransactionValidator _txValidator;
     private readonly WebSocketHandler _wsHandler;
     private readonly ILoggerFactory _loggerFactory;
@@ -116,7 +117,7 @@ public NodeCoordinator(
         ChainParameters chainParams,
         ChainManager chainManager,
         Mempool mempool,
-        IStateDatabase stateDb,
+        StateDbRef stateDb,
         TransactionValidator txValidator,
         WebSocketHandler wsHandler,
         ILoggerFactory loggerFactory,
@@ -1117,10 +1118,11 @@ private void HandleSyncResponse(PeerId sender, SyncResponseMessage response)
             }
         }
 
-        // N-05: Only adopt the forked state if all blocks were applied successfully
+        // N-05: Only adopt the forked state if all blocks were applied successfully.
+        // Swap() updates the shared StateDbRef so the API layer sees the new state.
         if (applied == blocksToApply.Count && applied > 0)
         {
-            _stateDb = forkedState;
+            _stateDb.Swap(forkedState);
             _logger.LogInformation("Synced {Count} blocks, now at #{Height}", applied, _chainManager.LatestBlockNumber);
         }
         else if (applied > 0)

src/node/Basalt.Node/Program.cs

@@ -22,6 +22,7 @@
 
 RocksDbStore? rocksDbStore = null;
 IStateDatabase? stateDb = null;
+StateDbRef? stateDbRef = null;
 try
 {
     var config = NodeConfiguration.FromEnvironment();
@@ -154,6 +155,11 @@
         Log.Information("Genesis block created. Hash: {Hash}", genesisBlock.Hash.ToHexString()[..18] + "...");
     }
 
+    // Wrap the state database in a mutable reference so that all consumers
+    // (API, faucet, consensus) share the same canonical view.  When the
+    // consensus layer swaps state after a sync, the API sees it immediately.
+    stateDbRef = new StateDbRef(stateDb);
+
     // Build the host
     var builder = WebApplication.CreateBuilder(args);
     builder.Host.UseSerilog();
@@ -173,7 +179,7 @@
 
     // Register services
     builder.Services.AddSingleton(chainParams);
-    builder.Services.AddSingleton<IStateDatabase>(stateDb);
+    builder.Services.AddSingleton<IStateDatabase>(stateDbRef);
     builder.Services.AddSingleton(chainManager);
     builder.Services.AddSingleton(mempool);
     builder.Services.AddSingleton(validator);
@@ -183,11 +189,11 @@
 
     // Map REST endpoints (with read-only call support via ManagedContractRuntime)
     var contractRuntime = new ManagedContractRuntime();
-    RestApiEndpoints.MapBasaltEndpoints(app, chainManager, mempool, validator, stateDb, contractRuntime, receiptStore);
+    RestApiEndpoints.MapBasaltEndpoints(app, chainManager, mempool, validator, stateDbRef, contractRuntime, receiptStore);
 
     // Map faucet endpoint
     var faucetLogger = app.Services.GetRequiredService<ILoggerFactory>().CreateLogger("Basalt.Faucet");
-    FaucetEndpoint.MapFaucetEndpoint(app, stateDb, mempool, chainParams, faucetPrivateKey, faucetLogger, chainManager);
+    FaucetEndpoint.MapFaucetEndpoint(app, stateDbRef, mempool, chainParams, faucetPrivateKey, faucetLogger, chainManager);
 
     // Map WebSocket endpoint
     app.UseWebSockets();
@@ -247,7 +253,7 @@
             // StorageMap key: "scr_vk:{schemaIdHex}", hashed to Hash256 via BLAKE3
             var storageKey = "scr_vk:" + schemaId.ToHexString();
             var slot = Basalt.Crypto.Blake3Hasher.Hash(System.Text.Encoding.UTF8.GetBytes(storageKey));
-            var raw = stateDb.GetStorage(schemaRegistryAddress, slot);
+            var raw = stateDbRef.GetStorage(schemaRegistryAddress, slot);
             if (raw == null || raw.Length < 2 || raw[0] != 0x07) // 0x07 = TagString
                 return null;
             var hexVk = System.Text.Encoding.UTF8.GetString(raw.AsSpan(1));
@@ -262,7 +268,7 @@
             zkVerifier);
 
         var coordinator = new NodeCoordinator(
-            config, chainParams, chainManager, mempool, stateDb, validator, wsHandler,
+            config, chainParams, chainManager, mempool, stateDbRef, validator, wsHandler,
             app.Services.GetRequiredService<ILoggerFactory>(),
             blockStore, receiptStore,
             stakingState, slashingEngine,
@@ -305,7 +311,7 @@
         // Single-node block production on a timer (existing behavior)
         var proposer = Address.FromHexString("0x0000000000000000000000000000000000000001");
         var blockProduction = new BlockProductionLoop(
-            chainParams, chainManager, mempool, stateDb, proposer,
+            chainParams, chainManager, mempool, stateDbRef, proposer,
             app.Services.GetRequiredService<ILogger<BlockProductionLoop>>());
 
         // Wire metrics and WebSocket to block production
@@ -341,7 +347,10 @@
 }
 finally
 {
-    if (stateDb is FlatStateDb flatState)
+    // Flush the current canonical state — after sync swaps this may differ
+    // from the original stateDb variable.
+    var canonical = stateDbRef?.Inner ?? stateDb;
+    if (canonical is FlatStateDb flatState)
         flatState.FlushToPersistence();
     rocksDbStore?.Dispose();
     Log.CloseAndFlush();

src/storage/Basalt.Storage/StateDbRef.cs

@@ -0,0 +1,46 @@
+using Basalt.Core;
+
+namespace Basalt.Storage;
+
+/// <summary>
+/// Thread-safe mutable reference to the canonical state database.
+/// All consumers (API, faucet, consensus) share the same <see cref="StateDbRef"/>
+/// instance, so when the consensus layer swaps the underlying state after sync,
+/// every reader immediately sees the new canonical state.
+/// </summary>
+public sealed class StateDbRef : IStateDatabase
+{
+    private volatile IStateDatabase _inner;
+
+    public StateDbRef(IStateDatabase inner)
+    {
+        _inner = inner ?? throw new ArgumentNullException(nameof(inner));
+    }
+
+    /// <summary>
+    /// Atomically replace the underlying state database.
+    /// Called by <c>NodeCoordinator</c> after a successful sync fork-and-swap.
+    /// </summary>
+    public void Swap(IStateDatabase newState)
+    {
+        _inner = newState ?? throw new ArgumentNullException(nameof(newState));
+    }
+
+    /// <summary>The current underlying state database.</summary>
+    public IStateDatabase Inner => _inner;
+
+    // ── IStateDatabase delegation ──────────────────────────────────────
+
+    public AccountState? GetAccount(Address address) => _inner.GetAccount(address);
+    public void SetAccount(Address address, AccountState state) => _inner.SetAccount(address, state);
+    public bool AccountExists(Address address) => _inner.AccountExists(address);
+    public void DeleteAccount(Address address) => _inner.DeleteAccount(address);
+    public Hash256 ComputeStateRoot() => _inner.ComputeStateRoot();
+    public IEnumerable<(Address Address, AccountState State)> GetAllAccounts() => _inner.GetAllAccounts();
+
+    public byte[]? GetStorage(Address contract, Hash256 key) => _inner.GetStorage(contract, key);
+    public void SetStorage(Address contract, Hash256 key, byte[] value) => _inner.SetStorage(contract, key, value);
+    public void DeleteStorage(Address contract, Hash256 key) => _inner.DeleteStorage(contract, key);
+
+    public IStateDatabase Fork() => _inner.Fork();
+}