primecli 0.10.0__tar.gz → 0.10.2__tar.gz

{primecli-0.10.0 → primecli-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: primecli
-Version: 0.10.0
+Version: 0.10.2
 Summary: Agent-friendly CLI tools for the DeltaPrime (Avalanche + Arbitrum) and DegenPrime (Base) lending and leverage protocols. Preview-by-default; no Etherscan key required.
 Author: Mnemosyne-quest contributors
 License: MIT
@@ -47,7 +47,7 @@ Built for agent use:
 - RedStone-signed solvency math handled internally, with a regression test pinning the half-boundary `toFixed(8)` encoding.
 - ParaSwap calldata validated client-side against the on-chain executor allowlist before broadcast.
 
-**Current version:** 0.10.0 The 0.x line is pre-1.0, so breaking changes are possible. See [Releases](https://github.com/Mnemosyne-quest/primecli/releases).
+**Current version:** 0.10.2 The 0.x line is pre-1.0, so breaking changes are possible. See [Releases](https://github.com/Mnemosyne-quest/primecli/releases).
 
 > **Breaking change in 0.5.0:** there is no longer a default signing key. Earlier versions silently fell back to a baked-in agent when no key was configured; that fallback has been removed. With no key configured, every command now fails closed with `No signing key found...`. Set a key explicitly (see [Configuration](#configuration)).
 

{primecli-0.10.0 → primecli-0.10.2}/README.md

@@ -16,7 +16,7 @@ Built for agent use:
 - RedStone-signed solvency math handled internally, with a regression test pinning the half-boundary `toFixed(8)` encoding.
 - ParaSwap calldata validated client-side against the on-chain executor allowlist before broadcast.
 
-**Current version:** 0.10.0 The 0.x line is pre-1.0, so breaking changes are possible. See [Releases](https://github.com/Mnemosyne-quest/primecli/releases).
+**Current version:** 0.10.2 The 0.x line is pre-1.0, so breaking changes are possible. See [Releases](https://github.com/Mnemosyne-quest/primecli/releases).
 
 > **Breaking change in 0.5.0:** there is no longer a default signing key. Earlier versions silently fell back to a baked-in agent when no key was configured; that fallback has been removed. With no key configured, every command now fails closed with `No signing key found...`. Set a key explicitly (see [Configuration](#configuration)).
 

primecli-0.10.2/primecli/_flowledger.py

@@ -0,0 +1,172 @@
+"""Live external-flow ledger appends for the PnL flow ledgers.
+
+Going-forward counterpart to scripts/pnl_backfill.py (which reconstructs history
+by scanning Diamond event logs). When a fund or withdrawal-execute broadcast
+succeeds, the calling tool appends one record here so the flow is captured at the
+moment it happens — no rescan of the chain needed later. Borrow/repay and
+internal swaps/rebalances are NOT flows (they don't cross the account boundary);
+only the fund/withdraw paths call in (methodology: docs/yield-pnl-methodology.md §3).
+
+The record schema and the `<chain>__<account.lower()>.jsonl` file naming are
+IDENTICAL to what pnl_backfill writes, so pnlctl and the backfill consume one
+shared ledger. Records carry: ts(int), type("deposit"|"withdraw"), asset(str),
+token_amount(float), usd_value(float|None), tx(str), block(int), source(str),
+and an optional log_index(int) — omitted for live appends (a broadcast tx has no
+single log index to attribute the flow to; the backfill fills it from getLogs).
+
+FAILURE-ISOLATED BY CONTRACT: append_flow never raises. A logging error must not
+fail a financial operation, so every path catches and downgrades to a stderr
+warning. The caller wraps the call defensively too — belt and suspenders.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+DEFAULT_FLOW_LEDGER_DIR = "/root/defi-sims/state/flow-ledgers"
+
+
+def _ledger_dir(ledger_dir=None) -> Path:
+    if ledger_dir:
+        return Path(ledger_dir)
+    return Path(os.environ.get("FLOW_LEDGER_DIR", DEFAULT_FLOW_LEDGER_DIR))
+
+
+def ledger_path(chain: str, account: str, ledger_dir=None) -> Path:
+    """Path to the JSONL ledger for (chain, account). The account is lowercased so
+    the filename matches pnl_backfill's `<chain>__<account.lower()>.jsonl`."""
+    return _ledger_dir(ledger_dir) / f"{chain}__{account.lower()}.jsonl"
+
+
+def _dedupe_key(rec: dict) -> tuple:
+    """Identity of a live flow for idempotency: (tx, asset, type). A single fund or
+    withdrawal-execute broadcast moves one asset in one direction, so this uniquely
+    keys it without needing a log_index (which live appends don't carry)."""
+    return (rec.get("tx"), rec.get("asset"), rec.get("type"))
+
+
+def append_flow(chain: str, account: str, record: dict, ledger_dir=None) -> bool:
+    """Append `record` to the (chain, account) flow ledger, idempotently.
+
+    Dedupes on (tx, asset, type): if a record with the same key is already present,
+    nothing is written (safe to call twice for the same broadcast). Creates the
+    ledger directory if missing and keeps the file sorted ascending by ts.
+
+    NEVER raises — any IO/serialisation error is swallowed with a stderr warning and
+    returns False. Returns True if a new record was written, False otherwise (already
+    present, or an error was swallowed).
+    """
+    try:
+        path = ledger_path(chain, account, ledger_dir)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing: list[dict] = []
+        if path.exists():
+            for line in path.read_text().splitlines():
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    existing.append(json.loads(line))
+                except json.JSONDecodeError:
+                    print(f"  WARN flowledger: skipping malformed line in {path}",
+                          file=sys.stderr)
+
+        key = _dedupe_key(record)
+        if any(_dedupe_key(r) == key for r in existing):
+            return False  # already logged this flow — idempotent no-op
+
+        merged = existing + [record]
+        merged.sort(key=lambda r: (r.get("ts", 0), r.get("block", 0)))
+
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text("\n".join(json.dumps(r) for r in merged) + "\n")
+        tmp.replace(path)
+        return True
+    except Exception as e:  # noqa: BLE001 — logging must NEVER break the caller
+        print(f"  WARN flowledger: failed to append flow ({type(e).__name__}: {e})",
+              file=sys.stderr)
+        return False
+
+
+# ERC20 Transfer(address,address,uint256) event topic (keccak of the signature).
+# Hardcoded so this module stays web3-free (it only does JSONL IO otherwise).
+_ERC20_TRANSFER_TOPIC = (
+    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+)
+
+
+def _to_hex(v) -> str:
+    """Normalise a web3 HexBytes / bytes / str to a 0x-prefixed lowercase hex string."""
+    h = v.hex() if hasattr(v, "hex") else str(v)
+    h = h.lower()
+    return h if h.startswith("0x") else "0x" + h
+
+
+def _norm_addr(v) -> str:
+    """Last-20-bytes address as 0x-prefixed lowercase (handles 32-byte padded topics
+    and 20-byte log addresses alike)."""
+    return "0x" + _to_hex(v)[2:][-40:]
+
+
+def transferred_amount(receipt, token_addr: str, from_addr: str, to_addr: str,
+                       decimals: int):
+    """Real ERC20 amount moved `from_addr` -> `to_addr` in `token_addr` within this
+    receipt, in human units (raw / 10**decimals). Sums all matching Transfer logs.
+
+    Returns None when the receipt carries NO matching Transfer log at all — the caller
+    then falls back to the requested amount (can't determine the truth). A matching
+    Transfer of value 0 returns 0.0 (the fund pulled nothing), NOT None.
+
+    This is the truth source for a fund flow: `fund(asset, amount)` can pull LESS than
+    `amount` when the wallet's balance/allowance is short — e.g. a leverage-open where
+    most of the position is borrowed, so the EOA only holds dust. Logging the requested
+    arg then over-counts contribution and corrupts every downstream PnL/ROI/APR. Parsing
+    the actual on-chain Transfer fixes that at the source.
+    """
+    try:
+        token = _norm_addr(token_addr)
+        frm = _norm_addr(from_addr)
+        to = _norm_addr(to_addr)
+        total_raw = 0
+        found = False
+        for log in receipt["logs"]:
+            if _norm_addr(log["address"]) != token:
+                continue
+            topics = log["topics"]
+            if len(topics) != 3 or _to_hex(topics[0]) != _ERC20_TRANSFER_TOPIC:
+                continue
+            if _norm_addr(topics[1]) != frm or _norm_addr(topics[2]) != to:
+                continue
+            total_raw += int(_to_hex(log["data"]), 16)
+            found = True
+        if not found:
+            return None
+        return total_raw / (10 ** decimals)
+    except Exception as e:  # noqa: BLE001 — never break the caller over a parse error
+        print(f"  WARN flowledger: transfer parse failed ({type(e).__name__}: {e})",
+              file=sys.stderr)
+        return None
+
+
+def make_record(*, ts: int, ftype: str, asset: str, token_amount: float,
+                usd_value, tx: str, block: int, source: str) -> dict:
+    """Build a ledger record with exactly the keys pnl_backfill writes (minus the
+    optional log_index, which live appends omit). Centralised so the three tools
+    construct byte-identical records."""
+    # web3.py 7.x HexBytes.hex() drops the 0x prefix; pnl_backfill normalises tx hashes
+    # to a 0x-prefixed string, so do the same here or the (tx, …) dedupe would never
+    # match a backfilled record for the same tx.
+    if tx and not tx.startswith("0x"):
+        tx = "0x" + tx
+    return {
+        "ts": int(ts),
+        "type": ftype,
+        "asset": asset,
+        "token_amount": float(token_amount),
+        "usd_value": (None if usd_value is None else float(usd_value)),
+        "tx": tx,
+        "block": int(block),
+        "source": source,
+    }

primecli-0.10.2/primecli/_wallets.py

@@ -0,0 +1,125 @@
+"""Shared named-wallet key resolution for the primecli siblings.
+
+Single source of truth for the agent→(env_file, var) secrets map and the
+helpers that read a private key out of it. degenprime and the bridge command
+import from here so the map is defined once; deltaprime/arbprime carry their own
+historical copies (kept for now to stay surgical — see the note below).
+
+Security: never log or echo the values these helpers return. They are raw
+private keys.
+"""
+
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# HD wallet derivation from a BIP39 seed file.
+# The seed file is a plaintext mnemonic with tight permissions (chmod 600).
+# The derivation functions NEVER log or print the mnemonic.
+# ---------------------------------------------------------------------------
+
+_HD_DERIVE_CACHE = {}
+
+
+def _ensure_hd_libs():
+    """Lazy-import HD derivation libs. Never echoes the seed."""
+    global _HD_DERIVE_CACHE
+    if "mnemonic" not in _HD_DERIVE_CACHE:
+        from mnemonic import Mnemonic
+        from bip32 import BIP32
+        _HD_DERIVE_CACHE["mnemonic"] = Mnemonic
+        _HD_DERIVE_CACHE["BIP32"] = BIP32
+
+
+def _derive_private_key(seed_path: str, derivation_path: str) -> str:
+    """
+    Read the BIP39 seed file and derive the private key at `derivation_path`.
+    NEVER logs or returns the mnemonic.
+    """
+    _ensure_hd_libs()
+    Mnemonic = _HD_DERIVE_CACHE["mnemonic"]
+    BIP32 = _HD_DERIVE_CACHE["BIP32"]
+
+    raw = Path(seed_path).read_text().strip()
+    if not raw:
+        raise RuntimeError(f"Seed file {seed_path} is empty")
+    words = raw.split()
+    if len(words) not in (12, 15, 18, 21, 24):
+        raise RuntimeError(
+            f"Seed file {seed_path} has {len(words)} words; expected 12-24"
+        )
+
+    mnemo = Mnemonic("english")
+    if not mnemo.check(raw):
+        raise RuntimeError(f"Seed file {seed_path} contains an invalid mnemonic (checksum fail)")
+
+    seed = mnemo.to_seed(raw)
+    bip = BIP32.from_seed(seed)
+    privkey = bip.get_privkey_from_path(derivation_path)
+    return privkey.hex()
+
+
+# ---------------------------------------------------------------------------
+# Agent / wallet registry
+#
+# Tuple formats:
+#   (env_path, env_var)           — raw key from env file (existing)
+#   (seed_path, None, deriv_path) — HD-derived from seed file
+# The third element (None vs deriv_path) distinguishes the two modes.
+# ---------------------------------------------------------------------------
+
+AGENTS = {
+    # Raw key entries (from env files)
+    "parakletos":   ("/root/.openclaw/.env",                "PARAKLETOS_EVM_PRIVATE_KEY"),
+    "paraklaudios": ("/root/paraklaudios/.credentials.env", "PARAKLAUDIOS_EVM_PRIVATE_KEY"),
+    "core1":        ("/root/.openclaw/.env",                "BRUNO_CORE1_PRIVATE_KEY"),
+
+    # HD seed-derived entries (from Parakletos's BIP39 seed)
+    "parakletos-2": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/0"),
+    "parakletos-3": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/1"),
+    "parakletos-4": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/2"),
+    "parakletos-5": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/3"),
+    "parakletos-6": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/4"),
+    "parakletos-7": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/1'/0/0"),
+    "parakletos-8": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/2'/0/0"),
+}
+
+HD_AGENTS = {name for name, entry in AGENTS.items() if len(entry) == 3 and entry[1] is None}
+
+
+def _read_env_var(path, var):
+    """Return the value of `var` from a KEY=VALUE env file, or None if absent."""
+    try:
+        for line in Path(path).read_text().splitlines():
+            s = line.strip()
+            if s.startswith(var + "="):
+                return s.split("=", 1)[1].strip().strip('"').strip("'")
+    except FileNotFoundError:
+        return None
+    return None
+
+
+def _agent_key(agent):
+    if agent not in AGENTS:
+        raise RuntimeError(
+            f"Unknown agent '{agent}'. Known agents: {', '.join(AGENTS)}. "
+            f"Or set DEGENPRIME_PRIVATE_KEY, or DEGENPRIME_KEY_FILE."
+        )
+    entry = AGENTS[agent]
+
+    # HD wallet derivation
+    if len(entry) == 3 and entry[1] is None:
+        seed_path, _, deriv_path = entry
+        try:
+            return _derive_private_key(seed_path, deriv_path)
+        except RuntimeError as e:
+            # Re-raise with the agent name for context, but never leak the seed
+            raise RuntimeError(
+                f"Failed to derive key for agent '{agent}' (deriv_path={deriv_path}): {e}"
+            ) from e
+
+    # Raw key from env file (existing logic)
+    path, var = entry
+    key = _read_env_var(path, var)
+    if not key:
+        raise RuntimeError(f"{var} not found in {path} (agent '{agent}').")
+    return key

{primecli-0.10.0 → primecli-0.10.2}/primecli/arbprime.py

@@ -20,6 +20,7 @@ Usage:
   arbprime create-prime-account --fund-pool usdc --fund-amount 100 [--execute]
   arbprime prime-summary
   arbprime defi --json          (aggregate ALL positions as DeBank-style JSON; read-only)
+  arbprime equity [--json] [--account 0x..]   (net equity = total value - debt + unclaimed rewards; read-only)
   arbprime fund --pool usdc --amount 100 [--execute]
   arbprime borrow --pool usdc --amount 100 [--execute]
   arbprime repay --pool usdc --amount 100 [--execute]
@@ -208,6 +209,7 @@ from eth_account import Account
 from eth_keys import keys as eth_keys
 from eth_abi import encode as abi_encode, decode as abi_decode
 from web3 import Web3
+from primecli import _flowledger
 
 # Health monitoring sub-system
 # Try both package import (installed) and local import (standalone script)
@@ -256,9 +258,52 @@ ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
 # If none resolve, fail closed (no silent default key).
 #
 # To add another wallet: add a row to AGENTS, export ARBPRIME_PRIVATE_KEY, or pass --key.
+
+# ---------------------------------------------------------------------------
+# HD wallet derivation from a BIP39 seed file.
+# The seed file is a plaintext mnemonic with tight permissions (chmod 600).
+# The derivation functions NEVER log or print the mnemonic.
+# ---------------------------------------------------------------------------
+_HD_DERIVE_CACHE = {}
+def _ensure_hd_libs():
+    global _HD_DERIVE_CACHE
+    if "mnemonic" not in _HD_DERIVE_CACHE:
+        from mnemonic import Mnemonic
+        from bip32 import BIP32
+        _HD_DERIVE_CACHE["mnemonic"] = Mnemonic
+        _HD_DERIVE_CACHE["BIP32"] = BIP32
+def _derive_private_key(seed_path, derivation_path):
+    _ensure_hd_libs()
+    Mnemonic = _HD_DERIVE_CACHE["mnemonic"]
+    BIP32 = _HD_DERIVE_CACHE["BIP32"]
+    raw = Path(seed_path).read_text().strip()
+    if not raw:
+        raise RuntimeError(f"Seed file {seed_path} is empty")
+    words = raw.split()
+    if len(words) not in (12, 15, 18, 21, 24):
+        raise RuntimeError(f"Seed file {seed_path} has {len(words)} words; expected 12-24")
+    mnemo = Mnemonic("english")
+    if not mnemo.check(raw):
+        raise RuntimeError(f"Seed file {seed_path} contains an invalid mnemonic (checksum fail)")
+    seed = mnemo.to_seed(raw)
+    bip = BIP32.from_seed(seed)
+    privkey = bip.get_privkey_from_path(derivation_path)
+    return privkey.hex()
+# ---------------------------------------------------------------------------
+
 AGENTS = {
+    # Raw key entries (from env files)
     "parakletos":   ("/root/.openclaw/.env",                "PARAKLETOS_EVM_PRIVATE_KEY"),
     "paraklaudios": ("/root/paraklaudios/.credentials.env", "PARAKLAUDIOS_EVM_PRIVATE_KEY"),
+
+    # HD seed-derived entries (from Parakletos's BIP39 seed)
+    "parakletos-2": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/0"),
+    "parakletos-3": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/1"),
+    "parakletos-4": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/2"),
+    "parakletos-5": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/3"),
+    "parakletos-6": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/0'/0/4"),
+    "parakletos-7": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/1'/0/0"),
+    "parakletos-8": ("/root/.openclaw/workspace/config/wallet.seed", None, "m/44'/60'/2'/0/0"),
 }
 _SELECTED_AGENT = None        # set by the --as CLI flag in main()
 _CLI_KEY = None               # set by the --key CLI flag in main()
@@ -699,11 +744,17 @@ def _estimate_gas_limit(w3, tx_dict, fallback_gas: int, buffer_bps: int = 1250)
     Solvency-gated swap paths append RedStone payloads and can vary materially by
     route. A fixed cap can pass simulation at a high gas allowance, then revert
     out-of-gas on broadcast. If the RPC cannot estimate, keep the old fixed cap.
+
+    fallback_gas is a fallback for when estimation FAILS, not a floor that overrides a
+    good estimate. Flooring at e.g. 4M over-reserved gas_limit*maxFeePerGas upfront,
+    so a low-gas-balance wallet hit "insufficient funds for gas" even when the tx
+    itself simulated fine. A successful estimate is authoritative; the OOG retry in
+    _sign_and_send (+50% on gasUsed>=gasLimit) covers any under-estimate.
     """
     try:
         call_tx = {k: tx_dict[k] for k in ("from", "to", "data", "value") if k in tx_dict}
         estimated = int(w3.eth.estimate_gas(call_tx))
-        return max(int(fallback_gas), (estimated * int(buffer_bps) + 999) // 1000)
+        return (estimated * int(buffer_bps) + 999) // 1000
     except Exception:
         return int(fallback_gas)
 
@@ -741,7 +792,18 @@ def _agent_key(agent):
             f"Unknown agent '{agent}'. Known agents: {', '.join(AGENTS)}. "
             f"Or set ARBPRIME_PRIVATE_KEY, or ARBPRIME_ENV_FILE + ARBPRIME_KEY_VAR."
         )
-    path, var = AGENTS[agent]
+    entry = AGENTS[agent]
+    # HD wallet derivation (3-tuple with None in middle)
+    if len(entry) == 3 and entry[1] is None:
+        seed_path, _, deriv_path = entry
+        try:
+            return _derive_private_key(seed_path, deriv_path)
+        except RuntimeError as e:
+            raise RuntimeError(
+                f"Failed to derive key for agent '{agent}' (deriv_path={deriv_path}): {e}"
+            ) from e
+    # Raw key from env file (existing logic)
+    path, var = entry
     key = _read_env_var(path, var)
     if not key:
         raise RuntimeError(f"{var} not found in {path} (agent '{agent}').")
@@ -1903,8 +1965,51 @@ def cmd_fund(pool_name: str, amount: float, execute: bool = False):
         })
         receipt = _sign_and_send(w3, acct, fund_tx, f"Fund {amount} {symbol}", fallback_gas=3000000)
         ok = receipt["status"] == 1
+        if ok:
+            _log_fund_flow(
+                pa, symbol, amount, receipt,
+                token_addr=(None if cfg["native"] else cfg["token"]),
+                from_addr=acct.address, decimals=cfg["decimals"],
+            )
         return ok
 
+
+def _log_fund_flow(account_addr: str, symbol: str, amount: float, receipt,
+                   token_addr: str = None, from_addr: str = None,
+                   decimals: int = None) -> None:
+    """Append a 'deposit' flow record after a successful fund broadcast. asset is the
+    funded bytes32 symbol (the wrapped-native symbol for native funding, e.g. 'ETH').
+    usd_value uses the current spot price (≈ flow-time price); None when unpriced.
+    Wrapped so a logging failure can never fail the financial op.
+
+    Logs the ACTUAL ERC20 Transfer(EOA -> account) amount from the receipt, not the
+    requested `amount`: an ERC20 fund() can pull less than asked when the wallet is
+    short (leverage-opens fund mostly from borrow), and logging the request over-counts
+    contribution. Native funding moves the exact msg.value, so `amount` stands there
+    (token_addr is None)."""
+    try:
+        actual = amount
+        if token_addr and from_addr and decimals is not None:
+            moved = _flowledger.transferred_amount(
+                receipt, token_addr, from_addr, account_addr, decimals)
+            if moved is not None:
+                if abs(moved - amount) > max(1e-6, abs(amount) * 1e-4):
+                    print(f"  NOTE fund pulled {moved} {symbol} of {amount} requested "
+                          f"(logging actual)", file=sys.stderr)
+                actual = moved
+        px = token_price(symbol)
+        usd = round(actual * px, 8) if px else None
+        rec = _flowledger.make_record(
+            ts=int(time.time()), ftype="deposit", asset=symbol,
+            token_amount=actual, usd_value=usd,
+            tx=receipt["transactionHash"].hex(), block=receipt["blockNumber"],
+            source="live-fund",
+        )
+        _flowledger.append_flow("arbitrum", account_addr, rec)
+    except Exception as e:  # noqa: BLE001 — never fail the fund over logging
+        print(f"  WARN flow logging skipped ({type(e).__name__}: {e})", file=sys.stderr)
+
+
 def _prices_usd(w3, account, symbols: list, payload: bytes) -> dict:
     """Best-effort per-symbol USD price map via the RedStone-gated getPrices view (1e8-scaled).
     Reuses an already-built `payload`; returns {symbol: float}. Any symbol whose feed is
@@ -2293,6 +2398,80 @@ def cmd_prime_summary():
         print(f"  Health/solvency:    RedStone fetch/call failed ({data.get('solvency_error', 'error')}); "
               "showing balances only")
 
+def get_account_equity(account_addr: str = None) -> dict:
+    """Net equity of a Prime Account: total_value_usd - debt_usd + rewards_usd.
+
+    Read-only (eth_call only): reuses gather_lending for the RedStone-gated
+    getTotalValue/getDebt reads. `account_addr` targets a specific Prime Account; when
+    None it resolves the one owned by the --as / --owner wallet.
+
+    rewards_usd is 0.0 here: Arbitrum DeltaPrime has no separate unclaimed-reward
+    primitive in this tool (no sJOE — that is the Avalanche TraderJoe path; GMX/GLV
+    fees compound inside the LP and are already counted by getTotalValue). It stays in
+    the dict for cross-tool shape parity.
+
+    Returns {agent, chain, protocol, wallet, prime_account, total_value_usd, debt_usd,
+    rewards_usd, net_equity_usd, block, ts, status}. On any read error: status="error",
+    an `error` field, and the numeric fields set to None."""
+    base = {
+        "agent": _SELECTED_AGENT, "chain": "arbitrum", "protocol": "DeltaPrime",
+        "wallet": None, "prime_account": None,
+        "total_value_usd": None, "debt_usd": None, "rewards_usd": None,
+        "net_equity_usd": None, "block": None, "ts": int(time.time()), "status": "ok",
+    }
+    try:
+        w3 = get_w3()
+        acct = get_account()
+        base["wallet"] = acct.address
+        pa = account_addr or get_prime_account(w3, acct.address)
+        base["block"] = w3.eth.block_number
+        if not pa:
+            base["status"] = "no_account"
+            return base
+        pa = Web3.to_checksum_address(pa)
+        base["prime_account"] = pa
+        account = w3.eth.contract(address=pa, abi=PRIME_ACCOUNT_ABI)
+        lending = gather_lending(w3, account)
+        if "solvency_error" in lending or lending.get("total_value_usd") is None:
+            base["status"] = "error"
+            base["error"] = lending.get("solvency_error", "solvency read failed")
+            return base
+        total_value = lending["total_value_usd"]
+        debt = lending["debt_usd"]
+        rewards = 0.0
+        base["total_value_usd"] = round(total_value, 2)
+        base["debt_usd"] = round(debt, 2)
+        base["rewards_usd"] = round(rewards, 2)
+        base["net_equity_usd"] = round(total_value - debt + rewards, 2)
+        return base
+    except Exception as e:
+        base["status"] = "error"
+        base["error"] = f"{type(e).__name__}: {e}"
+        return base
+
+def cmd_equity(as_json: bool = False, account_addr: str = None):
+    """Print net equity for the selected wallet's Prime Account (read-only)."""
+    eq = get_account_equity(account_addr)
+    if as_json:
+        print(json.dumps(eq, indent=2))
+        return
+    print(f"Owner wallet: {eq['wallet']}")
+    if eq["status"] == "no_account":
+        print("No Prime Account yet. Create one with: arbprime create-prime-account --execute")
+        return
+    print(f"Prime Account: {eq['prime_account']}")
+    if eq["status"] == "error":
+        print(f"  Equity: unavailable ({eq.get('error', 'read failed')})")
+        return
+    tv, debt, rw, net = (eq["total_value_usd"], eq["debt_usd"],
+                         eq["rewards_usd"], eq["net_equity_usd"])
+    health = (100.0 if debt < 0.01 else round((tv - debt) / tv * 100, 1)) if tv else 0.0
+    print(f"  Total value:   ${tv:,.2f}")
+    print(f"  Debt:          ${debt:,.2f}")
+    print(f"  Rewards:       ${rw:,.2f}  (no separate unclaimed-reward source on Arbitrum DeltaPrime)")
+    print(f"  Net equity:    ${net:,.2f}  (total - debt + rewards)")
+    print(f"  Equity health: {health:.1f}%  (equity / total value)")
+
 def cmd_borrow(pool_name: str, amount: float, execute: bool = False):
     cfg = POOLS[pool_name]
     w3 = get_w3()
@@ -3340,6 +3519,48 @@ def cmd_execute_withdrawal(pool_name: str, index: int = None, execute: bool = Fa
     }
     receipt = _sign_and_send(w3, acct, tx, "Execute withdrawal", fallback_gas=3000000)
     ok = receipt["status"] == 1
+    if ok:
+        executed_amount = sum(intents[i][0] for i in ready) / 10 ** cfg["decimals"]
+        _log_withdraw_flow(
+            pa, symbol, executed_amount, receipt,
+            token_addr=(None if cfg["native"] else cfg["token"]),
+            to_addr=acct.address, decimals=cfg["decimals"],
+        )
+
+
+def _log_withdraw_flow(account_addr: str, symbol: str, amount: float, receipt,
+                       token_addr: str = None, to_addr: str = None,
+                       decimals: int = None) -> None:
+    """Append a 'withdraw' flow record after a successful executeWithdrawalIntent
+    broadcast (funds left the account to the EOA). amount is the total executed across
+    the matured intents. usd_value uses current spot price; None when unpriced. Wrapped
+    so a logging failure can never fail the financial op.
+
+    Prefers the ACTUAL ERC20 Transfer(account -> EOA) amount from the receipt over the
+    committed `amount`, symmetric with the fund path: the executed amount is normally
+    exact, but parsing the receipt keeps the ledger honest if it ever diverges. Native
+    unwraps emit no ERC20 Transfer, so `amount` stands there (token_addr is None)."""
+    try:
+        actual = amount
+        if token_addr and to_addr and decimals is not None:
+            moved = _flowledger.transferred_amount(
+                receipt, token_addr, account_addr, to_addr, decimals)
+            if moved is not None:
+                if abs(moved - amount) > max(1e-6, abs(amount) * 1e-4):
+                    print(f"  NOTE withdraw moved {moved} {symbol} of {amount} executed "
+                          f"(logging actual)", file=sys.stderr)
+                actual = moved
+        px = token_price(symbol)
+        usd = round(actual * px, 8) if px else None
+        rec = _flowledger.make_record(
+            ts=int(time.time()), ftype="withdraw", asset=symbol,
+            token_amount=actual, usd_value=usd,
+            tx=receipt["transactionHash"].hex(), block=receipt["blockNumber"],
+            source="live-withdraw",
+        )
+        _flowledger.append_flow("arbitrum", account_addr, rec)
+    except Exception as e:  # noqa: BLE001 — never fail the withdrawal over logging
+        print(f"  WARN flow logging skipped ({type(e).__name__}: {e})", file=sys.stderr)
 
 # ─── GMX V2 GM / GM+ LP (GmxV2FacetArbitrum / GmxV2PlusFacetArbitrum) ─────────
 # GM tokens are GMX V2 market LP (two-sided long+short for GM, single-sided for GM+).
@@ -5630,8 +5851,8 @@ def main():
         return
 
     cmd = args[0]
-    if _OWNER_ADDRESS and cmd not in {"defi", "lb-positions"}:
-        print("--owner is only supported for read-only commands: defi, lb-positions")
+    if _OWNER_ADDRESS and cmd not in {"defi", "lb-positions", "equity"}:
+        print("--owner is only supported for read-only commands: defi, lb-positions, equity")
         return
     if cmd == "pool-info":
         # First positional after `pool-info` is the pool name; --json is an opt-in flag
@@ -5713,6 +5934,16 @@ def main():
         cmd_prime_summary()
     elif cmd == "defi":
         cmd_defi("--json" in args)
+    elif cmd == "equity":
+        account_addr = None
+        for i, a in enumerate(args):
+            if a == "--account" and i + 1 < len(args):
+                try:
+                    account_addr = Web3.to_checksum_address(args[i + 1])
+                except Exception:
+                    print(f"Invalid --account address: {args[i + 1]}")
+                    return
+        cmd_equity("--json" in args, account_addr)
     elif cmd == "fund":
         pool, amount = None, None
         execute = "--execute" in args