PMM soak grid: fund-grid progress/ERR trap, complete-grid START_LEG and timing, tranche RPC override, grid funding doc

- pmm-soak-operator-fund-grid: PMM_SOAK_FUND_PROGRESS_EVERY, ERR trap, help text comments only - pmm-soak-complete-grid-funding-operator: PMM_SOAK_START_LEG resume, per-leg and total wall time - pmm-soak-operator-fund-full-grid-tranches: PMM_SOAK_RPC_URL_OVERRIDE, bash --noprofile --norc, manual hint - pmm-soak-mint-mirror-usdc-deployer-shortfall: ASCII-only operator messages - CHAIN138_GRID_6534_WALLET_FUNDING_PLAN: full-grid orchestrator, env vars, log markers Made-with: Cursor
2026-04-11 20:56:40 -07:00
parent c6c57fa585
commit dc8abb06e2
5 changed files with 943 additions and 0 deletions
--- a/docs/11-references/CHAIN138_GRID_6534_WALLET_FUNDING_PLAN.md
+++ b/docs/11-references/CHAIN138_GRID_6534_WALLET_FUNDING_PLAN.md
@@ -0,0 +1,158 @@
+# Chain 138 — Funding plan for 33×33×6 (6,534) PMM soak grid wallets
+
+**Purpose:** Separate the **operator (deployer)** role from the **6,534 grid EOAs**, summarize how to fund native gas and ERC-20 inventory for soak activity, and give **order-of-magnitude budgets** with formulas.  
+**Companion:** [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md](DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md) (deployer liquidity / reserve split).  
+**Automation:** `scripts/deployment/pmm-soak-operator-fund-grid.sh` (`--native` or ERC-20), `scripts/deployment/pmm-soak-export-wallet-grid.py`, `scripts/deployment/chain138-pmm-soak-grid-bot.sh`, smoke `scripts/deployment/pmm-soak-grid-smoke-check.sh`, **one-shot** `scripts/deployment/pmm-soak-complete-operator-bootstrap.sh` (creates `~/.secure-secrets/chain138-pmm-soak-grid.mnemonic` when `PMM_SOAK_AUTO_INIT_GRID_MNEMONIC=1`, exports 6,534 addresses to `config/pmm-soak-wallet-grid.json`, optional `--apply-funds --to-linear N`), **full-grid resume** `scripts/deployment/pmm-soak-complete-grid-funding-operator.sh` (waits chain + deployer nonce, mirror-USDC mint shortfall, native + four ERC-20 legs in chunks; env `PMM_SOAK_START_LEG`, `PMM_SOAK_RESUME_NATIVE_FROM_LINEAR`, `PMM_SOAK_RPC_URL_OVERRIDE`), and **`scripts/deployment/pmm-soak-operator-fund-full-grid-tranches.sh`** (same legs as tranche loops; same RPC override pattern). **CI:** `.github/workflows/pmm-soak-grid-smoke.yml` runs the smoke script on `CI=true` with public read-only RPC when `RPC_URL_138` is unset.  
+**Pool narrowing:** `scripts/lib/pmm-soak-pools.sh` (`PMM_SOAK_POOL_PRESET`, `PMM_SOAK_POOLS_FILE`).  
+**Swap execution:** `scripts/lib/pmm-soak-chain138-tick.sh` defaults to **`CHAIN138_PMM_SOAK_SWAP_VIA=pool`** (EOA `transfer` into the DVM + `sellBase` / `sellQuote`). On this chain, `DODOPMMIntegration.swapExactIn` reverts inside the pool when the integration contract is `msg.sender`; set `CHAIN138_PMM_SOAK_SWAP_VIA=integration` only if you have confirmed that path on your RPC.  
+**Dotenv vs shell:** Root `.env` is loaded inside soak scripts; `scripts/lib/pmm-soak-dotenv-override.sh` restores **`PMM_SOAK_POOL_PRESET`**, **`PMM_SOAK_POOLS`**, **`PMM_SOAK_POOLS_FILE`**, **`CHAIN138_PMM_SOAK_SWAP_VIA`**, and **`RPC_URL_138`** (plus `CHAIN138_RPC_URL` / `CHAIN138_RPC` after restore) from the parent shell when set before launch — used by `chain138-pmm-soak-grid-bot.sh`, `chain138-pmm-random-soak-swaps.sh`, `pmm-soak-operator-fund-grid.sh`, `pmm-soak-complete-grid-funding-operator.sh`, `pmm-soak-operator-fund-full-grid-tranches.sh`, and `pmm-soak-complete-operator-bootstrap.sh`. Alternatively pass **`--pool-preset <name>`** or **`--swap-via pool|integration`** on the bot CLI (CLI wins over dotenv for preset and clears `PMM_SOAK_POOLS*` so the preset applies).
+
+---
+
+## 1. Two different key systems (do not confuse them)
+
+| Role | Keys | Address source | Typical use |
+|------|------|----------------|-------------|
+| **Operator / deployer** | `PRIVATE_KEY` / `DEPLOYER_PRIVATE_KEY` in `.env` | Single EOA | Funds grid wallets (native + ERC-20), operations, liquidity (see deployer funding plan doc) |
+| **Grid (6,534 wallets)** | **`PMM_SOAK_GRID_MNEMONIC`** (BIP39), separate from deployer | HD path `m/44'/60'/0'/0/{linearIndex}` with `linearIndex = lpbca×198 + branch×6 + class` | Sign PMM swaps (and optional inter-wallet transfers) in the soak bot |
+
+- The **deployer** is **not** derived from the grid mnemonic unless you intentionally use the same seed (not recommended).
+- Export **public** addresses only: `PMM_SOAK_GRID_MNEMONIC='…' python3 scripts/deployment/pmm-soak-export-wallet-grid.py --out config/pmm-soak-wallet-grid.json` — keep that JSON **local** (gitignored pattern in `.gitignore`).
+
+---
+
+## 2. Deployer (operator) — review and snapshot
+
+**Canonical address:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`  
+**Explorer:** https://explorer.d-bis.org/address/0x4A666F96fC8764181194447A7dFdb7d471b301C8  
+
+**Point-in-time read (LAN Core RPC `http://192.168.11.211:8545`, 2026-04-10):**
+
+| Asset | Raw (integer) | Human (approx.) |
+|-------|-----------------|-----------------|
+| Native | `989399835388702020921911788` wei | ~989,400 ETH nominal units (18 decimals) — private chain genesis style |
+| cUSDT `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | `688280049090000` | ~688.28M units (6 decimals) |
+| cUSDC `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | `689514099298585` | ~689.51M units (6 decimals) |
+
+Re-check before funding:
+
+```bash
+source scripts/lib/load-project-env.sh
+D=0x4A666F96fC8764181194447A7dFdb7d471b301C8
+cast balance "$D" --rpc-url "${RPC_URL_138:-http://192.168.11.211:8545}"
+cast call 0x93E66202A11B1772E55407B32B44e5Cd8eda7f22 'balanceOf(address)(uint256)' "$D" --rpc-url "$RPC_URL_138"
+cast call 0xf22258f57794CC8E06237084b353Ab30fFfa640b 'balanceOf(address)(uint256)' "$D" --rpc-url "$RPC_URL_138"
+```
+
+The deployer holds **large** stable inventory relative to typical per-wallet soak seeds; still treat **grid funding** as a **budgeted** draw (tranches), not an implicit unlimited tap.
+
+---
+
+## 3. Grid wallets (6,534) — what each needs
+
+### 3.1 Native (gas)
+
+Grid wallets must pay **legacy** gas for:
+
+- `approve` (when allowance &lt; swap amount) on the sold token  
+- `DODOPMMIntegration.swapExactIn`  
+- Optional `ERC20.transfer` if you enable inter-wallet flow (`PMM_SOAK_TRANSFER_*`)
+
+On Chain 138, `CHAIN138_DEPLOY_GAS_PRICE_WEI` is often **1000 wei** per gas unit (see deployment scripts). Cost per swap is **small in wei terms**, but **6,534 wallets × many swaps** adds up if native per wallet is set too high.
+
+**Suggested starting native per wallet (order of magnitude):**
+
+| Scenario | `NATIVE_AMOUNT_WEI` (per wallet) | Notes |
+|----------|----------------------------------|--------|
+| Smoke (few ticks) | `5e15` – `2e16` wei (0.005 – 0.02 ETH units) | Enough for multiple approve+swap paths at low gas price |
+| Sustained soak | `2e16` – `5e16` wei | Raise if you see OOG or heavy revert churn |
+| **Do not** blindly max-fund all 6,534 without a tranche plan | — | Operator native spend + recipient inventory must stay bounded |
+
+**Operator overhead (native):** Each funding tx is a native transfer from the deployer; budget **deployer native** for:
+
+- **Sum to recipients:** `6,534 × NATIVE_AMOUNT_WEI`  
+- **Funding transaction gas:** roughly `21_000 × gasPrice × 6,534` (plus buffer for retries). With `gasPrice = 1000` wei, this term is on the order of **1.4×10^11 wei** total — negligible next to recipient amounts unless `NATIVE_AMOUNT_WEI` is tiny.
+
+Use **slices** to limit blast radius:
+
+```bash
+PMM_SOAK_GRID_JSON=config/pmm-soak-wallet-grid.json NATIVE_AMOUNT_WEI=20000000000000000 \
+  bash scripts/deployment/pmm-soak-operator-fund-grid.sh --native --from-linear 0 --to-linear 199
+# dry-run first; then --apply
+```
+
+### 3.2 ERC-20 (swap inventory)
+
+Soak sizes default to **random USD face** between `PMM_SOAK_USD_MIN` / `PMM_SOAK_USD_MAX` (default 1,000–100,000 USD) expressed as **6-decimal** units for stables (`amount ≈ USD × 10^6`). A wallet must hold **at least** the token it sells each tick (often **cUSDT** or **cUSDC** on stable presets), plus gas.
+
+**Pool preset drives which tokens matter** (`PMM_SOAK_POOL_PRESET`):
+
+| Preset | Pools (count) | Primary inventory to fund |
+|--------|----------------|---------------------------|
+| `cusdt-cusdc` | 1 | cUSDT and/or cUSDC (both sides of pool) |
+| `stable` / `stable-mirrors` | 3 | cUSDT, cUSDC, mirror **USDT** / **USDC** as needed for sell side |
+| `xau-*` | XAU pairs | cUSDT/cUSDC/cEURT + cXAUC/cXAUT per pool (see [ADDRESS_MATRIX_AND_STATUS](ADDRESS_MATRIX_AND_STATUS.md)) |
+
+**Conservative per-wallet ERC-20 seed (example):**  
+`AMOUNT_WEI_PER_WALLET=500000000` (**500 USDT** face at 6 decimals: `500 × 10^6`) for **stable-only** testing — increase only after observing quote success rates.
+
+**Total ERC-20 to grid (single token, uniform):**  
+`6,534 × AMOUNT_WEI_PER_WALLET` raw — must be **≤ deployer balance** of that token (minus reserves for other ops). Example: 500 USDT per wallet → **~3.27M USDT** face total if all 6,534 wallets are funded equally.
+
+---
+
+## 4. Automated smoke check (no secrets on disk)
+
+From repo root (uses a **public test mnemonic** and **dry-run only**; removes temp JSON after):
+
+```bash
+bash scripts/deployment/pmm-soak-grid-smoke-check.sh
+```
+
+Override: `PMM_SOAK_GRID_SMOKE_MNEMONIC='twelve words…'` (still dry-run). For a **partial export** of real addresses:  
+`PMM_SOAK_GRID_MNEMONIC='…' python3 scripts/deployment/pmm-soak-export-wallet-grid.py --out config/pmm-soak-wallet-grid.json --count 100`
+
+---
+
+## 5. Recommended phased funding (6,534 wallets)
+
+1. **Export addresses** to `config/pmm-soak-wallet-grid.json` (local only).  
+2. **Narrow pools:** `PMM_SOAK_POOL_PRESET=stable` or `cusdt-cusdc` until healthy quotes.  
+3. **Phase A — native:** Fund **linear ranges** in batches (e.g. 0–199, 200–399, …); dry-run then `--apply`.  
+4. **Phase B — ERC-20:** Same batching; start with **one** token (e.g. cUSDT) aligned with your preset’s sell-side testing.  
+5. **Phase C — bot:** `chain138-pmm-soak-grid-bot.sh --dry-run`, then `--apply` with `PMM_SOAK_LINEAR_MIN` / `MAX` restricted before full 0–6533.  
+6. **Monitor:** deployer native + cUSDT/cUSDC balances; grid wallet balances via explorer or scripted `cast balance` / `balanceOf` samples.  
+7. **Full-grid resume (optional):** `bash scripts/deployment/pmm-soak-complete-grid-funding-operator.sh --dry-run` then `--apply`. For long runs from a host where LAN Core RPC may flap, set `PMM_SOAK_RPC_URL_OVERRIDE=https://rpc-http-pub.d-bis.org` (or another stable endpoint). To skip native when every wallet is already funded, set `PMM_SOAK_RESUME_NATIVE_FROM_LINEAR=6534` (above max linear `6533`). To resume after a partial leg, set `PMM_SOAK_START_LEG` to one of `native`, `mint`, `cusdt`, `cusdc`, `mirr_usdt`, `mirr_usdc` — earlier legs are skipped; you must already satisfy deployer balances and on-chain state for those legs. Chunk progress and ETA during apply: `PMM_SOAK_FUND_PROGRESS_EVERY` on `pmm-soak-operator-fund-grid.sh` (default `50`, use `0` for quiet except the last line per chunk). Example background log: `nohup env PMM_SOAK_RPC_URL_OVERRIDE=… bash scripts/deployment/pmm-soak-complete-grid-funding-operator.sh --apply >> /tmp/pmm-soak-complete-grid-lan.log 2>&1 &` — completion lines: `[complete] total apply wall_s=… (after waits)` then `[complete] all legs finished (apply=1)`.
+
+---
+
+## 6. Budget table (illustrative totals)
+
+Let `N = 6,534`, `g = NATIVE_AMOUNT_WEI`, `a = AMOUNT_WEI_PER_WALLET` (one token).
+
+| Item | Formula |
+|------|---------|
+| Native to grid | `N × g` |
+| One-token ERC-20 to grid | `N × a` |
+| Deployer funding txs gas (native, order of mag.) | `≈ N × 21_000 × gasPrice` |
+
+Example: `g = 2e16` wei (0.02 ETH per wallet) → native to grid ≈ `6,534 × 0.02 ≈ 131` ETH nominal (plus deployer gas for funding txs).  
+Example: `a = 500_000_000` raw (**500 USDT** face per wallet) → **~3.27×10^12** raw units total for that token if every wallet gets the same `a`.
+
+---
+
+## 7. References
+
+| Doc / script | Use |
+|--------------|-----|
+| [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md](DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md) | Deployer liquidity / 50% rule for pools |
+| [ADDRESS_MATRIX_AND_STATUS.md](ADDRESS_MATRIX_AND_STATUS.md) | PMM pool + token addresses |
+| `scripts/deployment/pmm-soak-operator-fund-grid.sh` | Batch fund native or ERC-20 |
+| `scripts/deployment/pmm-soak-complete-grid-funding-operator.sh` | One-shot resume: wait chain + nonce, mint mirror-USDC shortfall, native + four ERC-20 legs (`PMM_SOAK_START_LEG`, `PMM_SOAK_RESUME_NATIVE_FROM_LINEAR`, `PMM_SOAK_RPC_URL_OVERRIDE`) |
+| `scripts/deployment/pmm-soak-operator-fund-full-grid-tranches.sh` | Same funding legs as explicit tranche loops (RPC override + `bash --noprofile --norc` into fund-grid) |
+| `scripts/lib/pmm-soak-pools.sh` | Narrow pool sets |
+| `scripts/deployment/chain138-pmm-soak-grid-bot.sh` | Grid soak runner |
+
+---
+
+**Disclaimer:** Soak bots spend **real gas and tokens** on chain. Cap tranches, use dry-run, and align `PMM_SOAK_USD_*` with funded balances.