Updated README and architecture.md with Gemini, added AGENTS.md #1005
Conversation
hieblmi
left a comment
hieblmi
left a comment
There was a problem hiding this comment.
LGTM, thanks for updating the notes.
I read through it and like how concise it is.
Noted a few things that could be improved.
docs/architecture.md
Outdated
| ### Static Address (for Loop-In) | ||
|
|
||
| Provides a permanent, reusable on-chain address for receiving funds that can | ||
| then be looped into Lightning. |
There was a problem hiding this comment.
...can then be swapped for an off-chain lightning payment.
AGENTS.md
Outdated
| ### Project Summary: Lightning Loop | ||
|
|
||
| **1. Core Purpose:** | ||
| Lightning Loop is a non-custodial service from Lightning Labs for bridging the Bitcoin mainnet (on-chain) and the Lightning Network (off-chain). It enables users to rebalance their channels—moving funds into or out of Lightning—without the need for closing and reopening them. The system is architected to be non-custodial, using atomic swaps to ensure neither the user nor the server can lose funds. |
There was a problem hiding this comment.
...their channels by moving funds into or out of Lightning - without the need for closing and...
AGENTS.md
Outdated
|
|
||
| * **Finite State Machines (FSM):** The core logic for managing swaps is built around a robust FSM pattern (`fsm/`). Each swap type (Instant Out, Static Address Loop-in, etc.) has its own state machine that defines its lifecycle. This ensures that swaps progress through a defined set of states, with transitions triggered by on-chain or off-chain events, making the system resilient to failures and restarts. | ||
|
|
||
| * **Database (`loopdb/`):** Persistence is handled by a database layer that supports both `bbolt` and `PostgreSQL` (via `sqlc` for query generation). It stores swap contracts, state history, liquidity parameters, and other critical data, allowing the daemon to recover and resume operations after a restart. |
There was a problem hiding this comment.
are we supporting bbolt? We do support SQLite though.
There was a problem hiding this comment.
Updated this part:
Persistence is handled by a database layer that supports both
sqlite3andPostgreSQL(viasqlcfor query generation). There is also deprecatedbboltimplementation which is left in the codebase to support migrating old instances.
docs/architecture.md
Outdated
| 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 creating the HTLC tx. |
There was a problem hiding this comment.
s/creating/publishing. The HTLC tx is created before the off-chain payment happens.
docs/architecture.md
Outdated
| ### Standard Loop-In (on -> off-chain) | ||
|
|
||
| The reverse of a Loop-Out. The client sends funds to an on-chain HTLC which is | ||
| a 2/2 MuSig2 address with a tapleaf which the server can use to sweep the funds |
There was a problem hiding this comment.
nit: let's use the wording 2-of-2.
docs/architecture.md
Outdated
|
|
||
| ### Standard Loop-In (on -> off-chain) | ||
|
|
||
| The reverse of a Loop-Out. The client sends funds to an on-chain HTLC which is |
There was a problem hiding this comment.
nit: instead of mentioning the preimage path specifically we could just reword such that it's an on-chain HTLC with a 2-of-2 MuSig2 keyspend path.
There was a problem hiding this comment.
Reworded this sentence.
The whole project was analyzed by AI and the context was saved to the file. This file is picked up by agents automatically and it should facilitate AI understanding of the project.
3 participants
My experiment of using Gemini in Loop code base.
I asked Gemini to read the whole project and to save the context to AGENTS.md. This file is picked up by such tools automatically so it may help with further AI application as they will know what is stored where.
I noticed that README.md and architecture.md were outdated and tried to update them using the same tool. The committed version includes my manual edits, since it didn't understand originally how onchain HTLCs work.
Pull Request Checklist
release_notes.mdif your PR contains major features, breaking changes or bugfixes