This renames the utxo_to_sqlite.py script to utxo_convert.py, and:
--format (default depends on filename extension).The goal is giving users a way to construct the UTXO set in a textual, greppable format.
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/34324.
See the guideline for information on the review process.
| Type | Reviewers |
|---|---|
| Concept ACK | nervana21 |
If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.
No conflicts as of last run.
Possible typos and grammar issues:
2026-03-12 13:42:27
61+
62+def byte_to_base58(b, version):
63+ "Compute the Base58Check encoding of an input byte array with given version."""
64+ result = ''
65+ b = bytes([version]) + b # prepend version
66+ b += hashlib.sha256(hashlib.sha256(b).digest()).digest() # append checksum
199+def scriptpubkey_to_descriptor(spk, network_string):
200+ """Infer a descriptor for the specified scriptpubkey."""
201+ if len(spk) == 25 and spk[0] == 0x76 and spk[1] == 0xa9 and spk[2] == 20 and spk[23] == 0x88 and spk[24] == 0xac:
202+ return "addr(" + byte_to_base58(spk[3:23], P2PKH_VERSIONS[network_string]) + ")"
203+ if len(spk) == 23 and spk[0] == 0xa9 and spk[1] == 20 and spk[22] == 0x87:
204+ return "addr(" + byte_to_base58(spk[1:21], P2SH_VERSIONS[network_string]) + ")"
based on https://github.com/bitcoin/bitcoin/blob/fa942332b40c97375af0722f32f7575bca3af819/src/script/solver.cpp#L149 we need to skip the second element as well:
0 return "addr(" + byte_to_base58(spk[2:22], P2SH_VERSIONS[network_string]) + ")"
212+ if multi is not None:
213+ keys, m = multi
214+ return f"multi({m}," + ",".join(key.hex() for key in keys) + ")"
215+ return "raw(" + spk.hex() + ")"
216+
217+def read_varint(f):
merge the two tools into one
+1 for that
🚧 At least one of the CI tasks failed.
Task lint: https://github.com/bitcoin/bitcoin/actions/runs/21081641168/job/60636466740
LLM reason (✨ experimental): Lint failure: duplicate dictionary key “Testnet3” in contrib/utxo-tools/utxo_to_csv.py.
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.
138+ ret = bech32_encode(encoding, hrp, [witver] + convertbits(witprog, frombits=8, tobits=5))
139+ return ret
140+
141+# Address/descriptor encoding
142+
143+def decode_bare_multisig(spk):
137+ encoding = Encoding.BECH32 if witver == 0 else Encoding.BECH32M
138+ ret = bech32_encode(encoding, hrp, [witver] + convertbits(witprog, frombits=8, tobits=5))
139+ return ret
140+
141+# Address/descriptor encoding
142+
This solution is based on l0rinc’s comment below. Please feel free to ignore if there is a better way to address the issue.
0
1def _pubkey_get_len(first_byte):
2 """Computes the length of a pubkey with a given first byte."""
3 if first_byte in (2, 3):
4 return 33
5 if first_byte in (4, 6, 7):
6 return 65
7 return 0
8
9def _pubkey_is_valid_size(key):
10 """True iff key is non-empty and first byte implies length == len(key)."""
11 return len(key) > 0 and _pubkey_get_len(key[0]) == len(key)
162+ return None
163+ # Decode public keys
164+ while pos < len(spk) and (spk[pos] == 33 or spk[pos] == 65):
165+ if pos + 1 + spk[pos] > len(spk):
166+ return None
167+ keys.append(spk[pos + 1:pos + 1 + spk[pos]])
Use the new helper in the key loop.
0 key_blob = spk[pos + 1:pos + 1 + spk[pos]]
1 if not _pubkey_is_valid_size(key_blob):
2 return None
3 keys.append(key_blob)
utxo_to_sqlite.py script (renaming it to utxo_convert.py).
@sedited That’s a fair question.
I wrote this when I wanted to grep the addresses in the UTXO set for partial matches, and thought this may be a generally useful conversion. While there certainly are libraries that can convert scriptPubKeys to addresses, I think it’s valuable for technical-but-not-programmer people to be able to query the UTXO set with a provided tool.
I didn’t consider sqlite-to-csv, or other direct sqlite tooling, because I’m not really familiar with it. A reasonable alternative here might be an option to add descriptor/address fields to the sqlite dump (or maybe generally control what fields go into it).
I think it’s valuable for technical-but-not-programmer people to be able to query the UTXO set with a provided tool.
Mmh, that seems like a weak motivation given llms and that most can just use an RPC call for that. I think what I’m not sure about is adding a bunch of general purpose parsing logic specifically to this contrib script. If the problem is that we wouldn’t want to rely on an external parser, I remember we’ve discussed making the core functionality of the test framework a reusable library. Would that be a better approach to this problem in general? I think we should eventually work towards migrating these tools to c++ and re-use our existing code.
All that said, I also don’t want to block this PR if it is actually useful to people.
I think what I’m not sure about is adding a bunch of general purpose parsing logic specifically to this contrib script. If the problem is that we wouldn’t want to rely on an external parser, I remember we’ve discussed making the core functionality of the test framework a reusable library. Would that be a better approach to this problem in general?
I don’t like that. I think our test framework should remain internal, so we are not beholden to interface promises for external users. The approach here indeed duplicates in a minimal way, but tests against the test framework, so it does at least inherit some of the assurances it provides.
I think we should eventually work towards migrating these tools to c++ and re-use our existing code.
Yeah, that may make sense for some of these tools. If there is interest, I’m willing to look into that.
All that said, I also don’t want to block this PR if it is actually useful to people.
Ok, let’s see what others think.
most can just use an RPC call for that.
Not sure what you’re talking about here.