github.com/ethw3/go-ethereuma@v0.0.0-20221013053120-c14602a4c23c/cmd/devp2p/README.md (about)

     1  # The devp2p command
     2  
     3  The devp2p command line tool is a utility for low-level peer-to-peer debugging and
     4  protocol development purposes. It can do many things.
     5  
     6  ### ENR Decoding
     7  
     8  Use `devp2p enrdump <base64>` to verify and display an Ethereum Node Record.
     9  
    10  ### Node Key Management
    11  
    12  The `devp2p key ...` command family deals with node key files.
    13  
    14  Run `devp2p key generate mynode.key` to create a new node key in the `mynode.key` file.
    15  
    16  Run `devp2p key to-enode mynode.key -ip 127.0.0.1 -tcp 30303` to create an enode:// URL
    17  corresponding to the given node key and address information.
    18  
    19  ### Maintaining DNS Discovery Node Lists
    20  
    21  The devp2p command can create and publish DNS discovery node lists.
    22  
    23  Run `devp2p dns sign <directory>` to update the signature of a DNS discovery tree.
    24  
    25  Run `devp2p dns sync <enrtree-URL>` to download a complete DNS discovery tree.
    26  
    27  Run `devp2p dns to-cloudflare <directory>` to publish a tree to CloudFlare DNS.
    28  
    29  Run `devp2p dns to-route53 <directory>` to publish a tree to Amazon Route53.
    30  
    31  You can find more information about these commands in the [DNS Discovery Setup Guide][dns-tutorial].
    32  
    33  ### Node Set Utilities
    34  
    35  There are several commands for working with JSON node set files. These files are generated
    36  by the discovery crawlers and DNS client commands. Node sets also used as the input of the
    37  DNS deployer commands.
    38  
    39  Run `devp2p nodeset info <nodes.json>` to display statistics of a node set.
    40  
    41  Run `devp2p nodeset filter <nodes.json> <filter flags...>` to write a new, filtered node
    42  set to standard output. The following filters are supported:
    43  
    44  - `-limit <N>` limits the output set to N entries, taking the top N nodes by score
    45  - `-ip <CIDR>` filters nodes by IP subnet
    46  - `-min-age <duration>` filters nodes by 'first seen' time
    47  - `-eth-network <mainnet/rinkeby/goerli/ropsten>` filters nodes by "eth" ENR entry
    48  - `-les-server` filters nodes by LES server support
    49  - `-snap` filters nodes by snap protocol support
    50  
    51  For example, given a node set in `nodes.json`, you could create a filtered set containing
    52  up to 20 eth mainnet nodes which also support snap sync using this command:
    53  
    54      devp2p nodeset filter nodes.json -eth-network mainnet -snap -limit 20
    55  
    56  ### Discovery v4 Utilities
    57  
    58  The `devp2p discv4 ...` command family deals with the [Node Discovery v4][discv4]
    59  protocol.
    60  
    61  Run `devp2p discv4 ping <enode/ENR>` to ping a node.
    62  
    63  Run `devp2p discv4 resolve <enode/ENR>` to find the most recent node record of a node in
    64  the DHT.
    65  
    66  Run `devp2p discv4 crawl <nodes.json path>` to create or update a JSON node set.
    67  
    68  ### Discovery v5 Utilities
    69  
    70  The `devp2p discv5 ...` command family deals with the [Node Discovery v5][discv5]
    71  protocol. This protocol is currently under active development.
    72  
    73  Run `devp2p discv5 ping <ENR>` to ping a node.
    74  
    75  Run `devp2p discv5 resolve <ENR>` to find the most recent node record of a node in
    76  the discv5 DHT.
    77  
    78  Run `devp2p discv5 listen` to run a Discovery v5 node.
    79  
    80  Run `devp2p discv5 crawl <nodes.json path>` to create or update a JSON node set containing
    81  discv5 nodes.
    82  
    83  ### Discovery Test Suites
    84  
    85  The devp2p command also contains interactive test suites for Discovery v4 and Discovery
    86  v5.
    87  
    88  To run these tests against your implementation, you need to set up a networking
    89  environment where two separate UDP listening addresses are available on the same machine.
    90  The two listening addresses must also be routed such that they are able to reach the node
    91  you want to test.
    92  
    93  For example, if you want to run the test on your local host, and the node under test is
    94  also on the local host, you need to assign two IP addresses (or a larger range) to your
    95  loopback interface. On macOS, this can be done by executing the following command:
    96  
    97      sudo ifconfig lo0 add 127.0.0.2
    98  
    99  You can now run either test suite as follows: Start the node under test first, ensuring
   100  that it won't talk to the Internet (i.e. disable bootstrapping). An easy way to prevent
   101  unintended connections to the global DHT is listening on `127.0.0.1`.
   102  
   103  Now get the ENR of your node and store it in the `NODE` environment variable.
   104  
   105  Start the test by running `devp2p discv5 test -listen1 127.0.0.1 -listen2 127.0.0.2 $NODE`.
   106  
   107  ### Eth Protocol Test Suite
   108  
   109  The Eth Protocol test suite is a conformance test suite for the [eth protocol][eth].
   110  
   111  To run the eth protocol test suite against your implementation, the node needs to be initialized as such:
   112  
   113  1. initialize the geth node with the `genesis.json` file contained in the `testdata` directory
   114  2. import the `halfchain.rlp` file in the `testdata` directory
   115  3. run geth with the following flags:
   116  ```
   117  geth --datadir <datadir> --nodiscover --nat=none --networkid 19763 --verbosity 5
   118  ```
   119  
   120  Then, run the following command, replacing `<enode>` with the enode of the geth node:
   121   ```
   122   devp2p rlpx eth-test <enode> cmd/devp2p/internal/ethtest/testdata/chain.rlp cmd/devp2p/internal/ethtest/testdata/genesis.json
   123  ```
   124  
   125  Repeat the above process (re-initialising the node) in order to run the Eth Protocol test suite again.
   126  
   127  #### Eth66 Test Suite
   128  
   129  The Eth66 test suite is also a conformance test suite for the eth 66 protocol version specifically.
   130  To run the eth66 protocol test suite, initialize a geth node as described above and run the following command,
   131  replacing `<enode>` with the enode of the geth node:
   132  
   133   ```
   134   devp2p rlpx eth66-test <enode> cmd/devp2p/internal/ethtest/testdata/chain.rlp cmd/devp2p/internal/ethtest/testdata/genesis.json
   135  ```
   136  
   137  [eth]: https://github.com/ethereum/devp2p/blob/master/caps/eth.md
   138  [dns-tutorial]: https://geth.ethereum.org/docs/developers/dns-discovery-setup
   139  [discv4]: https://github.com/ethereum/devp2p/tree/master/discv4.md
   140  [discv5]: https://github.com/ethereum/devp2p/tree/master/discv5/discv5.md