overlay-bridge

README

overlay-bridge

Part of the BSV Layered Multicast open-source project. See the main repository for the full architecture, design docs, and BRC specifications.

A landing-tier bridge that runs an unmodified overlay services engine with a multicast delivery fabric as its transport. Objects delivered by the BEEF object plane enter the engine through the submit interface it already serves, publication goes out once and the network fans it out to every subscribed host, and the block-header lane feeds the chain tracker the engine verifies against. The design is Paper 008, The overlay bridge (link under Papers).

   delivery (down)
   fabric ══push══▶ overlay-bridge
       object lane ─▶ feed ─▶ POST /submit (x-topics: matched) ─▶ engine
       header lane ─▶ header store ◀── chain tracker reads ──── engine

   publication (up)
   client ─▶ facade (POST /submit) ─┬─▶ engine  (local admittance, real STEAK)
                                    └─▶ up-tunnel ══▶ fabric ══▶ every subscribed host

   engine: propagation switched off in configuration, so it admits and
           indexes but never re-submits to another host

It is the application-tier sibling of arcade-bridge and teranode-bridge. Where those bridges front the broadcaster tier and a mining Teranode cluster, this one fronts an overlay host: a delivery consumer of the application tier, never a miner, and nothing here carries miner entitlements. The shared landing-tier machinery (lane termination, byte-order discipline, redial and failover across the tunnel's primary and standby paths) is imported from teranode-bridge's public packages, never forked.

Documentation

• Architecture: the feed, the header store, the facade and the loop guard, and what each holds
• Configuration: every flag, defaults, the modes, and the startup checks that refuse a half-configured host
• The header feeder: the header lane as a chain tracker, the two read shapes, anchoring and re-anchoring
• SPV verification: verify delivered objects in Go (-verify off|shadow|enforce), and the loopback trust marker that lets the engine skip its script checks
• The shadow engine: feed a second engine every object the primary is fed (-shadow-engine), compare the two answers per topic, and never let the shadow slow the primary
• Deliver once: one delivery slot per landing site, and how a site that runs several bridges fans out locally
• Metrics reference: every overlay_bridge_* series, its labels and meaning
• Contracts and open items: what has been proven against the released engines, and what is not yet settled
• BRC-148 and BRC-149: the BEEF object plane and the delivery record the object lane carries
• BRC-135: the block-header frame the header lane carries
• BRC-22 and BRC-24: the engine's submit and lookup interfaces

Requirements

• Go 1.26 or later
• A released overlay services engine reachable as a bare origin (ts-stack or go-overlay-services), with its propagation switched off in configuration (no advertiser, or an empty SLAP tracker list) and its chain tracker pointed at the bridge
• A provisioned delivery slot carrying the object lane and the header lane (-mode sink needs only the slot)
• A header anchor serving /v1/tip, /v1/root/{height} and /v1/header/{hash}; another overlay-bridge serves all three, so a second host can anchor on the first

Build

go build ./cmd/overlay-bridge
make verify        # what CI runs: formatting, vet, tests under -race, licence freshness

Quick start

# Sink: terminate the lanes, count, discard. Burn in a delivery slot before
# an engine exists.
./overlay-bridge -mode sink

# Feed with SPV in the bridge, shadowing the engine's own verification.
./overlay-bridge -mode feed -engine http://127.0.0.1:8080 -topics tm_example \
  -header-anchor http://127.0.0.1:9188 -verify shadow

Feed and full (facade plus publish) examples, every flag and the default ports are in docs/configuration.md.

Layout

.
├── cmd/overlay-bridge/  # entrypoint: flags, modes, wiring, the startup checks
├── feed/                # object lane -> delivery records -> engine submits
├── headers/             # header lane -> proof-of-work-checked chain -> chain-tracker API
├── facade/              # the engine's submit interface, forwarded then published
├── uptunnel/            # one publication per submission to the fabric ingress, with failover
├── guard/               # the bounded loop guard on object identity
├── topics/              # elected topic names and their identifiers
├── pkg/spv/             # SPV verifier and trust marker, reusable by a Go overlay engine
├── docs/                # architecture, configuration, contracts, deliver-once, header-feeder, references/
├── Dockerfile
├── Makefile
└── .github/workflows/{ci,codeql,image-publish,release,vuln}.yml

Observability

Prometheus series are overlay_bridge_* on -metrics-addr (default [::]:9179); see the metrics reference.

Status

Released (see the releases) and running in a lab deployment: the bridge lands objects into a released engine, serves headers from its own BRC-135 lane, and both reference hosts admit object-for-object. What has been proven against the released engines, and what remains open, is in docs/contracts.md.

Releases and notes live on GitHub Releases; there is no CHANGELOG.

Papers

• The overlay bridge: an unmodified engine on the object plane (Lightweb Inc., Paper 008): https://1bsv.net/papers/overlay-bridge.pdf
• The overlay object plane: publish BEEF once, and every overlay hears (Lightweb Inc., Paper 006): https://1bsv.net/papers/overlay-object-plane.pdf
• Arcade v2 on a multicast delivery fabric (Lightweb Inc., Paper 007), for the sibling bridge: https://1bsv.net/papers/arcade-on-the-fabric.pdf

Licence

Apache-2.0 (see LICENSE). Third-party dependencies and the attribution their licences require are in NOTICE. There is no licence check in this software, no call home, and no metering of any kind inside it.