mintbound-cli 0.1.0

package/dist/commands/claims.js

@@ -0,0 +1,207 @@
+import { Contract } from "ethers";
+import { CHAIN_INFO_ABI, ERC20_ABI } from "../abi.js";
+import { CHAIN_INFO_ADDRESS, EXPLORER, creditcoin, sepolia } from "../config.js";
+import { providers, readLive } from "../read.js";
+import { CROSS, TICK, c, heading, rule, units } from "../render.js";
+const BLOCKSCOUT_API = `${EXPLORER.creditcoin}/api`;
+/**
+ * Ask the explorer whether a contract's source is actually published.
+ *
+ * Distinguishes "not published" from "could not ask". Firing seven of these at once
+ * made Blockscout time out intermittently, and reporting that as an unpublished
+ * contract would be a false FAIL — exactly the kind of misreport this command exists to
+ * avoid. So: retry once, and return `reachable: false` rather than a verdict when the
+ * explorer will not answer.
+ */
+async function sourcePublished(address) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const res = await fetch(`${BLOCKSCOUT_API}?module=contract&action=getsourcecode&address=${address}`, { signal: AbortSignal.timeout(25_000) });
+            if (!res.ok)
+                throw new Error(String(res.status));
+            const body = await res.json();
+            const row = body?.result?.[0];
+            const src = String(row?.SourceCode ?? "");
+            return { published: src.length > 0, reachable: true, name: String(row?.ContractName ?? "") };
+        }
+        catch {
+            if (attempt === 0)
+                await new Promise((r) => setTimeout(r, 1500));
+        }
+    }
+    return { published: false, reachable: false, name: "" };
+}
+/** The guard's own mint gate, mirrored exactly: solvent AND fresh AND not frozen. */
+function canMintNow(s) {
+    return s.solvent && s.fresh && !s.mintFrozen;
+}
+export async function claims(opts = {}) {
+    const cc = creditcoin();
+    const sep = sepolia();
+    const { cc: ccProvider } = providers();
+    const s = await readLive();
+    const out = [];
+    const add = (id, claim, source, result, detail) => out.push({
+        id,
+        claim,
+        source,
+        verdict: typeof result === "boolean" ? (result ? "pass" : "fail") : result,
+        detail,
+    });
+    // ── 1. no reporter in the mint path ─────────────────────────────────────────
+    add("no-reporter", "No off-chain party has to be trusted for the reserve figure.", "chain: MintBoundASC.solvencyReport().trustedParties", s.trustedParties === 0, s.trustedParties === 0
+        ? "trustedParties() == 0 — the figure came from the Block Prover precompile"
+        : `trustedParties() == ${s.trustedParties} — this asset is oracle-backed, not proven`);
+    // ── 2. the reserve was actually proven, not merely configured ───────────────
+    const proven = s.epoch > 0 && s.attestedAtHeight > 0 && s.verifiedReserve > 0n;
+    add("proof-exists", "The reserve figure came from a verified inclusion proof of a real source transaction.", "chain: reserves[asset].epoch / attestedAtHeight", proven, proven
+        ? `${units(s.verifiedReserve, s.decimals)} proven at source height ${s.attestedAtHeight} (epoch ${s.epoch})`
+        : "no proof recorded — the guard has never accepted a snapshot for this asset");
+    // ── 3. freshness is read from the precompile, not reported to us ────────────
+    // Read 0x0FD3 directly and compare with what the guard reports. If an off-chain party
+    // could influence the freshness figure, these two would be free to disagree.
+    let precompileHeight = 0;
+    try {
+        const info = new Contract(CHAIN_INFO_ADDRESS, CHAIN_INFO_ABI, ccProvider);
+        const r = await info.get_latest_attestation_height_and_hash(s.sourceChainKey);
+        precompileHeight = Number(r.height);
+    }
+    catch {
+        /* leaves precompileHeight at 0, which fails the claim below */
+    }
+    const freshnessAgrees = precompileHeight > 0 && Math.abs(precompileHeight - s.latestAttestedHeight) <= 2;
+    add("freshness-on-chain", "Freshness is read on-chain from ChainInfo precompile 0x0FD3, so nobody off-chain can lie about it.", "chain: 0x0FD3 read directly, compared against the guard's own report", freshnessAgrees, freshnessAgrees
+        ? `precompile says ${precompileHeight}, guard says ${s.latestAttestedHeight} — same source`
+        : `precompile ${precompileHeight} vs guard ${s.latestAttestedHeight} — could not confirm they agree`);
+    // ── 4. the freshness bound actually bites ─────────────────────────────
+    // The first draft of this command omitted freshness and reported 10/10 while the
+    // deployment was frozen on a proof 23,741 blocks past its bound. That is exactly the
+    // bias a self-audit exists to remove — it checked only the claims we thought to list.
+    //
+    // The claim worth checking is not "minting works right now". It is the safety
+    // property: a proof past the staleness bound MUST freeze minting. When the proof is
+    // stale, that is directly observable, and the freeze is evidence rather than an
+    // outage. When it is fresh, the bound simply is not being exercised, and we say so
+    // instead of claiming credit.
+    const stale = s.stalenessBlocks > s.maxStalenessBlocks;
+    const gateBites = stale ? !s.fresh && !canMintNow(s) : s.fresh;
+    add("staleness-bites", "A proof past the staleness bound freezes minting, rather than being used anyway.", "chain: stalenessBlocks vs maxStalenessBlocks, against the guard's own mint gate", gateBites, stale
+        ? `proof is ${s.stalenessBlocks} of ${s.maxStalenessBlocks} blocks stale, and minting is ${canMintNow(s) ? "STILL OPEN — the gate did not bite" : "frozen — the gate bit"}`
+        : `proof is ${s.stalenessBlocks} of ${s.maxStalenessBlocks} blocks stale; the bound is not currently being exercised`);
+    // ── 4. the bound holds right now ────────────────────────────────────────────
+    const withinBound = s.outstandingSupply <= s.discountedReserve;
+    add("bound-holds", "Outstanding supply is within the proven ceiling.", "chain: totalSupply vs (verifiedReserve - encumbered) x haircut", withinBound, `${units(s.outstandingSupply, s.decimals)} supply against ${units(s.discountedReserve, s.decimals)} effective backing`);
+    // ── 5. encumbrance arithmetic matches the enforced rule ─────────────────────
+    // Recompute the ceiling the way the contract does and check the contract agrees.
+    const unenc = s.verifiedReserve > s.encumberedReserve ? s.verifiedReserve - s.encumberedReserve : 0n;
+    const expected = (unenc * BigInt(s.haircutBps)) / 10000n;
+    add("encumbrance-first", "Announced exits are subtracted from backing BEFORE the haircut, not after.", "chain: recomputed from verifiedReserve, encumbered and haircutBps", expected === s.discountedReserve, expected === s.discountedReserve
+        ? `${units(s.encumberedReserve, s.decimals)} encumbered, excluded before the ${(s.haircutBps / 100).toFixed(2)}% haircut`
+        : `recomputed ${units(expected, s.decimals)} but the guard reports ${units(s.discountedReserve, s.decimals)}`);
+    // ── 6. the liveness/safety margin, against MEASURED latency ─────────────────
+    const detection = Math.max(s.sourceHead - s.latestAttestedHeight, 0);
+    const marginOk = detection > 0 && s.withdrawalDelayBlocks >= 2 * detection;
+    add("margin", "A withdrawal cannot execute before the system could have detected it (delay >= 2x detection latency).", "chain: ReserveVault.WITHDRAWAL_DELAY vs live attestation lag", marginOk, detection > 0
+        ? `${s.withdrawalDelayBlocks} block delay vs ${detection} blocks of measured lag — ${(s.withdrawalDelayBlocks / detection).toFixed(1)}x margin`
+        : "attestation lag reads as zero; cannot evidence the margin right now");
+    // ── 7. the operator cannot move the reserve ─────────────────────────────────
+    add("renounced", "The operator has irreversibly given up the ability to move the reserve.", "chain: ReserveVault.emergencyEnabled()", !s.emergencyEnabled, s.emergencyEnabled
+        ? "emergency withdrawal is STILL ENABLED — the operator retains a unilateral exit"
+        : "emergencyEnabled() == false, permanently — there is no function to re-enable it");
+    // ── 8. the minter is immutable and is the guard ─────────────────────────────
+    let minter = "";
+    try {
+        const w = new Contract(cc.contracts.WrappedAsset, [...ERC20_ABI, "function MINTER() view returns (address)"], ccProvider);
+        minter = String(await w.MINTER());
+    }
+    catch {
+        /* empty string fails the claim */
+    }
+    const minterOk = minter.toLowerCase() === String(cc.contracts.MintBoundASC).toLowerCase();
+    add("minter-immutable", "Only the guard can mint, and that cannot be changed by anyone.", "chain: WrappedAsset.MINTER (immutable)", minterOk, minterOk
+        ? `MINTER is the guard at ${minter.slice(0, 10)}… and is declared immutable`
+        : `MINTER is ${minter || "unreadable"} — expected the guard`);
+    // ── 9. published source ─────────────────────────────────────────────────────
+    const ccNames = Object.keys(cc.contracts);
+    // Sequential on purpose. Seven parallel requests made the explorer time out and
+    // produced a false FAIL; this takes a few seconds longer and tells the truth.
+    const checks = [];
+    for (const n of ccNames) {
+        checks.push({ n, ...(await sourcePublished(cc.contracts[n])) });
+    }
+    const published = checks.filter((r) => r.published).length;
+    const unreachable = checks.filter((r) => !r.reachable).length;
+    add("source-published", "Every deployed contract publishes verified source, so the code behind each address can be read.", "explorer: Blockscout getsourcecode, queried live", 
+    // Unreachable is not the same as unpublished. Blockscout times out often enough
+    // that treating a slow explorer as a failed claim would make this command
+    // intermittently accuse its own project of something untrue.
+    unreachable > 0 ? "unknown" : published === ccNames.length ? "pass" : "fail", unreachable > 0
+        ? `${published}/${ccNames.length} confirmed; ${unreachable} could not be reached — the explorer did not answer, which is not evidence either way`
+        : `${published}/${ccNames.length} Creditcoin contracts return source from the explorer`);
+    // ── 10. the gas figure we quote ─────────────────────────────────────────────
+    // Quoting a measured number is only worth anything if the measurement is reachable.
+    const MINT_TX = "0xb5a9c959d5fcadad2608e6c0e0e444cc9854489706e96f0f1ee495ba33f70d56";
+    let mintGas = 0n;
+    try {
+        const rec = await ccProvider.getTransactionReceipt(MINT_TX);
+        mintGas = rec?.gasUsed ?? 0n;
+    }
+    catch {
+        /* zero fails the claim */
+    }
+    add("gas-measured", "mintWithProof costs about 382,578 gas including proof verification and the full invariant.", `chain: receipt for ${MINT_TX.slice(0, 12)}…`, mintGas === 0n ? "unknown" : mintGas < 400000n ? "pass" : "fail", mintGas > 0n
+        ? `the real receipt reports ${mintGas.toString()} gas`
+        : "the receipt could not be fetched — no evidence either way, not a failure");
+    // ── report ──────────────────────────────────────────────────────────────────
+    if (opts.json) {
+        console.log(JSON.stringify({ claims: out }, null, 2));
+        return out.some((x) => x.verdict === "fail") ? 1 : 0;
+    }
+    heading("MintBound — auditing our own claims");
+    console.log(c.grey("  Every factual claim in the submission, with the live check that settles it.\n" +
+        "  Read now, from chains and explorers. This command can fail, and says so when\n" +
+        "  it does — a self-audit that cannot return FAIL is marketing in a monospace font."));
+    console.log("");
+    // Operational status first. The claims below are about SAFETY properties, which hold
+    // whether or not the deployment is currently minting — so state the operational
+    // position plainly rather than letting a page of green ticks imply it.
+    const minting = canMintNow(s);
+    console.log(`  ${c.grey("right now:")} minting ${minting ? c.green("PERMITTED") : c.yellow("FROZEN")}` +
+        c.grey(`  ·  proof ${s.stalenessBlocks}/${s.maxStalenessBlocks} blocks stale  ·  redemption always open`));
+    if (!minting) {
+        console.log(c.grey("  A frozen mint is the safety property, not an outage: no fresh proof, no new\n" +
+            "  liabilities. Restart the snapshot worker and it clears on the next proof."));
+    }
+    console.log("");
+    for (const x of out) {
+        const mark = x.verdict === "pass"
+            ? c.green(TICK)
+            : x.verdict === "fail"
+                ? c.red(CROSS)
+                : c.yellow("?");
+        console.log(`  ${mark} ${c.bold(x.claim)}`);
+        console.log(`      ${x.detail}`);
+        console.log(`      ${c.grey(x.source)}`);
+        console.log("");
+    }
+    const passed = out.filter((x) => x.verdict === "pass").length;
+    const failed = out.filter((x) => x.verdict === "fail").length;
+    const unknown = out.filter((x) => x.verdict === "unknown").length;
+    rule();
+    const tally = `${passed}/${out.length}`;
+    console.log(`  ${failed > 0 ? c.red(tally) : c.green(tally)} claims verified against live state` +
+        (unknown > 0 ? c.yellow(`  ·  ${unknown} could not be reached`) : "") +
+        (failed > 0 ? c.red(`  ·  ${failed} FAILED`) : ""));
+    if (failed > 0) {
+        console.log(c.grey("\n  The failed claims above are printed exactly as loudly as the met ones,\n" +
+            "  because a submission you cannot fail is not evidence of anything."));
+    }
+    if (unknown > 0) {
+        console.log(c.grey("\n  An unreachable source is not a failed claim. Those rows are marked ? rather\n" +
+            "  than counted either way, and do not set a failing exit code — a third party\n" +
+            "  being slow is not evidence about this project."));
+    }
+    console.log("");
+    // Fail only on an actual FAIL. Unknown is honest uncertainty, not a defect.
+    return failed > 0 ? 1 : 0;
+}

package/dist/commands/status.js

@@ -0,0 +1,64 @@
+import { assess } from "../assurance.js";
+import { EXPLORER } from "../config.js";
+import { readLive, toAssuranceInput } from "../read.js";
+import { CROSS, TICK, bar, c, heading, kv, rule, units } from "../render.js";
+/**
+ * `mintbound status` — the whole solvency argument, read from live chains, in one screen.
+ *
+ * Every number printed here was fetched over RPC in the last few seconds. Nothing is
+ * cached, nothing is synthesised, and no key or funded account is required to run it.
+ */
+export async function status(opts = {}) {
+    const s = await readLive();
+    const a = assess(toAssuranceInput(s));
+    if (opts.json) {
+        console.log(JSON.stringify({ state: s, assurance: a }, (_k, v) => (typeof v === "bigint" ? v.toString() : v), 2));
+        return a.score === a.max ? 0 : 1;
+    }
+    const d = s.decimals;
+    const ratio = s.outstandingSupply === 0n ? Infinity : s.collateralRatioBps / 100;
+    heading("MintBound — live solvency");
+    kv("network", `Creditcoin CC3 (102031) <- Ethereum Sepolia (chainKey ${s.sourceChainKey})`);
+    kv("guard", s.asc);
+    kv("reserve vault", s.vault);
+    heading("Balance sheet");
+    kv("proven reserve", `${units(s.verifiedReserve, d)} @ source height ${s.attestedAtHeight}`);
+    kv("announced exits", `- ${units(s.encumberedReserve, d)} (encumbered, no longer counts)`);
+    kv("haircut", `x ${(s.haircutBps / 100).toFixed(2)}%`);
+    kv("effective backing", `= ${units(s.discountedReserve, d)}`);
+    kv("outstanding supply", `${units(s.outstandingSupply, d)} ${s.symbol}`);
+    kv("headroom to bound", `${units(s.maxMintable, d)}`);
+    console.log("");
+    const usage = s.discountedReserve === 0n
+        ? 0
+        : Number((s.outstandingSupply * 10000n) / s.discountedReserve) / 10000;
+    console.log(`  ${bar(usage)}  ${(usage * 100).toFixed(1)}% of the bound used`);
+    kv("", c.grey(ratio === Infinity ? "no supply outstanding" : `collateral ratio ${ratio.toFixed(0)}%`));
+    heading("Freshness");
+    kv("source tip", String(s.sourceHead));
+    kv("Creditcoin attested", `${s.latestAttestedHeight}  ${c.grey(`(${Math.max(s.sourceHead - s.latestAttestedHeight, 0)} blocks behind tip)`)}`);
+    kv("proof staleness", `${s.stalenessBlocks} / ${s.maxStalenessBlocks} blocks`);
+    kv("verdict", s.fresh ? c.green(`${TICK} fresh`) : c.red(`${CROSS} stale — minting frozen`));
+    heading("Mint gate");
+    const gate = s.solvent && s.fresh && !s.mintFrozen;
+    kv("solvent", s.solvent ? c.green(TICK) : c.red(CROSS));
+    kv("fresh", s.fresh ? c.green(TICK) : c.red(CROSS));
+    kv("circuit breaker", s.mintFrozen ? c.red("engaged") : c.green("clear"));
+    kv("minting", gate ? c.green("PERMITTED") : c.red("FROZEN"));
+    console.log(c.grey("\n  Redemption is never gated on any of the above. Every failure mode here\n" +
+        "  lands on the same side: minting stops, redeeming does not."));
+    heading(`Assurance  ${a.score}/${a.max}`);
+    for (const o of a.obligations) {
+        const mark = o.met ? c.green(TICK) : c.red(CROSS);
+        console.log(`  ${mark} ${o.label.padEnd(22)}${c.grey(String(o.weight).padStart(3))}  ${o.detail}`);
+    }
+    console.log("");
+    console.log(c.grey("  Assurance is a presentation-layer aggregation over six independently\n" +
+        "  checkable obligations, with published weights. No contract reads it and\n" +
+        "  no mint is gated on it — enforcement on-chain is binary."));
+    rule();
+    console.log(c.grey(`  ${EXPLORER.creditcoin}/address/${s.asc}`));
+    console.log(c.grey(`  ${EXPLORER.sepolia}/address/${s.vault}`));
+    console.log("");
+    return gate ? 0 : 1;
+}

package/dist/commands/verify.js

@@ -0,0 +1,164 @@
+import { Contract, Interface, id as keccakId } from "ethers";
+import { proofProvider } from "@gluwa/usc-sdk";
+import { ASC_ABI, ASC_ERRORS, CHAIN_INFO_ABI } from "../abi.js";
+import { CHAIN_INFO_ADDRESS, EXPLORER, RPC, creditcoin } from "../config.js";
+import { providers, readLive } from "../read.js";
+import { c, heading, kv, rule, step, stepFail, stepOk, units } from "../render.js";
+import { describeRevert } from "../revert.js";
+const RESERVE_SNAPSHOT_SIG = keccakId("ReserveSnapshot(address,address,uint256,uint256,uint256)");
+const LOCKED_SIG = keccakId("Locked(address,address,uint256,uint256)");
+function toQueryTuple(p) {
+    return [
+        BigInt(p.chainKey),
+        BigInt(p.headerNumber),
+        p.txBytes,
+        p.merkleProof.root,
+        p.merkleProof.siblings.map((s) => [s.hash, s.isLeft]),
+        p.continuityProof.lowerEndpointDigest,
+        p.continuityProof.roots,
+    ];
+}
+/**
+ * `mintbound verify --source-tx 0x...`
+ *
+ * Walks the entire evidence pipeline for one source-chain transaction and reports what
+ * the Creditcoin precompile makes of it. This is a read-only path end to end: the final
+ * step is an `eth_call`, not a transaction, so it costs nothing and needs no key.
+ *
+ * The point is that you do not have to take MintBound's word for anything. Point this at
+ * a transaction, watch the precompile answer, and decide for yourself.
+ */
+export async function verify(txHash) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(txHash)) {
+        console.error(c.red(`Not a transaction hash: ${txHash}`));
+        return 2;
+    }
+    const cc = creditcoin();
+    const { cc: ccProvider, sep: sepProvider } = providers();
+    const chainKey = Number(cc.config?.sourceChainKey ?? 1);
+    const ascAddr = cc.contracts.MintBoundASC;
+    heading("MintBound — verify source transaction");
+    kv("source tx", txHash);
+    kv("source chain", `Ethereum Sepolia (chainKey ${chainKey})`);
+    kv("verifier", `${ascAddr} on Creditcoin CC3`);
+    console.log("");
+    // ── 1. the transaction itself ───────────────────────────────────────────────
+    step(1, 4, "Fetching source receipt");
+    const receipt = await sepProvider.getTransactionReceipt(txHash);
+    if (!receipt) {
+        stepFail("not found on Sepolia");
+        return 1;
+    }
+    if (receipt.status !== 1) {
+        stepFail(`transaction reverted (status ${receipt.status})`);
+        console.log(c.grey("\n  A reverted source transaction proves nothing and MintBound rejects it\n" +
+            "  outright — the receipt status is part of what the precompile checks."));
+        return 1;
+    }
+    const height = receipt.blockNumber;
+    stepOk(`block ${height}, ${receipt.logs.length} logs`);
+    // Which entry point does this transaction belong to? Decide from the log signatures
+    // actually present, not from a flag the caller passed.
+    const topics = new Set(receipt.logs.flatMap((l) => (l.topics[0] ? [l.topics[0]] : [])));
+    const isSnapshot = topics.has(RESERVE_SNAPSHOT_SIG);
+    const isLock = topics.has(LOCKED_SIG);
+    if (!isSnapshot && !isLock) {
+        stepFail("no MintBound event in this transaction");
+        console.log(c.grey("\n  This transaction carries neither a ReserveSnapshot nor a Locked event, so\n" +
+            "  there is nothing here for the guard to act on. That is a correct rejection,\n" +
+            "  not a failure: an arbitrary transaction must not be able to move the bound."));
+        return 1;
+    }
+    const entry = isSnapshot ? "submitReserveSnapshot" : "mintWithProof";
+    kv("  event found", isSnapshot ? "ReserveSnapshot" : "Locked", 22);
+    kv("  routes to", `${entry}()`, 22);
+    console.log("");
+    // ── 2. attestation ──────────────────────────────────────────────────────────
+    step(2, 4, "Checking attestation via ChainInfo precompile 0x0FD3");
+    const info = new Contract(CHAIN_INFO_ADDRESS, CHAIN_INFO_ABI, ccProvider);
+    const latest = await info.get_latest_attestation_height_and_hash(chainKey);
+    const attestedTip = Number(latest.height);
+    const attested = attestedTip >= height;
+    if (!attested) {
+        const behind = height - attestedTip;
+        stepFail(`height ${height} not yet attested (tip ${attestedTip}, ${behind} blocks behind)`);
+        console.log(c.grey(`\n  Creditcoin attests finalized source blocks, so there is roughly a nine minute\n` +
+            `  lag before any given Sepolia block becomes provable. This one needs about\n` +
+            `  ${Math.ceil((behind * 12) / 60)} more minute(s). That delay is the cost of not trusting a reporter.`));
+        return 1;
+    }
+    stepOk(`height ${height} attested (tip ${attestedTip})`);
+    // ── 3. proof construction ───────────────────────────────────────────────────
+    step(3, 4, "Building Merkle + continuity proof");
+    const builder = new proofProvider.service.ProofBuilder(chainKey, RPC.proofBuilder);
+    let proof;
+    try {
+        const res = await builder.getProof(txHash);
+        if (!res?.success || !res?.data)
+            throw new Error(String(res?.error ?? "unknown"));
+        proof = res.data;
+    }
+    catch (e) {
+        stepFail(String(e?.shortMessage ?? e?.message ?? e).slice(0, 90));
+        console.log(c.grey("\n  Attestation does not imply the proof is servable yet — the Proof Builder's\n" +
+            "  block cache is eventually consistent and returns 422 for a short window\n" +
+            "  after attestation. Try again in a minute."));
+        return 1;
+    }
+    stepOk(`${proof.merkleProof.siblings.length} Merkle siblings, ` +
+        `${proof.continuityProof.roots.length} continuity roots`);
+    // ── 4. the precompile's verdict ─────────────────────────────────────────────
+    step(4, 4, `Calling ${entry}() on CC3 (eth_call, no transaction sent)`);
+    const iface = new Interface([...ASC_ABI, ...ASC_ERRORS]);
+    const asc = new Contract(ascAddr, iface, ccProvider);
+    const query = toQueryTuple(proof);
+    let verdict = "accepted";
+    let reason = "";
+    try {
+        await asc[entry].staticCall(query);
+        stepOk("precompile verified the proof, guard accepted it");
+    }
+    catch (e) {
+        reason = describeRevert(iface, e);
+        if (/processed|consumed|Replay|already/i.test(reason)) {
+            verdict = "already-processed";
+            stepOk("proof is valid but already spent");
+        }
+        else {
+            verdict = "rejected";
+            stepFail(reason.slice(0, 110));
+        }
+    }
+    // ── the answer ──────────────────────────────────────────────────────────────
+    const s = await readLive();
+    heading("Result");
+    if (verdict === "accepted") {
+        console.log("  " +
+            c.green("PROOF VALID") +
+            c.grey(" — the Block Prover precompile confirmed this transaction is in an"));
+        console.log(c.grey("  attested Sepolia block, and the guard's own checks passed on top of it."));
+    }
+    else if (verdict === "already-processed") {
+        console.log("  " + c.cyan("PROOF VALID, ALREADY SPENT"));
+        console.log(c.grey("  The cryptography checks out; the guard has simply seen this query before and\n" +
+            "  will not act on it twice. Replay protection working as designed."));
+    }
+    else {
+        console.log("  " + c.red("REJECTED") + c.grey(` — ${reason.slice(0, 120)}`));
+        console.log(c.grey("\n  A rejection here is the system working. The guard refuses anything it cannot\n" +
+            "  verify rather than falling back to a reported figure."));
+    }
+    console.log("");
+    kv("proven reserve", `${units(s.verifiedReserve, s.decimals)} @ height ${s.attestedAtHeight}`);
+    kv("outstanding supply", `${units(s.outstandingSupply, s.decimals)} ${s.symbol}`);
+    kv("effective backing", units(s.discountedReserve, s.decimals));
+    kv("status", s.solvent && s.fresh && !s.mintFrozen
+        ? c.green("CRYPTOGRAPHICALLY SOLVENT")
+        : c.red("MINTING FROZEN"));
+    kv("parties trusted", s.trustedParties === 0 ? c.green("0") : c.yellow(String(s.trustedParties)));
+    rule();
+    console.log(c.grey(`  ${EXPLORER.sepolia}/tx/${txHash}`));
+    console.log(c.grey(`  ${EXPLORER.creditcoin}/address/${ascAddr}`));
+    console.log("");
+    return verdict === "rejected" ? 1 : 0;
+}

package/dist/config.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Standalone configuration.
+ *
+ * Everything here has a working default. That is deliberate: the whole point of this
+ * CLI is that a stranger can run it against the live deployment without cloning the
+ * repo, funding a wallet, or obtaining a key. If you are running inside the repo the
+ * deployment files are picked up automatically and override the baked-in addresses.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+export const RPC = {
+    creditcoin: process.env.CREDITCOIN_RPC_URL ?? "https://rpc.cc3-testnet.creditcoin.network",
+    sepolia: process.env.SEPOLIA_RPC_URL ?? "https://ethereum-sepolia-rpc.publicnode.com",
+    proofBuilder: process.env.PROOF_BUILDER_URL ?? "https://proof-gen-api.cc3-testnet.creditcoin.network",
+};
+export const EXPLORER = {
+    creditcoin: "https://creditcoin-testnet.blockscout.com",
+    sepolia: "https://sepolia.etherscan.io",
+};
+/** The live CC3 deployment, as of the addresses committed to this repo. */
+const BAKED = {
+    creditcoin: {
+        chainId: 102031,
+        contracts: {
+            MintBoundASC: "0x91FAF68A9E5C0e013b5c01b7AACF4C841A6382f8",
+            WrappedAsset: "0x1f42B80ebac56AF3f023997A4240D3B97476A557",
+            ProvenReserveFeed: "0x5578784ddE6c05c0370119FF68c439847CB307D7",
+            ConventionalPoRFeed: "0xbAceA461241F5D9D27e2308D279AB1add95B226F",
+            SecureMintReference: "0x8f2A246623b000DE0486242f8806b0dDeF2375b9",
+            SolvencyGatedCredit: "0x44082286d90ebB087F34EE4Bc6Bd918B205d7156",
+            SolvencyContinuity: "0x448292774b807B49025002e256d004378f788d07",
+        },
+        config: {
+            sourceChainKey: 1,
+            canonicalVault: "0x1f42B80ebac56AF3f023997A4240D3B97476A557",
+            sourceAsset: "0x91FAF68A9E5C0e013b5c01b7AACF4C841A6382f8",
+            maxStalenessBlocks: 200,
+            haircutBps: 10000,
+        },
+    },
+    sepolia: {
+        chainId: 11155111,
+        contracts: {
+            TestUSD: "0x91FAF68A9E5C0e013b5c01b7AACF4C841A6382f8",
+            ReserveVault: "0x1f42B80ebac56AF3f023997A4240D3B97476A557",
+            SupplyBeacon: "0x448292774b807B49025002e256d004378f788d07",
+        },
+    },
+};
+/**
+ * Prefer an on-disk deployment record when one exists, so that a fresh redeploy is
+ * picked up without editing this file. Fall back to the baked-in addresses otherwise.
+ */
+function load(name) {
+    for (const root of [join(here, "..", "..", ".."), join(here, "..", "..", "..", "..")]) {
+        const p = join(root, "deployments", `${name}.json`);
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, "utf8"));
+            }
+            catch {
+                // A malformed local file should not defeat a working default.
+            }
+        }
+    }
+    return BAKED[name];
+}
+export const creditcoin = () => load("creditcoin");
+export const sepolia = () => load("sepolia");
+export const CHAIN_INFO_ADDRESS = "0x0000000000000000000000000000000000000fD3";
+export const BLOCK_PROVER_ADDRESS = "0x0000000000000000000000000000000000000FD2";

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { attack } from "./commands/attack.js";
+import { claims } from "./commands/claims.js";
+import { status } from "./commands/status.js";
+import { verify } from "./commands/verify.js";
+import { c } from "./render.js";
+const USAGE = `
+${c.bold("mintbound")} — check MintBound's solvency evidence yourself
+
+  ${c.bold("status")}                        the whole balance sheet and assurance vector, live
+  ${c.bold("verify")} --source-tx <hash>     walk one source transaction through the precompile
+  ${c.bold("attack")}                        fire the documented attacks at the live guard
+  ${c.bold("claims")}                        audit every claim our submission makes, live
+
+${c.grey("Options")}
+  --json                        machine-readable output (status only)
+  --help                        this text
+
+${c.grey("Everything here is read-only. No private key, no funded account, no setup — the")}
+${c.grey("Proof Builder is a read API and the guard's entry points are reachable by eth_call,")}
+${c.grey("so a stranger can check every claim MintBound makes without being trusted with")}
+${c.grey("anything. That is the point.")}
+
+${c.grey("Examples")}
+  npx @mintbound/cli status
+  npx @mintbound/cli verify --source-tx 0xc42a211e02ee86e5d92bb0bee2cef1679fbd358e474a044bdfe1e7ff7c9efa9c
+  npx @mintbound/cli attack
+  npx @mintbound/cli claims
+`;
+function arg(argv, name) {
+    const i = argv.indexOf(`--${name}`);
+    if (i >= 0 && argv[i + 1])
+        return argv[i + 1];
+    const inline = argv.find((a) => a.startsWith(`--${name}=`));
+    return inline ? inline.slice(name.length + 3) : undefined;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        return 0;
+    }
+    switch (cmd) {
+        case "status":
+            return status({ json: argv.includes("--json") });
+        case "verify": {
+            const tx = arg(argv, "source-tx") ?? arg(argv, "tx") ?? argv[1];
+            if (!tx || tx.startsWith("--")) {
+                console.error(c.red("verify needs a transaction hash: --source-tx 0x..."));
+                return 2;
+            }
+            return verify(tx);
+        }
+        case "attack":
+            return attack();
+        case "claims":
+            return claims({ json: argv.includes("--json") });
+        default:
+            console.error(c.red(`Unknown command: ${cmd}`));
+            console.log(USAGE);
+            return 2;
+    }
+}
+main()
+    .then((code) => {
+    process.exitCode = code ?? 0;
+})
+    .catch((e) => {
+    console.error(c.red(`\n${e?.shortMessage ?? e?.message ?? e}`));
+    process.exitCode = 1;
+});