chore: self review

Author: MaksymMalicki

migration/statehistory/class_hash_ingestor.go

@@ -26,6 +26,31 @@ func newClassHashIngestor(
 	return &classHashIngestor{baseIngestor: newBaseIngestor(ctx, sem, database)}
 }
 
+// Run migrates the class-hash history of a single contract.
+//
+// Legend: Bₙ = block at which the n-th class-hash *replacement* happened.
+// Vₙ = the class hash active *after* Bₙ; V₀ is the deploy-time hash. The
+// deprecated layout writes nothing at deploy: each entry is written only
+// on a *Replace*, and the value stored is the hash that was active before
+// that replace. So deprecated[B₁] = V₀ even though no replace happened at
+// deploy_h itself. The new layout adds an explicit deploy entry and shifts
+// everything else by one slot:
+//
+//	block    │ deprecated     │ new
+//	─────────┼────────────────┼──────
+//	deploy_h │  —             │ V₀     ← inserted from first deprecated entry
+//	  B₁     │  V₀            │ V₁
+//	  B₂     │  V₁            │ V₂
+//	  B₃     │  V₂            │ V₃
+//	─────────┼────────────────┼──────
+//	  > B₃   │  contract      │ V₃ (last entry — self-contained)
+//	            .ClassHash      ← deprecated must reach into the Contract
+//	                              record for any block past the last replace
+//
+// If the deprecated history is empty (no replaces ever), the single deploy
+// entry is written with contract.ClassHash directly. Deprecated rows are
+// deleted at the end of the run. Resume-safe: empty-deprecated + existing
+// deploy entry → no-op.
 func (i *classHashIngestor) Run(index int, addr *felt.Felt, outputs chan<- task) error {
 	t := &i.tasks[index]
 
@@ -35,64 +60,81 @@ func (i *classHashIngestor) Run(index int, addr *felt.Felt, outputs chan<- task)
 		return fmt.Errorf("class-hash: GetContract(%s): %w", addr, err)
 	}
 
-	deployKey := db.ContractClassHashHistoryAtBlockKey(addr, contract.DeployedHeight)
-	deployEntryExists, err := i.database.Has(deployKey)
-	if err != nil {
-		return fmt.Errorf("class-hash: Has(deploy entry): %w", err)
-	}
-
 	depIt, err := i.database.NewIterator(deprecatedPrefix, true)
 	if err != nil {
 		return fmt.Errorf("class-hash: open deprecated iter(%s): %w", addr, err)
 	}
 	defer depIt.Close()
 
 	if !depIt.First() {
-		if deployEntryExists {
-			return nil
-		}
-		err = state.WriteClassHashHistory(
-			t.batch,
-			addr,
-			contract.DeployedHeight,
-			&contract.ClassHash,
-		)
-		if err != nil {
-			return err
-		}
-		t.completedAddrs++
-		t.entryCount++
-		return i.flush(t, outputs)
+		return i.writeDeployOnly(t, outputs, addr, contract.DeployedHeight, &contract.ClassHash)
+	}
+	return i.writeShiftedHistory(
+		t, outputs, depIt, deprecatedPrefix, addr,
+		contract.DeployedHeight, &contract.ClassHash,
+	)
+}
+
+// writeDeployOnly handles the "no deprecated history" branch: write the
+// deploy-time entry from contract.ClassHash, unless a previous run already
+// wrote it.
+func (i *classHashIngestor) writeDeployOnly(
+	t *task,
+	outputs chan<- task,
+	addr *felt.Felt,
+	deployHeight uint64,
+	classHash *felt.Felt,
+) error {
+	deployKey := db.ContractClassHashHistoryAtBlockKey(addr, deployHeight)
+	deployEntryExists, err := i.database.Has(deployKey)
+	if err != nil {
+		return fmt.Errorf("class-hash: Has(deploy entry): %w", err)
+	}
+	if deployEntryExists {
+		return nil
 	}
+	if err := state.WriteClassHashHistory(t.batch, addr, deployHeight, classHash); err != nil {
+		return err
+	}
+	t.completedAddrs++
+	t.entryCount++
+	return i.flush(t, outputs)
+}
 
+// writeShiftedHistory handles the "non-empty deprecated history" branch:
+// writes the deploy entry from the first deprecated value, shifts each
+// deprecated entry into the new layout using the next entry's pre-value
+// (or contract.ClassHash for the last), and deletes the deprecated rows.
+// depIt must be positioned at the first deprecated entry.
+func (i *classHashIngestor) writeShiftedHistory(
+	t *task,
+	outputs chan<- task,
+	depIt db.Iterator,
+	prefix []byte,
+	addr *felt.Felt,
+	deployHeight uint64,
+	headClassHash *felt.Felt,
+) error {
 	rawValue, err := depIt.Value()
 	if err != nil {
 		return fmt.Errorf("class-hash: read first value(%s): %w", addr, err)
 	}
 	deployClassHash := felt.FromBytes[felt.Felt](rawValue)
-	if err := state.WriteClassHashHistory(
-		t.batch,
-		addr,
-		contract.DeployedHeight,
-		&deployClassHash,
-	); err != nil {
+	if err := state.WriteClassHashHistory(t.batch, addr, deployHeight, &deployClassHash); err != nil {
 		return err
 	}
 	t.entryCount++
 	if err := i.flush(t, outputs); err != nil {
 		return err
 	}
 
-	// Shift-up loop: each block in the deprecated history gets the *next*
-	// entry's value (since in the old layout the value at block B was the
-	// value before B's write). The final block gets the head class hash.
 	for {
-		block, err := parseBlockKey(depIt.Key(), deprecatedPrefix)
+		block, err := parseBlockKey(depIt.Key(), prefix)
 		if err != nil {
 			return fmt.Errorf("class-hash(%s): %w", addr, err)
 		}
 		hasNext := depIt.Next()
-		historyValue := contract.ClassHash
+		historyValue := *headClassHash
 		if hasNext {
 			rawValue, err := depIt.Value()
 			if err != nil {
@@ -112,7 +154,7 @@ func (i *classHashIngestor) Run(index int, addr *felt.Felt, outputs chan<- task)
 		}
 	}
 
-	if err := t.batch.DeleteRange(deprecatedPrefix, dbutils.UpperBound(deprecatedPrefix)); err != nil {
+	if err := t.batch.DeleteRange(prefix, dbutils.UpperBound(prefix)); err != nil {
 		return fmt.Errorf("class-hash: DeleteRange deprecated(%s): %w", addr, err)
 	}
 	t.completedAddrs++

migration/statehistory/migrator.go

@@ -36,6 +36,33 @@ var (
 
 var _ migration.Migration = (*Migrator)(nil)
 
+// Migrator rewrites the contract history layout so each entry stores the
+// post-update value at its block, instead of the pre-update value.
+//
+// Example — a contract whose class hash was 0xAA at deploy (block 100),
+// changed to 0xBB at block 200, then to 0xCC at block 500:
+//
+//	block │ old layout (pre-value) │ new layout (post-value)
+//	──────┼────────────────────────┼─────────────────────────
+//	100   │ (no entry)             │ 0xAA  ← explicit deploy
+//	200   │ 0xAA                   │ 0xBB
+//	500   │ 0xBB                   │ 0xCC
+//	head  │ 0xCC (contract record) │ (read from history)
+//
+// The same shape change applies to nonces and per-slot storage. The
+// migrator runs three phases (class-hash, nonce, storage); each phase
+// iterates the Contract bucket and rewrites one contract's deprecated
+// entries at a time, deleting them in the same batch.
+//
+// Crash / cancellation safety: pebble batches commit atomically, so the
+// writes inside any single committed batch are durable as a unit. A
+// contract whose history is large may span more than one batch — but each
+// new entry's value is a pure function of the deprecated source data, so
+// re-running over an already-partially-rewritten contract overwrites with
+// identical values and then deletes the (still-present) deprecated rows.
+// Contracts whose deprecated entries are already gone short-circuit on an
+// empty iterator. The three phases run sequentially: a later phase only
+// starts after the earlier phase completes.
 type Migrator struct{}
 
 func (Migrator) Before([]byte) error { return nil }

migration/statehistory/nonce_ingestor.go

@@ -26,6 +26,26 @@ func newNonceIngestor(
 	return &nonceIngestor{baseIngestor: newBaseIngestor(ctx, sem, database)}
 }
 
+// Run migrates the nonce history of a single contract.
+//
+// Legend: Bₙ = block at which the n-th nonce change happened. Nₙ = the
+// nonce active *after* Bₙ; the deploy nonce is always 0 and is *not*
+// written to the deprecated history — its presence is implicit in the
+// pre-value of the first change entry. The new layout stores the same
+// number of entries, just shifted to post-values:
+//
+//	block  │ deprecated     │ new
+//	───────┼────────────────┼──────
+//	  B₁   │  0             │ N₁
+//	  B₂   │  N₁            │ N₂
+//	  B₃   │  N₂            │ N₃
+//	───────┼────────────────┼──────
+//	  > B₃ │  contract      │ N₃ (last entry — self-contained)
+//	          .Nonce          ← deprecated must reach into the Contract
+//	                            record for any block past the last change
+//
+// Contracts with no deprecated nonce history are skipped. Deprecated rows
+// are deleted at the end of the run.
 func (i *nonceIngestor) Run(index int, addr *felt.Felt, outputs chan<- task) error {
 	t := &i.tasks[index]
 	deprecatedPrefix := db.DeprecatedContractNonceHistoryKey(addr)

migration/statehistory/storage_ingestor.go

@@ -29,6 +29,50 @@ func newStorageIngestor(
 	return &storageIngestor{baseIngestor: newBaseIngestor(ctx, sem, database)}
 }
 
+// Run migrates the per-slot storage history of a single contract.
+//
+// Legend: Bₙ = block at which the n-th change to a slot happened. preXₙ
+// is the value of slot X before Bₙ (= what the deprecated layout stores
+// at [X, Bₙ]); headX is the slot's current value, read from the head
+// storage trie. The deprecated layout writes nothing at deploy — the
+// pre-deploy value (0) is implicit in the first change entry. The new
+// layout stores the same number of entries per slot, just shifted to
+// post-values. For one slot:
+//
+//	block  │ deprecated[slotA] │ new[slotA]
+//	───────┼───────────────────┼───────────
+//	  B₁   │  0                │ preA₁
+//	  B₂   │  preA₁            │ preA₂
+//	  B₃   │  preA₂            │ headA
+//	───────┼───────────────────┼───────────
+//	  > B₃ │  head trie leaf   │ headA (last entry — self-contained)
+//	          for slotA          ← deprecated must reach into the head
+//	                               storage trie for any block past the
+//	                               last change
+//
+// For each deprecated entry the post-value comes from one of:
+//
+//   - the *next* deprecated entry, when it's on the same slot — its stored
+//     pre-value is exactly this block's post-value;
+//   - the head storage trie leaf for that slot, when there is no next
+//     deprecated entry on the same slot;
+//   - felt.Zero, when there is no head leaf for the slot (the slot was
+//     eventually zeroed out and dropped from the trie).
+//
+// Both the deprecated history and the head trie are sorted by raw slot
+// bytes, so the ingestor walks them in lockstep — the head-trie iterator
+// advances only when its current leaf matches the slot just resolved:
+//
+//	deprecated history       head trie         new history
+//	─────────────────────    ─────────────     ─────────────────────────
+//	[slotA, B₁..B₃]    ──→   [slotA] = headA   [slotA, B₁..B₃] last uses headA
+//	[slotB, B₁..B₂]    ──→   (no leaf)         [slotB, B₁..B₂] last uses 0
+//	                          ← slotB was set                   (slotB was zeroed
+//	                            and later zeroed                 at B₂)
+//	[slotC, B₁]        ──→   [slotC] = headC   [slotC, B₁] = headC
+//
+// Contracts with no deprecated storage history are skipped; deprecated
+// rows are deleted at the end of the run via DeleteRange.
 func (i *storageIngestor) Run(index int, addr *felt.Felt, outputs chan<- task) error {
 	t := &i.tasks[index]