From 0d859949c6458ad1ec5cbfb34d413a4f8f8f5bc5 Mon Sep 17 00:00:00 2001 From: Juan Olveira Date: Wed, 15 Apr 2026 23:37:42 +0000 Subject: [PATCH] Add BGP status reporting guidance to provisioning and operations documentation --- CLAUDE.md | 46 +++++++++++++++++++++++++++++++++ docs/contribute-operations.md | 25 ++++++++++++++++++ docs/contribute-provisioning.md | 9 +++++++ 3 files changed, 80 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c11208c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,46 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What This Repo Is + +This is the documentation site for **DoubleZero**, a decentralized high-performance networking protocol built by Malbec Labs. The site is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and deployed to GitHub Pages at `https://docs.malbeclabs.com/`. + +## Commands + +Install dependencies: +```bash +pip install mkdocs-material +``` + +Preview locally with live reload: +```bash +mkdocs serve +``` + +Build static site to `./site/`: +```bash +mkdocs build +``` + +## Deployment + +Merging to `main` triggers the GitHub Actions workflow (`.github/workflows/`) which builds and deploys the site to GitHub Pages automatically. There is no manual deploy step. + +## Site Structure + +Navigation is defined in `mkdocs.yml`. The docs directory is flat — all content pages live directly under `docs/`. The two primary audiences are: + +- **Users** — validators, RPC nodes, and MEV infrastructure that connect to DoubleZero to use the network. Docs cover setup, connection modes (IBRL and multicast), paying fees, and troubleshooting. +- **Contributors** — entities with underutilized fiber optic links and hardware who extend the network. Docs cover hardware requirements, device provisioning, and operations. + +## Key Concepts + +- **DoubleZero Device (DZD)**: Physical switching hardware running the DoubleZero Agent software at each end of a contributor's fiber link. +- **DoubleZero Exchange (DZX)**: Interconnect points (like internet exchanges) where contributor links peer together in major metros. +- **Multicast groups**: Logical groups with publisher/subscriber allowlists for efficient multi-recipient data distribution. Only the DoubleZero Foundation can create groups; owners manage the allowlists. +- **Connection modes**: IBRL (individual routing) and multicast — both require users to first run `doublezero keygen` and complete setup as described in `docs/setup.md`. + +## MkDocs Extensions in Use + +The site uses several pymdownx extensions — notably `pymdownx.superfences` with Mermaid diagram support, `admonition` for warning/note callouts, and `pymdownx.arithmatex` for MathJax. When adding content, use the existing patterns for these (e.g., `??? warning` for collapsible warnings, ` ```mermaid ` fences for diagrams). diff --git a/docs/contribute-operations.md b/docs/contribute-operations.md index 437f1a0..0e2be15 100644 --- a/docs/contribute-operations.md +++ b/docs/contribute-operations.md @@ -291,6 +291,31 @@ doublezero_device_telemetry_agent_peer_discovery_not_found_tunnels{local_device_ - `up` - This is the timeseries metric automatically generated by prometheus if the scrape instance is healthy and reachable. If it is not, either the agent is not reachable or the agent is not running. - `doublezero_device_telemetry_agent_errors_total` with an `error_type` of `submitter_failed_to_write_samples` - This is a signal the telemetry agent can't write samples onchain, which could be do to management connectivity issues on the device. +### BGP Status Reporting + +The telemetry agent can periodically submit each user's BGP session status (Up/Down) onchain. This enables idle user detection and connection diagnostics without relying solely on onchain activation state. + +To enable, add `--bgp-status-enable` to the `doublezero-telemetry` daemon configuration: + +``` +daemon doublezero-telemetry + exec /usr/local/bin/doublezero-telemetry --local-device-pubkey $PUBKEY --env $ENV --keypair $KEY_PAIR --bgp-status-enable + no shutdown +``` + +Optional tuning flags: + +| Flag | Default | Description | +|------|---------|-------------| +| `--bgp-status-interval` | `60s` | Collection and submission frequency | +| `--bgp-status-refresh-interval` | `6h` | Periodic re-submission interval even if status unchanged | +| `--bgp-status-down-grace-period` | `30s` | Minimum duration before reporting a session as Down | + +When metrics are also enabled, the following additional metrics are exposed: + +- `doublezero_bgpstatus_submissions_total` — total onchain submissions by status (Up/Down/Unknown) +- `doublezero_bgpstatus_submission_duration_seconds` — submission latency histogram + --- ## Link Management diff --git a/docs/contribute-provisioning.md b/docs/contribute-provisioning.md index cc6f507..8c1025d 100644 --- a/docs/contribute-provisioning.md +++ b/docs/contribute-provisioning.md @@ -928,6 +928,15 @@ daemon doublezero-telemetry no shut ``` +!!! note "BGP Status Reporting (Optional)" + To enable onchain BGP session status reporting, add `--bgp-status-enable` to the exec command: + ``` + daemon doublezero-telemetry + exec /usr/local/bin/doublezero-telemetry --local-device-pubkey --env mainnet --keypair /mnt/flash/metrics-publisher-keypair.json --bgp-status-enable + no shut + ``` + The submission interval (default `60s`), refresh interval (default `6h`), and Down grace period (default `30s`) can be tuned with `--bgp-status-interval`, `--bgp-status-refresh-interval`, and `--bgp-status-down-grace-period` respectively. + #### Verify it's running ```bash