SolverHub API

{"alg":"EdDSA","typ":"JWT","kid":1}

interface JwtClaims {
  sub: string; // Assigned solver ID, for example "123".
  aud: string; // Must be "anyflo:solver-hub".
  iat: number; // Integer Unix seconds.
  exp: number; // Integer Unix seconds; iat < exp <= iat + 900.
  jti?: string; // Token identifier, not a per-message replay nonce.
}

mkdir -p solverhub-client
cd solverhub-client
bun init -y
bun add --exact "@anyflo/lib@$LIB_VERSION" cbor-x

import { signJwt } from "@anyflo/lib/auth";
import { fromJwk, type Jwk } from "@anyflo/lib/ed25519";

export async function loadIdentity(): Promise<{
  solverId: number;
  kid: number;
  privateKey: CryptoKey;
}> {
  const id = process.env.SOLVER_ID;
  const secret = process.env.SOLVER_AUTH_PRIVATE_KEY;
  if (!id || !/^[0-9]+$/.test(id) || !secret) {
    throw new Error("SOLVER_ID and SOLVER_AUTH_PRIVATE_KEY are required");
  }
  const solverId = Number(id);
  if (!Number.isSafeInteger(solverId) || solverId <= 0) {
    throw new Error("SOLVER_ID must be a positive safe integer");
  }
  let record: unknown;
  try {
    record = JSON.parse(secret);
  } catch {
    throw new Error("SOLVER_AUTH_PRIVATE_KEY must contain valid JSON");
  }
  if (!record || typeof record !== "object") {
    throw new Error("Invalid authentication key record");
  }
  const { kid, jwk } = record as { kid?: unknown; jwk?: unknown };
  if (typeof kid !== "number" || !Number.isSafeInteger(kid) || kid <= 0 ||
      !jwk || typeof jwk !== "object") {
    throw new Error("A positive integer kid and private JWK are required");
  }
  const key = jwk as Record<string, unknown>;
  if (key.kty !== "OKP" || key.crv !== "Ed25519" ||
      typeof key.x !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(key.x) ||
      typeof key.d !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(key.d)) {
    throw new Error("An Ed25519 private JWK is required");
  }
  let privateKey: CryptoKey;
  try {
    privateKey = await fromJwk(key as Jwk);
  } catch {
    throw new Error("Cannot import authentication private key");
  }
  return { solverId, kid, privateKey };
}

export async function mintJwt(): Promise<string> {
  const { solverId, kid, privateKey } = await loadIdentity();
  return signJwt(solverId, kid, privateKey, 60);
}

if (import.meta.main) {
  try {
    console.log(await mintJwt());
  } catch {
    console.error("JWT generation failed; check identity and key configuration");
    process.exitCode = 1;
  }
}

import type { OrderDetails } from "@anyflo/lib/order";

interface RegisterKeyBody {
  kid: number; // Positive integer; must not have been used before.
  publicKey: {
    kty: "OKP";
    crv: "Ed25519";
    x: string; // Base64url public key. Never include private field d.
  };
}

interface RevokeKeyBody {
  kid?: number; // Positive integer; omission revokes all keys.
}

interface RevokeKeyRes {
  solverId: number;
  revoked: number; // Number of keys revoked.
}

interface ActiveOrdersResp {
  orders: OrderDetails[]; // An empty array is a valid success.
}

{
  "kid": 2,
  "publicKey": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "<base64url public key from the new keypair>"
  }
}

SOLVER_JWT="$(bun run solver-jwt.ts)"
curl --fail-with-body "$HUB_URL/v1/keys" \
  -X POST \
  -H "Authorization: Bearer $SOLVER_JWT" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @new-public-key.json

SOLVER_JWT="$(bun run solver-jwt.ts)"
curl --fail-with-body "$HUB_URL/v1/orders/active" \
  -H "Authorization: Bearer $SOLVER_JWT" \
  -H 'Accept: application/json'

{"orders":[]}

{
  "orders": [{
    "order": {
      "id": "123e4567-e89b-42d3-a456-426614174000",
      "senderId": "123e4567-e89b-42d3-a456-426614174001",
      "recipientId": null,
      "senderAddr": "0x1111111111111111111111111111111111111111",
      "recipientAddr": "0x2222222222222222222222222222222222222222",
      "senderChain": "eip155:84532",
      "recipientChain": "eip155:84532",
      "tokenIn": "0x3333333333333333333333333333333333333333",
      "amountIn": "1000000",
      "tokenOut": "0x3333333333333333333333333333333333333333",
      "amountOut": "998000",
      "typ": 1,
      "status": "selected",
      "solverId": 123,
      "solverAddress": null,
      "directDeposit": false,
      "fee": null,
      "feeRecipient": null,
      "depositExpiresAt": null,
      "createdAt": 1794441600000,
      "updatedAt": 1794441600000
    }
  }]
}

SOLVER_JWT="$(bun run solver-jwt.ts)"
curl --fail-with-body "$HUB_URL/v1/keys/revoke" \
  -X POST \
  -H "Authorization: Bearer $SOLVER_JWT" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"kid":1}'

import { decode } from "cbor-x";
import { FromHubMsgSchema } from "@anyflo/lib/solverhub";
import { mintJwt } from "./solver-jwt";

const configuredUrl = process.env.HUB_WS_URL;
if (!configuredUrl) throw new Error("HUB_WS_URL is required");
const url = new URL(configuredUrl);
if (url.protocol !== "wss:" || url.pathname !== "/connect" ||
    url.username || url.password) {
  throw new Error("HUB_WS_URL must be an assigned WSS /connect URL");
}
const jwt = await mintJwt();
const socket = new WebSocket(url.href, {
  headers: { Authorization: `Bearer ${jwt}` },
});
socket.binaryType = "arraybuffer";
let timer: ReturnType<typeof setInterval> | undefined;
let lastFrameAt = Date.now();
const clearHeartbeat = () => {
  if (timer !== undefined) clearInterval(timer);
  timer = undefined;
};

socket.addEventListener("open", () => {
  lastFrameAt = Date.now();
  console.log("SolverHub connected");
  timer = setInterval(() => {
    if (Date.now() - lastFrameAt > 90_000) {
      clearHeartbeat();
      socket.close(4003, "Heartbeat timeout");
      return;
    }
    if (socket.readyState === WebSocket.OPEN) socket.send("ping");
  }, 30_000);
});
socket.addEventListener("message", (event) => {
  lastFrameAt = Date.now();
  if (event.data === "pong") return;
  if (!(event.data instanceof ArrayBuffer)) {
    console.error("Unexpected non-binary SolverHub frame");
    return;
  }
  try {
    const message = FromHubMsgSchema.parse(decode(new Uint8Array(event.data)));
    console.log("SolverHub message:", message.type);
  } catch {
    console.error("Invalid SolverHub application frame");
  }
});
socket.addEventListener("close", (event) => {
  clearHeartbeat();
  console.log("SolverHub closed; code:", event.code);
});
socket.addEventListener("error", () => {
  clearHeartbeat();
  console.error("SolverHub transport error");
  socket.close();
});

bun run solver-connect.ts

import type { Chain } from "@anyflo/lib/chains";
import type { Order, TxHash } from "@anyflo/lib/order";
import type { UUID } from "@anyflo/lib/uuid";

type FromHubMsg =
  | {
      type: "NewOrder";
      payload: { order: Order; biddingDeadline: number }; // Epoch ms.
    }
  | {
      type: "OrderAssigned";
      payload: { orderId: UUID; winnerId: number; order: Order };
    }
  | {
      type: "OrderDeposit";
      payload: { orderId: UUID; depositTx: TxHash; chain: Chain };
    }
  | {
      type: "OrderDelivery";
      payload: { orderId: UUID; deliverTx: TxHash; chain: Chain };
    }
  | {
      type: "OrderDepositReorged" | "OrderDeliveryReorged";
      payload: {
        orderId: UUID;
        txHash: TxHash;
        chain: Chain;
        blockNumber: number; // Nonnegative integer.
      };
    }
  | {
      type: "OrderReassigned";
      payload: { orderId: UUID; reason: string };
    }
  | {
      type: "OrderCancelled";
      payload: { orderId: UUID; solverId: number; reason: string };
    }
  | {
      type: "BidAck";
      payload: {
        orderId: UUID;
        solverId: number; // Positive integer.
        quote: bigint;
        rank: number;
      };
    }
  | {
      type: "KeyRevoked";
      payload: {
        solverId: number; // Positive integer.
        kid: number | null; // Positive integer; null means all keys.
      };
    }
  | {
      type: "SolverSuspended";
      payload: { solverId: number }; // Positive integer.
    };

import type { TxHash } from "@anyflo/lib/order";
import type { UUID } from "@anyflo/lib/uuid";

type ToHubMsg =
  | {
      type: "Bid";
      payload: {
        orderId: UUID;
        timestamp: number; // Epoch ms.
        quote: bigint; // Positive, in token base units.
        expiresAt: number; // Epoch ms.
        kid: number; // Positive integer.
      };
      sig: Uint8Array; // Signature over the complete payload only.
    }
  | {
      type: "OrderAssignAck";
      payload: {
        orderId: UUID;
        timestamp: number; // Epoch ms.
        solverAddress: string; // Source-chain receiving address.
        directDeposit: boolean;
        kid: number; // Positive integer.
      };
      sig: Uint8Array;
    }
  | {
      type: "OrderAssignNotAck";
      payload: {
        orderId: UUID;
        timestamp: number; // Epoch ms.
        reason: string; // Trimmed length 1–256.
      };
    }
  | {
      type: "OrderDepositAck" | "OrderDepositNotAck" | "OrderDeliveryAck";
      payload: { orderId: UUID; timestamp: number }; // Epoch ms.
    }
  | {
      type: "OrderDeliveryNotAck";
      payload: {
        orderId: UUID;
        timestamp: number; // Epoch ms.
        deliverTx: TxHash;
      };
    };

import { encode } from "cbor-x";
import { deterministicEncode, sign } from "@anyflo/lib/ed25519";
import {
  MsgToHubBidSchema,
  MsgToHubOrderAssignAckSchema,
} from "@anyflo/lib/solverhub";

export async function sendBid(
  socket: WebSocket,
  input: unknown,
  privateKey: CryptoKey,
): Promise<void> {
  if (socket.readyState !== WebSocket.OPEN) throw new Error("Socket is not open");
  const payload = MsgToHubBidSchema.parse(input);
  if (payload.quote <= 0n) throw new Error("Quote must be positive");
  const sig = await sign(privateKey, deterministicEncode(payload));
  if (socket.readyState !== WebSocket.OPEN) throw new Error("Socket closed while signing");
  socket.send(encode({ type: "Bid", payload, sig }));
}

export async function acceptAssignment(
  socket: WebSocket,
  input: unknown,
  privateKey: CryptoKey,
): Promise<void> {
  if (socket.readyState !== WebSocket.OPEN) throw new Error("Socket is not open");
  const payload = MsgToHubOrderAssignAckSchema.parse(input);
  const sig = await sign(privateKey, deterministicEncode(payload));
  if (socket.readyState !== WebSocket.OPEN) throw new Error("Socket closed while signing");
  socket.send(encode({ type: "OrderAssignAck", payload, sig }));
}

import type {
  MsgFromHubNewOrder,
  MsgFromHubOrderAssigned,
} from "@anyflo/lib/solverhub";
import { acceptAssignment, sendBid } from "./solver-commitments";

type Identity = { solverId: number; kid: number; privateKey: CryptoKey };

export async function bidOnReceivedOrder(
  socket: WebSocket,
  received: MsgFromHubNewOrder,
  identity: Identity,
  operatorQuote: bigint,
  operatorQuoteExpiresAt: number,
): Promise<void> {
  const now = Date.now();
  if (now >= received.biddingDeadline || operatorQuoteExpiresAt <= now) {
    throw new Error("Bidding deadline or quote expiry has passed");
  }
  await sendBid(socket, {
    orderId: received.order.id,
    quote: operatorQuote,
    expiresAt: operatorQuoteExpiresAt,
    kid: identity.kid,
    timestamp: now,
  }, identity.privateKey);
}

export async function acceptReceivedAssignment(
  socket: WebSocket,
  received: MsgFromHubOrderAssigned,
  identity: Identity,
  storedBidQuote: bigint,
  solverAddress: string,
  directDeposit: boolean,
): Promise<void> {
  const assignedQuote = received.order.typ === 1
    ? received.order.amountOut : received.order.amountIn;
  if (received.winnerId !== identity.solverId ||
      received.orderId !== received.order.id || assignedQuote !== storedBidQuote) {
    throw new Error("Assignment does not match this solver's stored bid");
  }
  if (!solverAddress.trim()) throw new Error("OrderAssignAck.solverAddress is required");
  await acceptAssignment(socket, {
    orderId: received.orderId,
    solverAddress,
    directDeposit,
    kid: identity.kid,
    timestamp: Date.now(),
  }, identity.privateKey);
}

import { encode } from "cbor-x";
import { ToHubMsgSchema } from "@anyflo/lib/solverhub";

type UnsignedResponse =
  | { type: "OrderAssignNotAck"; reason: string }
  | { type: "OrderDepositAck" | "OrderDepositNotAck" | "OrderDeliveryAck" }
  | { type: "OrderDeliveryNotAck"; deliverTx: string };

export function sendUnsignedResponse(
  socket: WebSocket,
  orderId: string,
  response: UnsignedResponse,
): void {
  if (socket.readyState !== WebSocket.OPEN) throw new Error("Socket is not open");
  const { type, ...fields } = response;
  const message = ToHubMsgSchema.parse({
    type,
    payload: { orderId, timestamp: Date.now(), ...fields },
  });
  socket.send(encode(message));
}

import type { Chain } from "@anyflo/lib/chains";
import type { TxHash } from "@anyflo/lib/order";
import type { UUID } from "@anyflo/lib/uuid";

type OrderStatus =
  | "new"
  | "rejected"
  | "expired"
  | "bidding"
  | "selected"
  | "accepted"
  | "executing"
  | "delivered"
  | "depositNotAck"
  | "deliveredNotAck"
  | "cancelled";

interface Order {
  id: UUID;
  senderId: UUID;
  recipientId: UUID | null;
  senderAddr: string;
  recipientAddr: string; // Destination payout recipient, not the signer.
  senderChain: Chain;
  recipientChain: Chain;
  tokenIn: string;
  amountIn: bigint; // Solver's source receipt, in tokenIn base units.
  tokenOut: string;
  amountOut: bigint; // Payout to recipientAddr, in tokenOut base units.
  typ: 1 | 2; // Fixed input (1): quote output; fixed output (2): quote input.
  status: OrderStatus;
  solverId: number | null;
  solverAddress: string | null; // Source receiving address from OrderAssignAck.
  directDeposit: boolean; // true: direct receipt; false: contract credit.
  fee: bigint | null; // Anyflo fee, not the solver's quote premium.
  feeRecipient: string | null;
  depositExpiresAt: number | null; // Epoch ms.
  createdAt: number; // Epoch ms.
  updatedAt: number; // Epoch ms.
  depositTx?: TxHash | null;
  deliverTx?: TxHash | null;
  reorgedDeliveryTxs?: TxHash[];
  depositReorgedAt?: number | null; // Epoch ms.
}

import type { Order, OrderInstructions, OrderTxs } from "@anyflo/lib/order";

interface OrderDetails {
  order: Order;
  instructions?: OrderInstructions;
  txs?: OrderTxs;
}

interface OrderInstructions {
  target: string; // Deposit target.
  tokens: string[]; // Token identifiers.
  amounts: bigint[]; // Raw token base units.
  fees: bigint[]; // Raw token fee base units.
  directDeposit: boolean;
  solverAddress: string; // Minimum length 3; source-chain receiving address.
  depositExpiresAt: number; // Epoch ms.
  signature: string; // Deposit signature, not a WebSocket sig byte array.
}

import type { TxHash } from "@anyflo/lib/order";

interface OrderTxRef {
  txHash: TxHash; // String, length 1–256.
  timestamp: number; // Indexed on-chain timestamp.
}

interface OrderTxs {
  depositTxs: OrderTxRef[]; // Source deposits.
  deliverTxs: OrderTxRef[]; // Destination payouts.
}