@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta

package/dist/esm/defi/utils.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @file defi/utils.ts
+ * @module SolanaDeFi
+ * @author Keepeeto
+ * @license MIT
+ * @description Solana DeFi utilities: discovery, quoting and swap execution via Jupiter and Raydium.
+ *              Clean, strongly-typed API with event emissions for observability. No Kamino deps.
+ */
+import { EventEmitter } from 'eventemitter3';
+import type { Connection, VersionedTransaction, Transaction, Commitment } from '@solana/web3.js';
+import type { SynapseClient } from '../client';
+export type RiskTolerance = 'low' | 'medium' | 'high';
+export interface DeFiEventMap {
+    'defi:quote': {
+        quote: QuoteResponse;
+    };
+    'defi:swap:built': {
+        tx: BuildSwapTxResult;
+    };
+    'defi:swap:sent': {
+        signature: string;
+    };
+    'defi:tx:decoded': {
+        txType: string;
+    };
+    'defi:health': {
+        ok: boolean;
+        details: Record<string, any>;
+    };
+    'defi:warning': {
+        message: string;
+    };
+    'defi:error': {
+        error: Error;
+        context?: Record<string, any>;
+    };
+}
+export declare enum JUPITER_VERSIONED_URL {
+    v6 = "https://quote-api.jup.ag/v6",
+    v5 = "https://quote-api.jup.ag/v5",
+    v4 = "https://quote-api.jup.ag/v4"
+}
+export interface DeFiConfig {
+    client: SynapseClient;
+    connection?: Connection;
+    defaultCommitment?: Commitment;
+    jupiter?: {
+        /** Jupiter Quote/Swap API base URL (override if self-hosting) */
+        baseUrl?: JUPITER_VERSIONED_URL | string;
+        /** Percent fee in basis points for platforms (0-10000). Forwarded to Jupiter. */
+        platformFeeBps?: number;
+        /** Address to receive platform fees */
+        platformFeeAccount?: string;
+        /** If true, ask Jupiter to return a legacy tx instead of v0 */
+        asLegacyTransaction?: boolean;
+        /** Override paths for custom aggregator deployment */
+        quotePath?: string;
+        swapPath?: string;
+    };
+    raydium?: {
+        /** Raydium Aggregator base URL */
+        baseUrl?: string;
+        /** Optional: provide a custom builder using Raydium SDK v2 to create swap IX/Tx. */
+        customSwapBuilder?: (params: RaydiumBuildSwapParams) => Promise<BuildSwapTxResult>;
+        /** Override paths for custom aggregator deployment */
+        quotePath?: string;
+        swapPath?: string;
+    };
+    tokenRegistry?: (mint: string) => Promise<TokenInfo>;
+    logLevel?: 'debug' | 'info' | 'error' | 'none';
+}
+export interface TokenInfo {
+    mint: string;
+    symbol?: string;
+    name?: string;
+    decimals?: number;
+    verified?: boolean;
+    priceUSD?: number;
+}
+export interface QuoteRequestCommon {
+    inputMint: string;
+    outputMint: string;
+    /** Raw amount in base units (e.g., 1 SOL -> 1_000_000_000) */
+    amount: string | number;
+    /** Slippage in basis points (e.g., 50 = 0.5%). Must be 0-10000 */
+    slippageBps?: number;
+    /** Prefer direct (single-hop) routes */
+    onlyDirectRoutes?: boolean;
+    /** If provided, routes may be tailored to this wallet (e.g., account state) */
+    userPublicKey?: string;
+}
+export interface JupiterQuoteRequest extends QuoteRequestCommon {
+    /** Choose price/size tradeoff; defaults to SMART */
+    swapMode?: 'ExactIn' | 'ExactOut';
+    /** Restrict to DEXes */
+    dexes?: string[];
+    /** Maximum accounts in the swap transaction (Jupiter param) */
+    maxAccounts?: number;
+}
+export interface RaydiumQuoteRequest extends QuoteRequestCommon {
+    /** program IDs allowlist/denylist, pool types, etc., depending on aggregator */
+    allowAmmV4?: boolean;
+    allowClmm?: boolean;
+}
+export interface QuoteResponse {
+    inAmount: string;
+    outAmount: string;
+    priceImpactPct?: number;
+    route?: any;
+    context?: Record<string, any>;
+}
+export interface BuildSwapTxResult {
+    /** Base64-encoded serialized transaction to sign & send */
+    txBase64: string;
+    /** Optional human-readable route info */
+    route?: any;
+    /** Any aggregator-specific metadata */
+    meta?: Record<string, any>;
+}
+export interface ExecuteSwapParams {
+    /** Recipient/signer public key (payer). */
+    payer: string;
+    /** Pre-built swap tx (base64) OR a builder callback */
+    txBase64?: string;
+    build?: () => Promise<BuildSwapTxResult>;
+    /** If true, return the prepared Transaction/VersionedTransaction without sending. */
+    dryRun?: boolean;
+    /** Optional: max retries, skip preflight, etc. */
+    sendOpts?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+        preflightCommitment?: Commitment;
+    };
+}
+export interface RaydiumBuildSwapParams extends QuoteRequestCommon {
+    payer: string;
+    /** Additional settings per Raydium aggregator/SDK */
+    priorityFeeInMicroLamports?: number;
+}
+export declare class SynapseSolanaEngine extends EventEmitter {
+    private client;
+    private cfg;
+    private requestIdCounter;
+    constructor(config: DeFiConfig);
+    /**
+     * Internal logging helper
+     */
+    private log;
+    /**
+     * Generate unique request ID for tracing
+     */
+    private getRequestId;
+    /**
+     * Get token info from registry or well-known tokens
+     * @param mint - Token mint address (base58)
+     * @returns TokenInfo object with symbol, decimals, etc.
+     * @note Override via config.tokenRegistry for custom token data sources
+     */
+    getTokenInfo(mint: string): Promise<TokenInfo>;
+    /** Fetch a quote from Jupiter. */
+    jupiterQuote(params: JupiterQuoteRequest): Promise<QuoteResponse>;
+    /** Build a swap transaction via Jupiter Swap API. */
+    jupiterBuildSwapTx(args: {
+        payer: string;
+        quoteResponse?: any;
+        quoteArgs?: JupiterQuoteRequest;
+        dynamicSlippageBps?: number;
+        wrapAndUnwrapSol?: boolean;
+        restrictIntermediateTokens?: string[];
+        asLegacyTransaction?: boolean;
+    }): Promise<BuildSwapTxResult>;
+    /**
+     * Fetch a quote from Raydium Aggregator (REST). If you use the Raydium SDK,
+     * prefer injecting a custom builder/quoting path via `raydium.customSwapBuilder`.
+     */
+    raydiumQuote(params: RaydiumQuoteRequest): Promise<QuoteResponse>;
+    /**
+     * Build a Raydium swap transaction.
+     * - Prefer `raydium.customSwapBuilder` to use the official SDK for precision.
+     * - Fallback to REST aggregator transaction builder if available.
+     */
+    raydiumBuildSwapTx(args: RaydiumBuildSwapParams & {
+        route?: any;
+    }): Promise<BuildSwapTxResult>;
+    /**
+     * Decode a base64 transaction into a Transaction or VersionedTransaction.
+     * Supports both Node.js (Buffer) and browser (atob) environments.
+     */
+    decodeBase64Tx(txBase64: string): Promise<Transaction | VersionedTransaction>;
+    /**
+     * Sign and (optionally) send a prepared base64 transaction.
+     * @requires SynapseClient to implement signAndSend(tx, opts) or sendRawTransaction(raw, opts)
+     */
+    executeSwap(params: ExecuteSwapParams): Promise<{
+        signature?: string;
+        tx?: Transaction | VersionedTransaction;
+    }>;
+    swapWithJupiter(all: {
+        payer: string;
+        quoteArgs: JupiterQuoteRequest;
+        dynamicSlippageBps?: number;
+        restrictIntermediateTokens?: string[];
+        asLegacyTransaction?: boolean;
+        dryRun?: boolean;
+        sendOpts?: ExecuteSwapParams['sendOpts'];
+    }): Promise<{
+        signature?: string;
+        tx?: Transaction | VersionedTransaction;
+    }>;
+    swapWithRaydium(all: RaydiumBuildSwapParams & {
+        route?: any;
+        dryRun?: boolean;
+        sendOpts?: ExecuteSwapParams['sendOpts'];
+    }): Promise<{
+        signature?: string;
+        tx?: Transaction | VersionedTransaction;
+    }>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        details: {
+            jupiterBase: string;
+            jupiterPaths: {
+                quote: string;
+                swap: string;
+            };
+            raydiumBase: string;
+            raydiumPaths: {
+                quote: string;
+                swap: string;
+            };
+            hasCustomBuilder: boolean;
+            hasTokenRegistry: boolean;
+            logLevel: "none" | "error" | "info" | "debug";
+        };
+    }>;
+}
+export type DeFiEvents = keyof DeFiEventMap;
+/**
+ * Example:
+ *
+ * const engine = new SolanaDeFiEngine({ client: synapseClient, jupiter: { platformFeeBps: 50, platformFeeAccount: FEE_ACCT } });
+ *
+ * // Quote & swap with Jupiter
+ * const res = await engine.swapWithJupiter({
+ *   payer: wallet.publicKey.toBase58(),
+ *   quoteArgs: {
+ *     inputMint: SOL_MINT,
+ *     outputMint: USDC_MINT,
+ *     amount: 1_000_000_000n.toString(),
+ *     slippageBps: 50,
+ *     userPublicKey: wallet.publicKey.toBase58(),
+ *   },
+ *   dynamicSlippageBps: 50,
+ * });
+ *
+ * // Raydium (via REST or custom SDK builder)
+ * const rRes = await engine.swapWithRaydium({
+ *   payer: wallet.publicKey.toBase58(),
+ *   inputMint: SOL_MINT,
+ *   outputMint: USDC_MINT,
+ *   amount: 1_000_000_000n.toString(),
+ *   slippageBps: 50,
+ * });
+ */
+//# sourceMappingURL=utils.d.ts.map

package/dist/esm/defi/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/defi/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAa,oBAAoB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAM/C,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAGtD,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE;QAAE,KAAK,EAAE,aAAa,CAAA;KAAE,CAAC;IACvC,iBAAiB,EAAE;QAAE,EAAE,EAAE,iBAAiB,CAAA;KAAE,CAAC;IAC7C,gBAAgB,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,iBAAiB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,aAAa,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC;IAC7D,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,YAAY,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC;CAC/D;AAED,oBAAY,qBAAqB;IAC/B,EAAE,gCAAgC;IAClC,EAAE,gCAAgC;IAClC,EAAE,gCAAgC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAG/B,OAAO,CAAC,EAAE;QACR,iEAAiE;QACjE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;QACzC,iFAAiF;QACjF,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,uCAAuC;QACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,+DAA+D;QAC/D,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,sDAAsD;QACtD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IAIF,OAAO,CAAC,EAAE;QACR,kCAAkC;QAClC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oFAAoF;QACpF,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;QACnF,sDAAsD;QACtD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IAGF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAGrD,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAChD;AAyBD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,oDAAoD;IACpD,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAClC,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,gFAAgF;IAChF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzC,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE;QACT,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mBAAmB,CAAC,EAAE,UAAU,CAAC;KAClC,CAAC;CACH;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AA6DD,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,MAAM,EAAE,UAAU;IAiC9B;;OAEG;IACH,OAAO,CAAC,GAAG;IAeX;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IA+BpD,kCAAkC;IAC5B,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IA+DvE,qDAAqD;IAC/C,kBAAkB,CAAC,IAAI,EAAE;QAC7B,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,GAAG,CAAC;QACpB,SAAS,CAAC,EAAE,mBAAmB,CAAC;QAChC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;QACtC,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuE9B;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAwDvE;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG;QAAE,KAAK,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0EpG;;;OAGG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,oBAAoB,CAAC;IAmCnF;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,WAAW,GAAG,oBAAoB,CAAA;KAAE,CAAC;IAgFhH,eAAe,CAAC,GAAG,EAAE;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,mBAAmB,CAAC;QAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;QACtC,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;KAC1C;oBAxFmE,MAAM;aAAO,WAAW,GAAG,oBAAoB;;IAyG7G,eAAe,CAAC,GAAG,EAAE,sBAAsB,GAAG;QAClD,KAAK,CAAC,EAAE,GAAG,CAAC;QACZ,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;KAC1C;oBA7GmE,MAAM;aAAO,WAAW,GAAG,oBAAoB;;IAoH7G,WAAW;;;;;;;;;;;;;;;;;;CAoBlB;AAMD,MAAM,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC;AAK5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}