Breaking changes

⚠️ 17.0.0 rejects any JSON produced by CSL 16.0.0 or earlier that contains a Plutus script. Not "some of it" — all of it. Every released version up to and including 16.0.0 wrote a Plutus script as a bare hex string, for V1, V2 and V3 alike. 17.0.0 requires an object with an explicit language:

{ "bytes": "4d01000033222220051200120011", "language": "PlutusV1" }

so every one of those older documents now fails to parse:

invalid type: string "4d01000033222220051200120011", expected struct PlutusScriptJson

This is not limited to PlutusScript on its own — the type has no from_json of its own, it is always reached through a container. Every one of these will fail on a document holding a Plutus script:

PlutusScripts, TransactionWitnessSet, TransactionWitnessSets, AuxiliaryData, ScriptRef, TransactionOutput, TransactionOutputs, TransactionUnspentOutput, TransactionUnspentOutputs, TransactionBody, Transaction, Block, VersionedBlock.

If you have persisted any of the above as JSON — a UTxO cache, a stored partial transaction, a fixture file, a database column — it will not load under 17.0.0 until it is re-encoded. Documents with no Plutus script in them are unaffected.

The incompatibility runs both ways: JSON written by 17.0.0 will not parse under 16.0.0 or earlier, which see an object where they expect a string.

CBOR is untouched. to_bytes / from_bytes / to_hex / from_hex are byte-identical to 16.0.0, and the language has always been carried correctly there. If your stored data is CBOR, nothing changes for you, and going through CBOR is the reliable way to migrate JSON.

The JSON schema changed to match: PlutusScript is no longer an untagged union of string and object. schemars::schema_for!(PlutusScript) emits a plain object with required: ["bytes", "language"], so generated clients get one concrete type instead of a two-branch anyOf.

Why the language had to be written down

Dropping it meant a V2 or V3 script read back as V1, which changes the script_namespace() byte, which changes the ScriptHash, which changes the script address — silently, with no error anywhere along the way. A round-trip through JSON could hand you a different script than the one you put in. Fixed in #760, which landed after 16.0.0 was cut, so 17.0.0 is the first release to contain it.

Why a bare hex string is rejected rather than read as V1

#760 as merged still accepted one, for compatibility. Removing that fallback is the point of this major bump: a bare hex string in stored JSON is not "a V1 script", it is a script whose language an older CSL threw away. Reading it as V1 silently reproduces the very hash mismatch the fix was about, and a wrong script address is a far worse outcome than a parse error.

Migrating

The language cannot be recovered from a bare hex string — that information was never written down. You have to supply it:

• You still have the CBOR, or can rebuild the object from chain data: deserialize from CBOR under 17.0.0 and re-serialize to JSON. Nothing to guess.
• JSON only, and you know the language out of band (almost always the case — it is a property of your own scripts): rewrite each script in place, from

  "4d01000033222220051200120011"

  to

  { "bytes": "4d01000033222220051200120011", "language": "PlutusV2" }

  language is one of "PlutusV1", "PlutusV2", "PlutusV3".
• JSON only, and you do not know the language: it is recoverable if you know the script's on-chain hash — hash the bytes under each of the three namespace prefixes and keep the one that matches. Do not simply assume V1; that is precisely the bug this release exists to stop.

Thanks

Thanks to @npoxon (Nick Poxon) for #760, which found the dropped language version and fixed it. It is a quiet, nasty class of bug — no error, no panic, just a script hash that does not match the one you expected. This release ships that fix and finishes it by dropping the compatibility fallback it had to leave in place.

Published

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/17.0.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/17.0.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/17.0.0
https://crates.io/crates/cardano-serialization-lib/17.0.0

Experimental packages with gc support

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs-gc/v/17.0.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser-gc/v/17.0.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs-gc/v/17.0.0

Full Changelog: 16.0.0...17.0.0