@easy1staking/cip113-sdk-ts 0.10.0 → 0.11.0

package/dist/standard/bootstrap.d.ts

@@ -0,0 +1,552 @@
+/**
+ * Protocol bootstrap — the transactions that stand up a CIP-113 instance.
+ *
+ * TARGETS CIP-113 0.5.0-alpha.4 (upstream 7e8a63198c5b240135f1aa2f043ce5d7c046b2c4).
+ *
+ * ⚑ WHY THIS IS EXPORTED AT ALL. Until 2026-09-17 this sequence lived only in
+ * `test/harness/bootstrap.ts`, which `files: ["dist","blueprints"]` does not
+ * ship — so the platform maintained ITS OWN PORT of a protocol-critical
+ * sequence. That port had already diverged (it reserves the seed UTxOs from
+ * coin selection where the harness did not) and the divergence was CORRECT.
+ * Two implementations, one right and the other not yet wrong, is worse than one
+ * supported export. See CLAUDE.md, "Protocol bootstrap — AMENDED 2026-09-17",
+ * and `design/bootstrap-export.md` for the step boundaries and their reasons.
+ *
+ * ⛔ WHAT THIS MODULE DOES NOT DO, AND WILL NOT. It does not sign, submit, await,
+ * poll, fund, retry, or hold a key. It builds unsigned transactions and returns
+ * them. Orchestration is the caller's, and that is not a gap — it is what lets
+ * the platform keep its own UTxO reservation and its own confirmation strategy.
+ *
+ * ⛔ AND IT SHIPS NO FIXTURE VALUES. No mnemonic, no endpoint, no nonce, no
+ * security parameter, no placeholder policy id, no `any`. A value the caller
+ * must decide is a REQUIRED INPUT, never a default. That rule is the whole
+ * reason this export is safe to make: everything the devnet fixture chose for
+ * itself is now something its CALL passes in.
+ *
+ * ---------------------------------------------------------------------------
+ * THE SEQUENCE IS DEPENDENT, SO THE EXPORT IS STEPWISE
+ * ---------------------------------------------------------------------------
+ *
+ * The one-shot minting policies are parameterised by SPECIFIC OUTPUT REFERENCES
+ * of an earlier transaction, so step N+1 cannot be built until step N has been
+ * submitted and its outputs observed. There is no "give me five transactions"
+ * shape available; asking for one would mean signing, and signing is out.
+ *
+ *   1  buildSeedTx                  -> three distinct seed UTxOs
+ *   2  buildMultisigGenesisTx       -> the upgrade authority's config UTxO
+ *   3  buildProtocolGenesisTx       -> params, registry origin, issuance CBOR
+ *   4  buildReferenceScriptsTx      -> the seven reference scripts
+ *   5  buildStakeRegistrationTx     -> the six withdraw-0 registrations
+ *      assembleDeploymentParams     -> DeploymentParams (pure)
+ *
+ * ⚑ RESUMPTION. `planBootstrap(config)` is pure and deterministic: persist the
+ * CONFIG and every hash, address, datum and asset unit can be re-derived on any
+ * machine with no chain access. No step needs an earlier step's CONSUMED
+ * inputs, which is the property that makes resuming at step N work at all — by
+ * the time you resume at step 4 the seeds are spent and unfetchable.
+ */
+import type { Evaluator } from "@evolution-sdk/evolution/sdk/builders/TransactionBuilder";
+import type { Address, DeploymentParams, HexString, PlutusBlueprint, PlutusData, PlutusScript, ScriptHash, TxHash, TxInput, UTxO } from "../types.js";
+import type { EvoClient, UnsignedTx } from "../substandards/interface.js";
+import type { UpstreamPin } from "../core/provenance.js";
+import type { MultisigScriptTree } from "../core/evo-utils.js";
+/**
+ * Three seed UTxOs, and the count is not negotiable.
+ *
+ * utxo1 -> protocol_params AND registry, utxo2 -> issuance_cbor_hex_mint,
+ * utxo3 -> upgrade_multisig.
+ *
+ * ⛔ THREE DISTINCT ONES, NOT ONE REUSED. Reusing utxo1 for upgrade_multisig
+ * deploys perfectly well — a one-shot outref is consumed once, and the two
+ * policies consume it in different transactions, so nothing on chain objects.
+ * The reason it must be distinct is OFF chain: `DeploymentParams` carries TWO
+ * same-typed one-shot outrefs, `protocolParams.txInput` and
+ * `upgradeMultisig.txInput`, and `assertDeploymentScripts` derives a hash from
+ * each. A record that gives them ONE value makes the upgrade_multisig check
+ * pass whichever field the code reads, so the check cannot fail and a real
+ * defect in which field is read is invisible. That is not hypothetical: it hid
+ * a wrong derivation for an entire migration once already.
+ */
+export declare const BOOTSTRAP_SEED_COUNT = 3;
+/**
+ * The reference-script publication order, which is ONE FACT WRITTEN ONCE.
+ *
+ * ⛔ APPENDED, NEVER INSERTED. `buildReferenceScriptsTx` pays them in this
+ * order and `assembleDeploymentParams` derives every `…RefInput` index from the
+ * same array. alpha.3 inserted the dispatcher at index 1 and shifted all three
+ * delegates down — and a mismatch here does not fail loudly. It hands out a
+ * reference input carrying the WRONG script, and the transaction dies at
+ * evaluation naming neither.
+ *
+ * ⛔ AND APPENDING IS NOT FREE — THERE IS A CAP AND THIS LIST IS NEAR IT (F-9).
+ * MEASURED on devnet, 2026-09-17: the transaction publishing these seven comes
+ * to **12,496 bytes against a 16,384-byte protocol maximum — 76%**. Two more
+ * scripts of the size already here would burst it, and the failure arrives at
+ * SUBMISSION rather than at build. This is the same cap that forced the
+ * mint/publish/register split in the first place: the 0.3.x single-transaction
+ * fixture measured 21,816 bytes. `buildReferenceScriptsTx` now refuses over the
+ * chain's own `maxTxSize` rather than letting the ledger say it; when that
+ * refusal fires, the answer is a SECOND publish transaction and a second
+ * recorded tx hash, not a shorter list.
+ */
+export declare const REFERENCE_SCRIPT_ORDER: readonly ["programmableLogicBase", "programmableLogicGlobal", "transfer", "thirdParty", "unfracking", "issuanceLogic", "upgradeMultisig"];
+export type ReferenceScriptName = (typeof REFERENCE_SCRIPT_ORDER)[number];
+/**
+ * The six withdraw-0 credentials a bootstrap must register.
+ *
+ * ⛔ SIX, AND EVERY OMISSION IS UNDIAGNOSABLE. An unregistered stake credential
+ * does not fail with "not registered": the ledger answers code 3141, "rewards
+ * withdrawals must consume rewards in full", which reads as a balance problem
+ * and sends the reader to the wrong subsystem entirely. MEASURED on devnet —
+ * every programmable operation failed that way until the dispatcher joined this
+ * list, and `issuance_logic` rides EVERY mint and EVERY burn.
+ */
+export declare const STAKE_REGISTRATION_ORDER: readonly ["programmableLogicGlobal", "transfer", "thirdParty", "unfracking", "issuanceLogic", "upgradeMultisig"];
+export type StakeCredentialName = (typeof STAKE_REGISTRATION_ORDER)[number];
+/** The five steps, in order. Exported so a caller can name where it resumed. */
+export declare const BOOTSTRAP_STEPS: readonly ["seed", "multisig-genesis", "protocol-genesis", "reference-scripts", "stake-registrations"];
+export type BootstrapStepId = (typeof BOOTSTRAP_STEPS)[number];
+/**
+ * The 28-byte marker `issuance_mint` is parameterised against so the stored
+ * CBOR can be cut either side of its minting-logic argument.
+ *
+ * ⛔ NOT A PARAMETER, NOT A DEFAULT, AND NEVER DEPLOYED. It is applied and
+ * immediately cut back out; what reaches the chain is `pre` and `post` with the
+ * marker gone from between them, so that a later registration can splice a REAL
+ * minting-logic hash in without re-deriving the script. Passing this value
+ * anywhere a minting-logic hash is expected would produce a policy nobody can
+ * mint under — it is a cutting guide, not an identifier.
+ *
+ * ⚑ EXPORTED SO THE OCCURRENCE GUARD CAN BE EXERCISED, and for no other reason.
+ * `splitParts.length !== 2` below is the entire reason shipping a fixed hex
+ * marker is tolerable — and an unmutated guard is a claim rather than a check.
+ * A test cannot construct a body that collides with a marker it cannot see, so
+ * the marker is visible. (MEASURED: the `pre`/`post` halves do not depend on
+ * this VALUE — two different markers yield byte-identical halves, because the
+ * argument occupies the same bit positions either way.)
+ */
+export declare const ISSUANCE_SPLICE_MARKER = "deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeef";
+/** The three one-shot seed output references, by the role each plays. */
+export interface BootstrapSeeds {
+    /** Parameterises `protocol_params` AND `registry`. Consumed by the protocol genesis. */
+    readonly protocolParams: TxInput;
+    /** Parameterises `issuance_cbor_hex_mint`. Consumed by the protocol genesis. */
+    readonly issuance: TxInput;
+    /** Parameterises `upgrade_multisig`. Consumed by the multisig genesis. */
+    readonly upgradeMultisig: TxInput;
+}
+/** The same three, resolved to the UTxOs a transaction can actually spend. */
+export interface BootstrapSeedUtxos {
+    readonly protocolParams: UTxO;
+    readonly issuance: UTxO;
+    readonly upgradeMultisig: UTxO;
+}
+/**
+ * Whether this deployment's dispatcher can reach `unfracking`.
+ *
+ * ⚠ A CHOICE HERE, A VALUE IN THE RECORD, AND THE ASYMMETRY IS DELIBERATE.
+ * `DeploymentParams.programmableLogicGlobal.unfrackingParameter` must be a
+ * VALUE — a deployment file opened in three years has to say what the
+ * dispatcher was compiled from without needing a version of this SDK to
+ * interpret a boolean. But at bootstrap time the "enabled" value IS the
+ * `unfracking` script's own hash, which does not exist until the plan derives
+ * it, so a choice is the only thing a caller can express. `planBootstrap`
+ * resolves the choice into the value and `assembleDeploymentParams` records it.
+ *
+ * ⛔ Two deployments differing ONLY here are DIFFERENT PROTOCOLS: the parameter
+ * is baked into the dispatcher's hash. There is no default.
+ */
+export type UnfrackingChoice = "enabled" | "disabled";
+/**
+ * Everything needed to derive a protocol instance — and nothing that needs a
+ * network, a key or a clock.
+ *
+ * ⚑ THIS IS THE RESUME TOKEN. Persist it and `planBootstrap` re-derives every
+ * script, address, datum and asset unit byte-identically, offline.
+ *
+ * ⛔ IT IS NOT `JSON.stringify`-ABLE AS IT STANDS, AND THE FAILURE IS LOUD
+ * RATHER THAN SILENT (F-8): `maxInlineDatumBytes` is a `bigint`, and
+ * `JSON.stringify` THROWS `TypeError: Do not know how to serialize a BigInt`
+ * on it. Persist it with that one field converted — `String(...)` on the way
+ * out, `BigInt(...)` on the way back — and never with `Number(...)`, which
+ * would make a security parameter depend on a lossy round trip. The blueprint
+ * is ordinary JSON and needs no special handling.
+ */
+export interface BootstrapConfig {
+    /** The standard blueprint this instance is built from. */
+    readonly blueprint: PlutusBlueprint;
+    /** 0 for any testnet, 1 for mainnet. Determines every derived address. */
+    readonly networkId: number;
+    /** The three one-shot output references. */
+    readonly seeds: BootstrapSeeds;
+    /**
+     * `always_fail`'s nonce — REQUIRED, with no default and no generator.
+     *
+     * ⛔ THE CHOICE IS THE CALLER'S AND MUST STAY SO. A fixed nonce makes a
+     * rebuild against the same chain reproduce the same hashes, which is what a
+     * devnet fixture wants and what a production deployment usually does not. A
+     * value shipped here would be a value every deployment in the world shared.
+     */
+    readonly alwaysFailNonce: HexString;
+    /**
+     * `max_inline_datum_bytes` — REQUIRED. A SECURITY PARAMETER with no upstream
+     * guidance, and a compile-time parameter of all four delegates, so it is
+     * baked into their hashes.
+     *
+     * ⛔ THIS PACKAGE DELIBERATELY SHIPS NO VALUE FOR IT. The devnet fixture uses
+     * 1024n because that is what upstream's own test fixtures use; its own
+     * comment records that this is NOT a recommendation and that the production
+     * value is deferred. Defaulting it here would turn one fixture's convenience
+     * into everyone's security posture.
+     */
+    readonly maxInlineDatumBytes: bigint;
+    /** Whether the dispatcher is compiled against `unfracking` or the sentinel. */
+    readonly unfracking: UnfrackingChoice;
+}
+/** Every script this deployment derives, by the name the rest of the SDK uses. */
+export interface BootstrapScripts {
+    readonly alwaysFail: PlutusScript;
+    readonly protocolParams: PlutusScript;
+    readonly programmableLogicBase: PlutusScript;
+    readonly issuanceCborHexMint: PlutusScript;
+    readonly registry: PlutusScript;
+    readonly transfer: PlutusScript;
+    readonly thirdParty: PlutusScript;
+    readonly unfracking: PlutusScript;
+    readonly programmableLogicGlobal: PlutusScript;
+    readonly issuanceLogic: PlutusScript;
+    readonly upgradeMultisig: PlutusScript;
+}
+/**
+ * A fully derived protocol instance, before a single byte reaches a chain.
+ *
+ * Every field is a function of {@link BootstrapConfig} alone. Nothing here was
+ * read from a network and nothing here can disagree with what gets deployed —
+ * the build steps and `assembleDeploymentParams` both read THIS.
+ */
+export interface BootstrapPlan {
+    readonly config: BootstrapConfig;
+    readonly scripts: BootstrapScripts;
+    /** The resolved dispatcher parameter: the real hash, or `UNFRACKING_DISABLED`. */
+    readonly unfrackingParameter: ScriptHash;
+    readonly addresses: {
+        /** policy id == address payment credential. One value, one derivation. */
+        readonly protocolParams: Address;
+        /** Same collapse: node NFT policy AND node address. */
+        readonly registry: Address;
+        /** `always_fail`'s address — where the issuance CBOR UTxO is locked. */
+        readonly issuanceCborHex: Address;
+        /** The multisig config UTxO's address. */
+        readonly upgradeMultisig: Address;
+    };
+    readonly assetUnits: {
+        readonly protocolParamsNft: HexString;
+        /** The registry origin node's NFT — empty asset name, so the unit IS the policy. */
+        readonly registryNode: HexString;
+        readonly issuanceCborHexNft: HexString;
+        readonly upgradeMultisigNft: HexString;
+    };
+    readonly datums: {
+        readonly protocolParams: PlutusData;
+        readonly registryOrigin: PlutusData;
+        readonly issuanceCborHex: PlutusData;
+    };
+    /** The issuance_mint body either side of the minting-logic hash. */
+    readonly issuanceCbor: {
+        readonly pre: HexString;
+        readonly post: HexString;
+    };
+    /** The seven scripts of {@link REFERENCE_SCRIPT_ORDER}, in that order. */
+    readonly referenceScripts: readonly PlutusScript[];
+    /** The six scripts of {@link STAKE_REGISTRATION_ORDER}, in that order. */
+    readonly stakeCredentialScripts: readonly PlutusScript[];
+    /**
+     * Every parameterisation this plan performed, EXCLUDING `issuance_mint`.
+     *
+     * DERIVED, NEVER TRANSCRIBED — the unapplied hash and the application-order
+     * arguments are properties of the calls that made them and of nothing else.
+     * Feed to `buildCip171RecordFromPin`.
+     *
+     * ⚠ `issuance_mint` is excluded for a SEMANTIC reason, not a convenient one:
+     * it is parameterised PER MINTING-LOGIC HASH, once per substandard, so the
+     * instance derived here belongs to whichever substandard registers a token —
+     * not to the core deployment. Recording it here would name a script this
+     * deployment does not run.
+     */
+    readonly parameterizations: readonly {
+        rawScriptHash: HexString;
+        params: PlutusData[];
+    }[];
+}
+/**
+ * Derive a whole protocol instance from a config. Pure: no client, no network,
+ * no clock, no filesystem.
+ *
+ * ⚠ THE PARAMETERISATION ORDER IS LOAD-BEARING and each script's hash feeds the
+ * next. It is NOT a single chain — `programmable_logic_base` hangs off the
+ * params-NFT policy and everything downstream fans out — but the edges that do
+ * exist cannot be reordered. See `scripts.ts` for the full graph.
+ *
+ * ⛔ PARAMETER TYPES ARE NOT INTERCHANGEABLE AND TYPESCRIPT CANNOT TELL THEM
+ * APART: every one is a hex string at the call site. `issuance_logic` in
+ * particular takes TWO ADJACENT PolicyIds — `registry_node_cs` then
+ * `params_policy` — and swapping them yields a script that builds, hashes,
+ * deploys and is registered without a murmur. It simply looks for the registry
+ * under the params policy for the rest of its life.
+ */
+export declare function planBootstrap(config: BootstrapConfig): BootstrapPlan;
+/**
+ * What every build step needs, and what none of them will invent for you.
+ *
+ * ⛔ `availableUtxos` IS REQUIRED, AND THAT IS THE MOST IMPORTANT WORD IN THIS
+ * MODULE. Without it Evolution queries the wallet itself and coin selection may
+ * spend ANYTHING in it — including outputs carrying REFERENCE SCRIPTS. Spending
+ * one destroys protocol infrastructure silently: the script_ref is not carried
+ * into the change output, nothing errors, and the damage surfaces only when a
+ * later operation needs the script. MEASURED on preview: two of a live
+ * deployment's four reference scripts were consumed that way.
+ *
+ * ⚑ AND IT IS HOW A CALLER RESERVES THE SEEDS. The bootstrap's own seed UTxOs
+ * are ordinary wallet UTxOs until the step that consumes them runs; a caller
+ * that leaves them in `availableUtxos` for an EARLIER step invites coin
+ * selection to spend one for fees, and the later step then names a spent input.
+ * The ledger answers code 3117, "unknown UTxO references as inputs", which
+ * names a UTxO and reads as a builder bug — it is not. Exclude the seeds you
+ * have not consumed yet.
+ */
+export interface BootstrapBuildContext {
+    /** A read-only or signing Evolution client. The SDK never constructs one. */
+    readonly client: EvoClient;
+    /** Bech32 change address. */
+    readonly changeAddress: Address;
+    /** Exactly the UTxOs this transaction may spend. See the note above. */
+    readonly availableUtxos: readonly UTxO[];
+    /**
+     * Optional script evaluator.
+     *
+     * Without one the client's provider evaluates, and Kupmios reports a bare
+     * "evaluateTx failed" naming neither the script nor the reason. The SDK never
+     * constructs an evaluator and never names an endpoint — inject one.
+     */
+    readonly evaluator?: Evaluator;
+}
+export interface SeedTxParams extends BootstrapBuildContext {
+    /**
+     * Where the seed outputs are paid. Usually the bootstrapping wallet's own
+     * address: the steps that consume them must be able to spend them.
+     */
+    readonly ownerAddress: Address;
+    /**
+     * Lovelace per seed output — REQUIRED.
+     *
+     * Each seed funds part of the transaction that consumes it, so it must clear
+     * min-UTxO with room for a fee. There is no default because the right figure
+     * depends on the chain and on what the caller wants left over.
+     */
+    readonly seedLovelace: bigint;
+}
+/**
+ * Step 1 — fragment the wallet into {@link BOOTSTRAP_SEED_COUNT} distinct UTxOs.
+ *
+ * ⚑ THIS STEP IS OPTIONAL. A caller that already holds three distinct unspent
+ * UTxOs may skip it and call {@link planBootstrap} with their outrefs directly.
+ * It exists because most callers do not.
+ *
+ * ⚠ Its outputs cannot be predicted: the plan needs the OBSERVED outrefs. Submit
+ * this, wait for it, read the outputs back, then {@link selectBootstrapSeeds}.
+ */
+export declare function buildSeedTx(params: SeedTxParams): Promise<UnsignedTx>;
+/**
+ * Pick the three seeds out of a seed transaction's observed outputs.
+ *
+ * ⚠ REFUSES FEWER THAN THREE, LOUDLY. An earlier version of this logic asked
+ * for three and tolerated two, which handed `undefined` to the third consumer.
+ *
+ * The change output of the seed transaction lands at the same address and is a
+ * legitimate candidate; ordering by output index keeps the assignment stable
+ * across reads of an indexer that does not preserve order.
+ */
+export declare function selectBootstrapSeeds(utxos: readonly UTxO[], seedTxHash: TxHash): {
+    seeds: BootstrapSeeds;
+    utxos: BootstrapSeedUtxos;
+};
+export interface MultisigGenesisTxParams extends BootstrapBuildContext {
+    readonly plan: BootstrapPlan;
+    /** The unspent `seeds.upgradeMultisig` UTxO. Checked against the plan. */
+    readonly seedUtxo: UTxO;
+    /**
+     * WHO CONTROLS THE PROTOCOL — required, with no default of any kind.
+     *
+     * The signer tree lives in this UTxO's datum rather than in the script's
+     * parameters, which is what makes signer rotation possible without moving the
+     * hash. `multisigScriptDatum` enforces upstream's `well_formed` rules.
+     *
+     * ⛔ AN UNSATISFIABLE TREE IS A ONE-WAY BRICK, in upstream's own words: the
+     * authority check becomes "permanently unsatisfiable, with no repair path".
+     */
+    readonly upgradeMultisigTree: MultisigScriptTree;
+}
+/**
+ * Step 2 — mint the `upgrade_multisig` one-shot NFT and lock it with the signer
+ * tree, BEFORE the protocol genesis names this authority.
+ *
+ * ⛔ THE ORDER IS THE POINT, AND IT IS NOT A STYLE CHOICE. Step 3 writes a
+ * genesis datum naming `upgrade_cred = Script(upgrade_multisig)`. That authority
+ * is usable only while its config UTxO exists — the tree lives there, not in the
+ * script's parameters. Running this AFTER the protocol genesis and failing
+ * leaves a protocol on chain naming an authority whose config UTxO does not
+ * exist: upstream's documented ONE-WAY BRICK, manufactured by transaction
+ * ordering rather than by any defect in the validators. Failing BEFORE the
+ * irreversible step costs one transaction and nothing else.
+ *
+ * The four rails `upgrade_multisig.mint` enforces, all satisfied here:
+ *   1. the named UTxO is consumed                        -> collectFrom
+ *   2. exactly one "UpgradeMultisig" token of this policy -> mintAssets
+ *   3. an output found by `has_nft_strict`                -> the output below
+ *   4. well_formed(tree), NO reference script, address == from_script(policy)
+ *
+ * ⛔ THE NFT AND NOTHING ELSE in that output. `has_nft_strict` is strict about
+ * the WHOLE value: bundling any other asset with the config NFT means the output
+ * is simply NOT FOUND by `list.expect_find`, and the genesis fails naming
+ * nothing about bundling. Change is a separate output.
+ *
+ * ⚠ NO `script:` ON THE OUTPUT — rail 4 requires `reference_script == None`.
+ * The reference script is published in step 4 like every other one.
+ *
+ * ⚑ Additional outputs are the CALLER's to add in their own transaction if they
+ * want them. Rail 3 uses `list.expect_find`, which SKIPS a non-matching output
+ * rather than rejecting it, so a junk UTxO parked at this address is harmless —
+ * but it is not protocol state and this step will not mint one.
+ */
+export declare function buildMultisigGenesisTx(params: MultisigGenesisTxParams): Promise<UnsignedTx>;
+/**
+ * Assert the multisig config UTxO on chain is the one the genesis datum is
+ * about to name. PURE — the caller fetches the UTxOs, this decides.
+ *
+ * ⛔ AN OPERABILITY GATE, NOT DECORATION. The measured instance of "correct and
+ * useless" in this repo is a deployment naming an authority credential that
+ * could not be registered at all: every hash reproduced, every read-back
+ * matched, every test passed, and the protocol's upgrade path was permanently
+ * unsatisfiable. "It exists and is well-formed" left "and can be used" untested.
+ * Run this between step 2 and step 3, so it is structurally impossible for the
+ * genesis datum to name an authority that is not there.
+ *
+ * ⚑ FILTERS STRUCTURALLY, BY POLICY, EXACTLY AS THE VALIDATOR DOES — not by
+ * equality against a unit string we ourselves built. A lookup keyed on our own
+ * constructed unit shares a blind spot with the code that constructed it: get
+ * the asset name wrong in both places and the check agrees with itself.
+ */
+export declare function assertMultisigConfigUtxo(params: {
+    readonly plan: BootstrapPlan;
+    /** Every UTxO currently at `plan.addresses.upgradeMultisig`. */
+    readonly utxosAtAddress: readonly UTxO[];
+    /** The tree passed to {@link buildMultisigGenesisTx}. */
+    readonly expectedTree: MultisigScriptTree;
+}): {
+    utxo: UTxO;
+    ref: TxInput;
+};
+export interface ProtocolGenesisTxParams extends BootstrapBuildContext {
+    readonly plan: BootstrapPlan;
+    /** The unspent `seeds.protocolParams` UTxO. Checked against the plan. */
+    readonly protocolParamsSeedUtxo: UTxO;
+    /** The unspent `seeds.issuance` UTxO. Checked against the plan. */
+    readonly issuanceSeedUtxo: UTxO;
+    /**
+     * Optional CIP-171 provenance. Supply the `UPSTREAM_PIN.json` shipped beside
+     * the blueprint (import it via the "./blueprints/*" export path) and this
+     * transaction carries a record of what was parameterised into what.
+     *
+     * ⚠ A wrong-arity record is DISCARDED SILENTLY by the registry — no error, no
+     * REJECTED row. From outside, dropped and never-published are
+     * indistinguishable, so verify with a POSITIVE lookup by tx hash.
+     *
+     * ⛔ Pass the pin that ships WITH this package's blueprint. A copied
+     * repo/commit/compiler triple is a second copy that drifts silently and still
+     * verifies — against the wrong source.
+     */
+    readonly provenancePin?: UpstreamPin;
+}
+/**
+ * Step 3 — the protocol genesis: three one-shot mints and the three UTxOs that
+ * hold this instance's state.
+ *
+ * Outputs, and the indices are POSITIONAL — `assembleDeploymentParams` reads
+ * output 0 and nothing checks the rest but the chain:
+ *   0  the params UTxO          (NFT + the six-field params datum)
+ *   1  the registry origin node (NFT + the sentinel head of the linked list)
+ *   2  the issuance CBOR UTxO   (NFT + the spliced issuance_mint body)
+ */
+export declare function buildProtocolGenesisTx(params: ProtocolGenesisTxParams): Promise<UnsignedTx>;
+export interface ReferenceScriptsTxParams extends BootstrapBuildContext {
+    readonly plan: BootstrapPlan;
+    /**
+     * Where the reference scripts live — REQUIRED.
+     *
+     * ⚠ A LASTING DECISION, not a formality. These outputs are protocol
+     * infrastructure for the life of the deployment; every programmable
+     * transaction reads them. Pay them somewhere your own coin selection will
+     * never touch. MEASURED on preview: a wallet holding them alongside funds had
+     * two of four consumed by an ordinary retry, and nothing errored.
+     */
+    readonly referenceScriptAddress: Address;
+    /** Lovelace per reference-script output — REQUIRED. min-UTxO scales with the script's size. */
+    readonly referenceScriptLovelace: bigint;
+}
+/**
+ * Step 4 — publish the seven reference scripts, in {@link REFERENCE_SCRIPT_ORDER}.
+ *
+ * Cannot be folded into step 3: a transaction cannot reference a script it is
+ * itself creating.
+ */
+export declare function buildReferenceScriptsTx(params: ReferenceScriptsTxParams): Promise<UnsignedTx>;
+export interface StakeRegistrationTxParams extends BootstrapBuildContext {
+    readonly plan: BootstrapPlan;
+}
+/**
+ * Step 5 — the six Conway `RegCert`s, in one transaction.
+ *
+ * ⛔ `registerStake` + `attachScript` + a void redeemer, NEVER
+ * `registerAndDelegateTo`, FOR A SCRIPT CREDENTIAL. MEASURED: a combined
+ * certificate is a Conway `vote_reg_deleg_cert`, which arrives at the `publish`
+ * handler as a DIFFERENT `Certificate` constructor, and both
+ * `upgrade_multisig.publish` and `issuance_logic.publish` admit
+ * `RegisterCredential` and nothing else.
+ *
+ * ⚠ The DRep delegation a KEY credential needs is not missing here by oversight.
+ * A script withdraw-0 needs three things — a script witness, a registration, and
+ * the withdrawal itself. The DRep delegation is the FOURTH thing a key
+ * credential needs, and a script cannot have one.
+ *
+ * ⚠ Kept separate from step 3 because each certificate executes its script under
+ * the PUBLISH purpose: carrying all six script bodies alongside the mint
+ * witnesses is what breaks the 16,384-byte size cap. MEASURED at 21,816 bytes
+ * when this was one transaction.
+ */
+export declare function buildStakeRegistrationTx(params: StakeRegistrationTxParams): Promise<UnsignedTx>;
+/** The four things only a submitted chain can tell you. */
+export interface BootstrapObservations {
+    /** Step 3's transaction hash. Becomes `txHash` and the params UTxO reference. */
+    readonly protocolGenesisTxHash: TxHash;
+    /** Step 4's transaction hash. Becomes all seven reference inputs. */
+    readonly referenceScriptsTxHash: TxHash;
+    /**
+     * The multisig config UTxO, READ BACK OFF THE CHAIN — see
+     * {@link assertMultisigConfigUtxo}, which returns exactly this.
+     *
+     * ⚠ MUTABLE STATE. A signer rotation spends and recreates it, so a recorded
+     * value goes stale; re-read it rather than trusting an old record.
+     */
+    readonly multisigConfigUtxo: TxInput;
+}
+/**
+ * Assemble `DeploymentParams` from the plan and what was observed. Pure.
+ *
+ * ⛔ THE RECORD MUST SAY WHAT THE DATUM SAYS. `upgradeAuthority` is the
+ * deployment's account of the ACTIVE authority and the genesis datum writes
+ * `upgradeCred: Script(upgradeMultisig)`. Nothing derives one from the other and
+ * nothing may check them against each other on chain — which is exactly why
+ * both come from the same plan here, rather than being written twice.
+ */
+export declare function assembleDeploymentParams(plan: BootstrapPlan, observed: BootstrapObservations): DeploymentParams;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/standard/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/standard/bootstrap.ts"],"names":[],"mappings":"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"}