feat: add tx chaining

solidsnakedev · solidsnakedev · commit e20c16053b1c · 2025-12-23T11:33:11.000-07:00
diff --git a/packages/evolution-devnet/test/TxBuilder.Chain.test.ts b/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)
+    }
+  })
+})
diff --git a/packages/evolution-devnet/test/utils/utxo-helpers.ts b/packages/evolution-devnet/test/utils/utxo-helpers.ts
@@ -2,8 +2,7 @@ import { Core } from "@evolution-sdk/evolution"
 import * as CoreAddress from "@evolution-sdk/evolution/core/Address"
 import * as CoreData from "@evolution-sdk/evolution/core/Data"
 import * as CoreDatumOption from "@evolution-sdk/evolution/core/DatumOption"
-import * as CoreScript from "@evolution-sdk/evolution/core/Script"
-import * as CoreScriptRef from "@evolution-sdk/evolution/core/ScriptRef"
+import type * as CoreScript from "@evolution-sdk/evolution/core/Script"
 import * as CoreTransactionHash from "@evolution-sdk/evolution/core/TransactionHash"
 import * as CoreUTxO from "@evolution-sdk/evolution/core/UTxO"
 import type * as Datum from "@evolution-sdk/evolution/sdk/Datum"
@@ -103,20 +102,12 @@ export const createCoreTestUtxo = (options: CreateCoreTestUtxoOptions): CoreUTxO
     }
   }
 
-  // Convert Core Script to ScriptRef
-  let coreScriptRef: CoreScriptRef.ScriptRef | undefined
-  if (scriptRef) {
-    // Convert Script to ScriptRef bytes (CBOR-encoded script)
-    const scriptBytes = CoreScript.toCBOR(scriptRef)
-    coreScriptRef = new CoreScriptRef.ScriptRef({ bytes: scriptBytes })
-  }
-
   return new CoreUTxO.UTxO({
     transactionId: CoreTransactionHash.fromHex(paddedTxId),
     index: BigInt(index),
     address: CoreAddress.fromBech32(address),
     assets,
-    scriptRef: coreScriptRef,
+    scriptRef,
     datumOption: coreDatumOption
   })
 }
diff --git a/packages/evolution/src/sdk/builders/SignBuilder.ts b/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,27 @@ 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.
+   * 
+   * @example
+   * ```typescript
+   * const tx1 = await client.newTx().payToAddress(...).build({ availableUtxos: walletUtxos })
+   * const tx2 = await client.newTx().payToAddress(...).build({ availableUtxos: tx1.chainResult().available })
+   * await tx1.sign().submit()
+   * await tx2.sign().submit()
+   * ```
+   */
+  readonly chainResult: () => ChainResult
 }
diff --git a/packages/evolution/src/sdk/builders/SignBuilderImpl.ts b/packages/evolution/src/sdk/builders/SignBuilderImpl.ts
@@ -16,14 +16,18 @@
 
 import { Effect } from "effect"
 
+import * as Script from "../../core/Script.js"
 import * as Transaction from "../../core/Transaction.js"
+import * as TransactionHash from "../../core/TransactionHash.js"
 import * as TransactionWitnessSet from "../../core/TransactionWitnessSet.js"
-import type * as CoreUTxO from "../../core/UTxO.js"
+import type * as TxOut from "../../core/TxOut.js"
+import * as CoreUTxO from "../../core/UTxO.js"
+import { hashTransaction } from "../../utils/Hash.js"
 import type * as Provider from "../provider/Provider.js"
 import type * as WalletNew from "../wallet/WalletNew.js"
 import type { SignBuilder, SignBuilderEffect } from "./SignBuilder.js"
 import { makeSubmitBuilder } from "./SubmitBuilderImpl.js"
-import { TransactionBuilderError } from "./TransactionBuilder.js"
+import { type ChainResult, TransactionBuilderError } from "./TransactionBuilder.js"
 
 // ============================================================================
 // SignBuilder Factory
@@ -48,8 +52,38 @@ export const makeSignBuilder = (params: {
   referenceUtxos: ReadonlyArray<CoreUTxO.UTxO>
   provider: Provider.Provider
   wallet: Wallet
+  // Data for lazy chainResult computation
+  outputs: ReadonlyArray<TxOut.TransactionOutput>
+  availableUtxos: ReadonlyArray<CoreUTxO.UTxO>
 }): SignBuilder => {
-  const { fee, provider, referenceUtxos, transaction, transactionWithFakeWitnesses, utxos, wallet } = params
+  const { availableUtxos, fee, outputs, provider, referenceUtxos, transaction, transactionWithFakeWitnesses, utxos, wallet } = params
+
+  // Memoized chainResult - computed once on first access
+  let _chainResult: ChainResult | undefined
+  const chainResult = (): ChainResult => {
+    if (_chainResult) return _chainResult
+
+    const consumed = utxos
+    const txHash = hashTransaction(transaction.body)
+
+    const created: Array<CoreUTxO.UTxO> = outputs.map((output, index) =>
+      new CoreUTxO.UTxO({
+        transactionId: txHash,
+        index: BigInt(index),
+        address: output.address,
+        assets: output.assets,
+        datumOption: output.datumOption,
+        scriptRef: output.scriptRef ? Script.fromCBOR(output.scriptRef.bytes) : undefined
+      })
+    )
+
+    const consumedSet = new Set(consumed.map((u) => CoreUTxO.toOutRefString(u)))
+    const remaining = availableUtxos.filter((u) => !consumedSet.has(CoreUTxO.toOutRefString(u)))
+    const available = [...remaining, ...created]
+
+    _chainResult = { consumed, available, txHash: TransactionHash.toHex(txHash) }
+    return _chainResult
+  }
 
   // ============================================================================
   // Effect Namespace Implementation
@@ -108,6 +142,18 @@ export const makeSignBuilder = (params: {
         return makeSubmitBuilder(signedTransaction, mergedWitnessSet, provider)
       }),
 
+    /**
+     * Sign and submit the transaction in one step.
+     * 
+     * Convenience method that combines sign() and submit().
+     * Returns the transaction hash on success.
+     */
+    signAndSubmit: () =>
+      Effect.gen(function* () {
+        const submitBuilder = yield* signEffect.sign()
+        return yield* submitBuilder.Effect.submit()
+      }),
+
     /**
      * Sign the transaction using a pre-created witness set.
      * 
@@ -236,7 +282,9 @@ export const makeSignBuilder = (params: {
 
   return {
     Effect: signEffect,
+    chainResult,
     sign: () => Effect.runPromise(signEffect.sign()),
+    signAndSubmit: () => Effect.runPromise(signEffect.signAndSubmit()),
     signWithWitness: (witnessSet: TransactionWitnessSet.TransactionWitnessSet) =>
       Effect.runPromise(signEffect.signWithWitness(witnessSet)),
     assemble: (witnesses: ReadonlyArray<TransactionWitnessSet.TransactionWitnessSet>) =>
diff --git a/packages/evolution/src/sdk/builders/TransactionBuilder.ts b/packages/evolution/src/sdk/builders/TransactionBuilder.ts
