[v0.21.x-branch] Backport #11065: walletrpc: add XCreateAccount for wallet-derived accounts

[github-actions]

Backport of #11065

---

Motivation

lnd can already confine coin selection, change, balance, address derivation and
signing to a named wallet account — FundPsbt, FinalizePsbt, ListUnspent,
NextAddr, WalletBalance and ListTransactions all take one. What is missing
is a way to create such an account.

The only account-creating RPC today is ImportAccount, which registers a
watch-only account from an extended public key. The wallet stores no account
private key for it, so waddrmgr can only derive public keys for its addresses
and SignPsbt/FinalizePsbt silently skip its inputs. That makes it unusable
for partitioning one wallet into isolated pockets of funds, which is what two
applications sharing a single lnd node need in order not to spend each other's
coins.

btcwallet already supports this via Wallet.NextAccount, which derives a new
account from the wallet's master key. lnd simply never exposed it.

Changes

Split so each commit stands alone:

1. walletrpc: define the XCreateAccount RPC — proto, REST annotation, regen.
2. lnwallet: add CreateAccount to the WalletController interface — the
   BtcWallet implementation, the two mocks, and an explicit refusal in
   RPCKeyRing.
3. walletrpc: implement the XCreateAccount RPC — the handler.
4. itest: cover XCreateAccount end to end.
5. lncli: add wallet accounts create command.
6. docs: add release notes for XCreateAccount.

Notes for reviewers

• Duplicates are rejected across all key scopes, not just the requested one.
  Coin selection resolves a custom account through lookupFirstCustomAccount,
  which returns whichever scope matches first, so the same name under two scopes
  would make later funding calls ambiguous.

• NESTED_WITNESS_PUBKEY_HASH is rejected. A wallet-derived account stores
  no address schema, so BIP-0049Plus always behaves as the hybrid scheme.
  Accepting the strict type would hand back an account whose change outputs are
  not what was asked for. ImportAccount can honour the distinction because it
  passes an addrSchema through; NextAccount cannot.

• Remote signing is refused explicitly. RPCKeyRing embeds the
  WalletController interface, so without an override it would promote
  BtcWallet's implementation and fail deep inside waddrmgr with a bare
  "watching-only wallet". Creating the account on the signer and importing its
  xpub here is the supported path.

• Two caveats are documented in the proto and are worth a second opinion:

  • The address type is permanent and also fixes the account's change type, so
    a later NextAddr must ask for the same address type or the account will
    appear not to exist.
  • A seed-only recovery will not rediscover funds held in a created
    account: lnd's recovery scan only derives addresses for account 0. Ordinary
    rescans are unaffected.

• BtcWallet.CreateAccount reaches NextAccount through a local interface
  assertion rather than widening btcwallet's base.Interface, so lnd does not
  have to carry a forked btcwallet — a replace here would not propagate to
  modules that depend on lnd, and each of them would have to duplicate it. Happy
  to do the btcwallet PR instead; the assertion is marked for removal if so.

Testing

Unit tests cover the guards, key-scope forwarding, the unsupported-wallet path
and error wrapping. make rpc-check and the REST-annotation check pass.

There are also two itests, with the matching HarnessRPC helpers. The first
covers the property a unit test cannot reach: create → NewAddress → fund →
FundPsbt → FinalizePsbt → publish, asserting the balance lands on the new
account and not the default one, and that the spend confirms. Funding a PSBT
works for a watch-only account too, since it needs only public data — it is
finalizing and confirming that separates a wallet-derived account from an
imported one. The second covers the refusals: duplicate names across key
scopes, reserved names, an empty name, and the strict nested-witness type.

🤖 Generated with Claude Code

[github-actions]

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin backport-11065-to-v0.21.x-branch
git worktree add --checkout .worktree/backport-11065-to-v0.21.x-branch backport-11065-to-v0.21.x-branch
cd .worktree/backport-11065-to-v0.21.x-branch
git reset --hard HEAD^
git cherry-pick -x 9664abd4f4c95d8e128853e0364e3b4e293fda68
git push --force-with-lease

[github-actions]

🔴 PR Severity: CRITICAL

gh pr view | 20 files | 2199 lines changed

🔴 Critical (4 files)

• lnwallet/btcwallet/btcwallet.go - btcwallet controller: implements new account creation/derivation logic
• lnwallet/interface.go - core WalletController interface changes
• lnwallet/mock.go - mock wallet updated to conform to interface change
• lnwallet/rpcwallet/rpcwallet.go - remote signer wallet implementation changes

🟠 High (8 files)

• lnrpc/walletrpc/walletkit.proto - new RPC (XCreateAccount) added to wallet kit API
• lnrpc/walletrpc/walletkit_server.go - new RPC handler implementation
• lnrpc/walletrpc/walletkit.pb.go - generated from proto change
• lnrpc/walletrpc/walletkit.pb.gw.go - generated gateway code
• lnrpc/walletrpc/walletkit.pb.json.go - generated JSON marshaling code
• lnrpc/walletrpc/walletkit_grpc.pb.go - generated gRPC stubs
• lnrpc/walletrpc/walletkit.swagger.json - generated swagger docs
• lnrpc/walletrpc/walletkit.yaml - RPC middleware/macaroon config

🟡 Medium (1 file)

• cmd/commands/walletrpc_active.go - new CLI command for the xcreate-account RPC

🟢 Low (7 files)

• docs/release-notes/release-notes-0.21.3.md - release notes
• itest/lnd_wallet.go - integration test wiring
• itest/lnd_wallet_xcreate_account.go - new integration test
• lnrpc/walletrpc/xcreate_account_gate_test.go - unit test
• lntest/mock/walletcontroller.go - test mock
• lntest/rpc/wallet_kit.go - test harness helper
• lnwallet/btcwallet/create_account_test.go - unit test

Analysis

This PR adds a new XCreateAccount wallet RPC that lets callers derive/create wallet accounts using an explicit key scope and address type. The changes touch lnwallet/interface.go (the core WalletController interface), lnwallet/btcwallet/btcwallet.go (the primary wallet implementation), and lnwallet/rpcwallet/rpcwallet.go (the remote-signer wallet) — all squarely in wallet-operations territory, which drives the CRITICAL classification. The non-test/non-generated line count (~552 lines across cmd/, lnrpc/walletrpc/*.proto|.yaml|.swagger.json|_server.go, and the lnwallet/* implementation files) also exceeds the 500-line bump threshold, though this has no further effect since CRITICAL is already the ceiling.

Because this adds a new account-derivation code path to the wallet layer (affecting key/address derivation), it warrants careful review from someone familiar with lnwallet's account and key-scope handling, in addition to the standard RPC/API review for the new walletrpc endpoint.

---

_{To override, add a severity-override-{critical,high,medium,low} label.}

[ziggie1984]

LGTM (merge conflict was the wrong Release Notes which got fixed also on master with: #11091)