Error Handling

Evolution SDK is built on Effect, providing structured error handling with typed errors. Every operation that can fail returns an Effect<Success, Error> type, making error cases explicit and composable.

Error Types

Error	When
TransactionBuilderError	Build phase failures (insufficient funds, invalid parameters)
ProviderError	Provider communication issues (network, API errors)
EvaluationError	Plutus script evaluation failures

Promise API (Default)

The standard .build(), .sign(), .submit() methods return Promises. Errors throw as exceptions:

import { , ,  } from "@evolution-sdk/evolution"

const  = ({
  : "preprod",
  : { : "blockfrost", : "https://cardano-preprod.blockfrost.io/api/v0", : ..! },
  : { : "seed", : ..!, : 0 }
})

try {
  const  = await 
    .()
    .({
      : .("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
      : .(2_000_000n)
    })
    .()

  const  = await .()
  await .()
} catch () {
  .("Transaction failed:", )
}

Effect API

Use .buildEffect() for composable error handling with Effect:

import {  } from "effect"
import { , ,  } from "@evolution-sdk/evolution"

const  = ({
  : "preprod",
  : { : "blockfrost", : "https://cardano-preprod.blockfrost.io/api/v0", : ..! },
  : { : "seed", : ..!, : 0 }
})

// Build returns an Effect — errors are values, not exceptions
const  = 
  .()
  .({
    : .("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
    : .(2_000_000n)
  })
  .()

// Run with error handling
// Effect.runPromise(program).catch(console.error)

Either API

Use .buildEither() for explicit success/failure without exceptions:

import { , ,  } from "@evolution-sdk/evolution"

const  = ({
  : "preprod",
  : { : "blockfrost", : "https://cardano-preprod.blockfrost.io/api/v0", : ..! },
  : { : "seed", : ..!, : 0 }
})

const  = await 
  .()
  .({
    : .("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
    : .(2_000_000n)
  })
  .()

// result is Either<Error, SignBuilder>

Next Steps

Architecture — How errors flow through build phases
TypeScript Tips — Type patterns with Effect

Error Handling

Error Handling

Error Types

Promise API (Default)

Effect API

Either API

Next Steps

On this page