From 45d73ed5d46c86919578bb5af827a16309c92564 Mon Sep 17 00:00:00 2001
From: Boris Nagaev <bnagaev@gmail.com>
Date: Tue, 16 Sep 2025 00:48:56 -0300
Subject: [PATCH] README, docs: add static-ins and instant-outs

---
 README.md            |  2 ++
 docs/architecture.md | 46 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/README.md b/README.md
index 337f1da4..912df86f 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,8 @@ bitcoin into and out of the Lightning Network.
 - Automated channel balancing
 - Privacy-forward non-custodial swaps
 - Opportunistic transaction batching to save on fees
+- Instant Loop-Outs for faster off-chain to on-chain swaps
+- Static, reusable addresses for Loop-Ins
 - Progress monitoring of in-flight swaps
 
 ## Use Cases
diff --git a/docs/architecture.md b/docs/architecture.md
index 996f36c9..5762ef7f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -65,3 +65,49 @@ Phases:
            |                    |              |              |                  |               |
            '--------------------'              '--------------'                  '---------------'
 ```
+
+### Standard Loop-In (on -> off-chain)
+
+The reverse of a Loop-Out. The client sends funds to an on-chain HTLC with a
+2-of-2 MuSig2 keyspend path. Once the server detects that the HTLC transaction
+is confirmed, it pays the Lightning invoice provided by the client to "loop in"
+the funds to their node's channels and sweeps the HTLC. The client cooperates
+with the server to cosign the sweep transaction to save on onchain fees.
+
+### Instant Loop-Out
+
+A faster, more efficient Loop-Out that prioritizes a cooperative path, built on
+**Reservations** (on-chain UTXOs controlled by a 2-of-2 MuSig2 key between the
+client and server).
+
+1.  **Cooperative Path ("Sweepless Sweep"):** After the client pays the
+    off-chain swap invoice, the client and server cooperatively sign a
+    transaction that spends the reservation UTXO directly to the client's final
+    destination address. This avoids publishing an HTLC, saving fees and chain
+    space.
+
+2.  **Fallback Path:** If the cooperative path fails, the system falls back to
+    creating a standard on-chain HTLC from the reservation UTXO, which is then
+    swept by the client. This ensures the swap remains non-custodial.
+
+### Static Address (for Loop-In)
+
+Provides a permanent, reusable on-chain address for receiving funds that can
+then be swapped for an off-chain Lightning payment.
+
+-   **Address Type:** The address is a P2TR (Taproot) output with two spending
+    paths:
+    1.  **Keyspend Path (Cooperative):** The internal key is a 2-of-2 MuSig2
+        aggregate key held by the client and server. This path is used to
+        cooperatively sign transactions for performing a Loop-In or withdrawing
+        funds.
+    2.  **Scriptspend Path (Timeout):** A tapleaf contains a script that allows
+        the client to unilaterally sweep their funds after a CSV timeout. This
+        is a safety mechanism ensuring the client never loses access to their
+        deposits.
+
+-   **Loop-In Flow:** When a user wants to loop in funds from this address, the
+    client and server use the cooperative keyspend path to create and sign an
+    HTLC transaction, which then follows a standard Loop-In flow. When the
+    client gets the LN payment, they cooperate with the server to sweep the
+    deposit directly to the server's wallet instead of publishing the HTLC tx.