-
Notifications
You must be signed in to change notification settings - Fork 9
docs: nightly doc-gardening sweep 2026-06-28 #810
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # chainfees | ||
|
|
||
| ## Purpose | ||
|
|
||
| Provides reusable `chainfee.Estimator` implementations and combinators for | ||
| wallet and daemon chain backends. Bundles three concrete estimators — | ||
| `WalletKitEstimator` (queries lnd WalletKit), `MempoolSpaceEstimator` (queries | ||
| mempool.space API), and `MinEstimator` (selects the lowest successful estimate | ||
| across a set of child estimators) — so backends can compose fee estimation | ||
| strategies without re-implementing the interface. | ||
|
|
||
| ## Key Types | ||
|
|
||
| - `WalletKitEstimator` — proxies fee estimates to an lndclient WalletKitClient | ||
| with configurable timeout and optional degraded-mode fallback on error. | ||
| - `WalletKitEstimatorConfig` — config for `WalletKitEstimator`: client, | ||
| logger, timeout, fallback flag. | ||
| - `MempoolSpaceEstimator` — queries the mempool.space recommended-fee endpoint | ||
| with configurable URL, cache TTL, and chain params. Caches the last | ||
| successful response to avoid hammering the API on every block. | ||
| - `MempoolSpaceConfig` — config for `MempoolSpaceEstimator`. | ||
| - `MinEstimator` — queries multiple child estimators and returns the minimum | ||
| successful relay fee per KW. | ||
| - `NamedEstimator` — wraps a child estimator with a stable name for logging. | ||
|
|
||
| ## Relationships | ||
|
|
||
| - **Depends on**: `lnd/lnwallet/chainfee` (Estimator interface), | ||
| `lndclient` (WalletKitClient), `btcd/btcutil`, `btclog`. | ||
| - **Depended on by**: `darepod` (daemon fee estimation), | ||
| `chainbackends` (lnd-backed fee estimation adapter). | ||
| - **Sends**: nothing. | ||
| - **Receives**: nothing. | ||
|
|
||
| ## Invariants | ||
|
|
||
| - All three exported estimator types implement | ||
| `github.com/lightningnetwork/lnd/lnwallet/chainfee.Estimator`. | ||
| - `MempoolSpaceEstimator` caches the last successful response at the | ||
| configured TTL; concurrent callers share the cached estimate without | ||
| issuing duplicate HTTP requests. | ||
| - `WalletKitEstimator` with the fallback flag returns a static relay fee | ||
| rather than propagating errors, so fee estimation can degrade gracefully | ||
| when lnd is temporarily unreachable. | ||
|
|
||
| ## Deep Docs | ||
|
|
||
| - [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # chainfees | ||
|
|
||
| ## Purpose | ||
|
|
||
| Provides reusable `chainfee.Estimator` implementations and combinators for | ||
| wallet and daemon chain backends. Bundles three concrete estimators — | ||
| `WalletKitEstimator` (queries lnd WalletKit), `MempoolSpaceEstimator` (queries | ||
| mempool.space API), and `MinEstimator` (selects the lowest successful estimate | ||
| across a set of child estimators) — so backends can compose fee estimation | ||
| strategies without re-implementing the interface. | ||
|
|
||
| ## Key Types | ||
|
|
||
| - `WalletKitEstimator` — proxies fee estimates to an lndclient WalletKitClient | ||
| with configurable timeout and optional degraded-mode fallback on error. | ||
| - `WalletKitEstimatorConfig` — config for `WalletKitEstimator`: client, | ||
| logger, timeout, fallback flag. | ||
| - `MempoolSpaceEstimator` — queries the mempool.space recommended-fee endpoint | ||
| with configurable URL, cache TTL, and chain params. Caches the last | ||
| successful response to avoid hammering the API on every block. | ||
| - `MempoolSpaceConfig` — config for `MempoolSpaceEstimator`. | ||
| - `MinEstimator` — queries multiple child estimators and returns the minimum | ||
| successful relay fee per KW. | ||
| - `NamedEstimator` — wraps a child estimator with a stable name for logging. | ||
|
|
||
| ## Relationships | ||
|
|
||
| - **Depends on**: `lnd/lnwallet/chainfee` (Estimator interface), | ||
| `lndclient` (WalletKitClient), `btcd/btcutil`, `btclog`. | ||
| - **Depended on by**: `darepod` (daemon fee estimation), | ||
| `chainbackends` (lnd-backed fee estimation adapter). | ||
| - **Sends**: nothing. | ||
| - **Receives**: nothing. | ||
|
|
||
| ## Invariants | ||
|
|
||
| - All three exported estimator types implement | ||
| `github.com/lightningnetwork/lnd/lnwallet/chainfee.Estimator`. | ||
| - `MempoolSpaceEstimator` caches the last successful response at the | ||
| configured TTL; concurrent callers share the cached estimate without | ||
| issuing duplicate HTTP requests. | ||
| - `WalletKitEstimator` with the fallback flag returns a static relay fee | ||
| rather than propagating errors, so fee estimation can degrade gracefully | ||
| when lnd is temporarily unreachable. | ||
|
|
||
| ## Deep Docs | ||
|
|
||
| - [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| # cmd/walletdk-wasm | ||
|
|
||
| ## Purpose | ||
|
|
||
| Browser/WASM entry point for the embedded walletdk runtime. Installs a global | ||
| `walletdkCall(method, request)` JavaScript function via `syscall/js` and | ||
| dispatches each call to the corresponding `sdk/walletdk/mobile` verb, returning | ||
| a JS Promise. The daemon, swap, and OOR machinery all run in-process inside the | ||
| browser VM with no separate gateway. The bridge never reaches `walletdk.Client` | ||
| directly — it always goes through the mobile facade so WASM behavior stays in | ||
| sync with the gomobile bindings. | ||
|
|
||
| Only compiles with `GOOS=js GOARCH=wasm -tags "mobile walletdkrpc swapruntime"`. | ||
| `stub.go` provides an empty build so `go build ./...` succeeds on other targets. | ||
|
|
||
| ## Key Types | ||
|
|
||
| - `main` — installs `walletdkCall` on `js.Global()`, dispatches a | ||
| `walletdk-ready` custom event, then parks the Go runtime so exported | ||
| callbacks remain live for the page lifetime. | ||
| - `walletCall` — the single JS entry point; dispatches the method name to the | ||
| corresponding `mobile.*` verb and wraps the result in a Promise. | ||
| - `subscriptionHandle` — wraps `*mobile.Subscription` as a JS object with | ||
| `next()` (Promise → next entry JSON or null at EOF) and `close()` methods. | ||
|
|
||
| ## Relationships | ||
|
|
||
| - **Depends on**: `sdk/walletdk/mobile` (all wallet operations proxied through | ||
| the mobile facade). | ||
| - **Depended on by**: browser host applications, React Native WASM bridges. | ||
| - **Sends**: nothing (invokes mobile facade functions in goroutines). | ||
| - **Receives** ← JS host: `walletdkCall(method, request)` invocations. | ||
|
|
||
| ## Invariants | ||
|
|
||
| - `walletCall` is the only JS-exported function; all verb dispatch happens | ||
| inside its switch. Additional `js.Func` values outside `promise()` must be | ||
| released manually — `promise()` already releases its own executor immediately | ||
| after the Promise constructor returns to prevent per-call handle leaks. | ||
| - The browser data dir defaults to `/darepo` (injected by `startConfig`). | ||
| Without this override, `os.UserHomeDir` fails under `wasm_exec.js` with | ||
| `"$HOME is not defined"` and aborts start before the wallet boots. Callers | ||
| may override via `data_dir` in the start request. | ||
| - This package must not import `sdk/walletdk` directly; all access goes through | ||
| the `mobile` facade to keep the WASM bridge and gomobile bindings in sync. | ||
|
|
||
| ## Deep Docs | ||
|
|
||
| - [sdk/walletdk/mobile/CLAUDE.md](../../sdk/walletdk/mobile/CLAUDE.md) — | ||
| The gomobile facade this package wraps. | ||
| - [sdk/walletdk/CLAUDE.md](../../sdk/walletdk/CLAUDE.md) — Underlying Go SDK. | ||
| - [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| # cmd/walletdk-wasm | ||
|
|
||
| ## Purpose | ||
|
|
||
| Browser/WASM entry point for the embedded walletdk runtime. Installs a global | ||
| `walletdkCall(method, request)` JavaScript function via `syscall/js` and | ||
| dispatches each call to the corresponding `sdk/walletdk/mobile` verb, returning | ||
| a JS Promise. The daemon, swap, and OOR machinery all run in-process inside the | ||
| browser VM with no separate gateway. The bridge never reaches `walletdk.Client` | ||
| directly — it always goes through the mobile facade so WASM behavior stays in | ||
| sync with the gomobile bindings. | ||
|
|
||
| Only compiles with `GOOS=js GOARCH=wasm -tags "mobile walletdkrpc swapruntime"`. | ||
| `stub.go` provides an empty build so `go build ./...` succeeds on other targets. | ||
|
|
||
| ## Key Types | ||
|
|
||
| - `main` — installs `walletdkCall` on `js.Global()`, dispatches a | ||
| `walletdk-ready` custom event, then parks the Go runtime so exported | ||
| callbacks remain live for the page lifetime. | ||
| - `walletCall` — the single JS entry point; dispatches the method name to the | ||
| corresponding `mobile.*` verb and wraps the result in a Promise. | ||
| - `subscriptionHandle` — wraps `*mobile.Subscription` as a JS object with | ||
| `next()` (Promise → next entry JSON or null at EOF) and `close()` methods. | ||
|
|
||
| ## Relationships | ||
|
|
||
| - **Depends on**: `sdk/walletdk/mobile` (all wallet operations proxied through | ||
| the mobile facade). | ||
| - **Depended on by**: browser host applications, React Native WASM bridges. | ||
| - **Sends**: nothing (invokes mobile facade functions in goroutines). | ||
| - **Receives** ← JS host: `walletdkCall(method, request)` invocations. | ||
|
|
||
| ## Invariants | ||
|
|
||
| - `walletCall` is the only JS-exported function; all verb dispatch happens | ||
| inside its switch. Additional `js.Func` values outside `promise()` must be | ||
| released manually — `promise()` already releases its own executor immediately | ||
| after the Promise constructor returns to prevent per-call handle leaks. | ||
| - The browser data dir defaults to `/darepo` (injected by `startConfig`). | ||
| Without this override, `os.UserHomeDir` fails under `wasm_exec.js` with | ||
| `"$HOME is not defined"` and aborts start before the wallet boots. Callers | ||
| may override via `data_dir` in the start request. | ||
| - This package must not import `sdk/walletdk` directly; all access goes through | ||
| the `mobile` facade to keep the WASM bridge and gomobile bindings in sync. | ||
|
|
||
| ## Deep Docs | ||
|
|
||
| - [sdk/walletdk/mobile/CLAUDE.md](../../sdk/walletdk/mobile/CLAUDE.md) — | ||
| The gomobile facade this package wraps. | ||
| - [sdk/walletdk/CLAUDE.md](../../sdk/walletdk/CLAUDE.md) — Underlying Go SDK. | ||
| - [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # coinselect | ||
|
|
||
| ## Purpose | ||
|
|
||
| Provides a single, coin-type-agnostic coin-selection algorithm shared across | ||
| the client. The package holds no wallet, actor, or RPC dependencies so every | ||
| layer that needs a covering subset — the VTXO manager's reservation path and | ||
| the swap wallet's send preview alike — selects through the same generic code | ||
| rather than growing parallel implementations. | ||
|
|
||
| ## Key Types | ||
|
|
||
| - `Request` — selection parameters: `Target` amount, `MinChange` floor, | ||
| `SweepAll` flag. `SweepAll` takes precedence and ignores `Target` and | ||
| `MinChange`. | ||
| - `Result[T]` — selection outcome: `Selected` subset, `Total`, `Change`. | ||
| - `AmountFunc[T]` — callback to extract a `btcutil.Amount` from a candidate | ||
| of type `T`. | ||
|
|
||
| ## Selection Errors | ||
|
|
||
| - `ErrSelectionShortfall` — candidate set cannot cover target; `Result.Total` | ||
| carries the full candidate sum so callers can render a precise message. | ||
| - `ErrChangeBelowMin` — covering selection exists but change is below the | ||
| requested minimum and no exact-fit set was found. | ||
| - `ErrNoCandidates` — empty candidate set passed to the selector. | ||
| - `ErrInvalidTarget` — non-positive target in a bounded selection. | ||
|
|
||
| ## Relationships | ||
|
|
||
| - **Depends on**: `btcd/btcutil` (amount type). | ||
| - **Depended on by**: `vtxo` (VTXO manager reservation path), | ||
| `swapwallet` (send-preview coin selection). | ||
| - **Sends**: nothing. | ||
| - **Receives**: nothing. | ||
|
|
||
| ## Invariants | ||
|
|
||
| - `SweepAll` takes precedence: when set, `Target` and `MinChange` are ignored | ||
| and every candidate is selected. | ||
| - The selector is policy-free: it reports why a pass failed via typed errors | ||
| and leaves layer-specific diagnostics (e.g. locked liquidity vs. true | ||
| shortfall) to callers. | ||
| - Error values carry no total on `ErrNoCandidates` and `ErrInvalidTarget`; | ||
| only `ErrSelectionShortfall` and `ErrChangeBelowMin` populate `Result.Total`. | ||
|
|
||
| ## Deep Docs | ||
|
|
||
| - [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # coinselect | ||
|
|
||
| ## Purpose | ||
|
|
||
| Provides a single, coin-type-agnostic coin-selection algorithm shared across | ||
| the client. The package holds no wallet, actor, or RPC dependencies so every | ||
| layer that needs a covering subset — the VTXO manager's reservation path and | ||
| the swap wallet's send preview alike — selects through the same generic code | ||
| rather than growing parallel implementations. | ||
|
|
||
| ## Key Types | ||
|
|
||
| - `Request` — selection parameters: `Target` amount, `MinChange` floor, | ||
| `SweepAll` flag. `SweepAll` takes precedence and ignores `Target` and | ||
| `MinChange`. | ||
| - `Result[T]` — selection outcome: `Selected` subset, `Total`, `Change`. | ||
| - `AmountFunc[T]` — callback to extract a `btcutil.Amount` from a candidate | ||
| of type `T`. | ||
|
|
||
| ## Selection Errors | ||
|
|
||
| - `ErrSelectionShortfall` — candidate set cannot cover target; `Result.Total` | ||
| carries the full candidate sum so callers can render a precise message. | ||
| - `ErrChangeBelowMin` — covering selection exists but change is below the | ||
| requested minimum and no exact-fit set was found. | ||
| - `ErrNoCandidates` — empty candidate set passed to the selector. | ||
| - `ErrInvalidTarget` — non-positive target in a bounded selection. | ||
|
|
||
| ## Relationships | ||
|
|
||
| - **Depends on**: `btcd/btcutil` (amount type). | ||
| - **Depended on by**: `vtxo` (VTXO manager reservation path), | ||
| `swapwallet` (send-preview coin selection). | ||
| - **Sends**: nothing. | ||
| - **Receives**: nothing. | ||
|
|
||
| ## Invariants | ||
|
|
||
| - `SweepAll` takes precedence: when set, `Target` and `MinChange` are ignored | ||
| and every candidate is selected. | ||
| - The selector is policy-free: it reports why a pass failed via typed errors | ||
| and leaves layer-specific diagnostics (e.g. locked liquidity vs. true | ||
| shortfall) to callers. | ||
| - Error values carry no total on `ErrNoCandidates` and `ErrInvalidTarget`; | ||
| only `ErrSelectionShortfall` and `ErrChangeBelowMin` populate `Result.Total`. | ||
|
|
||
| ## Deep Docs | ||
|
|
||
| - [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The migration notes are listed in descending chronological order (from highest migration number to lowest). However,
000021_vhtlc_recovery_job_generationshas been placed below000020_accounting_wallet_sweeps. To maintain the correct descending order, please move the000021migration note to the very top of the 'Migration notes' section (above000020).