Skip to content

docs: make README, AGENTS.md and the Docker docs true (SNB-674) - #63

Closed
setavenger wants to merge 2 commits into
integrationfrom
snb-674-docs-true
Closed

setavenger wants to merge 2 commits into
integrationfrom
snb-674-docs-true

Conversation

@setavenger

@setavenger setavenger commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

Implements SNB-674. Part of the friglet cleanup (SNB-661).

Docs only: README.md, AGENTS.md, docs/docker.md and a comment in the Dockerfile. No code changes. Everything describes integration as it is now (a9ff4d6). Facts that open PRs will change are listed at the end.

What was false, and what the docs say now

README

  • blindbit-cli: the example lacked the required --end-height. --p2p-node-addr was documented as host:port, but only ip:port parses. The --state-file default was wrong: it is scanner_state.json in the working directory, not <config dir>/friglet/.... --log-level was missing. The example is now the signet range from AGENTS.md.
  • friglet: --log-level added to the flag table.
  • Logs: the daemon's console log goes to stdout, not stderr. The tray prints the daemon lines it forwards on its stdout too.
  • Tray build comment: a build needs WebKitGTK, GTK, pkg-config and protobuf. It does not need appindicator or rsvg.
  • HTTP API: the docs now say plainly that /height and /subscribe do not answer while scanning is enabled, and that they answer only while scanning is stopped. Status checks use GetStatus on the control socket or an Electrum server.version call. The HTTP API docs stay; whether to remove the API is still open (SNB-668).
  • Docker section: the scanner state is not in /data by default (SNB-635). The curl /height check is replaced by server.version.

docs/docker.md and Dockerfile

  • The Dockerfile comment and the layout table claimed the state lands in /data (via WORKDIR). It does not: friglet rewrites the bare default name to its config-dir path, so the state goes to /home/friglet/.config/friglet/scanner_state-<network>-<id>.json and is lost when the container is recreated. Both now say this and give the workaround: an absolute state_file = "/data/scanner_state.json". That line is now in the minimal config.toml.
  • The curl /height check is replaced by server.version and GetStatus (over the bind-mounted socket). The caveat says the endpoints stay silent even while the daemon is caught up and waiting for blocks, not only "while a scan is actively running".

AGENTS.md (432 → 421 lines)

  • Rust >= 1.85 → >= 1.90. friglet-tray's Tauri crates declare rust-version = "1.90", and friglet uses let-chains (1.88).
  • The package list is split into what a build needs and what release.yml additionally installs for bundling. libxdo-dev is dropped: no crate links it.
  • Changed "blindbit-lib has no in-repo tests": it has unit tests (68 with default features, 78 with serde, which cargo test --workspace turns on). blindbit-cli is fmt- and clippy-clean now, so only blindbit-lib is called out as not clean.
  • Settings tab: it saves with ApplySettings, not SetConfig/SetScanKey.
  • HTTP: replaced "unblock between scan iterations" with the actual behaviour (see verification).
  • Docker: the state is not under /data (same as above).
  • Removed "GetStatus uses tonic to poll the oracle tip", which contradicted the background-poller bullet.
  • Replaced "A server dying … now ends with exit code 1 instead of 0" with the current behaviour: Electrum/control bind failure → exit 1; HTTP bind failure → panic (101, abort in release builds).
  • Removed: the past-fix troubleshooting narrative ("a build that predates this fix…"), the "Verified in this VM" histories, the repeated system-deps list and the "Default state file" section. That section gave the old, non-per-wallet default and is now one bullet in the state-file paragraph. Every still-true instruction is kept: the setup-mode rules, the screenshot recipe, packaging, the Linear rules, the testing rules.
  • Added a short "Checking a running daemon" section with the exact GetStatus, server.version and timeout advice.

Verification

Each command written or corrected was run once, with debug binaries from this branch.

  • blindbit-cli scan --help lists --end-height <END_HEIGHT> as required, --state-file … [default: scanner_state.json] and --log-level … [default: info]. friglet scan --help lists --log-level … [default: info].
  • Without --end-height: error: the following required arguments were not provided: --end-height <END_HEIGHT>.
  • Hostname for --p2p-node-addr: Error: Invalid p2p_node_addr: invalid socket address syntax.
  • The AGENTS.md signet command (oracle signet.oracle.setor.dev, peer 152.53.151.148:38333, 274010..274060) exits 0: scanning blocks start=274010 end=274060 … balance after scan total=0 BTC … scan completed successfully, in 0.8 s with the built binary. The state file holds last_scanned_block_height: 274060, so --end-height is inclusive. A second run logs scanner state loaded last_scanned_height=274060, then scanning blocks start=274010 end=274060 again, which is why the docs say "the given range is scanned either way".
  • friglet daemon on signet, caught up:
    • printf '"GetStatus"\n' | nc -U -w 2 friglet.sock → {"Status":{"scanning":true,"scanned_height":324759,"tip_height":324759,…}}
    • server.version via nc -w 2 → {"jsonrpc":"2.0","id":1,"result":["Friglet","1.4"]}
    • curl -m 10 /height with scanning enabled → curl: (28) Operation timed out after 10002 milliseconds with 0 bytes received
    • After "Stop" → {"height":324759} in 0.05 s. After "Start", it timed out again.
  • Console streams: the daemon wrote 24 lines to stdout and 0 to stderr. The tray under xvfb-run (spawning a stub daemon) wrote 73 lines to stdout, including the forwarded friglet-daemon lines, and 0 to stderr.
  • Docker: an image built from this Dockerfile's runtime stage, with the debug binary copied in instead of the release build:
    • Without state_file, docker logs shows state_file=/home/friglet/.config/friglet/scanner_state-signet-fe70a2fd.json, and ls /data lists only config.toml friglet.log friglet.sock scan.key.
    • With state_file = "/data/scanner_state.json": state_file=/data/scanner_state.json, and scanner_state.json and scanner_state.birthday.json appear in the volume.
    • From the host, GetStatus over the bind-mounted socket and server.version on the published port both answered. curl -m 5 /height timed out.
  • Bind failures: with the HTTP port taken, the process panicked at friglet/src/main.rs:400 (Failed to bind HTTP server … AddrInUse, exit 101). With the Electrum port taken: friglet exited with an error: Electrum server stopped, exit 1.
  • Rust version: cargo metadata gives the highest rust-version in each crate's normal dependency graph. It is 1.90 for friglet-tray (tauri, tauri-runtime-wry, tray-icon, …) and 1.85 for the other crates.
  • Packages: ci: stop installing packages the tests do not need (SNB-675) #50's CI run built and tested the whole workspace without libssl-dev, librsvg2-dev, libayatana-appindicator3-dev and patchelf (check test passed). Cargo.lock has no openssl, rsvg or xdo crate.
  • Pre-push suite: cargo check --workspace --all-targets --all-features 0 warnings; cargo clippy --no-deps -p friglet -p friglet-ipc -p friglet-tray --all-targets -- -D warnings clean; cargo fmt -p friglet -p friglet-ipc -p friglet-tray -- --check clean; cargo test --workspace 254 passed, 1 ignored, 0 failed.

To update when open PRs merge

Left out

  • No code changes: the HTTP endpoints hanging (SNB-668), the Docker state location (SNB-635) and the HTTP bind panic are described, not fixed.
  • The full Docker image (rust:1.97-slim builder, cargo build --release) was not built. Only the runtime stage was, with a debug binary copied in, to keep release builds off a shared disk. The builder stage is unchanged apart from the comment.
  • .cursor/skills not touched.

Independent review follow-up: the Linux GetStatus example now selects the data-directory socket when XDG_RUNTIME_DIR is unset, and honors FRIGLET_CONTROL_SOCKET. README also names the fallback paths. The exact documented command was run against the real daemon with a temporary XDG_DATA_HOME and no XDG_RUNTIME_DIR: GetStatus answered at scanned height 300, and the daemon shut down cleanly. Runtime-directory and explicit-override path selection were checked separately. Workspace check (all targets/features, zero warnings), CI clippy, scoped fmt, and full workspace tests passed again (254 passed, 1 ignored). Independent source review cleared the final docs diff.

The first CI run for this follow-up hit the existing lifecycle fixture race (Text file busy in spawn_failure_surfaces_captured_stderr); PR #45 addresses that race. The CI rerun passed.

setavenger and others added 2 commits October 3, 2026 10:26
Correct what the docs say about integration as it is now; no code changes.

- README: blindbit-cli needs --end-height, takes only ip:port for the P2P
  node, keeps its state in ./scanner_state.json by default and has
  --log-level; friglet's --log-level is documented; console logs go to
  stdout, not stderr; the tray build needs no appindicator/rsvg packages.
- HTTP /height and /subscribe do not answer while scanning is enabled,
  so status checks use the control socket's GetStatus or an Electrum
  server.version call instead of curl /height. The HTTP docs stay.
- Docker: the scanner state is not in /data by default (SNB-635); the docs
  and the Dockerfile comment say so and give the workaround, an absolute
  state_file under /data.
- AGENTS.md: Rust >= 1.90 (Tauri crates declare it; let-chains need 1.88),
  the packages a build actually needs vs. release bundling, blindbit-lib
  has tests, the Settings tab saves with ApplySettings, GetStatus reads a
  background poller, the default state file is per wallet, an HTTP bind
  failure panics. Past-fix narrative and repeated sections removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Use the Linux data-directory socket when XDG_RUNTIME_DIR is unset,
and prefer the explicit environment override. Document the fallback
paths and how to use a configured socket override.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@setavenger

Copy link
Copy Markdown
Owner Author

Merged into integration through #72 on 2026-10-11 (the user live-tested the combined stack first). GitHub's stacked-PR merge rebased the stack, so this PR's commits landed with new IDs and GitHub can't mark it merged itself. The code is identical: integration now has the same tree as the tested branch friglet-deslop-live-test (08bf11d), which contains this PR's head. Closing as merged via #72.

@setavenger setavenger closed this Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant