Add MiningMarginVault: stateful mining-margin two-token vault (hashrate derivatives)

[tiero]

Summary

Adds examples/mining_margin/ — a market price for the economics of running a machine. Hashprice alone already trades (NDF markets exist); the mining margin — hashprice minus power, the actual P&L line of a machine — has no non-custodial, fully-collateralized, fungible instrument. This is that instrument, following the stateful two-token range-vault design of the hashprice option vaults (#57): shares and pots are constructor state, updated by dynamic recreation on every spend.

margin = clamp(hashPrice − powerCost, 0, cap)

Depositing cap sats mints a paired RIG (long a call spread on the margin) + GRID (a cap-sat escrow claim short the same spread), fungible Arkade Assets under identity-gated mint. RIG + GRID always equals cap, so the vault is exactly collateralized at every fixing — no margin calls, no liquidations, and settlement splits the pot with no division.

What it can and cannot do (framing revised after a dialectical review of the thesis): a cash-settled derivative cannot reduce aggregate energy burn — difficulty re-pins mining spend to protocol revenue whoever holds the paper. What a margin price does deliver: it prices the keep-vs-scrap decision for old-gen fleets (traded RIG at a fleet's efficiency is the market-implied option time value, the number that rationally decides decommissioning against carrying cost); it turns idle-hot fleets into price-responsive dispatch (a margin-locked miner curtails through negative spreads and runs the spikes); it accelerates efficiency turnover (same revenue-pinned security spend, fewer joules); and it lets AI-pivoting power owners stay financially long mining economics. The flagship position is the producer hedge — mint, sell RIG, keep GRID, keep operating — not "sell and unplug" (a seller who unplugs holds a naked short via GRID). The natural short base is merchant-power miners; fixed-price-PPA miners already own the power leg. The doc states the legs honestly (GRID is a bond minus the margin spread, not "watts sold elsewhere"; single-series RIG is not a machine — replication takes a strip, with known one-sided Jensen basis) and documents the hard-cap and sats-quanto trade-offs against #57's USD-vault alternative.

Settlement design (hardened after adversarial code review)

• Averaged (Asian) fixings, maturity-stamped. Both tickers are defined as period-averaged indices over a window stated in the oracle spec and ending at maturity — the settlement form physical power markets use — and both are signed over exactly maturity (sha256(ticker ‖ price(8) ‖ maturity(8))). One message slot per (ticker, maturity): no timestamp window for a permissionless settler to shop in (the previous ±settleWindow design let a settler pair max-hashprice with min-power across the window), no cross-series fixing replay, and equivocation is provable. settleWindow is deleted.
• Wall-clock settle gate (tx.offchainTime >= maturity): an early oracle print cannot fix the margin or freeze issuance ahead of schedule; settle also requires non-zero supply, so an empty series cannot be griefed shut.
• Negative power fixings admitted (routine at volatile hubs; the old powerCost >= 0 guard made an ordinary ERCOT-West condition unsettleable), range-bounded to keep all arithmetic in int64.
• Oracle-death recovery: burnPair is gated only on settled == 0 — a matched pair is worth exactly cap under every fixing, so pairs recover escrow 1:1 even if the oracle never publishes; only single-sided legs bear liveness.
• Every function pins the vault at input 0 (two vault inputs can't share one recreation if the identity-singleton assumption ever fails), value accounting is input-relative (incidental balance above backing is preserved, not claimable), and issue restores the amount ≤ 2.1e15 / cap bound so pairs × cap stays inside total sat supply.

Compiler status

Dynamic contract transitions are disabled (the symbolic-stack validator rejects runtime values as contract-instance arguments), so the five state-transition functions ship commented out with a disabled() placeholder, as in the other stateful examples — the compiled artifact has no satisfiable spend path and must not be deployed (stated in the doc). Two safeguards new in this round:

• CI guard test (test_commented_design_fails_only_on_dynamic_recreation, runs live): mechanically uncomments the design, drops the placeholder, compiles, and asserts failure with exactly the 10 dynamic-recreation errors and nothing else — so the commented design cannot rot silently, and the test fails loudly the day transitions are restored (restoration tripwire).
• Restore checklist in the contract source (uncomment functions → delete placeholder → un-ignore design tests → retire guard test), plus an order-sensitive constructor-schema test so a parameter reorder cannot silently corrupt the five hard-coded recreations.

Files

• examples/mining_margin/mining_margin_vault.ark — the vault (full stateful design in source; placeholder compiles today)
• examples/mining_margin/mining_margin.md — honest framing: what a margin price can and cannot do, the primitive, positions, trade-offs, trust assumptions
• tests/examples/mining_margin.rs — live schema + guard tests, five #[ignore]d design tests, roundtrip entry
• playground/main.js — dedicated Mining Margin playground project, with the disabled-status caveat in its description

Verification

Full workspace suite green (389 passed), cargo clippy --workspace --all-targets -- -D warnings clean, cargo fmt --check clean, ./playground/build.sh end to end (WASM into playground/pkg/, contracts.js regenerated). The uncommented design was probe-compiled: it fails on exactly the ten runtime-value contract-instance arguments across the five functions — no parse, type, or other validation errors.

https://claude.ai/code/session_01UtS4WKhQbHTypH5mQbWWfM

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 92a95478-90ef-40f5-b57b-b83883ce948e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Playground Preview

A live preview of this PR's playground is available at:
https://arkade-os.github.io/compiler/pr-previews/pr-77/

Built from commit 98f5119b1495cd2a15c0aa60e5c6df07c9f730da · Workflow run