# 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>