Skip to content

wallet: Add exportwatchonlywallet RPC to export a watchonly version of a wallet - #32489

Merged
fanquake merged 8 commits into
bitcoin:masterfrom
achow101:export-watchonly-wallet
Jul 3, 2026
Merged

fanquake merged 8 commits into
bitcoin:masterfrom
achow101:export-watchonly-wallet

Conversation

@achow101

@achow101 achow101 commented May 13, 2025 •

Copy link
Copy Markdown
Member

Currently, if a user wants to use an airgapped setup, they need to manually create the watchonly wallet that will live on the online node by importing the public descriptors. This PR introduces exportwatchonlywallet which will create a wallet file with the public descriptors to avoid exposing the specific internals to the user. Additionally, this RPC will copy any existing labels, transactions, and wallet flags. This ensures that the exported watchonly wallet is almost entirely a copy of the original wallet but without private keys.

@DrahtBot

DrahtBot commented May 13, 2025 •

Copy link
Copy Markdown
Contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32489.

Reviews

See the guideline for information on the review process.

Type Reviewers
ACK polespinasa, pablomartin4btc, w0xlt, Sjors
Concept ACK shahsb, vicjuma, stringintech, enirox001
Stale ACK ryanofsky, rkrux, Eunovo

If your review is incorrectly listed, please copy-paste <!--meta-tag:bot-skip--> into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

  • #35445 (wallet, descriptor: Revert StringType::COMPAT for Miniscript expressions and drop the concept of a Descriptor ID that can be validated by achow101)
  • #35444 (wallet: make descriptor SPKM mutex non-recursive by w0xlt)
  • #35377 (wallet: Allow importing of descriptors without private keys when the wallet has the private keys by achow101)
  • #34993 (wallet: NotifyCanGetAddressesChanged when advancing next_index by davidgumberg)
  • #34909 (wallet, refactor: modularise wallet by extracting out legacy wallet migration by rkrux)
  • #34861 (wallet: Add importdescriptors interface by polespinasa)
  • #33392 (wallet, rpc: add UTXO set check and incremental rescan to importdescriptors by musaHaruna)
  • #33034 (wallet: Store transactions in a separate sqlite table by achow101)
  • #32895 (wallet: Prepare for future upgrades by recording versions of last client to open and decrypt by achow101)
  • #32784 (wallet: derivehdkey RPC to get xpub at arbitrary path by Sjors)
  • #27865 (wallet: Track no-longer-spendable TXOs separately by achow101)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

@achow101
achow101 force-pushed the export-watchonly-wallet branch from dc39a64 to 30ebc97 Compare May 13, 2025 22:38
@DrahtBot

Copy link
Copy Markdown
Contributor

🚧 At least one of the CI tasks failed.
Task lint: https://github.com/bitcoin/bitcoin/runs/42170822821
LLM reason (✨ experimental): The CI failure is due to linting errors in Python and C++ code.

Hints

Try to run the tests locally, according to the documentation. However, a CI failure may still
happen due to a number of reasons, for example:

  • Possibly due to a silent merge conflict (the changes in this pull request being
    incompatible with the current code in the target branch). If so, make sure to rebase on the latest
    commit of the target branch.

  • A sanitizer issue, which can only be found by compiling with the sanitizer and running the
    affected test.

  • An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

@shahsb shahsb left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concept ACK

@Sjors

Sjors commented May 19, 2025 •

Copy link
Copy Markdown
Member

Concept ACK

This might also be useful in a multisig airgapped scenario (where two private keys never go near each other).

E.g. create a 2-of-2 MuSig2 wallet on your offline machine, with one hot key held by Bitcoin Core and the other a hardware wallet. Export the watch-only wallet and put it on the online machine. You can then use the hardware wallet on either the online or offline machine to co-sign.

Though for that to work, the exportwatchonlywallet should have an option to set the external_signer flag (the offline wallet might not have this flag, depending on how you set it up).

@Sjors Sjors mentioned this pull request May 19, 2025
12 of 20 tasks
@achow101
achow101 force-pushed the export-watchonly-wallet branch from def9594 to d41059b Compare May 20, 2025 00:55

@Sjors Sjors left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

utACK eed2ac7161ecc60982a3f3f304ce93b0b58fc219

Left a bunch of comments, but I think they can wait for a followup.

Comment thread src/script/descriptor.h Resolved
[offline]$ ./build/bin/bitcoin-cli -signet -rpcwallet="offline_wallet" listdescriptors \
| jq -r '.descriptors' \
>> /path/to/descriptors.json
[offline]$ ./build/bin/bitcoin-cli -signet -rpcwallet="offline_wallet" -named exportwatchonlywallet \

@Sjors Sjors Jul 1, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In eed2ac7161ecc60982a3f3f304ce93b0b58fc219 doc: update offline-signing-tutorial to use exportwatchonlywallet rpc nit: could use bitcoin rpc and drop -named.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer to keep it to explicitly indicate the argument being set.

Comment thread src/script/descriptor.cpp Resolved
return m_wallet_descriptor.descriptor->IsSingleType() &&
m_wallet_descriptor.descriptor->IsRange() &&
(HavePrivateKeys() || m_wallet_descriptor.next_index < m_wallet_descriptor.range_end);
(HavePrivateKeys() || m_wallet_descriptor.next_index < m_wallet_descriptor.range_end || m_wallet_descriptor.descriptor->CanSelfExpand());

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In 336042e wallet: Use Descriptor::CanSelfExpand() in CanGetAddresses(): could add a direct test, in scriptpubkeyman_tests.cpp:

BOOST_AUTO_TEST_CASE(desc_spkm_can_get_addresses_self_expand)
{
    // A watch-only, unhardened, ranged descriptor can always
    // derive further addresses on its own. CanGetAddresses() must therefore
    // report true even when the cache is exhausted (next_index == range_end)
    // and no private keys are available: self-expansion is enough.
    CWallet keystore(m_node.chain.get(), "", CreateMockableWalletDatabase());
    keystore.SetWalletFlag(WALLET_FLAG_DESCRIPTORS);

    CExtKey extkey;
    extkey.SetSeed(std::array<std::byte, 32>{});

    FlatSigningProvider keys;
    std::string error;
    auto descs = Parse("wpkh(" + EncodeExtPubKey(extkey.Neuter()) + "/*)", keys, error, /*require_checksum=*/false);
    BOOST_CHECK(!descs.empty());

    // Collapsed range (range_end == next_index == 0): nothing is cached.
    WalletDescriptor w_desc(std::move(descs.at(0)), /*creation_time=*/1, /*range_start=*/0, /*range_end=*/0, /*next_index=*/0);

    // keypool_size=0 so the import does not top up and extend range_end.
    auto spkm = DescriptorScriptPubKeyMan::CreateFromImport(keystore, w_desc, /*keypool_size=*/0, keys);

    BOOST_CHECK(!spkm->HavePrivateKeys());
    BOOST_CHECK(spkm->CanGetAddresses());
}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is necessary, there are functional test which cover this.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does, but it's in a later commit and quite indirect.

Comment thread src/wallet/export.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
Comment thread src/script/descriptor.cpp Resolved
return m_wallet_descriptor.descriptor->IsSingleType() &&
m_wallet_descriptor.descriptor->IsRange() &&
(HavePrivateKeys() || m_wallet_descriptor.next_index < m_wallet_descriptor.range_end);
(HavePrivateKeys() || m_wallet_descriptor.next_index < m_wallet_descriptor.range_end || m_wallet_descriptor.descriptor->CanSelfExpand());

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in 336042e wallet: Use Descriptor::CanSelfExpand() in CanGetAddresses()

Just a question (maybe a stupid one 😅) the fact that next_index < range_end isn't enough to know if it can be expanded?

I guess the question in other words would be like: if it cannot be expanded will range_end != 0 in any moment?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When next_index < range_end, we have enough information, either in the descriptor or its cache, to continue to produce scripts for the descriptor up to at least range_end. If the descriptor uses unhardened derivation, once we get to next_index == range_end, we are still able to expand the descriptor because unhardened derivation does not require private keys. However, if the descriptor does use hardened derivation, it is no longer possible to make any scripts past range_end because private keys are required.

Comment thread src/wallet/wallet.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
Comment thread src/wallet/export.cpp Resolved
@polespinasa

Copy link
Copy Markdown
Member

wops forgot my main review comment

ACK eed2ac7161ecc60982a3f3f304ce93b0b58fc219

Didn't test this time, but I did in my previous review when writing the documentation update.
Left some comments, moslty nits and some questions.
The race condition and the files cleanup are not critical so maybe it's ok to just ignore or do it in a follow-up.

@sedited

sedited commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

@achow101 do you want to address the review here, or in a follow up?

@w0xlt w0xlt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

utACK eed2ac7161ecc60982a3f3f304ce93b0b58fc219

achow101 added 4 commits July 2, 2026 13:04
CanSelfExpand() reports whether a descriptor can be expanded without
needing any caches or private keys to be provided by the caller of
Expand().
If a descriptor does not need any caches or private keys in order to
expand, then CanGetAddresses() should return true for that descriptor.
If a new WalletDescriptor is provided to us with a cache, write the
cache to disk as well.
When listdescriptors retrieves the descriptors from the wallet, instead
of having this logic in the RPC, move it into CWallet itself. This
will enable other functions to get the descriptors in an exportable
form.
@polespinasa

polespinasa commented Jul 2, 2026 •

Copy link
Copy Markdown
Member
2026-07-02T21:14:25.4433180Z  node1 2026-07-02T21:14:24.648768Z [http.00] [wallet/sqlite.cpp:43] [ErrorLogCallback] [warning] SQLite Error. Code: 266. Message: os_win.c:50129: (33) winRead(D:\a\bitcoin\bitcoin\_ _\test_runner_₿_🏃_20260702_210457\wallet_exported_watchonly_217\exported_wallets\basic_watchonly.dat) - The process cannot access the file because another process has locked a portion of the file. 

I think the problem is that sqlite3_open() is not allow to create/open the file because you locked it before with FileLock.

I have no idea how FileLock works, but according to claudio it has some undefined cross-platform flaky behavior.
Seems that windows normally try to enforce those locks while in linux they are mostly advisory and ignored in practice. So basically it is doing nothing.

I think unlocking the file before BackupWallet should work. If not, after removing the fs::remove(destination); line, the race condition cannot happen anymore (I think) so removing the lock should be fine because a racy call would fail in fs::exist.

achow101 and others added 4 commits July 2, 2026 14:49
ExportWatchOnly produces a watchonly wallet file from a CWallet. This
can be restored onto another instance of Bitcoin Core to allow that
instance to watch the same descriptors, and also have all of the same
initial address book and transactions.
@achow101

achow101 commented Jul 2, 2026

Copy link
Copy Markdown
Member Author

Dropped the file lock, I think it's unnecessary as long as we only remove the file on failure.

@polespinasa

Copy link
Copy Markdown
Member

lgtm ACK a15bdc0

@pablomartin4btc pablomartin4btc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re-ACK a15bdc0

Since my last review: addressed feedback from @Sjors and @polespinasa plus dropping the file lock from fs::path& destination in ExportWatchOnlyWallet().

@w0xlt w0xlt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm reACK a15bdc0

@Sjors

Sjors commented Jul 3, 2026

Copy link
Copy Markdown
Member

re-utACK a15bdc0

Since #33032 landed, you could make the temporary wallet memory-only, which gets rid of some cleanup code.

@pablomartin4btc

Copy link
Copy Markdown
Member

Since #33032 landed, you could make the temporary wallet memory-only, which gets rid of some cleanup code.

Done in #35655.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.