From 9df1c9ca994a884ab9b1bc29de0f6f4a5eb24de3 Mon Sep 17 00:00:00 2001 From: claude-release Date: Tue, 21 Jul 2026 15:58:28 +0100 Subject: [PATCH] docs(witness-network): fix the operator-usability findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the stranger-operator review of the stand-up path: - /health shape: docs showed {status, roles[], witness}; the binary emits {status, witness_did, first_seen_count, receipt_count}. Fixed run-a-node, monitor-your-node, and the anchor-api /health prose to the real shape. - registry bootstrap: drop the false 'you must have a registry first / it's required' framing — a fresh witness boots empty and grows by receipting; the registry is needed to *anchor for* a party, not to *start*. Give a real peer URL (network.auths.dev) instead of the /path/to/registry placeholder. - helm example: add the required --set registry.url. - CLI reference: add the missing 'registry' role row. - prove-conformance: warn that the first xtask run cold-compiles for minutes. - retire auths.dev/network links → explorer.auths.dev (get-listed, monitor-your-node, choose-your-witnesses). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01NFugwwLVfYMGPwoP7fJKDJ Auths-Scope: sign_commit Auths-Id: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd Auths-Device: did:keri:EO1cBsYoV5izKvdIL6TstN5TOQl1hYN3WnhtAOh1lwAp Auths-Anchor-Seq: 13 --- .../operators/deploy-for-real.md | 1 + .../witness-network/operators/get-listed.md | 2 +- .../operators/monitor-your-node.md | 15 ++++++------- .../operators/prove-conformance.md | 5 ++++- .../witness-network/operators/run-a-node.md | 21 ++++++++++++------- .../witness-network/reference/anchor-api.md | 4 +++- .../reference/witness-node-cli.md | 1 + .../users/choose-your-witnesses.md | 2 +- 8 files changed, 33 insertions(+), 18 deletions(-) diff --git a/content/docs/witness-network/operators/deploy-for-real.md b/content/docs/witness-network/operators/deploy-for-real.md index 542fa07..258a687 100644 --- a/content/docs/witness-network/operators/deploy-for-real.md +++ b/content/docs/witness-network/operators/deploy-for-real.md @@ -15,6 +15,7 @@ The same templates the first-party quorum runs ship in `deploy/witness/`. helm install acme-w1 ./deploy/witness/helm \ --set image.digest=sha256: \ --set seed.existingSecret=acme-w1-seed \ + --set registry.url=https://network.auths.dev \ --set anchorStore.size=10Gi ``` diff --git a/content/docs/witness-network/operators/get-listed.md b/content/docs/witness-network/operators/get-listed.md index ee20140..fc0333d 100644 --- a/content/docs/witness-network/operators/get-listed.md +++ b/content/docs/witness-network/operators/get-listed.md @@ -7,7 +7,7 @@ order: 6 lastReviewed: "2026-07-20" --- -The [public directory](https://auths.dev/network) lists conformant witnesses with +The [public directory](https://explorer.auths.dev) lists conformant witnesses with the facts principals pick sets by. Listing has one bar: pass the harness. ## Submit diff --git a/content/docs/witness-network/operators/monitor-your-node.md b/content/docs/witness-network/operators/monitor-your-node.md index 9f208bd..ccd406d 100644 --- a/content/docs/witness-network/operators/monitor-your-node.md +++ b/content/docs/witness-network/operators/monitor-your-node.md @@ -15,8 +15,8 @@ curl -s localhost:3333/build ``` ```output -{"status":"ok","roles":["anchor","kel","cosign"],"witness":"acme-w1"} -{"version":"0.1.12","running_digest":"sha256:…","attestation":{…}} +{"status":"ok","witness_did":"did:key:z6Mk…","first_seen_count":0,"receipt_count":0} +{"version":"0.1.16","running_digest":"sha256:…","attestation":{…}} ``` `/build` is the node's **signed** statement of which binary it runs — checked @@ -24,11 +24,12 @@ against the digest you deployed. ## The console -Open your node in the network console at -[auths.dev/network](https://auths.dev/network) → **node**. It reads `/health` -and `/build` and re-verifies the signed payloads **in your browser** with the -published WASM verifier. The node is treated as an untrusted data source; -trust comes from the in-browser check, never the connection. +Open your node in the explorer at +[explorer.auths.dev](https://explorer.auths.dev) — point it at your own node +with `?witness=` on any member page. It reads the public GETs and +re-verifies the signed payloads **in your browser** with the published WASM +verifier. The node is treated as an untrusted data source; trust comes from the +in-browser check, never the connection. ## Container healthcheck diff --git a/content/docs/witness-network/operators/prove-conformance.md b/content/docs/witness-network/operators/prove-conformance.md index fe45eb2..d3406b9 100644 --- a/content/docs/witness-network/operators/prove-conformance.md +++ b/content/docs/witness-network/operators/prove-conformance.md @@ -13,8 +13,11 @@ Drive your live node through the published suite: cargo xtask witness-conformance --url http://127.0.0.1:3333 ``` +The first run compiles the `xtask` crate — expect a few minutes of Rust build +before any output; subsequent runs are instant. + ```output -witness-conformance: live endpoint http://127.0.0.1:3333 passed 4/4 transport checks +witness-conformance: live endpoint http://127.0.0.1:3333 passed 4/4 transport checks — certified did:key:z6Mk… ``` Emit the machine-readable vectors to drive your own harness (or a node you built diff --git a/content/docs/witness-network/operators/run-a-node.md b/content/docs/witness-network/operators/run-a-node.md index 368c2d5..db2c4b0 100644 --- a/content/docs/witness-network/operators/run-a-node.md +++ b/content/docs/witness-network/operators/run-a-node.md @@ -7,16 +7,19 @@ order: 1 lastReviewed: "2026-07-20" --- -**Before you start:** Docker, and a local copy of the parties' public identity -registry (see [Keep the registry synced](/witness-network/operators/keep-the-registry-synced)). +**Before you start:** just Docker. A fresh witness boots on an empty registry +and grows as it receipts events — you only need the parties' registry once you +want to *anchor for* them (see [Keep the registry synced](/witness-network/operators/keep-the-registry-synced)). ```bash git clone https://github.com/auths-dev/auths cd auths/deploy/witness export WITNESS_SEED=$(openssl rand -hex 32) # this IS your identity — keep it -export WITNESS_REGISTRY=/path/to/registry # required; mounted read-only export WITNESS_NAME=acme-w1 +# Optional — where to keep the parties' registry (defaults to ./registry beside +# the compose file). Sync it before you expect to anchor for those parties. +export WITNESS_REGISTRY=./registry docker compose up -d ``` @@ -28,7 +31,7 @@ curl -s localhost:3333/health ``` ```output -{"status":"ok","roles":["anchor","kel","cosign"],"witness":"acme-w1"} +{"status":"ok","witness_did":"did:key:z6Mk…","first_seen_count":0,"receipt_count":0} ``` Your **member key** is printed at first boot — that's what principals add to @@ -64,8 +67,12 @@ witness-node serve --roles anchor,kel,cosign --bind 0.0.0.0:3333 \ **If it fails:** -- *`set WITNESS_REGISTRY…`* — compose requires it; there is no default. -- *a role refuses to start* — that role's required config is missing. The node - fails closed with a named error rather than serving a half-configured witness. +- *anchors 404 though `/health` is green* — the node is up but hasn't synced the + parties' registry, so it can't resolve their keys yet. Sync it (see [Keep the + registry synced](/witness-network/operators/keep-the-registry-synced)); a + fresh node is "up" before it's "useful" for a given party. +- *a role refuses to start* — a role whose config is genuinely missing fails + closed with a named error (e.g. the `registry` role needs the `git` binary on + PATH), rather than serving a half-configured witness. **Next:** [Deploy for real](/witness-network/operators/deploy-for-real). diff --git a/content/docs/witness-network/reference/anchor-api.md b/content/docs/witness-network/reference/anchor-api.md index 7fbd440..cacee0a 100644 --- a/content/docs/witness-network/reference/anchor-api.md +++ b/content/docs/witness-network/reference/anchor-api.md @@ -47,7 +47,9 @@ curl https://w1.example.com/v1/anchor/ ## `GET /health` -Liveness. `200` with the served roles and witness name. +Liveness. `200` with `{status, witness_did, first_seen_count, receipt_count}` +(the KEL role's shape; an anchor-only node returns `{up, roles, witness_name}`). +`witness_did` is the node's member key — the value principals add to their set. ## `GET /build` diff --git a/content/docs/witness-network/reference/witness-node-cli.md b/content/docs/witness-network/reference/witness-node-cli.md index 9cbd409..5327bf9 100644 --- a/content/docs/witness-network/reference/witness-node-cli.md +++ b/content/docs/witness-network/reference/witness-node-cli.md @@ -48,6 +48,7 @@ distroless image where no HTTP tooling exists. | `anchor` | Spend-anchor acceptance and reads | `--data-dir`, `--registry` | | `kel` | Receipt witnessing for key histories | `--data-dir` | | `cosign` | Transparency-log checkpoint cosigning | `--data-dir` | +| `registry` | Serve the held `refs/auths/*` read-only over git smart-HTTP (the node is its own resolution surface) | `--registry`, `git` on PATH | All roles share one identity seed, one data dir, and one hardening envelope. A role whose requirements aren't configured **refuses to start with a named diff --git a/content/docs/witness-network/users/choose-your-witnesses.md b/content/docs/witness-network/users/choose-your-witnesses.md index 1aa8969..54c7058 100644 --- a/content/docs/witness-network/users/choose-your-witnesses.md +++ b/content/docs/witness-network/users/choose-your-witnesses.md @@ -32,7 +32,7 @@ strongest witness in your set is one your counterparty or regulator runs. ## Find operators -- **[The public directory](https://auths.dev/network)** — conformant witnesses +- **[The public directory](https://explorer.auths.dev)** — conformant witnesses with their operator facts and live status. - **[Run one yourself](/witness-network/operators/run-a-node)** — a fine first member, a bad only member.