Add the interim `/tipc/` maddr grammar

`mk_maddr()`/`parse_maddr()` learn,

    /tipc/<stype>/<instance>/<scope>

mirroring how `uds` maps onto the spec-legal `/unix`.

XXX `str`-ONLY for now: there is no registered `/tipc` proto
in the multiaddr table (upstream track gh #483 +
multiformats/py-multiaddr#107) and `Multiaddr()` rejects an
unregistered name outright. `MsgTransport.maddr`s return type
is already `Multiaddr|str` (and `MsgpackUDSStream` already
exercises the `str` branch), so this fits — but it IS why gh

`parse_maddr()` therefore special-cases the `/tipc/` prefix
BEFORE handing anything to `Multiaddr()`.

Also drive the maddr mapping-table tests off `_address_types`
instead of a hardcoded len/dict so the next backend can't
fail them for the wrong reason.

(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))

ai/tpt-backends/03_wg_tunnel_bindspace.md

@@ -26,11 +26,10 @@ onto `trio` as the library's sans-io layer allows.
   `/ip4|ip6/<h>/tcp/<p>` and `/unix/<p>`; a `.../wg/u<key>`
   maddr raises `ValueError('Unsupported multiaddr protocol
   combo')`.
-- there is no `wg` proto in the multiaddr *spec* yet, but
+- there is no `wg` proto in the multiaddr spec; the first-draft
-  multiformats/py-multiaddr#108 (key form `u<base64url>`) is
+  upstream PR is multiformats/py-multiaddr#108 with key form
-  **merged** as of 2026-07-28 (`f86519da`) — and unreleased, the
+  `u<base64url>` (commit `8be3a8b`), tracked by
-  latest `0.2.0` predating it. Spec registration is still tracked
+  multiformats/py-multiaddr#107 and gh #483.
-  by multiformats/py-multiaddr#107 and gh #483.
 - so **today's deployable story is declarative**: run `wg-quick`
   out-of-band, parse the maddr, strip to the inner
   `(host, port)`, verify the pubkey against the live tunnel,
@@ -113,12 +112,9 @@ class WGTunnelSpec(
 
 ### 3.2 `parse_maddr()`/`mk_maddr()`
 
-Grammar — **verified** against py-multiaddr#108, first on the
+Grammar — **verified** against py-multiaddr#108
-`baudco/py-multiaddr@wg_support` branch and re-verified after it
+(`baudco/py-multiaddr@wg_support`, installed in a throwaway venv;
-merged upstream (`multiformats/py-multiaddr@f86519da`); all three
+all three forms below parse *and* round-trip):
-forms below parse *and* round-trip. Note the codec also validates
-that the key decodes to exactly 32 bytes, so a truncated key is a
-`StringParseError`, not a silently-mangled parse:
 
 ```
 /ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616
@@ -173,16 +169,13 @@ Observed protocol-name lists, for writing the `match`:
   (bearer_names, tunnel_specs, inner_names)`. This is also what
   makes a wg-inside-wg stack fall out for free.
 - `mk_maddr()` inverse for `TunnelledAddress`.
-- **pending an upstream release**: py-multiaddr#108 is merged, so
+- **blocked on upstream**: `Multiaddr('/…/wg/u…')` only parses
-  `Multiaddr('/…/wg/u…')` parses — but off a `[tool.uv.sources]`
+  once py-multiaddr#108 lands. Until then: pin the branch in the
-  `rev` pin, since no release carries the codec. Gate the tests
+  `wg` extra / dev-group and gate the tests on
-  on `_have_wg_maddr_proto()`, implemented as
+  `_have_wg_maddr_proto()` (a cheap try/except around
-  `protocols.protocol_with_name('wg')` under
+  `Multiaddr('/wg/uAAAA')`). Do **not** hand-roll a `wg` parser
-  `except ProtocolNotFoundError`. Do **not** probe by parsing a
+  in `tractor` — the whole point of #429 was dropping the NIH
-  dummy like `Multiaddr('/wg/uAAAA')` — the codec enforces a
+  parser.
-  32-byte key, so that raises even when the proto *is* known. Do
-  **not** hand-roll a `wg` parser in `tractor` — the whole point
-  of #429 was dropping the NIH parser.
 
 ### 3.3 verification helper (pure, composable)
 
@@ -444,7 +437,7 @@ consider doing it *first* for exactly that reason.
 | risk | mitigation |
 | --- | --- |
 | `to_thread` worker runs in the wrong netns | §5.3; pass `netns=` to pyroute2 or pin a worker; test-first |
-| py-multiaddr#108 merged but unreleased | `[tool.uv.sources]` `rev` pin + `_have_wg_maddr_proto()` gate; layer A's inner-addr path works regardless |
+| py-multiaddr#108 not merged | branch pin + `_have_wg_maddr_proto()` gate; layer A's inner-addr path works regardless |
 | `TunnelledAddress` leaks into `Endpoint` and breaks `inspect.getmodule()` | unwrap at parse/bindspace boundary; assert `not isinstance(ep.addr, TunnelledAddress)` in `Endpoint.__post_init__` |
 | privileged ops in a library | never `sudo`; explicit cap probe + actionable error; pre-provisioned is the default |
 | pyroute2 0.9 asyncio core drags a loop into the actor | option (1) is a *thread*, not a loop; forbid `trio-asyncio` here (§4.1) |

examples/multihost/wg_lan/README.md

@@ -39,27 +39,16 @@ this composed form parses and round-trips
 
 ## requirements
 
-py-multiaddr #108 is **merged** (2026-07-28) but ships in no
+The `wg` proto isn't in released `py-multiaddr` yet (`0.2.0` has
-release yet — the latest `0.2.0` (2026-03-17) predates it and has
+no `wg` codec), so until #108 lands:
-no `wg` codec. So `pyproject.toml` carries a temporary
-`[tool.uv.sources]` `rev` pin at the merge commit, and a plain
 
 ```bash
-uv sync
+uv pip install 'git+https://github.com/baudco/py-multiaddr.git@wg_support' multibase
 ```
 
-gets you a `wg`-aware `multiaddr`. That pin goes away once a
+`wg_maddr.py` degrades to a plain segment split when the codec is
-release carries the codec. You also need `multibase`:
+absent, so the examples still run — but you lose per-segment
-
+validation. It deliberately does **not** hand-roll a `wg` codec
-```bash
-uv pip install multibase
-```
-
-Without the codec `wg_maddr.py` degrades to a plain segment split
-— the examples still run, but you lose per-segment validation
-(incl. the 32-byte key-length check), so a malformed key reaches
-the returned struct instead of raising. `_have_wg_maddr_proto()`
-is the gate. It deliberately does **not** hand-roll a `wg` codec
 (gh #429 was about *dropping* our NIH parser).
 
 ## 0. tunnel setup (out-of-band, both hosts)

examples/multihost/wg_lan/wg_maddr.py

@@ -2,9 +2,9 @@
 r'''
 Parse `wg`-tunnelled multiaddrs into `tractor`-ready addrs.
 
-The canonical form (per py-multiaddr #108, verified to parse +
+The canonical form (per py-multiaddr PR #108, verified to parse +
-round-trip against its upstream merge) nests the *overlay*
+round-trip on that branch) nests the *overlay* endpoint **after**
-endpoint **after** the `/wg/` segment:
+the `/wg/` segment:
 
     /ip4/10.0.0.1/udp/51820/wg/u<key>/ip4/10.0.11.1/tcp/1616
     \_______ wg bearer ______/\_ key _/\____ tractor ep _____/
@@ -111,10 +111,8 @@ def parse_wg_maddr(
     Split a `wg`-tunnelled maddr into its bearer/key/overlay
     parts. Pure — no I/O.
 
-    Total-or-raises: with a `wg`-aware `py-multiaddr` (#108) an
+    Uses `py-multiaddr` when it knows the `wg` proto (PR #108),
-    unparseable maddr raises instead of yielding a struct built
+    else falls back to a minimal segment split.
-    from garbage segments. See `_segments()` for the degraded
-    pre-#108 path.
 
     '''
     segs: list[str] = _segments(maddr)
@@ -166,53 +164,22 @@ def parse_wg_maddr(
     )
 
 
-_wg_proto_known: bool|None = None
-
-
-def _have_wg_maddr_proto() -> bool:
-    '''
-    True iff the installed `py-multiaddr` knows the `/wg/` proto,
-    i.e. carries py-multiaddr#108.
-
-    Merged upstream 2026-07-28 but in no release as of `0.2.0`,
-    hence the `[tool.uv.sources]` `rev` pin.
-
-    Pure predicate; result cached since it can't change without a
-    reinstall.
-
-    '''
-    global _wg_proto_known
-    if _wg_proto_known is None:
-        from multiaddr.protocols import protocol_with_name
-        from multiaddr.exceptions import ProtocolNotFoundError
-        try:
-            protocol_with_name('wg')
-            _wg_proto_known = True
-        except ProtocolNotFoundError:
-            _wg_proto_known = False
-
-    return _wg_proto_known
-
-
 def _segments(maddr: str) -> list[str]:
     '''
-    Deliver a maddr's `/`-split segments, validating via the real
+    Deliver a maddr's `/`-split segments, preferring the real
-    parser whenever it knows `wg`.
+    parser when it supports `wg`.
 
     '''
-    if _have_wg_maddr_proto():
+    from multiaddr import Multiaddr
-        from multiaddr import Multiaddr
+    try:
-        # the real thing: validates every proto + value, incl.
+        # the real thing: validates every proto + value
-        # that the `wg` key decodes to exactly 32 bytes. Let it
-        # raise — a maddr that doesn't parse must NOT reach
-        # `wg8_pubkey()`, which would happily emit a corrupt key.
         Multiaddr(maddr)
-
+    except Exception:
-    # XXX, degraded path for a pre-#108 `py-multiaddr` ONLY: no
+        # XXX STOPGAP, only until py-multiaddr#108 lands; then
-    # per-segment validation, so a malformed key survives to the
+        # this branch is dead and `Multiaddr` is authoritative.
-    # returned struct. We deliberately DON'T hand-roll a `wg`
+        # We deliberately DON'T hand-roll a `wg` codec (the whole
-    # codec (the whole point of gh #429 was dropping the NIH
+        # point of gh #429 was dropping the NIH parser).
-    # parser) — install the pinned rev to get validation back.
+        pass
     return [s for s in maddr.split('/') if s]
 
 

pyproject.toml

@@ -166,17 +166,6 @@ sync_pause = {requires-python = ">=3.13, <3.14"}
 # linux kernel networking
 # 'pyroute2
 
-# XXX TEMP, the `/wg/u<key>` maddr proto is MERGED upstream (in
-# py-multiaddr#108, 2026-07-28) but is in NO release yet; the
-# latest `0.2.0` (2026-03-17) predates the merge by ~4 months.
-# Pinned by `rev` (not `branch`) so CI stays reproducible.
-#
-# Drop this pin (and bump the `multiaddr` dep floor above) the
-# moment a release carries the `wg` codec; the only consumer is
-# `examples/multihost/wg_lan/`.
-# |_https://github.com/multiformats/py-multiaddr/pull/108
-multiaddr = { git = 'https://github.com/multiformats/py-multiaddr.git', rev = 'f86519daaa21699023d0037c58cdff600313dd09' }
-
 # ------ tool.uv.sources ------
 
 [tool.uv]

uv.lock

@@ -518,7 +518,7 @@ wheels = [
 [[package]]
 name = "multiaddr"
 version = "0.2.0"
-source = { git = "https://github.com/multiformats/py-multiaddr.git?rev=f86519daaa21699023d0037c58cdff600313dd09#f86519daaa21699023d0037c58cdff600313dd09" }
+source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "base58" },
     { name = "dnspython" },
@@ -533,6 +533,10 @@ dependencies = [
     { name = "trio-typing" },
     { name = "varint" },
 ]
+sdist = { url = "https://files.pythonhosted.org/packages/c7/10/4e26a8577cfce1c0febc8d83087e1373e93c695c6e73ad010546fb67e229/multiaddr-0.2.0.tar.gz", hash = "sha256:acb6b25c332ec1b2f1f8fef8d03a8c63385d34a87d690df0f4bba43cdf6efe8d", size = 58356, upload-time = "2026-03-17T21:51:00.274Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b5/13/56e503d01218d1ca27ea9fda862045a4b400cae5e756f47315f5aaba0eee/multiaddr-0.2.0-py3-none-any.whl", hash = "sha256:bcff7bf3d7de3d6da0b865b25423bcb411de1d20d70cc6abfacf75170d17866c", size = 40424, upload-time = "2026-03-17T21:50:58.833Z" },
+]
 
 [[package]]
 name = "mypy-extensions"
@@ -1174,7 +1178,7 @@ requires-dist = [
     { name = "bidict", specifier = ">=0.23.1" },
     { name = "colorlog", specifier = ">=6.8.2,<7" },
     { name = "msgspec", specifier = ">=0.20.0" },
-    { name = "multiaddr", git = "https://github.com/multiformats/py-multiaddr.git?rev=f86519daaa21699023d0037c58cdff600313dd09" },
+    { name = "multiaddr", specifier = ">=0.2.0" },
     { name = "pdbp", specifier = ">=1.8.2,<2" },
     { name = "platformdirs", specifier = ">=4.4.0" },
     { name = "setproctitle", specifier = ">=1.3,<2" },