npm package: @projectlibertylabs/p2p-peer-test
Description: CLI tool to test libp2p connections and discover peer protocols
Latest version: 1.0.0

# 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)

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

### Install globally

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

## What it does

- Connect to a peer using a [multiaddr](https://multiformats.io/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

```bash
# 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:

```bash
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:

```bash
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](https://libp2p.io) community for the networking stack this builds on.
- This code was partially written with AI.