diff --git a/AGENTS.md b/AGENTS.md index 0f4a258..f1dc705 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,334 +1,113 @@ -# AGENTS.md — GhostNode Tools - -## Purpose - -GhostNode Tools is an open-source toolkit for monitoring and analyzing Ghost -blockchain nodes, staking activity, and operational health. - -This document provides guidance for AI coding assistants and autonomous agents -working with the repository or assisting users with installation and -diagnostics. - -Safety, transparency, and reproducibility take priority over automation speed. - -These instructions are project guidance, not a security boundary. Agents must -also follow their operating environment's permissions and the user's explicit -authorization. - -## 1. Project Principles - -- Keep GhostNode Tools focused on monitoring, diagnostics, and read-only - intelligence. -- Preserve compatibility with supported Ghost Core installations. -- Prefer small, auditable changes over broad refactoring. -- Maintain English-language documentation and user-facing messages. -- Avoid unnecessary dependencies, network requests, and background services. -- Never assume a development environment is safe for production operations. -- Do not silently change configuration, permissions, or system state. -- The current public release line is v0.3.2. Verify source, tag, and package - metadata independently because the CLI/package version may lag the release - tag. - -## 2. Wallet and Blockchain Safety - -GhostNode Tools must never require users to disclose: - -- Wallet private keys. -- Recovery seeds or mnemonic phrases. -- Wallet unlock passphrases. -- Wallet backup files. -- Unrestricted RPC credentials in chat messages, logs, or issue reports. - -Agents must not: - -- Send or transfer cryptocurrency. -- Sign transactions. -- Unlock wallets. -- Export private keys. -- Import or replace wallets. -- Modify staking settings without explicit authorization. -- Delete or overwrite blockchain or wallet data. -- Run wallet-modifying RPC commands. - -The application is intended to use a restricted, read-only RPC method allowlist. - -**Important:** Application-level RPC restrictions do not necessarily restrict -the permissions granted to Ghost Core RPC credentials. Treat those credentials -as sensitive and potentially privileged. - -## 3. RPC and Network Security - -- Prefer local Ghost Core RPC connections. -- Never expose Ghost Core RPC directly to the public Internet. -- Never print, commit, or transmit RPC authentication secrets. -- Do not bypass the application's RPC allowlist. -- Do not introduce unrestricted RPC execution interfaces. -- Keep the dashboard bound to `127.0.0.1` by default. -- Optional LAN mode may add exactly one explicitly assigned private IPv4 - address. Wildcard, public, multicast, loopback, link-local, and IPv6 - bindings are not supported. -- Use `token_required` LAN authentication by default. `trusted_lan` is an - explicit operator choice and does not make read-only data private from other - reachable LAN clients. -- Never bind the dashboard to `0.0.0.0` or an unrestricted IPv6 interface. -- Prefer SSH tunneling for authorized remote dashboard access. -- Do not add external telemetry or outbound transmission of node data without - explicit approval and a security review. - -Do not treat localhost binding as authentication. Other processes with access -to the local host may still be able to reach the dashboard. - -## 4. Repository Architecture - -Before modifying code, inspect the current repository structure and relevant -modules. - -The project includes: - -- Ghost Core RPC collection components. -- Node and staking intelligence processing. -- Local data storage and read-only views. -- Command-line utilities. -- A dashboard that is localhost-only by default, with validated optional - single-address LAN mode. -- Automated tests and installation documentation. - -Agents must verify actual module paths and interfaces from the repository before -making changes. - -Do not invent APIs, configuration keys, commands, or database schemas. - -## 5. Installation Assistance - -When helping users install GhostNode Tools: - -1. Verify the operating system and Python version. -2. Follow the repository's current `docs/INSTALLATION.md` and `INSTALL.md`. -3. Use an isolated Python virtual environment. -4. Prefer pinned dependencies and hash verification. -5. Keep application files separate from Ghost Core wallet data. -6. Never ask users to upload wallet files or RPC credentials. -7. Explain security implications before recommending configuration changes. -8. Use localhost-only dashboard access unless an explicitly reviewed, - authenticated LAN mode is required. -9. Verify installation using documented diagnostics. -10. Explain how to stop or uninstall the application without affecting Ghost - Core. - -The v0.3.2 release documentation targets Debian 12 or supported Ubuntu with -Python 3.11. Agents must not assume that other environments have been tested. - -The public v0.3.2 tag may still expose the older `0.3.1` Python package/CLI -version string. Report this metadata limitation instead of silently changing -version claims or release contents. - -Do not automatically install packages, change firewall rules, create services, -or modify system configuration without appropriate user authorization. - -## 6. Development Workflow - -Before making changes: - -- Inspect `README.md`, `docs/INSTALLATION.md`, `INSTALL.md`, and relevant source - files. -- Check the current Git branch and working tree. -- Identify whether the environment contains production services or real wallet - data. -- Define the smallest reasonable change. -- Preserve unrelated user modifications. - -During development: - -- Prefer deterministic, testable implementations. -- Keep security-sensitive operations explicit. -- Preserve the existing RPC allowlist. -- Use synthetic data in tests. -- Avoid unnecessary dependencies. -- Do not introduce hidden background activity. -- Never silently modify production configuration. - -After making changes: - -- Run relevant automated tests. -- Check Python syntax and package integrity. -- Review changes for accidental secrets. -- Verify documentation consistency. -- Report changed files and test results. -- Clearly identify unverified assumptions. - -Do not claim tests passed unless they were actually executed. - -## 7. Testing Rules - -Use isolated test environments wherever possible. - -Tests must not: - -- Access real wallets. -- Submit blockchain transactions. -- Unlock wallets. -- Change production services. -- Modify production databases. -- Depend on real RPC credentials. -- Expose sensitive information in logs. - -Prefer mocked RPC responses, synthetic fixtures, and temporary databases. - -Before publishing changes, run the applicable test suite and release validation -checks. - -For reward-related changes, include tests for exact atomic values, Ghost PoS -identification, 101-confirmation maturity, idempotency, reorg handling, and -the rule that PARTIAL, UNKNOWN, UNVERIFIED, or ORPHANED data cannot increase -confirmed income. - -## 8. Data and Privacy - -Node information and staking statistics may reveal operational or financial -details. - -Agents must: - -- Minimize unnecessary data collection. -- Avoid exposing wallet addresses or transaction identifiers in public logs. -- Sanitize errors before displaying them. -- Avoid uploading local databases to external services. -- Never include real user data in examples or test fixtures without explicit - authorization. -- Treat diagnostic output as potentially sensitive. - -The public donation address in the README is intentionally published. Its -presence does not authorize access to the owner's wallet. - -The private Donations observer and dashboard wrapper are deployment-local -extensions. They must remain outside public source exports, release archives, -and pull requests. - -## 9. Documentation Standards - -All public-facing project materials must use clear English. - -This includes: - -- README and installation guides. -- Security documentation. -- CLI help and error messages. -- Dashboard labels. -- Release notes. -- Contributor guidance. -- Agent instructions. - -Documentation must distinguish between implemented features, experimental -capabilities, and future plans. - -Do not present proposed features as available functionality. - -Document the distinction between wallet-owned staking rewards and network-wide -block reward components. With `txindex` disabled, unavailable network-wide -components must remain NULL/UNKNOWN rather than being inferred. - -## 10. Release and GitHub Operations - -Agents must not independently: - -- Create public repositories. -- Publish GitHub Releases. -- Push code to remote repositories. -- Force-push branches. -- Rewrite public Git history. -- Publish release assets. -- Change repository visibility. - -These actions require explicit authorization from the repository owner. - -Before an authorized release, verify: - -- Git commit identity. -- Clean working tree. -- Release archive integrity. -- Dependency lockfile. -- Installation instructions. -- Checksums. -- Secret scanning. -- Test results. -- Consistency between published source and release assets. - -Never publish private wallet-monitoring functionality or production-specific -files accidentally. - -## 11. Production Change Policy - -Read-only inspection is preferred. - -Agents must obtain explicit authorization before: - -- Restarting Ghost Core. -- Changing systemd services. -- Modifying cron jobs. -- Changing firewall rules. -- Altering production configuration. -- Writing to production databases. -- Changing staking settings. -- Installing persistent background services. - -Never treat a request for diagnostics as permission to make production changes. - -For high-risk or irreversible operations, explain the impact and recovery -procedure before proceeding. - -When production changes are explicitly authorized, preserve the current -runtime, private configuration, SQLite database, locks, logs, backups, and -private Donations integration separately from public application source. Back -up affected files and database state before a cutover, verify one collector -instance, and keep a tested rollback path. Documentation-only changes do not -require a service restart. - -## 12. Current Operational Boundaries - -- The public application is read-only with respect to Ghost Core and wallets; - it does not create, unlock, encrypt, restore, or transact with wallets. -- Collector writes are limited to the configured local SQLite intelligence - database and must preserve atomicity, idempotency, and reorg handling. -- Production-only services or wrappers must never be inferred from the public - checkout; inspect their effective systemd unit and private configuration. - -## 13. Agent Communication - -Agents should communicate clearly and distinguish: - -- Observed facts. -- Test results. -- Assumptions. -- Recommendations. -- Unverified risks. - -When an action cannot be completed safely, explain the blocker rather than -bypassing security controls. - -When reporting work, include: - -- What was inspected. -- What was changed. -- What was tested. -- What remains uncertain. -- Whether production systems were affected. - -The preferred behavior is to stop and ask for authorization rather than guess -when wallet security, production integrity, or public publication is at stake. - -## 13. Scope of Agent Autonomy - -Agents may perform routine repository inspection, documentation review, code -analysis, and isolated testing within their granted permissions. - -Agents may propose improvements and prepare changes for review. - -Agents must not interpret this document as blanket permission to execute system -modifications, access wallets, or publish code. - -The user's explicit instructions and the execution environment's security -restrictions always apply. - ---- - -**GhostNode Tools — Read-only by design. Security-conscious by default.** +# AGENTS.md - GhostNode Tools + +## Scope + +GhostNode Tools is a read-only monitoring and staking-intelligence toolkit. +Keep changes small, auditable, reproducible, and in English. The repository is +the public source of truth; private deployments and data stay outside it. + +Before work, inspect `git status`, the relevant source and test files, and the +authoritative document linked below. Preserve unrelated worktree changes. + +## Safety boundaries + +- Never disclose or commit wallet private keys, seeds, unlock passphrases, + wallet backups, RPC passwords, Ghost Core cookies, bearer tokens, or private + environment files. +- Never send or sign transactions, unlock wallets, export or import keys, + change staking settings, modify wallet data, or bypass the read-only RPC + allowlist. +- Treat application-level RPC restrictions as distinct from the privileges of + supplied Ghost Core credentials. Prefer local RPC access. +- Keep the dashboard at `127.0.0.1` unless an explicitly reviewed private LAN + address and `token_required` configuration are involved. Never introduce + wildcard, public, multicast, loopback-as-LAN, or IPv6 bindings. +- Do not change production services, firewall rules, cron jobs, production + SQLite databases, Ghost Core configuration, systemd units, or staking state + unless the user has explicitly authorized that operation. +- Do not silently change permissions or system state. Never publish releases, + tags, repositories, or credentials. +- Keep private Donations observers, dashboard wrappers, production units, + logs, backups, wallet data, and monitoring extensions outside public source, + archives, pull requests, and commits. + +## Repository navigation + +Read `CONTRIBUTING.md` first for the compact module map and targeted test +workflow. + +- CLI and command entry points: `ghostnode/cli.py`, `ghostnode/__main__.py`, + and `ghostnode/commands/`. +- RPC, host, and network collection: `ghostnode/collectors/rpc.py`, + `ghostnode/collectors/network.py`, `ghostnode/host.py`, and + `ghostnode/network.py`. +- Staking, SQLite, rewards, locks, and views: + `ghostnode/intelligence/`. +- Dashboard: `ghostnode/web.py` and `ghostnode/templates/dashboard.html`. +- Tests: `tests/test_*.py`. +- Deployment examples: `deploy/`. +- CI: `.github/workflows/ci.yml`. + +Use exact symbol or filename searches before broad searches. Read task-specific +files rather than whole directories or complete history. Avoid generated data, +complete logs, and unrelated source. + +## Authoritative documentation + +- Overview and command examples: `README.md` +- Development, navigation, and test targeting: `CONTRIBUTING.md` +- Installation: `INSTALL.md` and `docs/INSTALLATION.md` +- Runtime settings: `CONFIGURATION.md` +- Security: `SECURITY.md` +- Ghost Core setup: `docs/GHOST_CORE_SETUP.md` +- Intelligence design: `docs/staking-intelligence.md` +- Reward engine: `docs/G5_8_HISTORICAL_REWARD_ENGINE.md` +- Release history: `CHANGELOG.md` + +Update only the affected source of truth. Use existing documents for detailed +knowledge instead of duplicating it in agent instructions. Preserve historical +documents and distinguish implementation from roadmap or proposal content. + +The public `v0.3.2` tag may have Python package metadata or a CLI version +still reporting `0.3.1`, as described in `docs/INSTALLATION.md`. Do not silently +change version numbers or infer that metadata mismatch is a source change. + +## Development workflow + +- Make the smallest focused change that satisfies the verified requirement. +- Reuse project patterns and preserve unrelated edits. +- Do not modify application source or CI for documentation-only work. +- Use synthetic data and mocks. Never use real wallets, RPC credentials, + production SQLite, or production services in tests. +- Make security-sensitive behavior explicit and testable. +- For reward changes, cover exact atomic values, Ghost PoS identification, + 101-confirmation maturity, idempotency, reorganization handling, and the rule + that PARTIAL, UNKNOWN, UNVERIFIED, or ORPHANED evidence cannot increase + confirmed income. +- Run the smallest relevant tests first, then broader tests when risk requires + it. Report tests not run and why. + +## Git and reporting + +Do not commit or push unless explicitly authorized. For authorized commits, +commit only intended files and do not amend or rewrite shared history. + +When work is interrupted or handed off, report: + +1. Goal. +2. Current branch and commit. +3. Completed and verified work. +4. Changed files. +5. Test results. +6. Remaining work. +7. Unresolved assumptions. +8. Production impact. + +Do not create permanent handoff files for routine completed work. + +## Autonomy + +Routine repository inspection, documentation review, and isolated testing are +allowed. Stop and explain the blocker instead of guessing when wallet security, +production integrity, public publication, or an authorization boundary is +uncertain. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd48755..8364de3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,5 +4,50 @@ Use fixture and mock data only. Do not use production RPC, wallet files, or production SQLite in tests. Add regression tests for RPC parsing, SQLite transactions, locks, reorgs, and reward accounting. -Before submitting changes, run pytest, compileall, and `git diff --check`. +Before submitting changes, run the smallest relevant tests, then broader checks +when the change warrants them. Typical final checks are: + +```bash +python -m pytest -q +python -m compileall -q ghostnode scripts +git diff --check +python scripts/check_tracked_artifacts.py +``` + Do not add generated files, databases, mainnet reports, or credentials. + +## Repository map + +- `ghostnode/cli.py` and `ghostnode/__main__.py`: CLI entry points. +- `ghostnode/commands/`: Click command implementations. +- `ghostnode/collectors/`: host, RPC, service, wallet, staking, and network + collection. +- `ghostnode/intelligence/`: SQLite storage, locks, runner, reward attribution, + prevout resolution, wallet history, diagnostics, and dashboard views. +- `ghostnode/models/results.py`, `ghostnode/presentation.py`, and + `ghostnode/output/`: shared result, presentation, and rendering structures. +- `ghostnode/web.py` and `ghostnode/templates/dashboard.html`: dashboard + application and template. +- `tests/test_*.py`: offline pytest suite and synthetic fixtures. +- `scripts/`: maintenance and diagnostic utilities. +- `deploy/`: example systemd units, not active services. +- `docs/`: installation, security-adjacent guidance, implementation design, + and historical decisions. +- `.github/workflows/ci.yml`: CI commands and artifact policy. + +## Targeted testing + +Start with the test file that exercises the changed subsystem: + +| Change area | Representative tests | +|---|---| +| CLI and command dispatch | `tests/test_status.py`, `tests/test_system.py`, `tests/test_doctor.py`, `tests/test_wallet_cli.py` | +| RPC parsing and probes | `tests/test_rpc.py`, `tests/test_rpc_probe.py`, `tests/test_rpc_schema_probe.py` | +| SQLite, locks, runner, and intelligence | `tests/test_intelligence.py`, `tests/test_runner.py`, `tests/test_wallet_history.py` | +| Rewards and prevout evidence | `tests/test_rewards.py`, `tests/test_reward_adapter.py`, `tests/test_prevout_resolver.py` | +| Network and dashboard | `tests/test_network.py`, `tests/test_web.py`, `tests/test_presentation.py` | +| Wallet diagnostics | `tests/test_wallet.py`, `tests/test_wallet_status.py`, `tests/test_wallet_location.py` | +| Installation and release artifacts | `tests/test_ci_artifact_policy.py`, `tests/test_first_run.py` | + +Run a focused file with `python -m pytest -q tests/test_.py`. Use the full +suite for broad behavioral changes or before release-level verification. diff --git a/README.md b/README.md index 2378f53..541d912 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,20 @@ installation, read-only Ghost Core configuration, dashboard access, collector review, troubleshooting and safe updates, see [docs/INSTALLATION.md](docs/INSTALLATION.md). +## Documentation + +- [INSTALL.md](INSTALL.md) - short Debian/Ubuntu installation workflow. +- [docs/INSTALLATION.md](docs/INSTALLATION.md) - complete installation and safe + update guide. +- [CONFIGURATION.md](CONFIGURATION.md) - environment variables and defaults. +- [SECURITY.md](SECURITY.md) - read-only, credential, wallet, and network + boundaries. +- [docs/GHOST_CORE_SETUP.md](docs/GHOST_CORE_SETUP.md) - detection, setup + guidance, and first-run workflow. +- [docs/staking-intelligence.md](docs/staking-intelligence.md) - current + collector, storage, locking, and reward design. +- [CHANGELOG.md](CHANGELOG.md) - public release history. + ## Tests ```bash