@liquid-af/sdk 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liquid-af/sdk",
-	"version": "0.4.1",
+	"version": "0.5.1",
 	"description": "TypeScript SDK for the Liquid DeFi protocol on Solana",
 	"type": "module",
 	"publishConfig": {

package/src/client.ts

@@ -28,6 +28,7 @@ import {
 	buildMigrateNative,
 	buildInitializeNativeReferralVault,
 	buildWithdrawReferralRewards,
+	buildWithdrawReferralTokenRewards,
 	buildExecuteBuybackNative,
 	buildExecuteBuybackToken,
 	buildCreateStableCurve,
@@ -250,13 +251,24 @@ export class LiquidClient {
 		});
 	}
 
-	/** Builds a withdrawReferralRewards instruction. */
+	/** Builds a withdrawReferralRewards instruction (native SOL). */
 	buildWithdrawReferralRewards(params: {
 		user: PublicKey;
 	}): Promise<TransactionInstruction> {
 		return buildWithdrawReferralRewards({ ...params, config: this.config });
 	}
 
+	/** Builds a withdrawReferralTokenRewards instruction (SPL token). */
+	buildWithdrawReferralTokenRewards(params: {
+		user: PublicKey;
+		quoteMint: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildWithdrawReferralTokenRewards({
+			...params,
+			config: this.config,
+		});
+	}
+
 	/** Builds an executeBuybackNative instruction for native SOL curves. Permissionless; requires revoked fee config. */
 	buildExecuteBuybackNative(params: {
 		payer: PublicKey;
@@ -372,7 +384,7 @@ export class LiquidClient {
 		return buildMigrateStable({ ...params, config: this.config });
 	}
 
-	/** Builds an initializeReferralTokenVault instruction (creates a referral token vault for stable curves). */
+	/** Builds an initializeReferralTokenVault instruction (creates a PDA token vault for stable curve referral rewards). */
 	buildInitializeReferralTokenVault(params: {
 		user: PublicKey;
 		quoteMint: PublicKey;

package/src/config.ts

@@ -12,6 +12,8 @@ export interface LiquidConfig {
 	liquidFeesProgramId: PublicKey;
 	/** Program ID for the user state program */
 	liquidStateProgramId: PublicKey;
+	/** Program ID for the events program */
+	liquidEventsProgramId: PublicKey;
 }
 
 /** Mainnet program IDs */
@@ -28,6 +30,9 @@ export const MAINNET_CONFIG: LiquidConfig = {
 	liquidStateProgramId: new PublicKey(
 		"State3HtEfi7cXdsTpAtRoBvrij8zSFCiGTAVWmYH2d",
 	),
+	liquidEventsProgramId: new PublicKey(
+		"EventsQeXA43nLKR69DhHwNsJ6aM512AweMCgG3wG8zG",
+	),
 } as const;
 
 /** Devnet program IDs (liquid differs, others same as mainnet) */
@@ -44,6 +49,9 @@ export const DEVNET_CONFIG: LiquidConfig = {
 	liquidStateProgramId: new PublicKey(
 		"9ZcKPa3HAEVEKxwFX8fYD56ZJCKPEQgqjgr9rfUvtwKJ",
 	),
+	liquidEventsProgramId: new PublicKey(
+		"Bast7hBDiqSsxiwEmqazwvPvXC3N4z8UQR5ZmkqXnCiY",
+	),
 } as const;
 
 /** Localnet program IDs (same as mainnet per Anchor.toml) */

package/src/events/parser.ts

@@ -1,4 +1,4 @@
-import { BorshCoder, EventParser, type Program } from "@coral-xyz/anchor";
+import { BorshCoder, type Program } from "@coral-xyz/anchor";
 
 /** Parsed event with name and data */
 export interface ParsedEvent<T = unknown> {
@@ -6,8 +6,15 @@ export interface ParsedEvent<T = unknown> {
 	data: T;
 }
 
+const PROGRAM_DATA = "Program data: ";
+const PROGRAM_LOG = "Program log: ";
+const INVOKE_RE = /^Program ([1-9A-HJ-NP-Za-km-z]+) invoke \[(\d+)\]$/;
+const EXIT_RE = /^Program ([1-9A-HJ-NP-Za-km-z]+) (success|failed)/;
+
 /**
  * Parses events from transaction logs for a given program.
+ * Unlike Anchor's built-in EventParser, this correctly identifies events
+ * from programs invoked via CPI (not just top-level invocations).
  *
  * @param logs - Transaction log messages
  * @param program - The Anchor program to parse events for
@@ -17,16 +24,11 @@ export const parseTransactionEvents = (
 	logs: string[],
 	program: Program,
 ): ParsedEvent[] => {
-	const parser = new EventParser(
-		program.programId,
+	return parseCpiLogs(
+		logs,
+		program.programId.toString(),
 		new BorshCoder(program.idl),
 	);
-	const events: ParsedEvent[] = [];
-	const generator = parser.parseLogs(logs);
-	for (const event of generator) {
-		events.push({ name: event.name, data: event.data });
-	}
-	return events;
 };
 
 /**
@@ -49,10 +51,13 @@ export const addEventListener = <T>(
 };
 
 /**
- * Registers an event listener, fires a trigger, and polls until the event
- * arrives or the timeout is exceeded.
+ * Subscribes to logs via WebSocket, fires a trigger, and polls until the
+ * event arrives or the timeout is exceeded.
  *
- * @param program - The Anchor program
+ * Uses CPI-aware log parsing so events emitted by programs that are only
+ * invoked via CPI (e.g., a centralized events program) are correctly detected.
+ *
+ * @param program - The Anchor program whose events to listen for
  * @param eventName - Name of the event to wait for
  * @param trigger - Async function to trigger the event (e.g., sendAndConfirm)
  * @param timeoutMs - Maximum wait time in milliseconds (default: 5000)
@@ -67,24 +72,88 @@ export async function waitForEvent<TEvent, TResult = string>(
 	timeoutMs = 5000,
 ): Promise<{ result: TResult; event: TEvent }> {
 	let eventData: TEvent | null = null;
-	const listenerId = program.addEventListener(eventName, (data: TEvent) => {
-		eventData = data;
-	});
+	const programId = program.programId.toString();
+	const coder = new BorshCoder(program.idl);
+
+	// Subscribe to logs mentioning this program (includes CPI invocations)
+	const subscriptionId = program.provider.connection.onLogs(
+		program.programId,
+		(logs) => {
+			if (logs.err) return;
+			const events = parseCpiLogs(logs.logs, programId, coder);
+			for (const event of events) {
+				if (event.name === eventName) {
+					eventData = event.data as TEvent;
+				}
+			}
+		},
+	);
+
 	try {
 		const result = await trigger();
 		const start = Date.now();
 		while (!eventData && Date.now() - start < timeoutMs) {
 			await new Promise((r) => setTimeout(r, 200));
 		}
-		await program.removeEventListener(listenerId);
 		if (!eventData) {
 			throw new Error(
 				`Event '${eventName}' not received within ${timeoutMs}ms`,
 			);
 		}
 		return { result, event: eventData };
-	} catch (err) {
-		await program.removeEventListener(listenerId);
-		throw err;
+	} finally {
+		await program.provider.connection.removeOnLogsListener(subscriptionId);
 	}
 }
+
+/**
+ * Parses events from transaction logs, properly handling CPI contexts.
+ *
+ * Anchor's built-in EventParser pushes a generic "cpi" string onto its
+ * execution stack for nested invocations, so it cannot identify events
+ * emitted by a CPI-only program. This parser extracts the actual program
+ * ID from each `invoke` log line, enabling correct attribution of events
+ * to programs at any CPI depth.
+ */
+function parseCpiLogs(
+	logs: string[],
+	programId: string,
+	coder: BorshCoder,
+): ParsedEvent[] {
+	const events: ParsedEvent[] = [];
+	const stack: string[] = [];
+
+	for (const log of logs) {
+		if (!log.startsWith("Program ")) continue;
+
+		const invokeMatch = INVOKE_RE.exec(log);
+		if (invokeMatch) {
+			stack.push(invokeMatch[1]);
+			continue;
+		}
+
+		const exitMatch = EXIT_RE.exec(log);
+		if (exitMatch) {
+			stack.pop();
+			continue;
+		}
+
+		// Only try to decode events when inside the target program's context
+		if (stack.length > 0 && stack[stack.length - 1] === programId) {
+			let logStr: string | null = null;
+			if (log.startsWith(PROGRAM_DATA)) {
+				logStr = log.slice(PROGRAM_DATA.length);
+			} else if (log.startsWith(PROGRAM_LOG)) {
+				logStr = log.slice(PROGRAM_LOG.length);
+			}
+			if (logStr) {
+				const event = coder.events.decode(logStr);
+				if (event) {
+					events.push({ name: event.name, data: event.data });
+				}
+			}
+		}
+	}
+
+	return events;
+}

package/src/idl/index.ts

@@ -8,8 +8,15 @@ import liquidIdl from "./liquid.json" with { type: "json" };
 import liquidSwapIdl from "./liquid_swap.json" with { type: "json" };
 import liquidFeesIdl from "./liquid_fees.json" with { type: "json" };
 import liquidStateIdl from "./liquid_state.json" with { type: "json" };
+import liquidEventsIdl from "./liquid_events.json" with { type: "json" };
 
-export { liquidIdl, liquidSwapIdl, liquidFeesIdl, liquidStateIdl };
+export {
+	liquidIdl,
+	liquidSwapIdl,
+	liquidFeesIdl,
+	liquidStateIdl,
+	liquidEventsIdl,
+};
 export { patchIdl } from "./patch-idl.js";
 
 // Re-export Anchor-generated IDL types
@@ -17,11 +24,13 @@ export type { Liquid } from "./liquid.js";
 export type { LiquidSwap } from "./liquid_swap.js";
 export type { LiquidFees } from "./liquid_fees.js";
 export type { LiquidState } from "./liquid_state.js";
+export type { LiquidEvents } from "./liquid_events.js";
 
 import type { Liquid } from "./liquid.js";
 import type { LiquidSwap } from "./liquid_swap.js";
 import type { LiquidFees } from "./liquid_fees.js";
 import type { LiquidState } from "./liquid_state.js";
+import type { LiquidEvents } from "./liquid_events.js";
 
 /**
  * Creates a typed Program instance for the Liquid bonding curve program.
@@ -115,3 +124,19 @@ export function getLiquidStateProgram(
 		: liquidStateIdl;
 	return new Program(idl as LiquidState, createReadonlyProvider(connection));
 }
+
+/**
+ * Creates a typed Program instance for the Liquid Events program.
+ * Uses a readonly provider — no signing capability.
+ *
+ * @param connection - Solana RPC connection
+ * @returns Read-only Program instance typed as LiquidEvents
+ */
+export function getLiquidEventsProgram(
+	connection: Connection,
+): Program<LiquidEvents> {
+	return new Program(
+		liquidEventsIdl as LiquidEvents,
+		createReadonlyProvider(connection),
+	);
+}