Scale the DAG

api-spec/openapi/swagger/ark/v1/indexer.openapi.json

@@ -1282,6 +1282,10 @@
             "type": "integer",
             "format": "int64"
           },
+          "depth": {
+            "type": "integer",
+            "format": "uint32"
+          },
           "expiresAt": {
             "type": "integer",
             "format": "int64"

api-spec/openapi/swagger/ark/v1/service.openapi.json

@@ -1436,6 +1436,10 @@
             "type": "integer",
             "format": "int64"
           },
+          "depth": {
+            "type": "integer",
+            "format": "uint32"
+          },
           "expiresAt": {
             "type": "integer",
             "format": "int64"

api-spec/openapi/swagger/ark/v1/types.openapi.json

@@ -410,6 +410,10 @@
             "type": "integer",
             "format": "int64"
           },
+          "depth": {
+            "type": "integer",
+            "format": "uint32"
+          },
           "expiresAt": {
             "type": "integer",
             "format": "int64"

api-spec/protobuf/ark/v1/indexer.proto

@@ -257,6 +257,7 @@ message IndexerVtxo {
   repeated string commitment_txids = 11;
   string settled_by = 12;
   string ark_txid = 13;
+  uint32 depth = 14;
 }
 
 message IndexerChain {

api-spec/protobuf/ark/v1/types.proto

@@ -28,6 +28,7 @@ message Vtxo {
   string spent_by = 11;
   string settled_by = 12;
   string ark_txid = 13;
+  uint32 depth = 14;
 }
 
 message TxData {

internal/core/application/indexer.go

@@ -239,8 +239,11 @@ func (i *indexerService) GetVtxoChain(
 	nextVtxos := []domain.Outpoint{vtxoKey}
 	visited := make(map[string]bool)
 
+	// Pre-fetch VTXOs using markers for optimization (reduces DB calls for deep chains)
+	vtxoCache := i.prefetchVtxosByMarkers(ctx, vtxoKey)
+
 	for len(nextVtxos) > 0 {
-		vtxos, err := i.repoManager.Vtxos().GetVtxos(ctx, nextVtxos)
+		vtxos, err := i.getVtxosFromCacheOrDB(ctx, nextVtxos, vtxoCache)
 		if err != nil {
 			return nil, err
 		}
@@ -369,6 +372,92 @@ func (i *indexerService) GetVtxoChain(
 	}, nil
 }
 
+// prefetchVtxosByMarkers pre-fetches VTXOs using markers for optimization.
+// This reduces the number of DB calls for deep chains by bulk fetching VTXOs
+// associated with the marker chain instead of fetching one at a time.
+func (i *indexerService) prefetchVtxosByMarkers(
+	ctx context.Context, startKey Outpoint,
+) map[string]domain.Vtxo {
+	cache := make(map[string]domain.Vtxo)
+
+	if i.repoManager.Markers() == nil {
+		return cache
+	}
+
+	// Get starting VTXO to find its marker
+	startVtxos, err := i.repoManager.Vtxos().GetVtxos(ctx, []domain.Outpoint{startKey})
+	if err != nil || len(startVtxos) == 0 {
+		return cache
+	}
+
+	startVtxo := startVtxos[0]
+	// Add starting VTXO to cache
+	cache[startVtxo.Outpoint.String()] = startVtxo
+
+	if startVtxo.MarkerID == "" {
+		return cache
+	}
+
+	// Collect marker chain by following ParentMarkerIDs
+	markerIDs := []string{startVtxo.MarkerID}
+	marker, err := i.repoManager.Markers().GetMarker(ctx, startVtxo.MarkerID)
+	if err != nil {
+		return cache
+	}
+
+	// Follow the marker chain up to the root (depth 0)
+	for marker != nil && len(marker.ParentMarkerIDs) > 0 {
+		markerIDs = append(markerIDs, marker.ParentMarkerIDs...)
+		// Follow first parent marker to continue chain
+		marker, _ = i.repoManager.Markers().GetMarker(ctx, marker.ParentMarkerIDs[0])
+	}
+
+	// Bulk fetch VTXOs for all markers in the chain
+	vtxos, err := i.repoManager.Markers().GetVtxoChainByMarkers(ctx, markerIDs)
+	if err != nil {
+		return cache
+	}
+
+	for _, v := range vtxos {
+		cache[v.Outpoint.String()] = v
+	}
+
+	return cache
+}
+
+// getVtxosFromCacheOrDB retrieves VTXOs from cache first, falling back to DB for cache misses.
+// This is used in conjunction with prefetchVtxosByMarkers to reduce DB calls.
+func (i *indexerService) getVtxosFromCacheOrDB(
+	ctx context.Context,
+	outpoints []domain.Outpoint,
+	cache map[string]domain.Vtxo,
+) ([]domain.Vtxo, error) {
+	result := make([]domain.Vtxo, 0, len(outpoints))
+	missingOutpoints := make([]domain.Outpoint, 0)
+
+	for _, op := range outpoints {
+		if v, ok := cache[op.String()]; ok {
+			result = append(result, v)
+		} else {
+			missingOutpoints = append(missingOutpoints, op)
+		}
+	}
+
+	if len(missingOutpoints) > 0 {
+		dbVtxos, err := i.repoManager.Vtxos().GetVtxos(ctx, missingOutpoints)
+		if err != nil {
+			return nil, err
+		}
+		result = append(result, dbVtxos...)
+		// Add to cache for future lookups in this chain traversal
+		for _, v := range dbVtxos {
+			cache[v.Outpoint.String()] = v
+		}
+	}
+
+	return result, nil
+}
+
 func (i *indexerService) GetVirtualTxs(
 	ctx context.Context, txids []string, page *Page,
 ) (*VirtualTxsResp, error) {

internal/core/application/service.go

@@ -321,6 +321,17 @@ func NewService(
 				return
 			}
 
+			// Calculate depth for new vtxos: max(parent depths) + 1
+			var maxDepth uint32
+			for _, v := range spentVtxos {
+				if v.Depth > maxDepth {
+					maxDepth = v.Depth
+				}
+			}
+			for i := range newVtxos {
+				newVtxos[i].Depth = maxDepth + 1
+			}
+
 			checkpointTxsByOutpoint := make(map[string]TxData)
 			for txid, tx := range offchainTx.CheckpointTxs {
 				// nolint

internal/core/application/utils.go

@@ -242,6 +242,7 @@ func getNewVtxosFromRound(round *domain.Round) []domain.Vtxo {
 				RootCommitmentTxid: round.CommitmentTxid,
 				CreatedAt:          createdAt,
 				ExpiresAt:          expireAt,
+				Depth:              0, // new vtxo from batch starts at depth 0
 			})
 		}
 	}

internal/core/domain/marker.go

@@ -0,0 +1,31 @@
+package domain
+
+// MarkerInterval is the depth interval at which markers are created.
+// VTXOs at depth 0, 100, 200, etc. create new markers.
+const MarkerInterval = 100
+
+// Marker represents a DAG traversal checkpoint created at regular depth intervals.
+// Markers enable compressed traversal of the VTXO chain by allowing jumps of
+// MarkerInterval depths instead of traversing each VTXO individually.
+type Marker struct {
+	// ID is the unique identifier for this marker (typically the VTXO outpoint)
+	ID string
+	// Depth is the chain depth at which this marker exists (0, 100, 200, ...)
+	Depth uint32
+	// ParentMarkerIDs is a list of marker IDs that this marker descends from
+	ParentMarkerIDs []string
+}
+
+// IsAtMarkerBoundary returns true if the given depth is at a marker boundary.
+func IsAtMarkerBoundary(depth uint32) bool {
+	return depth%MarkerInterval == 0
+}
+
+// SweptMarker records when a marker (and all VTXOs it covers) was swept.
+// This is an append-only table that enables efficient bulk sweep operations.
+type SweptMarker struct {
+	// MarkerID is the ID of the marker that was swept
+	MarkerID string
+	// SweptAt is the Unix timestamp (milliseconds) when the marker was swept
+	SweptAt int64
+}

internal/core/domain/marker_repo.go

@@ -0,0 +1,44 @@
+package domain
+
+import "context"
+
+type MarkerRepository interface {
+	// AddMarker creates or updates a marker
+	AddMarker(ctx context.Context, marker Marker) error
+	// GetMarker retrieves a marker by ID
+	GetMarker(ctx context.Context, id string) (*Marker, error)
+	// GetMarkersByDepth retrieves all markers at a specific depth
+	GetMarkersByDepth(ctx context.Context, depth uint32) ([]Marker, error)
+	// GetMarkersByDepthRange retrieves all markers within a depth range
+	GetMarkersByDepthRange(ctx context.Context, minDepth, maxDepth uint32) ([]Marker, error)
+	// GetMarkersByIds retrieves markers by their IDs
+	GetMarkersByIds(ctx context.Context, ids []string) ([]Marker, error)
+
+	// SweepMarker marks a marker as swept at the given timestamp
+	SweepMarker(ctx context.Context, markerID string, sweptAt int64) error
+	// SweepMarkerWithDescendants marks a marker and all its descendants as swept
+	// Returns the number of markers swept (including descendants)
+	SweepMarkerWithDescendants(ctx context.Context, markerID string, sweptAt int64) (int64, error)
+	// IsMarkerSwept checks if a marker has been swept
+	IsMarkerSwept(ctx context.Context, markerID string) (bool, error)
+	// GetSweptMarkers retrieves swept marker records for the given marker IDs
+	GetSweptMarkers(ctx context.Context, markerIDs []string) ([]SweptMarker, error)
+
+	// UpdateVtxoMarker updates the marker_id for a VTXO
+	UpdateVtxoMarker(ctx context.Context, outpoint Outpoint, markerID string) error
+	// GetVtxosByMarker retrieves all VTXOs associated with a marker
+	GetVtxosByMarker(ctx context.Context, markerID string) ([]Vtxo, error)
+	// SweepVtxosByMarker marks all VTXOs with the given marker_id as swept
+	// Returns the number of VTXOs that were swept (not already swept)
+	SweepVtxosByMarker(ctx context.Context, markerID string) (int64, error)
+
+	// Chain traversal methods for GetVtxoChain optimization
+	// GetVtxosByDepthRange retrieves VTXOs within a depth range
+	GetVtxosByDepthRange(ctx context.Context, minDepth, maxDepth uint32) ([]Vtxo, error)
+	// GetVtxosByArkTxid retrieves VTXOs created by a specific ark tx
+	GetVtxosByArkTxid(ctx context.Context, arkTxid string) ([]Vtxo, error)
+	// GetVtxoChainByMarkers retrieves VTXOs that have markers in the given list
+	GetVtxoChainByMarkers(ctx context.Context, markerIDs []string) ([]Vtxo, error)
+
+	Close()
+}