libp2p Peer Connection Tester

A CLI tool for testing libp2p connections and discovering what protocols a peer supports. Useful for debugging P2P networks, checking configs, and making sure nodes are reachable.

Install

Run with npx (no install)

npx @projectlibertylabs/p2p-peer-test <multiaddr>

Install globally

npm install -g @projectlibertylabs/p2p-peer-test
p2p-peer-test <multiaddr>

What it does

• Connect to a peer using a multiaddr
• Test multiple peers at once (CLI args or paste a list)
• Show supported protocols
• Report connection times and errors
• Retry with configurable attempts and timeouts
• Output results in JSON (for scripts/CI) or as human-readable text

Usage

# Test a specific peer
npx @projectlibertylabs/p2p-peer-test /ip4/127.0.0.1/tcp/4001

# Test multiple peers
npx @projectlibertylabs/p2p-peer-test /ip4/127.0.0.1/tcp/4001 /ip4/127.0.0.1/tcp/4002

# Interactive mode (prompts for multiaddr - supports pasting multiple!)
npx @projectlibertylabs/p2p-peer-test

# Custom timeout (ms)
npx @projectlibertylabs/p2p-peer-test /ip4/127.0.0.1/tcp/4001 --timeout 5000

# Retry a few times
npx @projectlibertylabs/p2p-peer-test /ip4/127.0.0.1/tcp/4001 --retries 3

# JSON output (great for multiple addresses)
npx @projectlibertylabs/p2p-peer-test /ip4/127.0.0.1/tcp/4001 /ip4/127.0.0.1/tcp/4002 --json

# Verbose errors
npx @projectlibertylabs/p2p-peer-test /ip4/127.0.0.1/tcp/4001 --verbose

# Show example multiaddrs
npx @projectlibertylabs/p2p-peer-test examples

# Show help
npx @projectlibertylabs/p2p-peer-test --help

Multiple Address Testing

You can test multiple multiaddrs in two ways:

1. CLI Arguments

Pass multiple multiaddrs as arguments:

npx @projectlibertylabs/p2p-peer-test \
  /dns4/3.collator.frequency.xyz/tcp/30333/p2p/12D3KooW... \
  /ip4/127.0.0.1/tcp/30333/p2p/12D3KooW... \
  /ip4/10.0.0.1/tcp/30334/ws/p2p/12D3KooW...

2. Interactive Mode (Paste Support)

Run without arguments and paste a list of multiaddrs:

npx @projectlibertylabs/p2p-peer-test
# Then paste:
/dns4/3.collator.frequency.xyz/tcp/30333/p2p/12D3KooWLsZTXsv1eY6U9YhowipQ73R5D1zQTaWECUCkxLawWpoB
/ip4/10.40.10.23/tcp/30333/p2p/12D3KooWLsZTXsv1eY6U9YhowipQ73R5D1zQTaWECUCkxLawWpoB
/ip4/3.129.100.199/tcp/30333/p2p/12D3KooWLsZTXsv1eY6U9YhowipQ73R5D1zQTaWECUCkxLawWpoB

Output includes:

• Individual test results for each address
• Summary with success/failure counts
• Total testing time
• JSON format available for automation

CLI Options

• -t, --timeout <ms> – Connection timeout (default: 10000)
• -r, --retries <n> – Retry attempts (default: 0)
• -j, --json – Output as JSON
• -v, --verbose – More error info
• -h, --help – Show help

Troubleshooting

ECONNREFUSED

• Node not running, wrong port, or firewall issue

Timeout

• Node unreachable/overloaded
• Increase --timeout

Protocol mismatch

• Peer doesn’t support libp2p on that transport
• Try TCP vs WebSocket

Invalid multiaddr

• Check syntax
• Use examples for reference

Common ports:

• 30333 / 30334 – Substrate/libp2p
• 4001 – Standard libp2p
• 443 – WSS
• 8080 – WS

Development

Scripts:

• npm run format – Prettier
• npm run lint – ESLint
• npm run test – Run tests (Vitest)

Contributing

1. Fork
2. Add code + tests
3. npm run lint && npm test
4. PR

Acknowledgments

• Thanks to the libp2p community for the networking stack this builds on.
• This code was partially written with AI.