Merge pull request #1792 from Roasbeef/supply-verify-logging

universe/supplyverifier: add logging and readme

Author: Roasbeef

supplysync_rpc.go

@@ -128,6 +128,12 @@ func (r *RpcSupplySync) FetchSupplyCommit(ctx context.Context,
 		return zero, fmt.Errorf("unable to unwrap group key: %w", err)
 	}
 
+	srvrLog.Infof("[RpcSupplySync.FetchSupplyCommit]: fetching supply "+
+		"commitment from remote server "+
+		"(server_addr=%s, asset=%s, spent_outpoint=%v)",
+		r.serverAddr.HostStr(), assetSpec.String(),
+		spentCommitOutpoint.IsSome())
+
 	req := &unirpc.FetchSupplyCommitRequest{
 		GroupKey: &unirpc.FetchSupplyCommitRequest_GroupKeyBytes{
 			GroupKeyBytes: groupKey.SerializeCompressed(),
@@ -140,6 +146,8 @@ func (r *RpcSupplySync) FetchSupplyCommit(ctx context.Context,
 	// If a spent commit outpoint is provided, use that to locate the next
 	// supply commitment.
 	spentCommitOutpoint.WhenSome(func(outpoint wire.OutPoint) {
+		srvrLog.Debugf("Using spent commitment outpoint as locator: %s",
+			outpoint.String())
 		// nolint: lll
 		req.Locator = &unirpc.FetchSupplyCommitRequest_SpentCommitOutpoint{
 			SpentCommitOutpoint: &taprpc.OutPoint{
@@ -222,7 +230,7 @@ func (r *RpcSupplySync) FetchSupplyCommit(ctx context.Context,
 			"root: %w", err)
 	}
 
-	return supplycommit.FetchSupplyCommitResult{
+	result := supplycommit.FetchSupplyCommitResult{
 		RootCommitment:  *rootCommitment,
 		SupplyLeaves:    *supplyLeaves,
 		ChainProof:      chainProof,
@@ -233,7 +241,15 @@ func (r *RpcSupplySync) FetchSupplyCommit(ctx context.Context,
 		IgnoreSubtreeRoot:   ignoreSubtreeRoot,
 
 		SpentCommitmentOutpoint: respSpentCommitOutpoint,
-	}, nil
+	}
+
+	srvrLog.Infof("[RpcSupplySync.FetchSupplyCommit]: succeeded in "+
+		"fetching supply commitment "+
+		"(server_addr=%s, asset=%s, supply_tree_root_hash=%x)",
+		r.serverAddr.HostStr(), assetSpec.String(),
+		rootCommitment.SupplyRoot.NodeHash())
+
+	return result, nil
 }
 
 // Close closes the RPC connection to the universe server.

universe/supplyverifier/README.md

@@ -0,0 +1,275 @@
+# Universe Supply Verifier State Machine
+
+This package implements a state machine responsible for verifying and tracking
+on-chain supply commitments for Taproot Assets created by other nodes in the
+network. It acts as the counterpart to the supply commitment state machine,
+ensuring the integrity and consistency of supply data across the distributed
+Universe network.
+
+## Rationale and Purpose
+
+While the supply commitment state machine creates and publishes supply commitments
+for assets where a node owns the delegation key, the supply verifier ensures that
+commitments created by other nodes are properly validated and tracked. This
+creates a trustless, verifiable system for tracking asset supply across the
+entire network.
+
+The verifier's primary objectives are:
+
+1. **Monitor Pre-commitments and Supply Commitments:** Track unspent outputs that
+   represent either initial pre-commitment outputs from asset issuance or existing
+   supply commitment outputs, watching for when they are spent.
+
+2. **Detect Supply Updates:** When a watched output is spent, recognize this as a
+   signal that a new supply commitment has been created and needs to be retrieved.
+
+3. **Retrieve and Verify:** Pull the new supply commitment from Universe servers,
+   including all associated supply leaves (mints, burns, ignores) and cryptographic
+   proofs.
+
+4. **Validate Chain Integrity:** Ensure each new commitment properly spends the
+   previous commitment (or pre-commitments for initial commitments), maintaining
+   an unbroken chain of commitments anchored to the blockchain.
+
+5. **Persist Verified State:** Store verified commitments and their associated
+   supply trees locally, enabling future verification of incremental updates and
+   serving as a foundation for the next verification cycle.
+
+## Scope
+
+The verifier manages the complete lifecycle of supply commitment verification for
+assets where the local node does not control the delegation key. Each asset group
+has its own dedicated state machine instance that handles:
+
+* Monitoring blockchain outputs for spend notifications
+* Coordinating with Universe servers to retrieve new commitments
+* Verifying the cryptographic integrity of supply commitments and leaves
+* Validating the chain of commitments back to asset issuance
+* Managing the transition between monitoring and syncing states
+* Persisting verified commitment data and supply trees
+
+The verifier does *not* handle:
+
+* Creating new supply commitments (handled by the supply commitment state machine)
+* Managing assets where the local node owns the delegation key
+* Direct interaction with asset issuance or transfer operations
+* Serving supply proofs to external clients (handled by Universe server components)
+
+## Architecture Overview
+
+The supply verifier consists of several cooperating components:
+
+### Core Components
+
+**Verifier (`verifier.go`):** The core verification engine that validates supply
+commitments against cryptographic proofs, ensures proper spending of previous
+commitments, and verifies individual supply leaves (mints, burns, ignores).
+
+**State Machine (`states.go`, `transitions.go`):** Implements the verification
+lifecycle through a series of well-defined states, managing the flow from output
+monitoring through commitment retrieval to verification and persistence.
+
+**Manager (`manager.go`):** Orchestrates multiple state machine instances, one per
+asset group, handling initialization, lifecycle management, and coordination with
+Universe sync events.
+
+**Syncer (`syncer.go`):** Manages communication with remote Universe servers to
+retrieve supply commitments, handling parallel fetches and error recovery across
+multiple servers.
+
+### Supporting Components
+
+**Environment (`env.go`):** Encapsulates all dependencies required by the state
+machine, including chain access, supply commitment storage, tree management, and
+Universe server communication.
+
+**Events (`events.go`):** Defines the event types that drive state transitions,
+including initialization, output spend notifications, and sync triggers.
+
+## State Machine Overview
+
+The verifier state machine manages the verification lifecycle through three primary
+states, transitioning based on blockchain events and sync operations. Unlike the
+commitment state machine which operates on a timer, the verifier is entirely
+event-driven, responding to on-chain activity.
+
+### States and Transitions
+
+```mermaid
+stateDiagram-v2
+    direction TB
+    
+    [*] --> InitState: Start
+    
+    InitState --> WatchOutputsState: InitEvent
+    
+    WatchOutputsState --> SyncVerifyState: SpendEvent<br/>(output spent)
+    
+    SyncVerifyState --> WatchOutputsState: SyncVerifyEvent<br/>(commitment verified)
+    
+    SyncVerifyState --> SyncVerifyState: SyncVerifyEvent<br/>(already synced)
+    
+    note right of InitState
+        Fetches pre-commitments
+        and latest commitment
+        from local DB
+    end note
+    
+    note right of WatchOutputsState
+        Registers spend notifications
+        for pre-commitments and
+        current supply commitment
+    end note
+    
+    note right of SyncVerifyState
+        Retrieves new commitment
+        from Universe servers,
+        verifies, and stores
+    end note
+```
+
+### State Descriptions
+
+**InitState:** The entry point for each state machine instance. Queries the local
+database for any unspent pre-commitment outputs (from asset issuance transactions)
+and the latest verified supply commitment for the asset group. This state ensures
+the verifier has the necessary starting context before beginning active monitoring.
+If neither pre-commitments nor an existing commitment are found, the state machine
+cannot proceed, as there would be nothing to watch.
+
+**WatchOutputsState:** The primary monitoring state where the verifier spends most
+of its time. Registers with the chain notification system to watch for spends of
+specific outputs: all known pre-commitment outputs and the current supply commitment
+output (if one exists). When any watched output is spent, this indicates a new
+supply commitment transaction has been broadcast. The state machine captures the
+spend details, including the spending transaction and block height, then transitions
+to retrieve and verify the new commitment.
+
+**SyncVerifyState:** The active verification state triggered by output spend
+detection. First checks if the commitment has already been processed (avoiding
+duplicate work), then retrieves the commitment from configured Universe servers.
+The retrieval includes the full commitment transaction, all supply leaves (mints,
+burns, ignores), and the cryptographic proofs linking them. Once retrieved, the
+verifier validates the entire structure: checking that previous outputs were properly
+spent, verifying leaf signatures and proofs, and ensuring the merkle tree roots
+match. Successfully verified commitments are stored in the database along with their
+supply trees, becoming the new "latest commitment" for future monitoring cycles.
+
+### Timing and Synchronization
+
+The verifier implements intelligent timing to handle the inherent race condition
+between commitment creation and Universe server availability. When a spend is
+detected, the verifier waits a configurable delay (default 5 seconds) before
+attempting to sync, giving the commitment creator time to publish to Universe
+servers. This delay is optimized based on how long the output was watched,
+reducing unnecessary waiting when possible.
+
+## Database Persistence
+
+The verifier relies on several database interfaces for persistence and state
+management:
+
+### SupplyCommitView
+
+Provides access to supply commitments and pre-commitments:
+- `FetchLatestCommitment`: Retrieves the most recent verified commitment
+- `FetchCommitmentByOutpoint`: Checks for existing commitments at specific outpoints
+- `FetchCommitmentBySpentOutpoint`: Finds commitments that spend specific outputs
+- `UnspentPrecommits`: Lists all unspent pre-commitment outputs for monitoring
+- `InsertSupplyCommit`: Stores newly verified commitments
+
+### SupplyTreeView
+
+Manages the merkle tree structures that represent supply state:
+- `FetchSupplyTrees`: Retrieves the current root tree and subtrees
+- Tree updates are performed during commitment verification to maintain consistency
+
+### Persistence Strategy
+
+The verifier maintains minimal persistent state, as most information can be
+reconstructed from the blockchain and stored commitments. The key persisted
+elements are:
+
+1. **Verified Commitments:** Each successfully verified commitment is stored with
+   its transaction details, merkle root, and relationship to previous commitments.
+
+2. **Supply Trees:** The merkle tree structures representing the supply state at
+   each commitment point, enabling efficient incremental verification.
+
+3. **Pre-commitment Tracking:** Records of which pre-commitment outputs have been
+   spent, preventing double-spending in the commitment chain.
+
+Unlike the commitment creator, the verifier does not need to persist state machine
+state itself, as it can always reconstruct its position from the latest verified
+commitment.
+
+## Integration and Dependencies
+
+The supply verifier integrates with several system components:
+
+### Chain Bridge
+
+Provides blockchain access for:
+- Header verification for proof-of-work validation
+- Transaction confirmation monitoring
+- Block height tracking for spend notifications
+
+### Universe Federation
+
+Coordinates with Universe servers to:
+- Retrieve supply commitments from multiple sources
+- Handle server failures gracefully with parallel fetching
+- Maintain consistency across the distributed network
+
+### Asset Management
+
+Interfaces with asset tracking systems to:
+- Determine which assets require verification (those without local delegation keys)
+- Access asset metadata including delegation keys for signature verification
+- Validate asset group membership for supply leaves
+
+### Event System
+
+Responds to system events including:
+- Asset issuance notifications to begin tracking new assets
+- Universe sync events that may indicate new commitments
+- Chain notifications for output spend detection
+
+## Error Handling and Recovery
+
+The verifier implements robust error handling to ensure verification integrity:
+
+**Verification Failures:** If a commitment fails verification, it is rejected and
+not stored. The verifier continues watching the previously verified commitment,
+ensuring only valid commitments enter the local database.
+
+**Network Failures:** When Universe servers are unreachable, the verifier retries
+with exponential backoff. Multiple servers are queried in parallel, requiring only
+one successful response to proceed.
+
+**State Recovery:** After system restarts, each state machine reconstructs its
+state from the latest verified commitment in the database, automatically resuming
+monitoring without loss of data.
+
+**Chain Reorganizations:** The verifier handles blockchain reorganizations by
+re-verifying commitments when their confirming blocks are reorganized away,
+maintaining consistency with the canonical chain.
+
+## Security Considerations
+
+The supply verifier enforces several security properties:
+
+1. **Cryptographic Verification:** All supply leaves must have valid signatures
+   from the delegation key holder, preventing unauthorized supply manipulation.
+
+2. **Chain Integrity:** Each commitment must properly spend previous commitments
+   or pre-commitments, creating an immutable audit trail.
+
+3. **Proof Validation:** All merkle proofs are verified against their claimed roots,
+   ensuring data integrity.
+
+4. **Byzantine Fault Tolerance:** By querying multiple Universe servers and requiring
+   only one valid response, the system tolerates malicious or faulty servers.
+
+5. **No Trust Required:** The verifier independently validates all data against
+   on-chain anchors, requiring no trust in Universe servers or other nodes.

universe/supplyverifier/env.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/btcsuite/btcd/wire"
+	"github.com/btcsuite/btclog/v2"
 	"github.com/lightninglabs/lndclient"
 	"github.com/lightninglabs/taproot-assets/asset"
 	"github.com/lightninglabs/taproot-assets/fn"
@@ -96,6 +97,9 @@ type Environment struct {
 	// that we're maintaining a supply commit for.
 	AssetSpec asset.Specifier
 
+	// AssetLog is the asset-specific logger for this state machine.
+	AssetLog btclog.Logger
+
 	// Chain is our access to the current main chain.
 	Chain tapgarden.ChainBridge
 
@@ -138,3 +142,14 @@ type Environment struct {
 func (e *Environment) Name() string {
 	return fmt.Sprintf("supply_verifier(%s)", e.AssetSpec.String())
 }
+
+// Logger returns the logger for the environment. If a logger is configured in
+// the environment configuration, it returns that logger. Otherwise, it returns
+// the package-level logger with an asset-specific prefix.
+func (e *Environment) Logger() btclog.Logger {
+	if e.AssetLog != nil {
+		return e.AssetLog
+	}
+
+	return NewAssetLogger(e.AssetSpec.String())
+}

universe/supplyverifier/log.go

@@ -1,6 +1,8 @@
 package supplyverifier
 
 import (
+	"fmt"
+
 	"github.com/btcsuite/btclog/v2"
 )
 
@@ -24,3 +26,10 @@ func DisableLog() {
 func UseLogger(logger btclog.Logger) {
 	log = logger
 }
+
+// NewAssetLogger creates a new prefixed logger for a specific asset. This
+// logger will automatically include the asset specifier in all log messages,
+// using the format "SupplyVerifier(asset): message".
+func NewAssetLogger(assetSpec string) btclog.Logger {
+	return log.WithPrefix(fmt.Sprintf("SupplyVerifier(%v): ", assetSpec))
+}