Skip to content

Simple System Clock Witnessing

Use system mode for Python system time with unspecified accuracy. No clock monitor, health file, extra volume, systemd service, or NTP configuration change is needed. Existing host NTP can continue normally, but Spurline does not check it or claim synchronization. Witnessing remains disabled by default, and existing deployments do not switch modes automatically.

Configure without enabling yet

In the relay's .env:

SPURLINE_WITNESS_ENABLED=false
SPURLINE_WITNESS_CLOCK_MODE=system

SPURLINE_WITNESS_CLOCK_FILE is ignored in system mode. Use the normal Compose file. If you added deploy/compose.clock.yaml to COMPOSE_FILE, remove only that overlay while preserving other custom files. If you installed the optional monitor, you can stop it without changing host NTP:

sudo systemctl disable --now spurline-clock-monitor.timer
sudo systemctl stop spurline-clock-monitor.service

Skip those commands if you never installed it. They leave installed files in place. Recreate the relay after removing a monitor bind mount.

Approve the system clock policy

Your existing service commissioning remains valid. Review System Clock Witness Policy Version 1. On the relay host, copy its exact bytes into the existing data directory. For the /mnt/bitcoin/spurline deployment:

sudo install -m 0644 docs/policies/system-clock-witness-v1.md /mnt/bitcoin/spurline/witness-policy.txt
docker compose exec -T spurline spurline service show > commissioning-state.json
docker compose exec -T spurline spurline service witness request \
  --policy /data/witness-policy.txt --valid-for 2592000 \
  --kind 1415 --kind 1416 > witness-request.json

Adjust the host path to your actual SPURLINE_DATA_DIR. Copy the two JSON files and exact policy to the trusted operator workstation. From its updated Spurline checkout, sign using the independently confirmed relay identity:

poetry run spurline operator sign-witness \
  --file witness-request.json \
  --commissioning-file commissioning-state.json \
  --policy witness-policy.txt \
  --service-npub EXPECTED_SERVICE_NPUB_OR_HEX > witness-authorization.json

The operator key is prompted privately. Copy the successful signed output back to the relay host and import it:

docker compose exec -T spurline spurline service witness authorize < witness-authorization.json
docker compose exec -T spurline spurline service witness verify
docker compose exec -T spurline spurline service publish --relay ws://127.0.0.1:8080
docker compose exec -T spurline spurline service witness publish --relay ws://127.0.0.1:8080

These commands assume no previous witness grant. Existing grants need the lifecycle renewal process, not deletion of history. The offline signer currently supports initial grants only. A pending unsigned request can be replaced before approval using the intended policy.

The exact policy line Spurline-Clock-Profile: system-v1 permits system mode. Other clock-policy markers cannot be combined with it. Changing the mode alone cannot weaken an approved monitored policy. The policy's 60-second maximum issuance delay remains enforced; its prose still requires human review.

Enable and check

Set SPURLINE_WITNESS_ENABLED=true, keeping SPURLINE_WITNESS_CLOCK_MODE=system, then rebuild/recreate the relay. /info reports clock_mode: "system", receipt_version: 3, and clock_health_required: false. That last field means no external health file is required, not that clock-jump checks are disabled.

Submit a fresh signed kind 1415 or 1416 test event and query kind 1418 by the subject's e tag. Expect schema version 3 and:

{"clock_basis":"system-clock","clock_accuracy":"unspecified","clock_uncertainty_ms":null}

Version 3 retains the version 2 fields and checks except for schema_version: 3, basis system-clock, and tag ["t","spurline-observation-receipt-v3"]. The verifier requires these exact values and rejects an NTP basis in v3. Versions 1 and 2 are unchanged. Old clients must reject unsupported versions rather than assume monitored time.

Signatures authenticate the relay's statement, not clock correctness. Accuracy, UTC deadlines and cross-relay ordering remain unverified. Authorization, suspension, receipt deduplication, restart recovery and clock-jump detection remain active. No new database migration is required. Mode changes never rewrite old receipts or silently convert pending jobs.