doc: improve NODE_NETWORK_LIMITED documentation per BIP159

jonatack commented at 5:32 pm on February 5, 2025: member

Per BIP159, the definition is:

NODE_NETWORK_LIMITED || bit 10 (0x400) || If signaled, the peer MUST be capable of serving at least the last 288 blocks (~2 days).

Fix our documentation related to this, and add BIP159 mentions where relevant.

Originally this PR also tried to clarify the following, but it was dropped in response to review:

NODE_NETWORK_LIMITED is set by default, and it only signals a pruned or otherwise limited node if NODE_NETWORK is not also set. See the init setup logic or IsLimitedPeer() in src/net_processing.cpp for examples.

DrahtBot commented at 5:32 pm on February 5, 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/31805.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Stale ACK	Sjors, kevkevinpal

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

DrahtBot added the label Docs on Feb 5, 2025

jonatack force-pushed on Feb 5, 2025

jonatack force-pushed on Feb 6, 2025

Sjors commented at 8:32 am on February 6, 2025: member

ACK 39e15f6ca4fd44cc459d80b7a1540c03923906dd

It’s good to clarify the description, because the term NODE_NETWORK_LIMITED has confused me before into assuming that a node that isn’t limited doesn’t use the flag. But instead it signals the minimum capability, and NODE_NETWORK is added when ready to signal full capability. Too late to rename them.

You can also see this in the init.cpp.

We start with just NODE_NETWORK_LIMITED:

https://github.com/bitcoin/bitcoin/blob/82ba50513425bf0568d4f9456282dc9713132490/src/init.cpp#L807-L811

And then add NODE_NETWORK, if possible:

https://github.com/bitcoin/bitcoin/blob/82ba50513425bf0568d4f9456282dc9713132490/src/init.cpp#L1733-L1739

We don’t drop NODE_NETWORK_LIMITED.

in src/bitcoin-cli.cpp:707 in 39e15f6ca4 outdated

703@@ -704,7 +704,7 @@ class NetinfoRequestHandler : public BaseRequestHandler
704         "           \"b\" - BLOOM: peer can handle bloom-filtered connections (see BIP 111)\n"
705         "           \"w\" - WITNESS: peer can be asked for blocks and transactions with witness data (SegWit)\n"
706         "           \"c\" - COMPACT_FILTERS: peer can handle basic block filter requests (see BIPs 157 and 158)\n"
707-        "           \"l\" - NETWORK_LIMITED: peer limited to serving only the last 288 blocks (~2 days)\n"
708+        "           \"l\" - NETWORK_LIMITED: peer can serve at least the last 288 blocks (~2 days); may signal a pruned node if NETWORK is unset (see BIP 159)\n"

maflcko commented at 8:52 am on February 6, 2025:

I understand that bip 159 uses the word “pruning” and that it can be used as an alias for “limited”, but internally in Bitcoin Core, pruning usually means that blocks are deleted. However, a limited peer may be limited for other reasons, for example:

AU-background download is still in progress (possible today in Bitcoin Core)
A node that just wants to limit itself (similar to maxuploadtarget?)
…

So I think it would be better to not imply the two words mean the same here.

jonatack commented at 3:20 pm on February 6, 2025:

Thanks, updated.

kevkevinpal commented at 2:11 pm on February 6, 2025: contributor

ACK 39e15f6

I agree with @maflcko maybe instead of using pruned node we can refer to the node as “network limited node”

jonatack force-pushed on Feb 6, 2025

jonatack commented at 3:23 pm on February 6, 2025: member

Updated per review feedback (thanks!)

It’s good to clarify the description, because the term NODE_NETWORK_LIMITED has confused me before into assuming that a node that isn’t limited doesn’t use the flag. But instead it signals the minimum capability, and NODE_NETWORK is added when ready to signal full capability. Too late to rename them.

Well said – same for me.

in src/bitcoin-cli.cpp:708 in 21233a7ea5 outdated

703@@ -704,7 +704,8 @@ class NetinfoRequestHandler : public BaseRequestHandler
704         "           \"b\" - BLOOM: peer can handle bloom-filtered connections (see BIP 111)\n"
705         "           \"w\" - WITNESS: peer can be asked for blocks and transactions with witness data (SegWit)\n"
706         "           \"c\" - COMPACT_FILTERS: peer can handle basic block filter requests (see BIPs 157 and 158)\n"
707-        "           \"l\" - NETWORK_LIMITED: peer limited to serving only the last 288 blocks (~2 days)\n"
708+        "           \"l\" - NETWORK_LIMITED: peer can serve at least the last 288 blocks (~2 days); signals a pruned or otherwise\n"
709+        "                                  limited peer (i.e., assumeutxo download in progress) if NETWORK is unset (see BIP 159)\n"

Sjors commented at 3:29 pm on February 6, 2025:

21233a7ea588f69011dcf3cfab595a5e643d0834: we should probably try to keep the output lines of bitcoin-cli -netinfo help below 80 characters. It doesn’t wrap in a nice way.

jonatack commented at 3:33 pm on February 6, 2025:

Don’t disagree but that would require reformatting most of the help. For here kept it shorter than the longest line (“If that argument is passed…”) and the same as other longer ones.

maflcko commented at 3:59 pm on February 6, 2025:

“i.e.” is latin and stands for “id est” (“that is”). I think what you want is to given an example? That’d be “e.g.”, which stands for “exempli gratia” (“for example”). See also

0src/net_processing.cpp:/** Whether this peer can only serve limited recent blocks (e.g. because
1src/net_processing.cpp- *  it prunes old blocks) */

However, I think it is fine to not list all examples here, because the list can never be known to be complete anyway. Just adding the reference to the BIP seems fine.

jonatack commented at 4:05 pm on February 6, 2025:

Thanks for the reminder, for some reason I keep thinking i.e. means “for example.”

Are you suggesting s/i.e./e.g./, or removing the example? My thought was that this doc is a bit more user-facing, so more explanation or an example might be helpful.

jonatack commented at 4:20 pm on February 6, 2025:

Removed the example here.

jonatack commented at 4:23 pm on February 6, 2025:

Shortened the line length in the last push.

Sjors commented at 6:43 pm on February 6, 2025:

Just the line you’re touching is fine, yes. Thanks.

Sjors commented at 6:44 pm on February 6, 2025:

“example given” is how I remember e.g.

jonatack force-pushed on Feb 6, 2025

in src/bitcoin-cli.cpp:708 in 658be9add9 outdated

703@@ -704,7 +704,8 @@ class NetinfoRequestHandler : public BaseRequestHandler
704         "           \"b\" - BLOOM: peer can handle bloom-filtered connections (see BIP 111)\n"
705         "           \"w\" - WITNESS: peer can be asked for blocks and transactions with witness data (SegWit)\n"
706         "           \"c\" - COMPACT_FILTERS: peer can handle basic block filter requests (see BIPs 157 and 158)\n"
707-        "           \"l\" - NETWORK_LIMITED: peer limited to serving only the last 288 blocks (~2 days)\n"
708+        "           \"l\" - NETWORK_LIMITED: peer can serve at least the last 288 blocks (~2 days); signals a\n"
709+        "                                  pruned or otherwise limited peer if NETWORK is unset (see BIP 159)\n"

luke-jr commented at 2:23 am on February 8, 2025:

That’s not guaranteed. Adding this is technically incorrect, and doesn’t provide any real information, just makes it more complex.

jonatack commented at 3:58 am on February 8, 2025:

Can you please clarify your comment – what isn’t correct? What do you suggest instead?

ajtowns commented at 8:38 am on February 12, 2025:

Dropping “; signals a pruned … (see BIP 159)” seems clearer, and matches the definition of NETWORK_LIMITED provided by BIP 159.

jonatack commented at 8:53 pm on February 12, 2025:

Done.

luke-jr changes_requested

Improve NODE_NETWORK_LIMITED documentation per BIP159 cce0c5b416

jonatack force-pushed on Feb 12, 2025

jonatack commented at 8:58 pm on February 12, 2025: member

In response to review feedback, I’ve reduced the scope of this PR and updated the pull description. Originally this tried to clarify the following, but it is now dropped:

NODE_NETWORK_LIMITED is set by default, and it only signals a pruned or otherwise limited node if NODE_NETWORK is not also set (see the init setup logic or IsLimitedPeer() in src/net_processing.cpp for examples).

jonasschnelli commented at 7:56 pm on February 13, 2025: contributor

I haven’t looked at this closely, but it could be that the implementation needs an update. The important point is fingerprinting resistance.

During designing the BIP, we decided that LIMITED NODES should always cut off at HEAD-288 to avoid getting fingerprinted by leaking the prune depth.

See the BIP:

Counter-measures for peer fingerprinting

Peers may have different prune depths (depending on the peers configuration, disk space, etc.) which can result in a fingerprinting weakness (finding the prune depth through getdata requests). NODE_NETWORK_LIMITED supporting peers SHOULD avoid leaking the prune depth and therefore not serve blocks deeper than the signaled NODE_NETWORK_LIMITED threshold (288 blocks).

jonatack commented at 8:10 pm on February 13, 2025: member

@jonasschnelli Good point. Yes. A BIP159 node MUST be able to serve at least the latest 288 blocks, but SHOULD not serve more.

jonatack commented at 9:08 pm on February 13, 2025: member

During designing the BIP, we decided that LIMITED NODES should always cut off at HEAD-288 to avoid getting fingerprinted by leaking the prune depth.

Maybe the BIP and documentation here should clarify that limited nodes are defined by both the limited bit being set and by the node network bit not being set, as described in #31805 (comment).

Edit: after offline discussion with @jonasschnelli and the BIP editors, will look at slightly clarifying BIP159.

jonatack commented at 9:00 pm on February 14, 2025: member

Opened https://github.com/bitcoin/bips/pull/1768 and putting this in draft for now.

jonatack marked this as a draft on Feb 14, 2025

doc: improve NODE_NETWORK_LIMITED documentation per BIP159 #31805

Code Coverage & Benchmarks

Reviews