@easy1staking/cip113-sdk-ts 0.7.0 → 0.10.0

package/dist/standard/scripts.js

@@ -1,34 +1,48 @@
 /**
- * Standard script parameterization — CIP-113 0.5.0-alpha.2 (upstream 9db7e06).
+ * Standard script parameterization — CIP-113 0.5.0-alpha.4
+ * (upstream 7e8a63198c5b240135f1aa2f043ce5d7c046b2c4).
  *
  * Uses Evolution SDK directly for UPLC.applyParamsToScript and ScriptHash.
  *
- * Dependency graph. Note it is NO LONGER a single chain: upstream #110 removed
- * programmable_logic_global, and PLB is now parameterised by the params-NFT
- * policy rather than by PLG's credential, so everything downstream hangs off
- * `params_policy` in parallel instead of in series.
+ * Dependency graph. It is NOT a single chain: `programmable_logic_base` hangs
+ * off the params-NFT policy, so everything downstream of it fans out in
+ * parallel rather than in series.
  *
- *   always_fail(nonce)                          -> hash   (issuance side only now)
- *   coordination_spend(nonce)                   -> hash   NEW: the lock target
- *   protocol_params_mint(utxo_ref, coord_hash)  -> policy  == params_policy
+ *   always_fail(nonce)                          -> hash   (issuance side only)
+ *   protocol_params(utxo_ref)                   -> policy  == params_policy
  *     |
- *     +-- programmable_logic_base(params_policy) -> hash
- *     +-- transfer(params_policy)                -> hash   (PLG's transfer arm, renamed)
- *     +-- third_party(params_policy)             -> hash   NEW: seize / clawback
- *     +-- unfracking(params_policy)              -> hash
- *     +-- registry_spend(params_policy)          -> hash
+ *     +-- programmable_logic_base(params_policy)                  -> hash  == plb
+ *     |     |
+ *     |     +-- transfer(Script(plb), registry_node_cs, max_inline)     -> hash
+ *     |     +-- third_party(Script(plb), registry_node_cs, max_inline)  -> hash
+ *     |     +-- unfracking(Script(plb), registry_node_cs, max_inline)   -> hash
+ *     |     +-- issuance_logic(Script(plb), registry_node_cs,
+ *     |                        params_policy, max_inline)              -> hash  NEW in alpha.4
+ *     |
+ *     +-- issuance_mint(Script(minting_logic), params_policy)     -> policy
+ *
+ *   programmable_logic_global(transfer_hash, third_party_hash, unfracking_hash)
+ *                                                                -> hash   (built LAST)
  *
- *   issuance_cbor_hex_mint(utxo_ref, always_fail_hash)              -> policy
- *   registry_mint(utxo_ref, issuance_cbor_hex_cs, registry_spend_cred) -> policy
- *   issuance_mint(PLB_cred, registry_node_cs, minting_logic_cred, params_policy)
- *   upgrade_multisig(signers, threshold)        -> hash   (independent)
+ *   issuance_cbor_hex_mint(utxo_ref, always_fail_hash)            -> policy
+ *   registry(utxo_ref, issuance_cbor_hex_cs)                      -> policy
+ *
+ *   upgrade_multisig(utxo_ref)                  -> hash   (independent one-shot)
  *
  * ⚠ PARAMETER TYPES ARE NOT INTERCHANGEABLE and TypeScript cannot tell them
  * apart — every one of these is a hex string at the call site. `params_policy`
- * is a PolicyId (a bare ByteArray); `minting_logic_cred` and friends are
- * Credentials (a constructor-wrapped Script/VerificationKey). Passing a policy
- * where a credential belongs produces a valid script with the wrong hash. The
- * types below come from the blueprint's own parameter schemas, not from
+ * and `registry_node_cs` are PolicyIds (bare ByteArrays); `minting_logic_cred`
+ * and `programmable_logic_base` are Credentials (constructor-wrapped
+ * Script/VerificationKey). `scriptCredential()` wraps; `Data.bytearray()` does
+ * not. Passing a policy where a credential belongs produces a valid script with
+ * the wrong hash.
+ *
+ * ⛔ alpha.4 makes that sharper: `issuance_logic` takes TWO ADJACENT PolicyId
+ * parameters — `registry_node_cs` then `params_policy`. They are the same type,
+ * the same length, and both are `string` here. Swapping them yields a script
+ * that builds, hashes and deploys, and nothing before the ledger will say so.
+ *
+ * The types below come from the blueprint's own parameter schemas, not from
  * upstream's prose docs — see the hazard note in blueprint.ts.
  */
 import { Data } from "@evolution-sdk/evolution";
@@ -55,14 +69,8 @@ export function createStandardScripts(blueprint, onParameterize) {
         alwaysFail(nonce) {
             return parameterize(STANDARD_VALIDATORS.ALWAYS_FAIL, [Data.bytearray(nonce)]);
         },
-        coordinationSpend(nonce) {
-            return parameterize(STANDARD_VALIDATORS.COORDINATION_SPEND, [Data.bytearray(nonce)]);
-        },
-        protocolParamsMint(utxoRef, coordinationHash) {
-            return parameterize(STANDARD_VALIDATORS.PROTOCOL_PARAMS_MINT, [
-                outputReference(utxoRef),
-                Data.bytearray(coordinationHash),
-            ]);
+        protocolParams(utxoRef) {
+            return parameterize(STANDARD_VALIDATORS.PROTOCOL_PARAMS, [outputReference(utxoRef)]);
         },
         programmableLogicBase(paramsPolicy) {
             // PolicyId — a bare ByteArray. It was scriptCredential(plgHash) before #110.
@@ -70,150 +78,464 @@ export function createStandardScripts(blueprint, onParameterize) {
                 Data.bytearray(paramsPolicy),
             ]);
         },
-        transfer(paramsPolicy) {
-            return parameterize(STANDARD_VALIDATORS.TRANSFER, [Data.bytearray(paramsPolicy)]);
-        },
-        thirdParty(paramsPolicy) {
-            return parameterize(STANDARD_VALIDATORS.THIRD_PARTY, [Data.bytearray(paramsPolicy)]);
+        transfer(progLogicCred, registryPolicy, maxInlineDatumBytes) {
+            return parameterize(STANDARD_VALIDATORS.TRANSFER, [
+                scriptCredential(progLogicCred),
+                Data.bytearray(registryPolicy),
+                Data.int(BigInt(maxInlineDatumBytes)),
+            ]);
         },
-        unfracking(paramsPolicy) {
-            return parameterize(STANDARD_VALIDATORS.UNFRACKING, [Data.bytearray(paramsPolicy)]);
+        thirdParty(progLogicCred, registryPolicy, maxInlineDatumBytes) {
+            return parameterize(STANDARD_VALIDATORS.THIRD_PARTY, [
+                scriptCredential(progLogicCred),
+                Data.bytearray(registryPolicy),
+                Data.int(BigInt(maxInlineDatumBytes)),
+            ]);
         },
-        upgradeMultisig(signers, threshold) {
-            return parameterize(STANDARD_VALIDATORS.UPGRADE_MULTISIG, [
-                Data.list(signers.map((s) => Data.bytearray(s))),
-                Data.int(BigInt(threshold)),
+        unfracking(progLogicCred, registryPolicy, maxInlineDatumBytes) {
+            return parameterize(STANDARD_VALIDATORS.UNFRACKING, [
+                scriptCredential(progLogicCred),
+                Data.bytearray(registryPolicy),
+                Data.int(BigInt(maxInlineDatumBytes)),
             ]);
         },
+        upgradeMultisig(utxoRef) {
+            return parameterize(STANDARD_VALIDATORS.UPGRADE_MULTISIG, [outputReference(utxoRef)]);
+        },
         issuanceCborHexMint(utxoRef, alwaysFailHash) {
             return parameterize(STANDARD_VALIDATORS.ISSUANCE_CBOR_HEX_MINT, [
                 outputReference(utxoRef),
                 Data.bytearray(alwaysFailHash),
             ]);
         },
-        registryMint(utxoRef, issuanceCborHexPolicy, registrySpendHash) {
-            return parameterize(STANDARD_VALIDATORS.REGISTRY_MINT, [
+        registry(utxoRef, issuanceCborHexPolicy) {
+            return parameterize(STANDARD_VALIDATORS.REGISTRY, [
                 outputReference(utxoRef),
                 Data.bytearray(issuanceCborHexPolicy),
-                scriptCredential(registrySpendHash),
             ]);
         },
-        registrySpend(paramsPolicy) {
-            return parameterize(STANDARD_VALIDATORS.REGISTRY_SPEND, [
-                Data.bytearray(paramsPolicy),
+        programmableLogicGlobal(transferHash, thirdPartyHash, unfrackingHash) {
+            // Bare ScriptHashes — NOT scriptCredential(). The blueprint declares
+            // `aiken/crypto/ScriptHash` here, while issuance_mint declares
+            // `cardano/address/Credential` for the same 28 bytes. Wrapping these
+            // would produce a different script that still hashes and still deploys.
+            return parameterize(STANDARD_VALIDATORS.PROGRAMMABLE_LOGIC_GLOBAL, [
+                Data.bytearray(transferHash),
+                Data.bytearray(thirdPartyHash),
+                Data.bytearray(unfrackingHash),
             ]);
         },
-        issuanceMint(plbHash, registryNodePolicy, mintingLogicHash, paramsPolicy) {
+        issuanceMint(mintingLogicHash, paramsPolicy) {
             return parameterize(STANDARD_VALIDATORS.ISSUANCE_MINT, [
-                scriptCredential(plbHash),
-                Data.bytearray(registryNodePolicy),
                 scriptCredential(mintingLogicHash),
                 Data.bytearray(paramsPolicy),
             ]);
         },
+        issuanceLogic(progLogicCred, registryPolicy, paramsPolicy, maxInlineDatumBytes) {
+            // Credential, then TWO bare PolicyIds in blueprint order
+            // (registry_node_cs, params_policy), then the Int. See the interface
+            // doc: the two policies are the swap hazard alpha.4 introduced.
+            return parameterize(STANDARD_VALIDATORS.ISSUANCE_LOGIC, [
+                scriptCredential(progLogicCred),
+                Data.bytearray(registryPolicy),
+                Data.bytearray(paramsPolicy),
+                Data.int(BigInt(maxInlineDatumBytes)),
+            ]);
+        },
     };
 }
-/** Thrown when a blueprint does not reproduce its deployment's script hashes. */
+/**
+ * Thrown when a deployment record and the blueprint do not describe the same
+ * protocol instance.
+ *
+ * ⛔ IT IS THE CLASS CONSUMERS CATCH, so every refusal from this module must
+ * be one. The documented consumer shape is
+ * `catch (e) { if (e instanceof DeploymentMismatchError) … }`; a bare `Error`
+ * thrown beside it drops silently into whatever generic handler comes next,
+ * which is how a refusal that names a field ends up reported as "something went
+ * wrong".
+ *
+ * ⚠ `mismatches` IS EMPTY FOR REFUSALS THAT ARE NOT HASH COMPARISONS, and the
+ * emptiness is the signal rather than an oversight: nothing derived disagreed
+ * with anything recorded — the record was malformed, or held a value that was
+ * never a legal choice. Those pass their own `detail` message, because the
+ * composed "N script hash(es) differ" text would describe a comparison that
+ * never happened.
+ */
 export class DeploymentMismatchError extends Error {
     mismatches;
-    constructor(mismatches, blueprintTitle) {
-        super(`Blueprint "${blueprintTitle}" does not reproduce this deployment. ` +
-            `${mismatches.length} script hash(es) differ:\n` +
-            mismatches
-                .map((m) => `  ${m.name}: derived ${m.derived}, deployment says ${m.deployed}`)
-                .join("\n") +
-            `\nThe blueprint and the DeploymentParams describe different protocol instances. ` +
-            `Transactions built from this pairing would be rejected at submission.`);
+    constructor(mismatches, blueprintTitle, detail) {
+        super(detail ??
+            `Blueprint "${blueprintTitle}" does not reproduce this deployment. ` +
+                `${mismatches.length} script hash(es) differ:\n` +
+                mismatches
+                    .map((m) => `  ${m.name}: derived ${m.derived}, deployment says ${m.deployed}`)
+                    .join("\n") +
+                `\nThe blueprint and the DeploymentParams describe different protocol instances. ` +
+                `Transactions built from this pairing would be rejected at submission.` +
+                dispatcherCauseHint(mismatches));
         this.name = "DeploymentMismatchError";
         this.mismatches = mismatches;
     }
 }
+/** The name `deriveDeploymentScripts` gives the dispatcher-coherence check. */
+const PLG_CHECK_NAME = "programmable_logic_global (dispatcher coherence)";
 /**
- * Derive every parameterizable standard script hash from the blueprint and
- * check it against DeploymentParams. Throws DeploymentMismatchError on any
- * difference; returns the full check list on success.
- *
- * Why this exists: parameterization changes are not always visible to the
- * compiler. Upstream has changed a parameter's *meaning* while keeping its
- * arity and type (protocol_params_mint's `always_fail_hash` became
- * `coordination_addr_hash` in 0.5.0-alpha.1), so a wrong value typechecks,
- * builds, and only fails when the ledger rejects the transaction. This is the
- * check that catches it, and it is why buildDeploymentScripts no longer
- * overwrites derived hashes with deployment values.
- *
- * Not covered: always_fail (its nonce is not carried in DeploymentParams),
- * issuance_mint (parameterized per minting logic), and upgrade_multisig (its
- * signers/threshold are an authority choice, not a derived protocol value).
- * coordination_spend IS covered — DeploymentParams carries its nonce precisely
- * so the lock target can be re-derived rather than trusted.
- *
- * WHERE THIS CHECK HAS VALUE — and where it has none.
- *
- * It is only meaningful when the blueprint and the deployment come from
- * INDEPENDENT sources, so that they can actually disagree: a deployment loaded
- * from disk, a database, or the chain, checked against the blueprint currently
- * bundled. That is the case it catches, and the failure it catches is real —
- * this repo shipped a blueprint swapped in place under an unchanged directory
- * name, with 4 of 8 validator hashes moved.
- *
- * It proves NOTHING at bootstrap time. A deployment script derives the hashes,
- * populates DeploymentParams from those same values, and then asserts against
- * them — a tautology that cannot fail. Do not read a passing assertion inside a
- * bootstrap as evidence that the deployment is correct; assert on LOAD instead.
+ * ⚠ THE DISPATCHER CHECK IS REACHABLE FROM THREE CAUSES AND ITS NAME ONLY
+ * SUGGESTS ONE. "dispatcher coherence" trains the reader to look for a stale
+ * delegate, so a mismatch caused by the RECORDED `unfrackingParameter` sends
+ * them to the wrong two fields — and the parameter is the one cause the reader
+ * cannot see by comparing the record against itself. The check's name is pinned
+ * by `test/deployment-assertion.test.mjs`; the causes are named here instead.
  */
-export function assertDeploymentScripts(blueprint, deployment) {
+function dispatcherCauseHint(mismatches) {
+    if (!mismatches.some((m) => m.name === PLG_CHECK_NAME))
+        return "";
+    return (`\n\n${PLG_CHECK_NAME} is derived from THREE recorded values, and any one of ` +
+        `them can cause it:\n` +
+        `  transfer.scriptHash\n` +
+        `  thirdParty.scriptHash\n` +
+        `  programmableLogicGlobal.unfrackingParameter — what the dispatcher was ` +
+        `COMPILED AGAINST, which is NOT necessarily unfracking.scriptHash: a deployment ` +
+        `may record UNFRACKING_DISABLED here while deploying the real unfracking script ` +
+        `beside it. Check this one before the delegates; it is the only one of the three ` +
+        `that cannot be checked against anything else in the record.`);
+}
+// ---------------------------------------------------------------------------
+// The unfracking parameter — a deployment CHOICE baked into the dispatcher
+// ---------------------------------------------------------------------------
+/**
+ * The `unfracking_hash` a dispatcher is compiled against when the deployment
+ * wants unfracking DEPLOYED BUT UNREACHABLE: 28 zero bytes.
+ *
+ * ⚠ IT IS BAKED INTO THE DISPATCHER'S HASH, so two deployments that chose
+ * differently are DIFFERENT PROTOCOLS. Same category as `maxInlineDatumBytes`
+ * (see `types.ts`): a deployment CHOICE, recoverable from no hash, which is why
+ * `DeploymentParams.programmableLogicGlobal.unfrackingParameter` records the
+ * value itself rather than a flag.
+ *
+ * ⚠ WHY 28 BYTES AND NOT `#""`. The Aiken parameter is a bare `ScriptHash`
+ * — a `ByteArray` with no length constraint, not an `Option`, so there is no
+ * "none" to reach for. `#""` is type-legal, but NOBODY HERE CAN READ THE
+ * COMPILED VALIDATOR'S BODY: whether it asserts a length, or builds an address
+ * out of this parameter, is unknown. A 28-byte value is structurally identical
+ * to a real script hash, so every path behaves normally.
+ * ⇒ Choose a value that cannot reach code we cannot read, rather than reason
+ * about what that code probably does.
+ *
+ * ⚠ NOTHING HASHES TO IT. At 2^224 that is an impossibility, not a low risk,
+ * so the sentinel can never collide with a real `unfracking` deployment. Zeros
+ * rather than `FF…FF`, which reads as a mask or a placeholder.
+ *
+ * ⛔ IT LIVES HERE AND NOWHERE ELSE. The platform must IMPORT it. A
+ * platform-side copy is a second place to disagree about a value that
+ * determines a script hash.
+ */
+export const UNFRACKING_DISABLED = "00".repeat(28);
+/**
+ * Refuse a recorded `unfrackingParameter` that is neither of the two values a
+ * deployment may legitimately hold.
+ *
+ * ⛔ THIS IS A TWO-ELEMENT SET MEMBERSHIP, NOT A "DOESN'T MATCH ⇒ SENTINEL"
+ * FALLBACK. `if (recorded !== derived) { assume sentinel }` is the shape that
+ * passes everything: it accepts a typo, a truncation, and a stale hash from a
+ * different deployment — each of which then silently becomes the value the
+ * dispatcher is built from. Both candidates are named explicitly, and so is the
+ * value that was actually found; the standing discipline is
+ * `test/provenance-artefact.test.mjs` — refused by a NAMED assertion, never by
+ * a `??`/`||` guess.
+ *
+ * ⚠ THE CASE ONLY THIS CATCHES, and the reason it has to exist at all: a
+ * bootstrap that compiled the dispatcher against a wrong value and then recorded
+ * BOTH. Every one of the ten hash checks then reproduces — the record is
+ * SELF-CONSISTENT, so there is nothing for a comparison to disagree with — and
+ * only this membership test says the parameter was never a legal choice.
+ */
+const CANONICAL_SCRIPT_HASH = /^[0-9a-f]{56}$/;
+/**
+ * Read `programmableLogicGlobal.unfrackingParameter` and refuse anything that
+ * is not a WELL-FORMED script hash — BEFORE a single script is derived.
+ *
+ * ⛔ REFUSAL 1, THE OWN-PROPERTY CHECK, AND IT IS NOT DEFENSIVE PROGRAMMING.
+ * With `Object.prototype.unfrackingParameter` set, a record with the field
+ * GENUINELY ABSENT reads back a value, passes every one of the ten hash checks,
+ * and builds the dispatcher from something nobody recorded. MEASURED, not
+ * feared. This repo already treats that exact shape as a defect class —
+ * `test/ledger-order.test.mjs`, *"refuses an inherited `Object.prototype` key"*
+ * — so the standard exists and this call site has to meet it. `in` and a
+ * truthiness test both walk the prototype chain; only `hasOwnProperty` does not.
+ *
+ * ⛔ REFUSAL 2, THE SHAPE CHECK. A stray space, a newline from a copy-paste, a
+ * `0x` prefix off a block explorer, a `Uint8Array`, a `Buffer`, `null` — every
+ * one of these used to fall through to Evolution's
+ * `ParseError: Data.ByteArray … Expected string`, which names NO field, NO
+ * record and NO file, in front of an artefact that cannot be regenerated.
+ * Fails closed either way; the whole difference is whether the deployer can act
+ * on it.
+ *
+ * ⚠ BYTE-EXACT, AND DELIBERATELY NOT NORMALISING. An uppercase spelling of a
+ * legal hash is REFUSED and told it is a CASE problem — never lowercased and
+ * accepted. This value is what the dispatcher was COMPILED AGAINST; accepting a
+ * record whose spelling differs from what was hashed would re-open the exact
+ * hole this ticket exists to close.
+ *
+ * ⚠ TWO REFUSALS, TWO MESSAGES, AND THEY ANSWER DIFFERENT QUESTIONS — *is this
+ * a well-formed script hash?* and *is it one of the two this deployment may
+ * record?* (`refuseOnUnfrackingParameter`, below). A reader who cannot tell
+ * which one fired cannot act, so they are never merged into one condition.
+ */
+function readUnfrackingParameter(deployment, blueprintTitle) {
+    const plg = deployment.programmableLogicGlobal;
+    if (!Object.prototype.hasOwnProperty.call(plg, "unfrackingParameter")) {
+        throw new DeploymentMismatchError([], blueprintTitle, `programmableLogicGlobal.unfrackingParameter is ABSENT from this deployment ` +
+            `record — it has no OWN property of that name. It is REQUIRED and it has no ` +
+            `default: it records what programmable_logic_global was COMPILED AGAINST, ` +
+            `either the real unfracking script hash or UNFRACKING_DISABLED ` +
+            `(${UNFRACKING_DISABLED}), and NOTHING IN THE RECORD DETERMINES WHICH. ` +
+            `unfracking.scriptHash is not it: a deployment may deploy, publish and ` +
+            `record the real unfracking script while compiling the dispatcher against ` +
+            `the sentinel, so defaulting to it would be right often enough that nobody ` +
+            `would ever check. Add the field to the record. ` +
+            `⚠ An inherited Object.prototype.unfrackingParameter does NOT satisfy this: ` +
+            `it would hand the dispatcher a value no deployment recorded.`);
+    }
+    const recorded = plg.unfrackingParameter;
+    if (typeof recorded !== "string" || !CANONICAL_SCRIPT_HASH.test(recorded)) {
+        const shown = typeof recorded === "string" ? JSON.stringify(recorded) : describe(recorded);
+        const caseOnly = typeof recorded === "string" &&
+            CANONICAL_SCRIPT_HASH.test(recorded.toLowerCase()) &&
+            recorded !== recorded.toLowerCase();
+        throw new DeploymentMismatchError([], blueprintTitle, `programmableLogicGlobal.unfrackingParameter records ${shown}, which is not a ` +
+            `well-formed script hash. It must be EXACTLY 56 LOWERCASE HEX CHARACTERS ` +
+            `(28 bytes), with no 0x prefix, no whitespace and no surrounding quotes.` +
+            (caseOnly
+                ? ` ⚠ THIS IS A CASE PROBLEM, AND ONLY A CASE PROBLEM: lowercased, this IS ` +
+                    `56 hex characters. It is refused rather than normalised because this value ` +
+                    `is what the dispatcher was COMPILED AGAINST — accepting a spelling that ` +
+                    `differs from the bytes that were hashed is the ambiguity this field exists ` +
+                    `to remove. Write it in lowercase in the record.`
+                : ``) +
+            `\nThis check runs BEFORE any script is derived, so nothing downstream saw ` +
+            `this value; without it the failure surfaces inside Evolution's CBOR encoder ` +
+            `naming neither the field, the record, nor the file.`);
+    }
+    return recorded;
+}
+/** A non-string value, described by type rather than by a misleading cast. */
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    const ctor = value?.constructor?.name;
+    return `a ${typeof value}${ctor && ctor !== typeof value ? ` (${ctor})` : ``}: ` +
+        `${String(value).slice(0, 80)}`;
+}
+function refuseOnUnfrackingParameter(recorded, derivedUnfrackingHash, blueprintTitle) {
+    if (recorded === derivedUnfrackingHash || recorded === UNFRACKING_DISABLED)
+        return;
+    const shown = JSON.stringify(recorded);
+    throw new DeploymentMismatchError([], blueprintTitle, `programmableLogicGlobal.unfrackingParameter records ${shown}, which is neither ` +
+        `value a deployment may record. It must be EXACTLY ONE OF:\n` +
+        `  ${derivedUnfrackingHash}  — the derived unfracking script hash ` +
+        `(unfracking ENABLED: the dispatcher's unfracking arm dispatches to it)\n` +
+        `  ${UNFRACKING_DISABLED}  — UNFRACKING_DISABLED ` +
+        `(unfracking deployed and published, but the dispatcher's unfracking arm made ` +
+        `permanently unsatisfiable)\n` +
+        `A third value is a typo, a truncation, or a hash from a different deployment. ` +
+        `It is not inferable and it is not defaultable: it is what this dispatcher was ` +
+        `COMPILED AGAINST, so a wrong value here means every transaction that withdraws ` +
+        `through programmable_logic_global was built for a script that is not on chain.`);
+}
+function deriveDeploymentScripts(blueprint, deployment) {
+    // ⛔ BEFORE ANY DERIVATION, AND READ EXACTLY ONCE. Two reads of one recorded
+    // field are two chances to disagree — this module's own founding lesson — and
+    // a guard placed after the first read would be guarding a value the builder
+    // had already consumed. `readUnfrackingParameter` refuses an absent or
+    // inherited property and a malformed one; `refuseOnUnfrackingParameter` (run
+    // after the hash checks, see the call sites) refuses a well-formed value that
+    // is not one of the two this deployment may record.
+    //
+    // ⚠ IT VALIDATES, IT DOES NOT TRANSFORM. The string handed to the builder
+    // below is the same string the record holds — no trim, no lowercase, no
+    // 0x-strip — so this guard cannot move a single derived hash.
+    const recordedUnfrackingParameter = readUnfrackingParameter(deployment, blueprint.preamble.title);
     const builders = createStandardScripts(blueprint);
+    const plb = deployment.programmableLogicBase.scriptHash;
+    const registryPolicy = deployment.registry.scriptHash;
+    const paramsPolicy = deployment.protocolParams.policyId;
+    const mid = deployment.maxInlineDatumBytes;
+    // ⚑ ONE call per script. Every `derived` field below reads a `.hash` off one
+    // of these objects, and `scripts` returns the very same objects — so a wrong
+    // argument here is caught by the check beside it rather than surviving into
+    // the resolved surface.
+    const protocolParams = builders.protocolParams(deployment.protocolParams.txInput);
+    const programmableLogicBase = builders.programmableLogicBase(paramsPolicy);
+    const transfer = builders.transfer(plb, registryPolicy, mid);
+    const thirdParty = builders.thirdParty(plb, registryPolicy, mid);
+    const unfracking = builders.unfracking(plb, registryPolicy, mid);
+    // ⛔ THE THIRD ARGUMENT IS READ FROM THE RECORD, NOT FROM `unfracking`. A
+    // deployment may compile this dispatcher against `UNFRACKING_DISABLED` while
+    // deploying, publishing and recording the REAL unfracking script beside it,
+    // so `deployment.unfracking.scriptHash` is NOT the value that was hashed —
+    // only `programmableLogicGlobal.unfrackingParameter` says what was. Reading
+    // the wrong one derives a dispatcher hash for a script nobody deployed, and
+    // the failure surfaces at withdrawal time naming neither field.
+    //
+    // ⚠ It is used unvalidated HERE and refused by `refuseOnUnfrackingParameter`
+    // before either public entry point returns — see the call sites for why the
+    // refusal is sequenced after the hash mismatches rather than before them.
+    const programmableLogicGlobal = builders.programmableLogicGlobal(deployment.transfer.scriptHash, deployment.thirdParty.scriptHash, recordedUnfrackingParameter);
+    const issuanceCborHexMint = builders.issuanceCborHexMint(deployment.issuance.txInput, deployment.issuance.alwaysFailScriptHash);
+    const registry = builders.registry(deployment.registry.txInput, deployment.registry.issuanceScriptHash);
+    const issuanceLogic = builders.issuanceLogic(plb, registryPolicy, paramsPolicy, mid);
+    const upgradeMultisig = builders.upgradeMultisig(deployment.upgradeMultisig.txInput);
     const checks = [
         {
-            name: "coordination_spend",
-            derived: builders.coordinationSpend(deployment.coordinationNonce).hash,
-            deployed: deployment.coordination.scriptHash,
-        },
-        {
-            name: "protocol_params_mint",
-            derived: builders.protocolParamsMint(deployment.protocolParams.txInput, deployment.protocolParams.coordinationScriptHash).hash,
+            // ⚑ ONE derivation for what used to be two. The params NFT policy and the
+            // params address's payment credential are the same value in alpha.3, so
+            // deriving them separately is not "belt and braces" — it is two chances
+            // to disagree about one fact.
+            name: "protocol_params (policy == address)",
+            derived: protocolParams.hash,
             deployed: deployment.protocolParams.policyId,
         },
         {
             name: "programmable_logic_base",
-            derived: builders.programmableLogicBase(deployment.protocolParams.policyId).hash,
-            deployed: deployment.programmableLogicBase.scriptHash,
+            derived: programmableLogicBase.hash,
+            deployed: plb,
         },
         {
             name: "transfer",
-            derived: builders.transfer(deployment.protocolParams.policyId).hash,
+            derived: transfer.hash,
             deployed: deployment.transfer.scriptHash,
         },
         {
             name: "third_party",
-            derived: builders.thirdParty(deployment.protocolParams.policyId).hash,
+            derived: thirdParty.hash,
             deployed: deployment.thirdParty.scriptHash,
         },
         {
             name: "unfracking",
-            derived: builders.unfracking(deployment.protocolParams.policyId).hash,
+            derived: unfracking.hash,
             deployed: deployment.unfracking.scriptHash,
         },
+        {
+            // ⛔ THE COHERENCE CHECK THE LEDGER CANNOT DO. A script cannot read
+            // another script's parameters, so nothing on chain verifies that the
+            // dispatcher was compiled against THESE three delegates. Deriving it from
+            // the deployment's own delegate hashes is the only place that mismatch
+            // can be caught — and a dispatcher naming stale delegates fails at
+            // withdrawal time with an index error, never with "wrong dispatcher".
+            //
+            // ⚠ AND IT IS NOW REACHABLE FROM THREE CAUSES, NOT ONE. Its name says
+            // "stale delegates", but the third derivation input is the RECORDED
+            // `programmableLogicGlobal.unfrackingParameter` — so a record that
+            // compiled against `UNFRACKING_DISABLED` and then wrote the enabled
+            // dispatcher's hash (or the reverse) fails HERE, with a name pointing at
+            // the two fields that are fine. The parameter is also the only one of the
+            // three that cannot be cross-checked against anything else in the record.
+            // `dispatcherCauseHint` names all three in the thrown message; do not let
+            // this comment and that message drift apart.
+            name: PLG_CHECK_NAME,
+            derived: programmableLogicGlobal.hash,
+            deployed: deployment.programmableLogicGlobal.scriptHash,
+        },
         {
             name: "issuance_cbor_hex_mint",
-            derived: builders.issuanceCborHexMint(deployment.issuance.txInput, deployment.issuance.alwaysFailScriptHash).hash,
+            derived: issuanceCborHexMint.hash,
             deployed: deployment.issuance.policyId,
         },
         {
-            name: "registry_spend",
-            derived: builders.registrySpend(deployment.protocolParams.policyId).hash,
-            deployed: deployment.directorySpend.scriptHash,
+            // ⚑ Also one derivation for what used to be two (registry_mint's policy
+            // and registry_spend's address).
+            name: "registry (policy == address)",
+            derived: registry.hash,
+            deployed: registryPolicy,
         },
         {
-            name: "registry_mint",
-            derived: builders.registryMint(deployment.directoryMint.txInput, deployment.issuance.policyId, deployment.directorySpend.scriptHash).hash,
-            deployed: deployment.directoryMint.scriptHash,
+            // ⛔ THE FOURTH CONSUMER OF `mid`. transfer, third_party and unfracking
+            // were three; alpha.4's issuance_logic is the fourth, and the count is
+            // the mechanism: the negative test asserting FOUR mismatches for a wrong
+            // `maxInlineDatumBytes` is what proves this call site exists. A comment
+            // cannot prove a call site; a count can.
+            //
+            // ⚠ Argument order is `(plb, registry_node_cs, params_policy, mid)` and
+            // the middle two are both bare PolicyIds. Swapping them builds, hashes
+            // and deploys — see the adjacent-parameter negative in
+            // test/deployment-assertion.test.mjs.
+            name: "issuance_logic",
+            derived: issuanceLogic.hash,
+            deployed: deployment.issuanceLogic.scriptHash,
+        },
+        {
+            // ⛔ CHECKED AGAIN, AND THE REASON IT CAN BE IS THE WHOLE CHANGE. This
+            // check was REMOVED in S-11 after it shipped a defect: it derived
+            // `upgrade_multisig` from `upgradeAuthority.hash`, a relationship that
+            // never existed (a PAYMENT key hash matched against `extra_signatories`
+            // versus the STAKE credential named in the params datum). alpha.3 could
+            // not derive it at all — its signer set and threshold were a deployment
+            // CHOICE that DeploymentParams did not record. alpha.4 replaces both
+            // parameters with a single `utxo_ref`, which IS recorded, so the hash is
+            // derivable and the check comes back.
+            //
+            // ⚠ AND THE VACUITY TRAP COMES BACK WITH IT, IN A NEW SHAPE. What hid the
+            // S-11 bug was a fixture using ONE value for two fields, so the wrong
+            // derivation reproduced perfectly and the check passed vacuously — only a
+            // live devnet exposed it. DeploymentParams now holds TWO one-shot
+            // `TxInput`s of identical type: `protocolParams.txInput` and
+            // `upgradeMultisig.txInput`. A fixture that reuses one for both makes
+            // this check pass no matter which one the code reads.
+            //
+            // ⛔ Do NOT add any check relating `upgradeAuthority` to
+            // `upgradeMultisig`. A deployment may legitimately name a key credential,
+            // a different script, or the multisig as its authority, and the validator
+            // never inspects it. Such a check would reject valid deployments — it is
+            // the S-11 defect returning under a new name.
+            name: "upgrade_multisig",
+            derived: upgradeMultisig.hash,
+            deployed: deployment.upgradeMultisig.scriptHash,
         },
     ];
+    return {
+        builders,
+        paramsPolicy,
+        unfrackingParameter: {
+            recorded: recordedUnfrackingParameter,
+            derivedUnfrackingHash: unfracking.hash,
+        },
+        scripts: {
+            protocolParams,
+            programmableLogicBase,
+            transfer,
+            thirdParty,
+            unfracking,
+            programmableLogicGlobal,
+            issuanceCborHexMint,
+            registry,
+            issuanceLogic,
+            upgradeMultisig,
+        },
+        checks,
+    };
+}
+/** Throw if any derived hash disagrees with the deployment record. */
+function refuseOnMismatch(checks, blueprintTitle) {
     const mismatches = checks.filter((c) => c.derived !== c.deployed);
     if (mismatches.length > 0) {
-        throw new DeploymentMismatchError(mismatches, blueprint.preamble.title);
+        throw new DeploymentMismatchError(mismatches, blueprintTitle);
     }
+}
+export function assertDeploymentScripts(blueprint, deployment) {
+    const { checks, unfrackingParameter } = deriveDeploymentScripts(blueprint, deployment);
+    refuseOnMismatch(checks, blueprint.preamble.title);
+    // ⚠ ORDER IS DELIBERATE, AND IT IS NOT A CONDITIONAL. A wrong
+    // `maxInlineDatumBytes` moves the derived `unfracking` hash, which would let a
+    // parameter complaint pre-empt — and hide — the four named delegate
+    // mismatches that say what actually went wrong. Hash disagreements are
+    // reported first, by name; this refusal is what is left when all ten
+    // reproduce and the record is nevertheless not a legal deployment.
+    refuseOnUnfrackingParameter(unfrackingParameter.recorded, unfrackingParameter.derivedUnfrackingHash, blueprint.preamble.title);
     return checks;
 }
 /**
@@ -225,21 +547,30 @@ export function assertDeploymentScripts(blueprint, deployment) {
  * undetectable until submission.
  */
 export function buildDeploymentScripts(blueprint, deployment) {
-    assertDeploymentScripts(blueprint, deployment);
-    const builders = createStandardScripts(blueprint);
-    const paramsPolicy = deployment.protocolParams.policyId;
+    // ⚑ ONE FACT, ONE DERIVATION — and this line is what makes that phrase true
+    // rather than aspirational. The scripts returned below are the SAME OBJECTS
+    // whose hashes were just checked, not a second build from the same arguments.
+    // A second build is a second chance to disagree, and it WAS unguarded here:
+    // see the block on `DerivedDeployment`.
+    const { builders, paramsPolicy, scripts, checks, unfrackingParameter } = deriveDeploymentScripts(blueprint, deployment);
+    refuseOnMismatch(checks, blueprint.preamble.title);
+    // Same refusal, same order, as `assertDeploymentScripts` — the resolved
+    // surface must never be built from a parameter the assertion would reject.
+    refuseOnUnfrackingParameter(unfrackingParameter.recorded, unfrackingParameter.derivedUnfrackingHash, blueprint.preamble.title);
     return {
-        coordinationSpend: builders.coordinationSpend(deployment.coordinationNonce),
-        protocolParamsMint: builders.protocolParamsMint(deployment.protocolParams.txInput, deployment.protocolParams.coordinationScriptHash),
-        programmableLogicBase: builders.programmableLogicBase(paramsPolicy),
-        transfer: builders.transfer(paramsPolicy),
-        thirdParty: builders.thirdParty(paramsPolicy),
-        unfracking: builders.unfracking(paramsPolicy),
-        issuanceCborHexMint: builders.issuanceCborHexMint(deployment.issuance.txInput, deployment.issuance.alwaysFailScriptHash),
-        registryMint: builders.registryMint(deployment.directoryMint.txInput, deployment.issuance.policyId, deployment.directorySpend.scriptHash),
-        registrySpend: builders.registrySpend(paramsPolicy),
+        ...scripts,
         buildIssuanceMint(mintingLogicHash) {
-            return builders.issuanceMint(deployment.programmableLogicBase.scriptHash, deployment.directoryMint.scriptHash, mintingLogicHash, paramsPolicy);
+            // ⚑ ITS SIGNATURE IS UNCHANGED AND ITS RESULT IS NOT. alpha.4 dropped
+            // `programmable_logic_base` and `registry_node_cs` from issuance_mint's
+            // parameters, so THE POLICY ID CHANGES FOR THE SAME MINTING LOGIC. That
+            // is correct, not a bug to fix: an alpha.3 token and an alpha.4 token
+            // built from identical issuance logic are different assets.
+            //
+            // ⚠ NOT part of the single-derivation collapse above, and cannot be: it
+            // is parameterised per minting logic, so there is no one hash for
+            // `assertDeploymentScripts` to check. It stays uncovered, as the
+            // assertion's own "Not covered" note says.
+            return builders.issuanceMint(mintingLogicHash, paramsPolicy);
         },
     };
 }