← Back to Whitepapers

FORGEPATH

The sovereign URL → chain → render dispatch bus — one protocol, infinite operands, no vendor in the byte path

NODEZEROINSIDE.


0. Abstract

FORGEPATH is the family's chain-resident content-delivery layer: an HTTP edge proxy that resolves any URL to bytes on the BSV chain, fetches them through the family-sovereign Tera-Z consumer, sha256-verifies every byte, and renders them to whatever operand the URL declares — a doctrine page, an HTML site, a FORTH dispatcher, a data blob, an SVG sigil, a Phi Omega V.6 fire summary, an app bundle, or a raw inscription passthrough. No vendor, no ICANN, no DNS is required in the canonical path: a URL is decoded as a payload for a chain call to a hash, and the answer comes back over our own metal. It is BUILT and running on Elder at port 7800, and its acceptance suite is 11/11 green. This paper documents the real dispatcher — its grammar, its resolution order, its provenance contract — grounded in the code that serves the requests, and marks honestly where the surface is proven versus where it is scaffolded for a future driver.

Definition (NZ-locked, 2026-05-04): "TX a URL → directed to a family server → URL decoded as payload for chain call to a hash → returned via FORTH @ 6633 Hz → rendered on the caller's base metal as a website OR ANY OPERAND we provide." FORGEPATH is the dispatch bus that makes that sentence executable. It is NOT a hosting company and NOT a validator we run — the family is a chain CONSUMER that operates the dispatch bus. Vendors are substrate, not gatekeepers.


1. Why FORGEPATH exists

A conventional web address is a lease. DNS + ICANN + a registrar + a hosting vendor sit between a name and its bytes, and any one of them can revoke, refuse, or disappear — the Wix registrar-transfer saga (2026-04-28 → 2026-05-15) and the FastComet cancellation (2026-05-10) are the family's own scars. For a sovereign OS whose canon, sites, and apps all live on chain, that leash is structurally wrong: the bytes are already immutable and public on BSV; the only thing missing is a way to ask for them by name and receive them rendered.

FORGEPATH inverts the lease. The bytes are the destination; the chain is the source of truth; DNS is at most an optional convenience bridge for Web-1/2 visitors. A sovereign client asks /<operand>/<name> and gets chain-verified content back with the source TX and on-chain sha256 stamped in the response headers — trust-falsifiable, so anyone can re-derive the bytes from the chain themselves. This is the Web-III addressing posture the family canonized ahead of the market (NZ, 2026-05-14: "I BELIEVE THE WEB III IS GOING THIS WAY — JUST NO ONE KNOWS IT EXISTS YET").

Vendor CDN / DNS host FORGEPATH
Name leased through ICANN + registrar + host Name resolves to chain bytes — Phi Omega V.6 indexer + designation, no ICANN in the canon path
Bytes live on a vendor's disk, mutable, revocable Bytes live on BSV — immutable, public, content-addressed
"Trust us, this is the file" sha256-verified + provenance headersX-Forgepath-Source-TX + X-Forgepath-Body-SHA256, re-derivable by anyone
One content type, one render path One protocol, infinite operands — canon/page/forth/data/sigil/fire/app/tx-passthrough
Registrar dies → site dies Registrar dies → nothing at the canon layer — designation persists chain-resident

2. The one protocol (universal resolution contract)

Every request — a doctrine, a website, a FORTH dictionary, a raw TX — runs the SAME pipeline, with a different operand renderer at the end. This is the dispatch contract, implemented in server.js over the lib/ modules:

parse URL        (url-resolver.parsePath)      → { operand, ref, ref_type }
   → resolve     (url-resolver.resolve)        → chain coordinates (txid | fire+sha | manifest | algo | 404)
   → cache?      (edge-cache.get)              ← content-hash keyed LRU; warm hit short-circuits
   → dispatch    (dispatcher.*)                → Tera-Z fetch + 1Sat envelope decode + sha256-verify
   → render      (render-glue.render)          → operand-specific output
   → stamp + send                              → provenance headers + streamed body

The single-pipeline property is what makes FORGEPATH a bus rather than a pile of endpoints: a website and a doctrine differ only in their final renderer, not in how they are fetched or verified.


3. The URL grammar (one bus, eight operands)

parsePath recognizes a leading operand segment, otherwise treats a bare token as a name (operand auto-derived from the artifact's kind) or a 64-hex string as a direct txid:

/                                → home / index page
/tx/<64-hex-txid>                → raw inscription body, any content-type (passthrough)
/canon/<name>                    → markdown doctrine → HTML (frontmatter-aware)
/page/<name>                     → chain-resident HTML page (passthrough)
/forth/<name>                    → FORTH dictionary → in-browser WASM dispatch wrapper
/data/<name>                     → JSON / CBOR / binary passthrough
/sigil/<name>                    → SVG passthrough (image/svg+xml)
/fire/<txid>                     → Phi Omega V.6 fire summary page
/app/<name>                      → application-bundle launcher page
/manifest/[<name>]               → MASTER-MANIFEST entry (HTML or JSON via Accept)
/algo/<...>                      → Algorand cross-chain ASA / contract / verify
/<name>                          → designation / indexer lookup, operand auto-derived

Resolution order (url-resolver.resolve):

  1. Direct txid in the path → Tera-Z fetch by txid (/tx/ raw passthrough; /fire/ → summary).
  2. /manifest/* → JSON shadow lookup (MASTER-MANIFEST.json); /algo/* → Algorand receipts + algod.
  3. Name → Phi Omega V.6 SQLite indexer (artifacts JOIN fires, newest fire wins) → fire txid + body sha256 → dispatch as a fire-artifact; operand inferred from the artifact kind when the path was bare.
  4. 404 if nothing resolves.

The operand vocabulary is closed and enumerated in the manifest (operands_supported: canon, page, forth, data, sigil, fire, app, tx-passthrough). "One protocol, infinite operands" is the design intent — the protocol is fixed, new operands are added as renderers.


4. The chain→bytes dispatcher (the sovereignty core)

lib/dispatcher.js is where sovereignty is enforced, and it is the piece that makes FORGEPATH more than a proxy:

Because every served body carries its origin, the response is trust-falsifiable: X-Forgepath-Source-TX names the chain TX, X-Forgepath-Body-SHA256 names the served body's hash, and anyone can pull the TX themselves and re-derive it. Trust is not requested; it is made checkable.


5. The operands (one dispatcher, many renderers)

lib/render-glue.js turns verified bytes into the declared operand. FORGEPATH authors no second machine — it renders existing chain bytes:

The bare /<name> path maps an artifact kind to an operand (doctrine/scar/feedback/spec → canon, forth-dict → forth, app-bundle → app, sigil → sigil, …) so a name resolves to the right renderer without the caller stating it.


6. The edge cache (content-hash keyed, immutable)

lib/edge-cache.js is an LRU (200 entries / 100 MB) keyed by canonical chain coordinates — tx:<txid>:<operand>, fa:<body_sha256>:<operand>, fire:<fire_txid>, or index. Because the key is content-addressed, a cached entry is never invalidated by time: the chain bytes are immutable, so a hit is always correct, and a URL that points at new content gets a new key automatically. Warm hits return in under a millisecond; cold reads pay the Tera-Z fetch + decode + render once. Every response is stamped X-Forgepath-Cache: HIT|MISS and X-Forgepath-Render-MS, so the cache behavior is observable from the outside. PROVEN — live _stats reports hit/miss counters incrementing across requests.


7. The publish surface (file → fire → URL)

bin/publish.js is the one-liner that closes the loop from a local file to a live global URL:

forgepath publish <file> --name <url-name> [--operand canon|page|forth|data|sigil|app] [--tile N]

It reads the file, derives operand + content-type (from --operand or the extension), accumulates the artifact into Phi Omega V.6, fires (broadcasts) the composite to BSV, and reports the live URL /<operand>/<name>. Once broadcast and indexed, the name resolves through the same dispatcher any reader uses. This is BUILT (CLI wired to the Phi Omega V.6 composer). Note the scar-#5 discipline: FORGEPATH itself never decides to fire family-internal content public — publishing to chain remains an explicit, gated act carrying the family-encrypted-by-default posture.


8. Non-DNS canon — the two addressing surfaces

Per doctrine_forgepath-non-dns-canon (NZ, 2026-05-14), every family ForgeSite client receives two addressing surfaces, and DNS is the junior one:

  1. ForgePath designation (CANON, required). A chain-resident name in tera-z/designation.json, resolving to chain bytes via the Phi Omega V.6 indexer + Tera-Z, rendered per-operand. No DNS, no vendor, no ICANN. At least one designation is required per tenant (accounts/<slug>.json schema v2, forgepath_designations: []).
  2. DNS domain (CONVENIENCE, optional). A vendor-edge translation for Web-1/2 visitors: nginx terminates TLS at the family edge and routes by Host header to the same backend the designation points at. May be empty.

DNS is the bridge, not the destination. Sovereign clients (ForgeView, WarDog mobile-command) bypass the browser and hit the designation directly; non-sovereign visitors get the same content via the convenience layer. A tenant whose registrar refuses transfer or whose vendor cancels is undamaged at the canon layer — the designation persists chain-resident. Forbidden patterns are explicit: DNS is never required for onboarding, never the canon addressing layer, and a <domain> is never a tenant's unique key (<slug> is).


9. Provenance — the trust-falsifiable contract (two honest hashes)

Every FORGEPATH response carries the receipts to verify itself against the chain. Because most operands render the on-chain source (canon wraps markdown in HTML chrome; forth/app wrap source in a launcher page), the served body is generally NOT byte-identical to the source artifact. A single "body sha" therefore cannot mean both things at once. FORGEPATH emits two hashes so both facts are independently checkable:

X-Forgepath-Cache:          HIT | MISS
X-Forgepath-Source-TX:      <chain txid the bytes came from>
X-Forgepath-Source-SHA256:  <sha256 of the on-chain SOURCE artifact, pre-render>
X-Forgepath-Rendered-SHA256:<sha256 of the EXACT bytes in this response body>
X-Forgepath-Body-SHA256:    <alias of Rendered-SHA256 — the served body (back-compat name)>
X-Forgepath-Render-MS:      <render time>

Two independent verifications, both re-derivable by anyone:

  1. Source-on-chain. Pull X-Forgepath-Source-TX from BSV yourself, decode the 1Sat envelope, and confirm the extracted artifact hashes to X-Forgepath-Source-SHA256. This proves the bytes FORGEPATH started from are the immutable on-chain bytes.
  2. Received-body. Hash the bytes you actually received and confirm they equal X-Forgepath-Rendered-SHA256 (== X-Forgepath-Body-SHA256). This proves the wire was not tampered between the render and your socket.

For /tx/ passthrough (no rendering) all three collapse to the same value — the served body is the source artifact — so Source-SHA256 == Rendered-SHA256 == Body-SHA256. For rendered operands they differ, and that is honest: Source-SHA256 is the chain artifact, Rendered-SHA256 is what left the process.

Honesty note (§9 correction, 2026-07-06): a prior build emitted only X-Forgepath-Body-SHA256 and set it to the source-artifact hash for rendered operands, so "hash what you received and compare the header" silently failed for canon/page/forth/fire and only held for /tx/ passthrough. The header now names the served body accurately, and Source-SHA256 carries the pre-render chain hash separately. Both are asserted in the acceptance suite (step 9: sha256(received body) == Rendered-SHA256 == Body-SHA256, and Source-SHA256 present + distinct for rendered operands). (Manifest and Algorand paths add X-Forgepath-Source / X-Forgepath-Chain-Layer.) Sovereignty here is not a claim in a banner — it is a checkable property of every response.


10. Proven by running — 11/11 green

FORGEPATH is proven by running, not by assertion. The acceptance suite (bin/acceptance.mjs) exercises URL → chain → render end-to-end and reports "FORGEPATH ACCEPTANCE PASSED — N/N green." As of the 2026-07-06 remediation the run is 15/15 (11 prior assertions + 4 for the §9 served-body-provenance fix):

  1. Liveness (/healthz).
  2. Root index renders.
  3. Canon doctrine — cold render.
  4. Canon doctrine — warm cache hit.
  5. Direct /tx/ passthrough, bit-perfect on a 2.13 MB v2 ForgeSite (18 ms, sha256 exact match).
  6. Fire summary page renders.
  7. 404 for an unknown name.
  8. Cache stats reflect requests.
  9. Provenance headers expose chain origin (source TX + served-body sha256).
  10. Served-body provenance is honest (§9): sha256(received canon body) == X-Forgepath-Rendered-SHA256 == X-Forgepath-Body-SHA256, X-Forgepath-Source-SHA256 present and distinct (pre-render source); and for /tx/ passthrough Rendered == Source == known on-chain sha.

Re-verified live at remediation (2026-07-06, Elder :7800):


11. What is BUILT vs what is VISION

BUILT + PROVEN (running today):
- The full dispatch pipeline: parse → resolve → cache → Tera-Z fetch → 1Sat envelope decode → sha256-verify → render → provenance headers.
- Operands canon, page, tx-passthrough, data, fire, manifest — all serving real chain bytes.
- Content-hash-keyed LRU cache; 404 handling; family-encrypted-fire refusal (scar #5, live-driven — see §10); CORS.
- Two honest provenance hashes: source-artifact (Source-SHA256) and served-body (Rendered-SHA256/Body-SHA256) — §9.
- 15/15 acceptance green.
- Two live instances, not one: FORGEPATH runs on Elder :7800 (Elder, ULA-bound ::) AND BH :7800 (BH, ULA-bound ::) — a redundant pair on the black-start backbone. Both answer /healthz as service:"forgepath" v0.1.0; at remediation BH reported 2906 hits / 99.9% hit rate and Elder was freshly restarted for the §9 fix. This is a co-equal two-node LAN service today.

BUILT (wired, lighter proof):
- sigil (SVG passthrough), app-launcher metadata page, publish CLI (file → Phi Omega V.6 fire → URL), algo cross-chain resolver (receipts + algod fallback).

SCAFFOLD / VISION (page exists, driver pending):
- /forth/* in-browser WASM dispatch — the page embeds the chain-resident FORTH source and canvas, but the pforth.wasm kernel hookup at /wasm/pforth.js is a pending surface.
- /app/* actual WASM/native bundle loader — the launcher reports the bundle; the loader "comes as the application surface appears ready."
- The PUBLIC front door. FORGEPATH is live on the LAN on two nodes (Elder :7800 (Elder, ULA-bound ::) + BH :7800 (BH, ULA-bound ::)), but there is no public forgepath backend yet: forgechainos.com currently 301-redirects to theforgechain.com and no public host routes to a forgepath instance. The gap is not the dispatcher (running, redundant, proven) — it is the sovereign public edge that fronts it. Scoped concretely in §13, NZ-go-gated, not yet deployed.
- /algo/* full round-trip is gated on the Algorand *_contract funding layer. Cross-DApp fix owed: the Algorand deployment shares a Merkle-leaf convention with the BSV side; the corrected leaf is leaf = txid (the raw transaction id), not dsha256(txid ‖ body). This is a shared-code fix that lands wherever the leaf is computed (Algorand receipts + any BSV verifier that mirrors it) and must be applied uniformly so cross-chain /algo/verify/<bsv-txid> proofs reconcile. Tracked here as a cross-DApp debt, not a FORGEPATH-local defect.

The honest line: FORGEPATH is a real, running dispatcher on two live nodes — the chain→bytes→render core is proven end-to-end and serving verified content today, with two honest provenance hashes and a live-driven scar-#5 refusal. The unfinished edges are two of the eight operands' client-side execution layers (FORTH-WASM, app-loader) and the sovereign public front door (§13). The sovereignty claim does not leak: every byte it serves is fetched over our own metal and sha256-verified against the chain.


12. Composition

FORGEPATH is a bus that drives existing sovereign surfaces:

Home: ~/.forgechain/forgepath/ (server + lib/ + bin/). Manifest: tools:forgepath (tx: a8e8e261…, source stamped in Phi Omega V.6 fire #2, 2026-05-05). Doctrine: doctrine_forgepath-sovereign-url-to-chain-cdn + doctrine_forgepath-non-dns-canon-for-all-family-forgesites-2026-05-14.

Home: ~/.forgechain/forgepath/ (server + lib/ + bin/).


13. The sovereign public front door — SCOPE (plan only, NZ-go-gated, NOT deployed)

This section is a plan, not an action. Nothing here is deployed by authoring it; the deploy is a separate, explicit, NZ-GO-gated act. It exists because §11 names the one honest gap: FORGEPATH is live and redundant on the LAN (Elder :7800 (Elder, ULA-bound ::) + BH :7800 (BH, ULA-bound ::)), but there is no public backend — forgechainos.com 301s to theforgechain.com with nothing routing to a forgepath instance.

Hard constraint (Babbage rule, family canon): the public edge is our own nginx + our own TLS on our own metal. No Cloudflare, no vendor proxy, no vendor WAF, no vendor DNS-in-the-byte-path. A vendor may be substrate (a registrar pointing an A/AAAA record, a CA issuing a cert) but never a gatekeeper in the request path. If a proposed step puts a third party between the visitor and our backend bytes, it is rejected. This mirrors the ordfs.network / Cloudflare scars (sovereignty leaks at delivery) and the FORGEPATH non-DNS canon: DNS is the junior convenience bridge, the designation is the canon.

Target topology:

visitor ──TLS──▶ nginx (OUR metal, family edge node)
                   │  terminates TLS with OUR cert
                   │  routes by Host: forgechainos.com
                   ▼
                 forgepath backend  (Elder  :7800 (Elder, ULA-bound ::)  ↔  BH  :7800 (BH, ULA-bound ::))
                   │  upstream { server  :7800 (Elder, ULA-bound ::); server  :7800 (BH, ULA-bound ::) backup; }
                   ▼
                 Tera-Z (127.0.0.1:9292) → BSV chain

Concrete steps (each independently reversible, none auto-fired):

  1. Edge host. Stand nginx on a family node with a stable public route (BH is the standing broadcaster/edge candidate; WarHorse/Outpost are black-start alternates). Reverse-proxy :443upstream of the two live forgepath instances, with the second as backup so a single-node loss does not drop the front door (the same black-start redundancy the backbone is built for).
  2. TLS, sovereign. Prefer the family CA (ECDSA P-384 Genesis, 2026-05-09) for family/sovereign clients; offer a Let's-Encrypt ACME cert (ACME is a protocol we run ourselves via certbot/acme.sh on our host — not a vendor proxy) for public browsers that don't trust the family root. TLS terminates on OUR nginx, never on a vendor edge. Auto-renew via a local systemd timer.
  3. DNS as junior bridge only. Point forgechainos.com A/AAAA at the edge host (IPv4 fallback + sovereign IPv6 ULA/AAAA). Registrar is substrate; if it refuses, the chain designation layer is undamaged (§8). Remove the current 301theforgechain.com only as part of the same gated cutover.
  4. Backend hardening. FORGEPATH already sets permissive CORS (chain is public) and emits provenance headers; add nginx-level rate limiting and request-size caps at the edge, keep the backend bound to LAN/ULA so the only public ingress is through the sovereign nginx. No app logic moves to the edge — nginx is a dumb sovereign terminator, all resolution/verify stays in the dispatcher.
  5. Verify by running before cutover. Curl the public name end-to-end, confirm X-Forgepath-Source-TX + both sha headers survive the proxy, confirm failover by stopping one backend, confirm TLS chain. Only then is the 301 retired.

Gate: steps 1–5 are authored as a plan; execution waits on an explicit Node Zero GO. Publishing any FORGEPATH content public also remains under scar-#5 discipline (family-encrypted-by-default; the dispatcher never self-decides to fire family-internal bytes public).


This paper is family-internal — NOT for public fire. It maps the module's structure and TX wayfinding (scar #5 surface). Do not stamp it public. If a public account of FORGEPATH is ever wanted, author a public-safe vision paper separately.

NODEZEROINSIDE. ∞.

NODE ADDRESSING (sovereign ULA — the fixed identity)

FORGEPATH binds dual-stack :: on both nodes and is reached by sovereign IPv6 ULA, which is identity-derived and NEVER drifts (no ISP/DHCP/vendor):
- Elder I → fd00:db8:ff:6:5809:6818:1db5:23fc
- BH → fd00:db8:ff:9:c8a3:a86a:6f2b:1f3e
The .155 / .162 IPv4s are point-in-time fallbacks that DRIFT (152→156→162 axis; a power-outage reboot is a drift trigger). Resolve live via family-node-lan-truth.json / resolve_family_node.{mjs,py} — never hardcode the IPv4. (Scar: 2026-07-06, ".162 is not a fixed state.")