From 0b58b13aa2677a36b9cf9d1f79c8df8e5e465535 Mon Sep 17 00:00:00 2001 From: jorbuedo Date: Wed, 21 Oct 2026 13:03:34 +0200 Subject: [PATCH] docs(transaction-output): deprecate it in favour of TxOut Two models of a transaction output are public from the entry point under names that give no hint which is which: this one (`address: AddressEras`, `amount: Value`, a Shelley and a Babbage class) and `TxOut` (`address: Address`, `assets: Assets`, one class for both eras), which is what `TransactionBody`, the builders and the sdk take. They reject each other, and the error says `Expected TransactionOutput, actual [toString threw]` about a value that IS a `TransactionOutput` -- the other one. Deprecation rather than removal or an alias: every caller holding a `BabbageTransactionOutput` keeps working, and new code is pointed at `TxOut`. The tag is on each of the sixteen exports, naming that export's `TxOut` counterpart, rather than on the module: TypeScript cannot deprecate a namespace re-export, so a module tag reaches no caller -- and docgen skips a module that carries one, which would have dropped the page from the docs site. --- .changeset/transaction-output-deprecated.md | 7 ++++ packages/evolution/src/TransactionOutput.ts | 42 +++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 .changeset/transaction-output-deprecated.md diff --git a/.changeset/transaction-output-deprecated.md b/.changeset/transaction-output-deprecated.md new file mode 100644 index 000000000..b8399465d --- /dev/null +++ b/.changeset/transaction-output-deprecated.md @@ -0,0 +1,7 @@ +--- +"@evolution-sdk/evolution": patch +--- + +`TransactionOutput` is deprecated in favour of `TxOut`. It is a second, parallel model of a transaction output (`address: AddressEras`, `amount: Value`, a Shelley and a Babbage class) while `TxOut` carries the one `TransactionBody`, the builders and the sdk use (`address: Address`, `assets: Assets`, one class for both eras). Both are public under names that give no hint which is which, and they reject each other: an output built with `TransactionOutput` cannot go into a `TransactionBody`. Nothing is removed or re-pointed, so no caller breaks. + +Every export of the module carries the tag, each naming its `TxOut` counterpart, since TypeScript cannot deprecate a namespace re-export and a tag on the module alone reaches no caller. diff --git a/packages/evolution/src/TransactionOutput.ts b/packages/evolution/src/TransactionOutput.ts index 24c4225c6..ef05fd11d 100644 --- a/packages/evolution/src/TransactionOutput.ts +++ b/packages/evolution/src/TransactionOutput.ts @@ -1,3 +1,20 @@ +/** + * Transaction outputs, as a union of a Shelley-era and a Babbage-era class. + * + * ⚠️ **Deprecated: use {@link TxOut} instead.** This is a SECOND, parallel model of a transaction + * output -- `address: AddressEras` and `amount: Value` -- while `TxOut` carries the one + * `TransactionBody`, the builders and the sdk actually use (`address: Address`, `assets: Assets`, + * one class covering both eras). Both are public from the package entry point under names that + * give no hint which is which, and they reject each other: an output built here cannot be placed + * in a `TransactionBody`, and the error reads `Expected TransactionOutput, actual [toString + * threw]` about a value that IS a `TransactionOutput` -- the other one. + * + * It stays exported, and keeps working, because removing it or pointing it at `TxOut` would break + * every caller that holds a `BabbageTransactionOutput`. New code should reach for `TxOut`. + * + * @since 2.0.0 + */ + import { Either as E, Equal, FastCheck, Hash, Inspectable, ParseResult, Schema } from "effect" import * as AddressEras from "./AddressEras.js" @@ -30,6 +47,7 @@ const decScriptRef = ParseResult.decodeUnknownEither(ScriptRef.FromCDDL) * * @since 2.0.0 * @category model + * @deprecated Use `TxOut.TransactionOutput` instead; `TransactionOutput` is a second, parallel model. */ export class ShelleyTransactionOutput extends Schema.TaggedClass()( "ShelleyTransactionOutput", @@ -82,6 +100,7 @@ export class ShelleyTransactionOutput extends Schema.TaggedClass()( "BabbageTransactionOutput", @@ -138,11 +157,20 @@ export class BabbageTransactionOutput extends Schema.TaggedClass { const { ledger, plutusData } = CBOR.toTxCodecOptions(options) @@ -300,6 +336,7 @@ export const FromCBORBytes = (options: CBOR.TxCodecOptions | CBOR.CodecOptions = * * @since 2.0.0 * @category transformer + * @deprecated Use `TxOut.FromCBORHex` instead; `TransactionOutput` is a second, parallel model. */ export const FromCBORHex = (options: CBOR.TxCodecOptions | CBOR.CodecOptions = CBOR.TX_DEFAULT_OPTIONS) => Schema.compose( @@ -314,6 +351,7 @@ export const FromCBORHex = (options: CBOR.TxCodecOptions | CBOR.CodecOptions = C /** * @since 2.0.0 * @category arbitrary + * @deprecated Use `TxOut.arbitrary` instead; `TransactionOutput` is a second, parallel model. */ export const arbitrary = FastCheck.oneof( // Shelley TransactionOutput @@ -337,6 +375,7 @@ export const arbitrary = FastCheck.oneof( * * @since 2.0.0 * @category encoding + * @deprecated Use `TxOut.toCBORBytes` instead; `TransactionOutput` is a second, parallel model. */ export const toCBORBytes = ( data: TransactionOutput, @@ -348,6 +387,7 @@ export const toCBORBytes = ( * * @since 2.0.0 * @category encoding + * @deprecated Use `TxOut.toCBORHex` instead; `TransactionOutput` is a second, parallel model. */ export const toCBORHex = ( data: TransactionOutput, @@ -359,6 +399,7 @@ export const toCBORHex = ( * * @since 2.0.0 * @category decoding + * @deprecated Use `TxOut.fromCBORBytes` instead; `TransactionOutput` is a second, parallel model. */ export const fromCBORBytes = (bytes: Uint8Array, options: CBOR.CodecOptions = CBOR.CML_DEFAULT_OPTIONS) => Schema.decodeSync(FromCBORBytes(options))(bytes) @@ -368,6 +409,7 @@ export const fromCBORBytes = (bytes: Uint8Array, options: CBOR.CodecOptions = CB * * @since 2.0.0 * @category decoding + * @deprecated Use `TxOut.fromCBORHex` instead; `TransactionOutput` is a second, parallel model. */ export const fromCBORHex = (hex: string, options: CBOR.CodecOptions = CBOR.CML_DEFAULT_OPTIONS) => Schema.decodeSync(FromCBORHex(options))(hex)