> For the complete documentation index, see [llms.txt](https://layerbtc.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://layerbtc.gitbook.io/docs/architecture-overview.md).

# Architecture Overview

LayerBTC is built as a three-layer stack that sits entirely above the Bitcoin base layer, yet anchors every critical state change back to on-chain Bitcoin.\
At a glance:<br>

### System Layers

| Layer                    | Role                                                                                                  | Key Components                                                                                                                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Application Layer        | Interfaces where end-users interact—wallets, merchant plugins, IoT endpoints.                         | REST / gRPC clients, UI widgets, CLI tooling                                                                                                                                                 |
| LayerBTC Service Layer   | Modular services exposing high-level APIs. Runs off-chain but continuously commits proofs to Bitcoin. | <p>• Assets Service (Taproot Asset node)</p><p>• Payments Service (Lightning++ daemon)</p><p>• Vault Service (policy engine + watchtowers)</p><p>• Dev-Hub (template registry, CI hooks)</p> |
| Bitcoin Settlement Layer | Immutable source of truth. All channels and asset commitments ultimately resolve to the UTXO set.     | Taproot outputs, Lightning channels, PSBTs                                                                                                                                                   |

### Data Flow

Asset Issuance

* Issuer calls POST /assets/mint → Assets Service constructs Taproot Asset commitment → commits to a Taproot output on-chain.
* Asset proof is broadcast to peer indexers and cached for wallets.

Instant Payment

* Payer’s wallet uses Payments SDK to request a route (queryRoute) and open/adjust channels if liquidity is low.
* Payment travels across Lightning; atomic swap of BTC ↔ Taproot Asset handled via HTLC-to-PTLC adaptor.
* Pre-image settlement recorded in channel state; periodic channel snapshots are checkpointed to the chain.

Vault Movement / Recovery

* Vault Service enforces n-of-m MuSig2 policy with optional timelocks.
* A successful spend assembles a composite Schnorr signature, producing a PSBT.
* PSBT is finalized and broadcast; watchtowers monitor for revoked states and respond if needed.

### Reference Transaction Lifecycles

| Flow                    | Confirmations on L1                                  | Latency to User            | Privacy Hooks                 |
| ----------------------- | ---------------------------------------------------- | -------------------------- | ----------------------------- |
| Lightning Payment (BTC) | Deferred until channel close                         | < 1 s                      | Route blinding, onion payload |
| Asset Transfer (L2)     | Deferred; Taproot proof piggy-backs on channel close | < 1 s                      | Silent Payments optional      |
| Vault Withdrawal        | 1 – 3 (depends on policy)                            | Tens of minutes (on-chain) | CoinJoin on sweep             |

### Upgrade & Compatibility Path

* Versioned RPCs — Breaking changes surface via semantic version tags; old clients continue to operate in read-only mode.
* Soft-fork-friendly — The design relies only on existing Taproot/Schnorr functionality; future Bitcoin soft forks (e.g., APO) can be adopted opportunistically, not mandatorily.
* Graceful Degradation — If a service layer node goes offline, wallets can fall back to direct PSBT workflows or raw Lightning RPC to keep funds accessible.

This layered, commitment-driven architecture lets LayerBTC expose web-level UX while inheriting Bitcoin’s final settlement guarantees. The next section dives deeper into each core module and its internal mechanics.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://layerbtc.gitbook.io/docs/architecture-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.