@acta-markets/ts-sdk 0.0.1-beta

package/dist/idl/hash.d.ts

@@ -0,0 +1 @@
+export declare const ACTA_IDL_SHA256 = "1466fbb647b4c33af315eefbb61e5e572ce14f22f16d050ac2894f8e017aaf66";

package/dist/idl/hash.js

@@ -0,0 +1 @@
+export const ACTA_IDL_SHA256 = "1466fbb647b4c33af315eefbb61e5e572ce14f22f16d050ac2894f8e017aaf66";

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import type { Address } from "@solana/addresses";
+import { ACTA_IDL_SHA256 } from "./idl/hash";
+export * from "./constants";
+export * from "./generated/accounts";
+export * from "./generated/errors";
+export * from "./generated/instructions";
+export * from "./generated/types";
+export * from "./actaClient";
+export * from "./events";
+export * from "./nonce";
+export * as ws from "./ws";
+export * as chain from "./chain";
+export * as types from "./types";
+export { ActaWsClient } from "./ws/client";
+export type { ActaWsClientOptions, ActaWsClientEvents, ClientRole as ActaWsClientRole, ConnectionState as ActaWsConnectionState, ClientState as ActaWsClientState, WebSocketFactory as ActaWsWebSocketFactory, WebSocketLike as ActaWsWebSocketLike, } from "./ws/client";
+export { KeypairAuthProvider, WalletAuthProvider, CustomAuthProvider, } from "./ws/auth";
+export type { AuthProvider, WalletLike } from "./ws/auth";
+export { ActaChainClient } from "./chain/client";
+export type { ChainOptions } from "./chain/client";
+export * from "./chain/tx";
+export declare const ACTA_IDL: {
+    version: string;
+    name: string;
+    instructions: {
+        name: string;
+        accounts: {
+            name: string;
+            isMut: boolean;
+            isSigner: boolean;
+            docs: string[];
+        }[];
+        args: ({
+            name: string;
+            type: string;
+        } | {
+            name: string;
+            type: {
+                array: (string | number)[];
+            };
+        })[];
+        discriminant: {
+            type: string;
+            value: number;
+        };
+    }[];
+    accounts: {
+        name: string;
+        type: {
+            kind: string;
+            fields: ({
+                name: string;
+                type: string;
+            } | {
+                name: string;
+                type: {
+                    array: (string | number)[];
+                };
+            })[];
+        };
+    }[];
+    types: ({
+        name: string;
+        type: {
+            kind: string;
+            variants: {
+                name: string;
+            }[];
+        };
+    } | {
+        name: string;
+        type: {
+            kind: string;
+            variants: {
+                name: string;
+                fields: ({
+                    name: string;
+                    type: string;
+                } | {
+                    name: string;
+                    type: {
+                        array: (string | number)[];
+                    };
+                })[];
+            }[];
+        };
+    })[];
+    metadata: {
+        origin: string;
+        address: string;
+        acta: {
+            events: {
+                version: number;
+                format: string;
+                types: never[];
+                fields: {};
+            };
+        };
+    };
+    errors: {
+        code: number;
+        name: string;
+        msg: string;
+    }[];
+};
+export declare function getActaProgramId(): Address<string>;
+export declare function setActaProgramId(programId: Address<string>): void;
+export declare function clearActaProgramId(): void;
+export declare const ACTA_PROGRAM_ID: Address<string>;
+export { ACTA_IDL_SHA256 };

package/dist/index.js

@@ -0,0 +1,34 @@
+import idl from "./idl/acta_contract.json";
+import { ACTA_IDL_SHA256 } from "./idl/hash";
+import { ACTA_CONTRACT_PROGRAM_ADDRESS } from "./generated/programs";
+export * from "./constants";
+export * from "./generated/accounts";
+export * from "./generated/errors";
+export * from "./generated/instructions";
+export * from "./generated/types";
+export * from "./actaClient";
+export * from "./events";
+export * from "./nonce";
+// New SDK surface (namespaced).
+export * as ws from "./ws";
+export * as chain from "./chain";
+export * as types from "./types";
+export { ActaWsClient } from "./ws/client";
+export { KeypairAuthProvider, WalletAuthProvider, CustomAuthProvider, } from "./ws/auth";
+export { ActaChainClient } from "./chain/client";
+export * from "./chain/tx";
+export const ACTA_IDL = idl;
+// --- Program ID override (useful for tests/devnet deployments) ---
+let PROGRAM_ID_OVERRIDE = null;
+export function getActaProgramId() {
+    return (PROGRAM_ID_OVERRIDE ?? ACTA_CONTRACT_PROGRAM_ADDRESS);
+}
+export function setActaProgramId(programId) {
+    PROGRAM_ID_OVERRIDE = programId;
+}
+export function clearActaProgramId() {
+    PROGRAM_ID_OVERRIDE = null;
+}
+// Default program id exports.
+export const ACTA_PROGRAM_ID = ACTA_CONTRACT_PROGRAM_ADDRESS;
+export { ACTA_IDL_SHA256 };

package/dist/nonce.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Nonce helpers for maker quotes.
+ *
+ * IMPORTANT:
+ * - If you don't pass a seed, the SDK will try to use `crypto.getRandomValues`.
+ * - If no crypto source is available, you MUST provide a 32-byte seed.
+ */
+/**
+ * Xoshiro256++ nonce generator (fast, deterministic).
+ * Seed can be passed explicitly (recommended for reproducibility),
+ * or generated internally if crypto.getRandomValues is available.
+ */
+export declare class NonceGenerator {
+    private s0;
+    private s1;
+    private s2;
+    private s3;
+    private seed;
+    constructor(seed?: Uint8Array);
+    /** Return a copy of the seed used to initialize this generator. */
+    getSeed(): Uint8Array;
+    /** Return next raw u64 (as bigint). */
+    nextU64(): bigint;
+    /**
+     * Return a nonce safe for JSON (`number`).
+     * Uses lower 53 bits to avoid precision loss.
+     */
+    nextNonce(): number;
+}

package/dist/nonce.js

@@ -0,0 +1,89 @@
+/**
+ * Nonce helpers for maker quotes.
+ *
+ * IMPORTANT:
+ * - If you don't pass a seed, the SDK will try to use `crypto.getRandomValues`.
+ * - If no crypto source is available, you MUST provide a 32-byte seed.
+ */
+const MASK_64 = (1n << 64n) - 1n;
+const MAX_SAFE_U64 = (1n << 53n) - 1n;
+const SEED_SIZE = 32;
+function u64(x) {
+    return x & MASK_64;
+}
+function rotl(x, k) {
+    return u64((x << k) | (x >> (64n - k)));
+}
+function readU64LE(bytes, offset) {
+    let out = 0n;
+    for (let i = 7; i >= 0; i--) {
+        out = (out << 8n) | BigInt(bytes[offset + i]);
+    }
+    return out;
+}
+function ensureNonZeroState(state) {
+    if ((state[0] | state[1] | state[2] | state[3]) === 0n) {
+        throw new Error("nonce seed must not be all zeros");
+    }
+}
+function makeSeed() {
+    if (globalThis.crypto?.getRandomValues) {
+        const seed = new Uint8Array(SEED_SIZE);
+        globalThis.crypto.getRandomValues(seed);
+        return seed;
+    }
+    throw new Error("no crypto.getRandomValues available; provide a 32-byte seed explicitly");
+}
+/**
+ * Xoshiro256++ nonce generator (fast, deterministic).
+ * Seed can be passed explicitly (recommended for reproducibility),
+ * or generated internally if crypto.getRandomValues is available.
+ */
+export class NonceGenerator {
+    s0;
+    s1;
+    s2;
+    s3;
+    seed;
+    constructor(seed) {
+        const resolvedSeed = seed ? new Uint8Array(seed) : makeSeed();
+        if (resolvedSeed.length !== SEED_SIZE) {
+            throw new Error(`nonce seed must be 32 bytes, got ${resolvedSeed.length}`);
+        }
+        const state = [
+            readU64LE(resolvedSeed, 0),
+            readU64LE(resolvedSeed, 8),
+            readU64LE(resolvedSeed, 16),
+            readU64LE(resolvedSeed, 24),
+        ];
+        ensureNonZeroState(state);
+        this.s0 = u64(state[0]);
+        this.s1 = u64(state[1]);
+        this.s2 = u64(state[2]);
+        this.s3 = u64(state[3]);
+        this.seed = resolvedSeed;
+    }
+    /** Return a copy of the seed used to initialize this generator. */
+    getSeed() {
+        return new Uint8Array(this.seed);
+    }
+    /** Return next raw u64 (as bigint). */
+    nextU64() {
+        const result = u64(rotl(u64(this.s0 + this.s3), 23n) + this.s0);
+        const t = u64(this.s1 << 17n);
+        this.s2 ^= this.s0;
+        this.s3 ^= this.s1;
+        this.s1 ^= this.s2;
+        this.s0 ^= this.s3;
+        this.s2 ^= t;
+        this.s3 = rotl(this.s3, 45n);
+        return result;
+    }
+    /**
+     * Return a nonce safe for JSON (`number`).
+     * Uses lower 53 bits to avoid precision loss.
+     */
+    nextNonce() {
+        return Number(this.nextU64() & MAX_SAFE_U64);
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./orders";
+export * from "./orderId";

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from "./orders";
+export * from "./orderId";

package/dist/types/orderId.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical OrderId representation across the SDK.
+ *
+ * Contract expects `orderId` as **32 bytes**: `sha256(order_preimage_182)`.
+ *
+ * - In TypeScript we represent it as `Uint8Array` of length 32.
+ * - For JSON/Wire formats we typically use **hex** (64 chars) when needed.
+ */
+export type OrderId32 = Uint8Array;
+export type OrderIdHex32 = string;
+export declare function assertOrderId32(orderId: Uint8Array): asserts orderId is OrderId32;
+export declare function orderIdToHex(orderId: Uint8Array): OrderIdHex32;
+export declare function orderIdFromHex(hex: string): OrderId32;

package/dist/types/orderId.js

@@ -0,0 +1,35 @@
+/**
+ * Canonical OrderId representation across the SDK.
+ *
+ * Contract expects `orderId` as **32 bytes**: `sha256(order_preimage_182)`.
+ *
+ * - In TypeScript we represent it as `Uint8Array` of length 32.
+ * - For JSON/Wire formats we typically use **hex** (64 chars) when needed.
+ */
+export function assertOrderId32(orderId) {
+    if (!(orderId instanceof Uint8Array)) {
+        throw new Error("orderId must be a Uint8Array");
+    }
+    if (orderId.length !== 32) {
+        throw new Error(`orderId must be 32 bytes, got ${orderId.length}`);
+    }
+}
+export function orderIdToHex(orderId) {
+    assertOrderId32(orderId);
+    return Buffer.from(orderId).toString("hex");
+}
+export function orderIdFromHex(hex) {
+    if (typeof hex !== "string") {
+        throw new Error("orderId hex must be a string");
+    }
+    const cleaned = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (cleaned.length !== 64) {
+        throw new Error(`orderId hex must be 64 hex chars (32 bytes), got ${cleaned.length}`);
+    }
+    if (!/^[0-9a-fA-F]+$/.test(cleaned)) {
+        throw new Error("orderId hex contains non-hex characters");
+    }
+    const bytes = Uint8Array.from(Buffer.from(cleaned, "hex"));
+    assertOrderId32(bytes);
+    return bytes;
+}

package/dist/types/orders.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SDK-level order-related *types*.
+ *
+ * These types are shared across on-chain flows and any off-chain tooling that needs
+ * to construct or reason about order preimages / orderIds.
+ *
+ * Implementation lives in `src/chain/orders.ts`.
+ */
+export type { OrderPreimageArgs, OrderSignatureParams, SignerLike, } from "../chain/orders";

package/dist/types/orders.js

@@ -0,0 +1,9 @@
+/**
+ * SDK-level order-related *types*.
+ *
+ * These types are shared across on-chain flows and any off-chain tooling that needs
+ * to construct or reason about order preimages / orderIds.
+ *
+ * Implementation lives in `src/chain/orders.ts`.
+ */
+export {};

package/dist/ws/apy.d.ts

@@ -0,0 +1,79 @@
+/**
+ * APY / annualized premium yield helpers for WS-only frontends.
+ *
+ * Goal: given a quote premium and an option term, compute:
+ * - "how much premium will I receive?" (notional)
+ * - "what is that as APR/APY?" (annualized)
+ *
+ * This is a display metric (premium / collateral), NOT an expected return model.
+ */
+export declare const PRICE_SCALE = 1000000000;
+export declare const SECONDS_PER_YEAR: number;
+export type PositionTypeWire = "covered_call" | "cash_secured_put";
+/** Annualize a term yield over `secondsToExpiry`. */
+export declare function annualizeYield(args: {
+    /** Term yield in [0..] */
+    termYield: number;
+    secondsToExpiry: number;
+}): {
+    apr: number;
+    apy: number;
+};
+/** term_yield = premium_notional / collateral_notional */
+export declare function termYieldFromNotionals(args: {
+    premiumNotional: number;
+    collateralNotional: number;
+}): number;
+/**
+ * Compute premium/collateral notionals and APR/APY from *human unit* amounts.
+ *
+ * Example (your case):
+ * - covered_call
+ * - underlyingAmount = 10 SOL
+ * - spotPrice = 150 USD/SOL  => collateralNotional = 1500 USD
+ * - premiumPerUnderlying = 1.5 USD/SOL => premiumNotional = 15 USD
+ * - 7 days => ~52% APR (simple)
+ */
+export declare function computeApyFromAmounts(args: {
+    positionType: PositionTypeWire;
+    /** underlying amount in human units (e.g. 10 SOL) */
+    underlyingAmount: number;
+    /** premium per 1 underlying in quote units (e.g. USD), gross */
+    premiumPerUnderlying: number;
+    /** for puts: strike price per 1 underlying (quote units) */
+    strikePrice: number;
+    /** for calls: current spot price per 1 underlying (quote units) */
+    spotPrice?: number;
+    /** seconds to option expiry (market expiry, not RFQ TTL) */
+    secondsToExpiry: number;
+}): {
+    premiumNotional: number;
+    collateralNotional: number;
+    termYield: number;
+    apr: number;
+    apy: number;
+};
+/** Convert a 1e9-scaled u64 price into a float price. */
+export declare function scaledPriceToFloat(price1e9: bigint | number): number;
+/**
+ * Convenience wrapper for WS-native numeric fields (1e9-scale).
+ *
+ * - `grossPremiumPerUnit1e9` is WS quote `price`
+ * - `strike1e9` is RFQ/quote strike
+ * - `spotPrice1e9` must be provided for covered_call (from your own spot feed)
+ * - `secondsToExpiry` should be (market.expiry_ts - now)
+ */
+export declare function computeApyFromScaledPrices(args: {
+    positionType: PositionTypeWire;
+    underlyingAmount: number;
+    grossPremiumPerUnit1e9: bigint | number;
+    strike1e9: bigint | number;
+    spotPrice1e9?: bigint | number;
+    secondsToExpiry: number;
+}): {
+    premiumNotional: number;
+    collateralNotional: number;
+    termYield: number;
+    apr: number;
+    apy: number;
+};

package/dist/ws/apy.js

@@ -0,0 +1,98 @@
+/**
+ * APY / annualized premium yield helpers for WS-only frontends.
+ *
+ * Goal: given a quote premium and an option term, compute:
+ * - "how much premium will I receive?" (notional)
+ * - "what is that as APR/APY?" (annualized)
+ *
+ * This is a display metric (premium / collateral), NOT an expected return model.
+ */
+export const PRICE_SCALE = 1_000_000_000;
+export const SECONDS_PER_YEAR = 365 * 24 * 60 * 60;
+/** Annualize a term yield over `secondsToExpiry`. */
+export function annualizeYield(args) {
+    const y = args.termYield;
+    const dt = args.secondsToExpiry;
+    if (!Number.isFinite(y) || y < 0)
+        throw new Error("invalid termYield");
+    if (!Number.isFinite(dt) || dt <= 0)
+        return { apr: 0, apy: 0 };
+    const yearOverDt = SECONDS_PER_YEAR / dt;
+    const apr = y * yearOverDt;
+    const apy = Math.pow(1 + y, yearOverDt) - 1;
+    return { apr, apy };
+}
+/** term_yield = premium_notional / collateral_notional */
+export function termYieldFromNotionals(args) {
+    const p = args.premiumNotional;
+    const c = args.collateralNotional;
+    if (!Number.isFinite(p) || p < 0)
+        throw new Error("invalid premiumNotional");
+    if (!Number.isFinite(c) || c <= 0)
+        throw new Error("invalid collateralNotional");
+    return p / c;
+}
+/**
+ * Compute premium/collateral notionals and APR/APY from *human unit* amounts.
+ *
+ * Example (your case):
+ * - covered_call
+ * - underlyingAmount = 10 SOL
+ * - spotPrice = 150 USD/SOL  => collateralNotional = 1500 USD
+ * - premiumPerUnderlying = 1.5 USD/SOL => premiumNotional = 15 USD
+ * - 7 days => ~52% APR (simple)
+ */
+export function computeApyFromAmounts(args) {
+    const qty = args.underlyingAmount;
+    if (!Number.isFinite(qty) || qty <= 0)
+        throw new Error("invalid underlyingAmount");
+    const premPU = args.premiumPerUnderlying;
+    if (!Number.isFinite(premPU) || premPU < 0)
+        throw new Error("invalid premiumPerUnderlying");
+    const premiumNotional = qty * premPU;
+    let collateralPerUnderlying;
+    if (args.positionType === "cash_secured_put") {
+        collateralPerUnderlying = args.strikePrice;
+    }
+    else {
+        collateralPerUnderlying = args.spotPrice ?? NaN;
+    }
+    if (!Number.isFinite(collateralPerUnderlying) || collateralPerUnderlying <= 0) {
+        throw new Error(args.positionType === "covered_call"
+            ? "spotPrice is required for covered_call yield"
+            : "invalid strikePrice");
+    }
+    const collateralNotional = qty * collateralPerUnderlying;
+    const termYield = termYieldFromNotionals({ premiumNotional, collateralNotional });
+    const { apr, apy } = annualizeYield({ termYield, secondsToExpiry: args.secondsToExpiry });
+    return { premiumNotional, collateralNotional, termYield, apr, apy };
+}
+function toNum(v) {
+    // Note: bigint->number can lose precision for huge values; acceptable for UI display.
+    return typeof v === "bigint" ? Number(v) : v;
+}
+/** Convert a 1e9-scaled u64 price into a float price. */
+export function scaledPriceToFloat(price1e9) {
+    const n = toNum(price1e9);
+    if (!Number.isFinite(n))
+        throw new Error("invalid price1e9");
+    return n / PRICE_SCALE;
+}
+/**
+ * Convenience wrapper for WS-native numeric fields (1e9-scale).
+ *
+ * - `grossPremiumPerUnit1e9` is WS quote `price`
+ * - `strike1e9` is RFQ/quote strike
+ * - `spotPrice1e9` must be provided for covered_call (from your own spot feed)
+ * - `secondsToExpiry` should be (market.expiry_ts - now)
+ */
+export function computeApyFromScaledPrices(args) {
+    return computeApyFromAmounts({
+        positionType: args.positionType,
+        underlyingAmount: args.underlyingAmount,
+        premiumPerUnderlying: scaledPriceToFloat(args.grossPremiumPerUnit1e9),
+        strikePrice: scaledPriceToFloat(args.strike1e9),
+        spotPrice: args.spotPrice1e9 == null ? undefined : scaledPriceToFloat(args.spotPrice1e9),
+        secondsToExpiry: args.secondsToExpiry,
+    });
+}

package/dist/ws/apy.test.d.ts

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

package/dist/ws/apy.test.js

@@ -0,0 +1,27 @@
+import { computeApyFromAmounts, computeApyFromScaledPrices } from "./apy";
+describe("ws apy helpers", () => {
+    it("matches the intuitive 10 SOL @ $150, $15 premium, 7 days => ~52% APR", () => {
+        const res = computeApyFromAmounts({
+            positionType: "covered_call",
+            underlyingAmount: 10,
+            spotPrice: 150,
+            strikePrice: 150, // not used for calls
+            premiumPerUnderlying: 1.5,
+            secondsToExpiry: 7 * 24 * 60 * 60,
+        });
+        expect(res.premiumNotional).toBeCloseTo(15, 10);
+        expect(res.collateralNotional).toBeCloseTo(1500, 10);
+        expect(res.termYield).toBeCloseTo(0.01, 10);
+        expect(res.apr).toBeCloseTo(0.01 * (365 / 7), 3);
+    });
+    it("scaled wrapper works (1e9 scale)", () => {
+        const res = computeApyFromScaledPrices({
+            positionType: "cash_secured_put",
+            underlyingAmount: 10,
+            grossPremiumPerUnit1e9: 1_500_000_000, // 1.5
+            strike1e9: 150_000_000_000, // 150
+            secondsToExpiry: 7 * 24 * 60 * 60,
+        });
+        expect(res.premiumNotional).toBeCloseTo(15, 10);
+    });
+});

package/dist/ws/auth.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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
+ */
+export interface AuthProvider {
+    /** Base58-encoded public key (address). */
+    getPublicKey(): Promise<string>;
+    /** Base58-encoded ed25519 signature over UTF-8 bytes of the challenge text. */
+    signChallenge(challenge: string): Promise<string>;
+}
+/**
+ * Auth provider backed by a `CryptoKeyPair`.
+ *
+ */
+export declare class KeypairAuthProvider implements AuthProvider {
+    private readonly address;
+    private readonly privateKey;
+    private constructor();
+    /** Create from a Solana CLI-style 64-byte secret key array (private + public). */
+    static fromSecretKeyBytes(secretKey64: Uint8Array): Promise<KeypairAuthProvider>;
+    /** Create from a 32-byte private key. */
+    static fromPrivateKeyBytes(privateKey32: Uint8Array): Promise<KeypairAuthProvider>;
+    /** Create from Solana CLI keypair JSON (array of numbers). */
+    static fromJson(json: number[] | string): Promise<KeypairAuthProvider>;
+    getPublicKey(): Promise<string>;
+    signChallenge(challenge: string): Promise<string>;
+}
+/**
+ * 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 declare class WalletAuthProvider implements AuthProvider {
+    private readonly wallet;
+    constructor(wallet: WalletLike);
+    getPublicKey(): Promise<string>;
+    signChallenge(challenge: string): Promise<string>;
+}
+export type WalletLike = {
+    /** Preferred: base58 address string. */
+    publicKeyBase58?: string | null;
+    /** Optional: object exposing `toBase58()` (no web3.js import needed). */
+    publicKey?: {
+        toBase58(): string;
+    } | null;
+    /** Returns raw 64-byte signature. */
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+};
+/**
+ * Custom auth provider for fully custom integrations (hardware wallets, remote signers, etc.).
+ */
+export declare class CustomAuthProvider implements AuthProvider {
+    private readonly getPublicKeyFn;
+    private readonly signChallengeFn;
+    constructor(getPublicKey: () => Promise<string>, signChallenge: (challenge: string) => Promise<string>);
+    getPublicKey(): Promise<string>;
+    signChallenge(challenge: string): Promise<string>;
+}