Examples

import { Keypair, VersionedTransaction } from "@solana/web3.js";

const BASE_URL = "https://hedgin.xyz/api/external/v1";
const POLL_INTERVAL_MS = 2_000;

interface NextStep { path: string; body: Record<string, unknown> }
interface BuildStep {
	transaction: string;
	ticket: string;
	sendConcurrently?: boolean;
	next?: NextStep;
}
interface BuildResponse { vault: string; result: BuildStep | BuildStep[] }
interface SendResponse { signature: string; receipt: string; status: "pending" | "unknown" }
type StatusResponse =
	| { status: "pending" | "confirmed" | "expired" }
	| { status: "failed"; code: string; message: string };

export class HedginError extends Error {
	constructor(readonly httpStatus: number, readonly code: string, message: string) {
		super(`${httpStatus} ${code}: ${message}`);
	}
}

async function call<T>(apiKey: string, method: "GET" | "POST", path: string, body?: unknown): Promise<T> {
	const response = await fetch(`${BASE_URL}/${path}`, {
		method,
		headers: {
			Authorization: `Bearer ${apiKey}`,
			...(body === undefined ? {} : { "Content-Type": "application/json" }),
		},
		body: body === undefined ? undefined : JSON.stringify(body),
	});
	// The edge proxy can answer 413 or 429 with a non-JSON body.
	const payload: unknown = await response.json().catch(() => null);
	if (!response.ok) {
		const error = (payload as { error?: { code?: string; message?: string } } | null)?.error;
		throw new HedginError(response.status, error?.code ?? "Unknown", error?.message ?? "Request failed");
	}
	return payload as T;
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/** Polls one receipt until it is final. Resolves only on `confirmed`. */
async function waitForConfirmation(apiKey: string, sent: SendResponse): Promise<void> {
	for (;;) {
		const status = await call<StatusResponse>(
			apiKey, "GET", `transactions/status?receipt=${encodeURIComponent(sent.receipt)}`,
		);
		if (status.status === "confirmed") return;
		if (status.status === "failed") throw new Error(`${sent.signature} failed: ${status.code} ${status.message}`);
		if (status.status === "expired") throw new Error(`${sent.signature} expired without landing`);
		await sleep(POLL_INTERVAL_MS);
	}
}

interface SignedStep extends BuildStep { signedTransaction: string }

/** Splits a batch into barrier steps and runs of `sendConcurrently` steps. */
function groups(steps: SignedStep[]): SignedStep[][] {
	const result: SignedStep[][] = [];
	for (const step of steps) {
		const last = result.at(-1);
		if (step.sendConcurrently && last?.[0]?.sendConcurrently) last.push(step);
		else result.push([step]);
	}
	return result;
}

/**
 * Builds `action`, signs every step with the manager keypair, sends each group in order,
 * waits for confirmation, and then follows `next`. Returns every confirmed signature.
 */
export async function execute(
	apiKey: string,
	manager: Keypair,
	action: string,
	body: Record<string, unknown>,
): Promise<string[]> {
	const confirmed: string[] = [];
	let pending: NextStep | undefined = { path: action, body };
	while (pending) {
		const build: BuildResponse = await call<BuildResponse>(apiKey, "POST", `transactions/${pending.path}`, pending.body);
		const steps: BuildStep[] = Array.isArray(build.result) ? build.result : [build.result];
		// Sign everything now: every ticket expires 90 seconds after the build.
		const signed: SignedStep[] = steps.map((step) => {
			const transaction = VersionedTransaction.deserialize(Buffer.from(step.transaction, "base64"));
			transaction.sign([manager]); // keeps signatures the builder already added
			return { ...step, signedTransaction: Buffer.from(transaction.serialize()).toString("base64") };
		});
		for (const group of groups(signed)) {
			const sends = await Promise.all(group.map((step) =>
				call<SendResponse>(apiKey, "POST", "transactions/send", { transaction: step.signedTransaction, ticket: step.ticket }),
			));
			// An "unknown" send is polled like a pending one, never rebuilt.
			await Promise.all(sends.map((sent) => waitForConfirmation(apiKey, sent)));
			confirmed.push(...sends.map((sent) => sent.signature));
		}
		pending = steps.at(-1)?.next;
	}
	return confirmed;
}