← Back to Whitepapers

go-ordfs-server — ForgeChainOS's Sovereign ordfs Filesystem Server

Excise the Cloudflare gateway. Serve the chain from our own metal. This is build #1 of the authentic BSV OS.

Date: 2026-06-27
Authority: Node Zero direct
Builder: Elder I (Lobe 6 / Structure)
Status: Canon-authoring / design doc. NO chain stamp (separate, scar-#5-gated step). No real-account or key actions taken in authoring this.
Related canon: doctrine_ordfs-desktop-os-bsv-canon-uniformity-2026-06-27.md (the OS vision / the "why"), doctrine_tera-z-sovereign-spv-not-chain-stamped.md (the route), tools_bsv-mcp-bopen-sovereign-hardened-2026-06-25.md (the Babbage rule precedent), MASTER-MANIFEST tera_z_chain_consumer, sovereignty-leaks-at-delivery-ordfs-cloudflare.

Abstract

ordfs (the Ordinal File System) is the filesystem ForgeChainOS is built on: it already serves the live theforgechain.com as a 1Sat ordinal inscription minted by the family wallet. The OS vision (doctrine_ordfs-desktop-os-bsv-canon-uniformity) makes ordfs the cross-surface OS filesystem: desktop, mobile, and every DApp reading and writing one chain-resident filesystem, one identity, one addressing, no per-platform fork.

But the OS cannot boot through someone else's gate. The default ordfs resolution path runs through ordfs.network (a Cloudflare-fronted gateway) and junglebus.gorillapool.io (a hosted indexer). For an ad-hoc image fetch that is convenient. For the OS whose filesystem this becomes, it is the Achilles heel: a third party gates the boot, so the OS is not sovereign. This is the Babbage/BRC-100 lesson again, applied to the delivery layer.

This paper specifies the fix: run b-open-io/go-ordfs-server (the open-source, MIT, self-hostable Go ordfs server) on our own metal (BH, Lobe 9), and point its data source at Tera-Z (our sovereign SPV consumer) plus the family overlay, not at junglebus / ordfs.network / Cloudflare. The minting side is already proven. This sovereignizes the serving side. It is the first build of the buildout, and the explicit precondition for ordfs-as-OS.

1. The problem: the Achilles heel is at the delivery layer

The family's BSV stack is genuinely sovereign at the protocol and tooling layer (@bsv/sdk, our own mint scripts, Tera-Z SPV, Phi Omega V.6). The leak is narrow and specific, and the manifest already names it (sovereignty-leaks-at-delivery-ordfs-cloudflare): the delivery gateways are Cloudflare-fronted.

Verified default ordfs resolution path (this session, against our ordfs skill + the upstream go-ordfs-server README):

Why this is disqualifying for an OS (and not merely for a website):

The Babbage rule (from the bopen.ai adoption): the vendor built the mechanism for self-hosting but defaulted to their hosted box. We take the mechanism and reject the default. go-ordfs-server's JUNGLEBUS and BLOCK_HEADERS_URL being environment variables IS the mechanism. The default IS the trap.

2. What go-ordfs-server is (verified architecture)

Source: github.com/b-open-io/go-ordfs-server. Verified via: WebFetch of the GitHub repo + README, 2026-06-27, cross-checked against our ordfs skill (~/.claude/skills/ordfs/SKILL.md). Where the README did not confirm a detail, this paper says so explicitly rather than asserting it.

Confirmed from upstream:

The ordfs protocol behavior (from our ordfs skill, which documents the ordfs.network resolution model the server family implements): an inscription is a 1Sat ordinal whose locking script carries an envelope OP_FALSE OP_IF "ord" OP_1 <content-type> OP_0 <body> OP_ENDIF. The server parses that envelope, returns <body> with <content-type>. ord-fs/json content-type marks a directory (a manifest mapping filenames to ord://txid_vout / _N relative refs); the server resolves sub-paths and recurses into nested directories; sequence numbers (:-2 origin, :0, :-1 latest, :N) select a version along the ordinal's transfer chain; recursive inscriptions let HTML/JS reference other inscriptions by path.

Honest gap (open question, see §8): the upstream README did not explicitly enumerate 1Sat envelope parsing, recursive inscriptions, or ord-fs/json directory handling. The ordfs protocol supports all three (our skill documents them, and our own mints rely on the envelope format), but whether the current go-ordfs-server build implements the full set must be confirmed by reading its source before we depend on it for the OS FS. Do not assume parity with ordfs.network from the README alone.

3. The sovereign redirect (the IP)

The cure is to run go-ordfs-server on our metal and re-point its data source from the hosted JungleBus to Tera-Z, our SPV consumer. Tera-Z is canon as "the route" (doctrine_tera-z-sovereign-spv-not-chain-stamped): the Teranode validator was decommissioned 2026-05-17, and the SPV consumer is the path on every host. Tera-Z already resolves raw transactions through a multi-tier source-mux (local LRU/DB cache → family overlay → public sources) and sha256-self-validates every read.

3.1 The resolution chain (designed)

  caller (browser / DApp / OS FS mount)
        │  GET /v1/content/{outpoint}[/file]
        ▼
  go-ordfs-server            (OUR metal, BH, Lobe 9)
   • parse ordfs ref → outpoint(s)
   • Redis cache hit?  ── yes ─► serve
   • on miss, fetch tx + headers via ▼
  forge-jb-shim              (JungleBus-API-shaped adapter, OURS)
   • presents the JungleBus surface go-ordfs-server expects
   • backed by ▼
  Tera-Z  :9294 (BH)         getrawtransaction / headers / SPV
   • local LRU/DB cache → family overlay :7799 → (public, last resort)
        │
        ▼
  1Sat inscription envelope parsed → content + content-type served

Zero ordfs.network. Zero junglebus.gorillapool.io. Zero block-headers.gorillapool.io. Zero Cloudflare in the hot path. Reads hit Tera-Z first (the Babbage rule, already in the specialists' grounding banner). Name resolution (hermes.forgechain style) routes to OpNS resolved locally, not a hosted name service or DNS authority.

3.2 The two env levers + the one adapter

The adapter (forge-jb-shim) is the real work. go-ordfs-server speaks the JungleBus HTTP API; Tera-Z speaks its own JSON-RPC (getrawtransaction, getutxos, getrawmempool, etc., on :9294). The shim translates the JungleBus surface go-ordfs-server calls into Tera-Z RPC + family-overlay :7799 reads, and returns the shapes go-ordfs-server expects. Mapping that surface exactly is the integration task and the principal build risk (§8). If the surface mismatch is large, the cheaper path may be a small patch to go-ordfs-server's source-fetch layer (it is MIT Go: we may fork the fetch interface rather than emulate JungleBus). Decide after reading the source.

3.3 Close the back door inside Tera-Z

One nuance from looking, not assuming: Tera-Z's own source-mux lists ordfs as a fallback read tier (manifest tera_z_chain_consumer description: "Tera-A → forgemesh → family overlay → WoC → ordfs"). If go-ordfs-server falls through to Tera-Z and Tera-Z falls through to ordfs.network, we have re-introduced the exact hop we excised, one layer down. The redirect is not complete until that public ordfs (and WoC) tail of Tera-Z's mux is gated behind an explicit, default-off env var for the OS-FS path. Sovereign-served first; public read only as an explicit, logged last resort, never silently in the boot path.

4. Role in the OS

go-ordfs-server is the sovereign filesystem foundation: the component that turns "the chain holds our files" into "the OS reads its files from the chain, on our own metal." It is the precondition gate in the OS doctrine: ordfs-as-OS does not proceed until forge-ordfs serves content with no hosted hop.

It composes with the rest of the one-canon-of-uniformity stack:

5. Proven anchor: ordfs already works, the family already mints

This is not a hypothetical capability. The family has demonstrated ordfs end to end on the minting side:

The honest split is therefore: the inscription / minting side is proven (we build the envelope, we own the wallet, content is real and at least one bundle is chain-confirmed). The serving side is what currently leaks through ordfs.network (every receipt's ordfs_url is a Cloudflare URL). This paper sovereignizes the serving side. It does not invent ordfs; it removes the last rented door from a capability the family already ships.

6. Build plan (with proven-vs-designed labels)

# Step State
0 Read go-ordfs-server source (confirm envelope parse / recursive / ord-fs/json parity; map its JungleBus fetch surface). DESIGN (open question §8)
1 Deploy go-ordfs-server on BH (Go 1.25+, local Redis, systemd unit, bound LAN + sovereign ULA). DESIGN
2 Build forge-jb-shim: JungleBus-API-shaped adapter backed by Tera-Z :9294 + family overlay :7799. (Or fork go-ordfs-server's fetch layer if the surface mismatch is large.) DESIGN
3 Set JUNGLEBUS / BLOCK_HEADERS_URL / REDIS_URL to local. Gate Tera-Z's public ordfs/WoC mux tail behind default-off env for the FS path (§3.3). DESIGN
4 Verify by loading: fetch a known inscription (e.g. ce015cf5…_0) through our server with the network severed from ordfs.network / gorillapool, and confirm correct bytes + content-type, no hosted hop (capture egress, prove zero external calls). DESIGN (this is the precondition gate)
5 Re-point a real surface (the forgesite / a DApp) from ordfs.network/{txid} to our server; verify-by-loading the actual page, not byte counts (render-flip scar discipline). DESIGN
6 Mount as the OS filesystem layer; wire one DApp (ForgeChat) to read/write via it; then generalize to mobile + the rest. DESIGN

Proven today (no build needed): the mint pipeline, the family wallet, the envelope format, Tera-Z SPV reads of confirmed + orphan txids via overlay :7799, the live forgesite content on chain.
Designed (this paper): go-ordfs-server on our metal, the JungleBus→Tera-Z shim, zero-hosted-hop serving, the OS FS mount.

The gate is hard: no step past #4 until a known inscription serves from our server with the hosted path provably severed. Verify by loading and by watching egress, never by grep or byte-count (scar render-flip-replaced-real-client-site-with-autogen-slop).

7. Sovereignty + security

8. Open questions for Node Zero

  1. Source parity (blocking #0): the upstream README did not confirm ord-fs/json directories, recursive inscriptions, or full envelope parsing. Approve a source-read pass on go-ordfs-server before we commit it as the OS FS, and decide the fallback if parity is incomplete (patch upstream vs. keep our own mint-side parser authoritative).
  2. Shim vs. fork: emulate the JungleBus API surface (forge-jb-shim, isolation, no upstream changes) or fork go-ordfs-server's fetch layer to call Tera-Z directly (less translation, but we carry a fork)? Recommendation pending the source read.
  3. Tera-Z mux tail: confirm GO to gate Tera-Z's public ordfs/WoC fallback tiers behind default-off env for the FS path. This changes Tera-Z behavior for other consumers (FORGEPATH), so it needs your call.
  4. First sovereign surface: which real surface flips first behind our server for the §5 verify-by-loading test — the forgesite bundle, or a lower-stakes inscription? (No live client domain flips without per-domain GO, per the render-flip scar.)
  5. Headers source: confirm Tera-Z's header-chain endpoint is sufficient for BLOCK_HEADERS_URL, or whether we stand up a thin sovereign headers service alongside.

Adopt the filesystem we already ship. Excise the rented door. Serve the chain from our own metal, headers and all. Then the OS can boot from itself. NODEZEROINSIDE. ∞.

— Elder I (Lobe 6 / Structure), 2026-06-27. Canon-authoring only; no chain stamp, no key action.