Serialized storage cache

benchmarks/Neo.Benchmarks/Benchmarks.Cache.cs

@@ -0,0 +1,69 @@
+// Copyright (C) 2015-2025 The Neo Project.
+//
+// Benchmarks.Cache.cs file belongs to the neo project and is free
+// software distributed under the MIT software license, see the
+// accompanying file LICENSE in the main directory of the
+// repository or http://www.opensource.org/licenses/mit-license.php
+// for more details.
+//
+// Redistribution and use in source and binary forms with or without
+// modifications are permitted.
+
+using BenchmarkDotNet.Attributes;
+using Neo.Persistence;
+using Neo.SmartContract;
+using Neo.SmartContract.Native;
+using System.Numerics;
+
+namespace Neo.Benchmark
+{
+    public class Benchmarks_Cache
+    {
+        // 256 KiB
+        readonly MemoryStore _store;
+        readonly StoreCache _snapshot;
+
+        public Benchmarks_Cache()
+        {
+            _store = new MemoryStore();
+            _snapshot = new(_store.GetSnapshot());
+
+            // Ledger.CurrentIndex
+
+            _snapshot.GetAndChange(new KeyBuilder(NativeContract.Ledger.Id, 12), () => new StorageItem(new HashIndexState() { Hash = UInt256.Zero, Index = 2 }));
+
+            // Gas Per block
+
+            _snapshot.GetAndChange(new KeyBuilder(NativeContract.NEO.Id, 29).AddBigEndian(0), () => new StorageItem(0));
+            _snapshot.GetAndChange(new KeyBuilder(NativeContract.NEO.Id, 29).AddBigEndian(1), () => new StorageItem(1));
+            _snapshot.GetAndChange(new KeyBuilder(NativeContract.NEO.Id, 29).AddBigEndian(2), () => new StorageItem(2));
+        }
+
+        [Benchmark]
+        public void WithCache()
+        {
+            for (var x = 0; x < 1_000; x++)
+            {
+                var ret = NativeContract.NEO.GetGasPerBlock(_snapshot);
+                if (ret != 2) throw new Exception("Test error");
+            }
+        }
+
+        [Benchmark]
+        public void WithoutCache()
+        {
+            for (var x = 0; x < 1_000; x++)
+            {
+                var ret = OldCode();
+                if (ret != 2) throw new Exception("Test error");
+            }
+        }
+
+        private BigInteger OldCode()
+        {
+            var end = NativeContract.Ledger.CurrentIndex(_snapshot) + 1;
+            var last = NativeContract.NEO.GetSortedGasRecords(_snapshot, end).First();
+            return last.GasPerBlock;
+        }
+    }
+}

benchmarks/Neo.Benchmarks/Program.cs

@@ -11,12 +11,10 @@
 
 using BenchmarkDotNet.Running;
 using Neo.Benchmark;
-using Neo.Benchmarks.Persistence.Benchmarks;
-using Neo.SmartContract.Benchmark;
 
-// BenchmarkRunner.Run<Benchmarks_PoCs>();
-BenchmarkRunner.Run<Benchmarks_UInt160>();
-BenchmarkRunner.Run<Benchmarks_Hash>();
-BenchmarkRunner.Run<Benchmarks_StorageKey>();
-BenchmarkRunner.Run<Bechmarks_ReadOnlyStoreView>();
-BenchmarkRunner.Run<Bechmarks_LevelDB>();
+BenchmarkRunner.Run<Benchmarks_Cache>();
+//BenchmarkRunner.Run<Benchmarks_UInt160>();
+//BenchmarkRunner.Run<Benchmarks_Hash>();
+//BenchmarkRunner.Run<Benchmarks_StorageKey>();
+//BenchmarkRunner.Run<Bechmarks_ReadOnlyStoreView>();
+//BenchmarkRunner.Run<Bechmarks_LevelDB>();

src/Neo/Neo.csproj

@@ -27,6 +27,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <InternalsVisibleTo Include="Neo.Benchmarks" />
     <InternalsVisibleTo Include="Neo.SmartContract.Testing" />
     <InternalsVisibleTo Include="Neo.SmartContract.TestEngine" />
     <InternalsVisibleTo Include="Neo.Plugins.RpcServer.Tests" />

src/Neo/Persistence/ClonedCache.cs

@@ -20,7 +20,7 @@ class ClonedCache : DataCache
     {
         private readonly DataCache _innerCache;
 
-        public ClonedCache(DataCache innerCache)
+        public ClonedCache(DataCache innerCache) : base(innerCache.SerializedCache)
         {
             _innerCache = innerCache;
         }

src/Neo/Persistence/DataCache.cs

@@ -24,7 +24,7 @@ namespace Neo.Persistence
     /// <summary>
     /// Represents a cache for the underlying storage of the NEO blockchain.
     /// </summary>
-    public abstract class DataCache : IReadOnlyStore
+    public abstract class DataCache : ICacheableReadOnlyStore
     {
         /// <summary>
         /// Represents an entry in the cache.
@@ -47,8 +47,23 @@ public class Trackable(StorageKey key, StorageItem item, TrackState state)
             public TrackState State { get; set; } = state;
         }
 
-        private readonly Dictionary<StorageKey, Trackable> _dictionary = new();
-        private readonly HashSet<StorageKey> _changeSet = new();
+        private readonly Dictionary<StorageKey, Trackable> _dictionary = [];
+        private readonly HashSet<StorageKey> _changeSet = [];
+        private readonly SerializedCache _serializedCacheChanges = new();
+
+        /// <summary>
+        /// Serialized cache
+        /// </summary>
+        public SerializedCache SerializedCache { get; }
+
+        /// <summary>
+        /// Constructor
+        /// </summary>
+        /// <param name="serializedCache">Serialized cache</param>
+        protected DataCache(SerializedCache serializedCache)
+        {
+            SerializedCache = serializedCache;
+        }
 
         /// <summary>
         /// Reads a specified entry from the cache. If the entry is not in the cache, it will be automatically loaded from the underlying storage.
@@ -106,6 +121,52 @@ public void Add(StorageKey key, StorageItem value)
             }
         }
 
+        /// <summary>
+        /// Adds a new entry to the cache.
+        /// </summary>
+        /// <param name="key">The key of the entry.</param>
+        /// <param name="value">The data of the entry.</param>
+        /// <exception cref="ArgumentException">The entry has already been cached.</exception>
+        /// <remarks>Note: This method does not read the internal storage to check whether the record already exists.</remarks>
+        public void Add<T>(StorageKey key, T value) where T : IStorageCacheEntry
+        {
+            lock (_dictionary)
+            {
+                Add(key, value.GetStorageItem());
+                AddToCache(value);
+            }
+        }
+
+        /// <summary>
+        /// Adds a new entry to the cache.
+        /// </summary>
+        /// <param name="value">The data of the entry.</param>
+        /// <exception cref="ArgumentException">The entry has already been cached.</exception>
+        /// <remarks>Note: This method does not read the internal storage to check whether the record already exists.</remarks>
+        public void AddToCache<T>(T? value = default) where T : IStorageCacheEntry
+        {
+            var type = typeof(T);
+            SerializedCache.Remove(type);
+            _serializedCacheChanges.Set(type, value);
+        }
+
+        /// <summary>
+        /// Tries to get the entry from cache.
+        /// </summary>
+        /// <typeparam name="T">Cache type</typeparam>
+        /// <returns>The entry if found, null otherwise.</returns>
+        public T? GetFromCache<T>() where T : IStorageCacheEntry
+        {
+            var value = _serializedCacheChanges.Get<T>();
+
+            if (value != null)
+            {
+                return value;
+            }
+
+            return SerializedCache.Get<T>();
+        }
+
         /// <summary>
         /// Adds a new entry to the underlying storage.
         /// </summary>
@@ -139,6 +200,8 @@ public virtual void Commit()
                             break;
                     }
                 }
+                SerializedCache.CopyFrom(_serializedCacheChanges);
+                _serializedCacheChanges.Clear();
                 _changeSet.Clear();
             }
         }
@@ -370,6 +433,19 @@ public bool Contains(StorageKey key)
             }
         }
 
+        /// <summary>
+        /// Reads a specified entry from the cache, and mark it as <see cref="TrackState.Changed"/>.
+        /// If the entry is not in the cache, it will be automatically loaded from the underlying storage.
+        /// </summary>
+        /// <param name="key">The key of the entry.</param>
+        /// <param name="serializedCache">Serialized cache</param>
+        public void GetAndChange<T>(StorageKey key, T serializedCache) where T : IStorageCacheEntry
+        {
+            var ret = GetAndChange(key, serializedCache.GetStorageItem);
+            ret!.FromReplica(serializedCache.GetStorageItem());
+            AddToCache(serializedCache);
+        }
+
         /// <summary>
         /// Reads a specified entry from the cache.
         /// If the entry is not in the cache, it will be automatically loaded from the underlying storage.

src/Neo/Persistence/ICacheableReadOnlyStore.cs

@@ -0,0 +1,44 @@
+// Copyright (C) 2015-2025 The Neo Project.
+//
+// ICacheableReadOnlyStore.cs file belongs to the neo project and is free
+// software distributed under the MIT software license, see the
+// accompanying file LICENSE in the main directory of the
+// repository or http://www.opensource.org/licenses/mit-license.php
+// for more details.
+//
+// Redistribution and use in source and binary forms with or without
+// modifications are permitted.
+
+#nullable enable
+
+using Neo.SmartContract;
+using System;
+
+namespace Neo.Persistence
+{
+    /// <summary>
+    /// This interface provides methods to read from the database.
+    /// </summary>
+    public interface ICacheableReadOnlyStore : ICacheableReadOnlyStore<StorageKey, StorageItem>, IReadOnlyStore { }
+
+    /// <summary>
+    /// This interface provides methods to read from the database.
+    /// </summary>
+    public interface ICacheableReadOnlyStore<TKey, TValue> : IReadOnlyStore<TKey, TValue>
+    {
+        /// <summary>
+        /// Tries to get the entry from cache.
+        /// </summary>
+        /// <typeparam name="T">Cache type</typeparam>
+        /// <returns>The entry if found, null otherwise.</returns>
+        public T? GetFromCache<T>() where T : IStorageCacheEntry;
+
+        /// <summary>
+        /// Adds a new entry to the cache.
+        /// </summary>
+        /// <param name="value">The data of the entry.</param>
+        /// <exception cref="ArgumentException">The entry has already been cached.</exception>
+        /// <remarks>Note: This method does not read the internal storage to check whether the record already exists.</remarks>
+        public void AddToCache<T>(T? value = default) where T : IStorageCacheEntry;
+    }
+}

src/Neo/Persistence/IStorageCacheEntry.cs

@@ -0,0 +1,20 @@
+// Copyright (C) 2015-2025 The Neo Project.
+//
+// IStorageCacheEntry.cs file belongs to the neo project and is free
+// software distributed under the MIT software license, see the
+// accompanying file LICENSE in the main directory of the
+// repository or http://www.opensource.org/licenses/mit-license.php
+// for more details.
+//
+// Redistribution and use in source and binary forms with or without
+// modifications are permitted.
+
+using Neo.SmartContract;
+
+namespace Neo.Persistence
+{
+    public interface IStorageCacheEntry
+    {
+        public StorageItem GetStorageItem();
+    }
+}

src/Neo/Persistence/IStore.cs

@@ -23,6 +23,11 @@ public interface IStore :
         IWriteStore<byte[], byte[]>,
         IDisposable
     {
+        /// <summary>
+        /// Serialized cache
+        /// </summary>
+        SerializedCache SerializedCache { get; }
+
         /// <summary>
         /// Creates a snapshot of the database.
         /// </summary>

src/Neo/Persistence/MemoryStore.cs

@@ -26,6 +26,7 @@ namespace Neo.Persistence
     public class MemoryStore : IStore
     {
         private readonly ConcurrentDictionary<byte[], byte[]> _innerData = new(ByteArrayEqualityComparer.Default);
+        public SerializedCache SerializedCache { get; } = new();
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Delete(byte[] key)