@voidifydao/sdk 1.0.0

package/dist/substream/modules/relayer.js

@@ -0,0 +1,290 @@
+import { PublicKey } from "@solana/web3.js";
+import { normalizePayload } from "../../substream/chain/events.js";
+import { parseEventsFromLogs, } from "../../utils/anchor-events.js";
+import { substreamLogger } from "../../utils/logger.js";
+import { syncTransactions } from "../../substream/chain/utils.js";
+export const RELAYER_SCOPE = {
+    scopeType: "relayer",
+    scopeKey: "global",
+};
+const RELAYER_LIVE_EVENTS = [
+    "relayerRegisteredEvent",
+    "relayerUpdatedEvent",
+    "relayerActivatedEvent",
+    "relayerUnregisteredEvent",
+    "relayerDeactivatedEvent",
+    "relayerSlashedEvent",
+    "withdrawalEvent",
+];
+const INDEXED_RELAYER_EVENT_NAMES = new Set(RELAYER_LIVE_EVENTS);
+export const relayerModule = {
+    id: "relayer",
+    scopeType: "relayer",
+    parseScopeKey(scopeKey) {
+        return scopeKey === RELAYER_SCOPE.scopeKey ? RELAYER_SCOPE : null;
+    },
+    createStream(ctx, voidify) {
+        return createRelayerStream(ctx, voidify);
+    },
+    liveEvents: RELAYER_LIVE_EVENTS.map((eventName) => ({
+        eventName,
+        async toRecord({ ctx, voidify, event, signature, slot }) {
+            const decoded = { name: eventName, data: event };
+            const pubkey = decoded.data.relayer.toBase58();
+            const cfg = decoded.name === "relayerRegisteredEvent"
+                ? await fetchRelayerConfig(voidify, pubkey)
+                : null;
+            return relayerEventToChainEvent({
+                event: decoded,
+                signature,
+                slot,
+                address: ctx.programId,
+                config: cfg,
+            });
+        },
+    })),
+    createProjections(store) {
+        return [new RelayerProjection(store)];
+    },
+    createClientApi(runtime) {
+        return {
+            async sync() {
+                await runtime.sync(RELAYER_SCOPE);
+            },
+            async list() {
+                const rows = await runtime.projections.list("relayer");
+                return rows.map((row) => relayerRecordFromValue(row.value));
+            },
+            async get(pubkey) {
+                const row = await runtime.projections.get("relayer", pubkey);
+                return row ? relayerRecordFromValue(row.value) : null;
+            },
+            async rebuild() {
+                await runtime.rebuildProjection(RELAYER_SCOPE, "relayer");
+            },
+        };
+    },
+};
+function createRelayerStream(ctx, voidify) {
+    return {
+        id: "relayer",
+        scope: RELAYER_SCOPE,
+        address: ctx.programId,
+        getChainLastIndex: async () => {
+            const counterPda = voidify.relayerEventCounter();
+            const counter = await voidify.program.account.relayerEventCounter.fetch(counterPda);
+            return BigInt(counter.count.toString()) - 1n;
+        },
+        collect: async (lastSignature) => {
+            const transactions = await syncTransactions(ctx.connection, ctx.programId, lastSignature);
+            const records = [];
+            for (const tx of transactions) {
+                const decoded = parseEventsFromLogs(tx.logs, voidify.program.coder.events);
+                for (const item of decoded) {
+                    if (!isIndexedRelayerEventName(item.name))
+                        continue;
+                    const event = item;
+                    const pubkey = event.data.relayer.toBase58();
+                    const cfg = event.name === "relayerRegisteredEvent"
+                        ? await fetchRelayerConfig(voidify, pubkey)
+                        : null;
+                    records.push(relayerEventToChainEvent({
+                        event,
+                        signature: tx.signature,
+                        slot: tx.slot,
+                        blockTime: tx.blockTime,
+                        address: ctx.programId,
+                        config: cfg,
+                    }));
+                }
+            }
+            return records;
+        },
+    };
+}
+function relayerEventToChainEvent(args) {
+    const payload = normalizePayload(args.event.data);
+    if (args.event.name === "relayerRegisteredEvent") {
+        payload.config = args.config ?? { name: "", url: "", feeBps: 0 };
+    }
+    return {
+        ...RELAYER_SCOPE,
+        eventName: args.event.name,
+        eventIndex: BigInt(String(payload.index)),
+        signature: args.signature,
+        slot: args.slot ?? null,
+        blockTime: args.blockTime ?? null,
+        address: args.address.toBase58(),
+        payload,
+        createdAt: Date.now(),
+    };
+}
+function isIndexedRelayerEventName(name) {
+    return INDEXED_RELAYER_EVENT_NAMES.has(name);
+}
+async function fetchRelayerConfig(voidify, relayerPubkey) {
+    try {
+        const cfgKey = voidify.relayerConfig(new PublicKey(relayerPubkey));
+        const cfg = await voidify.program.account.relayerConfig.fetch(cfgKey);
+        return { name: cfg.name, url: cfg.url, feeBps: cfg.feeBps };
+    }
+    catch (err) {
+        substreamLogger.warn({ err, relayerPubkey }, "fetchRelayerConfig failed");
+        return null;
+    }
+}
+class RelayerProjection {
+    store;
+    id = "relayer";
+    constructor(store) {
+        this.store = store;
+    }
+    matches(event) {
+        return event.scopeType === "relayer";
+    }
+    async apply(events) {
+        const sorted = [...events].sort((a, b) => a.eventIndex < b.eventIndex ? -1 : a.eventIndex > b.eventIndex ? 1 : 0);
+        for (const event of sorted) {
+            const pubkey = relayerPubkeyFromEvent(event);
+            if (!pubkey)
+                continue;
+            const existing = await this.store.get(this.id, pubkey);
+            const current = existing ? valueToRelayerState(existing.value) : null;
+            const next = reduceRelayerEvent(current, event);
+            if (!next)
+                continue;
+            await this.store.put({
+                projectionId: this.id,
+                key: pubkey,
+                value: relayerStateToValue(next),
+                updatedAt: next.lastUpdated,
+                lastEventIndex: next.lastEventIndex,
+            });
+        }
+    }
+}
+function defaultRelayerRecord(pubkey) {
+    return {
+        relayerPubkey: pubkey,
+        name: "",
+        url: "",
+        feeBps: 0,
+        stakeAmount: 0n,
+        isActive: true,
+        totalWithdrawals: 0,
+        totalSolEarned: 0n,
+        totalTokenDeducted: 0n,
+        lastUpdated: Date.now(),
+        lastEventIndex: -1n,
+    };
+}
+function reduceRelayerEvent(existing, event) {
+    const pubkey = relayerPubkeyFromEvent(event);
+    if (!pubkey)
+        return existing;
+    const record = existing ? { ...existing } : defaultRelayerRecord(pubkey);
+    if (event.eventIndex <= record.lastEventIndex)
+        return record;
+    switch (event.eventName) {
+        case "relayerRegisteredEvent": {
+            record.stakeAmount = payloadBigInt(event, "stakeAmount");
+            record.isActive = true;
+            const cfg = event.payload.config;
+            record.name = String(cfg?.name ?? "");
+            record.url = String(cfg?.url ?? "");
+            record.feeBps = Number(cfg?.feeBps ?? 0);
+            break;
+        }
+        case "relayerDeactivatedEvent": {
+            record.stakeAmount = payloadBigInt(event, "remainingStake");
+            record.isActive = false;
+            break;
+        }
+        case "relayerSlashedEvent":
+        case "relayerUnregisteredEvent": {
+            record.stakeAmount = 0n;
+            record.isActive = false;
+            break;
+        }
+        case "relayerUpdatedEvent": {
+            if (event.payload.feeBps !== null && event.payload.feeBps !== undefined) {
+                record.feeBps = Number(event.payload.feeBps);
+            }
+            if (event.payload.url !== null && event.payload.url !== undefined) {
+                record.url = String(event.payload.url);
+            }
+            if (event.payload.addedAmount !== null &&
+                event.payload.addedAmount !== undefined) {
+                record.stakeAmount += payloadBigInt(event, "addedAmount");
+            }
+            break;
+        }
+        case "relayerActivatedEvent": {
+            record.stakeAmount = payloadBigInt(event, "stakeAmount");
+            record.isActive = true;
+            break;
+        }
+        case "withdrawalEvent": {
+            const fee = payloadBigInt(event, "fee");
+            const treasury = payloadBigInt(event, "treasury");
+            const tokenDeducted = payloadBigInt(event, "tokenDeducted");
+            record.totalWithdrawals += 1;
+            record.totalSolEarned += fee + treasury;
+            record.totalTokenDeducted += tokenDeducted;
+            record.stakeAmount =
+                record.stakeAmount >= tokenDeducted
+                    ? record.stakeAmount - tokenDeducted
+                    : 0n;
+            break;
+        }
+        default:
+            return existing;
+    }
+    record.lastEventIndex = event.eventIndex;
+    record.lastUpdated = Date.now();
+    return record;
+}
+function relayerPubkeyFromEvent(event) {
+    const value = event.payload.relayer;
+    return value === null || value === undefined ? null : String(value);
+}
+function payloadBigInt(event, key) {
+    const value = event.payload[key];
+    if (value === null || value === undefined)
+        return 0n;
+    return BigInt(String(value));
+}
+function relayerStateToValue(state) {
+    return {
+        relayerPubkey: state.relayerPubkey,
+        name: state.name,
+        url: state.url,
+        feeBps: state.feeBps,
+        stakeAmount: state.stakeAmount.toString(),
+        isActive: state.isActive,
+        totalWithdrawals: state.totalWithdrawals,
+        totalSolEarned: state.totalSolEarned.toString(),
+        totalTokenDeducted: state.totalTokenDeducted.toString(),
+        lastUpdated: state.lastUpdated,
+        lastEventIndex: state.lastEventIndex.toString(),
+    };
+}
+function valueToRelayerState(value) {
+    return {
+        relayerPubkey: String(value.relayerPubkey),
+        name: String(value.name ?? ""),
+        url: String(value.url ?? ""),
+        feeBps: Number(value.feeBps ?? 0),
+        stakeAmount: BigInt(String(value.stakeAmount ?? "0")),
+        isActive: Boolean(value.isActive),
+        totalWithdrawals: Number(value.totalWithdrawals ?? 0),
+        totalSolEarned: BigInt(String(value.totalSolEarned ?? "0")),
+        totalTokenDeducted: BigInt(String(value.totalTokenDeducted ?? "0")),
+        lastUpdated: Number(value.lastUpdated ?? Date.now()),
+        lastEventIndex: BigInt(String(value.lastEventIndex ?? "-1")),
+    };
+}
+function relayerRecordFromValue(value) {
+    const { lastEventIndex: _lastEventIndex, ...record } = valueToRelayerState(value);
+    return record;
+}

package/dist/substream/runtime.d.ts

@@ -0,0 +1,38 @@
+import type { Context, SubstreamMode } from "../context.js";
+import type { EventScope, EventStore, ProjectionStore, SubstreamStores } from "../substream/types.js";
+import { ChainEventSyncer, ProjectionRegistry } from "../substream/chain/index.js";
+import { SubstreamModuleRegistry, type SubstreamModule, type SubstreamModuleRuntime } from "../substream/chain/registry.js";
+import { VoidifyProgram } from "../voidify/program.js";
+export interface SubstreamRuntimeConfig {
+    mode?: SubstreamMode;
+    timeout?: number;
+    healthCacheMs?: number;
+}
+export declare class SubstreamRuntime implements SubstreamModuleRuntime {
+    readonly ctx: Context;
+    readonly events: EventStore;
+    readonly projections: ProjectionStore;
+    readonly registry: SubstreamModuleRegistry;
+    readonly projectionRegistry: ProjectionRegistry;
+    readonly syncer: ChainEventSyncer;
+    readonly voidify: VoidifyProgram;
+    private readonly mode;
+    private readonly timeout;
+    private readonly healthCacheMs;
+    private healthState;
+    private initialized;
+    constructor(ctx: Context, stores: SubstreamStores, config?: SubstreamRuntimeConfig, modules?: readonly SubstreamModule[]);
+    initialize(): Promise<void>;
+    module(id: string): unknown;
+    sync(scope: EventScope): Promise<void>;
+    syncLocal(scope: EventScope): Promise<void>;
+    applyLiveEvent(eventScope: EventScope): Promise<void>;
+    applyLiveRecord(scope: EventScope, record: Parameters<ChainEventSyncer["applyLiveEvent"]>[1]): Promise<void>;
+    rebuildProjection(scope: EventScope, projectionId: string): Promise<void>;
+    private get baseUrl();
+    private resolveMode;
+    private healthCheck;
+    private syncRemote;
+    private fetchRemoteEvents;
+}
+export declare function createSubstreamRuntime(ctx: Context, stores: SubstreamStores, config?: SubstreamRuntimeConfig, modules?: readonly SubstreamModule[]): SubstreamRuntime;

package/dist/substream/runtime.js

@@ -0,0 +1,163 @@
+import { ChainEventSyncer, ProjectionRegistry, } from "../substream/chain/index.js";
+import { chainEventFromWire } from "../substream/chain/events.js";
+import { SubstreamModuleRegistry, } from "../substream/chain/registry.js";
+import { createSubstreamRegistry } from "../substream/modules/index.js";
+import { VoidifyProgram } from "../voidify/program.js";
+export class SubstreamRuntime {
+    ctx;
+    events;
+    projections;
+    registry;
+    projectionRegistry;
+    syncer;
+    voidify;
+    mode;
+    timeout;
+    healthCacheMs;
+    healthState = null;
+    initialized = false;
+    constructor(ctx, stores, config, modules) {
+        this.ctx = ctx;
+        this.events = stores.events;
+        this.projections = stores.projections;
+        this.mode = config?.mode ?? ctx.substream.type;
+        this.timeout = config?.timeout ?? 10000;
+        this.healthCacheMs = config?.healthCacheMs ?? 10000;
+        this.registry = modules
+            ? new SubstreamModuleRegistry([...modules])
+            : createSubstreamRegistry();
+        this.projectionRegistry = new ProjectionRegistry();
+        for (const projection of this.registry.createProjections(this.projections)) {
+            this.projectionRegistry.register(projection);
+        }
+        this.syncer = new ChainEventSyncer(this.events, this.projectionRegistry);
+        this.voidify = new VoidifyProgram(ctx.connection, ctx.programId);
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.events.initialize();
+        await this.projections.initialize();
+        this.initialized = true;
+    }
+    module(id) {
+        const module = this.registry.getById(id);
+        if (!module?.createClientApi) {
+            throw new Error(`Unknown substream module: ${id}`);
+        }
+        return module.createClientApi(this);
+    }
+    async sync(scope) {
+        const mode = await this.resolveMode();
+        if (mode === "local") {
+            await this.syncLocal(scope);
+            return;
+        }
+        try {
+            await this.syncRemote(scope);
+        }
+        catch (error) {
+            if (this.mode === "auto") {
+                this.healthState = { ok: false, checkedAt: Date.now() };
+                await this.syncLocal(scope);
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to sync substream scope ${scope.scopeType}:${scope.scopeKey}: ${message}`, {
+                cause: error,
+            });
+        }
+    }
+    async syncLocal(scope) {
+        await this.syncer.checkAndSync(this.registry.createStream(this.ctx, this.voidify, scope));
+    }
+    async applyLiveEvent(eventScope) {
+        await this.syncLocal(eventScope);
+    }
+    async applyLiveRecord(scope, record) {
+        await this.syncer.applyLiveEvent(this.registry.createStream(this.ctx, this.voidify, scope), record);
+    }
+    async rebuildProjection(scope, projectionId) {
+        const projection = this.projectionRegistry.get(projectionId);
+        if (!projection) {
+            throw new Error(`Unknown substream projection: ${projectionId}`);
+        }
+        await this.projections.clear(projectionId);
+        const events = await this.events.getAfter(scope);
+        await projection.apply(events.filter((event) => projection.matches(event)));
+    }
+    get baseUrl() {
+        const s = this.ctx.substream;
+        if (s.type === "local") {
+            throw new Error("baseUrl unavailable in local-only substream mode");
+        }
+        return s.url.replace(/\/$/, "");
+    }
+    async resolveMode() {
+        if (this.mode === "remote")
+            return "remote";
+        if (this.mode === "local")
+            return "local";
+        const now = Date.now();
+        if (this.healthState &&
+            now - this.healthState.checkedAt < this.healthCacheMs) {
+            return this.healthState.ok ? "remote" : "local";
+        }
+        const ok = await this.healthCheck();
+        const wasOk = this.healthState?.ok;
+        this.healthState = { ok, checkedAt: now };
+        if (!ok && wasOk !== false) {
+            console.log(`substream server unreachable at ${this.baseUrl}, falling back to local`);
+        }
+        else if (ok && wasOk === false) {
+            console.log(`substream server reachable at ${this.baseUrl}, using remote`);
+        }
+        return ok ? "remote" : "local";
+    }
+    async healthCheck() {
+        try {
+            const response = await fetch(`${this.baseUrl}/health`, {
+                method: "GET",
+                signal: AbortSignal.timeout(this.timeout),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async syncRemote(scope) {
+        const cursor = await this.events.getCursor(scope);
+        const afterIndex = cursor?.lastIndex ?? null;
+        const events = await this.fetchRemoteEvents(scope, afterIndex);
+        const newEvents = events.filter((event) => afterIndex === null || event.eventIndex > afterIndex);
+        if (newEvents.length === 0)
+            return;
+        const outcome = await this.events.applyBatch(scope, newEvents);
+        if (outcome.kind === "gap") {
+            throw new Error(`Remote events have a gap: expected ${outcome.expected.toString()}, got ${outcome.got.toString()}`);
+        }
+        await this.projectionRegistry.apply(newEvents);
+    }
+    async fetchRemoteEvents(scope, afterIndex) {
+        const params = new URLSearchParams();
+        if (afterIndex !== null && afterIndex !== undefined) {
+            params.set("after_index", afterIndex.toString());
+        }
+        const query = params.toString();
+        const url = `${this.baseUrl}/api/events/${scope.scopeType}/${scope.scopeKey}` +
+            (query ? `?${query}` : "");
+        const response = await fetch(url, {
+            method: "GET",
+            signal: AbortSignal.timeout(this.timeout),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch events: ${response.statusText}`);
+        }
+        const data = (await response.json());
+        return data.events.map(chainEventFromWire);
+    }
+}
+export function createSubstreamRuntime(ctx, stores, config, modules) {
+    return new SubstreamRuntime(ctx, stores, config, modules);
+}

package/dist/substream/server/event-listener.d.ts

@@ -0,0 +1,18 @@
+import { Program } from "@coral-xyz/anchor";
+import type { Voidify } from "../../idl/voidify/idl.js";
+export type EventCallback<T = any> = (event: T, signature: string, slot: number) => Promise<void>;
+export declare class EventListener {
+    private program;
+    private handlers;
+    private anchorListeners;
+    private nextListenerId;
+    constructor(program: Program<Voidify>);
+    registerHandler<T = any>(eventName: string, handler: EventCallback<T>): number;
+    unregisterHandler(_listenerId: number): void;
+    unregisterEvent(eventName: string): void;
+    removeAllListeners(): void;
+    getListenerCount(): number;
+    getRegisteredEvents(): string[];
+    private hasAnchorListener;
+    private createAnchorListener;
+}

package/dist/substream/server/event-listener.js

@@ -0,0 +1,68 @@
+import { substreamLogger as logger } from "../../utils/logger.js";
+export class EventListener {
+    program;
+    handlers = new Map();
+    anchorListeners = new Map();
+    nextListenerId = 1;
+    constructor(program) {
+        this.program = program;
+    }
+    registerHandler(eventName, handler) {
+        const listenerId = this.nextListenerId++;
+        if (!this.handlers.has(eventName)) {
+            this.handlers.set(eventName, []);
+        }
+        this.handlers.get(eventName).push(handler);
+        if (!this.hasAnchorListener(eventName)) {
+            this.createAnchorListener(eventName);
+        }
+        return listenerId;
+    }
+    unregisterHandler(_listenerId) { }
+    unregisterEvent(eventName) {
+        this.handlers.delete(eventName);
+        for (const [anchorId, name] of this.anchorListeners.entries()) {
+            if (name === eventName) {
+                this.program.removeEventListener(anchorId);
+                this.anchorListeners.delete(anchorId);
+                break;
+            }
+        }
+    }
+    removeAllListeners() {
+        for (const anchorId of this.anchorListeners.keys()) {
+            this.program.removeEventListener(anchorId);
+        }
+        this.anchorListeners.clear();
+        this.handlers.clear();
+    }
+    getListenerCount() {
+        return this.anchorListeners.size;
+    }
+    getRegisteredEvents() {
+        return Array.from(this.handlers.keys());
+    }
+    hasAnchorListener(eventName) {
+        for (const [, name] of this.anchorListeners.entries()) {
+            if (name === eventName) {
+                return true;
+            }
+        }
+        return false;
+    }
+    createAnchorListener(eventName) {
+        const anchorListenerId = this.program.addEventListener(eventName, async (event, slot, signature) => {
+            logger.info({ eventName, slot, signature }, "event received");
+            try {
+                const handlers = this.handlers.get(eventName);
+                if (handlers && handlers.length > 0) {
+                    await Promise.all(handlers.map((handler) => handler(event, signature, slot)));
+                }
+            }
+            catch (error) {
+                logger.error({ err: error, eventName, slot, signature }, "event handler failed");
+            }
+        });
+        this.anchorListeners.set(anchorListenerId, eventName);
+    }
+}

package/dist/substream/server/index.d.ts

@@ -0,0 +1,3 @@
+import { Context } from "../../context.js";
+import { SubstreamServiceOptions } from "../../substream/server/server.js";
+export declare function startSubstream(ctx: Context, options: SubstreamServiceOptions): Promise<void>;

package/dist/substream/server/index.js

@@ -0,0 +1,30 @@
+import { SubstreamService, } from "../../substream/server/server.js";
+import { substreamLogger as logger } from "../../utils/logger.js";
+export async function startSubstream(ctx, options) {
+    process.on("unhandledRejection", (reason) => {
+        logger.error({ reason }, "unhandledRejection");
+    });
+    process.on("uncaughtException", (err) => {
+        logger.error({ err }, "uncaughtException");
+        process.exit(1);
+    });
+    logger.info({
+        port: options.port,
+        dbPath: options.dbPath,
+    }, "Starting Substream service");
+    const service = new SubstreamService(ctx, options);
+    await service.start();
+    const shutdown = async () => {
+        logger.info("Received shutdown signal, stopping Substream service");
+        try {
+            await service.stop();
+        }
+        catch (err) {
+            logger.error({ err }, "substream stop failed");
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await new Promise(() => { });
+}

package/dist/substream/server/server.d.ts

@@ -0,0 +1,43 @@
+import { Context } from "../../context.js";
+import { type SubstreamRuntime } from "../../substream/runtime.js";
+export interface HttpServerConfig {
+    port: number;
+    host?: string;
+}
+export interface SubstreamServiceOptions {
+    port: number;
+    host?: string;
+    dbPath: string;
+}
+export declare class HttpServer {
+    private runtime;
+    private app;
+    private server;
+    private readonly host;
+    private readonly port;
+    constructor(runtime: SubstreamRuntime, config: HttpServerConfig);
+    private setupMiddleware;
+    private setupRoutes;
+    private handleHealth;
+    private handleGetEvents;
+    private parseScope;
+    private parseAfterIndex;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getAddress(): string;
+}
+export declare class SubstreamService {
+    private ctx;
+    private options;
+    private database;
+    private eventListener;
+    private httpServer;
+    private program;
+    private runtime;
+    private isRunning;
+    constructor(ctx: Context, options: SubstreamServiceOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private startEventListeners;
+    private cleanup;
+}