help: enrich help text for `-loadblock`

HowHsu commented at 5:41 pm on September 8, 2025: none

-loadblock doesn’t support XOR-ed files, mention it in its help text to avoid troubles for users.

DrahtBot commented at 5:41 pm on September 8, 2025: 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/33343.

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#31260 (scripted-diff: Type-safe settings retrieval by ryanofsky)
#17783 (common: Disallow calling IsArgSet() on ALLOW_LIST options by ryanofsky)
#17581 (refactor: Remove settings merge reverse precedence code by ryanofsky)
#17580 (refactor: Add ALLOW_LIST flags and enforce usage in CheckArgFlags by ryanofsky)
#17493 (util: Forbid ambiguous multiple assignments in config file by ryanofsky)

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.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

“Imports blocks from external file” -> “Imports blocks from an external file” [missing article “an” makes the phrase ungrammatical and may hinder comprehension]

drahtbot_id_5_m

in src/init.cpp:503 in 39a2e4ac5d outdated

499@@ -500,7 +500,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
500     argsman.AddArg("-dbcache=<n>", strprintf("Maximum database cache size <n> MiB (minimum %d, default: %d). Make sure you have enough RAM. In addition, unused memory allocated to the mempool is shared with this cache (see -maxmempool).", MIN_DB_CACHE >> 20, DEFAULT_DB_CACHE >> 20), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
501     argsman.AddArg("-includeconf=<file>", "Specify additional configuration file, relative to the -datadir path (only useable from configuration file, not command line)", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
502     argsman.AddArg("-allowignoredconf", strprintf("For backwards compatibility, treat an unused %s file in the datadir as a warning, not an error.", BITCOIN_CONF_FILENAME), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
503-    argsman.AddArg("-loadblock=<file>", "Imports blocks from external file on startup", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
504+    argsman.AddArg("-loadblock=<file>", "Imports blocks from external file on startup, it doesn't support XOR-ed files", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);

l0rinc commented at 9:44 pm on September 8, 2025:

For context we could mention the discussions in #33280 that lead here.

nit: I’d personally would prefer calling it by it’s function (obfuscation) instead of the implementation detail (xor)

0    argsman.AddArg("-loadblock=<file>", "Imports blocks from external file on startup (does not support obfuscated blocks)", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);

HowHsu commented at 2:35 pm on September 13, 2025:

Hi l0rinc, I’ve updated the code. Since I’m not very familiar with the Bitcoin Core workflow, I wasn’t sure if it’s appropriate for me to mark this conversation as resolved, but I went ahead and did so. Please feel free to reopen it if that’s not the right process.

l0rinc commented at 10:42 pm on September 8, 2025: contributor

I’m not sure it’s a documentation issue, I think we should rather fix it by adding the obfuscation key to the AutoFile instead. I will investigate if adding a fix and updating feature_loadblock.py makes more sense and will push an alternative PR to see what people think is more appropriate here. Thanks for jumping on this so quickly.

l0rinc commented at 10:59 pm on September 8, 2025: contributor

I wasn’t aware of this, it seems we have a dedicated tool to https://github.com/bitcoin/bitcoin/tree/master/contrib/linearize. It’s explicitly written to deobfuscate blocks from your node’s blk*.dat (handling XOR if present) and writes them plain to output_file or to an output/blkNNNNN.dat.

HowHsu commented at 3:56 am on September 9, 2025: none

I’m not sure it’s a documentation issue, I think we should rather fix it by adding the obfuscation key to the AutoFile instead. I will investigate if adding a fix and updating feature_loadblock.py makes more sense and will push an alternative PR to see what people think is more appropriate here. Thanks for jumping on this so quickly.

Hi l0rinc, I don’t think it’s good to either

update the Autofile code to use the current obfuscation key by the running node this makes it too restrictive.
add a new argument like -loadblock-xor=xor_value to indicate the xor key used by -loadblock since we can restore the obfuscated file with some external tools, it’s already very flexible, adding -loadblock-xor would be kind of meaningless. That’s why I only updated the help message.

l0rinc commented at 4:32 am on September 9, 2025: contributor

I wrote that before I found the contrib/linearize tool, which seems to be designed for unobfuscated block sharing anyway - maybe it can solve your problem of using -loadblock. If it does, we might want to mention that instead in the argument’s documentation.

mzumsande commented at 3:06 pm on September 10, 2025: contributor

I wrote that before I found the contrib/linearize tool, which seems to be designed for unobfuscated block sharing anyway

It was originally designed to to something else (create a linear, in order chain), so using the tool has side effects (maybe the users doesn’t want to lose historical forks for some reason). Could mention it as an example though.

I’m not convinced that changing the interface to support adding a xor-key per -loadblock arg (or one for all?) is really worth the effort, since I’m not sure people out there actually use this feature today, and, if so, to what end.

HowHsu force-pushed on Sep 13, 2025

HowHsu requested review from l0rinc on Sep 13, 2025

help: enrich help text for `-loadblock`

`-loadblock` doesn't support obfuscated blocks, mention it in its help text
to avoid troubles for users.

Signed-off-by: Hao Xu <hao.xu@linux.dev>

d787e5539d

HowHsu force-pushed on Sep 15, 2025

in src/init.cpp:503 in d787e5539d

499@@ -500,7 +500,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
500     argsman.AddArg("-dbcache=<n>", strprintf("Maximum database cache size <n> MiB (minimum %d, default: %d). Make sure you have enough RAM. In addition, unused memory allocated to the mempool is shared with this cache (see -maxmempool).", MIN_DB_CACHE >> 20, DEFAULT_DB_CACHE >> 20), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
501     argsman.AddArg("-includeconf=<file>", "Specify additional configuration file, relative to the -datadir path (only useable from configuration file, not command line)", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
502     argsman.AddArg("-allowignoredconf", strprintf("For backwards compatibility, treat an unused %s file in the datadir as a warning, not an error.", BITCOIN_CONF_FILENAME), ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
503-    argsman.AddArg("-loadblock=<file>", "Imports blocks from external file on startup", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
504+    argsman.AddArg("-loadblock=<file>", "Imports blocks from external file on startup (does not support obfuscated blocks, see Issue #33280 for related conversation, and see contrib/linearize tool for clues of deobfuscation and reobfuscation)", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);

l0rinc commented at 6:30 pm on September 15, 2025:

0    argsman.AddArg("-loadblock=<file>", "Imports blocks from external file on startup (obfuscated block files are not supported; use contrib/linearize to export blocks to a plain, loadable format)", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);

l0rinc changes_requested

l0rinc commented at 6:33 pm on September 15, 2025: contributor

@HowHsu Did you try contrib/linearize yourself to export the .blk files for -loadblock? Did it solve your issue? I have suggested a simpler documentation, do you think that help others to use the linearize tool when they’re in your situation?

HowHsu commented at 1:19 pm on September 16, 2025: none

@HowHsu Did you try contrib/linearize yourself to export the .blk files for -loadblock? Did it solve your issue? I have suggested a simpler documentation, do you think that help others to use the linearize tool when they’re in your situation?

I didn’t, but I read the code of them (files under contrib/linearize), linearize-data.py only generates a list of blocks based on a list of block hashes generated by linearize-hashes.py, which accepts a height range [min_height, max_height] and get block hashes of these heights from RPC. That is said, the blocks are not arbitrary, if a user use -loadblock to load some discontinuous blocks, it has to generate its own block hashes list to feed linearize-data.py. So I just add for clues of deobfuscation and reobfuscation. For my scenario, I’ve found another way to do the test, so I didn’t continue it with -loadblock

HowHsu requested review from l0rinc on Sep 16, 2025

l0rinc commented at 9:12 pm on September 16, 2025: contributor

I think we should try it ourselves before recommending it in the documentation

luke-jr commented at 5:29 am on September 18, 2025: member

I think it would make sense to support XOR for loadblock if we’re assuming the chain has data that can trigger bad things

maflcko commented at 1:55 pm on September 25, 2025: member

I think we should try it ourselves before recommending it in the documentation

It is already tested in test/functional/feature_loadblock.py, no?

HowHsu commented at 3:42 pm on September 25, 2025: none

I think it would make sense to support XOR for loadblock if we’re assuming the chain has data that can trigger bad things

Hi Luke, what do you mean by “assuming the chain has data that can trigger bad things”

HowHsu commented at 3:44 pm on September 25, 2025: none

I think we should try it ourselves before recommending it in the documentation

I’ll try that later when I have some time for it, though the function of the script is already clear enough for me by carefully reading the code.

l0rinc commented at 4:17 pm on September 25, 2025: contributor

It is already tested in test/functional/feature_loadblock.py, no?

That’s where I found it, but to see if it solves the original problem for why this PR was opened, it would help to have personal experience with the script so that we can document it such that others don’t need to browse the tests. I’m also fine with anyone else having experience with the script suggesting a useful help text.

help: enrich help text for -loadblock #33343

Code Coverage & Benchmarks

Reviews

Conflicts

LLM Linter (✨ experimental)

help: enrich help text for `-loadblock` #33343