@acta-markets/ts-sdk 0.0.1-beta

package/README.md

@@ -0,0 +1,308 @@
+# Acta TypeScript SDK
+
+Generated by Codama.
+
+- On-chain utilities live under `src/chain` (PDA helpers, instruction builders, fetchers, token helpers, tx sending).
+- WebSocket client lives under `src/ws` (canonical RFQ-server protocol).
+- `ActaClient` is the unified facade that optionally composes `ws` and/or `chain`.
+
+## Package
+
+Published package: **`@acta-markets/ts-sdk-v1@0.0.9-beta`** (ESM-first, CJS fallback)
+
+```bash
+yarn add @acta-markets/ts-sdk-v1@0.0.9-beta
+```
+
+## Tooling
+
+- `yarn install`
+- `yarn gen:codama` – regenerate `src/generated` from `src/idl/acta_contract.json`.
+- `yarn build` – runs codegen then `tsc`.
+- `yarn test` – Jest (offset/order encoding, order helpers).
+
+## Exposed helpers
+
+- `chain/helpers.ts`: `findConfigPda`, `findMakerPda`, `findMarketPda`, `findPositionPda`.
+- `chain/orders.ts`:
+  - `computeOrderId` / `encodeOrderPreimage` — compute `orderId = sha256(preimage)` (32 bytes).
+  - `orderSignatureInstruction` / `signOrderInstruction` — build Ed25519 verify instructions (sign **32-byte orderId** for on-chain use).
+- `nonce.ts`: `NonceGenerator` — deterministic Xoshiro256++ nonce generator for makers (seed optional; uses `crypto.getRandomValues` if available).
+- `chain/fetch.ts`: GPA helpers via `createSolanaRpc` + memcmp offsets; decoded accessors for markets/positions/config.
+- `ws/client.ts`: `ActaWsClient` (auth challenge, reconnect/backoff, ping, local state, ChainEvent).
+
+All instructions/codecs are in `src/generated/instructions` (Codama @solana/kit style); program id exported as `ACTA_PROGRAM_ID` and `getActaProgramId()` from `src/index.ts`.
+
+## Facade: ActaClient
+
+You can instantiate WS-only, chain-only, or both:
+
+```ts
+import { ActaClient } from "@acta-markets/ts-sdk-v1";
+
+// WS-only
+const c1 = new ActaClient({ ws: { url: "wss://...", role: "taker" } });
+
+// Chain-only
+const c2 = new ActaClient({ chain: { rpc, rpcSubscriptions, payer } });
+```
+
+## Web app quickstart (taker-only)
+
+### 1) Connect to WS anonymously, then authenticate on “Connect wallet”
+
+```ts
+import { ActaClient } from "@acta-markets/ts-sdk-v1";
+import { WalletAuthProvider } from "@acta-markets/ts-sdk-v1/ws";
+
+const client = new ActaClient({ ws: { url: "wss://localhost:8080", role: "taker" } });
+const auth = new WalletAuthProvider({
+  publicKeyBase58: walletPublicKeyBase58,
+  signMessage: async (msg: Uint8Array) => wallet.signMessage(msg),
+});
+
+// No wallet prompt:
+client.ws!.connectAnonymous();
+
+// Later, on “Connect wallet” button:
+await client.ws!.authenticate(auth);
+client.ws!.on("snapshot", (s) => console.log("snapshot", s));
+client.ws!.on("chainEvent", (e) => console.log("chain event", e));
+```
+
+#### Auth providers (why there are multiple)
+
+- **`WalletAuthProvider`**: browser wallets (Phantom/Privy/etc.) that support `signMessage` (typical web integration).
+- **`KeypairAuthProvider`**: Node scripts/CI/bots where you load a local keypair (e.g. from `KEYPAIR_PATH`).
+- **`CustomAuthProvider`**: advanced integrations (remote signers, hardware wallets, nonstandard wallet APIs).
+- **`AuthProvider` (type)**: shared interface the WS client accepts.
+- **`WalletLike` (type)**: minimal wallet adapter shape (no dependency on wallet-adapter / web3.js types).
+
+### Markets + positions without on-chain RPC (WS convenience)
+
+```ts
+client.ws!.on("markets", (markets) => console.log("markets", markets));
+client.ws!.on("positions", (positions) => console.log("positions", positions));
+
+client.ws!.getMarkets();
+// positions require auth:
+// client.ws!.getPositions();
+```
+
+### RFQ → accept quote → sign sponsored tx (wallet UX)
+
+```ts
+// 1) Request RFQ
+client.ws!.createRfq({
+  market: marketPdaBase58,
+  position_type: "cash_secured_put",
+  strike: 136_000_000_000,
+  quantity: 20_000_000,
+  timeoutSeconds: 31,
+});
+
+// RFQ window is short-lived. If it expires, server sends Error.code="rfq_expired".
+// To get fresh quotes, you must send a new createRfq (new rfq_id).
+
+// 2) Pick a quote and accept it
+client.ws!.on("quoteReceived", (q) => {
+  // ... render / pick best quote
+});
+await client.ws!.acceptQuote(rfqId, makerPubkeyBase58, orderIdHex32);
+
+// If accept is rejected with Error.code="quote_expired" or "quote_refresh_required",
+// backend asked maker to refresh. Wait for a refreshed QuoteReceived (new order_id) and accept that.
+
+// 3) Backend sends a v0 tx template (fee payer signature missing).
+//    Use wallet.signTransaction so the user sees preview/simulation UX.
+client.ws!.on("sponsoredTxToSign", async (orderIdHex, txBase64, signatureDeadline) => {
+  // If your wallet exposes `signTransaction` (Phantom/Privy via adapters), you can use it.
+  // Alternatively (lighter): sign the **message bytes** and fill signature slot 1.
+  const signedTxBase64 = await import("@acta-markets/ts-sdk-v1/ws").then(({ signSponsoredTxBase64 }) =>
+    signSponsoredTxBase64({
+      txBase64,
+      taker: { signMessage: (msg: Uint8Array) => wallet.signMessage(msg) },
+      takerSignatureIndex: 1,
+    })
+  );
+
+  await client.ws!.submitSignedSponsoredTx({ orderIdHex, txBase64: signedTxBase64 });
+});
+```
+
+### Handling server errors (RFQ/quote lifecycle)
+
+The server sends structured error messages:
+
+```json
+{ "type": "Error", "data": { "code": "string", "message": "string" } }
+```
+
+In the SDK you can listen to raw messages to branch on `code`:
+
+```ts
+client.ws!.on("message", (m) => {
+  if (m.type !== "Error") return;
+  switch (m.data.code) {
+    case "rfq_expired":
+      // show “quotes expired” and offer a “Retry RFQ” button
+      break;
+    case "quote_expired":
+    case "quote_refresh_required":
+      // wait for refreshed QuoteReceived (new order_id) and accept again
+      break;
+  }
+});
+```
+
+### APR/APY (annualized premium yield) from quotes
+
+Frontends often want to display a simple “premium yield” as an annualized percentage.
+Given:
+
+- `price` = gross premium per 1 underlying (1e9 scale)
+- `strike` = price per 1 underlying (1e9 scale)
+- `market.expiry_ts` = option expiry (unix seconds)
+
+The **term yield** (not annualized) is:
+
+- cash-secured put: `term_yield = price / strike`
+- covered call: `term_yield = price / spot_price` (requires current spot price \(S\))
+
+Then annualize using time to expiry \(dt = expiry\_ts - now\):
+
+- APR (simple): `apr = term_yield * (seconds_per_year / dt)`
+- APY (compounded): `apy = (1 + term_yield)^(seconds_per_year / dt) - 1`
+
+TS SDK helper (WS-only, no on-chain RPC needed):
+
+```ts
+import { ws } from "@acta-markets/ts-sdk-v1";
+
+const secondsToExpiry = rfq.market.expiry_ts - Math.floor(Date.now() / 1000);
+
+// Example: if you already render quantity as “10 SOL”, pass underlyingAmount=10.
+const { apr, apy, premiumNotional } = ws.computeApyFromScaledPrices({
+  positionType: "cash_secured_put",
+  underlyingAmount: 10,
+  grossPremiumPerUnit1e9: quote.price, // u64, 1e9 scale
+  strike1e9: rfq.strike,               // u64, 1e9 scale
+  secondsToExpiry,
+});
+```
+
+Note:
+- This is a **display metric** (premium / collateral annualized), not a promise of “guaranteed yield”.
+- For covered calls you also need `spotPrice1e9` (from your own spot feed) to value collateral in quote units.
+
+### Chain flow helpers
+
+Build the minimal instruction set for `open_position` (maker ed25519 verify + open ix):
+
+```ts
+import { chain } from "@acta-markets/ts-sdk-v1";
+
+const built = await chain.flows.buildOpenPositionFlowIxs({
+  underlyingMint,
+  quoteMint,
+  expiryTs,
+  isPut,
+  positionType,
+  strike,
+  quantity,
+  price,
+  validUntil,
+  nonce,
+  user,
+  makerOwner,
+  makerQuoteSigning,
+  makerSigner,
+  keeper: user,
+});
+
+// built.ixs = [makerSigIx, openPositionIx]
+// then: client.chain!.tx.sendAndConfirmIxs({ ixs: built.ixs, ... })
+```
+
+## Program ID override
+
+By default the SDK targets the mainnet deployment program id exported from `src/generated/programs`.
+For tests/devnet you can override it at runtime:
+
+```ts
+import { setActaProgramId, clearActaProgramId } from "@acta-markets/ts-sdk-v1";
+// setActaProgramId("...devnet program id..." as Address<string>);
+// clearActaProgramId();
+```
+
+## Recipe: open_position (hash-based orderId)
+
+On-chain expects an **Ed25519 verify instruction** (maker) immediately followed by `open_position`, where the signature signs the same **32-byte `orderId`**:
+
+```ts
+import { randomBytes } from "crypto";
+import { Address } from "@solana/addresses";
+import { PositionType } from "@acta-markets/ts-sdk-v1";
+import {
+  computeOrderId,
+  orderSignatureInstruction,
+  findMarketPda,
+  findPositionPda,
+  buildOpenPositionIx,
+} from "@acta-markets/ts-sdk-v1/chain";
+
+const nonce = Buffer.from(randomBytes(8)).readBigUInt64LE(0);
+const orderId = computeOrderId({
+  isTakerBuy: false,
+  positionType: PositionType.CoveredCall,
+  market: marketPda,          // PDA of the market you will open against
+  strike,
+  quantity,
+  price: grossPerUnit,        // gross per-unit (1e9 scale)
+  validUntil,
+  maker: makerOwner,
+  taker: user,
+  nonce,
+});
+
+const positionPda = await findPositionPda({ orderId });
+
+// makerSig is a 64-byte Ed25519 signature over `orderId` (NOT over the preimage).
+const makerSigIx = orderSignatureInstruction({
+  publicKey: makerQuoteSigning,
+  signature: makerSig,
+  message: orderId,
+});
+
+const openIx = await buildOpenPositionIx({
+  keeper,
+  user,
+  makerOwner,
+  underlyingMint,
+  quoteMint,
+  premiumMint: quoteMint,
+  positionType: PositionType.CoveredCall,
+  strike,
+  quantity,
+  price: grossPerUnit,
+  validUntil,
+  nonce,
+  orderId,
+  isPut,
+  expiryTs,
+  configPda, // optional; derived from premium mint if omitted
+});
+
+// Send [makerSigIx, openIx] in one tx (plus any ATA/setup ixs you need).
+```
+
+## OrderId rules (SDK-wide)
+
+- **Canonical**: `orderId` is always **32 bytes** (`sha256(preimage182)`), same as the on-chain program expects.
+- **In code**: use `Uint8Array(32)` everywhere.
+- **JSON / WS wire**: when `order_id` must be a string, it is **64-char hex** (32 bytes). SDK flow helpers handle encoding/decoding for you.
+
+## WS order status events
+
+Events: `orderAccepted/orderSubmitted/orderConfirmed/orderFailed` carry `orderId: string`.
+In this SDK the string is **64-char hex** (i.e. a **32-byte orderId**, sha256).

package/dist/actaClient.d.ts

@@ -0,0 +1,46 @@
+import { ActaChainClient, type ChainOptions } from "./chain";
+import { ActaWsClient, type ActaWsClientOptions } from "./ws";
+import type { AuthProvider } from "./ws/auth";
+export type ActaClientOptions = {
+    /**
+     * Optional on-chain component.
+     * - If provided, `client.chain` is constructed immediately.
+     * - If omitted, on-chain features are unavailable until `createChain()`.
+     */
+    chain?: ChainOptions;
+    /**
+     * Optional WS component (RFQ server).
+     * - If provided, `client.ws` is constructed immediately (but not connected).
+     * - Call `client.connectWs(authProvider)` or `client.ws.connect(authProvider)` to start.
+     */
+    ws?: ActaWsClientOptions;
+};
+/**
+ * Unified Acta client facade.
+ *
+ * - `client.chain` is optional (on-chain only usage is supported)
+ * - `client.ws` is optional (ws-only usage is supported)
+ */
+export declare class ActaClient {
+    chain?: ActaChainClient;
+    ws?: ActaWsClient;
+    private chainOpts?;
+    private wsOpts?;
+    constructor(opts?: ActaClientOptions);
+    createChain(opts: ChainOptions): this;
+    updateChain(patch: Partial<ChainOptions>): this;
+    createWs(opts: ActaWsClientOptions): this;
+    updateWs(patch: Partial<ActaWsClientOptions>): this;
+    /** Throw if `chain` is not configured, otherwise return it (for ergonomic call sites). */
+    assertChain(): ActaChainClient;
+    /** Throw if `ws` is not configured, otherwise return it (for ergonomic call sites). */
+    assertWs(): ActaWsClient;
+    /** Convenience: `client.connectWs(auth)` instead of `client.ws!.connect(auth)`. */
+    connectWs(authProvider: AuthProvider): this;
+    /** Convenience: connect and trigger auth flow in one call. */
+    connectWsAndAuthenticate(authProvider: AuthProvider): this;
+    /** Convenience: connect WS without triggering auth (anonymous browsing). */
+    connectWsAnonymous(): this;
+    /** Convenience: disconnect WS (and stop reconnect timers). */
+    disconnectWs(): this;
+}

package/dist/actaClient.js

@@ -0,0 +1,99 @@
+import { ActaChainClient } from "./chain";
+import { ActaWsClient } from "./ws";
+/**
+ * Unified Acta client facade.
+ *
+ * - `client.chain` is optional (on-chain only usage is supported)
+ * - `client.ws` is optional (ws-only usage is supported)
+ */
+export class ActaClient {
+    chain;
+    ws;
+    chainOpts;
+    wsOpts;
+    constructor(opts = {}) {
+        if (opts.chain)
+            this.createChain(opts.chain);
+        if (opts.ws)
+            this.createWs(opts.ws);
+    }
+    createChain(opts) {
+        this.chainOpts = opts;
+        this.chain = new ActaChainClient(opts);
+        return this;
+    }
+    updateChain(patch) {
+        if (!this.chainOpts) {
+            throw new Error("Cannot update chain: chain is not configured");
+        }
+        const next = {
+            ...this.chainOpts,
+            ...patch,
+            ...(Object.prototype.hasOwnProperty.call(patch, "rpcSubscriptions")
+                ? { rpcSubscriptions: patch.rpcSubscriptions }
+                : null),
+        };
+        return this.createChain(next);
+    }
+    createWs(opts) {
+        this.wsOpts = opts;
+        // If a previous instance exists, ensure it's not reconnecting anymore.
+        if (this.ws) {
+            try {
+                this.ws.disconnect();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.ws = new ActaWsClient(opts);
+        return this;
+    }
+    updateWs(patch) {
+        if (!this.wsOpts) {
+            throw new Error("Cannot update ws: ws is not configured");
+        }
+        const next = {
+            ...this.wsOpts,
+            ...patch,
+            ...(Object.prototype.hasOwnProperty.call(patch, "makeSocket")
+                ? { makeSocket: patch.makeSocket }
+                : null),
+        };
+        return this.createWs(next);
+    }
+    /** Throw if `chain` is not configured, otherwise return it (for ergonomic call sites). */
+    assertChain() {
+        if (!this.chain) {
+            throw new Error("chain is not configured on this ActaClient instance");
+        }
+        return this.chain;
+    }
+    /** Throw if `ws` is not configured, otherwise return it (for ergonomic call sites). */
+    assertWs() {
+        if (!this.ws) {
+            throw new Error("ws is not configured on this ActaClient instance");
+        }
+        return this.ws;
+    }
+    /** Convenience: `client.connectWs(auth)` instead of `client.ws!.connect(auth)`. */
+    connectWs(authProvider) {
+        this.assertWs().connect(authProvider);
+        return this;
+    }
+    /** Convenience: connect and trigger auth flow in one call. */
+    connectWsAndAuthenticate(authProvider) {
+        this.assertWs().connectAndAuthenticate(authProvider);
+        return this;
+    }
+    /** Convenience: connect WS without triggering auth (anonymous browsing). */
+    connectWsAnonymous() {
+        this.assertWs().connectAnonymous();
+        return this;
+    }
+    /** Convenience: disconnect WS (and stop reconnect timers). */
+    disconnectWs() {
+        this.ws?.disconnect();
+        return this;
+    }
+}

package/dist/chain/client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Acta on-chain client wrapper.
+ *
+ * This is a thin "composition" layer that:
+ * - stores rpc/rpcSubscriptions + default payer
+ * - exposes existing helpers/builders/fetchers under a single namespace
+ * - provides tx execution helpers (`tx.send*`)
+ */
+import type { TransactionSigner } from "@solana/kit";
+import type { Commitment } from "@solana/rpc-types";
+import type { createSolanaRpc } from "@solana/rpc";
+import type { createSolanaRpcSubscriptions } from "@solana/rpc-subscriptions";
+import type { Instruction } from "@solana/instructions";
+import * as helpers from "./helpers";
+import * as instructions from "./instructions";
+import * as fetch from "./fetch";
+import * as orders from "./orders";
+import * as token from "./token";
+import { type Rpc, type RpcSubscriptions, type SendOptions, type SignedTxWithLifetime } from "./tx";
+export type ChainOptions = {
+    rpc: ReturnType<typeof createSolanaRpc>;
+    rpcSubscriptions?: ReturnType<typeof createSolanaRpcSubscriptions>;
+    payer: TransactionSigner<string>;
+    commitment?: Commitment;
+};
+export declare class ActaChainClient {
+    readonly rpc: Rpc;
+    readonly rpcSubscriptions?: RpcSubscriptions;
+    readonly payer: TransactionSigner<string>;
+    readonly commitment: Commitment;
+    readonly helpers: typeof helpers;
+    readonly instructions: typeof instructions;
+    readonly fetch: typeof fetch;
+    readonly orders: typeof orders;
+    readonly token: typeof token;
+    constructor(opts: ChainOptions);
+    /**
+     * Transaction helpers.
+     *
+     * - `buildAndSignIxs`: returns a signed tx and the deterministic signature.
+     * - `sendSigned`: send without confirmation.
+     * - `sendAndConfirmSigned`: send + confirm (requires `rpcSubscriptions`).
+     * - `sendAndConfirmIxs`: build+sign+send+confirm (requires `rpcSubscriptions`).
+     */
+    readonly tx: {
+        buildAndSignIxs: (args: {
+            ixs: Instruction[];
+            signers?: TransactionSigner<string>[];
+            commitment?: Commitment;
+        }) => Promise<SignedTxWithLifetime>;
+        sendSigned: (args: {
+            signed: SignedTxWithLifetime;
+            options?: SendOptions;
+        }) => Promise<string>;
+        sendAndConfirmSigned: (args: {
+            signed: SignedTxWithLifetime;
+            options?: SendOptions;
+        }) => Promise<string>;
+        sendAndConfirmIxs: (args: {
+            ixs: Instruction[];
+            signers?: TransactionSigner<string>[];
+            options?: SendOptions;
+        }) => Promise<string>;
+    };
+}

package/dist/chain/client.js

@@ -0,0 +1,82 @@
+/**
+ * Acta on-chain client wrapper.
+ *
+ * This is a thin "composition" layer that:
+ * - stores rpc/rpcSubscriptions + default payer
+ * - exposes existing helpers/builders/fetchers under a single namespace
+ * - provides tx execution helpers (`tx.send*`)
+ */
+import * as helpers from "./helpers";
+import * as instructions from "./instructions";
+import * as fetch from "./fetch";
+import * as orders from "./orders";
+import * as token from "./token";
+import { buildAndSignTransactionFromIxs, sendAndConfirmIxs, sendAndConfirmSignedTransaction, sendSignedTransaction, } from "./tx";
+export class ActaChainClient {
+    rpc;
+    rpcSubscriptions;
+    payer;
+    commitment;
+    // Re-export existing modules for convenience.
+    helpers = helpers;
+    instructions = instructions;
+    fetch = fetch;
+    orders = orders;
+    token = token;
+    constructor(opts) {
+        this.rpc = opts.rpc;
+        this.rpcSubscriptions = opts.rpcSubscriptions;
+        this.payer = opts.payer;
+        this.commitment = opts.commitment ?? "confirmed";
+    }
+    /**
+     * Transaction helpers.
+     *
+     * - `buildAndSignIxs`: returns a signed tx and the deterministic signature.
+     * - `sendSigned`: send without confirmation.
+     * - `sendAndConfirmSigned`: send + confirm (requires `rpcSubscriptions`).
+     * - `sendAndConfirmIxs`: build+sign+send+confirm (requires `rpcSubscriptions`).
+     */
+    tx = {
+        buildAndSignIxs: async (args) => {
+            return buildAndSignTransactionFromIxs({
+                rpc: this.rpc,
+                payer: this.payer,
+                signers: args.signers,
+                ixs: args.ixs,
+                commitment: args.commitment ?? this.commitment,
+            });
+        },
+        sendSigned: async (args) => {
+            return sendSignedTransaction({
+                rpc: this.rpc,
+                signed: args.signed,
+                options: { commitment: this.commitment, ...args.options },
+            });
+        },
+        sendAndConfirmSigned: async (args) => {
+            if (!this.rpcSubscriptions) {
+                throw new Error("rpcSubscriptions is required for sendAndConfirm");
+            }
+            return sendAndConfirmSignedTransaction({
+                rpc: this.rpc,
+                rpcSubscriptions: this.rpcSubscriptions,
+                signed: args.signed,
+                options: { commitment: this.commitment, ...args.options },
+            });
+        },
+        sendAndConfirmIxs: async (args) => {
+            if (!this.rpcSubscriptions) {
+                throw new Error("rpcSubscriptions is required for sendAndConfirm");
+            }
+            return sendAndConfirmIxs({
+                rpc: this.rpc,
+                rpcSubscriptions: this.rpcSubscriptions,
+                payer: this.payer,
+                signers: args.signers,
+                ixs: args.ixs,
+                options: { commitment: this.commitment, ...args.options },
+            });
+        },
+    };
+}