@symbiome-forge/cow-sdk-wasm 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,278 @@
+# @symbiome-forge/cow-sdk-wasm
+
+TypeScript-callable WebAssembly bindings for the CoW Protocol Rust SDK.
+
+```sh
+npm install @symbiome-forge/cow-sdk-wasm@alpha
+```
+
+The package exposes a TypeScript facade over deterministic Rust protocol logic.
+JavaScript and TypeScript consumers get typed DTOs, explicit wallet and HTTP
+callbacks, per-call cancellation, per-call timeouts, and flavor-specific imports
+without depending on a specific wallet library.
+
+## When to use this SDK
+
+| You are building... | Choose | Why |
+| --- | --- | --- |
+| Browser dapp with viem, ethers, wagmi, or an EIP-1193 wallet | `@symbiome-forge/cow-sdk-wasm` | Wallet stack stays outside the package behind typed callbacks |
+| Browser dapp with a smaller orderbook bundle target | `@symbiome-forge/cow-sdk-wasm/orderbook` | Orderbook and signing subset with a smaller raw wasm budget |
+| Node.js 22 or 24 LTS backend | `@symbiome-forge/cow-sdk-wasm` | Node target works without browser polyfills when transport is configured |
+| Cloudflare Worker proxying CoW orderbook calls | `@symbiome-forge/cow-sdk-wasm/cloudflare` | Worker-compatible web target and explicit wasm module initialization |
+| Signer service or HSM proxy | `@symbiome-forge/cow-sdk-wasm/signing` | Signing primitives without orderbook, trading, subgraph, or IPFS clients |
+| Native Rust service, bot, solver, or treasury automation | `cow-sdk` | Avoids wasm-bindgen and npm packaging entirely |
+| Rust app compiled to browser WASM | `cow-sdk-browser-wallet` plus `cow-sdk-core` (browser `FetchTransport`) | Rust-on-wasm path; this package is for JavaScript hosts |
+
+## Not in this crate
+
+Use the upstream TypeScript SDK packages until these capability families ship
+in `cow-rs`:
+
+- TWAP and composable orders.
+- Cross-chain bridging.
+- Cow Shed account abstraction.
+- Flash-loan helpers.
+- Weiroll command planning.
+- Hardware wallet adapters.
+- On-chain transaction submission; this package emits typed data or
+  transaction requests and lets the caller's wallet submit.
+- WASI, WebAssembly components, TinyGo, Blazor, AssemblyScript guests, and
+  `no_std` embedded targets.
+
+## Quickstart
+
+### Node.js 22 or 24 with viem
+
+```ts
+import { TradingClient } from "@symbiome-forge/cow-sdk-wasm";
+
+const trading = new TradingClient({
+  chainId: 1,
+  env: "prod",
+  appCode: "my-node-service",
+  transport: { kind: "fetch" },
+  transportPolicy: {
+    retryPolicy: { maxAttempts: 3, baseDelayMs: 200 },
+    userAgent: "my-node-service/1.0"
+  }
+});
+
+// `getQuote` returns a fully resolved `QuoteResultsDto` envelope.
+const quote = await trading.getQuote({
+  kind: "sell",
+  sellToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+  buyToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  amount: "1000000000000000000"
+});
+
+// Reuse the quote to sign and post in one call; `quote.value` is the
+// `QuoteResultsDto` and the callback receives the EIP-712 envelope.
+const result = await trading.postSwapOrderFromQuote(
+  quote.value,
+  "0x1111111111111111111111111111111111111111",
+  async (envelope) => walletClient.signTypedData(envelope),
+  { walletConfig: { timeoutMs: 15_000 } }
+);
+// `result.value.orderId` is the posted order UID.
+```
+
+### Browser with `window.ethereum`
+
+```ts
+import { signOrderWithEip1193 } from "@symbiome-forge/cow-sdk-wasm";
+
+const ethereum = window.ethereum;
+const [owner] = await ethereum.request({ method: "eth_requestAccounts" });
+const abortController = new AbortController();
+
+// The order to sign: build it yourself or map it from a fetched quote.
+const order = {
+  sellToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+  buyToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  receiver: owner,
+  sellAmount: "1000000000000000000",
+  buyAmount: "3500000000",
+  validTo: Math.floor(Date.now() / 1000) + 3_600,
+  appData: "0x0000000000000000000000000000000000000000000000000000000000000000",
+  feeAmount: "0",
+  kind: "sell",
+  partiallyFillable: false,
+  sellTokenBalance: "erc20",
+  buyTokenBalance: "erc20"
+};
+
+const signed = await signOrderWithEip1193(
+  order,
+  1,
+  owner,
+  (rpc) => ethereum.request(rpc),
+  { signal: abortController.signal, walletConfig: { timeoutMs: 20_000 } }
+);
+// `signed.value` is the SignedOrderDto.
+```
+
+### Browser with MetaMask `eth_signTypedData_v4`
+
+When the wallet exposes the typed-data JSON-RPC method directly, callers can
+pass the envelope to `eth_signTypedData_v4` from inside the typed-data signer
+callback. The helper hands the callback a typed-data envelope — plain `domain`,
+`types`, `primaryType`, and `message` objects — that the callback serializes and
+returns the signature string for.
+
+```ts
+import { signOrderWithTypedDataSigner } from "@symbiome-forge/cow-sdk-wasm";
+
+const [owner] = await window.ethereum.request({ method: "eth_requestAccounts" });
+
+const signed = await signOrderWithTypedDataSigner(order, 1, owner, async (envelope) => {
+  const signature = await window.ethereum.request({
+    method: "eth_signTypedData_v4",
+    params: [owner, JSON.stringify(envelope)]
+  });
+  if (typeof signature !== "string") {
+    throw new Error("wallet did not return a signature");
+  }
+  return signature;
+});
+```
+
+### Cloudflare Worker
+
+```ts
+import initialize, {
+  OrderBookClient
+} from "@symbiome-forge/cow-sdk-wasm/cloudflare";
+import wasmModule from "@symbiome-forge/cow-sdk-wasm/cloudflare/wasm";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    await initialize(wasmModule);
+
+    const client = new OrderBookClient({
+      chainId: 1,
+      env: "prod",
+      apiKey: env.COW_PARTNER_API_KEY ?? null,
+      transport: { kind: "fetch" },
+      transportPolicy: { userAgent: "my-worker/1.0" }
+    });
+
+    const quote = await client.getQuote(await request.json(), {
+      timeoutMs: 8_000
+    });
+    client.dispose();
+
+    return Response.json(quote);
+  }
+};
+```
+
+## Choosing your import
+
+| Import | Surface | Use when |
+| --- | --- | --- |
+| `@symbiome-forge/cow-sdk-wasm` | Default facade with orderbook, signing, app-data, IPFS, trading, and subgraph | General TypeScript or Node use |
+| `@symbiome-forge/cow-sdk-wasm/orderbook` | Orderbook client, cancellation helpers, and signing helpers | Browser dapps that do not need trading or subgraph clients |
+| `@symbiome-forge/cow-sdk-wasm/signing` | Signing, UID, EIP-1271, deployment, and version helpers | Signer services and HSM-facing adapters |
+| `@symbiome-forge/cow-sdk-wasm/cloudflare` | Worker-compatible orderbook and trading facade | Cloudflare Workers |
+| `@symbiome-forge/cow-sdk-wasm/cloudflare/wasm` | Raw Worker wasm module asset | Pass to the Cloudflare `initialize` helper |
+
+Do not import from `dist/raw` or generated wasm-pack target directories. Raw
+wasm-bindgen output is package-internal; public imports go through the facade
+subpaths above.
+
+## Performance and bundle size
+
+The package is built with release-size settings and a `wasm-opt -Oz` post-pass.
+Measured on the `0.1.0-alpha.1` build:
+
+| Flavor | Raw wasm | Brotli | Gzip | Gate |
+| --- | ---: | ---: | ---: | --- |
+| default | 1.59 MiB | 501 KiB | 675 KiB | 3.3 MiB raw / 900 KiB brotli |
+| orderbook | 0.99 MiB | 330 KiB | 432 KiB | 1.5 MiB raw / 500 KiB brotli |
+| signing | 0.31 MiB | 119 KiB | 142 KiB | 0.9 MiB raw / 300 KiB brotli |
+| cloudflare | 1.50 MiB | 478 KiB | 642 KiB | 3.2 MiB raw / 850 KiB brotli / 3,000,000 B gzip (warn at 2,700,000 B) |
+
+The cloudflare flavor's gzip-compressed artifact is below the current
+Cloudflare Workers Free compressed-size limit at the time of measurement.
+Full Workers support still requires release-bundle verification and Worker
+startup measurement; the release pipeline enforces the gzip byte budget on
+every build, but Wrangler deployment and `startup_time_ms` telemetry are
+separate operational gates.
+
+Cloudflare Workers cold starts are runtime-sensitive. The package treats
+300 ms as the warning threshold, 500 ms as the release gate, and 1 second as
+the platform-limit budget that Worker consumers should stay well below.
+
+## Transport configuration
+
+Every client accepts one transport:
+
+```ts
+transport: { kind: "fetch" }
+transport: { kind: "fetch", fetch: customFetch }
+transport: { kind: "callback", callback: customHttpCallback }
+```
+
+Use `fetch` for browser, Node, and Worker runtimes that expose a standards
+compatible `fetch`. Use `callback` when the host must own request dispatch,
+fixtures, proxying, custom authentication, or observability.
+
+Every client also accepts optional `transportPolicy` settings for retry,
+rate-limit, jitter, and user-agent behavior.
+
+## Cancellation and timeouts
+
+Every call accepts an optional `signal` (an `AbortSignal`) and a per-call
+`timeoutMs`. Aborting the signal rejects the pending call promptly with a
+`cancelled` `CowError`; `timeoutMs` rejects with a `timeout` error. Both resolve
+the *awaited call* — an already-dispatched HTTP request may keep running in the
+background until it completes or the timeout elapses, so treat cancellation as
+"stop waiting," not a guarantee that the network request is halted.
+
+## Architecture
+
+The TypeScript facade is the public package contract. It:
+
+- exposes camelCase TypeScript APIs;
+- exposes `dispose()` and `[Symbol.dispose]` (so `using client = new …` works)
+  while hiding the raw wasm-bindgen `free()` handle;
+- maps raw wasm errors into `CowError`;
+- adapts `transport: { kind: "fetch" }` into the callback HTTP ABI;
+- keeps wallet libraries outside the package behind named callback types.
+
+## API reference
+
+The declaration snapshots under `crates/wasm/snapshots/facade/` show the
+public TypeScript surface for each flavor. Key exports include:
+
+- clients: `OrderBookClient`, `TradingClient`, `SubgraphClient`, `IpfsClient`;
+- signing helpers: `signOrderWithTypedDataSigner`, `signOrderWithEip1193`,
+  `signOrderEthSignDigest`, `signOrderWithEip1271`,
+  `signOrderWithCustomEip1271`;
+- cancellation helpers: `signCancellationWithTypedDataSigner`,
+  `signCancellationWithEip1193`, `signCancellationEthSignDigest`,
+  `buildCancelOrderTx`, `buildPresignTx`;
+- pure helpers: `domainSeparator`, `orderTypedData`, `computeOrderUid`,
+  `deploymentAddresses`, `supportedChainIds`, `appDataInfo`,
+  `validateAppDataDoc`, `appDataDoc`, `appDataHexToCid`,
+  `cidToAppDataHex`, `wasmVersion`.
+
+## When to use this package vs the upstream TypeScript SDK
+
+For most browser dapps, web apps, and CowSwap-style UIs, the upstream
+[`@cowprotocol/cow-sdk`](https://www.npmjs.com/package/@cowprotocol/cow-sdk)
+is the recommended choice; it is substantially smaller at equivalent feature
+subsets. This package is appropriate for specialized cases:
+
+- TypeScript services that need byte-for-byte parity with the Rust SDK's
+  EIP-712 + EIP-1271 signing path.
+- Single-source-of-truth Rust + TypeScript embedding (one implementation
+  across both runtimes).
+- Cloudflare Workers (size-compatible with the current Workers Free
+  compressed-size limit at the time of measurement; full Workers support
+  pending release-bundle and startup validation).
+- Embeddable signing helpers (the `./signing` flavor is the smallest).
+
+The "When to use this SDK" table at the top of this README routes consumers
+by use case. The Quickstart sections above show the supported import shapes
+for the most common runtimes.

package/dist/cloudflare/callbacks.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cloudflare/callbacks.d.ts

@@ -0,0 +1,55 @@
+export type SupportedChainId = 1 | 100 | 137 | 8453 | 42161 | 43114 | 56 | 11155111 | 9745 | 57073 | 59144;
+export type CowEnv = "prod" | "staging";
+export type CowFetchMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+export interface CowFetchRequest {
+    method: CowFetchMethod;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface CowFetchResponse {
+    status: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export type CowFetchCallback = (request: CowFetchRequest) => Promise<CowFetchResponse> | CowFetchResponse;
+export interface TypedDataDomainDto {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+export interface TypedDataFieldDto {
+    name: string;
+    type: string;
+}
+export interface TypedDataEnvelopeDto {
+    domain: TypedDataDomainDto;
+    types: Record<string, TypedDataFieldDto[]>;
+    primaryType: string;
+    message: unknown;
+}
+export interface CowEip1271SignRequest {
+    order: unknown;
+    typedData: TypedDataEnvelopeDto;
+    owner: string;
+    chainId: number;
+}
+export interface ContractCallDto {
+    address: string;
+    method: string;
+    abiJson: string;
+    argsJson: string;
+}
+export type TypedDataSignerCallback = (envelope: TypedDataEnvelopeDto) => Promise<string> | string;
+export type Eip1193RequestCallback = (request: {
+    method: string;
+    params?: unknown[];
+}) => Promise<unknown> | unknown;
+export type DigestSignerCallback = (digest: string) => Promise<string> | string;
+export type CowEip1271SignCallback = (request: CowEip1271SignRequest) => Promise<string> | string;
+export type CustomEip1271Callback = CowEip1271SignCallback;
+export type ContractReadCallback = (request: ContractCallDto) => Promise<string> | string;

package/dist/cloudflare/callbacks.js

@@ -0,0 +1 @@
+export {};

package/dist/cloudflare/envelope.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cloudflare/envelope.d.ts

@@ -0,0 +1,5 @@
+export type SchemaVersion = "v1" | "__unknown";
+export interface WasmEnvelope<T> {
+    schemaVersion: SchemaVersion;
+    value: T;
+}

package/dist/cloudflare/envelope.js

@@ -0,0 +1 @@
+export {};

package/dist/cloudflare/errors.cjs

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeError = normalizeError;
+exports.cancelledError = cancelledError;
+exports.invalidInput = invalidInput;
+const knownKinds = new Set([
+    "invalidInput",
+    "unknownEnumValue",
+    "unsupportedChain",
+    "walletRequest",
+    "walletTimeout",
+    "transport",
+    "orderbook",
+    "subgraph",
+    "signing",
+    "appData",
+    "cancelled",
+    "internal",
+    "__unknown"
+]);
+function normalizeError(raw) {
+    if (isRecord(raw)) {
+        // The Rust `WasmError` serializes with serde `rename_all(_fields) = "camelCase"`
+        // through a json-compatible serializer, so it already crosses the boundary as a
+        // camelCase plain object — no field renaming is needed here.
+        const normalized = raw;
+        const kind = typeof normalized.kind === "string" ? normalized.kind : undefined;
+        if (kind && knownKinds.has(kind)) {
+            const schemaVersion = normalized.schemaVersion === "__unknown" ? "__unknown" : "v1";
+            if (kind === "__unknown") {
+                return {
+                    schemaVersion,
+                    kind: "__unknown",
+                    message: unknownMessage(),
+                    raw: normalized.raw ?? raw
+                };
+            }
+            return withActionableMessage({
+                ...normalized,
+                schemaVersion,
+                kind
+            });
+        }
+        if (kind) {
+            return {
+                schemaVersion: normalized.schemaVersion === "__unknown" ? "__unknown" : "v1",
+                kind: "__unknown",
+                message: unknownMessage(),
+                raw
+            };
+        }
+    }
+    if (raw instanceof Error) {
+        return (classifyDeserializationFailure(raw.message) ?? {
+            schemaVersion: "v1",
+            kind: "internal",
+            message: internalMessage(raw.message)
+        });
+    }
+    return (classifyDeserializationFailure(String(raw)) ?? {
+        schemaVersion: "v1",
+        kind: "internal",
+        message: internalMessage(String(raw))
+    });
+}
+// Input-DTO deserialization failures cross the wasm boundary as a plain
+// `Error`: the generated wasm-bindgen glue throws the serde message, so it
+// never carries a structured `kind`. These are CALLER input errors — a value
+// that does not match the documented input type (unknown enum variant,
+// missing/unknown field, wrong type) — not SDK-internal faults, so they must
+// normalize to `invalidInput` rather than `internal` (whose contract implies
+// an SDK bug). The verbatim detail is preserved because it already names the
+// offending field/variant and the expected set, e.g.
+// "unknown variant `teleport`, expected `sell` or `buy`".
+const DESERIALIZATION_FAILURE_PATTERNS = [
+    /unknown variant `/,
+    /missing field `/,
+    /unknown field `/,
+    /duplicate field `/,
+    /invalid type:/,
+    /invalid length\b/,
+    /invalid value:/,
+    /data did not match any variant/
+];
+function classifyDeserializationFailure(message) {
+    if (!DESERIALIZATION_FAILURE_PATTERNS.some((pattern) => pattern.test(message))) {
+        return undefined;
+    }
+    const detail = message.replace(/^Error:\s*/, "");
+    const field = detail.match(/(?:missing|unknown|duplicate) field `([^`]+)`/)?.[1];
+    const reason = `Invalid SDK input: ${detail}. Check the value against the documented input type and retry.`;
+    return field !== undefined
+        ? { schemaVersion: "v1", kind: "invalidInput", field, message: reason }
+        : { schemaVersion: "v1", kind: "invalidInput", message: reason };
+}
+function cancelledError() {
+    return {
+        schemaVersion: "v1",
+        kind: "cancelled",
+        message: "Operation was cancelled. Create a fresh AbortController or retry without an already-aborted signal."
+    };
+}
+function invalidInput(field, reason) {
+    return {
+        schemaVersion: "v1",
+        kind: "invalidInput",
+        field,
+        message: `Invalid \`${field}\`: ${reason}. Check the value supplied for \`${field}\` and retry with a valid SDK input.`
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function withActionableMessage(error) {
+    if ("message" in error && typeof error.message === "string" && error.message.length > 0) {
+        return error;
+    }
+    switch (error.kind) {
+        case "unknownEnumValue":
+            return {
+                ...error,
+                message: `Unsupported value \`${error.value}\` for \`${error.field}\`. Use one of the documented values for this field.`
+            };
+        case "unsupportedChain":
+            return {
+                ...error,
+                message: `Unsupported chain ID ${error.chainId}. Call supportedChainIds() before constructing requests and route unsupported networks to another integration.`
+            };
+        case "walletTimeout":
+            return {
+                ...error,
+                message: `Wallet request timed out after ${error.timeoutMs} ms. Increase walletConfig.timeoutMs or ask the user to approve the wallet request before the timeout.`
+            };
+        case "cancelled":
+            return cancelledError();
+        case "__unknown":
+            return {
+                ...error,
+                message: unknownMessage()
+            };
+        default:
+            return error;
+    }
+}
+function internalMessage(detail) {
+    return `SDK internal error: ${detail}. This indicates serialization or invariant failure; retry with the same inputs only after checking the reported input shape.`;
+}
+function unknownMessage() {
+    return "SDK received an unrecognized error variant. Inspect raw, preserve it in logs without credentials, and update the SDK if the variant is now documented.";
+}

package/dist/cloudflare/errors.d.ts

@@ -0,0 +1,82 @@
+import type { SchemaVersion } from "./envelope.js";
+/**
+ * Coarse, switchable classification of an orderbook rejection. Lets a consumer
+ * branch on the action a rejection calls for — fix the request, fund the
+ * wallet, re-quote, wait, or escalate — without matching every wire tag. The
+ * `__unknown` member is the forward-compatible sentinel for a category a newer
+ * SDK may introduce.
+ */
+export type OrderBookRejectionCategory = "authorization" | "insufficientFunds" | "invalidOrder" | "notFound" | "conflict" | "unfulfillable" | "server" | "__unknown";
+export type CowError = {
+    schemaVersion: "v1";
+    kind: "invalidInput";
+    message: string;
+    field?: string;
+} | {
+    schemaVersion: "v1";
+    kind: "unknownEnumValue";
+    message: string;
+    field: string;
+    value: string;
+} | {
+    schemaVersion: "v1";
+    kind: "unsupportedChain";
+    message: string;
+    chainId: number;
+} | {
+    schemaVersion: "v1";
+    kind: "walletRequest";
+    method: string;
+    code?: number;
+    message: string;
+} | {
+    schemaVersion: "v1";
+    kind: "walletTimeout";
+    message: string;
+    timeoutMs: number;
+} | {
+    schemaVersion: "v1";
+    kind: "transport";
+    class: string;
+    message: string;
+    status?: number;
+    headers?: [string, string][];
+    body?: string;
+} | {
+    schemaVersion: "v1";
+    kind: "orderbook";
+    code?: string;
+    category?: OrderBookRejectionCategory;
+    message: string;
+    retryable: boolean;
+    retryAfterMs?: number;
+} | {
+    schemaVersion: "v1";
+    kind: "subgraph";
+    message: string;
+} | {
+    schemaVersion: "v1";
+    kind: "signing";
+    message: string;
+} | {
+    schemaVersion: "v1";
+    kind: "appData";
+    class?: string;
+    message: string;
+} | {
+    schemaVersion: "v1";
+    kind: "cancelled";
+    message: string;
+} | {
+    schemaVersion: "v1";
+    kind: "internal";
+    message: string;
+} | {
+    schemaVersion: SchemaVersion;
+    kind: "__unknown";
+    message: string;
+    raw: unknown;
+};
+export declare function normalizeError(raw: unknown): CowError;
+export declare function cancelledError(): CowError;
+export declare function invalidInput(field: string, reason: string): CowError;