@acta-markets/ts-sdk 0.0.1-beta

package/dist/ws/auth.js

@@ -0,0 +1,98 @@
+/**
+ * WebSocket auth providers.
+ *
+ * RFQ WS auth handshake:
+ * - Server sends `AuthRequest { challenge: <human-readable text> }`
+ * - Client signs UTF-8 bytes of that text and responds:
+ *   `AuthChallenge { challenge, signature: base58(ed25519(utf8(challenge))), pubkey }`
+ *
+ * Source of truth (server):
+ * - rust-backend/rfq-server/src/server/ws.rs
+ * - rust-backend/rfq-server/src/session/handler.rs
+ */
+import { getAddressFromPublicKey } from "@solana/addresses";
+import { createKeyPairFromBytes, createKeyPairFromPrivateKeyBytes, signBytes, } from "@solana/keys";
+import { getBase58Decoder } from "@solana/codecs-strings";
+const bytesToBase58 = (() => {
+    const dec = getBase58Decoder();
+    return (bytes) => dec.decode(bytes);
+})();
+const utf8ToBytes = (value) => new TextEncoder().encode(value);
+/**
+ * Auth provider backed by a `CryptoKeyPair`.
+ *
+ */
+export class KeypairAuthProvider {
+    address;
+    privateKey;
+    constructor(args) {
+        this.address = args.address;
+        this.privateKey = args.privateKey;
+    }
+    /** Create from a Solana CLI-style 64-byte secret key array (private + public). */
+    static async fromSecretKeyBytes(secretKey64) {
+        const keyPair = await createKeyPairFromBytes(secretKey64);
+        const address = await getAddressFromPublicKey(keyPair.publicKey);
+        return new KeypairAuthProvider({ address, privateKey: keyPair.privateKey });
+    }
+    /** Create from a 32-byte private key. */
+    static async fromPrivateKeyBytes(privateKey32) {
+        const keyPair = await createKeyPairFromPrivateKeyBytes(privateKey32);
+        const address = await getAddressFromPublicKey(keyPair.publicKey);
+        return new KeypairAuthProvider({ address, privateKey: keyPair.privateKey });
+    }
+    /** Create from Solana CLI keypair JSON (array of numbers). */
+    static async fromJson(json) {
+        const arr = typeof json === "string" ? JSON.parse(json) : json;
+        return KeypairAuthProvider.fromSecretKeyBytes(Uint8Array.from(arr));
+    }
+    async getPublicKey() {
+        return this.address;
+    }
+    async signChallenge(challenge) {
+        const challengeBytes = utf8ToBytes(challenge);
+        const signatureBytes = await signBytes(this.privateKey, challengeBytes);
+        return bytesToBase58(signatureBytes);
+    }
+}
+/**
+ * Wallet-like provider (browser wallets, custom signers, etc.)
+ *
+ * We intentionally do NOT depend on @solana/web3.js types. Consumers can adapt their wallet
+ * implementation to this minimal interface.
+ */
+export class WalletAuthProvider {
+    wallet;
+    constructor(wallet) {
+        this.wallet = wallet;
+    }
+    async getPublicKey() {
+        const pk = this.wallet.publicKeyBase58 ?? this.wallet.publicKey?.toBase58?.();
+        if (!pk)
+            throw new Error("Wallet not connected (missing public key)");
+        return pk;
+    }
+    async signChallenge(challenge) {
+        const challengeBytes = utf8ToBytes(challenge);
+        // Some wallet APIs expect a mutable `Uint8Array`; codecs return `ReadonlyUint8Array`.
+        const sig = await this.wallet.signMessage(new Uint8Array(challengeBytes));
+        return bytesToBase58(sig);
+    }
+}
+/**
+ * Custom auth provider for fully custom integrations (hardware wallets, remote signers, etc.).
+ */
+export class CustomAuthProvider {
+    getPublicKeyFn;
+    signChallengeFn;
+    constructor(getPublicKey, signChallenge) {
+        this.getPublicKeyFn = getPublicKey;
+        this.signChallengeFn = signChallenge;
+    }
+    async getPublicKey() {
+        return this.getPublicKeyFn();
+    }
+    async signChallenge(challenge) {
+        return this.signChallengeFn(challenge);
+    }
+}

package/dist/ws/client.d.ts

@@ -0,0 +1,263 @@
+/** Acta WebSocket client (rfq-server). */
+import type { AuthProvider } from "./auth";
+import type { SignerLike } from "../chain/orders";
+import type { Address } from "@solana/addresses";
+import type { ActiveRfqInfo, ChainEventMessage, GlobalStats, MarketDescriptorInfo, MarketInfo, MyActiveRfqInfo, MyActiveRfqsMessage, OrderStatusMessage, PositionInfo, QuoteAcknowledgedMessage, QuoteBestStatusMessage, QuoteCancelledMessage, QuoteMessage, QuoteRefreshRequestedMessage, QuoteOutbidMessage, QuoteReceivedMessage, QuoteSelectedMessage, QuotesUpdateMessage, RfqBroadcastMessage, RfqClosedMessage, RfqCreatedMessage, RfqRequestMessage, RfqAvailableAgainMessage, QuoteExpiredMessage, QuoteFilledMessage, IndicativePricesMessage, IndicativePricesRequestMessage, IndicativePricesResponseMessage, GetIndicativePricesMessage, ServerMessage, SnapshotMessage, StatsDelta, SubscriptionsMessage, TokenInfo, TradeInfo, UuidString, VersionMismatchMessage, WelcomeMessage, WsChannel } from "./types";
+export type ConnectionState = "disconnected" | "connecting" | "authenticating" | "authenticated" | "error";
+export type ClientRole = "taker" | "maker";
+export type PendingMessagesOverflowPolicy = "drop_oldest" | "drop_newest" | "throw";
+export type ActaWsClientOptions = {
+    /** Base server URL, e.g. `ws://localhost:8080` (client appends `/ws/{role}`) */
+    url: string;
+    role: ClientRole;
+    /** WS protocol version for Hello/Welcome negotiation (default "1.0.0"). */
+    protocolVersion?: string;
+    /** Optional feature flags to request in Hello. */
+    features?: string[];
+    /** Optional client name for Hello. */
+    clientName?: string;
+    /** Optional client version for Hello. */
+    clientVersion?: string;
+    /**
+     * If true (default), the client will automatically reconnect after disconnects/errors.
+     * Reconnect uses exponential backoff from `reconnectDelay` to `maxReconnectDelay`.
+     */
+    autoReconnect?: boolean;
+    /** Base reconnect delay in ms (default 1000). */
+    reconnectDelay?: number;
+    /** Max reconnect delay in ms (default 30000). */
+    maxReconnectDelay?: number;
+    /** Backoff jitter ratio in [0..1] (default 0.2). */
+    reconnectJitterRatio?: number;
+    /** Ping interval in ms (default 30000). */
+    pingInterval?: number;
+    /** Max queued client messages before Welcome (default 100). */
+    maxPendingMessages?: number;
+    /** Queue overflow policy before Welcome (default "drop_oldest"). */
+    pendingMessagesOverflowPolicy?: PendingMessagesOverflowPolicy;
+    debug?: boolean;
+    /**
+     * Optional socket factory for Node/browser portability.
+     * If omitted, global `WebSocket` will be used when available.
+     */
+    makeSocket?: WebSocketFactory;
+};
+export type ClientState = {
+    stats: GlobalStats | null;
+    activeRfqs: Map<UuidString, ActiveRfqInfo>;
+    myActiveRfqs: Map<UuidString, MyActiveRfqInfo>;
+    positions: Map<string, PositionInfo>;
+    recentTrades: TradeInfo[];
+    markets: Map<string, MarketInfo>;
+};
+export type ActaWsClientEvents = {
+    [event: string]: (...args: any[]) => void;
+    connecting: () => void;
+    connected: () => void;
+    welcome: (msg: WelcomeMessage) => void;
+    versionMismatch: (msg: VersionMismatchMessage) => void;
+    authenticated: (sessionId: string) => void;
+    disconnected: (code: number, reason: string) => void;
+    error: (error: Error) => void;
+    stateChange: (state: ConnectionState) => void;
+    message: (message: ServerMessage) => void;
+    snapshot: (snapshot: SnapshotMessage) => void;
+    positions: (positions: PositionInfo[]) => void;
+    markets: (markets: MarketInfo[]) => void;
+    marketDescriptors: (markets: MarketDescriptorInfo[]) => void;
+    expiries: (expiriesTs: number[]) => void;
+    tokens: (args: {
+        underlyings: TokenInfo[];
+        quotesByUnderlying: Record<string, TokenInfo[]>;
+    }) => void;
+    statsUpdate: (stats: GlobalStats) => void;
+    subscriptions: (msg: SubscriptionsMessage) => void;
+    activeRfqs: (rfqs: ActiveRfqInfo[]) => void;
+    rfqBroadcast: (rfq: RfqBroadcastMessage) => void;
+    rfqCreated: (msg: RfqCreatedMessage) => void;
+    rfqClosed: (msg: RfqClosedMessage) => void;
+    quoteReceived: (quote: QuoteReceivedMessage) => void;
+    quotesUpdate: (update: QuotesUpdateMessage) => void;
+    quoteAcknowledged: (msg: QuoteAcknowledgedMessage) => void;
+    quoteBestStatus: (msg: QuoteBestStatusMessage) => void;
+    quoteOutbid: (msg: QuoteOutbidMessage) => void;
+    quoteRefreshRequested: (msg: QuoteRefreshRequestedMessage) => void;
+    quoteSelected: (msg: QuoteSelectedMessage) => void;
+    quoteFilled: (msg: QuoteFilledMessage) => void;
+    quoteCancelled: (msg: QuoteCancelledMessage) => void;
+    rfqAvailableAgain: (msg: RfqAvailableAgainMessage) => void;
+    quoteExpired: (msg: QuoteExpiredMessage) => void;
+    indicativePrices: (msg: IndicativePricesMessage) => void;
+    indicativePricesRequest: (msg: IndicativePricesRequestMessage) => void;
+    myActiveRfqs: (msg: MyActiveRfqsMessage) => void;
+    orderStatus: (msg: OrderStatusMessage) => void;
+    orderAccepted: (orderId: string) => void;
+    sponsoredTxToSign: (orderId: string, txBase64: string, signatureDeadline: number) => void;
+    orderSubmitted: (orderId: string, txSignature: string) => void;
+    orderConfirmed: (orderId: string, positionPda: string) => void;
+    orderFailed: (orderId: string, reason: string) => void;
+    tradeExecuted: (trade: TradeInfo, delta?: StatsDelta | null) => void;
+    positionUpdated: (position: PositionInfo, updateType: string) => void;
+    marketCreated: (market: MarketInfo) => void;
+    marketFinalized: (marketPda: string, settlementPrice: number) => void;
+    chainEvent: (event: ChainEventMessage) => void;
+    positionOpened: (event: Extract<ChainEventMessage, {
+        event_type: "PositionOpened";
+    }>) => void;
+    makerRegistered: (event: Extract<ChainEventMessage, {
+        event_type: "MakerRegistered";
+    }>) => void;
+    chainMarketCreated: (event: Extract<ChainEventMessage, {
+        event_type: "MarketCreated";
+    }>) => void;
+    chainMarketFinalized: (event: Extract<ChainEventMessage, {
+        event_type: "MarketFinalized";
+    }>) => void;
+    positionSettled: (event: Extract<ChainEventMessage, {
+        event_type: "PositionSettled";
+    }>) => void;
+};
+type EventMap = Record<string, (...args: any[]) => void>;
+declare class TypedEventEmitter<TEvents extends EventMap> {
+    private readonly listeners;
+    on<K extends keyof TEvents>(event: K, listener: TEvents[K]): this;
+    once<K extends keyof TEvents>(event: K, listener: TEvents[K]): this;
+    off<K extends keyof TEvents>(event: K, listener: TEvents[K]): this;
+    removeAllListeners<K extends keyof TEvents>(event?: K): this;
+    protected emit<K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>): boolean;
+}
+export type WebSocketLike = {
+    readonly readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onclose: ((ev: {
+        code?: number;
+        reason?: string;
+    } | unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: string;
+    }) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+};
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents> {
+    private ws;
+    private options;
+    private authProvider;
+    private authRequested;
+    private startAuthSent;
+    private connectionState;
+    private sessionId;
+    private helloSent;
+    private welcomeReceived;
+    private pendingMessages;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private pingTimer;
+    private shouldReconnect;
+    private subscribedChannels;
+    private subscribedMarkets;
+    private hasMarketScope;
+    readonly state: ClientState;
+    constructor(options: ActaWsClientOptions);
+    connectAnonymous(): void;
+    connect(authProvider: AuthProvider): void;
+    connectAndAuthenticate(authProvider: AuthProvider): void;
+    authenticate(authProvider: AuthProvider): Promise<void>;
+    disconnect(): void;
+    getConnectionState(): ConnectionState;
+    isAuthenticated(): boolean;
+    getSessionId(): string | null;
+    createRfq(request: Omit<RfqRequestMessage, "timeout_seconds"> & {
+        timeoutSeconds?: number;
+        clientRequestId?: string;
+    }): Promise<void>;
+    acceptQuote(rfqId: string, maker: Address<string>, orderIdHex: string): Promise<void>;
+    /**
+     * Convenience: build and send `AcceptQuote` from a raw 32-byte `orderId`.
+     */
+    acceptQuoteByOrderId(args: {
+        rfqId: string;
+        maker: Address<string>;
+        orderId: Uint8Array;
+    }): Promise<void>;
+    /**
+     * Submit a partially-signed sponsored transaction back to the server.
+     *
+     * `txBase64` must be a base64-encoded `VersionedTransaction` (v0) signed by the taker.
+     */
+    submitSignedSponsoredTx(args: {
+        orderIdHex: string;
+        txBase64: string;
+    }): Promise<void>;
+    getPositions(): void;
+    getMarkets(): void;
+    getMarketDescriptors(args?: {
+        active_only?: boolean;
+    }): void;
+    getExpiries(args?: {
+        underlying_mint?: Address<string>;
+        quote_mint?: Address<string>;
+        is_put?: boolean | null;
+    }): void;
+    getTokens(args?: {
+        active_only?: boolean;
+    }): void;
+    getMyActiveRfqs(): void;
+    getActiveRfqs(): void;
+    getOrderStatus(orderIdHex: string): void;
+    cancelRfq(rfqId: string): void;
+    submitQuote(quote: QuoteMessage): void;
+    /**
+     * Convenience: sign 32-byte `orderId` and send `Quote`.
+     *
+     * Maker constructs the full on-chain order (incl. nonce), computes `orderId`,
+     * signs it, and sends the signature + orderId over WS.
+     */
+    submitQuoteSigned(args: {
+        rfqId: string;
+        strike: number;
+        price: number;
+        validUntil: number;
+        nonce: number;
+        orderId: Uint8Array;
+        makerSigner: SignerLike;
+    }): Promise<void>;
+    cancelQuote(rfqId: string): void;
+    subscribe(channels: WsChannel[], markets?: string[]): void;
+    unsubscribe(channels: WsChannel[]): void;
+    ping(): void;
+    private doConnect;
+    private handleMessage;
+    /** Taker-only: request current indicative prices for a market + position_type. */
+    getIndicativePrices(req: GetIndicativePricesMessage): void;
+    /** Maker-only: respond to an indicative request (unsigned, non-binding). */
+    sendIndicativePricesResponse(resp: IndicativePricesResponseMessage): void;
+    private handleAuthRequest;
+    private sendStartAuth;
+    private sendHello;
+    private flushPendingMessages;
+    private handleAuthSuccess;
+    private handleAuthError;
+    private handleSnapshot;
+    private handleMyActiveRfqs;
+    private handleOrderStatus;
+    private handlePositions;
+    private handleMarkets;
+    private handleStatsUpdate;
+    private handleTradeExecuted;
+    private handlePositionUpdated;
+    private handleChainEvent;
+    private send;
+    private ensureAuthenticated;
+    private setConnectionState;
+    private startPingInterval;
+    private stopPingInterval;
+    private enqueuePendingMessage;
+    private stopAutoReconnect;
+    private scheduleReconnect;
+    private cleanup;
+    private log;
+}
+export {};

package/dist/ws/client.handshake.integration.test.d.ts

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

package/dist/ws/client.handshake.integration.test.js

@@ -0,0 +1,64 @@
+import WebSocket from "ws";
+import { ActaWsClient } from "./client";
+const wsE2eUrl = process.env.ACTA_WS_E2E_URL;
+const describeIfWsUrl = wsE2eUrl ? describe : describe.skip;
+describeIfWsUrl("ws handshake integration (real backend)", () => {
+    jest.setTimeout(20_000);
+    it("performs Hello -> Welcome without VersionMismatch", async () => {
+        await new Promise((resolve, reject) => {
+            const client = new ActaWsClient({
+                url: wsE2eUrl,
+                role: "taker",
+                autoReconnect: false,
+                makeSocket: (url) => new WebSocket(url),
+            });
+            let settled = false;
+            let welcomeReceived = false;
+            const timeout = setTimeout(() => {
+                finish(new Error("Timed out waiting for Welcome"));
+            }, 15_000);
+            const finish = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                try {
+                    client.disconnect();
+                }
+                catch {
+                    // ignore disconnect cleanup errors in tests
+                }
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            };
+            client.on("welcome", (msg) => {
+                try {
+                    expect(msg.protocol_version).toBe("1.0.0");
+                    welcomeReceived = true;
+                    finish();
+                }
+                catch (err) {
+                    finish(err);
+                }
+            });
+            client.on("versionMismatch", (msg) => {
+                finish(new Error(`Unexpected VersionMismatch: requested=${msg.requested_version} server=${msg.server_version} min=${msg.min_supported_version}`));
+            });
+            client.on("error", (err) => {
+                if (!welcomeReceived) {
+                    finish(err);
+                }
+            });
+            client.on("disconnected", (code, reason) => {
+                if (!welcomeReceived) {
+                    finish(new Error(`Disconnected before Welcome (${code} ${reason})`));
+                }
+            });
+            client.connectAnonymous();
+        });
+    });
+});