Add/catchup

.gitignore

@@ -53,3 +53,14 @@ internal/WAL/.tmp/*
 .code-review-graph/*
 .cursor/*
 test_results/
+docs/FASTSYNC_V3_MIGRATION_PLAN.md
+eventlog.duckdb
+Scripts/sign_tx.go
+storage/thebe-kv/000017.vlog
+storage/thebe-kv/000018.vlog
+storage/thebe-kv/DISCARD
+storage/thebe-kv/KEYREGISTRY
+storage/thebe-kv/MANIFEST
+storage/thebe-kv/outbox.db
+dlq/DLQ.log
+jmdn2

CLI/CLI.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"strconv"
 	"strings"
 	"time"
 
@@ -107,8 +108,9 @@ func PrintFuncs() {
 	fmt.Println("  mempoolStats                      - Show mempool statistics")
 	fmt.Println("  stats                             - Show messaging statistics")
 	fmt.Println("  broadcast <message>              - Broadcast a message to all connected peers")
-	fmt.Println("  fastsync <peer_multiaddr>        - Fast sync blockchain data with a peer (V2 Engine)")
-	fmt.Println("  accountsync <peer_multiaddr>     - Sync missing accounts only (skip block sync)")
+	fmt.Println("  fastsync <peer_multiaddr>                    - Fast sync blockchain data with a peer (V2 Engine)")
+	fmt.Println("  catchup <peer_multiaddr> [from_block]        - Catch up to chain tip; from_block defaults to auto-detect (localTip+1)")
+	fmt.Println("  accountsync <peer_multiaddr>                 - Sync missing accounts only (skip block sync)")
 	fmt.Println("  dbstate                           - Show current ImmuDB database state")
 	fmt.Println("  propagateDID <did> <public_key>  - Propagate a DID to the network")
 	fmt.Println("  getDID <did>                      - Get a DID document from the network")
@@ -268,6 +270,8 @@ func (h *CommandHandler) handleCommand(parts []string) {
 		h.handleBroadcast(parts)
 	case "fastsync", "fastsyncv2", "firstsync":
 		h.handleFastSync(parts)
+	case "catchup":
+		h.handleCatchUpSync(parts)
 	case "accountsync":
 		h.handleAccountSync(parts)
 	case "propagateDID":
@@ -632,6 +636,41 @@ func (h *CommandHandler) handleFastSync(parts []string) {
 	printDashes()
 }
 
+func (h *CommandHandler) handleCatchUpSync(parts []string) {
+	if len(parts) < 2 {
+		fmt.Println("Usage: catchup <peer_multiaddr> [from_block]")
+		fmt.Println("  peer_multiaddr  full multiaddr with peer ID, e.g. /ip4/1.2.3.4/tcp/15000/p2p/12D3KooW...")
+		fmt.Println("  from_block      optional; defaults to 0 (auto-detect from local DB tip)")
+		fmt.Println("                  pass 1 to force a full scan from genesis")
+		return
+	}
+	if h.FastSyncerV2 == nil {
+		fmt.Println("Error: FastsyncV2 engine is not initialized")
+		return
+	}
+
+	var fromBlock uint64
+	if len(parts) >= 3 {
+		var err error
+		fromBlock, err = strconv.ParseUint(parts[2], 10, 64)
+		if err != nil {
+			fmt.Printf("Invalid from_block %q: %v\n", parts[2], err)
+			return
+		}
+	} // fromBlock=0 → auto-detect inside HandleCatchUpSync
+
+	fmt.Printf("Starting catch-up sync (from_block=%d) with peer %s\n", fromBlock, parts[1])
+	startTime := time.Now()
+
+	if err := h.FastSyncerV2.HandleCatchUpSync(fromBlock, parts[1]); err != nil {
+		fmt.Printf("CatchUpSync failed: %v\n", err)
+		return
+	}
+
+	fmt.Printf("CatchUpSync completed in %v\n", time.Since(startTime))
+	printDashes()
+}
+
 func (h *CommandHandler) handleAccountSync(parts []string) {
 	if len(parts) != 2 {
 		fmt.Println("Usage: accountsync <peer_multiaddr>")

CLI/CLI_GRPC.go

@@ -330,6 +330,38 @@ func (h *CommandHandler) HandleFastSyncV2(peeraddr string) (SyncStats, error) {
 	}, nil
 }
 
+func (h *CommandHandler) HandleCatchUpSync(peeraddr string, fromBlock uint64) (SyncStats, error) {
+	if peeraddr == "" {
+		return SyncStats{}, fmt.Errorf("usage: catchup <peer_multiaddr> [from_block]")
+	}
+	// fromBlock=0 → auto-detect inside HandleCatchUpSync
+	if !h.PullAllowed {
+		return SyncStats{}, fmt.Errorf("node is configured as a serve-only participant (pulling disabled). cannot pull data")
+	}
+	if h.FastSyncerV2 == nil {
+		return SyncStats{}, fmt.Errorf("FastsyncV2 engine is inactive")
+	}
+
+	startTime := time.Now().UTC()
+	if err := h.FastSyncerV2.HandleCatchUpSync(fromBlock, peeraddr); err != nil {
+		return SyncStats{}, fmt.Errorf("CatchUpSync failed: %w", err)
+	}
+
+	var newMainState, newAccountsState *schema.ImmutableState
+	if h.MainClient != nil {
+		newMainState, _ = DB_OPs.GetDatabaseState(h.MainClient.Client)
+	}
+	if h.DIDClient != nil {
+		newAccountsState, _ = DB_OPs.GetDatabaseState(h.DIDClient.Client)
+	}
+
+	return SyncStats{
+		TimeTaken:     time.Since(startTime),
+		MainState:     newMainState,
+		AccountsState: newAccountsState,
+	}, nil
+}
+
 func (h *CommandHandler) HandleAccountSync(peeraddr string) (SyncStats, error) {
 	if peeraddr == "" {
 		return SyncStats{}, fmt.Errorf("usage: accountsync <peer_multiaddr>")

CLI/GRPC_Server.go

@@ -256,9 +256,19 @@ func (s *CLIServer) AccountSync(ctx context.Context, req *pb.PeerRequest) (*pb.S
 func (s *CLIServer) FirstSync(ctx context.Context, req *pb.FirstSyncRequest) (*pb.SyncStats, error) {
 	stats, err := s.handler.HandleFirstSync(req.Peer, req.Mode)
 	if err != nil {
-		return &pb.SyncStats{
-			Error: err.Error(),
-		}, nil
+		return &pb.SyncStats{Error: err.Error()}, nil
+	}
+	return &pb.SyncStats{
+		TimeTaken:     int64(stats.TimeTaken.Seconds()),
+		MainState:     convertDBState(stats.MainState),
+		AccountsState: convertDBState(stats.AccountsState),
+	}, nil
+}
+
+func (s *CLIServer) CatchUpSync(ctx context.Context, req *pb.CatchUpRequest) (*pb.SyncStats, error) {
+	stats, err := s.handler.HandleCatchUpSync(req.Peer, req.FromBlock)
+	if err != nil {
+		return &pb.SyncStats{Error: err.Error()}, nil
 	}
 	return &pb.SyncStats{
 		TimeTaken:     int64(stats.TimeTaken.Seconds()),

CLI/client.go

@@ -179,6 +179,15 @@ func (c *Client) FirstSync(peerAddr string, mode string) (*pb.SyncStats, error)
 	})
 }
 
+// CatchUpSync reconciles blocks [fromBlock..remoteTip] without Merkle bisection.
+func (c *Client) CatchUpSync(peerAddr string, fromBlock uint64) (*pb.SyncStats, error) {
+	ctx := context.Background()
+	return c.conn.CatchUpSync(ctx, &pb.CatchUpRequest{
+		Peer:      peerAddr,
+		FromBlock: fromBlock,
+	})
+}
+
 // GetDatabaseState returns the current database state
 func (c *Client) GetDatabaseState() (*pb.DatabaseStates, error) {
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)