v1.0.0-beta.2 · experimental

gonkactl-trace

Fast on-chain event tracing & triage for Gonka network nodes and testbeds.

Turn a range of blocks into a local, interactive report. Follow consensus evidence, inspect anomalies, and keep the sources behind every finding.

Download and verify the installer

Use a trusted operating-system shell (/bin/sh) on Linux/macOS. These commands use only administrator-managed /usr/bin and /bin; stop if either directory or its tools can be modified by untrusted users. Do not source the installer or use a shell with untrusted startup configuration.

(
  set -eu
  PATH=/usr/bin:/bin
  export PATH
  trace_dir=$(mktemp -d /tmp/gonka-trace.XXXXXXXX)
  curl -fLsS https://gonka-dev.net/trace/install.sh -o "$trace_dir/install.sh"
  (
    cd "$trace_dir"
    printf '%s  %s\n' '2d46a7a4ade3491e5f8ff65bdfccf458155074d8c3f54f8d9c1cfe03b39c899f' install.sh | { if command -v sha256sum >/dev/null 2>&1; then sha256sum -c -; else shasum -a 256 -c -; fi; }
  )
  printf 'Verified installer: %s\n' "$trace_dir/install.sh"
)

Temporary files use the OS-managed, root-owned sticky /tmp (including its resolved parent on macOS), never inherited TMPDIR. Stop if that root is not trusted. Keep the private temporary directory intact and recheck the digest immediately before executing the installer or copying the skill files.

Linux & macOS. Inspect the verified file at the printed absolute path. Run /bin/sh /printed/path/install.sh --dry-run to preview, then /bin/sh /printed/path/install.sh only after approving the destination. The installer binds the release manifest to a reviewed digest and verifies the archive before installing into ~/.local/bin. No sudo or profile edits. Set GONKACTL_INSTALL_DIR to choose a directory. Installer SHA-256: 2d46a7a4ade3491e5f8ff65bdfccf458155074d8c3f54f8d9c1cfe03b39c899f. Windows: download the ZIP below.

Trace on-chain evidence

Collect recent or historical blocks and inspect events, signatures, validator membership and available application responses. Bounded snapshots, not continuous real-time monitoring.

Investigate the unexpected

Analyze emergency states and anomalies across distributed testbeds. Provenance and explicit gaps separate observed evidence from unknown causes.

Check your test runs

Inspect on-chain outcomes from E2E runs, compare retained evidence, and rebuild reports offline for diagnostics. Test pass/fail remains your harness's decision.

From blocks to a report

Replace the placeholder below with the approved absolute path of the installed binary. Before execution, verify its digest against the binary extracted from the verified official archive and check file/parent ownership and permissions; reject untrusted-writable paths. Do not select the binary through PATH or trust its own version text as provenance.

/approved/absolute/path/gonkactl-trace --version
/approved/absolute/path/gonkactl-trace --help
/approved/absolute/path/gonkactl-trace report mainnet HEAD~10
# Or: /approved/absolute/path/gonkactl-trace report devnet HEAD~10

Open the printed HTML path in your browser. Collection reads public endpoints; reports and retained data stay local. Review evidence before sharing. Signature fields are not cryptographically verified.

Investigate with your agent

Use the gonka-validator-diagnosis skill to investigate why a participant lost validator membership or failed PoC admission. The agent correlates a completed stage, votes and the effective validator set, and separates the chain decision from an underlying cause that may still be unknown.

Prepare skill v1.0.0 from its verified release archive, then copy the reviewed folder into your agent's configured skill directory. No registry installer or Node.js/npm is required. Linux/macOS verification uses curl, unzip and sha256sum or shasum:

(
  set -eu
  PATH=/usr/bin:/bin
  export PATH
  skill_dir=$(mktemp -d /tmp/gonka-skill.XXXXXXXX)
  curl -fLsS https://github.com/paranjko/external-test-lab/releases/download/gonka-validator-diagnosis-v1.0.0/gonka-validator-diagnosis_1.0.0.zip -o "$skill_dir/skill.zip"
  (
    cd "$skill_dir"
    printf '%s  %s\n' 'b3f4166858f3795bd22c4b6d96473b102b7e65d957c2d73bd789d4f9e09a083a' skill.zip | { if command -v sha256sum >/dev/null 2>&1; then sha256sum -c -; else shasum -a 256 -c -; fi; }
    unzip -q skill.zip
  )
  printf 'Verified skill folder: %s\n' "$skill_dir/gonka-validator-diagnosis"
)

The archive is checked before extraction. Review the printed folder, then manually copy it into your agent's skill directory; do not overwrite an existing skill without approval. The temporary source folder is retained for inspection. This does not install the trace binary; use the official installer above when you authorize local installation. Release, archive and usage guide ↗

Windows or manual setup: download the ZIP from that release, verify its SHA-256 is b3f4166858f3795bd22c4b6d96473b102b7e65d957c2d73bd789d4f9e09a083a (PowerShell: Get-FileHash -Algorithm SHA256), then extract into a new directory and follow the included README. The archive includes a per-file SHA256SUMS manifest. A checksum binds these reviewed bytes; it is not a publisher signature.

Then ask your agent, replacing the placeholders with your incident:

Use gonka-validator-diagnosis to explain why participant ADDRESS stopped
validating on NETWORK around HEIGHT or UTC TIME. Start with public evidence;
do not change the node. Separate the membership decision from its underlying
cause, cite the evidence, and identify any missing records.

Read-only diagnosis, not repair or a guaranteed root cause. No node restart, governance action or automatic upload. Reports stay local during public CLI collection, but a hosted agent sends context to its provider: use only public or approved, scrubbed evidence. Never attach credentials or unrestricted logs.

Download v1.0.0-beta.2

Latest trace beta. Choose your operating system and CPU.

System	CPU	Archive
Linux	x86-64	tar.gz
Linux	ARM64	tar.gz
macOS	Intel	tar.gz
macOS	Apple Silicon	tar.gz
Windows	x86-64	ZIP

SHA256SUMS · Release notes. Before using this manifest for manual or Windows verification, check its SHA-256 is 115eecd486f26e6720cca82d4852b96accdd8bda618877e647e5591f96ffa9b8; then verify the selected archive. These pins bind reviewed bytes, not a publisher signature. Binaries are unsigned. The optional full Perfetto viewer is a separate source build.