mintbound-cli 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# mintbound-cli
+
+Check MintBound's solvency evidence yourself, against live chains.
+
+```bash
+npx mintbound-cli status
+```
+
+> **If `npx` reports the package is not found**, it has not been published yet.
+> Everything above also runs straight from a clone, with no publish step:
+> `git clone https://github.com/Lawalgiyath/MintGuard && cd MintGuard && npm install && npm run claims`
+
+**No private key. No funded account. No setup.** The Attestcoin Proof Builder is a read
+API, and the guard's entry points are reachable by `eth_call` — so every claim MintBound
+makes can be checked by a stranger who has not been trusted with anything. That is the
+point of the tool.
+
+---
+
+## Commands
+
+### `claims`
+
+Audits our own pitch. Every factual claim MintBound's submission makes, with the live
+check that settles it — fetched now, from chains and explorers.
+
+```
+  right now: minting FROZEN  ·  proof 23741/200 blocks stale  ·  redemption always open
+
+  ✓ No off-chain party has to be trusted for the reserve figure.
+      trustedParties() == 0 — the figure came from the Block Prover precompile
+  ✓ A proof past the staleness bound freezes minting, rather than being used anyway.
+      proof is 23741 of 200 blocks stale, and minting is frozen — the gate bit
+  ✓ mintWithProof costs about 382,578 gas including proof verification and the invariant.
+      the real receipt reports 382578 gas
+
+  11/11 claims verified against live state.
+```
+
+Exits non-zero when any claim fails. That matters: a self-audit that cannot return FAIL
+is marketing in a monospace font.
+
+Claims resolve to **pass**, **fail**, or **unknown**. Unknown means the evidence could
+not be reached — a block explorer timed out, an RPC refused — which is not the same as a
+claim being false, so it is shown distinctly, never counted as verified, and does not set
+a failing exit code. Only a real failure does.
+
+### `status`
+
+The whole balance sheet, read live from Creditcoin CC3 and Ethereum Sepolia.
+
+```
+Balance sheet
+────────────────────────────────────────────────────────────────────
+  proven reserve        1,025,000 @ source height 11570929
+  announced exits       - 0 (encumbered, no longer counts)
+  haircut               x 100.00%
+  effective backing     = 1,025,000
+  outstanding supply    25,000 wmTUSD
+  headroom to bound     1,000,000
+
+Assurance  90/100
+────────────────────────────────────────────────────────────────────
+  ✓ Reserve evidence       25  cryptographic — no reporter in the mint path
+  ✓ Proof freshness        20  21 of 200 blocks stale
+  ✓ Liability coverage     20  single-chain deployment
+  ✓ Encumbrance margin     15  150 block delay vs 40 block detection (3.8x margin)
+  ✗ Interval continuity    10  no bonded continuity claim covers the current interval
+  ✓ Mint authority         10  emergency withdrawal irreversibly renounced
+```
+
+`--json` for machine-readable output.
+
+**On the Assurance number:** it is a presentation-layer aggregation over six
+independently checkable obligations, with weights published in
+[`src/assurance.ts`](src/assurance.ts). No contract reads it and no mint is gated on it —
+enforcement on-chain is binary. It exists so a human can see which parts of the solvency
+argument are currently carried by cryptography and which by an assumption. If you
+disagree with a weight, the full vector is printed alongside the total so you can
+reweight it yourself.
+
+### `verify --source-tx <hash>`
+
+Walk one source-chain transaction through the entire evidence pipeline and report what
+the precompile makes of it.
+
+```
+[1/4] Fetching source receipt ✓ block 11570611, 1 logs
+    event found         ReserveSnapshot
+    routes to           submitReserveSnapshot()
+[2/4] Checking attestation via ChainInfo precompile 0x0FD3 ✓ height 11570611 attested
+[3/4] Building Merkle + continuity proof ✓ 9 Merkle siblings, 90 continuity roots
+[4/4] Calling submitReserveSnapshot() on CC3 (eth_call, no transaction sent)
+      ✓ proof is valid but already spent
+```
+
+The entry point is chosen from the log signatures actually present in the receipt, not
+from a flag you pass. A transaction carrying neither `ReserveSnapshot` nor `Locked` is
+rejected — correctly, since an arbitrary transaction must not be able to move the bound.
+
+### `attack`
+
+Fire the documented attacks at the live guard. Every one is expected to revert, and the
+reverts are the product.
+
+```
+  6/6 blocked — 5 by the Block Prover precompile, 1 by the guard before it got that far
+```
+
+**What this proves, exactly:** each attempt carries forged proof material, so each is
+rejected before MintBoundASC's own logic runs. There is no path around the precompile.
+It does **not** exercise the guard's internal rejections — emitter binding, event
+matching, replay — because those need a *valid* proof carrying malicious contents, which
+cannot be forged against live CC3 by construction. Those are covered in
+`packages/contracts/test/MintBound.test.ts` against a mock verifier.
+
+---
+
+## Configuration
+
+Everything has a working default pointed at the live deployment. Override via env:
+
+| Variable | Default |
+|---|---|
+| `CREDITCOIN_RPC_URL` | `https://rpc.cc3-testnet.creditcoin.network` |
+| `SEPOLIA_RPC_URL` | `https://ethereum-sepolia-rpc.publicnode.com` |
+| `PROOF_BUILDER_URL` | `https://proof-gen-api.cc3-testnet.creditcoin.network` |
+
+Run from inside the repo and `deployments/*.json` is picked up automatically, so a fresh
+redeploy needs no edit here.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Solvent and fresh / proof valid / all attacks blocked |
+| 1 | Minting frozen / proof rejected / an attack succeeded |
+| 2 | Usage error |
+
+Suitable for CI: `npx mintbound-cli status` failing is a real signal.

package/dist/abi.js

@@ -0,0 +1,83 @@
+/**
+ * Hand-written ABIs. The CLI deliberately has no build dependency on the contracts
+ * package — it must be runnable against a deployed system by someone who has never
+ * compiled this repo.
+ */
+export const ASC_ABI = [
+    "function submitReserveSnapshot((uint64,uint64,bytes,bytes32,(bytes32,bool)[],bytes32,bytes32[]) q) returns (bool)",
+    "function mintWithProof((uint64,uint64,bytes,bytes32,(bytes32,bool)[],bytes32,bytes32[]) q) returns (bool)",
+    "function solvencyReport(address sourceAsset) view returns ((uint256 verifiedReserve,uint256 encumberedReserve,uint256 outstandingSupply,uint256 maxMintable,uint32 collateralRatioBps,uint64 attestedAtHeight,uint64 latestAttestedHeight,uint64 stalenessBlocks,uint64 epoch,uint16 haircutBps,uint64 provenAt,uint8 trustedParties,bool fresh,bool solvent,bool mintFrozen))",
+    "function trustedParties(address sourceAsset) view returns (uint8)",
+    "function maxStalenessBlocks() view returns (uint64)",
+    "function SOURCE_CHAIN_KEY() view returns (uint64)",
+    "function CANONICAL_VAULT() view returns (address)",
+    "function remoteChainKeys(address,uint256) view returns (uint64)",
+    "function totalLiabilities(address sourceAsset) view returns (uint256)",
+];
+/**
+ * MintBoundASC's custom errors. Without these in the ABI, ethers reports a real,
+ * informative revert as "unknown custom error" — which reads like a malfunction when it
+ * is in fact the guard answering precisely.
+ */
+export const ASC_ERRORS = [
+    "error WrongChainKey(uint64 got, uint64 expected)",
+    "error QueryAlreadyProcessed(bytes32 queryId)",
+    "error VerificationFailed()",
+    "error SourceTransactionReverted()",
+    "error UnsupportedTransactionType(uint8 txType)",
+    "error NoMatchingEvent()",
+    "error AssetNotRegistered(address sourceAsset)",
+    "error StaleEpoch(uint64 got, uint64 have)",
+    "error RegressiveHeight(uint64 got, uint64 have)",
+    "error LockAlreadyConsumed(bytes32 lockId)",
+    "error MintFrozen(address sourceAsset)",
+    "error NoReserveProof(address sourceAsset)",
+    "error ReserveStale(uint64 staleness, uint64 bound)",
+    "error InvariantViolated(uint256 wouldBeSupply, uint256 discountedReserve)",
+    "error InvalidHaircut(uint16 bps)",
+    "error NotHealthy()",
+    "error TimelockPending(uint256 eta)",
+    "error NoUnfreezeRequested()",
+    "error VelocityCapExceeded(uint256 wouldBeInWindow, uint256 cap)",
+    "error InvalidVelocityWindow()",
+    "error OracleMintDisabled(address sourceAsset)",
+    "error AssetNotOracleBacked(address sourceAsset)",
+    "error InvalidOracleFeed()",
+    "error RemoteChainNotRegistered(address sourceAsset, uint64 chainKey)",
+    "error WrongBeacon(address got, address expected)",
+    "error RemoteSupplyStale(uint64 chainKey, uint64 staleness, uint64 bound)",
+    "error RemoteSupplyMissing(uint64 chainKey)",
+    "error TooManyRemoteChains()",
+];
+export const ERC20_ABI = [
+    "function balanceOf(address) view returns (uint256)",
+    "function totalSupply() view returns (uint256)",
+    "function symbol() view returns (string)",
+    "function decimals() view returns (uint8)",
+];
+export const VAULT_ABI = [
+    "function reserveBalance(address asset) view returns (uint256)",
+    "function encumbered(address) view returns (uint256)",
+    "function availableReserve(address asset) view returns (uint256)",
+    "function emergencyEnabled() view returns (bool)",
+    "function WITHDRAWAL_DELAY() view returns (uint256)",
+    "function epoch(address) view returns (uint256)",
+];
+export const FEED_ABI = [
+    "function latestRoundData() view returns (uint80 roundId,int256 answer,uint256 startedAt,uint256 updatedAt,uint80 answeredInRound)",
+    "function decimals() view returns (uint8)",
+    "function description() view returns (string)",
+];
+export const CHAIN_INFO_ABI = [
+    "function get_latest_attestation_height_and_hash(uint64 chainKey) view returns ((uint64 height, bytes32 hash, bool isAttestation, bool exists))",
+    "function is_height_attested(uint64 chainKey, uint64 targetHeight) view returns (bool)",
+    "function get_supported_chains() view returns ((uint64 chainKey, uint64 chainId, bytes chainName, uint8 chainEncoding)[])",
+];
+export const CONTINUITY_ABI = [
+    "function coveredThrough(address asset) view returns (uint64)",
+    "function openClaim(address asset) view returns (bytes32)",
+    "function anchorHeight(address asset) view returns (uint64)",
+    "function claims(bytes32) view returns (address asset,address asserter,uint64 fromHeight,uint64 toHeight,uint64 settleAfter,uint256 bond,bool settled,bool disproven)",
+    "function MIN_BOND() view returns (uint256)",
+    "function LIVENESS() view returns (uint64)",
+];

package/dist/assurance.js

@@ -0,0 +1,101 @@
+/**
+ * MintBound Assurance — how much trust the solvency evidence still requires.
+ *
+ * WHAT THIS IS NOT
+ * ----------------
+ * This is not a consensus value, it is not read by any contract, and no mint is ever
+ * gated on it. Enforcement in MintBound is binary and lives on-chain: either the
+ * aggregate bound holds against a fresh proof or the mint reverts. Nothing here can
+ * loosen that.
+ *
+ * WHAT THIS IS
+ * ------------
+ * A presentation-layer aggregation over six independent proof obligations, so that a
+ * human can see at a glance which parts of the solvency argument are currently carried
+ * by cryptography and which are carried by an assumption. The weights below are
+ * published rather than tuned: they are part of the specification, and changing them
+ * changes a documented number, not a security property.
+ *
+ * The reason a score is defensible at all here is that each obligation is independently
+ * checkable from chain state — no obligation is scored on opinion. If you disagree with
+ * a weight, the vector is printed alongside the total so you can reweight it yourself.
+ */
+/** Published weights. These sum to 100 and are part of the spec. */
+export const WEIGHTS = {
+    reserveEvidence: 25,
+    freshness: 20,
+    liabilityCoverage: 20,
+    encumbrance: 15,
+    continuity: 10,
+    mintAuthority: 10,
+};
+export function assess(i) {
+    const marginOk = i.detectionLatencyBlocks > 0 &&
+        i.withdrawalDelayBlocks >= 2 * i.detectionLatencyBlocks;
+    const chainsOk = i.registeredChains === 0 || i.reportingChains >= i.registeredChains;
+    const continuityOk = i.coveredThrough > 0 && i.coveredThrough >= i.anchorHeight;
+    const obligations = [
+        {
+            id: "reserve",
+            label: "Reserve evidence",
+            weight: WEIGHTS.reserveEvidence,
+            met: i.trustedParties === 0,
+            evidence: "chain: MintBoundASC.solvencyReport().trustedParties",
+            detail: i.trustedParties === 0
+                ? "cryptographic — verified by the Block Prover precompile, no reporter in the mint path"
+                : `oracle-reported — ${i.trustedParties} off-chain part${i.trustedParties === 1 ? "y" : "ies"} must be honest`,
+        },
+        {
+            id: "freshness",
+            label: "Proof freshness",
+            weight: WEIGHTS.freshness,
+            met: i.fresh,
+            evidence: "chain: ChainInfo precompile 0x0FD3, read on-chain",
+            detail: `${i.stalenessBlocks} of ${i.maxStalenessBlocks} blocks stale`,
+        },
+        {
+            id: "liabilities",
+            label: "Liability coverage",
+            weight: WEIGHTS.liabilityCoverage,
+            met: chainsOk,
+            evidence: "chain: SupplyBeacon proofs aggregated by MintBoundASC.totalLiabilities()",
+            detail: i.registeredChains === 0
+                ? "single-chain deployment — local totalSupply is the whole liability"
+                : `${i.reportingChains} of ${i.registeredChains} registered chains reporting`,
+        },
+        {
+            id: "encumbrance",
+            label: "Encumbrance margin",
+            weight: WEIGHTS.encumbrance,
+            met: marginOk,
+            evidence: "chain: ReserveVault.WITHDRAWAL_DELAY vs observed attestation lag",
+            detail: marginOk
+                ? `${i.withdrawalDelayBlocks} block delay vs ${i.detectionLatencyBlocks} block detection ` +
+                    `(${(i.withdrawalDelayBlocks / Math.max(i.detectionLatencyBlocks, 1)).toFixed(1)}x margin)`
+                : `${i.withdrawalDelayBlocks} block delay does not cover 2x the ${i.detectionLatencyBlocks} block detection latency`,
+        },
+        {
+            id: "continuity",
+            label: "Interval continuity",
+            weight: WEIGHTS.continuity,
+            met: continuityOk,
+            evidence: "chain: SolvencyContinuity.coveredThrough()",
+            detail: continuityOk
+                ? `no-outflow bonded through source height ${i.coveredThrough}`
+                : "no bonded continuity claim covers the current interval",
+        },
+        {
+            id: "authority",
+            label: "Mint authority",
+            weight: WEIGHTS.mintAuthority,
+            met: i.emergencyRenounced,
+            evidence: "chain: ReserveVault.emergencyEnabled()",
+            detail: i.emergencyRenounced
+                ? "emergency withdrawal irreversibly renounced — the operator cannot move the reserve"
+                : "emergency withdrawal still enabled — the operator retains a unilateral exit",
+        },
+    ];
+    const score = obligations.reduce((n, o) => n + (o.met ? o.weight : 0), 0);
+    const max = obligations.reduce((n, o) => n + o.weight, 0);
+    return { obligations, score, max };
+}

package/dist/commands/attack.js

@@ -0,0 +1,167 @@
+import { AbiCoder, Contract, Interface, getAddress, keccak256, toUtf8Bytes, zeroPadValue, } from "ethers";
+import { ASC_ABI, ASC_ERRORS } from "../abi.js";
+import { EXPLORER, creditcoin, sepolia } from "../config.js";
+import { providers } from "../read.js";
+import { describeRevert } from "../revert.js";
+import { CROSS, TICK, c, heading, rule } from "../render.js";
+/**
+ * `mintbound attack` — fire the documented attacks at the live guard and report back.
+ *
+ * These are real `eth_call`s against the real MintBoundASC on CC3. Every one is
+ * expected to revert, and the reverts are the product.
+ *
+ * WHAT THIS PROVES, EXACTLY: each attempt carries forged proof material, so each is
+ * rejected by the Block Prover precompile before the guard's own logic runs. There is
+ * no path around the precompile. It does NOT exercise the guard's internal rejections
+ * (emitter binding, event matching, replay) — those require a *valid* proof carrying
+ * malicious contents, which cannot be forged against live CC3 by construction, and are
+ * covered in the unit suite against a mock verifier instead.
+ */
+const abi = AbiCoder.defaultAbiCoder();
+const RESERVE_SNAPSHOT_SIG = keccak256(toUtf8Bytes("ReserveSnapshot(address,address,uint256,uint256,uint256)"));
+const LOCKED_SIG = keccak256(toUtf8Bytes("Locked(address,address,uint256,uint256)"));
+const topic = (a) => zeroPadValue(getAddress(a), 32);
+function encodeTx(logs, receiptStatus = 1) {
+    const common = abi.encode(["uint64", "uint64", "address", "bool", "address", "uint256", "bytes"], [
+        1n,
+        500000n,
+        "0x1111111111111111111111111111111111111111",
+        false,
+        "0x2222222222222222222222222222222222222222",
+        0n,
+        "0x",
+    ]);
+    const typeSpecific = abi.encode(["uint64", "uint128", "uint128", "tuple(address,bytes32[])[]", "uint8", "bytes32", "bytes32"], [11155111n, 1n, 2n, [], 0, `0x${"11".repeat(32)}`, `0x${"22".repeat(32)}`]);
+    const receipt = abi.encode(["uint8", "uint64", "tuple(address,bytes32[],bytes)[]", "bytes"], [
+        receiptStatus,
+        100000n,
+        logs.map((l) => [l.address_, l.topics, l.data]),
+        "0x" + "00".repeat(256),
+    ]);
+    return abi.encode(["uint8", "bytes[]"], [2, [common, typeSpecific, receipt]]);
+}
+/** Three non-indexed words, matching ReserveVault's event exactly. */
+function snapshotLog(vault, asset, balance, epoch) {
+    return {
+        address_: vault,
+        topics: [RESERVE_SNAPSHOT_SIG, topic(vault), topic(asset)],
+        data: abi.encode(["uint256", "uint256", "uint256"], [balance, 0n, epoch]),
+    };
+}
+function lockedLog(vault, user, asset, amount, nonce) {
+    return {
+        address_: vault,
+        topics: [LOCKED_SIG, topic(user), topic(asset)],
+        data: abi.encode(["uint256", "uint256"], [amount, nonce]),
+    };
+}
+function query(blockHeight, encodedTransaction, opts = {}) {
+    return [
+        opts.chainKey ?? 1n,
+        blockHeight,
+        encodedTransaction,
+        `0x${"ab".repeat(32)}`,
+        [
+            [keccak256(toUtf8Bytes("s0")), false],
+            [keccak256(toUtf8Bytes("s1")), true],
+        ],
+        `0x${"cd".repeat(32)}`,
+        [`0x${"ef".repeat(32)}`],
+    ];
+}
+export async function attack() {
+    const cc = creditcoin();
+    const sep = sepolia();
+    const { cc: ccProvider, sep: sepProvider } = providers();
+    const ascAddr = cc.contracts.MintBoundASC;
+    const vault = String(cc.config?.canonicalVault ?? sep.contracts.ReserveVault);
+    const asset = String(cc.config?.sourceAsset ?? sep.contracts.TestUSD);
+    const iface = new Interface([...ASC_ABI, ...ASC_ERRORS]);
+    const asc = new Contract(ascAddr, iface, ccProvider);
+    // Aim at a height that actually exists, so a rejection is never merely "no such block".
+    const head = BigInt(await sepProvider.getBlockNumber().catch(() => 11_600_000));
+    heading("MintBound — live attack suite");
+    console.log(`  target   ${ascAddr}  ${c.grey("(Creditcoin CC3)")}`);
+    console.log(`  vault    ${vault}  ${c.grey("(Sepolia)")}`);
+    console.log(`  height   ${head}`);
+    console.log("");
+    console.log(c.grey("  Real eth_calls against the live guard. Every one should revert. Forged proof\n" +
+        "  material means each is stopped by the precompile before the guard's own\n" +
+        "  checks run — which is the property being demonstrated."));
+    const cases = [
+        {
+            name: "Forged inclusion proof",
+            expect: "the precompile will not verify fabricated material",
+            run: () => asc.submitReserveSnapshot.staticCall(query(head, encodeTx([snapshotLog(vault, asset, 10n ** 30n, 999n)]))),
+        },
+        {
+            name: "Counterfeit vault, identical event",
+            expect: "a counterfeit emitter still needs a real inclusion proof",
+            run: () => asc.submitReserveSnapshot.staticCall(query(head, encodeTx([
+                snapshotLog("0xdeadbeef00000000000000000000000000000000", asset, 10n ** 30n, 999n),
+            ]))),
+        },
+        {
+            name: "Reverted source transaction",
+            expect: "a reverted receipt is unprovable to begin with",
+            run: () => asc.submitReserveSnapshot.staticCall(query(head, encodeTx([snapshotLog(vault, asset, 10n ** 30n, 999n)], 0))),
+        },
+        {
+            name: "Proof from the wrong source chain",
+            expect: "chainKey is pinned at construction, before any proof work",
+            run: () => asc.submitReserveSnapshot.staticCall(query(head, encodeTx([snapshotLog(vault, asset, 1n, 999n)]), { chainKey: 3n })),
+        },
+        {
+            name: "Mint with no authorising Locked event",
+            expect: "nothing here authorises a mint",
+            run: () => asc.mintWithProof.staticCall(query(head, encodeTx([snapshotLog(vault, asset, 1n, 1n)]))),
+        },
+        {
+            name: "Unauthorised mint of an enormous amount",
+            expect: "rejected before any supply is created",
+            run: () => asc.mintWithProof.staticCall(query(head, encodeTx([
+                lockedLog(vault, "0x000000000000000000000000000000000000dEaD", asset, 10n ** 30n, 424242n),
+            ]))),
+        },
+    ];
+    const results = [];
+    for (const t of cases) {
+        console.log("");
+        console.log(`  ${c.bold(t.name)}`);
+        console.log(c.grey(`    expect: ${t.expect}`));
+        try {
+            await t.run();
+            console.log(`    ${c.red("SUCCEEDED")} — this must not happen. Investigate before shipping.`);
+            results.push({ name: t.name, blocked: false, reason: "call succeeded" });
+        }
+        catch (e) {
+            const reason = describeRevert(iface, e);
+            console.log(`    ${c.green(TICK + " BLOCKED")} ${c.grey(reason)}`);
+            results.push({ name: t.name, blocked: true, reason });
+        }
+    }
+    const blocked = results.filter((r) => r.blocked).length;
+    heading("Summary");
+    for (const r of results) {
+        console.log(`  ${r.blocked ? c.green(TICK) : c.red(CROSS)} ${r.name}`);
+    }
+    console.log("");
+    // Be precise about WHERE each one died. Most are stopped by the precompile; the
+    // chain-key case never reaches it, because the key is pinned at construction and
+    // checked first. Reporting them all as "blocked at the proof layer" would be tidier
+    // and wrong.
+    const atProof = results.filter((r) => /merkle|proof/i.test(r.reason)).length;
+    const beforeProof = blocked - atProof;
+    const tally = `${blocked}/${results.length}`;
+    console.log(`  ${blocked === results.length ? c.green(tally) : c.red(tally)} blocked` +
+        c.grey(` — ${atProof} by the Block Prover precompile` +
+            (beforeProof > 0 ? `, ${beforeProof} by the guard before it got that far` : "")));
+    console.log(c.grey("\n  Guard-internal rejections — emitter binding, event matching, chain-key pinning,\n" +
+        "  replay protection — need a valid proof carrying malicious contents, which cannot\n" +
+        "  be forged against live CC3. Those are covered in test/MintBound.test.ts against a\n" +
+        "  mock verifier."));
+    rule();
+    console.log(c.grey(`  ${EXPLORER.creditcoin}/address/${ascAddr}`));
+    console.log("");
+    return blocked === results.length ? 0 : 1;
+}