Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
11 changes: 7 additions & 4 deletions GITHUB_PUBLICATION_PREVIEW.md
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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`
Expand Down
21 changes: 14 additions & 7 deletions INSTALL.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down
22 changes: 17 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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.
5 changes: 5 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
5 changes: 5 additions & 0 deletions docs/INSTALLATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion docs/RELEASE_AUDIT.md
Original file line number Diff line number Diff line change
@@ -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**

Expand Down
5 changes: 5 additions & 0 deletions docs/V0_2_ROADMAP.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/V0_3_NETWORK_ACCESS.md
Original file line number Diff line number Diff line change
@@ -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:

Expand Down
37 changes: 22 additions & 15 deletions docs/staking-intelligence.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
# 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

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.

Expand All @@ -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.

Expand All @@ -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.
Loading