@liquid-af/sdk 0.1.0

package/src/instructions/liquid-state.ts

@@ -0,0 +1,336 @@
+import type { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { LiquidConfig } from "../config.js";
+import { getCachedStateProgram } from "./program-cache.js";
+import { getDealPDA, getUserSnapshotPDA } from "../pda/liquid-state.js";
+
+export interface BuildInitializeUserParams {
+	user: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an initializeUser instruction.
+ * Creates the user properties account in liquid-state.
+ *
+ * @param params - {@link BuildInitializeUserParams}
+ * @returns Transaction instruction
+ */
+export function buildInitializeUser(
+	params: BuildInitializeUserParams
+): Promise<TransactionInstruction> {
+	const { user, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods.initializeUser().accounts({ user }).instruction();
+}
+
+export interface BuildSetReferrerParams {
+	user: PublicKey;
+	referrer: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a setReferrer instruction.
+ * One-time operation — referrer cannot be changed once set.
+ *
+ * @param params - {@link BuildSetReferrerParams}
+ * @returns Transaction instruction
+ */
+export function buildSetReferrer(
+	params: BuildSetReferrerParams
+): Promise<TransactionInstruction> {
+	const { user, referrer, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods
+		.setReferrer(referrer)
+		.accounts({ user })
+		.instruction();
+}
+
+export interface BuildSetCashbackModeParams {
+	user: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a setCashbackMode instruction.
+ * Toggles user between earning mode (earn credits) and spending mode (spend credits).
+ *
+ * @param params - {@link BuildSetCashbackModeParams}
+ * @returns Transaction instruction
+ */
+export function buildSetCashbackMode(
+	params: BuildSetCashbackModeParams
+): Promise<TransactionInstruction> {
+	const { user, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods.setCashbackMode().accounts({ user }).instruction();
+}
+
+export interface BuildTransferAdminParams {
+	admin: PublicKey;
+	newAdmin: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a transferAdmin instruction.
+ * Proposes transfer of admin authority to a new pubkey (two-step).
+ * The new admin must call {@link buildAcceptAdmin} to complete the transfer.
+ *
+ * @param params - {@link BuildTransferAdminParams}
+ * @returns Transaction instruction
+ */
+export function buildTransferAdmin(
+	params: BuildTransferAdminParams
+): Promise<TransactionInstruction> {
+	const { admin, newAdmin, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods
+		.transferAdmin(newAdmin)
+		.accounts({ admin })
+		.instruction();
+}
+
+export interface BuildAcceptAdminParams {
+	newAdmin: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an acceptAdmin instruction.
+ * Completes a pending admin transfer. Must be called by the pending admin.
+ *
+ * @param params - {@link BuildAcceptAdminParams}
+ * @returns Transaction instruction
+ */
+export function buildAcceptAdmin(
+	params: BuildAcceptAdminParams
+): Promise<TransactionInstruction> {
+	const { newAdmin, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods
+		.acceptAdmin()
+		.accounts({ newAdmin })
+		.instruction();
+}
+
+export interface BuildCancelAdminTransferParams {
+	authority: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a cancelAdminTransfer instruction.
+ * Cancels a pending admin transfer. Callable by either the current admin or the pending admin.
+ *
+ * @param params - {@link BuildCancelAdminTransferParams}
+ * @returns Transaction instruction
+ */
+export function buildCancelAdminTransfer(
+	params: BuildCancelAdminTransferParams
+): Promise<TransactionInstruction> {
+	const { authority, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods
+		.cancelAdminTransfer()
+		.accounts({ authority })
+		.instruction();
+}
+
+export interface BuildCreateDealParams {
+	admin: PublicKey;
+	owner: PublicKey;
+	cashbackMultiplierBps: number;
+	payer: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a createDeal instruction.
+ * Admin creates an exclusive deal for a pubkey (typically a referrer/influencer).
+ *
+ * @param params - {@link BuildCreateDealParams}
+ * @returns Transaction instruction
+ */
+export function buildCreateDeal(
+	params: BuildCreateDealParams
+): Promise<TransactionInstruction> {
+	const { admin, owner, cashbackMultiplierBps, payer, config } = params;
+	const program = getCachedStateProgram(config);
+
+	return program.methods
+		.createDeal(owner, cashbackMultiplierBps)
+		.accounts({ admin, payer })
+		.instruction();
+}
+
+export interface BuildUpdateDealParams {
+	admin: PublicKey;
+	dealOwner: PublicKey;
+	newCashbackMultiplierBps: number;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an updateDeal instruction.
+ * Admin updates a deal's cashback multiplier.
+ *
+ * @param params - {@link BuildUpdateDealParams}
+ * @returns Transaction instruction
+ */
+export function buildUpdateDeal(
+	params: BuildUpdateDealParams
+): Promise<TransactionInstruction> {
+	const { admin, dealOwner, newCashbackMultiplierBps, config } = params;
+	const program = getCachedStateProgram(config);
+	const [deal] = getDealPDA(dealOwner, config.liquidStateProgramId);
+
+	return program.methods
+		.updateDeal(newCashbackMultiplierBps)
+		.accountsPartial({ admin, deal })
+		.instruction();
+}
+
+export interface BuildCloseDealParams {
+	admin: PublicKey;
+	dealOwner: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a closeDeal instruction.
+ * Admin closes/deletes a deal, returning rent to admin.
+ *
+ * @param params - {@link BuildCloseDealParams}
+ * @returns Transaction instruction
+ */
+export function buildCloseDeal(
+	params: BuildCloseDealParams
+): Promise<TransactionInstruction> {
+	const { admin, dealOwner, config } = params;
+	const program = getCachedStateProgram(config);
+	const [deal] = getDealPDA(dealOwner, config.liquidStateProgramId);
+
+	return program.methods
+		.closeDeal()
+		.accountsPartial({ admin, deal })
+		.instruction();
+}
+
+export interface BuildRedeemDealParams {
+	user: PublicKey;
+	dealOwner: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a redeemDeal instruction.
+ * User redeems their referrer's deal, copying the multiplier.
+ *
+ * @param params - {@link BuildRedeemDealParams}
+ * @returns Transaction instruction
+ */
+export function buildRedeemDeal(
+	params: BuildRedeemDealParams
+): Promise<TransactionInstruction> {
+	const { user, dealOwner, config } = params;
+	const program = getCachedStateProgram(config);
+	const [deal] = getDealPDA(dealOwner, config.liquidStateProgramId);
+
+	return program.methods
+		.redeemDeal()
+		.accountsPartial({ user, deal })
+		.instruction();
+}
+
+export interface BuildTakeSnapshotParams {
+	admin: PublicKey;
+	user: PublicKey;
+	payer: PublicKey;
+	snapshotIndex: number;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a takeSnapshot instruction.
+ * Admin takes a snapshot of a user's volume since last snapshot.
+ *
+ * The caller must provide the current `snapshotIndex` (from `user_properties.snapshot_count`)
+ * because the snapshot PDA seed depends on this value and cannot be resolved without a
+ * network fetch.
+ *
+ * @param params - {@link BuildTakeSnapshotParams}
+ * @returns Transaction instruction
+ */
+export function buildTakeSnapshot(
+	params: BuildTakeSnapshotParams
+): Promise<TransactionInstruction> {
+	const { admin, user, payer, snapshotIndex, config } = params;
+	const program = getCachedStateProgram(config);
+	const [userSnapshot] = getUserSnapshotPDA(
+		user,
+		snapshotIndex,
+		config.liquidStateProgramId
+	);
+
+	return program.methods
+		.takeSnapshot()
+		.accountsPartial({ admin, user, payer, userSnapshot })
+		.instruction();
+}
+
+export interface BuildAdminUpdateUserParams {
+	admin: PublicKey;
+	user: PublicKey;
+	payer: PublicKey;
+	newReferrer: PublicKey | null;
+	newCashbackMultiplierBps: number | null;
+	snapshotIndex: number;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an adminUpdateUser instruction.
+ * Admin updates a user's referrer/multiplier and always takes a snapshot.
+ *
+ * The caller must provide the current `snapshotIndex` (from `user_properties.snapshot_count`)
+ * because the snapshot PDA seed depends on this value and cannot be resolved without a
+ * network fetch.
+ *
+ * @param params - {@link BuildAdminUpdateUserParams}
+ * @returns Transaction instruction
+ */
+export function buildAdminUpdateUser(
+	params: BuildAdminUpdateUserParams
+): Promise<TransactionInstruction> {
+	const {
+		admin,
+		user,
+		payer,
+		newReferrer,
+		newCashbackMultiplierBps,
+		snapshotIndex,
+		config,
+	} = params;
+	const program = getCachedStateProgram(config);
+	const [userSnapshot] = getUserSnapshotPDA(
+		user,
+		snapshotIndex,
+		config.liquidStateProgramId
+	);
+
+	return program.methods
+		.adminUpdateUser({
+			newReferrer: newReferrer ?? null,
+			newCashbackMultiplierBps: newCashbackMultiplierBps ?? null,
+		})
+		.accountsPartial({ admin, user, payer, userSnapshot })
+		.instruction();
+}