otto-intel-mcp 0.1.2 → 0.1.4

package/dist/vendor/lp-v3/lp-v3-atomic-read-rpc.d.ts

@@ -0,0 +1,49 @@
+import { type Hex } from 'viem';
+import { z } from 'zod';
+import type { LpV3AtomicCall } from './lp-v3-atomic-contract.js';
+import type { LpV3JournalTransaction, LpV3ReadHoldReason } from './lp-v3-atomic-read-contract.js';
+import type { LpV3AtomicSettlementEvidence } from './lp-v3-atomic-settlement.js';
+export declare class LpV3ReadFailure extends Error {
+    readonly reason: LpV3ReadHoldReason;
+    constructor(reason: LpV3ReadHoldReason);
+}
+export declare function requireRead(value: unknown, reason: LpV3ReadHoldReason): asserts value;
+export interface LpV3ReadBlock {
+    number: string;
+    hash: Hex;
+    parentHash: Hex;
+    timestamp: number;
+    transactions: Hex[];
+}
+export declare function readBlock(raw: unknown, reason: LpV3ReadHoldReason): LpV3ReadBlock;
+declare const rawTransaction: z.ZodObject<{
+    type: z.ZodLiteral<"0x2">;
+    hash: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    chainId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    from: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    to: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    value: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    input: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    nonce: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    gas: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    maxFeePerGas: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    maxPriorityFeePerGas: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    accessList: z.ZodArray<z.ZodObject<{
+        address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        storageKeys: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+    }, z.core.$strip>>;
+    r: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    s: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    yParity: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    v: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    blockNumber: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    blockHash: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    transactionIndex: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>;
+export type LpV3ReadTransaction = z.infer<typeof rawTransaction>;
+/** Reconstruct the exact signed EIP-1559 envelope. A provider's hash/from labels
+ * cannot substitute for the journal hash or recovered signer. No key is used.
+ */
+export declare function readSignedTransaction(raw: unknown, expected: LpV3JournalTransaction, call: LpV3AtomicCall): Promise<LpV3ReadTransaction>;
+export declare function readReceipt(raw: unknown, tx: LpV3ReadTransaction, block: LpV3ReadBlock): LpV3AtomicSettlementEvidence['receipts'][number];
+export {};

package/dist/vendor/lp-v3/lp-v3-atomic-read-rpc.js

@@ -0,0 +1,88 @@
+import { keccak256, recoverAddress, toRlp } from 'viem';
+import { z } from 'zod';
+export class LpV3ReadFailure extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+export function requireRead(value, reason) { if (!value)
+    throw new LpV3ReadFailure(reason); }
+const quantity = z.string().regex(/^0x(?:0|[1-9a-fA-F][0-9a-fA-F]{0,63})$/).transform(s => s.toLowerCase());
+const data = z.string().regex(/^0x(?:[0-9a-fA-F]{2})*$/).transform(s => s.toLowerCase());
+const address = z.string().regex(/^0x[0-9a-fA-F]{40}$/).transform(s => s.toLowerCase());
+const word = z.string().regex(/^0x[0-9a-fA-F]{64}$/).transform(s => s.toLowerCase());
+const hash = word.refine(s => !/^0x0{64}$/.test(s));
+const number = (value) => { const n = BigInt(value); requireRead(n <= BigInt(Number.MAX_SAFE_INTEGER), 'RECEIPT_MISMATCH'); return Number(n); };
+const parsedBlock = z.object({ number: quantity, hash, parentHash: word, timestamp: quantity, transactions: z.array(hash).max(100_000) });
+export function readBlock(raw, reason) {
+    const p = parsedBlock.safeParse(raw);
+    requireRead(p.success, reason);
+    const b = p.data, timestamp = number(b.timestamp);
+    requireRead(timestamp > 0, reason);
+    requireRead(new Set(b.transactions).size === b.transactions.length, reason);
+    return { number: BigInt(b.number).toString(), hash: b.hash, parentHash: b.parentHash, timestamp, transactions: b.transactions };
+}
+const rawTransaction = z.object({
+    type: z.literal('0x2'), hash, chainId: quantity, from: address, to: address, value: quantity,
+    input: data, nonce: quantity, gas: quantity, maxFeePerGas: quantity, maxPriorityFeePerGas: quantity,
+    accessList: z.array(z.object({ address, storageKeys: z.array(word).max(1024) })).max(1024),
+    r: word, s: word, yParity: quantity.optional(), v: quantity.optional(),
+    blockNumber: quantity, blockHash: hash, transactionIndex: quantity,
+});
+const curveN = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+function rlpQuantity(value) { const n = BigInt(value); if (n === 0n)
+    return '0x'; const hex = n.toString(16); return `0x${hex.length % 2 ? '0' : ''}${hex}`; }
+/** Reconstruct the exact signed EIP-1559 envelope. A provider's hash/from labels
+ * cannot substitute for the journal hash or recovered signer. No key is used.
+ */
+export async function readSignedTransaction(raw, expected, call) {
+    requireRead(raw !== null && typeof raw === 'object' && raw.blockHash !== null, 'TRANSACTION_UNAVAILABLE');
+    const p = rawTransaction.safeParse(raw);
+    requireRead(p.success, 'TRANSACTION_MISMATCH');
+    const tx = p.data;
+    requireRead(tx.hash === expected.transactionHash && BigInt(tx.nonce).toString() === expected.nonce && BigInt(tx.nonce) < 1n << 64n
+        && BigInt(tx.chainId) === 8453n && tx.from === call.from && tx.to === call.to && tx.input === call.data && BigInt(tx.value).toString() === call.value
+        && BigInt(tx.gas) > 0n && BigInt(tx.maxPriorityFeePerGas) <= BigInt(tx.maxFeePerGas), 'TRANSACTION_MISMATCH');
+    const normalizeParity = (v) => { const n = BigInt(v); return n === 27n || n === 28n ? n - 27n : n; };
+    const parity = tx.yParity !== undefined ? BigInt(tx.yParity) : tx.v !== undefined ? normalizeParity(tx.v) : -1n;
+    requireRead((parity === 0n || parity === 1n) && (tx.v === undefined || normalizeParity(tx.v) === parity), 'TRANSACTION_MISMATCH');
+    requireRead(BigInt(tx.r) > 0n && BigInt(tx.r) < curveN && BigInt(tx.s) > 0n && BigInt(tx.s) <= curveN / 2n, 'TRANSACTION_MISMATCH');
+    const fields = [rlpQuantity(tx.chainId), rlpQuantity(tx.nonce), rlpQuantity(tx.maxPriorityFeePerGas), rlpQuantity(tx.maxFeePerGas), rlpQuantity(tx.gas), tx.to, rlpQuantity(tx.value), tx.input, tx.accessList.map(a => [a.address, a.storageKeys])];
+    const unsigned = `0x02${toRlp(fields).slice(2)}`;
+    requireRead(unsigned === expected.request.transaction.toLowerCase(), 'TRANSACTION_MISMATCH');
+    const signed = `0x02${toRlp([...fields, rlpQuantity(`0x${parity.toString(16)}`), rlpQuantity(tx.r), rlpQuantity(tx.s)]).slice(2)}`;
+    requireRead(keccak256(signed) === expected.transactionHash, 'TRANSACTION_MISMATCH');
+    try {
+        requireRead((await recoverAddress({ hash: keccak256(unsigned), signature: { r: tx.r, s: tx.s, yParity: Number(parity) } })).toLowerCase() === call.from, 'TRANSACTION_MISMATCH');
+    }
+    catch {
+        throw new LpV3ReadFailure('TRANSACTION_MISMATCH');
+    }
+    return tx;
+}
+const rawLog = z.object({ address, topics: z.array(word).min(1).max(4), data, logIndex: quantity,
+    transactionHash: hash, transactionIndex: quantity, blockNumber: quantity, blockHash: hash, removed: z.literal(false) });
+const rawReceipt = z.object({ transactionHash: hash, from: address, to: address, blockNumber: quantity, blockHash: hash,
+    transactionIndex: quantity, status: z.enum(['0x0', '0x1']), type: z.literal('0x2'), gasUsed: quantity, effectiveGasPrice: quantity,
+    logs: z.array(rawLog).max(4096) });
+export function readReceipt(raw, tx, block) {
+    requireRead(raw !== null, 'RECEIPT_UNAVAILABLE');
+    const p = rawReceipt.safeParse(raw);
+    requireRead(p.success, 'RECEIPT_MISMATCH');
+    const r = p.data;
+    requireRead(r.status === '0x1', 'TRANSACTION_REVERTED');
+    requireRead(r.transactionHash === tx.hash && r.from === tx.from && r.to === tx.to && r.blockNumber === tx.blockNumber && r.blockHash === tx.blockHash && r.transactionIndex === tx.transactionIndex
+        && BigInt(r.blockNumber).toString() === block.number && r.blockHash === block.hash && block.transactions[number(r.transactionIndex)] === r.transactionHash
+        && BigInt(r.gasUsed) > 0n && BigInt(r.gasUsed) <= BigInt(tx.gas) && BigInt(r.effectiveGasPrice) <= BigInt(tx.maxFeePerGas), 'RECEIPT_MISMATCH');
+    const logs = r.logs.map((l, i) => {
+        requireRead(l.transactionHash === r.transactionHash && l.transactionIndex === r.transactionIndex && l.blockHash === r.blockHash && l.blockNumber === r.blockNumber
+            && (i === 0 || BigInt(l.logIndex) > BigInt(r.logs[i - 1].logIndex)), 'RECEIPT_MISMATCH');
+        return { address: l.address, topics: l.topics, data: l.data, logIndex: number(l.logIndex) };
+    });
+    return { chainId: 8453, transactionHash: tx.hash, blockHash: block.hash, blockNumber: block.number,
+        blockTimestamp: block.timestamp, transactionIndex: number(r.transactionIndex), canonical: true, status: 'success',
+        from: tx.from, to: tx.to, input: tx.input, value: BigInt(tx.value).toString(), logs };
+}
+//# sourceMappingURL=lp-v3-atomic-read-rpc.js.map

package/dist/vendor/lp-v3/lp-v3-atomic-read.d.ts

@@ -0,0 +1,17 @@
+import { type LpV3GuardDeployment } from './lp-v3-atomic-contract.js';
+import { type LpV3FinalityPolicy, type LpV3SettlementReadClient, type LpV3SettlementReadResult } from './lp-v3-atomic-read-contract.js';
+export interface LpV3SettlementReaderOptions {
+    client: LpV3SettlementReadClient;
+    finalityPolicy: LpV3FinalityPolicy;
+    guardDeployments?: readonly LpV3GuardDeployment[];
+    /** Trusted host clock only. An independent monotonic deadline also bounds reads. */
+    nowSeconds?: () => number;
+}
+/** No default finality policy, HTTP provider, signer, database or worker. Each
+ * invocation consumes a copied projection from an already validated host journal.
+ * This EOA reader cannot process bundler/UserOperation transactions or release claims.
+ */
+export declare function createLpV3AtomicSettlementReader(options: LpV3SettlementReaderOptions): Readonly<{
+    policyCommitment: `0x${string}`;
+    reconcile(raw: unknown): Promise<LpV3SettlementReadResult>;
+}>;

package/dist/vendor/lp-v3/lp-v3-atomic-read.js

@@ -0,0 +1,232 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson, commitment, deepFreeze } from './lp-v3-contract.js';
+import { createLpV3AtomicLibrary } from './lp-v3-atomic-index.js';
+import { reviewedGuardPolicy, lpV3AtomicChainEvidenceSchema } from './lp-v3-atomic-contract.js';
+import { lpV3FinalityPolicySchema, lpV3SettlementReadInputSchema } from './lp-v3-atomic-read-contract.js';
+import { LpV3ReadFailure, requireRead, readBlock, readSignedTransaction, readReceipt } from './lp-v3-atomic-read-rpc.js';
+const READ_METHODS = new Set(['eth_chainId', 'eth_getBlockByNumber', 'eth_getCode', 'eth_getStorageAt', 'eth_call', 'eth_getBalance', 'eth_getTransactionByHash', 'eth_getTransactionReceipt']);
+const NO_AUTHORITY = { executionAuthorized: false, claimReleased: false, retainClaim: true, retrySafe: false };
+const quantity = (value) => `0x${BigInt(value).toString(16)}`;
+const summary = (b) => ({ number: b.number, hash: b.hash, timestamp: b.timestamp });
+const sameBlock = (a, b) => canonicalJson(a) === canonicalJson(b);
+const stateOnly = (e) => { const { observedAt: _, ...state } = e; return state; };
+/** No default finality policy, HTTP provider, signer, database or worker. Each
+ * invocation consumes a copied projection from an already validated host journal.
+ * This EOA reader cannot process bundler/UserOperation transactions or release claims.
+ */
+export function createLpV3AtomicSettlementReader(options) {
+    let policy, guards;
+    try {
+        policy = deepFreeze(lpV3FinalityPolicySchema.parse(options.finalityPolicy));
+        guards = reviewedGuardPolicy(options.guardDeployments);
+        if (!options.client || typeof options.client.request !== 'function')
+            throw new Error('client');
+    }
+    catch {
+        throw new Error('LP_ATOMIC_READER_INVALID_CONFIGURATION');
+    }
+    const library = createLpV3AtomicLibrary(guards), policyCommitment = commitment(policy);
+    const requestRpc = options.client.request.bind(options.client), now = options.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
+    return Object.freeze({ policyCommitment,
+        async reconcile(raw) {
+            let input;
+            let stopped = false;
+            let stoppedFailure;
+            const startedMonotonic = performance.now();
+            let startedAt = 0;
+            let lastClock = 0;
+            const clock = () => {
+                const t = now();
+                requireRead(Number.isSafeInteger(t) && t > 0 && t >= lastClock, 'INVALID_CLOCK');
+                lastClock = t;
+                return t;
+            };
+            const checkTime = () => {
+                if (stopped)
+                    throw stoppedFailure ?? new LpV3ReadFailure('READ_STALE');
+                const t = clock();
+                requireRead(t >= startedAt && t - startedAt <= policy.maxReadDurationSeconds
+                    && performance.now() - startedMonotonic <= policy.maxReadDurationSeconds * 1000, 'READ_STALE');
+                return t;
+            };
+            const rpc = async (request) => {
+                checkTime();
+                requireRead(READ_METHODS.has(request.method), 'RPC_UNAVAILABLE');
+                let timer;
+                try {
+                    const remaining = Math.max(1, policy.maxReadDurationSeconds * 1000 - (performance.now() - startedMonotonic));
+                    const result = await Promise.race([
+                        requestRpc(request),
+                        new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new LpV3ReadFailure('READ_STALE')), remaining); }),
+                    ]);
+                    checkTime();
+                    return result;
+                }
+                catch (error) {
+                    stopped = true;
+                    stoppedFailure = error instanceof LpV3ReadFailure ? error : new LpV3ReadFailure('RPC_UNAVAILABLE');
+                    throw stoppedFailure;
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                }
+            };
+            const chain = async () => {
+                const value = await rpc({ method: 'eth_chainId' });
+                requireRead(typeof value === 'string' && /^0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)$/.test(value) && BigInt(value) === 8453n, 'WRONG_CHAIN');
+            };
+            const blocks = new Map();
+            const canonicalBlock = async (number) => {
+                const block = readBlock(await rpc({ method: 'eth_getBlockByNumber', params: [quantity(number), false] }), 'BLOCK_REORG');
+                requireRead(block.number === number, 'BLOCK_REORG');
+                const previous = blocks.get(number);
+                requireRead(!previous || sameBlock(previous, block), 'BLOCK_REORG');
+                const parent = BigInt(number) > 0n ? blocks.get((BigInt(number) - 1n).toString()) : undefined;
+                const child = blocks.get((BigInt(number) + 1n).toString());
+                requireRead((!parent || block.parentHash === parent.hash) && (!child || child.parentHash === block.hash), 'BLOCK_REORG');
+                blocks.set(number, block);
+                return block;
+            };
+            const heads = async () => {
+                const latest = readBlock(await rpc({ method: 'eth_getBlockByNumber', params: ['latest', false] }), 'FINALITY_UNAVAILABLE');
+                const finalized = readBlock(await rpc({ method: 'eth_getBlockByNumber', params: ['finalized', false] }), 'FINALITY_UNAVAILABLE');
+                const time = checkTime();
+                requireRead(latest.timestamp <= time && time - latest.timestamp <= policy.maxHeadAgeSeconds
+                    && finalized.timestamp <= latest.timestamp && latest.timestamp - finalized.timestamp <= policy.maxFinalizedLagSeconds
+                    && BigInt(finalized.number) <= BigInt(latest.number), 'FINALITY_STALE');
+                if (finalized.number === latest.number)
+                    requireRead(sameBlock(finalized, latest), 'BLOCK_REORG');
+                const prior = blocks.get(finalized.number);
+                requireRead(!prior || sameBlock(prior, finalized), 'BLOCK_REORG');
+                blocks.set(finalized.number, finalized);
+                return { latest, finalized };
+            };
+            try {
+                const parsed = lpV3SettlementReadInputSchema.safeParse(raw);
+                requireRead(parsed.success, 'INVALID_INPUT');
+                input = deepFreeze(parsed.data);
+                startedAt = clock();
+                const { plan, journal } = input, transactions = journal.transactions;
+                requireRead(journal.operationId === plan.intent.operationId && journal.planCommitment === plan.planCommitment
+                    && canonicalJson(journal.independentIntent) === canonicalJson(plan.intent) && journal.originalVerifiedAt <= startedAt
+                    && transactions.length === plan.calls.length, 'JOURNAL_MISMATCH');
+                const hashes = new Set(), requestIds = new Set();
+                for (const [i, tx] of transactions.entries()) {
+                    requireRead(tx.callIndex === i && tx.request.userId === journal.userId && tx.request.address.toLowerCase() === plan.intent.account
+                        && tx.requestDigest === createHash('sha256').update(JSON.stringify(tx.request)).digest('hex')
+                        && !hashes.has(tx.transactionHash) && !requestIds.has(tx.request.idempotencyKey)
+                        && (i === 0 || BigInt(tx.nonce) > BigInt(transactions[i - 1].nonce)), 'JOURNAL_MISMATCH');
+                    hashes.add(tx.transactionHash);
+                    requestIds.add(tx.request.idempotencyKey);
+                }
+                await chain();
+                // Seal the finalized boundary BEFORE collecting any transaction/receipt/state.
+                const initial = await heads(), sealed = initial.finalized;
+                requireRead(BigInt(journal.baseline.blockNumber) <= BigInt(sealed.number), 'NOT_FINALIZED');
+                const baselineBlock = await canonicalBlock(journal.baseline.blockNumber);
+                requireRead(baselineBlock.hash === journal.baseline.blockHash && baselineBlock.timestamp === journal.baseline.blockTimestamp, 'BASELINE_MISMATCH');
+                let context;
+                try {
+                    context = library.verifyForSettlement(plan, journal.independentIntent, journal.baseline, {
+                        operationId: journal.operationId, planCommitment: journal.planCommitment, canonical: true,
+                        blockNumber: baselineBlock.number, blockHash: baselineBlock.hash,
+                        originalVerifiedAt: journal.originalVerifiedAt, canonicalCheckedAt: checkTime(),
+                    }, { now: checkTime });
+                }
+                catch {
+                    throw new LpV3ReadFailure('SETTLEMENT_UNPROVEN');
+                }
+                /** Explicit historical adapter for the already reviewed hash-pinned reader.
+                 * Its internal validation clock is the selected block's timestamp, never
+                 * presented as a fresh observation. Every actual state read stays at this
+                 * exact hash; the public result receives the real completion timestamp.
+                */
+                const historical = async (anchor) => {
+                    let adapterFailure;
+                    try {
+                        const pinned = { blockHash: anchor.hash, requireCanonical: true };
+                        let initialAnchorRead = false;
+                        const result = await library.collectEvidence(journal.independentIntent, {
+                            nowSeconds: () => anchor.timestamp,
+                            client: { async request(request) {
+                                    try {
+                                        if (request.method === 'eth_getBlockByNumber') {
+                                            const tag = request.params?.[0];
+                                            requireRead((tag === 'latest' && !initialAnchorRead) || (tag === quantity(anchor.number) && initialAnchorRead), 'HISTORY_UNAVAILABLE');
+                                            initialAnchorRead = true;
+                                            const rawBlock = await rpc({ method: 'eth_getBlockByNumber', params: [quantity(anchor.number), false] });
+                                            requireRead(sameBlock(readBlock(rawBlock, 'HISTORY_UNAVAILABLE'), anchor), 'BLOCK_REORG');
+                                            return rawBlock;
+                                        }
+                                        if (request.method !== 'eth_chainId')
+                                            requireRead(initialAnchorRead && canonicalJson(request.params?.at(-1)) === canonicalJson(pinned), 'HISTORY_UNAVAILABLE');
+                                        return await rpc(request);
+                                    }
+                                    catch (error) {
+                                        if (error instanceof LpV3ReadFailure)
+                                            adapterFailure ??= error;
+                                        throw error;
+                                    }
+                                } },
+                        });
+                        return lpV3AtomicChainEvidenceSchema.parse({ ...result, observedAt: checkTime() });
+                    }
+                    catch {
+                        checkTime();
+                        throw adapterFailure ?? new LpV3ReadFailure('HISTORY_UNAVAILABLE');
+                    }
+                };
+                const baseline = await historical(baselineBlock);
+                requireRead(canonicalJson(stateOnly(baseline)) === canonicalJson(stateOnly(journal.baseline)), 'BASELINE_MISMATCH');
+                const receipts = [];
+                let minimumDepth;
+                for (const [i, expected] of transactions.entries()) {
+                    const tx = await readSignedTransaction(await rpc({ method: 'eth_getTransactionByHash', params: [expected.transactionHash] }), expected, plan.calls[i]);
+                    const txBlockNumber = BigInt(tx.blockNumber).toString();
+                    const block = await canonicalBlock(txBlockNumber);
+                    requireRead(block.hash === tx.blockHash && BigInt(block.number) > BigInt(baselineBlock.number), 'RECEIPT_MISMATCH');
+                    const depth = BigInt(sealed.number) - BigInt(block.number) + 1n;
+                    requireRead(depth >= BigInt(policy.minFinalizedConfirmations), 'NOT_FINALIZED');
+                    minimumDepth = minimumDepth === undefined || depth < minimumDepth ? depth : minimumDepth;
+                    const receipt = readReceipt(await rpc({ method: 'eth_getTransactionReceipt', params: [expected.transactionHash] }), tx, block);
+                    const previous = receipts.at(-1);
+                    requireRead(!previous || BigInt(receipt.blockNumber) > BigInt(previous.blockNumber)
+                        || (receipt.blockNumber === previous.blockNumber && receipt.transactionIndex > previous.transactionIndex
+                            && (!previous.logs.length || !receipt.logs.length || receipt.logs[0].logIndex > previous.logs.at(-1).logIndex)), 'RECEIPT_MISMATCH');
+                    receipts.push(receipt);
+                }
+                const postBlock = blocks.get(receipts.at(-1).blockNumber);
+                const post = await historical(postBlock);
+                // No cached assertion substitutes for a fresh canonical-number mapping.
+                for (const number of [...blocks.keys()])
+                    await canonicalBlock(number);
+                const final = await heads();
+                await chain();
+                requireRead(BigInt(final.latest.number) >= BigInt(initial.latest.number) && BigInt(final.finalized.number) >= BigInt(sealed.number), 'BLOCK_REORG');
+                const observedAt = checkTime();
+                post.observedAt = observedAt;
+                const evidence = { schemaVersion: 2, planCommitment: plan.planCommitment, receipts, post };
+                let result;
+                try {
+                    result = library.verifySettlement(context, evidence, { now: () => observedAt });
+                }
+                catch {
+                    throw new LpV3ReadFailure('SETTLEMENT_UNPROVEN');
+                }
+                return deepFreeze({ ...NO_AUTHORITY, status: 'SETTLEMENT_VERIFIED', operationId: journal.operationId, planCommitment: plan.planCommitment,
+                    journalCommitment: commitment(input), evidence, result,
+                    finality: { policyCommitment, observedAt, latest: summary(final.latest), finalized: summary(sealed), minimumObservedFinalizedConfirmations: minimumDepth.toString() } });
+            }
+            catch (error) {
+                return deepFreeze({ ...NO_AUTHORITY, status: 'HELD', settlement: 'UNKNOWN',
+                    reason: error instanceof LpV3ReadFailure ? error.reason : 'RPC_UNAVAILABLE',
+                    operationId: input?.journal.operationId ?? null, planCommitment: input?.plan.planCommitment ?? null });
+            }
+            finally {
+                stopped = true;
+            }
+        },
+    });
+}
+//# sourceMappingURL=lp-v3-atomic-read.js.map

package/dist/vendor/lp-v3/lp-v3-atomic-settlement.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { type LpV3GuardDeployment } from './lp-v3-atomic-contract.js';
+import { type LpV3AtomicSettlementContext } from './lp-v3-atomic-plan.js';
+import type { LpV3VerifyOptions } from './lp-v3-plan.js';
+export declare const lpV3AtomicSettlementEvidenceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    planCommitment: z.ZodString;
+    receipts: z.ZodArray<z.ZodObject<{
+        chainId: z.ZodLiteral<8453>;
+        transactionHash: z.ZodString;
+        blockHash: z.ZodString;
+        blockNumber: z.ZodString;
+        blockTimestamp: z.ZodNumber;
+        transactionIndex: z.ZodNumber;
+        canonical: z.ZodLiteral<true>;
+        status: z.ZodLiteral<"success">;
+        from: z.ZodString;
+        to: z.ZodString;
+        input: z.ZodString;
+        value: z.ZodLiteral<"0">;
+        logs: z.ZodArray<z.ZodObject<{
+            address: z.ZodString;
+            topics: z.ZodArray<z.ZodString>;
+            data: z.ZodString;
+            logIndex: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    post: z.ZodObject<{
+        chainId: z.ZodLiteral<8453>;
+        blockNumber: z.ZodString;
+        blockHash: z.ZodString;
+        blockTimestamp: z.ZodNumber;
+        observedAt: z.ZodNumber;
+        canonical: z.ZodLiteral<true>;
+        account: z.ZodString;
+        accountCode: z.ZodLiteral<"0x">;
+        balances: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        allowances: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        manager: z.ZodLiteral<"0x03a520b32c04bf3beef7beb72e919cf822ed34f1">;
+        managerFactory: z.ZodLiteral<"0x33128a8fc17869897dce68ed026d694621f6fdfd">;
+        factory: z.ZodLiteral<"0x33128a8fc17869897dce68ed026d694621f6fdfd">;
+        factoryPool: z.ZodString;
+        factoryCodeHash: z.ZodLiteral<`0x${string}`>;
+        managerCodeHash: z.ZodLiteral<`0x${string}`>;
+        token0CodeHash: z.ZodLiteral<`0x${string}`>;
+        token1CodeHash: z.ZodLiteral<`0x${string}`>;
+        usdcImplementation: z.ZodLiteral<"0x2ce6311ddae708829bc0784c967b7d77d19fd779">;
+        usdcImplementationCodeHash: z.ZodLiteral<`0x${string}`>;
+        usdcPaused: z.ZodLiteral<false>;
+        accountBlacklisted: z.ZodLiteral<false>;
+        managerBlacklisted: z.ZodLiteral<false>;
+        pool: z.ZodString;
+        poolFactory: z.ZodLiteral<"0x33128a8fc17869897dce68ed026d694621f6fdfd">;
+        token0: z.ZodLiteral<"0x4200000000000000000000000000000000000006">;
+        token1: z.ZodLiteral<"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913">;
+        fee: z.ZodNumber;
+        tickSpacing: z.ZodNumber;
+        tick: z.ZodNumber;
+        sqrtPriceX96: z.ZodString;
+        unlocked: z.ZodLiteral<true>;
+        schemaVersion: z.ZodLiteral<2>;
+        position: z.ZodObject<{
+            tokenId: z.ZodString;
+            owner: z.ZodString;
+            token0: z.ZodString;
+            token1: z.ZodString;
+            fee: z.ZodNumber;
+            tickLower: z.ZodNumber;
+            tickUpper: z.ZodNumber;
+            liquidity: z.ZodString;
+            tokensOwed: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+            approved: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0x0000000000000000000000000000000000000000">]>;
+        }, z.core.$strict>;
+        managerNativeBalance: z.ZodString;
+        guard: z.ZodNullable<z.ZodObject<{
+            address: z.ZodString;
+            runtimeCodeHash: z.ZodString;
+            configurationHash: z.ZodString;
+            deploymentChainId: z.ZodLiteral<8453>;
+            ownerApprovalForAll: z.ZodLiteral<false>;
+            guardBlacklisted: z.ZodLiteral<false>;
+            poolBlacklisted: z.ZodLiteral<false>;
+            tokenAllowances: z.ZodTuple<[z.ZodLiteral<"0">, z.ZodLiteral<"0">], null>;
+            tokenBalances: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type LpV3AtomicSettlementEvidence = z.infer<typeof lpV3AtomicSettlementEvidenceSchema>;
+export interface LpV3AtomicSettlementResult {
+    status: 'SETTLED';
+    action: 'increase' | 'collect';
+    planCommitment: string;
+    tokenId: string;
+    depositedRaw: [string, string];
+    collectedRaw: [string, string];
+    liquidityDelta: string;
+    erc20AllowancesCleared: true;
+    nftTokenApprovalCleared: true;
+    profitClassification: 'UNKNOWN';
+    distributableProfitRaw: null;
+}
+/** The protected host supplies independently collected, journal-bound transactions
+ * and canonical logs/post-state. No client assertion is a receipt or finality proof.
+ */
+export declare function verifyLpV3AtomicSettlement(context: LpV3AtomicSettlementContext, input: unknown, policy: readonly LpV3GuardDeployment[], options?: LpV3VerifyOptions): LpV3AtomicSettlementResult;