Merge pull request #112 from IntersectMBO/feat/add-tx-chaining

feat/add tx chaining

Author: solidsnakedev

.changeset/cold-clubs-doubt.md

@@ -0,0 +1,11 @@
+---
+"@evolution-sdk/evolution": patch
+---
+
+Add transaction chaining support via `SignBuilder.chainResult()`
+
+- Add `chainResult()` method to `SignBuilder` for building dependent transactions
+- Returns `ChainResult` with `consumed`, `available` UTxOs and pre-computed `txHash`
+- Lazy evaluation with memoization - computed on first call, cached for subsequent calls
+- Add `signAndSubmit()` convenience method combining sign and submit in one call
+- Remove redundant `chain()`, `chainEffect()`, `chainEither()` methods from TransactionBuilder

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

@@ -25,11 +25,21 @@ SignBuilder extends TransactionResultBase with signing capabilities.
 Only available when the client has a signing wallet (seed, private key, or API wallet).
 Provides access to unsigned transaction (via base interface) and signing operations.
 
+Includes `chainResult` for transaction chaining - use `chainResult.available` as
+`availableUtxos` for the next transaction in a chain.
+
 **Signature**
 
 ```ts
 export interface SignBuilder extends TransactionResultBase, EffectToPromiseAPI<SignBuilderEffect> {
   readonly Effect: SignBuilderEffect
+  /**
+   * Compute chain result for building dependent transactions.
+   * Contains consumed UTxOs, available UTxOs (remaining + created), and txHash.
+   *
+   * Result is memoized - computed once on first call, cached for subsequent calls.
+   */
+  readonly chainResult: () => ChainResult
 }
 ```
 
@@ -52,6 +62,7 @@ export interface SignBuilderEffect {
 
   // Signing methods
   readonly sign: () => Effect.Effect<SubmitBuilder, TransactionBuilderError>
+  readonly signAndSubmit: () => Effect.Effect<string, TransactionBuilderError>
   readonly signWithWitness: (
     witnessSet: TransactionWitnessSet.TransactionWitnessSet
   ) => Effect.Effect<SubmitBuilder, TransactionBuilderError>

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

@@ -46,6 +46,8 @@ export declare const makeSignBuilder: (params: {
   referenceUtxos: ReadonlyArray<CoreUTxO.UTxO>
   provider: Provider.Provider
   wallet: Wallet
+  outputs: ReadonlyArray<TxOut.TransactionOutput>
+  availableUtxos: ReadonlyArray<CoreUTxO.UTxO>
 }) => SignBuilder
 ```
 

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

@@ -629,6 +629,36 @@ export interface TransactionBuilderBase {
    * @category builder-methods
    */
   readonly addSigner: (params: AddSignerParams) => this
+
+  // ============================================================================
+  // Transaction Chaining Methods
+  // ============================================================================
+
+  /**
+   * Execute transaction build and return consumed/available UTxOs for chaining.
+   *
+   * Runs the full build pipeline (coin selection, fee calculation, evaluation) and returns
+   * which UTxOs were consumed and which remain available for subsequent transactions.
+   * Use this when building multiple dependent transactions in sequence.
+   *
+   * @returns Promise<ChainResult> with consumed and available UTxOs
+   *
+   * @example
+   * ```typescript
+   * // Build first transaction, get remaining UTxOs
+   * const tx1 = await builder
+   *   .payTo({ address, value: { lovelace: 5_000_000n } })
+   *   .build({ availableUtxos: walletUtxos })
+   *
+   * // Build second transaction using remaining UTxOs from chainResult
+   * const tx2 = await builder
+   *   .payTo({ address, value: { lovelace: 3_000_000n } })
+   *   .build({ availableUtxos: tx1.chainResult().available })
+   * ```
+   *
+   * @since 2.0.0
+   * @category chaining-methods
+   */
 }
 ````
 
@@ -1021,17 +1051,22 @@ Added in v2.0.0
 
 Result type for transaction chaining operations.
 
-**NOTE: NOT YET IMPLEMENTED** - This interface is reserved for future implementation
-of multi-transaction workflows. Current chain methods return stub implementations.
+Provides consumed and available UTxOs for building chained transactions.
+The available UTxOs include both remaining unspent inputs AND newly created outputs
+with pre-computed txHash, ready to be spent in subsequent transactions.
+
+Accessed via `SignBuilder.chainResult()` after calling `build()`.
 
 **Signature**
 
 ```ts
 export interface ChainResult {
-  readonly transaction: Transaction.Transaction
-  readonly newOutputs: ReadonlyArray<CoreUTxO.UTxO> // UTxOs created by this transaction
-  readonly updatedUtxos: ReadonlyArray<CoreUTxO.UTxO> // Available UTxOs for next transaction (original - spent + new)
-  readonly spentUtxos: ReadonlyArray<CoreUTxO.UTxO> // UTxOs consumed by this transaction
+  /** UTxOs consumed from availableUtxos by coin selection */
+  readonly consumed: ReadonlyArray<CoreUTxO.UTxO>
+  /** Available UTxOs: remaining unspent + newly created (with computed txHash) */
+  readonly available: ReadonlyArray<CoreUTxO.UTxO>
+  /** Pre-computed transaction hash (blake2b-256 of transaction body) */
+  readonly txHash: string
 }
 ```
 

packages/evolution-devnet/test/TxBuilder.Chain.test.ts

@@ -0,0 +1,115 @@
+import { afterAll, beforeAll, describe, expect, it } from "@effect/vitest"
+import * as Cluster from "@evolution-sdk/devnet/Cluster"
+import * as Config from "@evolution-sdk/devnet/Config"
+import * as Genesis from "@evolution-sdk/devnet/Genesis"
+import { Core } from "@evolution-sdk/evolution"
+import * as Address from "@evolution-sdk/evolution/core/Address"
+import type { SignBuilder } from "@evolution-sdk/evolution/sdk/builders/SignBuilder"
+import { createClient } from "@evolution-sdk/evolution/sdk/client/ClientImpl"
+
+describe("TxBuilder.chainResult", () => {
+  let devnetCluster: Cluster.Cluster | undefined
+  let genesisConfig: Config.ShelleyGenesis
+  let genesisUtxos: ReadonlyArray<Core.UTxO.UTxO> = []
+
+  const TEST_MNEMONIC =
+    "test test test test test test test test test test test test test test test test test test test test test test test sauce"
+
+  const createTestClient = (accountIndex: number = 0) => {
+    if (!devnetCluster) throw new Error("Cluster not initialized")
+    const slotConfig = Cluster.getSlotConfig(devnetCluster)
+    return createClient({
+      network: 0,
+      slotConfig,
+      provider: {
+        type: "kupmios",
+        kupoUrl: "http://localhost:1449",
+        ogmiosUrl: "http://localhost:1344"
+      },
+      wallet: {
+        type: "seed",
+        mnemonic: TEST_MNEMONIC,
+        accountIndex,
+        addressType: "Base"
+      }
+    })
+  }
+
+  beforeAll(async () => {
+    const tempClient = createClient({
+      network: 0,
+      wallet: { type: "seed", mnemonic: TEST_MNEMONIC, accountIndex: 0, addressType: "Base" }
+    })
+
+    const testAddress = await tempClient.address()
+    const testAddressHex = Address.toHex(testAddress)
+
+    genesisConfig = {
+      ...Config.DEFAULT_SHELLEY_GENESIS,
+      slotLength: 0.02,
+      epochLength: 50,
+      activeSlotsCoeff: 1.0,
+      initialFunds: { [testAddressHex]: 500_000_000_000 }
+    }
+
+    genesisUtxos = await Genesis.calculateUtxosFromConfig(genesisConfig)
+
+    devnetCluster = await Cluster.make({
+      clusterName: "chain-test",
+      ports: { node: 6008, submit: 9009 },
+      shelleyGenesis: genesisConfig,
+      kupo: { enabled: true, port: 1449, logLevel: "Info" },
+      ogmios: { enabled: true, port: 1344, logLevel: "info" }
+    })
+
+    await Cluster.start(devnetCluster)
+    await new Promise((resolve) => setTimeout(resolve, 5_000))
+  }, 180_000)
+
+  afterAll(async () => {
+    if (devnetCluster) {
+      await Cluster.stop(devnetCluster)
+      await Cluster.remove(devnetCluster)
+    }
+  }, 60_000)
+
+  it("should chain multiple transactions and submit them all", { timeout: 90_000 }, async () => {
+    const client = createTestClient(0)
+    const address = await client.address()
+    const TX_COUNT = 5
+
+    // Build chained transactions using build() + chainResult
+    let available = [...genesisUtxos]
+    const txs: Array<SignBuilder> = []
+    
+    for (let i = 0; i < TX_COUNT; i++) {
+      const tx = await client
+        .newTx()
+        .payToAddress({ address, assets: Core.Assets.fromLovelace(10_000_000n) })
+        .build({ availableUtxos: available })
+      txs.push(tx)
+      available = [...tx.chainResult().available]
+    }
+
+    // Verify all txHashes are unique
+    const txHashes = txs.map((tx) => tx.chainResult().txHash)
+    expect(new Set(txHashes).size).toBe(TX_COUNT)
+
+    // Submit all transactions
+    const submittedHashes: Array<string> = []
+    for (const tx of txs) {
+      const hash = await tx.signAndSubmit()
+      submittedHashes.push(hash)
+    }
+
+    // Verify computed hashes match submitted hashes
+    for (let i = 0; i < TX_COUNT; i++) {
+      expect(submittedHashes[i]).toBe(txs[i].chainResult().txHash)
+    }
+
+    // Wait for all to confirm
+    for (const hash of submittedHashes) {
+      expect(await client.awaitTx(hash, 1000)).toBe(true)
+    }
+  })
+})

packages/evolution/docs/modules/sdk/builders/SignBuilder.ts.md

@@ -25,11 +25,21 @@ SignBuilder extends TransactionResultBase with signing capabilities.
 Only available when the client has a signing wallet (seed, private key, or API wallet).
 Provides access to unsigned transaction (via base interface) and signing operations.
 
+Includes `chainResult` for transaction chaining - use `chainResult.available` as
+`availableUtxos` for the next transaction in a chain.
+
 **Signature**
 
 ```ts
 export interface SignBuilder extends TransactionResultBase, EffectToPromiseAPI<SignBuilderEffect> {
   readonly Effect: SignBuilderEffect
+  /**
+   * Compute chain result for building dependent transactions.
+   * Contains consumed UTxOs, available UTxOs (remaining + created), and txHash.
+   *
+   * Result is memoized - computed once on first call, cached for subsequent calls.
+   */
+  readonly chainResult: () => ChainResult
 }
 ```
 
@@ -52,6 +62,7 @@ export interface SignBuilderEffect {
 
   // Signing methods
   readonly sign: () => Effect.Effect<SubmitBuilder, TransactionBuilderError>
+  readonly signAndSubmit: () => Effect.Effect<string, TransactionBuilderError>
   readonly signWithWitness: (
     witnessSet: TransactionWitnessSet.TransactionWitnessSet
   ) => Effect.Effect<SubmitBuilder, TransactionBuilderError>

packages/evolution/docs/modules/sdk/builders/SignBuilderImpl.ts.md

@@ -46,6 +46,8 @@ export declare const makeSignBuilder: (params: {
   referenceUtxos: ReadonlyArray<CoreUTxO.UTxO>
   provider: Provider.Provider
   wallet: Wallet
+  outputs: ReadonlyArray<TxOut.TransactionOutput>
+  availableUtxos: ReadonlyArray<CoreUTxO.UTxO>
 }) => SignBuilder
 ```
 

packages/evolution/docs/modules/sdk/builders/TransactionBuilder.ts.md

@@ -629,6 +629,36 @@ export interface TransactionBuilderBase {
    * @category builder-methods
    */
   readonly addSigner: (params: AddSignerParams) => this
+
+  // ============================================================================
+  // Transaction Chaining Methods
+  // ============================================================================
+
+  /**
+   * Execute transaction build and return consumed/available UTxOs for chaining.
+   *
+   * Runs the full build pipeline (coin selection, fee calculation, evaluation) and returns
+   * which UTxOs were consumed and which remain available for subsequent transactions.
+   * Use this when building multiple dependent transactions in sequence.
+   *
+   * @returns Promise<ChainResult> with consumed and available UTxOs
+   *
+   * @example
+   * ```typescript
+   * // Build first transaction, get remaining UTxOs
+   * const tx1 = await builder
+   *   .payTo({ address, value: { lovelace: 5_000_000n } })
+   *   .build({ availableUtxos: walletUtxos })
+   *
+   * // Build second transaction using remaining UTxOs from chainResult
+   * const tx2 = await builder
+   *   .payTo({ address, value: { lovelace: 3_000_000n } })
+   *   .build({ availableUtxos: tx1.chainResult().available })
+   * ```
+   *
+   * @since 2.0.0
+   * @category chaining-methods
+   */
 }
 ````
 
@@ -1021,17 +1051,22 @@ Added in v2.0.0
 
 Result type for transaction chaining operations.
 
-**NOTE: NOT YET IMPLEMENTED** - This interface is reserved for future implementation
-of multi-transaction workflows. Current chain methods return stub implementations.
+Provides consumed and available UTxOs for building chained transactions.
+The available UTxOs include both remaining unspent inputs AND newly created outputs
+with pre-computed txHash, ready to be spent in subsequent transactions.
+
+Accessed via `SignBuilder.chainResult()` after calling `build()`.
 
 **Signature**
 
 ```ts
 export interface ChainResult {
-  readonly transaction: Transaction.Transaction
-  readonly newOutputs: ReadonlyArray<CoreUTxO.UTxO> // UTxOs created by this transaction
-  readonly updatedUtxos: ReadonlyArray<CoreUTxO.UTxO> // Available UTxOs for next transaction (original - spent + new)
-  readonly spentUtxos: ReadonlyArray<CoreUTxO.UTxO> // UTxOs consumed by this transaction
+  /** UTxOs consumed from availableUtxos by coin selection */
+  readonly consumed: ReadonlyArray<CoreUTxO.UTxO>
+  /** Available UTxOs: remaining unspent + newly created (with computed txHash) */
+  readonly available: ReadonlyArray<CoreUTxO.UTxO>
+  /** Pre-computed transaction hash (blake2b-256 of transaction body) */
+  readonly txHash: string
 }
 ```
 

packages/evolution/src/sdk/builders/SignBuilder.ts

@@ -4,7 +4,7 @@ import type * as Transaction from "../../core/Transaction.js"
 import type * as TransactionWitnessSet from "../../core/TransactionWitnessSet.js"
 import type { EffectToPromiseAPI } from "../Type.js"
 import type { SubmitBuilder } from "./SubmitBuilder.js"
-import type { TransactionBuilderError } from "./TransactionBuilder.js"
+import type { ChainResult, TransactionBuilderError } from "./TransactionBuilder.js"
 import type { TransactionResultBase } from "./TransactionResult.js"
 
 // ============================================================================
@@ -27,6 +27,7 @@ export interface SignBuilderEffect {
 
   // Signing methods
   readonly sign: () => Effect.Effect<SubmitBuilder, TransactionBuilderError>
+  readonly signAndSubmit: () => Effect.Effect<string, TransactionBuilderError>
   readonly signWithWitness: (
     witnessSet: TransactionWitnessSet.TransactionWitnessSet
   ) => Effect.Effect<SubmitBuilder, TransactionBuilderError>
@@ -43,9 +44,19 @@ export interface SignBuilderEffect {
  * Only available when the client has a signing wallet (seed, private key, or API wallet).
  * Provides access to unsigned transaction (via base interface) and signing operations.
  * 
+ * Includes `chainResult` for transaction chaining - use `chainResult.available` as
+ * `availableUtxos` for the next transaction in a chain.
+ * 
  * @since 2.0.0
  * @category interfaces
  */
 export interface SignBuilder extends TransactionResultBase, EffectToPromiseAPI<SignBuilderEffect> {
   readonly Effect: SignBuilderEffect
+  /**
+   * Compute chain result for building dependent transactions.
+   * Contains consumed UTxOs, available UTxOs (remaining + created), and txHash.
+   * 
+   * Result is memoized - computed once on first call, cached for subsequent calls.
+   */
+  readonly chainResult: () => ChainResult
 }