otto-intel-mcp 0.1.0

package/dist/polymarket-clob-client.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { isPolymarketTickSize, } from './execution-config.js';
+import { isExecutionRefusal, refuse } from './execution-errors.js';
+/**
+ * Public, unauthenticated CLOB reads only. This client holds no API credentials, derives none, and
+ * never posts an order: the L2-authenticated surface (`postOrder`, key derivation, the Dynamic vault
+ * lifecycle) is fenced out of Step 1 by spec §11.
+ */
+const POLYMARKET_TOKEN_SCHEMA = z
+    .object({
+    token_id: z.string().min(1),
+    outcome: z.string().optional(),
+})
+    .passthrough();
+/** The live `/markets/{condition_id}` body, as captured in `test/fixtures/polymarket-market-*.json`. */
+export const POLYMARKET_MARKET_RESPONSE_SCHEMA = z
+    .object({
+    condition_id: z.string().min(1),
+    // The live feed sends this as a JSON number (0.001); the SDK stringifies it before use.
+    minimum_tick_size: z.union([z.number(), z.string()]),
+    minimum_order_size: z.union([z.number(), z.string()]),
+    neg_risk: z.boolean().optional(),
+    accepting_orders: z.boolean(),
+    active: z.boolean(),
+    closed: z.boolean(),
+    archived: z.boolean().optional(),
+    enable_order_book: z.boolean(),
+    tokens: z.array(POLYMARKET_TOKEN_SCHEMA).min(1),
+})
+    .passthrough();
+export const POLYMARKET_TOKEN_MARKET_RESPONSE_SCHEMA = z
+    .object({
+    condition_id: z.string().min(1),
+})
+    .passthrough();
+/** The live `/fees/builder-fees/{code}` body: the value source for the ruled builder rates (§8). */
+export const POLYMARKET_BUILDER_FEES_RESPONSE_SCHEMA = z
+    .object({
+    code: z.string().min(1),
+    builder_maker_fee_rate_bps: z.number(),
+    builder_taker_fee_rate_bps: z.number(),
+    enabled: z.boolean(),
+})
+    .passthrough();
+function metadataRefuse(message) {
+    return refuse('POLYMARKET_METADATA_INVALID', message);
+}
+function decimalNumber(value, name) {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        metadataRefuse(`Polymarket market metadata has a non-positive ${name}`);
+    }
+    return parsed;
+}
+/**
+ * Map a live market body onto the metadata the constructor needs, refusing every shape the
+ * constructor cannot act on. Shared by the REST client and the recorded-fixture loader, so the
+ * assertions in tests run over the same parse the network path uses.
+ */
+export function polymarketMarketMetadata(raw, tokenId) {
+    const parsed = POLYMARKET_MARKET_RESPONSE_SCHEMA.safeParse(raw);
+    if (!parsed.success) {
+        metadataRefuse('Polymarket market metadata is missing required fields');
+    }
+    const market = parsed.data;
+    if (!market.tokens.some((token) => token.token_id === tokenId)) {
+        // A token id that is not in the market it resolved to means the two reads disagree; building an
+        // order against either half would bind the user to a market they did not name.
+        metadataRefuse('Polymarket market metadata does not contain the requested token id');
+    }
+    const tickSize = String(decimalNumber(market.minimum_tick_size, 'minimum tick size'));
+    if (!isPolymarketTickSize(tickSize)) {
+        refuse('UNSUPPORTED_POLYMARKET_MARKET', `market tick size ${tickSize} is outside the supported set (0.1, 0.01, 0.001, 0.0001)`);
+    }
+    return Object.freeze({
+        tokenId,
+        conditionId: market.condition_id,
+        tickSize,
+        minimumOrderSize: decimalNumber(market.minimum_order_size, 'minimum order size'),
+        negRisk: market.neg_risk === true,
+        acceptingOrders: market.accepting_orders,
+        active: market.active,
+        closed: market.closed,
+        orderBookEnabled: market.enable_order_book,
+    });
+}
+/**
+ * The live builder-registry row for exactly the expected code. A row for a different code is
+ * refused rather than trusted: the whole point of the read is to bind Otto's own attribution.
+ */
+export function polymarketBuilderFeeRates(raw, expectedCode) {
+    const parsed = POLYMARKET_BUILDER_FEES_RESPONSE_SCHEMA.safeParse(raw);
+    if (!parsed.success) {
+        metadataRefuse('Polymarket builder-fee response is missing required fields');
+    }
+    const rates = parsed.data;
+    if (rates.code.toLowerCase() !== expectedCode.toLowerCase()) {
+        metadataRefuse('Polymarket builder-fee response describes a different builder code');
+    }
+    for (const [name, value] of [
+        ['maker', rates.builder_maker_fee_rate_bps],
+        ['taker', rates.builder_taker_fee_rate_bps],
+    ]) {
+        if (!Number.isInteger(value) || value < 0 || value > 10_000) {
+            metadataRefuse(`Polymarket builder-fee response has an out-of-range ${name} rate`);
+        }
+    }
+    return Object.freeze({
+        code: rates.code.toLowerCase(),
+        makerBps: rates.builder_maker_fee_rate_bps,
+        takerBps: rates.builder_taker_fee_rate_bps,
+        enabled: rates.enabled,
+    });
+}
+export function buildPolymarketMarketByTokenUrl(tokenId, config) {
+    return new URL(`${config.polymarketClobBaseUrl}/markets-by-token/${encodeURIComponent(tokenId)}`);
+}
+export function buildPolymarketMarketUrl(conditionId, config) {
+    return new URL(`${config.polymarketClobBaseUrl}/markets/${encodeURIComponent(conditionId)}`);
+}
+export function buildPolymarketBuilderFeesUrl(builderCode, config) {
+    return new URL(`${config.polymarketClobBaseUrl}/fees/builder-fees/${encodeURIComponent(builderCode)}`);
+}
+function boundedSignal(callerSignal, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('Polymarket CLOB 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 RestPolymarketClobClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async getMarketMetadata(tokenId, signal) {
+        const byToken = POLYMARKET_TOKEN_MARKET_RESPONSE_SCHEMA.safeParse(await this.getJson(buildPolymarketMarketByTokenUrl(tokenId, this.config), signal));
+        if (!byToken.success) {
+            metadataRefuse('Polymarket token lookup did not return a condition id');
+        }
+        return polymarketMarketMetadata(await this.getJson(buildPolymarketMarketUrl(byToken.data.condition_id, this.config), signal), tokenId);
+    }
+    async getBuilderFeeRates(builderCode, signal) {
+        return polymarketBuilderFeeRates(await this.getJson(buildPolymarketBuilderFeesUrl(builderCode, this.config), signal), builderCode);
+    }
+    async getJson(requestUrl, callerSignal) {
+        const abort = boundedSignal(callerSignal, this.config.polymarketTimeoutMs);
+        try {
+            // No credential header of any kind: every read here is on a public endpoint.
+            const response = await this.fetchImpl(requestUrl, {
+                method: 'GET',
+                headers: { Accept: 'application/json' },
+                signal: abort.signal,
+            });
+            if (!response.ok) {
+                refuse('POLYMARKET_METADATA_FAILED', `Polymarket CLOB read failed with HTTP ${response.status}`);
+            }
+            try {
+                return await response.json();
+            }
+            catch {
+                refuse('POLYMARKET_METADATA_FAILED', 'Polymarket CLOB response was not valid JSON');
+            }
+        }
+        catch (error) {
+            if (isExecutionRefusal(error))
+                throw error;
+            refuse('POLYMARKET_METADATA_FAILED', 'Polymarket CLOB read failed');
+        }
+        finally {
+            abort.cleanup();
+        }
+    }
+}
+//# sourceMappingURL=polymarket-clob-client.js.map

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

@@ -0,0 +1,60 @@
+import { type Address, type Hex } from 'viem';
+import { type ExecutionServiceConfig, type PolymarketTickSize } from './execution-config.js';
+import type { PolymarketOrderArgs, PolymarketOrderTypedData } from './execution-tool-definitions.js';
+import type { ExecutionAssertion } from './execution-types.js';
+import type { PolymarketBuilderFeeRates } from './polymarket-clob-client.js';
+import { type UnsignedPolymarketOrder } from './polymarket-order-builder.js';
+/**
+ * Assert-what-you-built for the Polymarket rail (spec §8.2): every check below runs on the order
+ * struct and EIP-712 payload the SDK actually produced — the exact bytes the user's signer will
+ * hash — never on the values this constructor intended to build.
+ */
+/** Price is carried as an exact integer count of 1/10,000ths, the finest tick the venue supports. */
+export declare const POLYMARKET_PRICE_SCALE = 10000n;
+/** Exact decimal-string → atomic-unit conversion. No float ever touches an amount. */
+export declare function polymarketAtomicUnits(decimal: string, decimals?: number): bigint;
+/** Exact price in 1/10,000ths. The caller's string form is authoritative; no rounding happens. */
+export declare function polymarketPriceUnits(price: string): bigint;
+export interface PolymarketPriceCheck {
+    readonly priceUnits: bigint;
+    readonly tickUnits: bigint;
+}
+/**
+ * The venue only accepts on-tick prices (live-verified 2026-08-17: every level of every book on a
+ * 0.01-tick market is an exact multiple of 0.01). The SDK would silently `roundNormal` an off-tick
+ * price to a different one, so an off-tick request is refused by name instead of being filled at a
+ * price the caller never asked for.
+ */
+export declare function assertPolymarketPriceOnTick(price: string, tickSize: PolymarketTickSize): PolymarketPriceCheck;
+/**
+ * The live builder registry is the value source for the ruled 0/0 bps rates (§8, Step-0 ruling).
+ * A registry row that no longer matches the ruled value means the rate moved without the ruling
+ * that governs it, so the constructor refuses instead of guessing which value is now in force — and
+ * a disabled row means the attribution would be inert, which is a missing fee, not a lower one.
+ */
+export declare function assertPolymarketBuilderAttributionRuled(rates: PolymarketBuilderFeeRates, config: ExecutionServiceConfig): ExecutionAssertion[];
+export interface PolymarketOrderAssertionInput {
+    readonly built: UnsignedPolymarketOrder;
+    readonly maker: Address;
+    readonly tokenId: string;
+    readonly side: 'BUY' | 'SELL';
+    readonly priceUnits: bigint;
+    readonly sizeAtomic: bigint;
+    readonly tickSize: PolymarketTickSize;
+    readonly negRisk: boolean;
+    readonly minimumOrderSizeAtomic: bigint;
+    readonly config: ExecutionServiceConfig;
+    readonly nowMs: number;
+}
+export interface AssertedPolymarketOrder {
+    readonly order: PolymarketOrderArgs;
+    readonly typedData: PolymarketOrderTypedData;
+    readonly orderHash: Hex;
+    readonly exchange: Address;
+    readonly assertions: readonly ExecutionAssertion[];
+}
+/**
+ * Decode the SDK's output back into a strictly typed order and assert every fund-critical field,
+ * including the exact Otto builder bytes32 inside the hashed struct (spec §7.3).
+ */
+export declare function decodeAndAssertPolymarketOrder(input: PolymarketOrderAssertionInput): AssertedPolymarketOrder;

package/dist/polymarket-order-assertions.js

@@ -0,0 +1,273 @@
+import { getAddress, hashTypedData } from 'viem';
+import { POLYMARKET_AMOUNT_DECIMALS, POLYMARKET_CHAIN_ID, POLYMARKET_EIP712_DOMAIN_NAME, POLYMARKET_EIP712_DOMAIN_VERSION, POLYMARKET_ORDER_PRIMARY_TYPE, POLYMARKET_ORDER_V2_EIP712_FIELDS, PM_BYTES32_ZERO, } from './execution-config.js';
+import { refuse } from './execution-errors.js';
+import { POLYMARKET_UNSIGNED_MARKER, } from './polymarket-order-builder.js';
+/**
+ * Assert-what-you-built for the Polymarket rail (spec §8.2): every check below runs on the order
+ * struct and EIP-712 payload the SDK actually produced — the exact bytes the user's signer will
+ * hash — never on the values this constructor intended to build.
+ */
+/** Price is carried as an exact integer count of 1/10,000ths, the finest tick the venue supports. */
+export const POLYMARKET_PRICE_SCALE = 10000n;
+const TICK_UNITS = Object.freeze({
+    '0.1': 1000n,
+    '0.01': 100n,
+    '0.001': 10n,
+    '0.0001': 1n,
+});
+function orderRefuse(message) {
+    return refuse('POLYMARKET_ORDER_INVALID', message);
+}
+/** Exact decimal-string → atomic-unit conversion. No float ever touches an amount. */
+export function polymarketAtomicUnits(decimal, decimals = POLYMARKET_AMOUNT_DECIMALS) {
+    const [whole, fraction = ''] = decimal.split('.');
+    if (fraction.length > decimals) {
+        orderRefuse('decimal value carries more precision than the venue supports');
+    }
+    return BigInt(`${whole}${fraction.padEnd(decimals, '0')}`);
+}
+/** Exact price in 1/10,000ths. The caller's string form is authoritative; no rounding happens. */
+export function polymarketPriceUnits(price) {
+    return polymarketAtomicUnits(price, 4);
+}
+/**
+ * The venue only accepts on-tick prices (live-verified 2026-08-17: every level of every book on a
+ * 0.01-tick market is an exact multiple of 0.01). The SDK would silently `roundNormal` an off-tick
+ * price to a different one, so an off-tick request is refused by name instead of being filled at a
+ * price the caller never asked for.
+ */
+export function assertPolymarketPriceOnTick(price, tickSize) {
+    const priceUnits = polymarketPriceUnits(price);
+    const tickUnits = TICK_UNITS[tickSize];
+    if (priceUnits % tickUnits !== 0n) {
+        refuse('UNSUPPORTED_POLYMARKET_MARKET', `price ${price} is not an exact multiple of the market tick size ${tickSize}`);
+    }
+    if (priceUnits < tickUnits || priceUnits > POLYMARKET_PRICE_SCALE - tickUnits) {
+        refuse('UNSUPPORTED_POLYMARKET_MARKET', `price ${price} is outside the tradable range [${tickSize}, ${1 - Number(tickSize)}] for this market`);
+    }
+    return { priceUnits, tickUnits };
+}
+/**
+ * The live builder registry is the value source for the ruled 0/0 bps rates (§8, Step-0 ruling).
+ * A registry row that no longer matches the ruled value means the rate moved without the ruling
+ * that governs it, so the constructor refuses instead of guessing which value is now in force — and
+ * a disabled row means the attribution would be inert, which is a missing fee, not a lower one.
+ */
+export function assertPolymarketBuilderAttributionRuled(rates, config) {
+    if (rates.code.toLowerCase() !== config.polymarketBuilderCode.toLowerCase()) {
+        refuse('ATTRIBUTION_MISSING', 'Polymarket builder registry row is for a different builder code');
+    }
+    if (!rates.enabled) {
+        refuse('ATTRIBUTION_MISSING', 'Otto builder code is registered but disabled: constructed orders would carry no attribution');
+    }
+    const ruled = config.polymarketRuledBuilderFeeBps;
+    if (rates.makerBps !== ruled.maker || rates.takerBps !== ruled.taker) {
+        refuse('POLYMARKET_BUILDER_FEE_UNRULED', `live builder rates ${rates.makerBps}/${rates.takerBps} bps do not match the ruled ${ruled.maker}/${ruled.taker} bps under config version ${config.polymarketBuilderFeeConfigVersion}; the rate value is a Founder ruling, not something this constructor may infer`);
+    }
+    return [
+        { id: 'polymarket_builder_registry_enabled', result: 'passed' },
+        { id: 'polymarket_builder_fee_matches_ruled', result: 'passed' },
+    ];
+}
+function sameAddress(left, right) {
+    try {
+        return getAddress(left) === getAddress(right);
+    }
+    catch {
+        return false;
+    }
+}
+function requiredString(source, key) {
+    const value = source[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        orderRefuse(`constructed Polymarket order is missing a string ${key}`);
+    }
+    return value;
+}
+/**
+ * Decode the SDK's output back into a strictly typed order and assert every fund-critical field,
+ * including the exact Otto builder bytes32 inside the hashed struct (spec §7.3).
+ */
+export function decodeAndAssertPolymarketOrder(input) {
+    const raw = input.built.order;
+    const captured = input.built.typedData;
+    // Re-checked here as well as in the builder: a signature present on the way OUT of construction
+    // means key material entered a prepare-only path, and dropping the field on rebuild would hide
+    // that rather than report it.
+    if (raw.signature !== POLYMARKET_UNSIGNED_MARKER) {
+        orderRefuse('constructed Polymarket order carries a signature; this constructor never signs');
+    }
+    // ---- the signed struct itself -------------------------------------------------------------
+    const domain = captured.domain;
+    const types = captured.types?.Order;
+    if (!domain || !Array.isArray(types)) {
+        orderRefuse('constructed Polymarket order carries no EIP-712 domain or Order struct');
+    }
+    if (captured.primaryType !== POLYMARKET_ORDER_PRIMARY_TYPE) {
+        orderRefuse('constructed Polymarket EIP-712 payload has an unexpected primary type');
+    }
+    if (types.length !== POLYMARKET_ORDER_V2_EIP712_FIELDS.length ||
+        types.some((field, index) => {
+            const entry = field;
+            const expected = POLYMARKET_ORDER_V2_EIP712_FIELDS[index];
+            return entry.name !== expected?.name || entry.type !== expected?.type;
+        })) {
+        // The SDK's struct drifting from the pinned one would silently change what `builder` commits to.
+        orderRefuse('constructed Polymarket order struct does not match the pinned CTF Exchange V2 struct');
+    }
+    const expectedExchange = input.built.exchange;
+    if (domain.name !== POLYMARKET_EIP712_DOMAIN_NAME ||
+        domain.version !== POLYMARKET_EIP712_DOMAIN_VERSION ||
+        domain.chainId !== POLYMARKET_CHAIN_ID ||
+        typeof domain.verifyingContract !== 'string' ||
+        !sameAddress(domain.verifyingContract, expectedExchange)) {
+        orderRefuse(`constructed Polymarket EIP-712 domain is not the ${input.negRisk ? 'negRisk ' : ''}CTF Exchange V2 domain on Polygon`);
+    }
+    const message = captured.message;
+    if (!message)
+        orderRefuse('constructed Polymarket order carries no signable message');
+    // ---- attribution: the exact Otto builder code, inside the hashed struct ---------------------
+    const builder = requiredString(message, 'builder').toLowerCase();
+    if (builder === PM_BYTES32_ZERO) {
+        refuse('ATTRIBUTION_MISSING', 'constructed Polymarket order carries the zero builder code');
+    }
+    if (builder !== input.config.polymarketBuilderCode.toLowerCase()) {
+        refuse('ATTRIBUTION_MISSING', 'constructed Polymarket order does not carry the configured Otto builder code');
+    }
+    if (requiredString(raw, 'builder').toLowerCase() !== builder) {
+        refuse('ATTRIBUTION_MISSING', 'Polymarket order args and signed struct disagree on the builder code');
+    }
+    if (requiredString(message, 'metadata').toLowerCase() !== PM_BYTES32_ZERO) {
+        orderRefuse('constructed Polymarket order carries unexpected metadata');
+    }
+    // ---- account-profile roles, which live INSIDE the signed order (spec §4) --------------------
+    const maker = requiredString(message, 'maker');
+    const signer = requiredString(message, 'signer');
+    if (!sameAddress(maker, input.maker) || !sameAddress(signer, input.maker)) {
+        refuse('ACCOUNT_BINDING_MISMATCH', 'constructed Polymarket order binds a maker or signer other than the declared account');
+    }
+    if (message.signatureType !== 0) {
+        refuse('UNSUPPORTED_ACCOUNT_PROFILE', 'constructed Polymarket order does not use the EOA signature type');
+    }
+    // ---- semantic identity: market, side, amounts ------------------------------------------------
+    if (requiredString(message, 'tokenId') !== input.tokenId) {
+        orderRefuse('constructed Polymarket order names a different outcome token');
+    }
+    const expectedSide = input.side === 'BUY' ? 0 : 1;
+    if (message.side !== expectedSide || raw.side !== input.side) {
+        orderRefuse('constructed Polymarket order is on the wrong side');
+    }
+    const makerAmount = BigInt(requiredString(message, 'makerAmount'));
+    const takerAmount = BigInt(requiredString(message, 'takerAmount'));
+    if (makerAmount <= 0n || takerAmount <= 0n) {
+        orderRefuse('constructed Polymarket order carries a non-positive leg');
+    }
+    // Both inputs are exact by schema (price ≤ 4 decimals and on-tick, size ≤ 2 decimals), and the
+    // venue's rounding precision for every tick size is at least the sum of those, so the collateral
+    // leg is exactly representable and the check is equality rather than a tolerance. Anything else is
+    // the caller buying dearer or selling cheaper than they asked.
+    const collateral = (input.sizeAtomic * input.priceUnits) / POLYMARKET_PRICE_SCALE;
+    if ((input.sizeAtomic * input.priceUnits) % POLYMARKET_PRICE_SCALE !== 0n) {
+        orderRefuse('requested price and size do not produce an exact collateral amount');
+    }
+    const shares = input.side === 'BUY' ? takerAmount : makerAmount;
+    const collateralLeg = input.side === 'BUY' ? makerAmount : takerAmount;
+    if (shares !== input.sizeAtomic) {
+        orderRefuse(`constructed Polymarket order is for ${shares} share units, not the requested ${input.sizeAtomic}`);
+    }
+    if (collateralLeg !== collateral) {
+        orderRefuse(`constructed Polymarket order prices ${shares} shares at ${collateralLeg} collateral units, not the requested ${collateral}`);
+    }
+    if (shares < input.minimumOrderSizeAtomic) {
+        refuse('UNSUPPORTED_POLYMARKET_MARKET', `order size is below the market minimum of ${input.minimumOrderSizeAtomic} share units`);
+    }
+    // ---- freshness of the signed timestamp -------------------------------------------------------
+    const timestampMs = Number(requiredString(message, 'timestamp'));
+    if (!Number.isSafeInteger(timestampMs) || Math.abs(timestampMs - input.nowMs) > 600_000) {
+        // The timestamp is inside the signed struct, so a clock skew between it and the artifact's own
+        // construction time would make the envelope's freshness bound describe a different order.
+        orderRefuse('constructed Polymarket order timestamp is not within the artifact freshness ceiling');
+    }
+    if (requiredString(raw, 'expiration') !== '0') {
+        // v1 constructs GTC orders only. `expiration` is not covered by the V2 signed struct, so a
+        // non-zero value would be an unsigned promise the exchange is free to ignore.
+        orderRefuse('constructed Polymarket GTC order carries a non-zero expiration');
+    }
+    // ---- rebuild the payload from the asserted values and re-derive the digest -------------------
+    const order = {
+        salt: requiredString(raw, 'salt'),
+        maker: getAddress(maker),
+        signer: getAddress(signer),
+        tokenId: input.tokenId,
+        makerAmount: makerAmount.toString(),
+        takerAmount: takerAmount.toString(),
+        side: input.side,
+        signatureType: 0,
+        metadata: PM_BYTES32_ZERO,
+        builder: builder,
+        timestamp: requiredString(message, 'timestamp'),
+        expiration: '0',
+    };
+    if (requiredString(raw, 'salt') !== requiredString(message, 'salt')) {
+        orderRefuse('Polymarket order args and signed struct disagree on the salt');
+    }
+    const typedData = {
+        primary_type: POLYMARKET_ORDER_PRIMARY_TYPE,
+        domain: {
+            name: POLYMARKET_EIP712_DOMAIN_NAME,
+            version: POLYMARKET_EIP712_DOMAIN_VERSION,
+            chainId: POLYMARKET_CHAIN_ID,
+            verifyingContract: getAddress(expectedExchange),
+        },
+        types: { Order: POLYMARKET_ORDER_V2_EIP712_FIELDS.map((field) => ({ ...field })) },
+        message: {
+            salt: order.salt,
+            maker: order.maker,
+            signer: order.signer,
+            tokenId: order.tokenId,
+            makerAmount: order.makerAmount,
+            takerAmount: order.takerAmount,
+            side: expectedSide,
+            signatureType: 0,
+            timestamp: order.timestamp,
+            metadata: order.metadata,
+            builder: order.builder,
+        },
+    };
+    const orderHash = hashTypedData({
+        domain: { ...typedData.domain, verifyingContract: typedData.domain.verifyingContract },
+        types: { Order: [...typedData.types.Order] },
+        primaryType: typedData.primary_type,
+        message: typedData.message,
+    });
+    // The rebuilt payload must hash to exactly what the SDK's own payload hashes to. If any field
+    // above was normalized into something different from what was built, the digests diverge here.
+    const capturedHash = hashTypedData({
+        domain: domain,
+        types: { Order: types },
+        primaryType: POLYMARKET_ORDER_PRIMARY_TYPE,
+        message: message,
+    });
+    if (orderHash !== capturedHash) {
+        orderRefuse('re-derived Polymarket order digest does not match the digest the SDK produced');
+    }
+    return Object.freeze({
+        order,
+        typedData,
+        orderHash,
+        exchange: getAddress(expectedExchange),
+        assertions: Object.freeze([
+            { id: 'polymarket_builder_code_exact', result: 'passed' },
+            { id: 'polymarket_eip712_struct_pinned', result: 'passed' },
+            { id: 'polymarket_eip712_domain_exact', result: 'passed' },
+            { id: 'polymarket_order_roles_bound', result: 'passed' },
+            { id: 'polymarket_price_on_tick', result: 'passed' },
+            { id: 'polymarket_amounts_exact_at_price', result: 'passed' },
+            { id: 'polymarket_size_meets_venue_minimum', result: 'passed' },
+            { id: 'polymarket_order_unsigned', result: 'passed' },
+            { id: 'polymarket_order_timestamp_bounded', result: 'passed' },
+            { id: 'polymarket_order_hash_recomputed', result: 'passed' },
+        ]),
+    });
+}
+//# sourceMappingURL=polymarket-order-assertions.js.map

package/dist/polymarket-order-builder.d.ts

@@ -0,0 +1,43 @@
+import { type Address, type Hex } from 'viem';
+import { type PolymarketTickSize } from './execution-config.js';
+/**
+ * Drives `@polymarket/clob-client-v2`'s OWN order-construction half (spec §7.3: reuse the SDK's
+ * `createOrder`/`postOrder` split) and stops before signing.
+ *
+ * The split is enforced structurally rather than by discipline: the signer handed to the SDK holds
+ * no key and cannot produce a signature. It exposes only the caller's declared address, records the
+ * exact EIP-712 payload the SDK asked it to sign, and returns a marker string that is not hex and
+ * can never be mistaken for a signature. `postOrder` is never reached — this module does not import
+ * `ClobClient`, so no credentialed surface is in scope at all.
+ */
+/** Returned in place of a signature. Deliberately not hex: no consumer can mistake it for one. */
+export declare const POLYMARKET_UNSIGNED_MARKER: "otto-prepare-only-unsigned";
+export interface PolymarketCapturedTypedData {
+    readonly domain: unknown;
+    readonly types: unknown;
+    readonly primaryType: unknown;
+    readonly message: unknown;
+}
+export interface UnsignedPolymarketOrderRequest {
+    readonly maker: Address;
+    readonly tokenId: string;
+    readonly side: 'BUY' | 'SELL';
+    /** Decimal probability price, already validated on-tick by the caller. */
+    readonly price: number;
+    /** Order size in shares, already validated against the venue minimum by the caller. */
+    readonly size: number;
+    readonly tickSize: PolymarketTickSize;
+    readonly negRisk: boolean;
+    readonly builderCode: Hex;
+}
+export interface UnsignedPolymarketOrder {
+    /** The SDK's own order object, with the marker where a signature would be. */
+    readonly order: Record<string, unknown>;
+    /** The exact EIP-712 payload the SDK handed to the signer. */
+    readonly typedData: PolymarketCapturedTypedData;
+    /** The exchange the SDK selected for this market; asserted against the domain afterwards. */
+    readonly exchange: Address;
+}
+/** The V2 exchange the SDK routes this market to; the EIP-712 `verifyingContract`. */
+export declare function polymarketExchangeAddress(negRisk: boolean): Address;
+export declare function buildUnsignedPolymarketOrder(request: UnsignedPolymarketOrderRequest): Promise<UnsignedPolymarketOrder>;

package/dist/polymarket-order-builder.js

@@ -0,0 +1,74 @@
+import { OrderBuilder, SignatureTypeV2, getContractConfig } from '@polymarket/clob-client-v2';
+import { getAddress } from 'viem';
+import { POLYMARKET_CHAIN_ID } from './execution-config.js';
+import { refuse } from './execution-errors.js';
+/**
+ * Drives `@polymarket/clob-client-v2`'s OWN order-construction half (spec §7.3: reuse the SDK's
+ * `createOrder`/`postOrder` split) and stops before signing.
+ *
+ * The split is enforced structurally rather than by discipline: the signer handed to the SDK holds
+ * no key and cannot produce a signature. It exposes only the caller's declared address, records the
+ * exact EIP-712 payload the SDK asked it to sign, and returns a marker string that is not hex and
+ * can never be mistaken for a signature. `postOrder` is never reached — this module does not import
+ * `ClobClient`, so no credentialed surface is in scope at all.
+ */
+/** Returned in place of a signature. Deliberately not hex: no consumer can mistake it for one. */
+export const POLYMARKET_UNSIGNED_MARKER = 'otto-prepare-only-unsigned';
+/**
+ * A signer in shape only. `getSignerAddress` in the SDK accepts any object exposing
+ * `signTypedData` plus an account address, which is exactly — and only — what this provides.
+ */
+class PolymarketPrepareOnlySigner {
+    account;
+    captured = [];
+    constructor(address) {
+        this.account = Object.freeze({ address });
+    }
+    async signTypedData(args) {
+        const { account: _account, ...payload } = args;
+        this.captured.push(payload);
+        return POLYMARKET_UNSIGNED_MARKER;
+    }
+}
+/** The V2 exchange the SDK routes this market to; the EIP-712 `verifyingContract`. */
+export function polymarketExchangeAddress(negRisk) {
+    const contracts = getContractConfig(POLYMARKET_CHAIN_ID);
+    return getAddress(negRisk ? contracts.negRiskExchangeV2 : contracts.exchangeV2);
+}
+export async function buildUnsignedPolymarketOrder(request) {
+    const signer = new PolymarketPrepareOnlySigner(request.maker);
+    // funderAddress === the maker: for the v1 EOA profile the account that signs is the account that
+    // holds the collateral, so the SDK's maker/signer split collapses onto one declared address.
+    const builder = new OrderBuilder(signer, POLYMARKET_CHAIN_ID, SignatureTypeV2.EOA, request.maker);
+    let order;
+    try {
+        order = (await builder.buildOrder({
+            tokenID: request.tokenId,
+            price: request.price,
+            size: request.size,
+            side: request.side,
+            // Otto attribution enters here and nowhere else; the caller has no seam to set it (§5) and
+            // the constructed struct is re-asserted against the configured value afterwards (§8).
+            builderCode: request.builderCode,
+        }, { tickSize: request.tickSize, negRisk: request.negRisk }, 2));
+    }
+    catch (error) {
+        return refuse('POLYMARKET_ORDER_INVALID', `Polymarket order construction failed: ${error instanceof Error ? error.message : 'unknown error'}`);
+    }
+    const typedData = signer.captured[0];
+    if (signer.captured.length !== 1 || !typedData) {
+        // Either the SDK never reached the signing leg (no typed data to assert) or it signed more than
+        // once. Both mean the artifact would describe something other than what was built.
+        return refuse('POLYMARKET_ORDER_INVALID', 'Polymarket order construction did not produce exactly one EIP-712 payload');
+    }
+    if (order.signature !== POLYMARKET_UNSIGNED_MARKER) {
+        // A real signature here would mean key material entered a prepare-only path.
+        return refuse('POLYMARKET_ORDER_INVALID', 'Polymarket order was signed inside the constructor');
+    }
+    return Object.freeze({
+        order,
+        typedData,
+        exchange: polymarketExchangeAddress(request.negRisk),
+    });
+}
+//# sourceMappingURL=polymarket-order-builder.js.map