Merge pull request #5 from rsantacroce/pps-thunder-classic

Pps thunder classic

Author: rsantacroce

.dockerignore

@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------------
+# Keep the docker build context small. Docker reads this from the context
+# root (the repo root, per docker-compose.yml `context: ../..`).
+# -----------------------------------------------------------------------------
+
+# host-only build outputs — the image builds fresh from source
+build/
+**/node_modules/
+
+# runtime data lives in a bind-mounted volume, never in the image
+data/
+.regtest/
+
+# operator secrets and local notes — never bake into an image
+proxy.conf
+FORKNET_CHEATSHEET.md
+memory.md
+*.pre-reconcile-*
+*.pre-restart-*
+
+# vcs & editor cruft
+.git/
+.gitignore
+.DS_Store
+
+# docs — not needed at runtime
+*.md
+!dashboard/README.md
+!payout/README.md
+!deploy/docker/README.md

.github/workflows/build_docker.yaml

@@ -0,0 +1,87 @@
+# Build the three simplepool container images and push them to the GitHub
+# Container Registry (ghcr.io) — the same registry coinshift-rs publishes to.
+#
+# This job runs only in the canonical LayerTwo-Labs repo (see the `if:` guard
+# on the job), so images land in the org namespace, tagged automatically:
+#   ghcr.io/layertwo-labs/simplepool            (C stratum proxy)
+#   ghcr.io/layertwo-labs/simplepool-dashboard  (Node read-only web UI)
+#   ghcr.io/layertwo-labs/simplepool-payout     (Node Thunder payout worker)
+#
+# Auth uses the built-in GITHUB_TOKEN — no secrets to configure, because the
+# repo lives in the same org that owns the packages (exactly like coinshift).
+# Pull-request runs build the images (to prove the Dockerfiles still work) but
+# do not push; only pushes to main, tags, and manual runs publish.
+name: Build and push Docker images
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  build-push-docker:
+    runs-on: ubuntu-latest
+    # Publish only from the LayerTwo-Labs org repo. On a personal fork/repo
+    # (e.g. rsantacroce/simplepool) this is false, so the whole job is skipped
+    # — nothing is built and nothing is pushed. (String compare is
+    # case-insensitive, so 'LayerTwo-Labs' also matches 'layertwo-labs'.)
+    if: github.repository_owner == 'LayerTwo-Labs'
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: simplepool
+            dockerfile: deploy/docker/Dockerfile.simplepool
+          - image: simplepool-dashboard
+            dockerfile: deploy/docker/Dockerfile.dashboard
+          - image: simplepool-payout
+            dockerfile: deploy/docker/Dockerfile.payout
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository_owner }}/${{ matrix.image }}
+          tags: |
+            type=sha,event=push
+            type=ref,event=pr
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        # Skipped on pull_request, where we build-only and don't push.
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.dockerfile }}
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # Per-image GitHub Actions cache so the three legs don't collide.
+          cache-from: type=gha,scope=${{ matrix.image }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.image }}

.github/workflows/check_build.yaml

@@ -0,0 +1,37 @@
+# Compile simplepool and run its unit tests on every push/PR.
+# simplepool is pure C11 (see Makefile); its deps are the same -dev packages
+# the build stage of deploy/docker/Dockerfile.simplepool installs.
+name: Build and test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    # Match build_docker.yaml: CI runs only in the LayerTwo-Labs org repo, so
+    # pushing to a personal repo doesn't spend Actions minutes. Remove this line
+    # if you *do* want build/test CI to run on your own fork too.
+    if: github.repository_owner == 'LayerTwo-Labs'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential \
+            libsqlite3-dev \
+            libcurl4-openssl-dev \
+            libhiredis-dev
+
+      - name: Build
+        run: make -j"$(nproc)"
+
+      - name: Test
+        run: make test

.gitignore

@@ -1,6 +1,4 @@
-build/
-data/
-*.o
-*.d
-proxy.conf
-.DS_Store
+/build/
+/data/
+/.regtest/
+/proxy.conf

CLASSIC_PAYOUTS.md

@@ -0,0 +1,171 @@
+# `pps-thunder-classic` — traditional coinbase + operator-driven deposits
+
+## Why this branch exists
+
+The `pps-thunder` design embeds a BIP300 drivechain deposit in every
+coinbase, aiming to make the pool never custody BTC. End-to-end
+validation on regtest AND on the live forknet server proved that the
+LayerTwo-Labs enforcer **does not credit coinbase outputs as
+drivechain deposits** — the block is accepted into the chain but the
+sidechain Ctip never moves. The rule requires the deposit tx to spend
+real, mature, spendable UTXOs; a coinbase does not qualify. This is
+consensus-level and unlikely to change.
+
+This branch flips the model to the pattern all real drivechain mining
+pools converge on:
+
+1. **Coinbase pays the pool's BTC wallet** — a normal solo-style
+   output. Pool now does briefly custody BTC (a design tradeoff, but
+   the only path that actually works).
+2. **Operator (via the admin dashboard) triggers batched deposits to
+   Thunder.** Each deposit is a real `CreateDepositTransaction` that
+   spends accumulated pool UTXOs → OP_DRIVECHAIN + OP_RETURN. This DOES
+   credit the Ctip on Thunder.
+3. **Payout worker (already in the code) drains the Thunder reserve to
+   miners.** No change from `pps-thunder` — same
+   `pps_credits.accrued_sats - paid_sats` sweep, same at-most-once
+   protocol.
+
+Everything upstream of the deposit step stays identical to
+`pps-thunder`: same stratum-username-is-a-Thunder-address, same PPS
+accrual math, same in-flight ledger, same audit tooling.
+
+## Concrete code delta from `pps-thunder`
+
+### 1. New pool mode value
+
+Add a third value to `pool_mode` in `src/config.h` /
+`src/config.c`:
+
+- `solo`  — unchanged; miners paid direct in coinbase (per-miner
+  address as the coinbase spendable output).
+- `pps`   — the drivechain-in-coinbase build (does not credit Thunder;
+  useful only as a shape validator).
+- **`pps-classic`** — new. Coinbase pays a single `pool_btc_address`
+  (P2WPKH) for the full net-of-operator-fee reward. PPS accrual math
+  and stratum username validation are the same as `pps`.
+
+In `pps-classic` mode the stratum server:
+- Validates usernames as Thunder addresses (as `pps` does now).
+- Renders one coinbase, identical for every miner, paying
+  `pool_btc_address` for `value - fee` and `operator_address` for
+  `fee`. No OP_DRIVECHAIN output; no OP_RETURN destination.
+- Accrues `difficulty × pps_sats_per_diff` to each worker's
+  `pps_credits.accrued_sats` (unchanged).
+
+### 2. New config keys
+
+Add to `proxy.conf`:
+
+```
+pool_mode = pps-classic
+
+# Where mined BTC lands. Should be a wallet the operator controls
+# and that has enough age/maturity for later deposit-tx use.
+pool_btc_address = bc1q...
+
+# Everything else — pps_sats_per_diff, operator_address, fee_bps —
+# behaves exactly as in pps mode. pool_thunder_reserve_address is
+# ignored in this mode (deposits go via the admin dashboard, not
+# the coinbase).
+```
+
+### 3. New coinbase builder
+
+`src/coinbase.c`: `coinbase_build_split` already emits
+`[pool_btc_p2wpkh, operator_fee, witness_commit]` — that IS the
+classic-mode layout. No new builder required. Just call it with
+`miner_address = pool_btc_address` in `stratum.c`.
+
+The `_drivechain*` builders stay in the codebase (they still power
+`pool_mode = pps` for shape validation), but aren't reached in
+classic mode.
+
+### 4. New database table
+
+`deposits` — one row per operator-triggered Thunder deposit:
+
+```sql
+CREATE TABLE IF NOT EXISTS deposits (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts            INTEGER NOT NULL,           -- unix seconds
+  btc_txid      TEXT    NOT NULL,           -- mainchain deposit tx
+  sats_deposited INTEGER NOT NULL,
+  fee_sats      INTEGER NOT NULL,
+  thunder_recipient TEXT NOT NULL,          -- deposit-format address
+  ctip_seq_before INTEGER,                  -- for audit trail
+  ctip_seq_after  INTEGER,
+  notes         TEXT
+);
+CREATE INDEX IF NOT EXISTS deposits_ts_idx ON deposits(ts);
+```
+
+### 5. New admin controls
+
+Extend `dashboard/views/admin.ejs` and `dashboard/server.js` with a
+new **"Deposit to Thunder"** card:
+
+- Shows: `pool_btc_address` current spendable balance (via bitcoind
+  `getreceivedbyaddress` or a lightweight scan), amount already
+  waiting on-chain vs already deposited (from `deposits` table).
+- **POST /admin/deposit** — form fields: `amount_sats`, `fee_sats`.
+  Server calls the enforcer's gRPC
+  `WalletService/CreateDepositTransaction` with the pool's Thunder
+  reserve address as the destination. On success, `INSERT INTO
+  deposits` + refresh reserve balance.
+- All controls require the same basic auth as the read-only admin
+  view; CSRF protection via a per-session token (or an
+  `Origin`-header check for simplicity).
+
+### 6. New operator-facing docs
+
+- Update `PPS_THUNDER.md` with a subsection pointing at this file for
+  the classic-mode alternative.
+- Update `payout/README.md` — noting that in classic mode the reserve
+  is filled manually via the admin, not automatically via coinbase.
+
+## Migration story on the live server
+
+None required. `pps-thunder-classic` is a config change and a coinbase-
+builder swap on the same binary:
+
+```sh
+# on the forknet box, once this branch merges to main deployment:
+sed -i 's/^pool_mode = pps/pool_mode = pps-classic/' proxy.conf
+echo 'pool_btc_address = bc1q...' >> proxy.conf   # pool's BTC wallet
+systemctl restart simplepool.service
+```
+
+Existing `pps_credits` accruals carry over. In-flight ledger keeps
+working. Miners don't reconnect (stratum username is still a Thunder
+address).
+
+## What's NOT in this branch yet
+
+This branch currently contains only:
+- **this doc**,
+- a placeholder in `src/config.h` marked TODO for the new
+  `pool_mode` value,
+- a placeholder `deploy/schema/deposits.sql` with the deposits table
+  SQL.
+
+The actual C changes (config parser, stratum coinbase-render branch),
+the SQL wiring in `src/store.c`, the admin dashboard controls, and
+the gRPC client for the enforcer's `CreateDepositTransaction` are
+open work. When you're ready to build it, this doc is the blueprint.
+
+## Why do the design first
+
+Because the interesting decisions are all in the deposit-flow shape,
+not the code. Locking in:
+
+- **Manual vs auto deposits.** This design says manual (operator
+  clicks a button per deposit). An auto-batching worker is a later
+  improvement — no schema change required, just a new service that
+  posts to `/admin/deposit`.
+- **One pool BTC address vs many.** One is simpler and matches how
+  drivechain-launcher wallets typically hold funds. Migrating to a
+  rolling set of addresses is a follow-up.
+- **How much precision on the deposit fee.** Locked to
+  `enforcer.WalletService.CreateDepositTransaction`'s `fee_sats`
+  field. Operator eyeballs current fee market and picks a number.