#36126 wallet, rpc: Implements set key label functionality

ReviewabilityReviewsAgreementSize
#36126 polespinasa wallet, rpc: Implements set key label functionalityNeeds rebase0 -2Blocked294 + 156 tests
  • Help users and GUIs track which master key corresponds to which physical device or cosigner
  • Allow assigning and querying friendly labels for keys in multisig setups
  • Ready to review
  • Unaddressed objection: labels should only be temporary in the GUI and not stored in the wallet (achow101)
  • Objection: ongoing maintenance costs for RPCs offer little benefit (rkrux)
  • Support for persisting key labels to help users identify signers at signing time (davidgumberg)
  • Concept and approach approval with testing (jeanpablojp, vicjuma, Eunovo)
  • 294 lines added or modified outside tests
  • 156 lines added or modified in tests
  • 1 lines removed in total
  • 11 files, 11 commits
Wallet#61 of 92
P3 · new feature
  • P3 because tracking device identities across cosigners is a UX convenience for multisig workflows
  • It is a deferrable feature enhancement rather than an essential wallet capability
  • Ranking pass: Moved down: convenience labelling whose persistence design is still contested.
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

This pull request introduces key labeling to the wallet database, mapping master key fingerprints to arbitrary label strings. It adds three new RPCs (setkeylabel, getkeylabel, listkeylabels), exposes key labels in getaddressinfo and gethdkeys, and adds corresponding methods to interfaces::Wallet.

Problem: In multisig setups or setups with multiple signing devices, users and GUIs cannot easily track which master key corresponds to which physical device or cosigner.

Reviewability

Ready · Needs rebase

Conflicts with master; review the logic now, the rebase is mechanical.

Agreement

Blocked

objection that needs a change, nobody has replied (achow101)

Thread notes: Initial record. achow101 and rkrux raised blocking concept objections against storing key labels in the wallet and exposing them via RPC, leading the author to convert the PR to draft; earlier technical feedback from jeanpablojp and Eunovo was resolved. / Initial record for PR 36126. Open blocking objections from achow101 (NACK on DB persistence and fingerprint collidability) and rkrux (maintenance overhead before guided GUI multisig) prompted the author to convert the PR to draft, despite Conce

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
jeanpablojp (contributor)objection, scopegetaddressinfo did not return key labels for multisig script addressesfixed · fix pushed · v1, not yet re-checkedansweredyes2026-08-31: 'With both cosigners labelled, getaddressinfo on a wsh(sortedmulti(...)) address returns no key label.'
Status from: 2026-08-31: polespinasa: 'Added a per-object key label to getaddressinfo so it takes into account multi-keys scripts.'
Eunovo (member)objection, safetymaking m_key_labels public leaves it exposed to modification and out-of-sync states with the databasefixed · fix pushed · v1, not yet re-checkedansweredyes2026-09-02: 'The CWallet class is responsible for keeping it in sync with the DB; making it public leaves it open to modification.'
Status from: 2026-09-04: polespinasa: 'done'
achow101 (member)objection, approachstoring key labels in the wallet database is unnecessary because labels were intended only for temporary display during multisig GUI setupopen · v1, not yet re-checkedchangedno2026-09-07: 'The key labeling that was discussed is for the GUI only to show friendly names for keys during the multisig setup. Once the setup is complete, the labels would not be shown again, and hence do not need to be stored in the wallet.'
rkrux (member)objection, maintenanceincurs ongoing maintenance costs for RPCs that offer little benefit while complicating multisig setup workflowsanswered · reply on record; standing not assessed yet · v1, not yet re-checkedchangedyes2026-09-10: 'I don't see much benefit in providing RPCs for setting or viewing key labels (both separately and within the context of address(es) RPCs).'

Support:

  • jeanpablojp (contributor) (Concept ACK, 2026-08-31): Built the ten commits and ran the new test.
  • vicjuma (contributor) (Approach ACK, 2026-09-01): Approach ACK
  • Eunovo (member) (Concept ACK, 2026-09-02): Looks good; left some comments. I also think the new per-key label should be added to the output of gethdkeys.
  • davidgumberg (member) (2026-09-08): Shouldn't the key labels be persisted so that at signing time the user can see what keys have and haven't signed? I don't see a good reason to not persist key labels when it seems useful for UX.

Participants:

  • jeanpablojp (contributor, support, 7 statements 2026-08-31 to 2026-08-31): Concept ACK; raised issues regarding multisig key label support in getaddressinfo, which author resolved
  • vicjuma (contributor, support, 4 statements 2026-08-31 to 2026-09-01): Approach ACK; tested RPCs and noted labels help identify cosigners
  • maflcko (member, neutral, 1 statements 2026-09-01 to 2026-09-01): noted typos in release notes
  • Eunovo (member, support, 4 statements 2026-09-02 to 2026-09-02): Concept ACK; suggested encapsulating m_key_labels inside CWallet, which author implemented
  • achow101 (member, objection, 1 statements 2026-09-07 to 2026-09-07): NACK; argued key labels are GUI-only and should not be stored in the wallet DB, and warned against using collidable fingerprints
  • davidgumberg (member, support, 1 statements 2026-09-08 to 2026-09-08): advocated for persisting key labels to improve signing UX
  • rkrux (member, objection, 2 statements 2026-09-10 to 2026-09-10): Concept ~0 tending towards NACK; cited ongoing maintenance burden and unnecessary workflow complexity for RPC key labels

Dependencies

Enables:

  • #35645 (multisig setup GUI tracking)

Files

156 lines under test/bench/ci.

  • test/functional/wallet_keylabels.py +155/-0
  • src/wallet/rpc/addresses.cpp +153/-1
  • src/wallet/wallet.cpp +39/-0
  • src/wallet/walletdb.cpp +26/-0
  • src/wallet/wallet.h +20/-0
  • src/wallet/interfaces.cpp +16/-0
  • src/wallet/rpc/wallet.cpp +13/-0
  • doc/release-notes-36126.md +12/-0
  • src/interfaces/wallet.h +11/-0
  • src/wallet/walletdb.h +4/-0
  • test/functional/test_runner.py +1/-0

Card

The short text the ranking pass compares across PRs.

This PR adds a keylabel record to the wallet database and exposes RPCs (setkeylabel, getkeylabel, listkeylabels) to label master keys by their fingerprint. It aims to improve usability for multisig and hardware wallet setups by identifying cosigners across addresses. achow101 NACKed the PR over the decision to persist labels in the database and the collision risk of 4-byte key fingerprints. Review is paused as the author placed the PR in draft until design consensus is reached.

Data

dossier JSON · extract JSON · model ledger, generated 2026-09-18T04:55, confidence high, input hash ec6e93837440b500
thread read through 2026-09-10 (35 statements), head f9af8d7e2d
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: Needs rebase · draft

Categories

Wallet

P3 · new feature (ranking pass: Moved down: convenience labelling whose persistence design is still contested.)

Key labeling provides a clear UX convenience for multi-signing setups by mapping master key fingerprints to cosigner or hardware device names. Tracking device identities is helpful for multisig workflows, but it is a deferrable feature enhancement.

Membership: Changes walletdb, wallet methods, and wallet RPCs to persist and query key labels.

Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 1