From e047b1deca06fd8aafd4aa31d69fb70ef09a7995 Mon Sep 17 00:00:00 2001 From: jurraca Date: Fri, 7 Mar 2025 13:47:10 +0000 Subject: [PATCH 1/3] contrib: (asmap) add diff-addrs example to README this command exists and works as expected. --- contrib/asmap/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/contrib/asmap/README.md b/contrib/asmap/README.md index 5fab4b285e2..44fa84c00ec 100644 --- a/contrib/asmap/README.md +++ b/contrib/asmap/README.md @@ -9,4 +9,5 @@ Example usage: python3 asmap-tool.py encode /path/to/input.file /path/to/output.file python3 asmap-tool.py decode /path/to/input.file /path/to/output.file python3 asmap-tool.py diff /path/to/first.file /path/to/second.file +python3 asmap-tool.py diff-addrs /path/to/first.file /path/to/second.file addrs.file ``` From 67d5cc2a06e6c74e82221d35e2fc03ed6580b240 Mon Sep 17 00:00:00 2001 From: jurraca Date: Fri, 7 Mar 2025 14:16:30 +0000 Subject: [PATCH 2/3] contrib: (asmap) add documentation on diff and diff-addrs commands --- contrib/asmap/README.md | 45 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/contrib/asmap/README.md b/contrib/asmap/README.md index 44fa84c00ec..c16c74b1314 100644 --- a/contrib/asmap/README.md +++ b/contrib/asmap/README.md @@ -11,3 +11,48 @@ python3 asmap-tool.py decode /path/to/input.file /path/to/output.file python3 asmap-tool.py diff /path/to/first.file /path/to/second.file python3 asmap-tool.py diff-addrs /path/to/first.file /path/to/second.file addrs.file ``` +These commands may take a few minutes to run with `python3`, +depending on the amount of data involved and your machine specs. +Consider using `pypy3` for a faster run time. + +### Comparing ASmaps + +AS control of IP networks changes frequently, therefore it can be useful to get +the changes between to ASmaps via the `diff` and `diff_addrs` commands. + +`diff` takes two ASmap files, and returns a file detailing the changes +in the state of a network's AS assignment between the first and the second file. +This command may take a few minutes to run, depending on your machine. + +The example below shows the three possible output states: +- reassigned to a new AS (`AS26496 # was AS20738`), +- present in the first but not the second (`# 220.157.65.0/24 was AS9723`), +- or present in the second but not the first (`# was unassigned`). + +``` +217.199.160.0/19 AS26496 # was AS20738 +# 220.157.65.0/24 was AS9723 +216.151.172.0/23 AS400080 # was unassigned +2001:470:49::/48 AS20205 # was AS6939 +# 2001:678:bd0::/48 was AS207631 +2001:67c:308::/48 AS26496 # was unassigned +``` +`diff` accepts a `--ignore-unassigned`/`-i` flag +which ignores networks present in the second but not the first. + +`diff_addrs` is intended to provide changes between two ASmaps and +a node's known peers. +The command takes two ASmap files, and a file of IP addresses as output by +the `bitcoin-cli getnodeaddresses` command. +It returns the changes between the two ASmaps for the peer IPs provided in +the `getnodeaddresses` output. +The resulting file is in the same format as the `diff` command shown above. + +You can output address data to a file: +``` +bitcoin-cli getnodeaddresses 0 > addrs.json +``` +and pass in the address file as the third argument: +``` +python3 asmap-tool.py diff_addrs path/to/first.file path/to/second.file addrs.json +``` From 6afffba34e086de4cf0bb86729e12d116c1dcc9b Mon Sep 17 00:00:00 2001 From: jurraca Date: Wed, 12 Mar 2025 17:52:07 +0000 Subject: [PATCH 3/3] contrib: (asmap) add docs about encode and decode commands --- contrib/asmap/README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/contrib/asmap/README.md b/contrib/asmap/README.md index c16c74b1314..0a9d95e49c7 100644 --- a/contrib/asmap/README.md +++ b/contrib/asmap/README.md @@ -15,6 +15,31 @@ These commands may take a few minutes to run with `python3`, depending on the amount of data involved and your machine specs. Consider using `pypy3` for a faster run time. +### Encoding and Decoding + +ASmap files are somewhat large in text form, and need to be encoded +to binary before being used with Bitcoin Core. + +The `encode` command takes an ASmap and an output file. + +The `--fill`/`-f` flag further reduces the size of the output file +by assuming an AS assignment for an unmapped network if an adjacent network is assigned. +This procedure is lossy, in the sense that it loses information +about which ranges were unassigned. +However, if the input ASmap is incomplete, +this procedure will also reassign ranges that should have an AS assignment, +resulting in an ASmap that may diverge from reality significantly. +Finally, another consequence is that the resulting encoded file +will no longer be meaningful for diffs. +Therefore only use `--fill` if +you want to optimise space, you have a reasonably complete ASmap, +and do not intend to diff the file at a later time. + +The `decode` command takes an encoded ASmap and an output file. +As with `encode`, the `--fill`/`-f` flag reduces the output file size +by reassigning subnets. Conversely, the `--non-overlapping`/`-n` flag +increases output size by outputting strictly non-overlapping network ranges. + ### Comparing ASmaps AS control of IP networks changes frequently, therefore it can be useful to get