multiformats / multiformats/py-multiaddr

Track upstream registration of `wg` multiaddr protocol (0x01C7)

Open
#123 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
36
Forks
33
Avg merge
12m
Merged PRs (30d)
11

Description

Context

This issue tracks upstream registration of the draft WireGuard (wg) multiaddr protocol introduced in PR #108.

  • Closes the coordination gap left after removing author planning docs from the PR.
  • Related: #107, PR #108, goodboy/tractor#483 (author's expanded plan).

Settled implementation semantics (py-multiaddr #108)

Property Value
Protocol name wg
Code 0x01C7 (decimal 455) — slot between noise (0x01C6) and shs (0x01C8)
Binary form Exactly 32 bytes — raw Curve25519 public key; fixed size 256 bits; no length prefix
String form Multibase base64url — u prefix (matches /certhash in go-/py-multiaddr)
Conversion from wg(8) multibase.encode('base64url', base64.b64decode(key))
Example /ip4/1.2.3.4/udp/51820/wg/urCzgw_sszhsg-SpR8V5IPmVnYPg2PliWW739_SWemwY

Open questions for upstream spec review:

  • Canonical-only u prefix vs accept-any-multibase-and-normalize on decode
  • Whether degenerate keys (e.g. all-zero) are a codec concern (suggest: no — length check only)

Upstream registration plan

Step 1: multicodec PR (do first)

Repo: https://github.com/multiformats/multicodec

Add one row to table.csv (sorted by code, between noise and shs):

wg,                             multiaddr,      0x01c7,         draft,      WireGuard tunnel endpoint - 32-byte Curve25519 public key
  • Run table validation locally before pushing (make / npm test per CONTRIBUTING).
  • PR body: link WireGuard cryptokey-routing docs, py-multiaddr PR #108 as first implementation, overlay use case from #107.
Step 2: multiaddr spec PR (link multicodec PR)

Repo: https://github.com/multiformats/multiaddr

  1. Add one row to protocols.csv (sorted by code, after noise / 454):

    455,	256,	wg,	WireGuard tunnel endpoint (Curve25519 public key)
    
  2. If requested by maintainers, add a short protocol description covering:

    • Binary: 32-byte fixed-size Curve25519 public key (no length prefix)
    • String: multibase base64url u<43> (44 chars total)
    • Rationale: / in standard base64 collides with multiaddr delimiter; multibase matches certhash precedent
    • Canonical composition: /ip{4,6}/<host>/udp/<port>/wg/<key>

Open this PR referencing the multicodec PR from step 1.

Step 3: Circle back to py-multiaddr

After upstream PRs land (or in parallel once numbers are reserved):

  • Update multiaddr/codecs/wg.py docstring to point at upstream PRs instead of "speculative draft"
  • Update PR #108 description / tick multicodec TODO
  • Close this issue when both upstream rows are merged
Step 4: libp2p/specs (optional, later)

Only after multiformats registration: document how libp2p stacks use /…/wg/… for overlay/tunnel addressing (e.g. extend addressing/README.md). Not required for py-multiaddr merge.

Step 5: Cross-implementation follow-up (optional)

Propose the same protocol to go-multiaddr / js-multiaddr once spec rows land.

Checklist

  • Merge py-multiaddr PR #108 (pending removal of gh/wg_spec_submission_plan.md)
  • Open multicodec PR for 0x01C7
  • Open multiaddr PR for protocol 455 / wg
  • Update py-multiaddr docs after upstream lands

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the upstream multicodec table.csv entry and its local validation instructions, then inspect multiaddr's protocols.csv for the corresponding row. Review multiaddr/codecs/wg.py and the referenced PRs before opening either upstream PR. Done means both upstream registrations are merged and the py-multiaddr documentation and docstring are updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.