otto-intel-mcp 0.1.2 → 0.1.4

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

@@ -0,0 +1,30 @@
+import { type NativeYieldPlan, type NativeYieldDeployment } from './native-yield-definition.js';
+import type { NativeYieldRuntime } from './native-yield.js';
+export interface VerifiedNativeYieldPlan {
+    readonly plan: NativeYieldPlan;
+    readonly verificationOnly: true;
+}
+export interface NativeYieldVerificationContext {
+    /** Resolved from the actual signing account/session, never copied from plan metadata. */
+    readonly account: {
+        readonly address: string;
+        readonly chainId: number;
+    };
+    /** Owner-approved/engine-bounded amount for this action, in the exact input token's units. */
+    readonly maximumInputAtomic: bigint;
+}
+export declare function verifyNativeYieldPlan(runtime: NativeYieldRuntime, rawPlan: unknown, rawInput: unknown, context: NativeYieldVerificationContext): Promise<VerifiedNativeYieldPlan>;
+/** Protocol verification only. This cannot produce the opaque EOA-verifier capability. */
+export declare function verifyNativeYieldProtocolPlan(runtime: NativeYieldRuntime, rawPlan: unknown, rawInput: unknown, context: NativeYieldVerificationContext, requireEoaGas?: boolean): Promise<NativeYieldPlan>;
+/** Synchronous age check for the actual independent read, including time spent waiting on locks.
+ * Metadata is process-local and cannot be supplied by a stored plan or caller. */
+export declare function assertFreshNativeYieldProtocolPlan(plan: NativeYieldPlan, nowMs: number): void;
+export declare function assertVerifiedNativeYieldPlan(value: VerifiedNativeYieldPlan): NativeYieldPlan;
+/** Explicit recovery transaction. Caller must reconcile unknown execution first and ask its signer to approve this action. */
+export declare function nativeYieldAllowanceRevocation(rawPlan: NativeYieldPlan, context: Pick<NativeYieldVerificationContext, 'account'>, deployments?: readonly NativeYieldDeployment[]): {
+    chainId: import("./hybrid-yield-markets.js").HybridYieldChainId;
+    from: `0x${string}`;
+    to: `0x${string}`;
+    value: "0";
+    data: `0x${string}`;
+};

package/dist/native-yield-verify.js

@@ -0,0 +1,141 @@
+/** Independent decode-and-reject boundary for a native plan. Verification is not wallet authority. */
+import { decodeFunctionData, encodeFunctionData, getAddress, keccak256, parseAbi, stringToHex } from 'viem';
+import { freezeHybridValue, getHybridYieldMarket, hybridYieldCommitment } from './hybrid-yield-markets.js';
+import { NATIVE_YIELD_DEPLOYMENTS, NATIVE_YIELD_FEE_RECIPIENT, NATIVE_YIELD_PLAN_SCHEMA, NATIVE_YIELD_STATE_MAX_AGE_MS, NATIVE_YIELD_TTL_SECONDS, PREPARE_NATIVE_YIELD_INPUT_SCHEMA, nativeYieldFee, refuseNative, } from './native-yield-definition.js';
+import { assertNativeYieldProtocolState } from './native-yield.js';
+const APPROVE = parseAbi(['function approve(address spender, uint256 amount) returns (bool)']);
+const EXECUTE = parseAbi([
+    'function execute(bytes32 marketId, bool isDeposit, uint256 amount, uint256 minOutput, uint256 nonce, uint256 deadline) returns (uint256)',
+]);
+const verified = new WeakSet();
+const protocolFreshness = new WeakMap();
+function ensure(value, code, message) {
+    if (!value)
+        refuseNative(code, message);
+}
+export async function verifyNativeYieldPlan(runtime, rawPlan, rawInput, context) {
+    const plan = await verifyNativeYieldProtocolPlan(runtime, rawPlan, rawInput, context, true);
+    const result = freezeHybridValue({ plan, verificationOnly: true });
+    verified.add(result);
+    return result;
+}
+/** Protocol verification only. This cannot produce the opaque EOA-verifier capability. */
+export async function verifyNativeYieldProtocolPlan(runtime, rawPlan, rawInput, context, requireEoaGas = false) {
+    const plan = NATIVE_YIELD_PLAN_SCHEMA.parse(rawPlan);
+    const input = PREPARE_NATIVE_YIELD_INPUT_SCHEMA.parse(rawInput);
+    const now = (runtime.nowMs ?? Date.now)();
+    const { planCommitment, ...core } = plan;
+    ensure(hybridYieldCommitment(core) === planCommitment, 'NATIVE_PLAN_TAMPERED', 'Plan commitment mismatch');
+    ensure(plan.intentCommitment === hybridYieldCommitment(input), 'NATIVE_INTENT_MISMATCH', 'Plan belongs to different review input');
+    const market = getHybridYieldMarket(input.marketId);
+    ensure(market && hybridYieldCommitment(market) === input.registryCommitment &&
+        plan.registryCommitment === input.registryCommitment && plan.marketId === market.id, 'NATIVE_REGISTRY_MISMATCH', 'Exact current market record is required');
+    ensure(plan.action === input.action && plan.amount === input.amount &&
+        (input.action !== 'deposit' || market.capabilities.native.deposit !== 'unavailable'), 'NATIVE_ACTION_MISMATCH', 'Action or amount changed, or new deposits are unavailable');
+    const owner = getAddress(context.account.address);
+    ensure(owner === getAddress(input.accountProfile.address) && owner === getAddress(plan.owner) &&
+        context.account.chainId === market.chainId && input.accountProfile.chainId === market.chainId &&
+        plan.chainId === market.chainId, 'NATIVE_OWNER_MISMATCH', 'Actual account or chain is not the reviewed payer/owner');
+    const amount = BigInt(input.amount);
+    ensure(context.maximumInputAtomic > 0n && context.maximumInputAtomic < (1n << 256n) &&
+        amount <= context.maximumInputAtomic, 'NATIVE_CAP_EXCEEDED', 'Input exceeds the separately approved action limit');
+    ensure(plan.preparedAtMs <= now && plan.deadline > Math.floor(now / 1000) &&
+        plan.deadline === Math.floor(plan.preparedAtMs / 1000) + NATIVE_YIELD_TTL_SECONDS &&
+        plan.snapshot.observedAtMs <= plan.preparedAtMs &&
+        plan.preparedAtMs - plan.snapshot.observedAtMs <= NATIVE_YIELD_STATE_MAX_AGE_MS, 'NATIVE_PLAN_EXPIRED', 'Native plan is stale or has an invalid lifetime');
+    const deployment = (runtime.deployments ?? NATIVE_YIELD_DEPLOYMENTS).find((d) => d.chainId === market.chainId);
+    ensure(deployment && hybridYieldCommitment(deployment) === hybridYieldCommitment(plan.deployment), 'NATIVE_DEPLOYMENT_REQUIRED', 'No exact approved deployment matches the plan');
+    const executor = getAddress(deployment.address);
+    const isDeposit = input.action === 'deposit';
+    const inputToken = isDeposit ? market.asset.address : market.position.tokenAddress;
+    const outputToken = isDeposit ? market.position.tokenAddress : market.asset.address;
+    ensure(getAddress(plan.inputToken) === inputToken && getAddress(plan.outputToken) === outputToken, 'NATIVE_TOKEN_MISMATCH', 'Input/output token differs from the registry');
+    ensure(getAddress(plan.fee.recipient) === NATIVE_YIELD_FEE_RECIPIENT &&
+        getAddress(plan.fee.token) === market.asset.address, 'NATIVE_FEE_MISMATCH', 'Fee recipient or asset changed');
+    const protocolOutput = BigInt(plan.protocolOutput);
+    const fee = nativeYieldFee(isDeposit ? amount : protocolOutput);
+    const expected = isDeposit ? protocolOutput : protocolOutput - fee;
+    const floor = expected * BigInt(10_000 - input.slippage.maxBps) / 10000n;
+    const min = BigInt(plan.minimumOutput);
+    ensure(plan.fee.amount === fee.toString() && plan.expectedOutput === expected.toString(), 'NATIVE_FEE_MISMATCH', 'Preview silently changes the approved fee');
+    ensure(min > 0n && min >= floor && min <= expected &&
+        (input.slippage.minOutput === undefined || min >= BigInt(input.slippage.minOutput)), 'NATIVE_MINIMUM_INVALID', 'Reviewed minimum or slippage bound weakened');
+    for (const index of [0, 1]) {
+        const step = plan.steps[index];
+        ensure(step.kind === (index === 0 ? 'approve_reset' : 'approve') &&
+            getAddress(step.to) === inputToken && step.value === '0', 'NATIVE_APPROVAL_INVALID', 'Approval step has wrong token, sequence or native value');
+        const decoded = decodeFunctionData({ abi: APPROVE, data: step.data });
+        const [spender, approved] = decoded.args;
+        ensure(decoded.functionName === 'approve' && getAddress(spender) === executor &&
+            approved === (index === 0 ? 0n : amount) &&
+            encodeFunctionData({ abi: APPROVE, functionName: 'approve', args: [spender, approved] }).toLowerCase() === step.data.toLowerCase(), 'NATIVE_APPROVAL_INVALID', 'Approval spender, amount or canonical bytes differ');
+    }
+    const call = plan.steps[2];
+    ensure(call.kind === 'call' && getAddress(call.to) === executor && call.value === '0', 'NATIVE_CALL_INVALID', 'Action target or native value changed');
+    const decoded = decodeFunctionData({ abi: EXECUTE, data: call.data });
+    const [id, deposit, quantity, minimum, nonce, deadline] = decoded.args;
+    ensure(decoded.functionName === 'execute' && id === keccak256(stringToHex(market.id)) &&
+        deposit === isDeposit && quantity === amount && minimum === min &&
+        nonce === BigInt(plan.nonce) && deadline === BigInt(plan.deadline) &&
+        encodeFunctionData({ abi: EXECUTE, functionName: 'execute', args: decoded.args }).toLowerCase() === call.data.toLowerCase(), 'NATIVE_CALL_INVALID', 'Decoded market/action/amount/minimum/nonce/deadline or canonical bytes differ');
+    // Fresh independent protocol/account read immediately before the caller's signing boundary.
+    // Begin the span before the reader captures its block and observation, including all later awaited RPCs.
+    const readStartedMonotonicMs = performance.now();
+    const readStartedAtMs = (runtime.nowMs ?? Date.now)();
+    ensure(Number.isFinite(readStartedMonotonicMs) && readStartedMonotonicMs >= 0 &&
+        Number.isSafeInteger(readStartedAtMs) && readStartedAtMs >= now, 'NATIVE_STATE_STALE', 'A valid monotonic protocol-read span is required before signing');
+    const state = await runtime.reader.read(market, owner, input.action, amount, deployment);
+    const afterRead = (runtime.nowMs ?? Date.now)();
+    const monotonicAtMs = performance.now();
+    ensure(Number.isSafeInteger(afterRead) && afterRead >= readStartedAtMs &&
+        Number.isFinite(monotonicAtMs) && monotonicAtMs >= readStartedMonotonicMs, 'NATIVE_STATE_STALE', 'A valid monotonic protocol-read span is required before signing');
+    const effectiveAfterRead = Math.max(afterRead, readStartedAtMs + monotonicAtMs - readStartedMonotonicMs);
+    assertNativeYieldProtocolState(state, market, input, effectiveAfterRead);
+    ensure(effectiveAfterRead < plan.deadline * 1000 && state.observedAtMs <= effectiveAfterRead &&
+        effectiveAfterRead - state.observedAtMs <= NATIVE_YIELD_STATE_MAX_AGE_MS &&
+        state.blockTimestampMs <= effectiveAfterRead + 5000 &&
+        effectiveAfterRead - state.blockTimestampMs <= NATIVE_YIELD_STATE_MAX_AGE_MS, 'NATIVE_STATE_STALE', 'Fresh protocol state is required before signing');
+    ensure(state.chainId === market.chainId && state.marketId === market.id &&
+        getAddress(state.owner) === owner && state.routerNonce === nonce, 'NATIVE_NONCE_OR_OWNER_CHANGED', 'Execution nonce or owning account changed; reconcile before preparing again');
+    ensure(state.inputBalance >= amount && state.maxInput >= amount && (!requireEoaGas || state.nativeBalance > 0n), 'NATIVE_BALANCE_OR_LIQUIDITY', 'Balance, liquidity or native gas is no longer sufficient');
+    const currentExpected = isDeposit ? state.protocolOutput : state.protocolOutput - nativeYieldFee(state.protocolOutput);
+    ensure(currentExpected >= min && min >= currentExpected * BigInt(10_000 - input.slippage.maxBps) / 10000n, 'NATIVE_PARITY_CHANGED', 'Fresh protocol preview is outside the reviewed bound; prepare and review again');
+    const result = freezeHybridValue(plan);
+    protocolFreshness.set(result, { observedAtMs: state.observedAtMs, blockTimestampMs: state.blockTimestampMs,
+        checkedAtMs: afterRead, effectiveAtMs: effectiveAfterRead, monotonicAtMs });
+    return result;
+}
+/** Synchronous age check for the actual independent read, including time spent waiting on locks.
+ * Metadata is process-local and cannot be supplied by a stored plan or caller. */
+export function assertFreshNativeYieldProtocolPlan(plan, nowMs) {
+    const facts = protocolFreshness.get(plan), monotonicNow = performance.now();
+    ensure(facts && Number.isSafeInteger(nowMs) && nowMs >= facts.checkedAtMs &&
+        Number.isFinite(monotonicNow) && monotonicNow >= facts.monotonicAtMs, 'NATIVE_STATE_STALE', 'Fresh protocol state is required before signing');
+    // The read span is already included in effectiveAtMs; add only elapsed time since its endpoint.
+    const current = Math.max(nowMs, facts.effectiveAtMs + monotonicNow - facts.monotonicAtMs);
+    ensure(current < plan.deadline * 1000 && current - facts.observedAtMs <= NATIVE_YIELD_STATE_MAX_AGE_MS &&
+        current - facts.blockTimestampMs <= NATIVE_YIELD_STATE_MAX_AGE_MS, 'NATIVE_STATE_STALE', 'Fresh protocol state is required before signing');
+}
+export function assertVerifiedNativeYieldPlan(value) {
+    ensure(value && verified.has(value) && Object.isFrozen(value), 'NATIVE_UNVERIFIED_PLAN', 'Native plan lacks independent verification');
+    return value.plan;
+}
+/** Explicit recovery transaction. Caller must reconcile unknown execution first and ask its signer to approve this action. */
+export function nativeYieldAllowanceRevocation(rawPlan, context, deployments = NATIVE_YIELD_DEPLOYMENTS) {
+    const plan = NATIVE_YIELD_PLAN_SCHEMA.parse(rawPlan);
+    const { planCommitment, ...core } = plan;
+    ensure(hybridYieldCommitment(core) === planCommitment, 'NATIVE_PLAN_TAMPERED', 'Recovery plan commitment mismatch');
+    const market = getHybridYieldMarket(plan.marketId);
+    ensure(market && hybridYieldCommitment(market) === plan.registryCommitment, 'NATIVE_REGISTRY_MISMATCH', 'Unknown recovery market');
+    ensure(plan.chainId === market.chainId && context.account.chainId === market.chainId &&
+        getAddress(context.account.address) === getAddress(plan.owner), 'NATIVE_OWNER_MISMATCH', 'Recovery must use the actual owning account and chain');
+    const deployment = deployments.find((d) => d.chainId === market.chainId);
+    ensure(deployment && hybridYieldCommitment(deployment) === hybridYieldCommitment(plan.deployment), 'NATIVE_DEPLOYMENT_REQUIRED', 'Recovery target is not the approved executor');
+    const inputToken = plan.action === 'deposit' ? market.asset.address : market.position.tokenAddress;
+    ensure(getAddress(plan.inputToken) === inputToken, 'NATIVE_TOKEN_MISMATCH', 'Recovery token changed');
+    return freezeHybridValue({
+        chainId: market.chainId, from: getAddress(context.account.address), to: inputToken, value: '0',
+        data: encodeFunctionData({ abi: APPROVE, functionName: 'approve', args: [getAddress(deployment.address), 0n] }),
+    });
+}
+//# sourceMappingURL=native-yield-verify.js.map

package/dist/native-yield.d.ts

@@ -0,0 +1,17 @@
+import { type HybridYieldMarket } from './hybrid-yield-markets.js';
+import { type NativeYieldDeployment, type NativeYieldPlan, type NativeYieldReader, type NativeYieldState, type PrepareNativeYieldInput } from './native-yield-definition.js';
+export interface NativeYieldRuntime {
+    readonly reader: NativeYieldReader;
+    /** Server-owned deployment manifest. No request or environment-address seam. */
+    readonly deployments?: readonly NativeYieldDeployment[];
+    readonly nowMs?: () => number;
+}
+export declare function resolveNativeYieldMarket(input: PrepareNativeYieldInput): HybridYieldMarket;
+export declare function assertNativeYieldState(state: NativeYieldState, market: HybridYieldMarket, input: PrepareNativeYieldInput, now: number): void;
+/** Protocol-only checks for the separately authorized UserOp path; never grants EOA signing authority. */
+export declare function assertNativeYieldProtocolState(state: NativeYieldState, market: HybridYieldMarket, input: PrepareNativeYieldInput, now: number): void;
+/** Pure construction from a reader-validated state; the independent verifier decodes the resulting bytes. */
+export declare function buildNativeYieldPlan(input: PrepareNativeYieldInput, market: HybridYieldMarket, deployment: NativeYieldDeployment, state: NativeYieldState, now: number): NativeYieldPlan;
+/** Exact protocol recipe. Its caller must establish the separate gas-payer and account authority. */
+export declare function buildNativeYieldProtocolPlan(input: PrepareNativeYieldInput, market: HybridYieldMarket, deployment: NativeYieldDeployment, state: NativeYieldState, now: number): NativeYieldPlan;
+export declare function prepareNativeYield(runtime: NativeYieldRuntime, rawInput: unknown): Promise<NativeYieldPlan>;

package/dist/native-yield.js

@@ -0,0 +1,119 @@
+/** Native protocol constructor: fixed protocol, exact amounts, current state and account. Never signs. */
+import { encodeFunctionData, getAddress, keccak256, stringToHex } from 'viem';
+import { freezeHybridValue, getHybridYieldMarket, hybridYieldCommitment } from './hybrid-yield-markets.js';
+import { NATIVE_YIELD_DEPLOYMENTS, NATIVE_YIELD_DEPLOYMENT_SCHEMA, NATIVE_YIELD_ERC20_ABI, NATIVE_YIELD_FEE_RECIPIENT, NATIVE_YIELD_FEE_VERSION, NATIVE_YIELD_PLAN_SCHEMA, NATIVE_YIELD_ROUTER_ABI, NATIVE_YIELD_STATE_MAX_AGE_MS, NATIVE_YIELD_TTL_SECONDS, PREPARE_NATIVE_YIELD_INPUT_SCHEMA, nativeYieldFee, refuseNative, } from './native-yield-definition.js';
+export function resolveNativeYieldMarket(input) {
+    const market = getHybridYieldMarket(input.marketId);
+    if (!market)
+        return refuseNative('NATIVE_MARKET_UNKNOWN', 'Unknown exact native yield market');
+    if (hybridYieldCommitment(market) !== input.registryCommitment) {
+        return refuseNative('NATIVE_REGISTRY_MISMATCH', 'Re-read this market; its registry commitment changed');
+    }
+    if (market.chainId !== input.accountProfile.chainId) {
+        return refuseNative('NATIVE_CHAIN_MISMATCH', 'Native execution requires the position chain and exact underlying asset');
+    }
+    if (input.action === 'deposit' && market.capabilities.native.deposit === 'unavailable') {
+        return refuseNative('NATIVE_DEPOSIT_UNAVAILABLE', 'This legacy market supports exit, not a new native allocation');
+    }
+    return market;
+}
+export function assertNativeYieldState(state, market, input, now) {
+    assertNativeYieldProtocolState(state, market, input, now);
+    if (state.nativeBalance === 0n) {
+        refuseNative('NATIVE_GAS_REQUIRED', 'This EOA needs native gas on the selected network; sponsorship is not assumed');
+    }
+}
+/** Protocol-only checks for the separately authorized UserOp path; never grants EOA signing authority. */
+export function assertNativeYieldProtocolState(state, market, input, now) {
+    if (state.chainId !== market.chainId || state.marketId !== market.id ||
+        getAddress(state.owner) !== getAddress(input.accountProfile.address)) {
+        refuseNative('NATIVE_STATE_BINDING', 'Protocol reads belong to a different market, chain or owner');
+    }
+    for (const value of [state.blockNumber, state.routerNonce, state.inputBalance, state.inputAllowance,
+        state.positionBalance, state.assetBalance, state.nativeBalance, state.maxInput, state.protocolOutput]) {
+        if (typeof value !== 'bigint' || value < 0n || value >= (1n << 256n)) {
+            refuseNative('NATIVE_STATE_INVALID', 'Protocol read returned an invalid atomic quantity');
+        }
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(state.blockHash) ||
+        !Number.isSafeInteger(state.observedAtMs) || !Number.isSafeInteger(state.blockTimestampMs) ||
+        state.observedAtMs > now || now - state.observedAtMs > NATIVE_YIELD_STATE_MAX_AGE_MS ||
+        state.blockTimestampMs > now + 5000 || now - state.blockTimestampMs > NATIVE_YIELD_STATE_MAX_AGE_MS) {
+        refuseNative('NATIVE_STATE_STALE', 'Current anchored protocol state is required');
+    }
+    const amount = BigInt(input.amount);
+    if (state.inputBalance < amount || state.maxInput < amount) {
+        refuseNative('NATIVE_BALANCE_OR_LIQUIDITY', 'Insufficient exact input balance or currently redeemable liquidity');
+    }
+    if (state.protocolOutput === 0n)
+        refuseNative('NATIVE_ZERO_OUTPUT', 'Protocol preview returns zero output');
+}
+/** Pure construction from a reader-validated state; the independent verifier decodes the resulting bytes. */
+export function buildNativeYieldPlan(input, market, deployment, state, now) {
+    assertNativeYieldState(state, market, input, now);
+    return buildNativeYieldProtocolPlan(input, market, deployment, state, now);
+}
+/** Exact protocol recipe. Its caller must establish the separate gas-payer and account authority. */
+export function buildNativeYieldProtocolPlan(input, market, deployment, state, now) {
+    assertNativeYieldProtocolState(state, market, input, now);
+    const owner = getAddress(input.accountProfile.address);
+    const executor = getAddress(deployment.address);
+    const amount = BigInt(input.amount);
+    const isDeposit = input.action === 'deposit';
+    const fee = nativeYieldFee(isDeposit ? amount : state.protocolOutput);
+    const expectedOutput = isDeposit ? state.protocolOutput : state.protocolOutput - fee;
+    if (expectedOutput <= 0n)
+        return refuseNative('NATIVE_ZERO_OUTPUT', 'Output after the approved fee is zero');
+    const floor = expectedOutput * BigInt(10_000 - input.slippage.maxBps) / 10000n;
+    const requestedFloor = input.slippage.minOutput === undefined ? 0n : BigInt(input.slippage.minOutput);
+    const minOutput = requestedFloor > floor ? requestedFloor : floor;
+    if (minOutput <= 0n || minOutput > expectedOutput) {
+        return refuseNative('NATIVE_MINIMUM_INVALID', 'The minimum output is zero or exceeds the fresh protocol preview');
+    }
+    const inputToken = isDeposit ? market.asset.address : market.position.tokenAddress;
+    const outputToken = isDeposit ? market.position.tokenAddress : market.asset.address;
+    const deadline = Math.floor(now / 1000) + NATIVE_YIELD_TTL_SECONDS;
+    const core = {
+        schemaVersion: '1', kind: 'native-yield-plan', transport: 'native-protocol',
+        marketId: market.id, registryCommitment: input.registryCommitment, owner, chainId: market.chainId,
+        action: input.action, amount: amount.toString(), inputToken, outputToken,
+        expectedOutput: expectedOutput.toString(), minimumOutput: minOutput.toString(),
+        protocolOutput: state.protocolOutput.toString(),
+        fee: {
+            bps: 10, recipient: NATIVE_YIELD_FEE_RECIPIENT, token: market.asset.address,
+            amount: fee.toString(), version: NATIVE_YIELD_FEE_VERSION, rounding: 'floor',
+        },
+        nonce: state.routerNonce.toString(), deadline, preparedAtMs: now,
+        snapshot: { blockNumber: state.blockNumber.toString(), blockHash: state.blockHash, observedAtMs: state.observedAtMs },
+        deployment,
+        steps: [
+            { kind: 'approve_reset', to: inputToken, value: '0', data: encodeFunctionData({
+                    abi: NATIVE_YIELD_ERC20_ABI, functionName: 'approve', args: [executor, 0n],
+                }) },
+            { kind: 'approve', to: inputToken, value: '0', data: encodeFunctionData({
+                    abi: NATIVE_YIELD_ERC20_ABI, functionName: 'approve', args: [executor, amount],
+                }) },
+            { kind: 'call', to: executor, value: '0', data: encodeFunctionData({
+                    abi: NATIVE_YIELD_ROUTER_ABI, functionName: 'execute',
+                    args: [keccak256(stringToHex(market.id)), isDeposit, amount, minOutput, state.routerNonce, BigInt(deadline)],
+                }) },
+        ],
+        authorization: 'requires-separate-account-authority',
+        allowanceRecovery: 'approval-is-separate-and-may-remain-after-failure',
+        intentCommitment: hybridYieldCommitment(input),
+    };
+    return freezeHybridValue(NATIVE_YIELD_PLAN_SCHEMA.parse({ ...core, planCommitment: hybridYieldCommitment(core) }));
+}
+export async function prepareNativeYield(runtime, rawInput) {
+    const input = PREPARE_NATIVE_YIELD_INPUT_SCHEMA.parse(rawInput);
+    const market = resolveNativeYieldMarket(input);
+    const deployment = (runtime.deployments ?? NATIVE_YIELD_DEPLOYMENTS).find((d) => d.chainId === market.chainId);
+    if (!deployment) {
+        return refuseNative('NATIVE_DEPLOYMENT_REQUIRED', 'Native protocol construction is implemented; this chain has no approved executor deployment');
+    }
+    const pin = NATIVE_YIELD_DEPLOYMENT_SCHEMA.parse(deployment);
+    const owner = getAddress(input.accountProfile.address);
+    const state = await runtime.reader.read(market, owner, input.action, BigInt(input.amount), pin);
+    return buildNativeYieldPlan(input, market, pin, state, (runtime.nowMs ?? Date.now)());
+}
+//# sourceMappingURL=native-yield.js.map

package/dist/stock-buy-definition.d.ts

@@ -0,0 +1,338 @@
+/**
+ * `otto_prepare_stock_buy` — a tokenized-stock BUY (Coinbase B20 on Base) as a thin constructor over
+ * `otto_prepare_swap` (Founder word: delegation beyond swaps, 2026-09-03).
+ *
+ * WHY IT IS A SWAP, PROVEN LIVE (li.quest, 2026-09-03, production params `integrator=ottowallet&fee=0.001`):
+ * $10 USDC → AAPLc quoted as a same-chain route whose transactionRequest targets the reviewed LI.FI
+ * diamond with selector 0x5fd9ae2e = `swapTokensMultipleV3ERC20ToERC20` — one of the two fenced
+ * GenericSwapV3 entry points — USDC is the v1 allow-listed input token, and the receiver is the signing
+ * account. A B20 buy is therefore INSIDE the delegation fence as it stands (v1/v2, unchanged); the SELL
+ * direction needs a B20-token approve to the diamond, which fence v2 grants only to the two vault share
+ * tokens — a sell is fence v3, sized in docs/0903_delegation_empire_scope.md, not shipped here.
+ *
+ * WHAT THIS TOOL PINS THAT A RAW SWAP DOES NOT:
+ *   - the OUTPUT token is the registry row's B20 contract, never a caller input;
+ *   - the row is the CURRENT registry record (caller's commitment must match the recomputed one);
+ *   - chain 8453 / venue COINBASE_B20 / asset USDC, from the row, refused otherwise;
+ *   - PRICE PARITY on the WORST PERMISSIBLE FILL: `amount / minTokens` (the floor the router
+ *     enforces) may not exceed the row's own Chainlink total-return mark by more than the pinned
+ *     tolerance, and the slippage band is capped — a thin or poisoned pool, or a wide floor, can
+ *     never execute a delegated buy far over the venue's own mark;
+ *   - ORACLE FRESHNESS: a frozen feed (> 24 h — the dashboard's own frozen threshold; feeds hold their
+ *     last value off-hours) cannot anchor parity, so the buy is refused by name. Off-hours the pool may
+ *     legitimately trade away from Friday's close; a delegated buy waits for a live reference.
+ * The generic `otto_prepare_swap` refuses every executable-equity token address in either direction
+ * (the same discipline as the yield share tokens): this constructor is the only delegated path.
+ */
+import { z } from 'zod';
+export declare const STOCK_BUY_TOOL_NAME: "otto_prepare_stock_buy";
+/**
+ * 🔴 PINNED PRICE-PARITY TOLERANCE, in basis points of the Chainlink mark, on the WORST PERMISSIBLE
+ * FILL (`fromAmount / minTokens` — the floor the router actually enforces on-chain, fees included).
+ *
+ * Gate G1: a guard on the QUOTE alone lets the permitted slippage carry the executed fill past the
+ * tolerance (quote at 0 bps + 1,000-bps floor = an 11% overpay the guard never saw). So parity is
+ * checked against the FLOOR, and the floor's own room is bounded: this constructor caps
+ * `slippage.maxBps` at 100 (the generic swap's 1..1000 range is not a stock buy's).
+ *
+ * Derivation (live li.quest quotes 2026-09-03/04, production params):
+ *   - LI.FI fixed integrator fee 0.25% of the input                                    → 25 bps
+ *   - observed B20 pool spread over the oracle mark (~21 bps AAPLc · ~34 bps NVDAc
+ *     at small size; thin pools move with size)                                        → ~50 bps p95
+ *   - the slippage floor this schema permits                                           → ≤ 100 bps
+ *   = 175 bps on the worst permissible fill: whatever routing and slippage do, a delegated buy can
+ *   never execute more than 1.75% over the venue's own mark. A test pins this value; widening it
+ *   must redden that test.
+ */
+export declare const STOCK_BUY_PARITY_TOLERANCE_BPS: 175;
+/** Gate G1: the tightest slippage band of any constructor — the tolerance above assumes it. */
+export declare const STOCK_BUY_MAX_SLIPPAGE_BPS: 100;
+/** The dashboard's frozen threshold (freshness.ts STALE_MAX_MIN): beyond this the feed cannot anchor parity. */
+export declare const STOCK_BUY_MAX_ORACLE_AGE_SEC: number;
+export declare const PREPARE_STOCK_BUY_INPUT_SCHEMA: z.ZodObject<{
+    accountProfile: z.ZodObject<{
+        kind: z.ZodEnum<{
+            eoa: "eoa";
+            safe: "safe";
+        }>;
+        address: z.ZodString;
+        chainId: z.ZodNumber;
+    }, z.core.$strict>;
+    executableEquityId: z.ZodString;
+    registryCommitment: z.ZodString;
+    amount: z.ZodString;
+    slippage: z.ZodObject<{
+        maxBps: z.ZodNumber;
+    }, z.core.$strict>;
+    client_ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PrepareStockBuyInput = z.infer<typeof PREPARE_STOCK_BUY_INPUT_SCHEMA>;
+export declare const STOCK_BUY_PREVIEW_SCHEMA: z.ZodObject<{
+    equity_id: z.ZodString;
+    venue: z.ZodLiteral<"COINBASE_B20">;
+    chain_id: z.ZodLiteral<8453>;
+    underlying: z.ZodString;
+    symbol: z.ZodString;
+    token: z.ZodString;
+    asset: z.ZodString;
+    amount: z.ZodString;
+    expected_tokens: z.ZodString;
+    min_tokens: z.ZodString;
+    oracle_price: z.ZodString;
+    oracle_age_sec: z.ZodNumber;
+    parity_premium_bps: z.ZodNumber;
+    parity_tolerance_bps: z.ZodLiteral<175>;
+    quoted_fees: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        amount_usd: z.ZodString;
+    }, z.core.$strict>>;
+    quoted_gas_usd: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const PREPARE_STOCK_BUY_OUTPUT_SCHEMA: z.ZodObject<{
+    envelope: z.ZodObject<{
+        schema_version: z.ZodLiteral<"1">;
+        artifact_id: z.ZodString;
+        rail: z.ZodLiteral<"lifi">;
+        operation: z.ZodLiteral<"swap">;
+        intent_digest: z.ZodString;
+        account_binding: z.ZodObject<{
+            kind: z.ZodEnum<{
+                eoa: "eoa";
+                safe: "safe";
+            }>;
+            address: z.ZodString;
+            chainId: z.ZodNumber;
+            protocol_roles: z.ZodObject<{
+                lifi: z.ZodObject<{
+                    sender: z.ZodString;
+                    receiver: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        required_capabilities: z.ZodArray<z.ZodEnum<{
+            send_evm_transaction: "send_evm_transaction";
+            submit_evm_batch: "submit_evm_batch";
+        }>>;
+        payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"evm_execution_plan">;
+            chain_id: z.ZodNumber;
+            steps: z.ZodArray<z.ZodObject<{
+                to: z.ZodString;
+                value: z.ZodString;
+                data: z.ZodString;
+                kind: z.ZodEnum<{
+                    approve: "approve";
+                    approve_reset: "approve_reset";
+                    call: "call";
+                }>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>], "kind">;
+        fee_attribution: z.ZodObject<{
+            mechanism: z.ZodLiteral<"lifi_integrator_fee">;
+            config_version: z.ZodString;
+        }, z.core.$strict>;
+        replay_disclosure: z.ZodObject<{
+            artifact_role: z.ZodLiteral<"construction_aid">;
+            freshness_boundary: z.ZodLiteral<"valid_until">;
+            onchain_replay_boundary: z.ZodLiteral<"signer_account_nonce">;
+            tool_guarantees_single_execution: z.ZodLiteral<false>;
+        }, z.core.$strict>;
+        assertions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            result: z.ZodLiteral<"passed">;
+        }, z.core.$strict>>;
+        valid_until: z.ZodString;
+        submission: z.ZodObject<{
+            method: z.ZodEnum<{
+                send_evm_transaction: "send_evm_transaction";
+                submit_evm_batch: "submit_evm_batch";
+            }>;
+            chain_id: z.ZodNumber;
+            artifact_id: z.ZodString;
+            payload_digest: z.ZodString;
+            artifact_digest: z.ZodString;
+            adapter_owned_fields: z.ZodTuple<[z.ZodLiteral<"nonce">, z.ZodLiteral<"gas">, z.ZodLiteral<"serialization">], null>;
+            client_ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    prepareInput: z.ZodObject<{
+        accountProfile: z.ZodObject<{
+            kind: z.ZodEnum<{
+                eoa: "eoa";
+                safe: "safe";
+            }>;
+            address: z.ZodString;
+            chainId: z.ZodNumber;
+        }, z.core.$strict>;
+        chainId: z.ZodNumber;
+        fromToken: z.ZodString;
+        toToken: z.ZodString;
+        fromAmount: z.ZodString;
+        slippage: z.ZodObject<{
+            maxBps: z.ZodNumber;
+            minAmountOut: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        client_ref: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    preview: z.ZodObject<{
+        equity_id: z.ZodString;
+        venue: z.ZodLiteral<"COINBASE_B20">;
+        chain_id: z.ZodLiteral<8453>;
+        underlying: z.ZodString;
+        symbol: z.ZodString;
+        token: z.ZodString;
+        asset: z.ZodString;
+        amount: z.ZodString;
+        expected_tokens: z.ZodString;
+        min_tokens: z.ZodString;
+        oracle_price: z.ZodString;
+        oracle_age_sec: z.ZodNumber;
+        parity_premium_bps: z.ZodNumber;
+        parity_tolerance_bps: z.ZodLiteral<175>;
+        quoted_fees: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            amount_usd: z.ZodString;
+        }, z.core.$strict>>;
+        quoted_gas_usd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    registry_commitment: z.ZodString;
+}, z.core.$strict>;
+export type PrepareStockBuyOutput = z.infer<typeof PREPARE_STOCK_BUY_OUTPUT_SCHEMA>;
+/** The one on-chain read this constructor needs: the row's Chainlink feed, price + updatedAt. */
+export interface EquityOracleReader {
+    latestRoundData(feed: `0x${string}`): Promise<{
+        readonly answer: bigint;
+        readonly updatedAt: bigint;
+    }>;
+}
+export declare const STOCK_BUY_TOOL_DEFINITION: Readonly<{
+    name: "otto_prepare_stock_buy";
+    title: "Prepare a tokenized-stock buy (Coinbase B20 on Base) as a delegable swap pair";
+    description: "Prepare the EXACT otto_prepare_swap pair (envelope + prepareInput) that buys one of the executable Coinbase B20 tokenized equities on Base with USDC, as a LI.FI route through the fenced diamond whose receiver is the signing account. The token comes from the registry row named by executableEquityId and is never an input; the caller's registryCommitment must equal the commitment recomputed over the current record. The WORST PERMISSIBLE FILL (amount over the route's own floor) is checked against the equity's own Chainlink total-return mark and refused when it exceeds the pinned tolerance, or when the feed is frozen (> 24 h). Returns the pair unchanged plus a preview; never signs or submits — submit the pair through otto_submit_under_delegation under the end user's per-swap cap.";
+    inputSchema: z.ZodObject<{
+        accountProfile: z.ZodObject<{
+            kind: z.ZodEnum<{
+                eoa: "eoa";
+                safe: "safe";
+            }>;
+            address: z.ZodString;
+            chainId: z.ZodNumber;
+        }, z.core.$strict>;
+        executableEquityId: z.ZodString;
+        registryCommitment: z.ZodString;
+        amount: z.ZodString;
+        slippage: z.ZodObject<{
+            maxBps: z.ZodNumber;
+        }, z.core.$strict>;
+        client_ref: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    outputSchema: z.ZodObject<{
+        envelope: z.ZodObject<{
+            schema_version: z.ZodLiteral<"1">;
+            artifact_id: z.ZodString;
+            rail: z.ZodLiteral<"lifi">;
+            operation: z.ZodLiteral<"swap">;
+            intent_digest: z.ZodString;
+            account_binding: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    eoa: "eoa";
+                    safe: "safe";
+                }>;
+                address: z.ZodString;
+                chainId: z.ZodNumber;
+                protocol_roles: z.ZodObject<{
+                    lifi: z.ZodObject<{
+                        sender: z.ZodString;
+                        receiver: z.ZodString;
+                    }, z.core.$strict>;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+            required_capabilities: z.ZodArray<z.ZodEnum<{
+                send_evm_transaction: "send_evm_transaction";
+                submit_evm_batch: "submit_evm_batch";
+            }>>;
+            payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"evm_execution_plan">;
+                chain_id: z.ZodNumber;
+                steps: z.ZodArray<z.ZodObject<{
+                    to: z.ZodString;
+                    value: z.ZodString;
+                    data: z.ZodString;
+                    kind: z.ZodEnum<{
+                        approve: "approve";
+                        approve_reset: "approve_reset";
+                        call: "call";
+                    }>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>], "kind">;
+            fee_attribution: z.ZodObject<{
+                mechanism: z.ZodLiteral<"lifi_integrator_fee">;
+                config_version: z.ZodString;
+            }, z.core.$strict>;
+            replay_disclosure: z.ZodObject<{
+                artifact_role: z.ZodLiteral<"construction_aid">;
+                freshness_boundary: z.ZodLiteral<"valid_until">;
+                onchain_replay_boundary: z.ZodLiteral<"signer_account_nonce">;
+                tool_guarantees_single_execution: z.ZodLiteral<false>;
+            }, z.core.$strict>;
+            assertions: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                result: z.ZodLiteral<"passed">;
+            }, z.core.$strict>>;
+            valid_until: z.ZodString;
+            submission: z.ZodObject<{
+                method: z.ZodEnum<{
+                    send_evm_transaction: "send_evm_transaction";
+                    submit_evm_batch: "submit_evm_batch";
+                }>;
+                chain_id: z.ZodNumber;
+                artifact_id: z.ZodString;
+                payload_digest: z.ZodString;
+                artifact_digest: z.ZodString;
+                adapter_owned_fields: z.ZodTuple<[z.ZodLiteral<"nonce">, z.ZodLiteral<"gas">, z.ZodLiteral<"serialization">], null>;
+                client_ref: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        prepareInput: z.ZodObject<{
+            accountProfile: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    eoa: "eoa";
+                    safe: "safe";
+                }>;
+                address: z.ZodString;
+                chainId: z.ZodNumber;
+            }, z.core.$strict>;
+            chainId: z.ZodNumber;
+            fromToken: z.ZodString;
+            toToken: z.ZodString;
+            fromAmount: z.ZodString;
+            slippage: z.ZodObject<{
+                maxBps: z.ZodNumber;
+                minAmountOut: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            client_ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        preview: z.ZodObject<{
+            equity_id: z.ZodString;
+            venue: z.ZodLiteral<"COINBASE_B20">;
+            chain_id: z.ZodLiteral<8453>;
+            underlying: z.ZodString;
+            symbol: z.ZodString;
+            token: z.ZodString;
+            asset: z.ZodString;
+            amount: z.ZodString;
+            expected_tokens: z.ZodString;
+            min_tokens: z.ZodString;
+            oracle_price: z.ZodString;
+            oracle_age_sec: z.ZodNumber;
+            parity_premium_bps: z.ZodNumber;
+            parity_tolerance_bps: z.ZodLiteral<175>;
+            quoted_fees: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                amount_usd: z.ZodString;
+            }, z.core.$strict>>;
+            quoted_gas_usd: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        registry_commitment: z.ZodString;
+    }, z.core.$strict>;
+}>;