diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a42d93c..7d738d7 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -7,6 +7,15 @@ does not use a shell. Dashboard Intelligence views open SQLite read-only. The collector separates RPC planning from short SQLite writer transactions. `InstanceLock` prevents concurrent collector instances and `CollectorLock` protects writer operations. Reward attribution is conservative: incomplete or -unverified evidence cannot become confirmed income. +unverified evidence cannot become confirmed income. Ghost-specific PoS +detection, exact atomic-unit accounting, 101-confirmation maturity, idempotent +processing, and reorg handling are covered by the reward pipeline tests. + +`getblockreward` is optional enrichment, not a prerequisite for ordinary block +persistence. When network-wide reward components cannot be verified, they stay +`NULL`/`UNKNOWN`; wallet-owned income is not inferred from totals or balances. + +Private Donations and other host-specific wrappers are outside this public +architecture and must remain local-only. Systemd files are templates only and are not installed by this release. diff --git a/CHANGELOG.md b/CHANGELOG.md index 16f84f6..a69a6ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## 0.3.2 + +- Corrected Ghost-specific PoS block detection and exact atomic-unit reward + accounting. +- Added conservative historical prevout and wallet-ownership evidence handling. +- Corrected PoS reward maturity to 101 confirmations when + `COINBASE_MATURITY=100`. +- Preserved `NULL`/`PARTIAL`/`UNKNOWN` states for incomplete network-wide data; + incomplete evidence cannot increase confirmed income. +- Added idempotent reward persistence, reorg-safe handling, and focused + regression coverage for the reward pipeline. +- Added public Debian/Ubuntu installation documentation. + ## 0.3.1 - Added an explicit `trusted_lan` mode for direct, unauthenticated read-only diff --git a/CONFIGURATION.md b/CONFIGURATION.md index f6f6bd8..251b364 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -25,3 +25,6 @@ multicast, public, loopback-as-LAN, and IPv6 binds are rejected. Network setting are validated before listeners start and web proposals never apply changes. Never put RPC passwords, cookies, bearer tokens, seeds, or wallet keys in repository files or command-line arguments. + +Private environment files, token files, production database paths, and +local-only Donations configuration belong outside the public source tree. diff --git a/GITHUB_PUBLICATION_PREVIEW.md b/GITHUB_PUBLICATION_PREVIEW.md index 9a0e15b..a40d876 100644 --- a/GITHUB_PUBLICATION_PREVIEW.md +++ b/GITHUB_PUBLICATION_PREVIEW.md @@ -1,4 +1,7 @@ -# GitHub publication preview +# Historical GitHub publication preview — v0.2.0 + +> This file records the v0.2.0 publication plan. It is retained as history and +> is not the current release description. The current public release is v0.3.2. Repository owner: `eflipper13` Repository name: `GhostNode-Tools` @@ -9,12 +12,12 @@ intelligence tools for Python 3.11. Topics: `ghost`, `blockchain`, `node-monitoring`, `staking`, `python`, `open-source` -Visibility: public (planned only; not configured here). +Visibility: public; the repository is now published. License: MIT -Release assets: prepared locally for this release; publication remains a -separate owner-approved step. +Release assets and publication were completed separately; this file is not the +source of truth for current release assets. Topics: `ghost`, `ghost-core`, `blockchain`, `node-monitoring`, `staking`, `python`, `open-source` diff --git a/INSTALL.md b/INSTALL.md index 1e161da..89b9441 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,14 +1,15 @@ # Installation This guide describes an isolated Debian 12 installation for GhostNode Tools -v0.3.0. It does not install a systemd unit, modify Ghost Core, unlock a wallet, +v0.3.2. It does not install a systemd unit, modify Ghost Core, unlock a wallet, or create transactions. ## Requirements - Debian 12 with Python 3.11 and `python3.11-venv` available; - a local Ghost Core installation and its read-only `ghost-cli`; -- access to the release archive and its published SHA256 checksum. +- access to the v0.3.2 Git tag, or a release archive and its published SHA256 + checksum when an archive is provided. ## Verify and install @@ -17,9 +18,9 @@ Do not copy a production `.cookie`, `ghost.conf`, wallet file, SQLite database, or secret into the release tree. ```bash -sha256sum -c GhostNode-Tools-v0.3.0.tar.gz.sha256 +sha256sum -c GhostNode-Tools-v0.3.2.tar.gz.sha256 mkdir -p "$HOME/ghostnode-tools" -tar -xzf GhostNode-Tools-v0.3.0.tar.gz -C "$HOME/ghostnode-tools" --strip-components=1 +tar -xzf GhostNode-Tools-v0.3.2.tar.gz -C "$HOME/ghostnode-tools" --strip-components=1 cd "$HOME/ghostnode-tools" python3.11 -m venv .venv . .venv/bin/activate @@ -33,9 +34,10 @@ The checksum file must come from the same trusted release channel as the archive. Do not invent or skip hashes. No command above uses `sudo` or changes system-wide Python packages. -The stable archive and checksum are local release artifacts. Publication is a -separate owner-approved step. The checksum file is kept beside the archive when running -`sha256sum -c`. +The v0.3.2 Git tag is the canonical source reference. Use the archive commands +only when the matching archive and checksum are supplied through a trusted +release channel. The checksum file must be kept beside the archive when +running `sha256sum -c`. ## Local configuration @@ -79,6 +81,11 @@ Inspect `CONFIGURATION.md` and `SECURITY.md` before connecting any live node. Collector operation is a separate, reviewed step and is not started by this installation guide. +The private Donations observer and dashboard wrapper are not part of the public +installation. If a local deployment has those extensions, keep their code, +configuration, wallet-related data, and SQLite database outside this source +tree and outside public release artifacts. + ## Stop and remove Stop the foreground dashboard with `Ctrl-C`. To remove the application, stop diff --git a/README.md b/README.md index edc1cf3..2378f53 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ unlocks wallets, or changes node configuration. No Ghost Core connection is required for M1. -v0.3.1 adds an explicitly reviewed trusted-LAN access option on top of the +v0.3.2 includes the reviewed trusted-LAN access option on top of the configurable, validated dashboard network access introduced in v0.3.0. The portable defaults are `ghost-cli`, `~/.ghost`, and wallet `ghostmain`; they can be overridden with command options or environment variables. @@ -123,13 +123,17 @@ The runner is available as `python -m ghostnode collector`. It uses one shared process lock, a 60-second bounded block scan and a 15-minute snapshot schedule. `--check` performs only the read-only RPC preflight and does not open or create the SQLite database. `--once` runs one snapshot and one bounded scanner batch. -The runner is not installed or enabled as a systemd service by this change. +The public release provides the runner and unit templates; installing or +enabling a systemd service remains an explicit operator action. A production +deployment may use a private unit and private environment outside this tree. Staking Intelligence calculates wallet share and statistical probabilities from the node's current `expectedtime`. These are estimates, not guarantees or APY. -Historical blocks, rewards and difficulty series are shown as unavailable -because the current read-only RPC set does not expose historical data. No -synthetic history is generated. +Historical backfill is not automatic. Current-chain PoS blocks can be recorded +with conservative wallet reward attribution when the required evidence is +available; missing or ambiguous evidence remains `PARTIAL`/`UNKNOWN`, and +network-wide reward components that require unavailable data remain `NULL`. +No synthetic history is generated. ## systemd deployment (manual) @@ -198,3 +202,11 @@ GHOST donations are welcome. GHOST donation address: GZKRMKqiHp6WsVy9DsNAD9arSSK66Pv5Hv Donations are entirely optional. All features remain free. + +## Private local-only integrations + +The public project does not contain the private Donations observer, private +dashboard wrapper, private wallet-monitoring data, or production environment +files. Those extensions may exist in a separately managed local deployment, +but must remain outside this repository, public archives, pull requests, and +release assets. diff --git a/SECURITY.md b/SECURITY.md index f536b0b..f5d763b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -34,3 +34,8 @@ wallet path only when filesystem metadata identifies a supported location. Treat that output as local operator information. Remote RPC paths, ambiguous layouts, and unsupported wallet formats remain `WALLET_PATH_UNKNOWN`; the first-run report redacts local paths. The tool never opens wallet databases. + +The public release contains no Donations observer, private dashboard wrapper, +production SQLite, wallet data, or host-specific monitoring extension. Such +features are local-only deployment components and must remain outside the +public repository and release artifacts. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index c2aeee7..c7066e4 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -58,6 +58,11 @@ not assume an archive asset exists if it is not listed on the release page. Do not copy a Ghost Core datadir, wallet files, cookie files, SQLite database, or private configuration into this source directory. +The public installation does not include the private Donations observer, +private dashboard wrapper, wallet-monitoring data, or production environment. +Those are local-only deployment extensions and must remain outside this source +tree and outside public release archives. + The public release tag is v0.3.2. The current Python package metadata and CLI version string may still report 0.3.1; this does not change the tag or source being installed and is a packaging metadata limitation to be resolved in a diff --git a/docs/RELEASE_AUDIT.md b/docs/RELEASE_AUDIT.md index c10d340..1eb0376 100644 --- a/docs/RELEASE_AUDIT.md +++ b/docs/RELEASE_AUDIT.md @@ -1,4 +1,8 @@ -# GhostNode Tools — Open Source Release Candidate v0.1 +# Historical release audit — GhostNode Tools v0.1 + +> This is a historical v0.1 audit record. It is retained for provenance and is +> not the current release status. See the v0.3.2 documentation for current +> installation, security, network, and reward behavior. Status: **READY FOR PUBLICATION** diff --git a/docs/V0_2_ROADMAP.md b/docs/V0_2_ROADMAP.md index 4faa12e..f4e849d 100644 --- a/docs/V0_2_ROADMAP.md +++ b/docs/V0_2_ROADMAP.md @@ -1,5 +1,10 @@ # GhostNode Tools v0.2.0 roadmap +> Historical roadmap. M1–M3 are implemented in the v0.2.0 development history; +> this file is retained for project provenance. Current installation and +> security guidance is maintained in `docs/INSTALLATION.md`, `SECURITY.md`, and +> `AGENTS.md`. + The v0.2.0 development line begins with M1: Ghost Core detection and a guided setup assistant. M1 and M2 are diagnostic and planning-only. They do not install Ghost Core, write configuration, change permissions, create services, or change diff --git a/docs/V0_3_NETWORK_ACCESS.md b/docs/V0_3_NETWORK_ACCESS.md index c970303..a857735 100644 --- a/docs/V0_3_NETWORK_ACCESS.md +++ b/docs/V0_3_NETWORK_ACCESS.md @@ -1,4 +1,4 @@ -# GhostNode Tools v0.3.0 network access +# GhostNode Tools v0.3.x network access The dashboard is localhost-only by default: diff --git a/docs/staking-intelligence.md b/docs/staking-intelligence.md index 2e39c2b..1da6f28 100644 --- a/docs/staking-intelligence.md +++ b/docs/staking-intelligence.md @@ -1,8 +1,10 @@ -# Staking Intelligence 2.1 +# Staking Intelligence — current public implementation -The implementation is intentionally separate from the web dashboard. It provides a -SQLite foundation and mockable, read-only collectors; it is not enabled by the -dashboard and is not installed as a service by this change. +The public implementation provides the SQLite foundation, read-only collector, +reward attribution, and dashboard views. The public release includes runner and +systemd templates, but does not install or enable services automatically. A +production deployment may use private service units and private environment +files outside this repository. ## Storage @@ -10,7 +12,7 @@ The default deployment path is `data/staking_intelligence.sqlite3`. SQLite is configured for WAL mode, a busy timeout, foreign keys, UTC timestamps, and transactional idempotent writes. Missing RPC fields remain `NULL`. -Amounts must be stored in atomic units when a future reward tracker is added. +Amounts are stored in atomic units throughout reward tracking. Raw RPC responses, credentials, addresses, seeds, and private keys must not be stored. @@ -23,8 +25,9 @@ stored. - catch-up is bounded by the caller's batch policy and never advances `chain_state` past a block whose reward transaction history could not be read; - each reward separates lifecycle (`MATURED`, `IMMATURE`, etc.) from economic - data completeness (`COMPLETE`, `PARTIAL`, `UNKNOWN`); a wallet reward may be - confirmed while block economics remain partial; + data completeness (`COMPLETE`, `PARTIAL`, `UNKNOWN`); only `MATURED` plus + `COMPLETE` with a positive non-NULL wallet reward contributes to confirmed + income; - a writer transaction and process lock must prevent overlapping production runs; - reorgs are represented by inactive blocks and explicit reorg events, not deletes. @@ -34,24 +37,28 @@ chain cursor is left unchanged for a later retry. Wallet transaction history is read in bounded pages (20 x 1000 entries maximum per block attempt), with deduplication. The result is explicitly `COMPLETE`, `RPC_ERROR`, or `LIMIT_REACHED`; only `COMPLETE` can advance the cursor for a PoS block. -Production `getblockreward` currently requires `txindex`, which is not enabled -on the audited node; block-level reward components therefore remain `NULL` and -the record is `PARTIAL`, rather than being inferred from wallet balances. +`getblockreward` may require `txindex` on Ghost Core installations. It is +optional enrichment, not a prerequisite for ordinary block persistence. When +block-wide components cannot be verified, they remain `NULL` and the record +remains incomplete rather than being inferred from wallet balances. The scanner budget is distinct from RPC call count. At a 60-second block scan interval there are 1,440 cycles/day. A snapshot at 15-minute intervals is 96 cycles/day and, with three RPCs per snapshot, 288 RPC calls/day. Block-cycle RPC count depends on whether a block is already known: a normal cycle uses `getblockchaininfo`, `getblockhash`, and `getblock`; a PoS block additionally -uses `getblockreward` and bounded `listtransactions` pages. +uses bounded wallet-history and attribution reads; `getblockreward` is not +required by the normal scanner. -## Future service +## Runner and deployment The local runner is available as `python -m ghostnode collector`. It keeps the block scanner (60 seconds) and snapshots (15 minutes) on independent monotonic schedules, with a bounded retry backoff after RPC failures. Both writers use one shared process lock. `--check` does not open the database and `--once` runs one current snapshot plus one bounded scanner batch. The runner is not installed, -enabled, or started as a systemd unit by this task. Before deployment, validate -the configured RPC whitelist against the production Ghost Core build and review -the proposed systemd restrictions. +enabled, or started as a systemd unit by the public release. Before deployment, +validate the configured RPC whitelist against the production Ghost Core build +and review the proposed systemd restrictions. Private production units, runtime +data, logs, backups, and Donations extensions remain outside the public source +tree.