@ampvaleo/x402-hyperliquid-server 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,143 @@
+import * as _ampvaleo_x402_hyperliquid_core from '@ampvaleo/x402-hyperliquid-core';
+import { HyperliquidChainName, PaymentRequirements, PaymentPayload, HyperliquidChainConfig } from '@ampvaleo/x402-hyperliquid-core';
+import { Hex, Address } from 'viem';
+import * as express from 'express';
+
+/**
+ * Tracks seen payment nonces to prevent replay. Keys are opaque (e.g. `signer:nonceMs`).
+ */
+interface NonceStore {
+    /** Returns true if the nonce was unused and is now recorded */
+    tryConsume(key: string): Promise<boolean>;
+}
+declare class InMemoryNonceStore implements NonceStore {
+    private readonly used;
+    tryConsume(key: string): Promise<boolean>;
+}
+
+interface BuildRequirementsInput {
+    price: string;
+    payTo: Hex;
+    chain: HyperliquidChainName;
+    /** Full HL token string; defaults to canonical USDC for the chain */
+    token?: string;
+    sourceDex: "spot" | "";
+    destinationDex: "spot" | "";
+    resource: string;
+    description?: string;
+    maxTimeoutSeconds?: number;
+}
+declare function buildPaymentRequirements(input: BuildRequirementsInput): PaymentRequirements;
+
+declare class HyperliquidExchangeError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+interface SubmitOptions {
+    fetch?: typeof fetch;
+}
+/**
+ * Submits a signed sendAsset payment to Hyperliquid's public exchange API.
+ */
+declare function submitToExchange(payload: PaymentPayload, chain: HyperliquidChainConfig, options?: SubmitOptions): Promise<unknown>;
+
+interface SettlementMode {
+    settle: boolean;
+    /**
+     * When true, log a loud warning on each successful verification when settlement is skipped
+     * because `X402_HL_DEV_VERIFY_ONLY=1` was used (not because `settle: false` was passed explicitly).
+     */
+    warnDevVerifyOnlyEachPaidRequest: boolean;
+}
+/**
+ * Throws if `X402_HL_DEV_VERIFY_ONLY=1` is set in production without the explicit escape hatch.
+ * Call once at process startup (e.g. when creating middleware) or before handling traffic.
+ */
+declare function assertDevVerifyOnlyEnvAllowed(): void;
+/**
+ * Resolves whether to POST to Hyperliquid after verification.
+ *
+ * - If `explicitSettle` is set, it wins (no env). No dev-verify warning.
+ * - Otherwise, if `X402_HL_DEV_VERIFY_ONLY=1`, settlement is off and warnings apply (after assert).
+ * - Default: settle (direct mode).
+ */
+declare function resolveSettlementMode(explicitSettle?: boolean): SettlementMode;
+declare const DEV_VERIFY_ONLY_ENV = "X402_HL_DEV_VERIFY_ONLY";
+declare const ALLOW_VERIFY_ONLY_IN_PROD_ENV = "X402_HL_ALLOW_VERIFY_ONLY_IN_PROD";
+
+interface VerifyContext {
+    chain: HyperliquidChainConfig;
+    nonceStore: NonceStore;
+    /** Max age of nonce timestamp in ms from now (default 60_000) */
+    nonceWindowMs?: number;
+    nowMs?: number;
+}
+/**
+ * Verifies EIP-712 signature and that `payload.action` matches server `requirements`.
+ * Does **not** trust `payload.accepted` — compare only against `requirements`.
+ */
+declare function verifyPayment(payload: PaymentPayload, requirements: PaymentRequirements, ctx: VerifyContext): Promise<{
+    valid: true;
+    signer: Address;
+} | {
+    valid: false;
+    error: string;
+}>;
+/**
+ * Detects the case where the client tampers with `accepted` so it no longer reflects
+ * the signed `action` (servers must never rely on `accepted` alone).
+ */
+declare function mismatchesAcceptedAttack(payload: PaymentPayload): boolean;
+declare function assertValidPayment(result: {
+    valid: true;
+    signer: Address;
+} | {
+    valid: false;
+    error: string;
+}): asserts result is {
+    valid: true;
+    signer: Address;
+};
+
+interface X402HyperliquidExpressOptions extends Omit<BuildRequirementsInput, "resource"> {
+    /** Defaults to request URL */
+    resource?: string;
+    nonceStore: NonceStore;
+    nonceWindowMs?: number;
+    /**
+     * When set, forces settlement on/off. When omitted, `X402_HL_DEV_VERIFY_ONLY=1` can disable
+     * settlement for local dev (see `settlementMode.ts`).
+     */
+    settle?: boolean;
+    fetch?: SubmitOptions["fetch"];
+}
+type X402ExpressLocals = {
+    signer: Address;
+    payload: PaymentPayload;
+};
+/** Express middleware — returns 402 + `accepts` when unpaid; verifies + settles (default) when `X-PAYMENT` present */
+declare function x402Hyperliquid(options: X402HyperliquidExpressOptions): (req: express.Request, res: express.Response, next: express.NextFunction) => Promise<void>;
+
+interface X402HyperliquidNextOptions extends Omit<BuildRequirementsInput, "resource"> {
+    resource?: string;
+    nonceStore: NonceStore;
+    nonceWindowMs?: number;
+    settle?: boolean;
+    fetch?: SubmitOptions["fetch"];
+}
+type X402GateResult = {
+    ok: true;
+    signer: Address;
+    payload: _ampvaleo_x402_hyperliquid_core.PaymentPayload;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * App Router / edge-friendly gate: returns a `Response` to return early (402/400/502),
+ * or `{ ok: true, ... }` when the caller should continue the route.
+ */
+declare function runX402HyperliquidGate(request: Request, options: X402HyperliquidNextOptions): Promise<X402GateResult>;
+
+export { ALLOW_VERIFY_ONLY_IN_PROD_ENV, type BuildRequirementsInput, DEV_VERIFY_ONLY_ENV, HyperliquidExchangeError, InMemoryNonceStore, type NonceStore, type SettlementMode, type SubmitOptions, type VerifyContext, type X402ExpressLocals, type X402GateResult, type X402HyperliquidExpressOptions, type X402HyperliquidNextOptions, assertDevVerifyOnlyEnvAllowed, assertValidPayment, buildPaymentRequirements, mismatchesAcceptedAttack, resolveSettlementMode, runX402HyperliquidGate, submitToExchange, verifyPayment, x402Hyperliquid };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import * as _ampvaleo_x402_hyperliquid_core from '@ampvaleo/x402-hyperliquid-core';
+import { HyperliquidChainName, PaymentRequirements, PaymentPayload, HyperliquidChainConfig } from '@ampvaleo/x402-hyperliquid-core';
+import { Hex, Address } from 'viem';
+import * as express from 'express';
+
+/**
+ * Tracks seen payment nonces to prevent replay. Keys are opaque (e.g. `signer:nonceMs`).
+ */
+interface NonceStore {
+    /** Returns true if the nonce was unused and is now recorded */
+    tryConsume(key: string): Promise<boolean>;
+}
+declare class InMemoryNonceStore implements NonceStore {
+    private readonly used;
+    tryConsume(key: string): Promise<boolean>;
+}
+
+interface BuildRequirementsInput {
+    price: string;
+    payTo: Hex;
+    chain: HyperliquidChainName;
+    /** Full HL token string; defaults to canonical USDC for the chain */
+    token?: string;
+    sourceDex: "spot" | "";
+    destinationDex: "spot" | "";
+    resource: string;
+    description?: string;
+    maxTimeoutSeconds?: number;
+}
+declare function buildPaymentRequirements(input: BuildRequirementsInput): PaymentRequirements;
+
+declare class HyperliquidExchangeError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+interface SubmitOptions {
+    fetch?: typeof fetch;
+}
+/**
+ * Submits a signed sendAsset payment to Hyperliquid's public exchange API.
+ */
+declare function submitToExchange(payload: PaymentPayload, chain: HyperliquidChainConfig, options?: SubmitOptions): Promise<unknown>;
+
+interface SettlementMode {
+    settle: boolean;
+    /**
+     * When true, log a loud warning on each successful verification when settlement is skipped
+     * because `X402_HL_DEV_VERIFY_ONLY=1` was used (not because `settle: false` was passed explicitly).
+     */
+    warnDevVerifyOnlyEachPaidRequest: boolean;
+}
+/**
+ * Throws if `X402_HL_DEV_VERIFY_ONLY=1` is set in production without the explicit escape hatch.
+ * Call once at process startup (e.g. when creating middleware) or before handling traffic.
+ */
+declare function assertDevVerifyOnlyEnvAllowed(): void;
+/**
+ * Resolves whether to POST to Hyperliquid after verification.
+ *
+ * - If `explicitSettle` is set, it wins (no env). No dev-verify warning.
+ * - Otherwise, if `X402_HL_DEV_VERIFY_ONLY=1`, settlement is off and warnings apply (after assert).
+ * - Default: settle (direct mode).
+ */
+declare function resolveSettlementMode(explicitSettle?: boolean): SettlementMode;
+declare const DEV_VERIFY_ONLY_ENV = "X402_HL_DEV_VERIFY_ONLY";
+declare const ALLOW_VERIFY_ONLY_IN_PROD_ENV = "X402_HL_ALLOW_VERIFY_ONLY_IN_PROD";
+
+interface VerifyContext {
+    chain: HyperliquidChainConfig;
+    nonceStore: NonceStore;
+    /** Max age of nonce timestamp in ms from now (default 60_000) */
+    nonceWindowMs?: number;
+    nowMs?: number;
+}
+/**
+ * Verifies EIP-712 signature and that `payload.action` matches server `requirements`.
+ * Does **not** trust `payload.accepted` — compare only against `requirements`.
+ */
+declare function verifyPayment(payload: PaymentPayload, requirements: PaymentRequirements, ctx: VerifyContext): Promise<{
+    valid: true;
+    signer: Address;
+} | {
+    valid: false;
+    error: string;
+}>;
+/**
+ * Detects the case where the client tampers with `accepted` so it no longer reflects
+ * the signed `action` (servers must never rely on `accepted` alone).
+ */
+declare function mismatchesAcceptedAttack(payload: PaymentPayload): boolean;
+declare function assertValidPayment(result: {
+    valid: true;
+    signer: Address;
+} | {
+    valid: false;
+    error: string;
+}): asserts result is {
+    valid: true;
+    signer: Address;
+};
+
+interface X402HyperliquidExpressOptions extends Omit<BuildRequirementsInput, "resource"> {
+    /** Defaults to request URL */
+    resource?: string;
+    nonceStore: NonceStore;
+    nonceWindowMs?: number;
+    /**
+     * When set, forces settlement on/off. When omitted, `X402_HL_DEV_VERIFY_ONLY=1` can disable
+     * settlement for local dev (see `settlementMode.ts`).
+     */
+    settle?: boolean;
+    fetch?: SubmitOptions["fetch"];
+}
+type X402ExpressLocals = {
+    signer: Address;
+    payload: PaymentPayload;
+};
+/** Express middleware — returns 402 + `accepts` when unpaid; verifies + settles (default) when `X-PAYMENT` present */
+declare function x402Hyperliquid(options: X402HyperliquidExpressOptions): (req: express.Request, res: express.Response, next: express.NextFunction) => Promise<void>;
+
+interface X402HyperliquidNextOptions extends Omit<BuildRequirementsInput, "resource"> {
+    resource?: string;
+    nonceStore: NonceStore;
+    nonceWindowMs?: number;
+    settle?: boolean;
+    fetch?: SubmitOptions["fetch"];
+}
+type X402GateResult = {
+    ok: true;
+    signer: Address;
+    payload: _ampvaleo_x402_hyperliquid_core.PaymentPayload;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * App Router / edge-friendly gate: returns a `Response` to return early (402/400/502),
+ * or `{ ok: true, ... }` when the caller should continue the route.
+ */
+declare function runX402HyperliquidGate(request: Request, options: X402HyperliquidNextOptions): Promise<X402GateResult>;
+
+export { ALLOW_VERIFY_ONLY_IN_PROD_ENV, type BuildRequirementsInput, DEV_VERIFY_ONLY_ENV, HyperliquidExchangeError, InMemoryNonceStore, type NonceStore, type SettlementMode, type SubmitOptions, type VerifyContext, type X402ExpressLocals, type X402GateResult, type X402HyperliquidExpressOptions, type X402HyperliquidNextOptions, assertDevVerifyOnlyEnvAllowed, assertValidPayment, buildPaymentRequirements, mismatchesAcceptedAttack, resolveSettlementMode, runX402HyperliquidGate, submitToExchange, verifyPayment, x402Hyperliquid };