# lightninglabs/langchainbitcoin architecture

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

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

## Overview

##### Project Type and Purpose
- Type: Python-based full-stack library/toolkit for LangChain agents
- Purpose:
– Enable LLM agents to hold and spend on-chain and Lightning-network bitcoin
– Provide an HTTP client wrapper to traverse and pay for L402-protected APIs
– Integrate seamlessly with LND (Lightning Network Daemon) via gRPC and HTTP

##### File Structure
Top-level modules and their roles:
- lightning/lightning.py, protos/*.proto, protos/*_pb2*.py
– gRPC definitions and Python stubs for interacting with an LND node (invoice creation, payments, balance queries)
- L402/ (l402_api_chain.py, requests_l402.py)
– HTTP client wrapper around requests that handles LSATs and payment logic
– LangChain APIChain extension for L402-aware chains
- all_tools/api_tools/tools.py
– Generic API-tooling abstractions for LangChain
- all_tools/bitcoin_tools/tools.py
– Bitcoin-specific tool implementations (on-chain / LN send/receive, balance)
- utils.py, connect.py, main.py
– Configuration helpers, entry-point for launching agent executors
- Notebooks (.ipynb)
– Usage examples for agent workflows (LLM BitcoinTools, L402 traversal)
- .env.shared / .env.secret, requirements.txt
– Configuration and dependency management

##### README for Additional Insights
- Two main features – LLM Agent BitcoinTools & L402 HTTP API Traversal
- Shows dependencies on langchain, OpenAI function calls, requests, LND gRPC

##### Main Components & Their Interactions
A. LLM Agent Layer
– LangChain Agent + OpenAI LLM
– Invokes “tools” as function-call tools
B. Tools Layer
1. BitcoinTools Module
- Interfaces: LndNode / LightningNode classes
- Uses gRPC stubs (protos/*.py) to call LND for on-chain & LN ops
2. API Tools & L402 APIChain Module
- RequestsL402Wrapper: HTTP client with LSAT handling
- L402APIChain: LangChain wrapper that auto-pays on 402 responses
C. Protocol Layer
– gRPC endpoint: LND node (Lightning Network Daemon)
– HTTP endpoint: External APIs requiring L402 authentication
D. External Services
– Bitcoin Network (via LND)
– Lightning Network
– Third-party paid APIs behind L402

- Agent → Tools Layer → (gRPC → LND)
- Agent → Tools Layer → (HTTP → L402 API)
- Tools Layer ↔ Protocol Layer for payment negotiation and retries

##### Architectural Patterns & Design Principles
- Separation of Concerns:
– Agent logic, tool abstractions, protocol implementation are in distinct modules
- Adapter Pattern:
– requests_l402.py adapts standard HTTP client to L402 payments
- Façade/Wrapper Pattern:
– BitcoinTools façade over gRPC stubs, hiding protocol details
- Pluggability:
– all_tools package groups concrete tool implementations for LangChain
- Configuration via environment (.env.shared / .env.secret)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% LLM Agent Layer
    subgraph "LLM Agent Layer"
        direction TB
        AgentMain["main.py"]:::config
        AgentConnect["connect.py"]:::config
        NB1["llm_bitcoin_tools.ipynb"]:::config
        NB2["langchain_L402_agent.ipynb"]:::config
    end

    %% Tools Layer
    subgraph "Tools Layer"
        direction TB
        subgraph "BitcoinTools Module"
            direction TB
            BTCTools["all_tools/bitcoin_tools/tools.py"]:::core
            Lightning["lightning/lightning.py"]:::core
            subgraph "gRPC Stubs"
                direction TB
                Proto1["protos/lightning.proto"]:::core
                Proto2["protos/lightning_pb2.py"]:::core
                Proto3["protos/lightning_pb2_grpc.py"]:::core
                Proto4["protos/router.proto"]:::core
                Proto5["protos/router_pb2.py"]:::core
                Proto6["protos/router_pb2_grpc.py"]:::core
            end
        end
        subgraph "API Tools & L402 Module"
            direction TB
            APITools["all_tools/api_tools/tools.py"]:::core
            L402Req["L402/requests_l402.py"]:::core
            L402Chain["L402/l402_api_chain.py"]:::core
        end
    end

    %% Configuration & Entry Points
    subgraph "Configuration & Entry Points"
        direction TB
        EnvShared[".env.shared"]:::config
        EnvSecret[".env.secret"]:::config
        Utils["utils.py"]:::config
        ReqTxt["requirements.txt"]:::config
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        GRPC["gRPC Endpoint (LND)"]:::protocol
        HTTP["HTTP Endpoint (L402 APIs)"]:::protocol
    end

    %% External Services
    subgraph "External Services"
        direction TB
        BitcoinNet["Bitcoin Network"]:::external
        LightningNet["Lightning Network"]:::external
        L402APIs["Third-party Paid APIs"]:::external
    end

    %% Data Flows
    AgentMain -->|"invokes tools"| BTCTools
    AgentMain -->|"invokes tools"| L402Chain
    BTCTools -->|"gRPC calls"| GRPC
    GRPC -->|"settlement"| LightningNet
    BTCTools -->|"on-chain via gRPC"| BitcoinNet
    L402Chain -->|"HTTP calls"| HTTP
    HTTP -->|"requires LSAT"| L402APIs
    L402Req -.->|"on 402 retry"| HTTP

    %% Click Events
    click AgentMain "https://github.com/lightninglabs/langchainbitcoin/blob/main/main.py"
    click AgentConnect "https://github.com/lightninglabs/langchainbitcoin/blob/main/connect.py"
    click NB1 "https://github.com/lightninglabs/langchainbitcoin/blob/main/llm_bitcoin_tools.ipynb"
    click NB2 "https://github.com/lightninglabs/langchainbitcoin/blob/main/langchain_L402_agent.ipynb"
    click BTCTools "https://github.com/lightninglabs/langchainbitcoin/blob/main/all_tools/bitcoin_tools/tools.py"
    click Lightning "https://github.com/lightninglabs/langchainbitcoin/blob/main/lightning/lightning.py"
    click Proto1 "https://github.com/lightninglabs/langchainbitcoin/blob/main/protos/lightning.proto"
    click Proto2 "https://github.com/lightninglabs/langchainbitcoin/blob/main/protos/lightning_pb2.py"
    click Proto3 "https://github.com/lightninglabs/langchainbitcoin/blob/main/protos/lightning_pb2_grpc.py"
    click Proto4 "https://github.com/lightninglabs/langchainbitcoin/blob/main/protos/router.proto"
    click Proto5 "https://github.com/lightninglabs/langchainbitcoin/blob/main/protos/router_pb2.py"
    click Proto6 "https://github.com/lightninglabs/langchainbitcoin/blob/main/protos/router_pb2_grpc.py"
    click APITools "https://github.com/lightninglabs/langchainbitcoin/blob/main/all_tools/api_tools/tools.py"
    click L402Req "https://github.com/lightninglabs/langchainbitcoin/blob/main/L402/requests_l402.py"
    click L402Chain "https://github.com/lightninglabs/langchainbitcoin/blob/main/L402/l402_api_chain.py"
    click EnvShared "https://github.com/lightninglabs/langchainbitcoin/blob/main/.env.shared"
    click EnvSecret "https://github.com/lightninglabs/langchainbitcoin/blob/main/.env.secret"
    click Utils "https://github.com/lightninglabs/langchainbitcoin/blob/main/utils.py"
    click ReqTxt "https://github.com/lightninglabs/langchainbitcoin/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef external fill:#D6F5D6,stroke:#28a745,stroke-width:1px
    classDef config fill:#FFE5B4,stroke:#d2691e,stroke-width:1px
    classDef protocol fill:#F0F0F0,stroke:#999999,stroke-width:1px
```
