otto-intel-mcp 0.1.0

package/dist/execution-types.d.ts

@@ -0,0 +1,274 @@
+import { type Address, type Hex } from 'viem';
+import { type HyperliquidOrderAction, type HyperliquidSigningDeclaration, type PolymarketOrderArgs, type PolymarketOrderTypedData } from './execution-tool-definitions.js';
+export { MAX_ARTIFACT_TTL_MS, artifactIdTimestampMs, createArtifactId } from './artifact-id.js';
+export type AccountKind = 'eoa' | 'safe';
+export type SigningCapability = 'send_evm_transaction' | 'submit_evm_batch' | 'sign_eip712' | 'sign_hyperliquid_l1';
+export interface AccountProfile {
+    readonly kind: AccountKind;
+    readonly address: Address;
+    readonly chainId: number;
+}
+export interface AccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly lifi: {
+            readonly sender: Address;
+            readonly receiver: Address;
+        };
+    };
+}
+export interface EvmExecutionStep {
+    readonly to: Address;
+    readonly value: string;
+    readonly data: Hex;
+    readonly kind: 'approve_reset' | 'approve' | 'call';
+}
+export interface EvmExecutionPlan {
+    readonly kind: 'evm_execution_plan';
+    readonly chain_id: number;
+    readonly steps: readonly EvmExecutionStep[];
+}
+/** The EVM-plan payload variant, shared by the swap and bridge rails. */
+export type ExecutionPayload = EvmExecutionPlan;
+/**
+ * The Polymarket payload variant: order args pre-signing plus the exact EIP-712 payload and digest
+ * the caller's own signer will sign. No signature, no CLOB credential, no collateral movement.
+ */
+export interface PolymarketOrderPayload {
+    readonly kind: 'polymarket_order_v2';
+    readonly chain_id: number;
+    readonly exchange: Address;
+    readonly neg_risk: boolean;
+    readonly tick_size: string;
+    readonly order_type: 'GTC';
+    readonly order: PolymarketOrderArgs;
+    readonly eip712: PolymarketOrderTypedData;
+    readonly order_hash: Hex;
+}
+export interface ExecutionAssertion {
+    readonly id: string;
+    readonly result: 'passed';
+}
+export interface ExecutionSubmission {
+    readonly method: SigningCapability;
+    readonly chain_id: number;
+    readonly artifact_id: string;
+    readonly payload_digest: Hex;
+    /** Commitment over every envelope field except itself, including valid_until. */
+    readonly artifact_digest: Hex;
+    readonly adapter_owned_fields: readonly ['nonce', 'gas', 'serialization'];
+    readonly client_ref?: string;
+}
+export interface ExecutionEnvelope {
+    readonly schema_version: '1';
+    readonly artifact_id: string;
+    readonly rail: 'lifi';
+    readonly operation: 'swap';
+    readonly intent_digest: Hex;
+    readonly account_binding: AccountBinding;
+    readonly required_capabilities: readonly SigningCapability[];
+    readonly payload: ExecutionPayload;
+    readonly fee_attribution: {
+        readonly mechanism: 'lifi_integrator_fee';
+        readonly config_version: string;
+    };
+    readonly replay_disclosure: {
+        readonly artifact_role: 'construction_aid';
+        readonly freshness_boundary: 'valid_until';
+        readonly onchain_replay_boundary: 'signer_account_nonce';
+        readonly tool_guarantees_single_execution: false;
+    };
+    readonly assertions: readonly ExecutionAssertion[];
+    readonly valid_until: string;
+    readonly submission: ExecutionSubmission;
+}
+export interface BridgeAccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly lifi: {
+            readonly sender: Address;
+            /** Where the destination chain mints. For a Safe this is caller-declared, never derived. */
+            readonly receiver: Address;
+            readonly source_chain_id: number;
+            readonly destination_chain_id: number;
+            readonly sending_asset: Address;
+            readonly receiving_asset: Address;
+        };
+    };
+}
+export interface BridgeExecutionEnvelope extends Omit<ExecutionEnvelope, 'operation' | 'account_binding'> {
+    readonly operation: 'bridge';
+    readonly account_binding: BridgeAccountBinding;
+}
+export interface PolymarketAccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly polymarket: {
+            /** Source of funds for the order; inside the signed struct (spec §4). */
+            readonly maker: Address;
+            /** Who signs the EIP-712 order; inside the signed struct. */
+            readonly signer: Address;
+            /** Who holds the collateral. For the v1 EOA profile all three are the same account. */
+            readonly funder: Address;
+            readonly exchange: Address;
+            readonly token_id: string;
+            readonly signature_type: 0;
+        };
+    };
+}
+export interface PolymarketExecutionSubmission {
+    readonly method: 'sign_eip712';
+    readonly chain_id: number;
+    readonly artifact_id: string;
+    readonly payload_digest: Hex;
+    readonly artifact_digest: Hex;
+    readonly adapter_owned_fields: readonly ['signature', 'clob_post'];
+    readonly client_ref?: string;
+}
+export interface PolymarketExecutionEnvelope extends Omit<ExecutionEnvelope, 'rail' | 'operation' | 'account_binding' | 'payload' | 'fee_attribution' | 'replay_disclosure' | 'required_capabilities' | 'submission'> {
+    readonly rail: 'polymarket';
+    readonly operation: 'pm_order';
+    readonly account_binding: PolymarketAccountBinding;
+    readonly required_capabilities: readonly ['sign_eip712'];
+    readonly payload: PolymarketOrderPayload;
+    readonly fee_attribution: {
+        readonly mechanism: 'polymarket_builder_code';
+        readonly config_version: string;
+    };
+    readonly replay_disclosure: {
+        readonly artifact_role: 'construction_aid';
+        readonly freshness_boundary: 'valid_until';
+        /** An order struct carries its own salt, so the exchange's order hash is the replay boundary. */
+        readonly onchain_replay_boundary: 'exchange_order_hash';
+        readonly tool_guarantees_single_execution: false;
+    };
+    readonly submission: PolymarketExecutionSubmission;
+}
+/**
+ * The Hyperliquid payload variant: the canonical L1 order action plus the declared EIP-712 signing
+ * fields the caller's own signer needs. No nonce, no signature, no derived agent wallet.
+ */
+export interface HyperliquidL1ActionPayload {
+    readonly kind: 'hyperliquid_l1_action';
+    readonly chain_id: 1337;
+    readonly action: HyperliquidOrderAction;
+    readonly signing: HyperliquidSigningDeclaration;
+    readonly vault_address: Address | null;
+    /** Constructor-owned expiry in unix ms, equal to `valid_until` and inside the signed digest. */
+    readonly expires_after: number;
+}
+export interface HyperliquidAccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly hyperliquid: {
+            readonly master: Address;
+            readonly trading_signer: Address;
+            readonly vault_address: Address | null;
+            readonly asset: string;
+            readonly asset_id: number;
+            readonly sz_decimals: number;
+        };
+    };
+}
+export interface HyperliquidExecutionSubmission {
+    readonly method: 'sign_hyperliquid_l1';
+    readonly chain_id: 1337;
+    readonly artifact_id: string;
+    readonly payload_digest: Hex;
+    readonly artifact_digest: Hex;
+    readonly adapter_owned_fields: readonly ['nonce', 'signature', 'exchange_post'];
+    readonly client_ref?: string;
+}
+export interface HyperliquidExecutionEnvelope extends Omit<ExecutionEnvelope, 'rail' | 'operation' | 'account_binding' | 'payload' | 'fee_attribution' | 'replay_disclosure' | 'required_capabilities' | 'submission'> {
+    readonly rail: 'hyperliquid';
+    readonly operation: 'perp_order';
+    readonly account_binding: HyperliquidAccountBinding;
+    readonly required_capabilities: readonly ['sign_hyperliquid_l1'];
+    readonly payload: HyperliquidL1ActionPayload;
+    readonly fee_attribution: {
+        readonly mechanism: 'hyperliquid_builder_fee';
+        readonly config_version: string;
+        /** Ruled pending state; the `{b, f}` assert lands with the Step-0 reversal (spec §7.2). */
+        readonly status: 'pending_step0_builder_fee_approval';
+    };
+    readonly replay_disclosure: {
+        readonly artifact_role: 'construction_aid';
+        readonly freshness_boundary: 'valid_until';
+        /** HL's signed digest covers an adapter-chosen nonce AND the constructor's expiresAfter. */
+        readonly onchain_replay_boundary: 'signer_nonce_and_expires_after';
+        readonly tool_guarantees_single_execution: false;
+    };
+    readonly submission: HyperliquidExecutionSubmission;
+}
+/** Any artifact this MCP produces. Discriminated by `operation`. */
+export type ExecutionArtifact = ExecutionEnvelope | BridgeExecutionEnvelope | PolymarketExecutionEnvelope | HyperliquidExecutionEnvelope;
+/** Envelope shape before the self-referential artifact digest is stamped into submission. */
+export type UncommittedExecutionEnvelope = Omit<ExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<ExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Bridge envelope before the self-referential artifact digest is stamped into submission. */
+export type UncommittedBridgeExecutionEnvelope = Omit<BridgeExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<ExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Polymarket envelope before the self-referential artifact digest is stamped into submission. */
+export type UncommittedPolymarketExecutionEnvelope = Omit<PolymarketExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<PolymarketExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Hyperliquid envelope before the self-referential artifact digest is stamped into submission. */
+export type UncommittedHyperliquidExecutionEnvelope = Omit<HyperliquidExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<HyperliquidExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Any envelope shape awaiting its whole-envelope commitment. */
+export type UncommittedExecutionArtifact = UncommittedExecutionEnvelope | UncommittedBridgeExecutionEnvelope | UncommittedPolymarketExecutionEnvelope | UncommittedHyperliquidExecutionEnvelope;
+export declare function canonicalJson(value: unknown): string;
+export declare function executionDigest(value: unknown): Hex;
+export declare function accountBinding(profile: AccountProfile): AccountBinding;
+export declare function bridgeAccountBinding(profile: AccountProfile, route: {
+    readonly destinationRecipient: Address;
+    readonly destinationChainId: number;
+    readonly sendingAsset: Address;
+    readonly receivingAsset: Address;
+}): BridgeAccountBinding;
+/**
+ * The v1 Polymarket profile is a single EOA in all three roles: it signs the order, it is the maker
+ * of record inside the signed struct, and it funds the collateral. A Safe profile would need a
+ * signature type (POLY_GNOSIS_SAFE vs POLY_1271) that spec §13 leaves open, so it is refused rather
+ * than guessed — which is why this factory takes no separate signer or funder.
+ */
+export declare function polymarketAccountBinding(profile: AccountProfile, order: {
+    readonly exchange: Address;
+    readonly tokenId: string;
+}): PolymarketAccountBinding;
+/**
+ * The v1 Hyperliquid profile binds the master account to the signing EOA. `tradingSigner` may be a
+ * DIFFERENT address — the user's own approved API wallet — and is taken as a declared fact: Otto never
+ * derives an agent key, which is the custody line spec §11 draws around
+ * `trade-execution-agent/src/lib/hyperliquid-client.ts:558`. The vault address is likewise declared,
+ * never inferred from the account.
+ */
+export declare function hyperliquidAccountBinding(profile: AccountProfile, market: {
+    readonly tradingSigner?: Address;
+    readonly vaultAddress?: Address;
+    readonly asset: string;
+    readonly assetId: number;
+    readonly szDecimals: number;
+}): HyperliquidAccountBinding;
+export declare function assertArtifactAccountBinding(artifact: ExecutionArtifact, expected: AccountProfile): void;
+export declare function assertArtifactPayloadDigest(artifact: ExecutionArtifact): void;
+/**
+ * Commitment over the whole envelope except the commitment field itself. `valid_until` sits
+ * inside it, so freshness is bound to the artifact rather than being an editable side field.
+ */
+export declare function artifactCommitmentDigest(artifact: UncommittedExecutionArtifact): Hex;
+/**
+ * Fail-closed commitment check: payload digest, whole-envelope commitment, and the
+ * constructor-owned freshness bound derived from the artifact id.
+ */
+export declare function assertArtifactCommitment(artifact: ExecutionArtifact): void;
+/** Strict adapter-side validation, including every envelope cross-field relationship. */
+export declare function assertArtifactEnvelope(artifact: unknown): ExecutionArtifact;
+export declare function assertArtifactFresh(artifact: ExecutionArtifact, nowMs?: number): void;

package/dist/execution-types.js

@@ -0,0 +1,157 @@
+import { getAddress, keccak256, stringToHex } from 'viem';
+import { isArtifactFreshnessWellFormed } from './artifact-id.js';
+import { refuse } from './execution-errors.js';
+import { EXECUTION_ARTIFACT_SCHEMA, } from './execution-tool-definitions.js';
+export { MAX_ARTIFACT_TTL_MS, artifactIdTimestampMs, createArtifactId } from './artifact-id.js';
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => canonicalize(item));
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort()) {
+        if (source[key] !== undefined)
+            sorted[key] = canonicalize(source[key]);
+    }
+    return sorted;
+}
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function executionDigest(value) {
+    return keccak256(stringToHex(canonicalJson(value)));
+}
+export function accountBinding(profile) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            lifi: Object.freeze({ sender: address, receiver: address }),
+        }),
+    });
+}
+export function bridgeAccountBinding(profile, route) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            lifi: Object.freeze({
+                sender: address,
+                receiver: getAddress(route.destinationRecipient),
+                source_chain_id: profile.chainId,
+                destination_chain_id: route.destinationChainId,
+                sending_asset: getAddress(route.sendingAsset),
+                receiving_asset: getAddress(route.receivingAsset),
+            }),
+        }),
+    });
+}
+/**
+ * The v1 Polymarket profile is a single EOA in all three roles: it signs the order, it is the maker
+ * of record inside the signed struct, and it funds the collateral. A Safe profile would need a
+ * signature type (POLY_GNOSIS_SAFE vs POLY_1271) that spec §13 leaves open, so it is refused rather
+ * than guessed — which is why this factory takes no separate signer or funder.
+ */
+export function polymarketAccountBinding(profile, order) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            polymarket: Object.freeze({
+                maker: address,
+                signer: address,
+                funder: address,
+                exchange: getAddress(order.exchange),
+                token_id: order.tokenId,
+                signature_type: 0,
+            }),
+        }),
+    });
+}
+/**
+ * The v1 Hyperliquid profile binds the master account to the signing EOA. `tradingSigner` may be a
+ * DIFFERENT address — the user's own approved API wallet — and is taken as a declared fact: Otto never
+ * derives an agent key, which is the custody line spec §11 draws around
+ * `trade-execution-agent/src/lib/hyperliquid-client.ts:558`. The vault address is likewise declared,
+ * never inferred from the account.
+ */
+export function hyperliquidAccountBinding(profile, market) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            hyperliquid: Object.freeze({
+                master: address,
+                trading_signer: market.tradingSigner ? getAddress(market.tradingSigner) : address,
+                vault_address: market.vaultAddress ? getAddress(market.vaultAddress) : null,
+                asset: market.asset,
+                asset_id: market.assetId,
+                sz_decimals: market.szDecimals,
+            }),
+        }),
+    });
+}
+export function assertArtifactAccountBinding(artifact, expected) {
+    const actual = artifact.account_binding;
+    if (actual.kind !== expected.kind ||
+        actual.chainId !== expected.chainId ||
+        getAddress(actual.address) !== getAddress(expected.address)) {
+        refuse('ACCOUNT_BINDING_MISMATCH', 'execution artifact is bound to a different account');
+    }
+}
+export function assertArtifactPayloadDigest(artifact) {
+    if (artifact.submission.artifact_id !== artifact.artifact_id ||
+        executionDigest(artifact.payload) !== artifact.submission.payload_digest) {
+        refuse('DIGEST_MISMATCH', 'execution artifact payload digest does not match its payload');
+    }
+}
+/**
+ * Commitment over the whole envelope except the commitment field itself. `valid_until` sits
+ * inside it, so freshness is bound to the artifact rather than being an editable side field.
+ */
+export function artifactCommitmentDigest(artifact) {
+    const { submission, ...envelope } = artifact;
+    const { artifact_digest: _committed, ...committedSubmission } = submission;
+    return executionDigest({ ...envelope, submission: committedSubmission });
+}
+/**
+ * Fail-closed commitment check: payload digest, whole-envelope commitment, and the
+ * constructor-owned freshness bound derived from the artifact id.
+ */
+export function assertArtifactCommitment(artifact) {
+    assertArtifactPayloadDigest(artifact);
+    if (artifactCommitmentDigest(artifact) !== artifact.submission.artifact_digest) {
+        refuse('DIGEST_MISMATCH', 'execution artifact digest does not commit to this envelope');
+    }
+    if (!isArtifactFreshnessWellFormed(artifact.artifact_id, artifact.valid_until)) {
+        refuse('ARTIFACT_INVALID', 'execution artifact expiry is outside the constructor bound');
+    }
+}
+/** Strict adapter-side validation, including every envelope cross-field relationship. */
+export function assertArtifactEnvelope(artifact) {
+    const parsed = EXECUTION_ARTIFACT_SCHEMA.safeParse(artifact);
+    if (!parsed.success) {
+        return refuse('ARTIFACT_INVALID', 'execution artifact failed strict envelope validation');
+    }
+    const envelope = parsed.data;
+    assertArtifactCommitment(envelope);
+    return envelope;
+}
+export function assertArtifactFresh(artifact, nowMs = Date.now()) {
+    // Fail-closed first: the commitment check binds valid_until to the artifact and rejects any
+    // expiry outside the construction-anchored ceiling, so the deadline below is constructor-owned.
+    assertArtifactCommitment(artifact);
+    if (Date.parse(artifact.valid_until) <= nowMs) {
+        refuse('STALE_ARTIFACT', 'execution artifact has expired');
+    }
+}
+//# sourceMappingURL=execution-types.js.map

package/dist/hyperliquid-info-client.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { ExecutionServiceConfig, HyperliquidPerpAsset } from './execution-config.js';
+/** The live `POST /info {"type":"meta"}` body, as captured in `test/fixtures/hyperliquid-meta.json`. */
+export declare const HYPERLIQUID_META_RESPONSE_SCHEMA: z.ZodObject<{
+    universe: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        szDecimals: z.ZodNumber;
+        maxLeverage: z.ZodNumber;
+        isDelisted: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export interface HyperliquidInfoClient {
+    getPerpAsset(symbol: string, signal?: AbortSignal): Promise<HyperliquidPerpAsset>;
+}
+/**
+ * Resolve one perp symbol against a live `meta` body. Shared by the REST client and the recorded
+ * fixture loader, so the assertions in tests run over the same parse the network path uses.
+ *
+ * The symbol match is exact and case-sensitive against the venue's own `name`: the universe contains
+ * names that differ only by prefix conventions (`kPEPE` vs `PEPE`), and a case-folded match would let
+ * a caller's typo resolve to a different market than the one they named.
+ */
+export declare function hyperliquidPerpAsset(raw: unknown, symbol: string): HyperliquidPerpAsset;
+export declare function buildHyperliquidInfoUrl(config: Pick<ExecutionServiceConfig, 'hyperliquidApiBaseUrl'>): URL;
+export declare class RestHyperliquidInfoClient implements HyperliquidInfoClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: ExecutionServiceConfig, fetchImpl?: typeof fetch);
+    getPerpAsset(symbol: string, signal?: AbortSignal): Promise<HyperliquidPerpAsset>;
+    private postInfo;
+}

package/dist/hyperliquid-info-client.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { isExecutionRefusal, refuse } from './execution-errors.js';
+/**
+ * Public, unauthenticated Hyperliquid info reads only (spec §7.2). This client holds no key, derives
+ * no agent wallet, and never touches `/exchange`: the write surface, the root-secret-derived agent
+ * (`trade-execution-agent/src/lib/hyperliquid-client.ts:558`) and the Dynamic-vault lifecycle are
+ * fenced out of Step 1 by spec §11.
+ *
+ * One read is needed and only one: `{"type":"meta"}`, whose `universe` array is the authoritative
+ * source of the asset index (`a` in the order action), `szDecimals`, and the delisting flag. The
+ * index is POSITIONAL — asset id IS the array position — so it can only come from a live read.
+ */
+const PERP_UNIVERSE_ASSET_SCHEMA = z
+    .object({
+    name: z.string().min(1),
+    // 0 is a valid, common value (DOGE, XRP, kPEPE), so absence must not fall back to a truthy
+    // default: a wrong szDecimals silently changes both the size grid and the price grid.
+    szDecimals: z.number().int().min(0).max(18),
+    maxLeverage: z.number().int().positive(),
+    isDelisted: z.boolean().optional(),
+})
+    .passthrough();
+/** The live `POST /info {"type":"meta"}` body, as captured in `test/fixtures/hyperliquid-meta.json`. */
+export const HYPERLIQUID_META_RESPONSE_SCHEMA = z
+    .object({
+    universe: z.array(PERP_UNIVERSE_ASSET_SCHEMA).min(1),
+})
+    .passthrough();
+function metaRefuse(message) {
+    return refuse('HYPERLIQUID_META_INVALID', message);
+}
+/**
+ * Resolve one perp symbol against a live `meta` body. Shared by the REST client and the recorded
+ * fixture loader, so the assertions in tests run over the same parse the network path uses.
+ *
+ * The symbol match is exact and case-sensitive against the venue's own `name`: the universe contains
+ * names that differ only by prefix conventions (`kPEPE` vs `PEPE`), and a case-folded match would let
+ * a caller's typo resolve to a different market than the one they named.
+ */
+export function hyperliquidPerpAsset(raw, symbol) {
+    const parsed = HYPERLIQUID_META_RESPONSE_SCHEMA.safeParse(raw);
+    if (!parsed.success) {
+        metaRefuse('Hyperliquid perp meta is missing a well-formed universe');
+    }
+    const universe = parsed.data.universe;
+    const index = universe.findIndex((asset) => asset.name === symbol);
+    if (index < 0) {
+        refuse('UNSUPPORTED_HYPERLIQUID_MARKET', `perp ${symbol} is not in the live Hyperliquid perp universe`);
+    }
+    const asset = universe[index];
+    // Only native perps are in scope: a HIP-3 builder-deployed asset lives in a separate `perpDexs`
+    // universe whose asset ids are offset (100000 + dexIndex * 10000 + assetIndex), so a positional
+    // index taken from THIS universe would name a different market entirely.
+    return Object.freeze({
+        name: asset.name,
+        assetId: index,
+        szDecimals: asset.szDecimals,
+        maxLeverage: asset.maxLeverage,
+        isDelisted: asset.isDelisted === true,
+    });
+}
+export function buildHyperliquidInfoUrl(config) {
+    return new URL(`${config.hyperliquidApiBaseUrl}/info`);
+}
+function boundedSignal(callerSignal, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('Hyperliquid info read timeout')), timeoutMs);
+    const onAbort = () => controller.abort(callerSignal?.reason);
+    if (callerSignal?.aborted)
+        onAbort();
+    else
+        callerSignal?.addEventListener('abort', onAbort, { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            callerSignal?.removeEventListener('abort', onAbort);
+        },
+    };
+}
+export class RestHyperliquidInfoClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async getPerpAsset(symbol, signal) {
+        return hyperliquidPerpAsset(await this.postInfo({ type: 'meta' }, signal), symbol);
+    }
+    async postInfo(body, callerSignal) {
+        const abort = boundedSignal(callerSignal, this.config.hyperliquidTimeoutMs);
+        try {
+            // No credential header of any kind: `/info` is a public endpoint.
+            const response = await this.fetchImpl(buildHyperliquidInfoUrl(this.config), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify(body),
+                signal: abort.signal,
+            });
+            if (!response.ok) {
+                refuse('HYPERLIQUID_META_FAILED', `Hyperliquid info read failed with HTTP ${response.status}`);
+            }
+            try {
+                return await response.json();
+            }
+            catch {
+                refuse('HYPERLIQUID_META_FAILED', 'Hyperliquid info response was not valid JSON');
+            }
+        }
+        catch (error) {
+            if (isExecutionRefusal(error))
+                throw error;
+            refuse('HYPERLIQUID_META_FAILED', 'Hyperliquid info read failed');
+        }
+        finally {
+            abort.cleanup();
+        }
+    }
+}
+//# sourceMappingURL=hyperliquid-info-client.js.map

package/dist/hyperliquid-order-assertions.d.ts

@@ -0,0 +1,89 @@
+import { type HyperliquidOrderGrouping, type HyperliquidPerpAsset, type HyperliquidTimeInForce } from './execution-config.js';
+import type { HyperliquidOrderAction, HyperliquidSigningDeclaration } from './execution-tool-definitions.js';
+import type { ExecutionAssertion } from './execution-types.js';
+import type { UnsignedHyperliquidAction } from './hyperliquid-order-builder.js';
+export interface HyperliquidDecimal {
+    readonly raw: string;
+    readonly decimals: number;
+    readonly isInteger: boolean;
+    /** Digits from the first non-zero digit through the last; the venue's 5-sig-fig rule counts these. */
+    readonly significantDigits: number;
+}
+/**
+ * Parse an exact decimal string. The caller's string form is authoritative and is what lands in the
+ * signed action verbatim: no float ever touches a price or a size here.
+ *
+ * This is the deliberate divergence from the trade-execution agent, which formats prices through
+ * `parseFloat(price.toPrecision(5))` and `Math.floor(price * 10 ** d) / 10 ** d`
+ * (`hyperliquid-client.ts:55,1291`) and sizes through `size.toFixed(szDecimals)`. Those ROUND, and two
+ * of them round differently from each other. Rounding is acceptable when a caller's intent is "fill me
+ * around here" and the round trip is milliseconds; it is not acceptable in a prepare-only artifact the
+ * caller signs later, because the price they signed would not be the price they named. So the grid is
+ * extracted as a VALIDATION and an off-grid request is refused by name.
+ */
+export declare function hyperliquidDecimal(value: string): HyperliquidDecimal;
+/** Exact scaled integer for comparison. Refuses rather than truncating excess precision. */
+export declare function hyperliquidScaledUnits(value: string, decimals: number): bigint;
+/** Fractional digits the venue accepts in a perp price for this asset: `MAX_DECIMALS - szDecimals`. */
+export declare function hyperliquidMaxPriceDecimals(szDecimals: number): number;
+/**
+ * The venue's perp price grid: at most `MAX_DECIMALS - szDecimals` fractional digits AND at most 5
+ * significant digits, with integer prices always accepted regardless of significant figures.
+ */
+export declare function assertHyperliquidPriceOnGrid(price: string, szDecimals: number): HyperliquidDecimal;
+/** The venue's size grid: at most `szDecimals` fractional digits, strictly positive. */
+export declare function assertHyperliquidSizeOnGrid(size: string, szDecimals: number): HyperliquidDecimal;
+/**
+ * A take-profit below the entry on a long — or above it on a short — is not a take-profit: it is an
+ * instruction to close at a loss the moment the entry fills, and the same inversion on the stop-loss
+ * leg arms an immediate close. The venue accepts both, and the trade-execution agent does not check
+ * either (`hyperliquid-client.ts:1829,1851`). An inverted bracket is a defect in the REQUEST, so
+ * naming it is P0-clean (§7.0): a coherent bracket always constructs.
+ */
+export declare function assertHyperliquidBracketCoherent(input: {
+    readonly isBuy: boolean;
+    readonly price: string;
+    readonly takeProfitPrice?: string;
+    readonly stopLossPrice?: string;
+    readonly szDecimals: number;
+}): void;
+export interface HyperliquidLegExpectation {
+    readonly role: 'entry' | 'take_profit' | 'stop_loss';
+    readonly isBuy: boolean;
+    readonly price: string;
+    readonly size: string;
+    readonly reduceOnly: boolean;
+    readonly tif?: HyperliquidTimeInForce;
+    readonly trigger?: {
+        readonly triggerPx: string;
+        readonly tpsl: 'tp' | 'sl';
+    };
+    readonly clientOrderId: string;
+}
+export interface HyperliquidActionAssertionInput {
+    readonly built: UnsignedHyperliquidAction;
+    readonly asset: HyperliquidPerpAsset;
+    readonly grouping: HyperliquidOrderGrouping;
+    readonly legs: readonly HyperliquidLegExpectation[];
+}
+export interface AssertedHyperliquidAction {
+    readonly action: HyperliquidOrderAction;
+    readonly assertions: readonly ExecutionAssertion[];
+}
+/**
+ * Decode the normalizer's output back into a strictly typed action and assert every fund-critical
+ * field: the positional asset id, the exact price and size strings, the side, reduce-only, the trigger
+ * shape, the per-leg client order ids, the grouping, the canonical key order, and the ABSENCE of the
+ * builder key (the ruled valueless state, spec §7.2).
+ */
+export declare function decodeAndAssertHyperliquidAction(input: HyperliquidActionAssertionInput): AssertedHyperliquidAction;
+/**
+ * The signing declaration: exactly the domain, struct, primary type, and `source` the venue's own
+ * signer uses (`@nktkas/hyperliquid` signing/mod.js:170-189), plus the `connectionId` recipe.
+ *
+ * `connectionId` itself is NOT published, and cannot be: it is
+ * `keccak256(msgpack(action) ++ nonce ++ vault ++ expiresAfter)` and the nonce is adapter-owned
+ * (§6/§10). Pre-committing a nonce here is precisely what would turn a correct artifact into a stale
+ * or replayable one, so the artifact publishes the preimage layout and leaves the nonce to the signer.
+ */
+export declare function hyperliquidSigningDeclaration(): HyperliquidSigningDeclaration;