@metamask/ocap-kernel/dist/types.d.cts

OCap kernel core components

import type { SwingSetCapData, Message as SwingsetMessage, VatSyscallObject, VatSyscallSend } from "@agoric/swingset-liveslots";
import type { CapData } from "@endo/marshal";
import type { VatCheckpoint } from "@metamask/kernel-store";
import type { JsonRpcMessage } from "@metamask/kernel-utils";
import type { DuplexStream } from "@metamask/streams";
import type { Infer } from "@metamask/superstruct";
import type { Json } from "@metamask/utils";
export type VatId = string;
export type RemoteId = string;
export type EndpointId = VatId | RemoteId;
export type SubclusterId = string;
export type KRef = string;
export type VRef = string;
export type RRef = string;
export type ERef = VRef | RRef;
export type Ref = KRef | ERef;
export declare const ROOT_OBJECT_VREF: VRef;
export declare const CapDataStruct: import("@metamask/superstruct").Struct<{
    body: string;
    slots: string[];
}, {
    body: import("@metamask/superstruct").Struct<string, null>;
    slots: import("@metamask/superstruct").Struct<string[], import("@metamask/superstruct").Struct<string, null>>;
}>;
export declare const VatOneResolutionStruct: import("@metamask/superstruct").Struct<[string, boolean, {
    body: string;
    slots: string[];
}], null>;
export declare const MessageStruct: import("@metamask/superstruct").Struct<{
    methargs: {
        body: string;
        slots: string[];
    };
    result?: string | null;
}, {
    methargs: import("@metamask/superstruct").Struct<{
        body: string;
        slots: string[];
    }, {
        body: import("@metamask/superstruct").Struct<string, null>;
        slots: import("@metamask/superstruct").Struct<string[], import("@metamask/superstruct").Struct<string, null>>;
    }>;
    result: import("@metamask/superstruct").ExactOptionalStruct<string | null, null>;
}>;
/**
 * JSON-RPC-compatible Message type, originally from @agoric/swingset-liveslots.
 */
export type Message = Infer<typeof MessageStruct>;
/**
 * Coerce a {@link SwingsetMessage} to our own JSON-RPC-compatible {@link Message}.
 *
 * @param message - The SwingsetMessage to coerce.
 * @returns The coerced Message.
 */
export declare function coerceMessage(message: SwingsetMessage): Message;
type JsonVatSyscallObject = Exclude<VatSyscallObject, VatSyscallSend> | ['send', string, Message];
/**
 * Coerce a {@link VatSyscallObject} to a JSON-RPC-compatible {@link JsonVatSyscallObject}.
 *
 * @param vso - The VatSyscallObject to coerce.
 * @returns The coerced VatSyscallObject.
 */
export declare function coerceVatSyscallObject(vso: VatSyscallObject): JsonVatSyscallObject;
declare const RunQueueItemSendStruct: import("@metamask/superstruct").Struct<{
    type: "send";
    target: string;
    message: {
        methargs: {
            body: string;
            slots: string[];
        };
        result?: string | null;
    };
}, {
    type: import("@metamask/superstruct").Struct<"send", "send">;
    target: import("@metamask/superstruct").Struct<string, null>;
    message: import("@metamask/superstruct").Struct<{
        methargs: {
            body: string;
            slots: string[];
        };
        result?: string | null;
    }, {
        methargs: import("@metamask/superstruct").Struct<{
            body: string;
            slots: string[];
        }, {
            body: import("@metamask/superstruct").Struct<string, null>;
            slots: import("@metamask/superstruct").Struct<string[], import("@metamask/superstruct").Struct<string, null>>;
        }>;
        result: import("@metamask/superstruct").ExactOptionalStruct<string | null, null>;
    }>;
}>;
export type RunQueueItemSend = Infer<typeof RunQueueItemSendStruct>;
declare const RunQueueItemNotifyStruct: import("@metamask/superstruct").Struct<{
    type: "notify";
    vatId: string;
    kpid: string;
}, {
    type: import("@metamask/superstruct").Struct<"notify", "notify">;
    vatId: import("@metamask/superstruct").Struct<string, null>;
    kpid: import("@metamask/superstruct").Struct<string, null>;
}>;
export type RunQueueItemNotify = Infer<typeof RunQueueItemNotifyStruct>;
declare const GCRunQueueTypeStruct: import("@metamask/superstruct").Struct<"retireImports" | "retireExports" | "dropExports", null>;
export type GCRunQueueType = Infer<typeof GCRunQueueTypeStruct>;
export type GCActionType = 'dropExport' | 'retireExport' | 'retireImport';
export declare const actionTypePriorities: GCActionType[];
declare const RunQueueItemGCActionStruct: import("@metamask/superstruct").Struct<{
    type: "retireImports" | "retireExports" | "dropExports";
    vatId: string;
    krefs: string[];
}, {
    type: import("@metamask/superstruct").Struct<"retireImports" | "retireExports" | "dropExports", null>;
    vatId: import("@metamask/superstruct").Struct<string, null>;
    krefs: import("@metamask/superstruct").Struct<string[], import("@metamask/superstruct").Struct<string, null>>;
}>;
export type RunQueueItemGCAction = Infer<typeof RunQueueItemGCActionStruct>;
declare const RunQueueItemBringOutYourDeadStruct: import("@metamask/superstruct").Struct<{
    type: "bringOutYourDead";
    vatId: string;
}, {
    type: import("@metamask/superstruct").Struct<"bringOutYourDead", "bringOutYourDead">;
    vatId: import("@metamask/superstruct").Struct<string, null>;
}>;
export type RunQueueItemBringOutYourDead = Infer<typeof RunQueueItemBringOutYourDeadStruct>;
export declare const RunQueueItemStruct: import("@metamask/superstruct").Struct<{
    type: "send";
    target: string;
    message: {
        methargs: {
            body: string;
            slots: string[];
        };
        result?: string | null;
    };
} | {
    type: "notify";
    vatId: string;
    kpid: string;
} | {
    type: "retireImports" | "retireExports" | "dropExports";
    vatId: string;
    krefs: string[];
} | {
    type: "bringOutYourDead";
    vatId: string;
}, null>;
export type RunQueueItem = Infer<typeof RunQueueItemStruct>;
/**
 * Assert that a value is a valid message.
 *
 * @param value - The value to check.
 * @throws if the value is not a valid message.
 */
export declare function insistMessage(value: unknown): asserts value is Message;
type EndpointState<IdType> = {
    name: string;
    id: IdType;
    nextExportObjectIdCounter: number;
    nextExportPromiseIdCounter: number;
    eRefToKRef: Map<ERef, KRef>;
    kRefToERef: Map<KRef, ERef>;
};
type KernelVatState = {
    messagePort: typeof MessagePort;
    state: EndpointState<VatId>;
    source: string;
    kvTable: Map<string, string>;
};
type RemoteState = {
    state: EndpointState<RemoteId>;
    connectToURL: string;
};
export type PromiseState = 'unresolved' | 'fulfilled' | 'rejected';
export type KernelPromise = {
    state: PromiseState;
    decider?: EndpointId;
    subscribers?: EndpointId[];
    value?: CapData<KRef>;
};
export type KernelState = {
    vats: Map<VatId, KernelVatState>;
    remotes: Map<RemoteId, RemoteState>;
    kernelPromises: Map<KRef, KernelPromise>;
};
export declare const isVatId: (value: unknown) => value is VatId;
/**
 * Assert that a value is a valid vat id.
 *
 * @param value - The value to check.
 * @throws if the value is not a valid vat id.
 */
export declare function insistVatId(value: unknown): asserts value is VatId;
export declare const VatIdStruct: import("@metamask/superstruct").Struct<string, null>;
export declare const isSubclusterId: (value: unknown) => value is SubclusterId;
export declare const SubclusterIdStruct: import("@metamask/superstruct").Struct<string, null>;
export type VatMessageId = `m${number}`;
export declare const isVatMessageId: (value: unknown) => value is VatMessageId;
export declare const VatMessageIdStruct: import("@metamask/superstruct").Struct<`m${number}`, null>;
/**
 * A "service" for managing vat workers. Abstracts platform-specific details of
 * how vat workers are launched, terminated, and connected to the kernel.
 */
export type VatWorkerService = {
    /**
     * Launch a new worker with a specific vat id.
     *
     * @param vatId - The vat id of the worker to launch.
     * @param vatConfig - Configuration object describing vat.
     * @returns A promise for a duplex stream connected to the worker
     * which rejects if a worker with the given vat id already exists.
     */
    launch: (vatId: VatId, vatConfig: VatConfig) => Promise<DuplexStream<JsonRpcMessage, JsonRpcMessage>>;
    /**
     * Terminate a worker identified by its vat id.
     *
     * @param vatId - The vat id of the worker to terminate.
     * @param error - An optional error to terminate the worker with.
     * @returns A promise that resolves when the worker has terminated
     * or rejects if that worker does not exist.
     */
    terminate: (vatId: VatId, error?: Error) => Promise<void>;
    /**
     * Terminate all workers managed by the service.
     *
     * @returns A promise that resolves after all workers have terminated
     * or rejects if there was an error during termination.
     */
    terminateAll: () => Promise<void>;
};
export type VatConfig = UserCodeSpec & {
    creationOptions?: Record<string, Json>;
    parameters?: Record<string, Json>;
};
declare const UserCodeSpecStruct: import("@metamask/superstruct").Struct<{
    sourceSpec: string;
} | {
    bundleSpec: string;
} | {
    bundleName: string;
}, null>;
type UserCodeSpec = Infer<typeof UserCodeSpecStruct>;
export declare const VatConfigStruct: import("@metamask/superstruct").Struct<VatConfig, null>;
export declare const isVatConfig: (value: unknown) => value is VatConfig;
export type VatConfigTable = Record<string, VatConfig>;
export declare const ClusterConfigStruct: import("@metamask/superstruct").Struct<{
    bootstrap: string;
    vats: Record<string, VatConfig>;
    forceReset?: boolean;
    services?: string[];
    bundles?: Record<string, VatConfig>;
}, {
    bootstrap: import("@metamask/superstruct").Struct<string, null>;
    forceReset: import("@metamask/superstruct").ExactOptionalStruct<boolean, null>;
    services: import("@metamask/superstruct").ExactOptionalStruct<string[], import("@metamask/superstruct").Struct<string, null>>;
    vats: import("@metamask/superstruct").Struct<Record<string, VatConfig>, null>;
    bundles: import("@metamask/superstruct").ExactOptionalStruct<Record<string, VatConfig>, null>;
}>;
export type ClusterConfig = Infer<typeof ClusterConfigStruct>;
export declare const isClusterConfig: (value: unknown) => value is ClusterConfig;
export declare const SubclusterStruct: import("@metamask/superstruct").Struct<{
    id: string;
    vats: string[];
    config: {
        bootstrap: string;
        vats: Record<string, VatConfig>;
        forceReset?: boolean;
        services?: string[];
        bundles?: Record<string, VatConfig>;
    };
}, {
    id: import("@metamask/superstruct").Struct<string, null>;
    config: import("@metamask/superstruct").Struct<{
        bootstrap: string;
        vats: Record<string, VatConfig>;
        forceReset?: boolean;
        services?: string[];
        bundles?: Record<string, VatConfig>;
    }, {
        bootstrap: import("@metamask/superstruct").Struct<string, null>;
        forceReset: import("@metamask/superstruct").ExactOptionalStruct<boolean, null>;
        services: import("@metamask/superstruct").ExactOptionalStruct<string[], import("@metamask/superstruct").Struct<string, null>>;
        vats: import("@metamask/superstruct").Struct<Record<string, VatConfig>, null>;
        bundles: import("@metamask/superstruct").ExactOptionalStruct<Record<string, VatConfig>, null>;
    }>;
    vats: import("@metamask/superstruct").Struct<string[], import("@metamask/superstruct").Struct<string, null>>;
}>;
export type Subcluster = Infer<typeof SubclusterStruct>;
export declare const KernelStatusStruct: import("@metamask/superstruct").Struct<{
    vats: {
        id: string;
        config: VatConfig;
        subclusterId: string;
    }[];
    subclusters: {
        id: string;
        vats: string[];
        config: {
            bootstrap: string;
            vats: Record<string, VatConfig>;
            forceReset?: boolean;
            services?: string[];
            bundles?: Record<string, VatConfig>;
        };
    }[];
}, {
    subclusters: import("@metamask/superstruct").Struct<{
        id: string;
        vats: string[];
        config: {
            bootstrap: string;
            vats: Record<string, VatConfig>;
            forceReset?: boolean;
            services?: string[];
            bundles?: Record<string, VatConfig>;
        };
    }[], import("@metamask/superstruct").Struct<{
        id: string;
        vats: string[];
        config: {
            bootstrap: string;
            vats: Record<string, VatConfig>;
            forceReset?: boolean;
            services?: string[];
            bundles?: Record<string, VatConfig>;
        };
    }, {
        id: import("@metamask/superstruct").Struct<string, null>;
        config: import("@metamask/superstruct").Struct<{
            bootstrap: string;
            vats: Record<string, VatConfig>;
            forceReset?: boolean;
            services?: string[];
            bundles?: Record<string, VatConfig>;
        }, {
            bootstrap: import("@metamask/superstruct").Struct<string, null>;
            forceReset: import("@metamask/superstruct").ExactOptionalStruct<boolean, null>;
            services: import("@metamask/superstruct").ExactOptionalStruct<string[], import("@metamask/superstruct").Struct<string, null>>;
            vats: import("@metamask/superstruct").Struct<Record<string, VatConfig>, null>;
            bundles: import("@metamask/superstruct").ExactOptionalStruct<Record<string, VatConfig>, null>;
        }>;
        vats: import("@metamask/superstruct").Struct<string[], import("@metamask/superstruct").Struct<string, null>>;
    }>>;
    vats: import("@metamask/superstruct").Struct<{
        id: string;
        config: VatConfig;
        subclusterId: string;
    }[], import("@metamask/superstruct").Struct<{
        id: string;
        config: VatConfig;
        subclusterId: string;
    }, {
        id: import("@metamask/superstruct").Struct<string, null>;
        config: import("@metamask/superstruct").Struct<VatConfig, null>;
        subclusterId: import("@metamask/superstruct").Struct<string, null>;
    }>>;
}>;
export type KernelStatus = Infer<typeof KernelStatusStruct>;
export type UserCodeStartFn = (parameters?: Record<string, Json>) => object;
/**
 * A mapping of GC action type to queue event type.
 */
export declare const queueTypeFromActionType: Map<GCActionType, "retireImports" | "retireExports" | "dropExports">;
export declare const isGCActionType: (value: unknown) => value is GCActionType;
/**
 * Assert that a value is a valid GC action type.
 *
 * @param value - The value to check.
 * @throws if the value is not a valid GC action type.
 */
export declare function insistGCActionType(value: unknown): asserts value is GCActionType;
export type GCAction = `${VatId} ${GCActionType} ${KRef}`;
export declare const GCActionStruct: import("@metamask/superstruct").Struct<`${string} dropExport ${string}` | `${string} retireExport ${string}` | `${string} retireImport ${string}`, null>;
export declare const isGCAction: (value: unknown) => value is GCAction;
export type CrankResults = {
    didDelivery?: VatId;
    abort?: boolean;
    terminate?: {
        vatId: VatId;
        reject: boolean;
        info: SwingSetCapData;
    };
};
export type VatDeliveryResult = [VatCheckpoint, string | null];
export {};
//# sourceMappingURL=types.d.cts.map