@easy1staking/cip113-sdk-ts 0.10.0 → 0.12.0

package/README.md

@@ -58,6 +58,158 @@ 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
+not catch. The second is purely additive.
+
+### `SubstandardContext.network` was wrong, and its type hid it
+
+It was declared `string` and computed from `chain.id` — which is the **address** network id, `1`
+for mainnet and `0` for *every* testnet. **A preview client was therefore labelled `"preprod"`,
+and so was a devnet.** It is now `network?: Network`, derived from the chain's **network magic**,
+and a chain that is none of the three public networks yields **`undefined`** rather than a wrong
+name.
+
+```diff
+- network: string          // "preprod" on preview, and on a devnet
++ network?: Network        // "preview" on preview; undefined on a devnet
+```
+
+⛔ **The shape the compiler will NOT catch.** At 0.10.0 the field was declared `string` while the
+package exported a `Network` union, so a plugin that wanted the union **had no choice but to
+cast**:
+
+```ts
+switch (ctx.network as Network) { case "mainnet": … case "preprod": … case "preview": … }
+```
+
+**That cast still compiles and now yields `undefined` at runtime** — the exhaustive switch falls
+off the end and returns `undefined`, with no diagnostic anywhere. **Remove the cast.** Untyped
+JavaScript has the same exposure: `` `https://${ctx.network}.…` `` becomes `https://undefined.…`,
+`ctx.network.toUpperCase()` throws, and `JSON.stringify(ctx)` drops the key on a devnet.
+
+⚠ **The label is derived from the magic alone**, so a private network reusing a public magic is
+labelled as that network — a mainnet-fork devnet reports `"mainnet"`. If you gate a destructive
+path on `network !== "mainnet"`, that gate does not distinguish a fork from the real thing.
+`networkFromChain(chain)` is exported if you want the same mapping yourself, and
+`ctx.client.chain.networkMagic` / `.name` are on the same context object when you need more.
+
+### The protocol bootstrap is now exported
+
+`planBootstrap()`, five step builders and `assembleDeploymentParams()` build the transactions that
+stand up a protocol instance. **The SDK returns unsigned transactions and does not sign, submit or
+await** — orchestration, key handling and confirmation stay with the caller, which is also what
+lets a caller keep its own UTxO reservation and resume at a step rather than restart.
+
+The sequence is **stepwise, not a batch**: the one-shot minting policies are parameterised by
+output references of an earlier transaction, so step N+1 cannot be built until step N has been
+submitted and observed.
+
+⚠ **Values a caller must decide are required inputs, not defaults** — `maxInlineDatumBytes` (a
+security parameter), the one-shot nonces, the seed and reference-script lovelace, and
+`availableUtxos`. There are no devnet defaults in the published path: no mnemonic, no endpoint, no
+fixture values. `availableUtxos` is required on every step precisely so a caller can reserve its
+seed UTxOs from coin selection — a wallet-wide selection can otherwise spend a seed a later step
+names, or spend live reference scripts.
+
 ## Migrating to 0.10.0 (a required field on `DeploymentParams`)
 
 **0.10.0 adds one REQUIRED field and breaks every consumer that builds a `DeploymentParams`

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."
+    ]
+  }
+}