Taproot Assets

The rfqmath package provides fixed-point arithmetic implementations specifically designed for Request for Quote (RFQ) exchange rate calculations. It handles the mathematical precision required for financial operations within the Taproot Assets ecosystem.

For a high-level conceptual understanding of how RFQ, decimal display values, and price oracles interact, refer to the documentation at ../docs/rfq-and-decimal-display.md.

The Request for Quote (RFQ) protocol is designed for multi-hop, multi-asset payments across the Lightning Network. It enables trading partners to negotiate exchange rates and execute trustless trades without requiring on-chain transactions for every exchange.

Key capabilities include:

• Multi-asset support: Integrating arbitrary asset transfers with Bitcoin's payment infrastructure.
• Rate Negotiation: Coordinating systems to negotiate exchange rates between peers.
• Payment Transformation: Transforming payment flows to carry asset information.
• Non-invasive Integration: Using lnd's auxiliary interface system to extend Lightning capabilities without modifying the core protocol, ensuring compatibility with standard Lightning nodes.

The burn system interacts with several components in the Taproot Assets ecosystem:

• Universe Servers: Synchronize burn proofs across the network for global consistency.
• Supply Verifiers: Use burn data to maintain accurate total supply calculations.
• Monitoring Systems: Track burn events for analytics and alerting.
• Wallet Applications: Provide the UI for initiating and tracking burns.
• Internal Systems: Integrates with asset management (for balance/UTXO tracking), proof generation, the Bitcoin chain interface, and persistent databases.

The persistence layer for the universe/supplycommit state machine ensures that the process of creating and anchoring cryptographic commitments for asset supply changes (mints, burns, ignores) is durable across restarts. It manages the lifecycle of supply commitments by storing:

1. Operational State: The current state of the state machine for each asset group.
2. Historical Data: Details of past, successfully confirmed supply commitments.
3. Pending Transitions: Information about active state transitions and the specific supply update events being processed.
4. On-chain Anchors: Details of the Bitcoin transactions used to anchor commitments.

The RFQ implementation is organized into several specialized packages:

The RFQ subsystem is composed of several specialized packages. Use the following package locations to find specific logic:

• Business Logic: The core RFQ subsystem logic is contained within the rfq package.
• Arithmetic: For fixed-point arithmetic implementations used by RFQ, refer to the rfqmath package.
• Wire Messages: The actual wire message definitions are located in the rfqmsg package.
• RFQ gRPC API: The gRPC service definitions for RFQ methods are found in the taprpc/rfqrpc package.
• Price Oracle gRPC API: The gRPC service definitions for price oracle methods are found in the taprpc/priceoraclerpc package.

A Split Commitment tree is a temporary, third type of tree used specifically when assets are transferred with change (a split).

Unlike the persistent TAP and Asset commitment trees, the Split Commitment tree is independent and exists only within the root asset of a split operation. It serves as a proof structure showing how an asset was divided, enabling recipients to independently verify that the transfer was valid and that no assets were created or destroyed during the process.

The RFQ subsystem is a price-discovery and rate-binding protocol used to facilitate exchanges between Bitcoin (satoshis) and Taproot Assets within the Lightning Network. Because Lightning natively uses millisatoshis, RFQ allows two nodes to negotiate an exchange rate and cryptographically commit to it before an HTLC is executed.

Core capabilities:

• Asset → BTC (sell order): Pay a Lightning invoice using Taproot Assets.
• BTC → Asset (buy order): Receive a Lightning payment and credit assets.
• Rate binding: Uses Schnorr signatures on accepted quotes to prevent rate manipulation between negotiation and execution.
• Policy enforcement: Uses HTLC interceptors to reject payments that violate agreed terms.

The Merkle Sum Sparse Merkle Tree (MS-SMT) is the core data structure of the Taproot Assets protocol. Unlike standard Merkle trees, MS-SMTs commit to both data and numerical sums at every node.

This structure is used for three primary reasons:

1. Sum Preservation: It mathematically enforces conservation laws. For example, during an asset split, the sum of the output amounts must equal the input amount. This prevents asset inflation.
2. Efficient Proofs: The 'sparse' nature allows for both inclusion proofs (proving an asset exists) and exclusion proofs (proving an asset does not exist) without materializing the entire tree.
3. Scalability: The tree size grows logarithmically with the number of assets, allowing the protocol to scale to millions of assets.

The implementation uses a compacted representation that only stores non-empty nodes.

A Taproot Assets (tapd) wallet backup captures all active (unspent, non-burned) assets, including their proof files and key derivation information. There are three supported backup versions:

• Version 1 (BackupVersionOriginal): A full backup containing complete proof blobs stored as-is.
• Version 2 (BackupVersionStripped): A compact backup where blockchain-derivable fields are stripped to save space. It uses rehydration hints to reconstruct the full proof during import.
• Version 3 (BackupVersionOptimistic): The smallest backup format. It contains no proof data; instead, it stores asset metadata, key derivation info, and federation server URLs. Proofs are fetched from universe servers during the import process.

Split Commitments prove asset division by using locators as keys. A SplitLocator uniquely identifies an output by combining the OutputIndex, the AssetID, and the ScriptKey. The hash is computed using big-endian binary encoding for the index followed by the asset ID and the Schnorr-serialized script key.

// From commitment/split.go:78-87
func (l SplitLocator) Hash() [sha256.Size]byte {
    h := sha256.New()
    binary.Write(h, binary.BigEndian, l.OutputIndex)
    h.Write(l.AssetID[:])
    h.Write(l.ScriptKey.SchnorrSerialized())
    return *(*[sha256.Size]byte)(h.Sum(nil))
}