navskit/dist/types/index.d.ts

Deploy TypeScript logic on Ethereum. Includes core library, CLI tools, and utilities.

/**
 * Type definitions for the NAVS system
 */
import { Account } from 'viem';
/**
 * Represents a task ID with type information about the expected result
 */
export interface TaskId<T> {
    /** The numeric task ID */
    id: bigint;
    /** Function to await the task result */
    wait: (options?: WaitOptions) => Promise<T>;
}
/**
 * Options for waiting for a task result
 */
export interface WaitOptions {
    /** Maximum time to wait in milliseconds */
    timeout?: number;
    /** How frequently to poll for updates in milliseconds */
    pollInterval?: number;
}
/**
 * Configuration parameters for initializing NAVS
 */
export interface TNavsConfig {
    /** Service name used for task registration */
    serviceName: string;
    /** Service version used for task registration */
    serviceVersion?: string;
    /** Address of the AVS contract on L1 Ethereum */
    avsL1?: `0x${string}`;
    /** Address of the TaskDispatch contract on L2 Ethereum */
    taskDispatchL2?: `0x${string}`;
    /** Address of the Reexecution Endpoint contract */
    reexecutionEndpoint?: `0x${string}`;
    delegationManager?: `0x${string}`;
    allocationManager?: `0x${string}`;
    /** RPC URL for L2 (Base Sepolia) where TaskDispatch operates */
    l2rpcUrl?: string;
    /** RPC URL for L1 (Ethereum Sepolia) where the AVS lives */
    rpcUrlL1?: string;
}
export interface TStrictNavsConfig extends TNavsConfig {
    serviceName: string;
    serviceVersion: string;
    avsL1: `0x${string}`;
    taskDispatchL2: `0x${string}`;
    reexecutionEndpoint: `0x${string}`;
    delegationManager: `0x${string}`;
    allocationManager: `0x${string}`;
    l2rpcUrl: string | undefined;
    rpcUrlL1: string | undefined;
}
/**
 * Tools for interacting with the consensus + operator layer of navs.
 *
 * Using the `@navs` annotation's `onResponses` callback, you can do things like;
 *     - output a final answer which is an average of the operator answers.
 *     - slash operators whose outputs fall outside of a certain number of std deviations
 *     - reward operators who act quickly or correctly
 *
 *
 * Developer notes:
 *     - all usages of these tools must be deterministic per the input data.
 *     - breaks on determinism will result in operator ejection.
 */
export interface TTools {
    /**
     * slash the given operator for `amountWei`.
     *      - operator must be part of the current task
     */
    slash: (operator: `0x${string}`, percentageOutOf100: number, description: string) => void;
    /**
     * ejects the operator from your operator set, providing the given justification.
     *      - operator must be a part of the current task
     */
    eject: (operator: `0x${string}`, justification: string) => void;
}
export type TFun<R> = (...args: any[]) => (R | Promise<R>);
export interface TResponse<T> {
    raw: `0x${string}`;
    decoded: T;
    submissionTimestampMs: number;
}
export interface TOnResponseArgs<T extends TFun<any>> {
    responses: Record<`0x${string}`, TResponse<ReturnType<T>>>;
    quorum: TResponse<ReturnType<T>> | undefined;
    tools: TTools;
    stake: Record<`0x${string}`, bigint>;
}
export type TOnResponses<T extends TFun<any>> = (args: TOnResponseArgs<T>) => ReturnType<T>;
/**
 * Configuration options for @navs decorator
 */
export interface NavsConfig {
    /**
     * Whether this function produces deterministic results
     * @deprecated This feature is not fully implemented yet
     */
    deterministic?: boolean;
}
/**
 * A function registered with NAVS
 */
export interface NavsFunction<T extends TFun<any>> {
    /** The function implementation */
    fn: Function;
    /** Parameter types for the function */
    paramTypes: string[];
    /** Return type of the function */
    returnType: string;
    /** Service name this function belongs to */
    serviceName: string;
    /** Function to decode encoded arguments */
    decodeArgs: (encodedArgs: `0x${string}`) => any[];
    consensus?: TOnResponses<T>;
    /**
     * Whether this function produces deterministic results
     * @deprecated This feature is not fully implemented yet
     */
    deterministic?: boolean;
}
/**
 * Options for executing a NAVS function
 */
export interface ExecuteOptions {
    /** Account to use for the transaction */
    account: Account;
    /**
     * Minimum stake threshold for result agreement
     * (higher values require more operators to agree)
     */
    stakeThreshold?: bigint;
}
/**
 * Type mapping for conversion between NAVS and ABI types
 */
export interface TypeMapping {
    /** The ABI type */
    abiType: string;
    /** Function to encode values to the ABI format */
    encoder: (val: any) => any;
    /** Function to decode values from the ABI format */
    decoder: (val: any) => any;
}