feat: add tx validity module

Author: solidsnakedev

.changeset/long-deer-roll.md

@@ -0,0 +1,50 @@
+---
+"@evolution-sdk/devnet": patch
+"@evolution-sdk/evolution": patch
+---
+
+### TxBuilder setValidity API
+
+Add `setValidity()` method to TxBuilder for setting transaction validity intervals:
+
+```ts
+client.newTx()
+  .setValidity({ 
+    from: Date.now(),           // Valid after this Unix time (optional)
+    to: Date.now() + 300_000    // Expires after this Unix time (optional)
+  })
+  .payToAddress({ ... })
+  .build()
+```
+
+- Times are provided as Unix milliseconds and converted to slots during transaction assembly
+- At least one of `from` or `to` must be specified
+- Validates that `from < to` when both are provided
+
+### slotConfig support for devnets
+
+Add `slotConfig` parameter to `createClient()` for custom slot configurations:
+
+```ts
+const slotConfig = Cluster.getSlotConfig(devnetCluster)
+const client = createClient({ 
+  network: 0, 
+  slotConfig,  // Custom slot config for devnet
+  provider: { ... }, 
+  wallet: { ... } 
+})
+```
+
+Priority chain for slot config resolution:
+1. `BuildOptions.slotConfig` (per-transaction override)
+2. `TxBuilderConfig.slotConfig` (client default)
+3. `SLOT_CONFIG_NETWORK[network]` (hardcoded fallback)
+
+### Cluster.getSlotConfig helper
+
+Add `getSlotConfig()` helper to derive slot configuration from devnet cluster genesis:
+
+```ts
+const slotConfig = Cluster.getSlotConfig(cluster)
+// Returns: { zeroTime, zeroSlot, slotLength }
+```

packages/evolution-devnet/src/Cluster.ts

@@ -20,6 +20,8 @@ export interface Cluster {
   readonly kupo?: Container.Container | undefined
   readonly ogmios?: Container.Container | undefined
   readonly networkName: string
+  /** The Shelley genesis config used by this cluster (needed for slot config) */
+  readonly shelleyGenesis: Config.ShelleyGenesis
 }
 
 /**
@@ -288,7 +290,8 @@ export const makeEffect = (config: Config.DevNetConfig = {}): Effect.Effect<Clus
             name: `${fullConfig.clusterName}-ogmios`
           }
         : undefined,
-      networkName
+      networkName,
+      shelleyGenesis: fullConfig.shelleyGenesis as Config.ShelleyGenesis
     }
   })
 
@@ -489,3 +492,58 @@ export const removeEffect = (cluster: Cluster): Effect.Effect<void, ClusterError
  * @category lifecycle
  */
 export const remove = (cluster: Cluster) => Effect.runPromise(removeEffect(cluster))
+
+/**
+ * Slot configuration type for Unix time to slot conversion.
+ *
+ * @since 2.0.0
+ * @category model
+ */
+export interface SlotConfig {
+  readonly zeroTime: bigint
+  readonly zeroSlot: bigint
+  readonly slotLength: number
+}
+
+/**
+ * Extract slot configuration from a devnet cluster.
+ *
+ * This returns the slot config needed for converting Unix timestamps to slots
+ * when using setValidity() or other time-based transaction operations.
+ *
+ * The slot config is derived from the cluster's Shelley genesis:
+ * - zeroTime: Genesis system start time (in milliseconds)
+ * - zeroSlot: Always 0 for devnets
+ * - slotLength: Slot duration in milliseconds
+ *
+ * @example
+ * ```typescript
+ * import * as Cluster from "@evolution-sdk/devnet/Cluster"
+ * import { createClient } from "@evolution-sdk/evolution/sdk/client/ClientImpl"
+ *
+ * const cluster = await Cluster.make({ ... })
+ * const slotConfig = Cluster.getSlotConfig(cluster)
+ *
+ * const client = createClient({
+ *   network: 0,
+ *   slotConfig,
+ *   provider: { type: "kupmios", kupoUrl: "...", ogmiosUrl: "..." },
+ *   wallet: { type: "seed", mnemonic: "..." }
+ * })
+ * ```
+ *
+ * @since 2.0.0
+ * @category utilities
+ */
+export const getSlotConfig = (cluster: Cluster): SlotConfig => {
+  const genesis = cluster.shelleyGenesis
+  // systemStart is ISO string, convert to Unix ms
+  const zeroTime = BigInt(new Date(genesis.systemStart).getTime())
+  // slotLength in genesis is in seconds, convert to ms
+  const slotLength = genesis.slotLength * 1000
+  return {
+    zeroTime,
+    zeroSlot: 0n,
+    slotLength
+  }
+}

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

@@ -0,0 +1,194 @@
+/**
+ * Devnet tests for TxBuilder validity interval (setValidity).
+ *
+ * Tests the setValidity operation which sets transaction validity bounds:
+ * - `from`: Transaction valid after this Unix time (validityIntervalStart slot)
+ * - `to`: Transaction expires after this Unix time (ttl slot)
+ *
+ * Test scenarios:
+ * 1. Build and submit a transaction with only TTL (to)
+ * 2. Build and submit a transaction with both bounds (from + to)
+ * 3. Verify expired transaction is rejected
+ */
+
+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 { createClient } from "@evolution-sdk/evolution/sdk/client/ClientImpl"
+
+// Alias for readability
+const Time = Core.Time
+
+describe("TxBuilder Validity Interval", () => {
+  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"
+
+  // Creates a client with correct slot config for devnet
+  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:1448",
+        ogmiosUrl: "http://localhost:1343"
+      },
+      wallet: {
+        type: "seed",
+        mnemonic: TEST_MNEMONIC,
+        accountIndex,
+        addressType: "Base"
+      }
+    })
+  }
+
+  beforeAll(async () => {
+    // Create a minimal client just to get the address (before cluster is ready)
+    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: "validity-test",
+      ports: { node: 6006, submit: 9007 },
+      shelleyGenesis: genesisConfig,
+      kupo: { enabled: true, port: 1448, logLevel: "Info" },
+      ogmios: { enabled: true, port: 1343, logLevel: "info" }
+    })
+
+    await Cluster.start(devnetCluster)
+    await new Promise((resolve) => setTimeout(resolve, 3_000))
+  }, 180_000)
+
+  afterAll(async () => {
+    if (devnetCluster) {
+      await Cluster.stop(devnetCluster)
+      await Cluster.remove(devnetCluster)
+    }
+  }, 60_000)
+
+  it("should build transaction with TTL and convert to slot correctly", { timeout: 60_000 }, async () => {
+    const client = createTestClient(0)
+    const myAddress = await client.address()
+
+    // Set TTL to 5 minutes from now
+    const ttl = Time.now() + 300_000n
+
+    const signBuilder = await client
+      .newTx()
+      .setValidity({ to: ttl })
+      .payToAddress({
+        address: myAddress,
+        assets: Core.Assets.fromLovelace(5_000_000n)
+      })
+      .build({ availableUtxos: [...genesisUtxos], debug: true })
+
+    const tx = await signBuilder.toTransaction()
+    
+    // Verify TTL is set in transaction body and converted to a slot number
+    expect(tx.body.ttl).toBeDefined()
+    expect(typeof tx.body.ttl).toBe("bigint")
+    expect(tx.body.ttl! > 0n).toBe(true)
+    expect(tx.body.validityIntervalStart).toBeUndefined()
+  })
+
+  it("should build transaction with both validity bounds and convert to slots", { timeout: 60_000 }, async () => {
+    const client = createTestClient(0)
+    const myAddress = await client.address()
+
+    // Valid from now until 5 minutes from now
+    const from = Time.now()
+    const to = Time.now() + 300_000n
+
+    const signBuilder = await client
+      .newTx()
+      .setValidity({ from, to })
+      .payToAddress({
+        address: myAddress,
+        assets: Core.Assets.fromLovelace(5_000_000n)
+      })
+      .build({ availableUtxos: [...genesisUtxos], debug: true })
+
+    const tx = await signBuilder.toTransaction()
+    
+    // Verify both bounds are set as slot numbers
+    expect(tx.body.ttl).toBeDefined()
+    expect(typeof tx.body.ttl).toBe("bigint")
+    expect(tx.body.ttl! > 0n).toBe(true)
+    
+    expect(tx.body.validityIntervalStart).toBeDefined()
+    expect(typeof tx.body.validityIntervalStart).toBe("bigint")
+    expect(tx.body.validityIntervalStart! > 0n).toBe(true)
+    
+    // TTL should be after validity start
+    expect(tx.body.ttl! > tx.body.validityIntervalStart!).toBe(true)
+  })
+
+  it("should reject expired transaction", { timeout: 60_000 }, async () => {
+    const client = createTestClient(0)
+    const myAddress = await client.address()
+
+    // Set TTL to 1 second ago (already expired)
+    const expiredTtl = Time.now() - 1_000n
+
+    const signBuilder = await client
+      .newTx()
+      .setValidity({ to: expiredTtl })
+      .payToAddress({
+        address: myAddress,
+        assets: Core.Assets.fromLovelace(5_000_000n)
+      })
+      .build({ availableUtxos: [...genesisUtxos], debug: true })
+
+    const submitBuilder = await signBuilder.sign()
+    
+    // Submission should fail due to expired TTL
+    await expect(submitBuilder.submit()).rejects.toThrow()
+  })
+
+  it("should reject transaction before validity start", { timeout: 60_000 }, async () => {
+    const client = createTestClient(0)
+    const myAddress = await client.address()
+
+    // Valid starting 5 minutes from now (not valid yet)
+    const from = Time.now() + 300_000n
+    const to = Time.now() + 600_000n
+
+    const signBuilder = await client
+      .newTx()
+      .setValidity({ from, to })
+      .payToAddress({
+        address: myAddress,
+        assets: Core.Assets.fromLovelace(5_000_000n)
+      })
+      .build({ availableUtxos: [...genesisUtxos], debug: true })
+
+    const submitBuilder = await signBuilder.sign()
+    
+    // Submission should fail because tx is not valid yet
+    await expect(submitBuilder.submit()).rejects.toThrow()
+  })
+})