feat: enable archival mode for Firewood (#1416)

Author: RodrigoVillar

RELEASES.md

@@ -5,6 +5,8 @@
 - Removes `avax.version` API
 - Removes `customethclient` package in favor of `ethclient` package and temporary type registrations (`WithTempRegisteredLibEVMExtras`)
   - Also removes blockHook extension in `ethclient` package.
+- Enables Firewood to run with pruning disabled.
+  - This change modifies the filepath of Firewood and any nodes using Firewood will need to resync.
 
 ## [v0.16.0](https://github.com/ava-labs/coreth/releases/tag/v0.16.0)
 

core/blockchain.go

@@ -34,7 +34,6 @@ import (
 	"fmt"
 	"io"
 	"math/big"
-	"path/filepath"
 	"runtime"
 	"strings"
 	"sync"
@@ -177,8 +176,6 @@ const (
 	// trieCleanCacheStatsNamespace is the namespace to surface stats from the trie
 	// clean cache's underlying fastcache.
 	trieCleanCacheStatsNamespace = "hashdb/memcache/clean/fastcache"
-
-	firewoodFileName = "firewood.db"
 )
 
 // CacheConfig contains the configuration values for the trie database
@@ -231,12 +228,14 @@ func (c *CacheConfig) triedbConfig() *triedb.Config {
 		if c.ChainDataDir == "" {
 			log.Crit("Chain data directory must be specified for Firewood")
 		}
+
 		config.DBOverride = firewood.Config{
-			FilePath:             filepath.Join(c.ChainDataDir, firewoodFileName),
+			ChainDataDir:         c.ChainDataDir,
 			CleanCacheSize:       c.TrieCleanLimit * 1024 * 1024,
 			FreeListCacheEntries: firewood.Defaults.FreeListCacheEntries,
 			Revisions:            uint(c.StateHistory), // must be at least 2
 			ReadCacheStrategy:    ffi.CacheAllReads,
+			ArchiveMode:          !c.Pruning,
 		}.BackendConstructor
 	}
 	return config

core/blockchain_ext_test.go

@@ -166,27 +166,47 @@ func copyMemDB(db ethdb.Database) (ethdb.Database, error) {
 	return newDB, nil
 }
 
-// This copies all files from a flat directory [src] to a new temporary directory and returns
-// the path to the new directory.
-func copyFlatDir(t *testing.T, src string) string {
+// copyDir recursively copies all files and folders from a directory [src] to a
+// new temporary directory and returns the path to the new directory.
+func copyDir(t *testing.T, src string) string {
 	t.Helper()
+
 	if src == "" {
 		return ""
 	}
 
 	dst := t.TempDir()
-	ents, err := os.ReadDir(src)
-	require.NoError(t, err)
+	err := filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
 
-	for _, e := range ents {
-		require.False(t, e.IsDir(), "expected flat directory")
-		name := e.Name()
-		data, err := os.ReadFile(filepath.Join(src, name))
-		require.NoError(t, err)
-		info, err := e.Info()
-		require.NoError(t, err)
-		require.NoError(t, os.WriteFile(filepath.Join(dst, name), data, info.Mode().Perm()))
-	}
+		// Calculate the relative path from src
+		relPath, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+
+		// Skip the root directory itself
+		if relPath == "." {
+			return nil
+		}
+
+		dstPath := filepath.Join(dst, relPath)
+
+		if info.IsDir() {
+			return os.MkdirAll(dstPath, info.Mode().Perm())
+		}
+
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+
+		return os.WriteFile(dstPath, data, info.Mode().Perm())
+	})
+
+	require.NoError(t, err)
 	return dst
 }
 
@@ -237,7 +257,7 @@ func checkBlockChainState(
 	// Copy the database over to prevent any issues when re-using [originalDB] after this call.
 	originalDB, err = copyMemDB(originalDB)
 	require.NoError(err)
-	newChainDataDir := copyFlatDir(t, oldChainDataDir)
+	newChainDataDir := copyDir(t, oldChainDataDir)
 	restartedChain, err := create(originalDB, gspec, lastAcceptedBlock.Hash(), newChainDataDir)
 	require.NoError(err)
 	defer restartedChain.Stop()
@@ -1682,7 +1702,7 @@ func ReexecCorruptedStateTest(t *testing.T, create ReexecTestFunc) {
 	blockchain.Stop()
 
 	// Restart blockchain with existing state
-	newDir := copyFlatDir(t, tempDir) // avoid file lock
+	newDir := copyDir(t, tempDir) // avoid file lock
 	restartedBlockchain, err := create(chainDB, gspec, chain[1].Hash(), newDir, 4096)
 	require.NoError(t, err)
 	defer restartedBlockchain.Stop()

core/blockchain_test.go

@@ -72,7 +72,7 @@ var (
 		AcceptorQueueLimit:        64,
 	}
 
-	// Firewood should only be included for non-archive, snapshot disabled tests.
+	// Firewood should only be included for snapshot disabled tests.
 	schemes = []string{rawdb.HashScheme, customrawdb.FirewoodScheme}
 )
 
@@ -111,22 +111,36 @@ func TestArchiveBlockChain(t *testing.T) {
 }
 
 func TestArchiveBlockChainSnapsDisabled(t *testing.T) {
-	create := func(db ethdb.Database, gspec *Genesis, lastAcceptedHash common.Hash, _ string) (*BlockChain, error) {
+	for _, scheme := range schemes {
+		t.Run(scheme, func(t *testing.T) {
+			testArchiveBlockChainSnapsDisabled(t, scheme)
+		})
+	}
+}
+
+func testArchiveBlockChainSnapsDisabled(t *testing.T, scheme string) {
+	create := func(db ethdb.Database, gspec *Genesis, lastAcceptedHash common.Hash, dataPath string) (*BlockChain, error) {
+		cacheConfig := &CacheConfig{
+			TrieCleanLimit:            256,
+			TrieDirtyLimit:            256,
+			TrieDirtyCommitTarget:     20,
+			TriePrefetcherParallelism: 4,
+			Pruning:                   false, // Archive mode
+			StateHistory:              32,    // Required for Firewood's minimum Revision count
+			SnapshotLimit:             0,     // Disable snapshots
+			AcceptorQueueLimit:        64,
+			StateScheme:               scheme,
+			ChainDataDir:              dataPath,
+		}
+
 		return createBlockChain(
 			db,
-			&CacheConfig{
-				TrieCleanLimit:            256,
-				TrieDirtyLimit:            256,
-				TrieDirtyCommitTarget:     20,
-				TriePrefetcherParallelism: 4,
-				Pruning:                   false, // Archive mode
-				SnapshotLimit:             0,     // Disable snapshots
-				AcceptorQueueLimit:        64,
-			},
+			cacheConfig,
 			gspec,
 			lastAcceptedHash,
 		)
 	}
+
 	for _, tt := range tests {
 		t.Run(tt.Name, func(t *testing.T) {
 			tt.testFunc(t, create)
@@ -409,6 +423,164 @@ func TestBlockChainOfflinePruningUngracefulShutdown(t *testing.T) {
 	}
 }
 
+// TestPruningToNonPruning tests that opening a previously pruned database as a
+// non-pruned database is successful.
+func TestPruningToNonPruning(t *testing.T) {
+	for _, scheme := range schemes {
+		t.Run(scheme, func(t *testing.T) {
+			testPruningToNonPruning(t, scheme)
+		})
+	}
+}
+
+// testPruningToNonPruning tests that opening a previously pruned database as a
+// non-pruned database is successful.
+//
+// This test checks the following invariants:
+// 1. Verifies that a pruned node does not have the state for all blocks (except
+// the last accepted block) upon restart.
+// 2. Verify that a pruned => archival node has the state for all blocks
+// accepted during archival mode upon restart.
+func testPruningToNonPruning(t *testing.T, scheme string) {
+	var (
+		key1, _   = crypto.HexToECDSA("b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291")
+		key2, _   = crypto.HexToECDSA("8a1f9a8f95be41cd7ccb6168179afb4504aefe388d1e14474d32c45c72ce7b7a")
+		addr1     = crypto.PubkeyToAddress(key1.PublicKey)
+		addr2     = crypto.PubkeyToAddress(key2.PublicKey)
+		chainDB   = rawdb.NewMemoryDatabase()
+		numStates = uint64(5)
+	)
+
+	gspec := &Genesis{
+		Config: &params.ChainConfig{HomesteadBlock: new(big.Int)},
+		Alloc:  types.GenesisAlloc{addr1: {Balance: big.NewInt(1000000)}},
+	}
+
+	chainDataDir := t.TempDir()
+	pruningConfig := &CacheConfig{
+		TrieCleanLimit:            256,
+		TrieDirtyLimit:            256,
+		TrieDirtyCommitTarget:     20,
+		TriePrefetcherParallelism: 4,
+		Pruning:                   true, // Enable pruning
+		CommitInterval:            4096,
+		StateHistory:              numStates,
+		AcceptorQueueLimit:        64,
+		StateScheme:               scheme,
+		ChainDataDir:              chainDataDir,
+	}
+
+	// Create a node in pruning mode.
+	blockchain, err := createBlockChain(chainDB, pruningConfig, gspec, common.Hash{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Generate 10 (2 * numStates) blocks.
+	signer := types.HomesteadSigner{}
+	_, blocks, _, err := GenerateChainWithGenesis(gspec, blockchain.engine, 2*int(numStates), 10, func(i int, gen *BlockGen) {
+		tx, _ := types.SignTx(types.NewTransaction(gen.TxNonce(addr1), addr2, big.NewInt(10000), ethparams.TxGas, nil, nil), signer, key1)
+		gen.AddTx(tx)
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	prunedBlocks := blocks[:numStates]
+	nonPrunedBlocks := blocks[numStates:]
+
+	// Insert the first five blocks.
+	// The states of the first four blocks will be lost upon restart.
+	if _, err := blockchain.InsertChain(prunedBlocks); err != nil {
+		t.Fatal(err)
+	}
+	for _, block := range prunedBlocks {
+		if err := blockchain.Accept(block); err != nil {
+			t.Fatal(err)
+		}
+	}
+	blockchain.DrainAcceptorQueue()
+
+	lastAcceptedHash := blockchain.LastConsensusAcceptedBlock().Hash()
+	blockchain.Stop()
+
+	// Reopen the node.
+	blockchain, err = createBlockChain(chainDB, pruningConfig, gspec, lastAcceptedHash)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 1. Verify that a pruned node does not have the state for all blocks (except
+	// the last accepted block) upon restart.
+	for _, block := range prunedBlocks[:numStates-1] {
+		if blockchain.HasState(block.Root()) {
+			t.Fatalf("Expected blockchain to be missing state for intermediate block %d with pruning enabled", block.NumberU64())
+		}
+	}
+
+	blockchain.Stop()
+
+	archiveConfig := &CacheConfig{
+		TrieCleanLimit:            256,
+		TrieDirtyLimit:            256,
+		TrieDirtyCommitTarget:     20,
+		TriePrefetcherParallelism: 4,
+		Pruning:                   false, // Archive mode
+		AcceptorQueueLimit:        64,
+		StateScheme:               scheme,
+		StateHistory:              32,
+		ChainDataDir:              chainDataDir,
+	}
+
+	// Reopen the node, but switch from pruning to archival mode.
+	blockchain, err = createBlockChain(
+		chainDB,
+		archiveConfig,
+		gspec,
+		lastAcceptedHash,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Insert the remaining five blocks.
+	// The states of all these blocks will still be accessible on restart
+	// since we're now in archival mode.
+	if _, err := blockchain.InsertChain(nonPrunedBlocks); err != nil {
+		t.Fatal(err)
+	}
+
+	for _, block := range nonPrunedBlocks {
+		if err := blockchain.Accept(block); err != nil {
+			t.Fatal(err)
+		}
+	}
+	blockchain.DrainAcceptorQueue()
+
+	lastAcceptedHash = blockchain.LastConsensusAcceptedBlock().Hash()
+	blockchain.Stop()
+
+	// Reopen the archival node.
+	blockchain, err = createBlockChain(
+		chainDB,
+		archiveConfig,
+		gspec,
+		lastAcceptedHash,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer blockchain.Stop()
+
+	// 2. Verify that a pruned => archival node has the state for all blocks
+	// accepted during archival mode upon restart.
+	for _, block := range nonPrunedBlocks {
+		if !blockchain.HasState(block.Root()) {
+			t.Fatalf("Expected blockchain to have the state for block %d with pruning disabled", block.NumberU64())
+		}
+	}
+}
+
 func testRepopulateMissingTriesParallel(t *testing.T, parallelism int) {
 	var (
 		key1, _ = crypto.HexToECDSA("b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291")

core/extstate/database_test.go

@@ -6,7 +6,6 @@ package extstate
 import (
 	"encoding/binary"
 	"math/rand"
-	"path/filepath"
 	"slices"
 	"testing"
 
@@ -82,8 +81,8 @@ func newFuzzState(t *testing.T) *fuzzState {
 	})
 
 	firewoodMemdb := rawdb.NewMemoryDatabase()
-	fwCfg := firewood.Defaults                              // copy the defaults
-	fwCfg.FilePath = filepath.Join(t.TempDir(), "firewood") // Use a temporary directory for the Firewood
+	fwCfg := firewood.Defaults       // copy the defaults
+	fwCfg.ChainDataDir = t.TempDir() // Use a temporary directory for the Firewood
 	firewoodState := NewDatabaseWithConfig(
 		firewoodMemdb,
 		&triedb.Config{

core/genesis_test.go

@@ -32,7 +32,6 @@ import (
 	_ "embed"
 	"fmt"
 	"math/big"
-	"path/filepath"
 	"reflect"
 	"testing"
 
@@ -307,7 +306,7 @@ func newDbConfig(t *testing.T, scheme string) *triedb.Config {
 	case customrawdb.FirewoodScheme:
 		fwCfg := firewood.Defaults
 		// Create a unique temporary directory for each test
-		fwCfg.FilePath = filepath.Join(t.TempDir(), "firewood_state") // matches blockchain.go
+		fwCfg.ChainDataDir = t.TempDir()
 		return &triedb.Config{DBOverride: fwCfg.BackendConstructor}
 	default:
 		t.Fatalf("unknown scheme %s", scheme)

go.mod

@@ -16,7 +16,7 @@ go 1.24.9
 require (
 	github.com/VictoriaMetrics/fastcache v1.12.1
 	github.com/ava-labs/avalanchego v1.14.1-0.20251120155522-df4a8e531761
-	github.com/ava-labs/firewood-go-ethhash/ffi v0.0.14
+	github.com/ava-labs/firewood-go-ethhash/ffi v0.0.15
 	github.com/ava-labs/libevm v1.13.15-0.20251016142715-1bccf4f2ddb2
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc
 	github.com/deckarep/golang-set/v2 v2.1.0

go.sum

@@ -28,8 +28,8 @@ github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPd
 github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
 github.com/ava-labs/avalanchego v1.14.1-0.20251120155522-df4a8e531761 h1:FrsqYm5sms00jWnr8pV9Nj08v1ipYjp1x6p11NIpIBU=
 github.com/ava-labs/avalanchego v1.14.1-0.20251120155522-df4a8e531761/go.mod h1:Ntq3RBvDQzNjy14NU3RC2Jf1A9pzfM5RVQ30Gwx/6IM=
-github.com/ava-labs/firewood-go-ethhash/ffi v0.0.14 h1:Be+LO61hwmo7XKNm57Yoqx7ld8SgBapjVBEPjUcgI8o=
-github.com/ava-labs/firewood-go-ethhash/ffi v0.0.14/go.mod h1:hR/JSGXxST9B9olwu/NpLXHAykfAyNGfyKnYQqiiOeE=
+github.com/ava-labs/firewood-go-ethhash/ffi v0.0.15 h1:NAVjEu508HwdgbxH/xQxMQoBUgYUn9RQf0VeCrhtYMY=
+github.com/ava-labs/firewood-go-ethhash/ffi v0.0.15/go.mod h1:hR/JSGXxST9B9olwu/NpLXHAykfAyNGfyKnYQqiiOeE=
 github.com/ava-labs/libevm v1.13.15-0.20251016142715-1bccf4f2ddb2 h1:hQ15IJxY7WOKqeJqCXawsiXh0NZTzmoQOemkWHz7rr4=
 github.com/ava-labs/libevm v1.13.15-0.20251016142715-1bccf4f2ddb2/go.mod h1:DqSotSn4Dx/UJV+d3svfW8raR+cH7+Ohl9BpsQ5HlGU=
 github.com/aymerick/raymond v2.0.3-0.20180322193309-b565731e1464+incompatible/go.mod h1:osfaiScAUVup+UC9Nfq76eWqDhXlp+4UYaA8uhTBO6g=