Heartbeat Daemon
SPECIFICATION: Heartbeat Daemon (heartbeat.py)
Status: AUTHORIZED
Authorized: α.13, April 16 2026
Version: v1.0
Version: v1.0
PURPOSE
Trading challenge heartbeat daemon. Runs periodic balance checks, computes CAD progress toward the $1,000 CAD milestone, updates a public status file, and gates compounding actions (Beefy Leap, Bitcoin Gravity) behind gas and balance guards. Operates on Base network via CDP async client.
Source file: /home/nous/heartbeat.py
CRITICAL GOVERNANCE NOTE: heartbeat.py predates Agency Walls governance. All inline trade execution stubs currently bypass TMM/AgencyWalls. No trade stub may be activated without full Agency Walls integration. This spec defines what the daemon SHOULD enforce, not what it currently enforces.
INPUTS
| Input | Source | Notes |
|---|---|---|
| CDP credentials | ~/.aether/vault.json | Loaded by CDP Client; C.L.O.D. must not read raw values |
| TARGET_ADDRESS | Hardcoded constant | 0xafE9bA6841121ebF128F680ccE8035a65ad0Fa08 (AION wallet) |
| ETH balance | Base network via CDP | Live on-chain query |
| USDC balance | Base network via CDP | Live on-chain query |
| Gas estimate | Simulated (random 0.001–0.05 Gwei) | [GAP-01 — NOT live; oracle is a stub] |
| CAD_RATE | Hardcoded 1.38 | [GAP-02 — must be externally sourced in production] |
| MIN_USDC_THRESHOLD | Hardcoded 1.00 | Floor for Beefy Leap trigger |
| GAS_GUARD_FLOOR | Hardcoded 0.0004 ETH | Hard stop for all trade execution |
OUTPUTS
| Output | Destination | Notes |
|---|---|---|
| Action log entries | /home/nous/sisters_ledger.txt | Written by log_action(); append-only |
| Public status snapshot | /home/nous/sisters_public_status.json | Updated each cycle; human/external readable |
| Console output | stdout | Mirror of ledger entries via print() |
| Gas alert | ledger + stdout | Fires when ETH < 0.0005 |
| Milestone halt signal | ledger + stdout | Fires when total_cad >= 100; autonomous execution ceases |
INVARIANTS
| ID | Invariant | Enforcement |
|---|---|---|
| INV-01 | Gas guard floor: NO trade execution when ETH < 0.0004 | Must be checked before every compounding action |
| INV-02 | $100 CAD milestone → halt all autonomous strikes, await NOUS Phase 2 instruction | Non-negotiable ceiling; C.L.O.D. does not override |
| INV-03 | All compounding actions (Beefy Leap, Bitcoin Gravity) MUST be logged to sisters_ledger.txt | No silent execution |
| INV-04 | CAD rate (1.38) must be externally sourced before any trade stub is activated | Hardcoded value is a placeholder only |
| INV-05 | All trade stubs MUST be routed through AgencyWalls.check_all() before activation | Stubs are currently inert; activation without governance integration is FORBIDDEN |
| INV-06 | Vault credentials must not be exposed in logs, stdout, or any file output | C.L.O.D. turns the ignition; C.L.O.D. does not copy the key |
| INV-07 | CAD progress = (total_usd × CAD_RATE) / 1000 × 100 | Formula is fixed; do not alter without NOUS approval |
VERIFICATION CRITERIA
| ID | Criterion | Method |
|---|---|---|
| VER-01 | Each cycle writes at least one entry to sisters_ledger.txt | Tail ledger after single run; verify timestamp + action string present |
| VER-02 | sisters_public_status.json is valid JSON after each cycle | python3 -c "import json; json.load(open('sisters_public_status.json'))" |
| VER-03 | Gas guard fires correctly when ETH < 0.0004 | Unit test: mock ETH balance = 0.0003; assert no trade path reached |
| VER-04 | Milestone halt fires when total_cad >= 100 | Unit test: mock balance → $72.46 USD × 1.38 = $99.99 CAD (no halt); $72.47 USD × 1.38 = $100.01 CAD (halt) |
| VER-05 | Gas alert fires when ETH < 0.0005 (distinct from guard floor) | Unit test: mock ETH = 0.00045; assert alert logged, no trade blocked solely by alert |
| VER-06 | Trade stubs do NOT execute without AgencyWalls wrapper | Code audit: grep for execute, transfer, swap — all must be inside governance gate or marked # STUB |
| VER-07 | CDP vault path resolves to ~/.aether/vault.json | ls -la ~/.aether/vault.json confirms file exists; CDP client loads without error |
FAILURE MODES
| ID | Failure | Expected Behavior | Current Gap |
|---|---|---|---|
| FM-01 | CDP network timeout or Base RPC unavailable | Cycle aborts cleanly; logs error to ledger; retries on next cycle | [GAP-03 — no retry/recovery loop defined] |
| FM-02 | vault.json missing or malformed | CDP client raises; daemon should log and halt gracefully | [GAP-03 — unspecified] |
| FM-03 | sisters_public_status.json write fails (disk full, permission) | Log failure; do not crash; continue cycle | Not specified in current code |
| FM-04 | Gas oracle returns anomalous value (negative, >1000 Gwei) | Clamp or reject; log anomaly; do not trade | [GAP-01 — oracle is simulated; no validation path] |
| FM-05 | CAD rate drifts significantly (> 5%) from real rate | Miscalculated progress; possible premature or delayed milestone halt | [GAP-02 — hardcoded rate] |
| FM-06 | Milestone halt condition not persisted across restarts | Daemon reboots, recalculates total_cad < 100 due to balance change, resumes execution | [GAP-04 — halt state not persisted to disk] |
| FM-07 | Beefy Leap or Bitcoin Gravity stubs accidentally activated | Ungoverned trade execution | INV-05 prevents; but no automated test enforces |
GAPS
| ID | Gap | Severity | Resolution Path |
|---|---|---|---|
| GAP-01 | Gas oracle is simulated (random 0.001–0.05 Gwei); not connected to live Base gas data | HIGH | Wire to Base RPC eth_gasPrice or Blocknative API before any trade stub activation |
| GAP-02 | CAD_RATE = 1.38 is hardcoded; not sourced from live forex feed | MEDIUM | Add forex API call (e.g., exchangerate-api.com) or NOUS-provided rate injection on cycle start |
| GAP-03 | No failure recovery loop; exceptions likely crash the cycle silently | HIGH | Wrap main cycle in try/except with structured error logging to ledger; add restart logic or systemd WantedBy restart policy |
| GAP-04 | Milestone halt state not persisted to disk; lost on daemon restart | HIGH | Write halt flag to sisters_public_status.json or a dedicated halt_flag file; check on boot before first cycle |
| GAP-05 | No systemd service definition; daemon runs as standalone script with no supervisor | MEDIUM | Define heartbeat.service unit file; requires NOUS approval before deployment per governance |
| GAP-06 | Cycle frequency/schedule not specified in code or documentation | MEDIUM | Define CYCLE_INTERVAL_SECONDS constant; document expected run cadence |
| GAP-07 | Trade execution stubs (Beefy Leap, Bitcoin Gravity) not wired to AgencyWalls.check_all() | CRITICAL | Must be resolved before any stub is activated; see INV-05 |
| GAP-08 | No unit test suite for heartbeat.py | MEDIUM | Minimum: gas guard test, milestone halt test, ledger write test (see VER-03, VER-04, VER-07) |
Jeremy Zlabis
Chronogeometer · Visionary · Disruptor · Chief
42 Sisters AI · East York, Toronto
🍁 Φ 0.042