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
- The link address is the address a node holds its BGP sessions on, and the next hop it gives for its node address. It is never used as a traffic source (
datapath.md, "Link address and next hop").identity::link_address_from_public. - The node ASN is in the RFC 6996 private 4-octet range,
4_200_000_000..=4_294_967_294.identity::node_asn_from_public. Every node peers with it and origin validation checks it (PB-04,datapath.md); the snapshot holds at most one node per ASN (scoring.md§Snapshot inputs). testdata/vectors/address.jsoncarriesaddress,link_addressandnode_asnfor every test key (Invariant 8).
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).
Node consent (node-signed, proof of possession)
{"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)
seq(default0) is a per-(node, netuid)sequence number chosen by the node.revoked(defaultfalse) marks a revocation: the node withdraws from(hotkey, netuid). Both are covered by the node-key signature, and a revocation, like any consent, needs only the node key (never a hotkey).- Encoding: a field holding its default MUST be omitted (
seqwhen0,revokedwhenfalse). A consent signed before these fields existed therefore parses with the defaults, re-encodes byte-identically and still verifies; an explicit"seq":0or"revoked":falseis non-canonical and rejected by the strict decoder. - Effective consents (
identity::effective_consents), per node and for the scorednetuid:- Consider every consent with a valid signature that has started (
not_before <= now_block), expired or not. - Keep only the consents whose
seqequals the greatest consideredseqfor that node. Lower-seqconsents are superseded: replaying one never resurrects the node. - A kept revocation withdraws the node from its hotkey at once, before any earlier consent's
not_after, and stays in force after its ownnot_after. A revocation beats a non-revoked consent with the sameseqand hotkey. - A kept non-revoked consent counts only while live (
now_block <= not_after). An expired highest-seqconsent does not fall back to a live lower-seqone.
- Consider every consent with a valid signature that has started (
- Move. A higher-
seqconsent to a different hotkey supersedes the old one immediately, without waiting for itsnot_after, so a node can move between operators. Two kept non-revoked consents with the sameseqfor different hotkeys are the node's own equivocation: it counts for neither (rule 4 of Binding resolution). seqSHOULD increase by one per change. A node key that signsseq = 2^64 - 1can never be superseded on that netuid; the remedy is a new node key (as for any node-key compromise).- Validators SHOULD keep, per
(node, netuid), the highest-seqstarted consent they have seen, even after it expires, and MUST include revocations in the consent set; a validator that drops them loses the no-resurrection guarantee.resolve_live_bindings_with_revocationstakes revocations as a separate list; entries there that are notrevoked: trueare ignored, so a revocation feed can never add consent. - Transit Fabric Edge appliances sign the consent on-box from the operator-signed edge config (
bwos-node sign-consent -edge-config,seq= the configserial), seeedge/provisioning/README.mdstep 3a. The consent'shotkeyis the config'shotkeyand itsnetuidis the config's signednetuid(OQ-21,datapath.md§Edge-config netuid); a conflicting-netuidis refused. Only configs signed withoutnetuidfall back to-netuidor the unsigned/var/lib/bwos/netuidfile. The operator-hotkey pin on the appliance remains trust on first use until the claim step authenticates the operator.
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:
- A
(uid, binding)is considered only ifbinding.netuidis the subnet's netuid,binding.hotkeyisuid's metagraph hotkey, and the binding is live and valid. An Ed25519-hex hotkey is authenticated by a strictly verifiedhotkey_sig. An SS58 hotkey'ssr25519hotkey_sigis not checked inbwos-core; it is authenticated byhash("node-binding", binding)being among the commitments that hotkey published on chain. An uncommitted SS58 binding is ignored. - Within a considered binding, a node counts only if it has an effective (
### Sequence, revocation and moves), live, validnode-consentfor 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. - Supersession (
RT2-1): per UID, and then per(netuid, hotkey), only the considered live binding with the greatestnot_beforecounts; older live bindings are ignored (they neither own nor quarantine). This is the same rule asselect_live_wg_binding. Replaying a superseded but unexpired binding therefore cannot quarantine the fleet. Bindings that differ only innot_after(same UID, hotkey, netuid, nodes andnot_before, e.g. an expiry renewal) are one binding: the shorternot_afteris kept, as forwg-binding. If two bindings with different node sets tie on that greatestnot_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 greaternot_beforethan the one it replaces. - 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).
- Fields.
vMUST be0.hotkeyMUST be SS58 with the Bittensor prefix 42 (identity::BITTENSOR_SS58_PREFIX), the form the chain and metagraph print, so each account has exactly one hotkey string and comparing strings with the metagraph hotkey is sound. Any other prefix is refused (ManifestError::BadHotkey), even when the same account signed it.binding, when present, is thenode-bindingobject hash.objectsmaps a domain to that object's hash. A key MUST be inmanifest::MANIFEST_OBJECT_DOMAINS, which isroute-table,probe-result,outside-evidence,attestation-key,canary-plan,table-updateandcapacity-declarationfor now.capacity-declaration(Task 19b) names the UID's capacity declaration, which its one commitment used to name directly (capacity-bonds.md); it is under the same local-and-test-only activation asattestation-key.canary-plannames the validator's canary-plan commitment, the store key itsCanaryRevealis served under once the window ends, so the object isn't fetchable until then (measurement.md§Canary plans, Task 14). Likeattestation-key, it is active from window 0 on localnet and testnet only, and no scoring reads it before PB-38.attestation-keynames the hotkey's oneattestAttestationKeyRecordby its sealed hash (OQ-55 reading (b), OQ-97):bwos attest-key commitwrites it, andbwos validator-set buildreads it (cli-and-mcp.md). Since Task 19b the live loop scores from it (measurement.md§Live loop).hop-digest-batch(ADR-0038) is registered as a wire and object-store domain but withheld from manifests until OQ-45 and OQ-64 are settled. Each hash is the object's store key, as 64 lowercase hex characters. Validators find a hotkey's objects at its on-chain axon (serve_axon, OQ-223), read from the metagraph at the same block hash as the commitments, and pullhttp://<axon ip>:<port>/v0/objects/<domain>/<hash>from it (a bare base: IP literal, explicit port, no path or query;fetch::check_pull_base). Ontestthe axon must be a global unicast IP; loopback and private addresses only onlocal. The manifest carries no URL (Task 20 ruling). Every object is pulled by the hash the chain authenticates, withinMAX_OBJECT_BYTES, the fetch timeouts and a per-read time budget, so a missing or late object counts as absent. There are no uploads from outside.objectsis omitted when empty, and so arebindingandhotkey_sigwhen absent. - New object kinds. A later object kind is added by appending its domain to
MANIFEST_OBJECT_DOMAINS. The manifest version doesn't change. A validator refuses a whole manifest, binding included, if it names a domain the validator doesn't know (ManifestError::UnknownDomain). On its own, this doesn't keep validators aligned: during an upgrade an old validator drops such a manifest while a new one accepts it. The safeguard is activation. A new domain MUST NOT be named before an agreed activation window, and before that window every validator refuses it, including validators on new code. The activation rule is open (open-questions.mdOQ-45). - Activation of
attestation-key(Task D1, scoped exception to the rule above).attestation-keyis active from window 0 onlocalandtestonly. This is allowed because nothing scores from manifests before Task 19b: the only reader isbwos validator-set build, an operator tool, so an old validator refusing such a manifest can't make honest validators score differently. A store on code from before Task D1 still refuses the manifest (UnknownDomain), binding included, so operators SHOULD upgrade every validator store before a hotkey commits one. Before any scoring reads manifests, and before any mainnet use, Task 19b MUST set an activation window ahead of the upgrade (OQ-45), from which every validator accepts the domain; until then no mainnet manifest may name it. Task 19b: the live loop scores from manifests onlocalandtestonly, whereattestation-keyandcapacity-declarationare active from window 0 because every validator store there runs the same code. The mainnet activation window stays open (OQ-45); nothing in this repo touches mainnet. - Signature.
hotkey_sigis the sr25519 signature byhotkeyoversigning_bytes("commitment-manifest", manifest), with the Substrate signing context, or over exactly<Bytes>|| those bytes ||</Bytes>, which is what a browser wallet'ssignRawsigns (ADR-0054, §Linking with a browser wallet). Nothing else is accepted. It is checked inbwos-corebyidentity::verify_sr25519_hotkey_sig, which is sync and pure. A missing, malformed or all-zero signature is refused. So is the all-zero account, because any signature verifies under it. - On-chain hash. The chain holds
commitment_hash = SHA-256(sealed_bytes("commitment-manifest", manifest)), which includeshotkey_sig(encoding.md§Hashing). The manifest is served at/v0/objects/commitment-manifest/<commitment_hash>. The object store verifies the signature before it stores a manifest. - Read block. For window
w > 0, a validator MUST read each hotkey's commitment from the chain state at blockw·tempo − 1, the last block beforew, by that block's hash. It must not read at the block it happens to query. Every honest validator then fetches the same manifests (Invariant 1), and nothing named forwcan change afterwstarts. A hotkey has one commitment, so only the one in force at that block counts. Window 0 has no read. The live loop also reads atw·tempo + SOLVER_COMMIT_DEADLINE_BLOCKS, the solver commit deadline, for route tables, and at(w+1)·tempo − 1for the probe batches and evidence made duringw(measurement.md§Live loop). - Validity. A manifest read for
wcounts only ifcovers(w)holds:wis itswindoworwindow + 1(CommitmentManifest::covers). A manifest committed during windowmis read at the start ofm + 1and counts there, so objects produced duringmare picked up. Which window's objects are scored from each read (Task 19b, OQ-132): a binding, a capacity declaration and an attestation-key record count for everywthe manifest covers; a probe batch and outside evidence count only from a manifest made for the scored window and only when the object is for that window; a route table only when it is forcurrent_snapshot.window + 1. Callers checknetuid, and check thathotkeyis the committing UID's metagraph hotkey.bwos validator-set buildappliescoverstoo, for the window of the block it builds at (block / 360), so a validator recommits its manifest at least every other window to stay in the set (OQ-97). - What
verifycovers.CommitmentManifest::verifychecks only the manifest itself. The binding and every object it names are fetched by hash and verified on their own, each under its own domain rules. - Status. Since Task 19b,
bwos-validator livereads every hotkey's manifest at the read blocks and takes the binding hash (uid_binding_commitments), the declaration, the records, the probe batches, the evidence and the route tables from it.run-tempostill takes aTempoInputas given.
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).
- Where. Object
(domain, hash)is athttp://<axon ip>:<port>/v0/objects/<domain>/<hash>(an IPv6 address in brackets): the manifest atcommitment-manifest/<commitment_hash>, a route table atroute-table/<its object key>, an incumbent's signed table update attable-update/<its object key>, named by thetable-updateslot of its current manifest.bwos-solver daemon --serveserves these and sets the axon. The axon is read at the same block hash as the commitments it serves. Plain HTTP: the committed hash authenticates every object, so TLS would add no integrity. - Address. Only a bare base that
fetch::check_pull_baseaccepts:http://<ip>:<port>, an IP literal (no DNS), an explicit port, no path or query; ontesta global unicast IP, loopback and private addresses only onlocal. The axon is untrusted: it only says where to ask. - Authentication. The hash committed on chain authenticates each object: a validator recomputes the object's store key (
wire::object_hash_hex, or the sealed hash for the manifest) from the bytes it got and drops a mismatch. Each object then passes its own domain's checks. Nothing about the address or the server is trusted. - Limits. A response is at most
MAX_OBJECT_BYTES(4 MiB), refused above it, withinfetch::FETCH_TIMEOUTper request. Redirects are not followed. Each object races the validator's peers and the axon of every hotkey naming it, one attempt per source per window, withinREAD_FETCH_BUDGETfor a read. - When. A route table is pulled when the validator takes the
D(w)read, once blockS + SOLVER_COMMIT_DEADLINE_BLOCKSis final, never before (scoring.md§Grading item 9), and the path probes are drawn from the tables it got then. A solver MUST serve its table from that block on;bwos-solver daemonserves it once the best head reaches it. - Missing or late. A table not fetched and verified at the draw is no submission for the window (OQ-224, T240), and so is a missing manifest, or a hotkey with no axon or one
check_pull_baserefuses.
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).
Payload.
0x00 || u32be(not_before) || u32be(not_after) || node_1 || ... || node_n:- the first byte is the version, 0;
- each
node_iis a 32-byte valid, non-weak Ed25519 public key; - the keys are strictly ascending by bytes;
1 <= n <= 7(MAX_INLINE_NODES) andnot_before <= not_after.
So the payload is
9 + 32nbytes, at most 233. The decoder is strict: exact length, version, count, order, window and keys. There is no hotkey, netuid or signature: the commitment extrinsic is signed by the hotkey for this netuid, and its storage key is(netuid, hotkey).Fields. Field 1 is the payload's first 128 bytes and field 2 is the rest, present only when the payload is longer than 128 bytes. Each is
Raw<len>. Field 0 isSha256(commitment_hash)(§Commitment manifest) orNonewhen the hotkey has no manifest.Layouts. Transit Fabric reads exactly
[Sha256(m)]and[Sha256(m) | None, Raw(a), Raw(b)?]whosea || bdecodes, withaexactly 128 bytes whenbis present andbnon-empty (inline_binding::parse_commitment,bwos_chainparse_record, the page'sparseRegistration). Any other registration is not Transit Fabric's. Readers skip it, and Transit Fabric tools never replace it.Equivalent binding. For UID
u, the payload stands for the unsignednode-binding{v:0, hotkey: <u's metagraph hotkey>, netuid: <the subnet>, nodes: <lowercase hex>, not_before, not_after}(InlineBinding::to_node_binding). Itshash("node-binding", ·)isu's only committed binding hash. Binding resolution then applies unchanged (consent, liveness, conflicts).Read block, replay and timing. As for manifests (§Commitment manifest, "Read block"): a validator reads each registration at block
w·tempo − 1, by that block's hash (ChainClient::commitment_records_at_block). Only the registration in force there counts. A binding committed during windowmcounts fromm + 1, and only whilenot_before <= now_block <= not_after. A commitment can't be replayed (old state is gone, and extrinsics carry a nonce). Copying the bytes into another hotkey's commitment binds nodes whose consents name someone else, so they count for nobody (T220). Task 19b MUST read the metagraph (uid -> hotkey) and the commitments at the same finalized block hash, that ofw·tempo − 1.Fail closed. An inline entry that doesn't decode leaves its UID with no binding at all, never its manifest's (
decode_inline_mapkeeps it asNone), consistent withparse_commitment.Precedence. An inline binding in the registration in force is the UID's only binding for the window. The manifest's
bindingis ignored, and the manifest'sobjectsstill count (Binding resolution, the paragraph before rule 1).Supersession. A new commitment replaces the registration, so
not_beforeneed not increase between inline bindings (rule 3 is for the manifest path's several live hashes).Recommits keep it. Every Transit Fabric commit path reads the registration first and keeps fields 1 and 2 when it writes field 0 (
bwos bind commit --manifest,bwos attest-key commit, the page), and refuses a registration in no Transit Fabric layout. Going back to the manifest's binding takes an explicit--drop-inline(or the page's "Drop the inline binding" box): the bindingmnames then counts from the next read, even an old one (T223).Collisions.
- A node in two hotkeys' bindings: the consent decides (rule 4).
- Two nodes of one fleet with one derived ASN: refused by
bwos bind commit --inlineand the page. - An inline node's block for the earliest-commitment ASN rule is the block of the first registration that listed it under that UID, with no break at any read block since. Its tie-break uses the hash of the block after that one, so recommits neither push it back nor re-roll its tie (ADR-0058 §5, T226, OQ-204).
- Collisions across fleets: settled by the snapshot.
Size.
MaxSpaceis 3100 bytes per hotkey per tempo on testnet, and an inline commitment uses at most 265 (32 + 233).Activation (T221, OQ-201). Code from before ADR-0058 reads a multi-field registration as not Transit Fabric's and would drop the manifest too. Scoring therefore reads inline bindings only through Task 19b's chain reader, which fills
TempoInput::inline_bindings, from an ADR-0049 activation block. Before that block every validator ignores inline layouts. Onlocalandtestthe layout is active from window 0, because nothing scores from chain commitments yet. Mainnet also needs a read-only check of its runtime'sMaxFields,DataandMaxSpace(OQ-203).Writing it.
bwos bind commit --inline <binding file>(cli-and-mcp.md) keeps the field 0 it reads. So does the link page (§Linking with a browser wallet).Status. Encoding, layouts, precedence, resolution, the chain read and write, the CLI and the page are built. Task 19b's reader is not, and neither is the ASN block derivation (OQ-204).
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):
- its own
node-consentobjects, signed by its node key; - its operator's hotkey-signed objects, which the operator gives it as files: the
commitment-manifest, thenode-bindingthe manifest names (manifest mode only) and thecapacity-declaration. These areprobe_forward::FORWARDED_DOMAINS. The node never holds the hotkey (Invariant 5); it passes on signed bytes. Nothing else is forwarded: route tables have their reveal rules (scoring.mditem 9), and validators' objects come from validators.
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.
What the node sends. Its consents: per netuid the consents with its highest
seq, and every revocation, at mostMAX_NODE_CONSENTS(8;select_node_consents). Its operator's objects: at mostMAX_NODE_OBJECTS(4), each of which must verify as a store would keep it and fit one datagram (select_node_objects); a larger one is served from a store instead (OQ-262). It sends everything at its first handshake, on any change to its files, on a new handshake once the last send is at leastPROBE_FORWARD_MIN_GAP_SECS(60) old (so an agent that restarted gets them again), and at least everyPROBE_FORWARD_RESEND_SECS(600), several times a window. A no-root node takes them as--consents <file>(one consent, or a JSON array) and--forward-object <domain>=<file>, re-read when a file changes; every consent must be the node key's own, so--consentsneeds--node-key.What the agent takes (
accept_message). A payload that decodes, in a forwarded domain, whose object verifies as a store would keep it (object_store::verify_object_bytes: canonical, hash, signature), from a session bound by a livewg-binding(a--test-identitynode, known by its WireGuard key alone, forwards nothing). Then:- a consent counts only if its
nodeis the node key the session is bound to; - an operator object is kept tagged with that node key, and counts only once admitted (below).
Each session has a gate (
ForwardGate): it remembers its lastPROBE_FORWARD_RECENT(16) messages, so a resend is dropped before anything else and neither taken twice nor charged (forwarded_repeats; fix round 2, H3); what a resend of a message the session took gave is handed on to the pool again as sent once more, unverified and uncharged, at most once everyPROBE_FORWARD_MIN_GAP_SECS(60) per message (forwarded_refreshed; cold-start fix), so the pool's recency follows what the node still sends; and a new message spends a token of a bucket ofPROBE_FORWARD_BURST(16) datagrams, refilled one everyPROBE_FORWARD_REFILL_MS(5_000). Anything else is dropped and counted. Nobody else uploads anything (the founder declined public uploads).- a consent counts only if its
The pending pool (
ForwardPool, fix round 1, H2; per node, fix round 2, H3). What the agent takes goes into the validator's pending pool for its netuid, kept per session node, each entry with the block it first came at: the node's current consent (the highestseq, lowest canonical bytes on a tie), its newest revocation, andMAX_NODE_OBJECTS(4) objects (a repeat counts as sent again). Once a node has 4, a new one replaces the least recently sent of the node's objects in the domain it holds most of, the first such domain by name on a tie (cold-start fix): an operator that commits a new manifest every window (bwos declare keepalive) replaces its oldest manifest, never the declaration they all name, and the pool still holds the manifest on chain at the read block when the next one arrives. A node's entries replace only its own, so no node can crowd out another's, and the pool is bounded by the nodes the agent binds (retain_nodesforgets the others). The pool feeds only the validator's own reveal and its probe agent's plan (never scored). Nothing in it is scored, retained byconsent_stateor put in the object store: scoring reads forwarded items only through the window's revealed union, which every validator computes alike.Admitting operator objects (
admit_forwarded, against the chain at the read block). For each UIDuwhose commitment's field 0 is a manifest hashm(and whose hotkey no other UID has, as the chain ensures; a hotkey under two UIDs admits nothing):- the manifest: the forwarded one whose sealed hash is
m, if itsnetuidis the subnet's and itshotkeyisu's metagraph hotkey, from any forwarder; u's nodes: those of its inline binding when it has one (ADR-0058 §3; a UID whose inline binding doesn't decode admits nothing); otherwise those of the binding: the forwardednode-bindingwhose hash the manifest names asbinding(only that way, never throughobjects), if it isu's hotkey's and the subnet's, from any forwarder;- every object whose
(domain, hash)the manifest names inobjectsand whose ownhotkeyisu's (fix round 1, M2), only as forwarded by one ofu's nodes.
The manifest and the binding are pinned by the chain (field 0's hash, and the manifest's
bindingunder it), so who forwarded them changes nothing, and anyone may (fix round 2, H1): an outsider forwarding a UID's manifest only helps it reach validators, and a manifest-mode binding too large for a datagram can come from a store while the manifest still comes over a probe session. They are tagged with the lowest forwarding node key; each other object with the lowest ofu's nodes that forwarded it. Without the manifest a UID admits nothing, and without its nodes nothing past the manifest and binding. Each admitted object is kept once per(uid, domain, hash), and the chain authenticates every byte. Whether a binding is live, a manifestcoversthe window, or an object counts for it is decided by the reader as for any object (§Commitment manifest).- the manifest: the forwarded one whose sealed hash is
Making them a common input (OQ-200). Validators receive different subsets, so each validator lists what its pool held at the cutoff in its revealed
ProbeResultBatch(measurement.md§Results and commit-reveal):consents(reveal_consents) andforwarded(reveal_objectsof whatadmit_forwardedadmits at its read block). The window's sets are the unions of what counts of each revealed list. Consents, one at a time (accepted_reveal_consents, integration fix round, H1): a list whose shape fails, which only its signer controls (sorting and uniqueness, the totals and byte budget, the netuid, one current consent and one revocation per node, no current consent its listed revocation supersedes), adds nothing; otherwise each consent whose node a binding at the scorer's read lists under itshotkey(checked before its signature), and that verifies, counts, a UID's only while it keeps within its quota. A consent the scorer can't place, because it lacks that UID's binding, adds nothing and voids no other UID's. A validator checks its own list with the strictcheck_reveal_consentsbefore it signs. Objects, per UID (accepted_reveal_objects, fix round 2, H1): the entries admitted for a UID within its quota count; a UID over its quota adds nothing from that list, an entry admitted for no UID adds nothing, and the rest of the list still counts, so no entry can void another UID's. A validator checks its own object list withcheck_reveal_objects(all of it counts) before it signs. Every validator admits the object union again with the same chain read (revealed_objects), so all score the same sets.- Union can't add a forged consent or object.
- It can't resurrect a node through a lower
seq(effective_consents). - It restores a revocation that one validator withholds.
Bounds (OQ-200;
scoring.mdparameter table; fix round 1, H1, M1, M4).- Cutoff: a batch for window
wlists what its validator's pool held at block(w + 1)·tempo − FORWARD_REVEAL_CUTOFF_BLOCKS(60), which isS + 300, the blocklivecommits the batch at (OWN_COMMIT_OFFSET_BLOCKS; integration fix round, L4: it was 10, a block no committed batch could reach); what arrives later goes in the next window's batch. - Per node: its current consent (the started, non-revoked one with the highest
seq) and its newest started revocation, newest first, so old revocations can't displace the current consent. When the revocation supersedes the current consent (a higherseq, or the samesequnder the same hotkey, soeffective_consentswould drop the consent anyway), only the revocation (fix round 2, M4). Only when a binding at the read block lists the node under the consent'shotkey(validator::binding_listings). - Per UID, not one global truncation: at most
MAX_REVEAL_CONSENTS_PER_UID(16; every node's current consent first, then revocations) andMAX_REVEAL_OBJECTS_PER_UID(3; manifest, binding, then the rest), each object once per(domain, hash)whoever forwarded it. One UID can't crowd out another's (simconsent_crowd_out). A reveal's object list takes whole UIDs, so the totals never cut a UID's manifest from under its other entries. - Totals: at most
MAX_REVEAL_CONSENTS(4_096) andMAX_REVEAL_OBJECTS(768), 256 UIDs times the quotas, and together withinMAX_REVEAL_FORWARD_BYTES(2_750_000), which fits every cap at its maximum and leaves over 1.4 MB ofMAX_OBJECT_BYTESfor the rest of the batch.ProbeResultBatch::validaterefuses a batch over a total or the byte budget, out of order, with an object twice, or listing one that doesn't verify (check_reveal_structure). - A UID that binds more nodes than its quota covers gets only the first by node key into one validator's reveal (OQ-263): over probe forwarding a fleet of more than 16 nodes on one UID gets only 16 consents revealed. Such fleets deliver their consents by the store path instead (a store at
/v0/objects/node-consent/<hash>that validators fetch, or--consents-fileat the validator);bwos-validator livetakes neither (integration fix round, M1), so in the live loop they have no path yet (OQ-263).
- Cutoff: a batch for window
When forwarded items take effect (OQ-261, cold-start fix). A window's revealed consents join that window's
TempoInput::node_consents. Objects from windoww's union, admitted againstA(w), join the store before scoring readsA(w)'s manifests, so a manifest and the declaration it names that only a node forwarded count forwitself, as served ones fetched at scoring do. (They used to wait forw + 1's reads; an operator re-committing every window had a newer manifest there, so a no-server operator's declaration never counted.)What the validator loop calls (Task 19b). Each window:
ProbeAgent::take_consentsandtake_objectsinto the validator'sForwardPool::new(netuid)(insert_consent,insert_object, with the current block). Never intoconsent_stateor the object store.pool.retain_nodes(...)with the nodes the agent still binds.- At the cutoff block:
pool.held_at(cutoff);batch.consents = reveal_consents(held_consents, netuid, cutoff, &validator::binding_listings(&input));batch.forwarded = reveal_objects(&admit_forwarded(&held_objects, &ctx)), withctxthe chain read at the read block. The pool keeps each node's current state, so it isn't pruned by age: a node's resends are repeats the agent neither verifies nor charges, handed on again at most once everyPROBE_FORWARD_MIN_GAP_SECSso they refresh the pool's recency, and its entries stay held for later windows' reveals. - Once the window's batches are revealed:
revealed_consents(&batches, netuid, &listings)appended to that window'sTempoInput::node_consents(and from there, like any input consent, toconsent_state);revealed_objects(&batches, &ctx)into the object store, before the window's own manifest reads atA(w).
In
bwos-validator live(integrated after Task 19b). The probe agent and the validator are separate processes:bwos-probe serve --netuid <n> --pool-out <file>keeps its pool written to<file>(rewritten whole, then renamed, each time a node forwards something new), andbwos-validator live --probe-pool <file>reads it at the start of every pass (step 1, each entry at the block the validator first sees it, which can only be later than the agent took it; the nodes the file no longer holds are forgotten,retain_nodes). The pool is in memory only: after a restart the file is read again, which delays entries and adds none. Step 2 runs at the own commit,S + OWN_COMMIT_OFFSET_BLOCKS, which is the cutoff (L4); anything later stays held for the next window's batch. A cold start pastS + 300readsA(w)before it commits, so its batch still reveals. Its chain read isA(w), with every manifest admitted that the store already holds or that the validator's own pool admits againstA(w), and the bindings either holds (local only, so the commit never waits on a fetch), and the manifest hashes of field 0 for admitted and not-yet-fetched manifests alike (ChainRead::manifest_commitments). The lists replace the--probe-resultsbatch's own, and the batch is signed again with the attestation key; with no batch file, a batch of the lists alone is committed. Step 3 runs inside the window's assembly, before any live node is resolved: the union of the revealed batches' consents joinsnode_consents(sorted, unique), counting only batches committed by a validator-permit holder atA(w), checked before any signature (integration fix round, M2), and the objects the union admits againstA(w)go into the store first, andA(w)'s not-yet-fetched manifests are admitted from it, in the retained read too, before its bindings and declarations are read (cold-start fix; testa_forwarded_declaration_counts_in_its_own_window). The probe agent's plan readsA(cur)the same way as the reveal, with the own pool's admitted objects, so a no-server operator's declared capacity is planned in the window it counts in; the plan is not scored. Scoring never reads the pool (Invariant 1; testa_forwarded_consent_reaches_scoring_only_through_the_union), nor its own store's consents: inlivea consent counts only through the revealed union and the consent state it feeds (integration fix round, M1; a manifest can't name a consent, so a store copy is one validator's alone; testa_consent_only_in_the_local_store_does_not_count).liverefuses--consents-file, and every--consents-filerefuses a pool by name.bwos-probe serve --netuid --pool-out,bwos-probe batch-sign --pool --input --manifest-commitmentandbwos-validator forwardeddo the same steps from files (test/netns/probe_forward.sh). The pool file feeds onlybatch-sign, which reveals from it against the chain read and refuses a list that failscheck_reveal_consentsorcheck_reveal_objects; it is not a consent list, and--consents-filerefuses it (fix round 2, H2), since a validator scoring what it alone received would diverge from the others.Kernel nodes (PB-48, closes OQ-260) hold their probe sessions with
bwos-node probe-session: the no-root node's loop with no BGP peer, under the kernel node's own WireGuard key and node key, run bydeploy/kernel/install.shasbwos-probe-session.service(the system userbwos-probewith no capabilities, reading only a copy ofnode.keyin/etc/bwos-probe) from the config's"probe": {"peers", "hotkey", "netuid"}. It answers STAMP at the node's/128inside each session and delivers the node's consent (signed at install by the node key, the hotkey only its address) and each--forward-objectfile exactly as a no-root node does. Validators' agents bind it by the node key alone, its probe session being under the node key's X25519 form (ADR-0061); nowg-bindingis handed over.
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).
- Link URL.
bwos-node link-url -base <page> -hotkey <ss58> -netuid <n> -not-after <block> [-not-before <block>] [-seq <n>] [-key <node.key>]signs this node'snode-consentexactly asbwos-node consentdoes (the node key only) and prints{"hotkey","netuid","node","url"}. The URL is<base>#consent=<base64url(canonical consent)>: RFC 4648 §5 base64url without padding, decoded strictly (no padding, no other alphabet, zero spare bits). The consent is in the fragment, never the query, so a browser never sends it to a server.<base>ishttps://..., orhttp://to127.0.0.1,localhostor[::1], at most 512 printable characters, with no?or#(wallet_link::check_link_base). The consent's hotkey MUST be SS58 with prefix 42, and a revocation is refused. A fleet's consents join asconsent=<a>&consent=<b>...; any other fragment part is refused. The router's Setup button opens this same URL. - Binding.
wallet_link::binding_from_consents: onenode-bindingover the consenting nodes, sorted and unique, asbwos bind signbuilds it. Every consent MUST verify, not be a revocation, name the same hotkey and netuid, and cover the binding's whole[not_before, not_after]. Two consents for one node, and two nodes with one derived ASN (AsnCollision), are refused. The page can't see the snapshot, so a collision with another fleet's node is not checked there. - Manifest.
wallet_link::merge_manifest, withwindow = block / 360at the block the page reads. With no commitment on chain, the manifest names only the binding. With one, the operator MUST supply the manifest it names (pasted, or fetched from<their store>/v0/objects/commitment-manifest/<hash>); it must verify, hash to exactly the on-chain commitment, be the same hotkey's and netuid's and not for a later window. The result keeps itsobjectsunchanged, replacesbinding, and moveswindow, so a hotkey that also solves keeps its route table and attestation key. The page reads a registration only in a Transit Fabric layout (§Inline node binding, asbwos_chaindoes); the manifest hash is field 0'sSha256. A registration in any other layout is never replaced by the page, at signing or at commit. The page re-reads the registration before submitting and refuses if it changed at all since the merge. - Inline mode (ADR-0058), the default for at most 7 nodes. The page encodes the binding into fields 1 and 2 and keeps field 0 exactly as committed (
Sha256(m)orNone), so it doesn't merge, re-sign or need the manifest's objects. The wallet signs only theset_commitmenttransaction: there is nosignRawand no file to save, since nothing randomized is signed off chain. The operator still supplies a committed manifest, and the binding it names, but only for the review below. With more than 7 nodes, or with the box unticked, the page uses the manifest path. - The binding being replaced. When the registration carries an inline binding, that is the one being replaced (it is in force, ADR-0058 §3), decoded from the chain. Otherwise, when the committed manifest names a binding, the operator MUST supply it too (fetched from the same store, or pasted); it must hash to exactly the name. The page shows the nodes the new binding adds, removes and keeps. In manifest mode it requires the new
not_beforeto be strictly greater than the manifest binding's (Binding resolution, rule 3). It enables Sign only after the operator ticks "these are my nodes" for exactly what was reviewed; any change unticks it. - Signatures. The wallet
signRaws the binding's and the manifest's signing bytes; the page checks each signature with the ADR-0054 rule before going on. - Hotkey only. The page offers only wallet accounts that are the consents' hotkey, and refuses one that owns hotkeys or owns itself (a coldkey) or isn't registered on the subnet, where the runtime exposes
SubtensorModule::{OwnedHotkeys, Owner, Uids}; it warns that a coldkey must never be used. - Commit. The wallet submits
Commitments::set_commitment(netuid, {fields: [Sha256(commitment_hash)]})from the hotkey, asbwos bind commitdoes. In inline mode it submits{fields: [Sha256(m) | None, Raw…]}instead (inlineCommitmentInfo), asbwos bind commit --inlinedoes, and after finality it checks that the chain holds exactly that payload and field 0. Onlylocal(ws://127.0.0.1:9944) andtest(wss://test.finney.opentensor.ai:443). At connect, before review and signing, and before submitting, the page checks the genesis hash asbwos_chain::check_genesisdoes (mainnet refused on every network,testmust be the testnet,localmust be neither), and requires the endpoint'schain_getBlockHash(0)and the genesis polkadot.js signs into the extrinsic to agree. In manifest mode, it submits only in the manifest's ownwindow(a manifest for an earlier window must be signed again). It makes the operator save both files before it enables the commit, because the manifest signature is randomized and those files are the only copies. - The page itself. It loads only its own files: the four
@polkadotlibraries are one vendored bundle,site/link/vendor/polkadot.js, whose sha256 is insite/link/vendor/SHA256SUMSand checked bymake link-page-test; its CSP isscript-src 'self' 'wasm-unsafe-eval'. It refuses to run in a frame, and its host MUST sendContent-Security-Policy: frame-ancestors 'none'as an HTTP header (a meta tag can't;site/link/README.md). - Publication. No server is needed when the nodes are no-root nodes with
--probe-peer, or kernel nodes with a"probe"config (PB-48): each node delivers its own consent, and forwards the manifest, the binding (manifest mode) and the capacity declaration the operator copies to it, over its probe sessions (PB-45b, §Delivery over the probe session). In inline mode the binding is on chain. Otherwise, as forbwos bind: the operator serves the binding, the manifest and the consents at their/v0/objects/...paths (ADR-0015). Anode-bindingtoo large for one datagram (manifest mode, roughly more than 13 nodes) still needs a store (OQ-262).
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>"}
commission_ppmMUST be<= MAX_AGGREGATOR_COMMISSION_PPM(200_000ppm =20%).cost_ppm(when present) MUST be in[MIN_COST_PPM, MAX_COST_PPM](200_000..=2_000_000ppm).