Transit Fabric releases

Taken from the Transit Fabric source repository at commit 91be12e (91be12ef98b775c7f045124e6b8c686c15439650, main), file docs/specs/identity.md. Links into the private source tree are shown as plain text. Raw Markdown · Red-team pack

Spec: identity

Status: draft · Implemented in crates/bwos-core/src/identity.rs and inline_binding.rs · Vectors: testdata/vectors/address.json, inline_binding.json

Keys

Key Algorithm Where Purpose
Node key ed25519 Generated on node, ~/.bwos/node.key (0600) Network identity; signs receipts and WG bindings
WireGuard key X25519 Node Tunnel transport; rotatable
Hotkey sr25519 (Bittensor) Operator's wallet Economic identity (UID)
Client key ed25519 Client device Signs client receipts

Key files are created with O_CREAT|O_EXCL and mode 0600 (NodeKey::save, WgKey::save), so an existing key file or symlink is never replaced. Replacing a key requires the explicit opt-in save_overwrite. It writes a fresh 0600 temp file and atomically renames it into place, and it refuses a symlink at the target path.

Node address

digest  = SHA-512(SHA-512(node_pubkey_32_bytes))
address = 0xfc || digest[0:15]          # 16 bytes, inside fc00::/8

Text form is RFC 5952 (lowercase, zero compression). The address never changes for a given node key. Unlike CJDNS, no key grinding is needed: the 0xfc prefix is prepended, not required of the hash.

Two more values derive from the node key (ADR-0033 items 2 and 4; labels in encoding.md §Reserved derivation labels):

link_address = 0xfc || SHA-256("BWOS-v0/node-link" || 0x00 || node_pubkey_32_bytes)[0:15]
node_asn     = 4_200_000_000 + u32be(SHA-256("BWOS-v0/node-asn" || 0x00 || node_pubkey_32_bytes)[0:4]) % 94_967_295

WireGuard binding (node-signed)

{"v":0,"node":"<node pubkey hex>","wg":"<wg pubkey hex>","not_before":<block>,"not_after":<block>,"sig":"<ed25519 hex>"}

Domain wg-binding. A node publishes a new binding to rotate its WireGuard key (node MUST be a valid non-weak Ed25519 pubkey, wg MUST be distinct from node, and not_before <= not_after). Peers accept tunnels only from WG keys with a live binding. When several verified bindings for the same node are live, the one with the greatest not_before supersedes the others, so a rotation retires the old key as soon as the new binding is live. Two live bindings with that same greatest not_before but different wg keys are an equivocation: peers accept neither (identity::select_live_wg_binding).

Both node kinds enforce this before a session (PB-05): a peer MUST present a binding that verifies, names the WireGuard key it shook hands with and the node key its link address comes from, and is live at the binding block, or it gets no BGP session and is logged as PeerRefused with reason no-binding, binding-mismatch or binding-expired (datapath.md, "Peer admission"). Each node is handed one binding per peer by its operator. With --validators the block is the applied peer directory's (Phase B Task 11c, datapath.md "Signed inputs"), and without it the operator's; choosing among several published bindings with select_live_wg_binding is still to come. The WireGuard-key-only identity remains only as --test-identity, for tests at private or documentation addresses.

Node binding (hotkey-signed)

{"v":0,"hotkey":"<ss58>","netuid":<int>,"nodes":["<node pubkey hex>", ...],"not_before":<block>,"not_after":<block>,"hotkey_sig":"<sr25519 hex>"}

Domain node-binding. netuid MUST be > 0 (enforced by NodeBinding::validate), and nodes MUST be non-empty (1..=1024), strictly sorted, and unique non-weak Ed25519 pubkeys.

A fleet of at most 7 nodes MAY instead carry its binding in the hotkey's commitment itself, with no object to serve (§Inline node binding, ADR-0058).

{"v":0,"node":"<node pubkey hex>","hotkey":"<ss58 or hex>","netuid":<int>,"not_before":<block>,"not_after":<block>,"seq":<u64, omitted when 0>,"revoked":<true, omitted when false>,"sig":"<ed25519 hex>"}

Domain node-consent, signed by the node key (identity::NodeConsent). netuid > 0, not_before <= not_after, hotkey is 1..=64 printable ASCII distinct from node, node a valid non-weak Ed25519 key. A node key consents to the (hotkey, netuid) it serves; the hotkey-signed binding alone never proves control of a node key (T14). Consents are served like bindings at /v0/objects/node-consent/<sha256>.

Sequence, revocation and moves (T29)

Binding resolution

Validators MUST resolve bindings with resolve_live_bindings_with_consent, given the subnet netuid, the metagraph uid -> hotkey map, each UID's on-chain node-binding commitment hashes, and the window's node consents:

  1. A (uid, binding) is considered only if binding.netuid is the subnet's netuid, binding.hotkey is uid's metagraph hotkey, and the binding is live and valid. An Ed25519-hex hotkey is authenticated by a strictly verified hotkey_sig. An SS58 hotkey's sr25519 hotkey_sig is not checked in bwos-core; it is authenticated by hash("node-binding", binding) being among the commitments that hotkey published on chain. An uncommitted SS58 binding is ignored.
  2. Within a considered binding, a node counts only if it has an effective (### Sequence, revocation and moves), live, valid node-consent for the same (hotkey, netuid). Unconsented, superseded or revoked entries are ignored: they neither own nor quarantine the node, so listing someone else's node key achieves nothing.
  3. Supersession (RT2-1): per UID, and then per (netuid, hotkey), only the considered live binding with the greatest not_before counts; older live bindings are ignored (they neither own nor quarantine). This is the same rule as select_live_wg_binding. Replaying a superseded but unexpired binding therefore cannot quarantine the fleet. Bindings that differ only in not_after (same UID, hotkey, netuid, nodes and not_before, e.g. an expiry renewal) are one binding: the shorter not_after is kept, as for wg-binding. If two bindings with different node sets tie on that greatest not_before, the operator has equivocated and neither is accepted: their nodes are quarantined. An operator that re-signs its binding (for example to add a node) MUST give the new binding a strictly greater not_before than the one it replaces.
  4. A consented node in two surviving bindings (it consented to both hotkeys) counts for neither (quarantined conflict).

Before these rules, inline bindings take precedence (ADR-0058 §3, inline_binding::resolve_live_bindings_with_inline, which run_tempo uses with TempoInput::inline_bindings). A UID whose commitment in force at the read block carries an inline binding has exactly the equivalent unsigned binding (§Inline node binding), authenticated by that commitment. Every other binding attributed to the UID, its manifest's included, is ignored: it neither owns nor quarantines. Rules 1 to 4 then apply unchanged.

resolve_live_bindings (no consent, trusts the caller's UID pairing) is kept only for API compatibility. Any UID can grief another operator's fleet through it, so it MUST NOT be used for scoring.

Publication: the binding hash is committed on chain (Bittensor commitments) and the full canonical JSON object is served over HTTP by the operator at /v0/objects/node-binding/<sha256> (ADR-0015). A fleet of at most 7 nodes needs no server: its binding goes in the commitment (§Inline node binding). For a larger fleet with no HTTP endpoint, OQ-130 stays open.

The ADR-0054 wallet rule covers the manifest only. An SS58 binding's hotkey_sig is checked nowhere until OQ-131 decides; a check added then, and the link page's own check before it shows a binding, MUST use identity::verify_sr25519_hotkey_sig.

Commitment manifest (hotkey-signed, ADR-0036)

Bittensor keeps one commitment per hotkey per subnet, so that commitment holds the hash of a manifest, and the manifest names everything the hotkey publishes:

{"v":0,"netuid":<int>,"hotkey":"<ss58>","window":<u64>,"binding":"<node-binding hash, omitted when none>","objects":{"<domain>":"<hash>", ...},"hotkey_sig":"<sr25519 hex>"}

Domain commitment-manifest (manifest::CommitmentManifest).

Pulling a hotkey's objects (Task 20, OQ-220, OQ-223)

Nothing is uploaded to a validator. A hotkey serves its committed objects itself (ADR-0015), at its Bittensor axon (serve_axon: an IP and port in SubtensorModule::Axons; bwos_chain::ChainClient::serve_axon sets it, axons_at_block reads every hotkey's), and validators pull each one by its committed hash (bwos-validator live, measurement.md §Live loop).

Inline node binding (ADR-0058)

A hotkey's commitment has 3 fields (Commitments::MaxFields), and each field holds at most 128 raw bytes (Data::Raw0..Raw128; testnet runtime spec 488, read 2026-11-09). Field 0 keeps the manifest hash. Fields 1 and 2 MAY carry the binding of a fleet of 1 to 7 nodes (bwos_core::inline_binding; vectors testdata/vectors/inline_binding.json).

Delivery over the probe session (PB-45b)

An inline binding removes the binding object, but validators still need each node's node-consent, and a hotkey's first manifest and the objects it names have no path to validators when the operator runs no server (OQ-215). Every no-root node already dials every eligible validator's probe agent and keeps the WireGuard session up, behind NAT too (measurement.md §STAMP probes and probe sessions). Over that session the node forwards two kinds of signed object (bwos_core::probe_forward):

The message. One inner UDP datagram per object, from the node's /128 to the agent's probe address (measurement.md, "The probe address"), source and destination port PROBE_FORWARD_PORT (8_622). The payload is

domain || 0x00 || canonical JSON of the object

at most MAX_FORWARD_PAYLOAD (1_150) bytes, so the outer packet (inner IPv6 and UDP, WireGuard's framing, outer UDP and IPv6) stays within the IPv6 minimum MTU of 1,280 (fix round 1, M3). domain is one of FORWARDED_DOMAINS, and the object is the store's bytes for it (wire::canonical), signed under that same domain with signing_bytes (Invariant 7). The message has no envelope signature: WireGuard authenticates the session, and each object authenticates itself. Vectors: testdata/vectors/probe_forward.json.

Linking with a browser wallet (ADR-0054)

The wallet flow does what bwos bind does, with the hotkey in a browser wallet (Talisman, SubWallet, the Polkadot.js extension) and no hotkey file. Reference: bwos_core::wallet_link; the page's port, site/link/bwos-link.js, is tested against the same vectors (testdata/vectors/wallet_link.json).

Dedupe

For scoring, nodes are grouped by the network prefix of their public endpoint. The normative grouping (which prefixes, how capacity and the usage cap are pooled, and that ASN does not group in v0) is scoring.md §Endpoint dedupe ([T24]). Validators MUST derive endpoint prefixes themselves from the addresses they probe; they are never self-reported. Under ADR-0039, each validator commits the endpoints it saw, and the grouping uses the stake-aggregated endpoint (measurement.md §Probed endpoints), so every validator builds the same groups. The coverage multiplier C_n (the ADR-0039 diversity term) multiplies a node's own credited bytes, so splitting into many keys can't multiply it (scoring.md §Coverage).

Fleet enrollment (ADR-0019)

Prosumer and power-user edge nodes join a Fleet Aggregator UID without holding a Bittensor hotkey by signing a FleetEnrollment (domain fleet-enrollment) with their ed25519 node key:

{"v":0,"node":"<node pubkey hex>","aggregator_uid":14,"aggregator_node":"<aggregator node pubkey hex>","declared_mbps":0,"cost_ppm":800000,"commission_ppm":100000,"window_from":1,"sig":"<ed25519 hex>"}