@lit-protocol/e2e/src/helper/ShivaClient/createShivaClient.d.ts

Lit Protocol E2E testing package for running comprehensive integration tests

import { createLitClient } from '@lit-protocol/lit-client';
import { EpochSnapshot } from './helpers/createEpochSnapshot';
/**
 * Options used when Shiva spins up a brand-new testnet instance.
 * Values mirror the Rust manager contract; all fields are optional for our wrapper.
 */
type TestNetCreateRequest = {
    nodeCount: number;
    pollingInterval: string;
    epochLength: number;
    customBuildPath?: string | null;
    litActionServerCustomBuildPath?: string | null;
    existingConfigPath?: string | null;
    which?: string | null;
    ecdsaRoundTimeout?: string | null;
    enableRateLimiting?: string | null;
};
type TestNetState = 'Busy' | 'Active' | 'Mutating' | 'Shutdown' | 'UNKNOWN';
/**
 * Configuration accepted by {@link createShivaClient}.
 */
type CreateShivaClientOptions = {
    baseUrl: string;
    testnetId?: string;
    createRequest?: TestNetCreateRequest;
};
/**
 * Options for {@link ShivaClient.waitForEpochChange}.
 */
type WaitForEpochOptions = {
    expectedEpoch: number | undefined;
    timeoutMs?: number;
    intervalMs?: number;
};
type PollTestnetStateOptions = {
    waitFor?: TestNetState | TestNetState[];
    timeoutMs?: number;
    intervalMs?: number;
};
type WaitForTestnetInfoOptions = {
    timeoutMs?: number;
    intervalMs?: number;
};
export type ShivaTestnetInfo = {
    rpc_url?: string;
    [key: string]: unknown;
};
/**
 * High-level interface surfaced by {@link createShivaClient}.
 */
export type ShivaClient = {
    baseUrl: string;
    testnetId: string;
    /** Fetch a one-off snapshot of the Lit context and per-node epochs. */
    inspectEpoch: () => Promise<EpochSnapshot>;
    /**
     * Poll the Lit client until it reports an epoch different from {@link WaitForEpochOptions.baselineEpoch}.
     * Useful immediately after triggering an epoch change via Shiva.
     */
    waitForEpochChange: (options: WaitForEpochOptions) => Promise<EpochSnapshot>;
    /** Invoke Shiva's `/test/action/transition/epoch/wait/<id>` and wait for completion. */
    transitionEpochAndWait: () => Promise<boolean>;
    /** Stop a random node and wait for the subsequent epoch change. */
    stopRandomNodeAndWait: () => Promise<boolean>;
    /** Query the current state of the managed testnet (Busy, Active, etc.). */
    /**
     * @example
     * ```ts
     * // Wait up to two minutes for the testnet to become active.
     * await client.pollTestnetState({ waitFor: 'Active', timeoutMs: 120_000 });
     * ```
     */
    pollTestnetState: (options?: PollTestnetStateOptions) => Promise<TestNetState>;
    /** Retrieve the full testnet configuration (contract ABIs, RPC URL, etc.). */
    getTestnetInfo: () => Promise<ShivaTestnetInfo | null>;
    /** Poll the manager until `/test/get/info/testnet/<id>` returns a payload. */
    waitForTestnetInfo: (options?: WaitForTestnetInfoOptions) => Promise<ShivaTestnetInfo>;
    /** Shut down the underlying testnet through the Shiva manager. */
    deleteTestnet: () => Promise<boolean>;
    setLitClient: (litClient: Awaited<ReturnType<typeof createLitClient>>) => void;
};
/**
 * Creates a Shiva client wrapper for the provided Lit client instance.
 * The wrapper talks to the Shiva manager REST endpoints, auto-discovers (or optionally creates) a testnet,
 * and exposes helpers for triggering and validating epoch transitions.
 */
export declare const createShivaClient: (options: CreateShivaClientOptions) => Promise<ShivaClient>;
export {};