Drivechain - Observatory
The project directory and repository name are drivechain-observatory.
The existing pulse-* Rust crates/binaries, PULSE_* configuration variables,
database/role names and API fields such as pulse_revision remain compatible.
The rename requires no database migration or evidence rewrite. Historical
fixture labels are retained with their original hashes and protobuf envelopes.
Public Betanet BIP300/301 observatory consuming a fresh monitor contract 9 /
SQL schema 10 dataset, with projection 8. It uses unmodified official enforcer
APIs and independent node evidence; unsupported protocol effects remain unknown.
See SOURCE_CONTRACT.md. Deployment is operated separately.
Architecture
pulse-sync reads a private monitor PostgreSQL through a dedicated read-only
role. Observatory preserves evidence and projections in its own PostgreSQL.
pulse-api reads only that local database and serves REST/OpenAPI/SSE.
The Next.js frontend can run independently on Vercel. Public traffic never
queries the monitor.
Development
Requires Rust 1.96.0 (pinned by rust-toolchain.toml), Node.js 22, npm,
Docker Compose, Python 3 and curl. Install dependencies after cloning:
cargo fetch --locked
npm --prefix apps/web ci
The fixture verifier and OpenAPI generator use Cargo's offline mode after
this initial fetch. Keep both dependency lockfiles in version control.
Copy deploy/.env.example to .env; supply destination credentials, the existing
read-only MONITOR_DATABASE_URL and the explicit PULSE_DATASET_ID from the
source manifest. The example UUID is a fixture, not a production dataset.
Betanet network/checkpoint defaults are validated, not inferred from the
upstream NETWORK_MAINNET enum. Never commit database passwords.
Checks:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
npm --prefix apps/web run generate:api
npm --prefix apps/web run typecheck
npm --prefix apps/web run build
Or use just check when Just is available. Regenerate the API types after any
public DTO change; generate:api exports OpenAPI from Rust without a database.
Run the isolated fixture, migration and behavioral integration suite:
sh scripts/verify-local.sh
Requires Docker Compose, Rust, Python 3 and curl; uses loopback ports
55433/55434/18080/18081. It creates and removes only its own temporary Compose
project. The v9 fixture uses all ten actual monitor migrations and a separate
Observatory database. The exact upstream files are included under fixtures/v9
(and fixtures/upstream), with their license and checksums; no sibling monitor
checkout is needed.
To include Chromium checks against that same fixture, run:
PULSE_BROWSER_TESTS=1 sh scripts/verify-local.sh
This also requires an installed Playwright package and Chromium or Chrome, plus
free loopback port 13000. CI installs only the pinned library and uses the
runner's Chrome; locally, for example:
mkdir -p /tmp/observatory-browser-tools
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm --prefix /tmp/observatory-browser-tools install [email protected]
PULSE_PLAYWRIGHT_MODULE=/tmp/observatory-browser-tools/node_modules/playwright/index.mjs PULSE_BROWSER_EXECUTABLE=/usr/bin/google-chrome PULSE_BROWSER_TESTS=1 sh scripts/verify-local.sh
For an existing installation outside the project, set
PULSE_PLAYWRIGHT_MODULE to its absolute module entrypoint and
PULSE_BROWSER_EXECUTABLE to the Chromium executable. Screenshots are written to
/tmp/drivechain-observatory-browser-official (override with PULSE_BROWSER_ARTIFACTS).
For interactive development, start the two databases using compose.dev.yaml,
run migrations with the admin role, run pulse-sync with the reader/sync roles,
then start pulse-api with the API role. Start the web app with
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080 npm --prefix apps/web run dev.
Each network has its own Observatory backend (database, sync and API). To show
several networks, set NEXT_PUBLIC_NETWORKS to a JSON list of
{"id", "label", "apiBaseUrl"} and optionally NEXT_PUBLIC_DEFAULT_NETWORK
(see apps/web/.env.example). The id is mainnet or betanet, since the copy
states facts about each, and the build fails on any other; label defaults to
the network's full name. The header then shows a selector; the choice is
kept in a cookie, and ?network=<id> in any URL selects a network and remembers
it. Pages of one record (an event, a block, a monitor session or a reading
group) find the network that holds it by themselves, also when the selected
network's API is down.
See deploy/README.md for exact environment and upgrade rules.
Implemented HTTP surface
/health/live, /health/ready/api/v1/meta, /api/v1/status, /api/v1/overview, /api/v1/sidechains/api/v1/coverage, /api/v1/bmm/auctions/api/v1/blocks, /api/v1/blocks/{hash}/api/v1/datasets/{dataset_id}/events/{event_id} and /raw/api/v1/observatory, /api/v1/observations, /api/v1/chain-info/api/v1/sidechains/{slot} and its /activity and /instances/api/v1/sidechains/{slot}/dataset (format=zip, default, or json;
optional from_height/to_height): everything recorded for one slot,
read from one build, as typed CSV tables plus a manifest.json with row
counts, SHA-256 and column meanings. Each table holds up to 250,000 rows
and reports truncation; at most two datasets are built at a time./api/v1/sidechains/{slot}/stats (window_blocks=144, default, or 1008):
figures computed from the same records as the dataset: deposit count, total,
median and recent counts; treasury balance after each deposit and paid
withdrawal; BMM commitment rates over 24/144/1008 blocks and since
activation, streak and longest gap; bid statistics and whether the next
block committed to each bid; each pending withdrawal's votes needed, blocks
left and vote pace; and one row per block of the window. A result is reused
for 15 seconds./api/v1/network (window_blocks=144, default, 1008 or 2016): block
times and intervals, difficulty (block work × 65535 / 2^48), the retarget
period and its estimated adjustment, an estimated hashrate, and the
merged-mining bids seen for each block, from the selected chain's headers./api/v1/sidechain-proposals and /{id}, /api/v1/sidechain-instances and
/{id} and /{id}/ctip, /api/v1/deposits, /api/v1/ctip/history/api/v1/withdrawal-bundles and /{id} (pending bundles and block outcomes),
/api/v1/bundle-attempts and /{id}/api/v1/bmm, /api/v1/bmm/history, /api/v1/bmm/commitments, /api/v1/bmm/confirmed
The web app is a guided learning path: / and /learn/{chapter} teach BIP300/301
one concept at a time, each with live panels and links to the specification;
/sidechains, /sidechains/{slot}, /live, /glossary and /search follow the
same plain-language style. Run/capture details and dataset-scoped block/event
pages remain as the proof behind every value. Lesson claims and their sources are
tracked in apps/web/content/FACT_CHECK.md; the earlier technical routes redirect
to their lessons.
Bids are exact strings in satoshis. API availability, source reachability,
worker health and freshness are separate states. Branch selection reports its
evidence, verified boundary and uncertainty. Development verification uses
isolated fixtures. Live-dataset certification, public deployment, backup/restore,
retention and public-load checks remain operator work.
Branches and observation quality
Projection 8 follows the enforcer's observed tip while independently importing
node headers and raw blocks. A tip reported before its node header keeps the
selected branch until the header arrives. Alternatives and conflicting facts remain visible.
Node/enforcer disagreement blocks joint certification. Chainwork is a lossless
decimal string decoded from node little-endian uint256.
State responses are separate unanchored observations. Matching read-window tips
are not atomic state. Latest invalid/changed occurrences cannot borrow earlier
quality, and every list reports the quality and time of an item's latest read.
An unchanged re-read extends its history row (occurrence count, last read).
Subscription gaps of the global transition stream are listed in /coverage.
Imported evidence is audited against the source; rows that appear behind the
import cursor or change after import stop the sync as incompatible. Charts show points by observation time, with exact values in tables.
There is no local protocol rules engine; voting, expiry and historical BMM
eligibility are not inferred. Fees cover only previously observed matching bids.
Lists paginate with bounded limits and cursors tied to dataset, filters,
projection/build and branch revision. A cursor keeps reading the build it started on, so
re-reads that publish new builds do not interrupt it; a 409 cursor reset
(new block, branch or filters) requires restarting pagination. Evidence links retain their dataset. History time filters default
to occurrence time; explicit block filters exclude unanchored observations.
Exports retain filters and report the 10,000-row truncation boundary.
Use a fresh destination database for the new contract-8 dataset and retain the
old paired binaries/databases. Rebuilds operate only within the same dataset;
they cannot turn old fork evidence into official-source guarantees.
