@easy1staking/cip113-sdk-ts 0.11.0 → 0.12.0

package/README.md

@@ -58,6 +58,103 @@ await client.awaitTx(txHash);
 | `@easy1staking/cip113-sdk-ts/freeze-and-seize` | Freeze-and-Seize substandard |
 | `@easy1staking/cip113-sdk-ts/dummy` | Dummy substandard |
 
+## Migrating to 0.12.0 (CIP-113 0.5.0-alpha.5 — the upgrade authority activates itself)
+
+⛔ **EVERY SCRIPT HASH DOWNSTREAM OF THE PARAMS POLICY CHANGES — EIGHT OF TWELVE.** An alpha.4
+instance **cannot be upgraded; it must be REDEPLOYED.** The four that survive (`always_fail`,
+`issuance_cbor_hex_mint`, `registry`, `upgrade_multisig`) hang off seeds and nonces rather than the
+params policy — and a redeployment uses fresh seeds, so they cannot collide with the old instance in
+practice.
+
+There is no migration path for a running deployment, and nothing in this SDK will pretend otherwise:
+`validateStandardBlueprint` is a version-**equality** gate, so 0.12.0 refuses an alpha.4 blueprint as
+firmly as it refuses an alpha.3 one. Stay on 0.11.x for as long as you need to keep operating an
+alpha.4 instance.
+
+⚠ **An earlier draft of this note said "every script hash changes". That was FALSE and it is
+recorded here rather than quietly corrected**, because the false version is *checkable*: one
+operator deriving `registry` at their old seeds finds it identical, and the credibility of the whole
+migration note goes with it. The eight/four split is measured in `test/hash-cascade.test.mjs`. The
+operational conclusion did not change.
+
+### What upstream changed — one line
+
+`protocol_params.mint` gained a single check:
+
+```aiken
+pairs.has_key(self.withdrawals, genesis_params.upgrade_cred)?
+```
+
+The transaction that mints the protocol-params NFT must now carry a **withdraw-0 from the
+credential its own datum names as the upgrade authority**. The authority has to *run* — through
+the same trampoline every later upgrade uses — before it becomes canonical, so a typo or the hash
+of a script nobody deployed can never take the protocol's upgrade seat. Measured against alpha.4:
+34 validators either side, **31 byte-identical**, and the only compiled code that moved is
+`protocol_params`'s.
+
+### Why one line relocates eight of the twelve
+
+`protocol_params`'s hash **is** the params-NFT policy id, and that policy id is the parameter at the
+root of the parameterisation graph. It feeds `programmable_logic_base`, and through it `transfer`,
+`third_party`, `unfracking` and `programmable_logic_global`; it feeds `issuance_logic` and
+`issuance_mint` directly. Only the four scripts that hang off seeds and nonces instead —
+`always_fail`, `issuance_cbor_hex_mint`, `registry`, `upgrade_multisig` — keep their alpha.4 hashes
+for the same inputs. This is measured in `test/hash-cascade.test.mjs` against a live alpha.4
+deployment record, not asserted.
+
+### What moved in this package's API
+
+**`buildProtocolGenesisTx` takes two new REQUIRED fields.**
+
+```diff
+  await buildProtocolGenesisTx({
+    client, changeAddress, availableUtxos, evaluator, plan,
+    protocolParamsSeedUtxo, issuanceSeedUtxo,
++   upgradeMultisigConfigUtxo,   // REQUIRED — the config UTxO, as a reference input
++   upgradeAuthoritySigners,     // REQUIRED — key hashes for `extra_signatories`; may be []
+  });
+```
+
+`upgradeMultisigConfigUtxo` is the UTxO `assertMultisigConfigUtxo()` already returns: read it back
+off the chain rather than reconstructing it from a record, because a signer rotation spends and
+recreates it. `upgrade_multisig.withdraw` finds its authority tree among the transaction's
+**reference inputs**, so without it the withdrawal cannot be decided.
+
+`upgradeAuthoritySigners` **cannot be defaulted or inferred, and that is structural.** A
+`MultisigScript` tree has seven node kinds; only `Signature` names a key hash. `Script` names
+another withdraw-0, `Before`/`After` name a validity bound, and `AnyOf`/`AtLeast` leave a genuine
+choice of *which branch* to satisfy. Picking a branch is the caller's decision. Pass `[]` if your
+tree needs no signature — but pass it.
+
+⚠ **What this builder does not do for you.** It adds signers, the withdrawal, the reference input
+and the script witness. A tree whose satisfying branch needs a `Script` leaf (a second withdraw-0)
+or a `Before`/`After` leaf (a validity interval) is **not** served by this step; such a deployment
+must build its own genesis, or this builder must grow those inputs first. Left out deliberately
+rather than guessed at.
+
+**`BOOTSTRAP_STEPS` reordered, and the strings did not change.** `stake-registrations` moved from
+last to **third**, ahead of `protocol-genesis`:
+
+```diff
+- seed → multisig-genesis → protocol-genesis → reference-scripts → stake-registrations
++ seed → multisig-genesis → stake-registrations → protocol-genesis → reference-scripts
+```
+
+This is a ledger rule, not a preference: a reward account cannot be withdrawn from in the same
+transaction that registers it, because withdrawals are applied against the state **before**
+certificates. A caller that drives the sequence off `BOOTSTRAP_STEPS` follows automatically. One
+that hard-coded the old order gets ledger code **3141**, *"rewards withdrawals must consume rewards
+in full"* — a message that names a balance problem and not a missing certificate.
+
+### The blueprint
+
+`blueprints/standard/v0.5.0-alpha.5/` ships alongside the older directories, pinned to upstream
+`b83a041eaa053625c502f8ee64b607a787cf5f79` and **reproduced from source** (Aiken v1.1.23+8949565,
+sha256 `ca53475332b5932f021fa134f823b932b05433ccd335bbf6251f18167826da66`, 164120 bytes). ⚠ That
+commit is a **PR branch head** (`refs/pull/143/head`), not a commit on `main`; see
+`blueprints/standard/v0.5.0-alpha.5/UPSTREAM_PIN.json` for why the pull ref is recorded alongside
+the branch name.
+
 ## Migrating to 0.11.0 (a wrong network label, and the bootstrap becomes public API)
 
 Two changes. The first is breaking for plugin authors and silent in one shape the compiler will

package/blueprints/standard/v0.5.0-alpha.5/UPSTREAM_PIN.json

@@ -0,0 +1,36 @@
+{
+  "artifact": "plutus.json",
+  "sha256": "ca53475332b5932f021fa134f823b932b05433ccd335bbf6251f18167826da66",
+  "declares": {
+    "title": "cardano-foundation/cip113-programmable-tokens",
+    "version": "0.5.0-alpha.5",
+    "compiler": "Aiken v1.1.23+8949565",
+    "validators": 34
+  },
+  "upstream": {
+    "repo": "https://github.com/cardano-foundation/cip113-programmable-tokens",
+    "commit": "b83a041eaa053625c502f8ee64b607a787cf5f79",
+    "ref": "feat/verify-upgrade-authority-at-deployment",
+    "note": "PINNED TO THE COMMIT, NOT THE VERSION STRING, AND NOT THE BRANCH NAME — upstream publishes NO git tags, so \"0.5.0-alpha.5\" is a `version` field inside plutus.json on a MOVING branch. ⛔ THIS COMMIT IS NOT ON `main`. Reachability was VERIFIED, not assumed, by `git ls-remote` against the upstream URL on 2026-09-23: b83a041eaa053625c502f8ee64b607a787cf5f79 is BOTH `refs/heads/feat/verify-upgrade-authority-at-deployment` AND `refs/pull/143/head`, while `refs/heads/main` stood at c3d04b9ad0573f35852b1b2403d31956a685b12d. A PR head is the most perishable ref GitHub serves — a squash-merge orphans it the instant it lands, which has already bitten this repo twice (013c1154, then 2e067fe). The `refs/pull/143/head` co-reachability is what keeps this artifact fetchable after the branch is deleted; record it, do not rely on the branch name alone. ⚠ WHICH CLONE: this artifact was reproduced from /home/giovanni/Development/workspace/cip113-programmable-tokens-onchain. The sibling checkout whose path reads like \"the dependency\", workspace/deps/cip113-programmable-tokens, sits at 018415de and CANNOT produce this tree."
+  },
+  "blueprint_reproduced": true,
+  "provenance": "VERIFIED",
+  "reproduce": {
+    "requires": "Aiken v1.1.23+8949565",
+    "command": "git clone https://github.com/cardano-foundation/cip113-programmable-tokens && git fetch origin refs/pull/143/head && git checkout b83a041eaa053625c502f8ee64b607a787cf5f79 && aikup install v1.1.23 && rm plutus.json && aiken build",
+    "note": "`aikup install v1.1.23` with the version explicit, never bare `aikup install`, which follows latest and will stop reproducing this artifact the moment v1.1.24 ships. ⚠ aiken BUILDS ANYWAY on a mismatched compiler, emitting only a warning — check the preamble's compiler field, do not trust the environment."
+  },
+  "verified": {
+    "date": "2026-09-23",
+    "method": "REPRODUCED FROM SOURCE",
+    "findings": [
+      "OBSERVED: `aiken build` at upstream commit b83a041eaa053625c502f8ee64b607a787cf5f79, with Aiken v1.1.23+8949565 (the environment's installed v1.1.22 was upgraded by `aikup install v1.1.23` first), produced a plutus.json BYTE-IDENTICAL to the one upstream commits at that same commit. Both sha256 ca53475332b5932f021fa134f823b932b05433ccd335bbf6251f18167826da66, both 164120 bytes. The build ran in a THROWAWAY CLONE, and upstream's committed plutus.json was DELETED before the build so it could not be mistaken for output.",
+      "⚠ THE MUTABLE-DEPENDENCY CAVEAT THAT SCOPED EVERY EARLIER PIN IS GONE AT THIS COMMIT, AND THAT IS A CHANGE WORTH RECORDING RATHER THAN A SENTENCE WORTH DELETING. alpha.2, alpha.3 and alpha.4 all pinned `aiken-lang/fuzz` to the BRANCH `main`; at b83a041 aiken.toml pins it to the TAG `v2.2.0`. `aiken-lang/stdlib` remains the tag `v3.1.0`. Both dependencies are now immutable refs, so this reproducibility claim needs no scope note. aiken.lock's `[etags]` is empty either way — an empty etags table records nothing about what was fetched, which is exactly why the TAG, not the lockfile, is what makes this reproducible.",
+      "DELTA FROM alpha.4 (pin 7e8a63198c5b240135f1aa2f043ce5d7c046b2c4), MEASURED by hashing every validator's compiledCode either side rather than read from upstream's diff: 34 validators either side, no title added or removed. 31 are BYTE-IDENTICAL. The only three that move are `protocol_params.protocol_params.{mint,spend,else}` — which is ONE script, since every handler of an Aiken `validator` block shares a single compiledCode and hash. alpha.4 `20e612fcd69a51d0…` -> alpha.5 `edac935fccd8215a…` (sha256 prefixes of the compiledCode).",
+      "THE FUNCTIONAL CHANGE IS ONE LINE, in `protocol_params`'s mint handler: `pairs.has_key(self.withdrawals, genesis_params.upgrade_cred)?`. The genesis transaction that mints the protocol-params NFT must now carry a withdraw-0 from the credential the genesis datum names as `upgrade_cred` — proving the initial authority exists, can run and consents BEFORE it becomes canonical, by the same trampoline every later upgrade uses. Everything else in the validator's diff is prose.",
+      "⛔ THE CASCADE, AND IT IS WHY alpha.5 IS A REDEPLOYMENT AND NOT AN UPGRADE. `protocol_params`'s hash IS `paramsPolicy`, which parameterises `programmable_logic_base` (and through it transfer / third_party / unfracking / programmable_logic_global), `issuance_logic` and `issuance_mint`. Only `always_fail`, `issuance_cbor_hex_mint`, `registry` and `upgrade_multisig` hang off seeds or nonces instead, so ONLY those four keep their alpha.4 hashes for the same DeploymentParams. Measured, not assumed — see `test/hash-cascade.test.mjs`, which derives both sides from a live alpha.4 preview record's own seeds.",
+      "⚠ THE PARAMS DATUM DID NOT MOVE. Six fields, same order as alpha.4: programmable_logic_global_cred, issuance_logic_cred, transfer_cred, third_party_cred, upgrade_cred, pending_upgrade_cred. The alpha.3 -> alpha.4 field-order hazard recorded in the alpha.4 pin does NOT recur here; a positional reader built against alpha.4 reads alpha.5 correctly. What changed is the transaction shape at genesis, not the datum.",
+      "DERIVED: because the pin is keyed to a commit on a PR branch rather than a tag, re-running `aiken build` against that branch at a LATER date will legitimately produce a different artifact. That is not drift in this pin — it is a new pin. Do not update this file's sha256 to make a newer build pass; add a new directory."
+    ]
+  }
+}