Testbed, measurement tooling, and analysis for libp2p's DCUtR (Direct Connection Upgrade through Relay) hole-punching protocol across implementations and NAT environments.
Continuation of the AutoNAT measurement work in probe-lab/autonat-project
- DCUtR-enabled testbed — Docker-based testbed to exercise DCUtR hole-punching (single-NAT → dual-NAT → internet-facing → paper replication).
- NAT active monitoring tool — extends Punchr and AutoNAT with honeypot/ants infrastructure to classify NAT types and track DCUtR success in the wild.
- NAT classification and DCUtR analysis — run the tools, analyse results, publish findings.
Docker-based testbed that runs real libp2p stacks (go / rust / js) behind
emulated NATs (nftables) and exercises an actual DCUtR hole-punch over a
circuit-v2 relay, emitting OpenTelemetry traces. Scenarios are declaratively
defined in YAML and run with testbed/run.py.
# Preview the cross-impl × NAT matrix without running
python3 testbed/run.py testbed/scenarios/dcutr-cross-nat-matrix.yaml --dry-run
# Run a single cell
python3 testbed/run.py testbed/scenarios/dcutr-cross-nat-matrix.yaml \
--filter=listener_impl=go,dialer_impl=rust,nat_type=port-restricted,nat_type_b=port-restricted,transport=tcp --runs=1Requires Docker + Docker Compose on a native Linux host (Docker Desktop on macOS has bridge networking issues). See docs/dcutr-testbed.md for topology, NAT emulation, and how to run the matrix.
| Document | Description |
|---|---|
| Final report | Executive synthesis of all findings (testbed + live network) |
| DCUtR spec & flaws | Protocol walk-through + spec gaps, split by impact |
| DCUtR testbed | Topology, NAT emulation, running the matrix |
| Scenario Schema | Scenario YAML format (run.py) |
| Running Experiments | Commands, filtering, options |
| Deployment runbook | Cloud-agnostic deploy (binaries → cloud-init → systemd → Terraform); one-command AWS quick start |
| AWS deployment | Ready-to-run 3-region AWS fleet: ./scripts/deploy.sh, lifecycle, cost, security |
| Honeypot architecture & deployment | System mechanics — components, control flow, Postgres schema, data flow — plus the cloud-agnostic deployment runbook |
| NAT classification | NAT classification methodology — RFC 4787 taxonomy, observations used, classification rules, information-theoretic limits, per-transport caveat |
- DCUtR spec: https://github.com/libp2p/specs/blob/master/relay/DCUtR.md
- RFC 4787 — NAT Behavioral Requirements for Unicast UDP: https://www.rfc-editor.org/rfc/rfc4787
- Trautwein et al., Large-Scale Measurement of NAT Traversal for the Decentralized Web: A Case Study of DCUtR in IPFS (IMC '26): arXiv:2604.12484.
- Prior AutoNAT work: https://github.com/probe-lab/autonat-project