Common Patterns

Task-oriented recipes for the most common operations. Each pattern is self-contained — copy, paste, adapt.

For full tutorials, see the dedicated guide sections linked from each recipe.

Send ADA to an Address

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

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

const  = await 
  .()
  .({
    : .("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
    : .(5_000_000n) // 5 ADA
  })
  .()

const  = await .()
const  = await .()

More: Simple Payment | Multi-Output

Query Wallet UTxOs

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

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

// Get all UTxOs at your wallet address
const  = await .()
// utxos → UTxO[] with .txHash, .outputIndex, .assets, .datum

// Get UTxOs at a specific address
const  = .("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63")
const  = await .()

More: Querying UTxOs

Lock Funds to a Script

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

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

const  = .("addr_test1wrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qnmqsyu")

const  = await 
  .()
  .({
    : ,
    : .(10_000_000n),
    : new .({ : .(0n, []) })
  })
  .()

const  = await .()
await .()

More: Locking to Script | Datums

Spend from a Script

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

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

declare const : .[] // from client.getUtxos(scriptAddress)
declare const : any // compiled Plutus script (from Aiken build or Blueprint codegen)

const  = await 
  .()
  .({
    : ,
    : .(0n, [])
  })
  .({ :  })
  .()

const  = await .()
await .()

More: Spending from Script | Redeemers

Apply Parameters to a Compiled Script

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

declare const : string

const  = .(, [
  .("abc123def456abc123def456abc123def456abc123def456abc123de"),
  .(1735689600000n),
])
// applied → double-CBOR hex string ready for transaction use

More: Parameterized Scripts

Define a Type-Safe Datum

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

const  = .({
  : .,
  : .,
  : .,
})

type  = typeof .

const  = .()

// toData → PlutusData (Constr with 3 fields)
const  = .({
  : .("abc123def456abc123def456abc123def456abc123def456abc123de"),
  : 1735689600000n,
  : 25_000_000n,
})

// toCBORHex → CBOR hex string for on-chain use
const  = .({
  : .("abc123def456abc123def456abc123def456abc123def456abc123de"),
  : 1735689600000n,
  : 25_000_000n,
})
// cbor → "d8799f4e...1a017d7840ff" (ready for datum field)

More: TSchema | Datums

Register a Stake Key

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

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

declare const : .

const  = await 
  .()
  .({  })
  .()

const  = await .()
await .()

More: Staking Registration | Delegation

Set Transaction Validity Window

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

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

const  = (.())

const  = await 
  .()
  .({
    : .("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
    : .(2_000_000n)
  })
  .({
    : ,
    :  + 300_000n // 5 minutes
  })
  .()

const  = await .()
await .()

More: Validity Ranges

Sign and Verify a Message (CIP-30)

import { COSE, PrivateKey, Address } from "@evolution-sdk/evolution"

declare const privateKey: PrivateKey.PrivateKey
declare const myAddress: Address.Address

const payload = COSE.Utils.fromText("Login to MyDApp")

const signed = COSE.SignData.signData(
  Address.toHex(myAddress),
  payload,
  privateKey
)
// signed.signature — CBOR-encoded COSE_Sign1
// signed.key — CBOR-encoded COSE_Key

More: Message Signing

Handle Errors

import { Address, Assets, preprod, Client } from "@evolution-sdk/evolution"

const client = Client.make(preprod)
  .withBlockfrost({
    baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_API_KEY!
  })
  .withSeed({ mnemonic: process.env.WALLET_MNEMONIC!, accountIndex: 0 })

try {
  const tx = await client
    .newTx()
    .payToAddress({
      address: Address.fromBech32("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63"),
      assets: Assets.fromLovelace(2_000_000n)
    })
    .build()

  const signed = await tx.sign()
  await signed.submit()
} catch (error) {
  // TransactionBuilderError — build phase failure
  // EvaluationError — script evaluation failure
  // ProviderError — network/API error
  // CoinSelectionError — insufficient funds
  console.error(error)
}

More: Error Handling

Common Patterns

On this page