Documentation  /  Network integration note

HiNet Decentralized Network — Integration Note

Synthesis across the seven draft specs: Identity/Registry (P-I), Routing/Aggregation (P-J), Grand Monorepo (P-K), Onboarding/Harness (P-H), Owner-Identity & Proof-of-Personhood (HiNet-Owner-Identity-and-Proof-of-Personhood.md — proof-of-personhood + biometric owner key, the Sybil gate for payout routing), Query-Classification & Quorum-Cache (HiNet-Query-Classification-and-Quorum-Cache.md — query→topic-set→quorum-cache keying), and Quorumz-Map Integration (HiNet-Quorumz-Map-Integration.md — the node pool as a Quorumz-map layer). Purpose: lock the shared contracts, fix the build order, and surface the decisions only the owner can make.

1. Cross-cutting decisions that MUST stay consistent

These are the load-bearing contracts. If any one drifts between specs, the others silently break.

1.1 One key, one identity, everywhere

• One Ed25519 identity keypair per iCore, owner-held, never leaves the device except as ciphertext inside VaultReplication. Custody: Keychain/Secure Enclave (Tauri/Rust core, product) with an MVP fallback of a 0600 file / sealed vault row via cryptography/PyNaCl. The endpoint contract is identical across custody backends (P-H B-iii, P-I §1.1).
• node_id is self-certifying, derived from the identity pubkey. This is the anchor every other spec verifies against: it maps 1:1 to the DID (did:key), the future libp2p PeerId, and it is the key that signs the audit chain, WorkOrders, quorum receipts (P-J), GM commits/refs/proposals (P-K), and registration (P-H). No spec mints its own identity — three of the four consume P-I.
• Two-key split (P-I D1): genesis k_id defines the id forever; rotatable k_sign signs day-to-day. P-J/P-K/P-H all say "the node key" loosely — they must mean k_sign authorized by k_id, or rotation breaks their signatures.
• Recovery: BIP-39 phrase at identity-init, tied to VaultReplication restore. Key loss = identity loss (stated at onboarding). Same-k_id restore ⇒ same node_id ⇒ registration is an UPSERT, not a new node.

✅ Resolved — node_id derivation unified. P-I §1.2 is authoritative: icore_ + crockford_base32(sha256(0x01‖pubkey)[:20]) (domain byte, 20 bytes → 32 chars). P-H (Onboarding) now references P-I's formula rather than restating a divergent one, so ids are consistent network-wide.

1.2 The registry is the shared backbone (index, never authority)

• One central service, hinet-registry at registry.mind.quorumz.com, on the Quorumz GCP project but on dedicated HiNet resources (own SA, own Cloud SQL Postgres + pgvector, own GCS bucket) — hard-isolated from Quorumz product data. All four specs assert this identically; keep it that way.
• Naming caution (all specs): this is NOT hinetd/registry.py (the local MLX model registry). Node-side client = RegistryClient.
• The NodeRecord (P-I §2.3) is the single shared record every other spec reads: node_id → pubkey → capabilities → endpoint → membrane → liveness, owner-signed (record_sig), self-authenticating. Because records are owner-signed and ids self-certifying, the registry's trust envelope is bounded: it can censor/withhold/reorder/stall, but cannot forge. That bound is what makes the DHT migration tractable for all four.
• The registry also anchors GM refs (P-K RefRegistry) and hosts the receipt-ledger + relay (P-J) — these are partitions/services of the same HiNet footprint, not new infra.

✅ Resolved — one API surface + one CompetenceSignature. - Endpoints: unified on P-I's /v1/* — the earlier route-name variants across specs were renamed to match; GM's /refs + /coordinator and the relay/ledger sit as namespaces on it. Anti-replay unified on P-I's challenge-nonce (P-J's nonce+ts ±120s is a compatible profile). - CompetenceSignature: the per-speciality model is canonical. Competence is now per-speciality Verifiable Competence Attestation (Routing §2.5) with a derived effective_strength; P-I §4.1's single node-level competence_centroid is demoted to a coarse ANN discovery hint, and the registry stores per-(node, speciality) attestation rows (Node-Identity §4.5).

1.3 How routing consumes the capability index (clean seam)

• Registry = the index; router = the decision. Discovery answers "who plausibly matches?" (pgvector ANN over centroids + inverted-index node_capability_tag filter + freshness/status/visibility) and returns a ranked candidate set. The router (net/router.py) runs on the asker's node and does per-prompt right-sizing → minimal-sufficient set → mode pick → shard. Sovereign routing: the platform never re-routes or reads answers (P-J §0, P-H B-ii — "local decision over a central capability index").
• Membrane is a hard pre-filter on discovery (iCorp nodes hidden from public via visibility="membrane_hidden"; visible only inside the workspace). Enforced by the registry's visibility field and the router.
• The proof ladder gates weight: declared competence is unweighted in routing until challenged/usage-proven (P-I §4.3, P-J §5) — the shared sybil defense.

1.4 How the monorepo reuses node identity + the economy

• GM mints no identity — every commit/proposal/review/merge/build is k_sign-signed and verified against the registry pubkey by node_id. GM's RefRegistry is a registry partition (monotonic signed refs; content on IPFS).
• One economy across P-J and P-K. Routing's QueryReceipt and GM's AttributionRecord are the same pay-per-use primitive: pool = price − platform_share, split by contribution weight, signed receipts appended to the audit hash-chain, MVP = compute + log locally, settlement deferred. Shared verification ladder: Tier 0/1 signed+hash-chained (MVP) → Tier 3 TEE → Tier 5 zkLLM.
• Identical membrane + lease rules in both: a leased iCore's code (P-K) and intelligence (P-J) both stay in the iCorp on exit; an iCorp answers/earns as one unit, internal iCores never referenced/paid individually.
• One consent machinery (consent.py): P-J adds quorum_ask/quorum_answer; P-K adds repo_read|write|build|contribute|review; P-H's harness gates every write/egress plugin. All append to the audit chain; network-egress needs human approval (propose_change, sensitive quorum_ask).
• One no-leak invariant: only filtered text / Δ_public-derived artifacts ever leave; raw vault, Δ_private, and weights never do; receipts carry hashes, not content. The competence centroid is computed from the existing Δ_public/DeltaView surface — same leakage gate.

2. Dependency order + phased build roadmap

Dependency spine: Identity module (P-I §1) → hinet-registry (P-I §2) → network routing + GM refs (P-J/P-K) → real P2P transport + decentralized FS → DHT/settlement/TEE-zk. Onboarding + harness (P-H) are mostly local and can proceed in parallel from day one. Three newer specs slot onto this spine: Owner-Identity & Proof-of-Personhood (HiNet-Owner-Identity-and-Proof-of-Personhood.md) hangs off the identity module (P-I §1) — proof-of-personhood + biometric owner key, hardened at P1 as the Sybil gate for payout routing; Query-Classification & Quorum-Cache (HiNet-Query-Classification-and-Quorum-Cache.md) layers onto network routing (P-J) at P1 — query→topic-set→quorum-cache keying over discovery; Quorumz-Map Integration (HiNet-Quorumz-Map-Integration.md) surfaces the registry node pool as a Quorumz-map layer, available once the registry lands at P1.

Critical-path note: P-J's network and P-K's whole model both hard-depend on the P-I identity module + registry. Build the identity module + thin registry first even though P-H's funnel/harness looks like the "product" — the funnel's registration step and the harness's network mode are stubs until P1 lands. P0 (local funnel + identity + harness) delivers standalone value with zero central dependency and should start immediately.

3. Top open decisions for the owner

Ranked by how much they gate the build.

1. P2P protocol & transport phasing. Three candidate steps: (a) LAN/loopback simulation (P-H MVP, tests aggregation+attribution with no relay), (b) relay-based signed-HTTP over Quorumz (P-J MVP — real WAN, laptops are outbound-only behind NAT), (c) libp2p (AutoNAT/Circuit-Relay/DCUtR + gossipsub + DHT) — build, or adopt SAM (Sovereign Agent Mesh) (Google, Apache-2.0), which packages libp2p relay + environment-agnostic crypto identity + MCP tool routing as a ready substrate. Evaluate adopt-vs-build at P3 (caveats: unsupported project; keep our self-certifying identity + transport-agnostic wire so SAM is swappable). See Routing §4.2. Decision: confirm the sim → relay → libp2p order, and when libp2p is worth it. Keep every wire message (QuorumRequest/AnswerReceipt) transport-agnostic so the same bytes ride HTTP or a libp2p stream unchanged. (P-H A-iv, P-J §4.2.)

2. Decentralized-FS choice for GM + VaultReplication. IPFS/Helia + central pinning is the MVP both specs assume; Arweave for permanent tagged releases; Storj/Filecoin for paid durable pinning. Decision: ratify IPFS-MVP as the shared substrate for GM (plaintext) and VaultReplication (ciphertext), and pick the pre-token anti-spam bond currency (reputation-only vs off-chain credit) since pinning economics gate GM spam control. (P-K §2.2, §7, §11.5, §11.9.)

3. Central-vs-DHT registry — and when to pay for decentralization. Central Cloud SQL now (fast global discovery, capability ANN, handle uniqueness, single cold-start reach) vs DHT/on-chain later (censorship-resistant, but ANN-on-DHT and sybil-resistant naming are the genuinely hard parts, D4/D5). This one decision covers both identity discovery and GM ref anchoring. Recommendation to confirm: central-MVP with signed-record export as the migration hook; target a hybrid where the registry stays a bootstrap + naming authority + optional fast index even after a DHT lands. (P-I §5, P-K §2.3.)

4. Aggregation default. Ship committee/MoA + retrieval-union only for MVP: it's the only mode that works across different anchor DNAs/compat-classes, moves no weights or raw data, and hits ~ceiling quality — the privacy default. MoErging/weight-merge is deferred (needs an attested qCore host + Δ_public exchange). Decision: confirm committee-only MVP with the mode-selector's MoErging branches feature-flagged to COMMITTEE so no re-architecture when the host lands. (P-J §3.2, §3.3.)

Secondary decisions to settle early (they shape schemas): - Registration default: opt-in + strong nudge (sovereign ethos) vs opt-out (network effect). Recommend opt-in. (P-H A-i.) - Sybil gating strength / owner_ref mandatory: anonymous nodes in the public pool vs account/wallet-gated registration — privacy vs sybil-resistance. (P-I D6/D7, P-J §5.5.) - CompetenceSignature centroid model (single node-level vs per-speciality) and node_id formula — see the ⚠️ reconciliations in §1.2/§1.1; these must be fixed before the registry DDL and the ANN index are built, not after. - Two-key vs one-key identity (D1) and id-stability across genesis rotation (D2) — recommend the two-key split + pin-id-to-genesis, since routing/GM/economy all assume a stable, reputation-bearing node_id that survives key rotation.

Next: Node identity & registry →  ·  All documentation →