# lightninglabs/taproot-assets architecture

> Architecture diagram of the GitHub repository lightninglabs/taproot-assets, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lightninglabs/taproot-assets
- Repository: https://github.com/lightninglabs/taproot-assets

## Overview

##### Project Type and Purpose
- This is a full-stack, single-binary daemon (`tapd`) plus companion CLI (`tapcli`) implementing the Taproot Assets Protocol on Bitcoin.
- Purpose: mint, transfer, burn, and verify “Taproot Assets” using LND’s signing/Taproot wallet, off-chain witness data, and local state storage. It exposes both gRPC and REST interfaces, and integrates with Bitcoin and LND.

##### File Structure
- Top-level binaries:
- cmd/tapd (daemon)
- cmd/tapcli (CLI)
- cmd/merge-sql-schemas
- Core domain packages (asset, commitment, proof, rfq, universe, tapscript, tapchannel, etc.).
- Storage: tapdb with SQLC-generated code, supports Postgres/SQLite.
- RPC layer: taprpc contains .proto definitions and generated gRPC+REST gateway.
- LND integration: lndservices package for calling LND’s gRPC (chainrpc, walletrpc, signrpc).
- Monitoring: monitoring collects Prometheus metrics.
- Integration tests: itest directory with harnesses.
- Dev/CI: Dockerfiles, GitHub Actions, Makefile, scripts.

##### README Insights
- Architecture summary: Bitcoin ←→ LND ←→ Taproot Assets (tapd).
- Components: tapd (daemon), tapcli (CLI), gRPC & REST endpoints, LND backend, Bitcoin network.
- External federation: “universes” are peer tapd instances syncing asset universes.

a. Main Components
- Bitcoin Network (full node)
- LND Node (gRPC interface: chainrpc, signrpc, walletrpc)
- Taproot-Assets Daemon (tapd)
– Service Layer: modules for asset mgmt, commitments, proofs, RFQ, universe sync
– Storage Layer: tapdb (Postgres/SQLite)
– API Layer:
· gRPC Server (port 10029)
· REST Gateway (port 8089)
– Monitoring (Prometheus exporter)
- CLI Client (tapcli)
- Universe Federation Peers (other tapd instances)
b. Relationships & Data Flows
1. tapcli → (gRPC/REST) → tapd
2. tapd → (gRPC) → LND for on-chain wallet operations & signatures
3. tapd ↔ Bitcoin Network via LND’s chainrpc
4. tapd ↔ tapdb for persisting assets, commitments, proofs, macaroon/session data
5. tapd ↔ Universe Peers using custom peer-to-peer sync protocols (federation)
6. tapd → Prometheus for metrics
c. Architectural Patterns & Principles
- Layered/Hexagonal: clearly separated API, domain logic, infrastructure
- Domain-driven: each domain (asset, proof, universe, rfq) encapsulated in its package
- SQLC code generation for type-safe queries
- gRPC + REST Gateway for polyglot integration
- Test harnesses (unit, integration) for domain services
d. Key Technologies & Frameworks
- Go modules (go.mod), Docker
- gRPC (google.golang.org/grpc) + grpc-gateway (REST)
- SQLC for DB access (Postgres & SQLite)
- Prometheus for monitoring
- macaroons for authentication
- LND’s RPCs

##### Detail
- Drill down if necessary: e.g., inside domain, show “asset.Mint”, “commitment.Taproot”, “proof.Courier” modules
- SQL migrations and codegen as part of the storage infrastructure

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        tapcli["CLI Client (tapcli)"]:::client
        restclient["REST Client"]:::client
    end

    %% Server Layer
    subgraph "Taproot-Assets Daemon (tapd)" 
        direction TB
        %% API Layer
        subgraph "API Layer"
            direction TB
            grpc["gRPC Server (port 10029)"]:::server
            restgw["REST Gateway (port 8089)"]:::server
        end

        %% Domain Services Layer
        subgraph "Domain Services"
            direction TB
            asset["Asset Management"]:::server
            commitment["Commitments"]:::server
            proof["Proofs"]:::server
            rfq["RFQ"]:::server
            universe["Universe Federation & Sync"]:::server
            tapscript["TapScript Handling"]:::server
            tapchannel["Tap Channels"]:::server
            tapsend["TapSend"]:::server
            authmailbox["Auth Mailbox"]:::server
        end

        %% Infrastructure Layer
        subgraph "Infrastructure"
            direction TB
            lndservices["LND Integration (lndservices)"]:::server
            tapdb["tapdb Storage"]:::db
            monitoring["Monitoring (Prometheus)"]:::server
            config["Config & Bootstrap"]:::server
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        bitcoin["Bitcoin Network"]:::external
        lnd["LND Node"]:::external
        peers["Universe Federation Peers"]:::external
        prometheus["Prometheus"]:::external
    end

    %% Dev Tools
    subgraph "Utilities & Tools"
        direction TB
        merge["Merge SQL Schemas Tool"]:::server
        itests["Integration Tests (itest)"]:::server
        scripts["Dev/CI Scripts"]:::server
    end

    %% Connections
    tapcli -->|"gRPC/REST"| grpc
    restclient -->|"REST"| restgw

    grpc -->|"Call SignRPC, WalletRPC, ChainRPC"| lndservices
    restgw -->|"Invoke Domain APIs"| asset

    asset -->|"Store/Retrieve"| tapdb
    commitment -->|"Store/Retrieve"| tapdb
    proof -->|"Store/Retrieve"| tapdb
    rfq -->|"Store/Retrieve"| tapdb
    universe -->|"Store/Retrieve"| tapdb
    tapscript -->|"Store/Retrieve"| tapdb
    tapchannel -->|"Store/Retrieve"| tapdb
    tapsend -->|"Store/Retrieve"| tapdb
    authmailbox -->|"Store/Retrieve"| tapdb

    universe -->|"Peer Sync"| peers
    lndservices -->|"Chain Access"| lnd
    lnd -->|"Bitcoin Data"| bitcoin

    monitoring -->|"Export Metrics"| prometheus

    config --> grpc
    config --> restgw

    merge --> tapdb
    itests --> grpc
    itests --> universe
    scripts --> merge

    %% Click Events
    click tapd "https://github.com/lightninglabs/taproot-assets/blob/main/cmd/tapd/main.go"
    click tapcli "https://github.com/lightninglabs/taproot-assets/blob/main/cmd/tapcli/main.go"
    click merge "https://github.com/lightninglabs/taproot-assets/blob/main/cmd/merge-sql-schemas/main.go"
    click asset "https://github.com/lightninglabs/taproot-assets/blob/main/asset/asset.go"
    click commitment "https://github.com/lightninglabs/taproot-assets/blob/main/commitment/commitment.go"
    click proof "https://github.com/lightninglabs/taproot-assets/blob/main/proof/proof.go"
    click rfq "https://github.com/lightninglabs/taproot-assets/blob/main/rfq/manager.go"
    click universe "https://github.com/lightninglabs/taproot-assets/blob/main/universe/federation.go"
    click tapscript "https://github.com/lightninglabs/taproot-assets/blob/main/tapscript/script.go"
    click tapchannel "https://github.com/lightninglabs/taproot-assets/blob/main/tapchannel/commitment.go"
    click tapsend "https://github.com/lightninglabs/taproot-assets/blob/main/tapsend/send.go"
    click authmailbox "https://github.com/lightninglabs/taproot-assets/blob/main/authmailbox/server.go"
    click tapdb "https://github.com/lightninglabs/taproot-assets/blob/main/tapdb/assets_store.go"
    click tapdb_sqlc "https://github.com/lightninglabs/taproot-assets/blob/main/tapdb/sqlc/db.go"
    click grpc "https://github.com/lightninglabs/taproot-assets/blob/main/taprpc/rpcserver.go"
    click restgw "https://github.com/lightninglabs/taproot-assets/blob/main/taprpc/rpcserver.go"
    click lndservices "https://github.com/lightninglabs/taproot-assets/blob/main/lndservices/chain_bridge.go"
    click monitoring "https://github.com/lightninglabs/taproot-assets/blob/main/monitoring/prometheus.go"
    click config "https://github.com/lightninglabs/taproot-assets/blob/main/tapcfg/config.go"
    click itests "https://github.com/lightninglabs/taproot-assets/blob/main/itest/tapd_harness.go"
    click scripts "https://github.com/lightninglabs/taproot-assets/blob/main/scripts/check-rest-annotations.sh"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#D3D3D3,stroke:#333,stroke-width:1px
```
