feat/aiken uplc plugin

.changeset/cruel-wasps-worry.md

@@ -0,0 +1,5 @@
+---
+"@evolution-sdk/aiken-uplc": patch
+---
+
+Initial release of Aiken UPLC evaluator - a WASM-based plugin for local script evaluation in the Evolution SDK

.changeset/odd-cooks-jump.md

@@ -0,0 +1,52 @@
+---
+"@evolution-sdk/devnet": patch
+"@evolution-sdk/evolution": patch
+---
+
+### TxBuilder Composition API
+
+Add `compose()` and `getPrograms()` methods for modular transaction building:
+
+```ts
+// Create reusable builder fragments
+const mintBuilder = client.newTx()
+  .mintAssets({ policyId, assets: { tokenName: 1n }, redeemer })
+  .attachScript({ script: mintingPolicy })
+
+const metadataBuilder = client.newTx()
+  .attachMetadata({ label: 674n, metadata: "Cross-chain tx" })
+
+// Compose multiple builders into one transaction
+const tx = await client.newTx()
+  .payToAddress({ address, assets: { lovelace: 5_000_000n } })
+  .compose(mintBuilder)
+  .compose(metadataBuilder)
+  .build()
+```
+
+**Features:**
+- Merge operations from multiple builders into a single transaction
+- Snapshot accumulated operations with `getPrograms()` for inspection
+- Compose builders from different client instances
+- Works with all builder methods (payments, validity, metadata, minting, staking, etc.)
+
+### Fixed Validity Interval Fee Calculation Bug
+
+Fixed bug where validity interval fields (`ttl` and `validityIntervalStart`) were not included during fee calculation, causing "insufficient fee" errors when using `setValidity()`.
+
+**Root Cause**: Validity fields were being added during transaction assembly AFTER fee calculation completed, causing the actual transaction to be 3-8 bytes larger than estimated.
+
+**Fix**: Convert validity Unix times to slots BEFORE the fee calculation loop and include them in the TransactionBody during size estimation.
+
+### Error Type Corrections
+
+Corrected error types for pure constructor functions to use `never` instead of `TransactionBuilderError`:
+- `makeTxOutput` - creates TransactionOutput
+- `txOutputToTransactionOutput` - creates TransactionOutput  
+- `mergeAssetsIntoUTxO` - creates UTxO
+- `mergeAssetsIntoOutput` - creates TransactionOutput
+- `buildTransactionInputs` - creates and sorts TransactionInputs
+
+### Error Message Improvements
+
+Enhanced error messages throughout the builder to include underlying error details for better debugging.

docs/content/docs/modules/core/Metadata.mdx

@@ -497,8 +497,8 @@ Added in v2.0.0
 
 ## MetadataLabel
 
-Schema for transaction metadatum label (uint - unbounded positive integer).
-Uses Numeric.NonNegativeInteger for consistency with other numeric types.
+Schema for transaction metadatum label (uint64 per Cardano CDDL spec).
+Labels must be in range 0 to 2^64-1.
 
 **Signature**
 

docs/content/docs/modules/sdk/builders/TransactionBuilder.mdx

@@ -55,8 +55,6 @@ double-spending. UTxOs can come from any source (wallet, DeFi protocols, other p
     - [formatFailures (method)](#formatfailures-method)
   - [ScriptFailure (interface)](#scriptfailure-interface)
   - [TransactionBuilderError (class)](#transactionbuildererror-class)
-- [evaluators](#evaluators)
-  - [createUPLCEvaluator](#createuplcevaluator)
 - [model](#model)
   - [ChainResult (interface)](#chainresult-interface)
   - [EvaluationContext (interface)](#evaluationcontext-interface)
@@ -67,7 +65,6 @@ double-spending. UTxOs can come from any source (wallet, DeFi protocols, other p
   - [TxBuilderState (interface)](#txbuilderstate-interface)
 - [types](#types)
   - [ProgramStep (type alias)](#programstep-type-alias)
-  - [UPLCEvalFunction (type alias)](#uplcevalfunction-type-alias)
 - [utils](#utils)
   - [BuildOptions (interface)](#buildoptions-interface)
   - [PhaseContextTag (class)](#phasecontexttag-class)
@@ -633,7 +630,7 @@ export interface TransactionBuilderBase {
   /**
    * Attach metadata to the transaction.
    *
-   * Metadata is stored in the auxiliary data section and identified by labels (0-255)
+   * Metadata is stored in the auxiliary data section and identified by numeric labels
    * following the CIP-10 standard. Common use cases include:
    * - Transaction messages/comments (label 674, CIP-20)
    * - NFT metadata (label 721, CIP-25)
@@ -648,28 +645,19 @@ export interface TransactionBuilderBase {
    *
    * @example
    * ```typescript
-   * import * as TransactionMetadatum from "@evolution-sdk/core/TransactionMetadatum"
+   * import { fromEntries } from "@evolution-sdk/evolution/core/TransactionMetadatum"
    *
    * // Attach a simple message (CIP-20)
    * const tx = await builder
    *   .payToAddress({ address, assets: { lovelace: 2_000_000n } })
-   *   .attachMetadata({
-   *     label: 674n,
-   *     metadata: TransactionMetadatum.makeTransactionMetadatumMap(
-   *       new Map([[0n, TransactionMetadatum.makeTransactionMetadatumText("Hello, Cardano!")]])
-   *     )
-   *   })
+   *   .attachMetadata({ label: 674n, metadata: "Hello, Cardano!" })
    *   .build()
    *
    * // Attach NFT metadata (CIP-25)
-   * const nftMetadata = TransactionMetadatum.makeTransactionMetadatumMap(
-   *   new Map([
-   *     [TransactionMetadatum.makeTransactionMetadatumText("name"),
-   *      TransactionMetadatum.makeTransactionMetadatumText("My NFT #42")],
-   *     [TransactionMetadatum.makeTransactionMetadatumText("image"),
-   *      TransactionMetadatum.makeTransactionMetadatumText("ipfs://Qm...")],
-   *   ])
-   * )
+   * const nftMetadata = fromEntries([
+   *   ["name", "My NFT #42"],
+   *   ["image", "ipfs://Qm..."]
+   * ])
    * const tx = await builder
    *   .mintAssets({ assets: { [policyId + assetName]: 1n } })
    *   .attachMetadata({ label: 721n, metadata: nftMetadata })
@@ -681,6 +669,65 @@ export interface TransactionBuilderBase {
    */
   readonly attachMetadata: (params: AttachMetadataParams) => this
 
+  // ============================================================================
+  // Composition Methods
+  // ============================================================================
+
+  /**
+   * Compose this builder with another builder's accumulated operations.
+   *
+   * Merges all queued operations from another transaction builder into this one.
+   * The other builder's programs are captured at compose time and will be executed
+   * when build() is called on this builder.
+   *
+   * This enables modular transaction building where common patterns can be
+   * encapsulated in reusable builder fragments.
+   *
+   * **Important**: Composition is one-way - changes to the other builder after
+   * compose() is called will not affect this builder.
+   *
+   * @example
+   * ```typescript
+   * // Create reusable builder for common operations
+   * const mintBuilder = builder
+   *   .mintAssets({ policyId, assets: { tokenName: 1n }, redeemer })
+   *   .attachScript({ script: mintingPolicy })
+   *
+   * // Compose into a transaction that also pays to an address
+   * const tx = await builder
+   *   .payToAddress({ address, assets: { lovelace: 5_000_000n } })
+   *   .compose(mintBuilder)
+   *   .build()
+   *
+   * // Compose multiple builders
+   * const fullTx = await builder
+   *   .compose(mintBuilder)
+   *   .compose(metadataBuilder)
+   *   .compose(certBuilder)
+   *   .build()
+   * ```
+   *
+   * @param other - Another transaction builder whose operations will be merged
+   * @returns The same builder for method chaining
+   *
+   * @since 2.0.0
+   * @category composition-methods
+   */
+  readonly compose: (other: TransactionBuilder) => this
+
+  /**
+   * Get a snapshot of the accumulated programs.
+   *
+   * Returns a read-only copy of all queued operations that have been added
+   * to this builder. Useful for inspection, debugging, or advanced composition patterns.
+   *
+   * @returns Read-only array of accumulated program steps
+   *
+   * @since 2.0.0
+   * @category composition-methods
+   */
+  readonly getPrograms: () => ReadonlyArray<ProgramStep>
+
   // ============================================================================
   // Transaction Chaining Methods
   // ============================================================================
@@ -1079,23 +1126,6 @@ export declare class TransactionBuilderError
 
 Added in v2.0.0
 
-# evaluators
-
-## createUPLCEvaluator
-
-Creates an evaluator from a standard UPLC evaluation function.
-
-**NOTE: NOT YET IMPLEMENTED** - This function currently returns an evaluator
-that produces dummy data. Reserved for future UPLC script evaluation support.
-
-**Signature**
-
-```ts
-export declare const createUPLCEvaluator: (_evalFunction: UPLCEvalFunction) => Evaluator
-```
-
-Added in v2.0.0
-
 # model
 
 ## ChainResult (interface)
@@ -1168,7 +1198,7 @@ export interface Evaluator {
    * @category methods
    */
   evaluate: (
-    tx: string,
+    tx: Transaction.Transaction,
     additionalUtxos: ReadonlyArray<CoreUTxO.UTxO> | undefined,
     context: EvaluationContext
   ) => Effect.Effect<ReadonlyArray<EvalRedeemer>, EvaluationError>
@@ -1301,30 +1331,6 @@ export type ProgramStep = Effect.Effect<void, TransactionBuilderError, TxContext
 
 Added in v2.0.0
 
-## UPLCEvalFunction (type alias)
-
-Standard UPLC evaluation function signature (matches UPLC.eval_phase_two_raw).
-
-**NOTE: NOT YET IMPLEMENTED** - Reserved for future UPLC evaluation support.
-
-**Signature**
-
-```ts
-export type UPLCEvalFunction = (
-  tx_bytes: Uint8Array,
-  utxos_bytes_x: Array<Uint8Array>,
-  utxos_bytes_y: Array<Uint8Array>,
-  cost_mdls_bytes: Uint8Array,
-  initial_budget_n: bigint,
-  initial_budget_d: bigint,
-  slot_config_x: bigint,
-  slot_config_y: bigint,
-  slot_config_z: number
-) => Array<Uint8Array>
-```
-
-Added in v2.0.0
-
 # utils
 
 ## BuildOptions (interface)

docs/content/docs/modules/sdk/builders/TxBuilderImpl.mdx

@@ -78,7 +78,7 @@ Uses Core UTxO types directly.
 ```ts
 export declare const buildTransactionInputs: (
   utxos: ReadonlyArray<CoreUTxO.UTxO>
-) => Effect.Effect<ReadonlyArray<TransactionInput.TransactionInput>, TransactionBuilderError>
+) => Effect.Effect<ReadonlyArray<TransactionInput.TransactionInput>, never>
 ```
 
 Added in v2.0.0
@@ -187,7 +187,7 @@ export declare const calculateFeeIteratively: (
     }
   >,
   protocolParams: { minFeeCoefficient: bigint; minFeeConstant: bigint; priceMem?: number; priceStep?: number }
-) => Effect.Effect<bigint, TransactionBuilderError, TxContext>
+) => Effect.Effect<bigint, TransactionBuilderError, TxContext | BuildOptionsTag>
 ```
 
 Added in v2.0.0
@@ -350,7 +350,7 @@ export declare const makeTxOutput: (params: {
   assets: CoreAssets.Assets
   datum?: DatumOption.DatumOption
   scriptRef?: CoreScript.Script
-}) => Effect.Effect<TxOut.TransactionOutput, TransactionBuilderError>
+}) => Effect.Effect<TxOut.TransactionOutput, never>
 ```
 
 Added in v2.0.0
@@ -368,7 +368,7 @@ Use case: Draining wallet by merging leftover into an existing payment output.
 export declare const mergeAssetsIntoOutput: (
   output: TxOut.TransactionOutput,
   additionalAssets: CoreAssets.Assets
-) => Effect.Effect<TxOut.TransactionOutput, TransactionBuilderError>
+) => Effect.Effect<TxOut.TransactionOutput, never>
 ```
 
 Added in v2.0.0
@@ -386,7 +386,7 @@ Use case: Draining wallet by merging leftover into an existing payment output.
 export declare const mergeAssetsIntoUTxO: (
   utxo: CoreUTxO.UTxO,
   additionalAssets: CoreAssets.Assets
-) => Effect.Effect<CoreUTxO.UTxO, TransactionBuilderError>
+) => Effect.Effect<CoreUTxO.UTxO, never>
 ```
 
 Added in v2.0.0

docs/content/docs/modules/sdk/builders/operations/Attach.mdx

@@ -28,9 +28,7 @@ Scripts must be attached before being referenced by transaction inputs or mintin
 **Signature**
 
 ```ts
-export declare const attachScriptToState: (
-  script: ScriptCore.Script
-) => Effect.Effect<void, TransactionBuilderError, TxContext>
+export declare const attachScriptToState: (script: ScriptCore.Script) => Effect.Effect<void, never, TxContext>
 ```
 
 Added in v2.0.0

docs/content/docs/modules/sdk/builders/operations/AttachMetadata.mdx

@@ -42,7 +42,7 @@ Implementation:
 ```ts
 export declare const createAttachMetadataProgram: (
   params: AttachMetadataParams
-) => Effect.Effect<void, never, TxContext>
+) => Effect.Effect<undefined, TransactionBuilderError, TxContext>
 ```
 
 Added in v2.0.0

docs/content/docs/modules/sdk/builders/operations/Pay.mdx

@@ -35,9 +35,7 @@ Implementation:
 **Signature**
 
 ```ts
-export declare const createPayToAddressProgram: (
-  params: PayToAddressParams
-) => Effect.Effect<void, TransactionBuilderError, TxContext>
+export declare const createPayToAddressProgram: (params: PayToAddressParams) => Effect.Effect<void, never, TxContext>
 ```
 
 Added in v2.0.0

docs/content/docs/modules/sdk/builders/phases/FeeCalculation.mdx

@@ -68,6 +68,6 @@ goto balance
 export declare const executeFeeCalculation: () => Effect.Effect<
   PhaseResult,
   TransactionBuilderError,
-  PhaseContextTag | TxContext | ProtocolParametersTag
+  PhaseContextTag | TxContext | ProtocolParametersTag | BuildOptionsTag
 >
 ```

packages/aiken-uplc/.gitignore

@@ -0,0 +1 @@
+rust/target