posci-miner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proof of Scientist (POSCI) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+<div align="center">
+
+<img src="docs/logo.png" alt="POSCI logo" width="160" height="160" />
+
+# posci-miner
+
+**CLI miner for [POSCI](https://scientistdapp.online) — Proof of Scientist · Ethereum mainnet**
+
+`CPU + WebGPU + hybrid · Local encrypted wallet · Anti-MEV by design`
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518.17-339933)](https://nodejs.org)
+[![Chain](https://img.shields.io/badge/chain-Ethereum%20mainnet-627EEA)](https://etherscan.io/token/0xD020e5E5c2724B2661C2FEF9AE878f49410a8B77)
+
+</div>
+
+---
+
+## What is POSCI?
+
+[**POSCI**](https://scientistdapp.online) is a **21,000,000-cap, owner-less, PoW-mined ERC-20** on Ethereum mainnet. 95% of the supply is distributed via on-chain Proof-of-Work mining (Bitcoin-style halving + difficulty retarget). The mining contract is **fully renounced** — there is no admin, no mint function, no upgrade proxy. The launch LP is permanently burned to `0x000…dEaD`.
+
+The PoW digest is `keccak256(challenge ‖ msg.sender ‖ nonce)` — your wallet address is **inside the hash**. A copied nonce produces a different digest for any other miner, so **MEV bots cannot snipe your nonce from the mempool**.
+
+| | |
+|---|---|
+| Token contract  | [`0xD020e5E5c2724B2661C2FEF9AE878f49410a8B77`](https://etherscan.io/token/0xD020e5E5c2724B2661C2FEF9AE878f49410a8B77) |
+| Mining contract | [`0x9EAdD7dF7701e03d07c3727EC1ba816C2C9De936`](https://etherscan.io/address/0x9EAdD7dF7701e03d07c3727EC1ba816C2C9De936) |
+| Genesis contract| [`0x7bC1520Da49Cd56D5BE11aA77650cA998951459d`](https://etherscan.io/address/0x7bC1520Da49Cd56D5BE11aA77650cA998951459d) |
+| Site / web miner| https://scientistdapp.online |
+
+---
+
+## Install
+
+```bash
+# Requires Node.js ≥ 18.17
+npm install -g posci-miner
+
+# Or run without installing:
+npx posci-miner --help
+```
+
+> **GPU mining** requires Google Chrome / Chromium / Edge installed locally
+> (the CLI launches a headless instance for the WebGPU compute kernel).
+> Set `POSCI_CHROME_PATH=/path/to/chrome` if it's not in a default location.
+
+---
+
+## Quick start
+
+```bash
+# 1. Create a fresh wallet (encrypted under ~/.posci/wallets/)
+posci-miner wallet new alice --password mypw
+
+#    → prints address + private key (private key shown once, save it)
+#    → send some ETH to that address to pay for mine() tx fees (~0.001 ETH/win)
+
+# 2. Check network status
+posci-miner status --wallet alice --password mypw
+
+# 3. Start mining
+posci-miner mine --wallet alice --password mypw --hybrid
+```
+
+That's it. The CLI auto-submits successful PoW solutions and shows a live dashboard with hashrate, network difficulty, and recent hits.
+
+---
+
+## Commands
+
+### `wallet new <name>`
+Generate a fresh wallet, encrypt the private key with `--password` (AES-256-GCM, PBKDF2 250k rounds), store under `~/.posci/wallets/<name>.json`.
+
+```bash
+posci-miner wallet new alice --password mypw
+```
+
+### `wallet list` / `wallet show <name>` / `wallet import <name>`
+Manage local encrypted keystores. `wallet show --private` reveals the decrypted private key (requires password).
+
+### `mine`
+Start mining with one of three engines:
+
+| Flag | Meaning |
+|---|---|
+| `--cpu [n]` | n CPU worker threads (default: all cores) |
+| `--gpu [n]` | n WebGPU workgroups per dispatch (default: 64). Requires Chrome. |
+| `--hybrid` | both CPU and GPU concurrently |
+
+Examples:
+
+```bash
+# Pure CPU, all cores
+posci-miner mine --wallet alice --password mypw
+
+# Pure CPU, 4 workers
+posci-miner mine --wallet alice --password mypw --cpu 4
+
+# Pure GPU (one Chrome process)
+posci-miner mine --wallet alice --password mypw --gpu 256
+
+# Hybrid: CPU on N-1 cores + GPU
+posci-miner mine --wallet alice --password mypw --hybrid
+
+# Use raw private key instead of local wallet store
+posci-miner mine --key 0xabcdef... --hybrid
+
+# Use a specific RPC (defaults to a public Ethereum node)
+posci-miner mine --wallet alice --password mypw --rpc https://eth-mainnet.g.alchemy.com/v2/<key> --hybrid
+
+# Plain log mode (no full TUI — useful for CI / nohup)
+posci-miner mine --wallet alice --password mypw --no-dashboard
+```
+
+### `status`
+Snapshot the on-chain mining state and (optionally) your account balance.
+
+```bash
+posci-miner status                                      # network only
+posci-miner status --address 0xYourAddress              # + balance
+posci-miner status --wallet alice --password mypw       # + balance from local wallet
+```
+
+---
+
+## Live dashboard
+
+When stdout is a TTY, the `mine` command renders a live dashboard:
+
+```
+  POSCI miner · HYBRID · 3m 12s
+  ─────────────────────────────────────────────────────────────
+  Miner     0x9Fa33C79C8bc2Ad785fdE6D10608dB97A95093fa
+  Status    time ✓ · pool ✓
+
+  Hashrate
+  CPU       2.4 MH/s
+  GPU       18.7 MH/s
+  Total     21.1 MH/s
+  Network   ~134 MH/s  (implied by difficulty)
+
+  Network
+  Difficulty     1,920
+  Reward         1,000 POSCI/block
+  Epoch          47
+  Remaining      19,953,000 POSCI
+
+  My account
+  Balance        2,000.0000 POSCI
+  Mined this run 1,000.0000 POSCI
+
+  Recent hits
+  ✓ 14:23:01 GPU +1000 POSCI 0xa1b2c3d4…
+
+  Ctrl+C to stop
+```
+
+---
+
+## How it works
+
+1. **CPU engine** — N Node.js `worker_threads`, each running `js-sha3.keccak_256` in a tight loop with a unique stride to cover disjoint nonce ranges.
+2. **GPU engine** — spawns headless Chrome with our WGSL compute shader (same one the web frontend uses). Chrome posts hits + hashrate over a localhost WebSocket back to the CLI. Reuses the battle-tested shader in `src/mining/keccak256.wgsl.mjs`.
+3. **Hybrid** — both run concurrently with disjoint nonce strides so they never duplicate work. Dedup at the manager catches the rare cross-engine collision.
+4. **Auto-submit** — when any engine finds a valid digest, the CLI immediately calls `mine(nonce, digest)` on the contract from your wallet. Reward lands in your wallet.
+5. **Auto-refresh** — every 12s (configurable), the CLI polls the chain for new challenge / target / difficulty and hot-swaps the job into running workers.
+
+The hash that the contract verifies is exactly:
+```
+keccak256(abi.encodePacked(challengeNumber, msg.sender, nonce))
+```
+Both engines produce digests with **your wallet's address** as `msg.sender`. That's why **only YOU** can submit a valid mine() tx — anyone copying your nonce from the mempool would get a different digest (since their msg.sender is different) and the contract would revert.
+
+---
+
+## Wallet security
+
+Wallets created with `wallet new`:
+- Stored under `~/.posci/wallets/<name>.json` (POSIX 0600 perms)
+- Private key encrypted with AES-256-GCM
+- Key derivation: PBKDF2-HMAC-SHA256, 250,000 iterations, 16-byte random salt
+- Plaintext private key only held in memory while mining
+
+If you lose the password, the wallet is unrecoverable. Back up the keystore JSON + remember the password.
+
+You can also pass a private key directly with `--key 0x...` for ephemeral use (e.g., a dedicated mining wallet), or set `POSCI_PRIVATE_KEY` / `POSCI_WALLET` + `POSCI_PASSWORD` env vars.
+
+---
+
+## Realistic expectations
+
+POSCI mining is competitive — at any given moment, the network hashrate × difficulty determines your expected wait. Some napkin math:
+
+| Your hashrate | Network hashrate | Expected wait per block (1000 POSCI) |
+|---|---|---|
+| 1 MH/s   | 100 MH/s | ~10 minutes |
+| 10 MH/s  | 100 MH/s | ~1 minute   |
+| 100 MH/s | 1 GH/s   | ~10 minutes |
+
+Use the live `posci-miner status` to see current network hashrate.
+
+Each successful `mine()` tx costs ETH gas (~0.0005-0.005 ETH at typical mainnet rates). At low POSCI prices, ensure your reward × POSCI_USD_price > tx_gas_cost.
+
+---
+
+## Troubleshooting
+
+**"Mining is not yet open"** — both gates (time + pool) must be open. Time gate opens 12h after deploy. Pool gate opens after the genesis sale fills 0.5 ETH. Check live status: https://scientistdapp.online/stats
+
+**"No Chrome/Edge/Chromium binary found"** — install Chrome or set `POSCI_CHROME_PATH`. GPU mode needs a recent Chrome (≥113) for WebGPU.
+
+**"WebGPU NOT available in this Chrome"** — your Chrome was started without GPU access. On Linux, ensure you have GPU drivers + try `--enable-features=Vulkan` flag (the CLI passes this automatically).
+
+**Hits show ✗ failed** — the most common cause is the challenge having rotated between when your worker hashed and when your tx landed. The CLI auto-detects this via periodic chain reads and hot-swaps. If you see persistent failures, check that your wallet has enough ETH for gas.
+
+**"DifficultyNotMet"** — your engine's local target was stale (chain difficulty went up). The CLI will auto-correct on the next 12s refresh.
+
+---
+
+## Architecture
+
+```
+posci-miner/
+├── bin/posci-miner.mjs              CLI entry (commander)
+├── src/
+│   ├── commands/                    wallet · mine · status
+│   ├── lib/
+│   │   ├── chain.mjs                viem clients, mining contract calls
+│   │   ├── wallet.mjs               local encrypted keystore (AES-256-GCM)
+│   │   ├── config.mjs               contract addresses + RPCs
+│   │   ├── format.mjs               hashrate / POSCI / duration formatters
+│   │   └── log.mjs                  colored logging
+│   ├── mining/
+│   │   ├── manager.mjs              orchestrator (CPU + GPU + dedup)
+│   │   ├── cpu-worker.mjs           Node worker_threads CPU keccak
+│   │   ├── gpu-driver.mjs           spawns headless Chrome for WebGPU
+│   │   └── keccak256.wgsl.mjs       the WGSL compute shader
+│   └── ui/dashboard.mjs             live TUI dashboard
+└── docs/                            logo assets
+```
+
+---
+
+## Contributing
+
+PRs welcome. Open an issue for design discussion before significant changes.
+
+Please don't submit token-shilling spam — this repo is for the miner only. For protocol questions, [open an issue](https://github.com/Scientists-posci/posci-miner/issues) or come to [@scientistsdapp](https://x.com/scientistsdapp) on X.
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Proof of Scientist contributors
+
+This software is provided as-is. Mining cryptocurrency may be regulated in your jurisdiction. You are responsible for understanding and complying with applicable laws.
+
+The POSCI smart contracts are immutable, non-custodial, and were deployed by an EOA with no admin powers. The contributors of this miner have no control over the protocol or any user funds.

package/bin/posci-miner.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+//
+//  posci-miner — CLI miner for POSCI (Proof of Scientist) on Ethereum mainnet
+//
+
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { registerWalletCommands } from '../src/commands/wallet.mjs';
+import { registerMineCommand }    from '../src/commands/mine.mjs';
+import { registerStatusCommand }  from '../src/commands/status.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+program
+  .name('posci-miner')
+  .description('CLI miner for POSCI (Proof of Scientist) on Ethereum mainnet.\n  CPU + WebGPU + hybrid modes. Local encrypted wallet store.')
+  .version(pkg.version, '-v, --version', 'show version')
+  .addHelpText('after', `
+Examples:
+  $ posci-miner wallet new alice --password mypw
+  $ posci-miner status --wallet alice --password mypw
+  $ posci-miner mine --wallet alice --password mypw --hybrid
+  $ posci-miner mine --key 0xabc... --cpu 8
+  $ posci-miner mine --wallet alice --password mypw --gpu 256
+
+Live data:  https://scientistdapp.online
+Source:     https://github.com/Scientists-posci/posci-miner
+`);
+
+registerWalletCommands(program);
+registerMineCommand(program);
+registerStatusCommand(program);
+
+program.parseAsync(process.argv).catch((e) => {
+  console.error('FATAL:', e?.stack ?? e?.message ?? e);
+  process.exit(1);
+});

package/docs/logo.svg

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  POSCI primary token logo. Monochrome edition matching the Tesla/Starlink-
+  inflected site theme. 512×512 viewBox, recognizable at any size from 16px to
+  1024px, no gradients (rasterizes cleanly via Chrome headless).
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <radialGradient id="orbBg" cx="35%" cy="28%" r="80%">
+      <stop offset="0%"   stop-color="#3a3f4a"/>
+      <stop offset="35%"  stop-color="#1a1d23"/>
+      <stop offset="100%" stop-color="#000000"/>
+    </radialGradient>
+    <radialGradient id="specular" cx="38%" cy="22%" r="35%">
+      <stop offset="0%"   stop-color="#ffffff" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="#ffffff" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+
+  <!-- Outer body — slightly off-pure-black sphere, gives subtle depth -->
+  <circle cx="256" cy="256" r="248" fill="url(#orbBg)"/>
+
+  <!-- Top-light specular highlight — gives the orb a "lit" feel -->
+  <ellipse cx="200" cy="160" rx="160" ry="90" fill="url(#specular)"/>
+
+  <!-- Crisp 1px white outline ring — readable at any size -->
+  <circle cx="256" cy="256" r="248" fill="none" stroke="#ffffff" stroke-width="2" stroke-opacity="0.92"/>
+
+  <!-- Subtle inner mesh: 2 latitude lines, suggests "scientific instrument" -->
+  <g fill="none" stroke="#ffffff" stroke-opacity="0.10" stroke-width="1">
+    <ellipse cx="256" cy="256" rx="246" ry="80"/>
+    <ellipse cx="256" cy="256" rx="246" ry="160"/>
+  </g>
+
+  <!-- One thin tilted orbital ring — the project's "scientist" motif -->
+  <g transform="rotate(-22 256 256)">
+    <ellipse cx="256" cy="256" rx="234" ry="58" fill="none" stroke="#ffffff" stroke-opacity="0.42" stroke-width="2"/>
+    <circle cx="22" cy="256" r="6" fill="#ffffff"/>
+  </g>
+
+  <!-- Φ glyph — the brand. Light weight, large, perfectly centered. -->
+  <text
+    x="256" y="256"
+    text-anchor="middle"
+    dominant-baseline="central"
+    font-family="Georgia, 'Times New Roman', serif"
+    font-weight="500"
+    font-size="296"
+    fill="#ffffff"
+  >Φ</text>
+</svg>

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "posci-miner",
+  "version": "0.1.0",
+  "description": "CLI miner for POSCI (Proof of Scientist) — Bitcoin-style PoW token on Ethereum mainnet. CPU + WebGPU (via headless Chrome) + hybrid modes. Anti-MEV: hash includes msg.sender.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://scientistdapp.online",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Scientists-posci/posci-miner.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Scientists-posci/posci-miner/issues"
+  },
+  "keywords": [
+    "posci",
+    "ethereum",
+    "mining",
+    "pow",
+    "proof-of-work",
+    "erc20",
+    "webgpu",
+    "0xbitcoin",
+    "fair-launch",
+    "cli",
+    "miner"
+  ],
+  "author": "scientistsdapp",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "bin": {
+    "posci-miner": "bin/posci-miner.mjs",
+    "posci": "bin/posci-miner.mjs"
+  },
+  "scripts": {
+    "start": "node bin/posci-miner.mjs",
+    "dev": "node bin/posci-miner.mjs --help",
+    "test": "node --test test/"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "js-sha3": "^0.9.3",
+    "kleur": "^4.1.5",
+    "viem": "^2.21.55",
+    "ws": "^8.18.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/logo.png",
+    "docs/logo.svg",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/commands/mine.mjs

@@ -0,0 +1,222 @@
+// `posci-miner mine` — start mining with CPU / GPU / hybrid.
+
+import { availableParallelism } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+import { resolveAccount } from '../lib/wallet.mjs';
+import { makePublicClient, makeWalletClient, readMiningState, readPosciBalance, submitMine } from '../lib/chain.mjs';
+import { MiningManager } from '../mining/manager.mjs';
+import { Dashboard } from '../ui/dashboard.mjs';
+import { log, c } from '../lib/log.mjs';
+import { formatPosci, formatHashrate } from '../lib/format.mjs';
+
+export function registerMineCommand(program) {
+  program.command('mine')
+    .description('start mining POSCI (CPU / GPU / hybrid)')
+    .option('--cpu [n]',   'use n CPU workers (default: number of cores)')
+    .option('--gpu [n]',   'use GPU with n workgroups per dispatch (1-1024, default: 64). Requires Chrome.')
+    .option('--hybrid',    'use both CPU and GPU')
+    .option('--rpc <url>', 'Ethereum RPC URL (or POSCI_RPC env)')
+    .option('--wallet <name>', 'local wallet name (use `wallet new` to create one)')
+    .option('--password <pw>', 'wallet password (or POSCI_PASSWORD env)')
+    .option('--key <0x...>', 'raw private key (skip local wallet store; use with care)')
+    .option('--chrome <path>', 'path to chrome binary (or POSCI_CHROME_PATH env)')
+    .option('--no-dashboard', 'plain log mode instead of full TUI')
+    .option('--refresh <sec>', 'how often to re-poll chain state', '12')
+    .action(async (opts) => {
+      // ── Resolve auth + mode ────────────────────────────────────────────
+      let acct;
+      try { acct = resolveAccount(opts); }
+      catch (e) { log.err(e.message); process.exit(1); }
+
+      let cpuN = 0, gpuN = 0;
+      const allCores = availableParallelism();
+
+      if (opts.hybrid) {
+        cpuN = Math.max(1, allCores - 1);
+        gpuN = 64;
+      } else if (opts.gpu !== undefined) {
+        gpuN = Number(opts.gpu === true ? 64 : opts.gpu);
+        if (opts.cpu !== undefined) cpuN = Number(opts.cpu === true ? allCores : opts.cpu);
+      } else if (opts.cpu !== undefined) {
+        cpuN = Number(opts.cpu === true ? allCores : opts.cpu);
+      } else {
+        // Default: CPU with all cores
+        cpuN = allCores;
+      }
+
+      cpuN = Math.max(0, Math.min(64,  cpuN));
+      gpuN = Math.max(0, Math.min(1024, gpuN));
+
+      const mode = (cpuN > 0 && gpuN > 0) ? 'hybrid' : (gpuN > 0 ? 'gpu' : 'cpu');
+
+      log.banner(c.bold().cyan('  POSCI miner'));
+      log.info(`  miner: ${acct.address}  (${acct.source})`);
+      log.info(`  mode : ${mode.toUpperCase()}  (cpu=${cpuN}, gpu=${gpuN})`);
+
+      const pub    = makePublicClient(opts.rpc);
+      const wallet = makeWalletClient(opts.rpc, acct.privateKey);
+
+      // ── Initial chain pull ─────────────────────────────────────────────
+      let chain = await readMiningState(pub);
+      if (!chain.canMine) {
+        log.warn(`Mining is not yet open:`);
+        log.warn(`  time gate ${chain.timeGateOpen ? '✓' : '⏳'}  pool gate ${chain.poolGateOpen ? '✓' : '⏳'}`);
+        log.info(`  CLI will wait and check every ${opts.refresh}s.`);
+      }
+
+      const myMinedAtStart = await readPosciBalance(pub, acct.address);
+      let myMinedRun = 0n;
+
+      const dash = new Dashboard({ minerAddress: acct.address, mode });
+      dash.update({
+        difficulty:      chain.difficulty,
+        reward:          chain.miningReward,
+        remaining:       chain.remainingSupply,
+        epoch:           chain.epochCount,
+        poolGate:        chain.poolGateOpen,
+        timeGate:        chain.timeGateOpen,
+        miningStartTime: chain.miningStartTime,
+        networkHashrate: chain.networkHashrate,
+        myBalance:       myMinedAtStart,
+      });
+
+      if (opts.dashboard !== false) dash.start();
+
+      // ── Mining manager ─────────────────────────────────────────────────
+      const startNonce = BigInt('0x' + randomBytes(8).toString('hex'));
+      const mgr = new MiningManager({
+        minerAddress: acct.address,
+        cpuWorkers:   cpuN,
+        gpuPower:     gpuN,
+        gpuChromePath: opts.chrome,
+      });
+      mgr.on('error', ({ source, error }) => log.warn(`[${source}] ${error.message ?? error}`));
+      mgr.on('stats', ({ cpu, gpu }) => dash.update({ cpuRate: cpu.hashrate, gpuRate: gpu.hashrate }));
+
+      // ── Hit handling — gated on chain.canMine ─────────────────────────
+      // Workers don't know about gates; they just hash. The check that
+      // matters is "is the contract actually willing to accept mine() right
+      // now?" — driven by chain.canMine (time gate AND pool gate both open).
+      //
+      // If gates are closed, we BUFFER the most recent valid solution
+      // (against the current challenge) and re-attempt as soon as gates
+      // open. This gets you the FIRST submission window without burning gas
+      // on guaranteed-revert txs.
+      let pendingHit = null;
+      let busy = false;       // ensure only one in-flight tx at a time
+
+      async function trySubmit(hit) {
+        if (busy) return;
+        if (!chain.canMine) {
+          pendingHit = hit;
+          return;
+        }
+        busy = true;
+        const nonceHex = '0x' + hit.nonce.toString(16);
+        dash.pushHit({ source: hit.source, nonce: nonceHex, digest: hit.digest,
+                       reward: chain.miningReward, status: 'pending' });
+        try {
+          const txHash = await submitMine(wallet, pub, hit.nonce, hit.digest);
+          dash.pushHit({ source: hit.source, nonce: nonceHex, digest: hit.digest,
+                         reward: chain.miningReward, txHash, status: 'pending' });
+          const receipt = await pub.waitForTransactionReceipt({ hash: txHash, timeout: 180_000 });
+          if (receipt.status === 'success') {
+            myMinedRun += chain.miningReward;
+            const bal = await readPosciBalance(pub, acct.address);
+            dash.pushHit({ source: hit.source, nonce: nonceHex, digest: hit.digest,
+                           reward: chain.miningReward, txHash, status: 'success' });
+            dash.update({ myMined: myMinedRun, myBalance: bal });
+          } else {
+            dash.pushHit({ source: hit.source, nonce: nonceHex, digest: hit.digest,
+                           reward: 0n, txHash, status: 'failed' });
+          }
+        } catch (e) {
+          dash.pushHit({ source: hit.source, nonce: nonceHex, digest: hit.digest,
+                         reward: 0n, status: 'failed' });
+          log.warn(`submit error: ${e.shortMessage ?? e.message ?? e}`);
+        } finally {
+          busy = false;
+          pendingHit = null;
+        }
+      }
+
+      mgr.on('hit', (hit) => {
+        if (chain.canMine) {
+          // Gates open — submit immediately
+          trySubmit(hit).catch(() => {});
+        } else {
+          // Gates closed — keep the most recent solution for current challenge.
+          // Don't try to submit yet (would burn gas on guaranteed revert).
+          pendingHit = hit;
+        }
+      });
+
+      // Surface "we have a buffered solution waiting for gates" in the dashboard
+      const pendingTimer = setInterval(() => {
+        dash.update({
+          pendingNote: (!chain.canMine && pendingHit)
+            ? `★ buffered solution ready — will submit the moment gates open`
+            : '',
+        });
+      }, 1000);
+
+      await mgr.start({
+        challenge:  chain.challengeNumber,
+        target:     chain.miningTarget,
+        startNonce,
+      });
+
+      // ── Periodic chain refresh: detect new challenge / target / gates ──
+      const refreshSec = Math.max(3, Number(opts.refresh));
+      const refreshTimer = setInterval(async () => {
+        try {
+          const fresh = await readMiningState(pub);
+          const gatesJustOpened = fresh.canMine && !chain.canMine;
+          const challengeRotated = fresh.challengeNumber !== chain.challengeNumber
+                                || fresh.miningTarget    !== chain.miningTarget;
+
+          if (challengeRotated) {
+            mgr.setJob({
+              challenge: fresh.challengeNumber,
+              target:    fresh.miningTarget,
+              startNonce: BigInt('0x' + randomBytes(8).toString('hex')),
+            });
+            // Old buffered solution is now invalid (different challenge)
+            pendingHit = null;
+          }
+          chain = fresh;
+          dash.update({
+            difficulty:      chain.difficulty,
+            reward:          chain.miningReward,
+            remaining:       chain.remainingSupply,
+            epoch:           chain.epochCount,
+            poolGate:        chain.poolGateOpen,
+            timeGate:        chain.timeGateOpen,
+            miningStartTime: chain.miningStartTime,
+            networkHashrate: chain.networkHashrate,
+          });
+
+          // Race-window: gates just flipped open AND we have a buffered solution
+          if (gatesJustOpened && pendingHit) {
+            log.ok(`Gates opened — submitting buffered solution from pre-warm period`);
+            trySubmit(pendingHit).catch(() => {});
+          }
+        } catch { /* ignore transient RPC errors */ }
+      }, refreshSec * 1000);
+
+      // ── Graceful exit ──────────────────────────────────────────────────
+      const cleanup = () => {
+        clearInterval(refreshTimer);
+        clearInterval(pendingTimer);
+        mgr.stop();
+        dash.stop();
+        log.banner(c.bold('  Stopped.'));
+        log.info(`  Hashes computed this run: ${(mgr.cpuStats.totalHashes + mgr.gpuStats.totalHashes).toString()}`);
+        log.info(`  POSCI mined this run    : ${formatPosci(myMinedRun, 4)}`);
+        process.exit(0);
+      };
+      process.on('SIGINT',  cleanup);
+      process.on('SIGTERM', cleanup);
+    });
+}