### Run the Development Server

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/examples/with-vite-react/README.md

Navigate to the example directory and start the Vite development server.

```bash
cd examples/with-vite-react
pnpm dev
```

--------------------------------

### Provide Example Environment Variables

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/wallets/security.mdx

Create an example environment file (`.env.example`) to document the required variables and their formats, without exposing actual secrets. This aids in setup for new developers.

```bash
# .env.example
MNEMONIC="your 24 word mnemonic here"
PRIVATE_KEY="ed25519e_sk1..."
BLOCKFROST_PROJECT_ID="your_project_id"
```

--------------------------------

### Kupmios Docker Compose Example

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/providers/provider-types.mdx

Example Docker Compose setup for running Cardano node, Ogmios, and Kupo services for Kupmios provider.

```bash
# Docker Compose example
services:
  cardano-node:
    image: inputoutput/cardano-node:latest
    # ... node configuration

  ogmios:
    image: cardanosolutions/ogmios:latest
    ports:
      - "1337:1337"
    depends_on:
      - cardano-node

  kupo:
    image: cardanosolutions/kupo:latest
    ports:
      - "1442:1442"
    depends_on:
      - cardano-node
```

--------------------------------

### Complete Devnet Cluster Workflow Example

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/getting-started.mdx

Provides a full example of setting up, running, and cleaning up a devnet cluster for a development session. It includes starting the cluster with specific configurations, verifying service health, and ensuring proper cleanup using a try-finally block. Dependencies include '@evolution-sdk/devnet'.

```typescript
import { Cluster, Container } from "@evolution-sdk/devnet";

async function runDevnetSession() {
  // Create cluster with full stack
  const cluster = await Cluster.make({
    clusterName: "dev-session",
    ports: { node: 3001, submit: 3002 },
    kupo: { enabled: true, port: 1442 },
    ogmios: { enabled: true, port: 1337 }
  });

  try {
    // Start the environment
    await Cluster.start(cluster);
    console.log("✓ Devnet started");

    // Wait for initialization
    await new Promise(resolve => setTimeout(resolve, 5000));

    // Verify all services are healthy
    const nodeStatus = await Container.getStatus(cluster.cardanoNode);
    const kupoStatus = cluster.kupo 
      ? await Container.getStatus(cluster.kupo)
      : null;
    const ogmiosStatus = cluster.ogmios
      ? await Container.getStatus(cluster.ogmios)
      : null;

    console.log("✓ Node:", nodeStatus?.State.Status);
    console.log("✓ Kupo:", kupoStatus?.State.Status);
    console.log("✓ Ogmios:", ogmiosStatus?.State.Status);

    // Your development work happens here
    console.log("\n🚀 Devnet ready for development");
    console.log("   Ogmios: http://localhost:1337");
    console.log("   Kupo: http://localhost:1442");

    // Keep running for development
    // In real usage, this would be your test suite or app runtime
    await new Promise(resolve => setTimeout(resolve, 10000));

  } finally {
    // Always clean up
    await Cluster.stop(cluster);
    await Cluster.remove(cluster);
    console.log("\n✓ Devnet stopped and removed");
  }
}

runDevnetSession().catch(console.error);
```

--------------------------------

### Complete Devnet to Transaction Workflow

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/integration.mdx

This example shows the full cycle from cluster creation to confirmed transaction, including wallet setup, genesis configuration, client connection, parameter querying, transaction building, signing, submission, and confirmation.

```typescript
import {
  Cluster,
  Config,
  Genesis } from "@evolution-sdk/devnet"
import { Address,
  Assets,
  TransactionHash,
  Client,
} from "@evolution-sdk/evolution"

const MNEMONIC = "your twenty-four word mnemonic phrase here"

async function completeWorkflow() {
  // Step 1: Derive sender address (synchronous, no network required)
  const senderAddress = Address.fromSeed(MNEMONIC, { accountIndex: 0, networkId: 0 })
  const senderAddressHex = Address.toHex(senderAddress)

  console.log("Sender address:", Address.toBech32(senderAddress))

  // Step 2: Create genesis configuration with funded address
  const genesisConfig = {
    ...Config.DEFAULT_SHELLEY_GENESIS,
    slotLength: 0.1, // 100ms blocks
    epochLength: 100,
    initialFunds: {
      [senderAddressHex]: 1_000_000_000_000 // 1 million ADA
    }
  }

  // Step 3: Create and start devnet cluster
  const cluster = await Cluster.make({
    clusterName: "integration-example",
    ports: { node: 3001, submit: 3002 },
    shelleyGenesis: genesisConfig,
    kupo: { enabled: true, port: 1442, logLevel: "Info" },
    ogmios: { enabled: true, port: 1337, logLevel: "info" }
  })

  await Cluster.start(cluster)

  // Wait for Kupo and Ogmios to fully initialize
  await new Promise((resolve) => setTimeout(resolve, 8000))

  console.log("Devnet started with Kupo and Ogmios")

  // Step 4: Create client connected to devnet
  const client = Client.make(Cluster.getChain(cluster))
  .withKupmios({ kupoUrl: "http://localhost:1442", ogmiosUrl: "http://localhost:1337" })
  .withSeed({ mnemonic: MNEMONIC, accountIndex: 0 })

  console.log("Client connected to devnet")

  // Step 5: Query protocol parameters
  const params = await client.getProtocolParameters()
  console.log("Protocol parameters:", {
    minFeeA: params.minFeeA,
    minFeeB: params.minFeeB,
    maxTxSize: params.maxTxSize
  })

  // Step 6: Calculate genesis UTxOs (returns Core UTxOs)
  const genesisUtxos = await Genesis.calculateUtxosFromConfig(genesisConfig)

  console.log("Genesis UTxOs:", genesisUtxos.length)
  console.log("Initial balance:", genesisUtxos[0]?.assets.lovelace, "lovelace")

  // Step 7: Build transaction
  const receiverAddress = Address.fromBech32(
    "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgs68faae"
  )

  const signBuilder = await client
    .newTx()
    .payToAddress({
      address: receiverAddress,
      assets: Assets.fromLovelace(10_000_000n) // Send 10 ADA
    })
    .build({ availableUtxos: genesisUtxos })

  const tx = await signBuilder.toTransaction()
  console.log("Transaction built:", {
    inputs: tx.body.inputs.length,
    outputs: tx.body.outputs.length
  })

  // Step 8: Sign transaction
  const submitBuilder = await signBuilder.sign()
  console.log("Transaction signed")

  // Step 9: Submit transaction
  const txHash = await submitBuilder.submit()
  console.log("Transaction submitted:", txHash)

  // Step 10: Wait for confirmation
  const confirmed = await client.awaitTx(txHash, 1000)
  console.log("Transaction confirmed:", confirmed)

  // Step 11: Query final state
  const finalUtxos = await client.getWalletUtxos()
  const totalBalance = finalUtxos.reduce((sum, utxo) => sum + utxo.assets.lovelace, 0n)

  console.log("Final balance:", totalBalance, "lovelace")
  console.log("Fee paid:", genesisUtxos[0]?.assets.lovelace! - totalBalance - 10_000_000n, "lovelace")

  // Step 12: Clean up
  await Cluster.stop(cluster)
  await Cluster.remove(cluster)
  console.log("Devnet stopped and removed")
}

completeWorkflow().catch(console.error)
```

--------------------------------

### Install Evolution SDK Devnet Dependencies

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/getting-started.mdx

Commands to install the required SDK packages and verify the Docker environment prerequisites.

```bash
pnpm add @evolution-sdk/devnet @evolution-sdk/evolution
docker --version
```

--------------------------------

### Install and Build Evolution SDK with pnpm

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/CONTRIBUTING.md

This snippet demonstrates the commands to set up the development environment for the Evolution SDK. It includes cloning the repository, entering the development environment using Nix, installing dependencies with pnpm, building the project, running type checks, and starting the development server.

```bash
git clone https://github.com/your-username/evolution-sdk.git
cd evolution-sdk
nix develop
pnpm install
pnpm turbo build
pnpm turbo type-check
pnpm turbo dev
```

--------------------------------

### Staging Environment Configuration

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/wallets/security.mdx

Configure the staging environment using mainnet settings but with separate, non-production keys. This example shows the `.env.staging` setup.

```bash
# .env.staging
NETWORK=mainnet
MNEMONIC="staging staging staging..."
BLOCKFROST_PROJECT_ID=mainnetxxxxxxxxxxxx
```

--------------------------------

### Comprehensive Devnet Configuration Example

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/configuration.mdx

A complete example combining fast block production, custom protocol parameters, multiple funded addresses, and enabled services like Kupo and Ogmios for thorough integration testing.

```typescript
import {
  Cluster,
  Config,
  Genesis } from "@evolution-sdk/devnet"
import { Address,
  TransactionHash,
} from "@evolution-sdk/evolution"

// Generate funded addresses (synchronous, no network required)
const addr1 = Address.toHex(Address.fromSeed("test wallet one mnemonic here", {
  accountIndex: 0,
  networkId: 0
}))

const addr2 = Address.toHex(Address.fromSeed("test wallet two mnemonic here", {
  accountIndex: 0,
  networkId: 0
}))

// Custom genesis configuration
const genesisConfig = {
  ...Config.DEFAULT_SHELLEY_GENESIS,

  // Fast block production
  slotLength: 0.05, // 50ms slots
  epochLength: 200, // 200 slots (10 seconds) per epoch
  activeSlotsCoeff: 1.0, // Every slot produces a block

  // Fund multiple addresses
  initialFunds: {
    [addr1]: 5_000_000_000_000, // 5M ADA for primary testing
    [addr2]: 1_000_000_000_000 // 1M ADA for secondary scenarios
  },

  // Custom protocol parameters
  protocolParams: {
    ...Config.DEFAULT_SHELLEY_GENESIS.protocolParams,
    minFeeA: 40, // Lower fees for testing
    minFeeB: 150000,
    maxTxSize: 32768, // Larger transactions allowed
    maxBlockBodySize: 131072 // Larger blocks for throughput
  },

  // Faster key evolution for staking tests
  maxKESEvolutions: 60,
  slotsPerKESPeriod: 3600
} satisfies Config.ShelleyGenesis

// Create cluster with full services
const cluster = await Cluster.make({
  clusterName: "comprehensive-devnet",
  ports: { node: 3001, submit: 3002 },
  shelleyGenesis: genesisConfig,
  kupo: {
    enabled: true,
    port: 1442,
    logLevel: "Info"
  },
  ogmios: {
    enabled: true,
    port: 1337,
    logLevel: "info"
  }
})

// Start the devnet
await Cluster.start(cluster)

console.log("Comprehensive devnet ready:")
console.log("- Two funded addresses")
console.log("- 50ms block time")
console.log("- Custom protocol parameters")
console.log("- Kupo and Ogmios enabled")

// Calculate and verify genesis UTxOs
const utxos = await Genesis.calculateUtxosFromConfig(genesisConfig)
console.log(`\nGenesis UTxOs: ${utxos.length}`)
utxos.forEach((utxo, i) => {
  console.log(`  Address ${i + 1}: ${utxo.assets.lovelace} lovelace`)
})
```

--------------------------------

### Start Development Server

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/README.md

Start the development server using pnpm turbo. This command is used for active development.

```bash
pnpm turbo dev
```

--------------------------------

### Install Evolution SDK

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/README.md

Installs the Evolution SDK package using npm.

```bash
npm install @evolution-sdk/evolution
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/README.md

Clone the Evolution SDK repository, navigate into the directory, and install project dependencies using pnpm. Nix is recommended for development.

```bash
git clone https://github.com/no-witness-labs/evolution-sdk.git
cd evolution-sdk
nix develop
pnpm install
```

--------------------------------

### Run Development Server

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/README.md

Commands to start the development server using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Install with pnpm

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/introduction/installation.mdx

Use pnpm to install the Evolution SDK. pnpm is a performant package manager that saves disk space and speeds up installations.

```bash
pnpm add @evolution-sdk/evolution
```

--------------------------------

### Install with yarn

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/introduction/installation.mdx

Use yarn to install the Evolution SDK. Yarn is an alternative package manager for Node.js.

```bash
yarn add @evolution-sdk/evolution
```

--------------------------------

### Start and Query Devnet with Provider Client

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/integration.mdx

Use this snippet to start a local devnet, configure Kupo and Ogmios, and perform provider-only queries for UTxOs and protocol parameters. Ensure Kupo and Ogmios are enabled in the cluster configuration.

```typescript
import {
  Cluster,
  Config,
  Genesis } from "@evolution-sdk/devnet"
import { Address,
  Assets,
  TransactionHash,
  Client,
} from "@evolution-sdk/evolution"

// Start devnet with funded address
const cluster = await Cluster.make({
  clusterName: "query-example",
  ports: { node: 3001, submit: 3002 },
  shelleyGenesis: {
    ...Config.DEFAULT_SHELLEY_GENESIS,
    initialFunds: {
      address_hex_here: 100_000_000_000
    }
  },
  kupo: { enabled: true, port: 1442 },
  ogmios: { enabled: true, port: 1337 }
})

await Cluster.start(cluster)
await new Promise((resolve) => setTimeout(resolve, 6000))

// Provider-only client (no wallet configured)
const providerClient = Client.make(Cluster.getChain(cluster))
  .withKupmios({ kupoUrl: "http://localhost:1442", ogmiosUrl: "http://localhost:1337" })

// Query any address on the devnet
const utxos = await providerClient.getUtxos(
  Address.fromBech32(
    "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgs68faae"
  )
)
console.log("UTxOs at address:", utxos.length)

// Query protocol parameters
const params = await providerClient.getProtocolParameters()
console.log("Max transaction size:", params.maxTxSize)

await Cluster.stop(cluster)
await Cluster.remove(cluster)
```

--------------------------------

### Clone Repository

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/README.md

Clone the Evolution SDK repository to start development. Ensure you have Git installed.

```bash
git clone https://github.com/IntersectMBO/evolution-sdk.git
cd evolution-sdk
```

--------------------------------

### Install Dependencies

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/README.md

Install project dependencies using pnpm. Ensure Node.js and pnpm are installed.

```bash
pnpm install
```

--------------------------------

### Development Environment Configuration

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/wallets/security.mdx

Configure the development environment using test networks (like preprod) and specific test mnemonics. This example shows the `.env.development` setup and corresponding TypeScript configuration.

```typescript
// Example server-side provider + wallet configs. Instantiate the client in your
// backend code (see /docs/clients for client creation examples).

const providerConfig = {
  network: process.env.NETWORK as "preprod" | "mainnet",
  provider: {
    baseUrl: process.env.NETWORK === "preprod"
      ? "https://cardano-preprod.blockfrost.io/api/v0"
      : "https://cardano-mainnet.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_PROJECT_ID!
  }
};

const walletConfig = { mnemonic: process.env.MNEMONIC! };
```

```bash
# .env.development
NETWORK=preprod
MNEMONIC="develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop develop art"
BLOCKFROST_PROJECT_ID=preprodxxxxxxxxxxxx
```

--------------------------------

### Start Local Devnet Emulator

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/testing/emulator.mdx

Initializes and starts a local devnet emulator with custom configurations for ports, genesis settings, and Kupo/Ogmios services. Ensure to stop and remove the cluster when testing is complete.

```typescript
import { Cluster, Config } from "@evolution-sdk/devnet"

const cluster = await Cluster.make({
  clusterName: "my-emulator",
  ports: { node: 3001, submit: 3002 },
  shelleyGenesis: {
    ...Config.DEFAULT_SHELLEY_GENESIS,
    slotLength: 0.1,
    initialFunds: {
      "your_address_hex": 1_000_000_000_000
    }
  },
  kupo: { enabled: true, port: 1442 },
  ogmios: { enabled: true, port: 1337 }
})

await Cluster.start(cluster)
// ... run tests ...
await Cluster.stop(cluster)
await Cluster.remove(cluster)
```

--------------------------------

### Install Evolution SDK

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/packages/evolution/README.md

Commands to install the Evolution SDK package using common Node.js package managers.

```bash
pnpm add @evolution-sdk/evolution

# Or use npm
npm install @evolution-sdk/evolution

# Or use yarn
yarn add @evolution-sdk/evolution
```

--------------------------------

### Install @evolution-sdk/devnet

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/packages/evolution-devnet/README.md

Installs the necessary development dependencies for the local Cardano network using pnpm.

```bash
pnpm add -D @evolution-sdk/devnet @evolution-sdk/evolution
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/index.mdx

Run this command in your terminal to verify that Docker is installed and accessible.

```bash
docker --version
```

--------------------------------

### Credential Examples: Wallet and Script

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/encoding/plutus.mdx

Illustrates the creation of Credential types for both wallet ownership (VerificationKey) and smart contract references (Script).

```typescript
import { Credential } from "@evolution-sdk/evolution/plutus"
import { Bytes, Data } from "@evolution-sdk/evolution"

// Wallet credential
const walletCred: Credential.Credential = {
  VerificationKey: {
    hash: Bytes.fromHex("abc123def456abc123def456abc123def456abc123def456abc123de")
  }
}

// Smart contract credential
const scriptCred: Credential.Credential = {
  Script: {
    hash: Bytes.fromHex("def456abc123def456abc123def456abc123def456abc123def456ab")
  }
}
```

--------------------------------

### Quick Start: Using Credential Type

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/encoding/plutus.mdx

Demonstrates how to import and use the pre-built Credential type from @evolution-sdk/evolution/plutus and encode it to CBOR hex.

```typescript
import { Credential } from "@evolution-sdk/evolution/plutus"
import { Bytes, Data } from "@evolution-sdk/evolution"

// Use pre-built Credential type
const cred: Credential.Credential = {
  VerificationKey: {
    hash: Bytes.fromHex("abc123def456abc123def456abc123def456abc123def456abc123de")
  }
}

// Encode to CBOR
const cbor = Credential.CredentialCodec.toCBORHex(cred)
```

--------------------------------

### Client Configuration Examples

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/clients/index.mdx

Demonstrates how to configure different client types by chaining .withX() methods. Add a provider first for blockchain reads or submission. Use .withAddress() for wallet context only. Use signing methods like .withSeed() or .withPrivateKey() for transaction signing.

```typescript
const readClient = client(preprod).withBlockfrost({ ... })
const addressClient = client(preprod).withAddress("addr_test1...")
const signingClient = client(preprod).withBlockfrost({ ... }).withSeed({ ... })
```

--------------------------------

### Evolution SDK Integration Example

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/examples/with-vite-react/README.md

Demonstrates how to initialize the Evolution SDK client, connect a CIP-30 wallet, and build/submit a transaction to pay an address.

```typescript
import { client, preprod } from "@evolution-sdk/evolution";

// Create a staged client with provider and CIP-30 wallet access
const sdk = client(preprod)
  .withBlockfrost({
    baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
    projectId: "your_project_id"
  })
  .withCip30(walletApi);

// Build and submit transaction
const txHash = await sdk
  .newTx()
  .payToAddress({
    address: recipientAddress,
    assets: { lovelace: 5_000_000n }
  })
  .build()
  .then(tx => tx.sign())
  .then(tx => tx.submit());
```

--------------------------------

### Create and Manage Cardano Devnet Clusters

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/getting-started.mdx

Demonstrates the lifecycle operations for a Cardano devnet cluster including creation, starting, monitoring status, and cleanup using TypeScript.

```typescript
import { Cluster, Container } from "@evolution-sdk/devnet";

// Create a basic devnet cluster
const cluster = await Cluster.make({
  clusterName: "my-first-devnet",
  ports: { node: 3001, submit: 3002 }
});

// Start the cluster
await Cluster.start(cluster);

// Check status
const status = await Container.getStatus(cluster.cardanoNode);

// Stop and remove
await Cluster.stop(cluster);
await Cluster.remove(cluster);
```

--------------------------------

### Basic Provider-Only Client Setup and Query

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/providers/provider-only-client.mdx

Demonstrates how to initialize a provider-only client with Blockfrost and query UTxOs for a given address. Ensure your BLOCKFROST_PROJECT_ID environment variable is set.

```typescript
import {
  Address,
  Assets,
  Bytes,
  DatumHash,
  RewardAddress,
  Transaction,
  TransactionHash,
  TransactionInput,
  mainnet,
  Client,
} from "@evolution-sdk/evolution"

const client = Client.make(mainnet)
  .withBlockfrost({
    baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_PROJECT_ID!
  })

// Query any address
const utxos = await client.getUtxos(
  Address.fromBech32(
    "addr1qxy8sclc58rsck0pzsc0v4skmqjwuqsqpwfcvrdldl5sjvvhyltp7fk0fmtmrlnykgmhnzcns2msa2cmpvllzgqd2azqhpv8e4"
  )
)
console.log("Found UTxOs:", utxos.length)

// Get protocol parameters
const params = await client.getProtocolParameters()
console.log("Min fee A:", params.minFeeA)
```

--------------------------------

### Set up Wallet Client for Testing

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/wallets/seed-phrase.mdx

Initializes a wallet client using a mnemonic from environment variables for testing on preprod networks. Ensure the TEST_WALLET_MNEMONIC environment variable is set.

```typescript
import { PrivateKey, preprod, Client } from "@evolution-sdk/evolution"

// Mock test runner functions for documentation
declare function describe(name: string, fn: () => void): void
declare function beforeEach(fn: () => void): void
declare function it(name: string, fn: () => void | Promise<void>): void
declare const expect: any

// Mock environment variable
declare const process: { env: { TEST_WALLET_MNEMONIC?: string } }

describe("Payment tests", () => {
  let client: any

  beforeEach(() => {
    client = Client.make(preprod)
      .withSeed({
        mnemonic: process.env.TEST_WALLET_MNEMONIC!,
        accountIndex: 0
      })
  })

  it("should sign transaction", async () => {
    // Wallet client can sign but needs provider to build/submit
    // For full flow, add a provider: client.withBlockfrost(...)
    const address = await client.address()
    expect(address).toBeDefined()
  })
})
```

--------------------------------

### Retrieve Secret from Azure Key Vault

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/wallets/private-key.mdx

This example demonstrates retrieving secrets from Azure Key Vault. It requires the Azure SDK and proper authentication setup.

```typescript
import { mainnet, Client } from "@evolution-sdk/evolution"

// Mock Azure SDK classes for documentation
declare class DefaultAzureCredential {}

declare class SecretClient {
  constructor(vaultUrl: string, credential: any)
  getSecret(name: string): Promise<{ value?: string }>
}

const credential = new DefaultAzureCredential()
const vaultUrl = "https://your-vault.vault.azure.net"
const secretClient = new SecretClient(vaultUrl, credential)

async function createProductionClient() {
  // Retrieve secret
  const secret = await secretClient.getSecret("cardano-payment-key")

  return Client.make(mainnet)
    .withPrivateKey({
      paymentKey: secret.value!
    })
}
```

--------------------------------

### Switching Between Providers

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/providers/provider-types.mdx

Demonstrates how to initialize clients for different networks and providers, such as Blockfrost for development and Kupmios for production. The same query methods are applicable across all providers.

```typescript
import { preprod, mainnet, Client } from "@evolution-sdk/evolution"

// Development: Blockfrost
const devClient = Client.make(preprod)
  .withBlockfrost({
    baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_PROJECT_ID!
  })

// Production: Self-hosted Kupmios
const prodClient = Client.make(mainnet)
  .withKupmios({
    ogmiosUrl: process.env.OGMIOS_URL!,
    kupoUrl: process.env.KUPO_URL!
  })

// Same query methods work across all providers
const params = await devClient.getProtocolParameters()
```

--------------------------------

### Start and Manage Local Devnet Cluster

Source: https://context7.com/intersectmbo/evolution-sdk/llms.txt

Initialize and manage a local Cardano development network using Docker containers for Kupo and Ogmios. Ensure Docker is installed and running.

```typescript
import { Cluster, Container } from "@evolution-sdk/devnet"

// Create cluster with Kupo and Ogmios
const cluster = await Cluster.make({
  clusterName: "my-devnet",
  ports: { node: 3001, submit: 3002 },
  kupo: { enabled: true, port: 1442, logLevel: "Info" },
  ogmios: { enabled: true, port: 1337, logLevel: "info" }
})

// Start all containers
await Cluster.start(cluster)
console.log("Devnet started")

// Wait for initialization
await new Promise(resolve => setTimeout(resolve, 5000))

// Check container status
const nodeStatus = await Container.getStatus(cluster.cardanoNode)
console.log("Node status:", nodeStatus?.State.Status)  // "running"

// Your development work here
console.log("Ogmios: http://localhost:1337")
console.log("Kupo: http://localhost:1442")

// Clean up
await Cluster.stop(cluster)
await Cluster.remove(cluster)
```

--------------------------------

### Configure Devnet with Kupo and Ogmios

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/getting-started.mdx

Shows how to extend a devnet cluster by enabling Kupo for UTxO indexing and Ogmios for JSON-RPC/WebSocket API access.

```typescript
import { Cluster, Container } from "@evolution-sdk/devnet";

const cluster = await Cluster.make({
  clusterName: "full-stack-devnet",
  ports: { node: 3001, submit: 3002 },
  kupo: { enabled: true, port: 1442, logLevel: "Info" },
  ogmios: { enabled: true, port: 1337, logLevel: "info" }
});

await Cluster.start(cluster);
```

--------------------------------

### Create and Start Devnet Cluster

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/index.mdx

Use this snippet to create a devnet cluster with custom genesis parameters, including initial funds and slot length. Ensure Docker is running and Node.js version 18 or higher is installed.

```typescript
import { Cluster } from "@evolution-sdk/devnet";

// Create cluster with custom genesis
const cluster = await Cluster.make({
  clusterName: "my-devnet",
  ports: { node: 3001, submit: 3002 },
  shelleyGenesis: {
    slotLength: 0.1, // 100ms blocks
    initialFunds: {
      "addr_test1_hex_address": 1_000_000_000_000 // 1M ADA
    }
  }
});

// Start the network
await Cluster.start(cluster);

// Network is ready for transactions
console.log("Devnet running on port", 3001);

// Cleanup when done
await Cluster.stop(cluster);
await Cluster.remove(cluster);
```

--------------------------------

### Troubleshooting Devnet Port Conflicts

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/getting-started.mdx

Illustrates how to resolve port conflicts when setting up a devnet cluster by specifying alternative ports for the node and submit services. This is a common issue when other applications are already using the default ports.

```typescript
ports: { node: 4001, submit: 4002 }
```

--------------------------------

### Complete Transaction Workflow

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/transactions/first-transaction.mdx

This example shows the entire process of configuring a client, building, signing, and submitting a payment transaction. Ensure your environment variables for Blockfrost API key and wallet mnemonic are set.

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

// 1. Configure your client
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
  })

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

// 3. Sign with your wallet
const signed = await tx.sign()

// 4. Submit to network
const txHash = await signed.submit()
console.log("Transaction submitted:", txHash)
```

--------------------------------

### Control Individual Containers in Devnet Cluster

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/getting-started.mdx

Demonstrates how to stop, check the status of, and restart a specific container (cardano-node) within a devnet cluster. This allows for granular testing of failure scenarios. It relies on the '@evolution-sdk/devnet' library.

```typescript
import { Cluster, Container } from "@evolution-sdk/devnet";
const cluster = await Cluster.make()

// Stop just the cardano-node
await Container.stop(cluster.cardanoNode);

console.log("Node stopped, Kupo and Ogmios still running");

// Check stopped status
const stoppedStatus = await Container.getStatus(cluster.cardanoNode);
console.log("Status:", stoppedStatus?.State.Status); // "exited"

// Restart the node
await Container.start(cluster.cardanoNode);

await new Promise(resolve => setTimeout(resolve, 2000));

// Verify running again
const runningStatus = await Container.getStatus(cluster.cardanoNode);
console.log("Status:", runningStatus?.State.Status); // "running"
```

--------------------------------

### Initialize Kupo/Ogmios Client

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/advanced/custom-providers.mdx

Shows how to initialize a client with the Kupo and Ogmios providers, specifying their respective URLs. This is useful for self-hosted or development environments.

```typescript
// Kupo/Ogmios
const kupmiosClient = Client.make(preprod)
  .withKupmios({
    kupoUrl: "http://localhost:1442",
    ogmiosUrl: "http://localhost:1337"
  })
```

--------------------------------

### Query UTxOs, Delegation Status, and Protocol Parameters

Source: https://context7.com/intersectmbo/evolution-sdk/llms.txt

This example shows how to query unspent transaction outputs (UTxOs) for a wallet or a specific address, filter UTxOs by asset, retrieve protocol parameters, and wait for transaction confirmation. Ensure Blockfrost and wallet mnemonic are configured.

```typescript
import { Address, 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 })

// Query wallet UTxOs
const walletUtxos = await client.getWalletUtxos()
console.log("Wallet has", walletUtxos.length, "UTxOs")

// Query specific address
const addr = Address.fromBech32("addr_test1vrm9x2dgvdau8vckj4duc89m638t8djmluqw5pdrFollw8qd9k63")
const addressUtxos = await client.getUtxos(addr)

// Query UTxOs containing a specific asset
const assetUnit = "7edb7a2d9fbc4d2a68e4c9e9d3d7a5c8f2d1e9f8a7b6c5d4e3f2a1b0c9d8e7f6"
const assetUtxos = await client.getUtxosWithUnit(addr, assetUnit)

// Get protocol parameters
const params = await client.getProtocolParameters()
console.log("Min fee coefficient:", params.minFeeCoefficient)

// Wait for transaction confirmation
const confirmed = await client.awaitTx(txHash, { timeout: 60000 })
console.log("Transaction confirmed:", confirmed)
```

--------------------------------

### Preview Production Build

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/examples/with-vite-react/README.md

Preview the production build of the application using pnpm.

```bash
pnpm preview
```

--------------------------------

### Plutus V2 Language View Example (Hex)

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/CostModel.mdx

Example of the script_integrity_data for an all-zero costmodel for Plutus V2, encoded as a hex string.

```plaintext
98af0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
```

--------------------------------

### Plutus V1 Language View Example (Hex)

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/CostModel.mdx

Example of the script_integrity_data for an all-zero costmodel for Plutus V1, encoded as a hex string.

```plaintext
58a89f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000ff
```

--------------------------------

### Create a Wallet Client

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/introduction/getting-started.mdx

Instantiate a client with a preprod network configuration and attach a wallet using a seed phrase. Ensure you have a Cardano testnet wallet with tADA.

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

const client = Client.make(preprod)
  .withSeed({
    mnemonic: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    accountIndex: 0
  })
```

--------------------------------

### Client Assembly and Initialization

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/sdk/client/Client.mdx

This section covers the construction of a client assembly, which is the initial stage for creating a chain-scoped client. It also details how to attach various data providers and wallet capabilities to this assembly.

```APIDOC
## Client Assembly

### Description
The `ClientAssembly` interface represents a stage in client construction, scoped to a specific blockchain chain. It provides methods to attach different data providers and wallet functionalities.

### Methods
- `withBlockfrost(config: BlockfrostConfig): ReadClient`
- `withKoios(config: KoiosConfig): ReadClient`
- `withKupmios(config: KupmiosConfig): ReadClient`
- `withMaestro(config: MaestroConfig): ReadClient`
- `withAddress(address: string, rewardAddress?: string): AddressClient`
- `withSeed(config: SeedWalletConfig): OfflineSignerClient`
- `withPrivateKey(config: PrivateKeyWalletConfig): OfflineSignerClient`
- `withCip30(api: Wallet.WalletApi): OfflineSignerClient`

### Endpoint
N/A (This is a client-side SDK construction method)

## make

### Description
Constructs a chain-scoped client assembly stage. This is the entry point for building a client instance.

### Method
`make(chain?: Chain): ClientAssembly`

### Endpoint
N/A (This is a client-side SDK construction method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```typescript
const assembly = make(Chain.Testnet)
```

### Response
Returns a `ClientAssembly` object.

#### Success Response (200)
N/A (This is a client-side SDK construction method)

#### Response Example
N/A
```

--------------------------------

### Build for Production

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/examples/with-vite-react/README.md

Build the application for production using pnpm.

```bash
pnpm build
```

--------------------------------

### Quick Test Configuration

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/integration.mdx

Use this configuration for rapid testing with fast block times and a high initial balance for a single wallet.

```typescript
{
  slotLength: 0.02,
  epochLength: 50,
  initialFunds: { [addr]: 10_000_000_000_000 }
}
```

--------------------------------

### Start Long-Running Development Sessions with Devnet

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/devnet/integration.mdx

Use this script to start a persistent devnet for manual testing, dApp development, or interactive exploration. The devnet remains active until manually stopped with Ctrl+C.

```typescript
import { Cluster, Config, Genesis } from "@evolution-sdk/devnet"

async function startDevSession() {
  const cluster = await Cluster.make({
    clusterName: "dev-session",
    ports: { node: 3001, submit: 3002 },
    shelleyGenesis: {
      ...Config.DEFAULT_SHELLEY_GENESIS,
      slotLength: 0.1,
      initialFunds: {
        your_address_hex_here: 1_000_000_000_000
      }
    },
    kupo: { enabled: true, port: 1442, logLevel: "Info" },
    ogmios: { enabled: true, port: 1337, logLevel: "info" }
  })

  await Cluster.start(cluster)

  console.log("\n✓ Devnet running")
  console.log("  Ogmios: http://localhost:1337")
  console.log("  Kupo: http://localhost:1442")
  console.log("  Node: localhost:3001")
  console.log("\nPress Ctrl+C to stop\n")

  // Graceful shutdown
  process.on("SIGINT", async () => {
    console.log("\nStopping devnet...")
    await Cluster.stop(cluster)
    await Cluster.remove(cluster)
    console.log("✓ Devnet stopped\n")
    process.exit(0)
  })

  // Keep process alive
  await new Promise(() => {})
}

startDevSession().catch(console.error)

```

--------------------------------

### Initialize Blockfrost Client

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/advanced/custom-providers.mdx

Demonstrates how to initialize a client with the Blockfrost provider using its base URL and project ID. Ensure the BLOCKFROST_API_KEY is set in your environment variables.

```typescript
import { preprod, Client } from "@evolution-sdk/evolution"

// Blockfrost
const blockfrostClient = Client.make(preprod)
  .withBlockfrost({
    baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
    projectId: process.env.BLOCKFROST_API_KEY!
  })
```

--------------------------------

### Set Transaction Start Time Only

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/time/validity-ranges.mdx

Sets only the start time for a transaction, useful for time-locked scripts where the transaction should only become valid after a specific point in time. The 'from' field specifies the Unix timestamp in milliseconds.

```typescript
.setValidity({ from: now })
```

--------------------------------

### Environment Configuration for Providers

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/clients/providers.mdx

Example of setting up environment variables for Blockfrost API key and Kupmios URLs. The code dynamically selects the provider based on the presence of the Blockfrost API key.

```bash
# .env.local
BLOCKFROST_API_KEY=your_key_here
KUPO_URL=http://localhost:1442
OGMIOS_URL=http://localhost:1337
```

```typescript
import { preprod, Client } from "@evolution-sdk/evolution"

const client = process.env.BLOCKFROST_API_KEY
  ? 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
      })
  : Client.make(preprod)
      .withKupmios({
        kupoUrl: process.env.KUPO_URL!,
        ogmiosUrl: process.env.OGMIOS_URL!
      })
      .withSeed({
        mnemonic: process.env.WALLET_MNEMONIC!,
        accountIndex: 0
      })
```

--------------------------------

### Complete Transaction Workflow

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/clients/client-basics.mdx

This example demonstrates the full transaction lifecycle: client creation, transaction building, signing, and submission. It uses environment variables for sensitive information like API keys and mnemonics. Ensure all necessary environment variables are correctly set.

```typescript
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
  })

// Build transaction
const builder = client.newTx()
builder.payToAddress({
  address: Address.fromBech32(
    "addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y"
  ),
  assets: Assets.fromLovelace(2000000n)
})

// Build, sign, and submit
const signBuilder = await builder.build()
const submitBuilder = await signBuilder.sign()
const txId = await submitBuilder.submit()

console.log("Transaction ID:", txId)
```

--------------------------------

### now Function

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/UnixTime.mdx

Gets the current UnixTime (milliseconds since epoch).

```APIDOC
## now Function

### Description
Get current UnixTime.

### Signature
```ts
export declare const now: () => UnixTime
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **UnixTime** (bigint) - The current Unix timestamp in milliseconds.

### Response Example
None
```

--------------------------------

### Get Custom Header

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/cose/Header.mdx

Retrieves a custom header by its label. Added in v2.0.0.

```typescript
header(label: Label): CBOR.CBOR | undefined
```

--------------------------------

### Create an Evolution SDK Client

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/clients/client-basics.mdx

Configure the client with the network, blockchain provider (e.g., Blockfrost), and wallet (e.g., using a seed phrase). Ensure necessary environment variables like BLOCKFROST_API_KEY are set.

```typescript
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: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    accountIndex: 0
  })
```

--------------------------------

### Get Current UnixTime

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/UnixTime.mdx

Retrieves the current UnixTime in milliseconds since epoch.

```typescript
export declare const now: () => UnixTime
```

--------------------------------

### Configure Clients for Environment Separation

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/wallets/private-key.mdx

This example shows how to configure separate Evolution SDK clients for different environments (development, staging, production) using distinct keys loaded from a vault.

```typescript
import { preprod, mainnet, Client } from "@evolution-sdk/evolution"

// Development
const devClient = Client.make(preprod)
  .withPrivateKey({
    paymentKey: await loadFromVault("dev/cardano-payment-key")
  })

// Staging
const stagingClient = Client.make(preprod)
  .withPrivateKey({
    paymentKey: await loadFromVault("staging/cardano-payment-key") // Different key
  })

// Production
const prodClient = Client.make(mainnet)
  .withPrivateKey({
    paymentKey: await loadFromVault("prod/cardano-payment-key") // Different key
  })

declare function loadFromVault(id: string): Promise<string>
```

--------------------------------

### Get Port from SingleHostName

Source: https://github.com/intersectmbo/evolution-sdk/blob/main/docs/content/docs/modules/SingleHostName.mdx

Retrieves the port number from a SingleHostName object, if it is present.

```APIDOC
## getPort

Get the port from a SingleHostName, if it exists.

### Signature

```ts
export declare const getPort: (hostName: SingleHostName) => Port.Port | undefined
```

Added in v2.0.0
```