assets swap deposits [4/N]: add asset deposit manager #982
Conversation
With this commit we add high level helpers along with scripts to create asset HTLCs.
This commit enables package relayed HTLCs by making the CSV check in the success path optional.
This commit adds additional scaffolding to our tapd client, along with new high-level helpers in the assets package, which will be used later for swaps and deposits.
This commit adds protos for the loopd asset deposit subserver RPCs.
This commit adds a placeholder asset deposit subserver along with the corresponding CLI commands to the Loop daemon and CLI.
This commit adds a high level deposit Kit type which includes the necessary functions to create and spend deposits to HTLC or through success, timeout or cooperative MuSig2 sweeps.
This commit adds a sweeper tailored for asset deposits, capable of sweeping a TAP deposit (a Kit) using either the timeout path or a revealed co-signer key. This lays the groundwork for implementing client-specific sweeping logic.
This commit extends the deposit package with the `Deposit` type and a bare-bones `Manager`, along with the structural definition of the `SQLStore` which together implement the basic structure, run loop and storage for the deposit manager. It is not yet functional and serves as a foundation for future commits that will gradually extend its functionality.
This commit extends the asset deposit manager along with the underlying sql store, adding functionality to create and fund new asset deposits.
This commit adds the necessary changes to the asset deposit manager, the underlying sql store and the asset deposit subserver to be able to list asset deposits.
With this commit, asset deposit expiry is checked on each new block. When a deposit expires, a timeout sweep is published. The deposit state is updated both when the sweep is first published and again upon its confirmation.
This commit adds deposit recovery to the deposit manager's startup process. All deposits that have not yet been spent by the server or swept by the client are recovered from the store.
This commit implements the necessary plumbing to enable deposit withdrawal. Withdrawing reveals the server's internal key for the deposit, allowing the client to sweep it independently.
This commit implements the full cooperative deposit withdrawal flow. The client first fetches keys for any pending withdrawals, then publishes sweep transactions using the revealed key to sign the deposit sweep. Once the sweep confirms, the deposit’s state is updated in the deposit store.
With this commit, the client can now reveal the keys of asset deposits to the server. This allows the server to sweep the deposits as needed, without requiring further interaction with the client.
This commit extends the deposit manager and sweeper to support generating a zero-fee HTLC transaction that spends a selected deposit. Once the HTLC is prepared, it is partially signed by the client and can be handed to the server as a safety measure before using the deposit in a trustless swap. This typically occurs after the client has accepted the swap payment. If the client becomes unresponsive during the swap process, the server can use the zero-fee HTLC as part of a recovery package.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @bhandras, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request introduces a foundational framework for managing asset deposits within the loop project, crucial for enabling asset swaps. It establishes a robust client-side manager that orchestrates the entire lifecycle of these deposits, from their initial setup and on-chain funding to their eventual spending or recovery. The changes involve significant new cryptographic logic, deep integration with tapd and LND's wallet capabilities, persistent storage solutions, and new user-facing interfaces, laying essential groundwork for future asset-based financial operations.
Highlights
- New Feature: Asset Deposit Manager: Introduced a comprehensive client-side asset deposit manager (
assets/deposit/manager.go) responsible for the full lifecycle of asset deposits, from creation and funding to spending or withdrawal, specifically designed for asset swaps. - Cryptographic Primitives and Protocol: Implemented a
Kit(assets/deposit/kit.go) to encapsulate the cryptographic parameters for 2-of-2 MuSig2 asset deposits, including key derivation, script generation (timeout paths), and proof verification. A newAssetDepositProtocolVersion(assets/deposit/protocol.go) is also defined. - On-chain Interaction and Sweeping: Added a
Sweepercomponent (assets/deposit/sweeper.go) to handle the on-chain Bitcoin transactions for sweeping assets, supporting both cooperative (MuSig2) and timeout-based spending paths. This includes complex PSBT manipulation and interaction withtapdand LND's wallet and signer services. - Persistence and State Management: Integrated a new SQL store (
assets/deposit/sql_store.go) with dedicated database tables (loopdb/sqlc/migrations/000015_asset_deposits.up.sql) to persistently store asset deposit information, track their state transitions, and manage leased UTXOs for sweep transactions. - RPC and CLI Exposure: Exposed the new asset deposit functionality via new gRPC services for both client-side (
looprpc/client_asset_deposit.proto) and server-side (swapserverrpc/asset_deposit.proto) interactions, complemented by new CLI commands (cmd/loop/asset_deposits.go) for user control.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
| for { | ||
| select { | ||
| case <-receiveEventsClient.Context().Done(): | ||
| panic(receiveEventsClient.Context().Err()) |
There was a problem hiding this comment.
Using panic here will crash the entire application if the client's context is done. This can happen for legitimate reasons, such as the client disconnecting or the context being cancelled. Instead of panicking, you should handle the context cancellation gracefully by sending the error on errChan and returning from the goroutine.
| panic(receiveEventsClient.Context().Err()) | |
| errChan <- receiveEventsClient.Context().Err() | |
| return |
| if !ok { | ||
| return 0, status.Error(codes.Internal, "internal error") | ||
| } |
There was a problem hiding this comment.
If the asset ID is not found in the balanceResp.AssetBalances map, it means the balance for that asset is zero. Returning an internal error in this case is misleading and could cause issues for callers. The function should return a balance of 0 and no error.
| if !ok { | |
| return 0, status.Error(codes.Internal, "internal error") | |
| } | |
| if !ok { | |
| return 0, nil | |
| } |
| if in.MinConfs < in.MaxConfs { | ||
| return nil, status.Error(codes.InvalidArgument, | ||
| "max_confs must be greater than or equal to min_confs") |
There was a problem hiding this comment.
The validation for min_confs and max_confs is incorrect. max_confs can be 0 to indicate no maximum limit. The current check in.MinConfs < in.MaxConfs would incorrectly fail for cases like min_confs=1, max_confs=0.
A better check would be to ensure that if max_confs is set (non-zero), it must be greater than or equal to min_confs.
if in.MaxConfs > 0 && in.MinConfs > in.MaxConfs {
return nil, status.Error(codes.InvalidArgument,
"max_confs must be greater than or equal to min_confs")
}| return nil, fmt.Errorf("invalid asset ID lenght: expected "+ | ||
| "%v bytes, got %d", len(assetID), len(assetIDBytes)) |
There was a problem hiding this comment.
There is a typo in the error message. "lenght" should be "length".
return nil, status.Error(codes.InvalidArgument,
"invalid asset ID length: expected "+
"%v bytes, got %d", len(assetID), len(assetIDBytes))| clientInteralPubKey, err := btcec.ParsePubKey( | ||
| sqlDeposit.ClientInternalPubkey, | ||
| ) |
There was a problem hiding this comment.
There is a typo in the variable name clientInteralPubKey. It should be clientInternalPubKey. This should be corrected here and where it's used later in this function (line 269).
| clientInteralPubKey, err := btcec.ParsePubKey( | |
| sqlDeposit.ClientInternalPubkey, | |
| ) | |
| clientInternalPubKey, err := btcec.ParsePubKey( | |
| sqlDeposit.ClientInternalPubkey, | |
| ) |
1 participant
This PR implements the client side asset deposit manager, store, client subserver and the asset deposit protocol for creating, withdrawing and spending asset deposits.
Pull Request Checklist
release_notes.mdif your PR contains major features, breaking changes or bugfixes