@easy1staking/cip113-sdk-ts 0.7.0 → 0.9.0

package/README.md

@@ -58,6 +58,76 @@ 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.9.0 (CIP-113 0.5.0-alpha.4)
+
+**0.9.0 targets a different protocol version and breaks every published consumer.** It is a
+minor bump because this package is pre-1.0; treat it as major. Version 0.8.0 was never published,
+so the real upgrade path is 0.3.1, or any later published release up to 0.7.0, to 0.9.0 and crosses both the
+alpha.2-to-alpha.3 and alpha.3-to-alpha.4 boundaries described here.
+
+⛔ **The alpha.3 change that will not announce itself.** `programmable_logic_base`'s redeemer went
+from a three-constructor enum to a single record:
+
+```
+0.5.0-alpha.2   SpendViaTransfer(params_idx, wdrl_idx)   = Constr(0, [Int, Int])
+0.5.0-alpha.3   BaseSpendRedeemer{params_idx, wdrl_idx}  = Constr(0, [Int, Int])
+```
+
+Those are **byte-identical**. A stale builder emitting `SpendViaTransfer` produces a redeemer that
+decodes cleanly and fails later on a credential check — because `wdrl_idx` now indexes the
+**dispatcher's** withdrawal, not the delegate's. `SpendViaThirdParty` and `SpendViaUnfracking`
+(constructors 1 and 2) fail loudly instead, so **the silence lands on the transfer path — the common
+one**. This SDK refuses the stale call shape at the API surface, because nothing downstream can.
+
+⛔ **The alpha.4 datum change is silent for the same reason.** The protocol-params datum grew
+from four fields to six, and `issuance_logic_cred` was inserted at **index 1**, not appended:
+
+| protocol version | protocol-params datum | size |
+|---|---|---|
+| 0.5.0-alpha.3 | `[plg, transfer, third_party, upgrade]` | 4 fields |
+| 0.5.0-alpha.4 | `[plg, ISSUANCE_LOGIC, transfer, third_party, upgrade, pending]` | 6 fields |
+
+Indices 1, 2 and 3 all hold a `Credential` before and after the change. An alpha.3 positional
+reader therefore returns well-formed credentials with the wrong meanings: `transfer_cred` moved
+to index 2, `third_party_cred` moved to index 3, and the old index 3 is no longer the upgrade
+credential. Nothing throws or fails to decode. Change positional readers to the six-field alpha.4
+layout and treat the field names, not their old positions, as the authority.
+
+⛔ **Every mint and burn now needs `issuance_logic`'s withdraw-0.** `issuance_mint` does not
+diagnose an omitted withdrawal: `covered_by` scans the transaction redeemers, returns `False` when
+it finds no matching withdrawal, and the mint fails naming no withdrawal, no policy and no index.
+Calling `register()`, `mint()`, or `burn()` on a 0.9.0 protocol emits the withdrawal and its
+policy-keyed redeemer alongside the minting-logic withdrawal.
+
+⚠ **CIP-68 metadata now meets the deployment's inline-datum bound on the issuance path.** At the
+CIP-68 datum shape, the chain's `serialise_data` measurement is exactly 2 bytes fewer than the
+SDK's `Data.toCBORBytes` measurement: Evolution emits indefinite-length CBOR for the outer
+constructor and metadata map, while Plutus's canonical encoder uses definite-length headers. The
+SDK is conservative: it never accepts a record the chain refuses. A caller's usable budget is
+`maxInlineDatumBytes - 2`; do not loosen the SDK comparison to reclaim those two bytes.
+
+| what changed | before | after |
+|---|---|---|
+| params NFT policy vs address | two derivations | **one hash serves both** (`protocolParams.policyId`) |
+| registry node policy vs address | `directoryMint` / `directorySpend` | **one hash serves both** (`registry.scriptHash`) |
+| protocol-params datum | 7 fields | **4** in alpha.3, then **6** in alpha.4 |
+| PLB redeemer | `SpendVia*` enum | `BaseSpendRedeemer` record; the act moved to the dispatcher |
+| `transferRedeemer` | `(params_idx, proofs)` | `(proofs)` |
+| `thirdPartyRedeemer` / `unfrackingRedeemer` | `(params_idx, node_idx, outputs_start_idx)` | `(node_idx, outputs_start_idx)` |
+| every programmable tx | delegate withdraw-0 | **plus the dispatcher's** — every `wdrl_idx` shifts |
+| every mint and burn | minting-logic withdraw-0 | **plus `issuance_logic`** |
+| new deployment input | — | `maxInlineDatumBytes`, a **choice**, baked into four script hashes |
+| gone | `coordinationNonce`, `coordination`, `directoryMint`, `directorySpend` | — |
+
+⚠ **`max_inline_datum_bytes` changed KIND, not just place.** It was a mutable datum field
+(re-tunable by an in-place upgrade) and is now a compile-time parameter of four delegates —
+`transfer`, `third_party`, `unfracking` and `issuance_logic` — so changing it is a redeployment.
+
+⚠ **Neither an alpha.3 nor an alpha.2 deployment can be represented by this SDK.** A 4-field
+alpha.3 params datum and a 7-field alpha.2 one are rejected outright rather than read
+positionally. No published release of this SDK operates an alpha.3 instance; its 0.8.x source line
+must be built from git. Point an alpha.2 instance at a published 0.7.x release.
+
 ## Examples
 
 > ### ⚠ The examples do not currently run. Do not follow this section yet.
@@ -65,8 +135,8 @@ await client.awaitTx(txHash);
 > Two things are wrong with it, both known and neither hidden:
 >
 > 1. **The scripts target a superseded protocol.** They are written against a CIP-113 **0.3.x**
->    deployment on preprod. This SDK now targets **0.5.0-alpha.2**, in which
->    `programmable_logic_global` no longer exists and `DeploymentParams` has a different shape.
+>    deployment on preprod. This SDK now targets **0.5.0-alpha.3**, in which `DeploymentParams`
+>    has a different shape again — see the migration note below.
 >    The scripts cannot work against that deployment, and the deployment cannot be represented
 >    by this SDK.
 > 2. **`.env.example` does not exist.** The `cp` below has never worked.

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

@@ -0,0 +1,35 @@
+{
+  "artifact": "plutus.json",
+  "sha256": "19bd7f1d4f5db0f0b63e3229d2393dd645d84ca8dd4d3318d78a5e5fbe364b34",
+  "declares": {
+    "title": "cardano-foundation/cip113-programmable-tokens",
+    "version": "0.5.0-alpha.3",
+    "compiler": "Aiken v1.1.23+8949565",
+    "validators": 28
+  },
+  "upstream": {
+    "repo": "https://github.com/cardano-foundation/cip113-programmable-tokens",
+    "commit": "f14b3594e1d6d3ae9e8511b99d39f17dfd4a3b65",
+    "ref": "main",
+    "note": "PINNED TO THE COMMIT, NOT THE VERSION STRING — same reasoning as v0.5.0-alpha.2: upstream publishes NO git tags, so \"0.5.0-alpha.3\" is a `version` field inside plutus.json on a MOVING branch and will eventually name two different programs. Reachability was VERIFIED, not assumed: `git merge-base --is-ancestor f14b359 origin/main` after a fetch. Full 40-char sha recorded deliberately — this repo has twice pinned an abbreviation or an orphan (013c1154, then 2e067fe, which GitHub's squash-merge orphaned the instant it landed)."
+  },
+  "blueprint_reproduced": true,
+  "provenance": "VERIFIED",
+  "reproduce": {
+    "requires": "Aiken v1.1.23+8949565",
+    "command": "git clone https://github.com/cardano-foundation/cip113-programmable-tokens && git checkout f14b3594e1d6d3ae9e8511b99d39f17dfd4a3b65 && aikup install v1.1.23 && 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-07",
+    "method": "REPRODUCED FROM SOURCE",
+    "findings": [
+      "OBSERVED: `aiken build` at upstream commit f14b3594e1d6d3ae9e8511b99d39f17dfd4a3b65, with Aiken v1.1.23+8949565, produced a plutus.json BYTE-IDENTICAL to the one upstream commits at that same commit. Both sha256 19bd7f1d4f5db0f0b63e3229d2393dd645d84ca8dd4d3318d78a5e5fbe364b34, both 113366 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.",
+      "⚠ ONE DEPENDENCY IS A MUTABLE BRANCH, AND THE REPRODUCIBILITY CLAIM IS SCOPED ACCORDINGLY. aiken.toml pins `aiken-lang/stdlib` to the TAG v3.1.0 (immutable), but `aiken-lang/fuzz` to `main` — a BRANCH. aiken.lock's [etags] records the fetched content hash. `fuzz` is referenced only from `test` and `bench` definitions and the generators serving them; `aiken build` emits neither, which is why byte-identity holds despite the mutable pin. A future rebuild could still see a different `fuzz` without that changing this blueprint.",
+      "This is the ONLY 0.5.0-alpha.3 artifact this repository ships, and it supersedes NOTHING: v0.5.0-alpha.2 is retained alongside because a LIVE preview protocol instance runs it (bootstrap tx 35954fc8c92db95dc7d1de361da3fe7d6ad0f6711f9501ebf7d7cf4219262031) and its record is deployments/preview/alpha2.json. Deleting alpha.2 would orphan a running deployment.",
+      "SURFACE DELTA vs alpha.2, measured by hashing every validator either side rather than read from upstream's changelog: 4 unchanged, 15 changed, 9 added, 8 removed (handler-level). Distinct validators REMOVED: coordination_spend, protocol_params_mint, registry_mint, registry_spend. ADDED: programmable_logic_global (3 params, the reintroduced dispatcher), protocol_params (1 param, mint+spend merged), registry (2 params, mint+spend merged). ARITY CHANGES: transfer, third_party and unfracking all go 1 -> 3 parameters while keeping their titles — a title that survives is not a validator that survived.",
+      "⚠ ProgrammableLogicGlobalParams went from SEVEN fields to FOUR, and not by truncation: it is now (plg_cred, transfer_cred, third_party_cred, upgrade_cred). registry_node_cs, unfracking_cred and max_inline_datum_bytes are gone; plg_cred is new. A positional parser written for the 7-field shape misreads every field from index 0 and throws nothing. RegistryNode is UNCHANGED at 7 fields.",
+      "DERIVED: because the pin is keyed to a commit on a moving branch, re-running `aiken build` against `main` 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."
+    ]
+  }
+}