otto-intel-mcp 0.1.0

package/dist/execution-tools.js

@@ -0,0 +1,690 @@
+import { randomBytes } from 'node:crypto';
+import { encodeFunctionData, getAddress, parseAbi } from 'viem';
+import { attributedFeeAmount, HL_BUILDER_ATTRIBUTION_STATUS, HYPERLIQUID_L1_SIGNATURE_CHAIN_ID, isEnumeratedCctpBridgeRoute, reviewedLiFiFeeForwarders, loadExecutionServiceConfig, POLYMARKET_CHAIN_ID, } from './execution-config.js';
+import { refuse } from './execution-errors.js';
+import { createDelegationServicesFromEnv, } from './execution-delegation.js';
+import { recordPreparedArtifact } from './prepared-artifacts.js';
+import { swapIntentDigestInput } from './execution-intent.js';
+import { BRIDGE_EXECUTION_ENVELOPE_SCHEMA, EXECUTION_ENVELOPE_SCHEMA, HYPERLIQUID_EXECUTION_ENVELOPE_SCHEMA, POLYMARKET_EXECUTION_ENVELOPE_SCHEMA, PREPARE_BRIDGE_INPUT_SCHEMA, PREPARE_PERP_ORDER_INPUT_SCHEMA, PREPARE_POLYMARKET_ORDER_INPUT_SCHEMA, PREPARE_SWAP_INPUT_SCHEMA, } from './execution-tool-definitions.js';
+import { accountBinding, artifactCommitmentDigest, bridgeAccountBinding, createArtifactId, executionDigest, hyperliquidAccountBinding, polymarketAccountBinding, } from './execution-types.js';
+import { RestHyperliquidInfoClient, } from './hyperliquid-info-client.js';
+import { assertHyperliquidBracketCoherent, assertHyperliquidPriceOnGrid, assertHyperliquidSizeOnGrid, decodeAndAssertHyperliquidAction, hyperliquidSigningDeclaration, } from './hyperliquid-order-assertions.js';
+import { buildUnsignedHyperliquidOrderAction, } from './hyperliquid-order-builder.js';
+import { decodeAndAssertLiFiBridge } from './lifi-bridge-assertions.js';
+import { RestLiFiQuoteClient } from './lifi-execution-client.js';
+import { decodeAndAssertLiFiSwap } from './lifi-swap-assertions.js';
+import { RestPolymarketClobClient } from './polymarket-clob-client.js';
+import { assertPolymarketBuilderAttributionRuled, assertPolymarketPriceOnTick, decodeAndAssertPolymarketOrder, polymarketAtomicUnits, } from './polymarket-order-assertions.js';
+import { buildUnsignedPolymarketOrder, } from './polymarket-order-builder.js';
+const ERC20_APPROVE_ABI = parseAbi([
+    'function approve(address spender, uint256 amount) returns (bool)',
+]);
+export function createExecutionToolRuntime(config, overrides = {}) {
+    return Object.freeze({
+        config,
+        quoteClient: overrides.quoteClient ?? new RestLiFiQuoteClient(config),
+        clobClient: overrides.clobClient ?? new RestPolymarketClobClient(config),
+        polymarketOrderBuilder: overrides.polymarketOrderBuilder ?? buildUnsignedPolymarketOrder,
+        hyperliquidInfoClient: overrides.hyperliquidInfoClient ?? new RestHyperliquidInfoClient(config),
+        hyperliquidActionBuilder: overrides.hyperliquidActionBuilder ?? buildUnsignedHyperliquidOrderAction,
+        nowMs: overrides.nowMs ?? Date.now,
+        entropy: overrides.entropy ?? (() => randomBytes(10)),
+        clientOrderIdEntropy: overrides.clientOrderIdEntropy ?? (() => randomBytes(16)),
+        ...(overrides.delegation ? { delegation: overrides.delegation } : {}),
+    });
+}
+export function createExecutionToolRuntimeFromEnv(env = process.env) {
+    const config = loadExecutionServiceConfig(env);
+    return config ? createExecutionToolRuntime(config) : undefined;
+}
+/**
+ * The hosted boot: the prepare runtime plus, when the five delegation variables are set, the delegated
+ * services (the optional SDK loaded, the Base RPC chain id checked). Delegation configured while
+ * execution is switched off is a misconfiguration and refuses to boot rather than silently dropping
+ * the tool.
+ */
+export async function createExecutionToolRuntimeWithDelegationFromEnv(env = process.env) {
+    const config = loadExecutionServiceConfig(env);
+    const delegation = await createDelegationServicesFromEnv(env);
+    if (!config) {
+        if (delegation) {
+            throw new Error('delegated send is configured but OTTO_EXECUTION_MCP_ENABLED is not true; enable the execution tools or unset the delegation variables');
+        }
+        return undefined;
+    }
+    return createExecutionToolRuntime(config, delegation ? { delegation } : {});
+}
+function normalizedAddress(value) {
+    return getAddress(value.toLowerCase());
+}
+function normalizedIntent(input, profile) {
+    // One implementation, shared with consumers through `otto-intel-mcp/execution`.
+    return swapIntentDigestInput({
+        ...input,
+        accountProfile: { ...input.accountProfile, address: profile.address },
+    });
+}
+function normalizedBridgeIntent(input, profile, destinationRecipient) {
+    return {
+        accountProfile: {
+            kind: profile.kind,
+            address: profile.address,
+            chainId: profile.chainId,
+        },
+        fromChainId: input.fromChainId,
+        toChainId: input.toChainId,
+        fromToken: normalizedAddress(input.fromToken),
+        toToken: normalizedAddress(input.toToken),
+        fromAmount: input.fromAmount,
+        destinationRecipient,
+        slippage: {
+            maxBps: input.slippage.maxBps,
+            ...(input.slippage.minAmountOut ? { minAmountOut: input.slippage.minAmountOut } : {}),
+        },
+        ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+    };
+}
+function normalizedPolymarketIntent(input, profile) {
+    return {
+        accountProfile: {
+            kind: profile.kind,
+            address: profile.address,
+            chainId: profile.chainId,
+        },
+        tokenId: input.tokenId,
+        side: input.side,
+        price: input.price,
+        size: input.size,
+        ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+    };
+}
+function normalizedPerpIntent(input, profile, tradingSigner, vaultAddress) {
+    return {
+        accountProfile: {
+            kind: profile.kind,
+            address: profile.address,
+            chainId: profile.chainId,
+        },
+        asset: input.asset,
+        side: input.side,
+        size: input.size,
+        limitPrice: input.limitPrice,
+        timeInForce: input.timeInForce,
+        reduceOnly: input.reduceOnly,
+        tradingSigner,
+        vaultAddress: vaultAddress ?? null,
+        ...(input.takeProfitPrice ? { takeProfitPrice: input.takeProfitPrice } : {}),
+        ...(input.stopLossPrice ? { stopLossPrice: input.stopLossPrice } : {}),
+        ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+    };
+}
+/** 0x + 32 lowercase hex, the venue's client-order-id shape (`hl-write-request-schema.ts:549`). */
+function mintClientOrderId(entropy) {
+    const bytes = entropy();
+    if (bytes.length !== 16) {
+        return refuse('HYPERLIQUID_ORDER_INVALID', 'client order id entropy source did not produce 16 bytes');
+    }
+    return `0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+function capabilityFor(profile) {
+    if (profile.kind === 'eoa')
+        return 'send_evm_transaction';
+    if (profile.kind === 'safe')
+        return 'submit_evm_batch';
+    return refuse('UNSUPPORTED_ACCOUNT_PROFILE', 'only EOA and Safe profiles are supported');
+}
+export async function prepareSwap(runtime, rawInput, signal) {
+    const input = PREPARE_SWAP_INPUT_SCHEMA.parse(rawInput);
+    const profile = {
+        kind: input.accountProfile.kind,
+        address: normalizedAddress(input.accountProfile.address),
+        chainId: input.accountProfile.chainId,
+    };
+    if (profile.chainId !== input.chainId) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', 'account profile chain does not match swap chain');
+    }
+    if (!reviewedLiFiFeeForwarders(input.chainId)) {
+        return refuse('UNSUPPORTED_LIFI_ROUTE', 'chain is outside the reviewed LI.FI v1 route set');
+    }
+    const fromToken = normalizedAddress(input.fromToken);
+    const toToken = normalizedAddress(input.toToken);
+    const fromAmount = BigInt(input.fromAmount);
+    if (attributedFeeAmount(fromAmount, runtime.config.lifiFee) <= 0n) {
+        return refuse('UNSUPPORTED_LIFI_ROUTE', 'input amount is too small for the configured Otto fee');
+    }
+    const quote = await runtime.quoteClient.getSameChainSwapQuote({
+        chainId: input.chainId,
+        fromToken,
+        toToken,
+        fromAmount: input.fromAmount,
+        sender: profile.address,
+        receiver: profile.address,
+        maxSlippageBps: input.slippage.maxBps,
+    }, signal);
+    const asserted = decodeAndAssertLiFiSwap({
+        quote,
+        profile,
+        chainId: input.chainId,
+        fromToken,
+        toToken,
+        fromAmount,
+        maxSlippageBps: input.slippage.maxBps,
+        minAmountOut: input.slippage.minAmountOut ? BigInt(input.slippage.minAmountOut) : undefined,
+        config: runtime.config,
+    });
+    const capability = capabilityFor(profile);
+    const approvalCalldata = (amount) => encodeFunctionData({
+        abi: ERC20_APPROVE_ABI,
+        functionName: 'approve',
+        args: [asserted.approvalSpender, amount],
+    });
+    const payload = Object.freeze({
+        kind: 'evm_execution_plan',
+        chain_id: input.chainId,
+        steps: Object.freeze([
+            // Approval-race-guarded ERC20s (USDT and friends) revert on a non-zero to non-zero
+            // approve, so a plan that only raises the allowance is not executable from every
+            // reachable prior allowance state. Resetting to zero first is executable from all of
+            // them, needs no allowance read, and leaves the swap step unchanged.
+            Object.freeze({
+                to: fromToken,
+                value: '0',
+                data: approvalCalldata(0n),
+                kind: 'approve_reset',
+            }),
+            Object.freeze({
+                to: fromToken,
+                value: '0',
+                data: approvalCalldata(fromAmount),
+                kind: 'approve',
+            }),
+            Object.freeze({
+                to: asserted.transaction.to,
+                value: asserted.transaction.value,
+                data: asserted.transaction.data,
+                kind: 'call',
+            }),
+        ]),
+    });
+    const nowMs = runtime.nowMs();
+    const artifactId = createArtifactId(nowMs, runtime.entropy());
+    const payloadDigest = executionDigest(payload);
+    const uncommitted = {
+        schema_version: '1',
+        artifact_id: artifactId,
+        rail: 'lifi',
+        operation: 'swap',
+        intent_digest: executionDigest(normalizedIntent(input, profile)),
+        account_binding: accountBinding(profile),
+        required_capabilities: [capability],
+        payload,
+        fee_attribution: {
+            mechanism: 'lifi_integrator_fee',
+            config_version: runtime.config.lifiFeeConfigVersion,
+        },
+        replay_disclosure: {
+            artifact_role: 'construction_aid',
+            freshness_boundary: 'valid_until',
+            onchain_replay_boundary: 'signer_account_nonce',
+            tool_guarantees_single_execution: false,
+        },
+        assertions: [
+            ...asserted.assertions,
+            { id: 'payload_digest_committed', result: 'passed' },
+            { id: 'erc20_allowance_reset_ordered', result: 'passed' },
+            { id: 'artifact_expiry_committed', result: 'passed' },
+        ],
+        valid_until: new Date(nowMs + runtime.config.artifactTtlMs).toISOString(),
+        submission: {
+            method: capability,
+            chain_id: input.chainId,
+            artifact_id: artifactId,
+            payload_digest: payloadDigest,
+            adapter_owned_fields: ['nonce', 'gas', 'serialization'],
+            ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+        },
+    };
+    const envelope = {
+        ...uncommitted,
+        submission: {
+            ...uncommitted.submission,
+            artifact_digest: artifactCommitmentDigest(uncommitted),
+        },
+    };
+    const parsed = EXECUTION_ENVELOPE_SCHEMA.parse(envelope);
+    // Bind the artifact — id AND whole-envelope commitment — to THIS process for the delegated tool: it submits
+    // only what this process prepared. At capacity the prepare is refused; nothing issued is ever dropped.
+    if (runtime.delegation) {
+        recordPreparedArtifact(runtime.delegation, artifactId, parsed.submission.artifact_digest, nowMs + runtime.config.artifactTtlMs, nowMs);
+    }
+    return parsed;
+}
+/**
+ * Build the ordered source-chain plan for a cross-chain native-USDC bridge over the enumerated v1
+ * Circle-CCTP route set. Prepare-only: the plan is handed to the caller's own custody to sign.
+ */
+export async function prepareBridge(runtime, rawInput, signal) {
+    const input = PREPARE_BRIDGE_INPUT_SCHEMA.parse(rawInput);
+    const profile = {
+        kind: input.accountProfile.kind,
+        address: normalizedAddress(input.accountProfile.address),
+        chainId: input.accountProfile.chainId,
+    };
+    if (profile.chainId !== input.fromChainId) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', 'account profile chain does not match the bridge source chain');
+    }
+    // An EOA is the same account on every EVM chain, so its own address is a safe default
+    // destination. A Safe is not, which is why the schema requires the caller to declare one.
+    const destinationRecipient = input.destinationRecipient
+        ? normalizedAddress(input.destinationRecipient)
+        : profile.address;
+    const fromToken = normalizedAddress(input.fromToken);
+    const toToken = normalizedAddress(input.toToken);
+    const fromAmount = BigInt(input.fromAmount);
+    if (!isEnumeratedCctpBridgeRoute(input.fromChainId, input.toChainId, fromToken, toToken)) {
+        return refuse('UNSUPPORTED_LIFI_ROUTE', `route ${input.fromChainId}:${fromToken} -> ${input.toChainId}:${toToken} is outside the enumerated v1 PolymerCCTP USDC route set`);
+    }
+    if (attributedFeeAmount(fromAmount, runtime.config.lifiFee) <= 0n) {
+        return refuse('UNSUPPORTED_LIFI_ROUTE', 'input amount is too small for the configured Otto fee');
+    }
+    const quote = await runtime.quoteClient.getCrossChainBridgeQuote({
+        fromChainId: input.fromChainId,
+        toChainId: input.toChainId,
+        fromToken,
+        toToken,
+        fromAmount: input.fromAmount,
+        sender: profile.address,
+        receiver: destinationRecipient,
+        maxSlippageBps: input.slippage.maxBps,
+    }, signal);
+    const asserted = decodeAndAssertLiFiBridge({
+        quote,
+        profile,
+        fromChainId: input.fromChainId,
+        toChainId: input.toChainId,
+        fromToken,
+        toToken,
+        fromAmount,
+        destinationRecipient,
+        maxSlippageBps: input.slippage.maxBps,
+        minAmountOut: input.slippage.minAmountOut ? BigInt(input.slippage.minAmountOut) : undefined,
+        config: runtime.config,
+    });
+    const capability = capabilityFor(profile);
+    const approvalCalldata = (amount) => encodeFunctionData({
+        abi: ERC20_APPROVE_ABI,
+        functionName: 'approve',
+        args: [asserted.approvalSpender, amount],
+    });
+    const payload = Object.freeze({
+        kind: 'evm_execution_plan',
+        chain_id: input.fromChainId,
+        steps: Object.freeze([
+            // Same allowance-reset ordering as the swap plan: it is what keeps the plan executable from
+            // every reachable prior allowance state, including approval-race-guarded ERC20s.
+            Object.freeze({
+                to: fromToken,
+                value: '0',
+                data: approvalCalldata(0n),
+                kind: 'approve_reset',
+            }),
+            Object.freeze({
+                to: fromToken,
+                value: '0',
+                data: approvalCalldata(fromAmount),
+                kind: 'approve',
+            }),
+            Object.freeze({
+                to: asserted.transaction.to,
+                value: asserted.transaction.value,
+                data: asserted.transaction.data,
+                kind: 'call',
+            }),
+        ]),
+    });
+    const nowMs = runtime.nowMs();
+    const artifactId = createArtifactId(nowMs, runtime.entropy());
+    const payloadDigest = executionDigest(payload);
+    const uncommitted = {
+        schema_version: '1',
+        artifact_id: artifactId,
+        rail: 'lifi',
+        operation: 'bridge',
+        intent_digest: executionDigest(normalizedBridgeIntent(input, profile, destinationRecipient)),
+        account_binding: bridgeAccountBinding(profile, {
+            destinationRecipient,
+            destinationChainId: input.toChainId,
+            sendingAsset: fromToken,
+            receivingAsset: toToken,
+        }),
+        required_capabilities: [capability],
+        payload,
+        fee_attribution: {
+            mechanism: 'lifi_integrator_fee',
+            config_version: runtime.config.lifiFeeConfigVersion,
+        },
+        replay_disclosure: {
+            artifact_role: 'construction_aid',
+            freshness_boundary: 'valid_until',
+            onchain_replay_boundary: 'signer_account_nonce',
+            tool_guarantees_single_execution: false,
+        },
+        assertions: [
+            ...asserted.assertions,
+            { id: 'payload_digest_committed', result: 'passed' },
+            { id: 'erc20_allowance_reset_ordered', result: 'passed' },
+            { id: 'artifact_expiry_committed', result: 'passed' },
+        ],
+        valid_until: new Date(nowMs + runtime.config.artifactTtlMs).toISOString(),
+        submission: {
+            // The source chain: the only chain any step in this plan is submitted to.
+            method: capability,
+            chain_id: input.fromChainId,
+            artifact_id: artifactId,
+            payload_digest: payloadDigest,
+            adapter_owned_fields: ['nonce', 'gas', 'serialization'],
+            ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+        },
+    };
+    const envelope = {
+        ...uncommitted,
+        submission: {
+            ...uncommitted.submission,
+            artifact_digest: artifactCommitmentDigest(uncommitted),
+        },
+    };
+    return BRIDGE_EXECUTION_ENVELOPE_SCHEMA.parse(envelope);
+}
+/**
+ * Build an unsigned Polymarket CTF Exchange V2 limit order for the caller's own Polygon EOA, with
+ * Otto's builder code inside the signed struct (spec §7.3). Prepare-only: the artifact carries order
+ * args and the EIP-712 payload; the caller's own signer signs it and the caller's own credentials
+ * post it. Nothing here holds a key, a CLOB credential, or the caller's collateral.
+ */
+export async function preparePolymarketOrder(runtime, rawInput, signal) {
+    const input = PREPARE_POLYMARKET_ORDER_INPUT_SCHEMA.parse(rawInput);
+    const profile = {
+        kind: input.accountProfile.kind,
+        address: normalizedAddress(input.accountProfile.address),
+        chainId: input.accountProfile.chainId,
+    };
+    if (profile.kind !== 'eoa') {
+        // A Safe maker needs a POLY_GNOSIS_SAFE-vs-POLY_1271 signature-type ruling that spec §13 still
+        // lists as open. Refused by name rather than guessed: the signature type is inside the signed
+        // order, so the wrong guess produces orders the exchange rejects or validates against the wrong
+        // owner.
+        return refuse('UNSUPPORTED_ACCOUNT_PROFILE', 'v1 supports the EOA profile only; the Safe signature type for Polymarket is an open ruling');
+    }
+    if (profile.chainId !== POLYMARKET_CHAIN_ID) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', `Polymarket orders are Polygon-only; the account profile declares chain ${profile.chainId}`);
+    }
+    const metadata = await runtime.clobClient.getMarketMetadata(input.tokenId, signal);
+    if (!metadata.acceptingOrders ||
+        !metadata.active ||
+        metadata.closed ||
+        !metadata.orderBookEnabled) {
+        return refuse('UNSUPPORTED_POLYMARKET_MARKET', `market ${metadata.conditionId} is not accepting orders (accepting_orders=${metadata.acceptingOrders}, active=${metadata.active}, closed=${metadata.closed}, order_book=${metadata.orderBookEnabled})`);
+    }
+    const { priceUnits } = assertPolymarketPriceOnTick(input.price, metadata.tickSize);
+    const sizeAtomic = polymarketAtomicUnits(input.size);
+    const minimumOrderSizeAtomic = polymarketAtomicUnits(String(metadata.minimumOrderSize));
+    const builderRates = await runtime.clobClient.getBuilderFeeRates(runtime.config.polymarketBuilderCode, signal);
+    const attributionAssertions = assertPolymarketBuilderAttributionRuled(builderRates, runtime.config);
+    const nowMs = runtime.nowMs();
+    const built = await runtime.polymarketOrderBuilder({
+        maker: profile.address,
+        tokenId: input.tokenId,
+        side: input.side,
+        price: Number(input.price),
+        size: Number(input.size),
+        tickSize: metadata.tickSize,
+        negRisk: metadata.negRisk,
+        builderCode: runtime.config.polymarketBuilderCode,
+    });
+    const asserted = decodeAndAssertPolymarketOrder({
+        built,
+        maker: profile.address,
+        tokenId: input.tokenId,
+        side: input.side,
+        priceUnits,
+        sizeAtomic,
+        tickSize: metadata.tickSize,
+        negRisk: metadata.negRisk,
+        minimumOrderSizeAtomic,
+        config: runtime.config,
+        nowMs,
+    });
+    const payload = Object.freeze({
+        kind: 'polymarket_order_v2',
+        chain_id: POLYMARKET_CHAIN_ID,
+        exchange: asserted.exchange,
+        neg_risk: metadata.negRisk,
+        tick_size: metadata.tickSize,
+        order_type: 'GTC',
+        order: Object.freeze(asserted.order),
+        eip712: asserted.typedData,
+        order_hash: asserted.orderHash,
+    });
+    const artifactId = createArtifactId(nowMs, runtime.entropy());
+    const payloadDigest = executionDigest(payload);
+    const assertions = [
+        ...attributionAssertions,
+        ...asserted.assertions,
+        { id: 'payload_digest_committed', result: 'passed' },
+        { id: 'artifact_expiry_committed', result: 'passed' },
+    ];
+    const uncommitted = {
+        schema_version: '1',
+        artifact_id: artifactId,
+        rail: 'polymarket',
+        operation: 'pm_order',
+        intent_digest: executionDigest(normalizedPolymarketIntent(input, profile)),
+        account_binding: polymarketAccountBinding(profile, {
+            exchange: asserted.exchange,
+            tokenId: input.tokenId,
+        }),
+        required_capabilities: ['sign_eip712'],
+        payload,
+        fee_attribution: {
+            mechanism: 'polymarket_builder_code',
+            config_version: runtime.config.polymarketBuilderFeeConfigVersion,
+        },
+        replay_disclosure: {
+            artifact_role: 'construction_aid',
+            freshness_boundary: 'valid_until',
+            onchain_replay_boundary: 'exchange_order_hash',
+            tool_guarantees_single_execution: false,
+        },
+        assertions,
+        valid_until: new Date(nowMs + runtime.config.artifactTtlMs).toISOString(),
+        submission: {
+            method: 'sign_eip712',
+            chain_id: POLYMARKET_CHAIN_ID,
+            artifact_id: artifactId,
+            payload_digest: payloadDigest,
+            adapter_owned_fields: ['signature', 'clob_post'],
+            ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+        },
+    };
+    const envelope = {
+        ...uncommitted,
+        submission: {
+            ...uncommitted.submission,
+            artifact_digest: artifactCommitmentDigest(uncommitted),
+        },
+    };
+    return POLYMARKET_EXECUTION_ENVELOPE_SCHEMA.parse(envelope);
+}
+/**
+ * Build an unsigned Hyperliquid perp order L1 action for the caller's own Hyperliquid account, with
+ * optional reduce-only take-profit and stop-loss triggers bundled under `normalTpsl` (spec §7.2).
+ *
+ * Prepare-only, and structurally so: nothing on this path can sign or submit. The artifact carries the
+ * canonical action plus the declared EIP-712 Agent domain, struct, and `connectionId` recipe; the
+ * caller's own signer picks the nonce, computes the digest, and signs. The root-secret-derived agent
+ * wallet the trade-execution agent uses (`hyperliquid-client.ts:558`) is fenced out entirely (§11), and
+ * the builder attribution field is spec'd and VALUELESS until the Step-0 `approveBuilderFee` reversal
+ * lands (§7.2), so the action carries no builder key and the envelope declares that pending state.
+ */
+export async function preparePerpOrder(runtime, rawInput, signal) {
+    const input = PREPARE_PERP_ORDER_INPUT_SCHEMA.parse(rawInput);
+    const profile = {
+        kind: input.accountProfile.kind,
+        address: normalizedAddress(input.accountProfile.address),
+        chainId: input.accountProfile.chainId,
+    };
+    if (profile.kind !== 'eoa') {
+        // Hyperliquid recovers an L1 action's signer with ecrecover and does not accept ERC-1271, so a
+        // Safe cannot sign one at all — and a Safe master cannot even approve an API wallet to sign for
+        // it. Refused by name rather than constructed into an artifact no signer could ever satisfy.
+        return refuse('UNSUPPORTED_ACCOUNT_PROFILE', 'Hyperliquid recovers the L1 action signer with ecrecover; a Safe cannot produce an accepted signature, so v1 supports the EOA profile only');
+    }
+    const tradingSigner = input.tradingSigner
+        ? normalizedAddress(input.tradingSigner)
+        : profile.address;
+    const vaultAddress = input.vaultAddress ? normalizedAddress(input.vaultAddress) : undefined;
+    const asset = await runtime.hyperliquidInfoClient.getPerpAsset(input.asset, signal);
+    if (asset.isDelisted) {
+        return refuse('UNSUPPORTED_HYPERLIQUID_MARKET', `perp ${asset.name} is delisted on Hyperliquid; it still occupies its universe index but no longer trades`);
+    }
+    // Grid checks, not rounding: an off-grid price or size is refused by name so the caller never signs
+    // an order at a price they did not ask for.
+    assertHyperliquidPriceOnGrid(input.limitPrice, asset.szDecimals);
+    assertHyperliquidSizeOnGrid(input.size, asset.szDecimals);
+    if (input.takeProfitPrice)
+        assertHyperliquidPriceOnGrid(input.takeProfitPrice, asset.szDecimals);
+    if (input.stopLossPrice)
+        assertHyperliquidPriceOnGrid(input.stopLossPrice, asset.szDecimals);
+    assertHyperliquidBracketCoherent({
+        isBuy: input.side === 'BUY',
+        price: input.limitPrice,
+        takeProfitPrice: input.takeProfitPrice,
+        stopLossPrice: input.stopLossPrice,
+        szDecimals: asset.szDecimals,
+    });
+    const isBuy = input.side === 'BUY';
+    // ONE DISTINCT CLIENT ID PER LEG, minted before construction. This is what lets the caller read the
+    // venue's per-leg verdict by identity instead of by position in the response array — the correlation
+    // failure `hyperliquid-client.ts:1801` documents.
+    const legs = [
+        {
+            role: 'entry',
+            isBuy,
+            price: input.limitPrice,
+            size: input.size,
+            reduceOnly: input.reduceOnly,
+            tif: input.timeInForce,
+            clientOrderId: mintClientOrderId(runtime.clientOrderIdEntropy),
+        },
+    ];
+    // Triggers close the entry, so they sit on the opposite side, reduce-only, at their own trigger
+    // price, sized to the entry (`hyperliquid-client.ts:1825-1870`).
+    if (input.takeProfitPrice) {
+        legs.push({
+            role: 'take_profit',
+            isBuy: !isBuy,
+            price: input.takeProfitPrice,
+            size: input.size,
+            reduceOnly: true,
+            trigger: { triggerPx: input.takeProfitPrice, tpsl: 'tp' },
+            clientOrderId: mintClientOrderId(runtime.clientOrderIdEntropy),
+        });
+    }
+    if (input.stopLossPrice) {
+        legs.push({
+            role: 'stop_loss',
+            isBuy: !isBuy,
+            price: input.stopLossPrice,
+            size: input.size,
+            reduceOnly: true,
+            trigger: { triggerPx: input.stopLossPrice, tpsl: 'sl' },
+            clientOrderId: mintClientOrderId(runtime.clientOrderIdEntropy),
+        });
+    }
+    const grouping = legs.length > 1 ? 'normalTpsl' : 'na';
+    const built = runtime.hyperliquidActionBuilder({
+        grouping,
+        legs: legs.map((leg) => ({
+            assetId: asset.assetId,
+            isBuy: leg.isBuy,
+            price: leg.price,
+            size: leg.size,
+            reduceOnly: leg.reduceOnly,
+            orderType: leg.trigger
+                ? { trigger: { isMarket: true, triggerPx: leg.trigger.triggerPx, tpsl: leg.trigger.tpsl } }
+                : { limit: { tif: leg.tif ?? input.timeInForce } },
+            clientOrderId: leg.clientOrderId,
+        })),
+    });
+    const asserted = decodeAndAssertHyperliquidAction({ built, asset, grouping, legs });
+    const nowMs = runtime.nowMs();
+    const validUntilMs = nowMs + runtime.config.artifactTtlMs;
+    const payload = Object.freeze({
+        kind: 'hyperliquid_l1_action',
+        chain_id: HYPERLIQUID_L1_SIGNATURE_CHAIN_ID,
+        action: asserted.action,
+        signing: hyperliquidSigningDeclaration(),
+        vault_address: vaultAddress ?? null,
+        // The one freshness control the constructor owns (§10), placed where the venue enforces it: inside
+        // the signed digest. The venue rejects the action after this instant, which makes `valid_until` a
+        // venue-side bound on this rail rather than an advisory one.
+        expires_after: validUntilMs,
+    });
+    const artifactId = createArtifactId(nowMs, runtime.entropy());
+    const payloadDigest = executionDigest(payload);
+    const assertions = [
+        ...asserted.assertions,
+        { id: 'hyperliquid_bracket_directionally_coherent', result: 'passed' },
+        { id: 'hyperliquid_signing_domain_pinned', result: 'passed' },
+        { id: 'hyperliquid_agent_struct_pinned', result: 'passed' },
+        { id: 'hyperliquid_expires_after_matches_valid_until', result: 'passed' },
+        { id: 'payload_digest_committed', result: 'passed' },
+        { id: 'artifact_expiry_committed', result: 'passed' },
+    ];
+    const uncommitted = {
+        schema_version: '1',
+        artifact_id: artifactId,
+        rail: 'hyperliquid',
+        operation: 'perp_order',
+        intent_digest: executionDigest(normalizedPerpIntent(input, profile, tradingSigner, vaultAddress)),
+        account_binding: hyperliquidAccountBinding(profile, {
+            tradingSigner,
+            vaultAddress,
+            asset: asset.name,
+            assetId: asset.assetId,
+            szDecimals: asset.szDecimals,
+        }),
+        required_capabilities: ['sign_hyperliquid_l1'],
+        payload,
+        fee_attribution: {
+            mechanism: 'hyperliquid_builder_fee',
+            config_version: runtime.config.hyperliquidBuilderFeeConfigVersion,
+            status: HL_BUILDER_ATTRIBUTION_STATUS,
+        },
+        replay_disclosure: {
+            artifact_role: 'construction_aid',
+            freshness_boundary: 'valid_until',
+            onchain_replay_boundary: 'signer_nonce_and_expires_after',
+            tool_guarantees_single_execution: false,
+        },
+        assertions,
+        valid_until: new Date(validUntilMs).toISOString(),
+        submission: {
+            method: 'sign_hyperliquid_l1',
+            chain_id: HYPERLIQUID_L1_SIGNATURE_CHAIN_ID,
+            artifact_id: artifactId,
+            payload_digest: payloadDigest,
+            adapter_owned_fields: ['nonce', 'signature', 'exchange_post'],
+            ...(input.client_ref ? { client_ref: input.client_ref } : {}),
+        },
+    };
+    const envelope = {
+        ...uncommitted,
+        submission: {
+            ...uncommitted.submission,
+            artifact_digest: artifactCommitmentDigest(uncommitted),
+        },
+    };
+    return HYPERLIQUID_EXECUTION_ENVELOPE_SCHEMA.parse(envelope);
+}
+//# sourceMappingURL=execution-tools.js.map