@easy1staking/cip113-sdk-ts 0.7.0 → 0.9.0

package/dist/core/evo-utils.js

@@ -4,7 +4,7 @@
  * These are used across the SDK to build scripts, addresses, datums, and
  * perform common conversions. All use Evolution SDK types directly.
  */
-import { Data, Bytes, ScriptHash as EvoScriptHash, Script, UPLC, Address as EvoAddress, AddressEras, BaseAddress, EnterpriseAddress, RewardAccount, Assets, Credential, InlineDatum, KeyHash, TransactionHash, Transaction, } from "@evolution-sdk/evolution";
+import { Data, Bytes, ScriptHash as EvoScriptHash, Script, UPLC, Address as EvoAddress, AddressEras, BaseAddress, EnterpriseAddress, RewardAccount, Assets, Credential, InlineDatum, KeyHash, TransactionHash, Transaction, TxOut, } from "@evolution-sdk/evolution";
 import * as Label from "@evolution-sdk/evolution/Label";
 const PlutusV3 = Script.Script.members[3];
 // ---------------------------------------------------------------------------
@@ -261,43 +261,162 @@ export function decodeRegistryNode(d) {
  * CHANGED. Deliberately generous: min-UTxO also moves with protocol parameters.
  */
 export const REGISTRY_NODE_MIN_ADA = 3000000n;
-/** Build the coordination datum. Field order is the on-chain contract. */
+/**
+ * The ledger's per-UTxO byte overhead, from the Babbage min-UTxO rule
+ * (`utxoEntrySize` = serialised output size + a fixed constant). Evolution uses
+ * the same value internally; it is restated here rather than imported because
+ * its home is `sdk/builders/internal/`, and this package does not reach into a
+ * dependency's internals.
+ */
+const UTXO_ENTRY_OVERHEAD_BYTES = 160n;
+/**
+ * The minimum lovelace an output must carry, computed from PROTOCOL PARAMETERS
+ * and the output's own serialised size.
+ *
+ * ⚠ WHY THIS EXISTS RATHER THAN ANOTHER CONSTANT. min-UTxO scales with
+ * SERIALISED OUTPUT SIZE, and three things that scale it are supplied by the
+ * CALLER, not by us:
+ *   - the CIP-68 metadata datum (name/description/ticker/url/logo). This
+ *     package imposes no length caps at all, so the datum is UNBOUNDED.
+ *   - the ASSET NAME. CIP-67-labelled names run to 32 bytes, and this package's
+ *     API takes raw hex names at every boundary.
+ *   - the QUANTITY, which is a CBOR integer and widens with magnitude.
+ *
+ * ⛔ AND EVOLUTION DOES NOT RESCUE AN UNDER-FUNDED OUTPUT. MEASURED on preview
+ * (2026-09-01): `calculateMinimumUtxoLovelace` is applied ONLY to CHANGE and
+ * unfracking outputs. An explicit `payToAddress` amount is passed through
+ * verbatim — a build with a deliberately short datum-bearing output produced a
+ * transaction carrying exactly the requested lovelace. The shortfall therefore
+ * survives to submission, where the ledger rejects it as "insufficient Ada"
+ * with a number and NEVER as "your datum grew".
+ *
+ * A flat constant cannot be right for an input the caller controls. This is the
+ * successor to {@link REGISTRY_NODE_MIN_ADA}'s "deliberately generous" habit:
+ * generous is a guess, and it was already wrong at 3 ADA for a CIP-68 datum
+ * whose fields sit within a consumer's own documented caps.
+ *
+ * Built from PUBLIC Evolution API only, and solved as a fixed point because the
+ * lovelace figure is itself part of what gets serialised.
+ */
+export function minUtxoForOutput(params) {
+    const address = EvoAddress.fromBech32(params.address);
+    const datumOption = params.datum
+        ? new InlineDatum.InlineDatum({ data: params.datum })
+        : undefined;
+    const required = (lovelace) => {
+        const output = new TxOut.TransactionOutput({
+            address,
+            assets: Assets.withLovelace(params.assets, lovelace),
+            datumOption,
+        });
+        const size = BigInt(TxOut.toCBORBytes(output).length);
+        return params.coinsPerUtxoByte * (UTXO_ENTRY_OVERHEAD_BYTES + size);
+    };
+    // Writing a larger number widens the CBOR, which raises the requirement. Two
+    // or three rounds converge; the cap only stops a pathological non-convergence
+    // from hanging a transaction build.
+    let current = 0n;
+    for (let i = 0; i < 10; i++) {
+        const next = required(current);
+        if (next === current)
+            return next;
+        current = next;
+    }
+    throw new Error(`min-UTxO did not converge after 10 iterations (last ${current} lovelace). ` +
+        `This should not happen for a well-formed output; report it with the datum.`);
+}
+/** Round up to a whole ADA. */
+export function ceilToWholeAda(lovelace) {
+    return ((lovelace + 999999n) / 1000000n) * 1000000n;
+}
+/**
+ * min-UTxO for an output, never returning less than `floor`.
+ *
+ * The floor keeps this change MONOTONE: every value this package used to emit
+ * is preserved for ordinary inputs, and the figure only ever rises — where it
+ * had to. A fix that lowered an amount would be a behaviour change smuggled in
+ * beside a bug fix.
+ */
+export function minUtxoAtLeast(floor, params) {
+    const computed = minUtxoForOutput(params);
+    return computed > floor ? computed : floor;
+}
+/** Build the protocol-params datum. Field order is the on-chain contract. */
 export function protocolParamsDatum(p) {
+    // `Option<Credential>`: Some(cred) = Constr(0, [Credential]), None = Constr(1, []).
+    const pending = p.pendingUpgradeCred == null
+        ? Data.constr(1n, [])
+        : Data.constr(0n, [credToData(p.pendingUpgradeCred)]);
     return Data.constr(0n, [
-        Data.bytearray(p.registryNodeCs),
-        credToData(p.progLogicCred),
+        credToData(p.plgCred),
+        credToData(p.issuanceLogicCred),
         credToData(p.transferCred),
         credToData(p.thirdPartyCred),
-        credToData(p.unfrackingCred),
         credToData(p.upgradeCred),
-        Data.int(p.maxInlineDatumBytes),
+        pending,
     ]);
 }
-/** Parse the coordination datum. */
+/** Decode index 5's `Option<Credential>`. */
+function dataToPendingCred(d) {
+    if (d instanceof Data.Constr) {
+        if (d.index === 1n && d.fields.length === 0)
+            return null;
+        if (d.index === 0n && d.fields.length === 1) {
+            return dataToCred(d.fields[0], "ProtocolParams.pendingUpgradeCred");
+        }
+    }
+    throw new Error(`ProtocolParams.pendingUpgradeCred: field 5 is Option<Credential> — ` +
+        `Constr(0, [Credential]) for a standing nomination, Constr(1, []) for none. ` +
+        `pending_upgrade_cred was added in 0.5.0-alpha.4; a datum without it is not a ` +
+        `six-field datum at all.`);
+}
+/**
+ * Parse the protocol-params datum. STRICT on arity — see the block above for
+ * why that strictness is load-bearing rather than defensive, AND for the one
+ * misread it CANNOT catch.
+ */
 export function decodeProtocolParams(d) {
     if (!(d instanceof Data.Constr) || d.index !== 0n) {
         throw new Error("ProgrammableLogicGlobalParams: expected Constr(0, ...)");
     }
-    if (d.fields.length !== 7) {
-        throw new Error(`ProgrammableLogicGlobalParams: expected exactly 7 fields, got ${d.fields.length}. ` +
-            `If you read 6 somewhere, that source predates #115 — max_inline_datum_bytes ` +
-            `is field 6. A 6-field datum is malformed for every programmable_logic_base spend.`);
+    if (d.fields.length !== 6) {
+        throw new Error(`ProgrammableLogicGlobalParams: expected exactly 6 fields, got ${d.fields.length}. ` +
+            `alpha.4 INSERTED issuance_logic_cred at index 1 — it was not appended — so ` +
+            `transfer_cred, which was index 1 in alpha.3, is now index 2. Both are Credentials, ` +
+            `so a shifted positional read returns a well-formed value naming the wrong authority. ` +
+            `A 4-field datum belongs to a 0.5.0-alpha.3 protocol instance and a 7-field one to ` +
+            `0.5.0-alpha.2; point at that instance's SDK, do not relax this check.`);
     }
     const f = d.fields;
-    const n = f[6];
-    if (typeof n !== "bigint") {
-        throw new Error("ProgrammableLogicGlobalParams.maxInlineDatumBytes: expected an integer");
-    }
     return {
-        registryNodeCs: expectBytes(f[0], "ProtocolParams.registryNodeCs"),
-        progLogicCred: dataToCred(f[1], "ProtocolParams.progLogicCred"),
+        plgCred: dataToCred(f[0], "ProtocolParams.plgCred"),
+        issuanceLogicCred: dataToCred(f[1], "ProtocolParams.issuanceLogicCred"),
         transferCred: dataToCred(f[2], "ProtocolParams.transferCred"),
         thirdPartyCred: dataToCred(f[3], "ProtocolParams.thirdPartyCred"),
-        unfrackingCred: dataToCred(f[4], "ProtocolParams.unfrackingCred"),
-        upgradeCred: dataToCred(f[5], "ProtocolParams.upgradeCred"),
-        maxInlineDatumBytes: n,
+        upgradeCred: dataToCred(f[4], "ProtocolParams.upgradeCred"),
+        pendingUpgradeCred: dataToPendingCred(f[5]),
     };
 }
+/**
+ * Verify that the deployment record and live protocol-params datum name the
+ * same issuance-logic script. They are independent sources: the record drives
+ * the withdrawal emitted here, while the datum drives the permanent issuance
+ * policy on chain.
+ */
+export function assertProtocolParamsIssuanceLogic(utxo, expectedScriptHash) {
+    const datum = getInlineDatum(utxo);
+    if (datum === undefined) {
+        throw new Error(`Protocol params UTxO has no inline datum; cannot verify deployment ` +
+            `issuanceLogic.scriptHash ${expectedScriptHash}.`);
+    }
+    const actual = decodeProtocolParams(datum).issuanceLogicCred;
+    if (actual.type !== "script" || actual.hash.toLowerCase() !== expectedScriptHash.toLowerCase()) {
+        throw new Error(`Deployment issuanceLogic.scriptHash ${expectedScriptHash} does not match the live ` +
+            `protocol-params datum's issuance_logic_cred ${actual.type}/${actual.hash}. ` +
+            `Refusing before transaction construction; use the DeploymentParams recorded for ` +
+            `this protocol instance.`);
+    }
+}
 /** Build a BlacklistNode datum */
 export function blacklistNodeDatum(key, next) {
     return Data.constr(0n, [Data.bytearray(key), Data.bytearray(next)]);
@@ -306,25 +425,172 @@ export function blacklistNodeDatum(key, next) {
 // Redeemer builders (CIP-113 validators)
 // ---------------------------------------------------------------------------
 /**
- * `issuance_mint`'s redeemer — a BARE `MintingRegistryProof`.
- *
- * Upstream #68 REMOVED the `SmartTokenMintingAction { minting_logic_cred,
- * minting_registry_proof }` wrapper these builders used to emit. The redeemer is
- * now the proof itself, and the minting-logic credential is no longer carried in
- * it at all — it comes from the registry node.
+ * A `MintingRegistryProof` — where the token's registry node is in this
+ * transaction.
  *
  *   ctor 0  RefInput    { index }  — the registry node is a REFERENCE input
  *   ctor 1  OutputIndex { index }  — the registry node is an OUTPUT of this tx
  *                                    (registration and first mint in one)
  *
- * Verified against the blueprint's own redeemer schema, not upstream's prose.
+ * ⛔ THIS IS NO LONGER `issuance_mint`'s REDEEMER, AND THE OLD COMMENT HERE WAS
+ * AN INSTRUCTION FOR BUILDING A TRANSACTION THE LEDGER REFUSES. In 0.5.0-alpha.3
+ * `issuance_mint` took a BARE `MintingRegistryProof`. In alpha.4 issuance was
+ * split (upstream #129): the permanent per-token policy's redeemer is now
+ * `IssuanceRedeemer { params_idx }` — see {@link issuanceRedeemer} — and the
+ * proof travels as a VALUE inside the `issuance_logic` withdraw-0 redeemer's
+ * map, keyed by policy id. See {@link issuanceLogicRedeemer}, which is where a
+ * proof built here now goes.
+ *
+ * Signatures and encodings are UNCHANGED on purpose: `src/substandards/**`
+ * still calls both, and rewiring those call sites is a separate slice.
+ *
+ * Verified against the blueprint's own `types/MintingRegistryProof` definition,
+ * not upstream's prose.
  */
 export function mintingProofRefInput(registryRefInputIndex) {
     return Data.constr(0n, [Data.int(BigInt(registryRefInputIndex))]);
 }
+/** The other arm of {@link mintingProofRefInput} — see its block comment. */
 export function mintingProofOutputIndex(registryOutputIndex) {
     return Data.constr(1n, [Data.int(BigInt(registryOutputIndex))]);
 }
+/**
+ * `issuance_mint`'s redeemer — `IssuanceRedeemer { params_idx }`.
+ *
+ * The PERMANENT half of issuance (upstream #129). This script's applied hash IS
+ * a token's policy id, so its redeemer is frozen for as long as any token
+ * exists: nothing but an index hint locating the protocol-params UTxO among the
+ * reference inputs. Everything that could ever change moved to
+ * {@link issuanceLogicRedeemer}.
+ *
+ * ⚠ `params_idx` INDEXES THE COMPLETE, LEDGER-SORTED REFERENCE-INPUT SET, and
+ * the validator jumps straight to `list.at(reference_inputs, params_idx)` and
+ * authenticates what it finds by the params NFT. Computing this index before
+ * the builder has added every reference input is a builder bug, and it does not
+ * report as one — it resolves to some other UTxO, fails the NFT check, and dies
+ * naming nothing. Use `referenceInputIndexOf` in `src/core/ledger-order.ts`,
+ * over the complete set, last.
+ */
+export function issuanceRedeemer(paramsIdx) {
+    if (!Number.isInteger(paramsIdx) || paramsIdx < 0) {
+        throw new Error(`issuanceRedeemer: params_idx must be a non-negative integer, got ${paramsIdx}`);
+    }
+    return Data.constr(0n, [Data.int(BigInt(paramsIdx))]);
+}
+/**
+ * `issuance_logic`'s withdraw-0 redeemer — a MAP from policy id to that
+ * policy's `MintingRegistryProof`.
+ *
+ * The REPLACEABLE half of issuance (upstream #129). This is a Plutus `Pairs`
+ * association list, NOT a Constr. The two consumers read disjoint halves of it:
+ *
+ *   - `issuance_mint` reads only the KEYS — `has_key(covered, own_policy)`. It
+ *     never decodes a value.
+ *   - `issuance_logic` reads only the VALUES — `list.all` over the entries,
+ *     running the per-policy rule set on each proof.
+ *
+ * Entry ORDER is not significant to either, which is why this takes a list and
+ * imposes no sort.
+ *
+ * Three refusals, each closing a builder bug that reports as something else:
+ *
+ * ⛔ AN EMPTY MAP. `list.all([])` is VACUOUSLY TRUE on chain, so an empty
+ * redeemer sails through `issuance_logic` while every `issuance_mint` in the
+ * transaction fails its `has_key`. The failure names the mint, not the empty
+ * map, and nothing points at the omission.
+ *
+ * ⛔ A DUPLICATE POLICY ID. Compared as LOWER-CASED HEX STRINGS, not as encoded
+ * keys. MEASURED: `Data.map` builds a JS `Map` keyed by `Uint8Array` IDENTITY,
+ * so two distinct arrays holding identical bytes BOTH survive and the map is not
+ * deduplicated for you. Which of the two proofs governs is then a property of
+ * the ledger's map handling rather than of anything you wrote. The keys are
+ * lower-cased first because hex case is presentation and two spellings of one
+ * policy encode to identical bytes — the same normalisation `cip171.ts` applies
+ * to raw script hashes, and the hazard `ledger-order.ts` measures for ordering.
+ *
+ * ⛔ A VALUE THAT IS NOT A `MintingRegistryProof`. The keys are the frozen
+ * interface `issuance_mint` depends on; the values are what `issuance_logic`
+ * decodes, and a value it cannot decode aborts the whole withdrawal.
+ */
+export function issuanceLogicRedeemer(entries) {
+    if (entries.length === 0) {
+        throw new Error(`issuanceLogicRedeemer: the entry list is EMPTY. On chain issuance_logic runs ` +
+            `list.all over these entries, which is vacuously TRUE for an empty map — so an ` +
+            `empty redeemer passes issuance_logic while every issuance_mint in the transaction ` +
+            `fails its has_key check, and the error names the mint rather than the omission. ` +
+            `Every policy this transaction issues must appear here.`);
+    }
+    const seen = new Set();
+    for (const e of entries) {
+        const k = e.policyId.toLowerCase();
+        if (seen.has(k)) {
+            throw new Error(`issuanceLogicRedeemer: duplicate policy id ${e.policyId}. A policy occupies exactly ` +
+                `one entry in the map issuance_mint's has_key runs against. MEASURED: Data.map is a ` +
+                `JS Map keyed by Uint8Array IDENTITY, so two byte-identical keys BOTH survive and the ` +
+                `map is not deduplicated — which of the two proofs governs is not something this ` +
+                `builder decides.`);
+        }
+        seen.add(k);
+        const p = e.proof;
+        const ok = p instanceof Data.Constr && (p.index === 0n || p.index === 1n) && p.fields.length === 1;
+        if (!ok) {
+            throw new Error(`issuanceLogicRedeemer: the value for policy ${e.policyId} is not a ` +
+                `MintingRegistryProof. issuance_logic decodes every value, and one it cannot decode ` +
+                `aborts the whole withdrawal. Build it with mintingProofRefInput() when the registry ` +
+                `node is a reference input, or mintingProofOutputIndex() when it is an output of this ` +
+                `transaction.`);
+        }
+    }
+    return Data.map(entries.map((e) => [Data.bytearray(e.policyId), e.proof]));
+}
+/**
+ * Which of the three upgrade-path shapes a `protocol_params` SPEND is.
+ * Field-less constructors; the index is the whole payload. Mirrors `PlgAct` in
+ * `src/core/ledger-order.ts`.
+ */
+export const ProtocolParamsAct = {
+    PROTOCOL_UPGRADE: 0n,
+    NOMINATE_AUTHORITY: 1n,
+    PROMOTE_AUTHORITY: 2n,
+};
+/**
+ * Build a `ProtocolParamsRedeemer`.
+ *
+ * The arms carry no payload: every value a branch needs is already in the
+ * continuing datum, which is validated regardless. They exist to make each
+ * transaction DECLARE its intent, so `ProtocolUpgrade` freezes the nomination
+ * and `NominateAuthority` freezes everything else — an authority handover can
+ * never ride along inside a parameter change.
+ *
+ * ⛔ HAZARD: `ProtocolUpgrade` IS BYTE-IDENTICAL TO {@link voidData}, which is
+ * `Constr(0, [])`. Every existing caller that passes `voidData()` as the params
+ * spend redeemer therefore keeps working BY ACCIDENT, and no decoder anywhere —
+ * on chain or off — can distinguish a migrated caller from a stale one, because
+ * the bytes are the same bytes. Same shape as the `SpendViaTransfer` /
+ * `BaseSpendRedeemer` collision recorded in WORKLOG S-6.
+ *
+ * ⇒ The silence is ASYMMETRIC, and that is the risk profile: the other two arms
+ * are constructors 1 and 2, which `voidData()` cannot represent, so they fail
+ * loudly. Only the upgrade path is quiet — and it is the one every deployment
+ * exercises first.
+ *
+ * ⇒ Because no offline instrument can settle it, the proof that this redeemer
+ * was ever really implemented is a devnet mutation: submit `Constr(1, [])` where
+ * the validator expects `ProtocolUpgrade` and require it to go RED on chain. The
+ * ledger is the only witness with jurisdiction.
+ */
+export function protocolParamsRedeemer(arm) {
+    // `Object.hasOwn`, not `=== undefined`: `ProtocolParamsAct["valueOf"]` inherits
+    // a FUNCTION from Object.prototype, so a plain lookup sails past an undefined
+    // check and dies inside the encoder as a Data.Constr index type error naming
+    // nothing the caller can act on.
+    const idx = Object.hasOwn(ProtocolParamsAct, arm) ? ProtocolParamsAct[arm] : undefined;
+    if (idx === undefined) {
+        throw new Error(`protocolParamsRedeemer: unknown act ${JSON.stringify(arm)}. ` +
+            `Expected one of: ${Object.keys(ProtocolParamsAct).join(", ")}.`);
+    }
+    return Data.constr(idx, []);
+}
 /** Build a TransferAct redeemer for PLGlobal. */
 export function transferActRedeemer(proofs) {
     return Data.constr(0n, [
@@ -371,6 +637,161 @@ export function blacklistRemoveRedeemer(stakingPkh) {
     return Data.constr(2n, [Data.bytearray(stakingPkh)]);
 }
 // ---------------------------------------------------------------------------
+// MultisigScript — the upgrade authority's tree
+// ---------------------------------------------------------------------------
+/**
+ * Upper bound on the number of nodes (inner and leaf) a `MultisigScript` may
+ * hold, from upstream `lib/multisig.ak`'s `max_size`. Chosen there on MEASURED
+ * execution budget, not on feel, and baked into the validator's bytes — so a
+ * tree above it is refused on chain and changing the cap is a redeployment.
+ */
+export const MULTISIG_MAX_SIZE = 20;
+/** Node count, leaves included — upstream `multisig.size`. */
+function multisigSize(t) {
+    switch (t.type) {
+        case "all-of":
+        case "any-of":
+        case "at-least":
+            return 1 + t.scripts.reduce((acc, c) => acc + multisigSize(c), 0);
+        default:
+            return 1;
+    }
+}
+function expect28ByteHash(hash, where) {
+    if (!/^[0-9a-fA-F]{56}$/.test(hash)) {
+        throw new Error(`multisigScriptDatum: ${where} must be exactly 28 bytes (56 hex chars), got ` +
+            `${hash.length} chars. A hash of any other length can never match a signatory or a ` +
+            `withdrawal credential, so the leaf is permanently unsatisfiable — and an authority ` +
+            `nobody can satisfy is a permanent brick with no repair path.`);
+    }
+}
+/** Encode one node, enforcing upstream `shape_ok` as it goes. */
+function encodeMultisigNode(t) {
+    switch (t.type) {
+        case "signature":
+            expect28ByteHash(t.keyHash, "Signature.key_hash");
+            return Data.constr(0n, [Data.bytearray(t.keyHash)]);
+        case "script":
+            expect28ByteHash(t.scriptHash, "Script.script_hash");
+            return Data.constr(6n, [Data.bytearray(t.scriptHash)]);
+        case "before":
+            return Data.constr(4n, [Data.int(t.time)]);
+        case "after":
+            return Data.constr(5n, [Data.int(t.time)]);
+        case "all-of":
+            return Data.constr(1n, [Data.list(encodeChildren(t.scripts, "AllOf"))]);
+        case "any-of":
+            return Data.constr(2n, [Data.list(encodeChildren(t.scripts, "AnyOf"))]);
+        case "at-least": {
+            if (!Number.isInteger(t.required) || t.required < 1 || t.required > t.scripts.length) {
+                throw new Error(`multisigScriptDatum: AtLeast.required must satisfy 1 <= required <= ` +
+                    `${t.scripts.length} (the child count), got ${t.required}. A threshold of 0 or ` +
+                    `below authorises with no evidence at all; one above the child count can never be ` +
+                    `met. Upstream MINR-054 / audit-3 finding 05.`);
+            }
+            return Data.constr(3n, [
+                Data.int(BigInt(t.required)),
+                Data.list(encodeChildren(t.scripts, "AtLeast")),
+            ]);
+        }
+    }
+}
+function encodeChildren(scripts, where) {
+    if (scripts.length === 0) {
+        throw new Error(`multisigScriptDatum: ${where} has an EMPTY child list. AllOf [] is VACUOUSLY TRUE on ` +
+            `chain — a permissionless authority, the sharpest edge in the whole type — and AnyOf [] ` +
+            `can never be satisfied at all. One rule for all three list nodes, as upstream does.`);
+    }
+    const encoded = scripts.map(encodeMultisigNode);
+    // Structural equality, matching Aiken's `list.unique` over the children:
+    // compare the ENCODED CBOR rather than the JS objects, which are distinct
+    // references even when they describe the same node.
+    const seen = new Set();
+    for (const child of encoded) {
+        const key = bytesToHex(Data.toCBORBytes(child));
+        if (seen.has(key)) {
+            throw new Error(`multisigScriptDatum: ${where} has DUPLICATE children. A duplicate distorts AtLeast — ` +
+                `[A, A, B] at threshold 2 is met by A alone — and upstream refuses it on every list ` +
+                `node rather than only where it bites. Upstream MINR-054 / audit-3 finding 05.`);
+        }
+        seen.add(key);
+    }
+    return encoded;
+}
+/**
+ * Build a `MultisigScript` datum, enforcing upstream `lib/multisig.ak`'s
+ * `well_formed` — 28-byte hashes, non-empty and duplicate-free child lists,
+ * `1 <= required <= |scripts|`, and at most {@link MULTISIG_MAX_SIZE} nodes.
+ *
+ * ⛔ THE RAIL LIVES ON THE ENCODER ONLY, AND {@link decodeMultisigScript}
+ * DELIBERATELY ENFORCES NONE OF IT. The two functions answer different
+ * questions: the encoder decides what may be WRITTEN, the decoder reads what is
+ * ON CHAIN. A decoder that refused an ill-formed tree could not be used to
+ * inspect one — and inspecting a live authority somebody managed to write is
+ * exactly the moment you need to read it. Do not "tidy" the check into the
+ * decoder for symmetry.
+ */
+export function multisigScriptDatum(tree) {
+    const size = multisigSize(tree);
+    if (size > MULTISIG_MAX_SIZE) {
+        throw new Error(`multisigScriptDatum: the tree has ${size} nodes, above MULTISIG_MAX_SIZE = ` +
+            `${MULTISIG_MAX_SIZE}. The cap is baked into the validator's bytes and was chosen on ` +
+            `MEASURED execution budget; an authority that writes itself a tree too expensive to ` +
+            `evaluate has bricked the upgrade path.`);
+    }
+    return encodeMultisigNode(tree);
+}
+/**
+ * Parse a `MultisigScript` datum. Reads what is on chain and enforces NO
+ * well-formedness — see {@link multisigScriptDatum} for why the asymmetry is
+ * deliberate.
+ */
+export function decodeMultisigScript(d) {
+    if (!(d instanceof Data.Constr)) {
+        throw new Error("MultisigScript: expected a Constr");
+    }
+    const f = d.fields;
+    const children = (where) => {
+        const list = f[0];
+        if (!Array.isArray(list)) {
+            throw new Error(`MultisigScript.${where}: expected a list of scripts`);
+        }
+        return list.map(decodeMultisigScript);
+    };
+    switch (d.index) {
+        case 0n:
+            return { type: "signature", keyHash: expectBytes(f[0], "MultisigScript.Signature.keyHash") };
+        case 1n:
+            return { type: "all-of", scripts: children("AllOf") };
+        case 2n:
+            return { type: "any-of", scripts: children("AnyOf") };
+        case 3n: {
+            const required = f[0];
+            if (typeof required !== "bigint") {
+                throw new Error("MultisigScript.AtLeast: expected required to be an Int");
+            }
+            const list = f[1];
+            if (!Array.isArray(list)) {
+                throw new Error("MultisigScript.AtLeast: expected a list of scripts");
+            }
+            return { type: "at-least", required: Number(required), scripts: list.map(decodeMultisigScript) };
+        }
+        case 4n:
+        case 5n: {
+            const time = f[0];
+            if (typeof time !== "bigint") {
+                throw new Error("MultisigScript.Before/After: expected time to be an Int");
+            }
+            return d.index === 4n ? { type: "before", time } : { type: "after", time };
+        }
+        case 6n:
+            return { type: "script", scriptHash: expectBytes(f[0], "MultisigScript.Script.scriptHash") };
+        default:
+            throw new Error(`MultisigScript: unknown constructor index ${d.index}. Valid indices are 0..6 ` +
+                `(Signature, AllOf, AnyOf, AtLeast, Before, After, Script).`);
+    }
+}
+// ---------------------------------------------------------------------------
 // Asset helpers
 // ---------------------------------------------------------------------------
 /** Build an Assets object with a single native token unit + min lovelace */
@@ -536,6 +957,71 @@ export function buildCIP68FTDatum(meta) {
     ]);
 }
 // ---------------------------------------------------------------------------
+// The inline-datum bound
+// ---------------------------------------------------------------------------
+/**
+ * Serialised size, in bytes, of an inline datum.
+ *
+ * The on-chain counterpart is `bytearray.length(builtin.serialise_data(d))`
+ * inside `is_seizable_output_shape_bounded` (upstream `lib/assets.ak`), which
+ * every script that creates a programmable-logic-base output applies as
+ * `... <= max_inline_datum_bytes`. Since alpha.4 that includes `issuance_logic`,
+ * so a CIP-68 mint datum is bounded at BIRTH — the old issuance exemption is
+ * expired, and CIP-68 reference tokens carrying data-URI logos were the
+ * standing example of the kilobyte datum it now refuses.
+ *
+ * TWO ENCODERS, AND ONLY ONE DIRECTION IS SAFE. This measures with Evolution's
+ * `Data.toCBORBytes`; the chain measures with Plutus's `serialise_data`. They
+ * are different implementations and no offline instrument can prove they agree.
+ * The SDK must measure GREATER THAN OR EQUAL TO the chain: if it ever measures
+ * fewer bytes than the ledger does, it accepts a record the ledger then
+ * refuses, which is precisely the failure the bound exists to prevent.
+ *
+ * That direction is NOT settled here, and nothing in `test/cip68-bound.test.mjs`
+ * establishes it — every figure in that file comes from this same encoder. It
+ * is settled by the devnet at-bound SUCCESS in T-F04-4: a datum measuring
+ * exactly `maxInlineDatumBytes` by this function, accepted by a real ledger.
+ * Until that test is green, the agreement of the two encoders is an ASSUMPTION.
+ */
+export function inlineDatumBytes(datum) {
+    return Data.toCBORBytes(datum).length;
+}
+/**
+ * Refuse an inline datum larger than `maxInlineDatumBytes`, naming the bound,
+ * the measured size and the parameter the caller would have to change.
+ *
+ * THE COMPARISON IS `<=`, MATCHING THE CHAIN. A datum measuring EXACTLY
+ * `maxInlineDatumBytes` is legal and MUST be accepted. A `<` here would read as
+ * prudence and would instead remove CIP-68 registration from this SDK for the
+ * boundary case: the caller sees a refusal, concludes the feature does not
+ * work, and there is no incident, no log and no corruption for anyone to
+ * investigate. `test/cip68-bound.test.mjs` pins both directions one byte apart
+ * for that reason.
+ *
+ * `datum` is a `Data.Data` and NOT a `CIP68MetadataInput` on purpose: the thing
+ * the chain bounds is the serialised datum, so a helper taking metadata would
+ * be measuring a different object one step removed from the rule it mirrors.
+ *
+ * @param datum   the inline datum that will be attached to the output
+ * @param maxInlineDatumBytes  the deployment's bound (`DeploymentParams`)
+ * @param what    what is being measured, for the refusal message
+ */
+export function assertInlineDatumWithinBound(datum, maxInlineDatumBytes, what) {
+    const size = inlineDatumBytes(datum);
+    if (size <= maxInlineDatumBytes)
+        return;
+    throw new Error(`${what}: inline datum is ${size} bytes, which exceeds this deployment's ` +
+        `maxInlineDatumBytes of ${maxInlineDatumBytes}. The scripts that create ` +
+        `programmable-token outputs refuse a datum over the bound, so this ` +
+        `transaction would be rejected on chain. Remedy: shorten the metadata — ` +
+        `an embedded data-URI logo is almost always the cause, since a record ` +
+        `with every field at a documented cap is only 419 bytes — or use a ` +
+        `deployment whose maxInlineDatumBytes is larger. Note that the bound is ` +
+        `baked into four script hashes (transfer, third_party, unfracking, ` +
+        `issuance_logic), so raising it produces a DIFFERENT protocol instance ` +
+        `rather than a configuration change.`);
+}
+// ---------------------------------------------------------------------------
 // Re-exports for convenience
 // ---------------------------------------------------------------------------
 export { Data, Bytes, Assets, Credential, InlineDatum, KeyHash, EvoAddress, EvoScriptHash, TransactionHash, Transaction, UPLC, };