chore: self review

Author: MaksymMalicki

core/state/accessors.go

@@ -41,10 +41,6 @@ func HasContract(r db.KeyValueReader, addr *felt.Felt) (bool, error) {
 	return r.Has(key)
 }
 
-// WriteContract writes a Contract record from raw fields. Used by the running
-// node (via writeContract on a fully-built stateContract) and by the deprecated
-// → new state migration (with StorageRoot left zero — the new state lazily
-// backfills it on the contract's first storage write).
 func WriteContract(
 	w db.KeyValueWriter,
 	addr *felt.Felt,

migration/headstate/committer.go

@@ -30,7 +30,7 @@ func newCommitter(
 func (c *committer) Run(_ int, t task, _ chan<- struct{}) error {
 	c.logger.Debug(
 		"writing batch",
-		zap.Int("addrCount", t.addrCount),
+		zap.Int("completedAddrs", t.completedAddrs),
 		zap.Int("batchSize", t.batch.Size()),
 	)
 
@@ -39,7 +39,7 @@ func (c *committer) Run(_ int, t task, _ chan<- struct{}) error {
 		return err
 	}
 
-	c.counter.log(byteSize, t.addrCount)
+	c.counter.log(byteSize, t.completedAddrs)
 	c.batchSemaphore.Put()
 	return nil
 }

migration/headstate/counter.go

@@ -9,11 +9,11 @@ import (
 )
 
 type counter struct {
-	logger      log.StructuredLogger
-	timeLogRate time.Duration
-	start       time.Time
-	size        uint64
-	addrCount   uint64
+	logger         log.StructuredLogger
+	timeLogRate    time.Duration
+	start          time.Time
+	size           uint64
+	completedAddrs uint64
 }
 
 func newCounter(logger log.StructuredLogger, timeLogRate time.Duration) counter {
@@ -24,24 +24,24 @@ func newCounter(logger log.StructuredLogger, timeLogRate time.Duration) counter
 	}
 }
 
-func (c *counter) log(byteSize uint64, addrCount int) {
+func (c *counter) log(byteSize uint64, completedAddrs int) {
 	c.size += byteSize
-	c.addrCount += uint64(addrCount)
+	c.completedAddrs += uint64(completedAddrs)
 
 	now := time.Now()
 	elapsed := now.Sub(c.start).Seconds()
-	if elapsed > float64(c.timeLogRate.Seconds()) {
+	if elapsed > c.timeLogRate.Seconds() {
 		mbs := float64(c.size) / float64(db.Megabyte)
 		c.logger.Info(
 			"write speed",
 			zap.Float64("MB", mbs),
 			zap.Float64("MB/s", mbs/elapsed),
-			zap.Uint64("contracts", c.addrCount),
-			zap.Float64("contracts/s", float64(c.addrCount)/elapsed),
+			zap.Uint64("completedContracts", c.completedAddrs),
+			zap.Float64("completedContracts/s", float64(c.completedAddrs)/elapsed),
 			zap.Float64("time", elapsed),
 		)
 		c.start = now
 		c.size = 0
-		c.addrCount = 0
+		c.completedAddrs = 0
 	}
 }

migration/headstate/ingestor.go

@@ -43,12 +43,12 @@ func (c *ingestor) Run(index int, addr felt.Address, outputs chan<- task) error
 		return err
 	}
 	if t.batch.Size() > sizeBefore {
-		t.addrCount++
+		t.completedAddrs++
 	}
 
 	if t.batch.Size() >= targetBatchByteSize {
-		outputs <- task{batch: t.batch, addrCount: t.addrCount}
-		t.addrCount = 0
+		outputs <- task{batch: t.batch, completedAddrs: t.completedAddrs}
+		t.completedAddrs = 0
 		t.batch = c.batchSemaphore.GetBlocking()
 	}
 	return nil

migration/headstate/migrator.go

@@ -2,6 +2,7 @@ package headstate
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"iter"
 	"time"
@@ -24,15 +25,67 @@ const (
 )
 
 type task struct {
-	batch     db.Batch
-	addrCount int
+	batch          db.Batch
+	completedAddrs int
 }
 
 var (
 	shouldRerun    = []byte{}
 	shouldNotRerun = []byte(nil)
 )
 
+var _ migration.Migration = (*Migrator)(nil)
+
+// Migrator consolidates the deprecated per-field contract layout into a
+// single Contract record per address, written via state.WriteContract:
+//
+//	ContractClassHash[addr]
+//	ContractNonce[addr]
+//	ContractDeploymentHeight[addr]
+//	          │
+//	          ▼
+//	Contract[addr] = { ClassHash, Nonce, DeployedHeight }
+//
+// StorageRoot is left zero — the running node lazily backfills it on the
+// contract's first storage write.
+//
+// Each address discovered in the ContractClassHash bucket is processed by one
+// of ingestorCount worker goroutines that read the three old fields into a
+// shared db.Batch; a single committer drains batches to disk. Once every
+// address has been migrated, the three deprecated buckets are wiped via
+// DeleteRange.
+//
+// Re-run safe: an address whose Contract record already exists is skipped
+// (via state.HasContract), and the trailing wipe re-issues DeleteRange over
+// the (possibly already empty) ranges.
+type Migrator struct{}
+
+func (Migrator) Before([]byte) error {
+	return nil
+}
+
+func (Migrator) Migrate(
+	ctx context.Context,
+	database db.KeyValueStore,
+	_ *networks.Network,
+	logger log.StructuredLogger,
+) ([]byte, error) {
+	addressesIter, sourceErr := pendingAddresses(database)
+	res := migrateAddresses(ctx, database, logger, addressesIter)
+
+	if err := errors.Join(sourceErr(), res.Err); err != nil {
+		return shouldRerun, err
+	}
+	if !res.IsDone {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return shouldRerun, ctxErr
+		}
+		return shouldRerun, errors.New("headstate migration did not complete")
+	}
+
+	return shouldNotRerun, wipeDeprecatedBuckets(database)
+}
+
 func migrateAddresses(
 	ctx context.Context,
 	database db.KeyValueStore,
@@ -64,51 +117,6 @@ func migrateAddresses(
 	return wait()
 }
 
-var _ migration.Migration = (*Migrator)(nil)
-
-type Migrator struct{}
-
-func (Migrator) Before([]byte) error {
-	return nil
-}
-
-func (Migrator) Migrate(
-	ctx context.Context,
-	database db.KeyValueStore,
-	_ *networks.Network,
-	logger log.StructuredLogger,
-) ([]byte, error) {
-	hasPending, err := hasPendingAddresses(database)
-	if err != nil {
-		return shouldRerun, err
-	}
-	if !hasPending {
-		return shouldNotRerun, wipeDeprecatedBuckets(database)
-	}
-
-	addressesIter, sourceErr := pendingAddresses(database)
-	res := migrateAddresses(ctx, database, logger, addressesIter)
-
-	if err := sourceErr(); err != nil {
-		return shouldRerun, err
-	}
-	if res.Err != nil || !res.IsDone {
-		return shouldRerun, res.Err
-	}
-
-	return shouldNotRerun, wipeDeprecatedBuckets(database)
-}
-
-func hasPendingAddresses(r db.KeyValueReader) (bool, error) {
-	prefix := db.ContractClassHash.Key()
-	it, err := r.NewIterator(prefix, true)
-	if err != nil {
-		return false, err
-	}
-	defer it.Close()
-	return it.First(), nil
-}
-
 func pendingAddresses(r db.KeyValueReader) (iter.Seq[felt.Address], func() error) {
 	var iterErr error
 	seq := func(yield func(felt.Address) bool) {

migration/headstate/migrator_test.go

@@ -189,7 +189,7 @@ func TestMigrate_Idempotent(t *testing.T) {
 	}
 	seedDeprecated(t, memDB, seeds)
 
-	for i := 0; i < 3; i++ {
+	for i := range 3 {
 		res, err := headstate.Migrator{}.Migrate(
 			context.Background(),
 			memDB,