lightninglabs / lightninglabs/wavelength
wallet: expose plain BTC wallet receive addresses
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 47
- Forks
- 14
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 103
Description
Problem
The public client wallet surfaces currently only expose Ark boarding addresses, not ordinary addresses from the underlying BTC wallet.
This makes it hard to add plain wallet UTXOs for exit/unroll/CPFP flows when all user funds have already been boarded into VTXOs. The problem is most acute for the embedded lwwallet and btcwallet backends, where the user does not necessarily have a separate wallet UI/API to fund the daemon wallet directly.
Current behavior
The existing public address/receive APIs are boarding-oriented:
daemonrpc.NewAddressis documented as generating a boarding address, andNewAddressResponse.addressis a taproot boarding address (daemonrpc/daemon.proto:40,daemonrpc/daemon.proto:514).- The RPC server implementation fetches operator terms and sends
wallet.CreateBoardingAddressRequestto the wallet actor (darepod/rpc_server.go:976,darepod/rpc_server.go:1000). WalletService.Depositis also documented as returning a boarding address (rpc/walletrpc/wallet.proto:49,rpc/walletrpc/wallet.proto:390).swapwallet.Service.Depositdelegates to daemonNewAddress, so it inherits the boarding-address behavior (swapwallet/service.go:106,swapwallet/service.go:118).walletdk.Client.Depositand its request/result types are explicitly "tracked boarding address" APIs (sdk/walletdk/client.go:227,sdk/walletdk/types.go:125).darepocli recv --onchainreturns a boarding address, not a plain wallet address (cmd/darepocli/darepoclicommands/cmd_recv.go:10).
At the same time, the daemon already has an underlying on-chain wallet concept:
GetBalanceexposesonchain_wallet_confirmed_satfrom backing wallet balance fetchers (darepod/rpc_server.go:540).- Unroll preflight can fail with "Fund the wallet's onchain address with more inputs and retry" (
darepod/rpc_server.go:2942). - The embedded lwwallet and btcwallet unroll adapters can internally allocate fresh wallet-managed scripts via
Wallet.NewAddress(ctx)(darepod/server.go:4220,darepod/server.go:4315).
The missing piece is a public API/CLI/SDK surface to request one of those wallet-owned BTC receive addresses.
Why this matters
If all funds are boarded, the daemon may not have enough ordinary wallet UTXOs to pay exit/unroll/CPFP fees or to satisfy preflight requirements. Today the user can be told to fund the wallet's on-chain address, but the client does not expose such an address for the embedded wallet backends. recv --onchain looks close, but it creates a boarding address that is meant to be rolled into Ark, which is the opposite of keeping a plain wallet UTXO available for L1 fee/exit use.
LND users may be able to use their existing LND wallet RPC/UI as an escape hatch. lwwallet and btcwallet users generally cannot.
Proposed fix
Add an explicit plain BTC wallet receive-address API that is distinct from boarding/deposit addresses. For example:
- daemon RPC:
NewWalletAddress/NewOnchainWalletAddress - wallet RPC:
WalletAddress/ReceiveAddress, or a clearly named method that does not overloadDeposit - walletdk:
OnchainAddress(ctx)or equivalent - CLI/MCP: either a dedicated
wallet addresscommand or an unambiguous flag such asrecv --wallet-onchain
The naming should make it clear that:
Deposit/recv --onchainremains a boarding address flow.- The new API returns an address controlled by the underlying BTC wallet.
- Funding the new address should create normal wallet UTXOs, not tracked boarding outputs.
Backend behavior can be scoped explicitly:
lwwallet: supported by allocating from the embedded wallet.btcwallet: supported by allocating from the embedded wallet.lnd: either proxy LND wallet address generation or return a documented unsupported/unimplemented response if we do not want to manage those funds through this client surface.
Acceptance criteria
- A public RPC exists to create a plain wallet-managed BTC receive address for supported backends.
- The walletdk and CLI expose that RPC with naming that cannot be confused with boarding deposits.
- For
lwwalletandbtcwallet, funding the address increasesonchain_wallet_confirmed_satafter confirmation. - Funding the address does not create a boarding address entry, does not register the output as an active boarding output, and does not auto-roll the UTXO into the next Ark round.
- Exit/unroll/CPFP funding paths can use these wallet UTXOs once confirmed.
- Tests cover at least the embedded wallet backends and document the intended LND behavior.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the existing address flows in darepod/rpc_server.go, daemonrpc/daemon.proto, rpc/walletrpc/wallet.proto, swapwallet/service.go, sdk/walletdk/client.go, and cmd/darepocli/darepoclicommands/cmd_recv.go. Compare them with the wallet.NewAddress calls in darepod/server.go and determine the API boundaries and backend behavior. Done means supported backends expose a distinct wallet address through RPC, walletdk, and CLI, with tests covering embedded wallets and the intended LND behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api, backend, cli, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100