multiformats / multiformats/py-multiaddr
Track upstream registration of `wg` multiaddr protocol (0x01C7)
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
uprefix 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 testper 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
-
Add one row to
protocols.csv(sorted by code, afternoise/ 454):455, 256, wg, WireGuard tunnel endpoint (Curve25519 public key) -
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 matchescerthashprecedent - 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.pydocstring 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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