lightninglabs / lightninglabs/wavelength

wallet: expose plain BTC wallet receive addresses

Open
#528 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cli P1 wallet
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.NewAddress is documented as generating a boarding address, and NewAddressResponse.address is a taproot boarding address (daemonrpc/daemon.proto:40, daemonrpc/daemon.proto:514).
  • The RPC server implementation fetches operator terms and sends wallet.CreateBoardingAddressRequest to the wallet actor (darepod/rpc_server.go:976, darepod/rpc_server.go:1000).
  • WalletService.Deposit is also documented as returning a boarding address (rpc/walletrpc/wallet.proto:49, rpc/walletrpc/wallet.proto:390).
  • swapwallet.Service.Deposit delegates to daemon NewAddress, so it inherits the boarding-address behavior (swapwallet/service.go:106, swapwallet/service.go:118).
  • walletdk.Client.Deposit and its request/result types are explicitly "tracked boarding address" APIs (sdk/walletdk/client.go:227, sdk/walletdk/types.go:125).
  • darepocli recv --onchain returns 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:

  • GetBalance exposes onchain_wallet_confirmed_sat from 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 overload Deposit
  • walletdk: OnchainAddress(ctx) or equivalent
  • CLI/MCP: either a dedicated wallet address command or an unambiguous flag such as recv --wallet-onchain

The naming should make it clear that:

  • Deposit / recv --onchain remains 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 lwwallet and btcwallet, funding the address increases onchain_wallet_confirmed_sat after 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.