@eco-incorp/sauce 0.99.0

package/sdk/dist/verify/decode.js

@@ -0,0 +1,465 @@
+/**
+ * SAUCE SETTLE PAYLOAD WIRE FORMAT — `recipes/settle.sauce.ts` on engine target v12, compiled by
+ * the published Rust compiler.
+ *
+ * `payload := PROGRAM || ARGS`. Byte 0 is the first program byte — there is no header, magic,
+ * version byte or length prefix. The two regions are DISJOINT: the program is a compile-time
+ * constant, the arguments are per-execution bytes the engine reads back through CALLDATA.
+ *
+ * ```
+ * payload     := program , args
+ * program     := 362 bytes                        ; SETTLE_WIRE.PROGRAM_BYTES — invariant
+ * args        := head , token_array
+ * head        := tokens_ptr , minout , recipient  ; three 32-byte big-endian words
+ * tokens_ptr  := word, value = 96                 ; byte offset WITHIN args of token_array
+ * minout      := word, uint256, value = minOut    ; 0 = floor disabled
+ * recipient   := word, uint160 in the LOW 20 bytes, upper 12 zero, MUST be nonzero
+ * token_array := count , token{count}             ; at args + 96
+ * count       := word, uint256, value = tokens.length, MUST be >= 1
+ * token       := word, uint160 in the LOW 20 bytes, upper 12 zero
+ * ```
+ *
+ * So `args` is exactly `128 + 32 * tokens.length` bytes, and `tokens[i]` — in SOURCE order, index 0
+ * is the floor token — sits at `PROGRAM_BYTES + 128 + 32*i`. This is the compiler's appended-args
+ * ABI: a scalar entry argument occupies one word at `PROGRAM_BYTES + slot*32`, and a dynamic array
+ * spends its word on a pointer to `[count][element…]`, ABI-style, rooted at the start of `args`.
+ *
+ * §4 CANONICALITY — WHY THIS IS STRICTER THAN THE ENGINE. Measured on a real v12 runtime, the engine
+ * ACCEPTS five payloads this decoder rejects — `SETTLE_REJECTIONS.filter(r => r.engineAccepts)` is the
+ * list, and the suite pins it, so this prose is a description and not the source of truth. They are: a
+ * `tokens_ptr` other than 96 (it follows any offset), trailing bytes past the token array, a token
+ * word whose upper 12 bytes are dirty (the call target is masked to 160 bits, so it sweeps the same
+ * token), a dirty RECIPIENT word, and a ZERO recipient. The first three move the same tokens against
+ * any ERC20. The last two both follow from one fact: the engine passes the recipient word through
+ * UNMASKED and never inspects it, so what refuses them is the callee's own `address` / zero check —
+ * against a token that omits those (Vyper, older solc, a forwarding proxy) they deliver too, the zero
+ * case to address(0).
+ * Each is a DIFFERENT byte string producing IDENTICAL behavior. Accepting them would make the decode
+ * non-injective and put `encodeSettleProgram`'s re-encode-and-compare (§5) at odds with a
+ * decode-and-compare, so ALL of them are refused — the recipient cases included, precisely because
+ * whether they are caught depends on the callee rather than on the payload. An accepted payload is the UNIQUE
+ * byte encoding of the values it decodes to.
+ *
+ * DO NOT PORT A POSITIONAL DECODER ONTO THIS WIRE. Values here are fixed 32-byte words and the
+ * tokens head word is a POINTER, not a value (see the layout at the top of this file) — so a reader
+ * that walks the tail by position,
+ * as a decoder for a PUSH-prologue encoding must, lands on the offset and returns a plausible
+ * wrong answer instead of failing. That is the one mistake this format invites, and §4 is what
+ * closes it.
+ *
+ * WHAT THIS PROVES. `decodeSettleProgram` is STRUCTURAL: it pins the program's LENGTH and reads the
+ * tail, so it tells you which `(tokens, minOut, recipient)` a payload carries and nothing about
+ * what the 362 program bytes do. `validateSettleProgram` adds the authenticity half — one
+ * `keccak256` over the WHOLE program against `SETTLE_WIRE.PROGRAM_HASH` — and that is now a
+ * complete answer rather than a partial one: because the arguments left the program, a matching
+ * hash means the payload runs the audited `settle.sauce.ts` and nothing else — a statement about
+ * the bytes alone, needing nothing the caller has to compile and compare for themselves.
+ *
+ * Dependency closure is `viem` only (`keccak256`) — no compiler, no `node:*`, no artifact
+ * resolution — so this surface stays safe to import in a browser or an edge runtime. That closure
+ * is the reason `/verify` decodes rather than recompiling-and-comparing: a recompile would put a
+ * 1.96 MB wasm compiler in every consumer's dependency graph to answer a question `viem` answers
+ * with one hash.
+ */
+import { keccak256 } from "viem";
+import { SETTLE_WIRE } from "./wire.js";
+/** Canonical `args` length for `count` tokens: the three head words, the count word, the elements. */
+const argsLengthFor = (count) => BigInt(SETTLE_WIRE.HEAD_BYTES + SETTLE_WIRE.WORD_BYTES) + BigInt(SETTLE_WIRE.WORD_BYTES) * count;
+/** The low 20 bytes of a word — an address's own bits. A value ABOVE this has dirty upper bytes and
+ *  is not a clean address; `dirtyWord` (§ below) reports those upper bytes themselves. */
+const ADDRESS_MASK = (1n << BigInt(SETTLE_WIRE.ADDRESS_BYTES * 8)) - 1n;
+export class SettleDecodeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SettleDecodeError";
+        this.code = code;
+    }
+}
+function toAddress(value) {
+    return ("0x" + value.toString(16).padStart(40, "0"));
+}
+function bytesToHexLocal(bytes) {
+    let hex = "0x";
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, "0");
+    return hex;
+}
+/** Returns `null` (never throws) on malformed hex — odd length, a non-hex character, or a
+ *  non-string argument entirely (a runtime caller bypassing the type system) — so
+ *  `parseSettleProgram` can report it as an `EMPTY`-coded fatal rather than throwing out of a
+ *  function documented to never throw. */
+function hexToBytesLocal(hex) {
+    if (typeof hex !== "string")
+        return null;
+    const clean = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(clean))
+        return null;
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+/** Read the 32-byte big-endian word whose `index`-th slot starts at `slot * 32` within `args`. */
+function wordAt(args, slot) {
+    const start = slot * SETTLE_WIRE.WORD_BYTES;
+    let value = 0n;
+    for (let i = start; i < start + SETTLE_WIRE.WORD_BYTES; i++)
+        value = (value << 8n) | BigInt(args[i]);
+    return value;
+}
+/** Best-effort single left-to-right pass — never throws. This is the shared engine both
+ *  `decodeSettleProgram` (throws on `parse.fatal`) and `bestEffortDecode` (keeps whatever DID
+ *  parse even when a later stage failed) run on top of. */
+export function parseSettleProgram(payload, programBytes = SETTLE_WIRE.PROGRAM_BYTES) {
+    const decodedHex = hexToBytesLocal(payload);
+    const bytes = decodedHex ?? new Uint8Array(0);
+    const result = {
+        bytes,
+        program: null,
+        programHash: null,
+        args: null,
+        tokensOffset: null,
+        minOut: null,
+        recipient: null,
+        recipientWord: null,
+        recipientNonZero: false,
+        tokenCount: null,
+        tokenWords: [],
+        fatal: null,
+    };
+    if (decodedHex === null) {
+        result.fatal = { code: "EMPTY", message: `not a valid hex string: ${render(payload)}` };
+        return result;
+    }
+    if (bytes.length === 0) {
+        result.fatal = { code: "EMPTY", message: "empty payload" };
+        return result;
+    }
+    if (bytes.length < programBytes) {
+        result.fatal = {
+            code: "PROGRAM_TRUNCATED",
+            message: `payload is ${bytes.length} bytes, shorter than the ${programBytes}-byte settle program`,
+        };
+        return result;
+    }
+    result.program = bytes.subarray(0, programBytes);
+    result.programHash = keccak256(bytesToHexLocal(result.program));
+    const args = bytes.subarray(programBytes);
+    result.args = args;
+    // The head plus the array's count word is the smallest readable tail; below that nothing can be
+    // named, so this returns rather than reporting values read past the end of the buffer.
+    const minimumArgs = SETTLE_WIRE.HEAD_BYTES + SETTLE_WIRE.WORD_BYTES;
+    if (args.length < minimumArgs) {
+        result.fatal = {
+            code: "ARGS_TRUNCATED",
+            message: `argument tail is ${args.length} bytes, below the ${minimumArgs}-byte minimum (three head words and the token count)`,
+        };
+        return result;
+    }
+    result.tokensOffset = wordAt(args, 0);
+    result.minOut = wordAt(args, 1);
+    const recipientWord = wordAt(args, 2);
+    result.recipient = recipientWord & ADDRESS_MASK;
+    result.recipientWord = recipientWord;
+    result.recipientNonZero = result.recipient !== 0n;
+    if (result.tokensOffset !== BigInt(SETTLE_WIRE.HEAD_BYTES)) {
+        // Reported at the CANONICAL offset, not at `result.tokensOffset`: this reads the array where a
+        // conforming payload puts it. It does NOT follow the pointer the way the engine does, so for a
+        // non-canonical payload the report and on-chain behaviour can differ -- which is exactly why this
+        // is a fatal code rather than a silent reinterpretation.
+        result.fatal = {
+            code: "TOKENS_OFFSET",
+            message: `tokens pointer is ${result.tokensOffset}, not the canonical ${SETTLE_WIRE.HEAD_BYTES} — the token array must follow the head immediately`,
+        };
+    }
+    result.tokenCount = wordAt(args, SETTLE_WIRE.HEAD_SLOTS);
+    const expected = argsLengthFor(result.tokenCount);
+    if (BigInt(args.length) < expected) {
+        result.fatal = result.fatal ?? {
+            code: "ARGS_TRUNCATED",
+            message: `token count ${result.tokenCount} needs a ${expected}-byte argument tail, but only ${args.length} bytes are present`,
+        };
+        return result; // reading elements past the end would fabricate values
+    }
+    if (BigInt(args.length) > expected) {
+        result.fatal = result.fatal ?? {
+            code: "ARGS_OVERLONG",
+            message: `argument tail is ${args.length} bytes, ${BigInt(args.length) - expected} past the ${expected} bytes ${result.tokenCount} token(s) occupy`,
+        };
+    }
+    const count = Number(result.tokenCount);
+    for (let i = 0; i < count; i++)
+        result.tokenWords.push(wordAt(args, SETTLE_WIRE.HEAD_SLOTS + 1 + i));
+    if (count === 0) {
+        result.fatal = result.fatal ?? {
+            code: "TOKENS_EMPTY",
+            message: "token count is 0 — a settle sweeps at least its floor token",
+        };
+    }
+    // Within the dirty check only: the recipient word precedes the array, so its complaint wins over a
+    // token's. This says nothing about ordering ACROSS codes -- `fatal` is first-wins by check position,
+    // not by byte position, and ARGS_OVERLONG and TOKENS_EMPTY are both recorded above. Trailing slack
+    // plus a dirty recipient reports ARGS_OVERLONG.
+    const dirtyToken = result.tokenWords
+        .map((word, i) => dirtyWord(word, `tokens[${i}]`))
+        .find((message) => message !== null);
+    const dirty = dirtyWord(recipientWord, "recipient") ?? dirtyToken ?? null;
+    if (dirty !== null) {
+        result.fatal = result.fatal ?? { code: "DIRTY_ADDRESS_WORD", message: dirty };
+    }
+    if (!result.recipientNonZero) {
+        result.fatal = result.fatal ?? {
+            code: "ZERO_RECIPIENT",
+            message: "recipient word decodes to the zero address",
+        };
+    }
+    return result;
+}
+/** The §4 rule for one address word: the 12 bytes above the address must be zero. Returns the
+ *  message for a dirty word, `null` for a clean one. */
+function dirtyWord(word, label) {
+    const upper = word >> BigInt(SETTLE_WIRE.ADDRESS_BYTES * 8);
+    return upper === 0n
+        ? null
+        : `${label} has nonzero bytes above its ${SETTLE_WIRE.ADDRESS_BYTES}-byte address (upper 0x${upper.toString(16)}) — the engine masks them away, so accepting this would make two byte strings decode alike`;
+}
+function render(payload) {
+    try {
+        return JSON.stringify(payload).slice(0, 80);
+    }
+    catch {
+        // `payload` was a type JSON.stringify itself rejects (e.g. a bigint) — never throw out of a
+        // function documented to always return a report.
+        return String(payload).slice(0, 80);
+    }
+}
+function parseToDecoded(parse) {
+    const { program, programHash, args, minOut, recipient, tokenWords } = parse;
+    if (program === null ||
+        programHash === null ||
+        args === null ||
+        minOut === null ||
+        recipient === null ||
+        tokenWords.length === 0) {
+        return null;
+    }
+    const tokens = tokenWords.map((w) => toAddress(w & ADDRESS_MASK));
+    return {
+        tokens,
+        minOut,
+        recipient: toAddress(recipient),
+        floorToken: tokens[0],
+        program: bytesToHexLocal(program),
+        programHash,
+        args: bytesToHexLocal(args),
+        argsSize: args.length,
+        payloadSize: parse.bytes.length,
+    };
+}
+/** Decode whenever the shape is well-formed enough to name a full `(tokens, minOut, recipient)` —
+ *  even when a check that does not block reading (a trailing-slack tail, a dirty address word, a
+ *  zero recipient) would make `decodeSettleProgram` throw — so a rejected payload's decoded intent is
+ *  still visible to a caller debugging the rejection.
+ *
+ *  DECLINES wherever the report would not match execution — the whole point being that on a hostile
+ *  payload, reporting nothing beats reporting a wrong answer confidently. Two cases:
+ *
+ *  - a non-canonical tokens pointer: the engine follows it, this reads at the canonical offset, so the
+ *    two name different TOKENS.
+ *  - a dirty RECIPIENT word: `recipient` is masked here, but the engine does not mask that word (§4),
+ *    so execution addresses a different 256-bit key than the masked answer would suggest.
+ *
+ *  A dirty TOKEN word is NOT declined: the engine masks a call target to 160 bits, so there the masked
+ *  answer is exactly what executes, and reporting it is what shows the payload's true meaning. */
+export function bestEffortDecode(parse) {
+    // Both declines read STATE, not `fatal.code`. Gating on the code would be correct only while the
+    // pointer check is the first non-returning fatal: add an earlier one, reorder the scan, or hand this
+    // a caller-built `SettleParse` (the type is exported and is this function's only parameter) and the
+    // decline would silently stop firing -- reporting tokens read at offset 96 for a payload the engine
+    // reads elsewhere, the exact wrong answer this exists to refuse.
+    if (parse.tokensOffset !== null && parse.tokensOffset !== BigInt(SETTLE_WIRE.HEAD_BYTES))
+        return null;
+    if (parse.recipientWord !== null && parse.recipientWord !== (parse.recipient ?? 0n))
+        return null;
+    return parseToDecoded(parse);
+}
+/**
+ * Decode a settle payload back into `(tokens, minOut, recipient)`. STRICT: rejects a non-canonical
+ * tokens pointer, a tail longer or shorter than the token count implies, an address word with
+ * dirty upper bytes, and a zero recipient — see §4 for why. Throws `SettleDecodeError` (carrying a
+ * stable `.code`) on any of the failures in `SettleFailureCode`.
+ *
+ * This is a STRUCTURAL decode: it proves the payload is `362 bytes || a canonical argument tail`.
+ * It does NOT prove those 362 bytes are the settle program you audited — any 362-byte prefix
+ * passes. Use `validateSettleProgram` when that matters, which is nearly always.
+ */
+export function decodeSettleProgram(payload, programBytes = SETTLE_WIRE.PROGRAM_BYTES) {
+    const parse = parseSettleProgram(payload, programBytes);
+    if (parse.fatal) {
+        throw new SettleDecodeError(parse.fatal.code, `decodeSettleProgram: ${parse.fatal.message}`);
+    }
+    const decoded = parseToDecoded(parse);
+    if (decoded === null) {
+        // Unreachable given parse.fatal === null, but keeps the return type honest.
+        throw new SettleDecodeError("PROGRAM_TRUNCATED", "decodeSettleProgram: incomplete parse");
+    }
+    return decoded;
+}
+/**
+ * `decodeSettleProgram` plus the authenticity pin: the payload's 362 program bytes must hash to
+ * `SETTLE_WIRE.PROGRAM_HASH`. Because the arguments no longer live inside the program, a match
+ * means the payload runs the audited `recipes/settle.sauce.ts` and nothing else — the whole
+ * question, not the structural half.
+ *
+ * Throws `SettleDecodeError` with code `PROGRAM_HASH` when the program is a different 362 bytes,
+ * and whatever `decodeSettleProgram` would throw otherwise.
+ *
+ * `accepted` overrides the pin. The dependency is a caret range and `SETTLE_WIRE` documents that a
+ * codegen change is answered by RE-PINNING — at which point every intent already on chain carries the
+ * OLD program, and a single hard-coded pin makes all of them unverifiable. Pass the pins you accept
+ * (the current one plus any historical ones) to keep those payloads readable across a re-pin.
+ *
+ * A PIN IS A HASH *AND* A LENGTH, which is why a bare hash is not enough. The payload is split into
+ * program and argument tail at a byte offset, before any hash is computed — so if a re-pin changes the
+ * program's length (the likely outcome of a codegen change), splitting a historical payload at the NEW
+ * length yields a wrong program and a truncated tail, and it dies as `ARGS_TRUNCATED` without any hash
+ * ever being compared. Each entry may be `{ hash, bytes }`; a bare `Hex` means the CURRENT
+ * `SETTLE_WIRE.PROGRAM_BYTES` and is only safe for a same-length re-pin. Candidates are tried in order
+ * and the first whose program hash matches wins. Defaults to the current pin.
+ */
+export function validateSettleProgram(payload, accepted = [
+    { hash: SETTLE_WIRE.PROGRAM_HASH, bytes: SETTLE_WIRE.PROGRAM_BYTES },
+]) {
+    // Compared case-insensitively: `programHash` is always viem's lowercase keccak, so a historical pin
+    // supplied in any other spelling would silently fail to match and orphan exactly the payloads this
+    // parameter exists to keep readable -- surfacing through the intent path as a bare `null`.
+    const pins = accepted.map((pin) => typeof pin === "string"
+        ? { hash: pin.toLowerCase(), bytes: SETTLE_WIRE.PROGRAM_BYTES }
+        : { hash: pin.hash.toLowerCase(), bytes: pin.bytes });
+    // Two kinds of failure, and they are NOT interchangeable. A pin whose length does not fit the
+    // payload yields a parse error about bytes read at the wrong offset -- an artefact of trying that
+    // candidate, not a fact about the payload. A pin that parses but does not match is the real answer:
+    // these are not the audited program. So a hash mismatch always outranks a length-mismatch parse
+    // error, whatever order the pins were supplied in; otherwise `.code` would depend on pin order and a
+    // payload with a perfectly canonical tail could be reported as having a malformed one.
+    //
+    // That precedence is the guarantee, and it is the whole of it. Among parse errors there is no such
+    // ordering: each is an artefact of the candidate that produced it, and the FIRST supplied pin's is
+    // the one reported -- so with several pins and no match at all, the code can still differ by pin
+    // order (a 362-byte program read at 338 reports TOKENS_OFFSET where reading it at 362 reports
+    // ARGS_TRUNCATED). Diagnostic only: through `intent.ts` every one of them collapses to `null`, and
+    // with a single pin -- the default and common case -- there is no order to depend on.
+    let hashMismatch = null;
+    let parseError = null;
+    for (const pin of pins) {
+        let candidate;
+        try {
+            candidate = decodeSettleProgram(payload, pin.bytes);
+        }
+        catch (error) {
+            parseError = parseError ?? error;
+            continue;
+        }
+        if (candidate.programHash.toLowerCase() === pin.hash)
+            return candidate;
+        hashMismatch =
+            hashMismatch ??
+                new SettleDecodeError("PROGRAM_HASH", `validateSettleProgram: program hashes to ${candidate.programHash}, not the pinned ${pin.hash}`);
+    }
+    if (hashMismatch !== null)
+        throw hashMismatch;
+    if (parseError !== null)
+        throw parseError;
+    // Only reachable for an empty pin list, which accepts nothing and would otherwise return a
+    // successful decode of a program no caller vouched for.
+    throw new SettleDecodeError("PROGRAM_HASH", "validateSettleProgram: no accepted program pins were supplied");
+}
+/** `BigInt` is the wrong gate for a caller-supplied address: `BigInt("")` is `0n` rather than a throw,
+ *  so an empty string would encode as `address(0)` and sweep it; and malformed hex raises `SyntaxError`,
+ *  where every other rejection here is a `RangeError` callers already catch. Require the canonical
+ *  `0x`-prefixed spelling and report both as `RangeError`. */
+function coerceAddressValue(value, label) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) {
+        throw new RangeError(`encodeSettleProgram: ${label} is not a 0x-prefixed hex address: ${String(value)}`);
+    }
+    return BigInt(value);
+}
+/**
+ * §5 of the wire spec — the cheaper, EQUIVALENT alternative to scan-and-check: when the caller
+ * already knows the intended `(tokens, minOut, recipient)` (the normal case — they asked for the
+ * swap), encode them directly and `memcmp`/hash-compare the whole payload rather than decoding.
+ * Given §4 this produces the UNIQUE canonical encoding, so `encodeSettleProgram(...)` equals
+ * `payload` exactly when `validateSettleProgram(payload)` succeeds with those values — in one
+ * comparison, with no parser exposed to a hostile input at all. This is the recommended
+ * non-TypeScript (Solidity/Go/Python) implementation, where a payload is bytes and the comparison is
+ * a plain `memcmp`.
+ *
+ * THE EQUIVALENCE IS OVER BYTES, NOT OVER HEX SPELLINGS. `validateSettleProgram` accepts any spelling
+ * of the same bytes — uppercase, a `0X` prefix, no prefix at all — while this returns canonical
+ * lowercase `0x`. So `validateSettleProgram(p.toUpperCase())` succeeds where
+ * `encodeSettleProgram(...) === p.toUpperCase()` is `false`. A string `===` is only equivalent once
+ * both sides are in canonical spelling; normalize first, or compare decoded bytes.
+ *
+ * `programHex` is supplied by the caller — pass the program you compiled yourself. There is
+ * deliberately no default: the bytes you compare against should be ones you derived, not ones
+ * shipped alongside the claim they support. `SETTLE_WIRE.PROGRAM_HASH` is what to check them
+ * against once you have them.
+ */
+export function encodeSettleProgram(tokens, minOut, recipient, programHex) {
+    if (tokens.length === 0)
+        throw new RangeError("encodeSettleProgram: tokens must have at least one entry");
+    const tokenValues = tokens.map((token, i) => coerceAddressValue(token, `tokens[${i}]`));
+    const recipientValue = coerceAddressValue(recipient, "recipient");
+    if (recipientValue === 0n)
+        throw new RangeError("encodeSettleProgram: recipient must be nonzero");
+    // Negatives need their own rejection, not just the upper bound: `-1n > ADDRESS_MASK` is FALSE and
+    // `-1n === 0n` is FALSE, so a negative clears both guards -- and the write loop below terminates on
+    // `value > 0n` before writing a byte, leaving an all-zero word. A negative recipient would encode as
+    // address(0), defeating the nonzero check above; a negative token would sweep it.
+    for (const [i, value] of tokenValues.entries()) {
+        if (value < 0n || value > ADDRESS_MASK) {
+            throw new RangeError(`encodeSettleProgram: tokens[${i}] does not fit in ${SETTLE_WIRE.ADDRESS_BYTES} bytes`);
+        }
+    }
+    if (recipientValue < 0n || recipientValue > ADDRESS_MASK) {
+        throw new RangeError(`encodeSettleProgram: recipient does not fit in ${SETTLE_WIRE.ADDRESS_BYTES} bytes`);
+    }
+    // Guarded like the addresses above, and for the same reason: a runtime caller bypassing the type
+    // system (minOut deserialized from JSON as a number) would otherwise reach the word-write loop and
+    // raise TypeError from a BigInt mix, where every rejection here is a RangeError callers catch.
+    if (typeof minOut !== "bigint")
+        throw new RangeError(`encodeSettleProgram: minOut must be a bigint, got ${typeof minOut}`);
+    if (minOut < 0n || minOut >= 1n << 256n)
+        throw new RangeError(`encodeSettleProgram: minOut ${minOut} is out of uint256 range`);
+    const programBytes = hexToBytesLocal(programHex);
+    if (programBytes === null)
+        throw new RangeError(`encodeSettleProgram: programHex is not valid hex: ${programHex}`);
+    // Deliberately NOT compared against `SETTLE_WIRE.PROGRAM_BYTES`. `programHex` is the program the
+    // caller compiled, and §5 offers this as the equivalent of `validateSettleProgram` — which now
+    // accepts historical pins of other lengths. Pinning the current constant here would make the two
+    // halves of that equivalence diverge for exactly the re-pin `ProgramPin.bytes` exists to survive.
+    if (programBytes.length === 0) {
+        throw new RangeError("encodeSettleProgram: programHex is empty");
+    }
+    const words = [
+        BigInt(SETTLE_WIRE.HEAD_BYTES),
+        minOut,
+        recipientValue,
+        BigInt(tokenValues.length),
+        ...tokenValues,
+    ];
+    const out = new Uint8Array(programBytes.length + words.length * SETTLE_WIRE.WORD_BYTES);
+    out.set(programBytes, 0);
+    words.forEach((value, slot) => {
+        let v = value;
+        for (let i = SETTLE_WIRE.WORD_BYTES - 1; i >= 0 && v > 0n; i--) {
+            out[programBytes.length + slot * SETTLE_WIRE.WORD_BYTES + i] = Number(v & 0xffn);
+            v >>= 8n;
+        }
+    });
+    return bytesToHexLocal(out);
+}
+//# sourceMappingURL=decode.js.map

package/sdk/dist/verify/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../src/verify/decode.ts"],"names":[],"mappings":"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"}

package/sdk/dist/verify/index.d.ts

@@ -0,0 +1,5 @@
+export { SETTLE_WIRE } from "./wire.js";
+export { decodeSettleProgram, validateSettleProgram, encodeSettleProgram, parseSettleProgram, bestEffortDecode, SettleDecodeError, type DecodedSettleProgram, type ProgramPin, type SettleFailureCode, type SettleParse, type Address20, } from "./decode.js";
+export { SETTLE_PROGRAM, SETTLE_VECTORS, SETTLE_REJECTIONS, settlePayload, type ConformanceVector, type RejectionVector, } from "./vectors.js";
+export { decodeSettleCall, extractEvmSettleFromCalls, extractEvmSettleFromIntent, type DecodedSettleCall, type ExtractedEvmSettle, type IntentCallLike, type IntentLike, } from "./intent.js";
+//# sourceMappingURL=index.d.ts.map

package/sdk/dist/verify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC"}

package/sdk/dist/verify/index.js

@@ -0,0 +1,37 @@
+// @eco-incorp/sauce/verify — turn a compiled Sauce settle payload's bytes back into the
+// `(tokens, minOut, recipient)` it will run with, and prove the program half is the audited one.
+//
+// That is the whole job. Dependency closure is `viem` ONLY (no node:fs, no compiler, no @solana/*,
+// no artifact resolution, no program source on disk), so this surface is safe to import anywhere —
+// including a browser or an edge runtime. That closure is the reason this decodes rather than
+// recompiling-and-comparing: a recompile would put a 1.96 MB wasm compiler in every consumer's
+// dependency graph to answer a question `viem` alone answers with one `keccak256`.
+//
+// WHICH PROGRAMS. The settle program this decodes is what the PUBLISHED RUST COMPILER emits for
+// `recipes/settle.sauce.ts` — the only compiler this package ships against. `main` takes
+// `(tokens, minOut, recipient)` as RUNTIME entry arguments, so the compiled program is a
+// 362-byte constant and the arguments ride the payload AFTER it, as 32-byte big-endian words the
+// engine reads back through CALLDATA. `SETTLE_VECTORS` is the conformance corpus and
+// `verify.compile.test.ts` recompiles the program and re-pins it on every run.
+//
+// SCOPE, stated plainly, in two tiers:
+//   • `decodeSettleProgram` is STRUCTURAL. It pins the program's LENGTH and reads the argument tail,
+//     so it names the tokens, floor and recipient a payload carries and nothing about what those
+//     362 bytes do. It is strict about the encoding (§4 of decode.ts: the canonical tokens pointer,
+//     no trailing slack, no dirty bytes above an address, a nonzero recipient), so an accepted
+//     payload is the UNIQUE byte encoding of the values it decodes to.
+//   • `validateSettleProgram` adds the authenticity half: one `keccak256` over the WHOLE program
+//     against `SETTLE_WIRE.PROGRAM_HASH`. Because the arguments are no longer inside the program,
+//     a match means the payload runs the audited `settle.sauce.ts` and nothing else — the complete
+//     answer, from bytes alone, with no compiler. Prefer it; the structural tier exists for callers
+//     inspecting a payload they already know is not canonical.
+//
+// The `intent.js` exports (`decodeSettleCall`, `extractEvmSettleFromIntent`) go one wrapper further:
+// a producer hands you an intent whose `route.calls[]` ends in a `Pot.cook(...)` call, not a bare
+// payload, so these unwrap the cook calldata and hand the settle program to `validateSettleProgram`
+// — same viem-only dependency closure, same strict decode, and identification by program hash.
+export { SETTLE_WIRE } from "./wire.js";
+export { decodeSettleProgram, validateSettleProgram, encodeSettleProgram, parseSettleProgram, bestEffortDecode, SettleDecodeError, } from "./decode.js";
+export { SETTLE_PROGRAM, SETTLE_VECTORS, SETTLE_REJECTIONS, settlePayload, } from "./vectors.js";
+export { decodeSettleCall, extractEvmSettleFromCalls, extractEvmSettleFromIntent, } from "./intent.js";
+//# sourceMappingURL=index.js.map

package/sdk/dist/verify/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,iGAAiG;AACjG,EAAE;AACF,mGAAmG;AACnG,mGAAmG;AACnG,8FAA8F;AAC9F,+FAA+F;AAC/F,mFAAmF;AACnF,EAAE;AACF,gGAAgG;AAChG,yFAAyF;AACzF,yFAAyF;AACzF,iGAAiG;AACjG,qFAAqF;AACrF,+EAA+E;AAC/E,EAAE;AACF,uCAAuC;AACvC,qGAAqG;AACrG,iGAAiG;AACjG,oGAAoG;AACpG,+FAA+F;AAC/F,uEAAuE;AACvE,iGAAiG;AACjG,kGAAkG;AAClG,mGAAmG;AACnG,oGAAoG;AACpG,+DAA+D;AAC/D,EAAE;AACF,qGAAqG;AACrG,kGAAkG;AAClG,oGAAoG;AACpG,+FAA+F;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAMlB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,aAAa,GAGd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,GAK3B,MAAM,aAAa,CAAC"}

package/sdk/dist/verify/intent.d.ts

@@ -0,0 +1,105 @@
+import { type Hex } from "viem";
+import { type DecodedSettleProgram, type ProgramPin } from "./decode.js";
+export interface DecodedSettleCall extends DecodedSettleProgram {
+    /** Index of the `cook` ingredient that validated as the settle payload. Always 0 — a v12 cook
+     *  carries one program, and on a v1 `SauceRouter` only ingredient 0 is examined. Kept as a field
+     *  because it is what the caller must reason about, not because it varies. */
+    ingredientIndex: number;
+    /** How many ingredients the cook carried. **A caller on a v1 `SauceRouter` must require this to be
+     *  1.** On a `V12Pot` the rest are inert, so a settle here is the whole call; a SauceRouter executes
+     *  EVERY ingredient, so `cook([settlePayload, drainPayload])` validates index 0 and returns a clean
+     *  settle while the drain runs too. That is the one hazard in this module a caller cannot see from
+     *  `(tokens, minOut, recipient)` — hence this count, in the same spirit as `target`. Always 1 for a
+     *  v12 cook, which carries one program by signature. */
+    ingredientCount: number;
+    /**
+     * The interpreter the cook names, for a v12 `cook(address engine, bytes program)`; `undefined` for
+     * a v1 `SauceRouter.cook(bytes[])`, which has no such field.
+     *
+     * **A verifier must check this, and this module cannot do it.** Validating the program proves
+     * which BYTES run, not what runs them: the audited settle program on an attacker-chosen engine is
+     * an attacker-chosen computation. Only the caller knows which engines it trusts, so compare
+     * against your own allow-list — **case-insensitively**, since this is lower-cased (like every
+     * other address here) while a checksummed constant is not. It is reported for the same reason
+     * `ingredientCount` is: a hazard visible in the calldata but not in
+     * `(tokens, minOut, recipient)`.
+     */
+    engine?: `0x${string}`;
+}
+/**
+ * Decodes one `Pot.cook(address,bytes)` / `SauceRouter.cook(bytes[])` call and returns the settle payload it
+ * carries — or `null` if the calldata is not a `cook` call, or ingredient 0 is not the settle payload.
+ * Never throws for a non-cook / non-settle input: a mismatched selector, malformed ABI, or a non-settle
+ * ingredient 0 all return `null`.
+ *
+ * The index-0 rule is a `V12Pot` property, and on a v1 `SauceRouter` it cuts BOTH ways, because a
+ * SauceRouter executes EVERY ingredient. A settle at index ≥1 reads as `null` here (a missed settle —
+ * harmless); but `cook([settlePayload, drainPayload])` on a SauceRouter validates index 0, returns the
+ * settle, and the drain runs too — a settle reported for a call that does more than settle. The
+ * returned `ingredientCount` is how a caller detects that: require it to be 1 on a SauceRouter. So a
+ * non-null result is a statement about a v12 cook ONLY. On a SauceRouter it is not sufficient, for the
+ * same reason `extractEvmSettleFromCalls` is not sufficient across `route.calls[]`. The detection IS `validateSettleProgram` (the pinned
+ * program hash, plus a canonical tail), so an accepted ingredient is the audited settle program AND the
+ * unique byte encoding of the `(tokens, minOut, recipient)` reported.
+ */
+export declare function decodeSettleCall(callData: Hex, accepted?: readonly (Hex | ProgramPin)[]): DecodedSettleCall | null;
+/** An intent call, duck-typed: only `data` (the cook calldata) is required; `target` (the Pot address)
+ *  is carried through when present. Matches eco-solver's `Call` (`{ data, target, value }`). */
+export interface IntentCallLike {
+    data: Hex;
+    target?: `0x${string}`;
+}
+export interface ExtractedEvmSettle extends DecodedSettleCall {
+    /** Index of the `route.calls[]` entry the settle cook was found in. */
+    callIndex: number;
+    /** The call's `target` (the Pot / router address), when the input carried one. */
+    target?: `0x${string}`;
+}
+/**
+ * Scans an intent's `route.calls[]` and returns the settle params from the first `cook` call carrying
+ * the settle payload — the EVM settle in a batch is a `Pot.cook(settleBytecodes)` alongside a
+ * `Pot.cook(swapBytecodes)`, so this finds it by CONTENT (which cook validates as settle), not by
+ * position. `null` if no call carries one.
+ *
+ * LOCATES THE SETTLE; DOES NOT CLEAR THE INTENT. Unlike a cook's sibling ingredients — where only
+ * ingredient 0 runs, so reading further would describe dead bytes — EVERY entry in `route.calls[]`
+ * executes. This returns the first entry that validates and leaves the others UNEXAMINED, so a
+ * non-null result answers "this intent contains the audited settle, with these parameters" and NOT
+ * "this intent does only that": in `[cook([drain]), cook([settle])]` the drain is real, executes
+ * first, and is not reported. A caller deciding whether an intent is safe must check `callIndex`
+ * against its own expectation and account for the remaining calls itself.
+ *
+ * AND IT MUST VALIDATE `target` AND `engine`. Matching is on a cook selector and the program bytes
+ * ONLY — nothing here looks at the callee or the interpreter.
+ *
+ * `target`: the one-program rule that makes a non-null result meaningful is a property of
+ * `V12Pot.cook`, so it says nothing about an arbitrary contract that merely exposes that selector.
+ * For `[{ target: attackerContract, data: cook(engine, canonicalSettlePayload) }]` this returns the
+ * correct `(tokens, minOut, recipient)` while the attacker's `cook` ignores the payload entirely.
+ * Compare it against a V12Pot address you trust; unvalidated, the parameters describe bytes that
+ * were handed to an unknown contract.
+ *
+ * `engine`: validating the program proves which BYTES run, not what runs them. The audited settle
+ * program on an attacker-chosen interpreter is an attacker-chosen computation, and the interpreter
+ * is a plain `cook` argument the producer picks. Compare it against your own allow-list,
+ * CASE-INSENSITIVELY — it is reported lower-cased here, and a checksummed constant will not match
+ * with `===`. It is `undefined` only for a v1 `SauceRouter.cook(bytes[])`, which names no engine.
+ *
+ * Both are carried on the result for exactly these checks. Neither is validated here, because only
+ * the caller knows which Pots and which interpreters it trusts.
+ */
+export declare function extractEvmSettleFromCalls(calls: readonly IntentCallLike[], accepted?: readonly (Hex | ProgramPin)[]): ExtractedEvmSettle | null;
+/** An intent, duck-typed to just the calls this reads — so it accepts eco-solver's `Intent` (and its
+ *  persisted schema) without importing either. */
+export interface IntentLike {
+    route: {
+        calls: readonly IntentCallLike[];
+    };
+}
+/**
+ * Extracts the EVM settle params `(tokens, minOut, recipient)` from an intent object — the thin
+ * intent-level wrapper over `extractEvmSettleFromCalls`. Duck-typed on `{ route: { calls } }`, so it takes
+ * an eco-solver `Intent` (runtime or persisted) as-is. `null` if the intent carries no settle cook.
+ */
+export declare function extractEvmSettleFromIntent(intent: IntentLike, accepted?: readonly (Hex | ProgramPin)[]): ExtractedEvmSettle | null;
+//# sourceMappingURL=intent.d.ts.map