otto-intel-mcp 0.1.2 → 0.1.4

package/dist/native-yield-definition.js

@@ -0,0 +1,105 @@
+/** Native yield contracts; separate from the existing LI.FI delegation envelope. */
+import { z } from 'zod';
+import { parseAbi } from 'viem';
+import { DEFAULT_LIFI_FEE_BPS, DEFAULT_OTTO_LIFI_FEE_RECIPIENT } from './execution-config.js';
+export const NATIVE_YIELD_FEE_BPS = DEFAULT_LIFI_FEE_BPS;
+export const NATIVE_YIELD_FEE_RECIPIENT = DEFAULT_OTTO_LIFI_FEE_RECIPIENT;
+export const NATIVE_YIELD_FEE_VERSION = 'native-yield-10bps-floor-v1';
+export const NATIVE_YIELD_TTL_SECONDS = 180;
+export const NATIVE_YIELD_STATE_MAX_AGE_MS = 60_000;
+export const NATIVE_YIELD_ROUTER_ABI = parseAbi([
+    'function execute(bytes32 marketId, bool isDeposit, uint256 amount, uint256 minOutput, uint256 nonce, uint256 deadline) returns (uint256 outputAmount)',
+    'function nonces(address owner) view returns (uint256)',
+    'function marketConfig(bytes32 marketId) view returns (uint8 protocol, address asset, address position, address target, bool depositEnabled)',
+    'event YieldExecuted(address indexed owner, bytes32 indexed marketId, uint256 indexed nonce, bool isDeposit, uint256 inputAmount, uint256 outputAmount, uint256 feeAmount)',
+]);
+export const NATIVE_YIELD_ERC20_ABI = parseAbi([
+    'function approve(address spender, uint256 amount) returns (bool)',
+    'function allowance(address owner, address spender) view returns (uint256)',
+    'function balanceOf(address owner) view returns (uint256)',
+    'function decimals() view returns (uint8)',
+    'function totalSupply() view returns (uint256)',
+    'event Transfer(address indexed from, address indexed to, uint256 value)',
+]);
+const address = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
+const uint = z.string().regex(/^(0|[1-9]\d*)$/)
+    .refine((v) => BigInt(v) < 1n << 256n, 'must fit uint256');
+const positive = uint.refine((v) => BigInt(v) > 0n, 'must be positive');
+const hash = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+const commitment = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+export const PREPARE_NATIVE_YIELD_INPUT_SCHEMA = z.object({
+    accountProfile: z.object({
+        kind: z.literal('eoa'), address, chainId: z.union([z.literal(8453), z.literal(42161)]),
+    }).strict(),
+    marketId: z.string().min(1).max(120),
+    registryCommitment: commitment,
+    action: z.enum(['deposit', 'withdraw']),
+    /** Deposit underlying units; withdraw exact nominal receipt-token units. */
+    amount: positive,
+    slippage: z.object({ maxBps: z.number().int().min(1).max(100), minOutput: positive.optional() }).strict(),
+    clientRef: z.string().trim().min(1).max(128).optional(),
+}).strict();
+export const NATIVE_YIELD_DEPLOYMENT_SCHEMA = z.object({
+    chainId: z.union([z.literal(8453), z.literal(42161)]),
+    address,
+    runtimeCodeHash: hash,
+    version: z.literal('native-yield-router-v1'),
+    reviewId: z.string().min(1).max(160),
+}).strict();
+/**
+ * Deliberately empty. No address/environment variable can activate a new spend
+ * target. Fill only in a separately approved exact-deployment review.
+ */
+export const NATIVE_YIELD_DEPLOYMENTS = Object.freeze([]);
+const step = z.object({
+    kind: z.enum(['approve_reset', 'approve', 'call']),
+    to: address, value: z.literal('0'), data: z.string().regex(/^0x(?:[0-9a-fA-F]{2}){4,}$/),
+}).strict();
+export const NATIVE_YIELD_PLAN_SCHEMA = z.object({
+    schemaVersion: z.literal('1'),
+    kind: z.literal('native-yield-plan'),
+    transport: z.literal('native-protocol'),
+    marketId: z.string(),
+    registryCommitment: commitment,
+    owner: address,
+    chainId: z.union([z.literal(8453), z.literal(42161)]),
+    action: z.enum(['deposit', 'withdraw']),
+    amount: positive,
+    inputToken: address,
+    outputToken: address,
+    expectedOutput: positive,
+    minimumOutput: positive,
+    protocolOutput: positive,
+    fee: z.object({
+        bps: z.literal(10), recipient: address, token: address,
+        amount: uint, version: z.literal(NATIVE_YIELD_FEE_VERSION), rounding: z.literal('floor'),
+    }).strict(),
+    nonce: uint,
+    deadline: z.number().int().positive().safe(),
+    preparedAtMs: z.number().int().positive().safe(),
+    snapshot: z.object({ blockNumber: uint, blockHash: hash, observedAtMs: z.number().int().positive().safe() }).strict(),
+    deployment: NATIVE_YIELD_DEPLOYMENT_SCHEMA,
+    steps: z.array(step).length(3),
+    /** An unsigned plan does not authorize a wallet or confer a CDP delegation. */
+    authorization: z.literal('requires-separate-account-authority'),
+    allowanceRecovery: z.literal('approval-is-separate-and-may-remain-after-failure'),
+    intentCommitment: commitment,
+    planCommitment: commitment,
+}).strict();
+export function nativeYieldFee(gross) {
+    if (gross < 0n || gross >= 1n << 256n)
+        throw new Error('Invalid fee basis');
+    return gross / 1000n; // Fixed 10 bp, floor, overflow-free. Dust rounding is explicit.
+}
+export class NativeYieldRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'NativeYieldRefusal';
+    }
+}
+export function refuseNative(code, message) {
+    throw new NativeYieldRefusal(code, message);
+}
+//# sourceMappingURL=native-yield-definition.js.map

package/dist/native-yield-reader.d.ts

@@ -0,0 +1,4 @@
+/** Fixed-block, owner-bound native preflight. Uses only the configured client's pinned market addresses. */
+import { type PublicClient } from 'viem';
+import { type NativeYieldReader } from './native-yield-definition.js';
+export declare function viemNativeYieldReader(clients: Readonly<Partial<Record<number, PublicClient>>>, nowMs?: () => number): NativeYieldReader;

package/dist/native-yield-reader.js

@@ -0,0 +1,137 @@
+/** Fixed-block, owner-bound native preflight. Uses only the configured client's pinned market addresses. */
+import { getAddress, keccak256, parseAbi, stringToHex } from 'viem';
+import { NATIVE_YIELD_ERC20_ABI, NATIVE_YIELD_ROUTER_ABI, NATIVE_YIELD_STATE_MAX_AGE_MS, nativeYieldFee, refuseNative, } from './native-yield-definition.js';
+const VAULT_ABI = parseAbi([
+    'function asset() view returns (address)',
+    'function maxDeposit(address receiver) view returns (uint256)',
+    'function maxRedeem(address owner) view returns (uint256)',
+    'function previewDeposit(uint256 assets) view returns (uint256)',
+    'function previewRedeem(uint256 shares) view returns (uint256)',
+]);
+const ATOKEN_ABI = parseAbi([
+    'function POOL() view returns (address)',
+    'function UNDERLYING_ASSET_ADDRESS() view returns (address)',
+    'function scaledTotalSupply() view returns (uint256)',
+]);
+const AAVE_ABI = parseAbi([
+    'function getConfiguration(address asset) view returns ((uint256 data))',
+    'function getVirtualUnderlyingBalance(address asset) view returns (uint128)',
+    'function getReserveNormalizedIncome(address asset) view returns (uint256)',
+    'function getReserveData(address asset) view returns (((uint256 data) configuration, uint128 liquidityIndex, uint128 currentLiquidityRate, uint128 variableBorrowIndex, uint128 currentVariableBorrowRate, uint128 currentStableBorrowRate, uint40 lastUpdateTimestamp, uint16 id, address aTokenAddress, address stableDebtTokenAddress, address variableDebtTokenAddress, address interestRateStrategyAddress, uint128 accruedToTreasury, uint128 unbacked, uint128 isolationModeTotalDebt))',
+]);
+const min = (a, b) => a < b ? a : b;
+const RAY = 10n ** 27n;
+export function viemNativeYieldReader(clients, nowMs = Date.now) {
+    return {
+        async read(market, owner, action, amount, deployment) {
+            const pub = clients[market.chainId];
+            if (!pub)
+                return refuseNative('NATIVE_CHAIN_UNAVAILABLE', 'No reviewed public reader for this chain');
+            if (await pub.getChainId() !== market.chainId) {
+                return refuseNative('NATIVE_CHAIN_MISMATCH', 'Configured RPC reports a different chain');
+            }
+            const block = await pub.getBlock({ blockTag: 'latest' });
+            if (block.number === null || !block.hash)
+                return refuseNative('NATIVE_STATE_UNAVAILABLE', 'Missing block anchor');
+            const observedAtMs = nowMs();
+            const blockTimestampMs = Number(block.timestamp) * 1000;
+            if (blockTimestampMs > observedAtMs + 5000 || observedAtMs - blockTimestampMs > NATIVE_YIELD_STATE_MAX_AGE_MS) {
+                return refuseNative('NATIVE_STATE_STALE', 'Protocol state is not current');
+            }
+            const blockNumber = block.number;
+            const read = async (address, abi, functionName, args = []) => await pub.readContract({ address, abi, functionName, args, blockNumber });
+            const router = getAddress(deployment.address);
+            const code = await pub.getCode({ address: router, blockNumber });
+            if (!code || keccak256(code).toLowerCase() !== deployment.runtimeCodeHash.toLowerCase()) {
+                return refuseNative('NATIVE_DEPLOYMENT_MISMATCH', 'Executor bytecode differs from the reviewed deployment');
+            }
+            const config = await read(router, NATIVE_YIELD_ROUTER_ABI, 'marketConfig', [keccak256(stringToHex(market.id))]);
+            if (config[0] !== (market.protocol === 'MORPHO' ? 1 : 2) ||
+                getAddress(config[1]) !== market.asset.address || getAddress(config[2]) !== market.position.tokenAddress ||
+                getAddress(config[3]) !== market.protocolTarget ||
+                config[4] !== (market.capabilities.native.deposit !== 'unavailable')) {
+                return refuseNative('NATIVE_MARKET_DRIFT', 'Executor market binding differs from the registry');
+            }
+            const inputToken = action === 'deposit' ? market.asset.address : market.position.tokenAddress;
+            const [assetDecimals, positionDecimals, assetBalance, positionBalance, inputAllowance, nativeBalance, routerNonce] = await Promise.all([
+                read(market.asset.address, NATIVE_YIELD_ERC20_ABI, 'decimals'),
+                read(market.position.tokenAddress, NATIVE_YIELD_ERC20_ABI, 'decimals'),
+                read(market.asset.address, NATIVE_YIELD_ERC20_ABI, 'balanceOf', [owner]),
+                read(market.position.tokenAddress, NATIVE_YIELD_ERC20_ABI, 'balanceOf', [owner]),
+                read(inputToken, NATIVE_YIELD_ERC20_ABI, 'allowance', [owner, router]),
+                pub.getBalance({ address: owner, blockNumber }),
+                read(router, NATIVE_YIELD_ROUTER_ABI, 'nonces', [owner]),
+            ]);
+            if (assetDecimals !== market.asset.decimals || positionDecimals !== market.position.decimals) {
+                return refuseNative('NATIVE_TOKEN_DRIFT', 'Underlying or receipt-token decimals differ from the registry');
+            }
+            const inputBalance = action === 'deposit' ? assetBalance : positionBalance;
+            let maxInput;
+            let protocolOutput;
+            if (market.protocol === 'MORPHO') {
+                const asset = await read(market.protocolTarget, VAULT_ABI, 'asset');
+                if (getAddress(asset) !== market.asset.address)
+                    return refuseNative('NATIVE_TOKEN_DRIFT', 'Vault underlying changed');
+                if (action === 'deposit') {
+                    const net = amount - nativeYieldFee(amount);
+                    const maxAssets = await read(market.protocolTarget, VAULT_ABI, 'maxDeposit', [owner]);
+                    // Compare NET supply to capacity, but keep the owner's gross spend within balance.
+                    maxInput = inputBalance;
+                    if (net > maxAssets)
+                        return refuseNative('NATIVE_CAPACITY', 'Requested net supply exceeds vault maxDeposit');
+                    protocolOutput = await read(market.protocolTarget, VAULT_ABI, 'previewDeposit', [net]);
+                }
+                else {
+                    maxInput = min(inputBalance, await read(market.protocolTarget, VAULT_ABI, 'maxRedeem', [owner]));
+                    protocolOutput = await read(market.protocolTarget, VAULT_ABI, 'previewRedeem', [amount]);
+                }
+            }
+            else {
+                const [pool, underlying, reserve, normalizedIncome, scaledSupply] = await Promise.all([
+                    read(market.position.tokenAddress, ATOKEN_ABI, 'POOL'),
+                    read(market.position.tokenAddress, ATOKEN_ABI, 'UNDERLYING_ASSET_ADDRESS'),
+                    read(market.protocolTarget, AAVE_ABI, 'getReserveData', [market.asset.address]),
+                    read(market.protocolTarget, AAVE_ABI, 'getReserveNormalizedIncome', [market.asset.address]),
+                    read(market.position.tokenAddress, ATOKEN_ABI, 'scaledTotalSupply'),
+                ]);
+                if (getAddress(pool) !== market.protocolTarget || getAddress(underlying) !== market.asset.address ||
+                    getAddress(reserve.aTokenAddress) !== market.position.tokenAddress) {
+                    return refuseNative('NATIVE_TOKEN_DRIFT', 'Aave reserve, Pool and aToken binding disagree');
+                }
+                const flags = reserve.configuration.data;
+                const active = (flags & (1n << 56n)) !== 0n;
+                const frozen = (flags & (1n << 57n)) !== 0n;
+                const paused = (flags & (1n << 60n)) !== 0n;
+                if (!active || paused || (action === 'deposit' && frozen)) {
+                    return refuseNative('NATIVE_RESERVE_UNAVAILABLE', 'Aave reserve is inactive, paused or frozen for supply');
+                }
+                if (action === 'deposit') {
+                    const net = amount - nativeYieldFee(amount);
+                    const cap = ((flags >> 116n) & ((1n << 36n) - 1n)) * 10n ** BigInt(market.asset.decimals);
+                    // Round up conservatively and include treasury accrual, as Aave's cap validation does.
+                    const accountedSupply = ((scaledSupply + reserve.accruedToTreasury) * normalizedIncome + RAY - 1n) / RAY;
+                    if (cap !== 0n && accountedSupply + net > cap) {
+                        return refuseNative('NATIVE_CAPACITY', 'Requested net supply exceeds Aave reserve supply capacity');
+                    }
+                    maxInput = inputBalance;
+                    // aToken normalized balances can round by one atomic unit.
+                    protocolOutput = net > 1n ? net - 1n : net;
+                }
+                else {
+                    const liquidity = await read(market.protocolTarget, AAVE_ABI, 'getVirtualUnderlyingBalance', [market.asset.address]);
+                    maxInput = min(inputBalance, liquidity);
+                    protocolOutput = amount;
+                }
+            }
+            const anchor = await pub.getBlock({ blockNumber });
+            if (anchor.hash !== block.hash)
+                return refuseNative('NATIVE_STATE_REORG', 'Preflight block changed during reads');
+            return {
+                chainId: market.chainId, marketId: market.id, owner, blockNumber,
+                blockHash: block.hash, blockTimestampMs, observedAtMs, routerNonce, inputBalance,
+                inputAllowance, positionBalance, assetBalance, nativeBalance, maxInput, protocolOutput,
+            };
+        },
+    };
+}
+//# sourceMappingURL=native-yield-reader.js.map

package/dist/native-yield-settlement.d.ts

@@ -0,0 +1,48 @@
+/** Receipt reconciliation only. This module never broadcasts, retries or changes an allowance. */
+import { type Address, type Hex, type PublicClient, type TransactionReceipt } from 'viem';
+import { type NativeYieldDeployment, type NativeYieldPlan } from './native-yield-definition.js';
+export type NativeYieldSettlement = {
+    readonly status: 'unknown' | 'pending' | 'needs-attention';
+    readonly reason: string;
+    readonly transactionHash: Hex;
+    readonly retrySafe: false;
+} | {
+    readonly status: 'reverted';
+    readonly transactionHash: Hex;
+    readonly remainingAllowance: string;
+    readonly retrySafe: false;
+} | {
+    readonly status: 'completed';
+    readonly transactionHash: Hex;
+    readonly blockNumber: string;
+    readonly owner: Address;
+    readonly marketId: string;
+    readonly action: 'deposit' | 'withdraw';
+    readonly actualInput: string;
+    readonly actualOutput: string;
+    readonly actualOttoFee: string;
+    readonly feeToken: Address;
+    readonly inputAllowance: '0';
+    readonly protocolAllowance: '0';
+    readonly positionBalanceAtBlock: string;
+    readonly assetBalanceAtBlock: string;
+    readonly protocolActionVerified: true;
+    readonly gasUsed: string;
+    readonly receiptGasCostWei: string;
+    readonly excludesApprovalTransactionCosts: true;
+    readonly retrySafe: false;
+};
+/**
+ * Match isolated transaction events, never a quote estimate or a whole-block
+ * balance difference (which can include unrelated transfers and aToken interest).
+ */
+export declare function nativeYieldReceiptAmounts(plan: NativeYieldPlan, receipt: TransactionReceipt): {
+    owner: Address;
+    marketId: Hex;
+    nonce: bigint;
+    isDeposit: boolean;
+    inputAmount: bigint;
+    outputAmount: bigint;
+    feeAmount: bigint;
+};
+export declare function readNativeYieldSettlement(pub: PublicClient, rawPlan: NativeYieldPlan, transactionHash: Hex, deployments?: readonly NativeYieldDeployment[]): Promise<NativeYieldSettlement>;

package/dist/native-yield-settlement.js

@@ -0,0 +1,167 @@
+/** Receipt reconciliation only. This module never broadcasts, retries or changes an allowance. */
+import { decodeEventLog, getAddress, keccak256, parseAbi, stringToHex, } from 'viem';
+import { freezeHybridValue, getHybridYieldMarket, hybridYieldCommitment } from './hybrid-yield-markets.js';
+import { NATIVE_YIELD_DEPLOYMENTS, NATIVE_YIELD_ERC20_ABI, NATIVE_YIELD_FEE_RECIPIENT, NATIVE_YIELD_PLAN_SCHEMA, NATIVE_YIELD_ROUTER_ABI, nativeYieldFee, } from './native-yield-definition.js';
+const PROTOCOL_EVENTS = parseAbi([
+    'event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares)',
+    'event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares)',
+    'event Supply(address indexed reserve, address user, address indexed onBehalfOf, uint256 amount, uint16 indexed referralCode)',
+]);
+const AAVE_WITHDRAW = parseAbi([
+    'event Withdraw(address indexed reserve, address indexed user, address indexed to, uint256 amount)',
+]);
+function events(receipt, address, abi) {
+    return receipt.logs.filter((l) => l.address.toLowerCase() === address.toLowerCase()).flatMap((log) => {
+        try {
+            return [decodeEventLog({ abi, data: log.data, topics: log.topics, strict: true })];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function same(a, b) { return typeof a === 'string' && a.toLowerCase() === b.toLowerCase(); }
+/**
+ * Match isolated transaction events, never a quote estimate or a whole-block
+ * balance difference (which can include unrelated transfers and aToken interest).
+ */
+export function nativeYieldReceiptAmounts(plan, receipt) {
+    const market = getHybridYieldMarket(plan.marketId);
+    if (!market || hybridYieldCommitment(market) !== plan.registryCommitment)
+        throw new Error('Market commitment mismatch');
+    const router = plan.deployment.address;
+    const matches = events(receipt, router, NATIVE_YIELD_ROUTER_ABI).filter((e) => e.eventName === 'YieldExecuted');
+    if (matches.length !== 1)
+        throw new Error('Expected exactly one native execution event');
+    const event = matches[0].args;
+    if (!same(event.owner, plan.owner) || event.marketId !== keccak256(stringToHex(market.id)) ||
+        event.nonce !== BigInt(plan.nonce) || event.isDeposit !== (plan.action === 'deposit') ||
+        event.inputAmount !== BigInt(plan.amount) || event.outputAmount < BigInt(plan.minimumOutput)) {
+        throw new Error('Native receipt differs from the reviewed owner/action/amount/minimum/nonce');
+    }
+    const grossAssets = event.isDeposit ? event.inputAmount : event.outputAmount + event.feeAmount;
+    if (event.feeAmount !== nativeYieldFee(grossAssets))
+        throw new Error('Native fee amount mismatch');
+    const transfers = events(receipt, market.asset.address, NATIVE_YIELD_ERC20_ABI)
+        .filter((e) => e.eventName === 'Transfer')
+        .map((e) => e.args);
+    const sentTo = (recipient) => transfers
+        .filter((e) => same(e.from, router) && same(e.to, recipient)).map((e) => e.value);
+    const equals = (actual, expected) => actual.length === expected.length && actual.every((v, i) => v === expected[i]);
+    const feeLegs = event.feeAmount > 0n ? [event.feeAmount] : [];
+    if (!event.isDeposit && same(plan.owner, NATIVE_YIELD_FEE_RECIPIENT)) {
+        // The two transfers have identical endpoints; bind their exact ordered values
+        // instead of incorrectly counting the gross sum as both fee and net proceeds.
+        if (!equals(sentTo(plan.owner), [...feeLegs, event.outputAmount])) {
+            throw new Error('Exact fee and net exit transfers to the owning fee account are missing');
+        }
+    }
+    else {
+        if (!equals(sentTo(NATIVE_YIELD_FEE_RECIPIENT), feeLegs)) {
+            throw new Error('Actual Otto fee transfer is missing or differs');
+        }
+        if (!event.isDeposit && !equals(sentTo(plan.owner), [event.outputAmount])) {
+            throw new Error('Exact net exit proceeds were not transferred to the owner');
+        }
+    }
+    if (market.protocol === 'MORPHO') {
+        const protocol = events(receipt, market.protocolTarget, PROTOCOL_EVENTS).filter((e) => e.eventName === (event.isDeposit ? 'Deposit' : 'Withdraw'));
+        const matched = protocol.filter((e) => {
+            const a = e.args;
+            return same(a.sender, router) && same(a.owner, event.isDeposit ? plan.owner : router) &&
+                (event.isDeposit || same(a.receiver, router)) &&
+                a.assets === (event.isDeposit ? event.inputAmount - event.feeAmount : grossAssets) &&
+                a.shares === (event.isDeposit ? event.outputAmount : event.inputAmount);
+        });
+        if (matched.length !== 1)
+            throw new Error('Exact Morpho deposit/redeem event is missing');
+    }
+    else {
+        const protocol = events(receipt, market.protocolTarget, event.isDeposit ? PROTOCOL_EVENTS : AAVE_WITHDRAW)
+            .filter((e) => e.eventName === (event.isDeposit ? 'Supply' : 'Withdraw'));
+        const matched = protocol.filter((e) => {
+            const a = e.args;
+            return same(a.reserve, market.asset.address) && same(a.user, router) &&
+                (event.isDeposit ? same(a.onBehalfOf, plan.owner) : same(a.to, router)) &&
+                a.amount === (event.isDeposit ? event.inputAmount - event.feeAmount : grossAssets);
+        });
+        if (matched.length !== 1)
+            throw new Error('Exact Aave supply/withdraw event is missing');
+    }
+    return event;
+}
+export async function readNativeYieldSettlement(pub, rawPlan, transactionHash, deployments = NATIVE_YIELD_DEPLOYMENTS) {
+    const pending = (status, reason) => ({ status, reason, transactionHash, retrySafe: false });
+    try {
+        const plan = NATIVE_YIELD_PLAN_SCHEMA.parse(rawPlan);
+        const { planCommitment, ...core } = plan;
+        if (hybridYieldCommitment(core) !== planCommitment)
+            return pending('needs-attention', 'Plan commitment mismatch');
+        const deployment = deployments.find((d) => d.chainId === plan.chainId);
+        if (!deployment || hybridYieldCommitment(deployment) !== hybridYieldCommitment(plan.deployment)) {
+            return pending('needs-attention', 'Executor deployment is not approved');
+        }
+        if (await pub.getChainId() !== plan.chainId)
+            return pending('needs-attention', 'Receipt reader is on another chain');
+        const [tx, receipt] = await Promise.all([
+            pub.getTransaction({ hash: transactionHash }), pub.getTransactionReceipt({ hash: transactionHash }),
+        ]);
+        if (!same(tx.from, plan.owner) || !same(tx.to, deployment.address) || tx.value !== 0n ||
+            tx.input.toLowerCase() !== plan.steps[2].data.toLowerCase() ||
+            receipt.transactionHash.toLowerCase() !== transactionHash.toLowerCase()) {
+            return pending('needs-attention', 'Known transaction differs from the reviewed action');
+        }
+        const [canonical, finalized, code] = await Promise.all([
+            pub.getBlock({ blockNumber: receipt.blockNumber }), pub.getBlock({ blockTag: 'finalized' }),
+            pub.getCode({ address: getAddress(deployment.address), blockNumber: receipt.blockNumber }),
+        ]);
+        if (canonical.hash !== receipt.blockHash || !code ||
+            keccak256(code).toLowerCase() !== deployment.runtimeCodeHash.toLowerCase()) {
+            return pending('needs-attention', 'Receipt block or executor bytecode is not canonical');
+        }
+        if (finalized.number === null || finalized.number < receipt.blockNumber) {
+            return pending('pending', 'Known receipt is awaiting canonical finality');
+        }
+        const allowance = await pub.readContract({
+            address: getAddress(plan.inputToken), abi: NATIVE_YIELD_ERC20_ABI, functionName: 'allowance',
+            args: [getAddress(plan.owner), getAddress(deployment.address)], blockNumber: receipt.blockNumber,
+        });
+        if (receipt.status === 'reverted')
+            return { status: 'reverted', transactionHash, remainingAllowance: allowance.toString(), retrySafe: false };
+        const market = getHybridYieldMarket(plan.marketId);
+        if (!market)
+            return pending('needs-attention', 'Unknown position');
+        const amounts = nativeYieldReceiptAmounts(plan, receipt);
+        const [protocolAllowance, positionBalance, assetBalance, nonce] = await Promise.all([
+            pub.readContract({ address: market.asset.address, abi: NATIVE_YIELD_ERC20_ABI, functionName: 'allowance',
+                args: [getAddress(deployment.address), market.protocolTarget], blockNumber: receipt.blockNumber }),
+            pub.readContract({ address: market.position.tokenAddress, abi: NATIVE_YIELD_ERC20_ABI, functionName: 'balanceOf',
+                args: [getAddress(plan.owner)], blockNumber: receipt.blockNumber }),
+            pub.readContract({ address: market.asset.address, abi: NATIVE_YIELD_ERC20_ABI, functionName: 'balanceOf',
+                args: [getAddress(plan.owner)], blockNumber: receipt.blockNumber }),
+            pub.readContract({ address: getAddress(deployment.address), abi: NATIVE_YIELD_ROUTER_ABI, functionName: 'nonces',
+                args: [getAddress(plan.owner)], blockNumber: receipt.blockNumber }),
+        ]);
+        if (allowance !== 0n || protocolAllowance !== 0n || nonce < BigInt(plan.nonce) + 1n) {
+            return pending('needs-attention', 'Execution observed, but allowance or nonce recovery is unresolved');
+        }
+        const recheck = await pub.getBlock({ blockNumber: receipt.blockNumber });
+        if (recheck.hash !== receipt.blockHash)
+            return pending('pending', 'Receipt changed while reconciling');
+        return freezeHybridValue({
+            status: 'completed', transactionHash, blockNumber: receipt.blockNumber.toString(),
+            owner: getAddress(plan.owner), marketId: market.id, action: plan.action,
+            actualInput: amounts.inputAmount.toString(), actualOutput: amounts.outputAmount.toString(),
+            actualOttoFee: amounts.feeAmount.toString(), feeToken: market.asset.address,
+            inputAllowance: '0', protocolAllowance: '0', positionBalanceAtBlock: positionBalance.toString(),
+            assetBalanceAtBlock: assetBalance.toString(), protocolActionVerified: true,
+            gasUsed: receipt.gasUsed.toString(), receiptGasCostWei: (receipt.gasUsed * receipt.effectiveGasPrice).toString(),
+            excludesApprovalTransactionCosts: true,
+            retrySafe: false,
+        });
+    }
+    catch {
+        return pending('unknown', 'Transaction or position evidence is unavailable; reconcile this hash before any new spend');
+    }
+}
+//# sourceMappingURL=native-yield-settlement.js.map

package/dist/native-yield-simulation.d.ts

@@ -0,0 +1,18 @@
+/** Simulation after exact approval, with no state overrides and no signer. */
+import { type PublicClient } from 'viem';
+import type { NativeYieldRuntime } from './native-yield.js';
+import { type NativeYieldVerificationContext } from './native-yield-verify.js';
+/**
+ * Run after approval is mined, immediately before the signing boundary. A passing
+ * simulation is a snapshot, not wallet authority or a guarantee of later execution.
+ * RPC gas estimates follow each chain's fee semantics; additional chain charges
+ * may apply. Already-mined approval transactions are separately accounted.
+ */
+export declare function simulateNativeYieldPlan(pub: PublicClient, runtime: NativeYieldRuntime, rawPlan: unknown, rawInput: unknown, context: NativeYieldVerificationContext): Promise<{
+    verified: import("./native-yield-verify.js").VerifiedNativeYieldPlan;
+    simulatedOutput: string;
+    estimatedGasLimit: string;
+    rpcGasEstimateWei: string;
+    excludesApprovalTransactionCosts: true;
+    simulationOnly: true;
+}>;

package/dist/native-yield-simulation.js

@@ -0,0 +1,45 @@
+/** Simulation after exact approval, with no state overrides and no signer. */
+import { decodeAbiParameters, getAddress, parseAbiParameters } from 'viem';
+import { freezeHybridValue } from './hybrid-yield-markets.js';
+import { NATIVE_YIELD_ERC20_ABI, refuseNative } from './native-yield-definition.js';
+import { verifyNativeYieldPlan } from './native-yield-verify.js';
+/**
+ * Run after approval is mined, immediately before the signing boundary. A passing
+ * simulation is a snapshot, not wallet authority or a guarantee of later execution.
+ * RPC gas estimates follow each chain's fee semantics; additional chain charges
+ * may apply. Already-mined approval transactions are separately accounted.
+ */
+export async function simulateNativeYieldPlan(pub, runtime, rawPlan, rawInput, context) {
+    const verified = await verifyNativeYieldPlan(runtime, rawPlan, rawInput, context);
+    const plan = verified.plan;
+    if (await pub.getChainId() !== plan.chainId)
+        refuseNative('NATIVE_CHAIN_MISMATCH', 'Simulation chain differs');
+    const owner = getAddress(plan.owner);
+    const router = getAddress(plan.deployment.address);
+    const allowance = await pub.readContract({
+        address: getAddress(plan.inputToken), abi: NATIVE_YIELD_ERC20_ABI, functionName: 'allowance',
+        args: [owner, router],
+    });
+    if (allowance !== BigInt(plan.amount)) {
+        refuseNative('NATIVE_APPROVAL_REQUIRED', 'Reconcile/reset and mine the exact input approval before simulation');
+    }
+    const request = { account: owner, to: router, data: plan.steps[2].data, value: 0n };
+    const [simulation, gas, gasPrice, nativeBalance] = await Promise.all([
+        pub.call(request), pub.estimateGas(request), pub.getGasPrice(), pub.getBalance({ address: owner }),
+    ]);
+    if (!simulation.data)
+        refuseNative('NATIVE_SIMULATION_FAILED', 'Native call returned no output');
+    const [actualOutput] = decodeAbiParameters(parseAbiParameters('uint256'), simulation.data);
+    if (actualOutput < BigInt(plan.minimumOutput))
+        refuseNative('NATIVE_SIMULATION_FAILED', 'Simulation output is below the reviewed minimum');
+    const gasLimit = (gas * 120n + 99n) / 100n;
+    if (nativeBalance < gasLimit * gasPrice)
+        refuseNative('NATIVE_GAS_REQUIRED', 'Native balance cannot cover the estimated execution gas');
+    return freezeHybridValue({
+        verified, simulatedOutput: actualOutput.toString(), estimatedGasLimit: gasLimit.toString(),
+        rpcGasEstimateWei: (gasLimit * gasPrice).toString(),
+        excludesApprovalTransactionCosts: true,
+        simulationOnly: true,
+    });
+}
+//# sourceMappingURL=native-yield-simulation.js.map