@vtechcom/hexcore 2.0.0-beta.1

package/node_modules/@hexcore/shared/dist/cjs/api.d.ts

@@ -0,0 +1,730 @@
+/**
+ * Request/response contracts. Imported by the control-plane (validation) AND the
+ * web UI (typed fetch) so the two can never drift.
+ */
+import { z } from 'zod';
+import { type CardanoNetwork } from './domain';
+/**
+ * Creating a head in v2 only needs a name and a node count — the control-plane
+ * generates every Hydra/Cardano key itself. In v1 the caller had to supply
+ * pre-generated key material for every node, which was the single biggest
+ * source of setup friction.
+ */
+/**
+ * A Blockfrost project id carries the network in its prefix. Checking the shape
+ * here turns a typo into a field error on the create form instead of a head
+ * that boots and then never observes its own init transaction.
+ */
+export declare const blockfrostProjectIdSchema: z.ZodString;
+/**
+ * Offline-mode settings. Only read when `chainBackend` is `offline`; the flags
+ * they produce are mutually exclusive with every online one (see offline.ts).
+ */
+export declare const offlineConfigSchema: z.ZodObject<{
+    /**
+     * `--offline-head-seed`. Left out, it is derived from the head id, which is
+     * both unique per head and stable across restarts — two heads sharing a
+     * seed would derive the same head id.
+     */
+    headSeed: z.ZodOptional<z.ZodString>;
+    /**
+     * The L2 ledger's entire starting state, verbatim, as hydra-node's
+     * `--initial-utxo` file. Left out, each node's own address is seeded with
+     * `seedLovelace` — so the operator holds the keys to everything in the head
+     * without having to write this by hand.
+     */
+    initialUtxo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * Bounded well below Number.MAX_SAFE_INTEGER: the value ends up in a JSON
+     * file read as JSON, and a seed large enough to round is a typo, not a
+     * requirement.
+     */
+    seedLovelace: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Shelley genesis for `--ledger-genesis`, which gives the simulated L1 its
+     * slot/time arithmetic. Genuinely optional — hydra-node's own default is
+     * "no genesis file" — so it is omitted rather than invented when absent: a
+     * hand-built partial genesis fails to decode and kills the node at startup.
+     */
+    ledgerGenesis: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    seedLovelace: number;
+    headSeed?: string | undefined;
+    initialUtxo?: Record<string, unknown> | undefined;
+    ledgerGenesis?: Record<string, unknown> | undefined;
+}, {
+    headSeed?: string | undefined;
+    initialUtxo?: Record<string, unknown> | undefined;
+    seedLovelace?: number | undefined;
+    ledgerGenesis?: Record<string, unknown> | undefined;
+}>;
+export type OfflineConfigInput = z.infer<typeof offlineConfigSchema>;
+/** Per-head logging. See HeadLoggingView for why hydra-node and Docker knobs sit together. */
+export declare const headLoggingSchema: z.ZodObject<{
+    /** hydra-node `--quiet`. */
+    quiet: z.ZodDefault<z.ZodBoolean>;
+    /** Docker json-file max-size per file, in MB. */
+    maxSizeMb: z.ZodDefault<z.ZodNumber>;
+    /** Docker json-file max-file. */
+    maxFiles: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    quiet: boolean;
+    maxSizeMb: number;
+    maxFiles: number;
+}, {
+    quiet?: boolean | undefined;
+    maxSizeMb?: number | undefined;
+    maxFiles?: number | undefined;
+}>;
+export type HeadLoggingInput = z.infer<typeof headLoggingSchema>;
+export declare const createHeadSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    /** 1 = solo head (useful for smoke tests), up to 10 peers. */
+    nodeCount: z.ZodDefault<z.ZodNumber>;
+    network: z.ZodOptional<z.ZodEnum<["preprod", "preview", "mainnet"]>>;
+    chainBackend: z.ZodOptional<z.ZodEnum<["blockfrost", "cardano-node", "offline"]>>;
+    contestationPeriod: z.ZodDefault<z.ZodNumber>;
+    depositPeriod: z.ZodDefault<z.ZodNumber>;
+    persistenceRotateAfter: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Overrides merged on top of whatever protocol parameters are fetched at
+     * start. TOP-LEVEL keys only: the merge is a shallow spread, so a partial
+     * nested object replaces its whole key and drops the siblings. The create
+     * form builds these with `diffProtocolParameters`, which is what keeps them
+     * whole — see protocol-params.ts.
+     */
+    protocolParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Only read when chainBackend is `offline`. */
+    offline: z.ZodOptional<z.ZodObject<{
+        /**
+         * `--offline-head-seed`. Left out, it is derived from the head id, which is
+         * both unique per head and stable across restarts — two heads sharing a
+         * seed would derive the same head id.
+         */
+        headSeed: z.ZodOptional<z.ZodString>;
+        /**
+         * The L2 ledger's entire starting state, verbatim, as hydra-node's
+         * `--initial-utxo` file. Left out, each node's own address is seeded with
+         * `seedLovelace` — so the operator holds the keys to everything in the head
+         * without having to write this by hand.
+         */
+        initialUtxo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /**
+         * Bounded well below Number.MAX_SAFE_INTEGER: the value ends up in a JSON
+         * file read as JSON, and a seed large enough to round is a typo, not a
+         * requirement.
+         */
+        seedLovelace: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Shelley genesis for `--ledger-genesis`, which gives the simulated L1 its
+         * slot/time arithmetic. Genuinely optional — hydra-node's own default is
+         * "no genesis file" — so it is omitted rather than invented when absent: a
+         * hand-built partial genesis fails to decode and kills the node at startup.
+         */
+        ledgerGenesis: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        seedLovelace: number;
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    }, {
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        seedLovelace?: number | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    }>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        /** hydra-node `--quiet`. */
+        quiet: z.ZodDefault<z.ZodBoolean>;
+        /** Docker json-file max-size per file, in MB. */
+        maxSizeMb: z.ZodDefault<z.ZodNumber>;
+        /** Docker json-file max-file. */
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        quiet: boolean;
+        maxSizeMb: number;
+        maxFiles: number;
+    }, {
+        quiet?: boolean | undefined;
+        maxSizeMb?: number | undefined;
+        maxFiles?: number | undefined;
+    }>>;
+    /**
+     * Blockfrost key for every node of this head, unless a node overrides it
+     * below. Optional: left out, nodes fall back to the server-wide key, and
+     * the control-plane refuses the head if there isn't one.
+     */
+    blockfrostProjectId: z.ZodOptional<z.ZodString>;
+    /**
+     * Per-node keys, one per node in index order.
+     *
+     * Blockfrost meters per project id, so a head whose nodes all share one key
+     * spends a single rate limit budget N ways — fine for a smoke test, not for
+     * N independent participants. Sharing stays the default (this is left out,
+     * or filled with the same value); giving each node its own is a matter of
+     * filling the array.
+     */
+    nodeBlockfrostProjectIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Cardano payment keys to reuse instead of generating, one entry per node
+     * in index order; null for a node that should get a fresh pair.
+     *
+     * The point is funds: a generated node starts at a brand-new address that
+     * has to be filled from the faucet before the head can commit anything.
+     * Supplying a key that already holds test ADA skips that entirely.
+     *
+     * Hydra keys are never imported — they only sign Head protocol messages,
+     * so there is no state attached to carrying one over.
+     */
+    nodeCardanoKeys: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodObject<{
+        /** A .skey file, its cborHex, 64 hex chars, or ed25519_sk1… */
+        signingKey: z.ZodString;
+        /** Optional .vkey, checked against the signing key. */
+        verificationKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        signingKey: string;
+        verificationKey?: string | undefined;
+    }, {
+        signingKey: string;
+        verificationKey?: string | undefined;
+    }>>, "many">>;
+    /**
+     * Optional per-head hydra-node image; falls back to HYDRA_NODE_IMAGE.
+     *
+     * Any reference is accepted, not just the ones in HYDRA_VERSION_PROFILES —
+     * a tag with no profile is probed instead of refused, so a fork or a release
+     * newer than this build still boots. What the tag cannot be is empty or
+     * whitespace-bearing, which would reach Docker as an unparseable ref.
+     */
+    hydraNodeImage: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    nodeCount: number;
+    contestationPeriod: number;
+    depositPeriod: number;
+    persistenceRotateAfter: number;
+    offline?: {
+        seedLovelace: number;
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    } | undefined;
+    description?: string | undefined;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    chainBackend?: "blockfrost" | "cardano-node" | "offline" | undefined;
+    protocolParameters?: Record<string, unknown> | undefined;
+    logging?: {
+        quiet: boolean;
+        maxSizeMb: number;
+        maxFiles: number;
+    } | undefined;
+    blockfrostProjectId?: string | undefined;
+    nodeBlockfrostProjectIds?: string[] | undefined;
+    nodeCardanoKeys?: ({
+        signingKey: string;
+        verificationKey?: string | undefined;
+    } | null)[] | undefined;
+    hydraNodeImage?: string | undefined;
+}, {
+    name: string;
+    offline?: {
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        seedLovelace?: number | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    } | undefined;
+    description?: string | undefined;
+    nodeCount?: number | undefined;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    chainBackend?: "blockfrost" | "cardano-node" | "offline" | undefined;
+    contestationPeriod?: number | undefined;
+    depositPeriod?: number | undefined;
+    persistenceRotateAfter?: number | undefined;
+    protocolParameters?: Record<string, unknown> | undefined;
+    logging?: {
+        quiet?: boolean | undefined;
+        maxSizeMb?: number | undefined;
+        maxFiles?: number | undefined;
+    } | undefined;
+    blockfrostProjectId?: string | undefined;
+    nodeBlockfrostProjectIds?: string[] | undefined;
+    nodeCardanoKeys?: ({
+        signingKey: string;
+        verificationKey?: string | undefined;
+    } | null)[] | undefined;
+    hydraNodeImage?: string | undefined;
+}>, {
+    name: string;
+    nodeCount: number;
+    contestationPeriod: number;
+    depositPeriod: number;
+    persistenceRotateAfter: number;
+    offline?: {
+        seedLovelace: number;
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    } | undefined;
+    description?: string | undefined;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    chainBackend?: "blockfrost" | "cardano-node" | "offline" | undefined;
+    protocolParameters?: Record<string, unknown> | undefined;
+    logging?: {
+        quiet: boolean;
+        maxSizeMb: number;
+        maxFiles: number;
+    } | undefined;
+    blockfrostProjectId?: string | undefined;
+    nodeBlockfrostProjectIds?: string[] | undefined;
+    nodeCardanoKeys?: ({
+        signingKey: string;
+        verificationKey?: string | undefined;
+    } | null)[] | undefined;
+    hydraNodeImage?: string | undefined;
+}, {
+    name: string;
+    offline?: {
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        seedLovelace?: number | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    } | undefined;
+    description?: string | undefined;
+    nodeCount?: number | undefined;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    chainBackend?: "blockfrost" | "cardano-node" | "offline" | undefined;
+    contestationPeriod?: number | undefined;
+    depositPeriod?: number | undefined;
+    persistenceRotateAfter?: number | undefined;
+    protocolParameters?: Record<string, unknown> | undefined;
+    logging?: {
+        quiet?: boolean | undefined;
+        maxSizeMb?: number | undefined;
+        maxFiles?: number | undefined;
+    } | undefined;
+    blockfrostProjectId?: string | undefined;
+    nodeBlockfrostProjectIds?: string[] | undefined;
+    nodeCardanoKeys?: ({
+        signingKey: string;
+        verificationKey?: string | undefined;
+    } | null)[] | undefined;
+    hydraNodeImage?: string | undefined;
+}>;
+export type CreateHeadInput = z.infer<typeof createHeadSchema>;
+export declare const updateHeadSchema: z.ZodObject<{
+    offline: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        /**
+         * `--offline-head-seed`. Left out, it is derived from the head id, which is
+         * both unique per head and stable across restarts — two heads sharing a
+         * seed would derive the same head id.
+         */
+        headSeed: z.ZodOptional<z.ZodString>;
+        /**
+         * The L2 ledger's entire starting state, verbatim, as hydra-node's
+         * `--initial-utxo` file. Left out, each node's own address is seeded with
+         * `seedLovelace` — so the operator holds the keys to everything in the head
+         * without having to write this by hand.
+         */
+        initialUtxo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /**
+         * Bounded well below Number.MAX_SAFE_INTEGER: the value ends up in a JSON
+         * file read as JSON, and a seed large enough to round is a typo, not a
+         * requirement.
+         */
+        seedLovelace: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Shelley genesis for `--ledger-genesis`, which gives the simulated L1 its
+         * slot/time arithmetic. Genuinely optional — hydra-node's own default is
+         * "no genesis file" — so it is omitted rather than invented when absent: a
+         * hand-built partial genesis fails to decode and kills the node at startup.
+         */
+        ledgerGenesis: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        seedLovelace: number;
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    }, {
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        seedLovelace?: number | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    }>>>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    network: z.ZodOptional<z.ZodOptional<z.ZodEnum<["preprod", "preview", "mainnet"]>>>;
+    chainBackend: z.ZodOptional<z.ZodOptional<z.ZodEnum<["blockfrost", "cardano-node", "offline"]>>>;
+    contestationPeriod: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    depositPeriod: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    persistenceRotateAfter: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    protocolParameters: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    logging: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        /** hydra-node `--quiet`. */
+        quiet: z.ZodDefault<z.ZodBoolean>;
+        /** Docker json-file max-size per file, in MB. */
+        maxSizeMb: z.ZodDefault<z.ZodNumber>;
+        /** Docker json-file max-file. */
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        quiet: boolean;
+        maxSizeMb: number;
+        maxFiles: number;
+    }, {
+        quiet?: boolean | undefined;
+        maxSizeMb?: number | undefined;
+        maxFiles?: number | undefined;
+    }>>>;
+    blockfrostProjectId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    nodeBlockfrostProjectIds: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    nodeCardanoKeys: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodObject<{
+        /** A .skey file, its cborHex, 64 hex chars, or ed25519_sk1… */
+        signingKey: z.ZodString;
+        /** Optional .vkey, checked against the signing key. */
+        verificationKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        signingKey: string;
+        verificationKey?: string | undefined;
+    }, {
+        signingKey: string;
+        verificationKey?: string | undefined;
+    }>>, "many">>>;
+    hydraNodeImage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+} & {
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    offline?: {
+        seedLovelace: number;
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    } | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    chainBackend?: "blockfrost" | "cardano-node" | "offline" | undefined;
+    contestationPeriod?: number | undefined;
+    depositPeriod?: number | undefined;
+    persistenceRotateAfter?: number | undefined;
+    protocolParameters?: Record<string, unknown> | undefined;
+    logging?: {
+        quiet: boolean;
+        maxSizeMb: number;
+        maxFiles: number;
+    } | undefined;
+    blockfrostProjectId?: string | undefined;
+    nodeBlockfrostProjectIds?: string[] | undefined;
+    nodeCardanoKeys?: ({
+        signingKey: string;
+        verificationKey?: string | undefined;
+    } | null)[] | undefined;
+    hydraNodeImage?: string | undefined;
+}, {
+    offline?: {
+        headSeed?: string | undefined;
+        initialUtxo?: Record<string, unknown> | undefined;
+        seedLovelace?: number | undefined;
+        ledgerGenesis?: Record<string, unknown> | undefined;
+    } | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    chainBackend?: "blockfrost" | "cardano-node" | "offline" | undefined;
+    contestationPeriod?: number | undefined;
+    depositPeriod?: number | undefined;
+    persistenceRotateAfter?: number | undefined;
+    protocolParameters?: Record<string, unknown> | undefined;
+    logging?: {
+        quiet?: boolean | undefined;
+        maxSizeMb?: number | undefined;
+        maxFiles?: number | undefined;
+    } | undefined;
+    blockfrostProjectId?: string | undefined;
+    nodeBlockfrostProjectIds?: string[] | undefined;
+    nodeCardanoKeys?: ({
+        signingKey: string;
+        verificationKey?: string | undefined;
+    } | null)[] | undefined;
+    hydraNodeImage?: string | undefined;
+}>;
+export type UpdateHeadInput = z.infer<typeof updateHeadSchema>;
+/**
+ * Check a Cardano key before it is committed to a head.
+ *
+ * Pasting a key is the one step of head creation with no feedback: the address
+ * it produces is not visible until the head exists, and by then a wrong key
+ * means deleting and starting over. This answers "what address is this, and
+ * does it hold anything" while the form is still open.
+ */
+export declare const verifyCardanoKeySchema: z.ZodObject<{
+    signingKey: z.ZodString;
+    /** Optional, and only ever cross-checked against the signing key. */
+    verificationKey: z.ZodOptional<z.ZodString>;
+    /** Defaults to the server's network — the address differs per network. */
+    network: z.ZodOptional<z.ZodEnum<["preprod", "preview", "mainnet"]>>;
+    /**
+     * Key to look the balance up with, for a head that will carry its own.
+     * Falls back to the server-wide one; without either, the address still
+     * comes back and the balance does not.
+     */
+    blockfrostProjectId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    signingKey: string;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    blockfrostProjectId?: string | undefined;
+    verificationKey?: string | undefined;
+}, {
+    signingKey: string;
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    blockfrostProjectId?: string | undefined;
+    verificationKey?: string | undefined;
+}>;
+export type VerifyCardanoKeyInput = z.infer<typeof verifyCardanoKeySchema>;
+export interface VerifyCardanoKeyResult {
+    /** Enterprise address the signing key produces on `network`. */
+    address: string;
+    network: CardanoNetwork;
+    /** Present only when the pair was supplied and agrees. */
+    verificationKeyMatches?: boolean;
+    /** null when no chain connection was available to ask. */
+    balance: {
+        lovelace: string;
+        utxoCount: number;
+    } | null;
+    /** Why the balance is null — a missing key, or the lookup failing. */
+    balanceUnavailable?: string;
+}
+/**
+ * The protocol parameters a head created right now would boot with.
+ *
+ * The create form needs the effective baseline before it can offer to edit it:
+ * overrides merge at the top level, so a field can only be changed safely by
+ * starting from the whole current value and diffing. Asking the server also
+ * keeps the browser out of the business of holding a Blockfrost key.
+ */
+export declare const protocolParametersQuerySchema: z.ZodObject<{
+    network: z.ZodOptional<z.ZodEnum<["preprod", "preview", "mainnet"]>>;
+    /** For a head that will carry its own key, before it exists. */
+    blockfrostProjectId: z.ZodOptional<z.ZodString>;
+    /** Set false to see real L1 fees instead of the zeroed L2 ones. */
+    zeroFees: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    blockfrostProjectId?: string | undefined;
+    zeroFees?: boolean | undefined;
+}, {
+    network?: "preprod" | "preview" | "mainnet" | undefined;
+    blockfrostProjectId?: string | undefined;
+    zeroFees?: boolean | undefined;
+}>;
+export type ProtocolParametersQuery = z.infer<typeof protocolParametersQuerySchema>;
+export interface ProtocolParametersResult {
+    parameters: Record<string, unknown>;
+    /** `blockfrost` when live values were fetched, `defaults` for the static baseline. */
+    source: 'blockfrost' | 'defaults';
+    /** Why the static baseline was used, when it was. */
+    note?: string;
+}
+export declare const listHeadsQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status?: string | undefined;
+}, {
+    status?: string | undefined;
+}>;
+/** Wipe persistence dirs so the head can restart from a clean slate. */
+export declare const resetHeadSchema: z.ZodObject<{
+    /** Also delete generated key material (forces brand-new addresses). */
+    includeKeys: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    includeKeys: boolean;
+}, {
+    includeKeys?: boolean | undefined;
+}>;
+export type ResetHeadInput = z.infer<typeof resetHeadSchema>;
+export declare const loginSchema: z.ZodObject<{
+    username: z.ZodString;
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    username: string;
+    password: string;
+}, {
+    username: string;
+    password: string;
+}>;
+export type LoginInput = z.infer<typeof loginSchema>;
+/**
+ * First-run setup.
+ *
+ * Until this exists, standing up Hexcore meant editing a 123-line `.env` by
+ * hand — which assumes the reader already knows what a Blockfrost project id is
+ * and which of thirty keys matter. docs/PRODUCT.md names non-technical
+ * operators as a first-class audience, and that file is where they stopped.
+ *
+ * The settings a wizard may write are deliberately a SMALL subset of the env
+ * schema. Two rules decide what is in:
+ *
+ *  1. It must be answerable by someone who has not read the code. `PORT_BASE`
+ *     and `HYDRA_UNSYNCED_PERIOD` are not; they stay env-only, where whoever
+ *     needs them will find them.
+ *  2. It must be applicable without a restart. `PORT` and `STATE_DIR` are read
+ *     once while the process boots — offering them in a web form would produce
+ *     a saved setting that silently does not take effect.
+ */
+export declare const settingsSchema: z.ZodObject<{
+    network: z.ZodEnum<["preprod", "preview", "mainnet"]>;
+    chainBackend: z.ZodEnum<["blockfrost", "cardano-node", "offline"]>;
+    /**
+     * Blank clears it. The wizard sends what the operator typed, and an empty
+     * box has to mean "no key" rather than "keep the old one" — the opposite
+     * rule is what makes a settings form unable to remove a value.
+     */
+    blockfrostProjectId: z.ZodOptional<z.ZodString>;
+    cardanoNodeSocket: z.ZodOptional<z.ZodString>;
+    /** Default image for heads that name none; a head can still pin its own. */
+    hydraNodeImage: z.ZodOptional<z.ZodString>;
+    adminUsername: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    network: "preprod" | "preview" | "mainnet";
+    chainBackend: "blockfrost" | "cardano-node" | "offline";
+    blockfrostProjectId?: string | undefined;
+    hydraNodeImage?: string | undefined;
+    cardanoNodeSocket?: string | undefined;
+    adminUsername?: string | undefined;
+}, {
+    network: "preprod" | "preview" | "mainnet";
+    chainBackend: "blockfrost" | "cardano-node" | "offline";
+    blockfrostProjectId?: string | undefined;
+    hydraNodeImage?: string | undefined;
+    cardanoNodeSocket?: string | undefined;
+    adminUsername?: string | undefined;
+}>;
+export type SettingsInput = z.infer<typeof settingsSchema>;
+/**
+ * The setup request.
+ *
+ * Carries the admin password, which is the one value that must never reach the
+ * settings file: it is handed to the auth service, hashed into `secrets.json`,
+ * and dropped. Left blank, one is generated and printed once — the same
+ * behaviour a fresh boot has always had.
+ */
+export declare const completeSetupSchema: z.ZodObject<{
+    network: z.ZodEnum<["preprod", "preview", "mainnet"]>;
+    chainBackend: z.ZodEnum<["blockfrost", "cardano-node", "offline"]>;
+    /**
+     * Blank clears it. The wizard sends what the operator typed, and an empty
+     * box has to mean "no key" rather than "keep the old one" — the opposite
+     * rule is what makes a settings form unable to remove a value.
+     */
+    blockfrostProjectId: z.ZodOptional<z.ZodString>;
+    cardanoNodeSocket: z.ZodOptional<z.ZodString>;
+    /** Default image for heads that name none; a head can still pin its own. */
+    hydraNodeImage: z.ZodOptional<z.ZodString>;
+    adminUsername: z.ZodOptional<z.ZodString>;
+} & {
+    /**
+     * Proves the caller can read the terminal Hexcore was started from.
+     *
+     * Setup is necessarily reachable without a token — it is where the password
+     * is set — so on any interface but loopback the first request wins, and on
+     * a shared network that is a takeover. The CLI prints the URL with this in
+     * it, so for the person who just ran `hexcore` it costs a click.
+     */
+    setupToken: z.ZodString;
+    adminPassword: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    network: "preprod" | "preview" | "mainnet";
+    chainBackend: "blockfrost" | "cardano-node" | "offline";
+    setupToken: string;
+    blockfrostProjectId?: string | undefined;
+    hydraNodeImage?: string | undefined;
+    cardanoNodeSocket?: string | undefined;
+    adminUsername?: string | undefined;
+    adminPassword?: string | undefined;
+}, {
+    network: "preprod" | "preview" | "mainnet";
+    chainBackend: "blockfrost" | "cardano-node" | "offline";
+    setupToken: string;
+    blockfrostProjectId?: string | undefined;
+    hydraNodeImage?: string | undefined;
+    cardanoNodeSocket?: string | undefined;
+    adminUsername?: string | undefined;
+    adminPassword?: string | undefined;
+}>;
+export type CompleteSetupInput = z.infer<typeof completeSetupSchema>;
+/** Public, pre-login: what the UI needs to decide whether to show the wizard. */
+export interface SetupStatus {
+    /** No settings have been saved and no `.env` was found. */
+    required: boolean;
+    /**
+     * Why setup is considered done, when it is. Worth stating: an operator
+     * whose `.env` is being read but who expected the wizard needs to know
+     * which of the two Hexcore picked.
+     */
+    completedVia?: 'wizard' | 'env-file' | 'environment';
+    completedAt?: string;
+    /** Suggested defaults for the form, from whatever is already resolvable. */
+    defaults: SettingsInput;
+    /** True when the server is only listening on loopback. */
+    loopbackOnly: boolean;
+}
+/** Where a resolved setting actually came from. Answers "why is this value X". */
+export type SettingSource = 'environment' | 'env-file' | 'settings-file' | 'default';
+export interface SettingProvenance {
+    key: string;
+    /** Secrets are reported as whether they are set, never as their value. */
+    value: string | null;
+    secret: boolean;
+    source: SettingSource;
+}
+/**
+ * How far a wipe goes.
+ *
+ * Split into three because the middle one is the one people actually want and
+ * the last one destroys money. A head's Cardano keys control addresses that may
+ * hold test ADA — or, on mainnet, ADA — and Hexcore is the only place they
+ * exist. `everything` is therefore CLI-only; see the note on cleanSchema.
+ */
+export declare const cleanScopeSchema: z.ZodEnum<["config", "heads", "everything"]>;
+export type CleanScope = z.infer<typeof cleanScopeSchema>;
+/**
+ * `everything` is deliberately absent from the API surface.
+ *
+ * Two reasons, and the second is not negotiable: it deletes the key material
+ * behind funded addresses, and it deletes the SQLite database the request is
+ * being served from. A server cannot honestly delete its own state mid-request
+ * and then answer. `hexcore clean --all` does it with the process stopped.
+ */
+export declare const cleanSchema: z.ZodObject<{
+    scope: z.ZodEnum<["config", "heads"]>;
+    /** Must equal the machine's own name; the UI shows which to type. */
+    confirm: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    scope: "config" | "heads";
+    confirm: string;
+}, {
+    scope: "config" | "heads";
+    confirm: string;
+}>;
+export type CleanInput = z.infer<typeof cleanSchema>;
+export interface CleanResult {
+    scope: CleanScope;
+    headsRemoved: number;
+    containersRemoved: number;
+    /** Set when the wipe cleared settings and setup is required again. */
+    setupRequired: boolean;
+}
+/** Uniform envelope for every control-plane response. */
+export interface ApiOk<T> {
+    ok: true;
+    data: T;
+}
+export interface ApiErr {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+export type ApiResponse<T> = ApiOk<T> | ApiErr;
+//# sourceMappingURL=api.d.ts.map