Inside Bitcoin

1# ASMap Tool
2
3Tool for performing various operations on textual and binary asmap files,
4particularly encoding/compressing the raw data to the binary format that can
5be used in Bitcoin Core with the `-asmap` option.
6
7Example usage:
8```
9python3 asmap-tool.py encode /path/to/input.file /path/to/output.file
10python3 asmap-tool.py decode /path/to/input.file /path/to/output.file
11python3 asmap-tool.py diff /path/to/first.file /path/to/second.file
12python3 asmap-tool.py diff_addrs /path/to/first.file /path/to/second.file addrs.file
13```
14These commands may take a few minutes to run with `python3`,
15depending on the amount of data involved and your machine specs.
16Consider using `pypy3` for a faster run time.
17
18### Encoding and Decoding
19
20ASmap files are somewhat large in text form, and need to be encoded
21to binary before being used with Bitcoin Core.
22
23The `encode` command takes an ASmap and an output file.
24
25The `--fill`/`-f` flag further reduces the size of the output file
26by assuming an AS assignment for an unmapped network if an adjacent network is assigned.
27This procedure is lossy, in the sense that it loses information
28about which ranges were unassigned.
29However, if the input ASmap is incomplete,
30this procedure will also reassign ranges that should have an AS assignment,
31resulting in an ASmap that may diverge from reality significantly.
32Finally, another consequence is that the resulting encoded file
33will no longer be meaningful for diffs.
34Therefore only use `--fill` if
35you want to optimise space, you have a reasonably complete ASmap,
36and do not intend to diff the file at a later time.
37
38The `decode` command takes an encoded ASmap and an output file.
39As with `encode`, the `--fill`/`-f` flag reduces the output file size
40by reassigning subnets. Conversely, the `--non-overlapping`/`-n` flag
41increases output size by outputting strictly non-overlapping network ranges.
42
43### Comparing ASmaps
44
45AS control of IP networks changes frequently, therefore it can be useful to get
46the changes between two ASmaps via the `diff` and `diff_addrs` commands.
47
48`diff` takes two ASmap files, and returns a file detailing the changes
49in the state of a network's AS assignment between the first and the second file.
50This command may take a few minutes to run, depending on your machine.
51
52The example below shows the three possible output states:
53- reassigned to a new AS (`AS26496 # was AS20738`),
54- present in the first but not the second (`# 220.157.65.0/24 was AS9723`),
55- or present in the second but not the first (`# was unassigned`).
56
57```
58217.199.160.0/19 AS26496 # was AS20738
59# 220.157.65.0/24 was AS9723
60216.151.172.0/23 AS400080 # was unassigned
612001:470:49::/48 AS20205 # was AS6939
62# 2001:678:bd0::/48 was AS207631
632001:67c:308::/48 AS26496 # was unassigned
64```
65`diff` accepts a `--ignore-unassigned`/`-i` flag
66which ignores networks present in the second but not the first.
67
68`diff_addrs` is intended to provide changes between two ASmaps and
69a node's known peers.
70The command takes two ASmap files, and a file of IP addresses as output by
71the `bitcoin-cli getnodeaddresses` command.
72It returns the changes between the two ASmaps for the peer IPs provided in
73the `getnodeaddresses` output.
74The resulting file is in the same format as the `diff` command shown above.
75
76You can output address data to a file:
77```
78bitcoin-cli getnodeaddresses 0 > addrs.json
79```
80and pass in the address file as the third argument:
81```
82python3 asmap-tool.py diff_addrs path/to/first.file path/to/second.file addrs.json
83```
84