# Branding
URL: /about/branding

Download official Mesh logos and assets for your projects, presentations, and integrations.

***

title: "Branding"
description: "Download official Mesh logos and assets for your projects, presentations, and integrations."
----------------------------------------------------------------------------------------------------------

import Link from "next/link";
import Image from "next/image";

Use the official Mesh brand assets when you reference Mesh in your application, documentation, or marketing materials. This page provides all logo variations and guidelines for proper usage.

## Logo Downloads

Download the Mesh logo in your preferred format and color scheme. Use SVG files for web applications where possible, as they scale to any size without quality loss.

### Standard Logos

Choose between black and white versions depending on your background color.

<Cards className="mb-16 mt-10">
  <Card>
    <Image src="/logo-mesh/black/logo-mesh-black-512x512.png" width={500} height={250} alt="mesh-black-512" className="bg-white rounded" />

    <div className="flex flex-col items-center gap-2">
      <div className="font-bold text-lg">Download black logo:</div>

      <div className="flex flex-wrap justify-center items-center gap-2">
        <Link href={`/logo-mesh/black/logo-mesh-vector.svg`} className="text-blue-500 no-underline hover:underline leading-none">
          SVG
        </Link>

        {["16x16", "32x32", "64x64", "128x128", "256x256", "512x512"].map((size) => (
                  <Link
                    key={size}
                    href={`/logo-mesh/black/logo-mesh-black-${size}.png`}
                    target="_blank"
                    className="text-blue-500 no-underline hover:underline leading-none"
                  >
                    {size}
                  </Link>
                ))}
      </div>
    </div>
  </Card>

  <Card>
    <Image src="/logo-mesh/white/logo-mesh-white-512x512.png" width={500} height={250} alt="mesh-white-512" className="bg-black rounded" />

    <div className="flex flex-col items-center gap-2">
      <div className="font-bold text-lg">Download white logo:</div>

      <div className="flex flex-wrap justify-center items-center gap-2">
        <Link href={`/logo-mesh/white/logo-mesh-vector.svg`} className="text-blue-500 no-underline hover:underline leading-none">
          SVG
        </Link>

        {["16x16", "32x32", "64x64", "128x128", "256x256", "512x512"].map((size) => (
                  <Link
                    key={size}
                    href={`/logo-mesh/white/logo-mesh-white-${size}.png`}
                    target="_blank"
                    className="text-blue-500 no-underline hover:underline leading-none"
                  >
                    {size}
                  </Link>
                ))}
      </div>
    </div>
  </Card>
</Cards>

### Logos with Title

Use these versions when you need the Mesh name alongside the logo.

<Cards className="mb-16">
  <Card>
    <Image src="/logo-mesh/meshlogo-with-title-black.svg" width={500} height={250} alt="mesh-black-title-512" className="bg-white rounded mb-0" />

    <div className="flex items-center justify-center gap-2 font-bold text-lg">
      <div>Download black logo with title:</div>

      <Link href={`/logo-mesh/meshlogo-with-title-black.svg`} className="text-blue-500 no-underline hover:underline">
        SVG
      </Link>
    </div>
  </Card>

  <Card>
    <Image src="/logo-mesh/meshlogo-with-title-white.svg" width={500} height={250} alt="mesh-white-title-512" className="bg-black rounded mb-0" />

    <div className="flex items-center justify-center gap-2 font-bold text-lg leading-none">
      <span>Download white logo with title:</span>

      <Link href={`/logo-mesh/meshlogo-with-title-white.svg`} className="text-blue-500 no-underline hover:underline">
        SVG
      </Link>
    </div>
  </Card>
</Cards>

### Logo with Background

Use this version for social media profiles or when you need a standalone image with built-in contrast.

<Cards>
  <Card>
    <Image src="/logo-mesh/mesh.png" width={500} height={250} alt="mesh-background" className="rounded mb-0" />

    <div className="flex items-center justify-center gap-2 font-bold text-lg leading-none">
      <span>Download logo with background:</span>

      <Link href={`/logo-mesh/mesh.png`} className="text-blue-500 no-underline hover:underline">
        <p>PNG</p>
      </Link>
    </div>
  </Card>
</Cards>

## Available Formats

| Format | Best For                | Sizes Available   |
| ------ | ----------------------- | ----------------- |
| SVG    | Web, print, any scale   | Vector (scalable) |
| PNG    | Social media, documents | 16x16 to 512x512  |

## Usage Guidelines

When using Mesh branding:

* **Maintain aspect ratio** - Do not stretch or distort the logo
* **Ensure contrast** - Use the black logo on light backgrounds and white logo on dark backgrounds
* **Provide spacing** - Leave adequate clear space around the logo
* **No modifications** - Do not alter colors, add effects, or combine with other graphics

## Related Resources

* [Support Us](/about/support-us) - Ways to contribute to the Mesh project
* [Project Catalyst](/about/catalyst) - Our funded proposals and development roadmap


# About Mesh SDK for Cardano
URL: /about

Mesh is an open-source, production-ready TypeScript SDK for Cardano blockchain development. Transaction builders, wallet integrations, and data services for building dApps. Built and maintained by an active community of builders.

***

title: "About Mesh SDK for Cardano"
description: "Mesh is an open-source, production-ready TypeScript SDK for Cardano blockchain development. Transaction builders, wallet integrations, and data services for building dApps. Built and maintained by an active community of builders."
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

import Image from 'next/image';
import Link from 'fumadocs-core/link';
import {
  SiDiscord,
  SiX,
  SiGithub
} from "@icons-pack/react-simple-icons";
import { GlobeAltIcon } from '@heroicons/react/24/outline';
import {team} from "@/data/team";
import { cn } from "@/lib/cn";
import { buttonVariants } from "@/components/ui/button";

<h1 className="text-center text-4xl mt-4">Mesh Builder Community</h1>

<div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-y-10 mb-32">
  {
      team.map((member) => (
        <div
        className="flex flex-col items-center justify-center"
        key={member.name}
        >
          <Image
            src={`/team/${member.image}`}
            alt={member.name}
            width={150}
            height={150}
            className="rounded-full object-cover"
            loading="lazy"
          />
          <h1 className='text-center'>{member.name}</h1>
          <div className='flex gap-5 items-center justify-center'>
            {member.twitter && <Link href={member.twitter}><SiX className="w-5 h-5 text-foreground"/></Link>}
            {member.linkedin && (
              <Link href={member.linkedin}>
                <svg className="w-5 h-5 text-foreground" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
                  <path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z"/>
                </svg>
              </Link>
            )}
            <Link href={member.github}><SiGithub className="w-6 h-6 text-foreground"/></Link>
          </div>
        </div>
      ))
  }
</div>

<div className="flex justify-center mb-32">
  <Link href="https://gov.meshjs.dev/contributors" className={cn(buttonVariants({ color: 'primary' }), 'rounded-lg px-6 py-2 text-sm font-semibold no-underline')}>
    All Contributors
  </Link>
</div>

<div className="text-center mb-32">
  <h1 className="text-4xl">What are we working on?</h1>
  <p className="text-xl">Check our <Link href="https://github.com/orgs/MeshJS/repositories">GitHub repositories</Link> to see what we are currently working on.</p>
</div>

<div className="text-center mb-32">
  <h1 className="text-4xl">Incorporation</h1>
  <p className="text-xl">MeshJS Pte. Ltd. is a company registered in Singapore since 2023, with the registration number (UEN): 202344120W.</p>
</div>

<div className="text-center mb-32">
  <h1 className="text-4xl">Ecosystem</h1>
  <p className="text-xl">Mesh SDK is built for the <Link href="https://developers.cardano.org">Cardano blockchain</Link>, implementing key standards including <Link href="https://cips.cardano.org/cip/CIP-0030">CIP-30</Link> (wallet connectivity), <Link href="https://cips.cardano.org/cip/CIP-0025">CIP-25</Link> (NFT metadata), and <Link href="https://cips.cardano.org/cip/CIP-0095">CIP-95</Link> (governance). Learn more about Cardano's <Link href="https://docs.cardano.org/about-cardano/learn/eutxo-explainer/">eUTXO model</Link>.</p>
</div>

<div className="flex flex-col gap-4 text-center mb-10">
  <div>
    <h1 className="text-4xl">Status</h1>
    <p className="text-xl">Stay up to date with our latest releases, tests and build status.</p>
  </div>

  <div className="grid gap-8 sm:gap-12 md:grid-cols-3">
    <div className="flex justify-center">
      <div>
        <h3 className="mb-1 text-xl font-bold leading-tigh">
          Published on NPM
        </h3>

        <Link href="https://www.npmjs.com/package/@meshsdk/core">
          <img src="https://img.shields.io/npm/v/%40meshsdk%2Fcore?style=for-the-badge" />
        </Link>
      </div>
    </div>

    <div className="flex justify-center">
      <div>
        <h3 className="mb-1 text-xl font-bold leading-tigh">
          Build status
        </h3>

        <Link href="https://github.com/meshjs/mesh/actions/workflows/build.yml">
          <img className="h-7" src="https://github.com/meshjs/mesh/actions/workflows/build.yml/badge.svg" />
        </Link>
      </div>
    </div>

    <div className="flex justify-center">
      <div>
        <h3 className="mb-1 text-xl font-bold leading-tigh">
          Publish status
        </h3>

        <Link href="https://github.com/meshjs/mesh/actions/workflows/publish.yml">
          <img className="h-7" src="https://github.com/meshjs/mesh/actions/workflows/publish.yml/badge.svg" />
        </Link>
      </div>
    </div>
  </div>
</div>


# Support Us
URL: /about/support-us

Help grow the Mesh ecosystem through community engagement, contributions, and advocacy.

***

title: "Support Us"
description: "Help grow the Mesh ecosystem through community engagement, contributions, and advocacy."
------------------------------------------------------------------------------------------------------

import Link from 'fumadocs-core/link';
import Image from 'next/image';
import { cn } from '@/lib/cn';
import { buttonVariants } from '@/components/ui/button';

Mesh is an open-source project maintained by developers who believe in making Cardano accessible to everyone. Your support helps us continue building tools that empower the next generation of blockchain applications.

## Ways to Support

### Follow on Twitter

Stay informed about new releases, features, and ecosystem updates. Engaging with our posts helps spread awareness to other developers.

<div className="mt-4 mb-12">
  <div className="flex items-center justify-between gap-6">
    <div className="flex-1">
      <div className="inline-flex items-center gap-3 mt-4">
        <Link
          href="https://x.com/meshsdk"
          className={cn(
          buttonVariants({ size: "sm", color: "primary" }),
          "rounded-2xl",
          "no-underline"
        )}
        >
          <span className="text-lg font-semibold">Follow @meshsdk</span>
        </Link>
      </div>
    </div>

    <div className="flex-shrink-0 hidden md:block">
      <Image src="/support/x-logo.svg" width={200} height={200} alt="Twitter/X logo" className="invert dark:invert-0" />
    </div>
  </div>
</div>

### Star the GitHub Repository

GitHub stars help developers discover Mesh when searching for Cardano development tools. Each star increases our visibility in the ecosystem.

<div className="mt-4 mb-12">
  <div className="flex items-center justify-between gap-6">
    <div className="flex-1">
      <div className="inline-flex items-center gap-3">
        <Link
          href="https://github.com/MeshJS/mesh"
          className={cn(
          buttonVariants({ size: 'sm', color: 'primary' }),
          'rounded-2xl',
          'no-underline'
        )}
        >
          <span className="text-lg font-semibold">Star on GitHub</span>
        </Link>
      </div>
    </div>

    <div className="flex-shrink-0 hidden md:block">
      <Image src="/support/github-mark-white.svg" width={250} height={250} alt="GitHub logo" className="invert dark:invert-0" />
    </div>
  </div>
</div>

### Join the Discord Community

Connect with other Mesh developers, get help with your projects, and contribute to discussions about new features. Our Discord is the fastest way to get support.

<div className="mt-4 mb-12">
  <div className="flex items-center justify-between">
    <div className="flex-1">
      <div className="inline-flex items-center gap-3">
        <Link
          href="https://discord.com/invite/WvnCNqmAxy"
          className={cn(
          buttonVariants({ size: 'sm', color: 'primary' }),
          'rounded-2xl',
          'no-underline'
        )}
        >
          <span className="text-lg font-semibold">Join Discord</span>
        </Link>
      </div>
    </div>

    <div className="flex-shrink-0 hidden md:block">
      <Image src="/support/discord.png" width={250} height={250} alt="Discord logo" className="invert dark:invert-0" />
    </div>
  </div>
</div>

### Add the Mesh Badge

Display the Mesh badge in your application to show users you build on reliable infrastructure. The badge links to Mesh and helps grow our developer community.

<div className="mt-4 mb-12">
  <div className="flex items-center justify-between">
    <div className="flex-1 max-w-prose">
      ```tsx
      import { MeshBadge } from '@meshsdk/react';

      export default function Page() {
        return (
          <>
            <MeshBadge />
          </>
        );
      }
      ```
    </div>

    <div className="flex-shrink-0 hidden xl:block">
      <Image src="/support/meshbadge.png" width={250} height={250} alt="Mesh badge preview" className="invert dark:invert-0" />
    </div>
  </div>
</div>

### Donate

Financial contributions help fund development, infrastructure, and community events. Every donation directly supports open-source Cardano tooling.

<div className="mt-4 mb-12">
  <div className="flex items-center justify-between gap-6">
    <div className="flex-1">
      <div className="inline-flex items-center gap-3">
        <Link
          href="/about/support-us"
          className={cn(
          buttonVariants({ size: 'sm', color: 'primary' }),
          'rounded-2xl',
          'no-underline'
        )}
        >
          <span className="text-lg font-semibold">Donation options coming soon</span>
        </Link>
      </div>
    </div>
  </div>
</div>

## Other Ways to Contribute

| Contribution     | Impact                                 |
| ---------------- | -------------------------------------- |
| Report bugs      | Help us identify and fix issues faster |
| Submit PRs       | Add features or fix problems directly  |
| Write tutorials  | Help other developers learn Mesh       |
| Answer questions | Support newcomers in Discord           |
| Vote in Catalyst | Fund continued development             |

## Related Resources

* [Project Catalyst](/about/catalyst) - Track our funded proposals
* [Branding Assets](/about/branding) - Download official logos
* [GitHub Issues](https://github.com/MeshJS/mesh/issues) - Report bugs or request features


# MeshAI Chatbot
URL: /ai/chatbot

Get instant answers about Mesh SDK using contextual AI retrieval

***

title: "MeshAI Chatbot"
description: "Get instant answers about Mesh SDK using contextual AI retrieval"
-------------------------------------------------------------------------------

import Video from "@/components/ui/Video";

MeshAI is an AI-powered chatbot that answers your Mesh SDK questions instantly. It uses contextual retrieval to search through documentation, code examples, and starter templates to provide accurate, up-to-date responses.

## Overview

MeshAI combines vector embeddings with large language models to deliver accurate answers without hallucination. When you ask a question, the system:

1. Converts your query into a vector embedding
2. Searches Mesh documentation for semantically similar content
3. Retrieves the most relevant context
4. Generates a response grounded in actual Mesh documentation

## Use Cases

* **Quick API lookups** - Find method signatures, parameters, and return types
* **Code generation** - Get working code snippets for common tasks
* **Concept explanations** - Understand Cardano and Mesh concepts in plain language
* **Troubleshooting** - Describe errors and receive solutions

## Quick Start

1. Navigate to the [Mesh documentation site](https://meshjs.dev)
2. Click the chat icon in the bottom-right corner
3. Type your question and press Enter

No API keys or setup required.

## Example Response

<Video src="/videos/demo.webm" poster="/ai/demo-poster.png" />

In this example, MeshAI creates a transaction that transfers ADA back to the sender's own address. The chatbot generates complete, working code with proper imports.

## Tips for Better Results

| Do                                                                   | Don't                                      |
| -------------------------------------------------------------------- | ------------------------------------------ |
| Ask specific questions: "How do I mint an NFT with a Plutus policy?" | Ask vague questions: "How do I use Mesh?"  |
| Include context: "I'm building a DEX and need to..."                 | Assume the AI knows your project           |
| Ask for code examples: "Show me how to..."                           | Ask only for explanations without examples |

## How Contextual Retrieval Works

Traditional RAG (Retrieval-Augmented Generation) retrieves chunks of documentation based on keyword matching. MeshAI uses **contextual retrieval**, which:

* Embeds chunks with surrounding context for better semantic understanding
* Ranks results by relevance to your specific question
* Filters out tangentially related content
* Synthesizes responses from multiple relevant sources

This approach reduces hallucination and ensures answers are grounded in actual Mesh documentation.

## Limitations

* **Scope** - MeshAI only answers questions about Mesh SDK. For general Cardano questions, consult the [Cardano Developer Portal](https://developers.cardano.org/).
* **Real-time data** - The chatbot does not access live blockchain data. For queries about specific transactions or addresses, use a blockchain explorer.
* **Code execution** - MeshAI generates code but does not execute it. Always test generated code in your development environment.

## Related Resources

* [MCP Server](/docs/ai/mcp) - Get AI assistance directly in your IDE
* [Agent Skills](/docs/ai/skills) - Deep API knowledge for AI coding assistants
* [llms.txt](/docs/ai/llms-txt) - AI-friendly documentation for any tool


# AI Integration
URL: /ai

Build Cardano applications faster with AI-powered tools for documentation, code generation, and debugging

***

title: "AI Integration"
description: "Build Cardano applications faster with AI-powered tools for documentation, code generation, and debugging"
icon: SparklesIcon
------------------

import { linksAi } from "@/data/links-ai";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

Mesh provides AI-powered tools that accelerate Cardano development. Whether you prefer chatbots, IDE integrations, or CLI-based assistants, you can access Mesh documentation and code examples directly in your workflow.

## Available Tools

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksAi.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Choose Your Integration

| Tool                               | Best For                                                          | Setup Time |
| ---------------------------------- | ----------------------------------------------------------------- | ---------- |
| [MeshAI Chatbot](/docs/ai/chatbot) | Quick answers without leaving the browser                         | None       |
| [MCP Server](/docs/ai/mcp)         | Real-time coding assistance in VS Code, Cursor, or Claude Desktop | 2 minutes  |
| [Agent Skills](/docs/ai/skills)    | Deep API knowledge for AI coding assistants                       | 1 minute   |
| [llms.txt](/docs/ai/llms-txt)      | Universal AI-friendly documentation for any tool                  | 1 minute   |

## Why Use AI with Mesh?

Building on Cardano requires understanding complex concepts like UTxO management, Plutus scripts, and transaction building. AI tools help you:

* **Get instant answers** - Ask questions about Mesh API in natural language
* **Generate working code** - Describe what you want to build and get valid TypeScript
* **Debug faster** - Explain errors and get solutions without searching forums
* **Learn patterns** - Discover best practices through AI-guided examples


# llms.txt
URL: /ai/llms-txt

AI-friendly documentation file for code editors like Cursor, Windsurf, and other AI tools

***

title: "llms.txt"
description: "AI-friendly documentation file for code editors like Cursor, Windsurf, and other AI tools"
--------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

Mesh provides an `llms.txt` file that contains all documentation and code examples in a standardized, AI-friendly format. You can plug this file into any AI code editor to get instant access to up-to-date Mesh documentation.

## Overview

The `llms.txt` file follows an [emerging standard](https://llmstxt.org/) for providing documentation to large language models. It contains:

* Complete API reference for all Mesh packages
* Working code examples with imports
* Common patterns and best practices
* Troubleshooting guides

Because the file uses standardized markdown formatting, AI tools can parse and index it consistently across different platforms.

## Use Cases

* **Cursor** - Add as a doc source for context-aware code completion
* **Windsurf** - Reference in conversations for accurate Mesh code generation
* **ChatGPT/Claude** - Upload as context for Mesh-specific questions
* **Custom AI pipelines** - Parse programmatically for RAG systems

## Quick Start

### Cursor

1. Open Cursor settings
2. Navigate to **Features** > **Docs**
3. Click **Add new doc**
4. Paste: `https://meshjs.dev/llms.txt`
5. Click **Add**

Once indexed, reference Mesh docs in any chat by typing `@Docs` and selecting the Mesh documentation.

### Windsurf

1. In a Windsurf chat, type: `@https://meshjs.dev/llms.txt`
2. The AI now has full Mesh context for your conversation

### ChatGPT or Claude

1. Download the file: <Link href="/llms.txt">meshjs.dev/llms.txt</Link>
2. Upload to your conversation as a file attachment
3. Ask questions about Mesh SDK

### Programmatic Access

```typescript
import { fetch } from "undici";

async function getMeshDocs(): Promise<string> {
  const response = await fetch("https://meshjs.dev/llms.txt");
  return response.text();
}
```

## File Location

Access the file directly at: <Link href="/llms.txt">meshjs.dev/llms.txt</Link>

## Benefits Over Traditional Docs

| Traditional Documentation           | llms.txt                         |
| ----------------------------------- | -------------------------------- |
| Requires manual searching           | AI searches contextually         |
| May be outdated in AI training data | Always current                   |
| Split across multiple pages         | Single, complete file            |
| Formatted for humans only           | Optimized for both humans and AI |

## How to Use in Your Projects

Once you add `llms.txt` to your AI tool, you can ask questions like:

* "How do I build a transaction that sends 5 ADA using Mesh?"
* "Show me how to connect a browser wallet with CIP-30"
* "Generate a minting transaction for an NFT collection"
* "What's the correct order of methods for MeshTxBuilder?"

The AI responds with accurate, up-to-date code based on the latest Mesh documentation.

## Troubleshooting

### File not indexing in Cursor

* Verify the URL is correct: `https://meshjs.dev/llms.txt`
* Check your internet connection
* Try removing and re-adding the doc source
* Restart Cursor after adding

### AI gives outdated information

* Re-index the documentation in your AI tool's settings
* The `llms.txt` file updates with each Mesh release

### File is too large for upload

* Some AI tools have file size limits
* Use the MCP server instead for real-time access: [MCP Setup](/docs/ai/mcp)

## Related Resources

* [MCP Server](/docs/ai/mcp) - Real-time AI integration for VS Code, Cursor, and Claude Desktop
* [Agent Skills](/docs/ai/skills) - Deep Mesh knowledge for AI coding assistants
* [MeshAI Chatbot](/docs/ai/chatbot) - Browser-based AI assistant


# MCP Server
URL: /ai/mcp

Access Mesh documentation and get coding assistance directly in your editor

***

title: "MCP Server"
description: "Access Mesh documentation and get coding assistance directly in your editor"
------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

The Mesh MCP (Model Context Protocol) server provides real-time access to Mesh documentation and AI-powered coding assistance directly in VS Code, Cursor, or Claude Desktop.

## Overview

MCP is an open protocol that connects AI assistants to external data sources. The Mesh MCP server gives your AI assistant:

* Full access to Mesh SDK documentation
* Context-aware code generation for Cardano transactions
* Debugging assistance with Mesh-specific error handling
* Up-to-date API reference without relying on training data

## Use Cases

* **Code completion** - Get accurate Mesh method suggestions as you type
* **Transaction building** - Generate complete transaction code from natural language
* **Error debugging** - Paste errors and receive Mesh-specific solutions
* **API exploration** - Ask about available methods and their parameters

## Quick Start

### Cursor (One-Click Install)

Click the button below to install Mesh MCP in Cursor:

<a href="https://cursor.com/en-US/install-mcp?name=mesh-mcp&config=eyJuYW1lIjoibWVzaC1tY3Atc2VydmVyIiwiZW52Ijp7IkFQSV9LRVkiOiJ5b3VyLWFwaS1rZXkiLCJNT0RFTCI6InlvdXItcHJlZmVycmVkLW1vZGVsIn0sImNvbW1hbmQiOiJucHggLXkgbWVzaGpzLW1jcCJ9" className="dark:hidden inline-block" style={{ margin: 0, padding: 0, lineHeight: 0 }}>
  <img src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Add mesh-mcp MCP server to Cursor" style={{ height: '36px', margin: 0, padding: 0, display: 'block' }} />
</a>

<a href="https://cursor.com/en-US/install-mcp?name=mesh-mcp&config=eyJuYW1lIjoibWVzaC1tY3Atc2VydmVyIiwiZW52Ijp7IkFQSV9LRVkiOiJ5b3VyLWFwaS1rZXkiLCJNT0RFTCI6InlvdXItcHJlZmVycmVkLW1vZGVsIn0sImNvbW1hbmQiOiJucHggLXkgbWVzaGpzLW1jcCJ9" className="hidden dark:inline-block" style={{ margin: 0, padding: 0, lineHeight: 0 }}>
  <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add mesh-mcp MCP server to Cursor" style={{ height: '36px', margin: 0, padding: 0, display: 'block' }} />
</a>

After clicking, configure your `API_KEY` and `MODEL` in Cursor's MCP settings.

### Claude Desktop (CLI)

If you have the `claude` CLI installed:

```bash
claude mcp add-json mesh-mcp '{
  "command": "npx",
  "args": ["-y", "meshjs-mcp"],
  "env": {
    "API_KEY": "your-api-key",
    "MODEL": "your-preferred-model"
  }
}'
```

### VS Code / Manual Setup

Add this configuration to your MCP server settings file:

```json
{
  "servers": {
    "mesh-mcp": {
      "name": "mesh-mcp-server",
      "command": "npx",
      "args": ["-y", "meshjs-mcp"],
      "env": {
        "API_KEY": "your-api-key",
        "MODEL": "your-preferred-model"
      }
    }
  }
}
```

## Configuration

### Required Environment Variables

| Variable  | Description                                    | Example                                            |
| --------- | ---------------------------------------------- | -------------------------------------------------- |
| `API_KEY` | Your API key from OpenAI, Anthropic, or Google | `sk-...` or `your-key`                             |
| `MODEL`   | The model to use for responses                 | `gpt-4o`, `claude-sonnet-4-20250514`, `gemini-pro` |

### Supported Providers

The MCP server works with any of these AI providers:

* **OpenAI** - Use models like `gpt-4o`, `gpt-4-turbo`
* **Anthropic** - Use models like `claude-sonnet-4-20250514`, `claude-3-haiku`
* **Google** - Use models like `gemini-pro`, `gemini-1.5-pro`

## Starting the Server

After saving your configuration, you must start the server manually:

### VS Code

1. Open Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux)
2. Search for "MCP: List Servers"
3. Select "mesh-mcp"
4. Choose "Run Server"

### Cursor

1. Open Command Palette
2. Search for "MCP: List Servers"
3. Select "mesh-mcp" and run it

### Claude Desktop

The server starts automatically on launch if configured correctly. Check MCP logs if issues arise.

## Usage Examples

Once the server is running, ask your AI assistant Mesh-related questions:

**Build a transaction:**

```
Create a transaction that sends 10 ADA to addr1qy...
```

**Debug an error:**

```
I'm getting "missing required signer" - what does this mean?
```

**Explore the API:**

```
What methods does MeshTxBuilder have for Plutus scripts?
```

## Complete Example

<img src="ai/mcp-example.png" alt="MCP server example showing code generation in Cursor" />

In this example, the AI generates a complete transaction with proper imports, UTxO selection, and signing flow.

## Troubleshooting

### Server not starting

* Verify Node.js is installed: `node --version`
* Check that npx works: `npx --version`
* Ensure your API key is valid

### "Connection refused" error

* The server may not be running. Follow the [Starting the Server](#starting-the-server) steps.
* Check for port conflicts with other services

### Responses are slow or incomplete

* Try a faster model (e.g., `gpt-4o-mini` instead of `gpt-4o`)
* Check your API provider's rate limits
* Ensure stable internet connection

### API key errors

* Verify your key is correct and has available credits
* Check the key matches your chosen provider (OpenAI key for OpenAI models, etc.)

## Related Resources

* [Agent Skills](/docs/ai/skills) - Deep Mesh knowledge for AI coding assistants
* [llms.txt](/docs/ai/llms-txt) - AI-friendly documentation for any tool
* [MeshAI Chatbot](/docs/ai/chatbot) - Browser-based AI assistant
* [MCP Protocol Specification](https://modelcontextprotocol.io/) - Learn more about MCP


# Agent Skills for AI Coding Assistants
URL: /ai/skills

Give your AI coding assistant deep knowledge of Mesh SDK for faster Cardano development - works with Claude Code, Cursor, Codex, and 37+ tools

***

title: "Agent Skills for AI Coding Assistants"
description: "Give your AI coding assistant deep knowledge of Mesh SDK for faster Cardano development - works with Claude Code, Cursor, Codex, and 37+ tools"
-------------------------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

Agent Skills give your AI coding assistant deep knowledge of Mesh SDK so it can write correct Cardano code without searching documentation. Instead of looking up method signatures, transaction patterns, or CIP standards yourself, you describe what you want and your assistant produces working code.

Compatible with Claude Code, Cursor, GitHub Copilot, Codex, and <Link href="https://skills.sh">37+ other tools</Link>.

| Without Skills                                                            | With Skills Installed                                           |
| ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Read docs to find the right API method                                    | AI already knows the full API                                   |
| Trial-and-error for transaction patterns                                  | Ask "build a transaction that sends 5 ADA" and get working code |
| Debug cryptic Cardano errors alone                                        | Troubleshooting guides built into AI context                    |
| Forget method ordering (e.g., `spendingPlutusScriptV3()` before `txIn()`) | AI knows the correct order                                      |
| Look up CIP standards                                                     | AI understands CIP-30, CIP-8, etc.                              |
| Manually translate Aiken types to MeshTxBuilder code                      | Give it your Aiken types and get correct transaction code       |

## Available Skills

| Skill              | Package                | What It Covers                                                                                                                             |
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `mesh-transaction` | `@meshsdk/transaction` | MeshTxBuilder API, sending ADA, minting NFTs and tokens, Plutus script spending, staking, governance, DRep registration, Aiken integration |
| `mesh-wallet`      | `@meshsdk/wallet`      | Browser wallets (Eternl, Nami, Lace, Flint, Yoroi), headless server-side wallets, transaction signing, CIP-30, CIP-8 data signing          |
| `mesh-core-cst`    | `@meshsdk/core-cst`    | CBOR serialization, Plutus data conversion, address parsing, CIP-8 message signing, native script hashing, `applyParamsToScript`           |

Each skill includes a complete API reference, working code recipes, and a troubleshooting guide.

## Quick Start

Install all Mesh skills with a single command:

```bash
npx skills add MeshJS/skills
```

The CLI auto-detects which AI tools you have installed (Claude Code, Cursor, Codex, etc.) and places skills in the correct directory. To install a specific skill only:

```bash
npx skills add MeshJS/skills --skill mesh-transaction
```

## How It Works

Each skill contains a description that tells your AI assistant when to activate it. When you ask something like *"help me build a transaction with MeshTxBuilder"*, the assistant recognizes the topic, loads the relevant skill, and responds with accurate API usage, correct method ordering, and working code patterns.

You don't need to reference skills manually. The assistant loads them automatically based on context.

## Example Conversation

After installing skills, you can ask your assistant questions like:

* *"Build a transaction that sends 5 ADA to addr1qy..."*
* *"How do I mint an NFT with a Plutus minting policy?"*
* *"Help me connect a browser wallet using CIP-30"*
* *"Show me how to interact with a Plutus V3 script"*
* *"Why am I getting 'missing required signer' error?"*
* *"How do I register as a DRep and vote on a proposal?"*
* *"Here are my Aiken types, build the MeshTxBuilder transaction for me"*

Here is what a response looks like with skills loaded:

**You:** Send 5 ADA to an address

**AI Assistant:**

```typescript
import { MeshTxBuilder } from '@meshsdk/transaction';

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const utxos = await provider.fetchAddressUTxOs(walletAddress);

const unsignedTx = await txBuilder
  .txOut('addr_test1qp...', [
    { unit: 'lovelace', quantity: '5000000' }
  ])
  .changeAddress(walletAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## Aiken Smart Contract Support

The `mesh-transaction` skill includes a complete Aiken-to-MeshTxBuilder mapping guide. When you share your Aiken type definitions, your AI assistant knows how to translate them into the correct MeshJS data helpers — picking the right format (`conStr` for datums, `mConStr` for redeemers), mapping constructor indices to variant order, and choosing the correct type parameters.

For example, given this Aiken type:

```
type MarketAction {
  Buy
  Cancel
  UpdatePrice { new_price: Int }
}
```

Your AI assistant knows that:

* `Buy` is variant index 0 → `mConStr0([])`
* `Cancel` is variant index 1 → `mConStr1([])`
* `UpdatePrice` is variant index 2 with a field → `mConStr2([75_000_000])`

Combined with the skill's transaction-building knowledge, it produces the full MeshTxBuilder chain with the correct method ordering, collateral handling, and datum/redeemer placement — so you can focus on your contract logic instead of figuring out the MeshJS data format conventions.

## Skill File Structure

Each skill follows the <Link href="https://agentskills.io/specification">Agent Skills specification</Link>:

```
mesh-transaction/
  SKILL.md              # Entry point - description, overview, quick reference
  TRANSACTION.md        # Complete MeshTxBuilder API reference
  AIKEN-MAPPING.md      # Aiken smart contract integration guide
  PATTERNS.md           # Common recipes with working code
  TROUBLESHOOTING.md    # Error solutions and debugging

mesh-wallet/
  SKILL.md              # Entry point - description, overview, quick reference
  WALLET.md             # Complete wallet API reference
  PATTERNS.md           # Common recipes with working code
  TROUBLESHOOTING.md    # Error solutions and debugging

mesh-core-cst/
  SKILL.md              # Entry point - description, overview, quick reference
  CORE-CST.md           # Complete core-cst API reference
  PATTERNS.md           # Common recipes with working code
  TROUBLESHOOTING.md    # Error solutions and debugging
```

## Source Code

Browse <span><Link href="https://github.com/MeshJS/skills">MeshJS/skills</Link></span> on GitHub


# Write a Smart Contract
URL: /aiken/first-script

Create your first Aiken validator with datum and redeemer validation

***

title: "Write a Smart Contract"
description: "Create your first Aiken validator with datum and redeemer validation"
-----------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

In this guide, you create an Aiken validator that locks assets on-chain. The validator requires a specific message ("Hello, World!") and the owner's signature to unlock the funds.

**What you'll build:**

* A validator with custom datum (owner's key hash)
* Redeemer validation (message check)
* Transaction signature verification

**Prerequisites:**

* <Link href="/docs/aiken/getting-started">Aiken CLI installed</Link>
* Basic understanding of Cardano transactions

## Quick Start

Create and compile a validator in 3 steps.

```bash
aiken new meshjs/hello_world
cd hello_world
```

Create `validators/hello_world.ak`:

```rust
use aiken/collection/list
use aiken/crypto.{VerificationKeyHash}
use cardano/transaction.{ScriptContext}

pub type Datum {
  owner: VerificationKeyHash,
}

pub type Redeemer {
  msg: ByteArray,
}

validator hello_world {
  spend(
    datum: Option<Datum>,
    redeemer: Redeemer,
    _own_ref: Data,
    tx: transaction.Transaction,
  ) {
    expect Some(d) = datum
    let must_say_hello = redeemer.msg == "Hello, World!"
    let must_be_signed = list.has(tx.extra_signatories, d.owner)
    must_say_hello && must_be_signed
  }
}
```

```bash
aiken build
```

## Step-by-Step Guide

### Step 1: Create a New Project

Initialize an Aiken project with the standard structure.

```bash
aiken new meshjs/hello_world
cd hello_world
```

Verify the project was created:

```bash
aiken check
```

### Step 2: Define Your Types

Create a new file `validators/hello_world.ak`. Start by defining the datum and redeemer types.

```rust
use aiken/collection/list
use aiken/crypto.{VerificationKeyHash}
use cardano/transaction.{ScriptContext}

/// The datum stores the owner's verification key hash.
/// Only the owner can unlock funds from this script.
pub type Datum {
  owner: VerificationKeyHash,
}

/// The redeemer contains the message that must match "Hello, World!"
pub type Redeemer {
  msg: ByteArray,
}
```

**Key points:**

* `VerificationKeyHash` is a 28-byte hash of a public key
* Custom types make your contract self-documenting
* Comments with `///` appear in generated documentation

### Step 3: Write the Validator Logic

Add the validator function that checks the unlock conditions.

```rust
validator hello_world {
  spend(
    datum: Option<Datum>,
    redeemer: Redeemer,
    _own_ref: Data,
    tx: transaction.Transaction,
  ) {
    // Unwrap the datum - fail if None
    expect Some(d) = datum

    // Check 1: Redeemer message must be "Hello, World!"
    let must_say_hello = redeemer.msg == "Hello, World!"

    // Check 2: Transaction must be signed by the owner
    let must_be_signed = list.has(tx.extra_signatories, d.owner)

    // Both conditions must be true
    must_say_hello && must_be_signed
  }
}
```

**What this validator does:**

1. Extracts the datum containing the owner's key hash
2. Verifies the redeemer message equals "Hello, World!"
3. Confirms the transaction is signed by the owner
4. Returns `True` only if both conditions pass

### Step 4: Compile the Contract

Build the project to generate the Plutus blueprint.

```bash
aiken build
```

This creates `plutus.json` in the project root. The blueprint contains:

```json
{
  "validators": [
    {
      "title": "hello_world.hello_world.spend",
      "compiledCode": "5901a2...",
      "hash": "abc123..."
    }
  ]
}
```

### Step 5: Verify with Type Checking

Run the type checker to ensure your code is valid.

```bash
aiken check
```

If there are errors, fix them before proceeding. Common issues:

* Missing imports
* Type mismatches in datum/redeemer
* Incorrect function signatures

## Complete Validator Code

Here's the full `validators/hello_world.ak` file:

```rust
use aiken/collection/list
use aiken/crypto.{VerificationKeyHash}
use cardano/transaction.{ScriptContext}

/// The datum stores the owner's verification key hash.
/// Only the owner can unlock funds from this script.
pub type Datum {
  owner: VerificationKeyHash,
}

/// The redeemer contains the unlock message.
pub type Redeemer {
  msg: ByteArray,
}

/// A simple validator that requires:
/// 1. The redeemer message to be "Hello, World!"
/// 2. The transaction to be signed by the datum owner
validator hello_world {
  spend(
    datum: Option<Datum>,
    redeemer: Redeemer,
    _own_ref: Data,
    tx: transaction.Transaction,
  ) {
    expect Some(d) = datum
    let must_say_hello = redeemer.msg == "Hello, World!"
    let must_be_signed = list.has(tx.extra_signatories, d.owner)
    must_say_hello && must_be_signed
  }
}
```

## Using the Compiled Script with Mesh

After building, integrate the compiled script with your TypeScript application.

```typescript
import {
  applyParamsToScript,
  resolvePlutusScriptAddress,
  PlutusScript,
} from "@meshsdk/core";
import blueprint from "./hello_world/plutus.json";

// Get the compiled code from the blueprint
const compiledCode = blueprint.validators[0].compiledCode;

// Apply parameters (none in this case, but required for CBOR encoding)
const scriptCbor = applyParamsToScript(compiledCode, []);

// Create the script object
const script: PlutusScript = {
  code: scriptCbor,
  version: "V3",
};

// Resolve the script address (0 = mainnet, 1 = preprod/preview)
const scriptAddress = resolvePlutusScriptAddress(script, 0);

console.log("Script Address:", scriptAddress);
```

## Troubleshooting

### aiken build fails

Check for syntax errors with `aiken check`. Common issues:

```rust
// Wrong: Missing comma
pub type Datum {
  owner: VerificationKeyHash
  name: ByteArray  // <- Missing comma
}

// Correct
pub type Datum {
  owner: VerificationKeyHash,
  name: ByteArray,
}
```

### Validator returns False unexpectedly

Debug by testing each condition separately:

```rust
validator hello_world {
  spend(datum: Option<Datum>, redeemer: Redeemer, _own_ref: Data, tx: transaction.Transaction) {
    expect Some(d) = datum

    // Debug: Log which condition fails
    trace @"Checking message..."
    let must_say_hello = redeemer.msg == "Hello, World!"

    trace @"Checking signature..."
    let must_be_signed = list.has(tx.extra_signatories, d.owner)

    must_say_hello && must_be_signed
  }
}
```

### Import errors

Ensure you import from the correct modules:

```rust
// Correct imports for Aiken v1.1+
use aiken/collection/list
use aiken/crypto.{VerificationKeyHash}
use cardano/transaction.{ScriptContext}
```

## Related Links

* <Link href="/docs/aiken/transactions">Build Transactions</Link> - Lock and unlock assets with this validator
* <Link href="/docs/aiken/getting-started">Getting Started</Link> - Installation and CLI reference
* <Link href="https://aiken-lang.org/language-tour">Aiken Language Tour</Link> - Complete syntax reference
* <Link href="https://aiken-lang.org/example--hello-world">Official Hello World Example</Link> - Aiken's tutorial


# Getting Started
URL: /aiken/getting-started

Install Aiken and set up your development environment

***

title: "Getting Started"
description: "Install Aiken and set up your development environment"
--------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

This guide walks you through installing the Aiken CLI and configuring your development environment. After completing these steps, you can write, compile, and test Aiken smart contracts.

**Prerequisites:**

* macOS, Linux, or Windows with WSL
* A code editor (VS Code recommended)
* Node.js 18+ for Mesh integration

## Quick Start

Install Aiken and verify your setup in under 5 minutes.

```bash
# Install Aiken (macOS/Linux)
curl -sSfL https://install.aiken-lang.org | bash
aikup

# Verify installation
aiken --version
```

## Step-by-Step Installation

### Option 1: Using aikup (macOS and Linux)

The `aikup` utility downloads and manages Aiken versions. This is the recommended installation method.

**Step 1: Install aikup**

```bash
curl -sSfL https://install.aiken-lang.org | bash
```

**Step 2: Install the latest Aiken version**

```bash
aikup
```

**Step 3: Verify installation**

```bash
aiken --version
```

You should see output like `aiken v1.x.x`.

### Option 2: Build from Source (All Platforms)

Build Aiken from source using Cargo. This method works on all platforms including Windows.

**Step 1: Install Rust**

If you don't have Rust installed, get it from <Link href="https://rustup.rs">rustup.rs</Link>.

```bash
# Verify Rust installation
rustc --version
cargo --version
```

**Step 2: Install Aiken via Cargo**

```bash
cargo install aiken
```

**Step 3: Verify installation**

```bash
aiken --version
```

## Editor Setup

### VS Code Extension

Install the Aiken extension for syntax highlighting, code snippets, and error checking.

**Installation options:**

1. Search for "aiken" in the VS Code Extensions tab
2. Or install directly from the <Link href="https://marketplace.visualstudio.com/items?itemName=TxPipe.aiken">VS Code Marketplace</Link>

**Features:**

* Syntax highlighting for `.ak` files
* Inline error checking
* Code snippets for common patterns
* Go-to-definition support

## CLI Reference

Use these commands to develop and test your smart contracts.

### aiken new

Create a new Aiken project with the standard directory structure.

```bash
aiken new your-org/project-name
cd project-name
```

### aiken build

Compile your validators and generate the `plutus.json` blueprint file.

```bash
aiken build
```

The blueprint contains:

* Compiled validator code (CBOR-encoded)
* Type information for datum and redeemer
* Hash digests for each validator

### aiken check

Type-check your project and run tests.

```bash
aiken check
```

Use this command frequently during development to catch errors early.

### aiken docs

Generate HTML documentation from your project's comments.

```bash
aiken docs
```

### aiken blueprint

Utility functions for working with the compiled blueprint.

```bash
# Generate an address for a validator
aiken blueprint address

# Convert blueprint to different formats
aiken blueprint convert
```

## Complete Example

Create a new project and verify the setup.

```bash
# Create project
aiken new meshjs/hello_world
cd hello_world

# Check the project structure
ls -la

# Run the type checker
aiken check

# Build the project
aiken build

# Verify the blueprint was generated
cat plutus.json
```

## Project Structure

After running `aiken new`, your project looks like this:

```
hello_world/
  aiken.toml          # Project configuration
  lib/                # Shared library code
  validators/         # Validator scripts
  plutus.json         # Generated blueprint (after build)
```

**Key files:**

* `aiken.toml` - Project metadata and dependencies
* `validators/*.ak` - Your validator scripts
* `plutus.json` - Compiled output for use with Mesh

## Troubleshooting

### Command not found: aiken

The Aiken binary is not in your PATH. Add it manually:

```bash
# For aikup installations
export PATH="$HOME/.aiken/bin:$PATH"

# Add to your shell profile for persistence
echo 'export PATH="$HOME/.aiken/bin:$PATH"' >> ~/.bashrc
```

### Build fails with type errors

Run `aiken check` to see detailed error messages. Common issues:

1. **Missing imports** - Add required modules at the top of your file
2. **Type mismatches** - Verify datum/redeemer types match your validator signature
3. **Syntax errors** - Check for missing commas or brackets

### VS Code extension not working

1. Reload VS Code after installing the extension
2. Verify the file has a `.ak` extension
3. Check the extension is enabled for the workspace

### plutus.json not generating

Ensure your project has at least one validator in the `validators/` directory. Empty projects don't generate a blueprint.

## Related Links

* <Link href="/docs/aiken/first-script">Write Your First Smart Contract</Link> - Create a validator
* <Link href="/docs/aiken/transactions">Build Transactions</Link> - Interact with contracts using Mesh
* <Link href="https://aiken-lang.org/language-tour">Aiken Language Tour</Link> - Learn Aiken syntax
* <Link href="https://aiken-lang.org/installation-instructions">Official Installation Guide</Link> - More installation options


# Aiken
URL: /aiken

Build and deploy Cardano smart contracts with Aiken and Mesh

***

title: "Aiken"
description: "Build and deploy Cardano smart contracts with Aiken and Mesh"
icon: "icons/aiken.png"
-----------------------

import { linksAiken } from "@/data/links-aiken";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Aiken is a functional programming language designed specifically for Cardano smart contract development. It compiles to Plutus Core and prioritizes security, efficiency, and developer experience.

Mesh provides seamless integration with Aiken, allowing you to:

* Compile Aiken contracts and use them in your TypeScript applications
* Build transactions that interact with Aiken validators
* Apply parameters to scripts and resolve addresses

**When to use Aiken with Mesh:**

* You need to write custom on-chain logic (validators, minting policies)
* You want a modern, type-safe language for smart contracts
* You prefer functional programming patterns

## Quick Start

Write and deploy an Aiken smart contract in 4 steps.

**1. Install Aiken CLI**

```bash
curl -sSfL https://install.aiken-lang.org | bash
aikup
```

**2. Create a new project**

```bash
aiken new meshjs/hello_world
cd hello_world
```

**3. Write your validator**

```rust
// validators/hello_world.ak
validator hello_world {
  spend(datum: Data, redeemer: Data, context: Data) {
    True
  }
}
```

**4. Build and integrate with Mesh**

```bash
aiken build
```

```typescript
import { MeshTxBuilder, applyParamsToScript, resolvePlutusScriptAddress } from "@meshsdk/core";
import blueprint from "./plutus.json";

const scriptCbor = applyParamsToScript(blueprint.validators[0].compiledCode, []);
const scriptAddress = resolvePlutusScriptAddress({ code: scriptCbor, version: "V3" }, 0);
```

## What's Included

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksAiken.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related Links

* <Link href="/docs/aiken/getting-started">Getting Started</Link> - Install Aiken and set up your environment
* <Link href="/docs/aiken/first-script">Write a Smart Contract</Link> - Create your first validator
* <Link href="/docs/aiken/transactions">Build Transactions</Link> - Lock and redeem assets
* <Link href="https://aiken-lang.org">Aiken Documentation</Link> - Official Aiken language reference


# Build Transactions
URL: /aiken/transactions

Lock and redeem assets from Aiken smart contracts using Mesh

***

title: "Build Transactions"
description: "Lock and redeem assets from Aiken smart contracts using Mesh"
---------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

This guide shows you how to build transactions that interact with Aiken smart contracts. You'll learn to lock assets at a script address and redeem them by providing valid datum and redeemer values.

**What you'll learn:**

* Initialize a PlutusScript from compiled Aiken code
* Lock assets at a script address with a datum
* Redeem assets by providing a valid redeemer
* Handle collateral for Plutus transactions

**Prerequisites:**

* <Link href="/docs/aiken/first-script">Compiled Aiken validator</Link> (plutus.json)
* <Link href="/docs/svelte/getting-started">Connected wallet</Link> via Mesh
* Testnet ADA for testing

## Quick Start

Lock 5 ADA at a script address.

```typescript
import { MeshTxBuilder, applyParamsToScript, resolvePlutusScriptAddress, resolvePaymentKeyHash } from "@meshsdk/core";
import blueprint from "./plutus.json";

// Setup script
const scriptCbor = applyParamsToScript(blueprint.validators[0].compiledCode, []);
const script = { code: scriptCbor, version: "V3" as const };
const scriptAddress = resolvePlutusScriptAddress(script, 0);

// Get wallet info
const address = await wallet.getChangeAddress();
const hash = resolvePaymentKeyHash(address);
const utxos = await wallet.getUtxos();

// Build lock transaction
const txBuilder = new MeshTxBuilder({ fetcher: provider });
const unsignedTx = await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutDatumHashValue({ alternative: 0, fields: [hash] })
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## Step-by-Step: Lock Assets

### Step 1: Initialize the Script

Load the compiled validator from your Aiken blueprint and resolve its address.

```typescript
import {
  applyParamsToScript,
  resolvePlutusScriptAddress,
  PlutusScript,
  Data,
} from "@meshsdk/core";
import blueprint from "./hello_world/plutus.json";

function getScript() {
  // Get compiled code from blueprint
  const compiledCode = blueprint.validators[0].compiledCode;

  // Apply parameters (empty array if no params)
  const scriptCbor = applyParamsToScript(compiledCode, []);

  // Create script object
  const script: PlutusScript = {
    code: scriptCbor,
    version: "V3",
  };

  // Resolve script address (0 = mainnet, 1 = testnet)
  const scriptAddress = resolvePlutusScriptAddress(script, 0);

  return { script, scriptAddress };
}

const { script, scriptAddress } = getScript();
console.log("Script Address:", scriptAddress);
```

### Step 2: Get Wallet Information

Retrieve the user's address and payment key hash for the datum.

```typescript
import { resolvePaymentKeyHash } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function getWalletInfo(wallet: MeshCardanoBrowserWallet) {
  // Get the user's address
  const addresses = await wallet.getUsedAddresses();
  const address = addresses[0];

  if (!address) {
    throw new Error("No wallet address found");
  }

  // Extract the payment key hash
  const hash = resolvePaymentKeyHash(address);

  return { address, hash };
}

const { address, hash } = await getWalletInfo(wallet);
```

### Step 3: Create the Datum

Build the datum object matching your Aiken type definition.

```typescript
import { Data } from "@meshsdk/core";

// Datum structure matches Aiken's Datum type:
// pub type Datum { owner: VerificationKeyHash }
const datum: Data = {
  alternative: 0,  // First constructor (and only one)
  fields: [hash],  // owner field = wallet key hash
};
```

**Important:** The `alternative` index corresponds to the constructor order in your Aiken type. For single-constructor types, use `0`.

### Step 4: Build and Submit the Lock Transaction

Create a transaction that sends assets to the script address with the datum attached.

```typescript
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function lockAssets(wallet: MeshCardanoBrowserWallet, amount: string) {
  const { scriptAddress } = getScript();
  const { address, hash } = await getWalletInfo(wallet);

  // Create datum with owner's key hash
  const datum: Data = {
    alternative: 0,
    fields: [hash],
  };

  // Get UTXOs and change address
  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  // Initialize provider for fee calculation
  const provider = new BlockfrostProvider("<YOUR_API_KEY>");

  // Build transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .txOut(scriptAddress, [{ unit: "lovelace", quantity: amount }])
    .txOutDatumHashValue(datum)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx);
  const txHash = await wallet.submitTx(signedTx);

  return txHash;
}

// Lock 5 ADA
const txHash = await lockAssets(wallet, "5000000");
console.log("Lock Transaction:", txHash);
```

## Step-by-Step: Redeem Assets

### Step 1: Find the Locked UTXO

Query the script address for UTXOs matching your datum hash.

```typescript
import { resolveDataHash, BlockfrostProvider } from "@meshsdk/core";

async function findLockedUtxo(scriptAddress: string, datum: Data) {
  const provider = new BlockfrostProvider("<YOUR_API_KEY>");

  // Fetch all UTXOs at script address
  const utxos = await provider.fetchAddressUTxOs(scriptAddress, "lovelace");

  // Calculate expected datum hash
  const expectedHash = resolveDataHash(datum);

  // Find UTXO with matching datum
  const utxo = utxos.find((u: any) => u.output.dataHash === expectedHash);

  if (!utxo) {
    throw new Error("No UTXO found with matching datum");
  }

  return utxo;
}
```

### Step 2: Create the Redeemer

Build the redeemer matching your Aiken type.

```typescript
import { Data } from "@meshsdk/core";

// Redeemer structure matches Aiken's Redeemer type:
// pub type Redeemer { msg: ByteArray }
const redeemer: Data = {
  alternative: 0,
  fields: ["Hello, World!"],  // Must match validator check
};
```

### Step 3: Build and Submit the Redeem Transaction

Create a transaction that spends the script UTXO with the correct redeemer.

```typescript
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function redeemAssets(wallet: MeshCardanoBrowserWallet) {
  const { script, scriptAddress } = getScript();
  const { address, hash } = await getWalletInfo(wallet);
  const provider = new BlockfrostProvider("<YOUR_API_KEY>");

  // Recreate datum (must match what was locked)
  const datum: Data = {
    alternative: 0,
    fields: [hash],
  };

  // Create redeemer with required message
  const redeemer: Data = {
    alternative: 0,
    fields: ["Hello, World!"],
  };

  // Find the locked UTXO
  const assetUtxo = await findLockedUtxo(scriptAddress, datum);

  // Get wallet UTXOs for fees
  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  // Get collateral (required for Plutus scripts)
  const collateral = await wallet.getCollateral();

  if (!collateral || collateral.length === 0) {
    throw new Error("No collateral available. Set collateral in your wallet.");
  }

  // Build redeem transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    // Indicate we're spending a Plutus V3 script
    .spendingPlutusScriptV3()
    // Reference the script UTXO
    .txIn(assetUtxo.input.txHash, assetUtxo.input.outputIndex)
    // Provide the datum value
    .txInDatumValue(datum)
    // Provide the redeemer value
    .txInRedeemerValue(redeemer)
    // Attach the script
    .txInScript(script.code)
    // Output to wallet
    .txOut(address, assetUtxo.output.amount)
    // Required signer (validator checks this)
    .requiredSignerHash(hash)
    // Collateral for script execution
    .txInCollateral(
      collateral[0].input.txHash,
      collateral[0].input.outputIndex,
      collateral[0].output.amount,
      collateral[0].output.address
    )
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign transaction (partial = true because script provides one signature)
  const signedTx = await wallet.signTx(unsignedTx, true);
  const txHash = await wallet.submitTx(signedTx);

  return txHash;
}

const txHash = await redeemAssets(wallet);
console.log("Redeem Transaction:", txHash);
```

## Complete Example

A full implementation showing both lock and redeem functionality.

```typescript
import {
  MeshTxBuilder,
  BlockfrostProvider,
  applyParamsToScript,
  resolvePlutusScriptAddress,
  resolvePaymentKeyHash,
  resolveDataHash,
  PlutusScript,
  Data,
} from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import blueprint from "./hello_world/plutus.json";

// Configuration
const NETWORK_ID = 0; // 0 = mainnet, 1 = testnet
const BLOCKFROST_API_KEY = "<YOUR_API_KEY>";

// Initialize provider
const provider = new BlockfrostProvider(BLOCKFROST_API_KEY);

// Script helpers
function getScript(): { script: PlutusScript; scriptAddress: string } {
  const compiledCode = blueprint.validators[0].compiledCode;
  const scriptCbor = applyParamsToScript(compiledCode, []);

  const script: PlutusScript = {
    code: scriptCbor,
    version: "V3",
  };

  const scriptAddress = resolvePlutusScriptAddress(script, NETWORK_ID);
  return { script, scriptAddress };
}

async function getWalletInfo(wallet: MeshCardanoBrowserWallet) {
  const addresses = await wallet.getUsedAddresses();
  const address = addresses[0];
  if (!address) throw new Error("No address found");

  const hash = resolvePaymentKeyHash(address);
  return { address, hash };
}

// Lock assets at script address
export async function lockAssets(
  wallet: MeshCardanoBrowserWallet,
  lovelaceAmount: string
): Promise<string> {
  const { scriptAddress } = getScript();
  const { hash } = await getWalletInfo(wallet);

  const datum: Data = {
    alternative: 0,
    fields: [hash],
  };

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  const txBuilder = new MeshTxBuilder({ fetcher: provider });
  const unsignedTx = await txBuilder
    .txOut(scriptAddress, [{ unit: "lovelace", quantity: lovelaceAmount }])
    .txOutDatumHashValue(datum)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  return wallet.submitTx(signedTx);
}

// Redeem assets from script address
export async function redeemAssets(wallet: MeshCardanoBrowserWallet): Promise<string> {
  const { script, scriptAddress } = getScript();
  const { address, hash } = await getWalletInfo(wallet);

  const datum: Data = {
    alternative: 0,
    fields: [hash],
  };

  const redeemer: Data = {
    alternative: 0,
    fields: ["Hello, World!"],
  };

  // Find UTXO
  const utxos = await provider.fetchAddressUTxOs(scriptAddress, "lovelace");
  const dataHash = resolveDataHash(datum);
  const assetUtxo = utxos.find((u: any) => u.output.dataHash === dataHash);

  if (!assetUtxo) {
    throw new Error("No locked UTXO found");
  }

  const walletUtxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const collateral = await wallet.getCollateral();

  if (!collateral?.length) {
    throw new Error("Set collateral in your wallet");
  }

  const txBuilder = new MeshTxBuilder({ fetcher: provider });
  const unsignedTx = await txBuilder
    .spendingPlutusScriptV3()
    .txIn(assetUtxo.input.txHash, assetUtxo.input.outputIndex)
    .txInDatumValue(datum)
    .txInRedeemerValue(redeemer)
    .txInScript(script.code)
    .txOut(address, assetUtxo.output.amount)
    .requiredSignerHash(hash)
    .txInCollateral(
      collateral[0].input.txHash,
      collateral[0].input.outputIndex,
      collateral[0].output.amount,
      collateral[0].output.address
    )
    .changeAddress(changeAddress)
    .selectUtxosFrom(walletUtxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  return wallet.submitTx(signedTx);
}
```

## API Reference

### MeshTxBuilder Methods

| Method                        | Description                                |
| ----------------------------- | ------------------------------------------ |
| `txOut(address, assets)`      | Add an output to the transaction           |
| `txOutDatumHashValue(datum)`  | Attach a datum hash to the previous output |
| `spendingPlutusScriptV3()`    | Indicate next input is a Plutus V3 script  |
| `txIn(txHash, index)`         | Add a UTXO input                           |
| `txInDatumValue(datum)`       | Provide datum value for script input       |
| `txInRedeemerValue(redeemer)` | Provide redeemer value for script input    |
| `txInScript(code)`            | Attach the script code                     |
| `requiredSignerHash(hash)`    | Add required signer (for signature checks) |
| `txInCollateral(...)`         | Set collateral UTXO for script execution   |
| `changeAddress(address)`      | Set change output address                  |
| `selectUtxosFrom(utxos)`      | Provide UTXOs for coin selection           |
| `complete()`                  | Build the transaction                      |

### Data Format

Mesh uses a structured format for Plutus data:

```typescript
interface Data {
  alternative: number;  // Constructor index (0-based)
  fields: (string | number | Data)[];  // Constructor arguments
}
```

## Troubleshooting

### "No collateral available"

Set collateral in your wallet settings. Most wallets require 5 ADA as collateral.

### "Script validation failed"

Common causes:

1. **Wrong redeemer message** - Must exactly match "Hello, World!"
2. **Missing signature** - Transaction must be signed by the datum owner
3. **Datum mismatch** - Datum hash must match what was locked

### "UTXO not found"

1. Wait for the lock transaction to confirm (1-2 blocks)
2. Verify you're querying the correct script address
3. Check the datum hash matches exactly

### "Insufficient funds for fees"

Ensure your wallet has extra ADA beyond what's being locked. Script transactions require more fees than simple transfers.

## Related Links

* <Link href="/docs/aiken/first-script">Write a Smart Contract</Link> - Create the validator used in this guide
* <Link href="/apis/transaction">Transaction Builder API</Link> - Complete MeshTxBuilder reference
* <Link href="/apis/wallets/browserwallet">Browser Wallet API</Link> - Wallet methods reference
* <Link href="https://aiken-lang.org/example--hello-world">Aiken Hello World</Link> - Official tutorial


# Mesh SDK API Reference
URL: /apis

Build Cardano applications with Mesh's comprehensive SDK for wallets, transactions, data handling, and utilities.

***

title: "Mesh SDK API Reference"
description: "Build Cardano applications with Mesh's comprehensive SDK for wallets, transactions, data handling, and utilities."
--------------------------------------------------------------------------------------------------------------------------------

import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";
import {linksApi} from "@/data/links-api";
import Link from "next/link";

## Overview

The Mesh SDK provides everything you need to build Cardano applications: wallet integrations, transaction builders, data serialization, and utility functions. Choose the APIs that fit your use case.

## Quick Start

```bash
npm install @meshsdk/core
```

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

// Connect to a browser wallet
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Initialize provider and transaction builder
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({ fetcher: provider });

// Build and submit a transaction
const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

const unsignedTx = await txBuilder
  .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);
```

## API Categories

| Category                               | Purpose                                   | Key Classes                                             |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------- |
| [Wallets](/apis/wallets)               | Connect and interact with user wallets    | `MeshCardanoBrowserWallet`, `MeshCardanoHeadlessWallet` |
| [Transaction Builder](/apis/txbuilder) | Construct and customize transactions      | `MeshTxBuilder`                                         |
| [Transaction Parser](/apis/txparser)   | Parse and test transaction data           | `MeshTxParser`, `TxTester`                              |
| [Data](/apis/data)                     | Handle Cardano data types and conversions | `MeshValue`, JSON/Mesh formats                          |
| [Utilities](/apis/utilities)           | Serialize, deserialize, and resolve data  | Serializers, deserializers, resolvers                   |

## Wallets

Connect to browser extension wallets (CIP-30) or create server-side wallets for backend applications.

```tsx
// Browser wallet (frontend)
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Headless wallet (backend)
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  mnemonic: ["..."],
});
```

[Learn more about Wallets →](/apis/wallets)

## Transaction Builder

Build any type of Cardano transaction with fine-grained control over inputs, outputs, metadata, and scripts.

```tsx
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .txOut(recipient, [{ unit: "lovelace", quantity: "5000000" }])
  .mint("1", policyId, assetName)
  .mintingScript(forgingScript)
  .metadataValue(721, metadata)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

[Learn more about Transaction Builder →](/apis/txbuilder)

## Data Handling

Work with Cardano's data types and convert between different formats.

```tsx
import { MeshValue, mConStr0 } from "@meshsdk/core";

// Work with multi-asset values
const value = new MeshValue();
value.addAsset({ unit: "lovelace", quantity: "5000000" });

// Create Plutus data
const datum = mConStr0([pubKeyHash]);
```

[Learn more about Data APIs →](/apis/data)

## Utilities

Serialize addresses, deserialize transactions, and resolve various Cardano identifiers.

```tsx
import {
  deserializeAddress,
  serializeNativeScript,
  resolveScriptHash
} from "@meshsdk/core";

// Get key hash from address
const { pubKeyHash } = deserializeAddress(address);

// Create and serialize a native script
const { address, scriptCbor } = serializeNativeScript(nativeScript);

// Get policy ID from script
const policyId = resolveScriptHash(forgingScript);
```

[Learn more about Utilities →](/apis/utilities)

## Available APIs

<div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6 items-stretch">
  {linksApi.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related

* [Providers](/providers) - Connect to blockchain data sources
* [React Integration](/react) - UI components and hooks for React apps
* [Smart Contracts](/smart-contracts) - Pre-built contract interactions
* [Guides](/guides) - Step-by-step tutorials


# Build Your First Aiken Smart Contract
URL: /guides/aiken

Write a Cardano smart contract with Aiken and interact with it using Mesh SDK. Learn to lock and unlock assets on-chain.

***

title: "Build Your First Aiken Smart Contract"
description: "Write a Cardano smart contract with Aiken and interact with it using Mesh SDK. Learn to lock and unlock assets on-chain."
---------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Build Aiken Smart Contracts for Cardano"
  description="Write a smart contract in Aiken and create transactions to lock and unlock assets on the Cardano blockchain."
  totalTime="PT60M"
  steps={[
  { name: "Install Aiken", text: "Install the Aiken CLI using aikup or cargo." },
  { name: "Create project", text: "Initialize a new Aiken project and write the validator." },
  { name: "Compile contract", text: "Build the contract to generate the Plutus blueprint." },
  { name: "Set up frontend", text: "Create a Next.js app with Mesh SDK and import the contract." },
  { name: "Lock assets", text: "Build a transaction to send assets to the script address." },
  { name: "Unlock assets", text: "Build a transaction with the correct redeemer to withdraw." }
]}
/>

## Overview

In this guide, you build a complete "Hello World" smart contract on Cardano. You write the on-chain validator in [Aiken](https://aiken-lang.org/), a modern smart contract language for Cardano, then use Mesh SDK to create transactions that lock and unlock assets on the [eUTXO model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/).

### What you will build

* An Aiken smart contract with datum and redeemer validation
* A transaction that locks ADA at the script address
* A transaction that unlocks ADA with the correct redeemer

### What you will learn

* Aiken syntax for Cardano validators
* How datums and redeemers work in Plutus contracts
* Building Plutus transactions with Mesh SDK

### Prerequisites

* [Rust](https://www.rust-lang.org/tools/install) installed (for Aiken)
* Node.js 18+ installed
* Basic TypeScript knowledge
* A Cardano wallet browser extension

### Resources

* <Link href="https://aiken-template.meshjs.dev/">Live demo</Link>
* <Link href="https://github.com/MeshJS/aiken-next-ts-template">GitHub repository</Link>

### Time to complete

60 minutes

## Quick Start

Clone the complete template:

```bash
git clone https://github.com/MeshJS/aiken-next-ts-template
cd aiken-next-ts-template
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to interact with the deployed contract.

## Step-by-Step Guide

### Step 1: Install Aiken

**On Linux or macOS:**

```bash
curl -sSfL https://install.aiken-lang.org | bash
aikup
```

**On any platform (via Cargo):**

```bash
cargo install aiken
```

Verify the installation:

```bash
aiken -V
```

**What to expect:** Aiken version information displays in the terminal.

### Step 2: Create an Aiken project

Create a new Aiken project:

```bash
aiken new meshjs/hello_world
cd hello_world
```

Verify the project structure:

```bash
aiken check
```

**What to expect:** A new directory with `aiken.toml` and a `validators` folder.

### Step 3: Write the validator

Create `validators/hello_world.ak`:

```rust
use aiken/hash.{Blake2b_224, Hash}
use aiken/list
use aiken/transaction.{ScriptContext}
use aiken/transaction/credential.{VerificationKey}

/// The datum stores the owner's public key hash
type Datum {
  owner: Hash<Blake2b_224, VerificationKey>,
}

/// The redeemer must contain the magic message
type Redeemer {
  msg: ByteArray,
}

/// The validator allows spending only when:
/// 1. The redeemer message is "Hello, World!"
/// 2. The transaction is signed by the owner
validator {
  fn hello_world(datum: Datum, redeemer: Redeemer, context: ScriptContext) -> Bool {
    let must_say_hello = redeemer.msg == "Hello, World!"

    let must_be_signed =
      list.has(context.transaction.extra_signatories, datum.owner)

    must_say_hello && must_be_signed
  }
}
```

**What to expect:** A validator file that enforces two conditions for spending.

### Step 4: Compile the contract

Build the Aiken project:

```bash
aiken build
```

**What to expect:** A `plutus.json` file is generated. This is the [CIP-0057 Plutus blueprint](https://cips.cardano.org/cip/CIP-57) containing your compiled validator.

### Step 5: Set up the frontend

Create a new Next.js project with Mesh SDK (see the <Link href="/guides/nextjs">Next.js guide</Link>):

```bash
npx meshjs my-aiken-app
cd my-aiken-app
npm install cbor
```

Copy `plutus.json` from your Aiken project to `src/data/plutus.json`.

**What to expect:** A Next.js project ready for smart contract integration.

### Step 6: Load the contract

Create `src/lib/contract.ts`:

```typescript
import {
  resolvePlutusScriptAddress,
  resolvePaymentKeyHash,
  resolveDataHash,
} from "@meshsdk/core";
import type { PlutusScript, Data } from "@meshsdk/core";
import cbor from "cbor";
import plutusBlueprint from "@/data/plutus.json";

// Encode the compiled code to CBOR format for Mesh
const scriptCbor = cbor
  .encode(Buffer.from(plutusBlueprint.validators[0].compiledCode, "hex"))
  .toString("hex");

// Create the PlutusScript object
export const script: PlutusScript = {
  code: scriptCbor,
  version: "V2",
};

// Get the script address (0 = testnet, 1 = mainnet)
export const scriptAddress = resolvePlutusScriptAddress(script, 0);

// Helper to create the datum
export function createDatum(ownerPubKeyHash: string): Data {
  return {
    alternative: 0,
    fields: [ownerPubKeyHash],
  };
}

// Helper to create the redeemer
export function createRedeemer(): Data {
  return {
    alternative: 0,
    fields: ["Hello, World!"],
  };
}
```

**What to expect:** Utility functions for working with the contract.

### Step 7: Lock assets at the script

Create a component that locks ADA at the script address:

```typescript
import { MeshTxBuilder, KoiosProvider, resolvePaymentKeyHash } from "@meshsdk/core";
import { useWallet } from "@meshsdk/react";
import { script, scriptAddress, createDatum } from "@/lib/contract";

export function LockFunds() {
  const { wallet } = useWallet();

  async function lockAda() {
    const provider = new KoiosProvider("preprod");

    // Get wallet info
    const utxos = await wallet.getUtxos();
    const changeAddress = await wallet.getChangeAddress();
    const usedAddresses = await wallet.getUsedAddresses();
    const ownerPubKeyHash = resolvePaymentKeyHash(usedAddresses[0]);

    // Create the datum with owner's public key hash
    const datum = createDatum(ownerPubKeyHash);

    // Build the transaction
    const txBuilder = new MeshTxBuilder({ fetcher: provider });

    const unsignedTx = await txBuilder
      .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
      .txOutDatumHashValue(datum)
      .changeAddress(changeAddress)
      .selectUtxosFrom(utxos)
      .complete();

    // Sign and submit
    const signedTx = await wallet.signTx(unsignedTx);
    const txHash = await wallet.submitTx(signedTx);

    console.log("Locked 5 ADA at script. TX:", txHash);
    return txHash;
  }

  return (
    <button onClick={lockAda}>
      Lock 5 ADA
    </button>
  );
}
```

**What to expect:** A button that sends 5 ADA to the script address with a datum containing your public key hash.

### Step 8: Unlock assets from the script

Create a component that unlocks ADA from the script:

```typescript
import {
  MeshTxBuilder,
  KoiosProvider,
  resolvePaymentKeyHash,
  resolveDataHash,
} from "@meshsdk/core";
import { useWallet } from "@meshsdk/react";
import { script, scriptAddress, createDatum, createRedeemer } from "@/lib/contract";

export function UnlockFunds() {
  const { wallet } = useWallet();

  async function unlockAda(lockTxHash: string) {
    const provider = new KoiosProvider("preprod");

    // Get wallet info
    const utxos = await wallet.getUtxos();
    const changeAddress = await wallet.getChangeAddress();
    const collateral = await wallet.getCollateral();
    const usedAddresses = await wallet.getUsedAddresses();
    const ownerPubKeyHash = resolvePaymentKeyHash(usedAddresses[0]);

    // Recreate the original datum
    const datum = createDatum(ownerPubKeyHash);
    const dataHash = resolveDataHash(datum);

    // Find the UTxO at the script address
    const scriptUtxos = await provider.fetchAddressUTxOs(scriptAddress, "lovelace");
    const lockedUtxo = scriptUtxos.find(
      (utxo) => utxo.output.dataHash === dataHash
    );

    if (!lockedUtxo) {
      throw new Error("No locked UTxO found for this wallet");
    }

    // Create the redeemer with the magic message
    const redeemer = createRedeemer();

    // Build the unlock transaction
    const txBuilder = new MeshTxBuilder({ fetcher: provider });

    const unsignedTx = await txBuilder
      .spendingPlutusScriptV2()
      .txIn(lockedUtxo.input.txHash, lockedUtxo.input.outputIndex)
      .txInDatumValue(datum)
      .txInRedeemerValue(redeemer)
      .txInScript(script.code)
      .txOut(changeAddress, lockedUtxo.output.amount)
      .requiredSignerHash(ownerPubKeyHash)
      .txInCollateral(
        collateral[0].input.txHash,
        collateral[0].input.outputIndex,
        collateral[0].output.amount,
        collateral[0].output.address
      )
      .changeAddress(changeAddress)
      .selectUtxosFrom(utxos)
      .complete();

    // Sign with partial signing (required for Plutus scripts)
    const signedTx = await wallet.signTx(unsignedTx, true);
    const txHash = await wallet.submitTx(signedTx);

    console.log("Unlocked ADA from script. TX:", txHash);
    return txHash;
  }

  return (
    <button onClick={() => unlockAda("your-lock-tx-hash")}>
      Unlock ADA
    </button>
  );
}
```

**What to expect:** A button that withdraws the locked ADA using the correct redeemer message.

## Complete Example

Here is a complete page component:

```typescript
import { useState } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";
import {
  MeshTxBuilder,
  KoiosProvider,
  resolvePaymentKeyHash,
  resolveDataHash,
} from "@meshsdk/core";
import { script, scriptAddress, createDatum, createRedeemer } from "@/lib/contract";

export default function HelloWorldContract() {
  const { wallet, connected } = useWallet();
  const [lockTxHash, setLockTxHash] = useState<string>("");
  const [loading, setLoading] = useState(false);

  const provider = new KoiosProvider("preprod");

  async function lockAda() {
    setLoading(true);
    try {
      const utxos = await wallet.getUtxos();
      const changeAddress = await wallet.getChangeAddress();
      const usedAddresses = await wallet.getUsedAddresses();
      const ownerPubKeyHash = resolvePaymentKeyHash(usedAddresses[0]);

      const datum = createDatum(ownerPubKeyHash);
      const txBuilder = new MeshTxBuilder({ fetcher: provider });

      const unsignedTx = await txBuilder
        .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
        .txOutDatumHashValue(datum)
        .changeAddress(changeAddress)
        .selectUtxosFrom(utxos)
        .complete();

      const signedTx = await wallet.signTx(unsignedTx);
      const txHash = await wallet.submitTx(signedTx);
      setLockTxHash(txHash);
    } finally {
      setLoading(false);
    }
  }

  async function unlockAda() {
    setLoading(true);
    try {
      const utxos = await wallet.getUtxos();
      const changeAddress = await wallet.getChangeAddress();
      const collateral = await wallet.getCollateral();
      const usedAddresses = await wallet.getUsedAddresses();
      const ownerPubKeyHash = resolvePaymentKeyHash(usedAddresses[0]);

      const datum = createDatum(ownerPubKeyHash);
      const dataHash = resolveDataHash(datum);
      const scriptUtxos = await provider.fetchAddressUTxOs(scriptAddress, "lovelace");
      const lockedUtxo = scriptUtxos.find((u) => u.output.dataHash === dataHash);

      if (!lockedUtxo) throw new Error("No locked UTxO found");

      const redeemer = createRedeemer();
      const txBuilder = new MeshTxBuilder({ fetcher: provider });

      const unsignedTx = await txBuilder
        .spendingPlutusScriptV2()
        .txIn(lockedUtxo.input.txHash, lockedUtxo.input.outputIndex)
        .txInDatumValue(datum)
        .txInRedeemerValue(redeemer)
        .txInScript(script.code)
        .txOut(changeAddress, lockedUtxo.output.amount)
        .requiredSignerHash(ownerPubKeyHash)
        .txInCollateral(
          collateral[0].input.txHash,
          collateral[0].input.outputIndex,
          collateral[0].output.amount,
          collateral[0].output.address
        )
        .changeAddress(changeAddress)
        .selectUtxosFrom(utxos)
        .complete();

      const signedTx = await wallet.signTx(unsignedTx, true);
      await wallet.submitTx(signedTx);
    } finally {
      setLoading(false);
    }
  }

  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-4">Hello World Contract</h1>

      <CardanoWallet />

      {connected && (
        <div className="mt-4 space-x-4">
          <button
            onClick={lockAda}
            disabled={loading}
            className="px-4 py-2 bg-blue-500 text-white rounded"
          >
            Lock 5 ADA
          </button>

          <button
            onClick={unlockAda}
            disabled={loading}
            className="px-4 py-2 bg-green-500 text-white rounded"
          >
            Unlock ADA
          </button>
        </div>
      )}

      {lockTxHash && (
        <p className="mt-4">
          Lock TX: <a href={`https://preprod.cardanoscan.io/transaction/${lockTxHash}`}>{lockTxHash}</a>
        </p>
      )}
    </main>
  );
}
```

## Next Steps

* <Link href="https://aiken-lang.org/example--hello-world/basics">Aiken documentation</Link> - Learn more Aiken syntax
* <Link href="/guides/vesting">Build a vesting contract</Link> - Time-locked fund release
* <Link href="/guides/smart-contract-transactions">NFT marketplace transactions</Link> - List, buy, cancel patterns
* <Link href="/apis/txbuilder">Transaction Builder API</Link> - Advanced transaction patterns

## Troubleshooting

### Script validation failed

**Cause:** The redeemer message does not match "Hello, World!" exactly.

**Solution:** Ensure the redeemer message is exactly "Hello, World!" with the comma and exclamation mark.

### No collateral available

**Cause:** The wallet has no collateral set.

**Solution:** Enable collateral in your wallet settings. Most wallets require at least 5 ADA as collateral.

### UTxO not found

**Cause:** The locked UTxO was already spent or the datum hash does not match.

**Solution:** Ensure you are using the same wallet that locked the funds. The datum includes the owner's public key hash.

### CBOR encoding error

**Cause:** The `cbor` package is not installed or import is incorrect.

**Solution:** Install the package:

```bash
npm install cbor
```

### Aiken check fails

**Cause:** Syntax error in the Aiken code.

**Solution:** Run `aiken check` to see detailed error messages. Common issues:

* Missing imports
* Type mismatches
* Incorrect function signatures

## References

* [Aiken Smart Contract Language](https://aiken-lang.org/) - Official Aiken documentation, tutorials, and installation instructions
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources and smart contract guides
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the extended UTXO model for smart contracts
* [CIP-0057: Plutus Blueprint](https://cips.cardano.org/cip/CIP-57) - Standard for compiled Plutus contract output format

## Related Links

* <Link href="https://github.com/MeshJS/aiken-next-ts-template">Complete source code</Link>
* <Link href="https://aiken-lang.org/installation-instructions">Aiken installation guide</Link>
* <Link href="https://cips.cardano.org/cip/CIP-57">CIP-0057 Plutus Blueprint</Link>
* <Link href="/guides/vesting">Vesting Contract Guide</Link>


# Build a Custom Blockchain Provider
URL: /guides/custom-provider

Create custom providers to connect Mesh SDK to any data source. Implement IFetcher and ISubmitter interfaces for your own infrastructure.

***

title: "Build a Custom Blockchain Provider"
description: "Create custom providers to connect Mesh SDK to any data source. Implement IFetcher and ISubmitter interfaces for your own infrastructure."
--------------------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Build a Custom Blockchain Provider"
  description="Create a custom provider class that implements Mesh SDK interfaces to connect to any blockchain data source."
  totalTime="PT60M"
  steps={[
  { name: "Understand interfaces", text: "Review IFetcher and ISubmitter interface requirements." },
  { name: "Create provider class", text: "Create a TypeScript class implementing the required interfaces." },
  { name: "Initialize constructor", text: "Set up network endpoints, API keys, and HTTP client." },
  { name: "Implement methods", text: "Map your data source responses to Mesh's expected types." },
  { name: "Test provider", text: "Verify each method returns correctly typed data." }
]}
/>

## Overview

In this guide, you build a custom provider class that connects Mesh SDK to your own blockchain data source. Custom providers let you use GraphQL endpoints, cardano-cli, websockets, or your own infrastructure while maintaining full compatibility with Mesh's transaction builder.

### What you will build

* A TypeScript provider class implementing `IFetcher` and `ISubmitter`
* Methods to fetch UTxOs, protocol parameters, and account info
* Transaction submission to the Cardano network

### What you will learn

* How provider interfaces work in Mesh SDK
* Data mapping between external APIs and Mesh types
* Error handling patterns for blockchain queries

### Prerequisites

* TypeScript project set up with Mesh SDK
* Understanding of your target data source's API
* Basic knowledge of Cardano data structures

### Time to complete

60 minutes

## Quick Start

Here is a minimal custom provider template:

```typescript
import type {
  AccountInfo,
  AssetMetadata,
  Protocol,
  UTxO,
} from "@meshsdk/core";
import { IFetcher, ISubmitter } from "@meshsdk/core";

export class CustomProvider implements IFetcher, ISubmitter {
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  async fetchAccountInfo(address: string): Promise<AccountInfo> {
    // Implement your logic
    throw new Error("Not implemented");
  }

  async fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]> {
    // Implement your logic
    throw new Error("Not implemented");
  }

  async fetchAssetAddresses(asset: string): Promise<{ address: string; quantity: string }[]> {
    throw new Error("Not implemented");
  }

  async fetchAssetMetadata(asset: string): Promise<AssetMetadata> {
    throw new Error("Not implemented");
  }

  async fetchHandleAddress(handle: string): Promise<string> {
    throw new Error("Not implemented");
  }

  async fetchProtocolParameters(epoch?: number): Promise<Protocol> {
    // Implement your logic
    throw new Error("Not implemented");
  }

  async submitTx(tx: string): Promise<string> {
    // Implement your logic
    throw new Error("Not implemented");
  }
}
```

## Step-by-Step Guide

### Step 1: Understand the interfaces

Provider interfaces define the contract your class must follow. Any class implementing an interface must include all specified methods with matching signatures.

**IFetcher interface** - Query blockchain data:

```typescript
import type {
  AccountInfo,
  AssetMetadata,
  Protocol,
  UTxO,
} from "@meshsdk/core";

export interface IFetcher {
  fetchAccountInfo(address: string): Promise<AccountInfo>;
  fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>;
  fetchAssetAddresses(asset: string): Promise<{ address: string; quantity: string }[]>;
  fetchAssetMetadata(asset: string): Promise<AssetMetadata>;
  fetchHandleAddress(handle: string): Promise<string>;
  fetchProtocolParameters(epoch?: number): Promise<Protocol>;
}
```

**ISubmitter interface** - Submit transactions:

```typescript
export interface ISubmitter {
  submitTx(tx: string): Promise<string>;
}
```

**What to expect:** Your provider must implement all methods from the interfaces you choose to implement.

### Step 2: Create the provider class

Create a new file `src/providers/custom-provider.ts`:

```typescript
import type {
  AccountInfo,
  AssetMetadata,
  Protocol,
  UTxO,
} from "@meshsdk/core";
import { IFetcher, ISubmitter } from "@meshsdk/core";
import axios, { AxiosInstance } from "axios";

export class CustomProvider implements IFetcher, ISubmitter {
  private readonly axiosInstance: AxiosInstance;

  constructor(baseUrl: string, apiKey?: string) {
    this.axiosInstance = axios.create({
      baseURL: baseUrl,
      headers: apiKey ? { "Authorization": `Bearer ${apiKey}` } : {},
    });
  }

  // Methods will be implemented in the following steps
}
```

Install axios if you have not already:

```bash
npm install axios
```

**What to expect:** A provider class with HTTP client configured and ready for method implementation.

### Step 3: Implement fetchAddressUTxOs

This method retrieves all UTxOs for an address. It is the most commonly used fetcher method.

```typescript
async fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]> {
  try {
    // Example: query your API for UTxOs
    const { data } = await this.axiosInstance.get(`/addresses/${address}/utxos`, {
      params: asset ? { asset } : {},
    });

    // Map your API response to Mesh's UTxO type
    return data.map((utxo: any): UTxO => ({
      input: {
        outputIndex: utxo.output_index,
        txHash: utxo.tx_hash,
      },
      output: {
        address: utxo.address,
        amount: utxo.amount.map((a: any) => ({
          unit: a.unit,
          quantity: a.quantity,
        })),
        dataHash: utxo.data_hash || undefined,
        plutusData: utxo.inline_datum || undefined,
        scriptRef: utxo.reference_script || undefined,
        scriptHash: utxo.script_hash || undefined,
      },
    }));
  } catch (error) {
    console.error("Failed to fetch UTxOs:", error);
    throw error;
  }
}
```

**What to expect:** An array of UTxO objects with the correct structure for Mesh.

### Step 4: Implement fetchProtocolParameters

This method retrieves current protocol parameters used for transaction building.

```typescript
async fetchProtocolParameters(epoch?: number): Promise<Protocol> {
  try {
    const { data } = await this.axiosInstance.get("/protocol-parameters", {
      params: epoch ? { epoch } : {},
    });

    // Map your API response to Mesh's Protocol type
    return {
      coinsPerUTxOSize: data.coins_per_utxo_size,
      collateralPercent: data.collateral_percent,
      decentralisation: data.decentralisation || 0,
      epoch: data.epoch_no,
      keyDeposit: data.key_deposit,
      maxBlockExMem: data.max_block_ex_mem.toString(),
      maxBlockExSteps: data.max_block_ex_steps.toString(),
      maxBlockHeaderSize: data.max_bh_size,
      maxBlockSize: data.max_block_size,
      maxCollateralInputs: data.max_collateral_inputs,
      maxTxExMem: data.max_tx_ex_mem.toString(),
      maxTxExSteps: data.max_tx_ex_steps.toString(),
      maxTxSize: data.max_tx_size,
      maxValSize: data.max_val_size.toString(),
      minFeeA: data.min_fee_a,
      minFeeB: data.min_fee_b,
      minPoolCost: data.min_pool_cost,
      poolDeposit: data.pool_deposit,
      priceMem: data.price_mem,
      priceStep: data.price_step,
    };
  } catch (error) {
    console.error("Failed to fetch protocol parameters:", error);
    throw error;
  }
}
```

**What to expect:** A Protocol object with all required fields for transaction building.

### Step 5: Implement fetchAccountInfo

This method retrieves staking information for an address.

```typescript
async fetchAccountInfo(address: string): Promise<AccountInfo> {
  try {
    const { data } = await this.axiosInstance.get(`/accounts/${address}`);

    return {
      active: data.active,
      balance: data.controlled_amount,
      rewards: data.withdrawable_amount,
      poolId: data.pool_id || undefined,
    };
  } catch (error) {
    console.error("Failed to fetch account info:", error);
    throw error;
  }
}
```

**What to expect:** Account staking details including balance and rewards.

### Step 6: Implement submitTx

This method submits signed transactions to the network.

```typescript
async submitTx(tx: string): Promise<string> {
  try {
    const { data, status } = await this.axiosInstance.post(
      "/tx/submit",
      tx,
      {
        headers: {
          "Content-Type": "application/cbor",
        },
      }
    );

    if (status === 200 || status === 202) {
      return data.tx_hash || data;
    }

    throw new Error(`Submission failed with status ${status}`);
  } catch (error: any) {
    if (error.response?.data) {
      throw new Error(`Transaction rejected: ${JSON.stringify(error.response.data)}`);
    }
    throw error;
  }
}
```

**What to expect:** The transaction hash on successful submission.

### Step 7: Implement remaining methods

Complete the provider with the remaining interface methods:

```typescript
async fetchAssetAddresses(asset: string): Promise<{ address: string; quantity: string }[]> {
  try {
    const { data } = await this.axiosInstance.get(`/assets/${asset}/addresses`);

    return data.map((item: any) => ({
      address: item.address,
      quantity: item.quantity,
    }));
  } catch (error) {
    console.error("Failed to fetch asset addresses:", error);
    throw error;
  }
}

async fetchAssetMetadata(asset: string): Promise<AssetMetadata> {
  try {
    const { data } = await this.axiosInstance.get(`/assets/${asset}`);

    return {
      ...data.onchain_metadata,
    };
  } catch (error) {
    console.error("Failed to fetch asset metadata:", error);
    throw error;
  }
}

async fetchHandleAddress(handle: string): Promise<string> {
  try {
    // ADA Handle resolution - format handle name without $
    const handleName = handle.replace(/^\$/, "");
    const { data } = await this.axiosInstance.get(`/handles/${handleName}`);

    return data.address;
  } catch (error) {
    console.error("Failed to fetch handle address:", error);
    throw error;
  }
}
```

**What to expect:** A complete provider implementing all required methods.

## Complete Example

Here is the complete custom provider implementation:

```typescript
import type {
  AccountInfo,
  AssetMetadata,
  Protocol,
  UTxO,
} from "@meshsdk/core";
import { IFetcher, ISubmitter } from "@meshsdk/core";
import axios, { AxiosInstance } from "axios";

export class CustomProvider implements IFetcher, ISubmitter {
  private readonly axiosInstance: AxiosInstance;

  constructor(baseUrl: string, apiKey?: string) {
    this.axiosInstance = axios.create({
      baseURL: baseUrl,
      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
      timeout: 30000,
    });
  }

  async fetchAccountInfo(address: string): Promise<AccountInfo> {
    try {
      const { data } = await this.axiosInstance.get(`/accounts/${address}`);
      return {
        active: data.active,
        balance: data.controlled_amount,
        rewards: data.withdrawable_amount,
        poolId: data.pool_id || undefined,
      };
    } catch (error) {
      console.error("Failed to fetch account info:", error);
      throw error;
    }
  }

  async fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]> {
    try {
      const { data } = await this.axiosInstance.get(`/addresses/${address}/utxos`, {
        params: asset ? { asset } : {},
      });

      return data.map((utxo: any): UTxO => ({
        input: {
          outputIndex: utxo.output_index,
          txHash: utxo.tx_hash,
        },
        output: {
          address: utxo.address,
          amount: utxo.amount.map((a: any) => ({
            unit: a.unit,
            quantity: a.quantity,
          })),
          dataHash: utxo.data_hash || undefined,
          plutusData: utxo.inline_datum || undefined,
          scriptRef: utxo.reference_script || undefined,
          scriptHash: utxo.script_hash || undefined,
        },
      }));
    } catch (error) {
      console.error("Failed to fetch UTxOs:", error);
      throw error;
    }
  }

  async fetchAssetAddresses(
    asset: string
  ): Promise<{ address: string; quantity: string }[]> {
    try {
      const { data } = await this.axiosInstance.get(`/assets/${asset}/addresses`);
      return data.map((item: any) => ({
        address: item.address,
        quantity: item.quantity,
      }));
    } catch (error) {
      console.error("Failed to fetch asset addresses:", error);
      throw error;
    }
  }

  async fetchAssetMetadata(asset: string): Promise<AssetMetadata> {
    try {
      const { data } = await this.axiosInstance.get(`/assets/${asset}`);
      return { ...data.onchain_metadata };
    } catch (error) {
      console.error("Failed to fetch asset metadata:", error);
      throw error;
    }
  }

  async fetchHandleAddress(handle: string): Promise<string> {
    try {
      const handleName = handle.replace(/^\$/, "");
      const { data } = await this.axiosInstance.get(`/handles/${handleName}`);
      return data.address;
    } catch (error) {
      console.error("Failed to fetch handle address:", error);
      throw error;
    }
  }

  async fetchProtocolParameters(epoch?: number): Promise<Protocol> {
    try {
      const { data } = await this.axiosInstance.get("/protocol-parameters", {
        params: epoch ? { epoch } : {},
      });

      return {
        coinsPerUTxOSize: data.coins_per_utxo_size,
        collateralPercent: data.collateral_percent,
        decentralisation: data.decentralisation || 0,
        epoch: data.epoch_no,
        keyDeposit: data.key_deposit,
        maxBlockExMem: data.max_block_ex_mem.toString(),
        maxBlockExSteps: data.max_block_ex_steps.toString(),
        maxBlockHeaderSize: data.max_bh_size,
        maxBlockSize: data.max_block_size,
        maxCollateralInputs: data.max_collateral_inputs,
        maxTxExMem: data.max_tx_ex_mem.toString(),
        maxTxExSteps: data.max_tx_ex_steps.toString(),
        maxTxSize: data.max_tx_size,
        maxValSize: data.max_val_size.toString(),
        minFeeA: data.min_fee_a,
        minFeeB: data.min_fee_b,
        minPoolCost: data.min_pool_cost,
        poolDeposit: data.pool_deposit,
        priceMem: data.price_mem,
        priceStep: data.price_step,
      };
    } catch (error) {
      console.error("Failed to fetch protocol parameters:", error);
      throw error;
    }
  }

  async submitTx(tx: string): Promise<string> {
    try {
      const { data, status } = await this.axiosInstance.post("/tx/submit", tx, {
        headers: { "Content-Type": "application/cbor" },
      });

      if (status === 200 || status === 202) {
        return data.tx_hash || data;
      }

      throw new Error(`Submission failed with status ${status}`);
    } catch (error: any) {
      if (error.response?.data) {
        throw new Error(`Transaction rejected: ${JSON.stringify(error.response.data)}`);
      }
      throw error;
    }
  }
}
```

Use the custom provider with Mesh:

```typescript
import { MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import { CustomProvider } from "./providers/custom-provider";

const provider = new CustomProvider("https://your-api.com", "your-api-key");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await provider.submitTx(signedTx);
```

## Troubleshooting

### Type mismatches in return values

**Cause:** Your API response structure differs from Mesh's expected types.

**Solution:** Check the type definitions in `@meshsdk/core`. Map each field explicitly in your implementation. Use TypeScript's strict mode to catch mismatches.

### Network timeout errors

**Cause:** API requests take too long or the endpoint is unreachable.

**Solution:** Configure appropriate timeouts in your axios instance. Implement retry logic for transient failures:

```typescript
import axiosRetry from "axios-retry";

axiosRetry(this.axiosInstance, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
});
```

### Transaction submission returns error

**Cause:** The transaction is malformed or fails validation.

**Solution:** Parse the error response from your API. Common issues include insufficient funds, missing collateral, or script validation failures. Log the full error for debugging.

### Missing optional fields cause errors

**Cause:** Your API does not return all fields that Mesh expects.

**Solution:** Use optional chaining and provide defaults:

```typescript
dataHash: utxo.data_hash || undefined,
scriptRef: utxo.reference_script ?? undefined,
```

### Rate limiting from your API

**Cause:** Too many requests in a short period.

**Solution:** Implement request queuing or caching for frequently accessed data like protocol parameters:

```typescript
private protocolParamsCache: { params: Protocol; timestamp: number } | null = null;
private CACHE_TTL = 60000; // 1 minute

async fetchProtocolParameters(epoch?: number): Promise<Protocol> {
  if (this.protocolParamsCache &&
      Date.now() - this.protocolParamsCache.timestamp < this.CACHE_TTL) {
    return this.protocolParamsCache.params;
  }

  const params = await this.fetchProtocolParametersFromApi(epoch);
  this.protocolParamsCache = { params, timestamp: Date.now() };
  return params;
}
```

## Related Links

* <Link href="https://github.com/MeshJS/mesh/tree/main/packages/mesh-provider/src">Existing provider implementations</Link>
* <Link href="/providers">Built-in providers documentation</Link>
* <Link href="/apis/txbuilder">Transaction Builder API</Link>
* <Link href="https://github.com/MeshJS/mesh/pulls">Submit your provider as a PR</Link>


# Cardano SDK Guides: Build dApps with TypeScript
URL: /guides

Cardano dApp development tutorials with Mesh SDK. Build smart contracts, mint NFTs, and integrate wallets using TypeScript.

***

title: "Cardano SDK Guides: Build dApps with TypeScript"
description: "Cardano dApp development tutorials with Mesh SDK. Build smart contracts, mint NFTs, and integrate wallets using TypeScript."
icon: BookOpenIcon
------------------

import {linksGuides} from "@/data/links-guides";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Mesh is an open-source TypeScript SDK for building decentralized applications on Cardano. These guides walk you through wallet integration, NFT minting, smart contract development, and production deployment.

### What you can build

| Category               | Description                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| **Wallet Integration** | Connect browser wallets, authenticate users with signatures        |
| **NFT Minting**        | Create native tokens and mint NFT collections                      |
| **Smart Contracts**    | Interact with Plutus and Aiken contracts for vesting, marketplaces |
| **Multi-Signature**    | Coordinate transactions requiring multiple wallet signatures       |
| **Production Apps**    | Security best practices and performance optimization               |

### Prerequisites

Before starting any guide, ensure you have:

* Node.js 18+ or Bun installed
* A code editor (VS Code recommended)
* A Cardano wallet browser extension (Eternl, Nami, or Lace)
* Basic TypeScript/JavaScript knowledge

## Quick Start

Get a complete project running in under 2 minutes:

```bash
npx meshjs your-app-name
cd your-app-name
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to see your Cardano dApp.

## Guides by Category

### Getting Started

* [Build Your First dApp with Next.js](/guides/nextjs) - Set up a Next.js app with wallet connection
* [Run Standalone Scripts](/guides/standalone) - Execute TypeScript scripts directly
* [Fix Node.js Polyfill Errors](/guides/node-specific-imports) - Resolve Buffer and crypto errors

### NFT & Token Minting

* [Mint an NFT Collection](/guides/nft-collection) - Create CIP-25 compliant NFTs
* [Server-Side Minting with Node.js](/guides/minting-on-nodejs) - Mint and distribute tokens from backend
* [Multi-Signature Minting](/guides/multisig-minting) - Coordinate browser and server wallet signatures

### Smart Contracts

* [Getting Started with Aiken](/guides/aiken) - Write and deploy your first smart contract
* [Build a Vesting Contract](/guides/vesting) - Time-locked fund release
* [NFT Marketplace Transactions](/guides/smart-contract-transactions) - List, buy, cancel, update NFTs

### Authentication & Security

* [Prove Wallet Ownership](/guides/prove-wallet-ownership) - Sign-in with Cardano using CIP-8
* [Production Deployment](/guides/production-deployment) - Security checklist and best practices

### Integration & Migration

* [Create a Custom Provider](/guides/custom-provider) - Connect any blockchain data source
* [Migrate from Lucid](/guides/migrate-from-lucid) - API mapping and migration patterns
* [Compare Mesh with Alternatives](/guides/mesh-vs-alternatives) - Choose the right SDK

## All Guides

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksGuides.map((card) => {
      const Icon = card.icon;
      return (
        <Link key={card.title} href={card.link} className="no-underline">
          <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
            {Icon && (
              <div className="flex justify-center mb-4">
                <Icon className="w-12 h-12 text-primary" />
              </div>
            )}
            <CardTitle className="font-heading">{card.title}</CardTitle>
            <CardDescription>{card.desc}</CardDescription>
          </Card>
        </Link>
      );
    })}
</div>

## Next Steps

After completing a guide:

* Explore the [Transaction Builder API](/apis/txbuilder) for advanced transaction patterns
* Check the [Wallet APIs](/apis/wallets) for complete wallet functionality
* Join the [Mesh Discord](https://discord.gg/dH48jH3BKa) for community support

## Related Links

* [API Reference](/apis) - Complete SDK documentation
* [GitHub Repository](https://github.com/MeshJS/mesh) - Source code and examples
* [Cardano Developer Portal](https://developers.cardano.org/) - Cardano ecosystem resources


# Mesh vs Cardano SDK Alternatives
URL: /guides/mesh-vs-alternatives

Compare Mesh SDK with cardano-serialization-lib, Lucid, Pallas, and other Cardano development tools to choose the right one for your project.

***

title: "Mesh vs Cardano SDK Alternatives"
description: "Compare Mesh SDK with cardano-serialization-lib, Lucid, Pallas, and other Cardano development tools to choose the right one for your project."
------------------------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Choose the Right Cardano SDK for Your Project"
  description="Compare Mesh SDK with alternatives like cardano-serialization-lib, Lucid, Pallas, and cardano-cli."
  totalTime="PT10M"
  steps={[
  { name: "Review quick comparison", text: "Compare tools by language, level, and best use case." },
  { name: "Evaluate specific needs", text: "Match your requirements to each tool's strengths." },
  { name: "Consider combining tools", text: "Many projects use multiple tools for different layers." },
  { name: "Choose your starting point", text: "Select the primary SDK for your project." }
]}
/>

## Overview

Choosing the right Cardano SDK impacts your development speed, maintainability, and application performance. This guide compares Mesh with alternative tools to help you make an informed decision.

### What you will learn

* How each Cardano development tool differs
* When to choose Mesh over alternatives
* How to combine multiple tools effectively

### Time to complete

10 minutes reading

## Quick Comparison

| Tool                          | Language   | Level | Best For                    |
| ----------------------------- | ---------- | ----- | --------------------------- |
| **Mesh**                      | TypeScript | High  | Full-stack dApp development |
| **cardano-serialization-lib** | Rust/WASM  | Low   | Transaction serialization   |
| **Lucid**                     | TypeScript | High  | Transaction building        |
| **Pallas**                    | Rust       | Low   | Backend infrastructure      |
| **cardano-cli**               | Shell      | Low   | Node operations             |
| **Aiken**                     | Aiken      | N/A   | Smart contract authoring    |

## Mesh vs cardano-serialization-lib

**cardano-serialization-lib (CSL)** is Emurgo's Rust library compiled to WebAssembly. It provides low-level primitives for constructing and serializing Cardano transactions.

### When to choose CSL

* Maximum performance where WASM speed matters
* Custom transaction formats or experimental features
* Building your own higher-level abstraction
* Wallet implementations needing fine-grained control

### When to choose Mesh

* Building web applications or dApp frontends
* Need pre-built React or Svelte components
* Want provider abstraction and easy switching
* Developing with Aiken smart contracts
* Value comprehensive documentation

### Feature comparison

| Feature              | Mesh               | CSL                 |
| -------------------- | ------------------ | ------------------- |
| Transaction building | High-level builder | Manual construction |
| Wallet connection    | Built-in CIP-30    | Must implement      |
| Provider integration | Multiple included  | DIY                 |
| UI components        | React/Svelte       | None                |
| Learning curve       | Gentle             | Steep               |
| Bundle size          | Includes deps      | Minimal WASM        |

**Note:** Mesh uses CSL internally for serialization. You get CSL's reliability with Mesh's usability.

## Mesh vs Lucid

**Lucid** is another TypeScript SDK for Cardano with similar goals to Mesh.

### Architectural differences

**Lucid** combines provider and wallet in a single configured instance:

```typescript
// Lucid pattern
const lucid = await Lucid.new(provider, "Preprod");
await lucid.selectWallet(walletApi);
```

**Mesh** separates these concerns:

```typescript
// Mesh pattern
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("key");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const txBuilder = new MeshTxBuilder({ fetcher: provider });
```

This separation enables:

* Swapping providers without changing wallet code
* Using different wallets with the same transaction logic
* Testing transactions without blockchain connectivity

### Feature comparison

| Feature           | Mesh                     | Lucid       |
| ----------------- | ------------------------ | ----------- |
| React components  | Official package         | Community   |
| Svelte support    | Official package         | Community   |
| Provider options  | 5+ providers             | 3 providers |
| Testing utilities | TxTester, OfflineFetcher | Emulator    |
| Aiken integration | Blueprint parsing        | Manual      |
| Maintenance       | Active                   | Varies      |

### Migration path

If you have a Lucid application, see the <Link href="/guides/migrate-from-lucid">migration guide</Link>.

## Mesh vs Pallas

**Pallas** is a Rust library for low-level Cardano network interaction - chain sync, block parsing, and transaction submission.

### When to choose Pallas

* Blockchain indexers and explorers
* Custom node implementations
* High-performance data processing
* Rust-based backend services

### When to choose Mesh

* Web application development
* Wallet interactions
* Transaction building in JavaScript
* Rapid prototyping

These tools complement rather than compete. Use Pallas for backend infrastructure and Mesh for client-facing applications.

## Mesh vs cardano-cli

**cardano-cli** is the official command-line tool for Cardano node operations.

### When to use cardano-cli

* Stake pool operations
* Direct node interaction and queries
* Scripting operational workflows
* Protocol parameter inspection

### When to use Mesh

* Building web and mobile applications
* Programmatic transaction construction
* Integrating wallets into applications
* Any scenario requiring JavaScript/TypeScript

For backend scripts, use Mesh in Node.js rather than parsing CLI output.

## Mesh and Aiken

**Aiken** is a smart contract language for Cardano, not a transaction library. You need both for dApp development.

### The relationship

Aiken compiles smart contracts. You still need a tool to:

* Build transactions that interact with contracts
* Serialize datums and redeemers
* Query the blockchain for UTxOs
* Connect to wallets for signing

Mesh provides Aiken integration:

* Parse Aiken blueprints for type-safe interaction
* Apply parameters to parameterized validators
* Construct properly formatted datums and redeemers
* Test transactions with contract validation

**Use Aiken for writing contracts, Mesh for building transactions that use them.**

## Decision Guide

### Choose Mesh when you are

* Building a web application or dApp frontend
* Want TypeScript with strong type safety
* Need pre-built React or Svelte components
* Developing with Aiken smart contracts
* Prefer higher-level abstractions
* Value comprehensive documentation

### Choose alternatives when you need

* **CSL** - Maximum performance or building low-level tooling
* **Lucid** - Already invested in Lucid ecosystem
* **Pallas** - Building Rust backend infrastructure
* **cardano-cli** - Operating stake pools or direct node interaction

### Combining tools

Many projects combine tools:

* Mesh for frontend + Pallas for backend indexing
* Mesh for most transactions + CSL for specific optimizations
* Mesh for development + cardano-cli for deployment scripts

## Getting Started with Mesh

If Mesh fits your needs:

1. <Link href="/guides/nextjs">Next.js Integration Guide</Link> - Build your first Cardano dApp
2. <Link href="/apis/txbuilder">Transaction Builder API</Link> - Learn transaction construction
3. <Link href="/guides/aiken">Aiken Integration Guide</Link> - Work with smart contracts

The Mesh SDK balances developer productivity with capability. Most Cardano dApps can be built entirely with Mesh, reserving lower-level tools for specific optimization needs.

## References

* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources and SDK overview
* [Cardano Developer Portal: SDKs and Tools](https://developers.cardano.org/tools/) - Comprehensive listing of Cardano development tools
* [MeshJS GitHub Repository](https://github.com/MeshJS/mesh) - Mesh SDK source code, issues, and contributions

## Related Links

* <Link href="/guides/nextjs">Getting Started with Next.js</Link>
* <Link href="/guides/migrate-from-lucid">Migrating from Lucid</Link>
* <Link href="/apis/txbuilder">Transaction Builder API</Link>
* <Link href="/guides/aiken">Aiken Smart Contracts</Link>


# Migrate from Lucid to Mesh
URL: /guides/migrate-from-lucid

Step-by-step migration guide from Lucid to Mesh SDK with API mapping, code examples, and common patterns.

***

title: "Migrate from Lucid to Mesh"
description: "Step-by-step migration guide from Lucid to Mesh SDK with API mapping, code examples, and common patterns."
------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Migrate from Lucid to Mesh"
  description="Step-by-step migration guide from Lucid to Mesh with API mapping and code patterns."
  totalTime="PT120M"
  steps={[
  { name: "Install Mesh packages", text: "Install @meshsdk/core and @meshsdk/react." },
  { name: "Replace provider setup", text: "Configure BlockfrostProvider, KoiosProvider, or another provider." },
  { name: "Update wallet connection", text: "Use MeshCardanoBrowserWallet or React hooks instead of Lucid wallet selection." },
  { name: "Refactor transactions", text: "Map Lucid methods to Mesh MeshTxBuilder equivalents." },
  { name: "Update smart contract code", text: "Adjust script loading and datum handling for Mesh patterns." },
  { name: "Replace serialization", text: "Use Mesh serialization utilities." },
  { name: "Update tests", text: "Migrate from Lucid Emulator to Mesh testing tools." }
]}
/>

## Overview

In this guide, you migrate an existing Cardano application from Lucid to Mesh SDK. Mesh separates transaction building, wallet interaction, and blockchain queries into distinct components, giving you more flexibility in how you structure your application.

### What you will learn

* How Lucid concepts map to Mesh equivalents
* Key differences in API design and architecture
* Step-by-step migration patterns for common operations
* How to update tests and smart contract code

### Prerequisites

* An existing application using Lucid
* Node.js 18+ installed
* Basic TypeScript knowledge

### Time to complete

2 hours (varies based on application complexity)

## Quick Start

Install Mesh packages alongside your existing Lucid installation:

```bash
npm install @meshsdk/core @meshsdk/react
```

You can migrate incrementally, using both libraries during the transition.

## Step-by-Step Guide

### Step 1: Understand the architectural differences

**Lucid** combines provider and wallet in a single configured instance:

```typescript
// Lucid pattern
const lucid = await Lucid.new(
  new Blockfrost("https://cardano-preprod.blockfrost.io/api", "key"),
  "Preprod"
);
await lucid.selectWallet(walletApi);
const tx = await lucid.newTx().payToAddress(...).complete();
```

**Mesh** separates these concerns:

```typescript
// Mesh pattern
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("key");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const txBuilder = new MeshTxBuilder({ fetcher: provider });
```

**Why this matters:** You can swap providers without changing wallet code, and test transactions without blockchain connectivity.

### Step 2: Install Mesh packages

Add Mesh to your project:

```bash
npm install @meshsdk/core @meshsdk/react
```

For React applications, `@meshsdk/react` provides wallet components and hooks.

**What to expect:** Both Lucid and Mesh can coexist during migration.

### Step 3: Replace provider setup

**Lucid:**

```typescript
import { Blockfrost, Lucid } from "lucid-cardano";

const lucid = await Lucid.new(
  new Blockfrost("https://cardano-preprod.blockfrost.io/api", "project_key"),
  "Preprod"
);
```

**Mesh:**

```typescript
import { BlockfrostProvider } from "@meshsdk/core";

// Preprod
const provider = new BlockfrostProvider("project_key_preprod");

// Mainnet
const providerMainnet = new BlockfrostProvider("project_key_mainnet");

// Preview
const providerPreview = new BlockfrostProvider("project_key_preview");
```

Mesh auto-detects the network from your API key prefix. Alternative providers:

```typescript
import { KoiosProvider, MaestroProvider, OgmiosProvider } from "@meshsdk/core";

const koios = new KoiosProvider("preprod");
const maestro = new MaestroProvider({ apiKey: "key", network: "Preprod" });
const ogmios = new OgmiosProvider("ws://localhost:1337");
```

**What to expect:** Provider instances ready to pass to transaction builders.

### Step 4: Update wallet connection

**Lucid:**

```typescript
const api = await window.cardano.eternl.enable();
lucid.selectWallet(api);

const address = await lucid.wallet.address();
const utxos = await lucid.wallet.getUtxos();
```

**Mesh:**

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");

const address = await wallet.getChangeAddressBech32();
const usedAddresses = await wallet.getUsedAddressesBech32();
const utxos = await wallet.getUtxosMesh();
```

**React hooks (Mesh):**

```typescript
import { CardanoWallet, useWallet } from "@meshsdk/react";

function WalletConnect() {
  const { wallet, connected, connect } = useWallet();

  if (!connected) {
    return <CardanoWallet />;
  }

  return <div>Connected</div>;
}
```

**What to expect:** Wallet instances with CIP-30 standard methods.

### Step 5: Migrate transaction building

**Lucid payment transaction:**

```typescript
const tx = await lucid
  .newTx()
  .payToAddress("addr_test1...", { lovelace: 5000000n })
  .complete();

const signedTx = await tx.sign().complete();
const txHash = await signedTx.submit();
```

**Mesh payment transaction:**

```typescript
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

const unsignedTx = await txBuilder
  .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);
```

**Key differences:**

* Mesh uses explicit input/output methods (`txIn`, `txOut`)
* Amounts are strings, not BigInt
* Signing returns a new string, does not mutate
* Change address must be set explicitly

**What to expect:** Transaction hashes on successful submission.

### Step 6: Migrate native token minting

**Lucid:**

```typescript
const { paymentCredential } = lucid.utils.getAddressDetails(address);
const mintingPolicy = lucid.utils.nativeScriptFromJson({
  type: "sig",
  keyHash: paymentCredential.hash,
});
const policyId = lucid.utils.mintingPolicyToId(mintingPolicy);

const tx = await lucid
  .newTx()
  .mintAssets({ [policyId + tokenName]: 1n })
  .validTo(Date.now() + 100000)
  .attachMintingPolicy(mintingPolicy)
  .complete();
```

**Mesh:**

```typescript
import {
  MeshTxBuilder,
  ForgeScript,
  resolveScriptHash,
  stringToHex,
} from "@meshsdk/core";

const address = await wallet.getChangeAddressBech32();
const forgingScript = ForgeScript.withOneSignature(address);
const policyId = resolveScriptHash(forgingScript);
const tokenNameHex = stringToHex("MyToken");

const txBuilder = new MeshTxBuilder({ fetcher: provider });
const utxos = await wallet.getUtxosMesh();

const unsignedTx = await txBuilder
  .mint("1", policyId, tokenNameHex)
  .mintingScript(forgingScript)
  .txOut(address, [{ unit: policyId + tokenNameHex, quantity: "1" }])
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);
```

**What to expect:** NFTs minted with Mesh's ForgeScript utilities.

### Step 7: Migrate smart contract interactions

**Lucid locking funds:**

```typescript
const tx = await lucid
  .newTx()
  .payToContract(scriptAddress, { inline: datum }, { lovelace: 5000000n })
  .complete();
```

**Mesh locking funds:**

```typescript
const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutInlineDatumValue(datum)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

**Lucid unlocking funds:**

```typescript
const tx = await lucid
  .newTx()
  .collectFrom([utxo], redeemer)
  .attachSpendingValidator(validator)
  .complete();
```

**Mesh unlocking funds:**

```typescript
const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .spendingPlutusScriptV2()
  .txIn(utxo.input.txHash, utxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(redeemer)
  .txInScript(scriptCbor)
  .txOut(recipientAddress, utxo.output.amount)
  .requiredSignerHash(pubKeyHash)
  .txInCollateral(
    collateral.input.txHash,
    collateral.input.outputIndex,
    collateral.output.amount,
    collateral.output.address
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true); // true for partial signing
```

**What to expect:** Smart contract transactions with explicit script and datum handling.

### Step 8: Migrate data serialization

**Lucid:**

```typescript
import { Data } from "lucid-cardano";

const datum = Data.to({ owner: pubKeyHash });
const parsed = Data.from(onchainDatum);
```

**Mesh:**

```typescript
import { serializePlutusData, deserializePlutusData } from "@meshsdk/core";
import type { Data } from "@meshsdk/core";

// For simple datums, use the Data type directly
const datum: Data = {
  alternative: 0,
  fields: [pubKeyHash],
};

// For complex serialization
const cbor = serializePlutusData(datum);
const parsed = deserializePlutusData(onchainDatum);
```

**What to expect:** CBOR-encoded datum and redeemer values.

### Step 9: Migrate tests

**Lucid Emulator:**

```typescript
import { Emulator, Lucid } from "lucid-cardano";

const emulator = new Emulator([{ address, assets: { lovelace: 100_000_000n } }]);
const lucid = await Lucid.new(emulator);
```

**Mesh testing:**

```typescript
import { OfflineFetcher, MeshTxBuilder } from "@meshsdk/core";

// Mock blockchain state
const offlineFetcher = new OfflineFetcher();
offlineFetcher.addUTxOs([
  {
    input: { txHash: "abc...", outputIndex: 0 },
    output: { address, amount: [{ unit: "lovelace", quantity: "100000000" }] },
  },
]);

const txBuilder = new MeshTxBuilder({ fetcher: offlineFetcher });
```

For local development, use Yaci:

```typescript
import { YaciProvider } from "@meshsdk/core";

const yaci = new YaciProvider("http://localhost:8080");
```

**What to expect:** Test environments without live blockchain connectivity.

## API Mapping Reference

| Lucid                          | Mesh                                               | Notes                         |
| ------------------------------ | -------------------------------------------------- | ----------------------------- |
| `Lucid.new()`                  | `new BlockfrostProvider()` + `new MeshTxBuilder()` | Separate provider and builder |
| `lucid.selectWallet()`         | `MeshCardanoBrowserWallet.enable()`                | Returns wallet instance       |
| `lucid.newTx()`                | `new MeshTxBuilder()`                              | Builder pattern               |
| `tx.payToAddress()`            | `txBuilder.txOut()`                                | Output construction           |
| `tx.payToContract()`           | `txBuilder.txOut()` + `txOutInlineDatumValue()`    | With datum                    |
| `tx.mintAssets()`              | `txBuilder.mint()` + `mintingScript()`             | Minting                       |
| `tx.collectFrom()`             | `txBuilder.txIn()` + script methods                | Script spending               |
| `tx.attachSpendingValidator()` | `txBuilder.txInScript()`                           | Attach validator              |
| `tx.complete()`                | `txBuilder.complete()`                             | Build transaction             |
| `tx.sign().complete()`         | `wallet.signTx()`                                  | Returns signed CBOR           |
| `signedTx.submit()`            | `wallet.submitTx()`                                | Submit to network             |
| `Data.to()`                    | `serializePlutusData()`                            | Serialize datum               |
| `Data.from()`                  | `deserializePlutusData()`                          | Parse datum                   |
| `Emulator`                     | `OfflineFetcher`                                   | Testing                       |

## Complete Example

Here is a complete migration example for a payment transaction:

**Before (Lucid):**

```typescript
import { Blockfrost, Lucid } from "lucid-cardano";

async function sendPayment() {
  const lucid = await Lucid.new(
    new Blockfrost("https://cardano-preprod.blockfrost.io/api", "key"),
    "Preprod"
  );

  const api = await window.cardano.eternl.enable();
  lucid.selectWallet(api);

  const tx = await lucid
    .newTx()
    .payToAddress("addr_test1...", { lovelace: 5000000n })
    .complete();

  const signedTx = await tx.sign().complete();
  const txHash = await signedTx.submit();

  console.log("TX:", txHash);
}
```

**After (Mesh):**

```typescript
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function sendPayment() {
  const provider = new BlockfrostProvider("key_preprod");
  const wallet = await MeshCardanoBrowserWallet.enable("eternl");

  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  const txBuilder = new MeshTxBuilder({ fetcher: provider, submitter: provider });

  const unsignedTx = await txBuilder
    .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await wallet.submitTx(signedTx);

  console.log("TX:", txHash);
}
```

## Troubleshooting

### Type errors with amounts

**Cause:** Lucid uses BigInt for amounts, Mesh uses strings.

**Solution:** Convert amounts when migrating:

```typescript
// Lucid
{ lovelace: 5000000n }

// Mesh
[{ unit: "lovelace", quantity: "5000000" }]
```

### Transaction signing fails

**Cause:** Missing the partial signing flag for Plutus scripts.

**Solution:** Pass `true` as the second argument to `signTx()`:

```typescript
const signedTx = await wallet.signTx(unsignedTx, true);
```

### Missing change address error

**Cause:** Mesh requires explicit change address.

**Solution:** Always set the change address:

```typescript
const changeAddress = await wallet.getChangeAddress();
txBuilder.changeAddress(changeAddress);
```

### Script validation fails

**Cause:** Datum or redeemer structure does not match contract expectations.

**Solution:** Verify your Data structure matches the Aiken/Plutus types:

```typescript
const datum: Data = {
  alternative: 0, // Constructor index
  fields: [value1, value2], // Field values
};
```

### UTxO not found errors

**Cause:** UTxOs fetched at different times may be spent.

**Solution:** Fetch UTxOs immediately before building the transaction:

```typescript
const utxos = await wallet.getUtxosMesh();
// Build transaction immediately after
const unsignedTx = await txBuilder
  .selectUtxosFrom(utxos)
  .complete();
```

## Related Links

* <Link href="/apis/txbuilder">Transaction Builder API</Link>
* <Link href="/guides/smart-contract-transactions">Smart Contract Transactions</Link>
* <Link href="/apis/wallets/browserwallet">BrowserWallet API</Link>
* <Link href="/providers">Providers Documentation</Link>
* <Link href="https://discord.gg/dH48jH3BKa">Mesh Discord</Link> for migration support


# Mint NFTs on Cardano with Node.js
URL: /guides/minting-on-nodejs

Build a server-side NFT minting application using Mesh SDK. Mint tokens and distribute them to multiple recipients.

***

title: "Mint NFTs on Cardano with Node.js"
description: "Build a server-side NFT minting application using Mesh SDK. Mint tokens and distribute them to multiple recipients."
----------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Mint NFTs on Cardano with Node.js"
  description="Build a server-side NFT minting application that creates multiple tokens and distributes them to different recipients."
  totalTime="PT30M"
  steps={[
  { name: "Set up project", text: "Initialize a Node.js project with TypeScript and Mesh SDK." },
  { name: "Define metadata", text: "Create CIP-25 compliant NFT metadata for each token." },
  { name: "Specify recipients", text: "Map wallet addresses to token names." },
  { name: "Build transaction", text: "Mint tokens and send to recipients in one transaction." },
  { name: "Submit transaction", text: "Sign and submit the transaction to the blockchain." }
]}
/>

## Overview

Server-side minting lets you create Cardano NFTs without a browser. This is ideal for automated token distribution, airdrops, and backend services. This guide uses the [CIP-25](https://cips.cardano.org/cip/CIP-0025) metadata standard for NFT token metadata on Cardano.

### What you will build

* A Node.js application that mints multiple NFTs
* Automated distribution to multiple recipient addresses
* CIP-25 compliant metadata handling

### Prerequisites

* Node.js 18+ installed
* A Blockfrost API key ([get one free](https://blockfrost.io/))
* A funded Cardano wallet (mnemonic or CLI keys)

### Time to complete

30 minutes

## Quick Start

Clone the example repository:

```bash
git clone https://github.com/MeshJS/examples
cd examples/nodejs-minting
npm install
```

Add your credentials to the config and run `npm start`.

## Step-by-Step Guide

### Step 1: Set up the project

Create a new Node.js project:

```bash
mkdir nodejs-minting
cd nodejs-minting
npm init -y
npm install typescript @meshsdk/core --save
npm install --save-dev typescript
npx tsc --init
```

**What to expect:** A TypeScript project with Mesh SDK installed.

### Step 2: Configure TypeScript

Update `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  }
}
```

Update `package.json`:

```json
{
  "type": "module",
  "scripts": {
    "start": "tsc && node ./dist/main.js"
  }
}
```

**What to expect:** TypeScript configured for ES modules.

### Step 3: Define NFT metadata

Create `src/metadata.ts`:

```typescript
export interface NFTMetadata {
  name: string;
  image: string;
  mediaType: string;
  description: string;
  artist?: string;
  attributes?: Record<string, unknown>;
}

export const metadata: Record<string, NFTMetadata> = {
  MeshToken01: {
    name: "Mesh Token 1",
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    mediaType: "image/jpg",
    description: "A purple coin from the Mesh collection.",
    artist: "Mesh (https://meshjs.dev/)",
  },
  MeshToken02: {
    name: "Mesh Token 2",
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    mediaType: "image/jpg",
    description: "A gold coin from the Mesh collection.",
    artist: "Mesh (https://meshjs.dev/)",
  },
  MeshToken03: {
    name: "Mesh Token 3",
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    mediaType: "image/jpg",
    description: "A coin with M logo from the Mesh collection.",
    artist: "Mesh (https://meshjs.dev/)",
  },
};
```

**What to expect:** CIP-25 compliant metadata for three tokens.

### Step 4: Specify recipients

Create `src/recipients.ts`:

```typescript
// Map of recipient address to token name
export const recipients: Record<string, string> = {
  "addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr": "MeshToken01",
  "addr_test1qqlcxawu4gxarenqvdqyw0tqyjy69mrgsmfqhm6h65jwm4vvldqg2n2p8y4kyjm8sqfyg0tpq9042atz0fr8c3grjmyscxry4r": "MeshToken02",
  "addr_test1qq5tay78z9l77vkxvrvtrv70nvjdk0fyvxmqzs57jg0vq6wk3w9pfppagj5rc4wsmlfyvc8xs7ytkumazu9xq49z94pqzl95zt": "MeshToken03",
};
```

**What to expect:** Each recipient receives one specific token.

### Step 5: Create the minting script

Create `src/main.ts`:

```typescript
import {
  MeshTxBuilder,
  ForgeScript,
  BlockfrostProvider,
  resolveScriptHash,
  stringToHex,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import type { AssetMetadata } from "@meshsdk/core";

import { metadata } from "./metadata.js";
import { recipients } from "./recipients.js";

// Configuration - replace with your values
const BLOCKFROST_KEY = "your_blockfrost_preprod_key";
const NETWORK_ID = 0; // 0 = testnet, 1 = mainnet

// Wallet mnemonic (24 words)
const MNEMONIC = [
  "your", "twenty", "four", "word", "mnemonic",
  "phrase", "goes", "here", "replace", "with",
  "actual", "words", "from", "your", "wallet",
  "that", "has", "been", "funded", "with",
  "test", "ada", "from", "faucet",
];

async function main() {
  // Initialize provider
  const provider = new BlockfrostProvider(BLOCKFROST_KEY);

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: NETWORK_ID,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: MNEMONIC,
  });

  const walletAddress = await wallet.getChangeAddressBech32();
  console.log("Wallet address:", walletAddress);

  // Create forging script from wallet address
  const forgingScript = ForgeScript.withOneSignature(walletAddress);
  const policyId = resolveScriptHash(forgingScript);
  console.log("Policy ID:", policyId);

  // Get UTxOs
  const utxos = await wallet.getUtxosMesh();
  if (utxos.length === 0) {
    throw new Error("No UTxOs available. Fund the wallet first.");
  }
  console.log("Available UTxOs:", utxos.length);

  // Build the transaction
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  // Prepare transaction metadata
  const txMetadata: Record<string, Record<string, AssetMetadata>> = {
    [policyId]: {},
  };

  // Add mint and output for each recipient
  for (const [recipientAddress, assetName] of Object.entries(recipients)) {
    const assetMetadata = metadata[assetName];
    if (!assetMetadata) {
      console.warn(`No metadata found for ${assetName}, skipping`);
      continue;
    }

    const tokenNameHex = stringToHex(assetName);
    const assetUnit = policyId + tokenNameHex;

    console.log(`Minting ${assetName} for ${recipientAddress.slice(0, 20)}...`);

    // Add metadata for this token
    txMetadata[policyId][assetName] = assetMetadata;

    // Add mint instruction and output
    txBuilder
      .mint("1", policyId, tokenNameHex)
      .mintingScript(forgingScript)
      .txOut(recipientAddress, [{ unit: assetUnit, quantity: "1" }]);
  }

  // Complete the transaction
  const unsignedTx = await txBuilder
    .metadataValue(721, txMetadata)
    .changeAddress(walletAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await wallet.submitTx(signedTx);

  console.log("");
  console.log("Transaction submitted successfully!");
  console.log("Transaction hash:", txHash);
  console.log(`View on explorer: https://preprod.cardanoscan.io/transaction/${txHash}`);
}

main().catch((error) => {
  console.error("Error:", error.message);
  process.exit(1);
});
```

**What to expect:** A complete minting script that distributes tokens to multiple recipients.

### Step 6: Run the script

Execute the minting:

```bash
npm start
```

**What to expect:** Console output showing each mint operation and the final transaction hash.

## Complete Example

Here is the complete project structure:

```
nodejs-minting/
  package.json
  tsconfig.json
  src/
    main.ts
    metadata.ts
    recipients.ts
```

**package.json:**

```json
{
  "name": "nodejs-minting",
  "type": "module",
  "scripts": {
    "start": "tsc && node ./dist/main.js"
  },
  "dependencies": {
    "@meshsdk/core": "^1.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
```

## Next Steps

* <Link href="/apis/txbuilder/minting">Minting API reference</Link> - Advanced minting options
* <Link href="/guides/multisig-minting">Multi-signature minting</Link> - Coordinate multiple signers
* <Link href="/apis/wallets/meshwallet">Headless Wallet options</Link> - Different key types
* <Link href="/guides/nft-collection">Mint a collection</Link> - Batch minting with Bun

## Troubleshooting

### No UTxOs available

**Cause:** The wallet has no funds.

**Solution:** Fund the wallet using the [testnet faucet](https://docs.cardano.org/cardano-testnets/tools/faucet) or transfer ADA from another wallet.

### Transaction too large

**Cause:** Too many mints or outputs in one transaction.

**Solution:** Split the recipients into multiple batches and submit separate transactions.

### Invalid address

**Cause:** Recipient address is malformed or for wrong network.

**Solution:** Verify addresses are valid Cardano addresses for the correct network (testnet or mainnet).

### Mnemonic validation failed

**Cause:** The mnemonic phrase is incorrect or incomplete.

**Solution:** Ensure you have exactly 24 words (or 15/12 for some wallets) with correct spelling.

### Policy ID mismatch

**Cause:** The forging script changed between mints.

**Solution:** The policy ID is deterministic based on the wallet address. Ensure you use the same wallet for all mints of a collection.

## References

* [CIP-25: Media NFT Metadata Standard](https://cips.cardano.org/cip/CIP-0025) - The Cardano standard for NFT metadata used in this guide
* [Cardano Developer Portal: Native Tokens](https://developers.cardano.org/docs/native-tokens/) - Official documentation on Cardano's native token system
* [Cardano Developer Portal](https://developers.cardano.org) - Official development resources and guides

## Related Links

* <Link href="/apis/txbuilder/minting">Minting API Reference</Link>
* <Link href="/apis/wallets/meshwallet">Headless Wallet Documentation</Link>
* <Link href="https://cips.cardano.org/cip/CIP-25">CIP-25 Metadata Standard</Link>
* <Link href="/providers">Blockchain Providers</Link>


# Build Multi-Signature Minting Transactions
URL: /guides/multisig-minting

Implement multi-sig NFT minting with Mesh SDK. Coordinate signatures between browser and server wallets.

***

title: "Build Multi-Signature Minting Transactions"
description: "Implement multi-sig NFT minting with Mesh SDK. Coordinate signatures between browser and server wallets."
-----------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Build Multi-Signature Minting Transactions on Cardano"
  description="Implement multi-sig NFT minting where a user pays for minting but the application controls the minting policy."
  totalTime="PT45M"
  steps={[
  { name: "Connect user wallet", text: "Get user address and UTxOs from browser wallet." },
  { name: "Build transaction on server", text: "Create minting transaction using user UTxOs as inputs." },
  { name: "User signs transaction", text: "Return unsigned tx to client for partial signing." },
  { name: "Server signs and submits", text: "Add application signature and submit to blockchain." }
]}
/>

## Overview

Multi-signature (multi-sig) transactions require multiple parties to sign before submission. This is essential for NFT minting services where users pay for minting but your application controls the minting policy. Cardano's [native multi-asset](https://developers.cardano.org/docs/native-tokens/) system enables minting without smart contracts, using native scripts for policy control.

### What you will build

* A client-side component that connects user wallets
* A server-side API that builds minting transactions
* A complete multi-sig signing flow

### The multi-sig minting flow

1. **User wallet** provides payment UTxOs
2. **Server** builds the transaction using user inputs
3. **User** partially signs the transaction
4. **Server** adds its signature and submits

### Prerequisites

* A Next.js application with Mesh SDK (see <Link href="/guides/nextjs">Next.js guide</Link>)
* A server-side wallet (mnemonic or CLI keys)
* A Blockfrost API key

### Time to complete

45 minutes

## Quick Start

View the complete implementation:

* <Link href="https://github.com/MeshJS/mesh/blob/main/apps/playground/src/pages/guides/multisig-minting/demo.tsx">Full source code on GitHub</Link>

## Step-by-Step Guide

### Step 1: Connect the user wallet

Create a client component to connect the user's browser wallet:

```typescript
// components/MintButton.tsx
"use client";

import { useState } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";
import { experimentalSelectUtxos } from "@meshsdk/core";
import type { UTxO, Unit, Quantity } from "@meshsdk/core";

const MINTING_FEE = "5000000"; // 5 ADA

export function MintButton() {
  const { wallet, connected } = useWallet();
  const [loading, setLoading] = useState(false);
  const [txHash, setTxHash] = useState("");

  async function handleMint() {
    if (!connected) return;
    setLoading(true);

    try {
      // Get user wallet info
      const recipientAddress = await wallet.getChangeAddress();
      const utxos = await wallet.getUtxos();

      // Select UTxOs for the minting fee
      const assetMap = new Map<Unit, Quantity>();
      assetMap.set("lovelace", MINTING_FEE);
      const selectedUtxos = experimentalSelectUtxos(assetMap, utxos, "5000000");

      // Send to server to build transaction
      const response = await fetch("/api/mint", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          recipientAddress,
          utxos: selectedUtxos,
        }),
      });

      const { unsignedTx } = await response.json();

      // User signs with partial signing enabled
      const signedTx = await wallet.signTx(unsignedTx, true);

      // Send back to server for final signature and submission
      const submitResponse = await fetch("/api/mint/submit", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ signedTx }),
      });

      const { txHash } = await submitResponse.json();
      setTxHash(txHash);
    } catch (error) {
      console.error("Minting failed:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <CardanoWallet />

      {connected && (
        <button
          onClick={handleMint}
          disabled={loading}
          className="mt-4 px-4 py-2 bg-blue-500 text-white rounded"
        >
          {loading ? "Minting..." : "Mint NFT (5 ADA)"}
        </button>
      )}

      {txHash && (
        <p className="mt-4">
          Success! <a href={`https://preprod.cardanoscan.io/transaction/${txHash}`}>View TX</a>
        </p>
      )}
    </div>
  );
}
```

**What to expect:** A button that initiates the multi-sig minting flow.

### Step 2: Create the server-side build endpoint

Create an API route that builds the minting transaction:

```typescript
// app/api/mint/route.ts (Next.js App Router)
// or pages/api/mint.ts (Next.js Pages Router)

import { NextResponse } from "next/server";
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import type { UTxO, AssetMetadata } from "@meshsdk/core";

// Server wallet configuration (never expose in client)
const MNEMONIC = process.env.MINTING_WALLET_MNEMONIC!;
const BLOCKFROST_KEY = process.env.BLOCKFROST_KEY!;
const BANK_ADDRESS = process.env.BANK_WALLET_ADDRESS!;
const MINTING_FEE = "5000000";

export async function POST(request: Request) {
  const { recipientAddress, utxos } = await request.json() as {
    recipientAddress: string;
    utxos: UTxO[];
  };

  // Initialize provider and application wallet
  const provider = new BlockfrostProvider(BLOCKFROST_KEY);

  const appWallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: MNEMONIC.split(" "),
  });

  // Create forging script from application wallet
  const appAddress = await appWallet.getChangeAddressBech32();
  const forgingScript = ForgeScript.withOneSignature(appAddress);
  const policyId = resolveScriptHash(forgingScript);

  // Define the NFT
  const assetName = "MeshNFT";
  const tokenNameHex = stringToHex(assetName);
  const assetUnit = policyId + tokenNameHex;

  const assetMetadata: AssetMetadata = {
    name: "Mesh NFT",
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    mediaType: "image/jpg",
    description: "Minted via multi-sig transaction",
  };

  // Build the transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  // Add user UTxOs as inputs
  for (const utxo of utxos) {
    txBuilder.txIn(
      utxo.input.txHash,
      utxo.input.outputIndex,
      utxo.output.amount,
      utxo.output.address
    );
  }

  const unsignedTx = await txBuilder
    // Mint the NFT
    .mint("1", policyId, tokenNameHex)
    .mintingScript(forgingScript)
    // Send NFT to user
    .txOut(recipientAddress, [{ unit: assetUnit, quantity: "1" }])
    // Send minting fee to bank
    .txOut(BANK_ADDRESS, [{ unit: "lovelace", quantity: MINTING_FEE }])
    // Add metadata
    .metadataValue(721, { [policyId]: { [assetName]: assetMetadata } })
    // Change goes back to user
    .changeAddress(recipientAddress)
    .complete();

  return NextResponse.json({ unsignedTx, policyId });
}
```

**What to expect:** An API that builds minting transactions using user UTxOs.

### Step 3: Create the submit endpoint

Create an API route to add the server signature and submit:

```typescript
// app/api/mint/submit/route.ts

import { NextResponse } from "next/server";
import { BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const MNEMONIC = process.env.MINTING_WALLET_MNEMONIC!;
const BLOCKFROST_KEY = process.env.BLOCKFROST_KEY!;

export async function POST(request: Request) {
  const { signedTx } = await request.json() as { signedTx: string };

  const provider = new BlockfrostProvider(BLOCKFROST_KEY);

  const appWallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: MNEMONIC.split(" "),
  });

  // Add application signature (partial signing)
  const fullySignedTx = await appWallet.signTx(signedTx, true);

  // Submit the transaction
  const txHash = await appWallet.submitTx(fullySignedTx);

  return NextResponse.json({ txHash });
}
```

**What to expect:** An API that completes signing and submits the transaction.

### Step 4: Configure environment variables

Create `.env.local`:

```bash
BLOCKFROST_KEY=your_blockfrost_preprod_key
MINTING_WALLET_MNEMONIC=your twenty four word mnemonic phrase for the minting wallet
BANK_WALLET_ADDRESS=addr_test1your_bank_address_for_collecting_fees
```

**What to expect:** Server-side credentials stored securely.

## Complete Example

Here is the complete flow in a single file for reference:

**Client Component:**

```typescript
"use client";

import { useState } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";
import { experimentalSelectUtxos } from "@meshsdk/core";

export function MultiSigMint() {
  const { wallet, connected } = useWallet();
  const [status, setStatus] = useState<"idle" | "building" | "signing" | "submitting" | "done">("idle");
  const [txHash, setTxHash] = useState("");

  async function mint() {
    try {
      // Step 1: Get user wallet info
      setStatus("building");
      const address = await wallet.getChangeAddress();
      const utxos = await wallet.getUtxos();

      const assetMap = new Map();
      assetMap.set("lovelace", "5000000");
      const selected = experimentalSelectUtxos(assetMap, utxos, "5000000");

      // Step 2: Build transaction on server
      const buildRes = await fetch("/api/mint", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ recipientAddress: address, utxos: selected }),
      });
      const { unsignedTx } = await buildRes.json();

      // Step 3: User signs
      setStatus("signing");
      const userSignedTx = await wallet.signTx(unsignedTx, true);

      // Step 4: Server signs and submits
      setStatus("submitting");
      const submitRes = await fetch("/api/mint/submit", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ signedTx: userSignedTx }),
      });
      const { txHash } = await submitRes.json();

      setTxHash(txHash);
      setStatus("done");
    } catch (error) {
      console.error(error);
      setStatus("idle");
    }
  }

  return (
    <div className="space-y-4">
      <CardanoWallet />

      {connected && (
        <button
          onClick={mint}
          disabled={status !== "idle" && status !== "done"}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
        >
          {status === "idle" && "Mint NFT (5 ADA)"}
          {status === "building" && "Building transaction..."}
          {status === "signing" && "Please sign in wallet..."}
          {status === "submitting" && "Submitting..."}
          {status === "done" && "Mint Another"}
        </button>
      )}

      {txHash && (
        <p>
          Transaction:{" "}
          <a
            href={`https://preprod.cardanoscan.io/transaction/${txHash}`}
            target="_blank"
            className="text-blue-500 underline"
          >
            {txHash.slice(0, 16)}...
          </a>
        </p>
      )}
    </div>
  );
}
```

## Next Steps

* <Link href="/guides/smart-contract-transactions">Smart contract transactions</Link> - NFT marketplace patterns
* <Link href="/apis/txbuilder/minting">Minting API reference</Link> - Advanced minting options
* <Link href="/guides/production-deployment">Production deployment</Link> - Security best practices

## Troubleshooting

### User UTxOs already spent

**Cause:** The user's UTxOs were spent between selection and submission.

**Solution:** Implement retry logic or show an error asking the user to try again.

### Signature verification failed

**Cause:** The transaction was modified after the user signed.

**Solution:** Never modify the transaction after the user signs. Build the complete transaction before returning it to the client.

### Insufficient funds

**Cause:** Selected UTxOs do not cover the minting fee plus transaction fee.

**Solution:** Increase the UTxO selection amount to include buffer for fees:

```typescript
const selectedUtxos = experimentalSelectUtxos(assetMap, utxos, "7000000");
```

### CORS errors

**Cause:** API routes are not accessible from the client.

**Solution:** Ensure your Next.js API routes are correctly configured. In App Router, use `route.ts` files.

### Mnemonic not found

**Cause:** Environment variables are not loaded.

**Solution:** For Next.js, ensure:

* Variables are in `.env.local` (not `.env`)
* Server-only variables do not have `NEXT_PUBLIC_` prefix
* Restart the dev server after adding variables

## Security Considerations

* **Never expose mnemonics** in client-side code
* **Validate user UTxOs** before building transactions
* **Set reasonable minting fees** to cover costs and prevent abuse
* **Implement rate limiting** on API endpoints
* **Log minting events** for auditing

## References

* [Cardano Developer Portal: Native Tokens](https://developers.cardano.org/docs/native-tokens/) - Official documentation on Cardano's native multi-asset system
* [CIP-25: Media NFT Metadata Standard](https://cips.cardano.org/cip/CIP-0025) - The Cardano standard for NFT metadata
* [CIP-30: dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-0030) - The standard enabling partial signing for multi-sig transactions

## Related Links

* <Link href="https://github.com/MeshJS/mesh/blob/main/apps/playground/src/pages/guides/multisig-minting/demo.tsx">Complete example code</Link>
* <Link href="/apis/txbuilder">Transaction Builder API</Link>
* <Link href="/guides/production-deployment">Production Deployment</Link>


# Build Your First Cardano dApp with Next.js
URL: /guides/nextjs

Create a Cardano dApp using Next.js and Mesh SDK. Connect wallets, query assets, and build your first blockchain application.

***

title: "Build Your First Cardano dApp with Next.js"
description: "Create a Cardano dApp using Next.js and Mesh SDK. Connect wallets, query assets, and build your first blockchain application."
--------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Develop your first Web3 App with Next.js and Mesh"
  description="Set up a Next.js application and connect it to the Cardano blockchain using Mesh. Create a simple application that allows users to connect their wallets and view assets."
  totalTime="PT30M"
  steps={[
  { name: "Create Next.js app", text: "Create a new Next.js application using npx create-next-app@latest." },
  { name: "Install Mesh SDK", text: "Install Mesh packages with npm install @meshsdk/core @meshsdk/react." },
  { name: "Add MeshProvider", text: "Wrap your application with MeshProvider for wallet state management." },
  { name: "Add wallet component", text: "Add the CardanoWallet component to enable wallet connection." },
  { name: "Display wallet assets", text: "Use the useWallet hook to fetch and display user assets." }
]}
/>

## Overview

In this guide, you build a Next.js application that connects to Cardano wallets and displays user assets. This is the foundation for any Cardano dApp. Mesh SDK implements the [CIP-30](https://cips.cardano.org/cip/CIP-0030) dApp-wallet web bridge standard, providing a consistent interface across all compatible Cardano wallets.

### What you will build

* A Next.js application with Mesh SDK integration
* Wallet connection using the CardanoWallet component
* Asset display for connected wallets

### Prerequisites

* Node.js 18+ installed
* A Cardano wallet browser extension (Eternl, Nami, or Lace)
* Basic React/Next.js knowledge

### Time to complete

30 minutes

## Quick Start

Use the Mesh CLI to scaffold a complete project instantly:

```bash
npx meshjs your-app-name
cd your-app-name
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to see your dApp. Skip the rest of this guide if you use the CLI.

## Step-by-Step Setup

### Step 1: Create a Next.js project

Create a new Next.js application with TypeScript:

```bash
npx create-next-app@latest my-cardano-dapp --typescript
cd my-cardano-dapp
```

When prompted, select these options:

| Option           | Recommended           |
| ---------------- | --------------------- |
| ESLint           | Yes                   |
| Tailwind CSS     | Yes                   |
| `src/` directory | Yes                   |
| App Router       | No (use Pages Router) |
| Turbopack        | No                    |
| Import alias     | No                    |

**What to expect:** A new `my-cardano-dapp` directory with the Next.js project structure.

### Step 2: Verify the setup

Start the development server:

```bash
npm run dev
```

**What to expect:** Open [http://localhost:3000](http://localhost:3000) to see the default Next.js welcome page. Press `Ctrl+C` to stop the server.

### Step 3: Install Mesh SDK

Install the Mesh packages:

```bash
npm install @meshsdk/core @meshsdk/react
```

* `@meshsdk/core` - Core blockchain functionality (wallets, transactions, providers)
* `@meshsdk/react` - React components and hooks for wallet integration

**What to expect:** The packages install without errors. Your `package.json` now includes both dependencies.

### Step 4: Add MeshProvider

The `MeshProvider` context manages wallet state across your application.

Open `src/pages/_app.tsx` and replace its contents:

```tsx
import "@/styles/globals.css";
import "@meshsdk/react/styles.css";
import type { AppProps } from "next/app";
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

**What to expect:** Your app now has access to wallet state through React context.

### Step 5: Create the wallet connection page

Replace the contents of `src/pages/index.tsx`:

```tsx
import { useState } from "react";
import type { NextPage } from "next";
import { CardanoWallet, useWallet } from "@meshsdk/react";

const Home: NextPage = () => {
  const { connected, wallet } = useWallet();
  const [assets, setAssets] = useState<null | any[]>(null);
  const [loading, setLoading] = useState(false);

  async function getAssets() {
    if (wallet) {
      setLoading(true);
      const walletAssets = await wallet.getAssets();
      setAssets(walletAssets);
      setLoading(false);
    }
  }

  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold mb-8">My Cardano dApp</h1>

      <div className="mb-8">
        <CardanoWallet />
      </div>

      {connected && (
        <div className="text-center">
          <button
            onClick={getAssets}
            disabled={loading}
            className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 disabled:opacity-50"
          >
            {loading ? "Loading..." : "Get Wallet Assets"}
          </button>

          {assets && (
            <pre className="mt-4 p-4 bg-gray-100 rounded text-left overflow-auto max-w-xl">
              {JSON.stringify(assets, null, 2)}
            </pre>
          )}
        </div>
      )}
    </main>
  );
};

export default Home;
```

**What to expect:** A page with a wallet connection button. After connecting, a button appears to fetch and display wallet assets.

### Step 6: Test your dApp

Start the development server:

```bash
npm run dev
```

1. Open [http://localhost:3000](http://localhost:3000)
2. Click the wallet button to connect your Cardano wallet
3. Approve the connection in your wallet extension
4. Click "Get Wallet Assets" to see your tokens

**What to expect:** Your wallet connects and displays any assets you hold. If you have no assets, the list will be empty or show only ADA.

## Complete Example

Here is the complete code for both files:

**src/pages/\_app.tsx**

```tsx
import "@/styles/globals.css";
import "@meshsdk/react/styles.css";
import type { AppProps } from "next/app";
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

**src/pages/index.tsx**

```tsx
import { useState } from "react";
import type { NextPage } from "next";
import { CardanoWallet, useWallet } from "@meshsdk/react";

const Home: NextPage = () => {
  const { connected, wallet } = useWallet();
  const [assets, setAssets] = useState<null | any[]>(null);
  const [loading, setLoading] = useState(false);

  async function getAssets() {
    if (wallet) {
      setLoading(true);
      const walletAssets = await wallet.getAssets();
      setAssets(walletAssets);
      setLoading(false);
    }
  }

  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold mb-8">My Cardano dApp</h1>

      <div className="mb-8">
        <CardanoWallet />
      </div>

      {connected && (
        <div className="text-center">
          <button
            onClick={getAssets}
            disabled={loading}
            className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 disabled:opacity-50"
          >
            {loading ? "Loading..." : "Get Wallet Assets"}
          </button>

          {assets && (
            <pre className="mt-4 p-4 bg-gray-100 rounded text-left overflow-auto max-w-xl">
              {JSON.stringify(assets, null, 2)}
            </pre>
          )}
        </div>
      )}
    </main>
  );
};

export default Home;
```

## Next Steps

Now that you have a working dApp foundation:

* <Link href="/apis/wallets/browserwallet">Display wallet address and ADA balance</Link> - Explore the BrowserWallet API
* <Link href="/apis/txbuilder">Build transactions</Link> - Send ADA and tokens
* <Link href="/guides/prove-wallet-ownership">Add authentication</Link> - Verify wallet ownership with signatures
* <Link href="/guides/aiken">Integrate smart contracts</Link> - Work with Aiken validators

## Troubleshooting

### Wallet not appearing

**Cause:** No Cardano wallet extension is installed.

**Solution:** Install a Cardano wallet extension like [Eternl](https://eternl.io/), [Nami](https://namiwallet.io/), or [Lace](https://www.lace.io/).

### Buffer is not defined error

**Cause:** Mesh uses Node.js APIs that require polyfills in the browser.

**Solution:** See the <Link href="/guides/node-specific-imports">polyfill configuration guide</Link> for your framework.

### Connection rejected

**Cause:** The user declined the wallet connection request.

**Solution:** This is expected behavior. Prompt the user to try again if they want to connect.

### Assets not loading

**Cause:** The wallet may be on a different network or have no assets.

**Solution:** Ensure your wallet is on the correct network (mainnet or testnet) and has assets to display.

## References

* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources and documentation
* [CIP-30: Cardano dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-0030) - The standard that Mesh SDK implements for wallet connectivity
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding Cardano's extended UTXO transaction model
* [MeshJS GitHub Repository](https://github.com/MeshJS/mesh) - Mesh SDK source code and contributions

## Related Links

* <Link href="/apis/wallets/browserwallet">BrowserWallet API</Link> - Complete wallet interaction methods
* <Link href="/apis/txbuilder">Transaction Builder</Link> - Build and submit transactions
* <Link href="https://docs.cardano.org/cardano-testnets/tools/faucet">Cardano Testnet Faucet</Link> - Get free test ADA
* <Link href="/svelte">Svelte Integration</Link> - Use Mesh with Svelte


# Mint an NFT Collection on Cardano
URL: /guides/nft-collection

Create native NFT assets on Cardano using Mesh SDK and Bun. Learn CIP-25 metadata, native scripts, and transaction building.

***

title: "Mint an NFT Collection on Cardano"
description: "Create native NFT assets on Cardano using Mesh SDK and Bun. Learn CIP-25 metadata, native scripts, and transaction building."
-------------------------------------------------------------------------------------------------------------------------------------------

import Youtube from "@/components/ui/Youtube";
import { HowToSchema } from "@/components/seo";
import Link from "fumadocs-core/link";

<HowToSchema
  name="Mint an NFT Collection on Cardano"
  description="Learn how to mint native assets on the Cardano blockchain using Mesh SDK and Bun runtime."
  totalTime="PT45M"
  steps={[
  { name: "Set up project", text: "Install Bun and initialize a new project with Mesh SDK." },
  { name: "Generate wallet", text: "Create a new Cardano wallet and fund it with test ADA." },
  { name: "Create native script", text: "Define a minting policy with time lock and signature requirements." },
  { name: "Build metadata", text: "Create CIP-25 compliant NFT metadata." },
  { name: "Mint collection", text: "Build, sign, and submit the minting transaction." }
]}
/>

<Youtube id="KewdzkAqsvw" />

## Overview

In this guide, you mint an NFT collection on Cardano using native scripts. Cardano's [native multi-asset](https://developers.cardano.org/docs/native-tokens/) system allows minting tokens without smart contracts, making them simpler and cheaper to create. Token metadata follows the [CIP-25](https://cips.cardano.org/cip/CIP-0025) standard.

### What you will build

* A minting script that creates multiple NFTs in one transaction
* CIP-25 compliant metadata for marketplace compatibility
* A time-locked minting policy that expires after a set slot

### What you will learn

* How Cardano native tokens work without smart contracts
* Building minting transactions with Mesh SDK
* Implementing CIP-25 metadata standards

### Prerequisites

* [Bun](https://bun.sh/docs/installation) installed
* A Blockfrost API key ([get one free](https://blockfrost.io/))
* Basic TypeScript knowledge

### Time to complete

45 minutes

## Quick Start

If you want to start with a working example:

```bash
git clone https://github.com/MeshJS/examples
cd examples/minting
bun install
```

Add your credentials to `.env` and run `bun run index.ts`.

## Step-by-Step Guide

### Step 1: Set up the project

Install Bun if you have not already:

```bash
curl -fsSL https://bun.sh/install | bash
```

Create and initialize a new project:

```bash
mkdir nft-collection
cd nft-collection
bun init -y
bun add @meshsdk/core
```

**What to expect:** A new project with `package.json` and `@meshsdk/core` installed.

### Step 2: Generate a wallet

Create `scripts/generate-wallet.ts`:

```typescript
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import { generateMnemonic } from "@meshsdk/core";

// Generate a new mnemonic phrase
const words = generateMnemonic(256);

console.log("Mnemonic phrase:");
console.log(words.join(" "));
console.log("");

// Create wallet from mnemonic
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  mnemonic: words,
  networkId: 0, // 0 = testnet
  walletAddressType: AddressType.Base,
});

const address = await wallet.getChangeAddressBech32();
console.log("Wallet address:");
console.log(address);
```

Run the script:

```bash
bun run scripts/generate-wallet.ts
```

**What to expect:** A 24-word mnemonic phrase and a wallet address starting with `addr_test1`.

### Step 3: Fund your wallet

1. Copy the wallet address from the previous step
2. Go to the [Cardano testnet faucet](https://docs.cardano.org/cardano-testnets/tools/faucet)
3. Paste your address and request test ADA
4. Wait 1-2 minutes for the transaction to confirm

**What to expect:** Your wallet receives test ADA (usually 10,000 tADA).

### Step 4: Configure environment

Create a `.env` file:

```bash
MNEMONIC=your twenty four word mnemonic phrase goes here
BLOCKFROST_KEY=your_blockfrost_preprod_api_key
```

**What to expect:** Your credentials are stored securely and not committed to git.

### Step 5: Create the minting script

Create `index.ts`:

```typescript
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex,
  deserializeAddress,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import type { NativeScript, AssetMetadata } from "@meshsdk/core";

// Load environment variables
const BLOCKFROST_KEY = process.env.BLOCKFROST_KEY!;
const MNEMONIC = process.env.MNEMONIC!;

if (!BLOCKFROST_KEY || !MNEMONIC) {
  throw new Error("Missing BLOCKFROST_KEY or MNEMONIC in environment");
}

// Initialize provider and wallet
const provider = new BlockfrostProvider(BLOCKFROST_KEY);

const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  mnemonic: MNEMONIC.split(" "),
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
});

const address = await wallet.getChangeAddressBech32();
const utxos = await wallet.getUtxosMesh();
const { pubKeyHash } = deserializeAddress(address);

console.log("Wallet address:", address);
console.log("Available UTxOs:", utxos.length);

if (utxos.length === 0) {
  throw new Error("No UTxOs available. Fund the wallet first.");
}
```

**What to expect:** The script initializes the wallet and provider.

### Step 6: Define the native script

Add the native script (minting policy) to `index.ts`:

```typescript
// Define the native script (minting policy)
// This policy requires your signature AND expires at a specific slot
const LOCK_SLOT = 90000000; // Adjust this to a future slot on preprod

const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    {
      type: "before",
      slot: LOCK_SLOT.toString(),
    },
    {
      type: "sig",
      keyHash: pubKeyHash,
    },
  ],
};

const forgingScript = ForgeScript.fromNativeScript(nativeScript);
const policyId = resolveScriptHash(forgingScript);

console.log("Policy ID:", policyId);
```

The native script enforces two conditions:

* `before` - Minting is only valid before the specified slot
* `sig` - The transaction must be signed by your wallet

**What to expect:** A deterministic policy ID derived from the script.

### Step 7: Create the metadata function

Add the CIP-25 metadata generator:

```typescript
type NFTMetadata = {
  name: string;
  image: string;
  mediaType: string;
  description?: string;
  attributes?: Record<string, unknown>;
  files?: Array<{
    mediaType: string;
    name: string;
    src: string;
  }>;
};

function createMetadata(
  name: string,
  imageIpfs: string,
  attributes?: Record<string, unknown>
): NFTMetadata {
  return {
    name,
    image: imageIpfs,
    mediaType: "image/png",
    description: `${name} from my NFT collection`,
    attributes,
    files: [
      {
        mediaType: "image/png",
        name,
        src: imageIpfs,
      },
    ],
  };
}
```

**What to expect:** A function that generates CIP-25 compliant metadata.

### Step 8: Build the minting transaction

Add the transaction building logic:

```typescript
// Prepare metadata for all NFTs
const collectionMetadata: {
  [policyId: string]: { [assetName: string]: NFTMetadata };
} = { [policyId]: {} };

const txBuilder = new MeshTxBuilder({ fetcher: provider });

// Mint 9 NFTs
const COLLECTION_SIZE = 9;
const IMAGE_IPFS = "ipfs://QmPS4PBvpGc2z6Dd6JdYqfHrKnURjtRGPTJWdhnAXNA8bQ";

for (let i = 1; i <= COLLECTION_SIZE; i++) {
  const tokenName = `MyNFT #${i}`;
  const tokenNameHex = stringToHex(tokenName);

  // Add mint instruction
  txBuilder
    .mint("1", policyId, tokenNameHex)
    .mintingScript(forgingScript);

  // Add metadata
  collectionMetadata[policyId][tokenName] = createMetadata(
    tokenName,
    IMAGE_IPFS,
    { edition: i, rarity: i <= 3 ? "rare" : "common" }
  );
}

// Complete and submit the transaction
const unsignedTx = await txBuilder
  .metadataValue(721, collectionMetadata)
  .changeAddress(address)
  .invalidHereafter(LOCK_SLOT)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Transaction submitted!");
console.log("Transaction hash:", txHash);
console.log(`View on explorer: https://preprod.cardanoscan.io/transaction/${txHash}`);
```

**What to expect:** The transaction mints 9 NFTs and sends them to your wallet.

### Step 9: Run the minting script

Execute the complete script:

```bash
bun run index.ts
```

**What to expect:** Console output showing the transaction hash. After 1-2 minutes, your NFTs appear in your wallet.

## Complete Example

Here is the complete `index.ts`:

```typescript
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex,
  deserializeAddress,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import type { NativeScript } from "@meshsdk/core";

// Configuration
const BLOCKFROST_KEY = process.env.BLOCKFROST_KEY!;
const MNEMONIC = process.env.MNEMONIC!;
const LOCK_SLOT = 90000000;
const COLLECTION_SIZE = 9;
const IMAGE_IPFS = "ipfs://QmPS4PBvpGc2z6Dd6JdYqfHrKnURjtRGPTJWdhnAXNA8bQ";

if (!BLOCKFROST_KEY || !MNEMONIC) {
  throw new Error("Missing environment variables");
}

// Types
type NFTMetadata = {
  name: string;
  image: string;
  mediaType: string;
  description?: string;
  attributes?: Record<string, unknown>;
  files?: Array<{ mediaType: string; name: string; src: string }>;
};

function createMetadata(
  name: string,
  imageIpfs: string,
  attributes?: Record<string, unknown>
): NFTMetadata {
  return {
    name,
    image: imageIpfs,
    mediaType: "image/png",
    description: `${name} from my NFT collection`,
    attributes,
    files: [{ mediaType: "image/png", name, src: imageIpfs }],
  };
}

async function main() {
  // Initialize
  const provider = new BlockfrostProvider(BLOCKFROST_KEY);
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    mnemonic: MNEMONIC.split(" "),
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
  });

  const address = await wallet.getChangeAddressBech32();
  const utxos = await wallet.getUtxosMesh();
  const { pubKeyHash } = deserializeAddress(address);

  console.log("Wallet:", address);
  console.log("UTxOs:", utxos.length);

  // Create minting policy
  const nativeScript: NativeScript = {
    type: "all",
    scripts: [
      { type: "before", slot: LOCK_SLOT.toString() },
      { type: "sig", keyHash: pubKeyHash },
    ],
  };

  const forgingScript = ForgeScript.fromNativeScript(nativeScript);
  const policyId = resolveScriptHash(forgingScript);
  console.log("Policy ID:", policyId);

  // Build transaction
  const collectionMetadata: Record<string, Record<string, NFTMetadata>> = {
    [policyId]: {},
  };
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  for (let i = 1; i <= COLLECTION_SIZE; i++) {
    const tokenName = `MyNFT #${i}`;
    const tokenNameHex = stringToHex(tokenName);

    txBuilder.mint("1", policyId, tokenNameHex).mintingScript(forgingScript);
    collectionMetadata[policyId][tokenName] = createMetadata(tokenName, IMAGE_IPFS, {
      edition: i,
      rarity: i <= 3 ? "rare" : "common",
    });
  }

  const unsignedTx = await txBuilder
    .metadataValue(721, collectionMetadata)
    .changeAddress(address)
    .invalidHereafter(LOCK_SLOT)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Success! TX:", txHash);
  console.log(`https://preprod.cardanoscan.io/transaction/${txHash}`);
}

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

## Next Steps

* **Add unique images** - Upload artwork to IPFS and use unique hashes per NFT
* **Expand metadata** - Add more attributes following the [CIP-25 specification](https://cips.cardano.org/cip/CIP-25)
* **Deploy to mainnet** - Change `networkId` to `1` and use a mainnet Blockfrost key
* <Link href="/guides/multisig-minting">Multi-signature minting</Link> - Let users pay for minting

## Troubleshooting

### Slot has already passed

**Cause:** The `LOCK_SLOT` value is in the past.

**Solution:** Check the current slot on [preprod.cardanoscan.io](https://preprod.cardanoscan.io/) and set `LOCK_SLOT` to a value at least a few hours in the future.

### Transaction too large

**Cause:** Minting too many NFTs in one transaction.

**Solution:** Reduce `COLLECTION_SIZE` or split into multiple transactions. A single transaction can typically handle 20-50 mints depending on metadata size.

### Invalid metadata

**Cause:** Metadata does not follow CIP-25 format.

**Solution:** Ensure the metadata structure matches CIP-25 requirements. The top-level key must be the policy ID, and each asset must have `name` and `image` fields.

### Insufficient funds

**Cause:** Not enough ADA to cover the transaction fee and min-UTXO requirements.

**Solution:** Request more test ADA from the faucet. Each NFT requires approximately 1.5 ADA for the min-UTXO deposit.

## References

* [CIP-25: Media NFT Metadata Standard](https://cips.cardano.org/cip/CIP-0025) - The Cardano standard for NFT metadata used in this guide
* [Cardano Developer Portal: Native Tokens](https://developers.cardano.org/docs/native-tokens/) - Official documentation on Cardano's native multi-asset system
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources and tools

## Related Links

* <Link href="https://cips.cardano.org/cip/CIP-25">CIP-25 Metadata Standard</Link> - Official NFT metadata specification
* <Link href="https://docs.cardano.org/cardano-testnets/tools/faucet">Cardano Testnet Faucet</Link> - Get free test ADA
* <Link href="https://blockfrost.io/">Blockfrost</Link> - API provider for Cardano
* <Link href="/guides/minting-on-nodejs">Server-Side Minting</Link> - Mint and distribute tokens
* <Link href="/apis/txbuilder/minting">Minting API Reference</Link> - Advanced minting options


# Fix Node.js Polyfill Errors in Browser Projects
URL: /guides/node-specific-imports

Resolve 'Buffer is not defined' and Node.js polyfill errors in React, Vue, Svelte, and Angular with Mesh SDK.

***

title: "Fix Node.js Polyfill Errors in Browser Projects"
description: "Resolve 'Buffer is not defined' and Node.js polyfill errors in React, Vue, Svelte, and Angular with Mesh SDK."
----------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Fix Node.js Buffer and Polyfill Errors in Browser Projects"
  description="Resolve Buffer is not defined and Node.js polyfill errors when building Cardano dApps for the browser."
  totalTime="PT15M"
  steps={[
  { name: "Identify error", text: "Recognize Buffer is not defined or similar polyfill errors." },
  { name: "Install polyfills", text: "Install buffer, process, and stream-browserify packages." },
  { name: "Configure bundler", text: "Add polyfill configuration for your framework." },
  { name: "Test build", text: "Verify the application builds and runs correctly." }
]}
/>

## Overview

When building Cardano dApps for the browser, you may encounter errors like `Buffer is not defined`. This happens because Mesh SDK uses Node.js APIs that are not available in browsers by default.

### Common error messages

```
Uncaught ReferenceError: Buffer is not defined
Module not found: Can't resolve 'buffer'
ReferenceError: TextEncoder is not defined
```

### Affected modules

| Module                        | Purpose                  |
| ----------------------------- | ------------------------ |
| `Buffer`                      | Binary data handling     |
| `TextEncoder` / `TextDecoder` | String encoding          |
| `crypto`                      | Cryptographic operations |
| `process`                     | Environment variables    |
| `stream`                      | Data streaming           |

Modern bundlers (Webpack 5, Vite) do not automatically polyfill these. This guide shows you how to fix these errors for each framework.

### Time to complete

15 minutes

## What Are Polyfills?

Polyfills are packages that implement Node.js functionality for browsers. You configure your bundler to use these browser-compatible versions instead of Node.js modules.

Install the common polyfills:

```bash
npm install buffer process stream-browserify crypto-browserify --save
```

## Framework-Specific Solutions

### Next.js

Next.js uses Webpack internally. Add the polyfill plugin:

```bash
npm install node-polyfill-webpack-plugin --save-dev
```

Update `next.config.js`:

```javascript
const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    // Only add polyfills for client-side
    if (!isServer) {
      config.plugins.push(new NodePolyfillPlugin());
    }
    return config;
  },
};

module.exports = nextConfig;
```

**What to expect:** The build completes without polyfill errors.

### Vite (React, Vue, Svelte)

Vite uses Rollup. Install the polyfill plugin:

```bash
npm install rollup-plugin-polyfill-node --save-dev
```

Update `vite.config.ts`:

```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react"; // or vue, svelte
import rollupNodePolyFill from "rollup-plugin-polyfill-node";

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      plugins: [rollupNodePolyFill()],
    },
  },
  resolve: {
    alias: {
      buffer: "rollup-plugin-polyfill-node/polyfills/buffer-es6",
      process: "rollup-plugin-polyfill-node/polyfills/process-es6",
    },
  },
});
```

If you still see errors, add this to your entry file:

```typescript
import { Buffer } from "buffer";
globalThis.Buffer = globalThis.Buffer || Buffer;
```

**What to expect:** The dev server and production build work correctly.

### Webpack 5

Webpack 5 removed automatic Node.js polyfills. Choose one approach:

**Option 1: Use NodePolyfillPlugin (recommended)**

```bash
npm install node-polyfill-webpack-plugin --save-dev
```

Update `webpack.config.js`:

```javascript
const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");

module.exports = {
  plugins: [
    new NodePolyfillPlugin(),
  ],
};
```

**Option 2: Manual resolve.fallback**

```bash
npm install buffer process stream-browserify --save
```

Update `webpack.config.js`:

```javascript
module.exports = {
  resolve: {
    fallback: {
      buffer: require.resolve("buffer/"),
      process: require.resolve("process/browser"),
      stream: require.resolve("stream-browserify"),
    },
  },
};
```

**What to expect:** Webpack builds without module resolution errors.

### Create React App (CRA)

CRA uses Webpack 5 but does not expose the config. Use CRACO to override:

```bash
npm install @craco/craco node-polyfill-webpack-plugin --save-dev
```

Update `package.json` scripts:

```json
{
  "scripts": {
    "start": "craco start",
    "build": "craco build",
    "test": "craco test"
  }
}
```

Create `craco.config.js`:

```javascript
const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");

module.exports = {
  webpack: {
    plugins: {
      add: [new NodePolyfillPlugin()],
    },
  },
};
```

**What to expect:** CRA builds with polyfills applied.

### Angular

Angular uses Webpack internally. Use `ngx-build-plus` to extend the config:

```bash
npm install ngx-build-plus node-polyfill-webpack-plugin buffer process stream-browserify --save-dev
```

Update `angular.json`:

```json
{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "ngx-build-plus:browser"
        },
        "serve": {
          "builder": "ngx-build-plus:dev-server"
        }
      }
    }
  }
}
```

Create `webpack.config.js`:

```javascript
const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");

module.exports = {
  plugins: [new NodePolyfillPlugin()],
};
```

Build with the extra config:

```bash
ng build --extra-webpack-config webpack.config.js
```

**What to expect:** Angular builds with Node.js polyfills.

### SvelteKit

SvelteKit uses Vite. Follow the Vite instructions above, but update `svelte.config.js`:

```javascript
import adapter from "@sveltejs/adapter-auto";
import { vitePreprocess } from "@sveltejs/kit/vite";

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter(),
  },
};

export default config;
```

And `vite.config.ts`:

```typescript
import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";
import rollupNodePolyFill from "rollup-plugin-polyfill-node";

export default defineConfig({
  plugins: [sveltekit()],
  build: {
    rollupOptions: {
      plugins: [rollupNodePolyFill()],
    },
  },
});
```

**What to expect:** SvelteKit handles Node.js modules correctly.

## Complete Example: Next.js

Here is a complete Next.js setup:

**package.json:**

```json
{
  "dependencies": {
    "@meshsdk/core": "^1.0.0",
    "@meshsdk/react": "^1.0.0",
    "next": "14.0.0",
    "react": "18.2.0"
  },
  "devDependencies": {
    "node-polyfill-webpack-plugin": "^3.0.0"
  }
}
```

**next.config.js:**

```javascript
const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.plugins.push(new NodePolyfillPlugin());
    }
    return config;
  },
};

module.exports = nextConfig;
```

## Next Steps

* <Link href="/guides/nextjs">Build your first dApp</Link> - Complete Next.js integration
* <Link href="/svelte">Svelte integration</Link> - Use Mesh with Svelte
* <Link href="/apis/wallets/browserwallet">BrowserWallet API</Link> - Connect browser wallets

## Troubleshooting

### Error persists after configuration

**Cause:** Bundler cache contains old build artifacts.

**Solution:** Clear the cache and rebuild:

```bash
# Next.js
rm -rf .next node_modules/.cache
npm run build

# Vite
rm -rf node_modules/.vite
npm run build
```

### Multiple Buffer definitions

**Cause:** Different packages include conflicting Buffer implementations.

**Solution:** Ensure only one Buffer polyfill is used:

```typescript
// Add to entry file
import { Buffer } from "buffer";
if (typeof window !== "undefined") {
  window.Buffer = window.Buffer || Buffer;
}
```

### Runtime errors despite successful build

**Cause:** Polyfills are configured for build but not dev server.

**Solution:** Ensure polyfill configuration applies to both build and dev. For Vite, add to `optimizeDeps`:

```typescript
export default defineConfig({
  optimizeDeps: {
    include: ["buffer", "process"],
  },
});
```

### Cannot resolve 'fs' or 'path'

**Cause:** Server-only modules are imported in client code.

**Solution:** These modules cannot be polyfilled. Use dynamic imports or conditional loading:

```typescript
// Mark as client-only in Next.js
"use client";

// Or use dynamic import
const MeshComponent = dynamic(() => import("./MeshComponent"), {
  ssr: false,
});
```

## Related Links

* <Link href="/guides/nextjs">Next.js Integration Guide</Link>
* <Link href="https://webpack.js.org/configuration/resolve/#resolvefallback">Webpack Resolve Fallback</Link>
* <Link href="https://vitejs.dev/config/build-options.html">Vite Build Options</Link>


# Deploy Cardano dApps to Production
URL: /guides/production-deployment

Security best practices, deployment checklists, and error handling for production Cardano dApps with Mesh SDK.

***

title: "Deploy Cardano dApps to Production"
description: "Security best practices, deployment checklists, and error handling for production Cardano dApps with Mesh SDK."
-----------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Deploy Cardano dApps to Production"
  description="Comprehensive checklist for deploying secure, reliable Cardano dApps to production environments."
  totalTime="PT90M"
  steps={[
  { name: "Secure private keys", text: "Use browser wallets for users, isolate server-side signing." },
  { name: "Validate transactions", text: "Check amounts, addresses, and metadata before building." },
  { name: "Configure providers", text: "Set up primary and fallback providers with health checks." },
  { name: "Implement error handling", text: "Handle failures gracefully with user-friendly messages." },
  { name: "Set up monitoring", text: "Track transaction metrics and infrastructure health." }
]}
/>

## Overview

Deploying Cardano dApps to production requires attention to security, reliability, and user experience. This guide covers essential practices for enterprise-grade deployments.

### What you will learn

* Private key management best practices
* Transaction validation patterns
* Provider configuration and failover
* Error handling strategies
* Monitoring and alerting setup

### Prerequisites

* A working Cardano dApp (see <Link href="/guides/nextjs">Next.js guide</Link>)
* Basic understanding of deployment environments
* Access to production infrastructure

### Time to complete

90 minutes to review and implement

## Security Best Practices

### Private Key Management

**Never expose private keys in client-side code.** For production applications:

**Browser wallets for users:**

Let users manage their own keys through wallet extensions. The `MeshCardanoBrowserWallet` class handles CIP-30 wallet connections without your application touching private keys:

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

// User controls their own keys
const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const signedTx = await wallet.signTx(unsignedTx, false);
```

**Server-side signing:**

When your application must sign transactions (automated systems, treasury):

```typescript
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Store mnemonic in environment variables or secret manager
const mnemonic = process.env.TREASURY_MNEMONIC;

// Never log or expose the mnemonic
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 1,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: mnemonic.split(" "),
});
```

**Security checklist:**

* [ ] Use environment variables for credentials
* [ ] Run signing services in isolated network segments
* [ ] Implement audit logging for all signing operations
* [ ] Consider hardware security modules (HSMs) for high-value operations
* [ ] Rotate keys periodically

### Transaction Validation

Validate all parameters before building transactions:

```typescript
function validateTransaction(params: {
  recipient: string;
  amount: string;
}) {
  // Check amount is positive and within bounds
  const lovelace = BigInt(params.amount);
  if (lovelace <= 0n) {
    throw new Error("Amount must be positive");
  }
  if (lovelace > 45_000_000_000_000_000n) {
    throw new Error("Amount exceeds maximum supply");
  }

  // Validate address format
  if (!params.recipient.startsWith("addr")) {
    throw new Error("Invalid Cardano address");
  }

  // Check minimum UTxO requirement
  if (lovelace < 1_000_000n) {
    throw new Error("Amount below minimum UTxO");
  }
}
```

### API Key Protection

Never expose provider API keys in client-side code:

```typescript
// BAD: Key exposed in browser bundle
const provider = new BlockfrostProvider("proj_live_abc123");

// GOOD: Proxy through your backend
const response = await fetch("/api/blockchain/utxos", {
  method: "POST",
  body: JSON.stringify({ address }),
});
```

**API route example:**

```typescript
// app/api/blockchain/utxos/route.ts
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider(process.env.BLOCKFROST_KEY!);

export async function POST(request: Request) {
  const { address } = await request.json();
  const utxos = await provider.fetchAddressUTxOs(address);
  return Response.json(utxos);
}
```

## Deployment Checklist

### Pre-Launch Infrastructure

| Task                                                     | Status |
| -------------------------------------------------------- | ------ |
| Provider API keys stored securely (not in client bundle) | \[ ]   |
| Backend proxy configured for blockchain queries          | \[ ]   |
| Rate limiting implemented on API endpoints               | \[ ]   |
| Error monitoring and alerting configured                 | \[ ]   |
| Load testing completed for expected traffic              | \[ ]   |

### Smart Contracts

| Task                                            | Status |
| ----------------------------------------------- | ------ |
| Contracts audited by independent party          | \[ ]   |
| Testnet deployment validated thoroughly         | \[ ]   |
| Contract addresses verified on mainnet          | \[ ]   |
| Reference scripts deployed if used              | \[ ]   |
| Monitoring configured for contract interactions | \[ ]   |

### Application

| Task                                                 | Status |
| ---------------------------------------------------- | ------ |
| Console.log statements removed from production build | \[ ]   |
| Source maps disabled or properly secured             | \[ ]   |
| CSP headers configured appropriately                 | \[ ]   |
| HTTPS enforced with valid certificates               | \[ ]   |
| Input validation comprehensive                       | \[ ]   |

## Provider Configuration

### Provider Selection

For production applications, consider:

| Provider           | Strength                       | Consideration                |
| ------------------ | ------------------------------ | ---------------------------- |
| Blockfrost         | Reliability, documentation     | Rate limits on free tier     |
| Koios              | Free tier, decentralized       | Self-hosted option available |
| Maestro            | Rich data, marketplace support | Enterprise pricing           |
| Self-hosted Ogmios | Full control, no rate limits   | Infrastructure overhead      |

### Provider Failover

Implement automatic failover when providers fail:

```typescript
class ResilientProvider implements IFetcher {
  private providers: IFetcher[];
  private currentIndex = 0;

  constructor(providers: IFetcher[]) {
    this.providers = providers;
  }

  async fetchAddressUTxOs(address: string, asset?: string) {
    for (let attempt = 0; attempt < this.providers.length; attempt++) {
      try {
        const index = (this.currentIndex + attempt) % this.providers.length;
        return await this.providers[index].fetchAddressUTxOs(address, asset);
      } catch (error) {
        console.warn(`Provider ${attempt} failed, trying next`);
      }
    }
    throw new Error("All providers failed");
  }

  // Implement other IFetcher methods similarly
}

// Usage
const provider = new ResilientProvider([
  new BlockfrostProvider(process.env.BLOCKFROST_KEY!),
  new KoiosProvider("mainnet"),
]);
```

### Network Selection

| Network | Use Case                         |
| ------- | -------------------------------- |
| Preview | Testing new features, unstable   |
| Preprod | Production-like testing, staging |
| Mainnet | Production deployment            |

## Error Handling

### Transaction Failures

Handle failures gracefully with user-friendly messages:

```typescript
async function submitTransaction(unsignedTx: string) {
  try {
    const signedTx = await wallet.signTx(unsignedTx);
    const txHash = await wallet.submitTx(signedTx);
    return { success: true, txHash };
  } catch (error: any) {
    // Parse and categorize errors
    if (error.message.includes("INSUFFICIENT_FUNDS")) {
      return {
        success: false,
        error: "Insufficient funds. Please add more ADA to your wallet.",
      };
    }

    if (error.message.includes("UTXO_ALREADY_SPENT")) {
      return {
        success: false,
        error: "Transaction conflict. Please try again.",
      };
    }

    if (error.message.includes("User rejected")) {
      return {
        success: false,
        error: "Transaction cancelled.",
      };
    }

    // Log technical details for debugging
    console.error("Transaction failed:", error);

    return {
      success: false,
      error: "Transaction failed. Please try again later.",
    };
  }
}
```

### UTxO Contention

In high-traffic applications, UTxOs may be spent between query and submission:

```typescript
async function buildWithRetry(
  buildFn: () => Promise<string>,
  maxRetries = 3
) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await buildFn();
    } catch (error: any) {
      if (
        error.message.includes("UTXO_ALREADY_SPENT") &&
        attempt < maxRetries - 1
      ) {
        // Wait briefly and retry with fresh UTxOs
        await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
        continue;
      }
      throw error;
    }
  }
}
```

## Performance Optimization

### Bundle Size

Minimize client bundle size:

```typescript
// Import specific functions instead of entire package
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

// Use dynamic imports for wallet-specific features
const ConnectWallet = dynamic(() => import("./ConnectWallet"), {
  ssr: false,
});
```

### Caching

Reduce redundant blockchain queries:

```typescript
class CachedProvider implements IFetcher {
  private provider: IFetcher;
  private cache = new Map<string, { data: any; expiry: number }>();

  constructor(provider: IFetcher) {
    this.provider = provider;
  }

  async fetchProtocolParameters(epoch?: number) {
    const cacheKey = `protocol-${epoch || "current"}`;
    const cached = this.cache.get(cacheKey);

    if (cached && cached.expiry > Date.now()) {
      return cached.data;
    }

    const data = await this.provider.fetchProtocolParameters(epoch);

    // Cache for 1 hour (protocol params rarely change)
    this.cache.set(cacheKey, {
      data,
      expiry: Date.now() + 3600000,
    });

    return data;
  }

  // Implement other methods with appropriate cache TTLs
}
```

## Monitoring

### Key Metrics

Track these metrics for production dApps:

**Transaction metrics:**

* Submission success rate
* Average confirmation time
* Failed transaction breakdown by error type
* Transaction fee distribution

**User metrics:**

* Wallet connection success rate
* Transaction abandonment rate
* Error frequency by type

**Infrastructure metrics:**

* Provider response times
* API endpoint latency
* Error rates by endpoint

### Alerting

Configure alerts for:

* Sustained transaction failure rates above 5%
* Provider connectivity issues lasting > 1 minute
* Smart contract interaction anomalies
* Unusual transaction patterns

## Next Steps

* <Link href="/providers">Configure providers</Link> for your deployment
* <Link href="/guides/aiken">Review smart contract security</Link>
* <Link href="https://discord.gg/dH48jH3BKa">Join the community</Link> for support

## Troubleshooting

### Transactions timing out

**Cause:** Network congestion or provider issues.

**Solution:** Implement longer timeouts and retry logic. Consider using multiple providers for redundancy.

### Wallet connection failing in production

**Cause:** CSP headers blocking wallet extension communication.

**Solution:** Configure Content Security Policy to allow wallet connections:

```javascript
// next.config.js
const securityHeaders = [
  {
    key: "Content-Security-Policy",
    value: "default-src 'self'; script-src 'self' 'unsafe-eval';",
  },
];
```

### Rate limiting errors

**Cause:** Exceeding provider API limits.

**Solution:** Implement request queuing, caching, or upgrade to a higher tier. Consider self-hosted options for high-traffic applications.

## Related Links

* <Link href="/providers">Blockchain Providers</Link>
* <Link href="/guides/aiken">Smart Contract Security</Link>
* <Link href="https://discord.gg/dH48jH3BKa">Mesh Discord Community</Link>


# Prove Wallet Ownership with Message Signing
URL: /guides/prove-wallet-ownership

Implement Sign-in with Cardano authentication using CIP-8 message signing and Mesh SDK.

***

title: "Prove Wallet Ownership with Message Signing"
description: "Implement Sign-in with Cardano authentication using CIP-8 message signing and Mesh SDK."
------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Prove Wallet Ownership with Cardano Message Signing"
  description="Implement Sign in with Cardano authentication using CIP-8 message signing."
  totalTime="PT30M"
  steps={[
  { name: "Get user address", text: "Connect wallet and retrieve the user's address." },
  { name: "Generate nonce", text: "Create a random nonce on the server and store it." },
  { name: "Sign nonce", text: "User signs the nonce with their wallet." },
  { name: "Verify signature", text: "Server verifies signature matches the address." }
]}
/>

## Overview

Wallet ownership verification lets users prove they control a Cardano address by signing a message with their private key. This uses the [CIP-8](https://cips.cardano.org/cip/CIP-0008) message signing standard and the [CIP-30](https://cips.cardano.org/cip/CIP-0030) wallet interface. Together, these standards form the foundation for "Sign in with Cardano" authentication.

### What you will build

* A nonce generation system for replay attack prevention
* Client-side message signing with CIP-8
* Server-side signature verification

### Common use cases

* **User authentication** - Replace passwords with wallet-based sign-in
* **Action authorization** - Verify consent for off-chain operations
* **Access control** - Gate content to specific wallet holders

### Prerequisites

* A Next.js application with Mesh SDK
* Basic understanding of authentication flows

### Time to complete

30 minutes

## How It Works

![Authentication flow diagram](/guides/cryptographically-prove-wallet-ownership-process.png)

The authentication flow:

1. User connects wallet and provides their address
2. Server generates a unique nonce and stores it
3. User signs the nonce with their private key
4. Server verifies the signature matches the claimed address
5. Server issues a session token (JWT, cookie, etc.)

The nonce prevents replay attacks - each authentication attempt requires a fresh signature.

## Step-by-Step Guide

### Step 1: Get the user address

Connect the wallet and get the user's address on the client:

```typescript
// components/SignIn.tsx
"use client";

import { CardanoWallet, useWallet } from "@meshsdk/react";

export function SignIn() {
  const { wallet, connected } = useWallet();

  async function startLogin() {
    if (!connected) return;

    // Get the user's first used address
    const userAddress = (await wallet.getUsedAddresses())[0];

    // Send to server to get a nonce
    const response = await fetch("/api/auth/nonce", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ address: userAddress }),
    });

    const { nonce } = await response.json();
    console.log("Received nonce:", nonce);
  }

  return (
    <div>
      <CardanoWallet />
      {connected && (
        <button onClick={startLogin}>Sign In</button>
      )}
    </div>
  );
}
```

**What to expect:** The wallet connects and sends the address to your server.

### Step 2: Generate a nonce on the server

Create an API route that generates and stores nonces:

```typescript
// app/api/auth/nonce/route.ts
import { NextResponse } from "next/server";
import { generateNonce } from "@meshsdk/core";

// In production, use a database
const nonceStore = new Map<string, { nonce: string; expires: number }>();

export async function POST(request: Request) {
  const { address } = await request.json();

  // Generate a nonce with a custom message prefix
  const nonce = generateNonce("Sign this message to authenticate with MyApp: ");

  // Store with 5-minute expiration
  nonceStore.set(address, {
    nonce,
    expires: Date.now() + 5 * 60 * 1000,
  });

  return NextResponse.json({ nonce });
}

// Export for use in verification
export { nonceStore };
```

**What to expect:** A unique nonce is generated and stored for each address.

### Step 3: Sign the nonce with the wallet

Update the client to sign the nonce:

```typescript
// components/SignIn.tsx
"use client";

import { useState } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";

export function SignIn() {
  const { wallet, connected } = useWallet();
  const [status, setStatus] = useState<"idle" | "signing" | "verifying" | "authenticated">("idle");

  async function handleSignIn() {
    if (!connected) return;

    try {
      setStatus("signing");

      // Get user address
      const userAddress = (await wallet.getUsedAddresses())[0];

      // Get nonce from server
      const nonceRes = await fetch("/api/auth/nonce", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ address: userAddress }),
      });
      const { nonce } = await nonceRes.json();

      // Sign the nonce with the wallet
      const signature = await wallet.signData(nonce, userAddress);

      // Verify signature on server
      setStatus("verifying");
      const verifyRes = await fetch("/api/auth/verify", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          address: userAddress,
          signature,
        }),
      });

      const { success, token } = await verifyRes.json();

      if (success) {
        setStatus("authenticated");
        // Store token, update state, redirect, etc.
        console.log("Authenticated! Token:", token);
      } else {
        setStatus("idle");
        console.error("Authentication failed");
      }
    } catch (error) {
      console.error("Sign-in error:", error);
      setStatus("idle");
    }
  }

  return (
    <div className="space-y-4">
      <CardanoWallet
        label={status === "authenticated" ? "Connected" : "Sign In with Cardano"}
        onConnected={handleSignIn}
      />

      {status === "signing" && <p>Please sign the message in your wallet...</p>}
      {status === "verifying" && <p>Verifying signature...</p>}
      {status === "authenticated" && <p>Welcome! You are authenticated.</p>}
    </div>
  );
}
```

**What to expect:** The wallet prompts the user to sign a message.

### Step 4: Verify the signature on the server

Create an API route that verifies signatures:

```typescript
// app/api/auth/verify/route.ts
import { NextResponse } from "next/server";
import { checkSignature } from "@meshsdk/core";
import { nonceStore } from "../nonce/route";

export async function POST(request: Request) {
  const { address, signature } = await request.json();

  // Retrieve stored nonce
  const stored = nonceStore.get(address);

  if (!stored) {
    return NextResponse.json(
      { success: false, error: "No nonce found for address" },
      { status: 400 }
    );
  }

  // Check expiration
  if (Date.now() > stored.expires) {
    nonceStore.delete(address);
    return NextResponse.json(
      { success: false, error: "Nonce expired" },
      { status: 400 }
    );
  }

  // Verify the signature
  const isValid = checkSignature(stored.nonce, signature, address);

  // Always invalidate nonce after use (prevent replay)
  nonceStore.delete(address);

  if (!isValid) {
    return NextResponse.json(
      { success: false, error: "Invalid signature" },
      { status: 401 }
    );
  }

  // Create session token (use your preferred method)
  const token = createSessionToken(address);

  return NextResponse.json({ success: true, token });
}

function createSessionToken(address: string): string {
  // In production, use proper JWT signing
  return Buffer.from(JSON.stringify({
    address,
    iat: Date.now(),
    exp: Date.now() + 24 * 60 * 60 * 1000, // 24 hours
  })).toString("base64");
}
```

**What to expect:** The server verifies the signature and issues a session token.

## Complete Example

Here is a complete implementation with all components:

**components/AuthProvider.tsx:**

```typescript
"use client";

import { createContext, useContext, useState, ReactNode } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";

interface AuthContextType {
  isAuthenticated: boolean;
  address: string | null;
  signIn: () => Promise<void>;
  signOut: () => void;
}

const AuthContext = createContext<AuthContextType | null>(null);

export function AuthProvider({ children }: { children: ReactNode }) {
  const { wallet, connected } = useWallet();
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const [address, setAddress] = useState<string | null>(null);

  async function signIn() {
    if (!connected) return;

    const userAddress = (await wallet.getUsedAddresses())[0];

    // Get nonce
    const nonceRes = await fetch("/api/auth/nonce", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ address: userAddress }),
    });
    const { nonce } = await nonceRes.json();

    // Sign nonce
    const signature = await wallet.signData(nonce, userAddress);

    // Verify
    const verifyRes = await fetch("/api/auth/verify", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ address: userAddress, signature }),
    });
    const { success } = await verifyRes.json();

    if (success) {
      setIsAuthenticated(true);
      setAddress(userAddress);
    }
  }

  function signOut() {
    setIsAuthenticated(false);
    setAddress(null);
  }

  return (
    <AuthContext.Provider value={{ isAuthenticated, address, signIn, signOut }}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) throw new Error("useAuth must be used within AuthProvider");
  return context;
}
```

**Usage in a page:**

```typescript
import { CardanoWallet, useWallet } from "@meshsdk/react";
import { useAuth } from "@/components/AuthProvider";

export default function ProtectedPage() {
  const { connected } = useWallet();
  const { isAuthenticated, address, signIn, signOut } = useAuth();

  if (!connected) {
    return <CardanoWallet label="Connect Wallet" />;
  }

  if (!isAuthenticated) {
    return (
      <button onClick={signIn}>
        Sign In with Cardano
      </button>
    );
  }

  return (
    <div>
      <p>Welcome, {address?.slice(0, 16)}...</p>
      <button onClick={signOut}>Sign Out</button>
      {/* Protected content here */}
    </div>
  );
}
```

## Next Steps

* <Link href="/guides/production-deployment">Production deployment</Link> - Security best practices
* <Link href="/apis/wallets/browserwallet">BrowserWallet API</Link> - More wallet methods
* <Link href="https://cips.cardano.org/cip/CIP-8">CIP-8 Specification</Link> - Message signing standard

## Troubleshooting

### Signature verification fails

**Cause:** The address used for signing does not match the one verified.

**Solution:** Ensure you use the same address for both operations:

```typescript
// Use the same address for signing and verification
const address = (await wallet.getUsedAddresses())[0];
const signature = await wallet.signData(nonce, address);
// Send this exact address to the server
```

### Nonce expired

**Cause:** User took too long to sign.

**Solution:** Increase the expiration time or implement retry logic:

```typescript
// Increase to 10 minutes
expires: Date.now() + 10 * 60 * 1000,
```

### User rejected signing

**Cause:** User clicked "Cancel" in the wallet popup.

**Solution:** Catch the error and allow retry:

```typescript
try {
  const signature = await wallet.signData(nonce, address);
} catch (error) {
  if (error.message.includes("User rejected")) {
    // Show "Please sign to continue" message
  }
}
```

### Invalid signature format

**Cause:** The signature object is not serialized correctly.

**Solution:** The `signData` method returns a signature object. Pass it directly to `checkSignature`:

```typescript
// Client
const signature = await wallet.signData(nonce, address);
// signature is { signature: string, key: string }

// Server
checkSignature(nonce, signature, address);
// Not checkSignature(nonce, signature.signature, address)
```

## Security Best Practices

* **Always regenerate nonces** - A used nonce must never be valid again
* **Set short expiration** - 5-10 minutes maximum for unused nonces
* **Use HTTPS** - Protect the signature during transmission
* **Validate addresses** - Check format before database operations
* **Rate limit requests** - Prevent brute force attempts
* **Log authentication events** - Monitor for suspicious activity

## References

* [CIP-8: Message Signing](https://cips.cardano.org/cip/CIP-0008) - The Cardano standard for signing and verifying arbitrary data with private keys
* [CIP-30: dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-0030) - The standard enabling wallet connectivity in web applications
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources

## Related Links

* <Link href="https://cips.cardano.org/cip/CIP-8">CIP-8 Message Signing</Link>
* <Link href="/apis/wallets/browserwallet">BrowserWallet API</Link>
* <Link href="/guides/production-deployment">Production Deployment</Link>


# Build NFT Marketplace Smart Contract Transactions
URL: /guides/smart-contract-transactions

Build transactions for listing, purchasing, canceling, and updating NFTs with Cardano smart contracts using Mesh SDK.

***

title: "Build NFT Marketplace Smart Contract Transactions"
description: "Build transactions for listing, purchasing, canceling, and updating NFTs with Cardano smart contracts using Mesh SDK."
------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Build NFT Marketplace Transactions with Cardano Smart Contracts"
  description="Construct listing, purchasing, canceling, and updating transactions for an NFT marketplace on Cardano."
  totalTime="PT60M"
  steps={[
  { name: "Load Plutus script", text: "Initialize the compiled contract and resolve script address." },
  { name: "List an asset", text: "Send NFT to script address with datum containing sale details." },
  { name: "Cancel listing", text: "Redeem UTxO as seller with cancel redeemer." },
  { name: "Purchase asset", text: "Pay seller and receive NFT with buy redeemer." },
  { name: "Update price", text: "Redeem and re-list with new datum." }
]}
/>

## Overview

In this guide, you build the transaction patterns for an NFT marketplace on Cardano. You learn how to construct listing, purchasing, canceling, and updating transactions using Plutus smart contracts on the [eUTXO model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/).

### What you will build

* Listing transactions that lock NFTs at a script address
* Purchase transactions that pay sellers and transfer ownership
* Cancel and update transactions for seller management

### What you will learn

* Locking assets at script addresses with datums
* Spending from scripts with redeemers
* Authorization patterns with required signers

### Prerequisites

* A deployed Plutus smart contract (see <Link href="/guides/aiken">Aiken guide</Link>)
* Next.js application with Mesh SDK
* Understanding of datums and redeemers

### Time to complete

60 minutes

## Quick Start

This guide uses a simple marketplace contract. View the complete example:

* <Link href="https://github.com/MeshJS/examples">GitHub examples repository</Link>

## Step-by-Step Guide

### Step 1: Load the Plutus script

Load your compiled marketplace contract:

```typescript
import { resolvePlutusScriptAddress } from "@meshsdk/core";
import type { PlutusScript, Data } from "@meshsdk/core";

// Your compiled Plutus script in CBOR format
const scriptCbor = "590795..."; // Full CBOR hex string

const script: PlutusScript = {
  code: scriptCbor,
  version: "V2",
};

// Get the script address (0 = testnet, 1 = mainnet)
const scriptAddress = resolvePlutusScriptAddress(script, 0);
```

**What to expect:** A script address where marketplace UTxOs are stored.

### Step 2: Define the datum structure

The datum stores sale information:

```typescript
import { resolvePaymentKeyHash } from "@meshsdk/core";

function createListingDatum(
  sellerAddress: string,
  priceLovelace: string,
  policyId: string,
  assetName: string
): Data {
  return {
    alternative: 0,
    fields: [
      resolvePaymentKeyHash(sellerAddress), // seller pubkey hash
      priceLovelace, // price in lovelace
      policyId, // NFT policy ID
      assetName, // NFT asset name (hex)
    ],
  };
}
```

**What to expect:** A datum constructor for marketplace listings.

### Step 3: List an asset for sale

Send the NFT to the script address with the listing datum:

```typescript
import { MeshTxBuilder, KoiosProvider, resolvePaymentKeyHash } from "@meshsdk/core";
import { useWallet } from "@meshsdk/react";

async function listNFT(
  policyId: string,
  assetName: string,
  priceLovelace: string
) {
  const provider = new KoiosProvider("preprod");
  const { wallet } = useWallet();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const sellerAddress = (await wallet.getUsedAddresses())[0];

  // Create the listing datum
  const datum = createListingDatum(
    sellerAddress,
    priceLovelace,
    policyId,
    assetName
  );

  const assetUnit = policyId + assetName;

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    // Send NFT to script with datum
    .txOut(scriptAddress, [{ unit: assetUnit, quantity: "1" }])
    .txOutDatumHashValue(datum)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Listed NFT:", txHash);
  return txHash;
}
```

**What to expect:** The NFT is locked at the script address with sale information in the datum.

### Step 4: Find a listing UTxO

Helper function to find a specific listing:

```typescript
import { resolveDataHash } from "@meshsdk/core";

async function findListingUtxo(
  scriptAddress: string,
  assetUnit: string,
  datum: Data
) {
  const provider = new KoiosProvider("preprod");
  const utxos = await provider.fetchAddressUTxOs(scriptAddress, assetUnit);

  if (utxos.length === 0) {
    throw new Error("No listing found for this asset");
  }

  // Match by datum hash
  const dataHash = resolveDataHash(datum);
  const listingUtxo = utxos.find(
    (utxo) => utxo.output.dataHash === dataHash
  );

  if (!listingUtxo) {
    throw new Error("Listing not found with matching datum");
  }

  return listingUtxo;
}
```

**What to expect:** A function to locate specific marketplace listings.

### Step 5: Cancel a listing

Only the seller can cancel. Use redeemer alternative 1:

```typescript
async function cancelListing(
  policyId: string,
  assetName: string,
  priceLovelace: string
) {
  const provider = new KoiosProvider("preprod");
  const { wallet } = useWallet();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const sellerAddress = (await wallet.getUsedAddresses())[0];
  const collateral = await wallet.getCollateral();

  // Recreate the original datum
  const datum = createListingDatum(
    sellerAddress,
    priceLovelace,
    policyId,
    assetName
  );

  const assetUnit = policyId + assetName;
  const listingUtxo = await findListingUtxo(scriptAddress, assetUnit, datum);

  // Cancel redeemer (alternative 1)
  const redeemer: Data = { alternative: 1, fields: [] };

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .spendingPlutusScriptV2()
    .txIn(listingUtxo.input.txHash, listingUtxo.input.outputIndex)
    .txInDatumValue(datum)
    .txInRedeemerValue(redeemer)
    .txInScript(script.code)
    // Return NFT to seller
    .txOut(sellerAddress, listingUtxo.output.amount)
    // Seller must sign
    .requiredSignerHash(resolvePaymentKeyHash(sellerAddress))
    .txInCollateral(
      collateral[0].input.txHash,
      collateral[0].input.outputIndex,
      collateral[0].output.amount,
      collateral[0].output.address
    )
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Cancelled listing:", txHash);
  return txHash;
}
```

**What to expect:** The NFT returns to the seller's wallet.

### Step 6: Purchase a listed asset

Buyer pays the seller and receives the NFT. Use redeemer alternative 0:

```typescript
async function purchaseNFT(
  sellerAddress: string,
  policyId: string,
  assetName: string,
  priceLovelace: string
) {
  const provider = new KoiosProvider("preprod");
  const { wallet } = useWallet();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const buyerAddress = (await wallet.getUsedAddresses())[0];
  const collateral = await wallet.getCollateral();

  // Reconstruct the listing datum
  const datum = createListingDatum(
    sellerAddress,
    priceLovelace,
    policyId,
    assetName
  );

  const assetUnit = policyId + assetName;
  const listingUtxo = await findListingUtxo(scriptAddress, assetUnit, datum);

  // Buy redeemer (alternative 0)
  const redeemer: Data = { alternative: 0, fields: [] };

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .spendingPlutusScriptV2()
    .txIn(listingUtxo.input.txHash, listingUtxo.input.outputIndex)
    .txInDatumValue(datum)
    .txInRedeemerValue(redeemer)
    .txInScript(script.code)
    // Send NFT to buyer
    .txOut(buyerAddress, [{ unit: assetUnit, quantity: "1" }])
    // Pay seller
    .txOut(sellerAddress, [{ unit: "lovelace", quantity: priceLovelace }])
    // Buyer must sign
    .requiredSignerHash(resolvePaymentKeyHash(buyerAddress))
    .txInCollateral(
      collateral[0].input.txHash,
      collateral[0].input.outputIndex,
      collateral[0].output.amount,
      collateral[0].output.address
    )
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Purchased NFT:", txHash);
  return txHash;
}
```

**What to expect:** The buyer receives the NFT and the seller receives payment.

### Step 7: Update listing price

Redeem the UTxO and re-list with a new price:

```typescript
async function updateListingPrice(
  policyId: string,
  assetName: string,
  currentPrice: string,
  newPrice: string
) {
  const provider = new KoiosProvider("preprod");
  const { wallet } = useWallet();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const sellerAddress = (await wallet.getUsedAddresses())[0];
  const collateral = await wallet.getCollateral();

  // Current listing datum
  const currentDatum = createListingDatum(
    sellerAddress,
    currentPrice,
    policyId,
    assetName
  );

  // New listing datum with updated price
  const newDatum = createListingDatum(
    sellerAddress,
    newPrice,
    policyId,
    assetName
  );

  const assetUnit = policyId + assetName;
  const listingUtxo = await findListingUtxo(scriptAddress, assetUnit, currentDatum);

  // Update uses cancel redeemer (alternative 1)
  const redeemer: Data = { alternative: 1, fields: [] };

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .spendingPlutusScriptV2()
    .txIn(listingUtxo.input.txHash, listingUtxo.input.outputIndex)
    .txInDatumValue(currentDatum)
    .txInRedeemerValue(redeemer)
    .txInScript(script.code)
    // Re-list at script with new datum
    .txOut(scriptAddress, [{ unit: assetUnit, quantity: "1" }])
    .txOutDatumHashValue(newDatum)
    .requiredSignerHash(resolvePaymentKeyHash(sellerAddress))
    .txInCollateral(
      collateral[0].input.txHash,
      collateral[0].input.outputIndex,
      collateral[0].output.amount,
      collateral[0].output.address
    )
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Updated listing price:", txHash);
  return txHash;
}
```

**What to expect:** The listing is updated with the new price while remaining at the script address.

## Complete Example

Here is a complete React component with all marketplace actions:

```typescript
import { useState } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";
import {
  MeshTxBuilder,
  KoiosProvider,
  resolvePaymentKeyHash,
  resolveDataHash,
  resolvePlutusScriptAddress,
} from "@meshsdk/core";
import type { PlutusScript, Data, UTxO } from "@meshsdk/core";

// Your marketplace script
const script: PlutusScript = {
  code: "590795...", // Your compiled script
  version: "V2",
};
const scriptAddress = resolvePlutusScriptAddress(script, 0);

export default function Marketplace() {
  const { wallet, connected } = useWallet();
  const [loading, setLoading] = useState(false);

  // Implement list, cancel, purchase, update functions here
  // using the patterns shown above

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">NFT Marketplace</h1>
      <CardanoWallet />

      {connected && (
        <div className="mt-4 space-y-4">
          <button
            onClick={() => listNFT("policyId", "assetName", "10000000")}
            disabled={loading}
            className="px-4 py-2 bg-blue-500 text-white rounded"
          >
            List NFT for 10 ADA
          </button>

          {/* Add more action buttons */}
        </div>
      )}
    </div>
  );
}
```

## Next Steps

* <Link href="/guides/aiken">Write custom validators with Aiken</Link>
* <Link href="/guides/vesting">Build a vesting contract</Link>
* <Link href="/apis/txbuilder">Advanced transaction patterns</Link>

## Troubleshooting

### Script validation failed

**Cause:** Datum or redeemer does not match contract expectations.

**Solution:** Ensure the datum fields match your contract's expected structure. Check that the redeemer alternative matches the action (0 for buy, 1 for cancel in this example).

### UTxO not found

**Cause:** The listing was already purchased or cancelled.

**Solution:** Verify the listing exists before building the transaction. Implement a refresh mechanism in your UI.

### Collateral required error

**Cause:** No collateral set in the wallet.

**Solution:** Enable collateral in wallet settings. Most wallets require at least 5 ADA:

```typescript
const collateral = await wallet.getCollateral();
if (collateral.length === 0) {
  throw new Error("Please set collateral in your wallet");
}
```

### Authorization failed

**Cause:** The signer does not match the datum's seller address.

**Solution:** Ensure `requiredSignerHash` matches the original seller for cancel/update operations.

## References

* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the extended UTXO model that enables deterministic smart contracts
* [Aiken Smart Contract Language](https://aiken-lang.org/) - Official documentation for writing Cardano validators
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources and smart contract guides

## Related Links

* <Link href="/guides/aiken">Getting Started with Aiken</Link>
* <Link href="/guides/vesting">Vesting Contract Guide</Link>
* <Link href="/apis/txbuilder">Transaction Builder API</Link>


# Run Standalone Cardano Scripts with TypeScript
URL: /guides/standalone

Execute TypeScript scripts directly to interact with Cardano using Mesh SDK. Build, sign, and submit transactions without a framework.

***

title: "Run Standalone Cardano Scripts with TypeScript"
description: "Execute TypeScript scripts directly to interact with Cardano using Mesh SDK. Build, sign, and submit transactions without a framework."
-----------------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Execute standalone Cardano scripts with Mesh SDK"
  description="Run JavaScript/TypeScript files directly to interact with the Cardano blockchain using Mesh SDK and the tsx package."
  totalTime="PT15M"
  steps={[
  { name: "Create project", text: "Initialize a new project with package.json configured for ES modules." },
  { name: "Install dependencies", text: "Install tsx for TypeScript execution and @meshsdk/core for blockchain interaction." },
  { name: "Create script", text: "Write a TypeScript script that builds and submits a transaction." },
  { name: "Configure credentials", text: "Add your Blockfrost API key and wallet mnemonic." },
  { name: "Run the script", text: "Execute the script with npm run dev to submit the transaction." }
]}
/>

## Overview

Standalone scripts let you interact with Cardano without a web framework. This is ideal for testing, automation, backend services, and quick prototypes. The Mesh SDK provides a TypeScript-first interface to the [Cardano blockchain](https://developers.cardano.org), handling transaction construction, signing, and submission.

### What you will build

* A minimal TypeScript project that runs directly with `tsx`
* A script that creates a wallet and sends a transaction
* Zero-config TypeScript execution

### Prerequisites

* Node.js 18+ installed
* A Blockfrost API key (free tier available)
* A funded Cardano wallet (testnet or mainnet)

### Time to complete

15 minutes

## Quick Start

Clone the template repository for the fastest setup:

```bash
git clone https://github.com/MeshJS/standalone-template
cd standalone-template
npm install
```

Add your credentials to `.env` and run:

```bash
npm run dev
```

## Step-by-Step Setup

### Step 1: Create the project

Create a new directory and initialize the project:

```bash
mkdir mesh-script
cd mesh-script
npm init -y
```

**What to expect:** A `package.json` file is created.

### Step 2: Configure package.json

Update `package.json` with ES module settings:

```json
{
  "name": "mesh-script",
  "type": "module",
  "scripts": {
    "dev": "tsx index.ts"
  },
  "dependencies": {}
}
```

**What to expect:** The project is configured to use ES modules and run TypeScript directly.

### Step 3: Install dependencies

Install the required packages:

```bash
npm install tsx @meshsdk/core
```

* `tsx` - Runs TypeScript files directly without compilation
* `@meshsdk/core` - Mesh SDK core functionality

**What to expect:** Both packages install successfully.

### Step 4: Create the script

Create `index.ts`:

```typescript
import {
  BlockfrostProvider,
  MeshTxBuilder,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Configure the blockchain provider
const provider = new BlockfrostProvider("YOUR_BLOCKFROST_KEY");

// Initialize wallet with mnemonic
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // 0 = testnet, 1 = mainnet
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: [
    "your", "twelve", "word", "mnemonic",
    "phrase", "goes", "here", "replace",
    "with", "actual", "words", "now",
  ],
});

// Get wallet info
const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

console.log("Wallet address:", changeAddress);
console.log("UTxO count:", utxos.length);

// Build and send a transaction
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
});

const recipientAddress = "addr_test1qp2k7wnshzngpqw0xmy33hvexw4aeg60yr79x3yeeqt3s2uvldqg2n2p8y4kyjm8sqfyg0tpq9042atz0fr8c3grjmysdp6yv3";

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "1000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Transaction submitted:", txHash);
```

**What to expect:** A TypeScript file that sends 1 ADA to a recipient address.

### Step 5: Configure credentials

Before running, replace the placeholder values:

1. Get a Blockfrost API key from [blockfrost.io](https://blockfrost.io/)
2. Generate a wallet mnemonic using `generateMnemonic()` from `@meshsdk/core` or use an existing one
3. Fund the wallet using the [Cardano testnet faucet](https://docs.cardano.org/cardano-testnets/tools/faucet)

**What to expect:** Your script is configured with valid credentials.

### Step 6: Run the script

Execute the script:

```bash
npm run dev
```

**What to expect:** The console displays:

```
Wallet address: addr_test1q...
UTxO count: 3
Transaction submitted: abc123def456...
```

## Complete Example

Here is the complete `index.ts` with environment variables:

```typescript
import {
  BlockfrostProvider,
  MeshTxBuilder,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Load from environment variables for security
const BLOCKFROST_KEY = process.env.BLOCKFROST_KEY!;
const MNEMONIC = process.env.MNEMONIC!;

if (!BLOCKFROST_KEY || !MNEMONIC) {
  console.error("Missing BLOCKFROST_KEY or MNEMONIC environment variables");
  process.exit(1);
}

const provider = new BlockfrostProvider(BLOCKFROST_KEY);

async function main() {
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: MNEMONIC.split(" "),
  });

  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  console.log("Wallet address:", changeAddress);
  console.log("Available UTxOs:", utxos.length);

  if (utxos.length === 0) {
    console.error("No UTxOs available. Fund the wallet first.");
    process.exit(1);
  }

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const recipientAddress = "addr_test1qp2k7wnshzngpqw0xmy33hvexw4aeg60yr79x3yeeqt3s2uvldqg2n2p8y4kyjm8sqfyg0tpq9042atz0fr8c3grjmysdp6yv3";

  const unsignedTx = await txBuilder
    .txOut(recipientAddress, [{ unit: "lovelace", quantity: "1000000" }])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Transaction submitted:", txHash);
  console.log(`View on explorer: https://preprod.cardanoscan.io/transaction/${txHash}`);
}

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

Run with environment variables:

```bash
BLOCKFROST_KEY=your_key MNEMONIC="your twelve word phrase" npm run dev
```

## Next Steps

* <Link href="/apis/txbuilder">Learn transaction building options</Link> - Multiple outputs, metadata, minting
* <Link href="/guides/minting-on-nodejs">Mint NFTs server-side</Link> - Create tokens without a browser
* <Link href="/apis/wallets/meshwallet">Explore Headless Wallet options</Link> - Private keys, mnemonic
* <Link href="/guides/aiken">Interact with smart contracts</Link> - Lock and unlock funds

## Troubleshooting

### No UTxOs available

**Cause:** The wallet has no funds.

**Solution:** Fund the wallet using the [Cardano testnet faucet](https://docs.cardano.org/cardano-testnets/tools/faucet) or transfer ADA from another wallet.

### Invalid Blockfrost key

**Cause:** The API key is incorrect or for the wrong network.

**Solution:** Verify the key at [blockfrost.io](https://blockfrost.io/). Use a Preprod key for testnet (`networkId: 0`) or Mainnet key for mainnet (`networkId: 1`).

### Transaction failed

**Cause:** Various issues like insufficient funds, invalid addresses, or network problems.

**Solution:** Check the error message. Common fixes:

* Ensure you have enough ADA (at least 2 ADA for most transactions)
* Verify the recipient address is valid
* Wait and retry if the network is congested

### TypeScript errors

**Cause:** Type mismatches or missing dependencies.

**Solution:** Ensure you have the latest `@meshsdk/core` installed:

```bash
npm install @meshsdk/core@latest
```

## References

* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources, SDKs, and getting started guides
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding Cardano's transaction model
* [MeshJS GitHub Repository](https://github.com/MeshJS/mesh) - Mesh SDK source code and contributions

## Related Links

* <Link href="https://github.com/MeshJS/standalone-template">Complete template on GitHub</Link>
* <Link href="/apis/txbuilder">Transaction Builder API</Link>
* <Link href="/apis/wallets/meshwallet">Headless Wallet API</Link>
* <Link href="/providers">Blockchain Providers</Link>


# Build a Vesting Smart Contract
URL: /guides/vesting

Implement a time-locked vesting contract using Aiken and Mesh SDK. Lock funds with scheduled withdrawal.

***

title: "Build a Vesting Smart Contract"
description: "Implement a time-locked vesting contract using Aiken and Mesh SDK. Lock funds with scheduled withdrawal."
-----------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";
import { HowToSchema } from "@/components/seo";

<HowToSchema
  name="Build a Vesting Smart Contract on Cardano"
  description="Implement a time-locked vesting contract using Aiken for the validator and Mesh SDK for transactions."
  totalTime="PT60M"
  steps={[
  { name: "Define datum", text: "Create VestingDatum with lock time, owner, and beneficiary." },
  { name: "Write validator", text: "Implement spend logic with time and signature checks." },
  { name: "Compile contract", text: "Build with Aiken to generate Plutus blueprint." },
  { name: "Deposit funds", text: "Lock assets at script with inline datum." },
  { name: "Withdraw funds", text: "Build withdrawal transaction after lock expires." }
]}
/>

## Overview

A vesting contract locks funds until a specified time, then allows a beneficiary to withdraw. This is commonly used for employee compensation, token distributions, and escrow arrangements. This contract runs on Cardano's [extended UTXO (eUTXO) model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/), which enables deterministic script execution and predictable transaction fees.

### What you will build

* An Aiken validator with time-based release
* Deposit transactions that lock funds
* Withdrawal transactions after the lock period

### What you will learn

* Cardano's time handling with validity intervals
* Owner vs beneficiary access patterns
* Building time-constrained transactions

### Prerequisites

* Aiken CLI installed (see <Link href="/guides/aiken">Aiken guide</Link>)
* Next.js application with Mesh SDK
* Understanding of datums and redeemers

### Time to complete

60 minutes

## Quick Start

Clone the complete example:

```bash
git clone https://github.com/MeshJS/examples
cd examples/aiken-vesting
```

## Step-by-Step Guide

### Step 1: Define the vesting datum

Create the datum type that configures vesting parameters:

```rust
// lib/vesting/types.ak
pub type VestingDatum {
  /// POSIX time in milliseconds when funds unlock
  lock_until: Int,
  /// Owner's public key hash (can withdraw anytime)
  owner: ByteArray,
  /// Beneficiary's public key hash (can withdraw after lock_until)
  beneficiary: ByteArray,
}
```

The datum contains:

* `lock_until` - POSIX timestamp (ms) when funds become available
* `owner` - Can withdraw at any time (emergency access)
* `beneficiary` - Can withdraw only after the lock expires

**What to expect:** A type definition for vesting configuration.

### Step 2: Write the validator

Create `validators/vesting.ak`:

```rust
use aiken/transaction.{ScriptContext, Spend}
use vesting/types.{VestingDatum}

// Helper to check if a key signed the transaction
fn key_signed(signatories: List<ByteArray>, key: ByteArray) -> Bool {
  list.has(signatories, key)
}

// Helper to check if transaction is valid after a certain time
fn valid_after(validity_range, lock_until: Int) -> Bool {
  when validity_range.lower_bound.bound_type is {
    Finite(tx_earliest_time) -> tx_earliest_time > lock_until
    _ -> False
  }
}

validator {
  pub fn vesting(datum: VestingDatum, _redeemer: Data, ctx: ScriptContext) {
    when ctx.purpose is {
      Spend(_) -> or {
        // Owner can always withdraw
        key_signed(ctx.transaction.extra_signatories, datum.owner),
        // Beneficiary can withdraw after lock period
        and {
          key_signed(ctx.transaction.extra_signatories, datum.beneficiary),
          valid_after(ctx.transaction.validity_range, datum.lock_until),
        },
      }
      _ -> False
    }
  }
}
```

The validator allows withdrawal when:

1. The **owner** signs (can withdraw anytime), OR
2. The **beneficiary** signs AND current time is after `lock_until`

**What to expect:** A validator file with time-based access control.

### Step 3: Write tests

Create `validators/vesting_test.ak`:

```rust
use vesting

test owner_can_withdraw_early() {
  // Owner should be able to withdraw before lock_until
  True
}

test beneficiary_cannot_withdraw_early() {
  // Beneficiary should NOT be able to withdraw before lock_until
  True
}

test beneficiary_can_withdraw_after_lock() {
  // Beneficiary should be able to withdraw after lock_until
  True
}
```

Run the tests:

```bash
aiken check
```

**What to expect:** All tests pass (implement actual test logic for production).

### Step 4: Compile the contract

Build the Aiken project:

```bash
aiken build
```

**What to expect:** A `plutus.json` blueprint file is generated.

### Step 5: Set up the frontend

Create a contract helper file `src/lib/vesting.ts`:

```typescript
import {
  resolvePlutusScriptAddress,
  resolvePaymentKeyHash,
  deserializeAddress,
} from "@meshsdk/core";
import type { PlutusScript, Data } from "@meshsdk/core";
import cbor from "cbor";
import plutusBlueprint from "@/data/plutus.json";

// Load compiled contract
const scriptCbor = cbor
  .encode(Buffer.from(plutusBlueprint.validators[0].compiledCode, "hex"))
  .toString("hex");

export const script: PlutusScript = {
  code: scriptCbor,
  version: "V2",
};

export const scriptAddress = resolvePlutusScriptAddress(script, 0);

// Create vesting datum
export function createVestingDatum(
  lockUntilMs: number,
  ownerAddress: string,
  beneficiaryAddress: string
): Data {
  const { pubKeyHash: ownerHash } = deserializeAddress(ownerAddress);
  const { pubKeyHash: beneficiaryHash } = deserializeAddress(beneficiaryAddress);

  return {
    alternative: 0,
    fields: [lockUntilMs, ownerHash, beneficiaryHash],
  };
}
```

**What to expect:** Helper functions for working with the vesting contract.

### Step 6: Deposit funds

Create the deposit transaction:

```typescript
import { MeshTxBuilder, KoiosProvider } from "@meshsdk/core";
import { useWallet } from "@meshsdk/react";
import { script, scriptAddress, createVestingDatum } from "@/lib/vesting";

async function depositFunds(
  amountLovelace: string,
  lockDurationMinutes: number,
  beneficiaryAddress: string
) {
  const provider = new KoiosProvider("preprod");
  const { wallet } = useWallet();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const ownerAddress = (await wallet.getUsedAddresses())[0];

  // Calculate lock time
  const lockUntilMs = Date.now() + lockDurationMinutes * 60 * 1000;

  // Create datum
  const datum = createVestingDatum(lockUntilMs, ownerAddress, beneficiaryAddress);

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    // Lock funds at script with inline datum
    .txOut(scriptAddress, [{ unit: "lovelace", quantity: amountLovelace }])
    .txOutInlineDatumValue(datum)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Deposited funds:", txHash);
  console.log("Unlocks at:", new Date(lockUntilMs).toISOString());

  return { txHash, lockUntilMs };
}
```

**What to expect:** Funds are locked at the script address with vesting parameters.

### Step 7: Withdraw funds

Create the withdrawal transaction:

```typescript
import {
  MeshTxBuilder,
  KoiosProvider,
  deserializeAddress,
  unixTimeToEnclosingSlot,
  SLOT_CONFIG_NETWORK,
} from "@meshsdk/core";
import { useWallet } from "@meshsdk/react";
import { script, scriptAddress, createVestingDatum } from "@/lib/vesting";

async function withdrawFunds(depositTxHash: string) {
  const provider = new KoiosProvider("preprod");
  const { wallet } = useWallet();

  // Find the vesting UTxO
  const scriptUtxos = await provider.fetchUTxOs(depositTxHash);
  const vestingUtxo = scriptUtxos[0];

  if (!vestingUtxo) {
    throw new Error("Vesting UTxO not found");
  }

  // Parse the inline datum
  const plutusData = vestingUtxo.output.plutusData;
  // Extract lock_until from datum
  const lockUntilMs = plutusData.fields[0].int;

  // Check if we can withdraw
  const now = Date.now();
  if (now < lockUntilMs) {
    throw new Error(`Cannot withdraw yet. Unlocks in ${Math.ceil((lockUntilMs - now) / 60000)} minutes`);
  }

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const collateral = await wallet.getCollateral();
  const { pubKeyHash } = deserializeAddress(changeAddress);

  // Calculate validity interval (must be after lock_until)
  const invalidBefore = unixTimeToEnclosingSlot(
    Math.max(lockUntilMs, now - 15000),
    SLOT_CONFIG_NETWORK.preprod
  ) + 1;

  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .spendingPlutusScriptV2()
    .txIn(
      vestingUtxo.input.txHash,
      vestingUtxo.input.outputIndex,
      vestingUtxo.output.amount,
      scriptAddress
    )
    .spendingReferenceTxInInlineDatumPresent()
    .spendingReferenceTxInRedeemerValue("") // Empty redeemer
    .txInScript(script.code)
    .txOut(changeAddress, [])
    .txInCollateral(
      collateral[0].input.txHash,
      collateral[0].input.outputIndex,
      collateral[0].output.amount,
      collateral[0].output.address
    )
    .invalidBefore(invalidBefore)
    .requiredSignerHash(pubKeyHash)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  const txHash = await wallet.submitTx(signedTx);

  console.log("Withdrawn funds:", txHash);
  return txHash;
}
```

**What to expect:** Funds are transferred to the beneficiary's wallet.

## Complete Example

Here is a complete React component:

```typescript
import { useState } from "react";
import { CardanoWallet, useWallet } from "@meshsdk/react";

export default function VestingApp() {
  const { wallet, connected } = useWallet();
  const [depositTxHash, setDepositTxHash] = useState("");
  const [loading, setLoading] = useState(false);

  async function handleDeposit() {
    setLoading(true);
    try {
      const beneficiary = "addr_test1..."; // Beneficiary address
      const result = await depositFunds("10000000", 5, beneficiary); // 10 ADA, 5 min lock
      setDepositTxHash(result.txHash);
    } finally {
      setLoading(false);
    }
  }

  async function handleWithdraw() {
    setLoading(true);
    try {
      await withdrawFunds(depositTxHash);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">Vesting Contract</h1>
      <CardanoWallet />

      {connected && (
        <div className="mt-4 space-y-4">
          <button
            onClick={handleDeposit}
            disabled={loading}
            className="px-4 py-2 bg-blue-500 text-white rounded"
          >
            Deposit 10 ADA (5 min lock)
          </button>

          {depositTxHash && (
            <>
              <p>Deposit TX: {depositTxHash}</p>
              <button
                onClick={handleWithdraw}
                disabled={loading}
                className="px-4 py-2 bg-green-500 text-white rounded"
              >
                Withdraw
              </button>
            </>
          )}
        </div>
      )}
    </div>
  );
}
```

## Next Steps

* <Link href="https://preprod.cardanoscan.io/transaction/b108f91a1dcd1b4c0bc978fb7557fc23ad052f1681cca078aa2515f8ab01e05e">View a successful withdrawal transaction</Link>
* <Link href="https://github.com/MeshJS/examples">Full source code</Link>
* <Link href="/guides/smart-contract-transactions">More contract patterns</Link>

## Troubleshooting

### Cannot withdraw yet

**Cause:** Current time is before `lock_until`.

**Solution:** Wait for the lock period to expire. The `invalidBefore` constraint must be after `lock_until` for the transaction to be valid.

### Validity interval error

**Cause:** The `invalidBefore` slot is in the past or incorrectly calculated.

**Solution:** Ensure you use the correct slot config for your network:

```typescript
import { SLOT_CONFIG_NETWORK } from "@meshsdk/core";

// For preprod testnet
const slotConfig = SLOT_CONFIG_NETWORK.preprod;

// For mainnet
const slotConfig = SLOT_CONFIG_NETWORK.mainnet;
```

### Owner vs beneficiary withdrawal

**Cause:** Wrong signer for the withdrawal type.

**Solution:** The owner can withdraw anytime by signing. The beneficiary must:

1. Sign the transaction
2. Set `invalidBefore` to a slot after `lock_until`

### Inline datum not found

**Cause:** The UTxO was created with a datum hash instead of inline datum.

**Solution:** Use `txOutInlineDatumValue` for deposits:

```typescript
.txOut(scriptAddress, amount)
.txOutInlineDatumValue(datum)  // Use inline datum
// NOT .txOutDatumHashValue(datum)
```

## References

* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - How Cardano's transaction model enables deterministic smart contracts
* [Aiken Smart Contract Language](https://aiken-lang.org/) - Official documentation for the Aiken language used in this guide
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources
* [CIP-0057: Plutus Blueprint](https://cips.cardano.org/cip/CIP-57) - The standard for compiled Plutus contract blueprints

## Related Links

* <Link href="https://github.com/MeshJS/examples">Complete source code</Link>
* <Link href="/guides/aiken">Getting Started with Aiken</Link>
* <Link href="/guides/smart-contract-transactions">Smart Contract Transactions</Link>


# Hydra - Layer 2 Scaling for Cardano
URL: /hydra

Build fast, low-cost applications with Hydra Head protocol. Process thousands of transactions per second while maintaining Cardano's security guarantees.

***

title: "Hydra - Layer 2 Scaling for Cardano"
description: "Build fast, low-cost applications with Hydra Head protocol. Process thousands of transactions per second while maintaining Cardano's security guarantees."
icon: "icons/hydra.svg"
-----------------------

import { linksHydra } from "@/data/links-hydra";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Hydra is a Layer 2 scaling solution for Cardano that enables near-instant, low-cost transactions between participants. By opening a "Hydra Head" (a state channel), you can process thousands of transactions per second while maintaining the security guarantees of the Cardano mainnet.

### When to use Hydra

* **High-frequency transactions**: Gaming, micropayments, or real-time applications requiring sub-second finality
* **Cost-sensitive applications**: Reduce transaction fees by batching settlements on Layer 1
* **Private transactions**: Keep transaction details off-chain until final settlement
* **Interactive applications**: Multi-party protocols requiring rapid state updates

### Key benefits

| Feature        | Description                                                   |
| -------------- | ------------------------------------------------------------- |
| **Speed**      | Near-instant transaction confirmation within the Head         |
| **Low cost**   | Minimal fees inside the Head; only pay L1 fees for open/close |
| **Security**   | Funds are always secured by Cardano's consensus               |
| **Isomorphic** | Use the same transaction format as Layer 1                    |

## Quick start

Install the Mesh Hydra package and connect to a running Hydra node:

```typescript
import { HydraProvider, HydraInstance } from "@meshsdk/hydra";
import { BlockfrostProvider } from "@meshsdk/core";

// Initialize the blockchain provider for L1 operations
const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

// Connect to your Hydra node
const hydraProvider = new HydraProvider({
  httpUrl: "http://localhost:4001",
});

// Create a Hydra instance for head operations
const hydraInstance = new HydraInstance({
  provider: hydraProvider,
  fetcher: blockfrost,
  submitter: blockfrost,
});

// Connect and initialize the head
await hydraProvider.connect();
await hydraProvider.init();
```

## Documentation

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksHydra.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## How Hydra works

1. **Initialize**: Participants agree to open a Hydra Head
2. **Commit**: Each participant commits funds from Layer 1 to the Head
3. **Transact**: Process unlimited transactions instantly within the Head
4. **Close**: Submit the final state back to Layer 1
5. **Fanout**: Distribute funds according to the final Head state

## Related resources

* [Hydra Instance API](/docs/hydra/instance) - Detailed API reference for HydraInstance
* [End-to-end Tutorial](/docs/hydra/tutorial) - Complete walkthrough from setup to settlement
* [Hydra Protocol Documentation](https://hydra.family/head-protocol/) - Official Hydra protocol specifications
* [Cardano Providers](/providers) - Configure blockchain providers for L1 operations


# Hydra Instance API
URL: /hydra/instance

Complete API reference for HydraInstance - commit funds, manage UTxOs, and interact with Hydra Heads programmatically.

***

title: "Hydra Instance API"
description: "Complete API reference for HydraInstance - commit funds, manage UTxOs, and interact with Hydra Heads programmatically."
-------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

The `HydraInstance` class provides methods to interact with a Hydra Head after initialization. Use it to commit funds, manage incremental deposits, and handle blueprint transactions for advanced use cases like script UTxOs.

### When to use HydraInstance

* Committing funds to a new or existing Hydra Head
* Managing incremental deposits to an open Head
* Handling complex transactions with script UTxOs
* Building custom commit workflows

## Prerequisites

Before using HydraInstance, ensure you have:

* A running Hydra node with API access
* A configured blockchain provider (Blockfrost, Maestro, etc.)
* A wallet with funds for committing to the Head
* The `@meshsdk/hydra` package installed

## Quick start

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
import { BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Set up providers
const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

const hydraProvider = new HydraProvider({
  httpUrl: "http://localhost:4001",
});

// Create the Hydra instance
const instance = new HydraInstance({
  provider: hydraProvider,
  fetcher: blockfrost,
  submitter: blockfrost,
});

// Connect to the Hydra node
await hydraProvider.connect();
```

## Setup

### Installation

```bash
npm install @meshsdk/hydra @meshsdk/core
```

### Configuration

The `HydraInstance` constructor accepts the following options:

| Parameter   | Type            | Description                                     |
| ----------- | --------------- | ----------------------------------------------- |
| `provider`  | `HydraProvider` | Connected HydraProvider instance                |
| `fetcher`   | `IFetcher`      | Blockchain provider for fetching UTxOs          |
| `submitter` | `ISubmitter`    | Blockchain provider for submitting transactions |

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
import { BlockfrostProvider } from "@meshsdk/core";

const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

const hydraProvider = new HydraProvider({
  httpUrl: "http://localhost:4001",
});

const instance = new HydraInstance({
  provider: hydraProvider,
  fetcher: blockfrost,
  submitter: blockfrost,
});
```

## API reference

### commitEmpty()

Request an empty commit transaction to open the Head without committing funds. Use this when you only want to receive funds on Layer 2.

**Returns:** `Promise<string>` - Transaction CBOR hex ready for signing

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
import { MeshCardanoHeadlessWallet } from "@meshsdk/wallet";

const commit = await instance.commitEmpty();
const signedTx = await wallet.signTx(commit, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Empty commit submitted:", txHash);
```

### commitFunds(txHash, outputIndex)

Commit a specific UTxO to the Hydra Head. The committed funds become available on Layer 2 after the Head opens.

**Parameters:**

| Name          | Type     | Description                          |
| ------------- | -------- | ------------------------------------ |
| `txHash`      | `string` | Transaction hash containing the UTxO |
| `outputIndex` | `number` | Index of the output to commit        |

**Returns:** `Promise<string>` - Transaction CBOR hex ready for partial signing

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
import { MeshCardanoHeadlessWallet } from "@meshsdk/wallet";

const txHash = "abc123...";
const outputIndex = 0;

const commitTx = await instance.commitFunds(txHash, outputIndex);
const signedTx = await wallet.signTx(commitTx, true); // partial sign
const commitTxHash = await wallet.submitTx(signedTx);

console.log("Funds committed:", commitTxHash);
```

### commitBlueprint(txHash, outputIndex, hydraTransaction)

Commit a Cardano transaction blueprint to the Hydra Head. Use this for advanced scenarios like committing script UTxOs.

**Parameters:**

| Name               | Type     | Description                  |
| ------------------ | -------- | ---------------------------- |
| `txHash`           | `string` | Transaction hash of the UTxO |
| `outputIndex`      | `number` | Index of the output          |
| `hydraTransaction` | `object` | Blueprint transaction object |

**hydraTransaction object:**

| Property      | Type     | Description                            |
| ------------- | -------- | -------------------------------------- |
| `cborHex`     | `string` | Unsigned transaction CBOR              |
| `description` | `string` | Human-readable description             |
| `type`        | `string` | Transaction era (e.g., "Tx ConwayEra") |

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
import { MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet } from "@meshsdk/wallet";

// Build the blueprint transaction
const txBuilder = new MeshTxBuilder({
  fetcher: blockfrost,
  verbose: true,
});

const unsignedTx = await txBuilder
  .txIn(txHash, outputIndex)
  .setFee("0")
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

// Commit the blueprint
const commitTx = await instance.commitBlueprint(txHash, outputIndex, {
  cborHex: unsignedTx,
  description: "Commit script UTxO",
  type: "Tx ConwayEra",
});

const signedTx = await wallet.signTx(commitTx, false);
const commitTxHash = await wallet.submitTx(signedTx);

console.log("Blueprint committed:", commitTxHash);
```

### incrementalCommitFunds(txHash, outputIndex)

Add additional UTxOs to an already open Hydra Head. The deposit period is configured by the `--deposit-period` hydra-node parameter.

**Parameters:**

| Name          | Type     | Description                          |
| ------------- | -------- | ------------------------------------ |
| `txHash`      | `string` | Transaction hash containing the UTxO |
| `outputIndex` | `number` | Index of the output to commit        |

**Returns:** `Promise<string>` - Transaction CBOR hex ready for signing

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";

const txHash = "def456...";
const outputIndex = 0;

const incrementalTx = await instance.incrementalCommitFunds(txHash, outputIndex);
const signedTx = await wallet.signTx(incrementalTx, true);
const txHash = await wallet.submitTx(signedTx);

console.log("Incremental commit submitted:", txHash);
```

For more details on incremental commits, see the <Link href="https://hydra.family/head-protocol/docs/how-to/incremental-commit">Hydra documentation</Link>.

### incrementalBlueprintCommit(txHash, outputIndex, hydraTransaction)

Add a blueprint transaction to an open Hydra Head incrementally.

**Parameters:**

| Name               | Type     | Description                  |
| ------------------ | -------- | ---------------------------- |
| `txHash`           | `string` | Transaction hash of the UTxO |
| `outputIndex`      | `number` | Index of the output          |
| `hydraTransaction` | `object` | Blueprint transaction object |

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";

const incrementalTx = await instance.incrementalBlueprintCommit(
  txHash,
  outputIndex,
  {
    cborHex: unsignedTx,
    description: "Incremental blueprint commit",
    type: "Tx ConwayEra",
  }
);

const signedTx = await wallet.signTx(incrementalTx);
const txHash = await wallet.submitTx(signedTx);
```

## Complete example

This example demonstrates the full workflow of connecting to a Hydra node and committing funds when the Head is initializing:

```typescript
import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
import { BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Initialize providers
const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

const hydraProvider = new HydraProvider({
  httpUrl: "http://localhost:4001",
});

const instance = new HydraInstance({
  provider: hydraProvider,
  fetcher: blockfrost,
  submitter: blockfrost,
});

// Set up wallet
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: blockfrost,
  submitter: blockfrost,
  mnemonic: ["your", "mnemonic", "words", "..."],
});

// Connect to Hydra
await hydraProvider.connect();
await hydraProvider.init();

// Listen for Head status and commit when initializing
hydraProvider.onMessage(async (message) => {
  const status =
    message.tag === "Greetings"
      ? { headStatus: message.headStatus }
      : { tag: message.tag };

  if (
    status.tag === "HeadIsInitializing" ||
    status.headStatus === "Initializing"
  ) {
    // Get a UTxO to commit
    const utxos = await wallet.getUtxosMesh();
    const utxoToCommit = utxos[0];

    // Commit funds to the Head
    const commitTx = await instance.commitFunds(
      utxoToCommit.input.txHash,
      utxoToCommit.input.outputIndex
    );
    const signedTx = await wallet.signTx(commitTx, true);
    const txHash = await wallet.submitTx(signedTx);

    console.log("Committed funds to Head:", txHash);
  }

  if (status.tag === "HeadIsOpen") {
    console.log("Head is now open! Ready for L2 transactions.");
  }
});
```

## Troubleshooting

### "Connection refused" when connecting to Hydra node

Ensure your Hydra node is running and the API port is accessible:

```bash
# Check if Hydra node is running
curl http://localhost:4001/protocol-parameters
```

### Commit transaction fails with "UTxO not found"

The UTxO you are trying to commit may have been spent. Fetch fresh UTxOs before committing:

```typescript
const utxos = await blockfrost.fetchAddressUTxOs(address);
const validUtxo = utxos[0];
```

### "Head is not initializing" error

You can only commit funds during the `HeadIsInitializing` phase. Check the Head status:

```typescript
hydraProvider.onMessage((message) => {
  console.log("Current status:", message.tag || message.headStatus);
});
```

### Partial signing issues

When committing funds, use partial signing (`true` as second parameter):

```typescript
const signedTx = await wallet.signTx(commitTx, true); // Enable partial signing
```

## Related resources

* [End-to-end Tutorial](/docs/hydra/tutorial) - Complete walkthrough of Hydra Head lifecycle
* [Hydra Overview](/docs/hydra) - Introduction to Hydra and its benefits
* [Hydra Protocol Docs](https://hydra.family/head-protocol/docs/how-to/incremental-commit) - Official incremental commit documentation
* [Cardano Providers](/providers) - Configure blockchain providers


# End-to-End Hydra Tutorial
URL: /hydra/tutorial

Learn how to open a Hydra Head between two participants, execute Layer 2 transactions, and settle back to Cardano mainnet.

***

title: "End-to-End Hydra Tutorial"
description: "Learn how to open a Hydra Head between two participants, execute Layer 2 transactions, and settle back to Cardano mainnet."
-----------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

This tutorial walks you through the complete lifecycle of a Hydra Head on Cardano's preprod testnet. You will learn how to:

* Set up Hydra nodes for two participants
* Open a Hydra Head and commit funds
* Execute instant transactions on Layer 2
* Close the Head and settle funds on Layer 1

This tutorial is adapted from the <Link href="https://hydra.family/head-protocol/docs/tutorial">official Hydra documentation</Link>.

## Prerequisites

Before starting, ensure you have:

| Requirement        | Description                                    |
| ------------------ | ---------------------------------------------- |
| **Cardano node**   | Running node with `cardano-cli` access         |
| **Hydra node**     | Installed and configured `hydra-node` binary   |
| **Test ADA**       | At least 100 tADA per participant on preprod   |
| **Network access** | Two machines or terminals that can communicate |
| **Mesh SDK**       | `@meshsdk/hydra` and `@meshsdk/core` packages  |

### Installation

```bash
npm install @meshsdk/hydra @meshsdk/core
```

For Hydra node setup, see the <Link href="https://hydra.family/head-protocol/docs/tutorial#step-0-installation">official installation guide</Link> or use the <Link href="https://github.com/cardano-scaling/hydra/tree/master/demo">Docker demo setup</Link>.

## Quick start

If you already have Hydra nodes running, connect to a Head with Mesh:

```typescript
import { HydraProvider, HydraInstance } from "@meshsdk/hydra";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Connect to Hydra
const hydraProvider = new HydraProvider({
  httpUrl: "http://localhost:4001",
});

const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

const instance = new HydraInstance({
  provider: hydraProvider,
  fetcher: blockfrost,
  submitter: blockfrost,
});

await hydraProvider.connect();
```

## Step 1: Generate keys and fund wallets

Each Hydra participant needs two key pairs:

1. **Cardano keys**: For Layer 1 operations and paying fees
2. **Hydra keys**: For signing snapshots within the Head

### Generate Cardano keys

Create keys for Alice:

```bash
mkdir -p credentials

# Node keys (for hydra-node identity and fees)
cardano-cli address key-gen \
  --verification-key-file credentials/alice-node.vk \
  --signing-key-file credentials/alice-node.sk

cardano-cli address build \
  --payment-verification-key-file credentials/alice-node.vk \
  --out-file credentials/alice-node.addr \
  --testnet-magic 1

# Funds keys (for committing to the Head)
cardano-cli address key-gen \
  --verification-key-file credentials/alice-funds.vk \
  --signing-key-file credentials/alice-funds.sk

cardano-cli address build \
  --payment-verification-key-file credentials/alice-funds.vk \
  --out-file credentials/alice-funds.addr \
  --testnet-magic 1
```

Create keys for Bob:

```bash
# Node keys
cardano-cli address key-gen \
  --verification-key-file credentials/bob-node.vk \
  --signing-key-file credentials/bob-node.sk

cardano-cli address build \
  --payment-verification-key-file credentials/bob-node.vk \
  --out-file credentials/bob-node.addr \
  --testnet-magic 1

# Funds keys
cardano-cli address key-gen \
  --verification-key-file credentials/bob-funds.vk \
  --signing-key-file credentials/bob-funds.sk

cardano-cli address build \
  --payment-verification-key-file credentials/bob-funds.vk \
  --out-file credentials/bob-funds.addr \
  --testnet-magic 1
```

### Generate Hydra keys

```bash
hydra-node gen-hydra-key --output-file credentials/alice-hydra
hydra-node gen-hydra-key --output-file credentials/bob-hydra
```

### Fund the wallets

Use the <Link href="https://docs.cardano.org/cardano-testnets/tools/faucet">Cardano testnet faucet</Link> to fund the addresses:

| Address            | Minimum Amount |
| ------------------ | -------------- |
| `alice-node.addr`  | 30 tADA        |
| `bob-node.addr`    | 30 tADA        |
| `alice-funds.addr` | Any amount     |
| `bob-funds.addr`   | Any amount     |

### Configure protocol parameters

Fetch and modify the protocol parameters to eliminate fees inside the Head:

```bash
cardano-cli query protocol-parameters \
  --testnet-magic 1 \
  --socket-path "${CARDANO_NODE_SOCKET_PATH}" \
  --out-file protocol-parameters.json
```

Edit `protocol-parameters.json` and set these values to `0`:

* `txFeeFixed`
* `txFeePerByte`
* `executionUnitPrices.priceMemory`
* `executionUnitPrices.priceSteps`

## Step 2: Configure Hydra nodes

Start the Hydra node for each participant with the correct configuration.

### Alice's node

```bash
hydra-node \
  --node-id alice-node \
  --api-host 0.0.0.0 \
  --api-port 4001 \
  --listen 172.16.239.10:5001 \
  --monitoring-port 6001 \
  --peer 172.16.239.20:5001 \
  --hydra-scripts-tx-id <HYDRA_SCRIPTS_TX_ID> \
  --cardano-signing-key credentials/alice-node.sk \
  --cardano-verification-key credentials/bob-node.vk \
  --hydra-signing-key credentials/alice-hydra.sk \
  --hydra-verification-key credentials/bob-hydra.vk \
  --ledger-protocol-parameters protocol-parameters.json \
  --testnet-magic 1 \
  --node-socket "${CARDANO_NODE_SOCKET_PATH}" \
  --contestation-period 300s
```

### Bob's node

```bash
hydra-node \
  --node-id bob-node \
  --api-host 0.0.0.0 \
  --api-port 4002 \
  --listen 172.16.239.20:5001 \
  --monitoring-port 6001 \
  --peer 172.16.239.10:5001 \
  --hydra-scripts-tx-id <HYDRA_SCRIPTS_TX_ID> \
  --cardano-signing-key credentials/bob-node.sk \
  --cardano-verification-key credentials/alice-node.vk \
  --hydra-signing-key credentials/bob-hydra.sk \
  --hydra-verification-key credentials/alice-hydra.vk \
  --ledger-protocol-parameters protocol-parameters.json \
  --testnet-magic 1 \
  --node-socket "${CARDANO_NODE_SOCKET_PATH}" \
  --contestation-period 300s
```

### Configuration reference

| Parameter               | Description                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--node-id`             | Unique identifier for the node                                                                                                                             |
| `--api-port`            | Port for the HTTP/WebSocket API                                                                                                                            |
| `--listen`              | Address for peer-to-peer communication                                                                                                                     |
| `--peer`                | Other participant's listen address                                                                                                                         |
| `--hydra-scripts-tx-id` | Reference to published Hydra scripts (<Link href="https://github.com/cardano-scaling/hydra/blob/master/hydra-node/networks.json">see networks.json</Link>) |
| `--contestation-period` | Time window for contesting the final state                                                                                                                 |

For complete configuration options, see the <Link href="https://hydra.family/head-protocol/docs/configuration">Hydra configuration documentation</Link>.

## Step 3: Open a Hydra Head

### Connect with Mesh

```typescript
import { HydraProvider, HydraInstance } from "@meshsdk/hydra";
import { BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

const hydraProvider = new HydraProvider({
  httpUrl: "http://localhost:4001", // Alice's API
});

const instance = new HydraInstance({
  provider: hydraProvider,
  fetcher: blockfrost,
  submitter: blockfrost,
});

// Connect to the Hydra node
await hydraProvider.connect();
```

### Initialize the Head

```typescript
await hydraProvider.init();
```

### Commit funds

Set up your wallet and commit funds when the Head is initializing:

```typescript
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const wallet = await MeshCardanoHeadlessWallet.fromCliKeys({
  networkId: 0, // testnet
  walletAddressType: AddressType.Base,
  fetcher: blockfrost,
  submitter: blockfrost,
  paymentSkey: "credentials/alice-funds.sk",
});

// Listen for Head status changes
hydraProvider.onMessage(async (message) => {
  const status =
    message.tag === "Greetings"
      ? { headStatus: message.headStatus }
      : { tag: message.tag };

  if (
    status.tag === "HeadIsInitializing" ||
    status.headStatus === "Initializing"
  ) {
    // Get UTxOs to commit
    const utxos = await wallet.getUtxosMesh();
    const utxo = utxos[0];

    // Commit funds
    const commitTx = await instance.commitFunds(
      utxo.input.txHash,
      utxo.input.outputIndex
    );
    const signedTx = await wallet.signTx(commitTx, true, false);
    const txHash = await wallet.submitTx(signedTx);

    console.log("Committed funds:", txHash);
  }

  if (status.tag === "HeadIsOpen") {
    console.log("Head is open! Ready for L2 transactions.");
  }
});
```

### Head status flow

| Status               | Description                     |
| -------------------- | ------------------------------- |
| `HeadIsInitializing` | Head creation in progress       |
| `Committed`          | Participant has committed funds |
| `HeadIsOpen`         | Head is open for transactions   |

When all participants commit, the Head opens automatically.

## Step 4: Transact on Layer 2

With the Head open, you can execute transactions instantly with zero fees.

### Fetch UTxOs in the Head

```typescript
// Get all UTxOs in the Head
const allUtxos = await hydraProvider.fetchUTxOs();

// Get UTxOs for a specific address
const aliceUtxos = await hydraProvider.fetchAddressUTxOs(aliceAddress);
```

### Build and submit a transaction

Send ADA from Alice to Bob inside the Head:

```typescript
import { MeshTxBuilder } from "@meshsdk/core";

// Fetch protocol parameters from the Head
const protocolParams = await hydraProvider.fetchProtocolParameters();

// Get Alice's UTxOs
const aliceAddress = await wallet.getChangeAddressBech32();
const utxos = await hydraProvider.fetchAddressUTxOs(aliceAddress);

// Build the transaction
const txBuilder = new MeshTxBuilder({
  fetcher: hydraProvider,
  submitter: hydraProvider,
  isHydra: true,
  params: protocolParams,
});

const unsignedTx = await txBuilder
  .txOut(bobAddress, [{ unit: "lovelace", quantity: "3000000" }])
  .changeAddress(aliceAddress)
  .selectUtxosFrom(utxos)
  .setNetwork("preprod")
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await hydraProvider.submitTx(signedTx);

console.log("L2 transaction submitted:", txHash);
```

### Transaction status flow

| Status              | Description                             |
| ------------------- | --------------------------------------- |
| `NewTx`             | Transaction submitted to the Head       |
| `TxValid`           | All nodes validated the transaction     |
| `SnapshotConfirmed` | New state confirmed by all participants |

If validation fails, you receive a `TxInvalid` message with the reason.

## Step 5: Close the Head

When you are done transacting, close the Head to settle funds on Layer 1.

### Initiate close

Any participant can close the Head:

```typescript
await hydraProvider.close();
```

### Contestation period

After closing, there is a contestation period (configured with `--contestation-period`) during which:

* Participants can contest with a more recent snapshot
* No new transactions can be submitted
* The final state is locked for settlement

### Fanout to Layer 1

After the contestation deadline, distribute the final state to Layer 1:

```typescript
await hydraProvider.fanout();
```

### Verify final balances

Check that funds are back on Layer 1:

```typescript
const aliceBalance = await blockfrost.fetchAddressUTxOs(aliceAddress);
const bobBalance = await blockfrost.fetchAddressUTxOs(bobAddress);

console.log("Alice L1 UTxOs:", aliceBalance);
console.log("Bob L1 UTxOs:", bobBalance);
```

## Complete example

Here is the full workflow in a single script:

```typescript
import { HydraProvider, HydraInstance } from "@meshsdk/hydra";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function main() {
  // Setup providers
  const blockfrost = new BlockfrostProvider("<YOUR_BLOCKFROST_KEY>");

  const hydraProvider = new HydraProvider({
    httpUrl: "http://localhost:4001",
  });

  const instance = new HydraInstance({
    provider: hydraProvider,
    fetcher: blockfrost,
    submitter: blockfrost,
  });

  // Setup wallet
  const wallet = await MeshCardanoHeadlessWallet.fromCliKeys({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: blockfrost,
    submitter: blockfrost,
    paymentSkey: "credentials/alice-funds.sk",
  });

  const aliceAddress = await wallet.getChangeAddressBech32();
  const bobAddress = "addr_test1..."; // Bob's address

  // Connect to Hydra
  await hydraProvider.connect();

  // Handle Head lifecycle
  hydraProvider.onMessage(async (message) => {
    switch (message.tag) {
      case "HeadIsInitializing":
        console.log("Head initializing, committing funds...");
        const utxos = await wallet.getUtxosMesh();
        const commitTx = await instance.commitFunds(
          utxos[0].input.txHash,
          utxos[0].input.outputIndex
        );
        const signedCommit = await wallet.signTx(commitTx, true, false);
        await wallet.submitTx(signedCommit);
        break;

      case "HeadIsOpen":
        console.log("Head is open, sending transaction...");

        const pp = await hydraProvider.fetchProtocolParameters();
        const l2Utxos = await hydraProvider.fetchAddressUTxOs(aliceAddress);

        const txBuilder = new MeshTxBuilder({
          fetcher: hydraProvider,
          submitter: hydraProvider,
          isHydra: true,
          params: pp,
        });

        const unsignedTx = await txBuilder
          .txOut(bobAddress, [{ unit: "lovelace", quantity: "5000000" }])
          .changeAddress(aliceAddress)
          .selectUtxosFrom(l2Utxos)
          .setNetwork("preprod")
          .complete();

        const signedTx = await wallet.signTx(unsignedTx, false);
        await hydraProvider.submitTx(signedTx);
        break;

      case "SnapshotConfirmed":
        console.log("Transaction confirmed, closing Head...");
        await hydraProvider.close();
        break;

      case "ReadyToFanout":
        console.log("Contestation period ended, fanning out...");
        await hydraProvider.fanout();
        break;

      case "HeadIsFinalized":
        console.log("Head finalized! Funds are back on L1.");
        break;
    }
  });

  // Initialize the Head
  await hydraProvider.init();
}

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

## Head lifecycle reference

| Phase      | Status               | Description                    |
| ---------- | -------------------- | ------------------------------ |
| Initialize | `HeadIsInitializing` | Head creation started          |
| Commit     | `Committed`          | Funds committed by participant |
| Open       | `HeadIsOpen`         | Head open for transactions     |
| Transact   | `SnapshotConfirmed`  | L2 transaction confirmed       |
| Close      | `HeadIsClosed`       | Head closing initiated         |
| Contest    | `ReadyToFanout`      | Contestation period ended      |
| Fanout     | `HeadIsFinalized`    | Funds settled on L1            |

## Troubleshooting

### Hydra node won't start

Check that the Cardano node socket path is correct and the node is synced:

```bash
cardano-cli query tip --testnet-magic 1 --socket-path "${CARDANO_NODE_SOCKET_PATH}"
```

### Nodes can't connect to each other

Ensure firewall rules allow traffic on the listen ports (5001 in the examples) and verify the peer IP addresses are correct.

### Commit transaction rejected

Verify that:

* The UTxO exists and has not been spent
* The address matches your signing key
* You have enough ADA to cover the L1 transaction fee

### Transaction rejected in Head

Common reasons:

* Insufficient funds in the Head
* Invalid transaction format
* UTxO already spent in a previous transaction

Check the `TxInvalid` message for specific error details.

## Related resources

* [Hydra Instance API](/docs/hydra/instance) - Detailed API reference
* [Hydra Overview](/docs/hydra) - Introduction and architecture
* [Official Hydra Tutorial](https://hydra.family/head-protocol/docs/tutorial) - Full setup guide
* [Hydra Configuration](https://hydra.family/head-protocol/docs/configuration) - All node options
* [Cardano Providers](/providers) - Configure blockchain providers


# Midnight
URL: /midnight

Build privacy-preserving dApps with zero-knowledge proofs on the Midnight Network

***

title: "Midnight"
description: "Build privacy-preserving dApps with zero-knowledge proofs on the Midnight Network"
icon: "icons/midnight.svg"
--------------------------

import { linksMidnight } from "@/data/links-midnight";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

Midnight is a zero-knowledge privacy network that enables you to build confidential smart contracts and transactions on Cardano. With Mesh SDK's Midnight integration, you can create privacy-preserving decentralized applications without deep cryptographic expertise.

## Why Midnight?

| Feature                          | Benefit                                          |
| -------------------------------- | ------------------------------------------------ |
| **Zero-knowledge proofs**        | Verify data without revealing it                 |
| **Confidential smart contracts** | Execute logic while keeping inputs private       |
| **Cardano integration**          | Leverage Cardano's security and ecosystem        |
| **TypeScript SDK**               | Full type safety and modern developer experience |

## When to use Midnight

Use Midnight when you need:

* **Financial privacy**: Hide transaction amounts while proving validity
* **Identity verification**: Prove attributes (age, citizenship) without revealing personal data
* **Confidential voting**: Enable verifiable elections with secret ballots
* **Private DeFi**: Build lending, staking, or trading with hidden positions

## Quick start

Install the Midnight setup package:

```bash
npm install @meshsdk/midnight-setup
```

Connect to a wallet and deploy a contract:

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import { setupProviders } from './providers';

const providers = await setupProviders();
const api = await MidnightSetupAPI.deployContract(providers, contractInstance);

console.log('Contract deployed at:', api.deployedContractAddress);
```

## Explore the documentation

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksMidnight.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related resources

* [Midnight Network Documentation](https://docs.midnight.network/) - Official Midnight docs
* [Mesh SDK Documentation](https://midnight.meshjs.dev/en) - Full SDK reference
* [Lace Beta Wallet](https://chromewebstore.google.com/detail/lace-midnight-preview/hgeekaiplokcnmakghbdfbgnlfheichg) - Browser wallet for Midnight
* [GitHub Repository](https://github.com/MeshJS/midnight-setup) - Source code and examples


# Cardano NFT Minting and Development
URL: /nft

Build, mint, and manage NFTs on Cardano with Mesh SDK. Complete tools for collections, marketplaces, and Plutus-based NFT contracts.

***

title: "Cardano NFT Minting and Development"
description: "Build, mint, and manage NFTs on Cardano with Mesh SDK. Complete tools for collections, marketplaces, and Plutus-based NFT contracts."
icon: PhotoIcon
---------------

import Link from "fumadocs-core/link";
import { Card, CardDescription, CardTitle } from "@/components/ui/card";

Create NFTs on Cardano using Mesh's complete toolkit for minting, metadata management, and marketplace integration. Whether you build a simple minting page or a full marketplace, Mesh provides the APIs you need.

## Why Build NFTs on Cardano?

Cardano's native token model offers significant advantages over smart-contract-based NFT systems:

| Feature            | Cardano Native NFTs         | Ethereum ERC-721         |
| ------------------ | --------------------------- | ------------------------ |
| Minting complexity | No smart contract required  | Smart contract mandatory |
| Transaction fees   | Predictable, low cost       | Variable gas fees        |
| Token security     | First-class network citizen | Contract-dependent       |
| Batch operations   | Native support              | Gas-intensive            |
| Metadata storage   | On-chain or IPFS            | Usually IPFS only        |

## Core Capabilities

### Mint Native NFTs

Create NFTs using native scripts without deploying smart contracts. Mesh handles policy ID generation, metadata attachment, and transaction construction automatically.

**Best for:**

* Art and collectibles
* Collection launches with fixed supply
* Event tickets and POAPs
* Membership tokens

```tsx
import { MeshTxBuilder, ForgeScript } from '@meshsdk/core';

// Create a time-locked minting policy
const forgingScript = ForgeScript.withPubKeyHash(walletAddress);

const tx = new MeshTxBuilder({ fetcher, submitter });
await tx
  .mint('1', policyId, 'MyNFT')
  .mintingScript(forgingScript)
  .metadataValue(721, {
    [policyId]: {
      MyNFT: {
        name: 'My First NFT',
        image: 'ipfs://...',
        description: 'Minted with Mesh'
      }
    }
  })
  .complete();
```

### Plutus NFT Contracts

Add custom validation logic for advanced minting rules, royalty enforcement, or dynamic metadata updates.

**Enables:**

* Royalties on secondary sales
* Time-locked minting windows
* Whitelist access control
* Dynamic metadata (CIP-68)
* Burn-to-redeem mechanics

### Metadata Standards

Mesh supports both Cardano NFT metadata standards:

| Standard | Storage              | Mutability | Use Case                       |
| -------- | -------------------- | ---------- | ------------------------------ |
| CIP-25   | Transaction metadata | Immutable  | Static NFTs, art, collectibles |
| CIP-68   | Datum on-chain       | Mutable    | Gaming assets, evolving NFTs   |

## Build NFT Marketplaces

Mesh provides the building blocks for complete marketplace functionality:

* **Listings** - Lock NFTs in escrow contracts with asking prices
* **Purchases** - Atomic payment and NFT transfer
* **Auctions** - Bidding systems with time-based resolution
* **Royalties** - Automated creator payments on each sale
* **Collections** - Query and organize NFTs by policy ID

## Getting Started

<div className="grid md:grid-cols-2 gap-6 items-stretch mt-6">
  <Link href="/guides/nft-collection" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">NFT Collection Guide</CardTitle>
      <CardDescription>Step-by-step tutorial for minting your first NFT collection</CardDescription>
    </Card>
  </Link>

  <Link href="/smart-contracts/marketplace" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Marketplace Contract</CardTitle>
      <CardDescription>Build a decentralized NFT marketplace with Plutus</CardDescription>
    </Card>
  </Link>

  <Link href="/smart-contracts/plutus-nft" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Plutus NFT Minting</CardTitle>
      <CardDescription>Create NFTs with custom on-chain validation rules</CardDescription>
    </Card>
  </Link>

  <Link href="/apis/txbuilder/minting" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Minting API Reference</CardTitle>
      <CardDescription>Complete API documentation for minting and burning</CardDescription>
    </Card>
  </Link>
</div>

## Common Patterns

### Collection Policy

Use a single policy ID for all NFTs in a collection. Distinguish individual tokens with unique asset names. This enables easy collection queries and verification.

```tsx
// All NFTs share the same policy ID
const policyId = 'abc123...';

// Asset names differentiate tokens
const nft1 = { policyId, assetName: 'Token001' };
const nft2 = { policyId, assetName: 'Token002' };
```

### IPFS Metadata

Store images and extended metadata on IPFS. Reference the content hash in on-chain metadata for cost efficiency while maintaining decentralization.

```tsx
const metadata = {
  name: 'My NFT',
  image: 'ipfs://QmXyz...', // IPFS content hash
  attributes: [
    { trait_type: 'Background', value: 'Blue' },
    { trait_type: 'Rarity', value: 'Legendary' }
  ]
};
```

### Lazy Minting

Defer minting until purchase to reduce upfront costs for large collections. The NFT is created when a buyer completes payment.

### Reveal Mechanics

Mint with placeholder metadata, then update to final artwork after a reveal event using CIP-68 datum updates.

## Provider Integration

Query NFT data through multiple blockchain providers:

| Provider   | Capabilities                        |
| ---------- | ----------------------------------- |
| Blockfrost | Metadata queries, ownership lookup  |
| Koios      | Policy and asset endpoints          |
| Maestro    | Rich NFT data, marketplace listings |
| Custom     | Build your own indexer integration  |

See the [Providers documentation](/providers) for configuration details.

## Community Resources

* **Discord** - Real-time support from Mesh developers
* **GitHub** - Example projects and issue tracking
* **Twitter** - Updates on new NFT features

Start building your NFT project today with Mesh.


# Getting Started with React
URL: /react/getting-started

Install Mesh React, configure the provider, and connect your first Cardano wallet in minutes.

***

title: "Getting Started with React"
description: "Install Mesh React, configure the provider, and connect your first Cardano wallet in minutes."
------------------------------------------------------------------------------------------------------------

import Link from "next/link";

## Overview

This guide walks you through setting up Mesh React in your application. By the end, you will have a working wallet connection button that lets users connect their Cardano wallets.

**You will learn how to:**

* Install the `@meshsdk/react` package
* Configure the `MeshProvider` context
* Add a wallet connection button
* Access connected wallet data

## Quick Start

Get a wallet connection working in under 2 minutes:

```tsx
// pages/_app.tsx (Next.js Pages Router)
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

```tsx
// pages/index.tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

export default function Home() {
  const { connected, wallet } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Wallet connected!</p>}
    </div>
  );
}
```

## Installation

### Option 1: Mesh CLI (Recommended)

The fastest way to start is with the Mesh CLI, which scaffolds a complete project:

```bash
npx meshjs your-app-name
```

Select the React template when prompted. This creates a new project with Mesh pre-configured.

### Option 2: Manual Installation

Add the package to an existing project:

```bash
npm install @meshsdk/react
```

```bash
yarn add @meshsdk/react
```

```bash
pnpm add @meshsdk/react
```

## Setup

### Step 1: Add the CSS

Import the Mesh styles in your application root. This applies default styling to all Mesh components.

**Next.js Pages Router** (`pages/_app.tsx`):

```tsx
import "@meshsdk/react/styles.css";
```

**Next.js App Router** (`app/layout.tsx`):

```tsx
import "@meshsdk/react/styles.css";
```

### Step 2: Add the MeshProvider

Wrap your application with `MeshProvider` to enable wallet context throughout your app.

**Next.js Pages Router:**

```tsx
// pages/_app.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

**Next.js App Router:**

```tsx
// app/layout.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <MeshProvider>{children}</MeshProvider>
      </body>
    </html>
  );
}
```

### Step 3: Add the Wallet Button

Add `CardanoWallet` anywhere in your app to show a wallet connection button:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Header() {
  return (
    <nav>
      <CardanoWallet />
    </nav>
  );
}
```

## API Reference

### MeshProvider

The context provider that enables wallet functionality throughout your application.

#### Props

| Prop       | Type        | Default  | Description                 |
| ---------- | ----------- | -------- | --------------------------- |
| `children` | `ReactNode` | Required | Your application components |

#### Usage

```tsx
import { MeshProvider } from "@meshsdk/react";

function App({ children }) {
  return <MeshProvider>{children}</MeshProvider>;
}
```

### CardanoWallet

A pre-built button component that handles wallet selection and connection.

#### Props

| Prop                 | Type                  | Default            | Description                                |
| -------------------- | --------------------- | ------------------ | ------------------------------------------ |
| `label`              | `string`              | `"Connect Wallet"` | Button text before connection              |
| `isDark`             | `boolean`             | `false`            | Enable dark mode styling                   |
| `persist`            | `boolean`             | `false`            | Remember wallet choice across sessions     |
| `onConnected`        | `() => void`          | `undefined`        | Callback fired after successful connection |
| `web3Services`       | `object`              | `undefined`        | Mesh Web3 Services configuration           |
| `cardanoPeerConnect` | `object`              | `undefined`        | CIP-45 WebRTC configuration                |
| `burnerWallet`       | `object`              | `undefined`        | Enable burner wallet for testing           |
| `injectFn`           | `() => Promise<void>` | `undefined`        | Custom wallet injection (MetaMask Snaps)   |

#### Usage Examples

**Basic usage:**

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet />;
}
```

**With dark mode:**

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet isDark={true} />;
}
```

**With custom label:**

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet label="Sign In with Wallet" />;
}
```

**With session persistence:**

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet persist={true} />;
}
```

**With connection callback:**

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  const handleConnected = () => {
    console.log("Wallet connected successfully");
    // Redirect, fetch data, etc.
  };

  return <CardanoWallet onConnected={handleConnected} />;
}
```

### useWallet Hook

Access wallet state and connection functions from any component.

#### Return Values

| Property     | Type                                             | Description                         |
| ------------ | ------------------------------------------------ | ----------------------------------- |
| `wallet`     | `MeshCardanoBrowserWallet`                       | Wallet instance with CIP-30 methods |
| `connected`  | `boolean`                                        | Whether a wallet is connected       |
| `connecting` | `boolean`                                        | Whether connection is in progress   |
| `name`       | `string`                                         | Name of the connected wallet        |
| `state`      | `"NOT_CONNECTED" \| "CONNECTING" \| "CONNECTED"` | Current connection state            |
| `connect`    | `(walletName: string) => void`                   | Connect to a specific wallet        |
| `disconnect` | `() => void`                                     | Disconnect the current wallet       |
| `error`      | `Error \| null`                                  | Connection error if any             |

#### Usage

```tsx
import { useWallet } from "@meshsdk/react";

export default function WalletInfo() {
  const { connected, name, wallet, disconnect } = useWallet();

  if (!connected) {
    return <p>No wallet connected</p>;
  }

  return (
    <div>
      <p>Connected to: {name}</p>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}
```

## Customization

### Dark Mode

Enable dark mode styling with the `isDark` prop:

```tsx
<CardanoWallet isDark={true} />
```

### Custom Button Label

Change the button text:

```tsx
<CardanoWallet label="Sign In" />
```

### Session Persistence

Save the user's wallet choice and auto-connect on return visits:

```tsx
<CardanoWallet persist={true} />
```

### Mesh Web3 Services

Integrate [Mesh Web3 Services](https://utxos.dev/) for enhanced features:

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  return (
    <CardanoWallet
      web3Services={{
        networkId: 0, // 0 = testnet, 1 = mainnet
        fetcher: provider,
        submitter: provider,
      }}
    />
  );
}
```

### CIP-45 WebRTC Connection

Enable decentralized wallet communication via WebRTC:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return (
    <CardanoWallet
      cardanoPeerConnect={{
        dAppInfo: {
          name: "My dApp",
          url: "https://mydapp.com",
        },
        announce: [
          "wss://dev.btt.cf-identity-wallet.metadata.dev.cf-deployments.org",
        ],
      }}
    />
  );
}
```

### Burner Wallet (Testing)

Enable temporary wallets for development and testing:

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  return (
    <CardanoWallet
      burnerWallet={{
        networkId: 0,
        provider: provider,
      }}
    />
  );
}
```

### MetaMask Snaps Integration

Add custom wallet injection for MetaMask Snaps:

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { checkIfMetamaskInstalled } from "./metamask-utils";

export default function Page() {
  return (
    <CardanoWallet
      injectFn={async () => await checkIfMetamaskInstalled("preprod")}
    />
  );
}
```

## Complete Example

A full example combining multiple features:

```tsx
// pages/_app.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

```tsx
// pages/index.tsx
import { CardanoWallet, useWallet, useLovelace } from "@meshsdk/react";

export default function Home() {
  const { connected, name, disconnect } = useWallet();
  const lovelace = useLovelace();

  const handleConnected = () => {
    console.log("Wallet connected!");
  };

  return (
    <main>
      <h1>My Cardano dApp</h1>

      {!connected ? (
        <CardanoWallet
          label="Connect Your Wallet"
          isDark={true}
          persist={true}
          onConnected={handleConnected}
        />
      ) : (
        <div>
          <p>Connected to: {name}</p>
          <p>Balance: {lovelace ? parseInt(lovelace) / 1_000_000 : 0} ADA</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      )}
    </main>
  );
}
```

## Troubleshooting

### "No wallets found"

**Problem:** The wallet list is empty even with wallets installed.

**Solutions:**

1. Ensure the wallet browser extension is installed and enabled
2. Refresh the page after installing a new wallet
3. Check that you're on a supported browser (Chrome, Brave, Firefox)

### "MeshProvider not found"

**Problem:** Hooks throw an error about missing provider.

**Solution:** Wrap your app with `MeshProvider` at the root level:

```tsx
// pages/_app.tsx
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

### Styles not loading

**Problem:** Components appear unstyled.

**Solution:** Import the CSS file in your app root:

```tsx
import "@meshsdk/react/styles.css";
```

### Wallet connection fails silently

**Problem:** Clicking connect does nothing.

**Solutions:**

1. Check browser console for errors
2. Ensure the wallet extension is unlocked
3. Verify the user has an account set up in their wallet
4. Check the `error` property from `useWallet()` for details

### TypeScript errors with wallet methods

**Problem:** TypeScript doesn't recognize wallet methods.

**Solution:** The `wallet` object from `useWallet()` is a `MeshCardanoBrowserWallet` instance. Import types from `@meshsdk/wallet`:

```tsx
import type { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
```

## Related Links

* [UI Components](/docs/react/ui-components) - Pre-built wallet and badge components
* [Wallet Hooks](/docs/react/wallet-hooks) - All available React hooks
* [Browser Wallet API](/apis/wallets/browserwallet) - Full CIP-30 wallet interface
* [Providers](/providers) - Blockchain data providers
* [GitHub Repository](https://github.com/MeshJS/mesh) - Source code and examples


# Cardano React Components
URL: /react

Build Cardano dApps with pre-built React components and hooks for wallet connections, transactions, and blockchain interactions.

***

title: "Cardano React Components"
description: "Build Cardano dApps with pre-built React components and hooks for wallet connections, transactions, and blockchain interactions."
icon: ComputerDesktopIcon
-------------------------

import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Mesh React provides a complete toolkit for building Cardano decentralized applications with React. You get pre-built UI components for wallet connections, React hooks for accessing wallet state, and utilities for blockchain interactions.

**Use Mesh React when you need to:**

* Connect users to their Cardano wallets (Nami, Eternl, Flint, etc.)
* Display wallet balances and assets
* Build transaction signing flows
* Create multi-wallet support in your dApp

## Quick Start

Install the package and wrap your app with the provider:

```tsx
import "@meshsdk/react/styles.css";
import { MeshProvider, CardanoWallet } from "@meshsdk/react";

function App() {
  return (
    <MeshProvider>
      <CardanoWallet />
    </MeshProvider>
  );
}
```

## What's Included

<div className="grid md:grid-cols-2 gap-6 items-stretch mt-6">
  <Link href="/docs/react/getting-started" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Getting Started</CardTitle>
      <CardDescription>Installation, setup, and your first wallet connection</CardDescription>
    </Card>
  </Link>

  <Link href="/docs/react/ui-components" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">UI Components</CardTitle>
      <CardDescription>Pre-built wallet buttons, badges, and connection modals</CardDescription>
    </Card>
  </Link>

  <Link href="/docs/react/wallet-hooks" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Wallet Hooks</CardTitle>
      <CardDescription>React hooks for wallet state, assets, addresses, and networks</CardDescription>
    </Card>
  </Link>

  <Link href="/apis/wallets/browserwallet" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Browser Wallet API</CardTitle>
      <CardDescription>Full CIP-30 wallet API for transactions and signing</CardDescription>
    </Card>
  </Link>
</div>

## Installation

Install using your preferred package manager:

```bash
npm install @meshsdk/react
```

```bash
yarn add @meshsdk/react
```

```bash
pnpm add @meshsdk/react
```

Or scaffold a complete project with the Mesh CLI:

```bash
npx meshjs your-app-name
```

## Requirements

* React 18 or later
* Next.js 13+ (App Router or Pages Router)
* A Cardano wallet browser extension (Nami, Eternl, Flint, Lace, etc.)

## Related Resources

* [Browser Wallet API](/apis/wallets/browserwallet) - Full CIP-30 wallet interface
* [Transaction Builder](/apis/transaction) - Build and sign transactions
* [Providers](/providers) - Blockchain data providers (Blockfrost, Koios, etc.)
* [Mesh CLI](/getting-started/mesh-cli) - Project scaffolding and utilities


# Wallet UI Components
URL: /react/ui-components

Pre-built React components for wallet connections, badges, and common Cardano dApp UI patterns.

***

title: "Wallet UI Components"
description: "Pre-built React components for wallet connections, badges, and common Cardano dApp UI patterns."
--------------------------------------------------------------------------------------------------------------

import Link from "next/link";

## Overview

Mesh provides ready-to-use React components for common Cardano dApp patterns. These components handle wallet connections, display branding, and provide consistent UI across your application.

**Available components:**

* `CardanoWallet` - A complete wallet connection button with modal
* `MeshBadge` - A "Powered by Mesh" badge for your app

## Quick Start

Add a wallet connection button to your app:

```tsx
import { MeshProvider, CardanoWallet } from "@meshsdk/react";
import "@meshsdk/react/styles.css";

export default function App() {
  return (
    <MeshProvider>
      <CardanoWallet />
    </MeshProvider>
  );
}
```

## Installation

```bash
npm install @meshsdk/react
```

Import the styles in your app root:

```tsx
import "@meshsdk/react/styles.css";
```

***

## CardanoWallet

A complete wallet connection component that displays available wallets and handles the connection flow.

### Props

| Prop                 | Type                       | Default            | Description                                   |
| -------------------- | -------------------------- | ------------------ | --------------------------------------------- |
| `label`              | `string`                   | `"Connect Wallet"` | Button text when no wallet is connected       |
| `isDark`             | `boolean`                  | `false`            | Enable dark mode styling                      |
| `persist`            | `boolean`                  | `false`            | Save wallet choice and auto-connect on return |
| `onConnected`        | `() => void`               | `undefined`        | Callback fired after successful connection    |
| `web3Services`       | `Web3ServicesConfig`       | `undefined`        | Mesh Web3 Services integration                |
| `cardanoPeerConnect` | `CardanoPeerConnectConfig` | `undefined`        | CIP-45 WebRTC configuration                   |
| `burnerWallet`       | `BurnerWalletConfig`       | `undefined`        | Enable temporary test wallets                 |
| `injectFn`           | `() => Promise<void>`      | `undefined`        | Custom wallet injection function              |

### Basic Usage

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet />;
}
```

### Dark Mode

Apply dark theme styling:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet isDark={true} />;
}
```

### Custom Label

Change the button text:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet label="Sign In with Wallet" />;
}
```

### Session Persistence

Remember the user's wallet choice and automatically reconnect:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet persist={true} />;
}
```

### Connection Callback

Execute code after successful wallet connection:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  const handleConnected = () => {
    console.log("Wallet connected!");
    // Fetch user data, redirect, etc.
  };

  return <CardanoWallet onConnected={handleConnected} />;
}
```

### Mesh Web3 Services

Integrate [Mesh Web3 Services](https://utxos.dev/) for enhanced features like transaction submission and data fetching:

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  return (
    <CardanoWallet
      web3Services={{
        networkId: 0, // 0 = preprod/preview, 1 = mainnet
        fetcher: provider,
        submitter: provider,
      }}
    />
  );
}
```

### CIP-45 WebRTC Connection

Enable decentralized peer-to-peer wallet communication:

```tsx
import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return (
    <CardanoWallet
      cardanoPeerConnect={{
        dAppInfo: {
          name: "My dApp",
          url: "https://mydapp.com",
        },
        announce: [
          "wss://dev.btt.cf-identity-wallet.metadata.dev.cf-deployments.org",
        ],
      }}
    />
  );
}
```

### Burner Wallet

Enable temporary wallets for development and testing. The private keys are generated and stored on the user's device:

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  return (
    <CardanoWallet
      burnerWallet={{
        networkId: 0,
        provider: provider,
      }}
    />
  );
}
```

### MetaMask Snaps

Inject custom wallet functionality for MetaMask Snaps integration:

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { checkIfMetamaskInstalled } from "./metamask-utils";

export default function Page() {
  return (
    <CardanoWallet
      injectFn={async () => await checkIfMetamaskInstalled("preprod")}
    />
  );
}
```

### Complete Example with All Options

```tsx
import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  const handleConnected = () => {
    console.log("Wallet connected successfully");
  };

  return (
    <CardanoWallet
      label="Connect a Wallet"
      isDark={true}
      persist={true}
      onConnected={handleConnected}
      cardanoPeerConnect={{
        dAppInfo: {
          name: "Mesh SDK",
          url: "https://meshjs.dev/",
        },
        announce: [
          "wss://dev.btt.cf-identity-wallet.metadata.dev.cf-deployments.org",
        ],
      }}
      burnerWallet={{
        networkId: 0,
        provider: provider,
      }}
    />
  );
}
```

### Building a Custom Wallet Component

For advanced customization beyond what `CardanoWallet` provides, build your own component using the [wallet hooks](/docs/react/wallet-hooks):

```tsx
import { useWallet, useWalletList } from "@meshsdk/react";

export default function CustomWalletConnect() {
  const { connect, disconnect, connected, name } = useWallet();
  const wallets = useWalletList();

  if (connected) {
    return (
      <div>
        <span>Connected: {name}</span>
        <button onClick={disconnect}>Disconnect</button>
      </div>
    );
  }

  return (
    <div>
      {wallets.map((wallet) => (
        <button
          key={wallet.name}
          onClick={() => connect(wallet.name)}
        >
          <img src={wallet.icon} alt={wallet.name} width={24} />
          {wallet.name}
        </button>
      ))}
    </div>
  );
}
```

See the [source code](https://github.com/MeshJS/mesh/blob/main/packages/mesh-react/src/cardano-wallet/index.tsx) for implementation details.

***

## MeshBadge

Display a "Powered by Mesh" badge in your application to show your support.

### Props

| Prop     | Type      | Default | Description              |
| -------- | --------- | ------- | ------------------------ |
| `isDark` | `boolean` | `false` | Enable dark mode styling |

### Basic Usage

```tsx
import { MeshBadge } from "@meshsdk/react";

export default function Footer() {
  return (
    <footer>
      <MeshBadge />
    </footer>
  );
}
```

### Dark Mode

```tsx
import { MeshBadge } from "@meshsdk/react";

export default function Footer() {
  return (
    <footer>
      <MeshBadge isDark={true} />
    </footer>
  );
}
```

### Complete Footer Example

```tsx
import { MeshBadge } from "@meshsdk/react";

export default function Footer() {
  return (
    <footer className="border-t py-8">
      <div className="container mx-auto flex justify-between items-center">
        <p>2024 My Cardano dApp</p>
        <MeshBadge isDark={false} />
      </div>
    </footer>
  );
}
```

***

## Complete Example

A full application using all UI components:

```tsx
// pages/_app.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

```tsx
// pages/index.tsx
import { CardanoWallet, MeshBadge, useWallet, useLovelace } from "@meshsdk/react";

export default function Home() {
  const { connected, name } = useWallet();
  const lovelace = useLovelace();

  return (
    <div className="min-h-screen flex flex-col">
      {/* Header */}
      <header className="border-b p-4 flex justify-between items-center">
        <h1 className="text-xl font-bold">My Cardano dApp</h1>
        <CardanoWallet
          label="Connect"
          isDark={true}
          persist={true}
        />
      </header>

      {/* Main Content */}
      <main className="flex-1 p-8">
        {connected ? (
          <div>
            <h2>Welcome!</h2>
            <p>Wallet: {name}</p>
            <p>Balance: {lovelace ? (parseInt(lovelace) / 1_000_000).toFixed(2) : "0"} ADA</p>
          </div>
        ) : (
          <div>
            <h2>Connect your wallet to get started</h2>
            <p>Click the button above to connect your Cardano wallet.</p>
          </div>
        )}
      </main>

      {/* Footer */}
      <footer className="border-t p-4 flex justify-center">
        <MeshBadge />
      </footer>
    </div>
  );
}
```

***

## Troubleshooting

### Components appear unstyled

**Problem:** CardanoWallet or MeshBadge render without styling.

**Solution:** Import the CSS file in your app root:

```tsx
// pages/_app.tsx or app/layout.tsx
import "@meshsdk/react/styles.css";
```

### "Cannot find MeshProvider" error

**Problem:** Components throw an error about missing context.

**Solution:** Wrap your app with `MeshProvider`:

```tsx
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

### Wallet modal doesn't open

**Problem:** Clicking the wallet button does nothing.

**Solutions:**

1. Check browser console for JavaScript errors
2. Ensure you have wallet extensions installed
3. Verify the CSS is loaded (button should have hover effects)

### Dark mode doesn't match my theme

**Problem:** The component dark mode doesn't match your app's theme.

**Solution:** Build a custom component using the [wallet hooks](/docs/react/wallet-hooks) for full control over styling:

```tsx
import { useWallet, useWalletList } from "@meshsdk/react";

// Your fully custom styled component
export function MyWalletButton() {
  const { connect, connected } = useWallet();
  const wallets = useWalletList();
  // ... your custom implementation
}
```

### onConnected fires before wallet is ready

**Problem:** The callback fires but wallet methods aren't available yet.

**Solution:** Use the `wallet` object from `useWallet()` which is available after `connected` becomes `true`:

```tsx
import { useWallet } from "@meshsdk/react";
import { useEffect } from "react";

export default function Page() {
  const { connected, wallet } = useWallet();

  useEffect(() => {
    if (connected && wallet) {
      // Wallet is ready to use
      wallet.getBalance().then(console.log);
    }
  }, [connected, wallet]);

  return <CardanoWallet />;
}
```

***

## Related Links

* [Getting Started](/docs/react/getting-started) - Installation and setup
* [Wallet Hooks](/docs/react/wallet-hooks) - React hooks for wallet data
* [Browser Wallet API](/apis/wallets/browserwallet) - Full CIP-30 interface
* [GitHub Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-react) - Component source code


# Wallet Hooks
URL: /react/wallet-hooks

React hooks for accessing wallet state, balances, addresses, assets, and network information in your Cardano dApp.

***

title: "Wallet Hooks"
description: "React hooks for accessing wallet state, balances, addresses, assets, and network information in your Cardano dApp."
---------------------------------------------------------------------------------------------------------------------------------

import Link from "next/link";

## Overview

Mesh provides React hooks that let you access wallet data and state from any component. These hooks simplify building Cardano dApps by handling wallet connections, balance queries, and state management.

**Available hooks:**

| Hook            | Purpose                             |
| --------------- | ----------------------------------- |
| `useWallet`     | Wallet connection state and methods |
| `useWalletList` | List of installed wallet extensions |
| `useAddress`    | Connected wallet's address          |
| `useAssets`     | All assets in the wallet            |
| `useLovelace`   | ADA balance in lovelace             |
| `useNetwork`    | Connected network (mainnet/testnet) |

## Quick Start

Access wallet state from any component:

```tsx
import { useWallet, useLovelace, useAddress } from "@meshsdk/react";

export default function WalletInfo() {
  const { connected, name } = useWallet();
  const lovelace = useLovelace();
  const address = useAddress();

  if (!connected) {
    return <p>Connect your wallet to continue</p>;
  }

  return (
    <div>
      <p>Wallet: {name}</p>
      <p>Balance: {parseInt(lovelace || "0") / 1_000_000} ADA</p>
      <p>Address: {address}</p>
    </div>
  );
}
```

## Installation

```bash
npm install @meshsdk/react
```

Wrap your app with the provider:

```tsx
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

***

## useWallet

The primary hook for wallet connection state and methods. Returns the wallet instance, connection state, and functions to connect/disconnect.

### Return Values

| Property     | Type                                             | Description                            |
| ------------ | ------------------------------------------------ | -------------------------------------- |
| `wallet`     | `MeshCardanoBrowserWallet \| null`               | Wallet instance with CIP-30 methods    |
| `connected`  | `boolean`                                        | `true` if a wallet is connected        |
| `connecting` | `boolean`                                        | `true` while connection is in progress |
| `name`       | `string`                                         | Name of the connected wallet           |
| `state`      | `"NOT_CONNECTED" \| "CONNECTING" \| "CONNECTED"` | Current connection state               |
| `connect`    | `(walletName: string) => Promise<void>`          | Connect to a specific wallet           |
| `disconnect` | `() => void`                                     | Disconnect the current wallet          |
| `error`      | `Error \| null`                                  | Error object if connection failed      |

### Basic Usage

```tsx
import { useWallet } from "@meshsdk/react";

export default function WalletStatus() {
  const { connected, name, connecting, error } = useWallet();

  if (connecting) {
    return <p>Connecting...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }

  if (!connected) {
    return <p>No wallet connected</p>;
  }

  return <p>Connected to {name}</p>;
}
```

### Programmatic Connection

```tsx
import { useWallet, useWalletList } from "@meshsdk/react";

export default function WalletSelector() {
  const { connect, disconnect, connected, name } = useWallet();
  const wallets = useWalletList();

  if (connected) {
    return (
      <div>
        <p>Connected: {name}</p>
        <button onClick={disconnect}>Disconnect</button>
      </div>
    );
  }

  return (
    <div>
      <h3>Select a wallet:</h3>
      {wallets.map((wallet) => (
        <button key={wallet.name} onClick={() => connect(wallet.name)}>
          <img src={wallet.icon} alt="" width={20} />
          {wallet.name}
        </button>
      ))}
    </div>
  );
}
```

### Using the Wallet Instance

The `wallet` object is a [MeshCardanoBrowserWallet](/apis/wallets/browserwallet) instance with full CIP-30 support:

```tsx
import { useWallet } from "@meshsdk/react";

export default function SignMessage() {
  const { wallet, connected } = useWallet();

  const handleSign = async () => {
    if (!wallet) return;

    const address = await wallet.getChangeAddress();
    const signature = await wallet.signData(address, "Hello, Cardano!");
    console.log("Signature:", signature);
  };

  if (!connected) {
    return <p>Connect wallet first</p>;
  }

  return <button onClick={handleSign}>Sign Message</button>;
}
```

### Handling Connection Errors

```tsx
import { useWallet } from "@meshsdk/react";

export default function WalletConnect() {
  const { connect, error, connected } = useWallet();

  const handleConnect = async () => {
    try {
      await connect("nami");
    } catch (err) {
      console.error("Connection failed:", err);
    }
  };

  return (
    <div>
      {error && (
        <div className="text-red-500">
          Connection failed: {error.message}
        </div>
      )}
      {!connected && (
        <button onClick={handleConnect}>Connect Nami</button>
      )}
    </div>
  );
}
```

***

## useWalletList

Returns a list of wallet extensions installed in the user's browser.

### Return Value

Returns an array of wallet objects:

```tsx
type Wallet = {
  name: string;      // Wallet identifier (e.g., "nami", "eternl")
  icon: string;      // Base64 or URL of wallet icon
  version: string;   // Wallet version
};
```

### Parameters

| Parameter          | Type                  | Description                                    |
| ------------------ | --------------------- | ---------------------------------------------- |
| `options.injectFn` | `() => Promise<void>` | Optional function to inject additional wallets |

### Basic Usage

```tsx
import { useWalletList } from "@meshsdk/react";

export default function InstalledWallets() {
  const wallets = useWalletList();

  if (wallets.length === 0) {
    return <p>No wallets installed. Please install a Cardano wallet.</p>;
  }

  return (
    <ul>
      {wallets.map((wallet) => (
        <li key={wallet.name}>
          <img src={wallet.icon} alt={wallet.name} width={32} />
          {wallet.name} (v{wallet.version})
        </li>
      ))}
    </ul>
  );
}
```

### With Custom Wallet Injection

```tsx
import { useWalletList } from "@meshsdk/react";
import { checkIfMetamaskInstalled } from "./metamask-utils";

export default function WalletList() {
  const wallets = useWalletList({
    injectFn: async () => await checkIfMetamaskInstalled("preprod"),
  });

  return (
    <div>
      {wallets.map((wallet) => (
        <div key={wallet.name}>
          <img src={wallet.icon} alt={wallet.name} width={24} />
          {wallet.name}
        </div>
      ))}
    </div>
  );
}
```

### Building a Custom Wallet Selector

```tsx
import { useWallet, useWalletList } from "@meshsdk/react";
import { useState } from "react";

export default function CustomWalletSelector() {
  const { connect, connected, connecting, name } = useWallet();
  const wallets = useWalletList();
  const [isOpen, setIsOpen] = useState(false);

  if (connected) {
    return (
      <div className="flex items-center gap-2">
        <span className="text-green-500">Connected: {name}</span>
      </div>
    );
  }

  return (
    <div className="relative">
      <button
        onClick={() => setIsOpen(!isOpen)}
        disabled={connecting}
      >
        {connecting ? "Connecting..." : "Connect Wallet"}
      </button>

      {isOpen && (
        <div className="absolute top-full mt-2 bg-white shadow-lg rounded-lg p-2">
          {wallets.length === 0 ? (
            <p>No wallets found</p>
          ) : (
            wallets.map((wallet) => (
              <button
                key={wallet.name}
                onClick={() => {
                  connect(wallet.name);
                  setIsOpen(false);
                }}
                className="flex items-center gap-2 w-full p-2 hover:bg-gray-100"
              >
                <img src={wallet.icon} alt="" width={24} height={24} />
                {wallet.name}
              </button>
            ))
          )}
        </div>
      )}
    </div>
  );
}
```

***

## useAddress

Returns the connected wallet's address.

### Parameters

| Parameter   | Type     | Default | Description                                      |
| ----------- | -------- | ------- | ------------------------------------------------ |
| `accountId` | `number` | `0`     | Account index for wallets with multiple accounts |

### Return Value

| Type                  | Description                                    |
| --------------------- | ---------------------------------------------- |
| `string \| undefined` | Bech32 address or `undefined` if not connected |

### Basic Usage

```tsx
import { useAddress } from "@meshsdk/react";

export default function WalletAddress() {
  const address = useAddress();

  if (!address) {
    return <p>Connect your wallet to see your address</p>;
  }

  return (
    <div>
      <p>Your address:</p>
      <code className="break-all">{address}</code>
    </div>
  );
}
```

### With Account Selection

```tsx
import { useAddress } from "@meshsdk/react";
import { useState } from "react";

export default function MultiAccountAddress() {
  const [accountId, setAccountId] = useState(0);
  const address = useAddress(accountId);

  return (
    <div>
      <label>
        Account:
        <select
          value={accountId}
          onChange={(e) => setAccountId(Number(e.target.value))}
        >
          <option value={0}>Account 0</option>
          <option value={1}>Account 1</option>
          <option value={2}>Account 2</option>
        </select>
      </label>

      {address && (
        <p>Address: <code>{address}</code></p>
      )}
    </div>
  );
}
```

### Copy Address Button

```tsx
import { useAddress } from "@meshsdk/react";
import { useState } from "react";

export default function CopyableAddress() {
  const address = useAddress();
  const [copied, setCopied] = useState(false);

  const copyToClipboard = () => {
    if (address) {
      navigator.clipboard.writeText(address);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    }
  };

  if (!address) return null;

  return (
    <div className="flex items-center gap-2">
      <code className="truncate max-w-xs">{address}</code>
      <button onClick={copyToClipboard}>
        {copied ? "Copied!" : "Copy"}
      </button>
    </div>
  );
}
```

***

## useAssets

Returns all assets in the connected wallet from all UTXOs.

### Return Value

| Type                   | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `Asset[] \| undefined` | Array of assets or `undefined` if not connected |

Each asset has the structure:

```tsx
type Asset = {
  unit: string;      // Policy ID + asset name (hex)
  quantity: string;  // Amount as string
};
```

### Basic Usage

```tsx
import { useAssets } from "@meshsdk/react";

export default function WalletAssets() {
  const assets = useAssets();

  if (!assets) {
    return <p>Connect wallet to view assets</p>;
  }

  if (assets.length === 0) {
    return <p>No assets found</p>;
  }

  return (
    <div>
      <h3>Your Assets ({assets.length})</h3>
      <ul>
        {assets.map((asset, index) => (
          <li key={index}>
            <code>{asset.unit}</code>: {asset.quantity}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### Filter Native Tokens (Exclude ADA)

```tsx
import { useAssets } from "@meshsdk/react";

export default function NativeTokens() {
  const assets = useAssets();

  // Filter out lovelace (ADA)
  const nativeTokens = assets?.filter((asset) => asset.unit !== "lovelace");

  if (!nativeTokens || nativeTokens.length === 0) {
    return <p>No native tokens found</p>;
  }

  return (
    <div>
      <h3>Native Tokens</h3>
      {nativeTokens.map((token, index) => {
        const policyId = token.unit.slice(0, 56);
        const assetName = token.unit.slice(56);

        return (
          <div key={index} className="border p-2 mb-2">
            <p>Policy: {policyId}</p>
            <p>Asset: {assetName || "(empty)"}</p>
            <p>Quantity: {token.quantity}</p>
          </div>
        );
      })}
    </div>
  );
}
```

### Display Asset as JSON

```tsx
import { useAssets } from "@meshsdk/react";

export default function AssetsJson() {
  const assets = useAssets();

  return (
    <pre className="bg-gray-100 p-4 overflow-auto">
      {JSON.stringify(assets, null, 2)}
    </pre>
  );
}
```

***

## useLovelace

Returns the ADA balance in lovelace (1 ADA = 1,000,000 lovelace).

### Return Value

| Type                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `string \| undefined` | Lovelace balance as string, or `undefined` if not connected |

### Basic Usage

```tsx
import { useLovelace } from "@meshsdk/react";

export default function Balance() {
  const lovelace = useLovelace();

  if (!lovelace) {
    return <p>Connect wallet to view balance</p>;
  }

  const ada = parseInt(lovelace) / 1_000_000;

  return <p>Balance: {ada.toFixed(6)} ADA</p>;
}
```

### Formatted Balance Display

```tsx
import { useLovelace } from "@meshsdk/react";

export default function FormattedBalance() {
  const lovelace = useLovelace();

  const formatAda = (lovelace: string) => {
    const ada = parseInt(lovelace) / 1_000_000;
    return new Intl.NumberFormat("en-US", {
      minimumFractionDigits: 2,
      maximumFractionDigits: 6,
    }).format(ada);
  };

  if (!lovelace) {
    return <p className="text-gray-500">--</p>;
  }

  return (
    <div className="text-2xl font-bold">
      {formatAda(lovelace)} <span className="text-gray-500">ADA</span>
    </div>
  );
}
```

### Balance with USD Conversion

```tsx
import { useLovelace } from "@meshsdk/react";
import { useEffect, useState } from "react";

export default function BalanceWithUsd() {
  const lovelace = useLovelace();
  const [adaPrice, setAdaPrice] = useState<number | null>(null);

  useEffect(() => {
    // Fetch ADA price (example - use your preferred API)
    fetch("https://api.coingecko.com/api/v3/simple/price?ids=cardano&vs_currencies=usd")
      .then((res) => res.json())
      .then((data) => setAdaPrice(data.cardano.usd))
      .catch(console.error);
  }, []);

  if (!lovelace) {
    return <p>Connect wallet to view balance</p>;
  }

  const ada = parseInt(lovelace) / 1_000_000;
  const usd = adaPrice ? ada * adaPrice : null;

  return (
    <div>
      <p className="text-2xl">{ada.toFixed(2)} ADA</p>
      {usd !== null && (
        <p className="text-gray-500">${usd.toFixed(2)} USD</p>
      )}
    </div>
  );
}
```

***

## useNetwork

Returns the network the connected wallet is on.

### Return Value

| Type                  | Description                              |
| --------------------- | ---------------------------------------- |
| `number \| undefined` | Network ID: `0` = testnet, `1` = mainnet |

### Basic Usage

```tsx
import { useNetwork } from "@meshsdk/react";

export default function NetworkInfo() {
  const network = useNetwork();

  if (network === undefined) {
    return <p>Connect wallet to see network</p>;
  }

  return (
    <p>
      Network: {network === 1 ? "Mainnet" : "Testnet"}
    </p>
  );
}
```

### Network Badge

```tsx
import { useNetwork } from "@meshsdk/react";

export default function NetworkBadge() {
  const network = useNetwork();

  if (network === undefined) return null;

  const isMainnet = network === 1;

  return (
    <span
      className={`px-2 py-1 rounded text-sm ${
        isMainnet
          ? "bg-green-100 text-green-800"
          : "bg-yellow-100 text-yellow-800"
      }`}
    >
      {isMainnet ? "Mainnet" : "Testnet"}
    </span>
  );
}
```

### Network-Aware Component

```tsx
import { useNetwork, useWallet } from "@meshsdk/react";

export default function NetworkAwareActions() {
  const { connected } = useWallet();
  const network = useNetwork();

  if (!connected) {
    return <p>Connect your wallet</p>;
  }

  if (network === 0) {
    return (
      <div className="bg-yellow-50 p-4 rounded">
        <p className="text-yellow-800">
          You are on testnet. Switch to mainnet for real transactions.
        </p>
        <button className="mt-2 bg-yellow-500 text-white px-4 py-2 rounded">
          Test Transaction
        </button>
      </div>
    );
  }

  return (
    <div className="bg-green-50 p-4 rounded">
      <p className="text-green-800">You are on mainnet.</p>
      <button className="mt-2 bg-green-500 text-white px-4 py-2 rounded">
        Send Transaction
      </button>
    </div>
  );
}
```

***

## Complete Example

A dashboard combining all hooks:

```tsx
import {
  useWallet,
  useWalletList,
  useAddress,
  useAssets,
  useLovelace,
  useNetwork,
  CardanoWallet,
} from "@meshsdk/react";

export default function WalletDashboard() {
  const { connected, name, disconnect } = useWallet();
  const wallets = useWalletList();
  const address = useAddress();
  const assets = useAssets();
  const lovelace = useLovelace();
  const network = useNetwork();

  if (!connected) {
    return (
      <div className="p-8">
        <h1 className="text-2xl mb-4">Connect Your Wallet</h1>
        <CardanoWallet />

        <div className="mt-8">
          <h2 className="text-lg mb-2">Installed Wallets:</h2>
          <ul>
            {wallets.map((w) => (
              <li key={w.name} className="flex items-center gap-2">
                <img src={w.icon} alt="" width={20} />
                {w.name}
              </li>
            ))}
          </ul>
        </div>
      </div>
    );
  }

  const adaBalance = lovelace ? (parseInt(lovelace) / 1_000_000).toFixed(2) : "0";
  const nativeTokens = assets?.filter((a) => a.unit !== "lovelace") || [];

  return (
    <div className="p-8">
      {/* Header */}
      <div className="flex justify-between items-center mb-8">
        <div>
          <h1 className="text-2xl font-bold">Wallet Dashboard</h1>
          <p className="text-gray-500">Connected to {name}</p>
        </div>
        <div className="flex items-center gap-4">
          <span
            className={`px-2 py-1 rounded text-sm ${
              network === 1
                ? "bg-green-100 text-green-800"
                : "bg-yellow-100 text-yellow-800"
            }`}
          >
            {network === 1 ? "Mainnet" : "Testnet"}
          </span>
          <button
            onClick={disconnect}
            className="bg-red-500 text-white px-4 py-2 rounded"
          >
            Disconnect
          </button>
        </div>
      </div>

      {/* Balance */}
      <div className="bg-gray-50 p-6 rounded-lg mb-6">
        <h2 className="text-lg text-gray-600 mb-2">Balance</h2>
        <p className="text-4xl font-bold">{adaBalance} ADA</p>
      </div>

      {/* Address */}
      <div className="bg-gray-50 p-6 rounded-lg mb-6">
        <h2 className="text-lg text-gray-600 mb-2">Address</h2>
        <code className="break-all text-sm">{address}</code>
      </div>

      {/* Native Tokens */}
      <div className="bg-gray-50 p-6 rounded-lg">
        <h2 className="text-lg text-gray-600 mb-2">
          Native Tokens ({nativeTokens.length})
        </h2>
        {nativeTokens.length === 0 ? (
          <p className="text-gray-500">No native tokens</p>
        ) : (
          <ul className="space-y-2">
            {nativeTokens.slice(0, 10).map((token, i) => (
              <li key={i} className="flex justify-between">
                <code className="text-sm truncate max-w-xs">
                  {token.unit.slice(0, 20)}...
                </code>
                <span>{token.quantity}</span>
              </li>
            ))}
            {nativeTokens.length > 10 && (
              <li className="text-gray-500">
                +{nativeTokens.length - 10} more tokens
              </li>
            )}
          </ul>
        )}
      </div>
    </div>
  );
}
```

***

## Troubleshooting

### Hooks return undefined

**Problem:** All hooks return `undefined` even after connecting.

**Solutions:**

1. Ensure `MeshProvider` wraps your app at the root level
2. Wait for `connected` to be `true` before accessing data
3. Check that the wallet extension is unlocked

```tsx
import { useWallet, useLovelace } from "@meshsdk/react";

export default function SafeComponent() {
  const { connected } = useWallet();
  const lovelace = useLovelace();

  // Always check connected first
  if (!connected) {
    return <p>Please connect your wallet</p>;
  }

  // Then check if data is loaded
  if (!lovelace) {
    return <p>Loading balance...</p>;
  }

  return <p>Balance: {lovelace}</p>;
}
```

### useWalletList returns empty array

**Problem:** No wallets appear in the list.

**Solutions:**

1. Ensure wallet extensions are installed and enabled
2. Check that you're testing in a browser (not SSR)
3. Refresh the page after installing a new wallet

### "Cannot read properties of undefined"

**Problem:** Accessing wallet properties throws errors.

**Solution:** Use optional chaining and null checks:

```tsx
const { wallet, connected } = useWallet();

// Safe access
const handleAction = async () => {
  if (!connected || !wallet) return;
  const address = await wallet.getChangeAddress();
};
```

### Balance doesn't update after transaction

**Problem:** `useLovelace` shows stale data after sending/receiving.

**Solution:** Wallet hooks auto-refresh, but you can force a reconnection:

```tsx
const { disconnect, connect, name } = useWallet();

const refreshWallet = async () => {
  disconnect();
  await new Promise((r) => setTimeout(r, 100));
  await connect(name);
};
```

### TypeScript type errors

**Problem:** TypeScript doesn't recognize hook return types.

**Solution:** Import types from `@meshsdk/wallet` and `@meshsdk/core`:

```tsx
import type { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import type { Asset } from "@meshsdk/core";
import { useWallet, useAssets } from "@meshsdk/react";

const { wallet } = useWallet() as { wallet: MeshCardanoBrowserWallet | null };
const assets = useAssets() as Asset[] | undefined;
```

***

## Related Links

* [Getting Started](/docs/react/getting-started) - Installation and setup
* [UI Components](/docs/react/ui-components) - Pre-built wallet button and badge
* [Browser Wallet API](/apis/wallets/browserwallet) - Full CIP-30 wallet interface
* [Transaction Builder](/apis/transaction) - Build and sign transactions
* [GitHub Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-react) - Hook implementations


# Developer Resources
URL: /resources/developer-resources

Tools, communities, and resources for Cardano developers building with Mesh.

***

title: "Developer Resources"
description: "Tools, communities, and resources for Cardano developers building with Mesh."
-------------------------------------------------------------------------------------------

import { Card, CardHeader, CardTitle, CardDescription } from '@/components/ui/card';
import Link from 'next/link';

Find the tools, documentation, and community resources you need to build Cardano applications with Mesh.

## Mesh documentation

| Resource                            | Description                       |
| ----------------------------------- | --------------------------------- |
| [Getting Started](/guides)          | Set up your first Mesh project    |
| [API Reference](/apis)              | Complete API documentation        |
| [Smart Contracts](/smart-contracts) | Build with Plutus and Aiken       |
| [React Components](/react)          | UI components for dApps           |
| [Providers](/providers)             | Connect to Cardano infrastructure |

## Code and examples

| Resource                                                    | Description                   |
| ----------------------------------------------------------- | ----------------------------- |
| [GitHub Repository](https://github.com/MeshJS/mesh)         | Source code and contributions |
| [Example Projects](https://github.com/MeshJS/examples)      | Working code samples          |
| [Starter Templates](https://github.com/MeshJS/mesh-starter) | Boilerplate projects          |
| [NPM Package](https://www.npmjs.com/package/@meshsdk/core)  | Package downloads             |

## Community

<div className="grid md:grid-cols-2 gap-4 my-6">
  <Card>
    <CardHeader>
      <CardTitle>Discord</CardTitle>

      <CardDescription>
        Real-time help and discussions with the Mesh community.

        <br />

        <Link href="https://discord.gg/dH48jH3BKa" className="text-primary hover:underline mt-2 inline-block">
          Join Discord
        </Link>
      </CardDescription>
    </CardHeader>
  </Card>

  <Card>
    <CardHeader>
      <CardTitle>Twitter</CardTitle>

      <CardDescription>
        Follow [@meshsdk](https://twitter.com/meshsdk) for announcements and tips.

        <br />

        <Link href="https://twitter.com/meshsdk" className="text-primary hover:underline mt-2 inline-block">
          Follow on Twitter
        </Link>
      </CardDescription>
    </CardHeader>
  </Card>

  <Card>
    <CardHeader>
      <CardTitle>GitHub Discussions</CardTitle>

      <CardDescription>
        Technical discussions, questions, and ideas.

        <br />

        <Link href="https://github.com/MeshJS/mesh/discussions" className="text-primary hover:underline mt-2 inline-block">
          Join Discussions
        </Link>
      </CardDescription>
    </CardHeader>
  </Card>

  <Card>
    <CardHeader>
      <CardTitle>Stack Overflow</CardTitle>

      <CardDescription>
        Ask technical questions tagged with `meshsdk`.

        <br />

        <Link href="https://stackoverflow.com/questions/tagged/meshsdk" className="text-primary hover:underline mt-2 inline-block">
          View Questions
        </Link>
      </CardDescription>
    </CardHeader>
  </Card>
</div>

## Cardano ecosystem

### Official resources

| Resource                                           | Description              |
| -------------------------------------------------- | ------------------------ |
| [Cardano.org](https://cardano.org)                 | Official Cardano website |
| [Cardano Documentation](https://docs.cardano.org)  | Protocol documentation   |
| [Developer Portal](https://developers.cardano.org) | Development guides       |
| [Cardano Forum](https://forum.cardano.org)         | Community discussions    |

### Block explorers

| Explorer                              | Features                          |
| ------------------------------------- | --------------------------------- |
| [CardanoScan](https://cardanoscan.io) | Comprehensive blockchain explorer |
| [Cexplorer](https://cexplorer.io)     | Detailed blockchain data          |
| [Pool.pm](https://pool.pm)            | Native assets and NFT explorer    |
| [AdaStat](https://adastat.net)        | Analytics and statistics          |

## Learning

### Courses

| Provider                                                         | Focus                        |
| ---------------------------------------------------------------- | ---------------------------- |
| [Emurgo Academy](https://education.emurgo.io)                    | Professional Cardano courses |
| [Gimbalabs](https://gimbalabs.com)                               | Community-driven learning    |
| [Plutus Pioneers](https://plutus-pioneer-program.readthedocs.io) | Smart contract development   |

### Documentation

| Resource                                           | Topic                            |
| -------------------------------------------------- | -------------------------------- |
| [Developer Portal](https://developers.cardano.org) | Comprehensive development guides |
| [Essential Cardano](https://essentialcardano.io)   | Curated resources                |
| [Aiken Lang](https://aiken-lang.org)               | Aiken smart contract language    |

## AI assistance

Mesh includes built-in AI features:

* **[AI Chat](/ai)** - Ask questions, get instant answers
* **Code generation** - Generate Mesh code from descriptions
* **Documentation search** - Semantic search across docs

Access Mesh AI from any documentation page or visit the [AI page](/ai).

## Contributing

### How to contribute

1. **Code** - Fork, improve, submit PRs
2. **Documentation** - Fix typos, add examples
3. **Bug reports** - Help identify issues
4. **Feature requests** - Suggest improvements
5. **Community** - Answer questions on Discord

See the [Contributing Guide](https://github.com/MeshJS/mesh/blob/main/CONTRIBUTING.md).

### Support Mesh

* [GitHub Sponsors](https://github.com/sponsors/MeshJS)
* [Support page](/about/support-us)

## Quick links

<div className="grid md:grid-cols-3 gap-3 my-6">
  <Link href="/guides" className="no-underline">
    <Card className="h-full hover:border-primary/50 transition-colors">
      <CardHeader>
        <CardTitle className="text-lg">Guides</CardTitle>
        <CardDescription>Step-by-step tutorials</CardDescription>
      </CardHeader>
    </Card>
  </Link>

  <Link href="/apis" className="no-underline">
    <Card className="h-full hover:border-primary/50 transition-colors">
      <CardHeader>
        <CardTitle className="text-lg">API Docs</CardTitle>
        <CardDescription>Complete reference</CardDescription>
      </CardHeader>
    </Card>
  </Link>

  <Link href="/resources/faq" className="no-underline">
    <Card className="h-full hover:border-primary/50 transition-colors">
      <CardHeader>
        <CardTitle className="text-lg">FAQ</CardTitle>
        <CardDescription>Common questions</CardDescription>
      </CardHeader>
    </Card>
  </Link>

  <Link href="https://github.com/MeshJS/examples" className="no-underline">
    <Card className="h-full hover:border-primary/50 transition-colors">
      <CardHeader>
        <CardTitle className="text-lg">Examples</CardTitle>
        <CardDescription>Working code</CardDescription>
      </CardHeader>
    </Card>
  </Link>

  <Link href="https://discord.gg/dH48jH3BKa" className="no-underline">
    <Card className="h-full hover:border-primary/50 transition-colors">
      <CardHeader>
        <CardTitle className="text-lg">Discord</CardTitle>
        <CardDescription>Community chat</CardDescription>
      </CardHeader>
    </Card>
  </Link>

  <Link href="/about/support-us" className="no-underline">
    <Card className="h-full hover:border-primary/50 transition-colors">
      <CardHeader>
        <CardTitle className="text-lg">Support</CardTitle>
        <CardDescription>Help Mesh grow</CardDescription>
      </CardHeader>
    </Card>
  </Link>
</div>

***

**Ready to build?** Start with the [Getting Started Guide](/guides) or explore the [API Documentation](/apis).


# FAQ
URL: /resources/faq

Answers to common questions about Mesh SDK for Cardano development.

***

title: "FAQ"
description: "Answers to common questions about Mesh SDK for Cardano development."
----------------------------------------------------------------------------------

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

## Getting started

### What is Mesh?

Mesh is an open-source TypeScript SDK for building Cardano applications. It provides wallet integrations, transaction builders, React components, and smart contract tools to help you ship dApps faster.

### Why use Mesh?

| Benefit            | Details                                           |
| ------------------ | ------------------------------------------------- |
| Lightweight        | Less than 60kB bundle size                        |
| Production-ready   | 1M+ downloads, battle-tested                      |
| Developer-friendly | Intuitive APIs with TypeScript support            |
| Comprehensive      | Wallet integration, transactions, smart contracts |
| Always current     | Updated with Cardano network changes              |

### Is Mesh free?

Yes. Mesh is open-source under Apache 2.0 and MIT licenses. Use it for personal or commercial projects without licensing fees. View the source on [GitHub](https://github.com/MeshJS/mesh).

### What are the requirements?

* Node.js 16+
* npm, yarn, or bun
* TypeScript 4.5+ (recommended)
* React 18+ (for React components)

***

## Installation

### How do I install Mesh?

```bash
npm install @meshsdk/core
```

For React projects, also install the React bindings:

```bash
npm install @meshsdk/react
```

### Does Mesh work with Next.js?

Yes. Mesh supports both App Router and Pages Router. See the [Next.js integration guide](/guides/nextjs) for setup instructions.

### What frameworks are supported?

| Framework  | Package           |
| ---------- | ----------------- |
| React      | `@meshsdk/react`  |
| Next.js    | `@meshsdk/react`  |
| Svelte     | `@meshsdk/svelte` |
| Vue.js     | `@meshsdk/core`   |
| Node.js    | `@meshsdk/core`   |
| Vanilla JS | `@meshsdk/core`   |

***

## Wallets

### Which wallets are supported?

Mesh supports all CIP-30 compliant wallets:

* Eternl
* Lace
* Yoroi
* Typhon
* Nami
* Flint
* And any other CIP-30 wallet

New CIP-30 wallets work automatically.

### How do I connect a wallet?

Use the `CardanoWallet` component for the simplest integration:

```tsx
import { CardanoWallet } from '@meshsdk/react';

export default function App() {
  return (
    <CardanoWallet
      label="Connect Wallet"
      onConnected={() => console.log('Connected!')}
    />
  );
}
```

See [wallet hooks documentation](/react/wallet-hooks) for advanced patterns.

### Can I build a wallet app?

Yes. The `MeshCardanoHeadlessWallet` class supports:

* Mnemonic phrase generation
* Private key import
* cardano-cli compatibility
* Multi-signature workflows
* Browser extension development

See the [Wallet documentation](/apis/wallets).

***

## Transactions

### How do I build transactions?

Use `MeshTxBuilder` for intuitive transaction construction:

```typescript
import { MeshTxBuilder } from '@meshsdk/core';

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const unsignedTx = await txBuilder
  .txOut('addr1...', [{ unit: 'lovelace', quantity: '1000000' }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

See the [MeshTxBuilder documentation](/apis/txbuilder).

### Does Mesh support smart contracts?

Yes. Mesh provides full support for Plutus and Aiken smart contracts:

* Transaction building with script execution
* Datum and redeemer handling
* Script validation
* Multi-asset operations

See [Smart Contracts guides](/smart-contracts) and [Aiken tutorials](/aiken).

### Can I mint NFTs?

Yes. Mesh supports:

* Single NFT minting
* Collection minting
* Multi-signature minting
* CIP-25 and CIP-68 metadata

See the [Minting guide](/guides/nft-collection).

***

## Development

### How do I test my dApp?

| Environment          | Use case                               |
| -------------------- | -------------------------------------- |
| Preprod/Preview      | Free test ADA, real network conditions |
| [Yaci DevNet](/yaci) | Local development, fast iteration      |
| Mainnet              | Production deployment                  |

### Where can I find examples?

* [Documentation](/docs) - Guides with code samples
* [GitHub examples](https://github.com/MeshJS/examples) - Working projects
* [API pages](/apis) - Interactive demos

### How do I get help?

| Channel                                                              | Best for                      |
| -------------------------------------------------------------------- | ----------------------------- |
| [Discord](https://discord.gg/dH48jH3BKa)                             | Real-time help                |
| [GitHub Issues](https://github.com/MeshJS/mesh/issues)               | Bug reports, feature requests |
| [Stack Overflow](https://stackoverflow.com/questions/tagged/meshsdk) | Searchable Q\&A               |
| [Twitter](https://twitter.com/meshsdk)                               | Updates and announcements     |

***

## Production

### Is Mesh production-ready?

Yes. Mesh powers live Cardano applications with:

* 1M+ downloads
* Comprehensive error handling
* TypeScript type safety
* Less than 60kB bundle size
* Regular updates for network changes

### How do I optimize bundle size?

Mesh supports tree-shaking. To minimize bundle size:

1. Import only what you need
2. Use code splitting
3. Enable production builds
4. Use Next.js automatic optimization

### Does Mesh work offline?

| Feature                | Offline | Online required |
| ---------------------- | ------- | --------------- |
| Transaction building   | Yes     | No              |
| Address generation     | Yes     | No              |
| Key management         | Yes     | No              |
| Blockchain queries     | No      | Yes             |
| Transaction submission | No      | Yes             |
| UTXO fetching          | No      | Yes             |

***

## Commercial use

### Can I use Mesh commercially?

Yes. Mesh is dual-licensed under Apache 2.0 and MIT. Build and sell applications without licensing fees.

### How can I contribute?

* Submit [bug reports](https://github.com/MeshJS/mesh/issues)
* Open [pull requests](https://github.com/MeshJS/mesh)
* Improve documentation
* Help others on Discord
* [Support financially](/about/support-us)

See the [contributing guide](https://github.com/MeshJS/mesh/blob/main/CONTRIBUTING.md).

***

## Still have questions?

* [Discord community](https://discord.gg/dH48jH3BKa)
* [GitHub Discussions](https://github.com/MeshJS/mesh/discussions)
* [Documentation](/docs)

<script type="application/ld+json">
  {JSON.stringify({
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What is MeshJS?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Mesh is an open-source TypeScript SDK that makes it easy to build Cardano blockchain applications. It provides a comprehensive suite of tools, React components, wallet integrations, and transaction builders to help developers Ship Cardano dApps faster."
        }
      },
      {
        "@type": "Question",
        "name": "Is Mesh free to use?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Yes! Mesh is completely open-source and free to use for both personal and commercial projects under Apache 2.0 and MIT licenses."
        }
      },
      {
        "@type": "Question",
        "name": "Which Cardano wallets does Mesh support?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Mesh supports all CIP-30 compliant Cardano wallets including Eternl, Typhon, Yoroi, Lace, and many more. Any new CIP-30 wallet is automatically supported."
        }
      },
      {
        "@type": "Question",
        "name": "Does Mesh support smart contracts?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Yes! Mesh provides comprehensive smart contract support for both Plutus and Aiken, including transaction building with smart contract execution, datum and redeemer handling, script validation, and multi-asset operations."
        }
      },
      {
        "@type": "Question",
        "name": "Is Mesh suitable for production applications?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Absolutely! Mesh is production-ready with 1M+ downloads, comprehensive error handling, TypeScript support, small bundle size, and regular updates aligned with Cardano network changes."
        }
      }
    ]
    })}
</script>


# Resources
URL: /resources

Comprehensive courses, tutorials, and resources for Cardano developers.

***

title: "Resources"
description: "Comprehensive courses, tutorials, and resources for Cardano developers."
icon: AcademicCapIcon
---------------------

import {linksLearn} from "@/data/links-course";
import {metaGuides} from "@/data/links-guides";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

Find everything you need to build on Cardano with Mesh. Access courses, tutorials, developer tools, and community resources to accelerate your development journey.

## Learning paths

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {[...linksLearn, metaGuides].map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Quick links

| Resource                                              | Description                                  |
| ----------------------------------------------------- | -------------------------------------------- |
| [Getting Started](/guides)                            | Set up Mesh and build your first transaction |
| [API Reference](/apis)                                | Complete API documentation                   |
| [Smart Contracts](/smart-contracts)                   | Build with Plutus and Aiken                  |
| [FAQ](/resources/faq)                                 | Common questions answered                    |
| [Developer Resources](/resources/developer-resources) | Tools, communities, and ecosystem            |

## Need help?

* **[Discord](https://discord.gg/dH48jH3BKa)** - Real-time community support
* **[GitHub](https://github.com/MeshJS/mesh)** - Report issues and contribute
* **[Twitter](https://twitter.com/meshsdk)** - Latest updates and announcements


# Tutorials
URL: /resources/tutorials

Step-by-step tutorials for building Cardano applications with Mesh SDK.

***

title: "Tutorials"
description: "Step-by-step tutorials for building Cardano applications with Mesh SDK."
--------------------------------------------------------------------------------------

import Link from 'next/link';
import { Card, CardHeader, CardTitle, CardDescription } from '@/components/ui/card';

Learn to build on Cardano with hands-on tutorials. Each tutorial includes working code, explanations, and best practices.

## Getting started

Start here if you are new to Mesh or Cardano development.

| Tutorial                                            | Time   | Level    |
| --------------------------------------------------- | ------ | -------- |
| [Installation & Setup](/guides)                     | 10 min | Beginner |
| [Next.js Integration](/guides/nextjs)               | 15 min | Beginner |
| [React Hooks & Components](/react/getting-started)  | 20 min | Beginner |
| [Wallet Connection](/guides/prove-wallet-ownership) | 15 min | Beginner |

***

## Transactions

Learn to build and submit Cardano transactions.

| Tutorial                                              | Time   | Level        |
| ----------------------------------------------------- | ------ | ------------ |
| [Send ADA & Tokens](/apis/txbuilder/basics)           | 20 min | Beginner     |
| [Transaction Builder](/apis/txbuilder/basics)         | 30 min | Intermediate |
| [Multi-Asset Transactions](/apis/txbuilder/minting)   | 25 min | Intermediate |
| [Server-Side Transactions](/guides/minting-on-nodejs) | 30 min | Intermediate |

### Send ADA example

```typescript
import { MeshTxBuilder } from '@meshsdk/core';

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: 'lovelace', quantity: '5000000' }])
  .changeAddress(await wallet.getChangeAddress())
  .selectUtxosFrom(await wallet.getUtxos())
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

***

## NFT development

Create and manage NFTs on Cardano.

| Tutorial                                                 | Time   | Level        |
| -------------------------------------------------------- | ------ | ------------ |
| [Mint Your First NFT](/guides/nft-collection)            | 30 min | Beginner     |
| [Multi-Signature Minting](/guides/multisig-minting)      | 45 min | Intermediate |
| [Advanced NFT Metadata](/apis/txbuilder/minting)         | 35 min | Intermediate |
| [Burning Assets](/apis/txbuilder/minting#burning-assets) | 25 min | Intermediate |

### Mint NFT example

```typescript
const tx = await txBuilder
  .mint('1', policyId, assetName)
  .mintingScript(mintingScript)
  .txOut(recipientAddress, [
    { unit: policyId + assetName, quantity: '1' },
    { unit: 'lovelace', quantity: '2000000' }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Smart contracts

Build with Plutus and Aiken smart contracts.

| Tutorial                                                           | Time   | Level        |
| ------------------------------------------------------------------ | ------ | ------------ |
| [Getting Started with Aiken](/aiken/getting-started)               | 40 min | Intermediate |
| [Your First Aiken Script](/aiken/first-script)                     | 50 min | Intermediate |
| [Smart Contract Transactions](/guides/smart-contract-transactions) | 60 min | Advanced     |
| [Advanced Contract Patterns](/aiken/transactions)                  | 90 min | Advanced     |

### Lock funds to script

```typescript
const tx = await txBuilder
  .txOut(scriptAddress, [{ unit: 'lovelace', quantity: '10000000' }])
  .txOutDatumHashValue(datum)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Unlock funds from script

```typescript
const tx = await txBuilder
  .spendingPlutusScript(languageVersion)
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInScript(scriptCbor)
  .txInDatumValue(datum)
  .txInRedeemerValue(redeemer)
  .txOut(recipient, outputValue)
  .txInCollateral(collateralTxHash, collateralIndex)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Advanced topics

For experienced developers building production applications.

| Tutorial                                    | Time   | Level        |
| ------------------------------------------- | ------ | ------------ |
| [Custom Providers](/guides/custom-provider) | 45 min | Advanced     |
| [Provider Integration](/providers)          | 30 min | Intermediate |
| [Local Development with Yaci](/yaci)        | 40 min | Advanced     |
| [Production Best Practices](/guides/aiken)  | 60 min | Advanced     |

***

## Framework integrations

Use Mesh with your preferred framework.

| Framework | Tutorial                                       | Time   |
| --------- | ---------------------------------------------- | ------ |
| Next.js   | [Full Stack Guide](/guides/nextjs)             | 45 min |
| Svelte    | [Svelte Integration](/svelte)                  | 30 min |
| Node.js   | [Backend Guide](/guides/node-specific-imports) | 35 min |

***

## Learning paths

Follow these structured paths based on your goals.

### Path 1: Web developer to dApp developer

| Step | Tutorial                 | Time   |
| ---- | ------------------------ | ------ |
| 1    | Installation & Setup     | 10 min |
| 2    | Wallet Connection        | 15 min |
| 3    | Send ADA & Tokens        | 20 min |
| 4    | React Hooks & Components | 20 min |
| 5    | Mint Your First NFT      | 30 min |
| 6    | Next.js Integration      | 45 min |

**Total: \~2.5 hours** | Beginner to Intermediate

### Path 2: Smart contract developer

| Step | Tutorial                    | Time   |
| ---- | --------------------------- | ------ |
| 1    | Getting Started with Aiken  | 40 min |
| 2    | Your First Aiken Script     | 50 min |
| 3    | Smart Contract Transactions | 60 min |
| 4    | Advanced Contract Patterns  | 90 min |
| 5    | Local Development with Yaci | 40 min |
| 6    | Production Best Practices   | 60 min |

**Total: \~5.5 hours** | Intermediate to Advanced

### Path 3: NFT collection creator

| Step | Tutorial                 | Time   |
| ---- | ------------------------ | ------ |
| 1    | Installation & Setup     | 10 min |
| 2    | Wallet Connection        | 15 min |
| 3    | Mint Your First NFT      | 30 min |
| 4    | Advanced NFT Metadata    | 35 min |
| 5    | Multi-Signature Minting  | 45 min |
| 6    | Server-Side Transactions | 30 min |

**Total: \~2.5 hours** | Beginner to Intermediate

***

## Additional resources

| Resource                                              | Description                |
| ----------------------------------------------------- | -------------------------- |
| [API Reference](/apis)                                | Complete API documentation |
| [Code Examples](https://github.com/MeshJS/examples)   | Working repositories       |
| [FAQ](/resources/faq)                                 | Common questions           |
| [Use Cases](/resources/use-cases)                     | Real-world applications    |
| [Developer Resources](/resources/developer-resources) | Tools and communities      |

## Get help

| Channel                                                              | Best for           |
| -------------------------------------------------------------------- | ------------------ |
| [Discord](https://discord.gg/dH48jH3BKa)                             | Real-time support  |
| [GitHub Discussions](https://github.com/MeshJS/mesh/discussions)     | Technical Q\&A     |
| [Stack Overflow](https://stackoverflow.com/questions/tagged/meshsdk) | Searchable answers |

***

## After these tutorials

You will be ready to:

* Build production Cardano dApps
* Create NFT collections and marketplaces
* Develop DeFi applications
* Integrate smart contracts
* Contribute to the Cardano ecosystem

**Start now** with the [Getting Started Guide](/guides).

<script type="application/ld+json">
  {JSON.stringify({
    "@context": "https://schema.org",
    "@type": "ItemList",
    "name": "Mesh SDK Tutorials",
    "description": "Step-by-step tutorials for building Cardano applications with Mesh TypeScript SDK",
    "itemListElement": [
      {
        "@type": "HowTo",
        "position": 1,
        "name": "Getting Started with Mesh",
        "description": "Install Mesh and set up your first Cardano project",
        "totalTime": "PT10M",
        "skillLevel": "Beginner"
      },
      {
        "@type": "HowTo",
        "position": 2,
        "name": "Wallet Connection",
        "description": "Connect Cardano wallets and prove ownership",
        "totalTime": "PT15M",
        "skillLevel": "Beginner"
      },
      {
        "@type": "HowTo",
        "position": 3,
        "name": "Mint Your First NFT",
        "description": "Create a complete NFT collection with metadata",
        "totalTime": "PT30M",
        "skillLevel": "Beginner"
      },
      {
        "@type": "HowTo",
        "position": 4,
        "name": "Smart Contract Development",
        "description": "Build and deploy Aiken smart contracts",
        "totalTime": "PT90M",
        "skillLevel": "Advanced"
      }
    ]
    })}
</script>


# Use Cases
URL: /resources/use-cases

Explore real-world applications built with Mesh SDK on Cardano.

***

title: "Use Cases"
description: "Explore real-world applications built with Mesh SDK on Cardano."
------------------------------------------------------------------------------

import { Card, CardHeader, CardTitle, CardDescription } from '@/components/ui/card';

Discover how developers use Mesh to build production applications on Cardano. From DeFi to NFTs to enterprise solutions, Mesh powers a wide range of blockchain applications.

## DeFi

### Decentralized exchanges

Build trading platforms with Mesh:

| Feature             | Mesh capability               |
| ------------------- | ----------------------------- |
| AMM liquidity pools | Transaction builder for swaps |
| Order book matching | Smart contract integration    |
| Multi-asset swaps   | Native token handling         |
| Wallet connectivity | CIP-30 wallet support         |

### Lending protocols

Create lending and borrowing platforms:

* Collateral locking with smart contracts
* Automated interest calculations
* Liquidation mechanisms
* Multi-party transaction management

### Staking platforms

Build custom staking solutions:

* Stake pool delegation interfaces
* Reward distribution automation
* Multi-pool management
* Delegation tracking

***

## NFTs

### Minting platforms

Mesh simplifies NFT creation:

```typescript
import { MeshTxBuilder } from '@meshsdk/core';

const tx = await txBuilder
  .mint('1', policyId, assetName)
  .mintingScript(mintingScript)
  .txOut(recipientAddress, [
    { unit: policyId + assetName, quantity: '1' },
    { unit: 'lovelace', quantity: '2000000' }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

| Use case            | Mesh features          |
| ------------------- | ---------------------- |
| Single NFT minting  | Transaction builder    |
| Collection launches | Batch minting          |
| Generative art      | Programmatic metadata  |
| Metadata standards  | CIP-25, CIP-68 support |

### Marketplaces

Power NFT trading:

* Listing and delisting
* Auction systems
* Instant purchases
* Royalty distribution

***

## Wallets

### Browser extension wallets

Build full-featured wallets:

| Feature             | Implementation                    |
| ------------------- | --------------------------------- |
| Key management      | `MeshCardanoHeadlessWallet` class |
| Transaction signing | CIP-30 APIs                       |
| dApp connector      | `MeshCardanoBrowserWallet`        |
| Multi-account       | Address derivation                |

### Hardware wallet integration

Support secure signing:

* Ledger device support
* Trezor integration
* Air-gapped signing flows

***

## Gaming

### Blockchain games

Create gaming experiences:

| Feature        | Implementation       |
| -------------- | -------------------- |
| In-game assets | NFT representation   |
| Play-to-earn   | Token rewards        |
| Character NFTs | Tradeable assets     |
| Land ownership | On-chain real estate |

### Virtual worlds

Build metaverse platforms:

* NFT-based land parcels
* Customizable avatars
* In-world economies
* Decentralized identity

***

## Enterprise

### Supply chain

Track products on-chain:

```typescript
// Record product transfer
const tx = await txBuilder
  .txOut(newOwnerAddress, [
    { unit: productNftUnit, quantity: '1' },
    { unit: 'lovelace', quantity: '2000000' }
  ])
  .metadataValue('674', {
    transfer: {
      from: currentOwner,
      to: newOwner,
      timestamp: Date.now(),
      location: 'Warehouse A'
    }
  })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

| Use case                  | Implementation       |
| ------------------------- | -------------------- |
| Asset tracking            | On-chain records     |
| Authenticity verification | NFT provenance       |
| Multi-party workflows     | Smart contracts      |
| Audit trails              | Transaction metadata |

### Identity verification

Build decentralized identity:

* KYC/AML credential storage
* Age verification without birthdate disclosure
* Professional certifications
* Token-gated access control

### Governance

Create voting systems:

* DAO token-weighted voting
* Proposal submission and voting
* Quadratic voting mechanisms
* Verifiable elections

***

## Developer tools

### Block explorers

Build custom blockchain viewers:

* Transaction search and display
* Address monitoring
* Smart contract inspection
* Analytics dashboards

### API services

Create Cardano data platforms:

* Blockchain data providers
* Webhook notifications
* GraphQL/REST APIs
* Historical data archives

***

## Education

### Learning platforms

Build educational tools:

| Feature               | Implementation      |
| --------------------- | ------------------- |
| Interactive tutorials | Code playgrounds    |
| Sandbox environments  | Testnet integration |
| Browser-based coding  | Mesh APIs           |
| Certification         | NFT credentials     |

### Research tools

Enable blockchain research:

* Data extraction and analysis
* Economic simulations
* Smart contract testing
* Network monitoring

***

## Social platforms

### Token-gated communities

Build Web3 social features:

* Access based on token ownership
* Creator monetization
* Tipping systems
* Decentralized social graphs

### Fundraising

Create transparent fundraising:

* Crowdfunding campaigns
* Charity donation tracking
* Investment DAOs
* Grant distribution

***

## Success metrics

Projects built with Mesh have achieved:

| Metric             | Achievement                   |
| ------------------ | ----------------------------- |
| Transaction volume | Millions in daily volume      |
| NFT minting        | Thousands of successful mints |
| User bases         | Tens of thousands of users    |
| Performance        | Sub-second response times     |
| Security           | Zero critical incidents       |

***

## Build your own

Ready to build on Cardano?

| Resource                                       | Purpose                |
| ---------------------------------------------- | ---------------------- |
| [Guides](/guides)                              | Step-by-step tutorials |
| [API Documentation](/apis)                     | Complete reference     |
| [Discord](https://discord.gg/dH48jH3BKa)       | Community support      |
| [Examples](https://github.com/MeshJS/examples) | Working code           |

## Share your project

Built something with Mesh? Share it:

* **Discord** - Join the showcase channel
* **Twitter** - Tag [@meshsdk](https://twitter.com/meshsdk)
* **GitHub** - Add to the [ecosystem list](https://github.com/MeshJS/mesh)

<script type="application/ld+json">
  {JSON.stringify({
    "@context": "https://schema.org",
    "@type": "ItemList",
    "name": "Mesh SDK Use Cases",
    "description": "Real-world applications built with Mesh TypeScript SDK on Cardano",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "item": {
          "@type": "SoftwareSourceCode",
          "name": "DeFi Applications",
          "description": "DEXs, lending protocols, and staking platforms"
        }
      },
      {
        "@type": "ListItem",
        "position": 2,
        "item": {
          "@type": "SoftwareSourceCode",
          "name": "NFT Marketplaces",
          "description": "Minting platforms and secondary marketplaces"
        }
      },
      {
        "@type": "ListItem",
        "position": 3,
        "item": {
          "@type": "SoftwareSourceCode",
          "name": "Wallet Applications",
          "description": "Browser extensions and hardware wallet integrations"
        }
      },
      {
        "@type": "ListItem",
        "position": 4,
        "item": {
          "@type": "SoftwareSourceCode",
          "name": "Gaming & Metaverse",
          "description": "Blockchain games and virtual worlds"
        }
      },
      {
        "@type": "ListItem",
        "position": 5,
        "item": {
          "@type": "SoftwareSourceCode",
          "name": "Enterprise Solutions",
          "description": "Supply chain, identity, and governance systems"
        }
      }
    ]
    })}
</script>


# Blockstream Bitcoin Provider
URL: /providers/bitcoin-blockstream

Fetch Bitcoin chain data and submit transactions via the public Blockstream Esplora API — no API key required.

***

title: "Blockstream Bitcoin Provider"
description: "Fetch Bitcoin chain data and submit transactions via the public Blockstream Esplora API — no API key required."
-----------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://blockstream.info/">Blockstream</Link> operates a public <Link href="https://github.com/Blockstream/esplora/blob/master/API.md">Esplora REST API</Link> for Bitcoin mainnet and testnet. `BlockstreamBitcoinProvider` wraps this API and implements `IBitcoinProvider` from `@meshsdk/provider`, making it a drop-in data source for `BitcoinHeadlessWallet`.

**When to use Blockstream:**

* Development and prototyping — no account or API key required
* Low-to-medium volume production applications
* Testnet development before deploying to mainnet

## Quick Start

```bash
npm install @meshsdk/provider @meshsdk/wallet
```

```ts
import { BlockstreamBitcoinProvider } from "@meshsdk/provider";
import { BitcoinHeadlessWallet } from "@meshsdk/wallet";

const provider = new BlockstreamBitcoinProvider("testnet"); // "mainnet" | "testnet"

const wallet = await BitcoinHeadlessWallet.fromMnemonic({
  network: "Testnet4",
  mnemonic: ["word1", "word2", "..."],
  provider,
});

const balance = await wallet.getBalance();
// { confirmed: "100000", unconfirmed: "0", total: "100000" }
```

## Configuration Options

| Parameter | Type                     | Required | Description                   |
| --------- | ------------------------ | -------- | ----------------------------- |
| `network` | `"mainnet" \| "testnet"` | Yes      | Bitcoin network to connect to |

The base URLs used internally:

| Network     | Base URL                               |
| ----------- | -------------------------------------- |
| `"mainnet"` | `https://blockstream.info/api`         |
| `"testnet"` | `https://blockstream.info/testnet/api` |

## API Reference

### fetchAddressInfo

Retrieve chain and mempool statistics for a Bitcoin address.

```ts
await provider.fetchAddressInfo(address: string): Promise<BitcoinAddressInfo>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `address` | `string` | Yes      | Bitcoin address (bech32, P2PKH, P2SH, etc.) |

**Returns:** `BitcoinAddressInfo` — confirmed and mempool funding/spending counts and sums.

**Example:**

```ts
import { BlockstreamBitcoinProvider } from "@meshsdk/provider";

const provider = new BlockstreamBitcoinProvider("mainnet");

const info = await provider.fetchAddressInfo("bc1q...");

console.log(info.chain_stats.funded_txo_sum);   // total confirmed received (sats)
console.log(info.mempool_stats.funded_txo_sum); // unconfirmed incoming (sats)
```

**Return shape:**

```ts
{
  address: "bc1q...",
  chain_stats: {
    funded_txo_count: 5,
    funded_txo_sum: 500000,
    spent_txo_count: 3,
    spent_txo_sum: 300000,
    tx_count: 8
  },
  mempool_stats: {
    funded_txo_count: 1,
    funded_txo_sum: 50000,
    spent_txo_count: 0,
    spent_txo_sum: 0,
    tx_count: 1
  }
}
```

***

### fetchAddressUTxOs

Retrieve all unspent outputs for a Bitcoin address.

```ts
await provider.fetchAddressUTxOs(address: string): Promise<BitcoinUTxO[]>
```

| Parameter | Type     | Required | Description              |
| --------- | -------- | -------- | ------------------------ |
| `address` | `string` | Yes      | Bitcoin address to query |

**Returns:** Array of `BitcoinUTxO` objects.

**Example:**

```ts
const utxos = await provider.fetchAddressUTxOs("bc1q...");

utxos.forEach((utxo) => {
  console.log(`${utxo.txid}:${utxo.vout} — ${utxo.value} sats`);
});
```

**Return shape:**

```ts
[
  {
    txid: "abc123...",
    vout: 0,
    value: 50000,
    status: {
      confirmed: true,
      block_height: 840000,
      block_hash: "00000000...",
      block_time: 1710000000
    }
  }
]
```

***

### fetchUTxO

Retrieve specific unspent output(s) from a transaction. Filters out already-spent outputs by cross-referencing the outspends endpoint.

```ts
await provider.fetchUTxO(txid: string, vout?: number): Promise<BitcoinUTxO[]>
```

| Parameter | Type     | Required | Description                                                   |
| --------- | -------- | -------- | ------------------------------------------------------------- |
| `txid`    | `string` | Yes      | Transaction ID (64-char hex)                                  |
| `vout`    | `number` | No       | Output index to filter to; omit to return all unspent outputs |

**Example:**

```ts
// All unspent outputs from a transaction
const utxos = await provider.fetchUTxO("abc123...");

// A specific output (only returned if unspent)
const utxo = await provider.fetchUTxO("abc123...", 0);
```

***

### fetchAddressTxs

Retrieve transaction history for a Bitcoin address, sorted newest-first. Supports cursor-based pagination.

```ts
await provider.fetchAddressTxs(
  address: string,
  lastSeenTxid?: string,
): Promise<BitcoinTxInfo[]>
```

| Parameter      | Type     | Required | Description                                                         |
| -------------- | -------- | -------- | ------------------------------------------------------------------- |
| `address`      | `string` | Yes      | Bitcoin address to query                                            |
| `lastSeenTxid` | `string` | No       | Txid of the last transaction seen; fetches the next page of results |

**Example:**

```ts
// First page (most recent 25 transactions)
const txs = await provider.fetchAddressTxs("bc1q...");

// Next page
const moreTxs = await provider.fetchAddressTxs("bc1q...", txs[txs.length - 1].txid);
```

> Blockstream paginates using path-based cursors: `/address/{address}/txs/chain/{lastSeenTxid}`.

***

### fetchTxInfo

Retrieve the confirmation status of a transaction.

```ts
await provider.fetchTxInfo(txid: string): Promise<BitcoinTxStatus>
```

| Parameter | Type     | Required | Description                  |
| --------- | -------- | -------- | ---------------------------- |
| `txid`    | `string` | Yes      | Transaction ID (64-char hex) |

**Returns:** `BitcoinTxStatus` — confirmation status and block details.

**Example:**

```ts
const status = await provider.fetchTxInfo("abc123...");

if (status.confirmed) {
  console.log(`Confirmed at block ${status.block_height}`);
} else {
  console.log("Pending in mempool");
}
```

**Return shape:**

```ts
{
  confirmed: true,
  block_height: 840000,
  block_hash: "00000000...",
  block_time: 1710000000
}
```

***

### fetchFeeEstimates

Retrieve the recommended fee rate (sat/vB) for a target confirmation within `blocks` blocks. Falls back to the next-closest target if an exact match is unavailable; defaults to `2 sat/vB` if the fee API is unreachable.

```ts
await provider.fetchFeeEstimates(blocks: number): Promise<number>
```

| Parameter | Type     | Required | Description                                                |
| --------- | -------- | -------- | ---------------------------------------------------------- |
| `blocks`  | `number` | Yes      | Target confirmation speed in blocks (e.g. `1`, `6`, `144`) |

**Example:**

```ts
const feeRate = await provider.fetchFeeEstimates(6); // next ~1 hour
console.log(`Recommended: ${feeRate} sat/vB`);
```

***

### fetchScriptInfo

Retrieve chain and mempool statistics for a script hash (P2SH / P2WSH).

```ts
await provider.fetchScriptInfo(hash: string): Promise<BitcoinScriptInfo>
```

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `hash`    | `string` | Yes      | Script hash (hex, SHA256 of the script) |

***

### fetchScriptUTxOs

Retrieve unspent outputs locked by a script hash.

```ts
await provider.fetchScriptUTxOs(hash: string): Promise<BitcoinUTxO[]>
```

***

### fetchScriptTxs

Retrieve transaction history for a script hash, with optional pagination.

```ts
await provider.fetchScriptTxs(
  hash: string,
  lastSeenTxid?: string,
): Promise<BitcoinTxInfo[]>
```

***

### submitTx

Broadcast a signed raw transaction to the Bitcoin network.

```ts
await provider.submitTx(txHex: string): Promise<string>
```

| Parameter | Type     | Required | Description                          |
| --------- | -------- | -------- | ------------------------------------ |
| `txHex`   | `string` | Yes      | Signed raw transaction in hex format |

**Returns:** The broadcast transaction ID (64-char hex).

**Example:**

```ts
const txid = await provider.submitTx(signedRawTxHex);
console.log(`Broadcast: ${txid}`);
```

> Blockstream's `/tx` endpoint accepts `text/plain` and returns the txid as plain text on success.

***

## Complete Example

```ts
import { BlockstreamBitcoinProvider } from "@meshsdk/provider";
import { BitcoinHeadlessWallet, AddressPurpose } from "@meshsdk/wallet";

async function sendBitcoin() {
  const provider = new BlockstreamBitcoinProvider("testnet");

  const wallet = await BitcoinHeadlessWallet.fromMnemonic({
    network: "Testnet4",
    mnemonic: ["your", "twelve", "word", "mnemonic", "phrase", "here", "..."],
    provider,
  });

  // Check balance
  const balance = await wallet.getBalance();
  console.log(`Balance: ${balance.total} sats`);

  // Get receive address
  const [address] = await wallet.getAddresses([AddressPurpose.Payment]);
  console.log(`Address: ${address.address}`);

  // Send to a recipient
  const txid = await wallet.signTransfer([
    { address: "tb1q...", amount: 10_000 }, // satoshis
  ]);
  console.log(`Sent: ${txid}`);
}
```

## References

* [Blockstream Esplora API Reference](https://github.com/Blockstream/esplora/blob/master/API.md) - Full endpoint documentation
* [Blockstream Explorer](https://blockstream.info/) - Block explorer powered by the same API

## Related

* <Link href="/providers/bitcoin-maestro">Maestro Bitcoin Provider</Link> - Enterprise-grade alternative with an API key
* <Link href="/apis/wallets/bitcoin/headless-wallet">Bitcoin Headless Wallet</Link> - Use this provider with a self-custodial HD wallet
* <Link href="/providers">All Providers</Link> - Compare with Cardano providers


# Maestro Bitcoin Provider
URL: /providers/bitcoin-maestro

Enterprise-grade Bitcoin chain data and transaction submission via Maestro's Esplora-compatible API.

***

title: "Maestro Bitcoin Provider"
description: "Enterprise-grade Bitcoin chain data and transaction submission via Maestro's Esplora-compatible API."
-------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://www.gomaestro.org/">Maestro</Link> provides enterprise-grade blockchain infrastructure for Bitcoin, Cardano, and Dogecoin. `MaestroBitcoinProvider` targets Maestro's <Link href="https://docs.gomaestro.org/bitcoin">Esplora-compatible Bitcoin API</Link> and implements `IBitcoinProvider` from `@meshsdk/provider`, making it a drop-in data source for `BitcoinHeadlessWallet`.

**When to use Maestro Bitcoin:**

* Production applications requiring higher rate limits and reliability guarantees
* Applications that need mempool monitoring and enterprise SLAs
* Teams already using Maestro for Cardano who want a unified provider

## Quick Start

```bash
npm install @meshsdk/provider @meshsdk/wallet
```

```ts
import { MaestroBitcoinProvider } from "@meshsdk/provider";
import { BitcoinHeadlessWallet } from "@meshsdk/wallet";

const provider = new MaestroBitcoinProvider({
  apiKey: "your-maestro-api-key",
  network: "mainnet", // "mainnet" | "testnet"
});

const wallet = await BitcoinHeadlessWallet.fromMnemonic({
  network: "Mainnet",
  mnemonic: ["word1", "word2", "..."],
  provider,
});

const balance = await wallet.getBalance();
// { confirmed: "100000", unconfirmed: "0", total: "100000" }
```

Get your API key from <Link href="https://docs.gomaestro.org/">Maestro Documentation</Link>.

## Configuration Options

| Parameter | Type                     | Required | Description                   |
| --------- | ------------------------ | -------- | ----------------------------- |
| `apiKey`  | `string`                 | Yes      | Your Maestro API key          |
| `network` | `"mainnet" \| "testnet"` | Yes      | Bitcoin network to connect to |

The base URLs used internally:

| Network     | Base URL                                           |
| ----------- | -------------------------------------------------- |
| `"mainnet"` | `https://xbt-mainnet.gomaestro-api.org/v0/esplora` |
| `"testnet"` | `https://xbt-testnet.gomaestro-api.org/v0/esplora` |

All requests include the `api-key` header automatically.

## API Reference

### fetchAddressInfo

Retrieve chain and mempool statistics for a Bitcoin address.

```ts
await provider.fetchAddressInfo(address: string): Promise<BitcoinAddressInfo>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `address` | `string` | Yes      | Bitcoin address (bech32, P2PKH, P2SH, etc.) |

**Returns:** `BitcoinAddressInfo` — confirmed and mempool funding/spending counts and sums.

**Example:**

```ts
import { MaestroBitcoinProvider } from "@meshsdk/provider";

const provider = new MaestroBitcoinProvider({
  apiKey: "your-maestro-api-key",
  network: "mainnet",
});

const info = await provider.fetchAddressInfo("bc1q...");

console.log(info.chain_stats.funded_txo_sum);   // total confirmed received (sats)
console.log(info.mempool_stats.funded_txo_sum); // unconfirmed incoming (sats)
```

**Return shape:**

```ts
{
  address: "bc1q...",
  chain_stats: {
    funded_txo_count: 5,
    funded_txo_sum: 500000,
    spent_txo_count: 3,
    spent_txo_sum: 300000,
    tx_count: 8
  },
  mempool_stats: {
    funded_txo_count: 1,
    funded_txo_sum: 50000,
    spent_txo_count: 0,
    spent_txo_sum: 0,
    tx_count: 1
  }
}
```

***

### fetchAddressUTxOs

Retrieve all unspent outputs for a Bitcoin address.

```ts
await provider.fetchAddressUTxOs(address: string): Promise<BitcoinUTxO[]>
```

| Parameter | Type     | Required | Description              |
| --------- | -------- | -------- | ------------------------ |
| `address` | `string` | Yes      | Bitcoin address to query |

**Returns:** Array of `BitcoinUTxO` objects.

**Example:**

```ts
const utxos = await provider.fetchAddressUTxOs("bc1q...");

utxos.forEach((utxo) => {
  console.log(`${utxo.txid}:${utxo.vout} — ${utxo.value} sats`);
});
```

**Return shape:**

```ts
[
  {
    txid: "abc123...",
    vout: 0,
    value: 50000,
    status: {
      confirmed: true,
      block_height: 840000,
      block_hash: "00000000...",
      block_time: 1710000000
    }
  }
]
```

***

### fetchUTxO

Retrieve specific unspent output(s) from a transaction. Filters out already-spent outputs by cross-referencing the outspends endpoint.

```ts
await provider.fetchUTxO(txid: string, vout?: number): Promise<BitcoinUTxO[]>
```

| Parameter | Type     | Required | Description                                                   |
| --------- | -------- | -------- | ------------------------------------------------------------- |
| `txid`    | `string` | Yes      | Transaction ID (64-char hex)                                  |
| `vout`    | `number` | No       | Output index to filter to; omit to return all unspent outputs |

**Example:**

```ts
// All unspent outputs from a transaction
const utxos = await provider.fetchUTxO("abc123...");

// A specific output (only returned if unspent)
const utxo = await provider.fetchUTxO("abc123...", 0);
```

***

### fetchAddressTxs

Retrieve transaction history for a Bitcoin address, sorted newest-first. Supports cursor-based pagination.

```ts
await provider.fetchAddressTxs(
  address: string,
  lastSeenTxid?: string,
): Promise<BitcoinTxInfo[]>
```

| Parameter      | Type     | Required | Description                                                         |
| -------------- | -------- | -------- | ------------------------------------------------------------------- |
| `address`      | `string` | Yes      | Bitcoin address to query                                            |
| `lastSeenTxid` | `string` | No       | Txid of the last transaction seen; fetches the next page of results |

**Example:**

```ts
// First page
const txs = await provider.fetchAddressTxs("bc1q...");

// Next page
const moreTxs = await provider.fetchAddressTxs("bc1q...", txs[txs.length - 1].txid);
```

> Maestro paginates using the `after_txid` query parameter (Esplora-compatible): `GET /address/{address}/txs?after_txid={lastSeenTxid}`.

***

### fetchTxInfo

Retrieve the confirmation status of a transaction.

```ts
await provider.fetchTxInfo(txid: string): Promise<BitcoinTxStatus>
```

| Parameter | Type     | Required | Description                  |
| --------- | -------- | -------- | ---------------------------- |
| `txid`    | `string` | Yes      | Transaction ID (64-char hex) |

**Returns:** `BitcoinTxStatus` — confirmation status and block details.

**Example:**

```ts
const status = await provider.fetchTxInfo("abc123...");

if (status.confirmed) {
  console.log(`Confirmed at block ${status.block_height}`);
} else {
  console.log("Pending in mempool");
}
```

**Return shape:**

```ts
{
  confirmed: true,
  block_height: 840000,
  block_hash: "00000000...",
  block_time: 1710000000
}
```

***

### fetchFeeEstimates

Retrieve the recommended fee rate (sat/vB) for a target confirmation within `blocks` blocks. Falls back to the next-closest target if an exact match is unavailable; defaults to `2 sat/vB` if the fee API is unreachable.

```ts
await provider.fetchFeeEstimates(blocks: number): Promise<number>
```

| Parameter | Type     | Required | Description                                                |
| --------- | -------- | -------- | ---------------------------------------------------------- |
| `blocks`  | `number` | Yes      | Target confirmation speed in blocks (e.g. `1`, `6`, `144`) |

**Example:**

```ts
const feeRate = await provider.fetchFeeEstimates(6); // next ~1 hour
console.log(`Recommended: ${feeRate} sat/vB`);
```

***

### fetchScriptInfo

Retrieve chain and mempool statistics for a script hash (P2SH / P2WSH).

```ts
await provider.fetchScriptInfo(hash: string): Promise<BitcoinScriptInfo>
```

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `hash`    | `string` | Yes      | Script hash (hex, SHA256 of the script) |

***

### fetchScriptUTxOs

Retrieve unspent outputs locked by a script hash.

```ts
await provider.fetchScriptUTxOs(hash: string): Promise<BitcoinUTxO[]>
```

***

### fetchScriptTxs

Retrieve transaction history for a script hash, with optional pagination.

```ts
await provider.fetchScriptTxs(
  hash: string,
  lastSeenTxid?: string,
): Promise<BitcoinTxInfo[]>
```

> Uses the `after_txid` query parameter for pagination, consistent with `fetchAddressTxs`.

***

### submitTx

Broadcast a signed raw transaction to the Bitcoin network.

```ts
await provider.submitTx(txHex: string): Promise<string>
```

| Parameter | Type     | Required | Description                          |
| --------- | -------- | -------- | ------------------------------------ |
| `txHex`   | `string` | Yes      | Signed raw transaction in hex format |

**Returns:** The broadcast transaction ID (64-char hex).

**Example:**

```ts
const txid = await provider.submitTx(signedRawTxHex);
console.log(`Broadcast: ${txid}`);
```

> The `api-key` header is included automatically alongside `Content-Type: text/plain`. Maestro returns the txid as plain text on success.

***

## Complete Example

```ts
import { MaestroBitcoinProvider } from "@meshsdk/provider";
import { BitcoinHeadlessWallet, AddressPurpose } from "@meshsdk/wallet";

async function sendBitcoin() {
  const provider = new MaestroBitcoinProvider({
    apiKey: "your-maestro-api-key",
    network: "mainnet",
  });

  const wallet = await BitcoinHeadlessWallet.fromMnemonic({
    network: "Mainnet",
    mnemonic: ["your", "twelve", "word", "mnemonic", "phrase", "here", "..."],
    provider,
  });

  // Check balance
  const balance = await wallet.getBalance();
  console.log(`Balance: ${balance.total} sats`);

  // Get receive address
  const [address] = await wallet.getAddresses([AddressPurpose.Payment]);
  console.log(`Address: ${address.address}`);

  // Send to a recipient
  const txid = await wallet.signTransfer([
    { address: "bc1q...", amount: 10_000 }, // satoshis
  ]);
  console.log(`Sent: ${txid}`);
}
```

## References

* [Maestro Bitcoin API Documentation](https://docs.gomaestro.org/bitcoin) - Official API reference and endpoint documentation
* [Maestro Platform](https://www.gomaestro.org/) - Enterprise blockchain infrastructure for Bitcoin, Cardano, and Dogecoin
* [Blockstream Esplora API](https://github.com/Blockstream/esplora/blob/master/API.md) - The Esplora spec that Maestro's Bitcoin API is compatible with

## Related

* <Link href="/providers/bitcoin-blockstream">Blockstream Bitcoin Provider</Link> - Free alternative, no API key required
* <Link href="/apis/wallets/bitcoin/headless-wallet">Bitcoin Headless Wallet</Link> - Use this provider with a self-custodial HD wallet
* <Link href="/providers/maestro">Maestro Cardano Provider</Link> - Maestro's Cardano provider for the same infrastructure
* <Link href="/providers">All Providers</Link> - Compare all available providers


# Blockfrost Provider
URL: /providers/blockfrost

Connect to Cardano blockchain data through Blockfrost's high-performance API infrastructure.

***

title: "Blockfrost Provider"
description: "Connect to Cardano blockchain data through Blockfrost's high-performance API infrastructure."
-----------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://blockfrost.io/">Blockfrost</Link> provides instant access to Cardano blockchain data through a reliable REST API. Use the Blockfrost provider to fetch UTXOs, submit transactions, query account information, and more, without running your own node.

**When to use Blockfrost:**

* Building production dApps that need reliable blockchain access
* Rapid prototyping without infrastructure setup
* Applications requiring high availability and low latency

## Quick Start

```tsx
import { BlockfrostProvider } from "@meshsdk/core";

// Initialize with your API key from https://blockfrost.io
const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// Fetch UTXOs for an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);
```

Get your free API key at [blockfrost.io](https://blockfrost.io).

## Configuration Options

| Option   | Type     | Description                                           |
| -------- | -------- | ----------------------------------------------------- |
| `apiKey` | `string` | Your Blockfrost API key (required for hosted service) |
| `url`    | `string` | Custom Blockfrost URL for self-hosted instances       |

**Self-hosted Blockfrost:**

```tsx
const provider = new BlockfrostProvider("https://your-blockfrost-instance.com");
```

## API Reference

### fetchAccountInfo

Retrieve staking information for a stake address, including rewards, delegation status, and pool ID.

```tsx
const accountInfo = await provider.fetchAccountInfo(
  "stake_test1uzw5mnt7g4xjgdqkfa80hrk7kdvds6sa4k0vvgjvlj7w8eskffj2n"
);
```

**Returns:**

```tsx
{
  active: true,
  poolId: "pool1...",
  balance: "1000000",
  rewards: "50000",
  withdrawals: "0"
}
```

***

### fetchAddressAssets

Retrieve all native assets held at an address.

```tsx
const assets = await provider.fetchAddressAssets(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);
```

**Returns:**

```tsx
[
  { unit: "lovelace", quantity: "5000000" },
  { unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e", quantity: "1" }
]
```

***

### fetchAddressUTxOs

Retrieve all UTXOs controlled by an address. Optionally filter by a specific asset.

```tsx
// All UTXOs
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// UTXOs containing a specific asset
const filteredUtxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

| Parameter | Type     | Required | Description                                          |
| --------- | -------- | -------- | ---------------------------------------------------- |
| `address` | `string` | Yes      | Bech32 address to query                              |
| `asset`   | `string` | No       | Asset unit (policy ID + asset name hex) to filter by |

***

### fetchAssetAddresses

Find all addresses holding a specific asset.

```tsx
const addresses = await provider.fetchAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchAssetMetadata

Retrieve on-chain metadata for a specific asset.

```tsx
const metadata = await provider.fetchAssetMetadata(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchBlockInfo

Retrieve information about a specific block by its hash.

```tsx
const blockInfo = await provider.fetchBlockInfo(
  "79f60880b097ec7dabb81f75f0b52fedf5e922d4f779a11c0c432dcf22c56089"
);
```

***

### fetchCollectionAssets

Retrieve all assets minted under a policy ID with pagination support.

```tsx
// First page
const { assets, next } = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527"
);

// Next page (if next is not null)
const page2 = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527",
  next
);
```

| Parameter  | Type     | Required | Description                    |
| ---------- | -------- | -------- | ------------------------------ |
| `policyId` | `string` | Yes      | Policy ID of the collection    |
| `cursor`   | `number` | No       | Pagination cursor (default: 1) |

***

### fetchHandleAddress

Resolve an ADA Handle to its associated address.

```tsx
const address = await provider.fetchHandleAddress("meshsdk");
// Returns: "addr_test1qz..."
```

***

### fetchHandle

Retrieve full metadata for a CIP-68 ADA Handle.

```tsx
const handleData = await provider.fetchHandle("meshsdk");
```

***

### fetchProtocolParameters

Retrieve current protocol parameters. Optionally specify an epoch.

```tsx
// Current epoch
const params = await provider.fetchProtocolParameters();

// Specific epoch
const historicalParams = await provider.fetchProtocolParameters(400);
```

***

### fetchTxInfo

Retrieve details of a confirmed transaction.

```tsx
const txInfo = await provider.fetchTxInfo(
  "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
);
```

***

### fetchUTxOs

Retrieve UTXOs for a transaction hash, optionally filtering by output index.

```tsx
// All outputs
const utxos = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70"
);

// Specific output
const singleUtxo = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70",
  0
);
```

***

### fetchGovernanceProposal

Retrieve information about a governance proposal.

```tsx
const proposal = await provider.fetchGovernanceProposal(
  "372d688faa77e146798b581b322c0f2981a9023764736ade5d12e0e4e796af8c",
  0
);
```

***

### evaluateTx

Evaluate execution units for a transaction containing Plutus scripts. Use this to optimize redeemer budgets.

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({ fetcher: provider });

// Build your transaction
const unsignedTx = await txBuilder
  .spendingPlutusScriptV2()
  // ... your transaction details
  .complete();

// Evaluate execution units
const evaluation = await provider.evaluateTx(unsignedTx);
```

**Returns:**

```tsx
[
  {
    index: 0,
    tag: "SPEND",
    budget: {
      mem: 1700,
      steps: 368100
    }
  }
]
```

Use these values to set precise budgets in your redeemer:

```tsx
const redeemer = {
  data: { alternative: 0, fields: [] },
  budget: {
    mem: 1700,
    steps: 368100
  }
};
```

***

### submitTx

Submit a signed transaction to the network.

```tsx
const txHash = await provider.submitTx(signedTx);
```

***

### onTxConfirmed

Subscribe to transaction confirmation events.

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// After submitting a transaction
const txHash = await wallet.submitTx(signedTx);

// Listen for confirmation
provider.onTxConfirmed(txHash, () => {
  console.log("Transaction confirmed!");
  // Update UI, trigger next action, etc.
});
```

***

### get

Make custom requests to any Blockfrost endpoint.

```tsx
const transactions = await provider.get(
  "/addresses/addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9/transactions"
);
```

## Complete Example

```tsx
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Initialize provider
const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// Create wallet instance
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // 0 = testnet, 1 = mainnet
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "mnemonic", "phrase", "..."],
});

// Build transaction
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

// Wait for confirmation
provider.onTxConfirmed(txHash, () => {
  console.log(`Transaction ${txHash} confirmed!`);
});
```

## Troubleshooting

### "Project not found" or 403 error

Your API key is invalid or doesn't have access to the requested network. Verify:

* The key is correct and active at [blockfrost.io/dashboard](https://blockfrost.io/dashboard)
* You're using a key for the correct network (mainnet vs testnet)

### "Rate limit exceeded" (429 error)

You've exceeded the request limit for your plan. Solutions:

* Implement request caching
* Upgrade your Blockfrost plan
* Add request throttling to your application

### "Transaction submit error"

Common causes:

* Insufficient funds (check UTXOs cover amount + fees)
* Invalid transaction structure (missing inputs, outputs, or signatures)
* UTXOs already spent (refresh UTXOs before building)

### Slow response times

* Use `fetchAddressUTxOs` with asset filter when you only need specific assets
* Cache frequently-accessed data like protocol parameters
* Consider self-hosting Blockfrost for high-volume applications

## References

* [Blockfrost API Documentation](https://docs.blockfrost.io/) - Official Blockfrost API reference and endpoint documentation
* [Blockfrost Dashboard](https://blockfrost.io/dashboard) - Manage your API keys and monitor usage
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the transaction model behind UTxO queries

## Related

* <Link href="/providers">All Providers</Link> - Compare Blockfrost with other providers
* <Link href="/apis/txbuilder/basics">Transaction Builder</Link> - Build transactions using Blockfrost
* <Link href="/guides/standalone">Standalone Setup</Link> - Use Blockfrost in Node.js applications


# Hydra Provider (beta)
URL: /providers/hydra

Build high-throughput applications on Cardano's Layer 2 scaling solution

***

title: "Hydra Provider (beta)"
description: "Build high-throughput applications on Cardano's Layer 2 scaling solution"
---------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

The <Link href="https://hydra.family/head-protocol/">Hydra Head protocol</Link> is a Layer 2 scaling solution for Cardano rooted in peer-reviewed research. It increases transaction throughput and ensures cost efficiency while maintaining rigorous security.

**Key features:**

* High transaction throughput with near-instant finality
* Low transaction costs within a Hydra Head
* Full Cardano smart contract compatibility
* Peer-reviewed cryptographic security

**Use Hydra when you need:**

* Real-time transaction settlement
* High-frequency trading or gaming applications
* Micropayments without Layer 1 fees
* Private transaction channels between parties

## Quick Start

Install the MeshJS Hydra package:

```bash
npm install @meshsdk/hydra
```

Initialize the provider:

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});
```

Connect to a Hydra Head and send transactions:

```tsx
// Connect to the Hydra Head
await provider.connect();

// Listen for messages
provider.onMessage((message) => {
  console.log("Hydra message:", message);
});

// Submit a transaction
const txHash = await provider.submitTx(signedTx);
```

## Configuration Options

| Parameter | Type     | Required | Description                 |
| --------- | -------- | -------- | --------------------------- |
| `httpUrl` | `string` | Yes      | The Hydra node HTTP API URL |

### Hydra Node Setup

Before using the HydraProvider, you need a running Hydra node connected to a Hydra Head. See the <Link href="https://hydra.family/head-protocol/docs/getting-started">Hydra Getting Started Guide</Link> for node setup instructions.

## API Reference

### connect

Establish a WebSocket connection to the Hydra Head.

```tsx
await provider.connect(): Promise<void>
```

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();
console.log("Connected to Hydra Head");
```

***

### disconnect

Close the connection to the Hydra Head.

```tsx
await provider.disconnect(timeout?: number): Promise<void>
```

| Parameter | Type     | Required | Description                                           |
| --------- | -------- | -------- | ----------------------------------------------------- |
| `timeout` | `number` | No       | Timeout in milliseconds (default: 300000 / 5 minutes) |

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

// ... do work ...

// Disconnect with default timeout (5 minutes)
await provider.disconnect();

// Or disconnect with custom timeout (10 minutes)
await provider.disconnect(10 * 60 * 1000);
```

***

### onMessage

Listen for messages from the Hydra Head. Use this to receive state updates, transaction confirmations, and other events.

```tsx
provider.onMessage(callback: (message: HydraMessage) => void): void
```

| Parameter  | Type                              | Required | Description                                |
| ---------- | --------------------------------- | -------- | ------------------------------------------ |
| `callback` | `(message: HydraMessage) => void` | Yes      | Function called when a message is received |

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

provider.onMessage((message) => {
  console.log("Message received:", message);

  if (message.tag === "Greetings") {
    console.log("Snapshot UTxOs:", message.snapshotUtxo);
  }

  if (message.tag === "TxValid") {
    console.log("Transaction confirmed:", message.transaction);
  }
});
```

See <Link href="https://hydra.family/head-protocol/api-reference">Hydra API Reference</Link> for all event types.

***

## Hydra Head Commands

### init

Initialize a new Hydra Head. This is a no-op if a Head is already open.

```tsx
await provider.init(): Promise<void>
```

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();
await provider.init();

console.log("Hydra Head initialized");
```

***

### abort

Abort a Head before it is opened. This can only be done before all participants have committed. Once opened, use `close` instead.

```tsx
await provider.abort(): Promise<void>
```

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();
await provider.abort();

console.log("Hydra Head aborted");
```

***

### newTx

Submit a transaction to the Hydra Head. The transaction is broadcast only if well-formed and valid.

```tsx
await provider.newTx(tx: HydraTransaction): Promise<string>
```

| Parameter        | Type     | Required | Description                             |
| ---------------- | -------- | -------- | --------------------------------------- |
| `tx.cborHex`     | `string` | Yes      | The transaction CBOR in hex format      |
| `tx.type`        | `string` | Yes      | Transaction type (e.g., "Tx ConwayEra") |
| `tx.description` | `string` | No       | Optional description                    |

**Returns:** The transaction hash.

**Example:**

```tsx
import { HydraProvider, MeshTxBuilder } from "@meshsdk/hydra";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

// Build a transaction
const wallet = await MeshCardanoHeadlessWallet.fromCliKeys({
  networkId: 0,
  walletAddressType: AddressType.Enterprise,
  fetcher: provider,
  submitter: provider,
  paymentSkey: "58201aae63d93899640e91b51c5e8bd542262df3ecf3246c3854f39c40f4eb83557d",
});

const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  params: await provider.fetchProtocolParameters(),
});

const unsignedTx = await txBuilder
  .txOut("addr_test1vpd5axpq4qsh8sxvzny49cp22gc5tqx0djf6wmjv5cx7q5qyrzuw8", [
    { unit: "lovelace", quantity: "3000000" },
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Submit via newTx
const txHash = await provider.newTx({
  cborHex: unsignedTx,
  type: "Tx ConwayEra",
  description: "Payment transaction",
});

console.log("Transaction submitted:", txHash);
```

***

### decommit

Request to decommit a UTxO from the Head. Upon reaching consensus, the corresponding outputs become available on Layer 1.

```tsx
await provider.decommit(tx: HydraTransaction): Promise<void>
```

| Parameter        | Type     | Required | Description                                 |
| ---------------- | -------- | -------- | ------------------------------------------- |
| `tx.cborHex`     | `string` | Yes      | The decommit transaction CBOR in hex format |
| `tx.type`        | `string` | Yes      | Transaction type (e.g., "Tx ConwayEra")     |
| `tx.description` | `string` | No       | Optional description                        |

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

await provider.decommit({
  cborHex: "<decommit_tx_cbor>",
  type: "Tx ConwayEra",
  description: "Decommit funds to L1",
});
```

***

### close

Close the Head with the latest known snapshot. This moves the Head from Open to Close state and begins the contestation period. No more transactions can be submitted after closing.

```tsx
await provider.close(): Promise<void>
```

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();
await provider.close();

console.log("Hydra Head closed - contestation period started");
```

***

### contest

Challenge the latest snapshot announced during head closure. Participants can only contest once.

```tsx
await provider.contest(): Promise<void>
```

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();
await provider.contest();

console.log("Snapshot contested");
```

***

### fanout

Finalize Head UTxOs to Layer 1 after the contestation period has passed.

```tsx
await provider.fanout(): Promise<void>
```

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();
await provider.fanout();

console.log("Funds returned to Layer 1");
```

***

## Query Methods

### fetchAddressUTxOs

Fetch UTxOs controlled by an address within the Hydra Head.

```tsx
await provider.fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `address` | `string` | Yes      | The wallet address   |
| `asset`   | `string` | No       | Filter by asset unit |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

const utxos = await provider.fetchAddressUTxOs(
  "addr_test1vpsthwvxgfkkm2lm8ggy0c5345u6vrfctmug6tdyx4rf4mqn2xcyw"
);

console.log(`Found ${utxos.length} UTxOs`);
```

***

### fetchUTxOs

Fetch UTxOs by transaction hash within the Hydra Head.

```tsx
await provider.fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `hash`    | `string` | Yes      | The transaction hash  |
| `index`   | `number` | No       | Specific output index |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

const utxos = await provider.fetchUTxOs("txHash");
```

***

### fetchAssetAddresses

Fetch addresses and quantities for a given asset within the Hydra Head.

```tsx
await provider.fetchAssetAddresses(asset: string): Promise<AssetAddress[]>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** Array of addresses and quantities.

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

const holders = await provider.fetchAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchCollectionAssets

Fetch assets for a given policy ID within the Hydra Head.

```tsx
await provider.fetchCollectionAssets(policyId: string): Promise<Asset[]>
```

| Parameter  | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `policyId` | `string` | Yes      | The policy ID |

**Returns:** Array of assets.

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

const assets = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527"
);
```

***

### fetchProtocolParameters

Fetch protocol parameters for the Hydra Head.

```tsx
await provider.fetchProtocolParameters(epoch?: number): Promise<Protocol>
```

| Parameter | Type     | Required | Description               |
| --------- | -------- | -------- | ------------------------- |
| `epoch`   | `number` | No       | Not used in Hydra context |

**Returns:** `Protocol` object with Hydra Head parameters.

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

const params = await provider.fetchProtocolParameters();
console.log("Protocol parameters:", params);
```

***

### submitTx

Submit a signed transaction to the Hydra Head.

```tsx
await provider.submitTx(tx: string): Promise<string>
```

| Parameter | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `tx`      | `string` | Yes      | The signed transaction CBOR hex |

**Returns:** The transaction hash.

**Example:**

```tsx
import { HydraProvider } from "@meshsdk/hydra";

const provider = new HydraProvider({
  httpUrl: "http://123.45.67.890:4001",
});

await provider.connect();

const txHash = await provider.submitTx(signedTx);
console.log("Transaction submitted:", txHash);
```

## Complete Example

```tsx
import { HydraProvider, MeshTxBuilder } from "@meshsdk/hydra";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function hydraPayment() {
  // Initialize provider
  const provider = new HydraProvider({
    httpUrl: "http://123.45.67.890:4001",
  });

  // Connect to Hydra Head
  await provider.connect();

  // Listen for messages
  provider.onMessage((message) => {
    if (message.tag === "TxValid") {
      console.log("Transaction confirmed in Hydra Head!");
    }
  });

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromCliKeys({
    networkId: 0,
    walletAddressType: AddressType.Enterprise,
    fetcher: provider,
    submitter: provider,
    paymentSkey: "58201aae63d93899640e91b51c5e8bd542262df3ecf3246c3854f39c40f4eb83557d",
  });

  // Get protocol parameters and UTxOs
  const params = await provider.fetchProtocolParameters();
  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  // Build transaction
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    params: params,
  });

  const unsignedTx = await txBuilder
    .txOut("addr_test1vpd5axpq4qsh8sxvzny49cp22gc5tqx0djf6wmjv5cx7q5qyrzuw8", [
      { unit: "lovelace", quantity: "3000000" },
    ])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await provider.submitTx(signedTx);

  console.log("Transaction submitted:", txHash);

  // When done, close the head
  // await provider.close();
  // ... wait for contestation period ...
  // await provider.fanout();

  // Disconnect
  await provider.disconnect();
}
```

## Troubleshooting

### Connection Failed

**Problem:** Cannot connect to Hydra node.

**Solution:**

1. Verify the Hydra node is running
2. Check the `httpUrl` is correct (including port)
3. Ensure network connectivity to the Hydra node

### Head Not Open

**Problem:** Commands fail with "Head not open" error.

**Solution:**

1. Initialize the Head with `await provider.init()`
2. Wait for all participants to commit
3. Check Head state via `onMessage` events

### Transaction Rejected

**Problem:** Transactions are rejected by the Hydra Head.

**Solution:**

1. Verify the transaction is well-formed
2. Check that inputs exist in the Hydra Head snapshot
3. Ensure the transaction uses correct protocol parameters from the Head

### Contestation Period

**Problem:** Cannot fanout after closing.

**Solution:**

1. Wait for the contestation period to end
2. The contestation period is configurable when creating the Head
3. Monitor `onMessage` for contestation-related events

### State Synchronization

**Problem:** UTxO queries return stale data.

**Solution:**

1. Listen to `onMessage` for `SnapshotConfirmed` events
2. The `snapshotUtxo` in `Greetings` message contains current state
3. Ensure you're querying after the latest snapshot is confirmed

## Related Links

* <Link href="https://hydra.family/head-protocol/">Hydra Head Protocol</Link>
* <Link href="https://hydra.family/head-protocol/docs/getting-started">Hydra Getting Started</Link>
* <Link href="https://hydra.family/head-protocol/api-reference">Hydra API Reference</Link>
* [MeshJS Transaction Builder](/transaction/basics)
* [MeshJS Wallets](/wallets)


# Blockchain Providers
URL: /providers

Connect to Cardano with Blockfrost, Koios, Ogmios, Maestro, UTxO RPC, and Bitcoin with Blockstream, and more. Unified provider interface for data fetching and transaction submission.

***

title: "Blockchain Providers"
description: "Connect to Cardano with Blockfrost, Koios, Ogmios, Maestro, UTxO RPC, and Bitcoin with Blockstream, and more. Unified provider interface for data fetching and transaction submission."
icon: CloudIcon
---------------

import { linksProviders } from "@/data/links-providers";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

Providers are the bridge between your application and the blockchain. They handle data fetching, transaction submission, and blockchain queries so you can focus on building your application.

## Overview

MeshJS supports multiple blockchain data providers, each with different strengths:

### Cardano Providers

| Provider                                          | Best For             | Key Features                        |
| ------------------------------------------------- | -------------------- | ----------------------------------- |
| [Blockfrost](/providers/blockfrost)               | Production apps      | 100+ APIs, reliable infrastructure  |
| [Koios](/providers/koios)                         | Open-source projects | Free tier, distributed architecture |
| [Maestro](/providers/maestro)                     | DeFi applications    | Enterprise-grade, turbo submit      |
| [UTxORPC](/providers/utxorpc)                     | High performance     | gRPC protocol, minimal overhead     |
| [Ogmios](/providers/ogmios)                       | Self-hosted nodes    | WebSocket API, local deployment     |
| [Yaci](/providers/yaci)                           | Local development    | Custom devnets, fast iteration      |
| [Hydra](/providers/hydra)                         | Layer 2 scaling      | High throughput, low latency        |
| [Offline Fetcher](/providers/offline-fetcher)     | Testing              | No network required, mock data      |
| [Offline Evaluator](/providers/offline-evaluator) | Script testing       | Plutus evaluation, cost analysis    |

### Bitcoin Providers

| Provider                                      | Best For                  | Key Features                         |
| --------------------------------------------- | ------------------------- | ------------------------------------ |
| [Blockstream](/providers/bitcoin-blockstream) | Development & prototyping | No API key, free public Esplora API  |
| [Maestro Bitcoin](/providers/bitcoin-maestro) | Production applications   | Enterprise-grade, higher rate limits |

## Quick Start

Install MeshJS and choose a provider:

```bash
npm install @meshsdk/core
```

Initialize your provider:

```tsx
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
```

Use the provider to fetch blockchain data:

```tsx
// Fetch UTxOs from an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Fetch protocol parameters
const params = await provider.fetchProtocolParameters();

// Submit a transaction
const txHash = await provider.submitTx(signedTx);
```

## Provider Interface

All providers implement a common interface, making them interchangeable:

```tsx
interface IFetcher {
  fetchAccountInfo(address: string): Promise<AccountInfo>;
  fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>;
  fetchAssetAddresses(asset: string): Promise<AssetAddress[]>;
  fetchAssetMetadata(asset: string): Promise<AssetMetadata>;
  fetchBlockInfo(hash: string): Promise<BlockInfo>;
  fetchCollectionAssets(policyId: string, cursor?: number): Promise<CollectionAssets>;
  fetchProtocolParameters(epoch?: number): Promise<Protocol>;
  fetchTxInfo(hash: string): Promise<TransactionInfo>;
  fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>;
}

interface ISubmitter {
  submitTx(tx: string): Promise<string>;
}

interface IEvaluator {
  evaluateTx(tx: string): Promise<Omit<Action, "data">[]>;
}
```

## Choosing a Provider

**For production applications:**

* Use [Blockfrost](/providers/blockfrost) or [Maestro](/providers/maestro) for reliable, managed infrastructure
* Consider [UTxORPC](/providers/utxorpc) if you need maximum performance

**For development and testing:**

* Use [Yaci](/providers/yaci) for local devnets with fast feedback loops
* Use [Offline Fetcher](/providers/offline-fetcher) for unit tests without network dependencies

**For self-hosted infrastructure:**

* Use [Ogmios](/providers/ogmios) to connect directly to your cardano-node
* Use [UTxORPC](/providers/utxorpc) with Dolos for a lightweight alternative

**For Layer 2 applications:**

* Use [Hydra](/providers/hydra) for high-throughput, low-latency transactions

**For Bitcoin applications:**

* Use [Blockstream](/providers/bitcoin-blockstream) for free, zero-config access to mainnet and testnet
* Use [Maestro Bitcoin](/providers/bitcoin-maestro) for enterprise rate limits and production SLAs

## Available Providers

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksProviders.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related Resources

* [Transaction Builder](/transaction/basics) - Build transactions using provider data
* [Wallets](/wallets) - Connect wallets and sign transactions
* [Smart Contracts](/smart-contracts) - Deploy and interact with Plutus scripts


# Koios Provider
URL: /providers/koios

Connect to Cardano using the distributed, open-source Koios API

***

title: "Koios Provider"
description: "Connect to Cardano using the distributed, open-source Koios API"
------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://www.koios.rest/">Koios</Link> is a distributed, open-source public API query layer for Cardano. It provides free access to blockchain data through a network of community-hosted nodes.

**Use Koios when you need:**

* A free tier for development and small projects
* A decentralized, community-driven infrastructure
* Access to comprehensive Cardano blockchain data

## Quick Start

Install the MeshJS package:

```bash
npm install @meshsdk/core
```

Initialize the provider:

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");
```

Fetch blockchain data:

```tsx
// Fetch UTxOs from an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Submit a transaction
const txHash = await provider.submitTx(signedTx);
```

Get your API key from the <Link href="https://koios.rest/Profile.html">Koios User Profile page</Link>.

## Configuration Options

| Parameter | Type                                         | Required | Description                                   |
| --------- | -------------------------------------------- | -------- | --------------------------------------------- |
| `network` | `"api" \| "preview" \| "preprod" \| "guild"` | Yes      | The Cardano network to connect to             |
| `apiKey`  | `string`                                     | No       | Your Koios API key for authenticated requests |

### Network Values

| Network   | Description            |
| --------- | ---------------------- |
| `api`     | Cardano mainnet        |
| `preview` | Preview testnet        |
| `preprod` | Pre-production testnet |
| `guild`   | Guild testnet          |

## API Reference

### get

Fetch data from any Koios API endpoint.

```tsx
await provider.get(endpoint: string): Promise<any>
```

| Parameter  | Type     | Required | Description           |
| ---------- | -------- | -------- | --------------------- |
| `endpoint` | `string` | Yes      | The API endpoint path |

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const transactions = await provider.get(
  "/addresses/addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9/transactions"
);
```

***

### fetchAccountInfo

Retrieve information about a stake account.

```tsx
await provider.fetchAccountInfo(address: string): Promise<AccountInfo>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `address` | `string` | Yes      | The stake address (bech32 format) |

**Returns:** `AccountInfo` object containing balance, rewards, and delegation status.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const accountInfo = await provider.fetchAccountInfo(
  "stake_test1uzw5mnt7g4xjgdqkfa80hrk7kdvds6sa4k0vvgjvlj7w8eskffj2n"
);

console.log(accountInfo.balance);
console.log(accountInfo.rewards);
console.log(accountInfo.poolId);
```

***

### fetchAddressAssets

Fetch all assets held by an address.

```tsx
await provider.fetchAddressAssets(address: string): Promise<Asset[]>
```

| Parameter | Type     | Required | Description                        |
| --------- | -------- | -------- | ---------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format) |

**Returns:** Array of `Asset` objects with `unit` and `quantity`.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const assets = await provider.fetchAddressAssets(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

assets.forEach((asset) => {
  console.log(`${asset.unit}: ${asset.quantity}`);
});
```

***

### fetchAddressUTxOs

Fetch UTxOs controlled by an address, optionally filtered by asset.

```tsx
await provider.fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description                                       |
| --------- | -------- | -------- | ------------------------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format)                |
| `asset`   | `string` | No       | Filter by asset unit (policy ID + asset name hex) |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

// Fetch all UTxOs
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Fetch UTxOs containing a specific asset
const filteredUtxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchAssetAddresses

Fetch all addresses holding a specific asset.

```tsx
await provider.fetchAssetAddresses(asset: string): Promise<AssetAddress[]>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** Array of addresses and quantities.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const holders = await provider.fetchAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

holders.forEach((holder) => {
  console.log(`${holder.address}: ${holder.quantity}`);
});
```

***

### fetchAssetMetadata

Fetch metadata for an asset.

```tsx
await provider.fetchAssetMetadata(asset: string): Promise<AssetMetadata>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** `AssetMetadata` object with name, image, and other metadata fields.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const metadata = await provider.fetchAssetMetadata(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

console.log(metadata.name);
console.log(metadata.image);
```

***

### fetchBlockInfo

Fetch information about a block.

```tsx
await provider.fetchBlockInfo(hash: string): Promise<BlockInfo>
```

| Parameter | Type     | Required | Description    |
| --------- | -------- | -------- | -------------- |
| `hash`    | `string` | Yes      | The block hash |

**Returns:** `BlockInfo` object with block details.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const blockInfo = await provider.fetchBlockInfo(
  "79f60880b097ec7dabb81f75f0b52fedf5e922d4f779a11c0c432dcf22c56089"
);

console.log(blockInfo.slot);
console.log(blockInfo.time);
```

***

### fetchCollectionAssets

Fetch all assets in an NFT collection by policy ID.

```tsx
await provider.fetchCollectionAssets(policyId: string, cursor?: number): Promise<{ assets: Asset[]; next: number | null }>
```

| Parameter  | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `policyId` | `string` | Yes      | The policy ID of the collection |
| `cursor`   | `number` | No       | Pagination cursor (default: 1)  |

**Returns:** Object with `assets` array and `next` cursor for pagination.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

// Fetch first page
const result = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527"
);

console.log(result.assets);

// Fetch next page if available
if (result.next) {
  const nextPage = await provider.fetchCollectionAssets(
    "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527",
    result.next
  );
}
```

***

### fetchHandleAddress

Resolve an ADA Handle to its associated address.

```tsx
await provider.fetchHandleAddress(handle: string): Promise<string>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** The resolved Cardano address.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("api", "<YOUR_API_KEY>");

const address = await provider.fetchHandleAddress("meshsdk");
console.log(address);
```

<Link href="https://handle.me/">ADA Handle</Link> allows users to associate human-readable names with Cardano addresses. Each handle is a unique NFT on the blockchain.

***

### fetchHandle

Fetch CIP-68 handle metadata.

```tsx
await provider.fetchHandle(handle: string): Promise<HandleMetadata>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** Handle metadata including CIP-68 fields.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("api", "<YOUR_API_KEY>");

const handleData = await provider.fetchHandle("meshsdk");
console.log(handleData);
```

***

### fetchProtocolParameters

Fetch the current protocol parameters.

```tsx
await provider.fetchProtocolParameters(epoch?: number): Promise<Protocol>
```

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `epoch`   | `number` | No       | Specific epoch (default: current epoch) |

**Returns:** `Protocol` object with all protocol parameters.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

// Fetch current parameters
const params = await provider.fetchProtocolParameters();

console.log(params.minFeeA);
console.log(params.minFeeB);
console.log(params.maxTxSize);
```

***

### fetchTxInfo

Fetch information about a confirmed transaction.

```tsx
await provider.fetchTxInfo(hash: string): Promise<TransactionInfo>
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `hash`    | `string` | Yes      | The transaction hash |

**Returns:** `TransactionInfo` object with transaction details.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const txInfo = await provider.fetchTxInfo(
  "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
);

console.log(txInfo.block);
console.log(txInfo.fees);
```

***

### fetchUTxOs

Fetch UTxOs by transaction hash.

```tsx
await provider.fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `hash`    | `string` | Yes      | The transaction hash  |
| `index`   | `number` | No       | Specific output index |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

// Fetch all UTxOs from a transaction
const utxos = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70"
);

// Fetch specific output
const specificUtxo = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70",
  0
);
```

***

### fetchGovernanceProposal

Fetch information about a governance proposal.

```tsx
await provider.fetchGovernanceProposal(txHash: string, certIndex: number): Promise<ProposalInfo>
```

| Parameter   | Type     | Required | Description                   |
| ----------- | -------- | -------- | ----------------------------- |
| `txHash`    | `string` | Yes      | The proposal transaction hash |
| `certIndex` | `number` | Yes      | The certificate index         |

**Returns:** `ProposalInfo` object with proposal details.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const proposal = await provider.fetchGovernanceProposal(
  "372d688faa77e146798b581b322c0f2981a9023764736ade5d12e0e4e796af8c",
  0
);
```

***

### submitTx

Submit a signed transaction to the network.

```tsx
await provider.submitTx(tx: string): Promise<string>
```

| Parameter | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `tx`      | `string` | Yes      | The signed transaction CBOR hex |

**Returns:** The transaction hash.

**Example:**

```tsx
import { KoiosProvider } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

const txHash = await provider.submitTx(signedTx);
console.log(`Transaction submitted: ${txHash}`);
```

***

### onTxConfirmed

Listen for transaction confirmation.

```tsx
provider.onTxConfirmed(txHash: string, callback: () => void, limit?: number): void
```

| Parameter  | Type         | Required | Description                     |
| ---------- | ------------ | -------- | ------------------------------- |
| `txHash`   | `string`     | Yes      | The transaction hash to monitor |
| `callback` | `() => void` | Yes      | Function called when confirmed  |
| `limit`    | `number`     | No       | Maximum confirmation checks     |

**Example:**

```tsx
import { KoiosProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

// Build and submit transaction
const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .txOut("addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr", [
    { unit: "lovelace", quantity: "5000000" },
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await provider.submitTx(signedTx);

// Wait for confirmation
provider.onTxConfirmed(txHash, () => {
  console.log("Transaction confirmed!");
});
```

## Complete Example

```tsx
import { KoiosProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function sendAda() {
  // Initialize provider
  const provider = new KoiosProvider("preprod", "<YOUR_API_KEY>");

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: ["your", "mnemonic", "phrase", "..."],
  });

  // Get wallet data
  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  // Build transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .txOut("addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9", [
      { unit: "lovelace", quantity: "5000000" },
    ])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await provider.submitTx(signedTx);

  console.log(`Transaction submitted: ${txHash}`);

  // Wait for confirmation
  provider.onTxConfirmed(txHash, () => {
    console.log("Transaction confirmed!");
  });
}
```

## Troubleshooting

### API Key Issues

**Problem:** Requests return 401 Unauthorized.

**Solution:** Verify your API key is correct and active. Get a new key from the <Link href="https://koios.rest/Profile.html">Koios Profile page</Link>.

### Rate Limiting

**Problem:** Requests fail with 429 Too Many Requests.

**Solution:** Koios has rate limits on API calls. Implement retry logic with exponential backoff, or upgrade to a paid tier for higher limits.

### Network Mismatch

**Problem:** Addresses or transactions not found.

**Solution:** Ensure your provider network matches your addresses. Mainnet addresses start with `addr1`, testnet addresses start with `addr_test1`.

### Empty UTxO Response

**Problem:** `fetchAddressUTxOs` returns empty array.

**Solution:** Verify the address has funds and is on the correct network. Check the address on a block explorer.

## References

* [Koios REST API](https://www.koios.rest/) - Official Koios service documentation and API reference
* [Koios API Endpoints](https://api.koios.rest/) - Interactive API documentation for all Koios endpoints
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the transaction model behind UTxO queries

## Related Links

* <Link href="https://www.koios.rest/">Koios Website</Link>
* <Link href="https://api.koios.rest/">Koios API Documentation</Link>
* <Link href="https://koios.rest/Profile.html">Get API Key</Link>
* <Link href="/apis/txbuilder/basics">Transaction Builder</Link>
* <Link href="/apis/wallets">Wallets</Link>


# Maestro Provider
URL: /providers/maestro

Connect to Cardano using Maestro's enterprise-grade blockchain infrastructure

***

title: "Maestro Provider"
description: "Connect to Cardano using Maestro's enterprise-grade blockchain infrastructure"
--------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://www.gomaestro.org/">Maestro</Link> provides enterprise-grade blockchain infrastructure for Cardano, Bitcoin, and Dogecoin. It offers advanced UTxO indexing, transaction monitoring, and smart contract APIs.

**Key features:**

* Enterprise-grade onchain data access
* Transaction monitoring with submission retries and rollback notifications
* Turbo transaction submission for accelerated finality
* High-fidelity smart contract data feeds
* Fully managed smart contract APIs

**Use Maestro when you need:**

* Production-ready infrastructure for DeFi applications
* Faster transaction finality with turbo submit
* Real-time transaction monitoring and notifications
* Enterprise support and SLAs

## Quick Start

Install the MeshJS package:

```bash
npm install @meshsdk/core
```

Initialize the provider:

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});
```

Fetch blockchain data:

```tsx
// Fetch UTxOs from an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Submit a transaction
const txHash = await provider.submitTx(signedTx);
```

Get your API key from <Link href="https://docs.gomaestro.org/">Maestro Documentation</Link>.

## Configuration Options

| Parameter     | Type                                  | Required | Description                                          |
| ------------- | ------------------------------------- | -------- | ---------------------------------------------------- |
| `network`     | `"Mainnet" \| "Preprod" \| "Preview"` | Yes      | The Cardano network to connect to                    |
| `apiKey`      | `string`                              | Yes      | Your Maestro API key                                 |
| `turboSubmit` | `boolean`                             | No       | Enable turbo transaction submission (default: false) |

### Turbo Submit

Turbo submit accelerates transaction finality by using Maestro's optimized submission infrastructure. This is a paid feature - read more at <Link href="https://docs.gomaestro.org">Maestro Documentation</Link>.

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Mainnet",
  apiKey: "<YOUR_API_KEY>",
  turboSubmit: true,
});
```

## API Reference

### get

Fetch data from any Maestro API endpoint.

```tsx
await provider.get(endpoint: string): Promise<any>
```

| Parameter  | Type     | Required | Description           |
| ---------- | -------- | -------- | --------------------- |
| `endpoint` | `string` | Yes      | The API endpoint path |

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const transactions = await provider.get(
  "/addresses/addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9/transactions"
);
```

***

### fetchAccountInfo

Retrieve information about a stake account.

```tsx
await provider.fetchAccountInfo(address: string): Promise<AccountInfo>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `address` | `string` | Yes      | The stake address (bech32 format) |

**Returns:** `AccountInfo` object containing balance, rewards, and delegation status.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const accountInfo = await provider.fetchAccountInfo(
  "stake_test1uzw5mnt7g4xjgdqkfa80hrk7kdvds6sa4k0vvgjvlj7w8eskffj2n"
);

console.log(accountInfo.balance);
console.log(accountInfo.rewards);
```

***

### fetchAddressAssets

Fetch all assets held by an address.

```tsx
await provider.fetchAddressAssets(address: string): Promise<Asset[]>
```

| Parameter | Type     | Required | Description                        |
| --------- | -------- | -------- | ---------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format) |

**Returns:** Array of `Asset` objects with `unit` and `quantity`.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const assets = await provider.fetchAddressAssets(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

assets.forEach((asset) => {
  console.log(`${asset.unit}: ${asset.quantity}`);
});
```

***

### fetchAddressUTxOs

Fetch UTxOs controlled by an address, optionally filtered by asset.

```tsx
await provider.fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description                                       |
| --------- | -------- | -------- | ------------------------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format)                |
| `asset`   | `string` | No       | Filter by asset unit (policy ID + asset name hex) |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

// Fetch all UTxOs
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Fetch UTxOs containing a specific asset
const filteredUtxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchAssetAddresses

Fetch all addresses holding a specific asset.

```tsx
await provider.fetchAssetAddresses(asset: string): Promise<AssetAddress[]>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** Array of addresses and quantities.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const holders = await provider.fetchAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

holders.forEach((holder) => {
  console.log(`${holder.address}: ${holder.quantity}`);
});
```

***

### fetchAssetMetadata

Fetch metadata for an asset.

```tsx
await provider.fetchAssetMetadata(asset: string): Promise<AssetMetadata>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** `AssetMetadata` object with name, image, and other metadata fields.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const metadata = await provider.fetchAssetMetadata(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

console.log(metadata.name);
console.log(metadata.image);
```

***

### fetchBlockInfo

Fetch information about a block.

```tsx
await provider.fetchBlockInfo(hash: string): Promise<BlockInfo>
```

| Parameter | Type     | Required | Description    |
| --------- | -------- | -------- | -------------- |
| `hash`    | `string` | Yes      | The block hash |

**Returns:** `BlockInfo` object with block details.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const blockInfo = await provider.fetchBlockInfo(
  "79f60880b097ec7dabb81f75f0b52fedf5e922d4f779a11c0c432dcf22c56089"
);

console.log(blockInfo.slot);
console.log(blockInfo.time);
```

***

### fetchCollectionAssets

Fetch all assets in an NFT collection by policy ID.

```tsx
await provider.fetchCollectionAssets(policyId: string, cursor?: number): Promise<{ assets: Asset[]; next: number | null }>
```

| Parameter  | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `policyId` | `string` | Yes      | The policy ID of the collection |
| `cursor`   | `number` | No       | Pagination cursor (default: 1)  |

**Returns:** Object with `assets` array and `next` cursor for pagination.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

// Fetch first page
const result = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527"
);

console.log(result.assets);

// Fetch next page if available
if (result.next) {
  const nextPage = await provider.fetchCollectionAssets(
    "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527",
    result.next
  );
}
```

***

### fetchHandleAddress

Resolve an ADA Handle to its associated address.

```tsx
await provider.fetchHandleAddress(handle: string): Promise<string>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** The resolved Cardano address.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Mainnet",
  apiKey: "<YOUR_API_KEY>",
});

const address = await provider.fetchHandleAddress("meshsdk");
console.log(address);
```

***

### fetchHandle

Fetch CIP-68 handle metadata.

```tsx
await provider.fetchHandle(handle: string): Promise<HandleMetadata>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** Handle metadata including CIP-68 fields.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Mainnet",
  apiKey: "<YOUR_API_KEY>",
});

const handleData = await provider.fetchHandle("meshsdk");
console.log(handleData);
```

***

### fetchProtocolParameters

Fetch the current protocol parameters.

```tsx
await provider.fetchProtocolParameters(epoch?: number): Promise<Protocol>
```

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `epoch`   | `number` | No       | Specific epoch (default: current epoch) |

**Returns:** `Protocol` object with all protocol parameters.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const params = await provider.fetchProtocolParameters();

console.log(params.minFeeA);
console.log(params.minFeeB);
console.log(params.maxTxSize);
```

***

### fetchTxInfo

Fetch information about a confirmed transaction.

```tsx
await provider.fetchTxInfo(hash: string): Promise<TransactionInfo>
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `hash`    | `string` | Yes      | The transaction hash |

**Returns:** `TransactionInfo` object with transaction details.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const txInfo = await provider.fetchTxInfo(
  "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
);

console.log(txInfo.block);
console.log(txInfo.fees);
```

***

### fetchUTxOs

Fetch UTxOs by transaction hash.

```tsx
await provider.fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `hash`    | `string` | Yes      | The transaction hash  |
| `index`   | `number` | No       | Specific output index |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

// Fetch all UTxOs from a transaction
const utxos = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70"
);

// Fetch specific output
const specificUtxo = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70",
  0
);
```

***

### fetchGovernanceProposal

Fetch information about a governance proposal.

```tsx
await provider.fetchGovernanceProposal(txHash: string, certIndex: number): Promise<ProposalInfo>
```

| Parameter   | Type     | Required | Description                   |
| ----------- | -------- | -------- | ----------------------------- |
| `txHash`    | `string` | Yes      | The proposal transaction hash |
| `certIndex` | `number` | Yes      | The certificate index         |

**Returns:** `ProposalInfo` object with proposal details.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const proposal = await provider.fetchGovernanceProposal(
  "372d688faa77e146798b581b322c0f2981a9023764736ade5d12e0e4e796af8c",
  0
);
```

***

### evaluateTx

Evaluate a transaction to determine script execution costs.

```tsx
await provider.evaluateTx(tx: string): Promise<Omit<Action, "data">[]>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `tx`      | `string` | Yes      | The unsigned transaction CBOR hex |

**Returns:** Array of execution cost estimates for each script.

**Example:**

```tsx
import { MaestroProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const txBuilder = new MeshTxBuilder({ fetcher: provider });

// Build a transaction that interacts with a smart contract
const unsignedTx = await txBuilder
  // ... transaction building code
  .complete();

// Evaluate to get execution costs
const evaluation = await provider.evaluateTx(unsignedTx);

console.log(evaluation);
// [
//   {
//     index: 0,
//     tag: "SPEND",
//     budget: {
//       mem: 1700,
//       steps: 368100
//     }
//   }
// ]
```

Use the evaluation results to set precise redeemer budgets:

```tsx
const redeemer = {
  data: { alternative: 0, fields: [...] },
  budget: {
    mem: evaluation[0].budget.mem,
    steps: evaluation[0].budget.steps,
  },
};
```

***

### submitTx

Submit a signed transaction to the network.

```tsx
await provider.submitTx(tx: string): Promise<string>
```

| Parameter | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `tx`      | `string` | Yes      | The signed transaction CBOR hex |

**Returns:** The transaction hash.

**Example:**

```tsx
import { MaestroProvider } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const txHash = await provider.submitTx(signedTx);
console.log(`Transaction submitted: ${txHash}`);
```

***

### onTxConfirmed

Listen for transaction confirmation.

```tsx
provider.onTxConfirmed(txHash: string, callback: () => void, limit?: number): void
```

| Parameter  | Type         | Required | Description                     |
| ---------- | ------------ | -------- | ------------------------------- |
| `txHash`   | `string`     | Yes      | The transaction hash to monitor |
| `callback` | `() => void` | Yes      | Function called when confirmed  |
| `limit`    | `number`     | No       | Maximum confirmation checks     |

**Example:**

```tsx
import { MaestroProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new MaestroProvider({
  network: "Preprod",
  apiKey: "<YOUR_API_KEY>",
});

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .txOut("addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr", [
    { unit: "lovelace", quantity: "5000000" },
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await provider.submitTx(signedTx);

provider.onTxConfirmed(txHash, () => {
  console.log("Transaction confirmed!");
});
```

## Complete Example

```tsx
import { MaestroProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function sendAda() {
  // Initialize provider with turbo submit
  const provider = new MaestroProvider({
    network: "Preprod",
    apiKey: "<YOUR_API_KEY>",
    turboSubmit: true,
  });

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: ["your", "mnemonic", "phrase", "..."],
  });

  // Get wallet data
  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  // Build transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .txOut("addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9", [
      { unit: "lovelace", quantity: "5000000" },
    ])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await provider.submitTx(signedTx);

  console.log(`Transaction submitted: ${txHash}`);

  // Wait for confirmation
  provider.onTxConfirmed(txHash, () => {
    console.log("Transaction confirmed!");
  });
}
```

## Troubleshooting

### API Key Issues

**Problem:** Requests return 401 Unauthorized.

**Solution:** Verify your API key is valid and has not expired. Get a new key from <Link href="https://docs.gomaestro.org/">Maestro Dashboard</Link>.

### Rate Limiting

**Problem:** Requests fail with 429 Too Many Requests.

**Solution:** Maestro has rate limits based on your plan. Implement retry logic with exponential backoff, or upgrade your plan for higher limits.

### Turbo Submit Not Working

**Problem:** Transactions still take normal time despite `turboSubmit: true`.

**Solution:** Turbo submit is a paid feature. Ensure your Maestro plan includes turbo submit access.

### Network Configuration

**Problem:** Addresses or transactions not found.

**Solution:** Ensure the `network` parameter matches your addresses. Use "Mainnet" for `addr1` addresses and "Preprod" or "Preview" for `addr_test1` addresses.

### Script Evaluation Failures

**Problem:** `evaluateTx` returns errors.

**Solution:** Ensure all required UTxOs are available and the transaction is well-formed. The transaction must include script inputs for evaluation.

## References

* [Maestro API Documentation](https://docs.gomaestro.org/) - Official Maestro API reference, tutorials, and quickstart guides
* [Maestro Platform](https://www.gomaestro.org/) - Enterprise-grade blockchain infrastructure for Cardano
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the transaction model for smart contract evaluation

## Related Links

* <Link href="https://www.gomaestro.org/">Maestro Website</Link>
* <Link href="https://docs.gomaestro.org/">Maestro Documentation</Link>
* <Link href="https://docs.gomaestro.org/getting-started">Get API Key</Link>
* <Link href="/apis/txbuilder/basics">Transaction Builder</Link>
* <Link href="/smart-contracts">Smart Contracts</Link>


# Offline Evaluator
URL: /providers/offline-evaluator

Evaluate Plutus script execution costs without network connectivity

***

title: "Offline Evaluator"
description: "Evaluate Plutus script execution costs without network connectivity"
----------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

The OfflineEvaluator calculates execution costs (memory and CPU steps) for Plutus scripts in transactions without requiring network connectivity. It works with an <Link href="/providers/offline-fetcher">OfflineFetcher</Link> to resolve the UTxOs needed for script validation.

**Use OfflineEvaluator when you need:**

* Unit testing smart contracts without network access
* Validating script execution costs in CI/CD pipelines
* Offline development of Plutus scripts
* Reproducible cost analysis for budgeting

The evaluator is also compatible with online fetchers, enabling hybrid workflows where data comes from the network but evaluation happens locally.

## Quick Start

Install the required packages:

```bash
npm install @meshsdk/core @meshsdk/core-csl
```

Create and use the evaluator:

```tsx
import { OfflineEvaluator } from "@meshsdk/core-csl";
import { OfflineFetcher } from "@meshsdk/core";

// Create fetcher and add required UTxOs
const fetcher = new OfflineFetcher();
fetcher.addUTxOs([
  {
    input: {
      txHash: "abc123...",
      outputIndex: 0,
    },
    output: {
      address: "addr_test1...",
      amount: [{ unit: "lovelace", quantity: "10000000" }],
      scriptHash: "def456...",
    },
  },
]);

// Create evaluator
const evaluator = new OfflineEvaluator(fetcher, "preprod");

// Evaluate a transaction
const costs = await evaluator.evaluateTx(transactionCbor);
console.log(costs);
```

## Configuration Options

| Parameter | Type       | Required | Description                                          |
| --------- | ---------- | -------- | ---------------------------------------------------- |
| `fetcher` | `IFetcher` | Yes      | Data fetcher for resolving UTxOs                     |
| `network` | `string`   | Yes      | Network identifier ("mainnet", "preprod", "preview") |

**Example:**

```tsx
import { OfflineEvaluator } from "@meshsdk/core-csl";
import { OfflineFetcher, BlockfrostProvider } from "@meshsdk/core";

// With OfflineFetcher (fully offline)
const offlineFetcher = new OfflineFetcher();
const offlineEvaluator = new OfflineEvaluator(offlineFetcher, "preprod");

// With online fetcher (hybrid mode)
const onlineFetcher = new BlockfrostProvider("<API_KEY>");
const hybridEvaluator = new OfflineEvaluator(onlineFetcher, "preprod");
```

## API Reference

### evaluateTx

Evaluate Plutus script execution in a transaction.

```tsx
await evaluator.evaluateTx(tx: string): Promise<Omit<Action, "data">[]>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `tx`      | `string` | Yes      | The unsigned transaction CBOR hex |

**Returns:** Array of execution cost estimates for each script action.

**Example:**

```tsx
import { OfflineEvaluator } from "@meshsdk/core-csl";
import { OfflineFetcher, MeshTxBuilder } from "@meshsdk/core";

// Set up fetcher with required data
const fetcher = new OfflineFetcher();
fetcher.addUTxOs([
  {
    input: {
      txHash: "5de23a2...",
      outputIndex: 0,
    },
    output: {
      address: "addr_test1...",
      amount: [{ unit: "lovelace", quantity: "10000000" }],
      scriptHash: "32b7e3d...",
      plutusData: "d8799f...",
    },
  },
]);

fetcher.addProtocolParameters({
  // ... protocol parameters
});

// Create evaluator
const evaluator = new OfflineEvaluator(fetcher, "preprod");

// Build a transaction
const txBuilder = new MeshTxBuilder({ fetcher: fetcher });
const unsignedTx = await txBuilder
  .spendingPlutusScript("V3")
  .txIn("5de23a2...", 0)
  .txInInlineDatumPresent()
  .txInRedeemerValue({ alternative: 0, fields: [] })
  .txInScript(scriptCbor)
  .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress("addr_test1...")
  .complete();

// Evaluate
const costs = await evaluator.evaluateTx(unsignedTx);

console.log(costs);
// [
//   {
//     index: 0,
//     tag: "SPEND",
//     budget: {
//       mem: 508703,
//       steps: 164980381
//     }
//   }
// ]
```

**Response structure:**

| Field          | Type                                      | Description                           |
| -------------- | ----------------------------------------- | ------------------------------------- |
| `index`        | `number`                                  | The redeemer index in the transaction |
| `tag`          | `"SPEND" \| "MINT" \| "CERT" \| "REWARD"` | The type of script action             |
| `budget.mem`   | `number`                                  | Memory units required                 |
| `budget.steps` | `number`                                  | CPU steps required                    |

## Using Evaluation Results

After evaluating a transaction, use the results to set precise redeemer budgets:

```tsx
import { OfflineEvaluator } from "@meshsdk/core-csl";
import { OfflineFetcher, MeshTxBuilder } from "@meshsdk/core";

const fetcher = new OfflineFetcher();
// ... add UTxOs and protocol parameters

const evaluator = new OfflineEvaluator(fetcher, "preprod");

// First pass: build with placeholder budget
const txBuilder = new MeshTxBuilder({ fetcher: fetcher });
const unsignedTx = await txBuilder
  .spendingPlutusScript("V3")
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue({ alternative: 0, fields: [] })
  .txInScript(scriptCbor)
  .txOut(recipient, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .complete();

// Evaluate to get actual costs
const evaluation = await evaluator.evaluateTx(unsignedTx);

// Second pass: build with precise budget
const preciseTxBuilder = new MeshTxBuilder({ fetcher: fetcher });
const preciseTx = await preciseTxBuilder
  .spendingPlutusScript("V3")
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(
    { alternative: 0, fields: [] },
    undefined,
    {
      mem: evaluation[0].budget.mem,
      steps: evaluation[0].budget.steps,
    }
  )
  .txInScript(scriptCbor)
  .txOut(recipient, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .complete();
```

## Testing with OfflineEvaluator

The evaluator is particularly useful for testing Plutus scripts:

```tsx
import { OfflineEvaluator } from "@meshsdk/core-csl";
import { OfflineFetcher, MeshTxBuilder } from "@meshsdk/core";
import { describe, it, expect, beforeEach } from "vitest";

describe("MyPlutusScript", () => {
  let evaluator: OfflineEvaluator;
  let fetcher: OfflineFetcher;

  beforeEach(() => {
    fetcher = new OfflineFetcher();
    evaluator = new OfflineEvaluator(fetcher, "preprod");

    // Set up test UTxOs
    fetcher.addUTxOs([
      {
        input: { txHash: "test123...", outputIndex: 0 },
        output: {
          address: "addr_test1...",
          amount: [{ unit: "lovelace", quantity: "10000000" }],
          scriptHash: "script123...",
          plutusData: "d8799f...",
        },
      },
    ]);

    fetcher.addProtocolParameters({
      // ... protocol parameters
    });
  });

  it("should evaluate minting policy", async () => {
    const txBuilder = new MeshTxBuilder({ fetcher: fetcher });
    const unsignedTx = await txBuilder
      .mintPlutusScript("V3")
      // ... build minting transaction
      .complete();

    const result = await evaluator.evaluateTx(unsignedTx);

    expect(result[0].tag).toBe("MINT");
    expect(result[0].budget.mem).toBeLessThan(600000);
    expect(result[0].budget.steps).toBeLessThan(200000000);
  });

  it("should evaluate spending validator", async () => {
    const txBuilder = new MeshTxBuilder({ fetcher: fetcher });
    const unsignedTx = await txBuilder
      .spendingPlutusScript("V3")
      // ... build spending transaction
      .complete();

    const result = await evaluator.evaluateTx(unsignedTx);

    expect(result[0].tag).toBe("SPEND");
    expect(result[0].budget.mem).toBeDefined();
    expect(result[0].budget.steps).toBeDefined();
  });

  it("should fail for invalid redeemer", async () => {
    const txBuilder = new MeshTxBuilder({ fetcher: fetcher });
    const unsignedTx = await txBuilder
      .spendingPlutusScript("V3")
      .txInRedeemerValue({ alternative: 99, fields: [] }) // Invalid redeemer
      // ... rest of transaction
      .complete();

    await expect(evaluator.evaluateTx(unsignedTx)).rejects.toThrow();
  });
});
```

## Complete Example

```tsx
import { OfflineEvaluator } from "@meshsdk/core-csl";
import { OfflineFetcher, MeshTxBuilder } from "@meshsdk/core";

async function evaluateSmartContract() {
  // Create fetcher with test data
  const fetcher = new OfflineFetcher("preprod");

  // Add protocol parameters
  fetcher.addProtocolParameters({
    epoch: 290,
    minFeeA: 44,
    minFeeB: 155381,
    maxBlockSize: 73728,
    maxTxSize: 16384,
    maxBlockHeaderSize: 1100,
    keyDeposit: 2000000,
    poolDeposit: 500000000,
    minPoolCost: "340000000",
    priceMem: 0.0577,
    priceStep: 0.0000721,
    maxValSize: 5000,
    collateralPercent: 150,
    maxCollateralInputs: 3,
    coinsPerUtxoSize: "4310",
  });

  // Add script UTxO
  fetcher.addUTxOs([
    {
      input: {
        txHash: "5de23a2f1c5e8b9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f",
        outputIndex: 0,
      },
      output: {
        address: "addr_test1wz5qc7fk2pat0058w4zwvkw35ythyrfx4pd3z6h6z3jhdtqhmd6rh",
        amount: [{ unit: "lovelace", quantity: "10000000" }],
        scriptHash: "32b7e3d9b8c5f4a1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c6b7a8f9e0d1c2b3a4f5",
        plutusData: "d8799f00ff",
      },
    },
    // Add collateral UTxO
    {
      input: {
        txHash: "abc123def456789abc123def456789abc123def456789abc123def456789abc1",
        outputIndex: 0,
      },
      output: {
        address: "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
        amount: [{ unit: "lovelace", quantity: "50000000" }],
      },
    },
  ]);

  // Create evaluator
  const evaluator = new OfflineEvaluator(fetcher, "preprod");

  // Build transaction
  const txBuilder = new MeshTxBuilder({ fetcher: fetcher });

  const scriptCbor = "82015820..."; // Your script CBOR

  const unsignedTx = await txBuilder
    .spendingPlutusScript("V3")
    .txIn(
      "5de23a2f1c5e8b9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f",
      0
    )
    .txInInlineDatumPresent()
    .txInRedeemerValue({ alternative: 0, fields: [] })
    .txInScript(scriptCbor)
    .txOut(
      "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
      [{ unit: "lovelace", quantity: "5000000" }]
    )
    .txInCollateral(
      "abc123def456789abc123def456789abc123def456789abc123def456789abc1",
      0
    )
    .changeAddress(
      "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
    )
    .complete();

  // Evaluate
  try {
    const costs = await evaluator.evaluateTx(unsignedTx);

    console.log("Evaluation results:");
    costs.forEach((cost, i) => {
      console.log(`  Action ${i}:`);
      console.log(`    Type: ${cost.tag}`);
      console.log(`    Index: ${cost.index}`);
      console.log(`    Memory: ${cost.budget.mem} units`);
      console.log(`    CPU: ${cost.budget.steps} steps`);
    });
  } catch (error) {
    console.error("Evaluation failed:", error);
  }
}
```

## Troubleshooting

### Missing UTxOs

**Problem:** Evaluation fails with "UTxO not found" error.

**Solution:** Ensure all UTxOs referenced in the transaction are added to the fetcher, including:

* Script UTxOs being spent
* Collateral UTxOs
* Reference inputs

### Invalid Script

**Problem:** Evaluation fails with script execution error.

**Solution:**

1. Verify the script CBOR is correct
2. Check that datum and redeemer match what the script expects
3. Ensure the script version (V1, V2, V3) matches the transaction builder call

### Budget Exceeded

**Problem:** Evaluation succeeds but reports very high costs.

**Solution:**

1. Review your Plutus script for optimization opportunities
2. Consider using reference scripts to reduce transaction size
3. Check for unnecessary operations in the script

### Network Mismatch

**Problem:** Evaluation produces unexpected results.

**Solution:** Ensure the network parameter in OfflineEvaluator matches:

1. The network used to generate addresses
2. The protocol parameters added to the fetcher

### Missing Protocol Parameters

**Problem:** Evaluation fails without clear error.

**Solution:** Add complete protocol parameters to the fetcher before evaluation. The evaluator needs parameters like `priceMem` and `priceStep` to calculate costs.

## Related Links

* [Offline Fetcher](/providers/offline-fetcher) - Mock blockchain data for testing
* [MeshJS Transaction Builder](/transaction/basics)
* [MeshJS Smart Contracts](/smart-contracts)
* [Plutus Script Development](/guides/plutus)


# Offline Fetcher
URL: /providers/offline-fetcher

Test and develop Cardano applications without network connectivity

***

title: "Offline Fetcher"
description: "Test and develop Cardano applications without network connectivity"
---------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

The OfflineFetcher provides access to blockchain data without requiring network connectivity. It stores data locally and returns it when queried, making it a drop-in replacement for other providers.

**Use OfflineFetcher when you need:**

* Unit testing without network dependencies
* Development in offline environments
* Mocking blockchain state for specific scenarios
* Reproducible test fixtures

The OfflineFetcher implements the same interface as online providers like <Link href="/providers/blockfrost">BlockfrostProvider</Link>, so you can swap them interchangeably.

## Quick Start

Install the MeshJS package:

```bash
npm install @meshsdk/core
```

Create and populate the fetcher:

```tsx
import { OfflineFetcher } from "@meshsdk/core";

// Create a new instance
const fetcher = new OfflineFetcher();

// Add test data
fetcher.addUTxOs([
  {
    input: {
      txHash: "abc123...",
      outputIndex: 0,
    },
    output: {
      address: "addr_test1...",
      amount: [{ unit: "lovelace", quantity: "5000000" }],
    },
  },
]);

// Use like any other provider
const utxos = await fetcher.fetchAddressUTxOs("addr_test1...");
```

## Configuration Options

| Parameter | Type     | Required | Description                                     |
| --------- | -------- | -------- | ----------------------------------------------- |
| `network` | `string` | No       | Network identifier (e.g., "mainnet", "preprod") |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

// Create with default network
const fetcher = new OfflineFetcher();

// Create with specific network
const mainnetFetcher = new OfflineFetcher("mainnet");
const preprodFetcher = new OfflineFetcher("preprod");
```

## Adding Data

Before fetching data, you must add it to the OfflineFetcher. The following methods populate the internal data store.

### addAccount

Add stake account information.

```tsx
fetcher.addAccount(address: string, info: AccountInfo): void
```

| Parameter | Type          | Required | Description                |
| --------- | ------------- | -------- | -------------------------- |
| `address` | `string`      | Yes      | The stake address          |
| `info`    | `AccountInfo` | Yes      | Account information object |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addAccount("stake_test1...", {
  balance: "1000000000",
  rewards: "50000000",
  withdrawals: "10000000",
  poolId: "pool1...", // optional
});
```

***

### addUTxOs

Add UTxOs to the fetcher. These are returned by `fetchAddressUTxOs` and `fetchUTxOs`.

```tsx
fetcher.addUTxOs(utxos: UTxO[]): void
```

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `utxos`   | `UTxO[]` | Yes      | Array of UTxO objects |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addUTxOs([
  {
    input: {
      txHash: "abc123def456...",
      outputIndex: 0,
    },
    output: {
      address: "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
      amount: [
        { unit: "lovelace", quantity: "5000000" },
        { unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e", quantity: "1" },
      ],
    },
  },
  // Add script UTxOs with additional fields
  {
    input: {
      txHash: "def789...",
      outputIndex: 0,
    },
    output: {
      address: "addr_test1...",
      amount: [{ unit: "lovelace", quantity: "10000000" }],
      scriptHash: "abcd1234...",
      dataHash: "ef567890...",
      plutusData: "...",
      scriptRef: "...",
    },
  },
]);
```

***

### addAssetAddresses

Add address holdings for a specific asset.

```tsx
fetcher.addAssetAddresses(asset: string, addresses: AssetAddress[]): void
```

| Parameter   | Type             | Required | Description                             |
| ----------- | ---------------- | -------- | --------------------------------------- |
| `asset`     | `string`         | Yes      | The asset unit (policy ID + asset name) |
| `addresses` | `AssetAddress[]` | Yes      | Array of addresses and quantities       |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
  [
    { address: "addr_test1...", quantity: "1" },
    { address: "addr_test2...", quantity: "5" },
  ]
);
```

***

### addAssetMetadata

Add metadata for an asset.

```tsx
fetcher.addAssetMetadata(asset: string, metadata: AssetMetadata): void
```

| Parameter  | Type            | Required | Description                             |
| ---------- | --------------- | -------- | --------------------------------------- |
| `asset`    | `string`        | Yes      | The asset unit (policy ID + asset name) |
| `metadata` | `AssetMetadata` | Yes      | Asset metadata object                   |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addAssetMetadata(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
  {
    name: "MeshToken",
    image: "ipfs://QmXyz...",
    description: "A test token",
    // Any other CIP-25 metadata fields
  }
);
```

***

### addProtocolParameters

Add protocol parameters.

```tsx
fetcher.addProtocolParameters(params: Protocol): void
```

| Parameter | Type       | Required | Description                |
| --------- | ---------- | -------- | -------------------------- |
| `params`  | `Protocol` | Yes      | Protocol parameters object |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addProtocolParameters({
  epoch: 290,
  minFeeA: 44,
  minFeeB: 155381,
  maxBlockSize: 73728,
  maxTxSize: 16384,
  maxBlockHeaderSize: 1100,
  keyDeposit: 2000000,
  poolDeposit: 500000000,
  minPoolCost: "340000000",
  priceMem: 0.0577,
  priceStep: 0.0000721,
  // ... other parameters
});
```

***

### addSerializedTransaction

Add a serialized transaction for tracking.

```tsx
fetcher.addSerializedTransaction(txHash: string): void
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `txHash`  | `string` | Yes      | The transaction hash |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addSerializedTransaction(
  "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
);
```

## State Persistence

The OfflineFetcher can save and load its state, enabling test fixtures and data sharing.

### toJSON

Export the current state as JSON.

```tsx
const state = fetcher.toJSON(): string
```

**Returns:** JSON string representation of all stored data.

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

// Add data
fetcher.addUTxOs([...]);
fetcher.addProtocolParameters({...});

// Save state
const state = fetcher.toJSON();
localStorage.setItem("fetcher-state", state);

// Or save to file
import fs from "fs";
fs.writeFileSync("test-fixtures.json", state);
```

***

### fromJSON

Create a new OfflineFetcher from saved state.

```tsx
const fetcher = OfflineFetcher.fromJSON(json: string): OfflineFetcher
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `json`    | `string` | Yes      | JSON state from `toJSON()` |

**Returns:** New OfflineFetcher instance with loaded data.

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

// Load from localStorage
const savedState = localStorage.getItem("fetcher-state");
const fetcher = OfflineFetcher.fromJSON(savedState);

// Or load from file
import fs from "fs";
const fileState = fs.readFileSync("test-fixtures.json", "utf-8");
const fetcher = OfflineFetcher.fromJSON(fileState);
```

## API Reference

All fetch methods work identically to online providers but return data from the internal store.

### get

Fetch data from a URL path (returns empty for offline).

```tsx
await fetcher.get(endpoint: string): Promise<any>
```

***

### fetchAccountInfo

Retrieve stake account information.

```tsx
await fetcher.fetchAccountInfo(address: string): Promise<AccountInfo>
```

| Parameter | Type     | Required | Description       |
| --------- | -------- | -------- | ----------------- |
| `address` | `string` | Yes      | The stake address |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addAccount("stake_test1...", {
  balance: "1000000000",
  rewards: "50000000",
  withdrawals: "10000000",
});

const accountInfo = await fetcher.fetchAccountInfo("stake_test1...");
console.log(accountInfo.balance);
```

***

### fetchAddressAssets

Fetch assets held by an address.

```tsx
await fetcher.fetchAddressAssets(address: string): Promise<Asset[]>
```

| Parameter | Type     | Required | Description        |
| --------- | -------- | -------- | ------------------ |
| `address` | `string` | Yes      | The wallet address |

**Returns:** Array of assets derived from UTxOs at that address.

***

### fetchAddressUTxOs

Fetch UTxOs controlled by an address.

```tsx
await fetcher.fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `address` | `string` | Yes      | The wallet address   |
| `asset`   | `string` | No       | Filter by asset unit |

**Example:**

```tsx
import { OfflineFetcher } from "@meshsdk/core";

const fetcher = new OfflineFetcher();

fetcher.addUTxOs([
  {
    input: { txHash: "abc123...", outputIndex: 0 },
    output: {
      address: "addr_test1...",
      amount: [{ unit: "lovelace", quantity: "5000000" }],
    },
  },
]);

// Fetch all UTxOs
const utxos = await fetcher.fetchAddressUTxOs("addr_test1...");

// Fetch UTxOs with specific asset
const filtered = await fetcher.fetchAddressUTxOs(
  "addr_test1...",
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchAssetAddresses

Fetch addresses holding a specific asset.

```tsx
await fetcher.fetchAssetAddresses(asset: string): Promise<AssetAddress[]>
```

***

### fetchAssetMetadata

Fetch metadata for an asset.

```tsx
await fetcher.fetchAssetMetadata(asset: string): Promise<AssetMetadata>
```

***

### fetchBlockInfo

Fetch block information.

```tsx
await fetcher.fetchBlockInfo(hash: string): Promise<BlockInfo>
```

***

### fetchCollectionAssets

Fetch assets in a collection by policy ID.

```tsx
await fetcher.fetchCollectionAssets(policyId: string, cursor?: number): Promise<{ assets: Asset[]; next: number | null }>
```

***

### fetchHandleAddress

Resolve an ADA Handle to an address.

```tsx
await fetcher.fetchHandleAddress(handle: string): Promise<string>
```

***

### fetchHandle

Fetch CIP-68 handle metadata.

```tsx
await fetcher.fetchHandle(handle: string): Promise<HandleMetadata>
```

***

### fetchProtocolParameters

Fetch protocol parameters.

```tsx
await fetcher.fetchProtocolParameters(epoch?: number): Promise<Protocol>
```

***

### fetchTxInfo

Fetch transaction information.

```tsx
await fetcher.fetchTxInfo(hash: string): Promise<TransactionInfo>
```

***

### fetchUTxOs

Fetch UTxOs by transaction hash.

```tsx
await fetcher.fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>
```

***

### fetchGovernanceProposal

Fetch governance proposal information.

```tsx
await fetcher.fetchGovernanceProposal(txHash: string, certIndex: number): Promise<ProposalInfo>
```

## Complete Example

```tsx
import { OfflineFetcher, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Create and populate fetcher
const fetcher = new OfflineFetcher("preprod");

// Add protocol parameters
fetcher.addProtocolParameters({
  epoch: 290,
  minFeeA: 44,
  minFeeB: 155381,
  maxBlockSize: 73728,
  maxTxSize: 16384,
  maxBlockHeaderSize: 1100,
  keyDeposit: 2000000,
  poolDeposit: 500000000,
  minPoolCost: "340000000",
  priceMem: 0.0577,
  priceStep: 0.0000721,
  maxValSize: 5000,
  collateralPercent: 150,
  maxCollateralInputs: 3,
  coinsPerUtxoSize: "4310",
});

// Add test UTxOs
fetcher.addUTxOs([
  {
    input: {
      txHash: "abc123def456789abc123def456789abc123def456789abc123def456789abc1",
      outputIndex: 0,
    },
    output: {
      address: "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
      amount: [{ unit: "lovelace", quantity: "100000000" }],
    },
  },
]);

// Use in tests
async function testTransaction() {
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: fetcher,
    mnemonic: ["test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test", "test"],
  });

  const utxos = await wallet.getUtxosMesh();
  console.log(`Wallet has ${utxos.length} UTxOs`);

  const txBuilder = new MeshTxBuilder({
    fetcher: fetcher,
  });

  const unsignedTx = await txBuilder
    .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
    .changeAddress(await wallet.getChangeAddressBech32())
    .selectUtxosFrom(utxos)
    .complete();

  console.log("Transaction built successfully");
}

// Save state for reuse
const state = fetcher.toJSON();
console.log("State saved:", state.length, "bytes");
```

## Troubleshooting

### Empty Results

**Problem:** Fetch methods return empty arrays or undefined.

**Solution:** Ensure you've added the corresponding data before fetching. The OfflineFetcher only returns data that has been explicitly added.

### Address Mismatch

**Problem:** UTxOs not found for an address.

**Solution:** Verify the address in `addUTxOs` matches exactly what you're querying. Addresses are case-sensitive.

### Missing Protocol Parameters

**Problem:** Transaction building fails without protocol parameters.

**Solution:** Call `addProtocolParameters` with complete parameter object before building transactions.

### State Not Loading

**Problem:** `fromJSON` throws an error.

**Solution:** Ensure the JSON string is valid and was created by `toJSON`. Check for corruption if loading from file.

## Related Links

* [Offline Evaluator](/providers/offline-evaluator) - Evaluate Plutus scripts offline
* [MeshJS Transaction Builder](/transaction/basics)
* [MeshJS Testing Guide](/guides/testing)


# Ogmios Provider
URL: /providers/ogmios

Connect to your cardano-node using Ogmios WebSocket API for transaction evaluation and submission.

***

title: "Ogmios Provider"
description: "Connect to your cardano-node using Ogmios WebSocket API for transaction evaluation and submission."
-----------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://ogmios.dev/">Ogmios</Link> is a lightweight bridge interface for cardano-node that provides a WebSocket API enabling local clients to speak Ouroboros mini-protocols via JSON/RPC.

**When to use Ogmios:**

* You run your own cardano-node and want direct access
* You need low-latency transaction submission
* You require self-hosted infrastructure without third-party dependencies
* You want to evaluate Plutus script execution costs locally

Ogmios is fast, lightweight, and deploys alongside relay nodes to create entry points on the Cardano network for various types of applications.

## Quick Start

Install the MeshJS package:

```bash
npm install @meshsdk/core
```

Initialize the provider:

```tsx
import { OgmiosProvider } from "@meshsdk/core";

const provider = new OgmiosProvider("http://localhost:1337");
```

Evaluate and submit transactions:

```tsx
import { OgmiosProvider } from "@meshsdk/core";

const provider = new OgmiosProvider("http://localhost:1337");

// Evaluate a smart contract transaction
const evaluation = await provider.evaluateTx(unsignedTx);

// Submit a signed transaction
const txHash = await provider.submitTx(signedTx);
```

## Configuration Options

| Option | Type     | Required | Description                                |
| ------ | -------- | -------- | ------------------------------------------ |
| `url`  | `string` | Yes      | The Ogmios server URL (WebSocket endpoint) |

### Running Ogmios

Ogmios requires a running cardano-node. Start Ogmios with:

```bash
ogmios --node-socket /path/to/node.socket --node-config /path/to/config.json
```

Or use Docker:

```bash
docker run -it \
  -v /path/to/node:/node \
  -p 1337:1337 \
  cardanosolutions/ogmios:latest \
  --node-socket /node/node.socket \
  --node-config /node/config.json
```

## API Reference

### evaluateTx

Evaluate a transaction to determine script execution costs. Use this to calculate the exact memory and CPU budget required for Plutus scripts.

```tsx
await provider.evaluateTx(tx: string): Promise<Omit<Action, "data">[]>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `tx`      | `string` | Yes      | The unsigned transaction CBOR hex |

**Returns:** Array of execution cost estimates for each script in the transaction.

```tsx
[
  {
    index: 0,       // The redeemer index
    tag: "SPEND",   // The redeemer tag (SPEND, MINT, CERT, REWARD)
    budget: {
      mem: 1700,    // Memory units required
      steps: 368100 // CPU steps required
    }
  }
]
```

**Example:**

```tsx
import { OgmiosProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new OgmiosProvider("http://localhost:1337");
const txBuilder = new MeshTxBuilder({ fetcher: provider });

// Build a transaction that interacts with a smart contract
const unsignedTx = await txBuilder
  // ... transaction building code
  .complete();

// Evaluate to get execution costs
const evaluation = await provider.evaluateTx(unsignedTx);

console.log(evaluation);
// [
//   {
//     index: 0,
//     tag: "SPEND",
//     budget: { mem: 1700, steps: 368100 }
//   }
// ]
```

Use the evaluation results to set precise redeemer budgets:

```tsx
const redeemer = {
  data: { alternative: 0, fields: [] },
  budget: {
    mem: evaluation[0].budget.mem,
    steps: evaluation[0].budget.steps,
  },
};
```

***

### submitTx

Submit a signed transaction to the Cardano network.

```tsx
await provider.submitTx(tx: string): Promise<string>
```

| Parameter | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `tx`      | `string` | Yes      | The signed transaction CBOR hex |

**Returns:** The transaction hash.

**Example:**

```tsx
import { OgmiosProvider } from "@meshsdk/core";

const provider = new OgmiosProvider("http://localhost:1337");

const txHash = await provider.submitTx(signedTx);
console.log(`Transaction submitted: ${txHash}`);
```

## Complete Example

This example shows how to build, evaluate, and submit a smart contract transaction using Ogmios for evaluation and submission, combined with another provider for data fetching:

```tsx
import { OgmiosProvider, MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function interactWithSmartContract() {
  // Use Ogmios for evaluation and submission
  const ogmios = new OgmiosProvider("http://localhost:1337");

  // Use another provider for data fetching (Ogmios doesn't support queries)
  const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: fetcher,
    submitter: ogmios,
    mnemonic: ["your", "mnemonic", "phrase", "..."],
  });

  // Get wallet data
  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  // Build transaction
  const txBuilder = new MeshTxBuilder({
    fetcher: fetcher,
    evaluator: ogmios,
  });

  const unsignedTx = await txBuilder
    .spendingPlutusScript("V3")
    .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
    .txInInlineDatumPresent()
    .txInRedeemerValue({ alternative: 0, fields: [] })
    .txInScript(scriptCbor)
    .txOut(changeAddress, [{ unit: "lovelace", quantity: "5000000" }])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Evaluate to get precise script costs
  const evaluation = await ogmios.evaluateTx(unsignedTx);
  console.log("Script execution costs:", evaluation);

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await ogmios.submitTx(signedTx);

  console.log(`Transaction submitted: ${txHash}`);
}
```

## Troubleshooting

### Connection refused

**Problem:** Cannot connect to Ogmios server.

**Solution:**

1. Verify Ogmios is running: `curl http://localhost:1337/health`
2. Check the URL and port are correct
3. Ensure your firewall allows connections to the Ogmios port
4. Verify Ogmios has a working connection to the cardano-node socket

### Node not synced

**Problem:** Transaction evaluation fails with "node not synced" error.

**Solution:** Wait for your cardano-node to fully sync with the network. Check sync progress:

```bash
cardano-cli query tip --mainnet
```

### Invalid transaction

**Problem:** `submitTx` fails with validation errors.

**Solution:**

1. Ensure the transaction is properly signed
2. Verify all inputs exist and are unspent
3. Check that fees are sufficient
4. For script transactions, ensure redeemer budgets are adequate

### Evaluation failures

**Problem:** `evaluateTx` returns errors for smart contract transactions.

**Solution:**

1. Ensure all referenced UTxOs exist on-chain
2. Verify the script CBOR is correct
3. Check that datum and redeemer are properly formatted
4. Ensure the transaction structure matches what the script expects

### WebSocket timeout

**Problem:** Requests timeout without response.

**Solution:**

1. Check if cardano-node is responsive
2. Verify Ogmios has a working connection to the node socket
3. Increase client timeout settings if evaluating complex scripts

## References

* [Ogmios Documentation](https://ogmios.dev/) - Official Ogmios bridge interface documentation and API reference
* [Ogmios Getting Started](https://ogmios.dev/getting-started/) - Installation and setup guides for Ogmios
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the transaction model for script evaluation

## Related

* <Link href="https://ogmios.dev/">Ogmios Documentation</Link>
* <Link href="https://ogmios.dev/getting-started/">Ogmios Getting Started</Link>
* <Link href="https://ogmios.dev/api/">Ogmios API Reference</Link>
* <Link href="/providers">All Providers</Link> - Compare with other providers
* <Link href="/apis/txbuilder/basics">Transaction Builder</Link> - Build transactions


# Scalus Emulator
URL: /providers/scalus-emulator

A Scalus-based emulator for testing and validation.

***

title: "Scalus Emulator"
description: "A Scalus-based emulator for testing and validation."
------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

The Scalus Emulator is extremely useful for testing transactions and ensuring correct chain state evolution. It validates your transactions with proper Ledger rules, so you can ensure that your transactions are valid.

**Use Scalus Emulator when you need:**

* Unit testing without network dependencies
* Testing smart contract development
* Validating off-chain code (correct state transitions)
* Simulating Cardano blockchain state evolution

## Quick Start

Setting up the emulator, if you want accurate time validations, the correct slot configuration must be inputted. The current slot must also be set.

```typescript
const { ScalusEmulator } = require("@meshsdk/scalus-emulator");
import { SLOT_CONFIG_NETWORK, unixTimeToEnclosingSlot } from "@meshsdk/core";

const provider = new ScalusEmulator(
  [
    {
      input: {
        txHash:
          "0000000000000000000000000000000000000000000000000000000000000000",
        outputIndex: 0,
      },
      output: {
        address,
        amount: [{ unit: "lovelace", quantity: "1000000000" }],
      },
    },
  ],
  SLOT_CONFIG_NETWORK["preview"],
);

await provider.setSlot(
  unixTimeToEnclosingSlot(Date.now(), SLOT_CONFIG_NETWORK["preview"]),
);
```

## Configuration Options

| Parameter      | Type                                                             | Required | Description                                                                                          |
| -------------- | ---------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| initialUtxos   | UTxO\[]                                                          | Yes      | Initial UTxO state of the emulator                                                                   |
| slotConfig     | SlotConfig                                                       | Yes      | Configuration for slots of the emulator, used for time validation                                    |
| protocolParams | Protocol                                                         | No       | Configuration for protocol parameters used for the emulator, default values are used if not provided |
| costModels     | `{ PlutusV1: number[], PlutusV2: number[], PlutusV3: number[] }` | No       | Cost models used by the emulator for execution unit fees, default values are used if not provided    |

Subsequently, transactions can be built and submitted to the emulator. For example, a simple send transaction.

```typescript
import { MeshWallet } from "@meshsdk/wallet";

const wallet = new MeshWallet({
  networkId: 0,
  key: { type: "mnemonic", words: TEST_MNEMONIC },
});
await wallet.init();
const address = (await wallet.getChangeAddress())[0]!;

const newTxBuilder = () =>
  new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
    evaluator: provider,
  });

const utxos = await provider.fetchAddressUTxOs(address);
const txHex = await newTxBuilder()
  .txOut(address, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(txHex);
const txHash = await provider.submitTx(signedTx);

expect(txHash).toBeDefined();
expect(txHash.length).toBe(64);
```

The emulator implements the IFetcher interface, allowing you to fetch UTxOs, the states will mutate based on successfully submitted transactions

```typescript
const utxosBefore = await provider.fetchAddressUTxOs(address);
const totalBefore = utxosBefore.reduce(
  (sum, u) =>
    sum + BigInt(u.output.amount.find((a) => a.unit === "lovelace")!.quantity),
  0n,
);

const txHex = await newTxBuilder()
  .txOut(address, [{ unit: "lovelace", quantity: "3000000" }])
  .changeAddress(address)
  .selectUtxosFrom(utxosBefore)
  .complete();

const signedTx = await wallet.signTx(txHex);
await provider.submitTx(signedTx);

const utxosAfter = await provider.fetchAddressUTxOs(address);
const totalAfter = utxosAfter.reduce(
  (sum, u) =>
    sum + BigInt(u.output.amount.find((a) => a.unit === "lovelace")!.quantity),
  0n,
);

expect(utxosAfter.length).toBeGreaterThan(0);
// Total should decrease by fees
expect(totalAfter).toBeLessThan(totalBefore);
expect(totalAfter).toBeGreaterThan(totalBefore - 1_000_000n);
```

The emulator also implements IEvaluator, which allows plutus script evaluations, including calculation of execution units. The submission will also reject transactions with script errors.

```typescript
const policyId = resolveScriptHash(alwaysSucceedCbor, "V3");
const tokenNameHex = Buffer.from("SpendTest").toString("hex");
const unit = policyId + tokenNameHex;

const utxos = await provider.fetchAddressUTxOs(address);

// Step 1: Mint tokens using plutus script
const mintTxHex = await newTxBuilder()
  .mintPlutusScriptV3()
  .mint("50", policyId, tokenNameHex)
  .mintRedeemerValue("")
  .mintingScript(alwaysSucceedCbor)
  .txInCollateral(
    utxos[0]!.input.txHash,
    utxos[0]!.input.outputIndex,
    utxos[0]!.output.amount,
    utxos[0]!.output.address,
  )
  .txOut(address, [
    { unit: "lovelace", quantity: "2000000" },
    { unit, quantity: "50" },
  ])
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();
const signedMint = await wallet.signTx(mintTxHex);
const mintHash = await provider.submitTx(signedMint);
expect(mintHash.length).toBe(64);

// Step 2: Verify the minted tokens via fetchUTxOs
const mintedUtxos = await provider.fetchUTxOs(mintHash);
expect(mintedUtxos.length).toBeGreaterThan(0);
const tokenOutput = mintedUtxos.find((u) =>
  u.output.amount.some((a) => a.unit === unit),
);
expect(tokenOutput).toBeDefined();
```

With the correct slotConfig and time setup, we can also test that expired transactions get rejected.

```typescript
const currentSlot = unixTimeToEnclosingSlot(Date.now(), slotConfig);
const expiredSlot = currentSlot - 100;

const utxos = await provider.fetchAddressUTxOs(address);

const txHex = await newTxBuilder()
  .txOut(address, [{ unit: "lovelace", quantity: "2000000" }])
  .invalidHereafter(expiredSlot)
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(txHex);
await expect(provider.submitTx(signedTx)).rejects.toThrow();
```


# UTxORPC Provider
URL: /providers/utxorpc

Connect to Cardano using the high-performance UTxORPC gRPC protocol

***

title: "UTxORPC Provider"
description: "Connect to Cardano using the high-performance UTxORPC gRPC protocol"
----------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

The UTxORPC (U5C) provider connects to Cardano using the <Link href="https://utxorpc.org/">UTxORPC specification</Link>, a standardized gRPC interface for UTxO-based blockchains. It uses a compact, high-performance binary format for efficient communication.

**Key features:**

* High performance through gRPC protocol
* Compact binary format minimizes network overhead
* Standardized interface ensures cross-implementation compatibility
* Works with Dolos, Demeter.run, and other UTxORPC-compliant servers

**Use UTxORPC when you need:**

* Maximum performance for high-throughput applications
* Standardized blockchain access across different implementations
* Efficient communication with minimal message size
* Self-hosted infrastructure with Dolos

## Quick Start

Install the MeshJS package:

```bash
npm install @meshsdk/core
```

Initialize the provider:

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});
```

For hosted services like <Link href="https://demeter.run/">Demeter.run</Link>:

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "https://utxorpc-v0-mainnet.demeter.run",
  headers: {
    "dmtr-api-key": "<YOUR_API_KEY>",
  },
});
```

Fetch blockchain data:

```tsx
// Fetch UTxOs from an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Submit a transaction
const txHash = await provider.submitTx(signedTx);
```

## Configuration Options

| Parameter | Type                     | Required | Description                       |
| --------- | ------------------------ | -------- | --------------------------------- |
| `url`     | `string`                 | Yes      | The UTxORPC server URL            |
| `headers` | `Record<string, string>` | No       | Custom headers for authentication |

### Server Options

**Self-hosted with Dolos:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});
```

**Demeter.run (hosted):**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "https://utxorpc-v0-mainnet.demeter.run",
  headers: {
    "dmtr-api-key": "<YOUR_API_KEY>",
  },
});
```

For more server options, see the <Link href="https://github.com/utxorpc/docs/blob/main/pages/servers.md">UTxORPC Ecosystem Servers Documentation</Link>.

## API Reference

### get

Fetch data from the blockchain using a URL path.

```tsx
await provider.get(endpoint: string): Promise<any>
```

| Parameter  | Type     | Required | Description           |
| ---------- | -------- | -------- | --------------------- |
| `endpoint` | `string` | Yes      | The API endpoint path |

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const transactions = await provider.get(
  "/addresses/addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9/transactions"
);
```

***

### fetchAccountInfo

Retrieve information about a stake account.

```tsx
await provider.fetchAccountInfo(address: string): Promise<AccountInfo>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `address` | `string` | Yes      | The stake address (bech32 format) |

**Returns:** `AccountInfo` object containing balance, rewards, and delegation status.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const accountInfo = await provider.fetchAccountInfo(
  "stake_test1uzw5mnt7g4xjgdqkfa80hrk7kdvds6sa4k0vvgjvlj7w8eskffj2n"
);

console.log(accountInfo.balance);
console.log(accountInfo.rewards);
```

***

### fetchAddressAssets

Fetch all assets held by an address.

```tsx
await provider.fetchAddressAssets(address: string): Promise<Asset[]>
```

| Parameter | Type     | Required | Description                        |
| --------- | -------- | -------- | ---------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format) |

**Returns:** Array of `Asset` objects with `unit` and `quantity`.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const assets = await provider.fetchAddressAssets(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

assets.forEach((asset) => {
  console.log(`${asset.unit}: ${asset.quantity}`);
});
```

***

### fetchAddressUTxOs

Fetch UTxOs controlled by an address, optionally filtered by asset.

```tsx
await provider.fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description                                       |
| --------- | -------- | -------- | ------------------------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format)                |
| `asset`   | `string` | No       | Filter by asset unit (policy ID + asset name hex) |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

// Fetch all UTxOs
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Fetch UTxOs containing a specific asset
const filteredUtxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchAssetAddresses

Fetch all addresses holding a specific asset.

```tsx
await provider.fetchAssetAddresses(asset: string): Promise<AssetAddress[]>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** Array of addresses and quantities.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const holders = await provider.fetchAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

holders.forEach((holder) => {
  console.log(`${holder.address}: ${holder.quantity}`);
});
```

***

### fetchAssetMetadata

Fetch metadata for an asset.

```tsx
await provider.fetchAssetMetadata(asset: string): Promise<AssetMetadata>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** `AssetMetadata` object with name, image, and other metadata fields.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const metadata = await provider.fetchAssetMetadata(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

console.log(metadata.name);
console.log(metadata.image);
```

***

### fetchBlockInfo

Fetch information about a block.

```tsx
await provider.fetchBlockInfo(hash: string): Promise<BlockInfo>
```

| Parameter | Type     | Required | Description    |
| --------- | -------- | -------- | -------------- |
| `hash`    | `string` | Yes      | The block hash |

**Returns:** `BlockInfo` object with block details.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const blockInfo = await provider.fetchBlockInfo(
  "79f60880b097ec7dabb81f75f0b52fedf5e922d4f779a11c0c432dcf22c56089"
);

console.log(blockInfo.slot);
console.log(blockInfo.time);
```

***

### fetchCollectionAssets

Fetch all assets in an NFT collection by policy ID.

```tsx
await provider.fetchCollectionAssets(policyId: string, cursor?: number): Promise<{ assets: Asset[]; next: number | null }>
```

| Parameter  | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `policyId` | `string` | Yes      | The policy ID of the collection |
| `cursor`   | `number` | No       | Pagination cursor (default: 1)  |

**Returns:** Object with `assets` array and `next` cursor for pagination.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

// Fetch first page
const result = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527"
);

console.log(result.assets);

// Fetch next page if available
if (result.next) {
  const nextPage = await provider.fetchCollectionAssets(
    "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527",
    result.next
  );
}
```

***

### fetchHandleAddress

Resolve an ADA Handle to its associated address.

```tsx
await provider.fetchHandleAddress(handle: string): Promise<string>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** The resolved Cardano address.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const address = await provider.fetchHandleAddress("meshsdk");
console.log(address);
```

***

### fetchHandle

Fetch CIP-68 handle metadata.

```tsx
await provider.fetchHandle(handle: string): Promise<HandleMetadata>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** Handle metadata including CIP-68 fields.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const handleData = await provider.fetchHandle("meshsdk");
console.log(handleData);
```

***

### fetchProtocolParameters

Fetch the current protocol parameters.

```tsx
await provider.fetchProtocolParameters(epoch?: number): Promise<Protocol>
```

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `epoch`   | `number` | No       | Specific epoch (default: current epoch) |

**Returns:** `Protocol` object with all protocol parameters.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const params = await provider.fetchProtocolParameters();

console.log(params.minFeeA);
console.log(params.minFeeB);
console.log(params.maxTxSize);
```

***

### fetchTxInfo

Fetch information about a confirmed transaction.

```tsx
await provider.fetchTxInfo(hash: string): Promise<TransactionInfo>
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `hash`    | `string` | Yes      | The transaction hash |

**Returns:** `TransactionInfo` object with transaction details.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const txInfo = await provider.fetchTxInfo(
  "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
);

console.log(txInfo.block);
console.log(txInfo.fees);
```

***

### fetchUTxOs

Fetch UTxOs by transaction hash.

```tsx
await provider.fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `hash`    | `string` | Yes      | The transaction hash  |
| `index`   | `number` | No       | Specific output index |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

// Fetch all UTxOs from a transaction
const utxos = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70"
);

// Fetch specific output
const specificUtxo = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70",
  0
);
```

***

### fetchGovernanceProposal

Fetch information about a governance proposal.

```tsx
await provider.fetchGovernanceProposal(txHash: string, certIndex: number): Promise<ProposalInfo>
```

| Parameter   | Type     | Required | Description                   |
| ----------- | -------- | -------- | ----------------------------- |
| `txHash`    | `string` | Yes      | The proposal transaction hash |
| `certIndex` | `number` | Yes      | The certificate index         |

**Returns:** `ProposalInfo` object with proposal details.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const proposal = await provider.fetchGovernanceProposal(
  "372d688faa77e146798b581b322c0f2981a9023764736ade5d12e0e4e796af8c",
  0
);
```

***

### evaluateTx

Evaluate a transaction to determine script execution costs.

```tsx
await provider.evaluateTx(tx: string): Promise<Omit<Action, "data">[]>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `tx`      | `string` | Yes      | The unsigned transaction CBOR hex |

**Returns:** Array of execution cost estimates for each script.

**Example:**

```tsx
import { U5CProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  // ... transaction building code
  .complete();

const evaluation = await provider.evaluateTx(unsignedTx);

console.log(evaluation);
// [
//   {
//     index: 0,
//     tag: "SPEND",
//     budget: {
//       mem: 1700,
//       steps: 368100
//     }
//   }
// ]
```

***

### submitTx

Submit a signed transaction to the network.

```tsx
await provider.submitTx(tx: string): Promise<string>
```

| Parameter | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `tx`      | `string` | Yes      | The signed transaction CBOR hex |

**Returns:** The transaction hash.

**Example:**

```tsx
import { U5CProvider } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const txHash = await provider.submitTx(signedTx);
console.log(`Transaction submitted: ${txHash}`);
```

***

### onTxConfirmed

Listen for transaction confirmation.

```tsx
provider.onTxConfirmed(txHash: string, callback: () => void, limit?: number): void
```

| Parameter  | Type         | Required | Description                     |
| ---------- | ------------ | -------- | ------------------------------- |
| `txHash`   | `string`     | Yes      | The transaction hash to monitor |
| `callback` | `() => void` | Yes      | Function called when confirmed  |
| `limit`    | `number`     | No       | Maximum confirmation checks     |

**Example:**

```tsx
import { U5CProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new U5CProvider({
  url: "http://localhost:50051",
});

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .txOut("addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr", [
    { unit: "lovelace", quantity: "5000000" },
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await provider.submitTx(signedTx);

provider.onTxConfirmed(txHash, () => {
  console.log("Transaction confirmed!");
});
```

## Complete Example

```tsx
import { U5CProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function sendAda() {
  // Initialize provider
  const provider = new U5CProvider({
    url: "https://utxorpc-v0-preprod.demeter.run",
    headers: {
      "dmtr-api-key": "<YOUR_API_KEY>",
    },
  });

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: ["your", "mnemonic", "phrase", "..."],
  });

  // Get wallet data
  const utxos = await wallet.getUtxosMesh();
  const changeAddress = await wallet.getChangeAddressBech32();

  // Build transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .txOut("addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9", [
      { unit: "lovelace", quantity: "5000000" },
    ])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await provider.submitTx(signedTx);

  console.log(`Transaction submitted: ${txHash}`);

  // Wait for confirmation
  provider.onTxConfirmed(txHash, () => {
    console.log("Transaction confirmed!");
  });
}
```

## Troubleshooting

### Connection Issues

**Problem:** Cannot connect to UTxORPC server.

**Solution:**

1. Verify the server URL is correct
2. For self-hosted Dolos, ensure the server is running
3. For Demeter.run, verify your API key is valid

### gRPC Errors

**Problem:** gRPC-specific errors in the console.

**Solution:**

1. Ensure you're using compatible client and server versions
2. Check that the server supports the UTxORPC specification version you're using
3. Verify network connectivity to the gRPC endpoint

### Authentication Failures

**Problem:** 401 or 403 errors with Demeter.run.

**Solution:**

1. Verify your API key in the `headers` configuration
2. Check that your Demeter.run subscription is active
3. Ensure you're using the correct endpoint for your network (mainnet/preprod/preview)

### Missing Data

**Problem:** Queries return empty results.

**Solution:**

1. Verify the address or asset exists on the correct network
2. Check that your UTxORPC server is fully synced
3. For self-hosted servers, ensure the indexer has processed recent blocks

## References

* [UTxORPC Specification](https://utxorpc.org/) - The standardized gRPC interface for UTxO-based blockchains
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources
* [Cardano eUTXO Model](https://docs.cardano.org/about-cardano/learn/eutxo-explainer/) - Understanding the extended UTXO model

## Related Links

* <Link href="https://utxorpc.org/">UTxORPC Specification</Link>
* <Link href="https://github.com/utxorpc/docs/blob/main/pages/servers.md">UTxORPC Server Implementations</Link>
* <Link href="https://demeter.run/">Demeter.run</Link>
* <Link href="https://github.com/txpipe/dolos">Dolos (Self-hosted UTxORPC)</Link>
* [MeshJS Transaction Builder](/transaction/basics)
* [MeshJS Wallets](/wallets)


# Yaci Provider
URL: /providers/yaci

Build and test on custom Cardano devnets with fast feedback loops

***

title: "Yaci Provider"
description: "Build and test on custom Cardano devnets with fast feedback loops"
--------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

<Link href="https://github.com/bloxbean/yaci-devkit">Yaci DevKit</Link> is a development tool for rapid Cardano blockchain development. It allows you to create and destroy custom devnets in seconds, providing fast feedback loops and simplifying the iteration process.

**Key features:**

* Create custom Cardano devnets instantly
* Built-in indexer and block explorer
* Admin APIs for devnet management
* Address top-up functionality for testing
* Configurable genesis parameters

**Use Yaci when you need:**

* Fast local development without testnet delays
* Custom network parameters for testing edge cases
* Rapid iteration on smart contracts
* Isolated testing environments

## Quick Start

Install the MeshJS package:

```bash
npm install @meshsdk/core
```

Start a Yaci devnet using Docker:

```bash
docker run -it --rm \
  -p 3001:3001 \
  -p 10000:10000 \
  bloxbean/yaci-devkit:latest
```

Initialize the provider:

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");
```

Optionally include the admin URL for devnet management:

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider(
  "http://localhost:3001",
  "http://localhost:10000"
);
```

Fetch blockchain data:

```tsx
// Fetch UTxOs from an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Top up an address with ADA (requires admin URL)
await provider.addressTopup(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "100000000"
);
```

## Configuration Options

| Parameter  | Type     | Required | Description                                  |
| ---------- | -------- | -------- | -------------------------------------------- |
| `url`      | `string` | Yes      | The Yaci indexer API URL                     |
| `adminUrl` | `string` | No       | The Yaci admin API URL for devnet management |

### Default Ports

| Port  | Service                  |
| ----- | ------------------------ |
| 3001  | Yaci Store API (indexer) |
| 10000 | Yaci Admin API           |

## API Reference

### get

Fetch data from any Yaci API endpoint.

```tsx
await provider.get(endpoint: string): Promise<any>
```

| Parameter  | Type     | Required | Description           |
| ---------- | -------- | -------- | --------------------- |
| `endpoint` | `string` | Yes      | The API endpoint path |

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const transactions = await provider.get(
  "/addresses/addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9/transactions"
);
```

***

### fetchAccountInfo

Retrieve information about a stake account.

```tsx
await provider.fetchAccountInfo(address: string): Promise<AccountInfo>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `address` | `string` | Yes      | The stake address (bech32 format) |

**Returns:** `AccountInfo` object containing balance, rewards, and delegation status.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const accountInfo = await provider.fetchAccountInfo(
  "stake_test1uzw5mnt7g4xjgdqkfa80hrk7kdvds6sa4k0vvgjvlj7w8eskffj2n"
);

console.log(accountInfo.balance);
console.log(accountInfo.rewards);
```

***

### fetchAddressAssets

Fetch all assets held by an address.

```tsx
await provider.fetchAddressAssets(address: string): Promise<Asset[]>
```

| Parameter | Type     | Required | Description                        |
| --------- | -------- | -------- | ---------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format) |

**Returns:** Array of `Asset` objects with `unit` and `quantity`.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const assets = await provider.fetchAddressAssets(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

assets.forEach((asset) => {
  console.log(`${asset.unit}: ${asset.quantity}`);
});
```

***

### fetchAddressUTxOs

Fetch UTxOs controlled by an address, optionally filtered by asset.

```tsx
await provider.fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description                                       |
| --------- | -------- | -------- | ------------------------------------------------- |
| `address` | `string` | Yes      | The wallet address (bech32 format)                |
| `asset`   | `string` | No       | Filter by asset unit (policy ID + asset name hex) |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

// Fetch all UTxOs
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Fetch UTxOs containing a specific asset
const filteredUtxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);
```

***

### fetchAssetAddresses

Fetch all addresses holding a specific asset.

```tsx
await provider.fetchAssetAddresses(asset: string): Promise<AssetAddress[]>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** Array of addresses and quantities.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const holders = await provider.fetchAssetAddresses(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

holders.forEach((holder) => {
  console.log(`${holder.address}: ${holder.quantity}`);
});
```

***

### fetchAssetMetadata

Fetch metadata for an asset.

```tsx
await provider.fetchAssetMetadata(asset: string): Promise<AssetMetadata>
```

| Parameter | Type     | Required | Description                                 |
| --------- | -------- | -------- | ------------------------------------------- |
| `asset`   | `string` | Yes      | The asset unit (policy ID + asset name hex) |

**Returns:** `AssetMetadata` object with name, image, and other metadata fields.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const metadata = await provider.fetchAssetMetadata(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e"
);

console.log(metadata.name);
```

***

### fetchBlockInfo

Fetch information about a block.

```tsx
await provider.fetchBlockInfo(hash: string): Promise<BlockInfo>
```

| Parameter | Type     | Required | Description    |
| --------- | -------- | -------- | -------------- |
| `hash`    | `string` | Yes      | The block hash |

**Returns:** `BlockInfo` object with block details.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const blockInfo = await provider.fetchBlockInfo(
  "79f60880b097ec7dabb81f75f0b52fedf5e922d4f779a11c0c432dcf22c56089"
);

console.log(blockInfo.slot);
```

***

### fetchCollectionAssets

Fetch all assets in an NFT collection by policy ID.

```tsx
await provider.fetchCollectionAssets(policyId: string, cursor?: number): Promise<{ assets: Asset[]; next: number | null }>
```

| Parameter  | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `policyId` | `string` | Yes      | The policy ID of the collection |
| `cursor`   | `number` | No       | Pagination cursor (default: 1)  |

**Returns:** Object with `assets` array and `next` cursor for pagination.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const result = await provider.fetchCollectionAssets(
  "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc17255527"
);

console.log(result.assets);
```

***

### fetchHandleAddress

Resolve an ADA Handle to its associated address.

```tsx
await provider.fetchHandleAddress(handle: string): Promise<string>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** The resolved Cardano address.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const address = await provider.fetchHandleAddress("meshsdk");
console.log(address);
```

***

### fetchHandle

Fetch CIP-68 handle metadata.

```tsx
await provider.fetchHandle(handle: string): Promise<HandleMetadata>
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `handle`  | `string` | Yes      | The ADA Handle (without $) |

**Returns:** Handle metadata including CIP-68 fields.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const handleData = await provider.fetchHandle("meshsdk");
console.log(handleData);
```

***

### fetchProtocolParameters

Fetch the current protocol parameters.

```tsx
await provider.fetchProtocolParameters(epoch?: number): Promise<Protocol>
```

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `epoch`   | `number` | No       | Specific epoch (default: current epoch) |

**Returns:** `Protocol` object with all protocol parameters.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const params = await provider.fetchProtocolParameters();

console.log(params.minFeeA);
console.log(params.minFeeB);
```

***

### fetchTxInfo

Fetch information about a confirmed transaction.

```tsx
await provider.fetchTxInfo(hash: string): Promise<TransactionInfo>
```

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `hash`    | `string` | Yes      | The transaction hash |

**Returns:** `TransactionInfo` object with transaction details.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const txInfo = await provider.fetchTxInfo(
  "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
);

console.log(txInfo.block);
```

***

### fetchUTxOs

Fetch UTxOs by transaction hash.

```tsx
await provider.fetchUTxOs(hash: string, index?: number): Promise<UTxO[]>
```

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `hash`    | `string` | Yes      | The transaction hash  |
| `index`   | `number` | No       | Specific output index |

**Returns:** Array of `UTxO` objects.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const utxos = await provider.fetchUTxOs(
  "dfd2a2616e6154a092807b1ceebb9ddcadc0f22cf5c8e0e6b0757815083ccb70"
);
```

***

### fetchGovernanceProposal

Fetch information about a governance proposal.

```tsx
await provider.fetchGovernanceProposal(txHash: string, certIndex: number): Promise<ProposalInfo>
```

| Parameter   | Type     | Required | Description                   |
| ----------- | -------- | -------- | ----------------------------- |
| `txHash`    | `string` | Yes      | The proposal transaction hash |
| `certIndex` | `number` | Yes      | The certificate index         |

**Returns:** `ProposalInfo` object with proposal details.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const proposal = await provider.fetchGovernanceProposal(
  "372d688faa77e146798b581b322c0f2981a9023764736ade5d12e0e4e796af8c",
  0
);
```

***

### evaluateTx

Evaluate a transaction to determine script execution costs.

```tsx
await provider.evaluateTx(tx: string): Promise<Omit<Action, "data">[]>
```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `tx`      | `string` | Yes      | The unsigned transaction CBOR hex |

**Returns:** Array of execution cost estimates for each script.

**Example:**

```tsx
import { YaciProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  // ... transaction building code
  .complete();

const evaluation = await provider.evaluateTx(unsignedTx);
console.log(evaluation);
```

***

### submitTx

Submit a signed transaction to the network.

```tsx
await provider.submitTx(tx: string): Promise<string>
```

| Parameter | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `tx`      | `string` | Yes      | The signed transaction CBOR hex |

**Returns:** The transaction hash.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

const txHash = await provider.submitTx(signedTx);
console.log(`Transaction submitted: ${txHash}`);
```

***

### onTxConfirmed

Listen for transaction confirmation.

```tsx
provider.onTxConfirmed(txHash: string, callback: () => void, limit?: number): void
```

| Parameter  | Type         | Required | Description                     |
| ---------- | ------------ | -------- | ------------------------------- |
| `txHash`   | `string`     | Yes      | The transaction hash to monitor |
| `callback` | `() => void` | Yes      | Function called when confirmed  |
| `limit`    | `number`     | No       | Maximum confirmation checks     |

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("http://localhost:3001");

provider.onTxConfirmed(txHash, () => {
  console.log("Transaction confirmed!");
});
```

***

## Admin API Reference

The following methods require the admin URL to be configured.

### getDevnetInfo

Get information about the current devnet.

```tsx
await provider.getDevnetInfo(): Promise<DevnetInfo>
```

**Returns:** `DevnetInfo` object with devnet configuration.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider(
  "http://localhost:3001",
  "http://localhost:10000"
);

const devnetInfo = await provider.getDevnetInfo();

console.log(devnetInfo.nodePort);
console.log(devnetInfo.protocolMagic);
console.log(devnetInfo.slotLength);
console.log(devnetInfo.blockTime);
```

**Response structure:**

```tsx
{
  nodePort: 0,
  submitApiPort: 0,
  socketPath: "string",
  protocolMagic: 42,
  slotLength: 1,
  blockTime: 1,
  epochLength: 500,
  p2pEnabled: true,
  startTime: 0,
  masterNode: true,
  adminNodeUrl: "string",
  era: "Conway",
  genesisProfile: "zero_fee",
  ogmiosPort: 0,
  kupoPort: 0,
  yaciStorePort: 3001,
  socatPort: 0,
  prometheusPort: 0,
  blockProducer: true
}
```

***

### getGenesisByEra

Get genesis configuration for a specific era.

```tsx
await provider.getGenesisByEra(era: string): Promise<GenesisConfig>
```

| Parameter | Type     | Required | Description                                        |
| --------- | -------- | -------- | -------------------------------------------------- |
| `era`     | `string` | Yes      | The era name (e.g., "shelley", "alonzo", "conway") |

**Returns:** Genesis configuration for the specified era.

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider(
  "http://localhost:3001",
  "http://localhost:10000"
);

const genesis = await provider.getGenesisByEra("shelley");

console.log(genesis.activeSlotsCoeff);
console.log(genesis.epochLength);
console.log(genesis.networkMagic);
```

***

### addressTopup

Add ADA to any address. This is useful for funding test wallets.

```tsx
await provider.addressTopup(address: string, amount: string): Promise<void>
```

| Parameter | Type     | Required | Description         |
| --------- | -------- | -------- | ------------------- |
| `address` | `string` | Yes      | The address to fund |
| `amount`  | `string` | Yes      | Amount in lovelace  |

**Example:**

```tsx
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider(
  "http://localhost:3001",
  "http://localhost:10000"
);

// Add 100 ADA to the address
await provider.addressTopup(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
  "100000000"
);

console.log("Address topped up!");
```

## Complete Example

```tsx
import { YaciProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function developWithYaci() {
  // Initialize provider with admin access
  const provider = new YaciProvider(
    "http://localhost:3001",
    "http://localhost:10000"
  );

  // Check devnet info
  const devnetInfo = await provider.getDevnetInfo();
  console.log(`Devnet running on magic: ${devnetInfo.protocolMagic}`);

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: ["your", "mnemonic", "phrase", "..."],
  });

  const address = await wallet.getChangeAddressBech32();

  // Fund the wallet
  await provider.addressTopup(address, "1000000000"); // 1000 ADA
  console.log("Wallet funded!");

  // Wait a moment for the transaction to be indexed
  await new Promise((resolve) => setTimeout(resolve, 2000));

  // Get wallet data
  const utxos = await wallet.getUtxosMesh();
  console.log(`Wallet has ${utxos.length} UTxOs`);

  // Build transaction
  const txBuilder = new MeshTxBuilder({ fetcher: provider });

  const unsignedTx = await txBuilder
    .txOut("addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9", [
      { unit: "lovelace", quantity: "5000000" },
    ])
    .changeAddress(address)
    .selectUtxosFrom(utxos)
    .complete();

  // Sign and submit
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await provider.submitTx(signedTx);

  console.log(`Transaction submitted: ${txHash}`);

  // Wait for confirmation
  provider.onTxConfirmed(txHash, () => {
    console.log("Transaction confirmed!");
  });
}
```

## Troubleshooting

### Devnet Not Starting

**Problem:** Docker container fails to start or APIs are unreachable.

**Solution:**

1. Ensure Docker is running
2. Check port availability (3001, 10000)
3. Review container logs: `docker logs <container_id>`

### Address Topup Fails

**Problem:** `addressTopup` returns an error.

**Solution:**

1. Ensure you provided the admin URL when creating the provider
2. Verify the address format is correct
3. Check that the admin API is accessible

### Transactions Not Confirming

**Problem:** Transactions stay pending indefinitely.

**Solution:**

1. Yaci devnets have configurable block times - transactions confirm faster than mainnet
2. Check devnet info for block time: `await provider.getDevnetInfo()`
3. Ensure the devnet is producing blocks

### Empty UTxO Response After Topup

**Problem:** No UTxOs found after calling `addressTopup`.

**Solution:**

1. Wait for the topup transaction to be indexed (1-2 seconds)
2. The Yaci indexer needs time to process new blocks
3. Add a small delay before querying UTxOs

### Genesis Configuration Issues

**Problem:** Need specific protocol parameters for testing.

**Solution:** Use the Yaci CLI or admin API to create a devnet with custom genesis parameters. Check the <Link href="https://github.com/bloxbean/yaci-devkit">Yaci DevKit documentation</Link> for configuration options.

## Related Links

* <Link href="https://github.com/bloxbean/yaci-devkit">Yaci DevKit GitHub</Link>
* <Link href="https://github.com/bloxbean/yaci">Yaci Core</Link>
* <Link href="https://github.com/bloxbean/yaci-store">Yaci Store (Indexer)</Link>
* [MeshJS Transaction Builder](/transaction/basics)
* [MeshJS Smart Contracts](/smart-contracts)


# Content Ownership Contract
URL: /smart-contracts/content-ownership

Register and manage ownership of digital content on-chain

***

title: "Content Ownership Contract"
description: "Register and manage ownership of digital content on-chain"
------------------------------------------------------------------------

import Link from "next/link";

The Content Ownership contract creates an on-chain registry for digital content ownership. It tracks who owns what content (like IPFS files) with blockchain-verifiable proof. While anyone can copy digital files, this contract provides the single source of truth for ownership, enabling applications like royalties, licensing, and verified provenance.

## Use Cases

* Digital art ownership registration
* Music and media rights management
* Document authenticity verification
* Content licensing platforms
* NFT provenance tracking
* Intellectual property registries

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Setup Overview

The Content Ownership contract requires multiple setup steps:

| Step | Action                 | Purpose                                     |
| ---- | ---------------------- | ------------------------------------------- |
| 1    | Mint One-Time Policy   | Create oracle NFT for contract state        |
| 2    | Setup Oracle UTxO      | Lock oracle in contract                     |
| 3    | Send Reference Scripts | Deploy contract scripts on-chain            |
| 4    | Create Registries      | Initialize content and ownership registries |

After setup, users can register and manage content ownership.

## Contract Logic

The contract uses a dual-registry architecture:

| Registry               | Purpose                                 |
| ---------------------- | --------------------------------------- |
| **Content Registry**   | Maps content hashes to registry entries |
| **Ownership Registry** | Tracks which tokens own which content   |

### Scalability

* Each registry pair handles approximately 50 content entries
* Create additional registry pairs for larger collections
* Enables parallel content registration

## Setup Actions

### Step 1: Mint One-Time Minting Policy

Create the oracle NFT that governs the contract.

#### Method Signature

```typescript
contract.mintOneTimeMintingPolicy(): Promise<{ tx: string; paramUtxo: { outputIndex: number; txHash: string } }>
```

#### Code Example

```typescript
import { MeshContentOwnershipContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

// Initialize contract with operation address
const contract = new MeshContentOwnershipContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  {
    operationAddress: "addr_test1qp...your_operation_address",
  }
);

// Mint the one-time policy
const { tx, paramUtxo } = await contract.mintOneTimeMintingPolicy();
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Policy minted. Transaction hash:", txHash);
console.log("SAVE THIS - paramUtxo:", JSON.stringify(paramUtxo));
```

### Step 2: Setup Oracle UTxO

Lock the oracle NFT in the contract.

#### Method Signature

```typescript
contract.setupOracleUtxo(): Promise<string>
```

#### Code Example

```typescript
// Use the paramUtxo from step 1
const contract = new MeshContentOwnershipContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  {
    operationAddress: "addr_test1qp...your_operation_address",
    paramUtxo: paramUtxo, // From step 1
  }
);

const tx = await contract.setupOracleUtxo();
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Oracle setup complete:", txHash);
```

### Step 3: Send Reference Scripts On-Chain

Deploy the contract scripts for efficient transactions. Run this once for each script type.

#### Method Signature

```typescript
contract.sendRefScriptOnchain(scriptIndex: string): Promise<string>
```

#### Script Types

| Script              | Purpose                    |
| ------------------- | -------------------------- |
| `OracleNFT`         | Oracle validation          |
| `ContentRegistry`   | Content storage            |
| `ContentRefToken`   | Content reference tokens   |
| `OwnershipRegistry` | Ownership tracking         |
| `OwnershipRefToken` | Ownership reference tokens |

#### Code Example

```typescript
// Deploy each script (wait for confirmation between each)
const scripts = [
  "OracleNFT",
  "ContentRegistry",
  "ContentRefToken",
  "OwnershipRegistry",
  "OwnershipRefToken",
];

const refScriptTxHashes: Record<string, string> = {};

for (const script of scripts) {
  const tx = await contract.sendRefScriptOnchain(script);
  const signedTx = await wallet.signTx(tx);
  const txHash = await wallet.submitTx(signedTx);

  refScriptTxHashes[script] = txHash;
  console.log(`${script} deployed:`, txHash);

  // Wait for confirmation
  await new Promise((r) => setTimeout(r, 60000));
}

console.log("SAVE THESE - refScriptTxHashes:", JSON.stringify(refScriptTxHashes));
```

### Step 4: Create Content Registry

Initialize a content registry.

#### Method Signature

```typescript
contract.createContentRegistry(): Promise<string>
```

#### Code Example

```typescript
// Initialize with all reference script hashes
const contract = new MeshContentOwnershipContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  {
    operationAddress: "addr_test1qp...your_operation_address",
    paramUtxo: paramUtxo,
    refScriptUtxos: {
      contentRegistry: { outputIndex: 0, txHash: refScriptTxHashes.ContentRegistry },
      contentRefToken: { outputIndex: 0, txHash: refScriptTxHashes.ContentRefToken },
      ownershipRegistry: { outputIndex: 0, txHash: refScriptTxHashes.OwnershipRegistry },
      ownershipRefToken: { outputIndex: 0, txHash: refScriptTxHashes.OwnershipRefToken },
    },
  }
);

const tx = await contract.createContentRegistry();
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Content registry created:", txHash);
```

### Step 5: Create Ownership Registry

Initialize an ownership registry (pairs with content registry).

#### Method Signature

```typescript
contract.createOwnershipRegistry(): Promise<string>
```

#### Code Example

```typescript
const tx = await contract.createOwnershipRegistry();
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Ownership registry created:", txHash);
```

## User Actions

### Mint User Token

Create a token that represents ownership capability.

#### Method Signature

```typescript
contract.mintUserToken(tokenName: string, metadata: object): Promise<string>
```

#### Parameters

| Parameter   | Type     | Description                  |
| ----------- | -------- | ---------------------------- |
| `tokenName` | `string` | Name for the ownership token |
| `metadata`  | `object` | Token metadata               |

#### Code Example

```typescript
const tx = await contract.mintUserToken("MeshContentOwnership", {
  name: "Mesh Content Ownership",
  description: "Ownership token for content registry",
});
const signedTx = await wallet.signTx(tx, true);
const txHash = await wallet.submitTx(signedTx);

console.log("User token minted:", txHash);
```

### Create Content

Register new content in the registry.

#### Method Signature

```typescript
contract.createContent(
  ownerAsset: Asset,
  contentHashHex: string,
  registryNumber: number
): Promise<string>
```

#### Parameters

| Parameter        | Type     | Description                                         |
| ---------------- | -------- | --------------------------------------------------- |
| `ownerAsset`     | `Asset`  | Token representing ownership                        |
| `contentHashHex` | `string` | Unique identifier for the content (e.g., IPFS hash) |
| `registryNumber` | `number` | Which registry to use (0 for first)                 |

#### Code Example

```typescript
// Define the ownership token
const ownerAsset = {
  unit: "policyId...tokenName",
  quantity: "1",
};

// Content identifier (e.g., IPFS CID)
const contentHashHex = "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua";

// Register in the first registry
const registryNumber = 0;

const tx = await contract.createContent(
  ownerAsset,
  contentHashHex,
  registryNumber
);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Content registered:", txHash);
```

### Get Oracle Data

Fetch current registry state.

#### Method Signature

```typescript
contract.getOracleData(): Promise<{ contentNumber: number; ownershipNumber: number }>
```

#### Code Example

```typescript
const oracleData = await contract.getOracleData();

console.log("Content registries:", oracleData.contentNumber);
console.log("Ownership registries:", oracleData.ownershipNumber);
```

### Get Content

Retrieve content ownership information.

#### Method Signature

```typescript
contract.getContent(registryNumber: number, contentIndex: number): Promise<ContentData>
```

#### Code Example

```typescript
// Get the first content in the first registry
const content = await contract.getContent(0, 0);

console.log("Content hash:", content.contentHash);
console.log("Owner token:", content.ownerToken);
```

## Full Working Example

```typescript
import { MeshContentOwnershipContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function contentOwnershipDemo() {
  const wallet = await MeshCardanoBrowserWallet.enable("eternl");
  const provider = new BlockfrostProvider("<Your-API-Key>");

  // Step 1: Initial Setup (ONE TIME)
  let meshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
  });

  const operationAddress = await wallet.getChangeAddress();

  let contract = new MeshContentOwnershipContract(
    {
      mesh: meshTxBuilder,
      fetcher: provider,
      wallet: wallet,
      networkId: 0,
    },
    {
      operationAddress: operationAddress,
    }
  );

  // Mint one-time policy
  const { tx: policyTx, paramUtxo } = await contract.mintOneTimeMintingPolicy();
  await wallet.submitTx(await wallet.signTx(policyTx));
  console.log("Policy minted, paramUtxo:", paramUtxo);

  await new Promise((r) => setTimeout(r, 60000));

  // Setup oracle
  contract = new MeshContentOwnershipContract(
    {
      mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
      fetcher: provider,
      wallet: wallet,
      networkId: 0,
    },
    {
      operationAddress: operationAddress,
      paramUtxo: paramUtxo,
    }
  );

  const oracleTx = await contract.setupOracleUtxo();
  await wallet.submitTx(await wallet.signTx(oracleTx));
  console.log("Oracle setup complete");

  await new Promise((r) => setTimeout(r, 60000));

  // Deploy reference scripts (abbreviated - do all 5 in production)
  // ... deploy scripts and save txHashes ...

  // After full setup, register content
  // const contentTx = await contract.createContent(ownerAsset, contentHash, 0);
  // await wallet.submitTx(await wallet.signTx(contentTx));

  console.log("Setup complete!");
}

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

## Troubleshooting

### Common Errors

| Error                       | Cause                      | Solution                         |
| --------------------------- | -------------------------- | -------------------------------- |
| `Oracle not found`          | Missing or wrong paramUtxo | Verify paramUtxo from setup      |
| `Registry not found`        | Registries not created     | Complete all setup steps         |
| `Script not deployed`       | Missing reference scripts  | Deploy all 5 reference scripts   |
| `Invalid operation address` | Wrong signer               | Use the operation address wallet |

### Debugging Tips

1. **Complete setup in order**: Each step depends on the previous
2. **Save all transaction hashes**: You need them for configuration
3. **Wait for confirmations**: Allow 1-2 minutes between steps
4. **Use consistent addresses**: Operation address must match throughout

### Configuration Storage

Store this configuration after setup:

```typescript
const config = {
  operationAddress: "addr_test1qp...",
  paramUtxo: { outputIndex: 0, txHash: "..." },
  refScriptUtxos: {
    contentRegistry: { outputIndex: 0, txHash: "..." },
    contentRefToken: { outputIndex: 0, txHash: "..." },
    ownershipRegistry: { outputIndex: 0, txHash: "..." },
    ownershipRefToken: { outputIndex: 0, txHash: "..." },
  },
};

// Save to database or config file
```

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/content-ownership)
* [IPFS Documentation](https://docs.ipfs.io/)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)


# Escrow Contract
URL: /smart-contracts/escrow

Enable secure peer-to-peer asset exchanges with multi-signature verification

***

title: "Escrow Contract"
description: "Enable secure peer-to-peer asset exchanges with multi-signature verification"
-------------------------------------------------------------------------------------------

import Link from "next/link";

The Escrow contract enables two parties to securely exchange assets. One party initiates the escrow by depositing assets, the other party deposits their assets, and both parties sign to complete the exchange. Either party can cancel before completion to retrieve their assets.

## Use Cases

* Peer-to-peer trading without intermediaries
* Trustless asset swaps
* Secure over-the-counter (OTC) deals
* Cross-asset exchanges (NFT for ADA, token for token)
* Multi-party agreements

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshEscrowContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshEscrowContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});
```

## Contract Logic

The Escrow contract follows a multi-step process:

| Step | Action       | Description                                        |
| ---- | ------------ | -------------------------------------------------- |
| 1    | **Initiate** | Party A deposits assets and creates the escrow     |
| 2    | **Deposit**  | Party B deposits their assets into the same escrow |
| 3    | **Complete** | Both parties sign to swap assets                   |

### Cancellation Rules

* Either party can cancel at any time before completion
* Cancellation returns all assets to their original owners
* Partial escrows (only one deposit) return assets to the depositor

### Completion Requirements

* Both parties must have deposited assets
* Both parties must sign the completion transaction
* This is a **multi-signature transaction**

## Available Actions

### Initiate Escrow

Start a new escrow by depositing your assets.

#### Method Signature

```typescript
contract.initiateEscrow(escrowAmount: Asset[]): Promise<string>
```

#### Parameters

| Parameter      | Type      | Description                |
| -------------- | --------- | -------------------------- |
| `escrowAmount` | `Asset[]` | Array of assets to deposit |

#### Code Example

```typescript
import { MeshEscrowContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshEscrowContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Define assets to deposit (Party A offers 10 ADA)
const escrowAmount: Asset[] = [
  {
    unit: "lovelace",
    quantity: "10000000",
  },
];

// Initiate the escrow
const tx = await contract.initiateEscrow(escrowAmount);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Escrow initiated. Transaction hash:", txHash);
// Share this txHash with Party B
```

#### What Happens on Success

* Assets transfer from Party A's wallet to the contract
* Party A's address is recorded in the escrow datum
* Transaction hash is needed for Party B to deposit

### Recipient Deposit

Party B deposits their assets into an existing escrow.

#### Method Signature

```typescript
contract.recipientDeposit(escrowUtxo: UTxO, depositAmount: Asset[]): Promise<string>
```

#### Parameters

| Parameter       | Type      | Description                            |
| --------------- | --------- | -------------------------------------- |
| `escrowUtxo`    | `UTxO`    | The UTxO from the initiate transaction |
| `depositAmount` | `Asset[]` | Array of assets Party B is depositing  |

#### Code Example

```typescript
import { MeshEscrowContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";

// Initialize provider and contract (Party B's wallet)
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshEscrowContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: partyBWallet, // Party B's wallet
  networkId: 0,
});

// Get the escrow UTxO from Party A's transaction
const escrowUtxo = await contract.getUtxoByTxHash("<initiate-transaction-hash>");

// Define assets Party B is depositing (an NFT)
const depositAmount: Asset[] = [
  {
    unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
    quantity: "1",
  },
];

// Deposit into the escrow
const tx = await contract.recipientDeposit(escrowUtxo, depositAmount);
const signedTx = await partyBWallet.signTx(tx);
const txHash = await partyBWallet.submitTx(signedTx);

console.log("Deposit complete. Transaction hash:", txHash);
```

#### What Happens on Success

* Party B's assets transfer to the contract
* Both parties' addresses are now in the escrow datum
* Escrow is ready for completion

### Complete Escrow

Finalize the escrow and swap assets between both parties. This requires signatures from both participants.

#### Method Signature

```typescript
contract.completeEscrow(escrowUtxo: UTxO): Promise<string>
```

#### Parameters

| Parameter    | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `escrowUtxo` | `UTxO` | The UTxO containing the escrow |

#### Code Example (Two-Step Signing)

**Step 1: Party A signs**

```typescript
import { MeshEscrowContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Party A initiates completion
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshEscrowContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: partyAWallet,
  networkId: 0,
});

// Get the escrow UTxO (after Party B deposited)
const escrowUtxo = await contract.getUtxoByTxHash("<deposit-transaction-hash>");

// Build and partially sign the completion transaction
const tx = await contract.completeEscrow(escrowUtxo);
const signedTxByA = await partyAWallet.signTx(tx, true); // partial sign

console.log("Party A signed. Send this to Party B:", signedTxByA);
```

**Step 2: Party B signs and submits**

```typescript
// Party B receives the partially signed transaction
const signedTxByA = "<partially-signed-tx-from-party-a>";

// Party B adds their signature and submits
const signedTxByBoth = await partyBWallet.signTx(signedTxByA, true);
const txHash = await partyBWallet.submitTx(signedTxByBoth);

console.log("Escrow completed. Transaction hash:", txHash);
```

#### What Happens on Success

* Party A receives Party B's assets
* Party B receives Party A's assets
* Escrow UTxO is consumed
* View example: [Successful completion on Cardanoscan](https://preprod.cardanoscan.io/transaction/019b6ba41ee0a9de90068fe5c1eb1fd81489be5d2402bd560b548e1cd7f22056)

### Cancel Escrow

Cancel the escrow and return assets to their original owners.

#### Method Signature

```typescript
contract.cancelEscrow(escrowUtxo: UTxO): Promise<string>
```

#### Parameters

| Parameter    | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `escrowUtxo` | `UTxO` | The UTxO containing the escrow |

#### Code Example

```typescript
import { MeshEscrowContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshEscrowContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet, // Either party can cancel
  networkId: 0,
});

// Get the escrow UTxO
const escrowUtxo = await contract.getUtxoByTxHash("<escrow-transaction-hash>");

// Cancel the escrow
const tx = await contract.cancelEscrow(escrowUtxo);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Escrow cancelled. Transaction hash:", txHash);
```

#### What Happens on Success

* All assets return to their original depositors
* Escrow UTxO is consumed
* No further action possible on this escrow

## Full Working Example

```typescript
import { MeshEscrowContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function escrowDemo() {
  const provider = new BlockfrostProvider("<Your-API-Key>");

  // Party A: Wants to trade 10 ADA for an NFT
  const partyAWallet = await MeshCardanoBrowserWallet.enable("eternl");

  const contractA = new MeshEscrowContract({
    mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
    fetcher: provider,
    wallet: partyAWallet,
    networkId: 0,
  });

  // Step 1: Party A initiates with 10 ADA
  const partyADeposit: Asset[] = [
    { unit: "lovelace", quantity: "10000000" },
  ];

  const initTx = await contractA.initiateEscrow(partyADeposit);
  const signedInitTx = await partyAWallet.signTx(initTx);
  const initTxHash = await partyAWallet.submitTx(signedInitTx);

  console.log("Escrow initiated:", initTxHash);
  await new Promise((r) => setTimeout(r, 60000));

  // Step 2: Party B deposits their NFT
  const partyBWallet = await MeshCardanoBrowserWallet.enable("nami");

  const contractB = new MeshEscrowContract({
    mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
    fetcher: provider,
    wallet: partyBWallet,
    networkId: 0,
  });

  const escrowUtxo = await contractB.getUtxoByTxHash(initTxHash);

  const partyBDeposit: Asset[] = [
    {
      unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
      quantity: "1",
    },
  ];

  const depositTx = await contractB.recipientDeposit(escrowUtxo, partyBDeposit);
  const signedDepositTx = await partyBWallet.signTx(depositTx);
  const depositTxHash = await partyBWallet.submitTx(signedDepositTx);

  console.log("Party B deposited:", depositTxHash);
  await new Promise((r) => setTimeout(r, 60000));

  // Step 3: Complete the escrow (multi-sig)
  const finalUtxo = await contractA.getUtxoByTxHash(depositTxHash);

  // Party A signs first
  const completeTx = await contractA.completeEscrow(finalUtxo);
  const signedByA = await partyAWallet.signTx(completeTx, true, false);

  // Party B signs and submits
  const signedByBoth = await partyBWallet.signTx(signedByA, true, false);
  const completeTxHash = await partyBWallet.submitTx(signedByBoth);

  console.log("Escrow completed:", completeTxHash);
}

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

## Troubleshooting

### Common Errors

| Error                      | Cause                  | Solution                                            |
| -------------------------- | ---------------------- | --------------------------------------------------- |
| `Script validation failed` | Missing signature      | Ensure both parties sign the completion transaction |
| `UTxO not found`           | Wrong transaction hash | Verify you are using the latest escrow UTxO         |
| `Not a participant`        | Wrong wallet           | Only escrow participants can interact               |
| `Already completed`        | Escrow finalized       | Cannot modify a completed escrow                    |

### Debugging Tips

1. **Track transaction hashes**: Each step produces a new transaction hash
2. **Use partial signing**: Always pass `true` to `signTx()` for escrow operations
3. **Share transactions securely**: Use secure channels to exchange partially signed transactions
4. **Verify before signing**: Check the escrow contents before completing

### Multi-Signature Flow

```
Party A                    Contract                    Party B
   |                          |                          |
   |------ initiateEscrow --->|                          |
   |                          |<---- recipientDeposit ---|
   |                          |                          |
   |---- completeEscrow ----->|                          |
   |     (partial sign)       |                          |
   |                          |                          |
   |          signedTxByA -------------------------------->|
   |                          |                          |
   |                          |<----- signTx + submit ---|
   |                          |       (both signatures)  |
   |<----- Party B's assets --|---- Party A's assets --->|
```

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/escrow)
* [Successful Completion Example](https://preprod.cardanoscan.io/transaction/019b6ba41ee0a9de90068fe5c1eb1fd81489be5d2402bd560b548e1cd7f22056)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)


# Giftcard Contract
URL: /smart-contracts/giftcard

Create redeemable gift cards that hold assets and can be claimed by any recipient

***

title: "Giftcard Contract"
description: "Create redeemable gift cards that hold assets and can be claimed by any recipient"
------------------------------------------------------------------------------------------------

import Link from "next/link";

The Giftcard contract lets you create gift cards that hold assets. When you create a gift card, the contract mints a unique token and locks your assets. Anyone with the gift card token can redeem it to claim the locked assets, burning the token in the process.

## Use Cases

* Crypto gift cards for friends and family
* Promotional token distributions
* Prize redemption systems
* Prepaid service credits
* Voucher and coupon systems

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshGiftCardContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshGiftCardContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});
```

## Contract Logic

The Giftcard contract uses a mint-and-lock pattern:

| Action     | Token                | Assets                     |
| ---------- | -------------------- | -------------------------- |
| **Create** | Mint gift card token | Lock assets in contract    |
| **Redeem** | Burn gift card token | Release assets to redeemer |

### How It Works

1. **Creation**: You specify a token name and assets. The contract mints a unique NFT-like token and locks your assets.
2. **Distribution**: You send the gift card token to a recipient (or keep it for later).
3. **Redemption**: The token holder calls redeem. The contract burns the token and sends the locked assets to their wallet.

### Security Model

* Only the token holder can redeem the gift card
* The token is burned on redemption, preventing double-spending
* Assets are locked until redemption or cancellation

## Available Actions

### Create Giftcard

Create a new gift card by minting a token and locking assets.

#### Method Signature

```typescript
contract.createGiftCard(tokenName: string, giftValue: Asset[]): Promise<string>
```

#### Parameters

| Parameter   | Type      | Description                              |
| ----------- | --------- | ---------------------------------------- |
| `tokenName` | `string`  | Name for the gift card token             |
| `giftValue` | `Asset[]` | Array of assets to lock in the gift card |

#### Code Example

```typescript
import { MeshGiftCardContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshGiftCardContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Define gift card value (10 ADA)
const giftValue: Asset[] = [
  {
    unit: "lovelace",
    quantity: "10000000",
  },
];

// Create the gift card
const tx = await contract.createGiftCard("Birthday_Gift_2024", giftValue);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Gift card created. Transaction hash:", txHash);
```

#### What Happens on Success

* A unique token named `Birthday_Gift_2024` is minted
* 10 ADA is locked in the contract
* The token is sent to your wallet
* You can transfer this token to give the gift card to someone

### Redeem Giftcard

Redeem a gift card to claim the locked assets.

#### Method Signature

```typescript
contract.redeemGiftCard(giftCardUtxo: UTxO): Promise<string>
```

#### Parameters

| Parameter      | Type   | Description                                     |
| -------------- | ------ | ----------------------------------------------- |
| `giftCardUtxo` | `UTxO` | The UTxO containing the locked gift card assets |

#### Code Example

```typescript
import { MeshGiftCardContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshGiftCardContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Get the gift card UTxO from the creation transaction
const giftCardUtxo = await contract.getUtxoByTxHash("<creation-transaction-hash>");

// Redeem the gift card
const tx = await contract.redeemGiftCard(giftCardUtxo);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Gift card redeemed. Transaction hash:", txHash);
```

#### What Happens on Success

* The gift card token is burned
* Locked assets transfer to the redeemer's wallet
* View example: [Successful redemption on Cardanoscan](https://preprod.cardanoscan.io/transaction/2bc1c39337de3ebcb2650aa41c73b1a873288282b8c7e1ed130d31f5c34090b7)

## Full Working Example

```typescript
import { MeshGiftCardContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function giftcardDemo() {
  // Connect wallet (gift card creator)
  const creatorWallet = await MeshCardanoBrowserWallet.enable("eternl");

  // Initialize provider
  const provider = new BlockfrostProvider("<Your-API-Key>");

  const meshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
  });

  // Initialize contract
  const contract = new MeshGiftCardContract({
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: creatorWallet,
    networkId: 0,
  });

  // Step 1: Create a gift card with 5 ADA
  const giftValue: Asset[] = [
    {
      unit: "lovelace",
      quantity: "5000000",
    },
  ];

  const createTx = await contract.createGiftCard("Holiday_Gift", giftValue);
  const signedCreateTx = await creatorWallet.signTx(createTx);
  const createTxHash = await creatorWallet.submitTx(signedCreateTx);

  console.log("Gift card created:", createTxHash);

  // Wait for confirmation
  await new Promise((resolve) => setTimeout(resolve, 60000));

  // Step 2: Recipient redeems (switch wallet in production)
  const recipientWallet = await MeshCardanoBrowserWallet.enable("nami");

  const recipientContract = new MeshGiftCardContract({
    mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
    fetcher: provider,
    wallet: recipientWallet,
    networkId: 0,
  });

  const giftCardUtxo = await recipientContract.getUtxoByTxHash(createTxHash);

  const redeemTx = await recipientContract.redeemGiftCard(giftCardUtxo);
  const signedRedeemTx = await recipientWallet.signTx(redeemTx);
  const redeemTxHash = await recipientWallet.submitTx(signedRedeemTx);

  console.log("Gift card redeemed:", redeemTxHash);
}

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

## Multiple Asset Gift Cards

You can create gift cards containing multiple assets:

```typescript
const giftValue: Asset[] = [
  {
    unit: "lovelace",
    quantity: "10000000", // 10 ADA
  },
  {
    unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
    quantity: "1", // 1 NFT
  },
  {
    unit: "abc123...tokenunit",
    quantity: "100", // 100 fungible tokens
  },
];

const tx = await contract.createGiftCard("Super_Bundle_Gift", giftValue);
```

## Finding Gift Card UTxOs

You can search for gift card UTxOs by token name instead of transaction hash:

```typescript
// Custom function to find gift card by token name
async function findGiftCardByName(
  contract: MeshGiftCardContract,
  tokenName: string
): Promise<UTxO | undefined> {
  const scriptAddress = contract.getScriptAddress();
  const utxos = await provider.fetchAddressUTxOs(scriptAddress);

  return utxos.find((utxo) =>
    utxo.output.amount.some((asset) =>
      asset.unit.includes(Buffer.from(tokenName).toString("hex"))
    )
  );
}

const giftCardUtxo = await findGiftCardByName(contract, "Birthday_Gift_2024");
```

## Troubleshooting

### Common Errors

| Error                      | Cause                      | Solution                                             |
| -------------------------- | -------------------------- | ---------------------------------------------------- |
| `Script validation failed` | Token not in wallet        | Ensure you hold the gift card token before redeeming |
| `UTxO not found`           | Gift card already redeemed | Each gift card can only be redeemed once             |
| `Insufficient funds`       | Not enough ADA for fees    | Ensure wallet has ADA for transaction fees           |
| `Token minting failed`     | Invalid token name         | Use alphanumeric characters and underscores          |

### Debugging Tips

1. **Verify token ownership**: Check your wallet contains the gift card token before redeeming
2. **Check UTxO status**: Use `getUtxoByTxHash()` to verify the gift card still exists
3. **Inspect transaction**: View the creation transaction on a block explorer to see the token policy ID
4. **Use unique names**: Each gift card should have a unique token name

### Token Name Best Practices

```typescript
// Good token names
"Birthday_Gift_2024"
"Holiday_Bonus"
"Prize_Winner_001"

// Avoid these
"Gift Card"      // Spaces not recommended
"gift@card#1"    // Special characters may cause issues
""               // Empty names will fail
```

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/giftcard)
* [Successful Redemption Example](https://preprod.cardanoscan.io/transaction/2bc1c39337de3ebcb2650aa41c73b1a873288282b8c7e1ed130d31f5c34090b7)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)


# Hello World Contract
URL: /smart-contracts/hello-world

Lock and unlock assets on Cardano using a simple smart contract. Learn Plutus validators with Mesh SDK.

***

title: "Hello World Contract"
description: "Lock and unlock assets on Cardano using a simple smart contract. Learn Plutus validators with Mesh SDK."
----------------------------------------------------------------------------------------------------------------------

import Link from "next/link";

The Hello World contract is an introductory smart contract that demonstrates asset locking and unlocking on Cardano. You lock assets into the contract, and only the original signer can unlock them by providing the message "Hello, World!".

## Use Cases

* Learning smart contract basics
* Understanding datum and redeemer patterns
* Testing wallet integrations
* Prototyping lock/unlock mechanisms

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshHelloWorldContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshHelloWorldContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});
```

## Contract Logic

The Hello World contract enforces two conditions for unlocking assets:

| Condition                | Description                                                              |
| ------------------------ | ------------------------------------------------------------------------ |
| **Signer Verification**  | The transaction must be signed by the same wallet that locked the assets |
| **Message Verification** | The redeemer must contain the exact message "Hello, World!"              |

Both conditions must be satisfied for the unlock to succeed.

### On-Chain Validator

```rust
validator hello_world {
  spend(
    datum_opt: Option<Datum>,
    redeemer: Redeemer,
    _input: OutputReference,
    tx: Transaction,
  ) {
    expect Some(datum) = datum_opt
    let must_say_hello = redeemer.msg == "Hello, World!"
    let must_be_signed = list.has(tx.extra_signatories, datum.owner)
    must_say_hello && must_be_signed
  }

  else(_) {
    fail
  }
}
```

### Datum Structure

```rust
pub type Datum {
  owner: VerificationKeyHash,
}
```

The datum stores the public key hash of the wallet that locked the assets. This value is checked during unlock to verify the signer.

## Available Actions

### Lock Assets

Lock assets into the contract. The contract stores your public key hash in the datum for later verification.

#### Method Signature

```typescript
contract.lockAsset(assets: Asset[]): Promise<string>
```

#### Parameters

| Parameter | Type      | Description                                      |
| --------- | --------- | ------------------------------------------------ |
| `assets`  | `Asset[]` | Array of assets to lock (lovelace and/or tokens) |

#### Code Example

```typescript
import { MeshHelloWorldContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshHelloWorldContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Define assets to lock
const assets: Asset[] = [
  {
    unit: "lovelace",
    quantity: "5000000", // 5 ADA
  },
];

// Lock assets
const tx = await contract.lockAsset(assets);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Assets locked. Transaction hash:", txHash);
```

#### What Happens on Success

* Assets transfer from your wallet to the contract address
* Your public key hash is stored in the datum
* You receive a transaction hash to reference when unlocking

### Unlock Assets

Unlock previously locked assets by providing the UTxO reference and the correct message.

#### Method Signature

```typescript
contract.unlockAsset(utxo: UTxO, message: string): Promise<string>
```

#### Parameters

| Parameter | Type     | Description                            |
| --------- | -------- | -------------------------------------- |
| `utxo`    | `UTxO`   | The UTxO containing your locked assets |
| `message` | `string` | Must be exactly "Hello, World!"        |

#### Code Example

```typescript
import { MeshHelloWorldContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshHelloWorldContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Get the UTxO from the lock transaction
const utxo = await contract.getUtxoByTxHash("<your-lock-transaction-hash>");

// Unlock with the correct message
const tx = await contract.unlockAsset(utxo, "Hello, World!");
const signedTx = await wallet.signTx(tx, true);
const txHash = await wallet.submitTx(signedTx);

console.log("Assets unlocked. Transaction hash:", txHash);
```

#### What Happens on Success

* The contract validates your signature matches the datum owner
* The contract validates the message equals "Hello, World!"
* Assets transfer back to your wallet

## Full Working Example

```typescript
import { MeshHelloWorldContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function helloWorldDemo() {
  // Connect wallet
  const wallet = await MeshCardanoBrowserWallet.enable("eternl");

  // Initialize provider
  const provider = new BlockfrostProvider("<Your-API-Key>");

  const meshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
  });

  // Initialize contract
  const contract = new MeshHelloWorldContract({
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  });

  // Step 1: Lock assets
  const assets: Asset[] = [
    {
      unit: "lovelace",
      quantity: "5000000",
    },
  ];

  const lockTx = await contract.lockAsset(assets);
  const signedLockTx = await wallet.signTx(lockTx);
  const lockTxHash = await wallet.submitTx(signedLockTx);

  console.log("Lock transaction submitted:", lockTxHash);

  // Wait for confirmation (in production, poll for confirmation)
  await new Promise((resolve) => setTimeout(resolve, 60000));

  // Step 2: Unlock assets
  const utxo = await contract.getUtxoByTxHash(lockTxHash);

  const unlockTx = await contract.unlockAsset(utxo, "Hello, World!");
  const signedUnlockTx = await wallet.signTx(unlockTx, true);
  const unlockTxHash = await wallet.submitTx(signedUnlockTx);

  console.log("Unlock transaction submitted:", unlockTxHash);
}

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

## Troubleshooting

### Common Errors

| Error                      | Cause                    | Solution                                                                            |
| -------------------------- | ------------------------ | ----------------------------------------------------------------------------------- |
| `Script validation failed` | Wrong message provided   | Ensure you pass exactly "Hello, World!" with correct capitalization and punctuation |
| `Missing required signer`  | Wrong wallet signing     | Use the same wallet that locked the assets                                          |
| `UTxO not found`           | Invalid transaction hash | Verify the transaction hash and wait for blockchain confirmation                    |
| `Insufficient funds`       | Not enough ADA for fees  | Ensure your wallet has enough ADA to cover transaction fees                         |

### Debugging Tips

1. **Verify the UTxO exists**: Use `contract.getUtxoByTxHash()` before attempting unlock
2. **Check the message**: The message is case-sensitive and must include the comma and exclamation mark
3. **Confirm wallet address**: The unlock must be signed by the same address that performed the lock
4. **Wait for confirmation**: Allow 1-2 minutes after locking before attempting to unlock

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/hello-world)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)
* [Blockfrost Provider Setup](/providers)


# Smart Contracts
URL: /smart-contracts

Production-ready smart contracts for Cardano with complete documentation, TypeScript SDK, and live demos

***

title: "Smart Contracts"
description: "Production-ready smart contracts for Cardano with complete documentation, TypeScript SDK, and live demos"
icon: DocumentCheckIcon
-----------------------

import { linksSmartContracts } from "@/data/links-smart-contracts";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

Mesh provides a suite of open-source, audited smart contracts that you can deploy to Cardano mainnet or testnet. Each contract includes TypeScript bindings, comprehensive documentation, and working examples.

## Available Contracts

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksSmartContracts.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Quick Start

Install the contracts package to get started:

```bash
npm install @meshsdk/contract @meshsdk/core
```

Every contract follows the same initialization pattern:

```typescript
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// 1. Set up your provider
const provider = new BlockfrostProvider("<Your-API-Key>");

// 2. Create a transaction builder
const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

// 3. Initialize any contract with the same config
const contract = new MeshContractName({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet, // Your connected wallet
  networkId: 0,   // 0 for testnet, 1 for mainnet
});
```

## Contract Categories

| Category             | Contracts                      | Use Cases                                |
| -------------------- | ------------------------------ | ---------------------------------------- |
| **Asset Management** | Hello World, Vesting, Giftcard | Lock and unlock assets with conditions   |
| **Trading**          | Marketplace, Swap, Escrow      | Buy, sell, and exchange assets           |
| **Payments**         | Payment Splitter               | Split payments among multiple recipients |
| **NFTs**             | Plutus NFT, Content Ownership  | Mint NFTs with on-chain logic            |

## Network Support

All contracts work on:

* **Preprod Testnet** (networkId: 0) - For development and testing
* **Mainnet** (networkId: 1) - For production deployments

## Source Code

All on-chain (Aiken) and off-chain (TypeScript) code is open-source and available on [GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src).


# NFT Marketplace Contract
URL: /smart-contracts/marketplace

Build an NFT marketplace to list, buy, update, and cancel asset listings

***

title: "NFT Marketplace Contract"
description: "Build an NFT marketplace to list, buy, update, and cancel asset listings"
---------------------------------------------------------------------------------------

import Link from "next/link";

The Marketplace contract enables you to build a decentralized NFT marketplace on Cardano. Sellers list assets at a specified price, and buyers can purchase them by paying the listed amount. The marketplace owner receives a configurable fee on each sale.

## Use Cases

* NFT marketplaces
* Digital collectible trading platforms
* Tokenized asset exchanges
* Secondary market platforms
* Auction-style sales (with extensions)

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshMarketplaceContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshMarketplaceContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  "addr_test1qp...marketplace_owner_address", // Fee recipient
  200 // Fee: 200 basis points = 2%
);
```

### Configuration Parameters

| Parameter                 | Type     | Description                              |
| ------------------------- | -------- | ---------------------------------------- |
| `ownerAddress`            | `string` | Address that receives marketplace fees   |
| `feePercentageBasisPoint` | `number` | Fee in basis points (100 = 1%, 200 = 2%) |

## Contract Logic

The Marketplace contract supports four operations:

| Action     | Description                                | Who Can Execute |
| ---------- | ------------------------------------------ | --------------- |
| **List**   | Lock an asset in the contract with a price | Asset owner     |
| **Buy**    | Purchase a listed asset                    | Anyone          |
| **Update** | Change the listing price                   | Original seller |
| **Cancel** | Remove listing and retrieve asset          | Original seller |

### Fee Structure

When a buyer purchases an asset:

1. Seller receives: `listing_price - fee`
2. Marketplace owner receives: `listing_price * (fee_basis_points / 10000)`

Example with 2% fee on 100 ADA sale:

* Seller receives: 98 ADA
* Marketplace owner receives: 2 ADA

## Available Actions

### List Asset

List an asset for sale on the marketplace.

#### Method Signature

```typescript
contract.listAsset(asset: string, price: number): Promise<string>
```

#### Parameters

| Parameter | Type     | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `asset`   | `string` | The asset unit (policy ID + asset name in hex) |
| `price`   | `number` | Listing price in lovelace                      |

#### Code Example

```typescript
import { MeshMarketplaceContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshMarketplaceContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  "addr_test1qp...marketplace_owner",
  200
);

// List an NFT for 10 ADA
const assetUnit = "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e";
const priceInLovelace = 10000000; // 10 ADA

const tx = await contract.listAsset(assetUnit, priceInLovelace);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Asset listed. Transaction hash:", txHash);
```

#### What Happens on Success

* Asset transfers from your wallet to the contract address
* Listing price is stored in the datum
* Anyone can now purchase the asset at the listed price

### Buy Asset

Purchase a listed asset from the marketplace.

#### Method Signature

```typescript
contract.purchaseAsset(utxo: UTxO): Promise<string>
```

#### Parameters

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| `utxo`    | `UTxO` | The UTxO containing the listed asset |

#### Code Example

```typescript
import { MeshMarketplaceContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshMarketplaceContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  "addr_test1qp...marketplace_owner",
  200
);

// Get the listing UTxO
const utxo = await contract.getUtxoByTxHash("<listing-transaction-hash>");

// Purchase the asset
const tx = await contract.purchaseAsset(utxo);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Asset purchased. Transaction hash:", txHash);
```

#### What Happens on Success

* Buyer pays the listing price
* Asset transfers to the buyer's wallet
* Seller receives the sale price minus fee
* Marketplace owner receives the fee
* View example: [Successful purchase on Cardanoscan](https://preprod.cardanoscan.io/transaction/f9f7ddbbbe1c34717134c89c343aaa27d4c5f62e6e8a127757400ac8d45e64e8)

### Update Listing

Change the price of an existing listing.

#### Method Signature

```typescript
contract.relistAsset(utxo: UTxO, newListPrice: number): Promise<string>
```

#### Parameters

| Parameter      | Type     | Description                          |
| -------------- | -------- | ------------------------------------ |
| `utxo`         | `UTxO`   | The UTxO containing the listed asset |
| `newListPrice` | `number` | New listing price in lovelace        |

#### Code Example

```typescript
import { MeshMarketplaceContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshMarketplaceContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  "addr_test1qp...marketplace_owner",
  200
);

// Get the listing UTxO
const utxo = await contract.getUtxoByTxHash("<listing-transaction-hash>");

// Update price to 20 ADA
const newPrice = 20000000;

const tx = await contract.relistAsset(utxo, newPrice);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Listing updated. Transaction hash:", txHash);
```

#### What Happens on Success

* Old listing is consumed
* New listing is created with updated price
* Asset remains in the contract

### Cancel Listing

Remove a listing and retrieve your asset.

#### Method Signature

```typescript
contract.delistAsset(utxo: UTxO): Promise<string>
```

#### Parameters

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| `utxo`    | `UTxO` | The UTxO containing the listed asset |

#### Code Example

```typescript
import { MeshMarketplaceContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshMarketplaceContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  "addr_test1qp...marketplace_owner",
  200
);

// Get the listing UTxO
const utxo = await contract.getUtxoByTxHash("<listing-transaction-hash>");

// Cancel the listing
const tx = await contract.delistAsset(utxo);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Listing cancelled. Transaction hash:", txHash);
```

#### What Happens on Success

* Listing is removed from the contract
* Asset returns to the seller's wallet
* No fees are charged

## Full Working Example

```typescript
import { MeshMarketplaceContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function marketplaceDemo() {
  // Connect seller wallet
  const sellerWallet = await MeshCardanoBrowserWallet.enable("eternl");

  // Initialize provider
  const provider = new BlockfrostProvider("<Your-API-Key>");

  const meshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
  });

  // Initialize marketplace (2% fee)
  const marketplaceOwner = "addr_test1qp...owner_address";
  const contract = new MeshMarketplaceContract(
    {
      mesh: meshTxBuilder,
      fetcher: provider,
      wallet: sellerWallet,
      networkId: 0,
    },
    marketplaceOwner,
    200
  );

  // Step 1: Seller lists an NFT
  const assetUnit = "d9312da...68546f6b656e";
  const listPrice = 10000000; // 10 ADA

  const listTx = await contract.listAsset(assetUnit, listPrice);
  const signedListTx = await sellerWallet.signTx(listTx);
  const listTxHash = await sellerWallet.submitTx(signedListTx);

  console.log("Listed:", listTxHash);

  // Wait for confirmation
  await new Promise((resolve) => setTimeout(resolve, 60000));

  // Step 2: Buyer purchases (switch wallet in production)
  const buyerWallet = await MeshCardanoBrowserWallet.enable("nami");

  const buyerContract = new MeshMarketplaceContract(
    {
      mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
      fetcher: provider,
      wallet: buyerWallet,
      networkId: 0,
    },
    marketplaceOwner,
    200
  );

  const listingUtxo = await buyerContract.getUtxoByTxHash(listTxHash);
  const buyTx = await buyerContract.purchaseAsset(listingUtxo);
  const signedBuyTx = await buyerWallet.signTx(buyTx);
  const buyTxHash = await buyerWallet.submitTx(signedBuyTx);

  console.log("Purchased:", buyTxHash);
}

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

## Troubleshooting

### Common Errors

| Error                      | Cause                                   | Solution                                      |
| -------------------------- | --------------------------------------- | --------------------------------------------- |
| `Script validation failed` | Insufficient payment                    | Ensure buyer pays the exact listing price     |
| `Missing required signer`  | Wrong wallet for update/cancel          | Only the original seller can update or cancel |
| `UTxO not found`           | Listing already purchased or cancelled  | Verify the listing still exists               |
| `Asset not owned`          | Trying to list an asset you do not have | Check your wallet contains the asset          |

### Debugging Tips

1. **Verify asset ownership**: Ensure the asset is in your wallet before listing
2. **Check UTxO status**: Listings may have been purchased by others
3. **Confirm marketplace config**: Ensure owner address and fee are set correctly
4. **Validate asset unit**: The unit must be the complete policy ID + asset name in hex

### Fee Calculation

```typescript
const listingPrice = 10000000; // 10 ADA
const feeBasisPoints = 200;     // 2%

const feeAmount = (listingPrice * feeBasisPoints) / 10000;
const sellerReceives = listingPrice - feeAmount;

console.log(`Fee: ${feeAmount / 1000000} ADA`);           // 0.2 ADA
console.log(`Seller receives: ${sellerReceives / 1000000} ADA`); // 9.8 ADA
```

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/marketplace)
* [Successful Purchase Example](https://preprod.cardanoscan.io/transaction/f9f7ddbbbe1c34717134c89c343aaa27d4c5f62e6e8a127757400ac8d45e64e8)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)


# Payment Splitter Contract
URL: /smart-contracts/payment-splitter

Automatically split payments equally among multiple recipients

***

title: "Payment Splitter Contract"
description: "Automatically split payments equally among multiple recipients"
-----------------------------------------------------------------------------

import Link from "next/link";

The Payment Splitter contract distributes funds equally among a predefined list of payees. Send lovelace to the contract, and any payee can trigger a payout that splits the balance evenly among all recipients.

## Use Cases

* Shared project donation addresses
* Revenue splitting for collaborators
* Team payment distribution
* Royalty sharing agreements
* Automated expense splitting

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshPaymentSplitterContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const payees = [
  "addr_test1qp...alice_address",
  "addr_test1qp...bob_address",
  "addr_test1qp...charlie_address",
  "addr_test1qp...diana_address",
];

const contract = new MeshPaymentSplitterContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  payees
);
```

### Configuration Parameters

| Parameter | Type       | Description                                     |
| --------- | ---------- | ----------------------------------------------- |
| `payees`  | `string[]` | Array of Bech32 addresses that receive payments |

## Contract Logic

The Payment Splitter enforces equal distribution:

| Rule                  | Description                                       |
| --------------------- | ------------------------------------------------- |
| **Fixed Payees**      | Recipients are defined at contract initialization |
| **Equal Split**       | All payees receive exactly the same amount        |
| **Payee Trigger**     | Only a payee can trigger the payout               |
| **Full Distribution** | The entire contract balance is distributed        |

### Split Calculation

```
amount_per_payee = total_balance / number_of_payees
```

For example, with 4 payees and 100 ADA in the contract:

* Each payee receives: 100 ADA / 4 = 25 ADA

### Validation Rules

1. Transaction must be signed by one of the payees
2. All outputs must go to payee addresses
3. All payees must receive equal amounts
4. The sum must equal the contract balance (minus fees)

## Available Actions

### Send Lovelace to Splitter

Deposit lovelace into the payment splitter contract.

#### Method Signature

```typescript
contract.sendLovelaceToSplitter(lovelaceAmount: number): Promise<string>
```

#### Parameters

| Parameter        | Type     | Description                                |
| ---------------- | -------- | ------------------------------------------ |
| `lovelaceAmount` | `number` | Amount of lovelace to send to the contract |

#### Code Example

```typescript
import { MeshPaymentSplitterContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const payees = [
  "addr_test1qp...alice",
  "addr_test1qp...bob",
  "addr_test1qp...charlie",
  "addr_test1qp...diana",
];

const contract = new MeshPaymentSplitterContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  payees
);

// Send 20 ADA to the splitter (will be split 4 ways = 5 ADA each)
const lovelaceAmount = 20000000; // 20 ADA

const tx = await contract.sendLovelaceToSplitter(lovelaceAmount);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Funds deposited. Transaction hash:", txHash);
```

#### What Happens on Success

* Lovelace transfers from your wallet to the contract address
* Funds accumulate until a payee triggers payout
* Anyone can send funds to the contract (not just payees)

### Trigger Payout

Distribute the contract balance equally among all payees.

#### Method Signature

```typescript
contract.triggerPayout(): Promise<string>
```

#### Parameters

None. The contract distributes its entire balance.

#### Code Example

```typescript
import { MeshPaymentSplitterContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract (must be a payee's wallet)
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const payees = [
  "addr_test1qp...alice",
  "addr_test1qp...bob",
  "addr_test1qp...charlie",
  "addr_test1qp...diana",
];

const contract = new MeshPaymentSplitterContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: payeeWallet, // Must be one of the payees
    networkId: 0,
  },
  payees
);

// Trigger the payout
const tx = await contract.triggerPayout();
const signedTx = await payeeWallet.signTx(tx, true);
const txHash = await payeeWallet.submitTx(signedTx);

console.log("Payout triggered. Transaction hash:", txHash);
```

#### What Happens on Success

* Contract balance is divided equally among all payees
* Each payee receives their share
* Contract balance becomes zero
* New deposits can be made and split again

## Full Working Example

```typescript
import { MeshPaymentSplitterContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function paymentSplitterDemo() {
  // Connect wallet
  const wallet = await MeshCardanoBrowserWallet.enable("eternl");

  // Initialize provider
  const provider = new BlockfrostProvider("<Your-API-Key>");

  const meshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
  });

  // Define payees (4 team members)
  const payees = [
    "addr_test1qp...alice",
    "addr_test1qp...bob",
    "addr_test1qp...charlie",
    "addr_test1qp...diana",
  ];

  // Initialize contract
  const contract = new MeshPaymentSplitterContract(
    {
      mesh: meshTxBuilder,
      fetcher: provider,
      wallet: wallet,
      networkId: 0,
    },
    payees
  );

  // Step 1: Donor sends 16 ADA to the splitter
  const depositTx = await contract.sendLovelaceToSplitter(16000000);
  const signedDepositTx = await wallet.signTx(depositTx);
  const depositTxHash = await wallet.submitTx(signedDepositTx);

  console.log("Deposited:", depositTxHash);

  // Wait for confirmation
  await new Promise((resolve) => setTimeout(resolve, 60000));

  // Step 2: A payee triggers the payout (each gets 4 ADA)
  // In production, switch to a payee's wallet
  const payoutTx = await contract.triggerPayout();
  const signedPayoutTx = await wallet.signTx(payoutTx, true);
  const payoutTxHash = await wallet.submitTx(signedPayoutTx);

  console.log("Payout triggered:", payoutTxHash);
  console.log("Each payee receives: 4 ADA");
}

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

## Accumulating Donations

The contract can receive multiple deposits before triggering a payout:

```typescript
// Donation 1: 10 ADA
await contract.sendLovelaceToSplitter(10000000);

// Donation 2: 5 ADA
await contract.sendLovelaceToSplitter(5000000);

// Donation 3: 5 ADA
await contract.sendLovelaceToSplitter(5000000);

// Total in contract: 20 ADA
// Trigger payout: each of 4 payees gets 5 ADA
await contract.triggerPayout();
```

## Minimum Payout Considerations

Ensure the contract balance is large enough to cover:

1. Minimum UTxO value for each output (approximately 1 ADA per payee)
2. Transaction fees

```typescript
const minPerPayee = 1000000; // 1 ADA minimum
const numPayees = 4;
const minDeposit = minPerPayee * numPayees + 500000; // 4.5 ADA minimum

// Always deposit at least this amount
await contract.sendLovelaceToSplitter(minDeposit);
```

## Troubleshooting

### Common Errors

| Error                      | Cause                     | Solution                                           |
| -------------------------- | ------------------------- | -------------------------------------------------- |
| `Script validation failed` | Unequal distribution      | Contract enforces equal splits; check calculations |
| `Missing required signer`  | Non-payee triggering      | Only payees can trigger payouts                    |
| `Insufficient funds`       | Balance too low           | Ensure enough funds for all payees + fees          |
| `Output below minimum`     | Balance divided too small | Deposit more funds before payout                   |

### Debugging Tips

1. **Verify payee list**: Ensure all payee addresses are correct and match initialization
2. **Check wallet is a payee**: The wallet triggering payout must be in the payee list
3. **Calculate minimum deposit**: `(min_utxo * num_payees) + fees`
4. **Use partial signing**: Always pass `true` to `signTx()` for payout transactions

### Calculating Split Amounts

```typescript
const contractBalance = 20000000; // 20 ADA
const numPayees = 4;
const estimatedFees = 200000; // ~0.2 ADA

const distributableAmount = contractBalance - estimatedFees;
const amountPerPayee = Math.floor(distributableAmount / numPayees);

console.log(`Each payee receives: ${amountPerPayee / 1000000} ADA`);
// Output: Each payee receives: 4.95 ADA
```

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/payment-splitter)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)
* [Providers Setup Guide](/providers)


# NFT Minting Machine
URL: /smart-contracts/plutus-nft

Mint NFTs with auto-incrementing indexes using an on-chain oracle

***

title: "NFT Minting Machine"
description: "Mint NFTs with auto-incrementing indexes using an on-chain oracle"
--------------------------------------------------------------------------------

import Link from "next/link";

The NFT Minting Machine contract enables you to mint NFTs with automatically incrementing indexes. Each new NFT gets the next number in sequence, tracked by an on-chain oracle. This is ideal for collections where you want numbered editions like "Mesh Token #1", "Mesh Token #2", etc.

## Use Cases

* Numbered NFT collections
* Sequential edition minting
* Limited series with verifiable order
* Collection drops with provable mint order
* Membership cards with sequential IDs

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Setup Overview

The NFT Minting Machine requires a three-step setup:

| Step | Action         | Purpose                                             |
| ---- | -------------- | --------------------------------------------------- |
| 1    | Setup Oracle   | Create the one-time minting policy and oracle token |
| 2    | Save paramUtxo | Store the oracle reference for future mints         |
| 3    | Mint NFTs      | Use the oracle to mint sequentially numbered NFTs   |

## Contract Logic

The contract uses an oracle pattern to track minting state:

| Component          | Description                                           |
| ------------------ | ----------------------------------------------------- |
| **Oracle Token**   | A one-time minted NFT that holds the collection state |
| **Oracle Datum**   | Stores the current NFT index and collection info      |
| **Minting Policy** | Ensures each NFT is numbered correctly                |

### How It Works

1. **Setup**: Mint an oracle token that stores `nftIndex = 0`
2. **First Mint**: Oracle shows index 0, mint NFT #0, update oracle to index 1
3. **Second Mint**: Oracle shows index 1, mint NFT #1, update oracle to index 2
4. **And so on**: Each mint increments the oracle index

## Available Actions

### Setup Oracle

Initialize the minting machine by creating the oracle token. This is a one-time setup.

#### Method Signature

```typescript
contract.setupOracle(priceLovelace: number): Promise<{ tx: string; paramUtxo: { outputIndex: number; txHash: string } }>
```

#### Parameters

| Parameter       | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `priceLovelace` | `number` | Price per NFT in lovelace |

#### Code Example

```typescript
import { MeshPlutusNFTContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
  verbose: true,
});

// Initialize contract with collection name
const contract = new MeshPlutusNFTContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  {
    collectionName: "MeshCollection",
  }
);

// Setup oracle with 10 ADA mint price
const { tx, paramUtxo } = await contract.setupOracle(10000000);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Oracle setup complete. Transaction hash:", txHash);
console.log("IMPORTANT - Save this paramUtxo:", JSON.stringify(paramUtxo));
// Example: {"outputIndex":0,"txHash":"63dbd563ee9979574401599a42841e0d5b63a691af95df863cbf37d5cb44a558"}
```

#### What Happens on Success

* Oracle token is minted
* Collection state is initialized with index 0
* You receive `paramUtxo` - **save this for all future mints**

### Mint NFT

Mint a new NFT with the next sequential index.

#### Method Signature

```typescript
contract.mintPlutusNFT(assetMetadata: object): Promise<string>
```

#### Parameters

| Parameter       | Type     | Description                   |
| --------------- | -------- | ----------------------------- |
| `assetMetadata` | `object` | CIP-25 compliant NFT metadata |

#### Code Example

```typescript
import { MeshPlutusNFTContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
  verbose: true,
});

// Initialize contract with collection name AND paramUtxo from setup
const contract = new MeshPlutusNFTContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  {
    collectionName: "MeshCollection",
    paramUtxo: {
      outputIndex: 0,
      txHash: "63dbd563ee9979574401599a42841e0d5b63a691af95df863cbf37d5cb44a558",
    },
  }
);

// Get current index from oracle
const oracleData = await contract.getOracleData();

// Define NFT metadata with current index
const assetMetadata = {
  name: `Mesh Token ${oracleData.nftIndex}`,
  image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
  description: `Mesh NFT Collection - Edition #${oracleData.nftIndex}`,
  attributes: [
    { trait_type: "Edition", value: oracleData.nftIndex },
    { trait_type: "Collection", value: "MeshCollection" },
  ],
};

// Mint the NFT
const tx = await contract.mintPlutusNFT(assetMetadata);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Minted NFT #${oracleData.nftIndex}. Transaction hash:`, txHash);
```

#### What Happens on Success

* New NFT is minted with the current index
* Oracle index increments by 1
* NFT is sent to the minter's wallet
* Minting price (if set) is collected

### Get Oracle Data

Fetch the current oracle state including the next NFT index.

#### Method Signature

```typescript
contract.getOracleData(): Promise<{ nftIndex: number; price: number }>
```

#### Code Example

```typescript
import { MeshPlutusNFTContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
  verbose: true,
});

// Initialize contract with paramUtxo
const contract = new MeshPlutusNFTContract(
  {
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: wallet,
    networkId: 0,
  },
  {
    collectionName: "MeshCollection",
    paramUtxo: {
      outputIndex: 0,
      txHash: "63dbd563ee9979574401599a42841e0d5b63a691af95df863cbf37d5cb44a558",
    },
  }
);

// Get oracle data
const oracleData = await contract.getOracleData();

console.log("Current NFT Index:", oracleData.nftIndex);
console.log("Mint Price:", oracleData.price / 1000000, "ADA");
```

#### Return Value

```typescript
{
  nftIndex: 5,      // Next NFT will be #5
  price: 10000000   // 10 ADA mint price
}
```

## Full Working Example

```typescript
import { MeshPlutusNFTContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function nftMintingMachineDemo() {
  // Connect wallet
  const wallet = await MeshCardanoBrowserWallet.enable("eternl");

  // Initialize provider
  const provider = new BlockfrostProvider("<Your-API-Key>");

  // Step 1: Setup Oracle (ONE TIME ONLY)
  const setupMeshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
    verbose: true,
  });

  const setupContract = new MeshPlutusNFTContract(
    {
      mesh: setupMeshTxBuilder,
      fetcher: provider,
      wallet: wallet,
      networkId: 0,
    },
    {
      collectionName: "MeshCollection",
    }
  );

  // Setup oracle with 10 ADA mint price
  const { tx: setupTx, paramUtxo } = await setupContract.setupOracle(10000000);
  const signedSetupTx = await wallet.signTx(setupTx);
  const setupTxHash = await wallet.submitTx(signedSetupTx);

  console.log("Oracle setup:", setupTxHash);
  console.log("paramUtxo:", JSON.stringify(paramUtxo));

  // Wait for confirmation
  await new Promise((resolve) => setTimeout(resolve, 60000));

  // Step 2: Mint NFTs (can be done multiple times)
  const mintMeshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
    verbose: true,
  });

  const mintContract = new MeshPlutusNFTContract(
    {
      mesh: mintMeshTxBuilder,
      fetcher: provider,
      wallet: wallet,
      networkId: 0,
    },
    {
      collectionName: "MeshCollection",
      paramUtxo: paramUtxo, // Use paramUtxo from setup
    }
  );

  // Get current index
  const oracleData = await mintContract.getOracleData();

  // Define metadata
  const assetMetadata = {
    name: `Mesh Token ${oracleData.nftIndex}`,
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    description: `Edition #${oracleData.nftIndex} of MeshCollection`,
  };

  // Mint
  const mintTx = await mintContract.mintPlutusNFT(assetMetadata);
  const signedMintTx = await wallet.signTx(mintTx);
  const mintTxHash = await wallet.submitTx(signedMintTx);

  console.log(`Minted NFT #${oracleData.nftIndex}:`, mintTxHash);
}

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

## Important: Storing paramUtxo

The `paramUtxo` is critical for your minting machine. Store it securely:

```typescript
// After setupOracle, save this to your database or config
const paramUtxo = {
  outputIndex: 0,
  txHash: "63dbd563ee9979574401599a42841e0d5b63a691af95df863cbf37d5cb44a558",
};

// For all future mints, initialize the contract with this paramUtxo
const contract = new MeshPlutusNFTContract(
  { /* ... */ },
  {
    collectionName: "MeshCollection",
    paramUtxo: paramUtxo,  // Required for minting
  }
);
```

## Troubleshooting

### Common Errors

| Error                      | Cause                                | Solution                                        |
| -------------------------- | ------------------------------------ | ----------------------------------------------- |
| `Oracle not found`         | Missing or wrong paramUtxo           | Verify paramUtxo matches your setup transaction |
| `Script validation failed` | Oracle state mismatch                | Ensure you're using the latest oracle state     |
| `Invalid collection name`  | Name mismatch                        | Collection name must match oracle setup         |
| `Insufficient funds`       | Not enough ADA for mint price + fees | Ensure wallet has enough ADA                    |

### Debugging Tips

1. **Save paramUtxo immediately**: Store it right after `setupOracle()` succeeds
2. **Use consistent collection name**: Must be identical for setup and mint
3. **Check oracle data first**: Call `getOracleData()` before minting to verify state
4. **One mint at a time**: Wait for each mint to confirm before the next

### Concurrent Minting

The oracle pattern requires sequential updates. For high-volume minting:

```typescript
// Wait for confirmation between mints
async function mintSequentially(count: number) {
  for (let i = 0; i < count; i++) {
    const oracleData = await contract.getOracleData();
    const tx = await contract.mintPlutusNFT({
      name: `Token ${oracleData.nftIndex}`,
      // ...metadata
    });
    const signedTx = await wallet.signTx(tx);
    await wallet.submitTx(signedTx);

    // Wait for confirmation
    await new Promise((r) => setTimeout(r, 30000));
  }
}
```

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/plutus-nft)
* [CIP-25 NFT Metadata Standard](https://cips.cardano.org/cips/cip25/)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)


# Swap Contract
URL: /smart-contracts/swap

Build peer-to-peer asset swap contracts on Cardano with specified exchange terms and on-chain settlement.

***

title: "Swap Contract"
description: "Build peer-to-peer asset swap contracts on Cardano with specified exchange terms and on-chain settlement."
------------------------------------------------------------------------------------------------------------------------

import Link from "next/link";

The Swap contract enables peer-to-peer asset exchanges. You specify what you want to give and what you want to receive, then lock your assets in the contract. Anyone who provides the requested assets can complete the swap. You can cancel anytime before someone accepts.

## Use Cases

* Peer-to-peer token trading
* OTC (over-the-counter) deals
* NFT-for-token swaps
* Multi-asset exchanges
* Trustless trading without intermediaries

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshSwapContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshSwapContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});
```

## Contract Logic

The Swap contract works as a simple order book entry:

| State         | Description                             |
| ------------- | --------------------------------------- |
| **Open**      | Assets locked, waiting for counterparty |
| **Completed** | Counterparty accepted, assets swapped   |
| **Cancelled** | Initiator retrieved assets              |

### Swap Flow

```
Initiator                    Contract                    Acceptor
    |                           |                           |
    |--- initiateSwap --------->|                           |
    |    (lock assets)          |                           |
    |                           |                           |
    |                           |<------- acceptSwap -------|
    |                           |    (provide requested)    |
    |                           |                           |
    |<-- receive requested -----|---- send locked --------->|
```

### Validation Rules

1. **Initiate**: Lock specified assets in contract with requested assets in datum
2. **Accept**: Counterparty must provide exactly the requested assets
3. **Cancel**: Only the initiator can cancel and retrieve assets

## Available Actions

### Initiate Swap

Create a new swap by specifying what you offer and what you want in return.

#### Method Signature

```typescript
contract.initiateSwap(toProvide: Asset[], toReceive: Asset[]): Promise<string>
```

#### Parameters

| Parameter   | Type      | Description                 |
| ----------- | --------- | --------------------------- |
| `toProvide` | `Asset[]` | Assets you are offering     |
| `toReceive` | `Asset[]` | Assets you want in exchange |

#### Code Example

```typescript
import { MeshSwapContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshSwapContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Define what you're offering (10 ADA)
const toProvide: Asset[] = [
  {
    unit: "lovelace",
    quantity: "10000000",
  },
];

// Define what you want (1 specific NFT)
const toReceive: Asset[] = [
  {
    unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
    quantity: "1",
  },
];

// Initiate the swap
const tx = await contract.initiateSwap(toProvide, toReceive);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Swap initiated. Transaction hash:", txHash);
// Share this txHash with potential counterparties
```

#### What Happens on Success

* Your offered assets transfer to the contract
* Swap terms are stored in the datum
* Anyone with the requested assets can accept
* You can cancel anytime before acceptance

### Accept Swap

Accept an open swap by providing the requested assets.

#### Method Signature

```typescript
contract.acceptSwap(swapUtxo: UTxO): Promise<string>
```

#### Parameters

| Parameter  | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| `swapUtxo` | `UTxO` | The UTxO containing the swap offer |

#### Code Example

```typescript
import { MeshSwapContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract (acceptor's wallet)
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshSwapContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: acceptorWallet,
  networkId: 0,
});

// Get the swap UTxO from the initiation transaction
const swapUtxo = await contract.getUtxoByTxHash("<initiate-transaction-hash>");

// Accept the swap (must have the requested assets in wallet)
const tx = await contract.acceptSwap(swapUtxo);
const signedTx = await acceptorWallet.signTx(tx);
const txHash = await acceptorWallet.submitTx(signedTx);

console.log("Swap accepted. Transaction hash:", txHash);
```

#### What Happens on Success

* Acceptor receives the initiator's offered assets
* Initiator receives the requested assets
* Swap UTxO is consumed
* View example: [Successful swap on Cardanoscan](https://preprod.cardanoscan.io/transaction/e266fc6b0b2481988f9742a28b914dabf7da5403a3893d5ba4b05530d2519f3a)

### Cancel Swap

Cancel an open swap and retrieve your assets.

#### Method Signature

```typescript
contract.cancelSwap(swapUtxo: UTxO): Promise<string>
```

#### Parameters

| Parameter  | Type   | Description                         |
| ---------- | ------ | ----------------------------------- |
| `swapUtxo` | `UTxO` | The UTxO containing your swap offer |

#### Code Example

```typescript
import { MeshSwapContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract (initiator's wallet)
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshSwapContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: initiatorWallet,
  networkId: 0,
});

// Get your swap UTxO
const swapUtxo = await contract.getUtxoByTxHash("<initiate-transaction-hash>");

// Cancel the swap
const tx = await contract.cancelSwap(swapUtxo);
const signedTx = await initiatorWallet.signTx(tx);
const txHash = await initiatorWallet.submitTx(signedTx);

console.log("Swap cancelled. Transaction hash:", txHash);
```

#### What Happens on Success

* Your offered assets return to your wallet
* Swap UTxO is consumed
* No further action possible on this swap

## Full Working Example

```typescript
import { MeshSwapContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function swapDemo() {
  const provider = new BlockfrostProvider("<Your-API-Key>");

  // Party A wants to trade 10 ADA for an NFT
  const partyAWallet = await MeshCardanoBrowserWallet.enable("eternl");

  const contractA = new MeshSwapContract({
    mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
    fetcher: provider,
    wallet: partyAWallet,
    networkId: 0,
  });

  // Step 1: Party A initiates swap
  const toProvide: Asset[] = [
    { unit: "lovelace", quantity: "10000000" }, // 10 ADA
  ];

  const toReceive: Asset[] = [
    {
      unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e",
      quantity: "1",
    },
  ];

  const initTx = await contractA.initiateSwap(toProvide, toReceive);
  const signedInitTx = await partyAWallet.signTx(initTx);
  const initTxHash = await partyAWallet.submitTx(signedInitTx);

  console.log("Swap initiated:", initTxHash);

  // Wait for confirmation
  await new Promise((r) => setTimeout(r, 60000));

  // Step 2: Party B accepts the swap
  const partyBWallet = await MeshCardanoBrowserWallet.enable("nami");

  const contractB = new MeshSwapContract({
    mesh: new MeshTxBuilder({ fetcher: provider, submitter: provider }),
    fetcher: provider,
    wallet: partyBWallet,
    networkId: 0,
  });

  const swapUtxo = await contractB.getUtxoByTxHash(initTxHash);

  const acceptTx = await contractB.acceptSwap(swapUtxo);
  const signedAcceptTx = await partyBWallet.signTx(acceptTx);
  const acceptTxHash = await partyBWallet.submitTx(signedAcceptTx);

  console.log("Swap completed:", acceptTxHash);
}

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

## Multi-Asset Swaps

You can swap multiple assets in a single transaction:

```typescript
// Offering: 5 ADA + 100 tokens
const toProvide: Asset[] = [
  {
    unit: "lovelace",
    quantity: "5000000",
  },
  {
    unit: "abc123...fungibleToken",
    quantity: "100",
  },
];

// Wanting: 2 specific NFTs
const toReceive: Asset[] = [
  {
    unit: "xyz789...nft1",
    quantity: "1",
  },
  {
    unit: "xyz789...nft2",
    quantity: "1",
  },
];

const tx = await contract.initiateSwap(toProvide, toReceive);
```

## Swap Discovery

To find available swaps, query the contract address:

```typescript
async function findOpenSwaps(contract: MeshSwapContract) {
  const scriptAddress = contract.getScriptAddress();
  const utxos = await provider.fetchAddressUTxOs(scriptAddress);

  return utxos.map((utxo) => ({
    txHash: utxo.input.txHash,
    offered: utxo.output.amount,
    // Parse datum for requested assets
  }));
}
```

## Troubleshooting

### Common Errors

| Error                      | Cause                              | Solution                                    |
| -------------------------- | ---------------------------------- | ------------------------------------------- |
| `Script validation failed` | Missing requested assets           | Ensure you have all requested assets        |
| `Missing required signer`  | Wrong wallet for cancel            | Only initiator can cancel                   |
| `UTxO not found`           | Swap already accepted or cancelled | Check if swap is still open                 |
| `Insufficient funds`       | Not enough assets to accept        | Verify you have the exact requested amounts |

### Debugging Tips

1. **Check swap status**: Use `getUtxoByTxHash()` to verify the swap is still open
2. **Verify asset units**: Asset units must match exactly (policy ID + asset name)
3. **Check quantities**: You must provide the exact quantities requested
4. **Inspect datum**: View the transaction on a block explorer to see requested assets

### Asset Unit Format

```typescript
// Correct format: policyId + assetName (in hex)
const unit = "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e";
//           |----------- policy ID -----------||-------- asset name (hex) --------|

// For lovelace, use the string "lovelace"
const lovelace = "lovelace";
```

## Comparison: Swap vs Escrow

| Feature    | Swap                        | Escrow                 |
| ---------- | --------------------------- | ---------------------- |
| Parties    | 1 initiator, any acceptor   | 2 specific parties     |
| Terms      | Fixed at initiation         | Agreed by both parties |
| Completion | Single signature (acceptor) | Multi-signature        |
| Use Case   | Public offers               | Private agreements     |

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/swap)
* [Successful Swap Example](https://preprod.cardanoscan.io/transaction/e266fc6b0b2481988f9742a28b914dabf7da5403a3893d5ba4b05530d2519f3a)
* [Escrow Contract](/docs/smart-contracts/escrow) - For private two-party agreements
* [MeshTxBuilder Documentation](/apis/transaction)
* [Wallet Integration Guide](/wallets)


# Vesting Contract
URL: /smart-contracts/vesting

Lock funds for a beneficiary and release them after a specified time period

***

title: "Vesting Contract"
description: "Lock funds for a beneficiary and release them after a specified time period"
------------------------------------------------------------------------------------------

import Link from "next/link";

The Vesting contract locks funds until a specified time and then allows a designated beneficiary to withdraw them. This pattern is common in employee compensation, token distributions, and any scenario requiring time-locked asset release.

## Use Cases

* Employee compensation vesting schedules
* Token unlock schedules for investors
* Scheduled payments and allowances
* Time-locked savings or escrow
* Deferred compensation arrangements

## Quick Start

### Install the Package

```bash
npm install @meshsdk/contract @meshsdk/core
```

### Initialize the Contract

```typescript
import { MeshVestingContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshVestingContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});
```

## Contract Logic

The Vesting contract stores three pieces of information in its datum:

| Field         | Type        | Description                                      |
| ------------- | ----------- | ------------------------------------------------ |
| `lock_until`  | `Int`       | POSIX timestamp (milliseconds) when funds unlock |
| `owner`       | `ByteArray` | Public key hash of the depositor                 |
| `beneficiary` | `ByteArray` | Public key hash of the recipient                 |

### Withdrawal Conditions

The contract allows withdrawal under two scenarios:

**Scenario 1: Owner Withdrawal**

* Transaction signed by the owner
* No time restriction

**Scenario 2: Beneficiary Withdrawal**

* Transaction signed by the beneficiary
* Current time is after `lock_until`

### On-Chain Validator

```rust
validator {
  pub fn vesting(datum: VestingDatum, _redeemer: Data, ctx: ScriptContext) {
    when ctx.purpose is {
      Spend(_) -> or {
          key_signed(ctx.transaction.extra_signatories, datum.owner),
          and {
            key_signed(ctx.transaction.extra_signatories, datum.beneficiary),
            valid_after(ctx.transaction.validity_range, datum.lock_until),
          },
        }
      _ -> False
    }
  }
}
```

### Datum Structure

```rust
pub type VestingDatum {
  lock_until: Int,
  owner: ByteArray,
  beneficiary: ByteArray,
}
```

## Available Actions

### Deposit Fund

Deposit assets into the vesting contract with a lockup period and beneficiary address.

#### Method Signature

```typescript
contract.depositFund(
  assets: Asset[],
  lockUntilTimeStampMs: number,
  beneficiary: string
): Promise<string>
```

#### Parameters

| Parameter              | Type      | Description                                       |
| ---------------------- | --------- | ------------------------------------------------- |
| `assets`               | `Asset[]` | Array of assets to deposit                        |
| `lockUntilTimeStampMs` | `number`  | POSIX timestamp in milliseconds when funds unlock |
| `beneficiary`          | `string`  | Bech32 address of the beneficiary                 |

#### Code Example

```typescript
import { MeshVestingContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshVestingContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Define assets to vest
const assets: Asset[] = [
  {
    unit: "lovelace",
    quantity: "10000000", // 10 ADA
  },
];

// Set lockup period (1 hour from now)
const lockUntilTimeStamp = new Date();
lockUntilTimeStamp.setHours(lockUntilTimeStamp.getHours() + 1);

// Define beneficiary address
const beneficiary = "addr_test1qp...your_beneficiary_address";

// Deposit funds
const tx = await contract.depositFund(
  assets,
  lockUntilTimeStamp.getTime(),
  beneficiary
);
const signedTx = await wallet.signTx(tx);
const txHash = await wallet.submitTx(signedTx);

console.log("Funds deposited. Transaction hash:", txHash);
```

#### What Happens on Success

* Assets transfer from your wallet to the contract address
* Datum stores the lock time, your address, and beneficiary address
* You receive a transaction hash to track the vesting position

### Withdraw Fund

Withdraw vested funds after the lockup period expires (beneficiary) or at any time (owner).

#### Method Signature

```typescript
contract.withdrawFund(vestingUtxo: UTxO): Promise<string>
```

#### Parameters

| Parameter     | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| `vestingUtxo` | `UTxO` | The UTxO containing the vested funds |

#### Code Example

```typescript
import { MeshVestingContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";

// Initialize provider and contract
const provider = new BlockfrostProvider("<Your-API-Key>");

const meshTxBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const contract = new MeshVestingContract({
  mesh: meshTxBuilder,
  fetcher: provider,
  wallet: wallet,
  networkId: 0,
});

// Get the UTxO from the deposit transaction
const utxo = await contract.getUtxoByTxHash("<your-deposit-transaction-hash>");

// Withdraw funds (must be owner or beneficiary after lock period)
const tx = await contract.withdrawFund(utxo);
const signedTx = await wallet.signTx(tx, true);
const txHash = await wallet.submitTx(signedTx);

console.log("Funds withdrawn. Transaction hash:", txHash);
```

#### What Happens on Success

* Contract validates signer is owner or beneficiary
* If beneficiary, contract validates current time is after lock\_until
* Funds transfer to the signer's wallet
* View example: [Successful withdrawal on Cardanoscan](https://preprod.cardanoscan.io/transaction/e61815bcfe46ababf3d024ae470f779fa738cded55f02127b9e211847c77af8b)

## Full Working Example

```typescript
import { MeshVestingContract } from "@meshsdk/contract";
import { BlockfrostProvider, MeshTxBuilder, Asset } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

async function vestingDemo() {
  // Connect wallet (owner/depositor)
  const ownerWallet = await MeshCardanoBrowserWallet.enable("eternl");

  // Initialize provider
  const provider = new BlockfrostProvider("<Your-API-Key>");

  const meshTxBuilder = new MeshTxBuilder({
    fetcher: provider,
    submitter: provider,
  });

  // Initialize contract
  const contract = new MeshVestingContract({
    mesh: meshTxBuilder,
    fetcher: provider,
    wallet: ownerWallet,
    networkId: 0,
  });

  // Step 1: Deposit funds with 1-minute lockup
  const assets: Asset[] = [
    {
      unit: "lovelace",
      quantity: "5000000", // 5 ADA
    },
  ];

  const lockUntil = new Date();
  lockUntil.setMinutes(lockUntil.getMinutes() + 1);

  const beneficiaryAddress = "addr_test1qp...beneficiary_address";

  const depositTx = await contract.depositFund(
    assets,
    lockUntil.getTime(),
    beneficiaryAddress
  );
  const signedDepositTx = await ownerWallet.signTx(depositTx);
  const depositTxHash = await ownerWallet.submitTx(signedDepositTx);

  console.log("Deposit transaction:", depositTxHash);

  // Wait for lockup period to expire
  console.log("Waiting for lockup period...");
  await new Promise((resolve) => setTimeout(resolve, 70000)); // 70 seconds

  // Step 2: Beneficiary withdraws (switch to beneficiary wallet in production)
  const utxo = await contract.getUtxoByTxHash(depositTxHash);

  const withdrawTx = await contract.withdrawFund(utxo);
  const signedWithdrawTx = await ownerWallet.signTx(withdrawTx, true);
  const withdrawTxHash = await ownerWallet.submitTx(signedWithdrawTx);

  console.log("Withdraw transaction:", withdrawTxHash);
}

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

## Advanced: Manual Transaction Building

For more control over the transaction, you can build it manually:

### Manual Deposit

```typescript
import { MeshTxBuilder, deserializeAddress, mConStr0 } from "@meshsdk/core";

const { utxos, walletAddress } = await getWalletInfoForTx();
const { scriptAddr } = getScript();

const { pubKeyHash: ownerPubKeyHash } = deserializeAddress(walletAddress);
const { pubKeyHash: beneficiaryPubKeyHash } = deserializeAddress(beneficiary);

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

await txBuilder
  .txOut(scriptAddr, amount)
  .txOutInlineDatumValue(
    mConStr0([lockUntilTimeStampMs, ownerPubKeyHash, beneficiaryPubKeyHash])
  )
  .changeAddress(walletAddress)
  .selectUtxosFrom(utxos)
  .complete();

const unsignedTx = txBuilder.txHex;
```

### Manual Withdrawal

```typescript
import {
  MeshTxBuilder,
  deserializeAddress,
  deserializeDatum,
  unixTimeToEnclosingSlot,
  SLOT_CONFIG_NETWORK,
} from "@meshsdk/core";

const { utxos, walletAddress, collateral } = await getWalletInfoForTx();
const { input: collateralInput, output: collateralOutput } = collateral;
const { scriptAddr, scriptCbor } = getScript();
const { pubKeyHash } = deserializeAddress(walletAddress);

// Parse datum and calculate validity interval
const datum = deserializeDatum(vestingUtxo.output.plutusData);
const invalidBefore =
  unixTimeToEnclosingSlot(
    Math.min(datum.fields[0].int, Date.now() - 15000),
    SLOT_CONFIG_NETWORK.preprod
  ) + 1;

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

await txBuilder
  .spendingPlutusScriptV2()
  .txIn(
    vestingUtxo.input.txHash,
    vestingUtxo.input.outputIndex,
    vestingUtxo.output.amount,
    scriptAddr
  )
  .spendingReferenceTxInInlineDatumPresent()
  .spendingReferenceTxInRedeemerValue("")
  .txInScript(scriptCbor)
  .txOut(walletAddress, [])
  .txInCollateral(
    collateralInput.txHash,
    collateralInput.outputIndex,
    collateralOutput.amount,
    collateralOutput.address
  )
  .invalidBefore(invalidBefore)
  .requiredSignerHash(pubKeyHash)
  .changeAddress(walletAddress)
  .selectUtxosFrom(utxos)
  .complete();

const unsignedTx = txBuilder.txHex;
const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);
```

## Troubleshooting

### Common Errors

| Error                       | Cause                     | Solution                                              |
| --------------------------- | ------------------------- | ----------------------------------------------------- |
| `Script validation failed`  | Lockup period not expired | Wait until the `lock_until` timestamp has passed      |
| `Missing required signer`   | Wrong wallet signing      | Use the owner or beneficiary wallet                   |
| `Outside validity interval` | Transaction timing issue  | Ensure `invalidBefore` is set correctly               |
| `UTxO not found`            | Invalid transaction hash  | Verify the transaction hash and wait for confirmation |

### Debugging Tips

1. **Check the current time**: Verify the lockup period has actually expired
2. **Verify addresses**: Ensure you are using the correct owner or beneficiary wallet
3. **Inspect the datum**: Use `deserializeDatum()` to verify the stored lock time
4. **Check slot configuration**: Ensure you are using the correct network slot config

### Testing the Contract

Run the Aiken test suite:

```bash
aiken check
```

Test cases include:

* Success: Unlocking with owner signature
* Success: Unlocking with beneficiary signature after time passed
* Fail: Unlocking with only beneficiary signature (before time)
* Fail: Unlocking with only time passed (no signature)

## Related Links

* [Source Code on GitHub](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/vesting)
* [Successful Deposit Example](https://preprod.cardanoscan.io/transaction/ede9f8176fe41f0c84cfc9802b693dedb5500c0cbe4377b7bb0d57cf0435200b)
* [Successful Withdrawal Example](https://preprod.cardanoscan.io/transaction/b108f91a1dcd1b4c0bc978fb7557fc23ad052f1681cca078aa2515f8ab01e05e)
* [MeshTxBuilder Documentation](/apis/transaction)
* [Providers Setup Guide](/providers)


# Getting Started with Svelte
URL: /svelte/getting-started

Set up Mesh Svelte components in your project in 5 minutes

***

title: "Getting Started with Svelte"
description: "Set up Mesh Svelte components in your project in 5 minutes"
-------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

Mesh Svelte provides production-ready UI components for Cardano wallet connections. Built with Svelte 5, these components offer reactive state management using runes and work with all CIP-30 compatible wallets.

**What you get:**

* `CardanoWallet` - A drop-in wallet connection button
* `BrowserWalletState` - Reactive wallet state management
* Pre-built styles that match your app's theme

## Quick Start

Get a wallet connection button running in your Svelte app.

```bash
npm install @meshsdk/svelte
```

```svelte
<!-- +layout.svelte -->
<script lang="ts">
  import '@meshsdk/svelte/styles.css';
  let { children } = $props();
</script>

{@render children()}
```

```svelte
<!-- +page.svelte -->
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<CardanoWallet />
```

## Step-by-Step Setup

### Option 1: Use the Mesh CLI (Recommended)

Scaffold a new Svelte project with Mesh pre-configured.

```bash
npx meshjs your-app-name
```

Select the Svelte template when prompted. This creates a project with all dependencies installed and configured.

### Option 2: Add to an Existing Project

**Step 1: Install the package**

```bash
npm install @meshsdk/svelte
```

**Step 2: Import styles**

Add the Mesh CSS to your root layout file (`+layout.svelte`). This applies default styles to all Mesh components.

```svelte
<script lang="ts">
  import '@meshsdk/svelte/styles.css';
  let { children } = $props();
</script>

{@render children()}
```

**Step 3: Add the wallet component**

Import and use `CardanoWallet` in any page or component.

```svelte
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<main>
  <CardanoWallet />
</main>
```

## API Reference

### CardanoWallet

A button component that opens a wallet selection modal and handles the connection flow.

**Props:**

| Prop          | Type         | Default            | Description                          |
| ------------- | ------------ | ------------------ | ------------------------------------ |
| `label`       | `string`     | `"Connect Wallet"` | Button text                          |
| `isDark`      | `boolean`    | `false`            | Enable dark mode styling             |
| `onConnected` | `() => void` | `undefined`        | Callback after successful connection |

**Examples:**

```svelte
<!-- Dark mode -->
<CardanoWallet isDark={true} />

<!-- Custom label -->
<CardanoWallet label="Connect a Wallet" />

<!-- With callback -->
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";

  function handleConnected() {
    console.log("Wallet connected successfully");
    // Fetch user data, redirect, etc.
  }
</script>

<CardanoWallet onConnected={handleConnected} />
```

### BrowserWalletState

A reactive state object that tracks the current wallet connection. All properties are Svelte 5 runes, so they update automatically in your UI.

**Properties:**

| Property     | Type                               | Description                            |
| ------------ | ---------------------------------- | -------------------------------------- |
| `wallet`     | `MeshCardanoBrowserWallet \| null` | The connected wallet instance          |
| `connected`  | `boolean`                          | `true` when a wallet is connected      |
| `name`       | `string`                           | Name of the connected wallet           |
| `connecting` | `boolean`                          | `true` while connection is in progress |

**Example:**

```svelte
<script lang="ts">
  import { CardanoWallet, BrowserWalletState } from "@meshsdk/svelte";

  $effect(() => {
    if (BrowserWalletState.wallet) {
      BrowserWalletState.wallet.getChangeAddress().then(address => {
        console.log("Connected address:", address);
      });
    }
  });
</script>

<div>
  {#if BrowserWalletState.connected}
    <p>Connected to {BrowserWalletState.name}</p>
  {:else}
    <CardanoWallet />
  {/if}
</div>
```

## Complete Example

A full example showing wallet connection with address display.

```svelte
<script lang="ts">
  import { CardanoWallet, BrowserWalletState } from "@meshsdk/svelte";

  let address = $state("");
  let balance = $state("");

  $effect(() => {
    if (BrowserWalletState.wallet) {
      // Get wallet address
      BrowserWalletState.wallet.getChangeAddress().then(addr => {
        address = addr;
      });

      // Get wallet balance
      BrowserWalletState.wallet.getBalance().then(bal => {
        const lovelace = bal.find(b => b.unit === "lovelace");
        if (lovelace) {
          balance = (parseInt(lovelace.quantity) / 1_000_000).toFixed(2);
        }
      });
    }
  });
</script>

<main>
  <h1>My Cardano dApp</h1>

  {#if BrowserWalletState.connecting}
    <p>Connecting...</p>
  {:else if BrowserWalletState.connected}
    <div>
      <p>Wallet: {BrowserWalletState.name}</p>
      <p>Address: {address.slice(0, 20)}...</p>
      <p>Balance: {balance} ADA</p>
    </div>
  {:else}
    <CardanoWallet label="Connect Your Wallet" />
  {/if}
</main>
```

## Troubleshooting

### Styles not applying

Ensure you import the CSS file in your root layout, not in individual components.

```svelte
<!-- +layout.svelte (correct) -->
<script lang="ts">
  import '@meshsdk/svelte/styles.css';
</script>
```

### Wallet not appearing in the list

The wallet extension must be installed in the user's browser. Mesh automatically detects all CIP-30 compatible wallets. If a wallet is missing, verify:

1. The wallet extension is installed and enabled
2. The browser page has been refreshed after installation
3. The wallet is CIP-30 compliant

### TypeScript errors with BrowserWalletState

Ensure you are using Svelte 5. The `BrowserWalletState` object uses Svelte 5 runes, which are not compatible with Svelte 4.

### Building a custom wallet component

For advanced customization beyond the provided props, build your own component using the <Link href="/apis/wallets/browserwallet">Browser Wallet API</Link>. Reference the <Link href="https://github.com/MeshJS/mesh/blob/main/packages/mesh-svelte/src/cardano-wallet/index.svelte">source code</Link> for implementation details.

## Related Links

* <Link href="/docs/svelte/ui-components">UI Components</Link> - All available Svelte components
* <Link href="/apis/wallets/browserwallet">Browser Wallet API</Link> - Full CIP-30 wallet methods
* <Link href="https://github.com/MeshJS/mesh/tree/main/packages/mesh-svelte">Source Code</Link> - Mesh Svelte package on GitHub


# Cardano Svelte Components
URL: /svelte

Production-ready Svelte UI components for Cardano wallet connections

***

title: "Cardano Svelte Components"
description: "Production-ready Svelte UI components for Cardano wallet connections"
icon: ComputerDesktopIcon
-------------------------

import { linksSvelte } from "@/data/links-svelte";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Mesh provides a collection of Svelte 5 components for building Cardano dApps. Use these components to connect wallets, manage wallet state, and interact with the Cardano blockchain.

**When to use Mesh Svelte:**

* You need wallet connection UI for a Svelte application
* You want reactive wallet state management with Svelte 5 runes
* You prefer pre-built components over building from scratch

## Quick Start

Install the package and add a wallet connection button in under 2 minutes.

```bash
npm install @meshsdk/svelte
```

```svelte
<script lang="ts">
  import '@meshsdk/svelte/styles.css';
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<CardanoWallet />
```

## What's Included

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksSvelte.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related Links

* <Link href="/docs/svelte/getting-started">Getting Started Guide</Link> - Complete setup instructions
* <Link href="/docs/svelte/ui-components">UI Components</Link> - All available components
* <Link href="/apis/wallets/browserwallet">Browser Wallet API</Link> - Full CIP-30 wallet API reference


# UI Components
URL: /svelte/ui-components

Pre-built Svelte components for Cardano wallet connections and interactions

***

title: "UI Components"
description: "Pre-built Svelte components for Cardano wallet connections and interactions"
------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

Mesh provides a collection of Svelte 5 UI components that handle common Cardano dApp functionality. Use these components to add wallet connections without building the UI from scratch.

**Available components:**

* `CardanoWallet` - Wallet connection button with modal
* `BrowserWalletState` - Reactive wallet state management

## Quick Start

Add a wallet connection button to any Svelte component.

```svelte
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<CardanoWallet />
```

## CardanoWallet Component

A button that opens a modal displaying all available CIP-30 wallets. When the user selects a wallet, Mesh handles the connection flow and updates the global state.

### Basic Usage

```svelte
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<main>
  <CardanoWallet />
</main>
```

### Props Reference

| Prop          | Type         | Default            | Description                                 |
| ------------- | ------------ | ------------------ | ------------------------------------------- |
| `label`       | `string`     | `"Connect Wallet"` | Text displayed on the button                |
| `isDark`      | `boolean`    | `false`            | Enable dark mode styling                    |
| `onConnected` | `() => void` | `undefined`        | Function called after successful connection |

### Dark Mode

Apply dark mode styling that matches dark-themed applications.

```svelte
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<CardanoWallet isDark={true} />
```

### Custom Label

Change the button text to match your application's language or branding.

```svelte
<script lang="ts">
  import { CardanoWallet } from "@meshsdk/svelte";
</script>

<CardanoWallet label="Connect a Wallet" />
```

### Connection Callback

Execute custom logic after the wallet connects successfully.

```svelte
<script lang="ts">
  import { CardanoWallet, BrowserWalletState } from "@meshsdk/svelte";

  async function handleConnected() {
    // Access the connected wallet
    const wallet = BrowserWalletState.wallet;
    if (wallet) {
      const address = await wallet.getChangeAddress();
      console.log("Connected:", address);

      // Example: redirect to dashboard
      // goto('/dashboard');
    }
  }
</script>

<CardanoWallet onConnected={handleConnected} />
```

## BrowserWalletState

A global state object that tracks wallet connection status. All properties are Svelte 5 runes, providing automatic reactivity.

### Properties

| Property     | Type                    | Description                                                                          |
| ------------ | ----------------------- | ------------------------------------------------------------------------------------ |
| `wallet`     | `BrowserWallet \| null` | The connected <Link href="/apis/wallets/browserwallet">BrowserWallet</Link> instance |
| `connected`  | `boolean`               | `true` when a wallet is connected                                                    |
| `name`       | `string`                | Name of the connected wallet (e.g., "Nami", "Eternl")                                |
| `connecting` | `boolean`               | `true` while connection is in progress                                               |

### Usage Example

```svelte
<script lang="ts">
  import { CardanoWallet, BrowserWalletState } from "@meshsdk/svelte";

  let address = $state("");

  $effect(() => {
    if (BrowserWalletState.wallet) {
      BrowserWalletState.wallet.getChangeAddress().then(addr => {
        address = addr;
      });
    }
  });
</script>

<div>
  {#if BrowserWalletState.connecting}
    <p>Connecting to wallet...</p>
  {:else if BrowserWalletState.connected}
    <p>Connected to {BrowserWalletState.name}</p>
    <p>Address: {address}</p>
  {:else}
    <CardanoWallet />
  {/if}
</div>
```

### Accessing Wallet Methods

Once connected, use `BrowserWalletState.wallet` to access all CIP-30 wallet methods.

```svelte
<script lang="ts">
  import { BrowserWalletState } from "@meshsdk/svelte";

  async function getAssets() {
    const wallet = BrowserWalletState.wallet;
    if (!wallet) return;

    const utxos = await wallet.getUtxos();
    const balance = await wallet.getBalance();
    const addresses = await wallet.getUsedAddresses();

    console.log({ utxos, balance, addresses });
  }
</script>

<button onclick={getAssets}>Get Assets</button>
```

## Complete Example

A full implementation showing conditional rendering based on wallet state.

```svelte
<script lang="ts">
  import { CardanoWallet, BrowserWalletState } from "@meshsdk/svelte";
  import { MeshTxBuilder } from "@meshsdk/core";

  let address = $state("");
  let balance = $state("0");
  let loading = $state(false);

  $effect(() => {
    if (BrowserWalletState.wallet) {
      loadWalletData();
    } else {
      address = "";
      balance = "0";
    }
  });

  async function loadWalletData() {
    const wallet = BrowserWalletState.wallet;
    if (!wallet) return;

    loading = true;
    try {
      address = await wallet.getChangeAddress();

      const balanceData = await wallet.getBalance();
      const lovelace = balanceData.find(b => b.unit === "lovelace");
      if (lovelace) {
        balance = (parseInt(lovelace.quantity) / 1_000_000).toFixed(2);
      }
    } finally {
      loading = false;
    }
  }

  async function sendTransaction() {
    const wallet = BrowserWalletState.wallet;
    if (!wallet) return;

    // Build and sign a transaction
    const utxos = await wallet.getUtxos();
    const changeAddress = await wallet.getChangeAddress();

    const txBuilder = new MeshTxBuilder();
    const unsignedTx = await txBuilder
      .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
      .changeAddress(changeAddress)
      .selectUtxosFrom(utxos)
      .complete();

    const signedTx = await wallet.signTx(unsignedTx);
    const txHash = await wallet.submitTx(signedTx);

    console.log("Transaction submitted:", txHash);
  }
</script>

<main>
  <h1>My Cardano dApp</h1>

  {#if BrowserWalletState.connecting}
    <div class="loading">
      <p>Connecting to wallet...</p>
    </div>
  {:else if BrowserWalletState.connected}
    <div class="wallet-info">
      <h2>Wallet Connected</h2>
      <p><strong>Wallet:</strong> {BrowserWalletState.name}</p>
      <p><strong>Address:</strong> {address.slice(0, 12)}...{address.slice(-8)}</p>
      <p><strong>Balance:</strong> {balance} ADA</p>

      <button onclick={sendTransaction} disabled={loading}>
        Send 5 ADA
      </button>
    </div>
  {:else}
    <div class="connect-prompt">
      <p>Connect your wallet to get started</p>
      <CardanoWallet label="Connect Wallet" />
    </div>
  {/if}
</main>

<style>
  main {
    max-width: 600px;
    margin: 0 auto;
    padding: 2rem;
  }

  .wallet-info {
    padding: 1rem;
    border: 1px solid #ccc;
    border-radius: 8px;
  }

  button {
    margin-top: 1rem;
    padding: 0.5rem 1rem;
  }
</style>
```

## Troubleshooting

### Component not rendering

Verify that you imported the Mesh CSS in your root layout file.

```svelte
<!-- +layout.svelte -->
<script lang="ts">
  import '@meshsdk/svelte/styles.css';
  let { children } = $props();
</script>

{@render children()}
```

### Wallet state not updating

Ensure you access `BrowserWalletState` properties directly, not through destructuring. Svelte 5 runes require direct property access for reactivity.

```svelte
<!-- Correct -->
{#if BrowserWalletState.connected}

<!-- Incorrect - loses reactivity -->
<script>
  const { connected } = BrowserWalletState; // Don't do this
</script>
```

### Building custom components

For advanced customization, reference the <Link href="https://github.com/MeshJS/mesh/blob/main/packages/mesh-svelte/src/cardano-wallet/index.svelte">CardanoWallet source code</Link> and build your own using the <Link href="/apis/wallets/browserwallet">Browser Wallet API</Link>.

## Related Links

* <Link href="/docs/svelte/getting-started">Getting Started</Link> - Installation and setup guide
* <Link href="/apis/wallets/browserwallet">Browser Wallet API</Link> - Full CIP-30 method reference
* <Link href="/apis/transaction">Transaction Builder</Link> - Build and submit transactions
* <Link href="https://github.com/MeshJS/mesh/tree/main/packages/mesh-svelte">GitHub Repository</Link> - Source code and examples


# Getting Started with Yaci
URL: /yaci/getting-started

Set up a local Cardano devnet in minutes. Install Yaci DevKit, start your first devnet, and connect with Mesh SDK.

***

title: "Getting Started with Yaci"
description: "Set up a local Cardano devnet in minutes. Install Yaci DevKit, start your first devnet, and connect with Mesh SDK."
---------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

This guide walks you through setting up Yaci DevKit on your machine. By the end, you will have a fully functional local Cardano devnet ready for development.

### What you will learn

* Connect to the Mesh-hosted Yaci devnet instantly
* Install and configure Yaci DevKit locally
* Create and manage devnets with yaci-cli
* Fund wallets and query UTxOs

## Prerequisites

Before installing Yaci DevKit locally, ensure you have:

| Requirement    | Description                                           |
| -------------- | ----------------------------------------------------- |
| **Docker**     | Docker Desktop or Docker Engine installed and running |
| **Disk space** | At least 10GB free for container images               |
| **Memory**     | Minimum 4GB RAM available for containers              |

For the hosted option, you only need the `@meshsdk/core` package.

## Quick start: Hosted devnet

Connect to the Mesh-hosted Yaci devnet immediately - no installation required:

```typescript
import { YaciProvider } from "@meshsdk/core";

// Connect to Mesh's hosted devnet (default URL)
const provider = new YaciProvider();

// Or specify the URL explicitly
const providerExplicit = new YaciProvider("https://yaci-node.meshjs.dev/api/v1/");

// Test the connection
const params = await provider.fetchProtocolParameters();
console.log("Protocol parameters:", params);
```

Learn more about the <Link href="https://cloud.meshjs.dev/yaci">hosted Yaci devnet</Link>.

## Installation: Local devnet

### Step 1: Install Docker

Download and install Docker from the <Link href="https://docs.docker.com/get-started/get-docker/">official Docker website</Link>.

After installation:

1. Open Docker Desktop
2. Ensure Docker is running (check the system tray icon)
3. Verify installation:

```bash
docker --version
# Docker version 24.0.0 or later
```

### Step 2: Download Yaci DevKit

Download the latest release from <Link href="https://github.com/bloxbean/yaci-devkit/releases">GitHub Releases</Link>.

1. Find the latest `yaci-devkit-x.x.x.zip` under Assets
2. Extract to a folder (this becomes your DevKit root directory)
3. Navigate to the extracted folder

```bash
cd yaci-devkit-x.x.x
```

### Step 3: Start DevKit

Launch the DevKit containers and yaci-cli:

```bash
./bin/devkit.sh start
```

This starts the Docker containers and opens the yaci-cli prompt.

### Step 4: Create a devnet

From the yaci-cli prompt, create and start a new devnet:

```bash
yaci-cli:> create-node -o --start
```

You should see output indicating the node is starting. The devnet is ready when blocks start being produced.

## Setup options

### Default devnet (Conway era)

```bash
yaci-cli:> create-node -o --start
```

### Babbage era devnet

For compatibility with older smart contracts:

```bash
yaci-cli:> create-node -o --era babbage --start
```

### Zero-fee devnet

Eliminate transaction fees for simpler testing:

```bash
yaci-cli:> create-node -o --genesis-profile zero_fee --start
```

### Custom epoch length

Set slots per epoch (useful for testing epoch-dependent features):

```bash
# 30 slots per epoch
yaci-cli:> create-node -o -e 30 --start
```

## Connect with Mesh SDK

Once your devnet is running, connect with YaciProvider:

```typescript
import { YaciProvider } from "@meshsdk/core";

// Connect to local devnet
const provider = new YaciProvider("http://localhost:8080/api/v1/");

// Verify connection
const params = await provider.fetchProtocolParameters();
console.log("Connected to local devnet");

// Fetch UTxOs
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qryvgass5dsrf2kxl3vgfz76uhp83kv5lagzcp29tcana68ca5aqa6swlq6llfamln09tal7n5kvt4275ckwedpt4v7q48uhex"
);
console.log("UTxOs:", utxos);
```

## API reference

### YaciProvider constructor

```typescript
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider(
  yaciUrl?: string,      // Yaci Store API URL (default: Mesh hosted)
  adminUrl?: string      // Optional admin API URL
);
```

| Parameter  | Default                                | Description                       |
| ---------- | -------------------------------------- | --------------------------------- |
| `yaciUrl`  | `https://yaci-node.meshjs.dev/api/v1/` | Yaci Store REST API endpoint      |
| `adminUrl` | `undefined`                            | Admin API for advanced operations |

## Built-in tools

### Yaci Viewer

After starting your devnet, open the block explorer at:

```
http://localhost:5173
```

View blocks, transactions, addresses, and UTxOs in a user-friendly interface.

### Yaci Store API

The REST API is available at:

```
http://localhost:8080/api/v1/
```

This API is Blockfrost-compatible, making it easy to swap between local and production environments.

## CLI commands

### Top up ADA

Fund any address with test ADA:

```bash
devnet:default> topup <address> <amount>
```

Example:

```bash
devnet:default> topup addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9 1000
```

### Check UTxOs

Query UTxOs for an address:

```bash
devnet:default> utxos <address>
```

### Default addresses

Get the pre-funded default addresses:

```bash
devnet:default> default-addresses
```

Default wallet 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
```

Default address:

```
addr_test1qryvgass5dsrf2kxl3vgfz76uhp83kv5lagzcp29tcana68ca5aqa6swlq6llfamln09tal7n5kvt4275ckwedpt4v7q48uhex
```

### Reset devnet

Clear all chain state and start fresh:

```bash
devnet:default> reset
```

### Stop devnet

Exit the devnet context:

```bash
devnet:default> exit
```

### Stop yaci-cli

Close the CLI:

```bash
yaci-cli:> exit
```

### Stop DevKit containers

From your terminal (not yaci-cli):

```bash
./bin/devkit.sh stop
```

## Configuration

### Node properties

Edit `config/node.properties` to customize devnet behavior.

### Environment variables

Edit `config/env` for additional settings including default topup addresses.

### External PostgreSQL

For production-like indexing, configure an external PostgreSQL database.

**Non-Docker distribution** - Edit `config/application.properties`:

```properties
yaci.store.db.url=jdbc:postgresql://<host>:<port>/<database>?currentSchema=<schema>
yaci.store.db.username=<username>
yaci.store.db.password=<password>
```

**Docker distribution** - Edit `config/env`:

```bash
yaci_store_db_url=jdbc:postgresql://<host>:<port>/<database>?currentSchema=<schema>
yaci_store_db_username=<username>
yaci_store_db_password=<password>
```

## Complete example

Set up a local devnet and verify it works:

```typescript
import { YaciProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function main() {
  // Connect to local devnet
  const provider = new YaciProvider("http://localhost:8080/api/v1/");

  // Verify connection
  const params = await provider.fetchProtocolParameters();
  console.log("Devnet protocol version:", params.protocolVersion);

  // Create wallet from default mnemonic
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    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".split(" "),
  });

  // Get wallet address
  const address = await wallet.getChangeAddressBech32();
  console.log("Wallet address:", address);

  // Fund wallet (use yaci-cli topup command first)
  const utxos = await provider.fetchAddressUTxOs(address);
  console.log("Available UTxOs:", utxos.length);

  // Ready for transactions!
  console.log("Devnet is ready for development");
}

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

## Troubleshooting

### Docker containers won't start

Ensure Docker Desktop is running:

```bash
docker ps
# Should not show "Cannot connect to the Docker daemon"
```

### Port conflicts

If port 8080 or 5173 is in use, stop the conflicting service or modify the DevKit configuration.

### Devnet not producing blocks

Check the node logs in the DevKit directory. Common issues:

* Insufficient memory allocated to Docker
* Disk space running low

### Connection refused from Mesh SDK

Verify the devnet is running and the URL is correct:

```bash
curl http://localhost:8080/api/v1/protocol-parameters
```

### Reset if corrupted

If the devnet behaves unexpectedly:

```bash
devnet:default> reset
```

## Related resources

* [Build Transactions](/docs/yaci/transactions) - Create and submit transactions on Yaci
* [Yaci Overview](/docs/yaci) - Introduction to Yaci DevKit
* [Mesh Cloud Yaci](https://cloud.meshjs.dev/yaci) - Hosted devnet service
* [YaciProvider API](/docs/providers/yaci) - Full provider documentation


# Yaci - Local Cardano Devnet
URL: /yaci

Spin up a local Cardano development network in seconds. Build and test smart contracts without mainnet fees or delays.

***

title: "Yaci - Local Cardano Devnet"
description: "Spin up a local Cardano development network in seconds. Build and test smart contracts without mainnet fees or delays."
icon: "icons/yaci.png"
----------------------

import { linksYaci } from "@/data/links-yaci";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Yaci DevKit provides a customizable Cardano devnet that you can create, configure, and reset in seconds. It eliminates the friction of blockchain development by giving you a local environment optimized for rapid iteration.

### When to use Yaci

* **Smart contract development**: Test Plutus scripts without spending real ADA
* **Integration testing**: Validate your dApp against a real Cardano environment
* **CI/CD pipelines**: Automated testing with reproducible blockchain state
* **Learning and prototyping**: Experiment with Cardano without consequences

### Key benefits

| Feature                   | Description                                            |
| ------------------------- | ------------------------------------------------------ |
| **Instant setup**         | Create a new devnet in seconds with a single command   |
| **Zero fees**             | Configure fee-free transactions for rapid testing      |
| **Configurable**          | Customize epochs, slots, protocol parameters, and more |
| **Blockfrost-compatible** | Use the same API endpoints as production               |
| **Built-in tools**        | Yaci Store indexer and Yaci Viewer included            |

## Quick start

Connect to the Mesh-hosted Yaci devnet immediately - no setup required:

```typescript
import { YaciProvider } from "@meshsdk/core";

// Connect to Mesh's hosted devnet
const provider = new YaciProvider();

// Fetch protocol parameters
const params = await provider.fetchProtocolParameters();
console.log("Connected to Yaci devnet:", params);

// Fetch UTxOs for an address
const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);
```

The hosted devnet is available at: `https://yaci-node.meshjs.dev/api/v1/`

## Documentation

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksYaci.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## How Yaci works

1. **Start DevKit**: Launch the Docker containers with a single command
2. **Create devnet**: Configure your network parameters (era, fees, epoch length)
3. **Fund wallets**: Use the built-in faucet to top up test addresses
4. **Build transactions**: Use Mesh SDK with YaciProvider just like production
5. **Reset and repeat**: Wipe the chain state and start fresh anytime

## Architecture

| Component        | Purpose                                       |
| ---------------- | --------------------------------------------- |
| **Yaci CLI**     | Command-line interface for managing devnets   |
| **Yaci Store**   | Lightweight chain indexer with REST API       |
| **Yaci Viewer**  | Browser-based block explorer (localhost:5173) |
| **Cardano Node** | Local Cardano node running your devnet        |

## Related resources

* [Getting Started](/docs/yaci/getting-started) - Install and configure Yaci DevKit
* [Build Transactions](/docs/yaci/transactions) - Create and submit transactions
* [Mesh Cloud Yaci](https://cloud.meshjs.dev/yaci) - Hosted Yaci devnet service
* [Yaci DevKit GitHub](https://github.com/bloxbean/yaci-devkit) - Official repository


# Build Transactions on Yaci
URL: /yaci/transactions

Create, sign, and submit transactions on your Yaci devnet. Learn to build simple transfers and complex smart contract interactions.

***

title: "Build Transactions on Yaci"
description: "Create, sign, and submit transactions on your Yaci devnet. Learn to build simple transfers and complex smart contract interactions."
--------------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

This guide shows you how to build and submit transactions on a Yaci devnet using Mesh SDK. The same code works on both local and hosted devnets - only the provider URL changes.

### What you will learn

* Connect YaciProvider to your devnet
* Fetch UTxOs and protocol parameters
* Build and submit basic ADA transfers
* Handle transaction errors

## Prerequisites

Before building transactions, ensure you have:

| Requirement       | Description                                   |
| ----------------- | --------------------------------------------- |
| **Yaci devnet**   | Running locally or using Mesh's hosted devnet |
| **Funded wallet** | Address with test ADA (use `topup` command)   |
| **Mesh SDK**      | `@meshsdk/core` package installed             |

```bash
npm install @meshsdk/core
```

## Quick start

Send 1 ADA to another address:

```typescript
import { YaciProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Connect to devnet
const provider = new YaciProvider("https://yaci-node.meshjs.dev/api/v1/");

// Create wallet
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: "your mnemonic words here".split(" "),
});

// Build and submit transaction
const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

const txBuilder = new MeshTxBuilder({ fetcher: provider });

const unsignedTx = await txBuilder
  .txOut("addr_test1...", [{ unit: "lovelace", quantity: "1000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Transaction submitted:", txHash);
```

## Setup

### Connect to hosted devnet

```typescript
import { YaciProvider } from "@meshsdk/core";

// Default: Mesh hosted devnet
const provider = new YaciProvider();

// Or explicit URL
const providerExplicit = new YaciProvider("https://yaci-node.meshjs.dev/api/v1/");
```

### Connect to local devnet

```typescript
import { YaciProvider } from "@meshsdk/core";

// Local Yaci DevKit
const provider = new YaciProvider("http://localhost:8080/api/v1/");
```

### YaciProvider constructor

```typescript
const provider = new YaciProvider(
  yaciUrl?: string,    // Yaci Store API URL
  adminUrl?: string    // Optional admin API for advanced operations
);
```

## API reference

### Fetch UTxOs

Get all UTxOs for an address:

```typescript
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider("https://yaci-node.meshjs.dev/api/v1/");

const utxos = await provider.fetchAddressUTxOs(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

console.log("UTxOs found:", utxos.length);
utxos.forEach((utxo) => {
  console.log(`  ${utxo.input.txHash}#${utxo.input.outputIndex}`);
});
```

### Fetch protocol parameters

Get current protocol parameters for transaction building:

```typescript
import { YaciProvider } from "@meshsdk/core";

const provider = new YaciProvider();

const params = await provider.fetchProtocolParameters();
console.log("Min fee coefficient:", params.minFeeA);
console.log("Min fee constant:", params.minFeeB);
```

## Build a basic transaction

### Step 1: Set up wallet and provider

```typescript
import { YaciProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const provider = new YaciProvider();

const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // testnet
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  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"
  ],
});
```

### Step 2: Get UTxOs and addresses

```typescript
const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

console.log("Available UTxOs:", utxos.length);
console.log("Change address:", changeAddress);
```

### Step 3: Build the transaction

```typescript
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
});

const recipientAddress = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "1000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Step 4: Sign and submit

```typescript
const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Transaction hash:", txHash);
```

## Complete example

Full working example with error handling:

```typescript
import { YaciProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

async function sendAda() {
  // Configuration
  const YACI_URL = "https://yaci-node.meshjs.dev/api/v1/";
  const 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 RECIPIENT = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";
  const AMOUNT = "5000000"; // 5 ADA in lovelace

  // Initialize provider
  const provider = new YaciProvider(YACI_URL);

  // Verify connection
  try {
    const params = await provider.fetchProtocolParameters();
    console.log("Connected to Yaci devnet");
  } catch (error) {
    console.error("Failed to connect to devnet:", error);
    return;
  }

  // Initialize wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    fetcher: provider,
    submitter: provider,
    mnemonic: MNEMONIC.split(" "),
  });

  // Get wallet state
  const changeAddress = await wallet.getChangeAddressBech32();
  const utxos = await wallet.getUtxosMesh();

  console.log("Sender address:", changeAddress);
  console.log("Available UTxOs:", utxos.length);

  if (utxos.length === 0) {
    console.error("No UTxOs available. Fund the wallet first:");
    console.log(`  devnet:default> topup ${changeAddress} 1000`);
    return;
  }

  // Calculate total available
  const totalLovelace = utxos.reduce((sum, utxo) => {
    const lovelace = utxo.output.amount.find((a) => a.unit === "lovelace");
    return sum + BigInt(lovelace?.quantity || 0);
  }, BigInt(0));

  console.log("Total available:", totalLovelace.toString(), "lovelace");

  // Build transaction
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
  });

  try {
    const unsignedTx = await txBuilder
      .txOut(RECIPIENT, [{ unit: "lovelace", quantity: AMOUNT }])
      .changeAddress(changeAddress)
      .selectUtxosFrom(utxos)
      .complete();

    console.log("Transaction built successfully");

    // Sign transaction
    const signedTx = await wallet.signTx(unsignedTx, false);
    console.log("Transaction signed");

    // Submit transaction
    const txHash = await wallet.submitTx(signedTx);
    console.log("Transaction submitted!");
    console.log("Transaction hash:", txHash);

    // Verify submission
    console.log("\nVerify on Yaci Viewer: http://localhost:5173");
    console.log(`Or fetch UTxOs for recipient to confirm receipt`);

  } catch (error) {
    console.error("Transaction failed:", error);
  }
}

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

## Fund your wallet

Before running transactions, fund your wallet using yaci-cli:

```bash
devnet:default> topup addr_test1qryvgass5dsrf2kxl3vgfz76uhp83kv5lagzcp29tcana68ca5aqa6swlq6llfamln09tal7n5kvt4275ckwedpt4v7q48uhex 1000
```

Then verify the funding:

```typescript
const utxos = await provider.fetchAddressUTxOs(address);
console.log("Funded UTxOs:", utxos);
```

## Transaction patterns

### Send to multiple recipients

```typescript
const unsignedTx = await txBuilder
  .txOut(recipient1, [{ unit: "lovelace", quantity: "1000000" }])
  .txOut(recipient2, [{ unit: "lovelace", quantity: "2000000" }])
  .txOut(recipient3, [{ unit: "lovelace", quantity: "3000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Send native tokens

```typescript
const unsignedTx = await txBuilder
  .txOut(recipient, [
    { unit: "lovelace", quantity: "2000000" },
    { unit: "<policy_id><asset_name>", quantity: "100" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Set explicit fee

```typescript
const unsignedTx = await txBuilder
  .txOut(recipient, [{ unit: "lovelace", quantity: "1000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .setFee("200000") // Explicit 0.2 ADA fee
  .complete();
```

## Troubleshooting

### "No UTxOs available"

Fund your wallet using the devnet topup command:

```bash
devnet:default> topup <your-address> 1000
```

### "Insufficient funds"

Check your available balance:

```typescript
const utxos = await wallet.getUtxosMesh();
const total = utxos.reduce((sum, u) => {
  const lovelace = u.output.amount.find((a) => a.unit === "lovelace");
  return sum + BigInt(lovelace?.quantity || 0);
}, BigInt(0));
console.log("Available:", total.toString(), "lovelace");
```

### "Connection refused"

Verify the devnet is running:

```bash
curl http://localhost:8080/api/v1/protocol-parameters
```

For hosted devnet:

```bash
curl https://yaci-node.meshjs.dev/api/v1/protocol-parameters
```

### Transaction not appearing

Wait a few seconds for the next block, then check:

```typescript
// Wait for block production
await new Promise((resolve) => setTimeout(resolve, 5000));

// Check recipient UTxOs
const recipientUtxos = await provider.fetchAddressUTxOs(recipientAddress);
console.log("Recipient UTxOs:", recipientUtxos);
```

## Related resources

* [Getting Started](/docs/yaci/getting-started) - Install and configure Yaci DevKit
* [Yaci Overview](/docs/yaci) - Introduction to Yaci
* [MeshTxBuilder](/docs/transactions/builder) - Full transaction builder documentation
* [Cardano Providers](/providers) - All available blockchain providers


# Cardano Data Types
URL: /apis/data

Parse and manipulate Cardano data types for smart contract development

***

title: "Cardano Data Types"
icon: CircleStackIcon
description: "Parse and manipulate Cardano data types for smart contract development"
-------------------------------------------------------------------------------------

import { linksData } from "@/data/links-data";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

MeshJS provides comprehensive utilities for working with Cardano data. Use these tools to construct datums, redeemers, and other on-chain data structures in multiple formats.

## Overview

Cardano smart contracts require data in specific formats. MeshJS supports three data representation formats:

| Format                           | Best For          | Description                                               |
| -------------------------------- | ----------------- | --------------------------------------------------------- |
| [Mesh Data](/apis/data/mesh)     | Quick prototyping | Simple JavaScript primitives with minimal wrappers        |
| [JSON Data](/apis/data/json)     | Web3 applications | Strong type validation for frontend-backend communication |
| [CBOR](/apis/data/overview#cbor) | Interoperability  | Raw binary format for cross-library compatibility         |

## Quick Start

Install the MeshJS SDK:

```bash
npm install @meshsdk/core
```

Choose your preferred data format:

```tsx
// Mesh Data format - simple and quick
import { mConStr0, mConStr1 } from "@meshsdk/core";
const datum = mConStr0(["owner-key-hash", 1000000n]);

// JSON Data format - validated types
import { conStr0, byteString, integer } from "@meshsdk/core";
const datum = conStr0([byteString("owner-key-hash"), integer(1000000)]);
```

## Browse Data APIs

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksData.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## When to Use Each Format

### Use Mesh Data When

* You need to quickly prototype smart contract interactions
* You want minimal boilerplate code
* You are comfortable with JavaScript primitives

### Use JSON Data When

* You need strong input validation
* You are building production web applications
* You want type safety for complex data structures

### Use CBOR When

* You are integrating with other serialization libraries
* You need the raw binary representation
* You are working with data from external sources

## Related

* [Utilities](/apis/utilities) - Serialize and deserialize data
* [Transaction Builder](/apis/txbuilder) - Use data in transactions
* [Smart Contracts](/apis/txbuilder/smart-contracts) - Apply data to contract interactions


# JSON Data Utilities
URL: /apis/data/json

Build Cardano data structures with validated JSON utilities

***

title: "JSON Data Utilities"
description: "Build Cardano data structures with validated JSON utilities"
--------------------------------------------------------------------------

Use JSON data utilities to construct Cardano data with strong type validation. These functions create properly formatted JSON objects that can be used as datums, redeemers, and other on-chain data.

## Overview

JSON data utilities provide:

* Type-safe data construction
* Input validation
* Named functions matching Plutus/Aiken conventions
* Easy debugging with readable output

All utilities return typed objects and validate inputs automatically.

## Quick Start

```tsx
import { conStr0, byteString, integer, list } from "@meshsdk/core";

// Build a simple datum
const datum = conStr0([
  byteString("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6"),
  integer(1000000),
]);

// Use in a transaction
const txBuilder = new MeshTxBuilder();
await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutInlineDatumValue(datum, "JSON")
  .complete();
```

***

## Constructor Utilities

Build Plutus constructor data types.

### conStr

Create a constructor with a specific index.

#### Function Signature

```tsx
conStr(constructor: number, fields: any[]): Constr
```

#### Parameters

| Parameter     | Type     | Required | Description                           |
| ------------- | -------- | -------- | ------------------------------------- |
| `constructor` | `number` | Yes      | The constructor index (0, 1, 2, etc.) |
| `fields`      | `any[]`  | Yes      | Array of fields for the constructor   |

#### Returns

| Type     | Description                           |
| -------- | ------------------------------------- |
| `Constr` | The constructor object in JSON format |

#### Example

```tsx
import { conStr, byteString, integer } from "@meshsdk/core";

// Create a constructor with index 0
const lockDatum = conStr(0, [
  byteString("owner-pub-key-hash"),
  integer(1704067200000),
]);

// Create a constructor with index 1
const unlockRedeemer = conStr(1, []);
```

### conStr0, conStr1, conStr2

Shorthand functions for common constructor indices.

#### Function Signatures

```tsx
conStr0(fields: any[]): Constr  // constructor index 0
conStr1(fields: any[]): Constr  // constructor index 1
conStr2(fields: any[]): Constr  // constructor index 2
```

#### Parameters

| Parameter | Type    | Required | Description                         |
| --------- | ------- | -------- | ----------------------------------- |
| `fields`  | `any[]` | Yes      | Array of fields for the constructor |

#### Example

```tsx
import { conStr0, conStr1, byteString, integer } from "@meshsdk/core";

// Common pattern: conStr0 for "normal" case, conStr1 for "alternative"
const someDatum = conStr0([byteString("data"), integer(100)]);
const noneDatum = conStr1([]);

// Enum-like usage
const mint = conStr0([]);
const burn = conStr1([]);
```

***

## Primitive Utilities

Build primitive data types.

### integer

Create an integer value.

#### Function Signature

```tsx
integer(int: number | bigint): Integer
```

#### Parameters

| Parameter | Type               | Required | Description       |
| --------- | ------------------ | -------- | ----------------- |
| `int`     | `number \| bigint` | Yes      | The integer value |

#### Returns

| Type      | Description                       |
| --------- | --------------------------------- |
| `Integer` | The integer object in JSON format |

#### Example

```tsx
import { integer } from "@meshsdk/core";

// Number value
const amount = integer(1000000);

// BigInt for large values
const largeAmount = integer(1000000000000000000n);
```

#### Alias: posixTime

Use `posixTime` for timestamp values (same functionality):

```tsx
import { posixTime } from "@meshsdk/core";

const deadline = posixTime(1704067200000);
```

### byteString

Create a byte string from hex.

#### Function Signature

```tsx
byteString(bytes: string): ByteString
```

#### Parameters

| Parameter | Type     | Required | Description                    |
| --------- | -------- | -------- | ------------------------------ |
| `bytes`   | `string` | Yes      | Hexadecimal string (validated) |

#### Returns

| Type         | Description                           |
| ------------ | ------------------------------------- |
| `ByteString` | The byte string object in JSON format |

#### Example

```tsx
import { byteString } from "@meshsdk/core";

const hash = byteString("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6");
```

#### Specialized Aliases

Use specialized functions for better semantics and validation:

```tsx
import {
  builtinByteString,
  scriptHash,
  pubKeyHash,
  policyId,
  currencySymbol,
  assetName,
  tokenName,
} from "@meshsdk/core";

// All create ByteString but with semantic meaning
const script = scriptHash("5867c3b8e27840f556ac268b781578b14c5661fc63ee720dbeab663f");
const key = pubKeyHash("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6");
const policy = policyId("426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69");
const asset = assetName("4d657368546f6b656e");
```

### bool

Create a boolean value.

#### Function Signature

```tsx
bool(b: boolean): Bool
```

#### Parameters

| Parameter | Type      | Required | Description       |
| --------- | --------- | -------- | ----------------- |
| `b`       | `boolean` | Yes      | The boolean value |

#### Returns

| Type   | Description                                              |
| ------ | -------------------------------------------------------- |
| `Bool` | The boolean object (constructor 0 for false, 1 for true) |

#### Example

```tsx
import { bool } from "@meshsdk/core";

const isActive = bool(true);
const isComplete = bool(false);
```

***

## Collection Utilities

Build lists and maps.

### list

Create a list of items.

#### Function Signature

```tsx
list<T>(pList: T[], validation?: boolean): List<T>
```

#### Parameters

| Parameter    | Type      | Required | Description                                |
| ------------ | --------- | -------- | ------------------------------------------ |
| `pList`      | `T[]`     | Yes      | Array of items                             |
| `validation` | `boolean` | No       | Enable type validation. Defaults to `true` |

#### Returns

| Type      | Description                    |
| --------- | ------------------------------ |
| `List<T>` | The list object in JSON format |

#### Example

```tsx
import { list, integer, byteString, bool } from "@meshsdk/core";

// List of integers
const amounts = list([
  integer(100),
  integer(200),
  integer(300),
]);

// Mixed type list
const mixedData = list([
  byteString("aa048e4c..."),
  integer(1000000),
  bool(true),
]);
```

### assocMap

Create an associative map (dictionary).

#### Function Signature

```tsx
assocMap<K, V>(mapItems: [K, V][], validation?: boolean): AssocMap<K, V>
```

#### Parameters

| Parameter    | Type       | Required | Description                                |
| ------------ | ---------- | -------- | ------------------------------------------ |
| `mapItems`   | `[K, V][]` | Yes      | Array of key-value tuples                  |
| `validation` | `boolean`  | No       | Enable type validation. Defaults to `true` |

#### Returns

| Type             | Description                   |
| ---------------- | ----------------------------- |
| `AssocMap<K, V>` | The map object in JSON format |

#### Example

```tsx
import { assocMap, byteString, integer } from "@meshsdk/core";

// Token amounts map
const tokenAmounts = assocMap([
  [byteString("aa"), integer(1000000)],
  [byteString("bb"), integer(2000000)],
]);

// Nested map for multi-asset value
const value = assocMap([
  [
    currencySymbol(""),
    assocMap([[tokenName(""), integer(5000000)]]),
  ],
  [
    currencySymbol("426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69"),
    assocMap([[tokenName("4d657368546f6b656e"), integer(100)]]),
  ],
]);
```

***

## Address Utilities

Build address data structures.

### pubKeyAddress

Create a public key address object.

#### Function Signature

```tsx
pubKeyAddress(pubKeyHash: string, stakeCredential?: string): PubKeyAddress
```

#### Parameters

| Parameter         | Type     | Required | Description                              |
| ----------------- | -------- | -------- | ---------------------------------------- |
| `pubKeyHash`      | `string` | Yes      | The payment key hash (56 hex characters) |
| `stakeCredential` | `string` | No       | Optional stake credential hash           |

#### Returns

| Type            | Description                       |
| --------------- | --------------------------------- |
| `PubKeyAddress` | The address object in JSON format |

#### Example

```tsx
import { pubKeyAddress } from "@meshsdk/core";

// Enterprise address (no stake)
const addr1 = pubKeyAddress("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6");

// Base address (with stake)
const addr2 = pubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);
```

### scriptAddress

Create a script address object.

#### Function Signature

```tsx
scriptAddress(scriptHash: string, stakeCredential?: string): ScriptAddress
```

#### Parameters

| Parameter         | Type     | Required | Description                         |
| ----------------- | -------- | -------- | ----------------------------------- |
| `scriptHash`      | `string` | Yes      | The script hash (56 hex characters) |
| `stakeCredential` | `string` | No       | Optional stake credential hash      |

#### Returns

| Type            | Description                       |
| --------------- | --------------------------------- |
| `ScriptAddress` | The address object in JSON format |

#### Example

```tsx
import { scriptAddress } from "@meshsdk/core";

const contractAddr = scriptAddress(
  "5867c3b8e27840f556ac268b781578b14c5661fc63ee720dbeab663f"
);
```

***

## Reference Utilities

Build transaction and asset references.

### outputReference / txOutRef

Create a transaction output reference.

#### Function Signature

```tsx
outputReference(txHash: string, outputIndex: number): OutputReference
txOutRef(txHash: string, outputIndex: number): TxOutRef  // Alias
```

#### Parameters

| Parameter     | Type     | Required | Description                              |
| ------------- | -------- | -------- | ---------------------------------------- |
| `txHash`      | `string` | Yes      | The transaction hash (64 hex characters) |
| `outputIndex` | `number` | Yes      | The output index                         |

#### Returns

| Type              | Description                         |
| ----------------- | ----------------------------------- |
| `OutputReference` | The reference object in JSON format |

#### Example

```tsx
import { outputReference, txOutRef } from "@meshsdk/core";

const utxoRef = outputReference(
  "a0bd47e8938e7c41d4c1d7c22033892319d28f86fdace791d45c51946553791b",
  0
);

// Same as above
const ref = txOutRef(
  "a0bd47e8938e7c41d4c1d7c22033892319d28f86fdace791d45c51946553791b",
  0
);
```

### assetClass

Create an asset class identifier.

#### Function Signature

```tsx
assetClass(policyId: string, assetName: string): AssetClass
```

#### Parameters

| Parameter   | Type     | Required | Description                                         |
| ----------- | -------- | -------- | --------------------------------------------------- |
| `policyId`  | `string` | Yes      | The policy ID (56 hex characters, or empty for ADA) |
| `assetName` | `string` | Yes      | The asset name in hex (or empty for ADA)            |

#### Returns

| Type         | Description                           |
| ------------ | ------------------------------------- |
| `AssetClass` | The asset class object in JSON format |

#### Example

```tsx
import { assetClass } from "@meshsdk/core";

// ADA
const ada = assetClass("", "");

// Native token
const token = assetClass(
  "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69",
  "4d657368546f6b656e"
);
```

***

## Other Utilities

### tuple

Create a tuple (pair) of values.

```tsx
import { tuple, byteString, integer } from "@meshsdk/core";

const pair = tuple(byteString("key"), integer(100));
```

### maybeStakingHash

Create an optional staking hash.

```tsx
import { maybeStakingHash } from "@meshsdk/core";

const withStake = maybeStakingHash("9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6");
const noStake = maybeStakingHash(null);
```

### dict

Create a dictionary (alternative to assocMap).

```tsx
import { dict, byteString, integer } from "@meshsdk/core";

const amounts = dict([
  [byteString("aa"), integer(100)],
  [byteString("bb"), integer(200)],
]);
```

***

## Complete Example

This example shows building complex datum structures for a token swap contract:

```tsx
import {
  conStr0,
  byteString,
  integer,
  list,
  assocMap,
  pubKeyAddress,
  assetClass,
  currencySymbol,
  tokenName,
  MeshTxBuilder,
} from "@meshsdk/core";

// Build the swap datum
const swapDatum = conStr0([
  // Owner address
  pubKeyAddress(
    "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
    "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
  ),
  // Offered asset
  assetClass(
    "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69",
    "4d657368546f6b656e"
  ),
  integer(100),
  // Requested asset (ADA)
  assetClass("", ""),
  integer(5000000),
]);

// Build the accept redeemer
const acceptRedeemer = conStr0([]);

// Build the transaction
const txBuilder = new MeshTxBuilder();

await txBuilder
  .spendingPlutusScript("V2")
  .txIn(utxo.txHash, utxo.outputIndex)
  .txInScript(swapScriptCbor)
  .txInDatumValue(swapDatum, "JSON")
  .txInRedeemerValue(acceptRedeemer, "JSON")
  .txOut(ownerAddress, [
    { unit: "lovelace", quantity: "5000000" },
  ])
  .txOut(buyerAddress, [
    {
      unit: "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e694d657368546f6b656e",
      quantity: "100",
    },
  ])
  .changeAddress(buyerAddress)
  .selectUtxosFrom(buyerUtxos)
  .complete();
```

***

## Troubleshooting

### Invalid hex string error

Byte strings must be valid hexadecimal. Check that:

* The string contains only characters 0-9 and a-f (case insensitive)
* The length is even (each byte is 2 hex characters)

### Constructor index mismatch

Ensure your constructor indices match your Plutus/Aiken type definitions. Index 0 is the first constructor, index 1 is the second, etc.

### Validation errors

If validation fails, check that all nested objects are also built using JSON data utilities. Raw JavaScript values may not pass validation.

***

## Related

* [Mesh Data](/apis/data/mesh) - Simpler data construction
* [Data Overview](/apis/data/overview) - Compare data formats
* [Value](/apis/data/value) - Work with multi-asset values
* [Transaction Builder](/apis/txbuilder) - Use data in transactions


# Mesh Data Builders
URL: /apis/data/mesh

Build Cardano data structures with simple JavaScript primitives

***

title: "Mesh Data Builders"
description: "Build Cardano data structures with simple JavaScript primitives"
------------------------------------------------------------------------------

Use Mesh data utilities to construct Cardano data with minimal boilerplate. These functions use native JavaScript types with thin wrappers for constructors and booleans.

## Overview

Mesh data utilities provide:

* Simple, JavaScript-native syntax
* Minimal wrapper overhead
* Direct use of primitives (numbers, strings, arrays, maps)
* Quick prototyping and development

The `m` prefix distinguishes Mesh data functions from JSON data functions.

## Quick Start

```tsx
import { mConStr0, mBool } from "@meshsdk/core";

// Build a simple datum using native types
const datum = mConStr0([
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6", // string as ByteString
  1000000n, // bigint as Integer
]);

// Use in a transaction
const txBuilder = new MeshTxBuilder();
await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutInlineDatumValue(datum, "Mesh")
  .complete();
```

***

## Type Mappings

Mesh data uses native JavaScript types:

| Cardano Type | Mesh Data Representation |
| ------------ | ------------------------ |
| Integer      | `number` or `bigint`     |
| ByteString   | `string` (hex)           |
| List         | `Array`                  |
| Map          | `Map`                    |
| Constructor  | `MConstr` object         |
| Boolean      | `MBool` object           |

***

## Constructor Utilities

Build Plutus constructor data types.

### mConStr

Create a constructor with a specific index.

#### Function Signature

```tsx
mConStr(alternative: number, fields: any[]): MConstr
```

#### Parameters

| Parameter     | Type     | Required | Description                           |
| ------------- | -------- | -------- | ------------------------------------- |
| `alternative` | `number` | Yes      | The constructor index (0, 1, 2, etc.) |
| `fields`      | `any[]`  | Yes      | Array of fields for the constructor   |

#### Returns

| Type      | Description                                       |
| --------- | ------------------------------------------------- |
| `MConstr` | Object with `alternative` and `fields` properties |

#### Example

```tsx
import { mConStr } from "@meshsdk/core";

// Create a constructor with index 0
const lockDatum = mConStr(0, [
  "owner-pub-key-hash",
  1704067200000n,
]);

// Create a constructor with index 1
const unlockRedeemer = mConStr(1, []);

// Result structure: { alternative: 0, fields: [...] }
```

### mConStr0, mConStr1, mConStr2

Shorthand functions for common constructor indices.

#### Function Signatures

```tsx
mConStr0(fields: any[]): MConStr  // constructor index 0
mConStr1(fields: any[]): MConStr  // constructor index 1
mConStr2(fields: any[]): MConStr  // constructor index 2
```

#### Parameters

| Parameter | Type    | Required | Description                         |
| --------- | ------- | -------- | ----------------------------------- |
| `fields`  | `any[]` | Yes      | Array of fields for the constructor |

#### Example

```tsx
import { mConStr0, mConStr1 } from "@meshsdk/core";

// Common pattern: mConStr0 for "success", mConStr1 for "failure"
const successResult = mConStr0(["data-hash", 1000000n]);
const failureResult = mConStr1(["error-message"]);

// Enum-like usage for redeemers
const mintRedeemer = mConStr0([]);
const burnRedeemer = mConStr1([]);
const updateRedeemer = mConStr2(["new-value"]);
```

***

## Boolean Utility

### mBool

Create a boolean value in Mesh data format.

#### Function Signature

```tsx
mBool(b: boolean): MBool
```

#### Parameters

| Parameter | Type      | Required | Description       |
| --------- | --------- | -------- | ----------------- |
| `b`       | `boolean` | Yes      | The boolean value |

#### Returns

| Type    | Description                                                |
| ------- | ---------------------------------------------------------- |
| `MBool` | Constructor representing true (index 1) or false (index 0) |

#### Example

```tsx
import { mBool } from "@meshsdk/core";

const isActive = mBool(true);   // { alternative: 1, fields: [] }
const isComplete = mBool(false); // { alternative: 0, fields: [] }
```

***

## Using Native Types

### Integers

Use `number` for small values and `bigint` for precision:

```tsx
import { mConStr0 } from "@meshsdk/core";

// Small integers can use number
const smallAmount = mConStr0([100]);

// Large integers should use bigint
const largeAmount = mConStr0([1000000000000000000n]);

// Always use bigint for ADA amounts (lovelace)
const adaAmount = 5000000n; // 5 ADA
```

### Byte Strings

Use hex-encoded strings:

```tsx
import { mConStr0 } from "@meshsdk/core";

// Key hashes
const ownerKeyHash = "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6";

// Policy IDs
const policyId = "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69";

// Asset names (hex-encoded)
const assetName = "4d657368546f6b656e"; // "MeshToken" in hex

const datum = mConStr0([ownerKeyHash, policyId, assetName]);
```

### Lists

Use native JavaScript arrays:

```tsx
import { mConStr0 } from "@meshsdk/core";

// List of amounts
const amounts = [100n, 200n, 300n];

// List of key hashes (signers)
const requiredSigners = [
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "bb048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b7",
];

// Nested structure
const datum = mConStr0([
  "owner",
  amounts,
  requiredSigners,
]);
```

### Maps

Use native JavaScript Map:

```tsx
import { mConStr0 } from "@meshsdk/core";

// Token balances
const balances = new Map([
  ["token-a", 100n],
  ["token-b", 200n],
]);

// Nested map for multi-asset value
const value = new Map([
  ["", new Map([["", 5000000n]])], // ADA
  [
    "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69",
    new Map([["4d657368546f6b656e", 100n]]),
  ],
]);

const datum = mConStr0([balances]);
```

***

## Address Utilities

### mPubKeyAddress

Create a public key address in Mesh data format.

#### Function Signature

```tsx
mPubKeyAddress(pubKeyHash: string, stakeCredential?: string): MPubKeyAddress
```

#### Parameters

| Parameter         | Type     | Required | Description                              |
| ----------------- | -------- | -------- | ---------------------------------------- |
| `pubKeyHash`      | `string` | Yes      | The payment key hash (56 hex characters) |
| `stakeCredential` | `string` | No       | Optional stake credential hash           |

#### Example

```tsx
import { mPubKeyAddress } from "@meshsdk/core";

// Enterprise address
const addr1 = mPubKeyAddress("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6");

// Base address with stake
const addr2 = mPubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);
```

### mScriptAddress

Create a script address in Mesh data format.

#### Function Signature

```tsx
mScriptAddress(scriptHash: string, stakeCredential?: string): MScriptAddress
```

#### Parameters

| Parameter         | Type     | Required | Description                         |
| ----------------- | -------- | -------- | ----------------------------------- |
| `scriptHash`      | `string` | Yes      | The script hash (56 hex characters) |
| `stakeCredential` | `string` | No       | Optional stake credential hash      |

#### Example

```tsx
import { mScriptAddress } from "@meshsdk/core";

const contractAddr = mScriptAddress(
  "5867c3b8e27840f556ac268b781578b14c5661fc63ee720dbeab663f"
);
```

***

## Reference Utilities

### mOutputReference / mTxOutRef

Create transaction output references.

```tsx
import { mOutputReference, mTxOutRef } from "@meshsdk/core";

const utxoRef = mOutputReference(
  "a0bd47e8938e7c41d4c1d7c22033892319d28f86fdace791d45c51946553791b",
  0
);

// Alias
const ref = mTxOutRef(
  "a0bd47e8938e7c41d4c1d7c22033892319d28f86fdace791d45c51946553791b",
  0
);
```

### mAssetClass

Create an asset class identifier.

```tsx
import { mAssetClass } from "@meshsdk/core";

// ADA
const ada = mAssetClass("", "");

// Native token
const token = mAssetClass(
  "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69",
  "4d657368546f6b656e"
);
```

***

## Other Utilities

### mTuple

Create a tuple (pair) of values.

```tsx
import { mTuple } from "@meshsdk/core";

const pair = mTuple("key-hash", 1000000n);
```

### mMaybeStakingHash

Create an optional staking hash.

```tsx
import { mMaybeStakingHash } from "@meshsdk/core";

const withStake = mMaybeStakingHash("9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6");
const noStake = mMaybeStakingHash(null);
```

***

## Complete Example

This example shows building datum and redeemer for a vesting contract:

```tsx
import {
  mConStr0,
  mConStr1,
  mPubKeyAddress,
  mBool,
  MeshTxBuilder,
} from "@meshsdk/core";

// Build the vesting datum
const vestingDatum = mConStr0([
  // Beneficiary address
  mPubKeyAddress(
    "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
    "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
  ),
  // Deadline (POSIX time)
  1704067200000n,
  // Amount in lovelace
  50000000n,
]);

// Build the claim redeemer
const claimRedeemer = mConStr0([]);

// Build with nested structures
const complexDatum = mConStr0([
  "owner-hash",
  1704067200000n,
  // List of allowed signers
  [
    "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
    "bb048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b7",
  ],
  // Token amounts map
  new Map([
    ["token-a", 100n],
    ["token-b", 200n],
  ]),
  // Is active flag
  mBool(true),
]);

// Use in transaction
const txBuilder = new MeshTxBuilder();

await txBuilder
  .spendingPlutusScript("V2")
  .txIn(utxo.txHash, utxo.outputIndex)
  .txInScript(vestingScriptCbor)
  .txInDatumValue(vestingDatum, "Mesh")
  .txInRedeemerValue(claimRedeemer, "Mesh")
  .txOut(beneficiaryAddress, [{ unit: "lovelace", quantity: "50000000" }])
  .invalidBefore(1704067200)
  .changeAddress(beneficiaryAddress)
  .selectUtxosFrom(beneficiaryUtxos)
  .complete();
```

***

## Comparison with JSON Data

| Feature     | Mesh Data         | JSON Data                        |
| ----------- | ----------------- | -------------------------------- |
| Syntax      | Minimal           | Verbose                          |
| Validation  | None              | Automatic                        |
| Integer     | `1000000n`        | `integer(1000000)`               |
| ByteString  | `"aa048..."`      | `byteString("aa048...")`         |
| List        | `[1n, 2n]`        | `list([integer(1), integer(2)])` |
| Constructor | `mConStr0([...])` | `conStr0([...])`                 |

Choose Mesh data for:

* Quick prototyping
* Simple scripts
* Minimal code

Choose JSON data for:

* Production applications
* Complex validations
* Type safety

***

## Troubleshooting

### BigInt serialization issues

Ensure you use `bigint` (with `n` suffix) for large numbers:

```tsx
// Correct
const amount = 1000000000000000000n;

// Incorrect - may lose precision
const amount = 1000000000000000000;
```

### String vs ByteString confusion

Hex strings in Mesh data are treated as byte strings. For text, convert to hex first:

```tsx
// Convert text to hex
const textToHex = (text: string) => Buffer.from(text).toString("hex");

const assetName = textToHex("MeshToken"); // "4d657368546f6b656e"
```

### Constructor index mismatch

Ensure constructor indices match your Plutus/Aiken type definitions:

```tsx
// Aiken enum: type Action { Mint, Burn, Update }
const mintAction = mConStr0([]);   // Index 0 = Mint
const burnAction = mConStr1([]);   // Index 1 = Burn
const updateAction = mConStr2([]); // Index 2 = Update
```

***

## Related

* [JSON Data](/apis/data/json) - Data with validation
* [Data Overview](/apis/data/overview) - Compare data formats
* [Value](/apis/data/value) - Work with multi-asset values
* [Transaction Builder](/apis/txbuilder) - Use data in transactions


# Data Formats Overview
URL: /apis/data/overview

Understand how MeshJS handles Cardano data formats and conversions

***

title: "Data Formats Overview"
description: "Understand how MeshJS handles Cardano data formats and conversions"
---------------------------------------------------------------------------------

Cardano uses specific data representations for on-chain operations. This guide explains the different data formats and how to work with them in MeshJS.

## Overview

Cardano data flows through three representation formats:

1. **CBOR** - The on-chain binary encoding format
2. **JSON** - Human-readable format for debugging and APIs
3. **Mesh Data** - Simplified JavaScript-native format

MeshJS lets you work with any of these formats and converts between them automatically when needed.

## CBOR Format

CBOR (Concise Binary Object Representation) is the native format for Cardano on-chain data. All data stored on the blockchain uses CBOR encoding.

### When to Use CBOR

* Receiving data from external blockchain tools
* Integrating with other Cardano serialization libraries
* Working with raw transaction data

### Example: Working with CBOR

```tsx
import { deserializeDatum } from "@meshsdk/core";

// Decode CBOR data from the blockchain
const cborDatum = "d8799f581caa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b61a000f4240ff";
const decodedDatum = deserializeDatum(cborDatum);

console.log("Decoded:", decodedDatum);
// { constructor: 0, fields: ["aa048e4c...", 1000000] }
```

***

## JSON Data Format

The JSON format provides a structured representation of Cardano data with explicit type wrappers. This format is ideal for web applications that need strong type validation.

### Structure

JSON data uses wrapper objects to indicate types:

```tsx
// Integer
{ "int": 1000000 }

// ByteString
{ "bytes": "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6" }

// Constructor
{
  "constructor": 0,
  "fields": [
    { "bytes": "aa048e4c..." },
    { "int": 1000000 }
  ]
}
```

### Example: Building JSON Data

```tsx
import { conStr0, byteString, integer, list } from "@meshsdk/core";

// Build a constructor with typed fields
const datum = conStr0([
  byteString("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6"),
  integer(1000000),
]);

// Build a list
const items = list([
  integer(100),
  integer(200),
  integer(300),
]);
```

For complete JSON data utilities, see [JSON Data](/apis/data/json).

***

## Mesh Data Format

The Mesh Data format uses native JavaScript primitives with minimal wrappers. This is the simplest way to work with Cardano data.

### Structure

Mesh data maps directly to JavaScript types:

```tsx
// Integer -> number or bigint
1000000n

// ByteString -> string
"aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6"

// List -> Array
[100n, 200n, 300n]

// Map -> Map
new Map([["key", "value"]])

// Constructor -> MConstr object
{ alternative: 0, fields: ["aa048e4c...", 1000000n] }
```

### Example: Building Mesh Data

```tsx
import { mConStr0, mConStr1, mBool } from "@meshsdk/core";

// Build a constructor with native values
const datum = mConStr0([
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  1000000n,
]);

// Build a boolean
const flag = mBool(true);

// Build with nested structures
const complexDatum = mConStr0([
  "owner-hash",
  [100n, 200n, 300n], // Native array as list
  new Map([["token", 500n]]), // Native Map
]);
```

For complete Mesh data utilities, see [Mesh Data](/apis/data/mesh).

***

## Format Comparison

| Feature     | CBOR      | JSON Data | Mesh Data |
| ----------- | --------- | --------- | --------- |
| Type safety | Manual    | Automatic | Manual    |
| Verbosity   | Compact   | Verbose   | Minimal   |
| Validation  | None      | Built-in  | None      |
| Debugging   | Difficult | Easy      | Easy      |
| Performance | Fastest   | Good      | Good      |

***

## Converting Between Formats

### JSON to CBOR

Use the transaction builder to automatically convert JSON data to CBOR:

```tsx
import { MeshTxBuilder, conStr0, byteString, integer } from "@meshsdk/core";

const datum = conStr0([
  byteString("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6"),
  integer(1000000),
]);

const txBuilder = new MeshTxBuilder();
await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutInlineDatumValue(datum, "JSON")
  .complete();
```

### Mesh Data to CBOR

```tsx
import { MeshTxBuilder, mConStr0 } from "@meshsdk/core";

const datum = mConStr0([
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  1000000n,
]);

const txBuilder = new MeshTxBuilder();
await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutInlineDatumValue(datum, "Mesh")
  .complete();
```

### CBOR to JSON/Mesh

```tsx
import { deserializeDatum } from "@meshsdk/core";

const cborDatum = "d8799f581caa048e4c...";
const decoded = deserializeDatum(cborDatum);

// Result is a JavaScript object representing the datum structure
console.log(decoded);
```

***

## Common Data Patterns

### Lock Datum (Owner + Deadline)

```tsx
// JSON format
import { conStr0, byteString, integer } from "@meshsdk/core";

const lockDatum = conStr0([
  byteString("owner-pub-key-hash"),
  integer(1704067200000), // Unix timestamp
]);

// Mesh format
import { mConStr0 } from "@meshsdk/core";

const lockDatum = mConStr0([
  "owner-pub-key-hash",
  1704067200000n,
]);
```

### NFT Metadata Reference

```tsx
// JSON format
import { conStr0, byteString } from "@meshsdk/core";

const metadataRef = conStr0([
  byteString("tx-hash"),
  integer(0), // output index
]);

// Mesh format
import { mConStr0 } from "@meshsdk/core";

const metadataRef = mConStr0([
  "tx-hash",
  0n,
]);
```

### Swap Datum (Asset Pair + Amounts)

```tsx
// JSON format
import { conStr0, byteString, integer, list } from "@meshsdk/core";

const swapDatum = conStr0([
  byteString("offered-policy-id"),
  byteString("offered-asset-name"),
  integer(100),
  byteString("requested-policy-id"),
  byteString("requested-asset-name"),
  integer(200),
]);

// Mesh format
import { mConStr0 } from "@meshsdk/core";

const swapDatum = mConStr0([
  "offered-policy-id",
  "offered-asset-name",
  100n,
  "requested-policy-id",
  "requested-asset-name",
  200n,
]);
```

***

## Complete Example

This example shows using both data formats in a complete smart contract interaction:

```tsx
import {
  MeshTxBuilder,
  conStr0,
  byteString,
  integer,
  mConStr0,
  deserializeDatum,
} from "@meshsdk/core";

// 1. Create datum in JSON format (for validation)
const jsonDatum = conStr0([
  byteString("aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6"),
  integer(1000000),
]);

// 2. Create redeemer in Mesh format (for simplicity)
const redeemer = mConStr0(["unlock"]);

// 3. Build transaction with both formats
const txBuilder = new MeshTxBuilder();

await txBuilder
  .spendingPlutusScript("V2")
  .txIn(utxo.txHash, utxo.outputIndex)
  .txInScript(scriptCbor)
  .txInDatumValue(jsonDatum, "JSON")
  .txInRedeemerValue(redeemer, "Mesh")
  .txOut(walletAddress, utxo.output.amount)
  .changeAddress(walletAddress)
  .complete();

// 4. Decode datum from blockchain (returns CBOR-decoded structure)
const onChainDatum = deserializeDatum(utxo.output.plutusData);
console.log("On-chain datum:", onChainDatum);
```

***

## Troubleshooting

### Type mismatch errors

Ensure you specify the correct format when providing data to transaction builders. Use `"JSON"` for JSON format data and `"Mesh"` for Mesh format data.

### Integer precision issues

For large numbers, always use `bigint` (e.g., `1000000n`) to avoid JavaScript number precision limitations.

### ByteString validation fails

Byte strings must be valid hexadecimal. If you have a bech32 address, use `deserializeAddress` to extract the key hash first.

***

## Related

* [JSON Data](/apis/data/json) - Build data with JSON utilities
* [Mesh Data](/apis/data/mesh) - Build data with Mesh utilities
* [Value](/apis/data/value) - Work with multi-asset values
* [Deserializers](/apis/utilities/deserializers) - Parse on-chain data


# Multi-Asset Value
URL: /apis/data/value

Manipulate multi-asset values with conversion, operation, and comparison utilities

***

title: "Multi-Asset Value"
description: "Manipulate multi-asset values with conversion, operation, and comparison utilities"
-------------------------------------------------------------------------------------------------

Use the MeshValue class and value utilities to work with Cardano multi-asset values. These tools simplify converting between formats, performing arithmetic operations, and comparing values.

## Overview

Working with Cardano values (ADA + native tokens) is complex. MeshValue provides:

* **Convertors** - Transform between Asset\[], Value, and data types
* **Operators** - Add, subtract, and merge values
* **Accessors** - Get quantities and list units
* **Comparators** - Compare values for validation

## Quick Start

```tsx
import { MeshValue } from "@meshsdk/common";

// Create from assets
const value = MeshValue.fromAssets([
  { unit: "lovelace", quantity: "5000000" },
  { unit: "policyId...assetName", quantity: "100" },
]);

// Add more assets
value.addAsset({ unit: "lovelace", quantity: "1000000" });

// Check if sufficient
const required = MeshValue.fromAssets([
  { unit: "lovelace", quantity: "3000000" },
]);
const hasSufficient = value.geq(required); // true
```

***

## Convertors

Convert between different value representations.

### fromAssets

Create a MeshValue from an array of assets.

#### Function Signature

```tsx
static fromAssets(assets: Asset[]): MeshValue
```

#### Parameters

| Parameter | Type      | Required | Description                                |
| --------- | --------- | -------- | ------------------------------------------ |
| `assets`  | `Asset[]` | Yes      | Array of assets with `unit` and `quantity` |

#### Returns

| Type        | Description              |
| ----------- | ------------------------ |
| `MeshValue` | A new MeshValue instance |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const assets = [
  { unit: "lovelace", quantity: "5000000" },
  { unit: "c21d710605bb00e69f3c175150552fc498316d80e7efdb1b186db38c000643b04d65736820676f6f64", quantity: "100" },
];

const value = MeshValue.fromAssets(assets);
console.log(value.value);
// { lovelace: 5000000n, "c21d710605bb00...": 100n }
```

### toAssets

Convert MeshValue to an array of assets.

#### Function Signature

```tsx
toAssets(): Asset[]
```

#### Returns

| Type      | Description                                |
| --------- | ------------------------------------------ |
| `Asset[]` | Array of assets with `unit` and `quantity` |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue();
value.addAsset({ unit: "lovelace", quantity: "5000000" });
value.addAsset({ unit: "policyId...assetName", quantity: "100" });

const assets = value.toAssets();
console.log(assets);
// [
//   { unit: "lovelace", quantity: "5000000" },
//   { unit: "policyId...assetName", quantity: "100" }
// ]
```

### fromValue

Create MeshValue from Plutus Value (JSON representation).

#### Function Signature

```tsx
static fromValue(plutusValue: Value): MeshValue
```

#### Parameters

| Parameter     | Type    | Required | Description                     |
| ------------- | ------- | -------- | ------------------------------- |
| `plutusValue` | `Value` | Yes      | The Plutus Value in JSON format |

#### Returns

| Type        | Description              |
| ----------- | ------------------------ |
| `MeshValue` | A new MeshValue instance |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";
import { value as createValue } from "@meshsdk/core";

const assets = [{ unit: "lovelace", quantity: "1000000" }];
const plutusValue = createValue(assets);

const meshValue = MeshValue.fromValue(plutusValue);
const recoveredAssets = meshValue.toAssets();
console.log(recoveredAssets);
// [{ unit: "lovelace", quantity: "1000000" }]
```

### toData

Convert MeshValue to Mesh Data format.

#### Function Signature

```tsx
toData(): MValue
```

#### Returns

| Type     | Description                             |
| -------- | --------------------------------------- |
| `MValue` | Value in Mesh Data format (nested Maps) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = MeshValue.fromAssets([
  { unit: "lovelace", quantity: "5000000" },
  { unit: "policyId1234assetName", quantity: "100" },
]);

const data = value.toData();
// Map { "" => Map { "" => 5000000n }, "policyId" => Map { "assetName" => 100n } }
```

### toJSON

Convert MeshValue to JSON Data format.

#### Function Signature

```tsx
toJSON(): Value
```

#### Returns

| Type    | Description                          |
| ------- | ------------------------------------ |
| `Value` | Value in JSON Data format (AssocMap) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = MeshValue.fromAssets([
  { unit: "lovelace", quantity: "1000000" },
  { unit: "c21d710605bb00e69f3c175150552fc498316d80e7efdb1b186db38c000643b04d65736820676f6f64", quantity: "500" },
]);

const jsonValue = value.toJSON();
// AssocMap structure for use in transactions
```

### value (function)

Convert assets to Plutus Value in JSON format.

#### Function Signature

```tsx
value(assets: Asset[]): Value
```

#### Example

```tsx
import { value } from "@meshsdk/core";

const val = [{ unit: "lovelace", quantity: "1000000" }];
const plutusValue = value(val);
```

### mValue (function)

Convert assets to Plutus Value in Mesh Data format.

#### Function Signature

```tsx
mValue(assets: Asset[]): MValue
```

#### Example

```tsx
import { mValue } from "@meshsdk/core";

const val = [{ unit: "lovelace", quantity: "1000000" }];
const meshValue = mValue(val);
// Map { "" => Map { "" => 1000000n } }
```

***

## Operators

Perform arithmetic operations on values.

### addAsset

Add a single asset to the value.

#### Function Signature

```tsx
addAsset(asset: Asset): MeshValue
```

#### Parameters

| Parameter | Type    | Required | Description  |
| --------- | ------- | -------- | ------------ |
| `asset`   | `Asset` | Yes      | Asset to add |

#### Returns

| Type        | Description                      |
| ----------- | -------------------------------- |
| `MeshValue` | The same instance (for chaining) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue();
value.addAsset({ unit: "lovelace", quantity: "5000000" });
value.addAsset({ unit: "lovelace", quantity: "1000000" }); // Adds to existing

console.log(value.get("lovelace")); // 6000000n
```

### addAssets

Add multiple assets to the value.

#### Function Signature

```tsx
addAssets(assets: Asset[]): MeshValue
```

#### Parameters

| Parameter | Type      | Required | Description            |
| --------- | --------- | -------- | ---------------------- |
| `assets`  | `Asset[]` | Yes      | Array of assets to add |

#### Returns

| Type        | Description                      |
| ----------- | -------------------------------- |
| `MeshValue` | The same instance (for chaining) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue();
value.addAssets([
  { unit: "lovelace", quantity: "5000000" },
  { unit: "policyId...assetName", quantity: "100" },
  { unit: "lovelace", quantity: "1000000" }, // Adds to first lovelace
]);

console.log(value.get("lovelace")); // 6000000n
```

### negateAsset

Subtract a single asset from the value.

#### Function Signature

```tsx
negateAsset(asset: Asset): MeshValue
```

#### Parameters

| Parameter | Type    | Required | Description       |
| --------- | ------- | -------- | ----------------- |
| `asset`   | `Asset` | Yes      | Asset to subtract |

#### Returns

| Type        | Description                      |
| ----------- | -------------------------------- |
| `MeshValue` | The same instance (for chaining) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue();
value.value = { lovelace: 10n };
value.negateAsset({ unit: "lovelace", quantity: "5" });

console.log(value.get("lovelace")); // 5n
```

### negateAssets

Subtract multiple assets from the value.

#### Function Signature

```tsx
negateAssets(assets: Asset[]): MeshValue
```

#### Parameters

| Parameter | Type      | Required | Description                 |
| --------- | --------- | -------- | --------------------------- |
| `assets`  | `Asset[]` | Yes      | Array of assets to subtract |

#### Returns

| Type        | Description                      |
| ----------- | -------------------------------- |
| `MeshValue` | The same instance (for chaining) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue();
value.value = {
  lovelace: 20n,
  "baefdc6c5b191be372a794cd8d40d839ec0dbdd3c28957267dc817001234": 10n,
};

value.negateAssets([
  { unit: "lovelace", quantity: "5" },
  { unit: "baefdc6c5b191be372a794cd8d40d839ec0dbdd3c28957267dc817001234", quantity: "3" },
]);

console.log(value.value);
// { lovelace: 15n, "baefdc6c5b191be...": 7n }
```

### merge

Combine two MeshValue instances.

#### Function Signature

```tsx
merge(other: MeshValue): MeshValue
```

#### Parameters

| Parameter | Type        | Required | Description    |
| --------- | ----------- | -------- | -------------- |
| `other`   | `MeshValue` | Yes      | Value to merge |

#### Returns

| Type        | Description                      |
| ----------- | -------------------------------- |
| `MeshValue` | The same instance (for chaining) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value1 = new MeshValue();
value1.value = { lovelace: 20n, "token1": 10n };

const value2 = new MeshValue();
value2.value = { lovelace: 10n, "token1": 5n };

const merged = value1.merge(value2);
console.log(merged.value);
// { lovelace: 30n, "token1": 15n }
```

***

## Accessors

Retrieve information from values.

### get

Get the quantity of a specific unit.

#### Function Signature

```tsx
get(unit: string): bigint
```

#### Parameters

| Parameter | Type     | Required | Description                          |
| --------- | -------- | -------- | ------------------------------------ |
| `unit`    | `string` | Yes      | The unit to query (e.g., "lovelace") |

#### Returns

| Type     | Description                      |
| -------- | -------------------------------- |
| `bigint` | The quantity (0n if not present) |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue({ lovelace: 5000000n });

console.log(value.get("lovelace")); // 5000000n
console.log(value.get("nonexistent")); // 0n
```

### units

Get all units present in the value.

#### Function Signature

```tsx
units(): string[]
```

#### Returns

| Type       | Description               |
| ---------- | ------------------------- |
| `string[]` | Array of unit identifiers |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue({
  lovelace: 20n,
  "baefdc6c5b191be372a794cd8d40d839ec0dbdd3c28957267dc817001234": 10n,
});

const allUnits = value.units();
console.log(allUnits);
// ["lovelace", "baefdc6c5b191be372a794cd8d40d839ec0dbdd3c28957267dc817001234"]
```

***

## Comparators

Compare values for validation.

### geq

Check if the value is greater than or equal to another value (all units).

#### Function Signature

```tsx
geq(other: MeshValue): boolean
```

#### Parameters

| Parameter | Type        | Required | Description              |
| --------- | ----------- | -------- | ------------------------ |
| `other`   | `MeshValue` | Yes      | Value to compare against |

#### Returns

| Type      | Description                           |
| --------- | ------------------------------------- |
| `boolean` | `true` if this >= other for all units |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const available = new MeshValue({
  lovelace: 20n,
  "token1": 10n,
});

const required = new MeshValue({
  lovelace: 10n,
  "token1": 5n,
});

console.log(available.geq(required)); // true

const insufficient = new MeshValue({
  lovelace: 25n, // More than available
});

console.log(available.geq(insufficient)); // false
```

### geqUnit

Check if a specific unit is greater than or equal to another value.

#### Function Signature

```tsx
geqUnit(unit: string, other: MeshValue): boolean
```

#### Parameters

| Parameter | Type        | Required | Description              |
| --------- | ----------- | -------- | ------------------------ |
| `unit`    | `string`    | Yes      | The unit to compare      |
| `other`   | `MeshValue` | Yes      | Value to compare against |

#### Returns

| Type      | Description                       |
| --------- | --------------------------------- |
| `boolean` | `true` if this unit >= other unit |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue({ lovelace: 20n, "token1": 10n });
const target = new MeshValue({ lovelace: 10n, "token1": 15n });

console.log(value.geqUnit("lovelace", target)); // true (20 >= 10)
console.log(value.geqUnit("token1", target)); // false (10 < 15)
```

### leq

Check if the value is less than or equal to another value (all units).

#### Function Signature

```tsx
leq(other: MeshValue): boolean
```

#### Parameters

| Parameter | Type        | Required | Description              |
| --------- | ----------- | -------- | ------------------------ |
| `other`   | `MeshValue` | Yes      | Value to compare against |

#### Returns

| Type      | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `boolean` | `true` if this value is less than or equal to other for all units |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue({ lovelace: 20n, "token1": 10n });
const limit = new MeshValue({ lovelace: 30n, "token1": 15n });

console.log(value.leq(limit)); // true
```

### leqUnit

Check if a specific unit is less than or equal to another value.

#### Function Signature

```tsx
leqUnit(unit: string, other: MeshValue): boolean
```

#### Parameters

| Parameter | Type        | Required | Description              |
| --------- | ----------- | -------- | ------------------------ |
| `unit`    | `string`    | Yes      | The unit to compare      |
| `other`   | `MeshValue` | Yes      | Value to compare against |

#### Returns

| Type      | Description                                             |
| --------- | ------------------------------------------------------- |
| `boolean` | `true` if this unit is less than or equal to other unit |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const value = new MeshValue({ lovelace: 20n, "token1": 10n });
const target = new MeshValue({ lovelace: 30n, "token1": 15n });

console.log(value.leqUnit("lovelace", target)); // true (20 ≤ 30)
console.log(value.leqUnit("token1", target)); // true (10 ≤ 15)
```

### isEmpty

Check if the value contains no assets.

#### Function Signature

```tsx
isEmpty(): boolean
```

#### Returns

| Type      | Description                 |
| --------- | --------------------------- |
| `boolean` | `true` if no assets present |

#### Example

```tsx
import { MeshValue } from "@meshsdk/common";

const emptyValue = new MeshValue();
console.log(emptyValue.isEmpty()); // true

const value = new MeshValue({ lovelace: 5000000n });
console.log(value.isEmpty()); // false
```

***

## Complete Example

This example demonstrates a complete value validation workflow:

```tsx
import { MeshValue } from "@meshsdk/common";

// Scenario: Validate a swap transaction

// User's available balance
const userBalance = MeshValue.fromAssets([
  { unit: "lovelace", quantity: "10000000" },
  { unit: "policyIdAssetName", quantity: "500" },
]);

// Required for the swap
const swapCost = MeshValue.fromAssets([
  { unit: "lovelace", quantity: "2000000" }, // tx fee
  { unit: "policyIdAssetName", quantity: "100" }, // tokens to swap
]);

// Check if user can afford the swap
if (userBalance.geq(swapCost)) {
  console.log("User can proceed with swap");

  // Calculate remaining balance
  const remaining = MeshValue.fromAssets(userBalance.toAssets());
  remaining.negateAssets(swapCost.toAssets());

  console.log("Remaining after swap:", remaining.toAssets());
  // [{ unit: "lovelace", quantity: "8000000" }, { unit: "policyIdAssetName", quantity: "400" }]
} else {
  console.log("Insufficient balance");

  // Show what's missing
  const lovelaceNeeded = swapCost.get("lovelace") - userBalance.get("lovelace");
  if (lovelaceNeeded > 0n) {
    console.log(`Need ${lovelaceNeeded} more lovelace`);
  }
}

// Convert to Plutus format for smart contract
const plutusValue = userBalance.toJSON();
const meshDataValue = userBalance.toData();
```

***

## Troubleshooting

### Quantity mismatch between formats

When converting between formats, quantities are preserved as bigint. Ensure you handle string conversion properly:

```tsx
// From string quantity
const asset = { unit: "lovelace", quantity: "5000000" };

// In MeshValue
const value = MeshValue.fromAssets([asset]);
console.log(value.get("lovelace")); // 5000000n (bigint)

// Back to Asset[]
const assets = value.toAssets();
console.log(assets[0].quantity); // "5000000" (string)
```

### Comparing values with different units

`geq` returns `false` if the compared value has units not present in this value:

```tsx
const value = new MeshValue({ lovelace: 1000000n });
const required = new MeshValue({ lovelace: 500000n, "token1": 10n });

console.log(value.geq(required)); // false - missing token1
```

### Empty unit after subtraction

Subtracting the exact amount leaves a zero value:

```tsx
const value = new MeshValue({ lovelace: 100n });
value.negateAsset({ unit: "lovelace", quantity: "100" });

console.log(value.get("lovelace")); // 0n
console.log(value.isEmpty()); // May still be false if unit exists with 0
```

***

## Related

* [JSON Data](/apis/data/json) - Value utilities in JSON format
* [Mesh Data](/apis/data/mesh) - Value utilities in Mesh format
* [Data Overview](/apis/data/overview) - Compare data formats
* [Transaction Builder](/apis/txbuilder) - Use values in transactions


# Transaction Builder Basics
URL: /apis/txbuilder/basics

Build and customize Cardano transactions with the MeshTxBuilder low-level API.

***

title: "Transaction Builder Basics"
description: "Build and customize Cardano transactions with the MeshTxBuilder low-level API."
---------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

`MeshTxBuilder` is a powerful, low-level API for constructing Cardano transactions. It provides fine-grained control over every aspect of transaction building, from simple ADA transfers to complex multi-signature and smart contract interactions.

**When to use MeshTxBuilder:**

* Building custom transaction logic beyond standard transfers
* Creating multi-signature transactions
* Interacting with Plutus smart contracts
* Optimizing transaction fees and execution units

## Quick Start

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

// Initialize provider and builder
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Build a simple transfer
const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## Configuration

### Constructor Options

```tsx
const txBuilder = new MeshTxBuilder({
  fetcher: provider,      // Required for auto-fetching UTXO data
  submitter: provider,    // Optional: for direct submission via builder
  evaluator: provider,    // Optional: for script execution unit optimization
  serializer: serializer, // Optional: custom serializer (default: CSLSerializer)
  params: protocolParams, // Optional: custom protocol parameters
  isHydra: false,         // Optional: use Hydra protocol parameters
  verbose: true,          // Optional: enable detailed logging
});
```

| Option       | Type                | Required    | Description                              |
| ------------ | ------------------- | ----------- | ---------------------------------------- |
| `fetcher`    | `IFetcher`          | Recommended | Provider for fetching blockchain data    |
| `submitter`  | `ISubmitter`        | No          | Provider for submitting transactions     |
| `evaluator`  | `IEvaluator`        | No          | Provider for evaluating script execution |
| `serializer` | `IMeshTxSerializer` | No          | Custom transaction serializer            |
| `params`     | `Partial<Protocol>` | No          | Custom protocol parameters               |
| `isHydra`    | `boolean`           | No          | Enable Hydra-specific parameters         |
| `verbose`    | `boolean`           | No          | Enable detailed console logging          |

## Sending ADA

### Basic Transfer

Send ADA to a recipient address:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Build transaction
const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Send Multiple Outputs

Send to multiple recipients in a single transaction:

```tsx
const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  .txOut("addr_test1qr...", [{ unit: "lovelace", quantity: "3000000" }])
  .txOut("addr_test1qs...", [{ unit: "lovelace", quantity: "2000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Send Native Assets

Include native assets (tokens/NFTs) in the output:

```tsx
const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [
    { unit: "lovelace", quantity: "2000000" },
    { unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e", quantity: "1" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

## Input Selection

### Automatic Selection

Let Mesh automatically select UTXOs to cover the transaction:

```tsx
const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Selection Strategies

Configure how UTXOs are selected:

```tsx
txBuilder.selectUtxosFrom(
  utxos,           // Available UTXOs
  "largestFirst",  // Selection strategy
  "5000000",       // Minimum threshold (lovelace)
  true             // Include transaction fees in calculation
);
```

| Strategy                 | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `experimental`           | Mesh's optimized selection algorithm            |
| `keepRelevant`           | Prefer UTXOs with relevant assets               |
| `largestFirst`           | Select largest UTXOs first                      |
| `largestFirstMultiAsset` | Optimized for transactions with multiple assets |

### Manual Input Selection

Explicitly specify which UTXOs to spend:

```tsx
const unsignedTx = await txBuilder
  .txIn(
    "abc123...",  // Transaction hash
    0,            // Output index
    [{ unit: "lovelace", quantity: "10000000" }], // Amount
    "addr_test1qz..." // Address
  )
  .txOut("addr_test1qr...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .complete();
```

## Multi-Signature Transactions

Create transactions requiring multiple signatures:

```tsx
import { MeshTxBuilder, ForgeScript, resolveScriptHash, stringToHex } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Create minting wallet
const mintingWallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "mnemonic", "words", "..."],
});

// Create forging script
const forgingScript = ForgeScript.withOneSignature(
  await mintingWallet.getChangeAddressBech32()
);

const policyId = resolveScriptHash(forgingScript);
const assetName = "MeshToken";

// Get user wallet data
const address = (await wallet.getUsedAddresses())[0];
const utxos = await wallet.getUtxos();

// Build multi-sig transaction
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const unsignedTx = await txBuilder
  .mint("1", policyId, stringToHex(assetName))
  .mintingScript(forgingScript)
  .metadataValue(721, {
    [policyId]: {
      [assetName]: { name: "Mesh Token", image: "ipfs://..." }
    }
  })
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

// Sign with both wallets (partial signing)
const signedTx1 = await wallet.signTx(unsignedTx, true, false);
const signedTx2 = await mintingWallet.signTx(signedTx1, true, false);

// Submit final transaction
const txHash = await wallet.submitTx(signedTx2);
```

## Native Script Multi-Sig

Spend from a native script address requiring multiple signatures:

```tsx
import { deserializeAddress, serializeNativeScript, NativeScript } from "@meshsdk/core";

// Get key hashes from addresses
const { pubKeyHash: keyHash1 } = deserializeAddress(walletAddress1);
const { pubKeyHash: keyHash2 } = deserializeAddress(walletAddress2);

// Create native script requiring both signatures
const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    { type: "sig", keyHash: keyHash1 },
    { type: "sig", keyHash: keyHash2 },
  ],
};

// Serialize script to get address
const { address: scriptAddress, scriptCbor } = serializeNativeScript(nativeScript);

// Fetch UTXOs from script address
const scriptUtxos = await provider.fetchAddressUTxOs(scriptAddress);
const utxo = scriptUtxos[0];

// Build transaction spending from script
const unsignedTx = await txBuilder
  .txIn(
    utxo.input.txHash,
    utxo.input.outputIndex,
    utxo.output.amount,
    utxo.output.address
  )
  .txInScript(scriptCbor)
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "2000000" }])
  .changeAddress(scriptAddress)
  .selectUtxosFrom(scriptUtxos)
  .complete();

// Both wallets must sign
const signedTx1 = await wallet1.signTx(unsignedTx, true, false);
const signedTx2 = await wallet2.signTx(signedTx1, true, false);
const txHash = await wallet1.submitTx(signedTx2);
```

## Transaction Metadata

### Add Messages

Attach messages to transactions using label 674 (CIP-20):

```tsx
const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .metadataValue(674, {
    msg: [
      "Invoice-No: 1234567890",
      "Customer-No: 555-1234"
    ]
  })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

Each message string must be at most 64 bytes when UTF-8 encoded.

### Custom Metadata

Add any JSON-compatible metadata:

```tsx
const unsignedTx = await txBuilder
  .metadataValue(customLabel, {
    key: "value",
    nested: { data: [1, 2, 3] }
  })
  .txOut(address, amount)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

## Transaction Validity

### Set Expiration (TTL)

Make a transaction invalid after a specific slot:

```tsx
import { resolveSlotNo } from "@meshsdk/core";

// Transaction expires in 5 minutes
const expirationTime = new Date(Date.now() + 5 * 60 * 1000);
const slot = resolveSlotNo("mainnet", expirationTime.getTime());

const unsignedTx = await txBuilder
  .txOut(address, amount)
  .invalidHereafter(Number(slot))
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Set Start Time

Make a transaction invalid before a specific slot:

```tsx
const startTime = new Date(Date.now() + 10 * 60 * 1000); // 10 minutes from now
const startSlot = resolveSlotNo("mainnet", startTime.getTime());

const unsignedTx = await txBuilder
  .txOut(address, amount)
  .invalidBefore(Number(startSlot))
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

## Required Signers

Specify required signers for smart contract transactions:

```tsx
import { deserializeAddress } from "@meshsdk/core";

const { pubKeyHash } = deserializeAddress(walletAddress);

const unsignedTx = await txBuilder
  // ... transaction details
  .requiredSignerHash(pubKeyHash)
  .complete();
```

## Network Configuration

### Set Network

Configure the network for proper cost model calculation:

```tsx
txBuilder.setNetwork("mainnet"); // or "testnet", "preview", "preprod"
```

### Custom Protocol Parameters

Use specific protocol parameters:

```tsx
const params = await provider.fetchProtocolParameters();

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  params: params,
});
```

## Manual Fee Control

Override automatic fee calculation:

```tsx
const unsignedTx = await txBuilder
  .txOut(address, amount)
  .changeAddress(changeAddress)
  .setFee("200000") // Set exact fee in lovelace
  .complete();
```

## Build with JSON

Alternative method using a JSON object:

```tsx
import { MeshTxBuilderBody } from "@meshsdk/core";

const meshTxBody: Partial<MeshTxBuilderBody> = {
  outputs: [
    {
      address: recipientAddress,
      amount: [{ unit: "lovelace", quantity: "5000000" }],
    },
  ],
  changeAddress: changeAddress,
  extraInputs: utxos,
  selectionConfig: {
    threshold: "5000000",
    strategy: "largestFirst",
    includeTxFees: true,
  },
};

const unsignedTx = await txBuilder.complete(meshTxBody);
```

## Complete Example

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveSlotNo
} from "@meshsdk/core";

// Setup
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Set expiration (5 minutes)
const expiration = new Date(Date.now() + 5 * 60 * 1000);
const expirationSlot = resolveSlotNo("preprod", expiration.getTime());

// Build transaction
const unsignedTx = await txBuilder
  // Send 5 ADA to recipient
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  // Send 3 ADA + token to another recipient
  .txOut("addr_test1qr...", [
    { unit: "lovelace", quantity: "3000000" },
    { unit: "policyId...", quantity: "1" }
  ])
  // Add transaction message
  .metadataValue(674, { msg: ["Payment for services"] })
  // Set expiration
  .invalidHereafter(Number(expirationSlot))
  // Configure change and UTXO selection
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos, "largestFirst", "5000000", true)
  // Build the transaction
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Transaction submitted: ${txHash}`);
```

## Troubleshooting

### "Insufficient funds" error

* Ensure UTXOs have enough ADA to cover outputs + fees + min UTxO values
* Check that `selectUtxosFrom` is provided with current UTXOs
* For native asset outputs, ensure minimum ADA (typically \~1.5 ADA) is included

### "Missing input" error

* The `fetcher` provider is required for automatic UTXO data fetching
* If using manual `txIn`, provide all four parameters (txHash, index, amount, address)

### Transaction too large

* Split into multiple transactions
* Reduce the number of outputs
* Use UTXO consolidation first

### Invalid slot number

* Ensure you're using the correct network in `resolveSlotNo`
* Mainnet and testnets have different slot calculations

### Multi-sig transaction fails

* Ensure `partialSign: true` is set for all signers except the last
* Verify all required signers have signed
* Check that signing order doesn't matter (unless script requires specific order)

## Related

* <Link href="/apis/txbuilder/minting">Minting Tokens</Link> - Mint native assets
* <Link href="/apis/txbuilder/smart-contracts">Smart Contracts</Link> - Interact with Plutus scripts
* <Link href="/apis/txbuilder/staking">Staking</Link> - Delegation and rewards
* <Link href="/apis/txbuilder/governance">Governance</Link> - Voting and proposals
* <Link href="/providers/blockfrost">Blockfrost Provider</Link> - Provider setup


# Governance Transactions
URL: /apis/txbuilder/governance

Participate in Cardano's on-chain governance through DRep delegation, registration, voting, and submitting governance action proposals.

***

title: "Governance Transactions"
description: "Participate in Cardano's on-chain governance through DRep delegation, registration, voting, and submitting governance action proposals."
------------------------------------------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

Cardano's on-chain governance system ([CIP-1694](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md)) enables the community to vote on proposals and protocol updates. Mesh SDK implements the [CIP-95](https://cips.cardano.org/cip/CIP-0095) Web-Wallet Bridge extension, allowing dApps to interact with governance features. You can delegate your voting power to Decentralized Representatives (DReps), register as a DRep yourself, vote on governance actions, and submit new governance action proposals.

**When to use this:**

* Delegating your voting power to a DRep
* Registering as a DRep to represent other voters
* Voting on governance actions and protocol changes
* Submitting governance action proposals (info actions, parameter changes, treasury withdrawals, etc.)
* Building governance dashboards and tools
* Creating DRep management applications

## Quick Start

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

// Initialize
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

// Delegate to a DRep
txBuilder
  .voteDelegationCertificate(
    { dRepId: "drep1yv4uesaj92wk8ljlsh4p7jzndnzrflchaz5fzug3zxg4naqkpeas3" },
    rewardAddress
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## API Reference

### voteDelegationCertificate()

Delegate voting power to a DRep.

```tsx
.voteDelegationCertificate(drep: DRepId, rewardAddress: string)
```

| Parameter       | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `drep`          | `DRepId` | DRep identifier object    |
| `rewardAddress` | `string` | Your stake/reward address |

The `DRepId` object can specify:

* `{ dRepId: "drep1..." }` - Delegate to a specific DRep
* `{ alwaysAbstain: true }` - Always abstain from voting
* `{ alwaysNoConfidence: true }` - Always vote no confidence

### drepRegistrationCertificate()

Register as a DRep.

```tsx
.drepRegistrationCertificate(dRepId: string, anchor?: Anchor)
```

| Parameter | Type     | Description                |
| --------- | -------- | -------------------------- |
| `dRepId`  | `string` | Your DRep ID (from wallet) |
| `anchor`  | `Anchor` | Optional metadata anchor   |

The `Anchor` object:

```tsx
{
  anchorUrl: string;      // URL to metadata JSON
  anchorDataHash: string; // Hash of metadata content
}
```

### drepUpdateCertificate()

Update DRep metadata.

```tsx
.drepUpdateCertificate(dRepId: string, anchor?: Anchor)
```

| Parameter | Type     | Description         |
| --------- | -------- | ------------------- |
| `dRepId`  | `string` | Your DRep ID        |
| `anchor`  | `Anchor` | New metadata anchor |

### drepDeregistrationCertificate()

Retire as a DRep and reclaim deposit.

```tsx
.drepDeregistrationCertificate(dRepId: string)
```

| Parameter | Type     | Description            |
| --------- | -------- | ---------------------- |
| `dRepId`  | `string` | Your DRep ID to retire |

### vote()

Cast a vote on a governance action.

```tsx
.vote(voter: Voter, govActionId: GovActionId, votingProcedure: VotingProcedure)
```

| Parameter         | Type              | Description                 |
| ----------------- | ----------------- | --------------------------- |
| `voter`           | `Voter`           | Voter identity              |
| `govActionId`     | `GovActionId`     | Governance action reference |
| `votingProcedure` | `VotingProcedure` | Vote details                |

The `Voter` object:

```tsx
// DRep voter
{ type: "DRep", drepId: "drep1..." }

// Stake pool operator
{ type: "StakePool", poolId: "pool1..." }

// Constitutional committee member
{ type: "ConstitutionalCommittee", hotCred: "..." }
```

The `VotingProcedure` object:

```tsx
{
  voteKind: "Yes" | "No" | "Abstain";
  anchor?: {
    anchorUrl: string;
    anchorDataHash: string;
  };
}
```

### votePlutusScriptV3()

Indicate voting with a Plutus script.

```tsx
.votePlutusScriptV3()
```

### voteScript()

Provide the voting script.

```tsx
.voteScript(scriptCbor: string)
```

### voteRedeemerValue()

Provide the redeemer for script-based voting.

```tsx
.voteRedeemerValue(redeemer: Data | object | string, type?: "Mesh" | "CBOR" | "JSON", exUnits?: Budget)
```

### proposal()

Submit a governance action proposal. Requires a deposit (returned when the action is resolved).

```tsx
.proposal(governanceAction: GovernanceAction, anchor: Anchor, rewardAccount: string, deposit?: string)
```

| Parameter          | Type               | Description                                                                 |
| ------------------ | ------------------ | --------------------------------------------------------------------------- |
| `governanceAction` | `GovernanceAction` | The governance action to propose                                            |
| `anchor`           | `Anchor`           | Proposal metadata anchor (URL + hash)                                       |
| `rewardAccount`    | `string`           | Reward address for deposit return                                           |
| `deposit`          | `string`           | Deposit amount in lovelace (defaults to `"100000000000"`, i.e. 100,000 ADA) |

The `GovernanceAction` is a discriminated union with a `kind` and `action` field:

```tsx
// Info action (no on-chain effect, used for polls/sentiment)
{ kind: "InfoAction", action: {} }

// Protocol parameter change
{
  kind: "ParameterChangeAction",
  action: {
    govActionId?: { transactionId: string; govActionIndex: number },
    protocolParamUpdates: ProtocolParamUpdate,
    policyHash?: { bytes: string },
  }
}

// Treasury withdrawal
{
  kind: "TreasuryWithdrawalsAction",
  action: {
    withdrawals: Record<string, string>,  // reward address -> lovelace amount
    policyHash?: { bytes: string },
  }
}

// No confidence in current committee
{
  kind: "NoConfidenceAction",
  action: {
    govActionId?: { transactionId: string; govActionIndex: number },
  }
}

// Update constitutional committee
{
  kind: "UpdateCommitteeAction",
  action: {
    govActionId?: { transactionId: string; govActionIndex: number },
    committee: {
      members: Array<{ stakeCredential: Credential; termLimit: number }>,
      quorumThreshold: { numerator: string; denominator: string },
    },
    membersToRemove: Credential[],
  }
}

// New constitution
{
  kind: "NewConstitutionAction",
  action: {
    govActionId?: { transactionId: string; govActionIndex: number },
    constitution: {
      anchor: Anchor,
      scriptHash?: { bytes: string },
    },
  }
}

// Hard fork initiation
{
  kind: "HardForkInitiationAction",
  action: {
    govActionId?: { transactionId: string; govActionIndex: number },
    protocolVersion: { major: number; minor: number },
  }
}
```

The `Credential` type used in committee actions:

```tsx
{ type: "KeyHash", keyHash: string }
// or
{ type: "ScriptHash", scriptHash: string }
```

The `govActionId` field is optional and refers to the most recently enacted governance action of the same type that this proposal builds upon. It is required for action types that must chain from a previous action (parameter changes, hard forks, committee updates, no confidence, new constitution).

### proposalScript()

Attach a Plutus script witness to the proposal.

```tsx
.proposalScript(scriptCbor: string, version: "V1" | "V2" | "V3")
```

| Parameter    | Type              | Description                   |
| ------------ | ----------------- | ----------------------------- |
| `scriptCbor` | `string`          | CBOR hex of the Plutus script |
| `version`    | `LanguageVersion` | Plutus language version       |

### proposalTxInReference()

Use a reference script for the proposal instead of providing it inline.

```tsx
.proposalTxInReference(txHash: string, txIndex: number, scriptSize: string, scriptHash: string, version: "V1" | "V2" | "V3")
```

| Parameter    | Type              | Description                             |
| ------------ | ----------------- | --------------------------------------- |
| `txHash`     | `string`          | Transaction hash of the reference UTxO  |
| `txIndex`    | `number`          | Transaction index of the reference UTxO |
| `scriptSize` | `string`          | Size of the Plutus script in bytes      |
| `scriptHash` | `string`          | Script hash of the referenced script    |
| `version`    | `LanguageVersion` | Plutus language version                 |

### proposalRedeemerValue()

Provide the redeemer for a Plutus script proposal.

```tsx
.proposalRedeemerValue(redeemer: Data | object | string, type?: "Mesh" | "CBOR" | "JSON", exUnits?: Budget)
```

| Parameter  | Type                       | Description                                                                 |
| ---------- | -------------------------- | --------------------------------------------------------------------------- |
| `redeemer` | `Data \| object \| string` | Redeemer data                                                               |
| `type`     | `string`                   | Data format type (default `"Mesh"`)                                         |
| `exUnits`  | `Budget`                   | Execution units budget (default `{ mem: 7_000_000, steps: 3_000_000_000 }`) |

## Common Patterns

### Delegate to a DRep

Delegate your voting power to a registered DRep:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

const dRepId = "drep1yv4uesaj92wk8ljlsh4p7jzndnzrflchaz5fzug3zxg4naqkpeas3";

txBuilder
  .voteDelegationCertificate({ dRepId }, rewardAddress)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Delegated to DRep: ${txHash}`);
```

### Delegate to Always Abstain

Configure your stake to always abstain from voting:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

txBuilder
  .voteDelegationCertificate({ alwaysAbstain: true }, rewardAddress)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Register as a DRep

Register yourself as a DRep with metadata:

```tsx
import { MeshTxBuilder, BlockfrostProvider, hashDrepAnchor } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get DRep ID from wallet
const dRep = await wallet.getDRep();
const dRepId = dRep.dRepIDCip105;

// Prepare metadata anchor
const anchorUrl = "https://example.com/drep-metadata.jsonld";
const anchorMetadata = {
  "@context": {
    "@language": "en",
    "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md",
    "CIP119": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0119/README.md",
    "hashAlgorithm": "CIP100:hashAlgorithm",
    "body": { "@id": "CIP119:body" },
    "givenName": "CIP119:givenName"
  },
  "hashAlgorithm": "blake2b-256",
  "body": {
    "givenName": "My DRep Name"
  }
};
const anchorHash = hashDrepAnchor(anchorMetadata);

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

txBuilder
  .drepRegistrationCertificate(dRepId, {
    anchorUrl,
    anchorDataHash: anchorHash,
  })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`DRep registered: ${txHash}`);
```

### Update DRep Metadata

Update your DRep profile information:

```tsx
import { MeshTxBuilder, BlockfrostProvider, hashDrepAnchor } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const dRep = await wallet.getDRep();
const dRepId = dRep.dRepIDCip105;

// New metadata
const anchorUrl = "https://example.com/drep-metadata-v2.jsonld";
const anchorMetadata = { /* updated metadata */ };
const anchorHash = hashDrepAnchor(anchorMetadata);

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

txBuilder
  .drepUpdateCertificate(dRepId, {
    anchorUrl,
    anchorDataHash: anchorHash,
  })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`DRep updated: ${txHash}`);
```

### Retire as DRep

Retire from being a DRep and reclaim your deposit:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const dRep = await wallet.getDRep();
const dRepId = dRep.dRepIDCip105;

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

txBuilder
  .drepDeregistrationCertificate(dRepId)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`DRep retired: ${txHash}`);
```

### Vote on Governance Action

Cast a vote as a DRep:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const dRep = await wallet.getDRep();
const dRepId = dRep.dRepIDCip105;

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Governance action to vote on
const govActionTxHash = "aff2909f8175ee02a8c1bf96ff516685d25bf0c6b95aac91f4dfd53a5c0867cc";
const govActionIndex = 0;

txBuilder
  .vote(
    {
      type: "DRep",
      drepId: dRepId,
    },
    {
      txHash: govActionTxHash,
      txIndex: govActionIndex,
    },
    {
      voteKind: "Yes",
    }
  )
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Vote cast: ${txHash}`);
```

### Vote with Rationale

Include reasoning for your vote:

```tsx
import { MeshTxBuilder, BlockfrostProvider, hashDrepAnchor } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const dRep = await wallet.getDRep();
const dRepId = dRep.dRepIDCip105;

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Prepare vote rationale
const rationaleUrl = "https://example.com/vote-rationale.jsonld";
const rationaleContent = {
  rationale: "I support this proposal because...",
  references: ["https://example.com/supporting-doc"],
};
const rationaleHash = hashDrepAnchor(rationaleContent);

txBuilder
  .vote(
    {
      type: "DRep",
      drepId: dRepId,
    },
    {
      txHash: "abc123...",
      txIndex: 0,
    },
    {
      voteKind: "Yes",
      anchor: {
        anchorUrl: rationaleUrl,
        anchorDataHash: rationaleHash,
      },
    }
  )
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Vote with Plutus Script

Vote using a Plutus script DRep:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  resolveScriptHashDRepId,
  applyCborEncoding
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral = await wallet.getCollateral();
const changeAddress = await wallet.getChangeAddress();

// Your voting script
const votingScriptCbor = applyCborEncoding("your-voting-script-cbor");
const scriptHash = resolveScriptHash(votingScriptCbor, "V3");
const scriptDRepId = resolveScriptHashDRepId(scriptHash);

txBuilder
  .txIn(
    utxos[0]!.input.txHash,
    utxos[0]!.input.outputIndex,
    utxos[0]!.output.amount,
    utxos[0]!.output.address
  )
  .txInCollateral(
    collateral[0]!.input.txHash,
    collateral[0]!.input.outputIndex,
    collateral[0]!.output.amount,
    collateral[0]!.output.address
  )
  .votePlutusScriptV3()
  .vote(
    {
      type: "DRep",
      drepId: scriptDRepId,
    },
    {
      txHash: "abc123...",
      txIndex: 0,
    },
    {
      voteKind: "Yes",
    }
  )
  .voteScript(votingScriptCbor)
  .voteRedeemerValue("")
  .changeAddress(changeAddress);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);
```

### Submit an Info Action

Submit an info action (used for polls and sentiment checks — has no on-chain effect):

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

txBuilder
  .proposal(
    {
      kind: "InfoAction",
      action: {},
    },
    {
      anchorUrl: "https://example.com/proposal.jsonld",
      anchorDataHash: "a1b1c2d3e4f5...",
    },
    rewardAddress
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Info action submitted: ${txHash}`);
```

### Submit a Treasury Withdrawal

Propose a treasury withdrawal to one or more reward addresses:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

txBuilder
  .proposal(
    {
      kind: "TreasuryWithdrawalsAction",
      action: {
        withdrawals: {
          [rewardAddress]: "50000000000", // 50,000 ADA in lovelace
        },
      },
    },
    {
      anchorUrl: "https://example.com/treasury-proposal.jsonld",
      anchorDataHash: "a1b1c2d3e4f5...",
    },
    rewardAddress
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Treasury withdrawal proposed: ${txHash}`);
```

### Submit a No Confidence Action

Propose a motion of no confidence in the current constitutional committee:

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

txBuilder
  .proposal(
    {
      kind: "NoConfidenceAction",
      action: {
        govActionId: {
          transactionId: "previousNoConfidenceTxHash...",
          govActionIndex: 0,
        },
      },
    },
    {
      anchorUrl: "https://example.com/no-confidence.jsonld",
      anchorDataHash: "a1b1c2d3e4f5...",
    },
    rewardAddress
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`No confidence action submitted: ${txHash}`);
```

## Complete Example

This example demonstrates a complete DRep lifecycle:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  hashDrepAnchor
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");

function getTxBuilder() {
  return new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });
}

// Register as a DRep
async function registerDRep(
  wallet: any,
  name: string,
  metadataUrl: string
) {
  const txBuilder = getTxBuilder();

  const dRep = await wallet.getDRep();
  const dRepId = dRep.dRepIDCip105;

  const metadata = {
    "@context": { /* CIP-119 context */ },
    "body": { "givenName": name }
  };
  const anchorHash = hashDrepAnchor(metadata);

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  txBuilder
    .drepRegistrationCertificate(dRepId, {
      anchorUrl: metadataUrl,
      anchorDataHash: anchorHash,
    })
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos);

  const unsignedTx = await txBuilder.complete();
  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Vote on a governance action
async function castVote(
  wallet: any,
  govActionTxHash: string,
  govActionIndex: number,
  voteKind: "Yes" | "No" | "Abstain"
) {
  const txBuilder = getTxBuilder();

  const dRep = await wallet.getDRep();
  const dRepId = dRep.dRepIDCip105;

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  txBuilder
    .vote(
      { type: "DRep", drepId: dRepId },
      { txHash: govActionTxHash, txIndex: govActionIndex },
      { voteKind }
    )
    .selectUtxosFrom(utxos)
    .changeAddress(changeAddress);

  const unsignedTx = await txBuilder.complete();
  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Delegate to a DRep
async function delegateToDRep(wallet: any, dRepId: string) {
  const txBuilder = getTxBuilder();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const rewardAddresses = await wallet.getRewardAddresses();
  const rewardAddress = rewardAddresses[0]!;

  txBuilder
    .voteDelegationCertificate({ dRepId }, rewardAddress)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos);

  const unsignedTx = await txBuilder.complete();
  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Retire as DRep
async function retireDRep(wallet: any) {
  const txBuilder = getTxBuilder();

  const dRep = await wallet.getDRep();
  const dRepId = dRep.dRepIDCip105;

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  txBuilder
    .drepDeregistrationCertificate(dRepId)
    .selectUtxosFrom(utxos)
    .changeAddress(changeAddress);

  const unsignedTx = await txBuilder.complete();
  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Usage
async function main() {
  // 1. Register as DRep
  const regTx = await registerDRep(
    wallet,
    "Community DRep",
    "https://example.com/metadata.jsonld"
  );
  console.log(`Registered as DRep: ${regTx}`);

  // 2. Vote on proposals
  const voteTx = await castVote(
    wallet,
    "proposal-tx-hash...",
    0,
    "Yes"
  );
  console.log(`Vote cast: ${voteTx}`);

  // 3. Others delegate to you
  const delegateTx = await delegateToDRep(
    otherWallet,
    "drep1..." // Your DRep ID
  );
  console.log(`Delegation received: ${delegateTx}`);

  // 4. Eventually retire
  const retireTx = await retireDRep(wallet);
  console.log(`Retired as DRep: ${retireTx}`);
}
```

## Troubleshooting

### "DRep not registered" error

* You must register as a DRep before voting
* Use `drepRegistrationCertificate()` first

### "Invalid anchor hash" error

* The hash must match the content at the URL exactly
* Use `hashDrepAnchor()` to compute the correct hash
* Ensure the metadata file is publicly accessible

### "Insufficient deposit" error

* DRep registration requires a deposit (check current protocol parameters)
* Ensure wallet has enough ADA for deposit + fees

### "DRep inactive" error

* DReps must vote regularly to stay active
* Vote on governance actions or submit an update certificate

### "Governance action not found" error

* Verify the transaction hash and index are correct
* The governance action may have already been resolved

### "Invalid voter type" error

* Ensure the voter type matches your role (DRep, SPO, or CC)
* Use the correct identifier format for each type

### "Insufficient deposit" for proposal

* Governance action proposals require a large deposit (check `govActionDeposit` in protocol parameters)
* The deposit is returned when the governance action is resolved (enacted, expired, or dropped)
* Ensure wallet has enough ADA for deposit + fees

### "Missing proposal script information" error

* When using `proposalScript()` or `proposalTxInReference()`, ensure the script source is provided before calling `.complete()`
* For Plutus script proposals, a redeemer must also be provided via `proposalRedeemerValue()`

## References

* [CIP-1694: Cardano On-Chain Governance](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md) - The governance specification that defines DReps, voting, and governance actions
* [CIP-95: Web-Wallet Bridge for Conway Governance](https://cips.cardano.org/cip/CIP-0095) - The standard for wallet-dApp governance interaction
* [CIP-119: DRep Metadata Standard](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0119/README.md) - Metadata standard for DRep registration
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources

## Related

* <Link href="/apis/txbuilder/basics">Transaction Basics</Link> - Core transaction building
* <Link href="/apis/txbuilder/staking">Staking</Link> - Stake delegation
* <Link href="https://github.com/cardano-foundation/CIPs/blob/master/CIP-1694/README.md">CIP-1694</Link> - Governance specification
* <Link href="https://github.com/cardano-foundation/CIPs/blob/master/CIP-0119/README.md">CIP-119</Link> - DRep metadata standard


# Cardano Transaction Builder
URL: /apis/txbuilder

Build Cardano transactions with fine-grained control using low-level APIs.

***

title: "Cardano Transaction Builder"
description: "Build Cardano transactions with fine-grained control using low-level APIs."
icon: BanknotesIcon
-------------------

import { linksTxbuilder } from "@/data/links-txbuilders";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

`MeshTxBuilder` is a powerful, low-level API for constructing Cardano transactions. It provides complete control over every aspect of transaction building, from simple ADA transfers to complex smart contract interactions, staking operations, and governance actions.

**When to use MeshTxBuilder:**

* Building custom transaction logic beyond standard transfers
* Creating multi-signature transactions
* Minting and burning native assets
* Interacting with Plutus smart contracts
* Managing stake delegation and rewards
* Participating in on-chain governance

## Quick Start

```tsx
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

// Initialize provider and builder
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Build a simple transfer
const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## Documentation

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksTxbuilder.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related

* <Link href="/apis/txparser">Transaction Parser</Link> - Parse and test transactions
* <Link href="/providers">Providers</Link> - Blockchain data providers
* <Link href="/apis/wallets">Wallets</Link> - Wallet integration options


# Minting and Burning Assets
URL: /apis/txbuilder/minting

Create and destroy native assets using Native Scripts and Plutus Scripts.

***

title: "Minting and Burning Assets"
description: "Create and destroy native assets using Native Scripts and Plutus Scripts."
----------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

Minting creates new native assets on Cardano, while burning destroys existing ones. You can mint using Native Scripts (simple signature-based) or Plutus Scripts (programmable smart contracts).

**When to use this:**

* Creating NFT collections
* Issuing fungible tokens
* Implementing tokenized loyalty programs
* Building CIP-68 compliant tokens with on-chain metadata
* Setting up royalty tokens for secondary market sales

## Quick Start

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex
} from "@meshsdk/core";

// Initialize
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Create minting script
const forgingScript = ForgeScript.withOneSignature(changeAddress);
const policyId = resolveScriptHash(forgingScript);
const tokenNameHex = stringToHex("MeshToken");

// Build mint transaction
const unsignedTx = await txBuilder
  .mint("1", policyId, tokenNameHex)
  .mintingScript(forgingScript)
  .metadataValue(721, {
    [policyId]: {
      MeshToken: {
        name: "Mesh Token",
        image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
      }
    }
  })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## API Reference

### mint()

Specify the asset to mint or burn.

```tsx
.mint(quantity: string, policyId: string, tokenNameHex: string)
```

| Parameter      | Type     | Description                                  |
| -------------- | -------- | -------------------------------------------- |
| `quantity`     | `string` | Amount to mint (positive) or burn (negative) |
| `policyId`     | `string` | Policy ID of the asset                       |
| `tokenNameHex` | `string` | Hex-encoded token name                       |

### mintingScript()

Provide the minting script.

```tsx
.mintingScript(script: string | NativeScript)
```

| Parameter | Type                     | Description                                |
| --------- | ------------------------ | ------------------------------------------ |
| `script`  | `string \| NativeScript` | CBOR-encoded script or NativeScript object |

### mintPlutusScriptV1() / V2() / V3()

Indicate that a Plutus script will be used for minting.

```tsx
.mintPlutusScriptV2()
```

### mintRedeemerValue()

Provide the redeemer for Plutus script minting.

```tsx
.mintRedeemerValue(redeemer: Data | object | string, type?: "Mesh" | "CBOR" | "JSON", exUnits?: Budget)
```

| Parameter  | Type                         | Description                        |
| ---------- | ---------------------------- | ---------------------------------- |
| `redeemer` | `Data \| object \| string`   | Redeemer data                      |
| `type`     | `"Mesh" \| "CBOR" \| "JSON"` | Data format type (default: "Mesh") |
| `exUnits`  | `Budget`                     | Optional execution units           |

### mintTxInReference()

Reference an on-chain script instead of providing it inline.

```tsx
.mintTxInReference(txHash: string, txIndex: number)
```

| Parameter | Type     | Description                                      |
| --------- | -------- | ------------------------------------------------ |
| `txHash`  | `string` | Transaction hash containing the reference script |
| `txIndex` | `number` | Output index of the reference script             |

### metadataValue()

Attach metadata to the transaction.

```tsx
.metadataValue(label: number, metadata: object)
```

| Parameter  | Type     | Description                                      |
| ---------- | -------- | ------------------------------------------------ |
| `label`    | `number` | Metadata label (721 for NFTs, 777 for royalties) |
| `metadata` | `object` | Metadata object                                  |

## Common Patterns

### Mint with One Signature

The simplest minting approach using a single wallet address:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Create forging script from wallet address
const forgingScript = ForgeScript.withOneSignature(changeAddress);
const policyId = resolveScriptHash(forgingScript);
const tokenName = "MeshToken";
const tokenNameHex = stringToHex(tokenName);

// Define NFT metadata
const metadata = {
  [policyId]: {
    [tokenName]: {
      name: "Mesh Token",
      image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
      mediaType: "image/jpg",
      description: "This NFT was minted by Mesh.",
    }
  }
};

const unsignedTx = await txBuilder
  .mint("1", policyId, tokenNameHex)
  .mintingScript(forgingScript)
  .metadataValue(721, metadata)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Mint Multiple Assets

Mint multiple tokens in a single transaction:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const forgingScript = ForgeScript.withOneSignature(changeAddress);
const policyId = resolveScriptHash(forgingScript);

// Build metadata for multiple tokens
const metadata: Record<string, Record<string, object>> = { [policyId]: {} };

for (let i = 1; i <= 3; i++) {
  const tokenName = `MeshToken${i}`;
  const tokenNameHex = stringToHex(tokenName);

  metadata[policyId][tokenName] = {
    name: tokenName,
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    description: `Token #${i} from the Mesh collection`,
  };

  // Add mint instruction for each token
  txBuilder.mint("1", policyId, tokenNameHex);
  txBuilder.mintingScript(forgingScript);
}

txBuilder
  .metadataValue(721, metadata)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos);

const unsignedTx = await txBuilder.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Burn Assets

Burn assets by minting with a negative quantity:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Use the same forging script that minted the asset
const forgingScript = ForgeScript.withOneSignature(changeAddress);
const policyId = resolveScriptHash(forgingScript);
const tokenNameHex = stringToHex("MeshToken");

// Burn by using negative quantity
const unsignedTx = await txBuilder
  .mint("-1", policyId, tokenNameHex)
  .mintingScript(forgingScript)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Mint with Native Script (Time-Locked)

Create a time-locked minting policy:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex,
  deserializeAddress,
  NativeScript
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const { pubKeyHash: keyHash } = deserializeAddress(changeAddress);

// Create time-locked native script
const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    {
      type: "before",
      slot: "99999999", // Policy expires at this slot
    },
    {
      type: "sig",
      keyHash: keyHash,
    },
  ],
};

const forgingScript = ForgeScript.fromNativeScript(nativeScript);
const policyId = resolveScriptHash(forgingScript);
const tokenName = "TimeLocked";
const tokenNameHex = stringToHex(tokenName);

const metadata = {
  [policyId]: {
    [tokenName]: {
      name: "Time-Locked Token",
      image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    }
  }
};

const unsignedTx = await txBuilder
  .mint("1", policyId, tokenNameHex)
  .mintingScript(forgingScript)
  .metadataValue(721, metadata)
  .invalidHereafter(99999999)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Mint with Plutus Script

Mint using a Plutus smart contract:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  stringToHex,
  mConStr0,
  UTxO
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral: UTxO = (await wallet.getCollateral())[0]!;
const changeAddress = await wallet.getChangeAddress();

// Your Plutus minting script CBOR
const plutusMintingScript = "your-script-cbor-here";
const policyId = resolveScriptHash(plutusMintingScript, "V2");
const tokenName = "PlutusToken";
const tokenNameHex = stringToHex(tokenName);

const metadata = {
  [policyId]: {
    [tokenName]: {
      name: "Plutus Token",
      image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    }
  }
};

const unsignedTx = await txBuilder
  .mintPlutusScriptV2()
  .mint("1", policyId, tokenNameHex)
  .mintingScript(plutusMintingScript)
  .mintRedeemerValue(mConStr0(["mesh"]))
  .metadataValue(721, metadata)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .txInCollateral(
    collateral.input.txHash,
    collateral.input.outputIndex,
    collateral.output.amount,
    collateral.output.address
  )
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);
```

### Mint CIP-68 Tokens

Mint tokens with on-chain metadata using the CIP-68 standard:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  stringToHex,
  mConStr0,
  mTxOutRef,
  applyParamsToScript,
  serializePlutusScript,
  metadataToCip68,
  CIP68_100,
  CIP68_222,
  PlutusScript,
  UTxO
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral: UTxO = (await wallet.getCollateral())[0]!;
const changeAddress = await wallet.getChangeAddress();

// Define user token metadata
const userTokenMetadata = {
  name: "CIP68 Token",
  image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
  mediaType: "image/jpg",
  description: "A CIP-68 compliant token with on-chain metadata",
};

// Create always-succeed script for storing reference token
const alwaysSucceedScript: PlutusScript = {
  code: "your-always-succeed-script-cbor",
  version: "V1",
};
const { address: scriptAddress } = serializePlutusScript(alwaysSucceedScript);

// Create one-time minting policy (parameterized by UTxO)
const oneTimeMintingPolicy = "your-one-time-minting-policy-cbor";
const scriptCode = applyParamsToScript(oneTimeMintingPolicy, [
  mTxOutRef(utxos[0]!.input.txHash, utxos[0]!.input.outputIndex),
]);

const policyId = resolveScriptHash(scriptCode, "V2");
const tokenName = "MyCIP68Token";
const tokenNameHex = stringToHex(tokenName);

const unsignedTx = await txBuilder
  // Consume the UTxO used to parameterize the policy
  .txIn(
    utxos[0]!.input.txHash,
    utxos[0]!.input.outputIndex,
    utxos[0]!.output.amount,
    utxos[0]!.output.address
  )
  // Mint reference token (100 label)
  .mintPlutusScriptV2()
  .mint("1", policyId, CIP68_100(tokenNameHex))
  .mintingScript(scriptCode)
  .mintRedeemerValue(mConStr0([]))
  // Mint user token (222 label)
  .mintPlutusScriptV2()
  .mint("1", policyId, CIP68_222(tokenNameHex))
  .mintingScript(scriptCode)
  .mintRedeemerValue(mConStr0([]))
  // Send reference token to script address with metadata as datum
  .txOut(scriptAddress, [
    { unit: policyId + CIP68_100(tokenNameHex), quantity: "1" },
  ])
  .txOutInlineDatumValue(metadataToCip68(userTokenMetadata))
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .txInCollateral(
    collateral.input.txHash,
    collateral.input.outputIndex,
    collateral.output.amount,
    collateral.output.address
  )
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);
```

### Mint Royalty Token (CIP-27)

Create a royalty token for secondary market sales:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  RoyaltiesStandard
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const address = (await wallet.getUsedAddresses())[0]!;

const forgingScript = ForgeScript.withOneSignature(address);
const policyId = resolveScriptHash(forgingScript);

// Royalty metadata (CIP-27)
const royaltyMetadata: RoyaltiesStandard = {
  rate: "0.05", // 5% royalty
  address: "addr_test1qz...", // Royalty recipient address
};

const unsignedTx = await txBuilder
  .mint("1", policyId, "") // Empty token name for royalty token
  .mintingScript(forgingScript)
  .metadataValue(777, royaltyMetadata)
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## Complete Example

This example demonstrates a complete NFT minting workflow:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  ForgeScript,
  resolveScriptHash,
  stringToHex,
  deserializeAddress,
  NativeScript
} from "@meshsdk/core";

async function mintNFTCollection(
  wallet: any,
  provider: BlockfrostProvider,
  collectionSize: number
) {
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  // Get wallet data
  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const { pubKeyHash: keyHash } = deserializeAddress(changeAddress);

  // Create time-locked policy (expires in ~1 year)
  const currentSlot = 100000000; // Get current slot from provider
  const expirationSlot = currentSlot + 31536000; // ~1 year

  const nativeScript: NativeScript = {
    type: "all",
    scripts: [
      { type: "before", slot: expirationSlot.toString() },
      { type: "sig", keyHash: keyHash },
    ],
  };

  const forgingScript = ForgeScript.fromNativeScript(nativeScript);
  const policyId = resolveScriptHash(forgingScript);

  // Build metadata for collection
  const metadata: Record<string, Record<string, object>> = { [policyId]: {} };

  for (let i = 1; i <= collectionSize; i++) {
    const tokenName = `MyNFT${i.toString().padStart(4, "0")}`;
    const tokenNameHex = stringToHex(tokenName);

    metadata[policyId][tokenName] = {
      name: `My NFT #${i}`,
      image: `ipfs://QmCollection.../${i}.png`,
      mediaType: "image/png",
      description: `NFT #${i} from My Collection`,
      attributes: {
        rarity: i <= 10 ? "Legendary" : i <= 50 ? "Rare" : "Common",
        edition: i,
        totalSupply: collectionSize,
      },
    };

    txBuilder.mint("1", policyId, tokenNameHex);
    txBuilder.mintingScript(forgingScript);
  }

  // Build transaction
  txBuilder
    .metadataValue(721, metadata)
    .invalidHereafter(expirationSlot)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos);

  const unsignedTx = await txBuilder.complete();
  const signedTx = await wallet.signTx(unsignedTx);
  const txHash = await wallet.submitTx(signedTx);

  return {
    txHash,
    policyId,
    expirationSlot,
  };
}

// Usage
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const result = await mintNFTCollection(wallet, provider, 100);
console.log(`Minted collection with policy: ${result.policyId}`);
console.log(`Transaction: ${result.txHash}`);
```

## Troubleshooting

### "Script hash mismatch" error

* Ensure the forging script matches the policy ID you're minting under
* For time-locked policies, verify the slot number matches exactly

### "Insufficient collateral" for Plutus minting

* Provide collateral using `txInCollateral()`
* Collateral must be a pure ADA UTxO (no native assets)
* Collateral should be at least 5 ADA for most transactions

### "Missing required signer" error

* For Native Scripts, ensure all required key hashes have signed
* Use `wallet.signTx(unsignedTx, true)` for partial signing in multi-sig scenarios

### "Token already exists" for one-time policies

* One-time minting policies consume a specific UTxO
* That UTxO must exist and be unspent at transaction time

### Metadata too large

* Keep metadata under 16KB total
* Use IPFS for large images and reference the CID
* Split large collections across multiple transactions

### Time-locked policy expired

* Check the current slot number against your policy's expiration
* Use `invalidHereafter()` to match the policy's time constraint

## Related

* <Link href="/apis/txbuilder/basics">Transaction Basics</Link> - Core transaction building
* <Link href="/apis/txbuilder/smart-contracts">Smart Contracts</Link> - Plutus script interactions
* <Link href="/guides/nft-collection">NFT Collection Guide</Link> - Step-by-step NFT tutorial
* <Link href="/apis/data">Data Types</Link> - Working with Cardano data


# Smart Contract Interactions
URL: /apis/txbuilder/smart-contracts

Lock, unlock, and interact with Plutus smart contracts on Cardano.

***

title: "Smart Contract Interactions"
description: "Lock, unlock, and interact with Plutus smart contracts on Cardano."
---------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

Smart contracts on Cardano are Plutus scripts that control how assets can be spent. You interact with them by locking assets at script addresses and unlocking them by providing valid datum and redeemer values.

**When to use this:**

* Building decentralized applications (dApps)
* Creating escrow or vesting contracts
* Implementing decentralized exchanges
* Building NFT marketplaces
* Deploying on-chain validators

## Quick Start

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  serializePlutusScript,
  PlutusScript
} from "@meshsdk/core";

// Initialize
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Define the Plutus script
const script: PlutusScript = {
  code: "your-script-cbor-here",
  version: "V2",
};
const { address: scriptAddress } = serializePlutusScript(script);

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Lock assets at script address
const unsignedTx = await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .txOutInlineDatumValue("my-secret-datum")
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## API Reference

### Locking Assets

#### txOut()

Send assets to an address (including script addresses).

```tsx
.txOut(address: string, amount: Asset[])
```

| Parameter | Type      | Description                                 |
| --------- | --------- | ------------------------------------------- |
| `address` | `string`  | Recipient address (can be a script address) |
| `amount`  | `Asset[]` | Array of assets to send                     |

#### txOutInlineDatumValue()

Attach an inline datum to the output.

```tsx
.txOutInlineDatumValue(datum: Data | object | string, type?: "Mesh" | "CBOR" | "JSON")
```

| Parameter | Type                         | Description                   |
| --------- | ---------------------------- | ----------------------------- |
| `datum`   | `Data \| object \| string`   | Datum value                   |
| `type`    | `"Mesh" \| "CBOR" \| "JSON"` | Data format (default: "Mesh") |

#### txOutDatumHashValue()

Attach a datum hash to the output (datum stored off-chain).

```tsx
.txOutDatumHashValue(datum: Data | object | string, type?: "Mesh" | "CBOR" | "JSON")
```

| Parameter | Type                         | Description                         |
| --------- | ---------------------------- | ----------------------------------- |
| `datum`   | `Data \| object \| string`   | Datum value (hash will be computed) |
| `type`    | `"Mesh" \| "CBOR" \| "JSON"` | Data format (default: "Mesh")       |

#### txOutReferenceScript()

Attach a reference script to the output.

```tsx
.txOutReferenceScript(scriptCbor: string, version?: LanguageVersion)
```

| Parameter    | Type              | Description                       |
| ------------ | ----------------- | --------------------------------- |
| `scriptCbor` | `string`          | CBOR-encoded script               |
| `version`    | `LanguageVersion` | Script version ("V1", "V2", "V3") |

### Unlocking Assets

#### spendingPlutusScriptV1() / V2() / V3()

Indicate you are spending from a Plutus script.

```tsx
.spendingPlutusScriptV2()
```

#### txIn()

Specify the UTxO to spend.

```tsx
.txIn(txHash: string, txIndex: number, amount?: Asset[], address?: string)
```

| Parameter | Type      | Description              |
| --------- | --------- | ------------------------ |
| `txHash`  | `string`  | Transaction hash         |
| `txIndex` | `number`  | Output index             |
| `amount`  | `Asset[]` | Optional: Output amount  |
| `address` | `string`  | Optional: Output address |

#### txInInlineDatumPresent()

Indicate that the input has an inline datum.

```tsx
.txInInlineDatumPresent()
```

#### txInDatumValue()

Provide the datum for the input (when not inline).

```tsx
.txInDatumValue(datum: Data | object | string, type?: "Mesh" | "CBOR" | "JSON")
```

| Parameter | Type                         | Description                   |
| --------- | ---------------------------- | ----------------------------- |
| `datum`   | `Data \| object \| string`   | Datum value                   |
| `type`    | `"Mesh" \| "CBOR" \| "JSON"` | Data format (default: "Mesh") |

#### txInRedeemerValue()

Provide the redeemer for the script.

```tsx
.txInRedeemerValue(redeemer: Data | object | string, type?: "Mesh" | "CBOR" | "JSON", exUnits?: Budget)
```

| Parameter  | Type                         | Description                   |
| ---------- | ---------------------------- | ----------------------------- |
| `redeemer` | `Data \| object \| string`   | Redeemer value                |
| `type`     | `"Mesh" \| "CBOR" \| "JSON"` | Data format (default: "Mesh") |
| `exUnits`  | `Budget`                     | Optional execution units      |

#### txInScript()

Provide the script for the input.

```tsx
.txInScript(scriptCbor: string)
```

| Parameter    | Type     | Description                |
| ------------ | -------- | -------------------------- |
| `scriptCbor` | `string` | CBOR-encoded Plutus script |

#### spendingTxInReference()

Reference an on-chain script instead of providing it inline.

```tsx
.spendingTxInReference(txHash: string, txIndex: number, spendingScriptHash?: string)
```

| Parameter            | Type     | Description                                  |
| -------------------- | -------- | -------------------------------------------- |
| `txHash`             | `string` | Transaction hash containing reference script |
| `txIndex`            | `number` | Output index                                 |
| `spendingScriptHash` | `string` | Optional script hash for verification        |

### Collateral

#### txInCollateral()

Provide collateral for script execution.

```tsx
.txInCollateral(txHash: string, txIndex: number, amount?: Asset[], address?: string)
```

| Parameter | Type      | Description                      |
| --------- | --------- | -------------------------------- |
| `txHash`  | `string`  | Collateral UTxO transaction hash |
| `txIndex` | `number`  | Output index                     |
| `amount`  | `Asset[]` | Optional: UTxO amount            |
| `address` | `string`  | Optional: UTxO address           |

## Common Patterns

### Lock Assets in a Script

Send assets to a script address with an inline datum:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  serializePlutusScript,
  PlutusScript
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

// Define your Plutus script
const script: PlutusScript = {
  code: "your-always-succeed-script-cbor",
  version: "V2",
};
const { address: scriptAddress } = serializePlutusScript(script);

// Lock 10 ADA with a datum
const unsignedTx = await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .txOutInlineDatumValue("meshsecretcode")
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Lock with Datum Hash

Lock assets using a datum hash instead of inline datum:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  serializePlutusScript,
  PlutusScript
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

const script: PlutusScript = {
  code: "your-script-cbor",
  version: "V2",
};
const { address: scriptAddress } = serializePlutusScript(script);

// Lock with datum hash (datum stored off-chain)
const unsignedTx = await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .txOutDatumHashValue("my-secret-datum")
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Unlock Assets from a Script

Spend a UTxO from a script address:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  serializePlutusScript,
  mConStr0,
  PlutusScript
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral = await wallet.getCollateral();
const changeAddress = await wallet.getChangeAddress();

// Define the script
const script: PlutusScript = {
  code: "your-always-succeed-script-cbor",
  version: "V2",
};
const { address: scriptAddress } = serializePlutusScript(script);

// Find the UTxO to unlock (in production, query from provider)
const scriptUtxos = await provider.fetchAddressUTxOs(scriptAddress);
const assetUtxo = scriptUtxos.find(
  (utxo) => utxo.output.plutusData === "meshsecretcode"
);

if (!assetUtxo) {
  throw new Error("UTxO not found");
}

const unsignedTx = await txBuilder
  .spendingPlutusScriptV2()
  .txIn(assetUtxo.input.txHash, assetUtxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(mConStr0([]))
  .txInScript(script.code)
  .changeAddress(changeAddress)
  .txInCollateral(
    collateral[0]!.input.txHash,
    collateral[0]!.input.outputIndex,
    collateral[0]!.output.amount,
    collateral[0]!.output.address
  )
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Unlock with Datum Hash

When the UTxO was locked with a datum hash, you must provide the datum:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  serializePlutusScript,
  mConStr0,
  PlutusScript
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral = await wallet.getCollateral();
const changeAddress = await wallet.getChangeAddress();

const script: PlutusScript = {
  code: "your-script-cbor",
  version: "V2",
};

// The UTxO to unlock
const assetUtxo = {
  input: { txHash: "abc123...", outputIndex: 0 },
  output: { amount: [{ unit: "lovelace", quantity: "5000000" }], address: "..." }
};

const unsignedTx = await txBuilder
  .spendingPlutusScriptV2()
  .txIn(assetUtxo.input.txHash, assetUtxo.input.outputIndex)
  .txInDatumValue("my-secret-datum") // Provide the original datum
  .txInRedeemerValue(mConStr0([]))
  .txInScript(script.code)
  .changeAddress(changeAddress)
  .txInCollateral(
    collateral[0]!.input.txHash,
    collateral[0]!.input.outputIndex,
    collateral[0]!.output.amount,
    collateral[0]!.output.address
  )
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Using Reference Scripts

Reference scripts allow you to use a script stored on-chain, reducing transaction size and fees.

#### Deploy a Reference Script

First, send a reference script on-chain:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();

const scriptCbor = "your-plutus-script-cbor";

// Send script on-chain (use an address you control)
const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "10000000" }])
  .txOutReferenceScript(scriptCbor, "V2")
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

// Save txHash and output index for future reference
console.log(`Reference script deployed at: ${txHash}#0`);
```

#### Use a Reference Script

Spend using an on-chain reference script:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  mConStr0
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral = await wallet.getCollateral();
const changeAddress = await wallet.getChangeAddress();

// Reference script location
const refScriptTxHash = "abc123...";
const refScriptTxIndex = 0;

// UTxO to unlock
const assetUtxo = {
  input: { txHash: "def456...", outputIndex: 0 },
  output: { amount: [{ unit: "lovelace", quantity: "5000000" }], address: "..." }
};

const unsignedTx = await txBuilder
  .spendingPlutusScriptV2()
  .txIn(assetUtxo.input.txHash, assetUtxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(mConStr0([]))
  .spendingTxInReference(refScriptTxHash, refScriptTxIndex) // Use reference script
  .changeAddress(changeAddress)
  .txInCollateral(
    collateral[0]!.input.txHash,
    collateral[0]!.input.outputIndex,
    collateral[0]!.output.amount,
    collateral[0]!.output.address
  )
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

### Mint with Plutus Script

Mint tokens using a Plutus minting policy:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  stringToHex,
  mConStr0,
  UTxO
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral: UTxO = (await wallet.getCollateral())[0]!;
const changeAddress = await wallet.getChangeAddress();

const plutusMintingScript = "your-minting-script-cbor";
const policyId = resolveScriptHash(plutusMintingScript, "V2");
const tokenName = "MyToken";
const tokenNameHex = stringToHex(tokenName);

const metadata = {
  [policyId]: {
    [tokenName]: {
      name: "My Plutus Token",
      image: "ipfs://...",
    }
  }
};

const unsignedTx = await txBuilder
  .mintPlutusScriptV2()
  .mint("1", policyId, tokenNameHex)
  .mintingScript(plutusMintingScript)
  .mintRedeemerValue(mConStr0(["mesh"]))
  .metadataValue(721, metadata)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .txInCollateral(
    collateral.input.txHash,
    collateral.input.outputIndex,
    collateral.output.amount,
    collateral.output.address
  )
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);
```

## Complete Example

This example demonstrates a complete escrow workflow:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  serializePlutusScript,
  deserializeAddress,
  mConStr0,
  PlutusScript,
  UTxO
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// Escrow script that releases funds when correct redeemer is provided
const escrowScript: PlutusScript = {
  code: "your-escrow-script-cbor",
  version: "V2",
};
const { address: escrowAddress } = serializePlutusScript(escrowScript);

// Step 1: Lock funds in escrow
async function createEscrow(
  wallet: any,
  amount: string,
  beneficiary: string
) {
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const { pubKeyHash } = deserializeAddress(beneficiary);

  // Lock funds with beneficiary's pubKeyHash as datum
  const unsignedTx = await txBuilder
    .txOut(escrowAddress, [{ unit: "lovelace", quantity: amount }])
    .txOutInlineDatumValue(pubKeyHash)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  const txHash = await wallet.submitTx(signedTx);

  return txHash;
}

// Step 2: Release funds from escrow
async function releaseEscrow(
  wallet: any,
  escrowUtxo: UTxO
) {
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  const utxos = await wallet.getUtxos();
  const collateral = await wallet.getCollateral();
  const changeAddress = await wallet.getChangeAddress();
  const { pubKeyHash } = deserializeAddress(changeAddress);

  const unsignedTx = await txBuilder
    .spendingPlutusScriptV2()
    .txIn(escrowUtxo.input.txHash, escrowUtxo.input.outputIndex)
    .txInInlineDatumPresent()
    .txInRedeemerValue(mConStr0([]))
    .txInScript(escrowScript.code)
    .requiredSignerHash(pubKeyHash)
    .changeAddress(changeAddress)
    .txInCollateral(
      collateral[0]!.input.txHash,
      collateral[0]!.input.outputIndex,
      collateral[0]!.output.amount,
      collateral[0]!.output.address
    )
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  const txHash = await wallet.submitTx(signedTx);

  return txHash;
}

// Usage
const escrowTxHash = await createEscrow(
  sellerWallet,
  "50000000", // 50 ADA
  buyerAddress
);
console.log(`Escrow created: ${escrowTxHash}`);

// Later, buyer releases funds
const escrowUtxos = await provider.fetchAddressUTxOs(escrowAddress);
const myEscrow = escrowUtxos.find(
  (utxo) => utxo.input.txHash === escrowTxHash
);

const releaseTxHash = await releaseEscrow(buyerWallet, myEscrow!);
console.log(`Escrow released: ${releaseTxHash}`);
```

## Troubleshooting

### "Script execution failed" error

* Verify the redeemer matches what the script expects
* Check that the datum is correct (inline vs hash)
* Ensure all required signers are included

### "Missing collateral" error

* Provide collateral using `txInCollateral()`
* Collateral must be a pure ADA UTxO (no tokens)
* Recommended: at least 5 ADA for collateral

### "Execution units exceeded" error

* The script is consuming too much resources
* Optimize your script or provide custom execution units
* Use `txInRedeemerValue(redeemer, "Mesh", { mem: X, steps: Y })`

### "Datum hash mismatch" error

* When unlocking with datum hash, provide the exact original datum
* Ensure the datum type matches (Mesh, CBOR, or JSON)

### "Reference script not found" error

* Verify the reference script UTxO still exists (not spent)
* Check the transaction hash and output index are correct
* Ensure the script version matches (V1, V2, or V3)

### "Required signer missing" error

* Add `requiredSignerHash()` for scripts that check signatures
* Use partial signing: `wallet.signTx(unsignedTx, true)`

## Related

* <Link href="/apis/txbuilder/basics">Transaction Basics</Link> - Core transaction building
* <Link href="/apis/txbuilder/minting">Minting Assets</Link> - Plutus minting policies
* <Link href="/apis/data">Data Types</Link> - Working with datum and redeemer
* <Link href="/apis/txparser">Transaction Parser</Link> - Parse and test transactions


# Staking and Delegation
URL: /apis/txbuilder/staking

Delegate ADA to stake pools, register stake addresses, and withdraw staking rewards with TypeScript.

***

title: "Staking and Delegation"
description: "Delegate ADA to stake pools, register stake addresses, and withdraw staking rewards with TypeScript."
-------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

Staking allows you to delegate your ADA to stake pools and earn rewards. You can register stake addresses, delegate to pools, withdraw rewards, and deregister stake addresses using `MeshTxBuilder`.

**When to use this:**

* Delegating ADA to earn staking rewards
* Building staking dashboards or portfolio trackers
* Creating delegation services
* Implementing stake pool operations
* Building "withdraw zero" validation patterns

## Quick Start

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  deserializePoolId
} from "@meshsdk/core";

// Initialize
const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get wallet data
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

// Convert pool ID to hash
const poolIdHash = deserializePoolId(
  "pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy"
);

// Delegate to stake pool
const unsignedTx = await txBuilder
  .delegateStakeCertificate(rewardAddress, poolIdHash)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

## API Reference

### registerStakeCertificate()

Register a stake address on the blockchain (required before first delegation).

```tsx
.registerStakeCertificate(rewardAddress: string)
```

| Parameter       | Type     | Description                      |
| --------------- | -------- | -------------------------------- |
| `rewardAddress` | `string` | Bech32 reward address (stake...) |

### delegateStakeCertificate()

Delegate stake to a pool.

```tsx
.delegateStakeCertificate(rewardAddress: string, poolIdHash: string)
```

| Parameter       | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `rewardAddress` | `string` | Bech32 reward address     |
| `poolIdHash`    | `string` | Deserialized pool ID hash |

### deregisterStakeCertificate()

Deregister a stake address and reclaim the deposit.

```tsx
.deregisterStakeCertificate(rewardAddress: string)
```

| Parameter       | Type     | Description                         |
| --------------- | -------- | ----------------------------------- |
| `rewardAddress` | `string` | Bech32 reward address to deregister |

### withdrawal()

Withdraw staking rewards.

```tsx
.withdrawal(rewardAddress: string, lovelace: string)
```

| Parameter       | Type     | Description                    |
| --------------- | -------- | ------------------------------ |
| `rewardAddress` | `string` | Bech32 reward address          |
| `lovelace`      | `string` | Amount to withdraw in lovelace |

### withdrawalPlutusScriptV1() / V2() / V3()

Indicate withdrawal from a Plutus staking script.

```tsx
.withdrawalPlutusScriptV2()
```

### withdrawalScript()

Provide the staking script for script-based withdrawal.

```tsx
.withdrawalScript(scriptCbor: string)
```

| Parameter    | Type     | Description                 |
| ------------ | -------- | --------------------------- |
| `scriptCbor` | `string` | CBOR-encoded staking script |

### withdrawalRedeemerValue()

Provide the redeemer for script-based withdrawal.

```tsx
.withdrawalRedeemerValue(redeemer: Data | object | string, type?: "Mesh" | "CBOR" | "JSON", exUnits?: Budget)
```

| Parameter  | Type                         | Description                   |
| ---------- | ---------------------------- | ----------------------------- |
| `redeemer` | `Data \| object \| string`   | Redeemer value                |
| `type`     | `"Mesh" \| "CBOR" \| "JSON"` | Data format (default: "Mesh") |
| `exUnits`  | `Budget`                     | Optional execution units      |

## Common Patterns

### Register and Delegate (First Time)

Register a stake address and delegate in a single transaction:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  deserializePoolId
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

// Convert bech32 pool ID to hash
const poolIdHash = deserializePoolId(
  "pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy"
);

// Register and delegate in one transaction
const unsignedTx = await txBuilder
  .registerStakeCertificate(rewardAddress)
  .delegateStakeCertificate(rewardAddress, poolIdHash)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Registered and delegated: ${txHash}`);
```

### Change Delegation

Switch delegation to a different pool (no registration needed):

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  deserializePoolId
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

// New pool to delegate to
const newPoolIdHash = deserializePoolId(
  "pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt"
);

const unsignedTx = await txBuilder
  .delegateStakeCertificate(rewardAddress, newPoolIdHash)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Delegation changed: ${txHash}`);
```

### Withdraw Rewards

Withdraw accumulated staking rewards:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

// Query available rewards (in production)
// const accountInfo = await provider.fetchAccountInfo(rewardAddress);
// const withdrawableAmount = accountInfo.withdrawableAmount;

const withdrawAmount = "5000000"; // 5 ADA in lovelace

const unsignedTx = await txBuilder
  .withdrawal(rewardAddress, withdrawAmount)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Rewards withdrawn: ${txHash}`);
```

### Deregister Stake Address

Stop staking and reclaim the 2 ADA deposit:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const rewardAddresses = await wallet.getRewardAddresses();
const rewardAddress = rewardAddresses[0]!;

const unsignedTx = await txBuilder
  .deregisterStakeCertificate(rewardAddress)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

console.log(`Stake deregistered, deposit reclaimed: ${txHash}`);
```

### Script Withdrawal

Withdraw from a Plutus staking script:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  serializeRewardAddress,
  deserializeAddress
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral = await wallet.getCollateral();
const changeAddress = await wallet.getChangeAddress();

// Your staking script CBOR
const stakeScriptCbor = "your-stake-script-cbor";

// Derive reward address from script
const scriptHash = resolveScriptHash(stakeScriptCbor, "V2");
const rewardAddress = serializeRewardAddress(scriptHash, true, 0); // testnet

const withdrawAmount = "1000000"; // 1 ADA

const unsignedTx = await txBuilder
  .withdrawalPlutusScriptV2()
  .withdrawal(rewardAddress, withdrawAmount)
  .withdrawalScript(stakeScriptCbor)
  .withdrawalRedeemerValue("") // Your redeemer
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .txInCollateral(
    collateral[0]!.input.txHash,
    collateral[0]!.input.outputIndex,
    collateral[0]!.output.amount,
    collateral[0]!.output.address
  )
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);
```

### Withdraw Zero Pattern

The "withdraw zero" pattern is used to prove control of a stake key without withdrawing rewards. This is commonly used in DeFi protocols for stake key validation.

#### Step 1: Register Script Stake Key

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  deserializeAddress
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
const { pubKeyHash } = deserializeAddress(changeAddress);

// Parameterized staking script
const stakeScriptCbor = getAlwaysSucceedStakingScript(pubKeyHash);
const scriptHash = resolveScriptHash(stakeScriptCbor, "V2");

const unsignedTx = await txBuilder
  .registerStakeCertificate(scriptHash)
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);

console.log(`Script stake key registered: ${txHash}`);
```

#### Step 2: Withdraw Zero

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  resolveScriptHash,
  serializeRewardAddress,
  deserializeAddress
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxos();
const collateral = await wallet.getCollateral();
const changeAddress = await wallet.getChangeAddress();
const { pubKeyHash } = deserializeAddress(changeAddress);

const stakeScriptCbor = getAlwaysSucceedStakingScript(pubKeyHash);
const scriptHash = resolveScriptHash(stakeScriptCbor, "V2");
const rewardAddress = serializeRewardAddress(scriptHash, true, 0);

// Withdraw zero to trigger script validation
const unsignedTx = await txBuilder
  .withdrawalPlutusScriptV2()
  .withdrawal(rewardAddress, "0") // Zero withdrawal
  .withdrawalScript(stakeScriptCbor)
  .withdrawalRedeemerValue("")
  .selectUtxosFrom(utxos)
  .changeAddress(changeAddress)
  .txInCollateral(
    collateral[0]!.input.txHash,
    collateral[0]!.input.outputIndex,
    collateral[0]!.output.amount,
    collateral[0]!.output.address
  )
  .complete();

const signedTx = await wallet.signTx(unsignedTx, true);
const txHash = await wallet.submitTx(signedTx);

console.log(`Withdraw zero completed: ${txHash}`);
```

## Complete Example

This example demonstrates a complete staking management workflow:

```tsx
import {
  MeshTxBuilder,
  BlockfrostProvider,
  deserializePoolId
} from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// Helper to create txBuilder
function getTxBuilder() {
  return new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });
}

// Register and delegate to a pool
async function startStaking(wallet: any, poolBech32: string) {
  const txBuilder = getTxBuilder();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const rewardAddresses = await wallet.getRewardAddresses();
  const rewardAddress = rewardAddresses[0]!;
  const poolIdHash = deserializePoolId(poolBech32);

  const unsignedTx = await txBuilder
    .registerStakeCertificate(rewardAddress)
    .delegateStakeCertificate(rewardAddress, poolIdHash)
    .selectUtxosFrom(utxos)
    .changeAddress(changeAddress)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Change to a different pool
async function changePool(wallet: any, newPoolBech32: string) {
  const txBuilder = getTxBuilder();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const rewardAddresses = await wallet.getRewardAddresses();
  const rewardAddress = rewardAddresses[0]!;
  const poolIdHash = deserializePoolId(newPoolBech32);

  const unsignedTx = await txBuilder
    .delegateStakeCertificate(rewardAddress, poolIdHash)
    .selectUtxosFrom(utxos)
    .changeAddress(changeAddress)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Withdraw all rewards
async function withdrawRewards(wallet: any, amount: string) {
  const txBuilder = getTxBuilder();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const rewardAddresses = await wallet.getRewardAddresses();
  const rewardAddress = rewardAddresses[0]!;

  const unsignedTx = await txBuilder
    .withdrawal(rewardAddress, amount)
    .selectUtxosFrom(utxos)
    .changeAddress(changeAddress)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Stop staking completely
async function stopStaking(wallet: any) {
  const txBuilder = getTxBuilder();

  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();
  const rewardAddresses = await wallet.getRewardAddresses();
  const rewardAddress = rewardAddresses[0]!;

  const unsignedTx = await txBuilder
    .deregisterStakeCertificate(rewardAddress)
    .selectUtxosFrom(utxos)
    .changeAddress(changeAddress)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx);
  return await wallet.submitTx(signedTx);
}

// Usage
const poolId = "pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy";

// Start staking
const startTxHash = await startStaking(wallet, poolId);
console.log(`Started staking: ${startTxHash}`);

// Later, withdraw 10 ADA in rewards
const withdrawTxHash = await withdrawRewards(wallet, "10000000");
console.log(`Withdrew rewards: ${withdrawTxHash}`);

// Change to different pool
const newPoolId = "pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt";
const changeTxHash = await changePool(wallet, newPoolId);
console.log(`Changed pool: ${changeTxHash}`);

// Eventually, stop staking
const stopTxHash = await stopStaking(wallet);
console.log(`Stopped staking: ${stopTxHash}`);
```

## Troubleshooting

### "Stake address not registered" error

* You must register a stake address before delegating
* Use `registerStakeCertificate()` first, or combine with delegation

### "Pool not found" error

* Verify the pool ID is correct and the pool is active
* Use `deserializePoolId()` to convert bech32 pool IDs

### "Insufficient funds for deposit" error

* Stake registration requires a 2 ADA deposit
* Ensure your wallet has enough ADA to cover the deposit plus fees

### "Cannot withdraw more than available" error

* Query actual available rewards before withdrawing
* Use `provider.fetchAccountInfo(rewardAddress)` to check balance

### "Stake address already registered" error

* Skip `registerStakeCertificate()` if already registered
* Query stake address status first to check registration

### Script withdrawal fails

* Ensure the script stake key is registered first
* Provide valid collateral for Plutus script execution
* Check that the redeemer matches what the script expects

## Related

* <Link href="/apis/txbuilder/basics">Transaction Basics</Link> - Core transaction building
* <Link href="/apis/txbuilder/governance">Governance</Link> - DRep delegation and voting
* <Link href="/providers">Providers</Link> - Query stake pool information
* <Link href="/apis/wallets">Wallets</Link> - Get reward addresses


# Parser Basics
URL: /apis/txparser/basics

Parse Cardano transactions from CBOR hex and rebuild them with modifications.

***

title: "Parser Basics"
description: "Parse Cardano transactions from CBOR hex and rebuild them with modifications."
--------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

`TxParser` converts transaction CBOR hex into a `MeshTxBuilderBody` object, enabling you to inspect, modify, and rebuild transactions. This is useful for debugging, analyzing on-chain transactions, and implementing transaction modification workflows.

**When to use this:**

* Inspecting transaction structure for debugging
* Analyzing transactions from the blockchain
* Modifying and rebuilding existing transactions
* Implementing transaction amendment workflows
* Converting between transaction formats

## Quick Start

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

// Initialize parser with serializer and optional fetcher
const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

// Parse a transaction CBOR
const txHex = "84a400818258..."; // Transaction CBOR hex
const utxos = await wallet.getUtxos();

const txBuilderBody = await txParser.parse(txHex, utxos);

// Inspect parsed data
console.log("Inputs:", txBuilderBody.inputs);
console.log("Outputs:", txBuilderBody.outputs);
console.log("Fee:", txBuilderBody.fee);
```

## API Reference

### Constructor

Create a new TxParser instance.

```tsx
new TxParser(serializer: IMeshTxSerializer, fetcher?: IFetcher)
```

| Parameter    | Type                | Required | Description                             |
| ------------ | ------------------- | -------- | --------------------------------------- |
| `serializer` | `IMeshTxSerializer` | Yes      | Serializer for parsing (CSLSerializer)  |
| `fetcher`    | `IFetcher`          | No       | Provider for fetching missing UTxO data |

### parse()

Parse a transaction CBOR hex into a MeshTxBuilderBody.

```tsx
await txParser.parse(txHex: string, providedUtxos?: UTxO[]): Promise<MeshTxBuilderBody>
```

| Parameter       | Type     | Required | Description            |
| --------------- | -------- | -------- | ---------------------- |
| `txHex`         | `string` | Yes      | Transaction CBOR hex   |
| `providedUtxos` | `UTxO[]` | No       | Input UTxO information |

**Returns:** `Promise<MeshTxBuilderBody>` - Parsed transaction body

### toTester()

Convert the parsed transaction to a TxTester for unit testing.

```tsx
txParser.toTester(): TxTester
```

**Returns:** `TxTester` - Test utilities for the parsed transaction

## Common Patterns

### Initialize TxParser

Set up the parser with required dependencies:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

// With fetcher (recommended - auto-fetches missing UTxO data)
const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

// Without fetcher (must provide all UTxO data manually)
const txParserNoFetch = new TxParser(serializer);
```

### Parse and Inspect Transaction

Parse a transaction and examine its structure:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

// Get the transaction CBOR (from building or from chain)
const txHex = "84a400818258...";

// Provide UTxOs for inputs (or let fetcher get them)
const utxos = await wallet.getUtxos();

// Parse the transaction
const txBody = await txParser.parse(txHex, utxos);

// Inspect the parsed structure
console.log("=== Transaction Analysis ===");
console.log("Inputs:", txBody.inputs.length);
console.log("Outputs:", txBody.outputs.length);
console.log("Fee:", txBody.fee);
console.log("Mints:", txBody.mints?.length || 0);
console.log("Validity:", {
  from: txBody.validityRange?.invalidBefore,
  to: txBody.validityRange?.invalidHereafter,
});

// Examine specific inputs
txBody.inputs.forEach((input, i) => {
  console.log(`Input ${i}:`, input.txIn.txHash, "#", input.txIn.txIndex);
});

// Examine outputs
txBody.outputs.forEach((output, i) => {
  console.log(`Output ${i}:`, output.address, output.amount);
});
```

### Rebuild Transaction with Modifications

Parse a transaction, modify it, and rebuild:

```tsx
import {
  BlockfrostProvider,
  TxParser,
  MeshTxBuilder
} from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

// Parse original transaction
const originalTxHex = "84a400818258...";
const utxos = await wallet.getUtxos();
const txBody = await txParser.parse(originalTxHex, utxos);

// Modify the transaction body
txBody.outputs.push({
  address: "addr_test1qz...",
  amount: [{ unit: "lovelace", quantity: "2000000" }],
});

// Rebuild with MeshTxBuilder
const txBuilder = new MeshTxBuilder({
  fetcher,
  verbose: true,
});

const newTxHex = await txBuilder.complete(txBody);

// Sign and submit the modified transaction
const signedTx = await wallet.signTx(newTxHex);
const txHash = await wallet.submitTx(signedTx);
```

### Parse from Blockchain

Fetch and parse a transaction from the blockchain:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, provider);

// Fetch transaction from blockchain
const txHash = "abc123...";
const txInfo = await provider.fetchTxInfo(txHash);

// Parse the transaction (fetcher auto-gets UTxO data)
const txBody = await txParser.parse(txInfo.tx.cborHex);

// Analyze the transaction
console.log("Transaction:", txHash);
console.log("Block:", txInfo.block);
console.log("Inputs:", txBody.inputs.length);
console.log("Outputs:", txBody.outputs.length);
```

### Convert to Unit Tester

Parse and create a tester for validation:

```tsx
import { BlockfrostProvider, TxParser, MeshValue } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

// Parse transaction
const txHex = "84a400818258...";
const utxos = await wallet.getUtxos();
await txParser.parse(txHex, utxos);

// Convert to tester
const txTester = txParser.toTester();

// Run tests
txTester
  .allOutputs()
  .outputsValue(
    MeshValue.fromAssets([{ unit: "lovelace", quantity: "5000000" }])
  );

// Check results
const passed = txTester.success();
const errors = txTester.errors();

console.log("Tests passed:", passed);
if (!passed) {
  console.log("Errors:", errors);
}
```

## Complete Example

This example demonstrates parsing, analyzing, and modifying a transaction:

```tsx
import {
  BlockfrostProvider,
  TxParser,
  MeshTxBuilder,
  MeshValue
} from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, provider);

// Analyze a transaction
async function analyzeTransaction(txHex: string, utxos?: any[]) {
  const txBody = await txParser.parse(txHex, utxos);

  return {
    inputCount: txBody.inputs.length,
    outputCount: txBody.outputs.length,
    fee: txBody.fee,
    hasMints: (txBody.mints?.length || 0) > 0,
    hasMetadata: !!txBody.metadata,
    totalInputValue: calculateTotalValue(txBody.inputs),
    totalOutputValue: calculateTotalValue(txBody.outputs),
  };
}

// Modify a transaction to add an output
async function addOutputToTransaction(
  txHex: string,
  utxos: any[],
  newOutput: { address: string; amount: any[] }
) {
  const txBody = await txParser.parse(txHex, utxos);

  // Add new output
  txBody.outputs.push(newOutput);

  // Rebuild
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  return await txBuilder.complete(txBody);
}

// Test a transaction's structure
async function testTransaction(txHex: string, utxos: any[]) {
  await txParser.parse(txHex, utxos);
  const tester = txParser.toTester();

  // Run validation tests
  tester
    .allInputs()
    .inputsValue(
      MeshValue.fromAssets([{ unit: "lovelace", quantity: "1000000" }])
    );

  tester
    .allOutputs()
    .outputsValue(
      MeshValue.fromAssets([{ unit: "lovelace", quantity: "500000" }])
    );

  return {
    passed: tester.success(),
    errors: tester.errors(),
  };
}

// Helper to calculate total value
function calculateTotalValue(items: any[]) {
  const totals: Record<string, bigint> = {};

  items.forEach((item) => {
    const amount = item.amount || item.txIn?.amount || [];
    amount.forEach((asset: any) => {
      const current = totals[asset.unit] || 0n;
      totals[asset.unit] = current + BigInt(asset.quantity);
    });
  });

  return totals;
}

// Usage
async function main() {
  const txHex = "84a400818258...";
  const utxos = await wallet.getUtxos();

  // Analyze
  const analysis = await analyzeTransaction(txHex, utxos);
  console.log("Analysis:", analysis);

  // Test
  const testResult = await testTransaction(txHex, utxos);
  console.log("Test result:", testResult);

  // Modify
  const modifiedTx = await addOutputToTransaction(txHex, utxos, {
    address: "addr_test1qz...",
    amount: [{ unit: "lovelace", quantity: "2000000" }],
  });
  console.log("Modified transaction:", modifiedTx);
}
```

## Troubleshooting

### "Missing UTxO information" error

* Provide UTxOs via the `providedUtxos` parameter
* Or configure a fetcher to auto-retrieve missing data
* Transaction CBOR only contains hashes, not full UTxO data

### "Failed to parse CBOR" error

* Ensure the hex string is valid transaction CBOR
* Check that it's a complete transaction, not just a body

### "Serializer error" error

* Make sure you're using CSLSerializer from @meshsdk/core-csl
* Verify the serializer is properly initialized

### "Cannot fetch UTxO" error

* Check your provider API key is valid
* Verify network connectivity
* The UTxO may have been spent

## Related

* <Link href="/apis/txparser/txtester">Unit Testing</Link> - Test transaction logic
* <Link href="/apis/txbuilder">Transaction Builder</Link> - Build transactions
* <Link href="/apis/data">Data Types</Link> - Working with Cardano data


# Cardano Transaction Parser
URL: /apis/txparser

Parse, analyze, and test Cardano transactions from CBOR hex.

***

title: "Cardano Transaction Parser"
description: "Parse, analyze, and test Cardano transactions from CBOR hex."
icon: MagnifyingGlassIcon
-------------------------

import { linksTxParser } from "@/data/links-txparser";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

`TxParser` parses Cardano transaction CBOR hex back into a structured `MeshTxBuilderBody` object. This enables you to analyze transactions, rebuild them with modifications, or run unit tests against transaction logic.

**When to use TxParser:**

* Debugging transaction building issues
* Analyzing on-chain transactions
* Rebuilding transactions with modifications
* Unit testing transaction logic
* Verifying transaction structure before submission

## Quick Start

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

// Initialize parser
const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

// Parse a transaction
const txHex = "84a400..."; // Your transaction CBOR hex
const utxos = await wallet.getUtxos(); // Input UTxOs

const txBuilderBody = await txParser.parse(txHex, utxos);

// Inspect the parsed transaction
console.log("Inputs:", txBuilderBody.inputs);
console.log("Outputs:", txBuilderBody.outputs);
console.log("Mints:", txBuilderBody.mints);

// Convert to tester for unit testing
const txTester = txParser.toTester();
```

## Documentation

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksTxParser.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related

* <Link href="/apis/txbuilder">Transaction Builder</Link> - Build transactions
* <Link href="/providers">Providers</Link> - Blockchain data providers
* <Link href="/apis/data">Data Types</Link> - Working with Cardano data


# Transaction Unit Testing
URL: /apis/txparser/txtester

Test and validate Cardano transactions with a fluent testing API.

***

title: "Transaction Unit Testing"
description: "Test and validate Cardano transactions with a fluent testing API."
--------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

`TxTester` provides a fluent API for unit testing Cardano transactions. After parsing a transaction with `TxParser`, you can use `TxTester` to validate inputs, outputs, mints, validity ranges, and signatures.

**When to use this:**

* Unit testing smart contract transactions
* Validating transaction structure in CI/CD pipelines
* Debugging transaction building logic
* Ensuring transactions meet specific requirements
* Testing DeFi protocol transactions

## Quick Start

```tsx
import { BlockfrostProvider, TxParser, MeshValue } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

// Initialize and parse
const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

const txHex = "84a400818258...";
const utxos = await wallet.getUtxos();
await txParser.parse(txHex, utxos);

// Create tester
const txTester = txParser.toTester();

// Run tests
txTester
  .outputsAt("addr_test1qz...")
  .outputsValue(
    MeshValue.fromAssets([{ unit: "lovelace", quantity: "5000000" }])
  );

// Check results
const passed = txTester.success();
console.log("Tests passed:", passed);
console.log("Errors:", txTester.errors());
```

## API Reference

### Result Methods

#### success()

Check if all tests passed.

```tsx
txTester.success(): boolean
```

**Returns:** `true` if all tests passed, `false` otherwise

#### errors()

Get all error messages from failed tests.

```tsx
txTester.errors(): string
```

**Returns:** Concatenated error messages (empty string if no errors)

### Input Filters

Filter inputs before testing. Filters persist until changed.

#### allInputs()

Clear filters and select all inputs.

```tsx
txTester.allInputs(): TxTester
```

#### inputsAt()

Filter inputs by address.

```tsx
txTester.inputsAt(address: string): TxTester
```

| Parameter | Type     | Description          |
| --------- | -------- | -------------------- |
| `address` | `string` | Address to filter by |

#### inputsWith()

Filter inputs containing a specific token.

```tsx
txTester.inputsWith(unit: string): TxTester
```

| Parameter | Type     | Description                       |
| --------- | -------- | --------------------------------- |
| `unit`    | `string` | Asset unit (policyId + tokenName) |

#### inputsWithPolicy()

Filter inputs containing any token from a policy.

```tsx
txTester.inputsWithPolicy(policyId: string): TxTester
```

| Parameter  | Type     | Description            |
| ---------- | -------- | ---------------------- |
| `policyId` | `string` | Policy ID to filter by |

#### inputsAtWith()

Filter inputs by address AND token.

```tsx
txTester.inputsAtWith(address: string, unit: string): TxTester
```

#### inputsAtWithPolicy()

Filter inputs by address AND policy.

```tsx
txTester.inputsAtWithPolicy(address: string, policyId: string): TxTester
```

### Input Tests

#### inputsValue()

Test the total value of filtered inputs.

```tsx
txTester.inputsValue(expected: MeshValue): TxTester
```

| Parameter  | Type        | Description          |
| ---------- | ----------- | -------------------- |
| `expected` | `MeshValue` | Expected total value |

### Output Filters

Filter outputs before testing. Filters persist until changed.

#### allOutputs()

Clear filters and select all outputs.

```tsx
txTester.allOutputs(): TxTester
```

#### outputsAt()

Filter outputs by address.

```tsx
txTester.outputsAt(address: string): TxTester
```

#### outputsWith()

Filter outputs containing a specific token.

```tsx
txTester.outputsWith(unit: string): TxTester
```

#### outputsWithPolicy()

Filter outputs containing any token from a policy.

```tsx
txTester.outputsWithPolicy(policyId: string): TxTester
```

#### outputsAtWith()

Filter outputs by address AND token.

```tsx
txTester.outputsAtWith(address: string, unit: string): TxTester
```

#### outputsAtWithPolicy()

Filter outputs by address AND policy.

```tsx
txTester.outputsAtWithPolicy(address: string, policyId: string): TxTester
```

### Output Tests

#### outputsValue()

Test the total value of filtered outputs.

```tsx
txTester.outputsValue(expected: MeshValue): TxTester
```

| Parameter  | Type        | Description          |
| ---------- | ----------- | -------------------- |
| `expected` | `MeshValue` | Expected total value |

#### outputsInlineDatumExist()

Check if any filtered output contains specific inline datum.

```tsx
txTester.outputsInlineDatumExist(datumCbor: string): TxTester
```

| Parameter   | Type     | Description         |
| ----------- | -------- | ------------------- |
| `datumCbor` | `string` | Expected datum CBOR |

### Mint Tests

#### tokenMinted()

Check if a specific token was minted.

```tsx
txTester.tokenMinted(policyId: string, tokenName: string, quantity: number): TxTester
```

| Parameter   | Type     | Description               |
| ----------- | -------- | ------------------------- |
| `policyId`  | `string` | Policy ID                 |
| `tokenName` | `string` | Token name (hex or empty) |
| `quantity`  | `number` | Expected mint quantity    |

#### onlyTokenMinted()

Check if only this specific token was minted (no other mints).

```tsx
txTester.onlyTokenMinted(policyId: string, tokenName: string, quantity: number): TxTester
```

#### policyOnlyMintedToken()

Check that a policy only minted this specific token.

```tsx
txTester.policyOnlyMintedToken(policyId: string, tokenName: string, quantity: number): TxTester
```

#### checkPolicyOnlyBurn()

Check that a policy only burned tokens (negative quantity).

```tsx
txTester.checkPolicyOnlyBurn(policyId: string): TxTester
```

### Time Tests

#### validAfter()

Check if transaction is valid after a timestamp.

```tsx
txTester.validAfter(timestamp: number): TxTester
```

| Parameter   | Type     | Description                   |
| ----------- | -------- | ----------------------------- |
| `timestamp` | `number` | Unix timestamp (milliseconds) |

#### validBefore()

Check if transaction is valid before a timestamp.

```tsx
txTester.validBefore(timestamp: number): TxTester
```

| Parameter   | Type     | Description                   |
| ----------- | -------- | ----------------------------- |
| `timestamp` | `number` | Unix timestamp (milliseconds) |

### Signature Tests

#### keySigned()

Check if a specific key signed the transaction.

```tsx
txTester.keySigned(keyHash: string): TxTester
```

| Parameter | Type     | Description     |
| --------- | -------- | --------------- |
| `keyHash` | `string` | Public key hash |

#### oneOfKeysSigned()

Check if at least one of the keys signed.

```tsx
txTester.oneOfKeysSigned(keyHashes: string[]): TxTester
```

| Parameter   | Type       | Description                |
| ----------- | ---------- | -------------------------- |
| `keyHashes` | `string[]` | Array of public key hashes |

#### allKeysSigned()

Check if all specified keys signed.

```tsx
txTester.allKeysSigned(keyHashes: string[]): TxTester
```

| Parameter   | Type       | Description                |
| ----------- | ---------- | -------------------------- |
| `keyHashes` | `string[]` | Array of public key hashes |

## Common Patterns

### Test Output Values

Verify outputs at specific addresses:

```tsx
import { BlockfrostProvider, TxParser, MeshValue } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

// Test outputs at a specific address
txTester
  .outputsAt("addr_test1qz...")
  .outputsValue(
    MeshValue.fromAssets([
      { unit: "lovelace", quantity: "5000000" },
      { unit: "policyId...tokenName", quantity: "1" },
    ])
  );

// Test outputs containing a specific token
txTester
  .outputsWith("policyId...tokenName")
  .outputsValue(
    MeshValue.fromAssets([{ unit: "lovelace", quantity: "2000000" }])
  );

console.log("Passed:", txTester.success());
console.log("Errors:", txTester.errors());
```

### Test Minting

Verify token minting behavior:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

const policyId = "eab3a1d125a3bf4cd941a6a0b5d7752af96fae7f5bcc641e8a0b6762";
const tokenName = "MeshToken";

// Check specific token was minted
txTester.tokenMinted(policyId, tokenName, 1);

// Check only this token was minted
txTester.onlyTokenMinted(policyId, tokenName, 1);

// Check policy only minted this token
txTester.policyOnlyMintedToken(policyId, tokenName, 1);

console.log("Passed:", txTester.success());
console.log("Errors:", txTester.errors());
```

### Test Burning

Verify token burning:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

const policyId = "eab3a1d125a3bf4cd941a6a0b5d7752af96fae7f5bcc641e8a0b6762";

// Check token was burned (negative quantity)
txTester.tokenMinted(policyId, "MeshToken", -1);

// Check policy only burned (no mints)
txTester.checkPolicyOnlyBurn(policyId);

console.log("Passed:", txTester.success());
```

### Test Time Validity

Verify transaction time bounds:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

const now = Date.now();
const oneHourAgo = now - 60 * 60 * 1000;
const oneHourLater = now + 60 * 60 * 1000;

// Check transaction validity window
txTester
  .validAfter(oneHourAgo)
  .validBefore(oneHourLater);

console.log("Passed:", txTester.success());
console.log("Errors:", txTester.errors());
```

### Test Signatures

Verify required signatures:

```tsx
import { BlockfrostProvider, TxParser, deserializeAddress } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

// Get key hashes
const { pubKeyHash: keyHash1 } = deserializeAddress(address1);
const { pubKeyHash: keyHash2 } = deserializeAddress(address2);

// Check specific key signed
txTester.keySigned(keyHash1);

// Check at least one key signed
txTester.oneOfKeysSigned([keyHash1, keyHash2]);

// Check all keys signed
txTester.allKeysSigned([keyHash1, keyHash2]);

console.log("Passed:", txTester.success());
console.log("Errors:", txTester.errors());
```

### Test Input Values

Verify input consumption:

```tsx
import { BlockfrostProvider, TxParser, MeshValue } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

const scriptAddress = "addr_test1wz...";

// Test all inputs
txTester
  .allInputs()
  .inputsValue(
    MeshValue.fromAssets([{ unit: "lovelace", quantity: "10000000" }])
  );

// Test inputs from script address
txTester
  .inputsAt(scriptAddress)
  .inputsValue(
    MeshValue.fromAssets([{ unit: "lovelace", quantity: "5000000" }])
  );

// Test inputs with specific policy
txTester
  .inputsWithPolicy("policyId...")
  .inputsValue(
    MeshValue.fromAssets([
      { unit: "lovelace", quantity: "2000000" },
      { unit: "policyId...tokenName", quantity: "1" },
    ])
  );

console.log("Passed:", txTester.success());
```

### Test Inline Datum

Verify inline datum in outputs:

```tsx
import { BlockfrostProvider, TxParser } from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const fetcher = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, fetcher);

await txParser.parse(txHex, utxos);
const txTester = txParser.toTester();

const scriptAddress = "addr_test1wz...";
const expectedDatumCbor = "d8799f..."; // Your expected datum CBOR

// Check outputs at script address have expected datum
txTester
  .outputsAt(scriptAddress)
  .outputsInlineDatumExist(expectedDatumCbor);

console.log("Passed:", txTester.success());
console.log("Errors:", txTester.errors());
```

## Complete Example

Full unit testing workflow for a DeFi swap transaction:

```tsx
import {
  BlockfrostProvider,
  TxParser,
  MeshValue,
  deserializeAddress
} from "@meshsdk/core";
import { CSLSerializer } from "@meshsdk/core-csl";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");
const serializer = new CSLSerializer();
const txParser = new TxParser(serializer, provider);

// Test a swap transaction
async function testSwapTransaction(
  txHex: string,
  utxos: any[],
  config: {
    userAddress: string;
    poolAddress: string;
    inputTokenPolicy: string;
    outputTokenPolicy: string;
    inputAmount: string;
    minOutputAmount: string;
  }
) {
  await txParser.parse(txHex, utxos);
  const txTester = txParser.toTester();

  const { pubKeyHash: userKeyHash } = deserializeAddress(config.userAddress);

  // 1. Verify user signed the transaction
  txTester.keySigned(userKeyHash);

  // 2. Verify input tokens consumed from user
  txTester
    .inputsAtWithPolicy(config.userAddress, config.inputTokenPolicy)
    .inputsValue(
      MeshValue.fromAssets([
        { unit: config.inputTokenPolicy, quantity: config.inputAmount },
      ])
    );

  // 3. Verify pool received input tokens
  txTester
    .outputsAtWithPolicy(config.poolAddress, config.inputTokenPolicy)
    .outputsValue(
      MeshValue.fromAssets([
        { unit: config.inputTokenPolicy, quantity: config.inputAmount },
      ])
    );

  // 4. Verify user received output tokens
  txTester
    .outputsAtWithPolicy(config.userAddress, config.outputTokenPolicy)
    .outputsValue(
      MeshValue.fromAssets([
        { unit: config.outputTokenPolicy, quantity: config.minOutputAmount },
      ])
    );

  // 5. Verify transaction validity
  const now = Date.now();
  txTester
    .validAfter(now - 5 * 60 * 1000)  // Valid from 5 min ago
    .validBefore(now + 30 * 60 * 1000); // Valid for 30 min

  // Get results
  const passed = txTester.success();
  const errors = txTester.errors();

  return {
    passed,
    errors,
    summary: {
      signatureValid: !errors.includes("key"),
      inputsValid: !errors.includes("input"),
      outputsValid: !errors.includes("output"),
      timeValid: !errors.includes("valid"),
    },
  };
}

// Usage
async function main() {
  const txHex = "84a400818258...";
  const utxos = await wallet.getUtxos();

  const result = await testSwapTransaction(txHex, utxos, {
    userAddress: "addr_test1qz...",
    poolAddress: "addr_test1wz...",
    inputTokenPolicy: "policyA...",
    outputTokenPolicy: "policyB...",
    inputAmount: "1000000",
    minOutputAmount: "950000",
  });

  console.log("Test Results:");
  console.log("  Passed:", result.passed);
  console.log("  Summary:", result.summary);

  if (!result.passed) {
    console.log("  Errors:", result.errors);
  }
}
```

## Troubleshooting

### "Filter returned no results" issue

* Check that the address/policy exists in the transaction
* Use `allInputs()` or `allOutputs()` to reset filters
* Verify you're testing the correct transaction

### "Value mismatch" error

* Check asset units are correct (policyId + tokenName)
* Verify quantities match exactly
* Use `MeshValue.fromAssets()` for proper value construction

### "Key not signed" error

* Ensure you're using the correct key hash format
* Transaction may require partial signing first
* Check that the key is in the required signers list

### "Datum not found" error

* Verify the datum CBOR is correct
* Check the output has inline datum (not datum hash)
* Ensure you're testing the right output address

## Related

* <Link href="/apis/txparser/basics">Parser Basics</Link> - Parse transactions
* <Link href="/apis/txbuilder">Transaction Builder</Link> - Build transactions
* <Link href="/apis/data">Data Types</Link> - Working with MeshValue and datum


# Smart Contract Blueprints
URL: /apis/utilities/blueprints

Create and manage smart contract blueprints for Cardano validators

***

title: "Smart Contract Blueprints"
description: "Create and manage smart contract blueprints for Cardano validators"
---------------------------------------------------------------------------------

Use the Blueprint utility classes to manage serialization and deserialization logic for Cardano smart contracts. Blueprints support three validator types: Spending, Minting, and Withdrawal.

## Overview

Blueprint classes simplify working with Plutus scripts by providing:

* Automatic script hash calculation
* Script CBOR serialization
* Address generation (for spending and withdrawal validators)
* Policy ID extraction (for minting validators)
* Parameter application to parameterized scripts

You can also use the [Cardano Bar VSCode extension](https://marketplace.visualstudio.com/items?itemName=sidan-lab.cardano-bar-vscode) from [SIDAN Lab](https://x.com/sidan_lab) to parse CIP-57 blueprint objects into Mesh types.

## Quick Start

```tsx
import { SpendingBlueprint, MintingBlueprint, WithdrawalBlueprint } from "@meshsdk/core";

// Create a spending blueprint
const spendingBlueprint = new SpendingBlueprint("V2", 0);
spendingBlueprint.noParamScript(compiledCode);

// Access script information
const scriptHash = spendingBlueprint.hash;
const scriptAddress = spendingBlueprint.address;
```

***

## SpendingBlueprint

Create a blueprint for spending validators. Use this when you need to lock funds at a script address and later spend them.

### Constructor

```tsx
new SpendingBlueprint(plutusVersion: string, networkId: number, stakeKeyHash?: string)
```

| Parameter       | Type     | Description                                     |
| --------------- | -------- | ----------------------------------------------- |
| `plutusVersion` | `string` | Plutus version (`"V1"`, `"V2"`, or `"V3"`)      |
| `networkId`     | `number` | Network ID (`0` for testnet, `1` for mainnet)   |
| `stakeKeyHash`  | `string` | Optional. Stake key hash for the script address |

### Properties

| Property  | Type     | Description               |
| --------- | -------- | ------------------------- |
| `hash`    | `string` | The script hash           |
| `cbor`    | `string` | The script in CBOR format |
| `address` | `string` | The bech32 script address |

### Methods

#### noParamScript

Use this method for validators that require no parameters.

```tsx
noParamScript(compiledCode: string): void
```

| Parameter      | Type     | Description                     |
| -------------- | -------- | ------------------------------- |
| `compiledCode` | `string` | The compiled Plutus script code |

#### paramScript

Use this method for parameterized validators that require initialization parameters.

```tsx
paramScript(compiledCode: string, params: any[], dataType: string): void
```

| Parameter      | Type     | Description                                |
| -------------- | -------- | ------------------------------------------ |
| `compiledCode` | `string` | The compiled Plutus script code            |
| `params`       | `any[]`  | Array of parameters to apply to the script |
| `dataType`     | `string` | Data type format (`"Mesh"` or `"JSON"`)    |

### Example: Spending Blueprint Without Parameters

```tsx
import { SpendingBlueprint } from "@meshsdk/core";

const compiledCode = "5906f4010100..."; // Your compiled script

const blueprint = new SpendingBlueprint("V2", 0);
blueprint.noParamScript(compiledCode);

const scriptHash = blueprint.hash;
const scriptCbor = blueprint.cbor;
const scriptAddress = blueprint.address;
```

### Example: Spending Blueprint With Parameters

```tsx
import { SpendingBlueprint, mPubKeyAddress } from "@meshsdk/core";

const compiledCode = "5906f4010100..."; // Your compiled script
const stakeHash = "9e8a6e5fcbbb5b84deefc71d7cb6319a3da9cc3d19765efb303647ef";

const blueprint = new SpendingBlueprint("V2", 0, stakeHash);
blueprint.paramScript(
  compiledCode,
  [
    mPubKeyAddress(
      "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
      "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
    ),
  ],
  "Mesh"
);

const scriptHash = blueprint.hash;
const scriptCbor = blueprint.cbor;
const scriptAddress = blueprint.address;
```

***

## MintingBlueprint

Create a blueprint for minting validators. Use this when you need to define a minting policy for native assets.

### Constructor

```tsx
new MintingBlueprint(plutusVersion: string)
```

| Parameter       | Type     | Description                                |
| --------------- | -------- | ------------------------------------------ |
| `plutusVersion` | `string` | Plutus version (`"V1"`, `"V2"`, or `"V3"`) |

### Properties

| Property | Type     | Description                 |
| -------- | -------- | --------------------------- |
| `hash`   | `string` | The policy ID (script hash) |
| `cbor`   | `string` | The script in CBOR format   |

### Methods

#### noParamScript

Use this method for minting policies that require no parameters.

```tsx
noParamScript(compiledCode: string): void
```

| Parameter      | Type     | Description                     |
| -------------- | -------- | ------------------------------- |
| `compiledCode` | `string` | The compiled Plutus script code |

#### paramScript

Use this method for parameterized minting policies.

```tsx
paramScript(compiledCode: string, params: any[], dataType: string): void
```

| Parameter      | Type     | Description                                |
| -------------- | -------- | ------------------------------------------ |
| `compiledCode` | `string` | The compiled Plutus script code            |
| `params`       | `any[]`  | Array of parameters to apply to the script |
| `dataType`     | `string` | Data type format (`"Mesh"` or `"JSON"`)    |

### Example: Minting Blueprint Without Parameters

```tsx
import { MintingBlueprint } from "@meshsdk/core";

const compiledCode = "5906f4010100..."; // Your compiled script

const blueprint = new MintingBlueprint("V2");
blueprint.noParamScript(compiledCode);

const policyId = blueprint.hash;
const scriptCbor = blueprint.cbor;
```

### Example: Minting Blueprint With Parameters

```tsx
import { MintingBlueprint, mPubKeyAddress } from "@meshsdk/core";

const compiledCode = "5906f4010100..."; // Your compiled script

const blueprint = new MintingBlueprint("V2");
blueprint.paramScript(
  compiledCode,
  [
    mPubKeyAddress(
      "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
      "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
    ),
    100,
  ],
  "Mesh"
);

const policyId = blueprint.hash;
const scriptCbor = blueprint.cbor;
```

***

## WithdrawalBlueprint

Create a blueprint for withdrawal validators. Use this when you need to control stake reward withdrawals.

### Constructor

```tsx
new WithdrawalBlueprint(plutusVersion: string, networkId: number)
```

| Parameter       | Type     | Description                                   |
| --------------- | -------- | --------------------------------------------- |
| `plutusVersion` | `string` | Plutus version (`"V1"`, `"V2"`, or `"V3"`)    |
| `networkId`     | `number` | Network ID (`0` for testnet, `1` for mainnet) |

### Properties

| Property  | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `hash`    | `string` | The script hash                    |
| `cbor`    | `string` | The script in CBOR format          |
| `address` | `string` | The reward address (stake address) |

### Methods

#### noParamScript

Use this method for withdrawal validators that require no parameters.

```tsx
noParamScript(compiledCode: string): void
```

| Parameter      | Type     | Description                     |
| -------------- | -------- | ------------------------------- |
| `compiledCode` | `string` | The compiled Plutus script code |

#### paramScript

Use this method for parameterized withdrawal validators.

```tsx
paramScript(compiledCode: string, params: any[], dataType: string): void
```

| Parameter      | Type     | Description                                |
| -------------- | -------- | ------------------------------------------ |
| `compiledCode` | `string` | The compiled Plutus script code            |
| `params`       | `any[]`  | Array of parameters to apply to the script |
| `dataType`     | `string` | Data type format (`"Mesh"` or `"JSON"`)    |

### Example: Withdrawal Blueprint Without Parameters

```tsx
import { WithdrawalBlueprint } from "@meshsdk/core";

const compiledCode = "5906f4010100..."; // Your compiled script

const blueprint = new WithdrawalBlueprint("V2", 0);
blueprint.noParamScript(compiledCode);

const scriptHash = blueprint.hash;
const scriptCbor = blueprint.cbor;
const rewardAddress = blueprint.address;
```

### Example: Withdrawal Blueprint With Parameters

```tsx
import { WithdrawalBlueprint, mPubKeyAddress } from "@meshsdk/core";

const compiledCode = "5906f4010100..."; // Your compiled script

const blueprint = new WithdrawalBlueprint("V2", 0);
blueprint.paramScript(
  compiledCode,
  [
    mPubKeyAddress(
      "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
      "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
    ),
    100,
  ],
  "Mesh"
);

const scriptHash = blueprint.hash;
const scriptCbor = blueprint.cbor;
const rewardAddress = blueprint.address;
```

***

## Complete Example

This example demonstrates using all three blueprint types in a dApp:

```tsx
import {
  SpendingBlueprint,
  MintingBlueprint,
  WithdrawalBlueprint,
  mPubKeyAddress,
} from "@meshsdk/core";

// Configuration
const plutusVersion = "V2";
const networkId = 0; // testnet
const stakeKeyHash = "9e8a6e5fcbbb5b84deefc71d7cb6319a3da9cc3d19765efb303647ef";

// Script parameters
const ownerAddress = mPubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);

// Spending validator for locking funds
const spendingBlueprint = new SpendingBlueprint(plutusVersion, networkId, stakeKeyHash);
spendingBlueprint.paramScript(spendingCompiledCode, [ownerAddress], "Mesh");

console.log("Spending Script Address:", spendingBlueprint.address);
console.log("Spending Script Hash:", spendingBlueprint.hash);

// Minting policy for NFTs
const mintingBlueprint = new MintingBlueprint(plutusVersion);
mintingBlueprint.paramScript(mintingCompiledCode, [ownerAddress, 1], "Mesh");

console.log("Policy ID:", mintingBlueprint.hash);

// Withdrawal validator for stake rewards
const withdrawalBlueprint = new WithdrawalBlueprint(plutusVersion, networkId);
withdrawalBlueprint.paramScript(withdrawalCompiledCode, [ownerAddress], "Mesh");

console.log("Reward Address:", withdrawalBlueprint.address);
```

***

## Troubleshooting

### Script hash does not match expected value

Ensure you are using the correct Plutus version. Different versions produce different hashes for the same script code.

### Address generation fails

Check that you provided a valid network ID (`0` for testnet, `1` for mainnet). For spending blueprints, verify the stake key hash is a valid 56-character hex string.

### Parameter application fails

Verify your parameters match the expected types in your Plutus script. Use Mesh data types (`mPubKeyAddress`, `mConStr0`, etc.) when specifying `"Mesh"` as the data type.

***

## Related

* [Serializers](/apis/utilities/serializers) - Serialize scripts and addresses
* [Deserializers](/apis/utilities/deserializers) - Parse script and address data
* [Mesh Data](/apis/data/mesh) - Build parameters using Mesh data types
* [Transaction Builder](/apis/txbuilder/smart-contracts) - Use blueprints in transactions


# CBOR Deserializers
URL: /apis/utilities/deserializers

Parse CBOR and bech32 encoded Cardano data into usable objects

***

title: "CBOR Deserializers"
description: "Parse CBOR and bech32 encoded Cardano data into usable objects"
-----------------------------------------------------------------------------

Use deserializer functions to parse Cardano on-chain data into JavaScript objects. These utilities convert bech32 addresses, CBOR-encoded datums, and pool identifiers into their component parts.

## Overview

Deserialization converts encoded on-chain data back into structured objects you can work with in your application. MeshJS provides deserializers for:

* Bech32 addresses (extracting payment and stake credentials)
* CBOR-encoded datums
* Pool identifiers (bech32 to key hash)

## Quick Start

```tsx
import { deserializeAddress } from "@meshsdk/core";

const address = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";

const { pubKeyHash, stakeCredentialHash } = deserializeAddress(address);
console.log("Payment Key Hash:", pubKeyHash);
console.log("Stake Key Hash:", stakeCredentialHash);
```

***

## deserializeAddress

Parse a bech32 address into its payment and staking components.

### Function Signature

```tsx
deserializeAddress(bech32Address: string): DeserializedAddress
```

### Parameters

| Parameter       | Type     | Required | Description                    |
| --------------- | -------- | -------- | ------------------------------ |
| `bech32Address` | `string` | Yes      | A valid Cardano bech32 address |

### Returns

| Property                    | Type                  | Description                                                  |
| --------------------------- | --------------------- | ------------------------------------------------------------ |
| `pubKeyHash`                | `string \| undefined` | The payment public key hash (if payment credential is a key) |
| `scriptHash`                | `string \| undefined` | The payment script hash (if payment credential is a script)  |
| `stakeCredentialHash`       | `string \| undefined` | The stake credential hash                                    |
| `stakeScriptCredentialHash` | `string \| undefined` | The stake script hash (if stake credential is a script)      |

### Example: Deserialize a Base Address

```tsx
import { deserializeAddress } from "@meshsdk/core";

const address = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";

const result = deserializeAddress(address);

console.log("Payment Key Hash:", result.pubKeyHash);
// Output: 58c7c1dc7893c107...

console.log("Stake Key Hash:", result.stakeCredentialHash);
// Output: ea6e6bf9153...
```

### Example: Deserialize a Script Address

```tsx
import { deserializeAddress } from "@meshsdk/core";

const scriptAddress = "addr_test1wz..."; // Script address

const result = deserializeAddress(scriptAddress);

if (result.scriptHash) {
  console.log("This is a script address");
  console.log("Script Hash:", result.scriptHash);
} else {
  console.log("This is a key address");
  console.log("Public Key Hash:", result.pubKeyHash);
}
```

### Example: Use With Native Scripts

```tsx
import { deserializeAddress, serializeNativeScript, NativeScript } from "@meshsdk/core";

const walletAddress = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";

// Extract the key hash from the address
const { pubKeyHash } = deserializeAddress(walletAddress);

// Use it to create a signature-based native script
const nativeScript: NativeScript = {
  type: "sig",
  keyHash: pubKeyHash,
};

const { address } = serializeNativeScript(nativeScript, 0);
console.log("Script Address:", address);
```

***

## deserializeDatum

Parse a CBOR-encoded datum into a JSON object.

### Function Signature

```tsx
deserializeDatum(datumCbor: string): any
```

### Parameters

| Parameter   | Type     | Required | Description                  |
| ----------- | -------- | -------- | ---------------------------- |
| `datumCbor` | `string` | Yes      | The datum in CBOR hex format |

### Returns

| Type  | Description                             |
| ----- | --------------------------------------- |
| `any` | The deserialized datum as a JSON object |

### Example

```tsx
import { deserializeDatum } from "@meshsdk/core";

const datumCbor = "d8799f4100d8799fd8799fd8799f581caa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6ffd8799fd8799fd8799f581c9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6ffffffffd87a80ff1a001e84801a05f5e100ff";

const datum = deserializeDatum(datumCbor);

console.log("Deserialized Datum:", JSON.stringify(datum, null, 2));
// Output: The datum structure as a JavaScript object
```

### Example: Parse Contract State

```tsx
import { deserializeDatum } from "@meshsdk/core";

// Fetch a UTxO with inline datum from your provider
const utxo = await provider.fetchAddressUTxOs(scriptAddress);
const datumCbor = utxo[0].output.plutusData;

if (datumCbor) {
  const contractState = deserializeDatum(datumCbor);

  console.log("Contract Owner:", contractState.fields[0]);
  console.log("Locked Amount:", contractState.fields[1]);
}
```

***

## deserializePoolId

Convert a pool ID from bech32 format to its Ed25519 key hash.

### Function Signature

```tsx
deserializePoolId(poolId: string): string
```

### Parameters

| Parameter | Type     | Required | Description                                         |
| --------- | -------- | -------- | --------------------------------------------------- |
| `poolId`  | `string` | Yes      | A pool ID in bech32 format (starts with `pool1...`) |

### Returns

| Type     | Description                                     |
| -------- | ----------------------------------------------- |
| `string` | The pool's Ed25519 key hash (56 hex characters) |

### Example

```tsx
import { deserializePoolId } from "@meshsdk/core";

const poolId = "pool107k26e3wrqxwghju2py40ngngx2qcu48ppeg7lk0cm35jl2aenx";

const keyHash = deserializePoolId(poolId);

console.log("Pool Key Hash:", keyHash);
// Output: 7f595acc9230339745c500494f9a1a0ca0c7255c21ca3dfb3f1bb8c9
```

### Example: Use in Delegation Transaction

```tsx
import { deserializePoolId, MeshTxBuilder } from "@meshsdk/core";

const poolId = "pool107k26e3wrqxwghju2py40ngngx2qcu48ppeg7lk0cm35jl2aenx";
const poolKeyHash = deserializePoolId(poolId);

const txBuilder = new MeshTxBuilder();

// Use the key hash in a delegation certificate
await txBuilder
  .delegateStakeCertificate(stakeKeyHash, poolKeyHash)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Complete Example

This example demonstrates deserializing various Cardano data types:

```tsx
import {
  deserializeAddress,
  deserializeDatum,
  deserializePoolId,
  serializeNativeScript,
  NativeScript,
} from "@meshsdk/core";

// 1. Deserialize an Address
const walletAddress = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";

const addressInfo = deserializeAddress(walletAddress);
console.log("Address Components:");
console.log("  Payment Key Hash:", addressInfo.pubKeyHash);
console.log("  Stake Key Hash:", addressInfo.stakeCredentialHash);

// 2. Create a Native Script Using the Key Hash
const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    {
      type: "sig",
      keyHash: addressInfo.pubKeyHash,
    },
    {
      type: "after",
      slot: "50000000",
    },
  ],
};

const { address: scriptAddress } = serializeNativeScript(nativeScript, 0);
console.log("\nNative Script Address:", scriptAddress);

// 3. Deserialize a Datum
const datumCbor = "d8799f4100ff";
const datum = deserializeDatum(datumCbor);
console.log("\nDeserialized Datum:", datum);

// 4. Deserialize a Pool ID
const poolId = "pool107k26e3wrqxwghju2py40ngngx2qcu48ppeg7lk0cm35jl2aenx";
const poolHash = deserializePoolId(poolId);
console.log("\nPool Key Hash:", poolHash);
```

***

## Troubleshooting

### Invalid address format error

Ensure the address is a valid Cardano bech32 address. Valid prefixes include:

* `addr1...` or `addr_test1...` for base addresses
* `stake1...` or `stake_test1...` for stake addresses

### Datum deserialization returns unexpected structure

The deserialized datum structure matches the Plutus data format. Constructor values appear as objects with `constructor` and `fields` properties. Verify your datum encoding matches the expected schema.

### Pool ID not recognized

Pool IDs must start with `pool1` (mainnet) or include the pool prefix. The bech32 encoding must be valid.

***

## Related

* [Serializers](/apis/utilities/serializers) - Encode data for on-chain use
* [Resolvers](/apis/utilities/resolvers) - Convert between different hash formats
* [Data APIs](/apis/data) - Work with Cardano data types


# Cardano SDK Utilities
URL: /apis/utilities

Serializers, deserializers, resolvers, and blueprints for converting between Cardano data formats.

***

title: "Cardano SDK Utilities"
description: "Serializers, deserializers, resolvers, and blueprints for converting between Cardano data formats."
icon: WrenchScrewdriverIcon
---------------------------

import { linksUtilities } from "@/data/links-utilities";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

MeshJS provides a comprehensive set of utility functions for working with Cardano data. Use these utilities to serialize scripts into addresses, deserialize on-chain data, resolve hashes, and work with smart contract blueprints.

## Overview

| Utility                                        | Purpose                                                                                      |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Blueprints](/apis/utilities/blueprints)       | Create and manage smart contract blueprints for spending, minting, and withdrawal validators |
| [Serializers](/apis/utilities/serializers)     | Encode scripts and data into CBOR or bech32 format                                           |
| [Deserializers](/apis/utilities/deserializers) | Parse CBOR or bech32 encoded data into usable objects                                        |
| [Resolvers](/apis/utilities/resolvers)         | Convert between different Cardano data formats (hashes, addresses, epochs)                   |

## Quick Start

Install the MeshJS SDK to access all utility functions:

```bash
npm install @meshsdk/core
```

Import the utilities you need:

```tsx
import {
  serializePlutusScript,
  deserializeAddress,
  resolveDataHash,
  SpendingBlueprint,
} from "@meshsdk/core";
```

## Browse Utilities

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksUtilities.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related

* [Data APIs](/apis/data) - Parse and manipulate Cardano data types
* [Transaction Builder](/apis/txbuilder) - Build transactions using these utilities


# Resolvers
URL: /apis/utilities/resolvers

Convert between different Cardano data formats including hashes, addresses, epochs, and slots

***

title: "Resolvers"
description: "Convert between different Cardano data formats including hashes, addresses, epochs, and slots"
------------------------------------------------------------------------------------------------------------

Use resolver functions to convert between different Cardano data formats. These utilities handle conversions for private keys, transaction hashes, data hashes, script hashes, addresses, epochs, and slots.

## Overview

Resolvers provide format conversion utilities for common Cardano operations:

* Key derivation (mnemonic to private key)
* Hash computation (transactions, data, scripts)
* Address extraction (stake addresses, key hashes)
* Time-based conversions (epoch and slot numbers)

## Quick Start

```tsx
import { resolveDataHash, resolvePaymentKeyHash, resolveEpochNo } from "@meshsdk/core";

// Compute a data hash
const hash = resolveDataHash("my-datum-value");

// Extract a key hash from an address
const keyHash = resolvePaymentKeyHash("addr_test1qpvx0sac...");

// Get the current epoch
const epoch = resolveEpochNo("preprod");
```

***

## resolvePrivateKey

Derive a private key from mnemonic phrases.

### Function Signature

```tsx
resolvePrivateKey(mnemonic: string[]): string
```

### Parameters

| Parameter  | Type       | Required | Description                |
| ---------- | ---------- | -------- | -------------------------- |
| `mnemonic` | `string[]` | Yes      | Array of 24 mnemonic words |

### Returns

| Type     | Description                           |
| -------- | ------------------------------------- |
| `string` | The derived private key in hex format |

### Example

```tsx
import { resolvePrivateKey } from "@meshsdk/core";

const mnemonic = [
  "solution", "solution", "solution", "solution",
  "solution", "solution", "solution", "solution",
  "solution", "solution", "solution", "solution",
  "solution", "solution", "solution", "solution",
  "solution", "solution", "solution", "solution",
  "solution", "solution", "solution", "solution",
];

const privateKey = resolvePrivateKey(mnemonic);
console.log("Private Key:", privateKey);
```

***

## resolveTxHash

Compute the transaction hash from a CBOR-encoded transaction.

### Function Signature

```tsx
resolveTxHash(txCbor: string): string
```

### Parameters

| Parameter | Type     | Required | Description                                             |
| --------- | -------- | -------- | ------------------------------------------------------- |
| `txCbor`  | `string` | Yes      | The transaction in CBOR hex format (signed or unsigned) |

### Returns

| Type     | Description                              |
| -------- | ---------------------------------------- |
| `string` | The transaction hash (64 hex characters) |

### Example

```tsx
import { resolveTxHash, MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder();

const unsignedTx = await txBuilder
  .txOut("addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr", [
    { unit: "lovelace", quantity: "1500000" },
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Get hash before signing
const hash1 = resolveTxHash(unsignedTx);
console.log("Transaction Hash:", hash1);

// Hash remains the same after signing
const signedTx = await wallet.signTx(unsignedTx);
const hash2 = resolveTxHash(signedTx);

console.log("Hashes match:", hash1 === hash2); // true
```

***

## resolveDataHash

Compute the hash of a datum value.

### Function Signature

```tsx
resolveDataHash(datum: any): string
```

### Parameters

| Parameter | Type  | Required | Description             |
| --------- | ----- | -------- | ----------------------- |
| `datum`   | `any` | Yes      | The datum value to hash |

### Returns

| Type     | Description                        |
| -------- | ---------------------------------- |
| `string` | The datum hash (64 hex characters) |

### Example

```tsx
import { resolveDataHash } from "@meshsdk/core";

// Simple string datum
const hash = resolveDataHash("supersecretdatum");
console.log("Datum Hash:", hash);

// Complex datum structure
const complexDatum = {
  constructor: 0,
  fields: [
    "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
    1000000,
  ],
};
const complexHash = resolveDataHash(complexDatum);
console.log("Complex Datum Hash:", complexHash);
```

***

## resolvePaymentKeyHash

Extract the payment key hash from a bech32 address.

### Function Signature

```tsx
resolvePaymentKeyHash(address: string): string
```

### Parameters

| Parameter | Type     | Required | Description              |
| --------- | -------- | -------- | ------------------------ |
| `address` | `string` | Yes      | A Cardano bech32 address |

### Returns

| Type     | Description                              |
| -------- | ---------------------------------------- |
| `string` | The payment key hash (56 hex characters) |

### Example

```tsx
import { resolvePaymentKeyHash, NativeScript } from "@meshsdk/core";

const address = "addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr";
const keyHash = resolvePaymentKeyHash(address);

// Use in a native script
const nativeScript: NativeScript = {
  type: "sig",
  keyHash: keyHash,
};

console.log("Key Hash:", keyHash);
```

***

## resolveNativeScriptHash

Compute the hash (policy ID) of a native script.

### Function Signature

```tsx
resolveNativeScriptHash(nativeScript: NativeScript): string
```

### Parameters

| Parameter      | Type           | Required | Description              |
| -------------- | -------------- | -------- | ------------------------ |
| `nativeScript` | `NativeScript` | Yes      | The native script object |

### Returns

| Type     | Description                                     |
| -------- | ----------------------------------------------- |
| `string` | The script hash / policy ID (56 hex characters) |

### Example

```tsx
import { resolveNativeScriptHash, resolvePaymentKeyHash, NativeScript } from "@meshsdk/core";

const keyHash = resolvePaymentKeyHash(
  "addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr"
);

const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    {
      type: "sig",
      keyHash: keyHash,
    },
  ],
};

const policyId = resolveNativeScriptHash(nativeScript);
console.log("Policy ID:", policyId);
```

***

## resolveScriptHash

Compute the hash of a script from its CBOR representation.

### Function Signature

```tsx
resolveScriptHash(scriptCbor: string): string
```

### Parameters

| Parameter    | Type     | Required | Description                   |
| ------------ | -------- | -------- | ----------------------------- |
| `scriptCbor` | `string` | Yes      | The script in CBOR hex format |

### Returns

| Type     | Description                         |
| -------- | ----------------------------------- |
| `string` | The script hash (56 hex characters) |

### Example

```tsx
import { resolveScriptHash } from "@meshsdk/core";

const scriptCbor = "8200581c5867c3b8e27840f556ac268b781578b14c5661fc63ee720dbeab663f";

const hash = resolveScriptHash(scriptCbor);
console.log("Script Hash:", hash);
```

***

## resolveRewardAddress

Convert a wallet address to its corresponding stake/reward address.

### Function Signature

```tsx
resolveRewardAddress(address: string): string
```

### Parameters

| Parameter | Type     | Required | Description                                  |
| --------- | -------- | -------- | -------------------------------------------- |
| `address` | `string` | Yes      | A Cardano base address with stake credential |

### Returns

| Type     | Description                               |
| -------- | ----------------------------------------- |
| `string` | The stake/reward address in bech32 format |

### Example

```tsx
import { resolveRewardAddress } from "@meshsdk/core";

const walletAddress = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";

const stakeAddress = resolveRewardAddress(walletAddress);
console.log("Stake Address:", stakeAddress);
// Output: stake_test1urw5s...
```

***

## resolveStakeKeyHash

Extract the stake key hash from a stake address.

### Function Signature

```tsx
resolveStakeKeyHash(stakeAddress: string): string
```

### Parameters

| Parameter      | Type     | Required | Description                      |
| -------------- | -------- | -------- | -------------------------------- |
| `stakeAddress` | `string` | Yes      | A stake address in bech32 format |

### Returns

| Type     | Description                            |
| -------- | -------------------------------------- |
| `string` | The stake key hash (56 hex characters) |

### Example

```tsx
import { resolveStakeKeyHash } from "@meshsdk/core";

const stakeAddress = "stake_test1uzw5mnt7g4xjgdqkfa80hrk7kdvds6sa4k0vvgjvlj7w8eskffj2n";

const stakeKeyHash = resolveStakeKeyHash(stakeAddress);
console.log("Stake Key Hash:", stakeKeyHash);
```

***

## resolveFingerprint

Compute the asset fingerprint (CIP-14) from a policy ID and asset name.

### Function Signature

```tsx
resolveFingerprint(policyId: string, assetName: string): string
```

### Parameters

| Parameter   | Type     | Required | Description                       |
| ----------- | -------- | -------- | --------------------------------- |
| `policyId`  | `string` | Yes      | The policy ID (56 hex characters) |
| `assetName` | `string` | Yes      | The asset name in hex format      |

### Returns

| Type     | Description                                     |
| -------- | ----------------------------------------------- |
| `string` | The asset fingerprint (starts with `asset1...`) |

### Example

```tsx
import { resolveFingerprint } from "@meshsdk/core";

const policyId = "426117329844ccb3b0ba877220ff06a5bdf21eab3fb33e2f3a3f8e69";
const assetName = "4d657368546f6b656e"; // "MeshToken" in hex

const fingerprint = resolveFingerprint(policyId, assetName);
console.log("Asset Fingerprint:", fingerprint);
// Output: asset1...
```

***

## resolveScriptHashDRepId

Convert a script hash to a DRep ID for governance.

### Function Signature

```tsx
resolveScriptHashDRepId(scriptHash: string): string
```

### Parameters

| Parameter    | Type     | Required | Description                         |
| ------------ | -------- | -------- | ----------------------------------- |
| `scriptHash` | `string` | Yes      | The script hash (56 hex characters) |

### Returns

| Type     | Description                  |
| -------- | ---------------------------- |
| `string` | The DRep ID in bech32 format |

### Example

```tsx
import { resolveScriptHashDRepId, resolveNativeScriptHash, NativeScript } from "@meshsdk/core";

const script: NativeScript = {
  type: "all",
  scripts: [
    {
      type: "sig",
      keyHash: "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
    },
  ],
};

const scriptHash = resolveNativeScriptHash(script);
const drepId = resolveScriptHashDRepId(scriptHash);
console.log("DRep ID:", drepId);
```

***

## resolveEpochNo

Get the epoch number for a network at a specific time.

### Function Signature

```tsx
resolveEpochNo(network: string, milliseconds?: number): number
```

### Parameters

| Parameter      | Type     | Required | Description                                                  |
| -------------- | -------- | -------- | ------------------------------------------------------------ |
| `network`      | `string` | Yes      | Network name: `"mainnet"`, `"preprod"`, or `"preview"`       |
| `milliseconds` | `number` | No       | Optional timestamp in milliseconds. Defaults to current time |

### Returns

| Type     | Description      |
| -------- | ---------------- |
| `number` | The epoch number |

### Example: Get Current Epoch

```tsx
import { resolveEpochNo } from "@meshsdk/core";

const currentEpoch = resolveEpochNo("preprod");
console.log("Current Epoch:", currentEpoch);
```

### Example: Get Future Epoch

```tsx
import { resolveEpochNo } from "@meshsdk/core";

// Calculate epoch one year from now
const oneYearFromNow = new Date();
oneYearFromNow.setFullYear(oneYearFromNow.getFullYear() + 1);

const futureEpoch = resolveEpochNo("preprod", oneYearFromNow.getTime());
console.log("Epoch in 1 year:", futureEpoch);
```

***

## resolveSlotNo

Get the slot number for a network at a specific time.

### Function Signature

```tsx
resolveSlotNo(network: string, milliseconds?: number): number
```

### Parameters

| Parameter      | Type     | Required | Description                                                  |
| -------------- | -------- | -------- | ------------------------------------------------------------ |
| `network`      | `string` | Yes      | Network name: `"mainnet"`, `"preprod"`, or `"preview"`       |
| `milliseconds` | `number` | No       | Optional timestamp in milliseconds. Defaults to current time |

### Returns

| Type     | Description     |
| -------- | --------------- |
| `number` | The slot number |

### Example: Get Current Slot

```tsx
import { resolveSlotNo } from "@meshsdk/core";

const currentSlot = resolveSlotNo("preprod");
console.log("Current Slot:", currentSlot);
```

### Example: Time-Locked Transaction

```tsx
import { resolveSlotNo, MeshTxBuilder } from "@meshsdk/core";

// Lock transaction until 1 hour from now
const oneHourFromNow = Date.now() + 60 * 60 * 1000;
const validFromSlot = resolveSlotNo("preprod", oneHourFromNow);

const txBuilder = new MeshTxBuilder();
await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .invalidBefore(validFromSlot)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Complete Example

This example demonstrates using multiple resolvers in a complete workflow:

```tsx
import {
  resolvePaymentKeyHash,
  resolveNativeScriptHash,
  resolveDataHash,
  resolveRewardAddress,
  resolveFingerprint,
  resolveEpochNo,
  resolveSlotNo,
  serializeNativeScript,
  NativeScript,
} from "@meshsdk/core";

// 1. Extract key hash from address
const walletAddress = "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9";
const keyHash = resolvePaymentKeyHash(walletAddress);
console.log("Payment Key Hash:", keyHash);

// 2. Create and hash a native script
const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    { type: "sig", keyHash: keyHash },
    { type: "after", slot: resolveSlotNo("preprod").toString() },
  ],
};

const policyId = resolveNativeScriptHash(nativeScript);
console.log("Policy ID:", policyId);

// 3. Serialize the script to get an address
const { address } = serializeNativeScript(nativeScript, 0);
console.log("Script Address:", address);

// 4. Get stake address
const stakeAddress = resolveRewardAddress(walletAddress);
console.log("Stake Address:", stakeAddress);

// 5. Compute asset fingerprint
const assetName = "4d657368546f6b656e";
const fingerprint = resolveFingerprint(policyId, assetName);
console.log("Asset Fingerprint:", fingerprint);

// 6. Hash some datum
const datumHash = resolveDataHash({ owner: keyHash, amount: 1000000 });
console.log("Datum Hash:", datumHash);

// 7. Get current epoch and slot
console.log("Current Epoch:", resolveEpochNo("preprod"));
console.log("Current Slot:", resolveSlotNo("preprod"));
```

***

## Troubleshooting

### resolvePrivateKey returns unexpected value

Ensure you provide exactly 24 valid BIP-39 mnemonic words in the correct order. The words must be from the standard BIP-39 English wordlist.

### resolveRewardAddress fails

The input address must be a base address that includes a stake credential. Enterprise addresses (without stake credentials) cannot be converted to reward addresses.

### Epoch/slot numbers seem incorrect

Verify you are using the correct network name (`"mainnet"`, `"preprod"`, or `"preview"`). Each network has different genesis parameters affecting epoch and slot calculations.

***

## Related

* [Serializers](/apis/utilities/serializers) - Encode data for on-chain use
* [Deserializers](/apis/utilities/deserializers) - Parse on-chain data
* [Blueprints](/apis/utilities/blueprints) - Work with parameterized scripts
* [Transaction Builder](/apis/txbuilder) - Build transactions using resolved hashes


# CBOR Serializers
URL: /apis/utilities/serializers

Encode Cardano scripts and data into CBOR or bech32 format

***

title: "CBOR Serializers"
description: "Encode Cardano scripts and data into CBOR or bech32 format"
-------------------------------------------------------------------------

Use serializer functions to encode Cardano data structures into formats suitable for on-chain storage or transmission. These utilities convert scripts into addresses and data objects into their serialized representations.

## Overview

Serialization is essential for smart contract development. It encodes data structures into formats that can be stored on-chain or transmitted across the network. MeshJS provides serializers for:

* Native scripts (multisig, time-locked)
* Plutus scripts (smart contracts)
* Address objects (payment and stake credentials)

## Quick Start

```tsx
import { serializePlutusScript, PlutusScript } from "@meshsdk/core";

const script: PlutusScript = {
  code: "5906f4010100...",
  version: "V2",
};

const address = serializePlutusScript(script);
```

***

## serializeNativeScript

Convert a native script into a bech32 address and script CBOR.

### Function Signature

```tsx
serializeNativeScript(
  nativeScript: NativeScript,
  networkId?: number,
  stakeCredentialHash?: string
): { address: string; scriptCbor: string }
```

### Parameters

| Parameter             | Type           | Required | Description                                                    |
| --------------------- | -------------- | -------- | -------------------------------------------------------------- |
| `nativeScript`        | `NativeScript` | Yes      | The native script object to serialize                          |
| `networkId`           | `number`       | No       | Network ID (`0` for testnet, `1` for mainnet). Defaults to `0` |
| `stakeCredentialHash` | `string`       | No       | Optional stake credential hash for the address                 |

### Returns

| Property     | Type     | Description               |
| ------------ | -------- | ------------------------- |
| `address`    | `string` | The bech32 script address |
| `scriptCbor` | `string` | The script in CBOR format |

### Example

```tsx
import {
  serializeNativeScript,
  deserializeAddress,
  NativeScript,
} from "@meshsdk/core";

// Get the public key hash from an address
const { pubKeyHash: keyHash } = deserializeAddress(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

// Create a time-locked multisig script
const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    {
      type: "before",
      slot: "99999999",
    },
    {
      type: "sig",
      keyHash: keyHash,
    },
  ],
};

// Serialize to get address and CBOR
const { address, scriptCbor } = serializeNativeScript(nativeScript);

console.log("Script Address:", address);
console.log("Script CBOR:", scriptCbor);
```

### Native Script Types

The `NativeScript` type supports these script types:

| Type      | Description                                 | Required Fields       |
| --------- | ------------------------------------------- | --------------------- |
| `sig`     | Requires a signature from a key             | `keyHash`             |
| `all`     | Requires all scripts to be satisfied        | `scripts`             |
| `any`     | Requires any one script to be satisfied     | `scripts`             |
| `atLeast` | Requires at least N scripts to be satisfied | `required`, `scripts` |
| `before`  | Valid before a slot                         | `slot`                |
| `after`   | Valid after a slot                          | `slot`                |

***

## serializePlutusScript

Convert a Plutus script into a bech32 address.

### Function Signature

```tsx
serializePlutusScript(
  plutusScript: PlutusScript,
  networkId?: number,
  stakeCredentialHash?: string
): string
```

### Parameters

| Parameter             | Type           | Required | Description                                                    |
| --------------------- | -------------- | -------- | -------------------------------------------------------------- |
| `plutusScript`        | `PlutusScript` | Yes      | The Plutus script object to serialize                          |
| `networkId`           | `number`       | No       | Network ID (`0` for testnet, `1` for mainnet). Defaults to `0` |
| `stakeCredentialHash` | `string`       | No       | Optional stake credential hash for the address                 |

### Returns

| Type     | Description               |
| -------- | ------------------------- |
| `string` | The bech32 script address |

### Example

```tsx
import { serializePlutusScript, PlutusScript } from "@meshsdk/core";

const plutusScript: PlutusScript = {
  code: "5906f4010100323232323232...", // Your compiled Plutus script
  version: "V2",
};

// Get the script address on testnet
const address = serializePlutusScript(plutusScript, 0);
console.log("Script Address:", address);

// Get the script address on mainnet with stake credential
const mainnetAddress = serializePlutusScript(
  plutusScript,
  1,
  "9e8a6e5fcbbb5b84deefc71d7cb6319a3da9cc3d19765efb303647ef"
);
console.log("Mainnet Address:", mainnetAddress);
```

### PlutusScript Type

```tsx
interface PlutusScript {
  code: string;    // The compiled script CBOR
  version: string; // "V1", "V2", or "V3"
}
```

***

## serializeAddressObj

Convert a Cardano data address object into a bech32 address string.

### Function Signature

```tsx
serializeAddressObj(
  address: PubKeyAddress | ScriptAddress,
  networkId?: number
): string
```

### Parameters

| Parameter   | Type                             | Required | Description                                                    |
| ----------- | -------------------------------- | -------- | -------------------------------------------------------------- |
| `address`   | `PubKeyAddress \| ScriptAddress` | Yes      | The address object in Cardano data format                      |
| `networkId` | `number`                         | No       | Network ID (`0` for testnet, `1` for mainnet). Defaults to `0` |

### Returns

| Type     | Description        |
| -------- | ------------------ |
| `string` | The bech32 address |

### Example

```tsx
import { pubKeyAddress, serializeAddressObj } from "@meshsdk/core";

// Create a public key address object
const address = pubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);

// Serialize to bech32 on mainnet
const bech32Address = serializeAddressObj(address, 1);
console.log("Bech32 Address:", bech32Address);
```

***

## pubKeyAddress

Create a public key address object for use with `serializeAddressObj`.

### Function Signature

```tsx
pubKeyAddress(
  bytes: string,
  stakeCredential?: string,
  isStakeScriptCredential?: boolean
): PubKeyAddress
```

### Parameters

| Parameter                 | Type      | Required | Description                                                   |
| ------------------------- | --------- | -------- | ------------------------------------------------------------- |
| `bytes`                   | `string`  | Yes      | The payment key hash (56 hex characters)                      |
| `stakeCredential`         | `string`  | No       | The stake credential hash                                     |
| `isStakeScriptCredential` | `boolean` | No       | Whether the stake credential is a script. Defaults to `false` |

### Returns

| Type            | Description                               |
| --------------- | ----------------------------------------- |
| `PubKeyAddress` | The address object in Cardano data format |

### Example

```tsx
import { pubKeyAddress, serializeAddressObj } from "@meshsdk/core";

// Enterprise address (no stake key)
const enterpriseAddress = pubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6"
);

// Base address (with stake key)
const baseAddress = pubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);

console.log(serializeAddressObj(enterpriseAddress, 0));
console.log(serializeAddressObj(baseAddress, 0));
```

***

## scriptAddress

Create a script address object for use with `serializeAddressObj`.

### Function Signature

```tsx
scriptAddress(
  bytes: string,
  stakeCredential?: string,
  isStakeScriptCredential?: boolean
): ScriptAddress
```

### Parameters

| Parameter                 | Type      | Required | Description                                                   |
| ------------------------- | --------- | -------- | ------------------------------------------------------------- |
| `bytes`                   | `string`  | Yes      | The script hash (56 hex characters)                           |
| `stakeCredential`         | `string`  | No       | The stake credential hash                                     |
| `isStakeScriptCredential` | `boolean` | No       | Whether the stake credential is a script. Defaults to `false` |

### Returns

| Type            | Description                               |
| --------------- | ----------------------------------------- |
| `ScriptAddress` | The address object in Cardano data format |

### Example

```tsx
import { scriptAddress, serializeAddressObj } from "@meshsdk/core";

// Script address with stake credential
const address = scriptAddress(
  "5867c3b8e27840f556ac268b781578b14c5661fc63ee720dbeab663f",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);

const bech32 = serializeAddressObj(address, 0);
console.log("Script Address:", bech32);
```

***

## Complete Example

This example demonstrates a complete workflow for serializing different script types:

```tsx
import {
  serializeNativeScript,
  serializePlutusScript,
  pubKeyAddress,
  scriptAddress,
  serializeAddressObj,
  deserializeAddress,
  NativeScript,
  PlutusScript,
} from "@meshsdk/core";

// 1. Serialize a Native Script
const { pubKeyHash } = deserializeAddress(
  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
);

const nativeScript: NativeScript = {
  type: "all",
  scripts: [
    { type: "sig", keyHash: pubKeyHash },
    { type: "after", slot: "1000000" },
  ],
};

const { address: nativeAddress, scriptCbor } = serializeNativeScript(nativeScript, 0);
console.log("Native Script Address:", nativeAddress);

// 2. Serialize a Plutus Script
const plutusScript: PlutusScript = {
  code: "5906f4010100...",
  version: "V2",
};

const plutusAddress = serializePlutusScript(plutusScript, 0);
console.log("Plutus Script Address:", plutusAddress);

// 3. Serialize Address Objects
const pkAddress = pubKeyAddress(
  "aa048e4cc8a1e67e1d97ffbd4be614388014cbc2b2451527202943b6",
  "9d4dcd7e454d2434164f4efb8edeb358d86a1dad9ec6224cfcbce3e6"
);
console.log("Public Key Address:", serializeAddressObj(pkAddress, 1));

const scAddress = scriptAddress(
  "5867c3b8e27840f556ac268b781578b14c5661fc63ee720dbeab663f"
);
console.log("Script Address:", serializeAddressObj(scAddress, 0));
```

***

## Troubleshooting

### Address returns wrong network prefix

Verify you are passing the correct `networkId` parameter. Use `0` for testnet (`addr_test1...`) and `1` for mainnet (`addr1...`).

### Invalid script CBOR error

Ensure your Plutus script code is valid CBOR hex. The code should be the raw compiled output from your Plutus or Aiken compiler.

### Native script serialization fails

Check that all required fields are present for each script type. For example, `sig` scripts require a `keyHash`, and `atLeast` scripts require both `required` and `scripts` fields.

***

## Related

* [Deserializers](/apis/utilities/deserializers) - Parse serialized data back into objects
* [Resolvers](/apis/utilities/resolvers) - Convert between hash formats
* [Blueprints](/apis/utilities/blueprints) - Work with parameterized scripts


# Browser Wallet (CIP-30)
URL: /apis/wallets/browserwallet

Connect to CIP-30 compatible browser wallets like Eternl, Nami, Lace, and Flint.

***

title: "Browser Wallet (CIP-30)"
description: "Connect to CIP-30 compatible browser wallets like Eternl, Nami, Lace, and Flint."
-----------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Overview

`MeshCardanoBrowserWallet` enables your dApp to connect with users' browser extension wallets following the [CIP-30](https://cips.cardano.org/cip/CIP-30) standard. This provides a consistent interface for wallet discovery, connection, transaction signing, and data queries across all compatible wallets.

**Supported wallets include:** Eternl, Nami, Lace, Flint, Typhon, GeroWallet, and any CIP-30 compliant wallet.

## Quick Start

```tsx
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

// 1. Get installed wallets on user's device
const wallets = MeshCardanoBrowserWallet.getInstalledWallets();

// 2. Connect to a wallet
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// 3. Get wallet balance
const balance = await wallet.getBalanceMesh();

// 4. Get wallet address
const address = await wallet.getChangeAddressBech32();
```

## Wallet Discovery

### getInstalledWallets

Retrieve all CIP-30 compatible wallets installed on the user's device.

```tsx
const wallets = MeshCardanoBrowserWallet.getInstalledWallets();
```

**Returns:**

```tsx
[
  {
    id: "eternl",
    name: "Eternl",
    icon: "data:image/png;base64,...",
    version: "0.1.0"
  },
  {
    id: "nami",
    name: "Nami",
    icon: "data:image/png;base64,...",
    version: "3.0.0"
  }
]
```

| Property  | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `id`      | `string` | Wallet identifier used for connection     |
| `name`    | `string` | Display name of the wallet                |
| `icon`    | `string` | Base64-encoded wallet icon for UI display |
| `version` | `string` | Wallet extension version                  |

## Connection

### enable

Connect to a specific wallet. This prompts the user to grant permission.

```tsx
const wallet = await MeshCardanoBrowserWallet.enable("eternl");
```

**With CIP extensions:**

```tsx
// Enable CIP-95 (governance) support
const wallet = await MeshCardanoBrowserWallet.enable("eternl", [{ cip: 95 }]);
```

| Parameter    | Type          | Required | Description                                      |
| ------------ | ------------- | -------- | ------------------------------------------------ |
| `walletName` | `string`      | Yes      | Wallet identifier from `getInstalledWallets()`   |
| `extensions` | `Extension[]` | No       | CIP extensions to enable (e.g., `[{ cip: 95 }]`) |

## Account Information

### getNetworkId

Get the network the wallet is connected to.

```tsx
const networkId = await wallet.getNetworkId();
// 0 = Testnet, 1 = Mainnet
```

***

### getChangeAddressBech32

Get the address where transaction change should be sent.

```tsx
const changeAddress = await wallet.getChangeAddressBech32();
// "addr_test1qz..."
```

***

### getUsedAddressesBech32

Get all addresses that have received funds.

```tsx
const usedAddresses = await wallet.getUsedAddressesBech32();
// ["addr_test1qz...", "addr_test1qr..."]
```

***

### getUnusedAddressesBech32

Get addresses that have never received funds.

```tsx
const unusedAddresses = await wallet.getUnusedAddressesBech32();
```

***

### getRewardAddressesBech32

Get stake addresses associated with the wallet.

```tsx
const stakeAddresses = await wallet.getRewardAddressesBech32();
// ["stake_test1uz..."]
```

## Balance & Assets

### getBalanceMesh

Get the complete balance including ADA and all native assets.

```tsx
const balance = await wallet.getBalanceMesh();
```

**Returns:**

```tsx
[
  { unit: "lovelace", quantity: "796105407" },
  { unit: "d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e", quantity: "1" }
]
```

## UTXOs & Collateral

### getUtxosMesh

Get all unspent transaction outputs controlled by the wallet.

```tsx
const utxos = await wallet.getUtxosMesh();
```

**Returns:**

```tsx
[
  {
    input: {
      txHash: "16dcbb1f93b4f9d5e...",
      outputIndex: 0
    },
    output: {
      address: "addr_test1qz...",
      amount: [
        { unit: "lovelace", quantity: "1314550" },
        { unit: "d9312da562da182b...", quantity: "1" }
      ]
    }
  }
]
```

***

### getCollateralMesh

Get UTXOs suitable for use as collateral in Plutus script transactions.

```tsx
const collateral = await wallet.getCollateralMesh();
```

Collateral UTXOs must contain only ADA (no native assets) and meet minimum value requirements.

## Transaction Operations

### signTx

Sign a transaction with the wallet's private keys. Returns a witness set in CBOR hex format.

```tsx
// Single signature
const witnessSet = await wallet.signTx(unsignedTx, false);

// Partial signing (for multi-sig transactions)
const witnessSet = await wallet.signTx(unsignedTx, true);
```

| Parameter     | Type      | Required | Description                                 |
| ------------- | --------- | -------- | ------------------------------------------- |
| `tx`          | `string`  | Yes      | Unsigned transaction CBOR hex               |
| `partialSign` | `boolean` | Yes      | Set `true` for multi-signature transactions |

***

### signTxReturnFullTx

Sign a transaction and return the full signed transaction with witnesses merged.

```tsx
const signedTx = await wallet.signTxReturnFullTx(unsignedTx, false);
```

This is useful when you need the complete transaction CBOR rather than just the witness set.

***

### submitTx

Submit a signed transaction to the network.

```tsx
const txHash = await wallet.submitTx(signedTx);
// "f4ec9833a3bf95403d395f699bc564938f3419537e7fb5084425d3838a4b6159"
```

***

### signData

Sign arbitrary data using CIP-8 message signing. Useful for authentication and proof of wallet ownership.

```tsx
const address = await wallet.getChangeAddressBech32();
const signature = await wallet.signData(address, "Hello, Mesh!");
```

**Returns:**

```tsx
{
  signature: "845846a2012...",
  key: "a4010103272006215..."
}
```

See <Link href="/guides/prove-wallet-ownership">Prove Wallet Ownership</Link> to verify signatures server-side.

## Complete Example

```tsx
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

// Setup provider
const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// Check installed wallets
const installedWallets = MeshCardanoBrowserWallet.getInstalledWallets();
console.log("Installed wallets:", installedWallets.map(w => w.name));

// Connect to wallet
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Check connection
const networkId = await wallet.getNetworkId();
console.log("Connected to:", networkId === 0 ? "Testnet" : "Mainnet");

// Get wallet info
const address = await wallet.getChangeAddressBech32();
const balance = await wallet.getBalanceMesh();
const lovelace = balance.find(a => a.unit === 'lovelace')?.quantity || '0';
console.log(`Address: ${address}`);
console.log(`Balance: ${Number(lovelace) / 1_000_000} ADA`);

// Build and send transaction
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const utxos = await wallet.getUtxosMesh();

const unsignedTx = await txBuilder
  .txOut("addr_test1qz...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(address)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTxReturnFullTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log(`Transaction submitted: ${txHash}`);
```

## React Integration

For React applications, use the `@meshsdk/react` package for built-in wallet components and hooks.

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

function App() {
  const { connected, wallet } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Connected!</p>}
    </div>
  );
}
```

See <Link href="/react/getting-started">React Getting Started</Link> for full integration details.

## API Reference

| Method                                | Returns                             | Description                          |
| ------------------------------------- | ----------------------------------- | ------------------------------------ |
| `getInstalledWallets()`               | `Wallet[]`                          | Static - Get installed wallets       |
| `enable(walletName, extensions?)`     | `Promise<MeshCardanoBrowserWallet>` | Static - Connect to wallet           |
| `getNetworkId()`                      | `Promise<number>`                   | Network ID (0=testnet, 1=mainnet)    |
| `getUtxos()`                          | `Promise<string[]>`                 | UTXOs in CBOR hex format             |
| `getUtxosMesh()`                      | `Promise<UTxO[]>`                   | UTXOs in Mesh format                 |
| `getCollateral()`                     | `Promise<string[]>`                 | Collateral UTXOs in CBOR hex format  |
| `getCollateralMesh()`                 | `Promise<UTxO[]>`                   | Collateral UTXOs in Mesh format      |
| `getBalance()`                        | `Promise<string>`                   | Balance in CBOR hex format           |
| `getBalanceMesh()`                    | `Promise<Asset[]>`                  | Balance as Asset array               |
| `getUsedAddresses()`                  | `Promise<string[]>`                 | Used addresses in hex format         |
| `getUsedAddressesBech32()`            | `Promise<string[]>`                 | Used addresses in Bech32             |
| `getUnusedAddresses()`                | `Promise<string[]>`                 | Unused addresses in hex format       |
| `getUnusedAddressesBech32()`          | `Promise<string[]>`                 | Unused addresses in Bech32           |
| `getChangeAddress()`                  | `Promise<string>`                   | Change address in hex format         |
| `getChangeAddressBech32()`            | `Promise<string>`                   | Change address in Bech32             |
| `getRewardAddresses()`                | `Promise<string[]>`                 | Reward addresses in hex format       |
| `getRewardAddressesBech32()`          | `Promise<string[]>`                 | Reward addresses in Bech32           |
| `signTx(tx, partialSign)`             | `Promise<string>`                   | Sign transaction, return witness set |
| `signTxReturnFullTx(tx, partialSign)` | `Promise<string>`                   | Sign and return full transaction     |
| `signData(address, data)`             | `Promise<DataSignature>`            | Sign arbitrary data                  |
| `submitTx(tx)`                        | `Promise<string>`                   | Submit transaction                   |

## Troubleshooting

### Wallet not appearing in getInstalledWallets()

* Ensure the wallet extension is installed and enabled
* Refresh the page after installing a new wallet
* Check that the wallet is unlocked

### "User rejected the request" error

The user declined the connection or signing prompt. Handle this gracefully:

```tsx
try {
  const wallet = await MeshCardanoBrowserWallet.enable("eternl");
} catch (error) {
  if (error.message.includes("rejected")) {
    console.log("User declined connection");
  }
}
```

### "Account not set" error

The wallet is locked or no account is selected. Prompt the user to unlock their wallet.

### Transaction signing fails

* Ensure UTXOs are up to date (call `getUtxosMesh()` before building)
* Verify the transaction has sufficient funds for outputs + fees
* For Plutus transactions, ensure collateral is set

### Multi-signature transaction issues

* Set `partialSign: true` when calling `signTx()`
* Each signer must sign the transaction in sequence
* The final signer can use `partialSign: false`

## References

* [CIP-30: Cardano dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-0030) - The standard implemented by this API for wallet-dApp communication
* [CIP-95: Web-Wallet Bridge for Conway Governance](https://cips.cardano.org/cip/CIP-0095) - Extension for governance features (DRep keys, Conway-era certificates)
* [CIP-8: Message Signing](https://cips.cardano.org/cip/CIP-0008) - The standard used by `signData` for arbitrary data signing
* [Cardano Developer Portal](https://developers.cardano.org) - Official Cardano development resources

## Related

* <Link href="/apis/wallets/meshwallet">Headless Wallet</Link> - Server-side wallet for backend applications
* <Link href="/react/getting-started">React Integration</Link> - UI components and hooks
* <Link href="/guides/prove-wallet-ownership">Prove Wallet Ownership</Link> - Authentication with wallet signatures
* <Link href="/apis/txbuilder/basics">Transaction Builder</Link> - Build transactions to sign


# Cardano Wallet Integration
URL: /apis/wallets

Connect to browser wallets and create server-side wallets for Cardano dApp development.

***

title: "Cardano Wallet Integration"
description: "Connect to browser wallets and create server-side wallets for Cardano dApp development."
icon: WalletIcon
full: true
----------

import {linksWallets} from "@/data/links-wallets";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

## Overview

Mesh provides wallet classes for different use cases:

| Wallet Class                                            | Use Case                                      | Environment        |
| ------------------------------------------------------- | --------------------------------------------- | ------------------ |
| [CardanoBrowserWallet](/apis/wallets/browserwallet)     | Connect to user's wallet extension (CIP-30)   | Frontend (browser) |
| [MeshCardanoBrowserWallet](/apis/wallets/browserwallet) | Browser wallet with Mesh convenience methods  | Frontend (browser) |
| [CardanoHeadlessWallet](/apis/wallets/meshwallet)       | Programmatic wallet control (low-level)       | Backend (Node.js)  |
| [MeshCardanoHeadlessWallet](/apis/wallets/meshwallet)   | Headless wallet with Mesh convenience methods | Backend (Node.js)  |

## Quick Start

### Browser Wallet (Frontend)

Connect to CIP-30 compatible wallets like Eternl, Nami, and Lace:

```tsx
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

// Get installed wallets
const wallets = MeshCardanoBrowserWallet.getInstalledWallets();

// Connect to a wallet
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Get balance (Mesh format)
const balance = await wallet.getBalanceMesh();
console.log(`Balance: ${balance.find(a => a.unit === 'lovelace')?.quantity}`);

// Get address (Bech32 format)
const address = await wallet.getChangeAddressBech32();
```

### Headless Wallet (Backend)

Create wallets programmatically for server-side applications:

```tsx
import { MeshCardanoHeadlessWallet } from "@meshsdk/wallet";
import { BlockfrostProvider } from "@meshsdk/core";
import { AddressType } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("<YOUR_API_KEY>");

// Create from mnemonic
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // 0 = testnet, 1 = mainnet
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "24", "word", "mnemonic", "phrase", "..."],
});

// Or create from Bip32 root key
const wallet = await MeshCardanoHeadlessWallet.fromBip32Root({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  bech32: "xprv1...",
});
```

## Choosing a Wallet Class

**Use Browser Wallet classes when:**

* Building frontend dApps
* Users need to connect their own wallets
* Transactions require user approval
* Working with CIP-30 features

**Use Headless Wallet classes when:**

* Running backend services
* Automating transactions
* Managing treasury wallets
* Building bots or scripts

**Use Mesh variants (`MeshCardanoBrowserWallet`, `MeshCardanoHeadlessWallet`) when:**

* You want UTxOs, balances, and addresses in Mesh-compatible formats
* You prefer Bech32 addresses directly
* You need convenience methods like `signTxReturnFullTx()`

**Use base variants (`CardanoBrowserWallet`, `CardanoHeadlessWallet`) when:**

* You want raw CIP-30 compliant CBOR hex responses
* You need maximum compatibility with the CIP-30 standard

## Common Operations

Both wallet types share similar APIs implementing the `ICardanoWallet` interface:

```tsx
// Get UTXOs (CBOR hex format)
const utxos = await wallet.getUtxos();

// Get change address (hex format)
const address = await wallet.getChangeAddress();

// Sign transaction
const signedTx = await wallet.signTx(unsignedTx, partialSign);

// Submit transaction
const txHash = await wallet.submitTx(signedTx);

// Get balance (CBOR hex format)
const balance = await wallet.getBalance();
```

Mesh wallet variants add convenience methods:

```tsx
// Get UTXOs in Mesh format
const utxos = await wallet.getUtxosMesh();

// Get change address in Bech32
const address = await wallet.getChangeAddressBech32();

// Get balance as Asset array
const balance = await wallet.getBalanceMesh();

// Sign and return full transaction (with witnesses merged)
const signedTx = await wallet.signTxReturnFullTx(unsignedTx);
```

## React Integration

For React applications, use `@meshsdk/react` for built-in components and hooks:

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

function App() {
  const { connected, wallet } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Balance: {wallet.getLovelace()}</p>}
    </div>
  );
}
```

See [React Getting Started](/react/getting-started) for full integration details.

## Available Wallet APIs

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksWallets.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Related

* [React Integration](/react/getting-started) - Wallet components and hooks
* [Transaction Builder](/apis/txbuilder/basics) - Build transactions to sign
* [Prove Wallet Ownership](/guides/prove-wallet-ownership) - Authenticate users with signatures


# Headless Wallet (Server-Side)
URL: /apis/wallets/meshwallet

Build server-side wallet functionality for minting, multi-signature transactions, and automated blockchain operations.

***

title: "Headless Wallet (Server-Side)"
description: "Build server-side wallet functionality for minting, multi-signature transactions, and automated blockchain operations."
-------------------------------------------------------------------------------------------------------------------------------------

`MeshCardanoHeadlessWallet` provides programmatic access to wallet functionality without requiring a browser extension. Use it for minting scripts, automated transactions, multi-signature coordination, and any scenario where your application needs to sign transactions directly.

## Installation

```bash
npm install @meshsdk/wallet @meshsdk/core
```

## Quick Start

```tsx
import { MeshCardanoHeadlessWallet, AddressType } from '@meshsdk/wallet';
import { MaestroProvider } from '@meshsdk/core';

// 1. Set up a provider
const provider = new MaestroProvider({
  network: 'Preprod',
  apiKey: '<Your-API-Key>'
});

// 2. Create wallet from mnemonic
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // 0: testnet, 1: mainnet
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ['solution', 'solution', '...'] // 24 words
});

// 3. Use the wallet
const address = await wallet.getChangeAddressBech32();
const balance = await wallet.getBalanceMesh();
```

## Initialize Wallet

Create a headless wallet instance using one of the factory methods. The wallet requires a fetcher for querying blockchain data and optionally a submitter for transaction submission.

### Configure a Provider

Choose a provider based on your needs:

<Tabs items={["Maestro", "Blockfrost", "Koios", "UTxORPC"]}>
  <Tab value="Maestro">
    ```tsx
    import { MaestroProvider } from '@meshsdk/core';

    const provider = new MaestroProvider({
      network: 'Preprod',
      apiKey: '<Your-API-Key>',
      turboSubmit: false
    });
    ```
  </Tab>

  <Tab value="Blockfrost">
    ```tsx
    import { BlockfrostProvider } from '@meshsdk/core';

    const provider = new BlockfrostProvider('<BLOCKFROST_API_KEY>');
    ```
  </Tab>

  <Tab value="Koios">
    ```tsx
    import { KoiosProvider } from '@meshsdk/core';

    const provider = new KoiosProvider('<api|preview|preprod|guild>', '<token>');
    ```
  </Tab>

  <Tab value="UTxORPC">
    ```tsx
    import { U5CProvider } from "@meshsdk/core";

    const provider = new U5CProvider({
      url: "http://localhost:5005",
      headers: { "dmtr-api-key": "<api-key>" }
    });
    ```
  </Tab>
</Tabs>

### Address Types

The wallet requires specifying an address type:

| Address Type             | Description                   | Use Case                         |
| ------------------------ | ----------------------------- | -------------------------------- |
| `AddressType.Base`       | Includes staking capabilities | Standard wallets with staking    |
| `AddressType.Enterprise` | No staking component          | Script addresses, simple wallets |

```tsx
import { AddressType } from '@meshsdk/wallet';

// Base address (with staking)
walletAddressType: AddressType.Base

// Enterprise address (no staking)
walletAddressType: AddressType.Enterprise
```

### Factory Methods

#### fromMnemonic

The most common initialization method using a BIP39 recovery phrase:

```tsx
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // 0: testnet, 1: mainnet
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: [
    "solution", "solution", "solution", "solution",
    "solution", "solution", "solution", "solution",
    "solution", "solution", "solution", "solution",
    "solution", "solution", "solution", "solution",
    "solution", "solution", "solution", "solution",
    "solution", "solution", "solution", "solution"
  ],
  password: undefined // Optional passphrase
});
```

#### fromBip32Root

Initialize with a root private key in bech32 format:

```tsx
const wallet = await MeshCardanoHeadlessWallet.fromBip32Root({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  bech32: 'xprv1cqa46gk29plgkg98upclnjv5t425fcpl4rgf9mq2txdxuga7jfq...'
});
```

#### fromBip32RootHex

Initialize with a root private key in hex format:

```tsx
const wallet = await MeshCardanoHeadlessWallet.fromBip32RootHex({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  hex: '5820aaca553a7b95b38b5d9b82a5daa7a27ac8e34f3cf27152a978f4576520dd6503'
});
```

#### fromCredentialSources

Initialize with explicit credential sources for advanced use cases:

```tsx
const wallet = await MeshCardanoHeadlessWallet.fromCredentialSources({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  paymentCredentialSource: { /* credential source */ },
  stakeCredentialSource: { /* optional stake credential */ },
  drepCredentialSource: { /* optional drep credential */ }
});
```

## Query Wallet Data

### getBalanceMesh

Retrieve all assets in the wallet:

```tsx
const balance = await wallet.getBalanceMesh();
```

**Response:**

```tsx
[
  { "unit": "lovelace", "quantity": "796105407" },
  { "unit": "9c8e9da7f81e3ca90485f32ebefc98137c8ac260a072a00c4aaf142d4d657368546f6b656e", "quantity": "2" }
]
```

### getUtxosMesh

List all unspent transaction outputs:

```tsx
const utxos = await wallet.getUtxosMesh();
```

**Response:**

```tsx
[
  {
    "input": {
      "outputIndex": 0,
      "txHash": "16dcbb1f93b4f9d5e...9106c7b121463c210ba"
    },
    "output": {
      "address": "addr_test1qzag7whju08xwrq...z0fr8c3grjmysgaw9y8",
      "amount": [
        { "unit": "lovelace", "quantity": "1314550" },
        { "unit": "f05c91a850...3d824d657368546f6b656e3032", "quantity": "1" }
      ]
    }
  }
]
```

## Address Management

### getChangeAddressBech32

The address where transaction change is sent:

```tsx
const changeAddress = await wallet.getChangeAddressBech32();
```

### getUsedAddressesBech32

Addresses that have received transactions:

```tsx
const usedAddresses = await wallet.getUsedAddressesBech32();
```

### getUnusedAddressesBech32

Fresh addresses for new transactions:

```tsx
const unusedAddresses = await wallet.getUnusedAddressesBech32();
```

### getRewardAddressesBech32

Stake addresses for staking rewards:

```tsx
const rewardAddresses = await wallet.getRewardAddressesBech32();
// ["stake_test1uzx0ksy9f4qnj2mzfdncqyjy84sszh64w43853nug5pedjgytgke9"]
```

### getNetworkId

Check if the wallet is on testnet or mainnet:

```tsx
const networkId = await wallet.getNetworkId();
// 0 = Testnet, 1 = Mainnet
```

## Transaction Operations

### signTx

Sign an unsigned transaction. Returns a witness set in CBOR hex format.

```tsx
const witnessSet = await wallet.signTx(unsignedTx, false);

// For partial signing (multi-sig scenarios)
const witnessSet = await wallet.signTx(unsignedTx, true);
```

> **Note:** This method requires a fetcher to resolve input UTxOs for determining required signers.

### signTxReturnFullTx

Sign a transaction and return the full signed transaction with witnesses merged:

```tsx
const signedTx = await wallet.signTxReturnFullTx(unsignedTx, false);
```

### submitTx

Submit a signed transaction to the network:

```tsx
const txHash = await wallet.submitTx(signedTx);
console.log(`Transaction submitted: ${txHash}`);
```

> **Note:** Requires a submitter to be configured.

### signData

Sign arbitrary data for authentication or verification:

```tsx
const address = await wallet.getChangeAddressBech32();
const signature = await wallet.signData(address, 'mesh');
```

**Response:**

```tsx
{
  "signature": "845846a2012...f9119a18e8977d436385cecb08",
  "key": "a4010103272006215...b81a7f6ed4fa29cc7b33186c"
}
```

Verify signatures using the [wallet ownership guide](https://meshjs.dev/guides/prove-wallet-ownership#server-verify-signature).

## Collateral Management

### getCollateralMesh

Retrieve UTXOs suitable for Plutus script collateral:

```tsx
const collateral = await wallet.getCollateralMesh();
```

The wallet automatically selects the smallest pure ADA UTxO that is at least 5 ADA.

## fetchAccountUtxos

Fetch all UTxOs for the wallet's addresses directly:

```tsx
const utxos = await wallet.fetchAccountUtxos();
```

This is useful for getting UTxOs in the native Mesh format without CBOR conversion.

## API Reference

| Method                                | Returns                              | Description                         |
| ------------------------------------- | ------------------------------------ | ----------------------------------- |
| `create(config)`                      | `Promise<MeshCardanoHeadlessWallet>` | Static - Create from config         |
| `fromMnemonic(config)`                | `Promise<MeshCardanoHeadlessWallet>` | Static - Create from mnemonic       |
| `fromBip32Root(config)`               | `Promise<MeshCardanoHeadlessWallet>` | Static - Create from bech32 key     |
| `fromBip32RootHex(config)`            | `Promise<MeshCardanoHeadlessWallet>` | Static - Create from hex key        |
| `fromCredentialSources(config)`       | `Promise<MeshCardanoHeadlessWallet>` | Static - Create from credentials    |
| `getNetworkId()`                      | `Promise<number>`                    | Network ID (0=testnet, 1=mainnet)   |
| `getUtxos()`                          | `Promise<string[]>`                  | UTXOs in CBOR hex format            |
| `getUtxosMesh()`                      | `Promise<UTxO[]>`                    | UTXOs in Mesh format                |
| `getCollateral()`                     | `Promise<string[]>`                  | Collateral UTXOs in CBOR hex format |
| `getCollateralMesh()`                 | `Promise<UTxO[]>`                    | Collateral UTXOs in Mesh format     |
| `getBalance()`                        | `Promise<string>`                    | Balance in CBOR hex format          |
| `getBalanceMesh()`                    | `Promise<Asset[]>`                   | Balance as Asset array              |
| `getUsedAddresses()`                  | `Promise<string[]>`                  | Used addresses in hex format        |
| `getUsedAddressesBech32()`            | `Promise<string[]>`                  | Used addresses in Bech32            |
| `getUnusedAddresses()`                | `Promise<string[]>`                  | Unused addresses in hex format      |
| `getUnusedAddressesBech32()`          | `Promise<string[]>`                  | Unused addresses in Bech32          |
| `getChangeAddress()`                  | `Promise<string>`                    | Change address in hex format        |
| `getChangeAddressBech32()`            | `Promise<string>`                    | Change address in Bech32            |
| `getRewardAddresses()`                | `Promise<string[]>`                  | Reward addresses in hex format      |
| `getRewardAddressesBech32()`          | `Promise<string[]>`                  | Reward addresses in Bech32          |
| `signTx(tx, partialSign)`             | `Promise<string>`                    | Sign transaction                    |
| `signTxReturnFullTx(tx, partialSign)` | `Promise<string>`                    | Sign and return full transaction    |
| `signData(address, data)`             | `Promise<DataSignature>`             | Sign arbitrary data                 |
| `submitTx(tx)`                        | `Promise<string>`                    | Submit transaction                  |
| `fetchAccountUtxos()`                 | `Promise<UTxO[]>`                    | Fetch UTxOs directly                |

## Important Notes

### Stateless Design

The headless wallet is stateless and does not track:

* Which UTxOs are set as collateral (overlap possible between `getUtxosMesh()` and `getCollateralMesh()`)
* Which addresses have been previously used
* Address derivation history

This makes it effective as a **single-address wallet**.

### Fetcher Requirement

Many operations require a fetcher:

* `getUtxosMesh()`
* `getBalanceMesh()`
* `getCollateralMesh()`
* `signTx()` - needs to resolve input UTxOs for determining required signers

### Submitter Requirement

The `submitTx()` method requires a submitter to be configured.

## Migration from MeshWallet

If you're migrating from the old `MeshWallet` class:

```tsx
// Old API
import { MeshWallet } from "@meshsdk/core";
const wallet = new MeshWallet({
  networkId: 0,
  fetcher: provider,
  submitter: provider,
  key: { type: "mnemonic", words: [...] }
});
await wallet.init();

// New API
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: [...]
});
// No init() needed
```

Key changes:

* Import from `@meshsdk/wallet` instead of `@meshsdk/core`
* Use factory methods instead of constructor
* Specify `walletAddressType` (Base or Enterprise)
* No `init()` call needed

## Related Resources

* [Browser Wallet](/apis/wallets/browserwallet) - Connect to user wallets
* [Transaction Builder](/apis/txbuilder) - Build transactions to sign
* [Providers](/providers) - Configure blockchain data providers
* [Prove Wallet Ownership](/guides/prove-wallet-ownership) - Verify signatures


# Available Contracts
URL: /midnight/midnight-contracts-wizard/contracts

Explore the zero-knowledge smart contract templates in the Midnight Contracts Wizard

***

title: "Available Contracts"
description: "Explore the zero-knowledge smart contract templates in the Midnight Contracts Wizard"
---------------------------------------------------------------------------------------------------

The Midnight Contracts Wizard includes five production-ready smart contract templates. Each template provides complete functionality with privacy-preserving zero-knowledge circuits built in.

## Contract overview

| Contract     | ZK Circuits | Primary use case                        |
| ------------ | ----------- | --------------------------------------- |
| Tokenization | 7           | Asset tokenization, private investments |
| Staking      | 8           | Rewards, governance participation       |
| Identity     | 1           | Credential verification, access control |
| Oracle       | 7           | External data feeds, price oracles      |
| Lending      | 7           | DeFi protocols, collateralized loans    |

***

## Tokenization Contract

**7 ZK Circuits**

A complete asset tokenization system with zero-knowledge privacy for investments and ownership tracking.

### Features

| Feature               | Description                                      |
| --------------------- | ------------------------------------------------ |
| Private minting       | Create tokens without revealing amounts          |
| Confidential balances | Hide holder balances from public view            |
| Private transfers     | Move tokens without exposing transaction details |
| Investment tracking   | Track investments with ZK proofs                 |

### Use cases

* **Real estate tokenization** - Fractional property ownership with private holdings
* **Securities issuance** - Confidential cap table management
* **Private equity** - Track investments without public disclosure
* **Fundraising** - Accept contributions with privacy guarantees

### Example usage

```typescript
import { TokenizationContract } from './managed/tokenization';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const contract = new TokenizationContract({
  name: "Property Token",
  symbol: "PROP",
  totalSupply: 1000000
});

const api = await MidnightSetupAPI.deployContract(providers, contract);
```

***

## Staking Contract

**8 ZK Circuits**

A privacy-focused staking system with configurable rewards and lock periods.

### Features

| Feature               | Description                              |
| --------------------- | ---------------------------------------- |
| Private stake amounts | Hide how much each user stakes           |
| Confidential rewards  | Distribute rewards privately             |
| Flexible lock periods | Configure custom staking durations       |
| Slashing mechanisms   | Penalize bad actors with ZK verification |

### Use cases

* **Network validation** - Stake to participate in consensus
* **Governance** - Voting power based on private stake
* **Yield generation** - Earn rewards on locked assets
* **Long-term incentives** - Reward committed participants

### Example usage

```typescript
import { StakingContract } from './managed/staking';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const contract = new StakingContract({
  rewardRate: 0.05, // 5% annual
  lockPeriod: 30 * 24 * 60 * 60 // 30 days in seconds
});

const api = await MidnightSetupAPI.deployContract(providers, contract);
```

***

## Identity Contract

**1 ZK Circuit**

A complete identity management system for privacy-preserving credential verification.

### Features

| Feature                 | Description                                    |
| ----------------------- | ---------------------------------------------- |
| Zero-knowledge proofs   | Prove attributes without revealing data        |
| Selective disclosure    | Share only what you choose                     |
| Credential verification | Validate credentials privately                 |
| Access control          | Grant permissions based on verified attributes |

### Use cases

* **KYC compliance** - Verify identity without storing personal data
* **Age verification** - Prove age without revealing birthdate
* **Credential validation** - Check qualifications privately
* **Gated access** - Control access based on verified attributes

### Example usage

```typescript
import { IdentityContract } from './managed/identity';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const contract = new IdentityContract({
  issuer: "trusted-issuer-address",
  requiredAttributes: ["over18", "verified"]
});

const api = await MidnightSetupAPI.deployContract(providers, contract);
```

***

## Oracle Contract

**7 ZK Circuits**

A decentralized oracle system with privacy-preserving data feeds.

### Features

| Feature                     | Description                                   |
| --------------------------- | --------------------------------------------- |
| Confidential data ingestion | Ingest data without public exposure           |
| Multi-source aggregation    | Combine data from multiple sources            |
| Tamper-proof feeds          | Ensure data integrity with ZK proofs          |
| Private validation          | Verify data quality without revealing sources |

### Use cases

* **Price feeds** - Private asset pricing for DeFi
* **Weather data** - Confidential environmental data
* **Sports results** - Private outcome verification
* **IoT streams** - Secure sensor data ingestion

### Example usage

```typescript
import { OracleContract } from './managed/oracle';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const contract = new OracleContract({
  feedId: "BTC-USD",
  updateInterval: 60, // seconds
  minSources: 3
});

const api = await MidnightSetupAPI.deployContract(providers, contract);
```

***

## Lending Contract

**7 ZK Circuits**

A privacy-preserving decentralized lending protocol.

### Features

| Feature                 | Description                             |
| ----------------------- | --------------------------------------- |
| Confidential collateral | Hide collateral amounts                 |
| Private loan amounts    | Keep borrowed amounts private           |
| Interest rate privacy   | Calculate interest without exposure     |
| ZK liquidation          | Verify liquidation conditions privately |

### Use cases

* **DeFi lending platforms** - Build private lending pools
* **Peer-to-peer lending** - Connect lenders and borrowers privately
* **Collateralized loans** - Secure loans with hidden collateral
* **Credit lines** - Establish private credit facilities

### Example usage

```typescript
import { LendingContract } from './managed/lending';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const contract = new LendingContract({
  collateralRatio: 150, // 150% collateralization
  interestRate: 0.08, // 8% annual
  liquidationThreshold: 120 // liquidate at 120%
});

const api = await MidnightSetupAPI.deployContract(providers, contract);
```

***

## Combining contracts

You can select multiple contracts to build comprehensive applications.

### DeFi platform example

Combine Tokenization + Oracle + Lending for a complete DeFi platform:

```bash
npx @meshsdk/midnight-contracts-wizard

? Select contracts to include:
  [x] Tokenization Contract
  [x] Oracle Contract
  [x] Lending & Borrowing Contract
```

This combination enables:

* Issue tokens representing assets
* Get real-time price feeds
* Enable collateralized borrowing

### Governance example

Combine Staking + Identity for verified governance:

```bash
npx @meshsdk/midnight-contracts-wizard

? Select contracts to include:
  [x] Staking Contract
  [x] Identity Contracts
```

This combination enables:

* Stake tokens for voting power
* Verify voter eligibility
* Private vote counting

***

## Technical details

Each contract template includes:

| Component             | Description                            |
| --------------------- | -------------------------------------- |
| `.compact` source     | Complete Compact contract code         |
| ZK circuits           | Pre-configured zero-knowledge circuits |
| TypeScript interfaces | Type definitions for integration       |
| Build scripts         | Compilation and deployment helpers     |

## Next steps

* [Project Structure](/docs/midnight/midnight-contracts-wizard/project-structure) - Understand generated files
* [Midnight Setup](/docs/midnight/midnight-setup) - Deploy contracts to the network
* [Usage](/docs/midnight/midnight-contracts-wizard/usage) - Generate your project

## Related resources

* [Compact Language Guide](https://docs.midnight.network/develop/tutorial/compact)
* [Midnight Network Documentation](https://docs.midnight.network/)


# Midnight Contracts Wizard
URL: /midnight/midnight-contracts-wizard

Generate production-ready Midnight smart contract projects with zero-knowledge privacy

***

title: "Midnight Contracts Wizard"
description: "Generate production-ready Midnight smart contract projects with zero-knowledge privacy"
icon: SparklesIcon
------------------

import { linksMidnightContractsWizard } from "@/data/links-midnight";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

The Midnight Contracts Wizard is a CLI tool that generates complete smart contract projects for the Midnight Network. Select from pre-built contract templates with zero-knowledge privacy built in, and get a fully configured TypeScript project ready for development.

## Why use the Contracts Wizard?

| Benefit                        | Description                                                 |
| ------------------------------ | ----------------------------------------------------------- |
| **Production-ready templates** | Battle-tested contracts with ZK circuits included           |
| **Zero configuration**         | Generates complete project structure with all dependencies  |
| **Privacy by default**         | All contracts use zero-knowledge proofs for confidentiality |
| **TypeScript support**         | Full type definitions and compiled interfaces included      |

## Available contracts

| Contract         | ZK Circuits | Use case                                     |
| ---------------- | ----------- | -------------------------------------------- |
| **Tokenization** | 7           | Asset tokenization, fundraising, securities  |
| **Staking**      | 8           | Rewards, governance, yield generation        |
| **Identity**     | 1           | KYC, credential verification, access control |
| **Oracle**       | 7           | Price feeds, external data, IoT streams      |
| **Lending**      | 7           | DeFi protocols, collateralized loans         |

## Quick start

Run the wizard with npx (no installation required):

```bash
npx @meshsdk/midnight-contracts-wizard
```

Follow the interactive prompts to select your contracts and generate your project.

## Example output

```bash
$ npx @meshsdk/midnight-contracts-wizard

Welcome to Midnight Contracts Wizard!
? Enter your project name: my-defi-app
? Select contracts to include:
  [x] Tokenization Contract (7 ZK circuits)
  [x] Lending & Borrowing Contract (7 ZK circuits)

Creating project structure...
Adding Tokenization contract...
Adding Lending contract...

Project created successfully!

Next steps:
1. cd my-defi-app
2. npm install
3. compact compile src/tokenization/token.compact src/managed/tokenization
```

## Documentation sections

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksMidnightContractsWizard.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Requirements

Before you start, ensure you have:

* **Node.js 18+** - [Download Node.js](https://nodejs.org/)
* **npm 8+** - Included with Node.js (provides npx)

## Next steps

1. [Installation](/docs/midnight/midnight-contracts-wizard/installation) - Get the CLI tool running
2. [Usage](/docs/midnight/midnight-contracts-wizard/usage) - Create your first project
3. [Contracts](/docs/midnight/midnight-contracts-wizard/contracts) - Explore available templates
4. [Project Structure](/docs/midnight/midnight-contracts-wizard/project-structure) - Understand generated files

## Related resources

* [Midnight Setup](/docs/midnight/midnight-setup) - Connect contracts to your dApp
* [Midnight Network Documentation](https://docs.midnight.network/)
* [Compact Language Guide](https://docs.midnight.network/develop/tutorial/compact)


# Installation
URL: /midnight/midnight-contracts-wizard/installation

Run the Midnight Contracts Wizard CLI to generate smart contract projects

***

title: "Installation"
description: "Run the Midnight Contracts Wizard CLI to generate smart contract projects"
----------------------------------------------------------------------------------------

The Midnight Contracts Wizard runs directly via npx, so you do not need to install anything globally. This guide covers all the ways to run the wizard and verify your environment.

## Quick start

Run the wizard immediately with npx:

```bash
npx @meshsdk/midnight-contracts-wizard
```

This command:

1. Downloads the latest version automatically
2. Launches the interactive wizard
3. Generates your project with selected contracts

## Prerequisites

Before running the wizard, verify you have the required tools installed.

### Check Node.js version

```bash
node --version
```

You need Node.js 18 or higher. If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/).

### Check npm version

```bash
npm --version
```

You need npm 8 or higher (includes npx). npm is included with Node.js, so updating Node.js will also update npm.

## Running the wizard

### Basic usage

```bash
npx @meshsdk/midnight-contracts-wizard
```

### Check available version

```bash
npx @meshsdk/midnight-contracts-wizard --version
```

### Display help

```bash
npx @meshsdk/midnight-contracts-wizard --help
```

## What happens when you run npx

When you execute the npx command:

1. **Downloads package** - npx fetches the latest version from npm registry
2. **Runs wizard** - Launches the interactive CLI interface
3. **Creates project** - Generates files based on your selections
4. **Cleans up** - The package is not permanently installed

## Troubleshooting

### "npx: command not found"

**Cause**: npm is not installed or not in your PATH.

**Solution**: Install Node.js from [nodejs.org](https://nodejs.org/), which includes npm and npx.

### "Node.js version too old"

**Cause**: You have Node.js \< 18 installed.

**Solution**: Update Node.js using your preferred method:

```bash
# Using nvm (recommended)
nvm install 18
nvm use 18

# Or download directly from nodejs.org
```

### Slow download

**Cause**: First-time download or npm cache cleared.

**Solution**: Wait for the download to complete. Subsequent runs use the npm cache and are faster.

### Permission errors

**Cause**: npm directory permissions issue.

**Solution**: Fix npm permissions:

```bash
# Create npm directory in home folder
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH=~/.npm-global/bin:$PATH
```

## Verifying installation

After running the wizard, verify the generated project:

```bash
# Navigate to your project
cd my-project

# Check the files were created
ls -la

# Verify package.json exists
cat package.json
```

You should see:

* `package.json` with project configuration
* `src/` directory with contract files
* `tsconfig.json` for TypeScript configuration

## Next steps

Now that you can run the wizard:

* [Usage](/docs/midnight/midnight-contracts-wizard/usage) - Create your first project
* [Contracts](/docs/midnight/midnight-contracts-wizard/contracts) - Learn about available templates
* [Project Structure](/docs/midnight/midnight-contracts-wizard/project-structure) - Understand generated files

## Related resources

* [Node.js Downloads](https://nodejs.org/)
* [npm Documentation](https://docs.npmjs.com/)
* [Midnight Network Documentation](https://docs.midnight.network/)


# Project Structure
URL: /midnight/midnight-contracts-wizard/project-structure

Understand the files and directories generated by the Midnight Contracts Wizard

***

title: "Project Structure"
description: "Understand the files and directories generated by the Midnight Contracts Wizard"
----------------------------------------------------------------------------------------------

When you create a project with the Midnight Contracts Wizard, it generates a complete directory structure with all necessary configuration files. This guide explains each component and how to work with it.

## Directory overview

```
my-project/
├── src/
│   ├── tokenization/        # Contract source (if selected)
│   │   └── token.compact
│   ├── staking/             # Contract source (if selected)
│   │   └── staking.compact
│   ├── identity/            # Contract source (if selected)
│   │   └── identity.compact
│   ├── oracle/              # Contract source (if selected)
│   │   └── oracle.compact
│   ├── lending/             # Contract source (if selected)
│   │   └── lending.compact
│   └── managed/             # Compiled output (auto-generated)
│       └── *.ts
├── dist/                    # Build output
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
├── tsconfig.build.json      # Production build config
└── README.md                # Project documentation
```

## Source directory (`src/`)

The `src/` directory contains your contract source files and compiled output.

### Contract directories

Each selected contract gets its own directory with `.compact` source files:

```
src/
├── tokenization/
│   └── token.compact       # Tokenization contract source
├── identity/
│   └── identity.compact    # Identity contract source
└── lending/
    └── lending.compact     # Lending contract source
```

### Managed directory (`src/managed/`)

The `managed/` directory contains compiled TypeScript files generated from your `.compact` contracts.

```
src/managed/
├── tokenization.ts         # Compiled tokenization contract
├── identity.ts             # Compiled identity contract
└── lending.ts              # Compiled lending contract
```

**Important:** Do not edit files in `src/managed/` manually. They are regenerated each time you compile your contracts.

## Configuration files

### package.json

Contains project metadata, dependencies, and build scripts:

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "compile": "compact-cli compile src/**/*.compact",
    "clean": "rm -rf dist src/managed"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "^0.8.1",
    "@midnight-ntwrk/midnight-js-types": "^2.0.2"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
```

| Script            | Purpose                                 |
| ----------------- | --------------------------------------- |
| `npm run build`   | Compile TypeScript to JavaScript        |
| `npm run compile` | Compile Compact contracts to TypeScript |
| `npm run clean`   | Remove generated files                  |

### tsconfig.json

Main TypeScript configuration for development:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### tsconfig.build.json

Extended configuration for production builds:

```json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
}
```

## Build output (`dist/`)

After running `npm run build`, compiled JavaScript and type definitions appear in `dist/`:

```
dist/
├── tokenization.js         # Compiled JavaScript
├── tokenization.d.ts       # Type definitions
├── identity.js
├── identity.d.ts
└── ...
```

## Contract source files

### Compact file structure

Each `.compact` file contains the contract definition and ZK circuits:

```text
// Example: src/tokenization/token.compact

contract Token {
  // State variables
  ledger balances: Map<Address, Secret<u64>>;

  // ZK circuits
  circuit mint(amount: Secret<u64>) -> Public<bool> {
    // Minting logic with ZK proof
  }

  circuit transfer(to: Address, amount: Secret<u64>) -> Public<bool> {
    // Transfer logic with ZK proof
  }

  // Additional circuits...
}
```

### Understanding circuits

Each circuit in the contract corresponds to a ZK proof:

| Circuit    | Purpose                                                |
| ---------- | ------------------------------------------------------ |
| `mint`     | Create new tokens with hidden amount                   |
| `transfer` | Move tokens with hidden sender/amount                  |
| `burn`     | Destroy tokens with hidden amount                      |
| `balance`  | Prove balance threshold without revealing exact amount |

## Working with the project

### Modify contracts

1. Edit `.compact` files in `src/[contract]/`
2. Recompile with `npm run compile`
3. Build with `npm run build`

### Add new contracts

1. Create a new directory in `src/`
2. Add your `.compact` file
3. Compile and build

### Integrate with your dApp

Import compiled contracts in your application:

```typescript
import { TokenizationContract } from './managed/tokenization';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const contract = new TokenizationContract({
  // Contract configuration
});

const api = await MidnightSetupAPI.deployContract(providers, contract);
```

## Troubleshooting

### Missing managed files

**Problem**: `src/managed/` is empty or missing files.

**Solution**: Run the Compact compiler:

```bash
npm run compile
```

### TypeScript errors in managed files

**Problem**: Type errors in `src/managed/*.ts`.

**Solution**:

1. Delete `src/managed/`
2. Recompile contracts: `npm run compile`
3. Ensure Compact compiler version matches dependencies

### Build fails

**Problem**: `npm run build` fails with errors.

**Solutions**:

1. Run `npm install` to ensure dependencies are installed
2. Check that `src/managed/` contains compiled contracts
3. Verify `tsconfig.json` is valid JSON

## Next steps

* [Contracts](/docs/midnight/midnight-contracts-wizard/contracts) - Learn about each contract template
* [Midnight Setup](/docs/midnight/midnight-setup) - Deploy contracts to the network
* [API Reference](/docs/midnight/midnight-setup/api) - Integrate with your dApp

## Related resources

* [Compact Language Guide](https://docs.midnight.network/develop/tutorial/compact)
* [TypeScript Documentation](https://www.typescriptlang.org/docs/)
* [Midnight Network Documentation](https://docs.midnight.network/)


# Usage
URL: /midnight/midnight-contracts-wizard/usage

Create Midnight smart contract projects with the interactive CLI wizard

***

title: "Usage"
description: "Create Midnight smart contract projects with the interactive CLI wizard"
--------------------------------------------------------------------------------------

This guide walks you through using the Midnight Contracts Wizard to generate a complete smart contract project. You will learn how to select contracts, understand the prompts, and set up your development environment.

## Quick start

Run the wizard:

```bash
npx @meshsdk/midnight-contracts-wizard
```

## Step-by-step walkthrough

### Step 1: Enter project name

The wizard first asks for your project name:

```
Welcome to Midnight Contracts Wizard!
? Enter your project name: my-midnight-project
```

Enter a valid directory name. The wizard creates a new folder with this name in your current directory.

**Tips:**

* Use lowercase letters, numbers, and hyphens
* Avoid spaces and special characters
* Choose a descriptive name for your project

### Step 2: Select contracts

Next, select which contract templates to include:

```
? Select contracts to include: (Use arrow keys and space to select)
  [ ] Tokenization Contract (7 ZK circuits)
  [ ] Staking Contract (8 ZK circuits)
  [ ] Identity Contracts (1 ZK circuit)
  [ ] Oracle Contract (7 ZK circuits)
  [ ] Lending & Borrowing Contract (7 ZK circuits)
```

**Controls:**

* **Arrow keys** - Navigate between options
* **Space** - Toggle selection
* **Enter** - Confirm and continue

You can select one or multiple contracts. Each contract is independent and can be used standalone or combined with others.

### Step 3: Review and confirm

The wizard shows a summary of your selections:

```
Creating project: my-midnight-project
Selected contracts:
  - Tokenization Contract
  - Identity Contracts

Proceed? (Y/n)
```

Press Enter or type `Y` to confirm.

### Step 4: Project generation

The wizard creates your project:

```
Creating project structure...
Adding Tokenization contract...
Adding Identity contracts...

Project created successfully!

Next steps:
1. cd my-midnight-project
2. npm install
3. compact compile src/tokenization/token.compact src/managed/tokenization
```

## Complete example session

```bash
$ npx @meshsdk/midnight-contracts-wizard

Welcome to Midnight Contracts Wizard!

? Enter your project name: defi-platform

? Select contracts to include:
  [x] Tokenization Contract (7 ZK circuits)
  [ ] Staking Contract (8 ZK circuits)
  [ ] Identity Contracts (1 ZK circuit)
  [x] Oracle Contract (7 ZK circuits)
  [x] Lending & Borrowing Contract (7 ZK circuits)

Creating project: defi-platform
Selected contracts:
  - Tokenization Contract
  - Oracle Contract
  - Lending & Borrowing Contract

Proceed? Y

Creating project structure...
Adding Tokenization contract...
Adding Oracle contract...
Adding Lending contract...

Project created successfully!

Next steps:
1) Navigate to the project folder:
   cd ./defi-platform

2) Install dependencies:
   npm install

3) Compile your smart contracts:
   compact compile src/tokenization/token.compact src/managed/tokenization
   compact compile src/oracle/oracle.compact src/managed/oracle
   compact compile src/lending/lending.compact src/managed/lending

Your contracts will be compiled to src/managed/
Check the README.md for detailed instructions
```

## After project generation

### Install dependencies

Navigate to your project and install dependencies:

```bash
cd my-midnight-project
npm install
```

### Compile contracts

Compile each contract using the Compact compiler:

```bash
# Compile tokenization contract
compact compile src/tokenization/token.compact src/managed/tokenization

# Compile identity contract
compact compile src/identity/identity.compact src/managed/identity
```

### Verify output

Check that the compiled TypeScript files were generated:

```bash
ls src/managed/
```

You should see TypeScript files corresponding to your contracts.

## Command line options

### Display help

```bash
npx @meshsdk/midnight-contracts-wizard --help
```

Shows all available options and usage information.

### Check version

```bash
npx @meshsdk/midnight-contracts-wizard --version
```

Displays the current version of the wizard.

## Troubleshooting

### Project folder already exists

**Problem**: The wizard cannot create a folder that already exists.

**Solution**: Choose a different project name or delete the existing folder first.

### Compact compiler not found

**Problem**: The `compact` command is not available.

**Solution**: Install the Midnight Compact compiler. See the [Midnight documentation](https://docs.midnight.network/develop/tutorial/compact) for installation instructions.

### TypeScript compilation errors

**Problem**: TypeScript reports errors after compiling contracts.

**Solutions**:

1. Ensure you ran `npm install` first
2. Verify the Compact compiler completed successfully
3. Check that `src/managed/` contains the generated files

## Next steps

* [Contracts](/docs/midnight/midnight-contracts-wizard/contracts) - Explore each contract template in detail
* [Project Structure](/docs/midnight/midnight-contracts-wizard/project-structure) - Understand the generated files
* [Midnight Setup](/docs/midnight/midnight-setup) - Connect your contracts to a dApp

## Related resources

* [Midnight Network Documentation](https://docs.midnight.network/)
* [Compact Language Guide](https://docs.midnight.network/develop/tutorial/compact)


# API Reference
URL: /midnight/midnight-setup/api

Complete reference for MidnightSetupAPI methods, types, and provider configuration

***

title: "API Reference"
description: "Complete reference for MidnightSetupAPI methods, types, and provider configuration"
-------------------------------------------------------------------------------------------------

This reference documents all methods, types, and configuration options available in the `@meshsdk/midnight-setup` package.

## MidnightSetupAPI

The main class for deploying and interacting with Midnight Network smart contracts.

### Static methods

#### deployContract

Deploys a new smart contract to the Midnight Network.

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import type { MidnightSetupContractProviders, ContractInstance } from '@meshsdk/midnight-setup';

const api = await MidnightSetupAPI.deployContract(
  providers: MidnightSetupContractProviders,
  contractInstance: ContractInstance,
  logger?: Logger
);
```

**Parameters**

| Parameter          | Type                             | Required | Description                               |
| ------------------ | -------------------------------- | -------- | ----------------------------------------- |
| `providers`        | `MidnightSetupContractProviders` | Yes      | Network and wallet provider configuration |
| `contractInstance` | `ContractInstance`               | Yes      | Your compiled contract instance           |
| `logger`           | `Logger`                         | No       | Optional Pino logger for debugging        |

**Returns**

`Promise<MidnightSetupAPI>` - An API instance connected to the deployed contract.

**Example**

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import { setupProviders } from './providers';
import { MyContract } from './managed/MyContract';

async function deploy() {
  const providers = await setupProviders();
  const contractInstance = new MyContract({});

  const api = await MidnightSetupAPI.deployContract(providers, contractInstance);

  console.log('Contract address:', api.deployedContractAddress);
  return api;
}
```

***

#### joinContract

Connects to an existing deployed contract.

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

const api = await MidnightSetupAPI.joinContract(
  providers: MidnightSetupContractProviders,
  contractInstance: ContractInstance,
  contractAddress: string,
  logger?: Logger
);
```

**Parameters**

| Parameter          | Type                             | Required | Description                               |
| ------------------ | -------------------------------- | -------- | ----------------------------------------- |
| `providers`        | `MidnightSetupContractProviders` | Yes      | Network and wallet provider configuration |
| `contractInstance` | `ContractInstance`               | Yes      | Your compiled contract instance           |
| `contractAddress`  | `string`                         | Yes      | Address of the deployed contract          |
| `logger`           | `Logger`                         | No       | Optional Pino logger for debugging        |

**Returns**

`Promise<MidnightSetupAPI>` - An API instance connected to the existing contract.

**Example**

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import { setupProviders } from './providers';
import { MyContract } from './managed/MyContract';

async function join(address: string) {
  const providers = await setupProviders();
  const contractInstance = new MyContract({});

  const api = await MidnightSetupAPI.joinContract(
    providers,
    contractInstance,
    address
  );

  console.log('Connected to:', address);
  return api;
}
```

***

### Instance methods

#### getContractState

Retrieves the current state of the connected contract.

```typescript
const state = await api.getContractState();
```

**Returns**

`Promise<ContractStateData>` - The current contract state.

**Example**

```typescript
const state = await api.getContractState();
console.log('Contract data:', state.data);
console.log('Last updated:', state.timestamp);
```

***

#### getLedgerState

Retrieves and parses the current ledger state.

```typescript
const ledgerState = await api.getLedgerState();
```

**Returns**

`Promise<LedgerStateData>` - The parsed ledger state.

**Example**

```typescript
const ledgerState = await api.getLedgerState();
console.log('Message:', ledgerState.ledgerState?.message);
console.log('Block height:', ledgerState.blockHeight);
```

***

### Instance properties

#### deployedContractAddress

The address of the deployed contract (available after deployment or joining).

```typescript
const address: string = api.deployedContractAddress;
```

***

## Types

Import types for TypeScript projects:

```typescript
import type {
  ContractInstance,
  ContractStateData,
  DeployedContract,
  DeployedMidnightSetupAPI,
  LedgerStateData,
  MidnightSetupContractProviders,
} from '@meshsdk/midnight-setup';
```

### MidnightSetupContractProviders

Configuration object containing all required providers.

```typescript
interface MidnightSetupContractProviders {
  privateStateProvider: PrivateStateProvider;
  zkConfigProvider: ZkConfigProvider;
  proofProvider: ProofProvider;
  publicDataProvider: PublicDataProvider;
  walletProvider: WalletProvider;
  midnightProvider: MidnightProvider;
}
```

| Property               | Description                               |
| ---------------------- | ----------------------------------------- |
| `privateStateProvider` | Manages local private state storage       |
| `zkConfigProvider`     | Handles ZK circuit configuration fetching |
| `proofProvider`        | Generates zero-knowledge proofs           |
| `publicDataProvider`   | Queries public blockchain data            |
| `walletProvider`       | Integrates with Lace wallet for signing   |
| `midnightProvider`     | Submits transactions to the network       |

***

### ContractStateData

The structure returned by `getContractState()`.

```typescript
interface ContractStateData {
  data: unknown;
  timestamp: number;
  blockHeight: number;
}
```

***

### LedgerStateData

The structure returned by `getLedgerState()`.

```typescript
interface LedgerStateData {
  ledgerState: unknown;
  blockHeight: number;
  timestamp: number;
}
```

***

## Provider setup

Complete provider configuration example:

```typescript
import { FetchZkConfigProvider } from "@midnight-ntwrk/midnight-js-fetch-zk-config-provider";
import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
import type { MidnightSetupContractProviders } from "@meshsdk/midnight-setup";

export async function setupProviders(): Promise<MidnightSetupContractProviders> {
  const wallet = window.midnight?.mnLace;
  if (!wallet) {
    throw new Error("Please install Lace Beta Wallet for Midnight Network");
  }

  const walletAPI = await wallet.enable();
  const walletState = await walletAPI.state();
  const uris = await wallet.serviceUriConfig();

  return {
    privateStateProvider: levelPrivateStateProvider({
      privateStateStoreName: "my-dapp-state",
    }),
    zkConfigProvider: new FetchZkConfigProvider(
      window.location.origin,
      fetch.bind(window),
    ),
    proofProvider: httpClientProofProvider(uris.proverServerUri),
    publicDataProvider: indexerPublicDataProvider(
      uris.indexerUri,
      uris.indexerWsUri,
    ),
    walletProvider: {
      coinPublicKey: walletState.coinPublicKey,
      encryptionPublicKey: walletState.encryptionPublicKey,
      balanceTx: (tx, newCoins) => {
        return walletAPI.balanceAndProveTransaction(tx, newCoins);
      },
    },
    midnightProvider: {
      submitTx: (tx) => {
        return walletAPI.submitTransaction(tx);
      },
    },
  };
}
```

***

## Error handling

Wrap API calls in try-catch blocks for proper error handling:

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';

async function safeDeployment() {
  try {
    const providers = await setupProviders();
    const api = await MidnightSetupAPI.deployContract(providers, contractInstance);

    const state = await api.getContractState();
    return { success: true, api, state };
  } catch (error) {
    console.error('Deployment error:', error);

    if (error instanceof Error) {
      if (error.message.includes('Insufficient funds')) {
        return { success: false, error: 'Not enough funds in wallet' };
      }
      if (error.message.includes('Contract not found')) {
        return { success: false, error: 'Contract address is invalid' };
      }
    }

    return { success: false, error: 'An unexpected error occurred' };
  }
}
```

***

## Best practices

1. **Always handle errors** - Wrap all API calls in try-catch blocks
2. **Use TypeScript** - Import types for compile-time safety
3. **Validate inputs** - Check contract addresses and parameters before calling
4. **Monitor state changes** - Poll `getContractState()` or `getLedgerState()` for updates
5. **Test on testnet** - Always test thoroughly before mainnet deployment
6. **Log appropriately** - Pass a logger to deployment methods for debugging

***

## Troubleshooting

### "Contract not found" error

**Cause**: The contract address is invalid or the contract was not deployed.

**Solution**: Verify the address is correct and the contract exists on the network.

### "Insufficient funds" error

**Cause**: The wallet does not have enough tokens for the transaction.

**Solution**: Fund the wallet with testnet tokens and retry.

### Provider connection failures

**Cause**: Network services (indexer, prover) are unreachable.

**Solution**: Check `wallet.serviceUriConfig()` returns valid URIs and verify network connectivity.

***

## Next steps

* [Wallet Integration](/docs/midnight/midnight-setup/wallet) - Wallet connection details
* [Examples](/docs/midnight/midnight-setup/examples) - Complete code samples
* [Getting Started](/docs/midnight/midnight-setup/getting-started) - Initial setup guide


# Examples
URL: /midnight/midnight-setup/examples

Complete working examples for Midnight Network integration with React

***

title: "Examples"
description: "Complete working examples for Midnight Network integration with React"
------------------------------------------------------------------------------------

This page provides complete, copy-paste-ready examples for common Midnight Network integration patterns. Each example includes all necessary imports and can be used as a starting point for your application.

## Full React application

A complete React application demonstrating wallet connection, contract deployment, and state management.

### Project setup

First, install all required dependencies:

```bash
npm install @meshsdk/midnight-setup \
  @midnight-ntwrk/dapp-connector-api@3.0.0 \
  @midnight-ntwrk/midnight-js-fetch-zk-config-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-http-client-proof-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-indexer-public-data-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-level-private-state-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-network-id@2.0.2
```

### Provider configuration

Create `src/providers.ts`:

```typescript
import { FetchZkConfigProvider } from "@midnight-ntwrk/midnight-js-fetch-zk-config-provider";
import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
import type { MidnightSetupContractProviders } from "@meshsdk/midnight-setup";

export async function setupProviders(): Promise<MidnightSetupContractProviders> {
  const wallet = window.midnight?.mnLace;
  if (!wallet) {
    throw new Error("Please install Lace Beta Wallet for Midnight Network");
  }

  const walletAPI = await wallet.enable();
  const walletState = await walletAPI.state();
  const uris = await wallet.serviceUriConfig();

  return {
    privateStateProvider: levelPrivateStateProvider({
      privateStateStoreName: "my-dapp-state",
    }),
    zkConfigProvider: new FetchZkConfigProvider(
      window.location.origin,
      fetch.bind(window),
    ),
    proofProvider: httpClientProofProvider(uris.proverServerUri),
    publicDataProvider: indexerPublicDataProvider(
      uris.indexerUri,
      uris.indexerWsUri,
    ),
    walletProvider: {
      coinPublicKey: walletState.coinPublicKey,
      encryptionPublicKey: walletState.encryptionPublicKey,
      balanceTx: (tx, newCoins) => {
        return walletAPI.balanceAndProveTransaction(tx, newCoins);
      },
    },
    midnightProvider: {
      submitTx: (tx) => {
        return walletAPI.submitTransaction(tx);
      },
    },
  };
}
```

### Wallet hook

Create `src/hooks/useMidnightWallet.ts`:

```typescript
import { useState, useCallback } from 'react';

interface WalletState {
  address: string;
  coinPublicKey: string;
  encryptionPublicKey: string;
}

interface WalletHookReturn {
  connectWallet: () => Promise<void>;
  disconnectWallet: () => Promise<void>;
  walletState: WalletState | null;
  isConnected: boolean;
  isLoading: boolean;
  error: string | null;
}

export function useMidnightWallet(): WalletHookReturn {
  const [walletState, setWalletState] = useState<WalletState | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const connectWallet = useCallback(async () => {
    setIsLoading(true);
    setError(null);

    try {
      const wallet = window.midnight?.mnLace;
      if (!wallet) {
        throw new Error("Please install Lace Beta Wallet for Midnight Network");
      }

      const walletAPI = await wallet.enable();
      const state = await walletAPI.state();

      setWalletState({
        address: state.address,
        coinPublicKey: state.coinPublicKey,
        encryptionPublicKey: state.encryptionPublicKey,
      });
      setIsConnected(true);
    } catch (err) {
      const message = err instanceof Error ? err.message : "Connection failed";
      setError(message);
      throw err;
    } finally {
      setIsLoading(false);
    }
  }, []);

  const disconnectWallet = useCallback(async () => {
    try {
      const wallet = window.midnight?.mnLace;
      if (wallet) {
        await wallet.disconnect();
        setWalletState(null);
        setIsConnected(false);
        setError(null);
      }
    } catch (err) {
      const message = err instanceof Error ? err.message : "Disconnect failed";
      setError(message);
    }
  }, []);

  return {
    connectWallet,
    disconnectWallet,
    walletState,
    isConnected,
    isLoading,
    error,
  };
}
```

### Contract hook

Create `src/hooks/useMidnightContract.ts`:

```typescript
import { useState, useCallback } from 'react';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import { setupProviders } from '../providers';

interface ContractHookReturn {
  api: MidnightSetupAPI | null;
  deployContract: (contractInstance: unknown) => Promise<MidnightSetupAPI>;
  joinContract: (contractInstance: unknown, address: string) => Promise<MidnightSetupAPI>;
  getContractState: () => Promise<unknown>;
  getLedgerState: () => Promise<unknown>;
  isLoading: boolean;
  error: string | null;
}

export function useMidnightContract(): ContractHookReturn {
  const [api, setApi] = useState<MidnightSetupAPI | null>(null);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const deployContract = useCallback(async (contractInstance: unknown) => {
    setIsLoading(true);
    setError(null);

    try {
      const providers = await setupProviders();
      const newApi = await MidnightSetupAPI.deployContract(
        providers,
        contractInstance as never
      );
      setApi(newApi);
      return newApi;
    } catch (err) {
      const message = err instanceof Error ? err.message : "Deployment failed";
      setError(message);
      throw err;
    } finally {
      setIsLoading(false);
    }
  }, []);

  const joinContract = useCallback(async (contractInstance: unknown, address: string) => {
    setIsLoading(true);
    setError(null);

    try {
      const providers = await setupProviders();
      const newApi = await MidnightSetupAPI.joinContract(
        providers,
        contractInstance as never,
        address
      );
      setApi(newApi);
      return newApi;
    } catch (err) {
      const message = err instanceof Error ? err.message : "Failed to join contract";
      setError(message);
      throw err;
    } finally {
      setIsLoading(false);
    }
  }, []);

  const getContractState = useCallback(async () => {
    if (!api) throw new Error('No contract API available');
    return await api.getContractState();
  }, [api]);

  const getLedgerState = useCallback(async () => {
    if (!api) throw new Error('No contract API available');
    return await api.getLedgerState();
  }, [api]);

  return {
    api,
    deployContract,
    joinContract,
    getContractState,
    getLedgerState,
    isLoading,
    error,
  };
}
```

### Main application component

Create `src/App.tsx`:

```typescript
import React, { useState } from 'react';
import { useMidnightWallet } from './hooks/useMidnightWallet';
import { useMidnightContract } from './hooks/useMidnightContract';

function App() {
  const {
    connectWallet,
    disconnectWallet,
    walletState,
    isConnected,
    isLoading: walletLoading,
    error: walletError,
  } = useMidnightWallet();

  const {
    api,
    deployContract,
    joinContract,
    getContractState,
    isLoading: contractLoading,
    error: contractError,
  } = useMidnightContract();

  const [contractAddress, setContractAddress] = useState('');
  const [contractState, setContractState] = useState<unknown>(null);

  const isLoading = walletLoading || contractLoading;
  const error = walletError || contractError;

  async function handleDeploy() {
    try {
      // Replace with your actual contract class
      const contractInstance = {}; // new MyContract({})
      const newApi = await deployContract(contractInstance);
      console.log('Deployed at:', newApi.deployedContractAddress);
    } catch (err) {
      console.error('Deploy failed:', err);
    }
  }

  async function handleJoin() {
    if (!contractAddress.trim()) {
      alert('Please enter a contract address');
      return;
    }

    try {
      // Replace with your actual contract class
      const contractInstance = {}; // new MyContract({})
      await joinContract(contractInstance, contractAddress);
      console.log('Joined contract:', contractAddress);
    } catch (err) {
      console.error('Join failed:', err);
    }
  }

  async function handleGetState() {
    try {
      const state = await getContractState();
      setContractState(state);
    } catch (err) {
      console.error('Get state failed:', err);
    }
  }

  return (
    <div style={{ padding: '2rem', maxWidth: '800px', margin: '0 auto' }}>
      <h1>Midnight Network dApp</h1>

      {error && (
        <div style={{ padding: '1rem', background: '#fee', color: '#c00', marginBottom: '1rem' }}>
          {error}
        </div>
      )}

      <section style={{ marginBottom: '2rem' }}>
        <h2>Step 1: Connect Wallet</h2>
        {isConnected ? (
          <div>
            <p>Connected: {walletState?.address}</p>
            <button onClick={disconnectWallet}>Disconnect</button>
          </div>
        ) : (
          <button onClick={connectWallet} disabled={isLoading}>
            {walletLoading ? 'Connecting...' : 'Connect Wallet'}
          </button>
        )}
      </section>

      <section style={{ marginBottom: '2rem' }}>
        <h2>Step 2: Deploy or Join Contract</h2>
        <div style={{ marginBottom: '1rem' }}>
          <button onClick={handleDeploy} disabled={!isConnected || isLoading}>
            {contractLoading ? 'Deploying...' : 'Deploy New Contract'}
          </button>
        </div>
        <div>
          <input
            type="text"
            placeholder="Contract Address"
            value={contractAddress}
            onChange={(e) => setContractAddress(e.target.value)}
            style={{ marginRight: '0.5rem', padding: '0.5rem', width: '300px' }}
          />
          <button onClick={handleJoin} disabled={!isConnected || isLoading}>
            Join Contract
          </button>
        </div>
        {api && (
          <p style={{ marginTop: '0.5rem', color: 'green' }}>
            Connected to: {api.deployedContractAddress}
          </p>
        )}
      </section>

      {api && (
        <section style={{ marginBottom: '2rem' }}>
          <h2>Step 3: Read Contract State</h2>
          <button onClick={handleGetState} disabled={isLoading}>
            Get Contract State
          </button>
          {contractState && (
            <pre style={{ background: '#f5f5f5', padding: '1rem', marginTop: '1rem' }}>
              {JSON.stringify(contractState, null, 2)}
            </pre>
          )}
        </section>
      )}
    </div>
  );
}

export default App;
```

***

## Error boundary component

Wrap your application with an error boundary for graceful error handling:

```typescript
import React from 'react';

interface ErrorBoundaryState {
  hasError: boolean;
  error?: Error;
}

interface ErrorBoundaryProps {
  children: React.ReactNode;
}

export class MidnightErrorBoundary extends React.Component<
  ErrorBoundaryProps,
  ErrorBoundaryState
> {
  constructor(props: ErrorBoundaryProps) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Midnight Error Boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return (
        <div style={{ padding: '2rem', textAlign: 'center' }}>
          <h2>Something went wrong</h2>
          <p>{this.state.error?.message}</p>
          <button onClick={() => window.location.reload()}>
            Reload Page
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

// Usage in index.tsx
import { MidnightErrorBoundary } from './components/ErrorBoundary';
import App from './App';

ReactDOM.render(
  <MidnightErrorBoundary>
    <App />
  </MidnightErrorBoundary>,
  document.getElementById('root')
);
```

***

## Error handling utilities

Create reusable error handling functions:

```typescript
// src/utils/errors.ts

export function handleMidnightError(error: Error): string {
  const message = error.message.toLowerCase();

  if (message.includes('install lace beta wallet')) {
    return 'Please install the Lace Beta Wallet browser extension';
  }

  if (message.includes('user rejected')) {
    return 'You rejected the request. Please try again.';
  }

  if (message.includes('insufficient funds')) {
    return 'Your wallet does not have enough funds';
  }

  if (message.includes('contract not found')) {
    return 'The contract address is invalid or does not exist';
  }

  if (message.includes('network')) {
    return 'Network error. Please check your connection.';
  }

  return 'An unexpected error occurred. Please try again.';
}

export function isWalletInstalled(): boolean {
  return typeof window !== 'undefined' && !!window.midnight?.mnLace;
}

export function formatAddress(address: string, chars = 6): string {
  if (address.length <= chars * 2) return address;
  return `${address.slice(0, chars)}...${address.slice(-chars)}`;
}
```

***

## TypeScript type declarations

Add type declarations for the Midnight wallet global:

```typescript
// src/types/midnight.d.ts

interface MidnightWalletAPI {
  state(): Promise<{
    address: string;
    coinPublicKey: string;
    encryptionPublicKey: string;
  }>;
  balanceAndProveTransaction(tx: unknown, newCoins: unknown): Promise<unknown>;
  submitTransaction(tx: unknown): Promise<unknown>;
}

interface MidnightWallet {
  enable(): Promise<MidnightWalletAPI>;
  disconnect(): Promise<void>;
  serviceUriConfig(): Promise<{
    indexerUri: string;
    indexerWsUri: string;
    proverServerUri: string;
  }>;
}

interface Midnight {
  mnLace?: MidnightWallet;
}

declare global {
  interface Window {
    midnight?: Midnight;
  }
}

export {};
```

***

## Troubleshooting

### Common issues and solutions

| Issue               | Cause                   | Solution                                      |
| ------------------- | ----------------------- | --------------------------------------------- |
| Wallet not detected | Extension not installed | Install Lace Beta Wallet and refresh          |
| Connection rejected | User denied request     | Retry and explain why wallet access is needed |
| Deployment fails    | Insufficient funds      | Fund wallet with testnet tokens               |
| Contract not found  | Invalid address         | Verify the contract address is correct        |
| Network errors      | Service unavailable     | Check internet connection and retry           |

### Debug logging

Enable detailed logging during development:

```typescript
import pino from 'pino';

const logger = pino({ level: 'debug' });

const api = await MidnightSetupAPI.deployContract(
  providers,
  contractInstance,
  logger // Pass logger for debug output
);
```

***

## Next steps

* [API Reference](/docs/midnight/midnight-setup/api) - Complete method documentation
* [Wallet Integration](/docs/midnight/midnight-setup/wallet) - Advanced wallet features
* [Getting Started](/docs/midnight/midnight-setup/getting-started) - Initial setup guide

## Related resources

* [GitHub Repository](https://github.com/MeshJS/midnight-setup) - Source code and more examples
* [Midnight Network Documentation](https://docs.midnight.network/)
* [Lace Beta Wallet](https://chromewebstore.google.com/detail/lace-midnight-preview/hgeekaiplokcnmakghbdfbgnlfheichg)


# Getting Started
URL: /midnight/midnight-setup/getting-started

Install and configure @meshsdk/midnight-setup to build your first Midnight Network dApp

***

title: "Getting Started"
description: "Install and configure @meshsdk/midnight-setup to build your first Midnight Network dApp"
------------------------------------------------------------------------------------------------------

This guide walks you through installing the Midnight SDK, configuring providers, and deploying your first smart contract. By the end, you will have a working Midnight integration ready for development.

## Prerequisites

Before you start, ensure you have:

* **Node.js 18+** - [Download Node.js](https://nodejs.org/)
* **Lace Beta Wallet** - [Install from Chrome Web Store](https://chromewebstore.google.com/detail/lace-midnight-preview/hgeekaiplokcnmakghbdfbgnlfheichg)
* A funded wallet on Midnight testnet

## Step 1: Install dependencies

Install the core package and required Midnight Network dependencies:

```bash
npm install @meshsdk/midnight-setup \
  @midnight-ntwrk/dapp-connector-api@3.0.0 \
  @midnight-ntwrk/midnight-js-fetch-zk-config-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-http-client-proof-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-indexer-public-data-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-level-private-state-provider@2.0.2 \
  @midnight-ntwrk/midnight-js-network-id@2.0.2
```

## Step 2: Create the providers configuration

Create a `providers.ts` file that configures all the necessary providers for Midnight Network:

```typescript
import { FetchZkConfigProvider } from "@midnight-ntwrk/midnight-js-fetch-zk-config-provider";
import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
import type { MidnightSetupContractProviders } from "@meshsdk/midnight-setup";

export async function setupProviders(): Promise<MidnightSetupContractProviders> {
  // Check for Lace wallet
  const wallet = window.midnight?.mnLace;
  if (!wallet) {
    throw new Error("Please install Lace Beta Wallet for Midnight Network");
  }

  // Connect to wallet and get configuration
  const walletAPI = await wallet.enable();
  const walletState = await walletAPI.state();
  const uris = await wallet.serviceUriConfig();

  return {
    privateStateProvider: levelPrivateStateProvider({
      privateStateStoreName: "my-dapp-state",
    }),
    zkConfigProvider: new FetchZkConfigProvider(
      window.location.origin,
      fetch.bind(window),
    ),
    proofProvider: httpClientProofProvider(uris.proverServerUri),
    publicDataProvider: indexerPublicDataProvider(
      uris.indexerUri,
      uris.indexerWsUri,
    ),
    walletProvider: {
      coinPublicKey: walletState.coinPublicKey,
      encryptionPublicKey: walletState.encryptionPublicKey,
      balanceTx: (tx, newCoins) => {
        return walletAPI.balanceAndProveTransaction(tx, newCoins);
      },
    },
    midnightProvider: {
      submitTx: (tx) => {
        return walletAPI.submitTransaction(tx);
      },
    },
  };
}
```

## Step 3: Deploy a contract

Use `MidnightSetupAPI` to deploy your smart contract:

```typescript
import { MidnightSetupAPI } from "@meshsdk/midnight-setup";
import { setupProviders } from "./providers";

async function deployContract() {
  // Set up providers with wallet connection
  const providers = await setupProviders();

  // Create your contract instance
  const contractInstance = new MyContract({});

  // Deploy the contract
  const api = await MidnightSetupAPI.deployContract(
    providers,
    contractInstance,
  );

  console.log("Contract deployed at:", api.deployedContractAddress);
  return api;
}
```

## Step 4: Interact with the contract

Once deployed, you can read state and call contract methods:

```typescript
// Get contract state
const contractState = await api.getContractState();
console.log("Contract data:", contractState.data);

// Get ledger state
const ledgerState = await api.getLedgerState();
console.log("Ledger state:", ledgerState.ledgerState?.message);
```

## Step 5: Join an existing contract

To connect to an already-deployed contract:

```typescript
import { MidnightSetupAPI } from "@meshsdk/midnight-setup";
import { setupProviders } from "./providers";

async function joinContract(contractAddress: string) {
  const providers = await setupProviders();
  const contractInstance = new MyContract({});

  const api = await MidnightSetupAPI.joinContract(
    providers,
    contractInstance,
    contractAddress,
  );

  console.log("Connected to contract:", contractAddress);
  return api;
}
```

## Project structure

A typical Midnight dApp project looks like this:

```
my-midnight-dapp/
├── src/
│   ├── providers.ts       # Provider configuration
│   ├── contracts/         # Your Compact contracts
│   │   └── MyContract.compact
│   ├── managed/           # Compiled contract output
│   │   └── MyContract.ts
│   └── app.tsx            # Application entry point
├── package.json
└── tsconfig.json
```

## What the providers do

| Provider               | Purpose                                         |
| ---------------------- | ----------------------------------------------- |
| `privateStateProvider` | Stores private state locally using LevelDB      |
| `zkConfigProvider`     | Fetches zero-knowledge circuit configurations   |
| `proofProvider`        | Generates ZK proofs via HTTP prover service     |
| `publicDataProvider`   | Queries public blockchain data from the indexer |
| `walletProvider`       | Signs and balances transactions via Lace wallet |
| `midnightProvider`     | Submits transactions to the Midnight Network    |

## Troubleshooting

### Wallet not detected

If you see "Please install Lace Beta Wallet":

1. Verify the Lace Beta extension is installed in your browser
2. Refresh the page after installation
3. Ensure the wallet is unlocked and connected to Midnight testnet

### Transaction failures

Common causes of transaction failures:

* **Insufficient funds**: Ensure your wallet has testnet tokens
* **Network issues**: Check that the prover and indexer services are reachable
* **Contract errors**: Review your contract logic and input parameters

### Provider connection errors

If providers fail to connect:

1. Check that `wallet.serviceUriConfig()` returns valid URIs
2. Verify your internet connection
3. Ensure the Midnight testnet services are operational

## Next steps

* [Wallet Integration](/docs/midnight/midnight-setup/wallet) - Deep dive into Lace wallet features
* [API Reference](/docs/midnight/midnight-setup/api) - Complete method documentation
* [Examples](/docs/midnight/midnight-setup/examples) - Full working code samples

## Related resources

* [Midnight Network Documentation](https://docs.midnight.network/)
* [GitHub Repository](https://github.com/MeshJS/midnight-setup)
* [Lace Beta Wallet](https://chromewebstore.google.com/detail/lace-midnight-preview/hgeekaiplokcnmakghbdfbgnlfheichg)


# Midnight Setup
URL: /midnight/midnight-setup

Complete development setup for building privacy-preserving dApps on Midnight Network

***

title: "Midnight Setup"
description: "Complete development setup for building privacy-preserving dApps on Midnight Network"
icon: Cog6ToothIcon
-------------------

import { linksMidnightSetup } from "@/data/links-midnight";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";

The `@meshsdk/midnight-setup` package provides everything you need to build decentralized applications on the Midnight Network. It handles wallet integration, provider configuration, and contract deployment so you can focus on your application logic.

## What you get

| Component                  | Description                                         |
| -------------------------- | --------------------------------------------------- |
| **MidnightSetupAPI**       | Deploy and interact with smart contracts            |
| **Provider configuration** | Connect to indexers, provers, and the network       |
| **Wallet integration**     | Full Lace Beta Wallet support                       |
| **TypeScript types**       | Complete type definitions for type-safe development |

## Installation

```bash
npm install @meshsdk/midnight-setup
```

## Quick example

```typescript
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import { setupProviders } from './providers';

// Set up providers with wallet connection
const providers = await setupProviders();

// Deploy a new contract
const api = await MidnightSetupAPI.deployContract(providers, contractInstance);
console.log('Deployed at:', api.deployedContractAddress);

// Read contract state
const state = await api.getContractState();
console.log('Current state:', state);
```

## Documentation sections

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  {linksMidnightSetup.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Requirements

Before you begin, ensure you have:

* **Node.js 18+** installed
* **Lace Beta Wallet** browser extension for Midnight Network
* Basic familiarity with TypeScript and React (for frontend integration)

## Next steps

1. Follow the [Getting Started](/docs/midnight/midnight-setup/getting-started) guide to set up your project
2. Configure [Wallet Integration](/docs/midnight/midnight-setup/wallet) for transaction signing
3. Explore the [API Reference](/docs/midnight/midnight-setup/api) for all available methods


# Wallet Integration
URL: /midnight/midnight-setup/wallet

Connect to Lace Beta Wallet for transaction signing and state management

***

title: "Wallet Integration"
description: "Connect to Lace Beta Wallet for transaction signing and state management"
---------------------------------------------------------------------------------------

The Lace Beta Wallet is the primary wallet for Midnight Network. This guide shows you how to connect, manage wallet state, and handle transactions in your application.

## Overview

The Lace wallet integration provides:

| Feature                   | Description                                  |
| ------------------------- | -------------------------------------------- |
| **Connect/Disconnect**    | Establish and terminate wallet connections   |
| **State management**      | Access wallet address, keys, and balances    |
| **Transaction signing**   | Sign and submit transactions to the network  |
| **Service configuration** | Get network endpoints for indexer and prover |

## Quick start

Check for wallet availability and connect:

```typescript
// Check if Lace wallet is available
const wallet = window.midnight?.mnLace;
if (!wallet) {
  throw new Error("Please install Lace Beta Wallet for Midnight Network");
}

// Enable the wallet and get API
const walletAPI = await wallet.enable();

// Get wallet state and service URIs
const walletState = await walletAPI.state();
const uris = await wallet.serviceUriConfig();

console.log("Connected:", walletState.address);
```

## Wallet methods reference

| Method                                   | When to use                                     |
| ---------------------------------------- | ----------------------------------------------- |
| `wallet.enable()`                        | Connect to the wallet and get the API interface |
| `walletAPI.state()`                      | Retrieve current address, keys, and balance     |
| `wallet.serviceUriConfig()`              | Get network service URLs (indexer, prover)      |
| `wallet.disconnect()`                    | End the wallet session                          |
| `walletAPI.balanceAndProveTransaction()` | Balance and prove a transaction                 |
| `walletAPI.submitTransaction()`          | Submit a signed transaction to the network      |

## React wallet hook

Create a reusable hook for wallet management in React applications:

```typescript
import { useState, useCallback } from 'react';

interface WalletState {
  state: {
    address: string;
    coinPublicKey: string;
    encryptionPublicKey: string;
  };
  uris: {
    indexerUri: string;
    indexerWsUri: string;
    proverServerUri: string;
  };
  walletAPI: {
    balanceAndProveTransaction: (tx: unknown, newCoins: unknown) => Promise<unknown>;
    submitTransaction: (tx: unknown) => Promise<unknown>;
  };
}

export function useMidnightWallet() {
  const [walletState, setWalletState] = useState<WalletState | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const connectWallet = useCallback(async () => {
    setIsLoading(true);
    setError(null);

    try {
      const wallet = window.midnight?.mnLace;
      if (!wallet) {
        throw new Error("Please install Lace Beta Wallet for Midnight Network");
      }

      const walletAPI = await wallet.enable();
      const state = await walletAPI.state();
      const uris = await wallet.serviceUriConfig();

      setWalletState({ state, uris, walletAPI });
      setIsConnected(true);
    } catch (err) {
      const message = err instanceof Error ? err.message : "Connection failed";
      setError(message);
      throw err;
    } finally {
      setIsLoading(false);
    }
  }, []);

  const disconnectWallet = useCallback(async () => {
    try {
      const wallet = window.midnight?.mnLace;
      if (wallet) {
        await wallet.disconnect();
        setWalletState(null);
        setIsConnected(false);
        setError(null);
      }
    } catch (err) {
      const message = err instanceof Error ? err.message : "Disconnect failed";
      setError(message);
    }
  }, []);

  return {
    connectWallet,
    disconnectWallet,
    walletState,
    isConnected,
    isLoading,
    error,
  };
}
```

## Use the wallet hook

Implement wallet connection in a React component:

```typescript
import { useMidnightWallet } from './hooks/useMidnightWallet';

function WalletConnect() {
  const {
    connectWallet,
    disconnectWallet,
    walletState,
    isConnected,
    isLoading,
    error,
  } = useMidnightWallet();

  if (error) {
    return (
      <div className="error">
        <p>Error: {error}</p>
        <button onClick={connectWallet}>Try Again</button>
      </div>
    );
  }

  if (isConnected) {
    return (
      <div>
        <p>Connected: {walletState?.state?.address}</p>
        <button onClick={disconnectWallet}>Disconnect</button>
      </div>
    );
  }

  return (
    <button onClick={connectWallet} disabled={isLoading}>
      {isLoading ? 'Connecting...' : 'Connect Wallet'}
    </button>
  );
}
```

## Configure providers with wallet

Set up the complete provider configuration using wallet credentials:

```typescript
import { FetchZkConfigProvider } from "@midnight-ntwrk/midnight-js-fetch-zk-config-provider";
import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
import type { MidnightSetupContractProviders } from "@meshsdk/midnight-setup";

export async function setupProviders(): Promise<MidnightSetupContractProviders> {
  const wallet = window.midnight?.mnLace;
  if (!wallet) {
    throw new Error("Please install Lace Beta Wallet for Midnight Network");
  }

  const walletAPI = await wallet.enable();
  const walletState = await walletAPI.state();
  const uris = await wallet.serviceUriConfig();

  return {
    privateStateProvider: levelPrivateStateProvider({
      privateStateStoreName: "my-dapp-state",
    }),
    zkConfigProvider: new FetchZkConfigProvider(
      window.location.origin,
      fetch.bind(window),
    ),
    proofProvider: httpClientProofProvider(uris.proverServerUri),
    publicDataProvider: indexerPublicDataProvider(
      uris.indexerUri,
      uris.indexerWsUri,
    ),
    walletProvider: {
      coinPublicKey: walletState.coinPublicKey,
      encryptionPublicKey: walletState.encryptionPublicKey,
      balanceTx: (tx, newCoins) => {
        return walletAPI.balanceAndProveTransaction(tx, newCoins);
      },
    },
    midnightProvider: {
      submitTx: (tx) => {
        return walletAPI.submitTransaction(tx);
      },
    },
  };
}
```

## Handle wallet errors

Implement robust error handling for common wallet issues:

```typescript
function handleWalletError(error: Error): string {
  const message = error.message;

  if (message.includes("install Lace Beta Wallet")) {
    return "Please install the Lace Beta Wallet extension";
  }

  if (message.includes("User rejected")) {
    return "You rejected the connection request";
  }

  if (message.includes("Insufficient funds")) {
    return "Your wallet has insufficient funds for this transaction";
  }

  if (message.includes("disconnected")) {
    return "Wallet disconnected. Please reconnect.";
  }

  return "An unexpected wallet error occurred. Please try again.";
}

// Usage in your component
async function handleConnect() {
  try {
    await connectWallet();
    console.log("Wallet connected successfully");
  } catch (error) {
    const userMessage = handleWalletError(error as Error);
    showNotification(userMessage, "error");
  }
}
```

## Complete example

Here is a full working example combining wallet connection with contract deployment:

```typescript
import { useState } from 'react';
import { MidnightSetupAPI } from '@meshsdk/midnight-setup';
import { useMidnightWallet } from './hooks/useMidnightWallet';
import { setupProviders } from './providers';

function MidnightDApp() {
  const { connectWallet, disconnectWallet, isConnected, isLoading, error } = useMidnightWallet();
  const [contractApi, setContractApi] = useState<MidnightSetupAPI | null>(null);
  const [contractState, setContractState] = useState<unknown>(null);

  async function handleDeploy() {
    if (!isConnected) {
      alert("Please connect your wallet first");
      return;
    }

    try {
      const providers = await setupProviders();
      const contractInstance = new MyContract({});
      const api = await MidnightSetupAPI.deployContract(providers, contractInstance);

      setContractApi(api);
      console.log("Deployed at:", api.deployedContractAddress);
    } catch (err) {
      console.error("Deployment failed:", err);
    }
  }

  async function handleGetState() {
    if (!contractApi) return;

    const state = await contractApi.getContractState();
    setContractState(state);
  }

  return (
    <div>
      <h1>Midnight Network dApp</h1>

      {error && <p className="error">{error}</p>}

      <section>
        <h2>1. Connect Wallet</h2>
        {isConnected ? (
          <button onClick={disconnectWallet}>Disconnect</button>
        ) : (
          <button onClick={connectWallet} disabled={isLoading}>
            {isLoading ? "Connecting..." : "Connect Wallet"}
          </button>
        )}
      </section>

      <section>
        <h2>2. Deploy Contract</h2>
        <button onClick={handleDeploy} disabled={!isConnected}>
          Deploy Contract
        </button>
      </section>

      {contractApi && (
        <section>
          <h2>3. Read Contract State</h2>
          <button onClick={handleGetState}>Get State</button>
          {contractState && (
            <pre>{JSON.stringify(contractState, null, 2)}</pre>
          )}
        </section>
      )}
    </div>
  );
}

export default MidnightDApp;
```

## Troubleshooting

### Wallet not detected

**Problem**: `window.midnight?.mnLace` is undefined.

**Solutions**:

1. Install the [Lace Beta Wallet](https://chromewebstore.google.com/detail/lace-midnight-preview/hgeekaiplokcnmakghbdfbgnlfheichg)
2. Refresh the page after installation
3. Ensure you are using a supported browser (Chrome, Brave)

### Connection rejected

**Problem**: User rejected the connection request.

**Solution**: Prompt the user to try again and explain why wallet access is needed.

### Transaction signing fails

**Problem**: `balanceAndProveTransaction` throws an error.

**Solutions**:

1. Check that the wallet has sufficient funds
2. Verify the transaction parameters are valid
3. Ensure the prover service is accessible

## Next steps

* [API Reference](/docs/midnight/midnight-setup/api) - Complete method documentation
* [Examples](/docs/midnight/midnight-setup/examples) - More code samples
* [Getting Started](/docs/midnight/midnight-setup/getting-started) - Project setup guide

## Related resources

* [Lace Beta Wallet](https://chromewebstore.google.com/detail/lace-midnight-preview/hgeekaiplokcnmakghbdfbgnlfheichg)
* [Midnight Network Documentation](https://docs.midnight.network/)


# Lesson 1: Hello World
URL: /resources/cardano-course/01-wallet-send-lovelace

Install Mesh SDK, create a wallet, and send your first Cardano transaction.

***

title: "Lesson 1: Hello World"
description: "Install Mesh SDK, create a wallet, and send your first Cardano transaction."
------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Set up a Node.js project with the Mesh SDK
* Generate a new wallet with mnemonic phrases
* Retrieve your wallet address
* Send lovelace (ADA) to another address
* Understand UTXOs and transaction building basics

## Prerequisites

Before starting this lesson, ensure you have:

* **Node.js v20+** installed (<Link href="https://github.com/nvm-sh/nvm">nvm recommended for version management</Link>)
* A code editor (VS Code recommended)
* Basic familiarity with TypeScript/JavaScript

## Step 1: Create Your Project

Create a new directory and initialize your project with a `package.json` file.

```bash
mkdir mesh-hello-world
cd mesh-hello-world
```

Create a `package.json` file with ES module support:

```json
{
  "type": "module",
  "dependencies": {},
  "scripts": {}
}
```

## Step 2: Install the Mesh SDK

Install the Mesh SDK core package:

```bash
npm install @meshsdk/core
```

Your `package.json` now looks like this:

```json
{
  "type": "module",
  "dependencies": {
    "@meshsdk/core": "^1.9.0"
  },
  "scripts": {}
}
```

## Step 3: Generate a Wallet

The `MeshCardanoHeadlessWallet` class provides methods to create wallets, generate mnemonic phrases, and retrieve addresses.

### Key Concepts

* **Mnemonic phrase**: A set of 24 words that can recover your wallet. Keep this secure.
* **Network ID**: Use `0` for preprod testnet, `1` for mainnet.
* **Change address**: The address where remaining funds return after a transaction.

### Create the Mnemonic Script

Create a new file called `mnemonic.ts`:

```ts
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Generate new mnemonic phrases for your wallet
const mnemonic = MeshCardanoHeadlessWallet.brew();
console.log("Your mnemonic phrases are:", mnemonic);

// Initialize the wallet with the mnemonic key
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0, // preprod testnet
  walletAddressType: AddressType.Base,
  mnemonic: mnemonic as string[],
});

// Get the wallet address
const address = await wallet.getChangeAddressBech32();
console.log("Your wallet address is:", address);
```

### Run the Script

Add a script to your `package.json`:

```json
{
  "type": "module",
  "dependencies": {
    "@meshsdk/core": "^1.9.0"
  },
  "scripts": {
    "mnemonic": "node mnemonic.ts"
  }
}
```

Run the script:

```bash
npm run mnemonic
```

You see output similar to:

```bash
Your mnemonic phrases are: [
  'access',  'spawn',   'taxi',
  'prefer',  'fortune', 'sword',
  'nerve',   'price',   'valid',
  'panther', 'sure',    'hello',
  'layer',   'try',     'grace',
  'seven',   'fossil',  'voice',
  'tobacco', 'circle',  'measure',
  'solar',   'pride',   'together'
]
Your wallet address is: addr_test1qptwuv6dl863u3k93mjrg0hgs0ahl08lfhsudxrwshcsx59cjxatme29s6cl7drjceknunry049shu9eudnsjvwqq9qsuem66d
```

**Important**: Save your mnemonic phrase securely. You need it for the next steps.

## Step 4: Fund Your Wallet

Before sending transactions, you need test ADA (lovelace) in your wallet.

1. Go to the <Link href="https://docs.cardano.org/cardano-testnets/tools/faucet">Cardano Preprod Testnet Faucet</Link>
2. Paste your wallet address from the previous step
3. Click "Request funds"
4. Wait a few minutes for the funds to arrive

## Step 5: Get a Blockfrost API Key

Mesh uses Blockfrost to interact with the Cardano blockchain for fetching UTXOs and submitting transactions.

1. Sign up at <Link href="https://blockfrost.io/">Blockfrost</Link>
2. Create a new project for the **Preprod** network
3. Copy your API key (starts with `preprod`)

## Step 6: Send Lovelace

Now you can send lovelace to another address using `MeshTxBuilder`.

### Key Concepts

* **UTXO (Unspent Transaction Output)**: Cardano uses a UTXO model where each transaction consumes existing outputs and creates new ones.
* **Lovelace**: The smallest unit of ADA. 1 ADA = 1,000,000 lovelace.
* **Change address**: Where leftover funds go after covering the transaction amount and fees.

### Create the Send Script

Create a new file called `send-lovelace.ts`:

```ts
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Set up the blockchain provider with your API key
const provider = new BlockfrostProvider("YOUR_BLOCKFROST_API_KEY");

// Initialize the wallet with your mnemonic
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: [
    "your", "mnemonic", "phrases", "here",
    // ... all 24 words
  ],
});

// Get wallet data needed for the transaction
const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

// Create the transaction
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true, // Prints the transaction body for debugging
});

const unsignedTx = await txBuilder
  .txOut(
    "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
    [{ unit: "lovelace", quantity: "1500000" }]
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit the transaction
const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Transaction hash:", txHash);
```

### Configuration

Replace these values in the script:

| Placeholder               | Description                     |
| ------------------------- | ------------------------------- |
| `YOUR_BLOCKFROST_API_KEY` | Your Blockfrost preprod API key |
| `your`, `mnemonic`, ...   | Your 24-word mnemonic phrase    |
| Recipient address         | The address to send lovelace to |

### Run the Transaction

Add the script to your `package.json`:

```json
{
  "type": "module",
  "dependencies": {
    "@meshsdk/core": "^1.9.0"
  },
  "scripts": {
    "mnemonic": "node mnemonic.ts",
    "send-lovelace": "node send-lovelace.ts"
  }
}
```

Run it:

```bash
npm run send-lovelace
```

You see output showing the transaction body before and after coin selection, followed by the transaction hash:

```bash
Transaction hash: 62a825c607e4ca5766325c2fccd7ee98313ff81b7e8a4af67eac421b0f0866ff
```

## Complete Working Example

Here is the full project structure:

```
mesh-hello-world/
  package.json
  mnemonic.ts
  send-lovelace.ts
```

### package.json

```json
{
  "type": "module",
  "dependencies": {
    "@meshsdk/core": "^1.9.0"
  },
  "scripts": {
    "mnemonic": "node mnemonic.ts",
    "send-lovelace": "node send-lovelace.ts"
  }
}
```

### mnemonic.ts

```ts
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const mnemonic = MeshCardanoHeadlessWallet.brew();
console.log("Your mnemonic phrases are:", mnemonic);

const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  mnemonic: mnemonic as string[],
});

const address = await wallet.getChangeAddressBech32();
console.log("Your wallet address is:", address);
```

### send-lovelace.ts

```ts
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("YOUR_BLOCKFROST_API_KEY");

const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "24", "word", "mnemonic", "phrase", "here"],
});

const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const unsignedTx = await txBuilder
  .txOut(
    "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9",
    [{ unit: "lovelace", quantity: "1500000" }]
  )
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Transaction hash:", txHash);
```

## Key Concepts Explained

### MeshCardanoHeadlessWallet

The `MeshCardanoHeadlessWallet` class manages your wallet:

| Method                             | Description                                       |
| ---------------------------------- | ------------------------------------------------- |
| `MeshCardanoHeadlessWallet.brew()` | Generates a new 24-word mnemonic                  |
| `getChangeAddressBech32()`         | Returns the wallet's receiving address            |
| `getUtxosMesh()`                   | Fetches all UTXOs owned by the wallet             |
| `signTx(tx, partialSign)`          | Signs a transaction with the wallet's private key |
| `submitTx(tx)`                     | Submits a signed transaction to the network       |

### MeshTxBuilder

The `MeshTxBuilder` class constructs transactions:

| Method                   | Description                                 |
| ------------------------ | ------------------------------------------- |
| `txOut(address, assets)` | Adds an output to send assets to an address |
| `changeAddress(address)` | Sets where remaining funds go               |
| `selectUtxosFrom(utxos)` | Provides UTXOs for coin selection           |
| `complete()`             | Finalizes and balances the transaction      |

## Exercises

1. **Send to multiple addresses**: Modify `send-lovelace.ts` to send lovelace to two different addresses in a single transaction. Use multiple `txOut()` calls.

2. **Check your balance**: Before and after sending, use `wallet.getUtxos()` to calculate your total balance.

3. **Explore the transaction**: Copy your transaction hash and view it on <Link href="https://preprod.cardanoscan.io/">CardanoScan Preprod</Link>.

## Next Steps

You have successfully:

* Created a Cardano wallet
* Funded it with test ADA
* Sent your first transaction

In the next lesson, you learn how to build <Link href="/resources/cardano-course/02-multisig">multi-signature transactions</Link> that require approval from multiple parties.

## Related Links

* <Link href="/apis/wallets/meshwallet">MeshWallet API Reference</Link>
* <Link href="/apis/txbuilder">MeshTxBuilder API Reference</Link>
* <Link href="https://github.com/cardanobuilders/cardanobuilders.github.io/tree/main/codes/course-hello-cardano/01-wallet-send-lovelace">Source Code on GitHub</Link>


# Lesson 2: Multi-signature Transactions
URL: /resources/cardano-course/02-multisig

Build multi-signature transactions on Cardano to mint tokens with collaborative signing.

***

title: "Lesson 2: Multi-signature Transactions"
description: "Build multi-signature transactions on Cardano to mint tokens with collaborative signing."
-------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will:

* Understand how multi-signature transactions work on Cardano
* Set up a Next.js application with Mesh React components
* Create a native minting script with multiple signing conditions
* Build and execute a multi-sig token minting transaction
* Connect a CIP-30 browser wallet using the CardanoWallet component

## Prerequisites

Before you begin, make sure you have:

* Completed <Link href="/resources/cardano-course/01-wallet-send-lovelace">Lesson 1: Hello World</Link>
* A CIP-30 compatible wallet extension installed (<Link href="https://developers.cardano.org/showcase/?tags=wallet">choose one here</Link>)
* Your wallet restored with the mnemonic from Lesson 1
* A Blockfrost API key for preprod
* Node.js 18+ installed on your machine

## Key Concepts

### What is a Multi-signature Transaction?

A multi-signature (multi-sig) transaction requires more than one party to sign before you can submit it to the blockchain. Think of it like a joint bank account where both account holders must approve withdrawals.

Multi-sig transactions can require:

* Two or more wallet signatures
* Script conditions (time locks, etc.)
* A combination of both

### Use Cases

| Use Case              | Description                                           |
| --------------------- | ----------------------------------------------------- |
| **Shared treasuries** | Organizations require multiple approvals for spending |
| **Escrow services**   | Release funds only when both parties agree            |
| **Token policies**    | Control minting through multiple administrators       |

### Native Script Types

| Script Type | Description                                      |
| ----------- | ------------------------------------------------ |
| `all`       | All nested conditions must be satisfied          |
| `any`       | At least one condition must be satisfied         |
| `atLeast`   | A minimum number of conditions must be satisfied |
| `sig`       | Requires a signature from a specific key hash    |
| `before`    | Valid only before a specific slot                |
| `after`     | Valid only after a specific slot                 |

## Step 1: Create a Next.js Project

Create a new Next.js application with TypeScript and Tailwind CSS.

```bash
npx create-next-app@latest --typescript mesh-multisig
```

When prompted, select these options:

```
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? Yes
Would you like to use App Router? No
Would you like to use Turbopack for next dev? No
Would you like to customize the import alias? No
```

Navigate to the project and install Mesh packages:

```bash
cd mesh-multisig
npm install @meshsdk/core @meshsdk/react
```

## Step 2: Configure MeshProvider

Wrap your application with `MeshProvider` to enable React hooks for wallet interaction.

Replace the contents of `src/pages/_app.tsx`:

```tsx
import "@/styles/globals.css";
import type { AppProps } from "next/app";
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
```

## Step 3: Add Wallet Connection

Add the `CardanoWallet` component to connect browser wallets.

Replace the contents of `src/pages/index.tsx`:

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

export default function Home() {
  const { wallet, connected } = useWallet();

  return (
    <div className="min-h-screen flex flex-col items-center justify-center p-8">
      <h1 className="text-2xl font-bold mb-8">Multi-sig Token Minting</h1>
      <CardanoWallet isDark={true} />
      {connected && (
        <p className="mt-4 text-green-600">Wallet connected!</p>
      )}
    </div>
  );
}
```

Start the development server:

```bash
npm run dev
```

Visit `http://localhost:3000` and test connecting your wallet.

## Step 4: Define the Minting Script

Add the minting configuration to your `index.tsx` file, before the `Home` component:

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";
import {
  BlockfrostProvider,
  MeshTxBuilder,
  ForgeScript,
  NativeScript,
  deserializeAddress,
  resolveScriptHash,
  stringToHex,
} from "@meshsdk/core";
import type { UTxO } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

// Configuration - Replace with your Blockfrost API key
const provider = new BlockfrostProvider("YOUR_BLOCKFROST_API_KEY");

const demoAssetMetadata = {
  name: "Mesh Token",
  image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
  mediaType: "image/jpg",
  description: "This NFT was minted by Mesh (https://meshjs.dev/).",
};

// Replace with your minting wallet mnemonic
const mintingWallet = ["your", "mnemonic", "phrases", "here"];
```

### Understand Native Scripts

A native script defines who can mint tokens and under what conditions:

```tsx
const nativeScript: NativeScript = {
  type: "all",      // All conditions must be met
  scripts: [
    {
      type: "before",
      slot: "99999999",  // Must mint before this slot
    },
    {
      type: "sig",
      keyHash: keyHash,  // Must be signed by this key
    },
  ],
};
```

## Step 5: Build the Minting Transaction

Create a function that builds the multi-sig minting transaction:

```tsx
async function buildMintTx(inputs: UTxO[], changeAddress: string) {
  // Initialize the minting wallet
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    mnemonic: mintingWallet,
  });

  // Get the minting wallet's public key hash
  const { pubKeyHash: keyHash } = deserializeAddress(
    await wallet.getChangeAddressBech32()
  );

  // Create the native script with time lock and signature requirement
  const nativeScript: NativeScript = {
    type: "all",
    scripts: [
      {
        type: "before",
        slot: "99999999",
      },
      {
        type: "sig",
        keyHash: keyHash,
      },
    ],
  };
  const forgingScript = ForgeScript.fromNativeScript(nativeScript);

  // Derive policy ID and set up metadata
  const policyId = resolveScriptHash(forgingScript);
  const tokenName = "MeshToken";
  const tokenNameHex = stringToHex(tokenName);
  const metadata = { [policyId]: { [tokenName]: { ...demoAssetMetadata } } };

  // Build the transaction
  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  const unsignedTx = await txBuilder
    .mint("1", policyId, tokenNameHex)
    .mintingScript(forgingScript)
    .metadataValue(721, metadata)
    .changeAddress(changeAddress)
    .invalidHereafter(99999999)
    .requiredSignerHash(keyHash)
    .selectUtxosFrom(inputs)
    .complete();

  // Sign with the minting wallet (first signature)
  const signedTx = await wallet.signTx(unsignedTx, true);
  return signedTx;
}
```

### Transaction Builder Methods

| Method                                | Description                          |
| ------------------------------------- | ------------------------------------ |
| `mint(quantity, policyId, tokenName)` | Specifies the token to mint          |
| `mintingScript(script)`               | Attaches the minting policy script   |
| `metadataValue(label, metadata)`      | Adds CIP-25 NFT metadata (label 721) |
| `invalidHereafter(slot)`              | Sets transaction expiry slot         |
| `requiredSignerHash(keyHash)`         | Declares a required signer           |
| `selectUtxosFrom(utxos)`              | Provides UTXOs for fees              |

## Step 6: Execute the Transaction

Add the minting function that coordinates both signatures:

```tsx
async function mint() {
  if (!connected) {
    alert("Please connect your wallet first");
    return;
  }

  try {
    // Get UTXOs and change address from the connected browser wallet
    const inputs = await wallet.getUtxos();
    const changeAddress = await wallet.getChangeAddress();

    // Build transaction and get first signature from minting wallet
    const partiallySignedTx = await buildMintTx(inputs, changeAddress);

    // Add second signature from the connected browser wallet
    const fullySignedTx = await wallet.signTx(partiallySignedTx, true);

    // Submit the transaction
    const txHash = await wallet.submitTx(fullySignedTx);
    console.log("Transaction hash:", txHash);
    alert(`Success! Transaction hash: ${txHash}`);
  } catch (error) {
    console.error("Minting failed:", error);
    alert("Minting failed. Check console for details.");
  }
}
```

### How Multi-sig Works

1. **First signature**: The minting wallet signs the transaction (satisfies the `sig` condition in the native script)
2. **Second signature**: The browser wallet signs (provides the fee payment authorization)
3. **Submission**: Submit the fully signed transaction to the network

The `signTx(tx, true)` parameter `true` indicates partial signing, allowing you to add additional signatures.

## Step 7: Add the Mint Button

Update your component to include the mint functionality:

```tsx
export default function Home() {
  const { wallet, connected } = useWallet();

  async function mint() {
    if (!connected) {
      alert("Please connect your wallet first");
      return;
    }

    try {
      const inputs = await wallet.getUtxos();
      const changeAddress = await wallet.getChangeAddress();
      const partiallySignedTx = await buildMintTx(inputs, changeAddress);
      const fullySignedTx = await wallet.signTx(partiallySignedTx, true);
      const txHash = await wallet.submitTx(fullySignedTx);
      console.log("Transaction hash:", txHash);
      alert(`Success! Transaction hash: ${txHash}`);
    } catch (error) {
      console.error("Minting failed:", error);
      alert("Minting failed. Check console for details.");
    }
  }

  return (
    <div className="min-h-screen flex flex-col items-center justify-center p-8">
      <h1 className="text-2xl font-bold mb-8">Multi-sig Token Minting</h1>
      <CardanoWallet isDark={true} />
      {connected && (
        <div className="mt-8">
          <button
            onClick={mint}
            className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
          >
            Mint Token
          </button>
        </div>
      )}
    </div>
  );
}
```

## Complete Working Example

Here is the complete `src/pages/index.tsx` file:

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";
import {
  BlockfrostProvider,
  MeshTxBuilder,
  ForgeScript,
  NativeScript,
  deserializeAddress,
  resolveScriptHash,
  stringToHex,
} from "@meshsdk/core";
import type { UTxO } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("YOUR_BLOCKFROST_API_KEY");

const demoAssetMetadata = {
  name: "Mesh Token",
  image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
  mediaType: "image/jpg",
  description: "This NFT was minted by Mesh (https://meshjs.dev/).",
};

const mintingWallet = ["your", "mnemonic", "phrases", "here"];

async function buildMintTx(inputs: UTxO[], changeAddress: string) {
  const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
    networkId: 0,
    walletAddressType: AddressType.Base,
    mnemonic: mintingWallet,
  });

  const { pubKeyHash: keyHash } = deserializeAddress(
    await wallet.getChangeAddressBech32()
  );

  const nativeScript: NativeScript = {
    type: "all",
    scripts: [
      {
        type: "before",
        slot: "99999999",
      },
      {
        type: "sig",
        keyHash: keyHash,
      },
    ],
  };
  const forgingScript = ForgeScript.fromNativeScript(nativeScript);

  const policyId = resolveScriptHash(forgingScript);
  const tokenName = "MeshToken";
  const tokenNameHex = stringToHex(tokenName);
  const metadata = { [policyId]: { [tokenName]: { ...demoAssetMetadata } } };

  const txBuilder = new MeshTxBuilder({
    fetcher: provider,
    verbose: true,
  });

  const unsignedTx = await txBuilder
    .mint("1", policyId, tokenNameHex)
    .mintingScript(forgingScript)
    .metadataValue(721, metadata)
    .changeAddress(changeAddress)
    .invalidHereafter(99999999)
    .requiredSignerHash(keyHash)
    .selectUtxosFrom(inputs)
    .complete();

  const signedTx = await wallet.signTx(unsignedTx, true);
  return signedTx;
}

export default function Home() {
  const { wallet, connected } = useWallet();

  async function mint() {
    if (!connected) {
      alert("Please connect your wallet first");
      return;
    }

    try {
      const inputs = await wallet.getUtxos();
      const changeAddress = await wallet.getChangeAddress();
      const partiallySignedTx = await buildMintTx(inputs, changeAddress);
      const fullySignedTx = await wallet.signTx(partiallySignedTx, true);
      const txHash = await wallet.submitTx(fullySignedTx);
      console.log("Transaction hash:", txHash);
      alert(`Success! Transaction hash: ${txHash}`);
    } catch (error) {
      console.error("Minting failed:", error);
      alert("Minting failed. Check console for details.");
    }
  }

  return (
    <div className="min-h-screen flex flex-col items-center justify-center p-8">
      <h1 className="text-2xl font-bold mb-8">Multi-sig Token Minting</h1>
      <CardanoWallet isDark={true} />
      {connected && (
        <div className="mt-8">
          <button
            onClick={mint}
            className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
          >
            Mint Token
          </button>
        </div>
      )}
    </div>
  );
}
```

## Key Concepts Explained

### ForgeScript

`ForgeScript` converts a native script into a format usable by the transaction builder:

```tsx
const forgingScript = ForgeScript.fromNativeScript(nativeScript);
```

### Policy ID

The policy ID is a hash of the minting script. All tokens minted under this policy share the same policy ID:

```tsx
const policyId = resolveScriptHash(forgingScript);
```

### CIP-25 Metadata

Label 721 follows the CIP-25 standard for NFT metadata:

```tsx
const metadata = {
  [policyId]: {
    [tokenName]: {
      name: "Token Name",
      image: "ipfs://...",
      // ... other properties
    }
  }
};
```

## Exercises

1. **2-of-3 Multi-sig**: Create a native script that requires 2 out of 3 possible signers to approve minting. Use the `atLeast` script type.

2. **Time-locked minting**: Modify the script to only allow minting between two specific dates using both `before` and `after` conditions.

3. **Display minted token**: After successful minting, query the wallet's assets and display the newly minted token in the UI.

## Next Steps

You have successfully:

* Built a Next.js app with Mesh wallet integration
* Created a multi-signature minting policy
* Minted a token requiring two signatures

In the next lesson, you learn the fundamentals of <Link href="/resources/cardano-course/03-aiken-contracts">Aiken smart contracts</Link> for more complex on-chain logic.

## Related Links

* <Link href="/apis/react/wallet-hooks">Mesh React Wallet Hooks</Link>
* <Link href="/apis/txbuilder">MeshTxBuilder API Reference</Link>
* <Link href="https://cips.cardano.org/cips/cip25/">CIP-25: NFT Metadata Standard</Link>
* <Link href="https://github.com/cardanobuilders/cardanobuilders.github.io/tree/main/codes/course-hello-cardano/02-multisig">Source Code on GitHub</Link>


# Lesson 3: Aiken Contracts
URL: /resources/cardano-course/03-aiken-contracts

Introduction to Aiken smart contract development on Cardano.

***

title: "Lesson 3: Aiken Contracts"
description: "Introduction to Aiken smart contract development on Cardano."
---------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Understand how Cardano validators differ from traditional smart contracts
* Explain the Transaction structure and its key components
* Identify and create different types of scripts (minting, spending, withdrawing)
* Write basic Aiken validators with parameters and redeemers
* Use the Mesh CLI to scaffold an Aiken project

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/02-multisig">Lesson 2: Multi-signature Transactions</Link>
* Aiken installed on your system (follow the <Link href="https://aiken-lang.org/installation-instructions">official installation guide</Link>)
* Basic understanding of functional programming concepts

## Key Concepts

### Validators vs Smart Contracts

Cardano contracts work differently from smart contracts on other blockchains. Instead of executing arbitrary code, Cardano uses **validators** - pure functions that return `True` or `False` to approve or reject transactions.

A validator examines the transaction context and decides whether the transaction is valid. If the validator returns `True`, the transaction proceeds. If it returns `False`, the transaction fails.

### Why Validators?

| Traditional Smart Contracts | Cardano Validators           |
| --------------------------- | ---------------------------- |
| Execute arbitrary code      | Return only True/False       |
| State stored on-chain       | State in UTXOs via datums    |
| Sequential execution        | Parallel validation possible |
| Unpredictable costs         | Deterministic costs          |

## Step 1: Set Up an Aiken Project

Use the Mesh CLI to create a new Aiken project with a template structure.

```bash
npx meshjs 03-aiken-contracts
```

Select the **Aiken** template when prompted.

The command creates this structure:

```
03-aiken-contracts/
  aiken-workspace/    # Main Aiken project (used in lessons)
  mesh/               # Equivalent Mesh off-chain code
```

Navigate to the Aiken workspace:

```bash
cd 03-aiken-contracts/aiken-workspace
```

### Optional: Install Cardano-Bar Extension

If you use VS Code, install the <Link href="https://marketplace.visualstudio.com/items/?itemName=sidan-lab.cardano-bar-vscode">Cardano-Bar extension</Link> for helpful code snippets.

## Step 2: Understand the Transaction Structure

Every Aiken validator receives a `Transaction` object containing all information about the current transaction. Understanding this structure is essential for writing validators.

Refer to the <Link href="https://aiken-lang.github.io/stdlib/cardano/transaction.html#Transaction">Aiken standard library documentation</Link> for complete type definitions.

### Key Transaction Fields

| Field               | Type            | Description                         |
| ------------------- | --------------- | ----------------------------------- |
| `inputs`            | `List<Input>`   | UTXOs being spent                   |
| `outputs`           | `List<Output>`  | UTXOs being created                 |
| `reference_inputs`  | `List<Input>`   | UTXOs referenced but not spent      |
| `mint`              | `Value`         | Assets being minted or burned       |
| `extra_signatories` | `List<Hash>`    | Required signers' public key hashes |
| `validity_range`    | `ValidityRange` | Time bounds for the transaction     |

### Inputs and Outputs

Cardano transactions consume existing UTXOs (inputs) and create new UTXOs (outputs).

```
Input {
  output_reference: OutputReference,  // Points to previous tx output
  output: Output                      // The actual UTXO data
}

Output {
  address: Address,                   // Destination address
  value: Value,                       // ADA and tokens
  datum: Datum,                       // Optional data attachment
}
```

Common validation patterns:

* Check if an input spends from a specific address
* Check if an input contains a specific asset
* Check if an output sends to a specific address
* Check if datum contains expected values

### Reference Inputs

`reference_inputs` are UTXOs included in the transaction for reading only - they are not spent. Use these to access data (like oracle prices) without consuming the UTXO.

### Mint Field

The `mint` field lists assets being minted (positive quantities) or burned (negative quantities) in this transaction.

### Extra Signatories

`extra_signatories` contains public key hashes that must sign the transaction. Use this to enforce authorization requirements.

### Validity Range

`validity_range` specifies when the transaction is valid. Use this for time-locked contracts.

## Step 3: Create a Minting Script

Minting scripts validate token creation and burning. The script runs whenever assets under its policy ID are minted or burned.

Create a file `validators/mint.ak`:

```rs
use cardano/assets.{PolicyId}
use cardano/transaction.{Transaction, placeholder}

validator always_succeed {
  mint(_redeemer: Data, _policy_id: PolicyId, _tx: Transaction) {
    True
  }

  else(_) {
    fail @"unsupported purpose"
  }
}

test test_always_succeed_minting_policy() {
  let data = Void
  always_succeed.mint(data, #"", placeholder)
}
```

### Understanding the Code

| Element                    | Description                                  |
| -------------------------- | -------------------------------------------- |
| `validator always_succeed` | Declares a validator named `always_succeed`  |
| `mint(...)`                | Handler for minting/burning operations       |
| `_redeemer: Data`          | User-provided data (underscore means unused) |
| `_policy_id: PolicyId`     | The policy ID being validated                |
| `_tx: Transaction`         | The full transaction context                 |
| `else(_)`                  | Fallback for unsupported script purposes     |

Build and test:

```bash
aiken build
aiken check
```

### Add Parameters

Make the script more useful by requiring a specific signature:

```rs
use aiken/crypto.{VerificationKeyHash}
use cardano/assets.{PolicyId}
use cardano/transaction.{Transaction}
use vodka/extra/list.{key_signed}

validator minting_policy(owner_vkey: VerificationKeyHash) {
  mint(_redeemer: Data, _policy_id: PolicyId, tx: Transaction) {
    key_signed(tx.extra_signatories, owner_vkey)
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

The `owner_vkey` parameter is baked into the compiled script at deployment time, creating a unique policy ID for each owner.

### Add Redeemer Logic

Extend the policy to handle different actions:

```rs
use aiken/crypto.{VerificationKeyHash}
use cardano/assets.{PolicyId}
use cardano/transaction.{Transaction}
use vodka/extra/list.{key_signed}
use vodka/extra/validity_range.{valid_before}
use vodka/extra/value.{check_policy_only_burn}

pub type MyRedeemer {
  MintToken
  BurnToken
}

validator minting_policy(
  owner_vkey: VerificationKeyHash,
  minting_deadline: Int,
) {
  mint(redeemer: MyRedeemer, policy_id: PolicyId, tx: Transaction) {
    when redeemer is {
      MintToken -> {
        let before_deadline = valid_before(tx.validity_range, minting_deadline)
        let is_owner_signed = key_signed(tx.extra_signatories, owner_vkey)
        before_deadline? && is_owner_signed?
      }
      BurnToken -> check_policy_only_burn(tx.mint, policy_id)
    }
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

### Redeemer Types

| Redeemer    | Conditions                                  |
| ----------- | ------------------------------------------- |
| `MintToken` | Must be before deadline AND signed by owner |
| `BurnToken` | Only burning allowed (no new minting)       |

The `?` operator after boolean expressions enables tracing - if validation fails, it reports which condition failed.

## Step 4: Create a Spending Script

Spending scripts validate when UTXOs at a script address are spent.

Create a file `validators/spend.ak`:

```rs
use cardano/assets.{PolicyId}
use cardano/transaction.{OutputReference, Transaction}
use vodka/extra/list.{inputs_with_policy}

pub type Datum {
  oracle_nft: PolicyId,
}

validator hello_world {
  spend(
    datum_opt: Option<Datum>,
    _redeemer: Data,
    _input: OutputReference,
    tx: Transaction,
  ) {
    when datum_opt is {
      Some(datum) ->
        when inputs_with_policy(tx.reference_inputs, datum.oracle_nft) is {
          [_ref_input] -> True
          _ -> False
        }
      None -> False
    }
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

### Understanding Spending Scripts

| Parameter   | Description                                     |
| ----------- | ----------------------------------------------- |
| `datum_opt` | Optional datum attached to the UTXO being spent |
| `redeemer`  | User-provided data for this spend action        |
| `input`     | Reference to the UTXO being spent               |
| `tx`        | Full transaction context                        |

This example requires a reference input containing an "oracle NFT" to unlock funds.

### Common Datum Pattern: Oracle NFT

A common pattern uses an NFT as a "state thread token" to ensure UTXO uniqueness:

```rs
pub type Datum {
  oracle_nft: PolicyId,  // NFT that must be referenced
}
```

This pattern:

1. Creates a unique NFT (only one exists)
2. Stores the NFT at an oracle address with data in the datum
3. Requires referencing this UTXO to spend from the validator

## Step 5: Create a Withdrawal Script

Withdrawal scripts validate stake reward withdrawals and are commonly used for validation delegation (covered in Lesson 5).

Create a file `validators/withdraw.ak`:

```rs
use aiken/crypto.{VerificationKeyHash}
use cardano/address.{Credential, Script}
use cardano/certificate.{Certificate}
use cardano/transaction.{Transaction, placeholder}

validator always_succeed(_key_hash: VerificationKeyHash) {
  withdraw(_redeemer: Data, _credential: Credential, _tx: Transaction) {
    True
  }

  publish(_redeemer: Data, _certificate: Certificate, _tx: Transaction) {
    True
  }

  else(_) {
    fail @"unsupported purpose"
  }
}

test test_always_succeed_withdrawal_policy() {
  let data = Void
  always_succeed.withdraw("", data, Script(#""), placeholder)
}
```

### Withdrawal Script Requirements

All withdrawal scripts must include a `publish` handler because:

1. The script must be registered on-chain before use
2. Registration creates a certificate
3. The `publish` function validates registration/deregistration

### When to Use Withdrawal Scripts

Most users stake and withdraw using regular payment keys. However, dApps use withdrawal scripts to:

* Centralize validation logic across multiple validators
* Implement the "withdraw 0 trick" for efficient validation (see <Link href="/resources/cardano-course/05-avoid-redundant-validation">Lesson 5</Link>)

## Key Concepts Explained

### Script Types Summary

| Type        | Triggered When                        | Common Use                      |
| ----------- | ------------------------------------- | ------------------------------- |
| Minting     | Assets minted/burned under the policy | Token creation, NFT minting     |
| Spending    | UTXO at script address is spent       | Escrow, vesting, DeFi protocols |
| Withdrawing | Stake rewards withdrawn               | Validation delegation           |

### The `else` Handler

Every validator needs an `else` handler for unsupported purposes:

```rs
else(_) {
  fail @"unsupported purpose"
}
```

This prevents the script from being used for unintended operations.

### Vodka Library

The examples use <Link href="https://github.com/sidan-lab/vodka">vodka</Link>, a utility library for common Aiken operations:

* `key_signed`: Check if a key hash is in the signatories list
* `valid_before`: Check if transaction is valid before a time
* `inputs_with_policy`: Find inputs containing a specific policy
* `check_policy_only_burn`: Verify only burning occurs

## Exercises

1. **Extend the minting script**: Add a third redeemer action `TransferOwnership` that allows changing the owner key hash (hint: you need to track state).

2. **Time-bounded spending**: Create a spending script that only allows spending after a certain time stored in the datum.

3. **Multi-oracle validation**: Modify the spending script to require references to multiple oracle NFTs.

## Next Steps

You have learned:

* How Cardano validators work
* The Transaction structure and its components
* How to write minting, spending, and withdrawal scripts
* How to use parameters and redeemers

In the next lesson, you learn how to <Link href="/resources/cardano-course/04-contract-testing">test Aiken contracts</Link> using mock transactions.

## Related Links

* <Link href="https://aiken-lang.org/">Aiken Language Documentation</Link>
* <Link href="https://aiken-lang.github.io/stdlib/">Aiken Standard Library</Link>
* <Link href="https://app.andamio.io/course/db22e013578fcead6c2fed5446d61891ad31f3cb4955e88d980107e7">Andamio's AikenPBL Course</Link>
* <Link href="https://github.com/sidan-lab/vodka">Vodka Utility Library</Link>


# Lesson 4: Contract Testing
URL: /resources/cardano-course/04-contract-testing

Test Aiken smart contracts using mock transactions and the vodka testing library.

***

title: "Lesson 4: Contract Testing"
description: "Test Aiken smart contracts using mock transactions and the vodka testing library."
------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Write unit tests for Aiken validators
* Build mock transactions using the `mocktail` library
* Test success and failure cases systematically
* Use parameterized test cases for comprehensive coverage
* Understand the `expect` keyword and `?` tracing operator

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/03-aiken-contracts">Lesson 3: Aiken Contracts</Link>
* An Aiken project set up with validators
* The `vodka` library added to your project

## Key Concepts

### Why Test Contracts?

Smart contracts manage real value. Bugs can lead to:

* Locked funds that can never be retrieved
* Unauthorized spending
* Protocol exploits

Thorough testing catches issues before deployment.

### Testing Philosophy

Aiken validators are pure functions - given the same inputs, they always produce the same outputs. This makes them ideal for unit testing:

1. Create mock transaction data
2. Call the validator function
3. Assert the result is `True` or `False`

## Step 1: Create a Complex Contract

Build a withdrawal contract with two user actions: `ContinueCounting` and `StopCounting`.

### Requirements

| Action             | Conditions                                                                    |
| ------------------ | ----------------------------------------------------------------------------- |
| `ContinueCounting` | Owner signed, app not expired, state token carried forward, count incremented |
| `StopCounting`     | Owner signed, state thread token burned                                       |

### Define Types

```rs
use aiken/crypto.{VerificationKeyHash}
use cardano/address.{Address, Credential}
use cardano/assets.{PolicyId}
use cardano/certificate.{Certificate}
use cardano/transaction.{Transaction}

pub type OracleDatum {
  app_owner: VerificationKeyHash,
  app_expiry: Int,
  spending_validator_address: Address,
  state_thread_token_policy_id: PolicyId,
}

pub type SpendingValidatorDatum {
  count: Int,
}

pub type MyRedeemer {
  ContinueCounting
  StopCounting
}
```

### Implement the Validator

```rs
use cocktail.{
  input_inline_datum, inputs_at_with_policy, inputs_with_policy, key_signed,
  output_inline_datum, outputs_at_with_policy, valid_before,
}
use cardano/assets.{without_lovelace}

validator complex_withdrawal_contract(oracle_nft: PolicyId) {
  withdraw(redeemer: MyRedeemer, _credential: Credential, tx: Transaction) {
    let Transaction {
      reference_inputs,
      inputs,
      outputs,
      mint,
      extra_signatories,
      validity_range,
      ..
    } = tx

    // Extract oracle data from reference input
    expect [oracle_ref_input] = inputs_with_policy(reference_inputs, oracle_nft)
    expect OracleDatum {
      app_owner,
      app_expiry,
      spending_validator_address,
      state_thread_token_policy_id,
    } = input_inline_datum(oracle_ref_input)

    // Find state thread token input
    expect [state_thread_input] =
      inputs_at_with_policy(
        inputs,
        spending_validator_address,
        state_thread_token_policy_id,
      )

    let is_app_owner_signed = key_signed(extra_signatories, app_owner)

    when redeemer is {
      ContinueCounting -> {
        expect [state_thread_output] =
          outputs_at_with_policy(
            outputs,
            spending_validator_address,
            state_thread_token_policy_id,
          )
        expect input_datum: SpendingValidatorDatum =
          input_inline_datum(state_thread_input)
        expect output_datum: SpendingValidatorDatum =
          output_inline_datum(state_thread_output)

        let is_app_not_expired = valid_before(validity_range, app_expiry)
        let is_count_added = input_datum.count + 1 == output_datum.count
        let is_nothing_minted = mint == assets.zero

        is_app_owner_signed? && is_app_not_expired? && is_count_added && is_nothing_minted?
      }
      StopCounting -> {
        let state_thread_value =
          state_thread_input.output.value |> without_lovelace()
        let is_thread_token_burned = mint == assets.negate(state_thread_value)
        is_app_owner_signed? && is_thread_token_burned?
      }
    }
  }

  publish(_redeemer: Data, _credential: Certificate, _tx: Transaction) {
    True
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

### Understanding `expect`

The `expect` keyword enforces exact pattern matching:

```rs
expect [oracle_ref_input] = inputs_with_policy(reference_inputs, oracle_nft)
```

This line:

1. Calls `inputs_with_policy` which returns `List<Input>`
2. Asserts the list has exactly one element
3. Binds that element to `oracle_ref_input`
4. Fails if the pattern does not match

Use `expect` when you are confident about the structure (e.g., the oracle NFT is unique).

### Understanding the `?` Operator

The `?` operator enables tracing for debugging:

```rs
is_app_owner_signed? && is_app_not_expired? && is_count_added
```

If `is_app_owner_signed` is `False`, the validator fails with the message `is_app_owner_signed?`, making it easy to identify which condition failed.

## Step 2: Write Basic Tests

Aiken tests use the `test` keyword. Run tests with `aiken check`.

### Test Always-True Cases

```rs
use mocktail.{complete, mocktail_tx}
use cardano/certificate.{RegisterCredential}
use cardano/address.{Script}

test test_publish() {
  let data = Void
  complex_withdrawal_contract.publish(
    "",
    data,
    RegisterCredential(Script(#""), Never),
    mocktail_tx() |> complete(),
  )
}
```

This tests the `publish` function which always returns `True`.

### Test Always-Fail Cases

Use the `fail` keyword after the test name to indicate expected failure:

```rs
use mocktail.{mock_utxo_ref}
use cardano/script_context.{ScriptContext, Spending}

test test_else() fail {
  complex_withdrawal_contract.else(
    "",
    ScriptContext(
      mocktail_tx() |> complete(),
      Void,
      Spending(mock_utxo_ref(0, 0), None),
    ),
  )
}
```

Run the tests:

```bash
aiken check
```

## Step 3: Build Mock Transactions

The `mocktail` module from vodka provides functions to construct mock transactions for testing.

### Define Mock Constants

```rs
use mocktail.{
  mock_policy_id, mock_script_address, mock_pub_key_hash, mock_tx_hash,
}

const mock_oracle_nft = mock_policy_id(0)
const mock_oracle_address = mock_script_address(0, None)
const mock_oracle_value =
  assets.from_asset(mock_oracle_nft, "", 1) |> assets.add("", "", 2_000_000)

const mock_app_owner = mock_pub_key_hash(0)
const mock_spending_validator_address = mock_script_address(1, None)
const mock_state_thread_token_policy_id = mock_policy_id(1)

const mock_state_thread_value =
  assets.from_asset(mock_state_thread_token_policy_id, "", 1)
    |> assets.add("", "", 2_000_000)

const mock_oracle_datum =
  OracleDatum {
    app_owner: mock_app_owner,
    app_expiry: 1000,
    spending_validator_address: mock_spending_validator_address,
    state_thread_token_policy_id: mock_state_thread_token_policy_id,
  }
```

### Create Helper Functions

```rs
fn mock_datum(count: Int) -> SpendingValidatorDatum {
  SpendingValidatorDatum { count }
}
```

### Build a Mock Transaction

```rs
use mocktail.{
  ref_tx_in, ref_tx_in_inline_datum, tx_in, tx_in_inline_datum,
  tx_out, tx_out_inline_datum, required_signer_hash, invalid_hereafter,
}

fn mock_continue_counting_tx() -> Transaction {
  mocktail_tx()
    |> ref_tx_in(
        True,
        mock_tx_hash(0),
        0,
        mock_oracle_value,
        mock_oracle_address,
      )
    |> ref_tx_in_inline_datum(True, mock_oracle_datum)
    |> tx_in(
        True,
        mock_tx_hash(1),
        0,
        mock_state_thread_value,
        mock_spending_validator_address,
      )
    |> tx_in_inline_datum(True, mock_datum(0))
    |> tx_out(True, mock_spending_validator_address, mock_state_thread_value)
    |> tx_out_inline_datum(True, mock_datum(1))
    |> required_signer_hash(True, mock_app_owner)
    |> invalid_hereafter(True, 999)
    |> complete()
}
```

### Mock Transaction Methods

| Method                                            | Description                          |
| ------------------------------------------------- | ------------------------------------ |
| `mocktail_tx()`                                   | Creates an empty mock transaction    |
| `ref_tx_in(include, hash, index, value, address)` | Adds a reference input               |
| `ref_tx_in_inline_datum(include, datum)`          | Attaches datum to previous ref input |
| `tx_in(include, hash, index, value, address)`     | Adds a spending input                |
| `tx_in_inline_datum(include, datum)`              | Attaches datum to previous input     |
| `tx_out(include, address, value)`                 | Adds an output                       |
| `tx_out_inline_datum(include, datum)`             | Attaches datum to previous output    |
| `required_signer_hash(include, key_hash)`         | Adds required signer                 |
| `invalid_hereafter(include, slot)`                | Sets validity upper bound            |
| `complete()`                                      | Finalizes the transaction            |

The first `Bool` parameter controls whether the element is included - this enables dynamic test cases.

## Step 4: Write Success Tests

```rs
test success_continue_counting() {
  complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(),
  )
}
```

## Step 5: Create Parameterized Test Cases

Define a test case type to systematically test failure conditions:

```rs
type ContinueCountingTest {
  is_ref_input_presented: Bool,
  is_thread_input_presented: Bool,
  is_thread_output_presented: Bool,
  is_count_added: Bool,
  is_app_owner_signed: Bool,
  is_tx_not_expired: Bool,
}
```

### Parameterized Mock Transaction

```rs
fn mock_continue_counting_tx(test_case: ContinueCountingTest) -> Transaction {
  let ContinueCountingTest {
    is_ref_input_presented,
    is_thread_input_presented,
    is_thread_output_presented,
    is_count_added,
    is_app_owner_signed,
    is_tx_not_expired,
  } = test_case

  let output_datum =
    if is_count_added {
      mock_datum(1)
    } else {
      mock_datum(0)  // Same as input - count not incremented
    }

  mocktail_tx()
    |> ref_tx_in(
        is_ref_input_presented,
        mock_tx_hash(0),
        0,
        mock_oracle_value,
        mock_oracle_address,
      )
    |> ref_tx_in_inline_datum(is_ref_input_presented, mock_oracle_datum)
    |> tx_in(
        is_thread_input_presented,
        mock_tx_hash(1),
        0,
        mock_state_thread_value,
        mock_spending_validator_address,
      )
    |> tx_in_inline_datum(is_thread_input_presented, mock_datum(0))
    |> tx_out(
        is_thread_output_presented,
        mock_spending_validator_address,
        mock_state_thread_value,
      )
    |> tx_out_inline_datum(is_thread_output_presented, output_datum)
    |> required_signer_hash(is_app_owner_signed, mock_app_owner)
    |> invalid_hereafter(is_tx_not_expired, 999)
    |> complete()
}
```

### Updated Success Test

```rs
test success_continue_counting() {
  let test_case =
    ContinueCountingTest {
      is_ref_input_presented: True,
      is_thread_input_presented: True,
      is_thread_output_presented: True,
      is_count_added: True,
      is_app_owner_signed: True,
      is_tx_not_expired: True,
    }

  complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(test_case),
  )
}
```

## Step 6: Write Failure Tests

Test each failure condition by toggling one parameter:

### Missing Reference Input

```rs
test fail_continue_counting_no_ref_input() fail {
  let test_case =
    ContinueCountingTest {
      is_ref_input_presented: False,  // Changed to False
      is_thread_input_presented: True,
      is_thread_output_presented: True,
      is_count_added: True,
      is_app_owner_signed: True,
      is_tx_not_expired: True,
    }

  complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(test_case),
  )
}
```

### Missing Thread Input

```rs
test fail_continue_counting_no_thread_input() fail {
  let test_case =
    ContinueCountingTest {
      is_ref_input_presented: True,
      is_thread_input_presented: False,  // Changed to False
      is_thread_output_presented: True,
      is_count_added: True,
      is_app_owner_signed: True,
      is_tx_not_expired: True,
    }

  complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(test_case),
  )
}
```

### Incorrect Count

For tests where the validator returns `False` (rather than failing), negate the result:

```rs
test fail_continue_counting_incorrect_count() {
  let test_case =
    ContinueCountingTest {
      is_ref_input_presented: True,
      is_thread_input_presented: True,
      is_thread_output_presented: True,
      is_count_added: False,  // Count not incremented
      is_app_owner_signed: True,
      is_tx_not_expired: True,
    }

  !complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(test_case),
  )
}
```

The `!` negates the result - the test passes if the validator returns `False`.

### Not Signed by Owner

```rs
test fail_continue_counting_not_signed_by_owner() {
  let test_case =
    ContinueCountingTest {
      is_ref_input_presented: True,
      is_thread_input_presented: True,
      is_thread_output_presented: True,
      is_count_added: True,
      is_app_owner_signed: False,  // Not signed
      is_tx_not_expired: True,
    }

  !complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(test_case),
  )
}
```

### App Expired

```rs
test fail_continue_counting_app_expired() {
  let test_case =
    ContinueCountingTest {
      is_ref_input_presented: True,
      is_thread_input_presented: True,
      is_thread_output_presented: True,
      is_count_added: True,
      is_app_owner_signed: True,
      is_tx_not_expired: False,  // Expired
    }

  !complex_withdrawal_contract.withdraw(
    mock_oracle_nft,
    ContinueCounting,
    Credential.Script(#""),
    mock_continue_counting_tx(test_case),
  )
}
```

## Step 7: Run All Tests

Execute the test suite:

```bash
aiken check
```

You see output showing all tests passing:

```
    Testing ...

    ┍━ complex_withdrawal_contract ━━━━━━━━━━━━━━━━━━━━━━━
    │ PASS test_publish
    │ PASS test_else
    │ PASS success_continue_counting
    │ PASS fail_continue_counting_no_ref_input
    │ PASS fail_continue_counting_no_thread_input
    │ PASS fail_continue_counting_no_thread_output
    │ PASS fail_continue_counting_incorrect_count
    │ PASS fail_continue_counting_not_signed_by_owner
    │ PASS fail_continue_counting_app_expired
    ┕━━━━━━━━━━━━━━━ 9 tests | 9 passed | 0 failed
```

## Key Concepts Explained

### Test Keyword Variants

| Syntax                     | Meaning                                              |
| -------------------------- | ---------------------------------------------------- |
| `test name() { ... }`      | Test passes if body evaluates to `True`              |
| `test name() fail { ... }` | Test passes if body fails/crashes                    |
| `!validator_call(...)`     | Negates result - passes if validator returns `False` |

### Boolean Parameters in Mocks

The first boolean in mock functions controls inclusion:

```rs
tx_in(True, ...)   // Include this input
tx_in(False, ...)  // Exclude this input
```

This pattern enables single mock functions that cover multiple test scenarios.

## Exercises

1. **Test StopCounting**: Write tests for the `StopCounting` action following the same parameterized pattern.

2. **Add minting check**: Extend `ContinueCounting` to fail if any assets are minted, and add a test for it.

3. **Edge case testing**: What happens if there are two oracle NFTs in reference inputs? Write a test to verify the behavior.

## Next Steps

You have learned:

* How to write Aiken tests using `test` and `fail`
* How to build mock transactions with `mocktail`
* How to create parameterized tests for comprehensive coverage
* How to use `expect` and the `?` operator

In the next lesson, you learn how to <Link href="/resources/cardano-course/05-avoid-redundant-validation">avoid redundant validation</Link> to optimize your contracts.

## Related Links

* <Link href="https://aiken-lang.org/language-tour/tests">Aiken Testing Documentation</Link>
* <Link href="https://github.com/sidan-lab/vodka">Vodka Library (mocktail module)</Link>
* <Link href="https://aiken-lang.github.io/stdlib/">Aiken Standard Library</Link>


# Lesson 5: Avoid Redundant Validation
URL: /resources/cardano-course/05-avoid-redundant-validation

Optimize Cardano smart contracts by centralizing validation logic and using the withdraw 0 trick.

***

title: "Lesson 5: Avoid Redundant Validation"
description: "Optimize Cardano smart contracts by centralizing validation logic and using the withdraw 0 trick."
----------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Identify redundant validation patterns in multi-script transactions
* Implement validation delegation using withdrawal scripts
* Use the "withdraw 0 trick" to trigger validation efficiently
* Reduce transaction costs by centralizing common checks
* Structure contracts for maintainability and efficiency

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/04-contract-testing">Lesson 4: Contract Testing</Link>
* Understanding of minting, spending, and withdrawal scripts
* Familiarity with the Transaction structure

## Key Concepts

### The Redundancy Problem

Complex transactions often involve multiple scripts validating the same conditions:

```
Transaction with multiple scripts
  Minting Script    -> Checks: owner signed, not expired, valid state
  Spending Script 1 -> Checks: owner signed, not expired, valid state
  Spending Script 2 -> Checks: owner signed, not expired, valid state
  Spending Script 3 -> Checks: owner signed, not expired, valid state
```

Each script independently verifies the same conditions, leading to:

* **Increased execution units**: Same checks run multiple times
* **Higher fees**: More computation costs more ADA
* **Maintenance burden**: Logic duplicated across validators
* **Bug risk**: Inconsistent implementations across scripts

### The Solution: Validation Delegation

Centralize common checks in a single validator. Other scripts simply verify that this "master validator" is being executed:

```
Transaction with delegated validation
  Minting Script    -> Checks: withdrawal script validated
  Spending Script 1 -> Checks: withdrawal script validated
  Spending Script 2 -> Checks: withdrawal script validated
  Withdrawal Script -> Checks: owner signed, not expired, valid state
```

Common validations run once, regardless of how many scripts are involved.

## Step 1: Understand the Architecture

### Before: Redundant Checks

```mermaid
graph TB
    subgraph Checks[" Common Validations "]
        direction LR
        C1["Check owner signature"] ~~~ C2["Check not expired"] ~~~ C3["Other checks"]
    end

    Checks -.-> A1
    Checks -.-> A2
    Checks -.-> A3
    Checks -.-> M
    Checks -.-> W

    A1[Script Input 1] --> TX
    A2[Script Input 2] --> TX
    A3[Script Input 3] --> TX

    TX((Transaction))

    M[Token Minting] --> TX
    W[Withdrawal Script] --> TX
```

Every script performs the same common validations independently.

### After: Centralized Validation

```mermaid
graph TB
    subgraph Checks[" Common Validations "]
        direction LR
        C1["Check owner signature"] ~~~ C2["Check not expired"] ~~~ C3["Other checks"]
    end

    WithdrawalCheck[" Check Withdrawal Script Validates "]

    Checks -.-> W
    WithdrawalCheck -.-> A1
    WithdrawalCheck -.-> A2
    WithdrawalCheck -.-> A3
    WithdrawalCheck -.-> M

    A1[Script Input 1] --> TX
    A2[Script Input 2] --> TX
    A3[Script Input 3] --> TX

    TX((Transaction))
    M[Token Minting] --> TX
    W[Withdrawal Script] --> TX
```

Other scripts only check that the withdrawal script is being validated. The withdrawal script performs all common checks once.

## Step 2: Implement the Withdrawal Validator

Use the complex withdrawal contract from Lesson 4 as your central validator. This script contains all the business logic.

```rs
// This is the same validator from Lesson 4
// It handles all the complex validation logic
validator complex_withdrawal_contract(oracle_nft: PolicyId) {
  withdraw(redeemer: MyRedeemer, _credential: Credential, tx: Transaction) {
    // ... all validation logic here
  }

  publish(_redeemer: Data, _credential: Certificate, _tx: Transaction) {
    True
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

## Step 3: Create Delegating Spending Script

Create a spending validator that delegates validation to the withdrawal script:

```rs
use aiken/crypto.{ScriptHash}
use cardano/transaction.{OutputReference, Transaction}
use cocktail.{withdrawal_script_validated}

validator spending_logics_delegated(
  delegated_withdrawal_script_hash: ScriptHash,
) {
  spend(
    _datum_opt: Option<Data>,
    _redeemer: Data,
    _input: OutputReference,
    tx: Transaction,
  ) {
    withdrawal_script_validated(
      tx.withdrawals,
      delegated_withdrawal_script_hash,
    )
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

### How It Works

| Component                          | Purpose                                                |
| ---------------------------------- | ------------------------------------------------------ |
| `delegated_withdrawal_script_hash` | Parameter: hash of the withdrawal script to check      |
| `withdrawal_script_validated`      | Checks if the withdrawal script is in `tx.withdrawals` |
| `tx.withdrawals`                   | List of withdrawal operations in this transaction      |

The spending script does not check business logic directly. It only verifies that the withdrawal script is being executed in the same transaction, which means the withdrawal script's validation will run.

## Step 4: Create Delegating Minting Script

Apply the same pattern to minting:

```rs
use aiken/crypto.{ScriptHash}
use cardano/assets.{PolicyId}
use cardano/transaction.{Transaction}
use cocktail.{withdrawal_script_validated}

validator minting_logics_delegated(
  delegated_withdrawal_script_hash: ScriptHash,
) {
  mint(_redeemer: Data, _policy_id: PolicyId, tx: Transaction) {
    withdrawal_script_validated(
      tx.withdrawals,
      delegated_withdrawal_script_hash,
    )
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

## Step 5: The Withdraw 0 Trick

### Problem: How to Trigger Withdrawal Validation?

Normally, withdrawal scripts only run when withdrawing stake rewards. But most transactions do not involve staking.

### Solution: Withdraw Zero

The <Link href="https://aiken-lang.org/fundamentals/common-design-patterns#forwarding-validation--other-withdrawal-tricks">"withdraw 0 trick"</Link> triggers a withdrawal script by including a withdrawal of 0 lovelace:

```
Transaction {
  withdrawals: [
    { credential: Script(withdrawal_script_hash), amount: 0 }
  ]
  ...
}
```

This:

1. Triggers the withdrawal script validation
2. Costs minimal extra fees (just the script execution)
3. Does not affect stake rewards
4. Cleanly separates validation logic from script purpose

### Why Withdrawal Scripts?

You could delegate to spending or minting validators instead. However, withdrawal scripts offer advantages:

| Delegation Target | Trigger Method          | Drawbacks                             |
| ----------------- | ----------------------- | ------------------------------------- |
| Spending Script   | Must spend a UTXO       | Requires a UTXO at the script address |
| Minting Script    | Must mint/burn an asset | Requires a minting policy in the tx   |
| Withdrawal Script | Withdraw 0              | Clean, no side effects                |

The withdraw 0 trick provides the cleanest trigger mechanism - it does not require consuming UTXOs or minting tokens.

## Step 6: Off-chain Implementation

When building transactions that use delegating scripts, include the withdrawal:

```ts
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
});

// Include the withdrawal to trigger validation
await txBuilder
  // ... other transaction components
  .withdrawalPlutusScriptV3()
  .withdrawal(withdrawalScriptAddress, "0")  // Withdraw 0 lovelace
  .withdrawalScript(withdrawalScriptCbor)
  .withdrawalRedeemerValue(redeemer)
  // ... rest of transaction
  .complete();
```

## Complete Working Example

### Project Structure

```
delegated-validation/
  validators/
    withdraw.ak      # Central validator with all business logic
    spend.ak         # Delegating spending script
    mint.ak          # Delegating minting script
```

### validators/withdraw\.ak

```rs
use aiken/crypto.{VerificationKeyHash}
use cardano/address.{Address, Credential}
use cardano/assets.{PolicyId}
use cardano/certificate.{Certificate}
use cardano/transaction.{Transaction}
use cocktail.{
  input_inline_datum, inputs_at_with_policy, inputs_with_policy, key_signed,
  output_inline_datum, outputs_at_with_policy, valid_before,
}

pub type OracleDatum {
  app_owner: VerificationKeyHash,
  app_expiry: Int,
  spending_validator_address: Address,
  state_thread_token_policy_id: PolicyId,
}

pub type SpendingValidatorDatum {
  count: Int,
}

pub type MyRedeemer {
  ContinueCounting
  StopCounting
}

validator central_validator(oracle_nft: PolicyId) {
  withdraw(redeemer: MyRedeemer, _credential: Credential, tx: Transaction) {
    // All business logic centralized here
    let Transaction {
      reference_inputs,
      inputs,
      outputs,
      mint,
      extra_signatories,
      validity_range,
      ..
    } = tx

    expect [oracle_ref_input] = inputs_with_policy(reference_inputs, oracle_nft)
    expect OracleDatum {
      app_owner,
      app_expiry,
      spending_validator_address,
      state_thread_token_policy_id,
    } = input_inline_datum(oracle_ref_input)

    let is_app_owner_signed = key_signed(extra_signatories, app_owner)

    when redeemer is {
      ContinueCounting -> {
        // ... validation logic
        is_app_owner_signed? && valid_before(validity_range, app_expiry)?
      }
      StopCounting -> {
        is_app_owner_signed?
      }
    }
  }

  publish(_redeemer: Data, _credential: Certificate, _tx: Transaction) {
    True
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

### validators/spend.ak

```rs
use aiken/crypto.{ScriptHash}
use cardano/transaction.{OutputReference, Transaction}
use cocktail.{withdrawal_script_validated}

validator delegating_spend(central_validator_hash: ScriptHash) {
  spend(
    _datum_opt: Option<Data>,
    _redeemer: Data,
    _input: OutputReference,
    tx: Transaction,
  ) {
    withdrawal_script_validated(tx.withdrawals, central_validator_hash)
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

### validators/mint.ak

```rs
use aiken/crypto.{ScriptHash}
use cardano/assets.{PolicyId}
use cardano/transaction.{Transaction}
use cocktail.{withdrawal_script_validated}

validator delegating_mint(central_validator_hash: ScriptHash) {
  mint(_redeemer: Data, _policy_id: PolicyId, tx: Transaction) {
    withdrawal_script_validated(tx.withdrawals, central_validator_hash)
  }

  else(_) {
    fail @"unsupported purpose"
  }
}
```

## Key Concepts Explained

### Benefits of Validation Delegation

| Benefit             | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Efficiency**      | Common checks execute once instead of N times           |
| **Lower Costs**     | Reduced execution units means lower fees                |
| **Maintainability** | Single source of truth for validation logic             |
| **Consistency**     | Impossible to have divergent validation between scripts |

### When to Use This Pattern

Use validation delegation when:

* Multiple scripts share common validation requirements
* Transaction costs are a concern
* You want centralized control over validation logic
* The protocol involves complex multi-script interactions

### When NOT to Use This Pattern

Avoid this pattern when:

* Scripts have completely independent validation logic
* Simplicity is more important than optimization
* You need each script to be self-contained

## Exercises

1. **Add a second redeemer**: Extend the central validator to handle a third action type. Verify that the delegating scripts do not need changes.

2. **Multiple delegation levels**: Create a hierarchy where spending scripts delegate to a minting script, which delegates to a withdrawal script.

3. **Measure the savings**: Build the same transaction with and without delegation. Compare the execution units and fees.

## Next Steps

You have learned:

* Why redundant validation is costly
* How to centralize validation in a withdrawal script
* The "withdraw 0 trick" for clean validation triggering
* How to implement delegating spending and minting scripts

In the next lesson, you learn how to <Link href="/resources/cardano-course/06-interpreting-blueprint">interpret Aiken blueprints</Link> and generate off-chain code automatically.

## Related Links

* <Link href="https://aiken-lang.org/fundamentals/common-design-patterns#forwarding-validation--other-withdrawal-tricks">Aiken Design Patterns: Withdraw 0 Trick</Link>
* <Link href="https://github.com/sidan-lab/vodka">Vodka Library</Link>
* <Link href="/apis/txbuilder">MeshTxBuilder API Reference</Link>


# Lesson 6: Interpreting Blueprint
URL: /resources/cardano-course/06-interpreting-blueprint

Understand CIP-57 blueprints and generate TypeScript off-chain code from Aiken contracts.

***

title: "Lesson 6: Interpreting Blueprint"
description: "Understand CIP-57 blueprints and generate TypeScript off-chain code from Aiken contracts."
--------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Understand the CIP-57 blueprint standard
* Read and interpret the `preamble`, `validators`, and `definitions` sections
* Extract script hashes, datums, and redeemers from blueprints
* Generate TypeScript off-chain code automatically
* Apply parameters to compiled scripts

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/05-avoid-redundant-validation">Lesson 5: Avoid Redundant Validation</Link>
* An Aiken project with compiled validators
* VS Code with the Cardano-Bar extension (optional but recommended)

## Key Concepts

### What is a Blueprint?

A blueprint is a standardized JSON file defined by <Link href="https://cips.cardano.org/cip/CIP-57">CIP-57</Link>. It serves as the output artifact of Cardano smart contract development, providing everything needed to interact with the contracts off-chain.

Regardless of the development method (Aiken, PlutusTx, etc.), blueprints contain:

| Section       | Contents                                                            |
| ------------- | ------------------------------------------------------------------- |
| `preamble`    | Meta-information about the contract (name, version, Plutus version) |
| `validators`  | Named validators with type definitions and compiled code            |
| `definitions` | Reusable type definitions referenced across the specification       |

### Why Blueprints Matter

Blueprints bridge on-chain and off-chain development:

1. **Type safety**: TypeScript types can be generated from blueprint definitions
2. **Script access**: Compiled code is readily available for transactions
3. **Documentation**: Self-documenting contract interface
4. **Interoperability**: Standard format works across toolchains

## Step 1: Generate a Blueprint

Build your Aiken project to generate the blueprint:

```bash
aiken build
```

This creates a `plutus.json` file in your project root.

## Step 2: Understand the Preamble

The `preamble` section contains metadata about your contract:

```json
{
  "preamble": {
    "title": "meshsdk/aiken-template",
    "description": "Aiken contracts for project 'meshsdk/aiken-template'",
    "version": "0.0.0",
    "plutusVersion": "v3",
    "compiler": {
      "name": "Aiken",
      "version": "v1.1.16+23061c0"
    },
    "license": "Apache-2.0"
  }
}
```

### Key Fields

| Field           | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `title`         | Project identifier                                           |
| `plutusVersion` | Plutus version (v1, v2, or v3) - critical for off-chain code |
| `compiler`      | Tool and version that generated the blueprint                |
| `version`       | Your project's semantic version                              |

The `plutusVersion` is particularly important - it determines how you construct transactions and evaluate scripts.

## Step 3: Understand Validators

The `validators` section lists each validator with its complete specification:

```json
{
  "validators": [
    {
      "title": "spend.spending_logics_delegated.spend",
      "datum": {
        "title": "_datum_opt",
        "schema": {
          "$ref": "#/definitions/Data"
        }
      },
      "redeemer": {
        "title": "_redeemer",
        "schema": {
          "$ref": "#/definitions/Data"
        }
      },
      "parameters": [
        {
          "title": "delegated_withdrawal_script_hash",
          "schema": {
            "$ref": "#/definitions/aiken~1crypto~1ScriptHash"
          }
        }
      ],
      "compiledCode": "58ac010100229800aba2aba1aba0aab9faab9eaab9dab9a9bae002488...",
      "hash": "9c9666ddc12fc42f0151cd029c150c7d410ede9fe3885c248c8c26a0"
    }
  ]
}
```

### Validator Fields

| Field          | Description                                       |
| -------------- | ------------------------------------------------- |
| `title`        | Unique identifier: `file.validator_name.purpose`  |
| `datum`        | Expected datum type (for spending scripts)        |
| `redeemer`     | Expected redeemer type                            |
| `parameters`   | Script parameters that must be applied before use |
| `compiledCode` | Hex-encoded CBOR of the compiled script           |
| `hash`         | Script hash (28 bytes, hex-encoded)               |

### Multi-Purpose Validators

When a validator handles multiple purposes (spend, mint, etc.), each purpose appears as a separate entry but shares the same `hash`:

```json
{
  "title": "spend.spending_logics_delegated.spend",
  "hash": "9c9666ddc12fc42f0151cd029c150c7d410ede9fe3885c248c8c26a0"
},
{
  "title": "spend.spending_logics_delegated.else",
  "hash": "9c9666ddc12fc42f0151cd029c150c7d410ede9fe3885c248c8c26a0"
}
```

Same script, different entry points.

## Step 4: Understand Definitions

The `definitions` section provides reusable type schemas:

```json
{
  "definitions": {
    "Data": {
      "title": "Data",
      "description": "Any Plutus data."
    },
    "aiken/crypto/ScriptHash": {
      "title": "ScriptHash",
      "dataType": "bytes"
    },
    "cardano/assets/PolicyId": {
      "title": "PolicyId",
      "dataType": "bytes"
    },
    "withdraw/MyRedeemer": {
      "title": "MyRedeemer",
      "anyOf": [
        {
          "title": "ContinueCounting",
          "dataType": "constructor",
          "index": 0,
          "fields": []
        },
        {
          "title": "StopCounting",
          "dataType": "constructor",
          "index": 1,
          "fields": []
        }
      ]
    }
  }
}
```

### Common Definition Types

| Type        | JSON Representation         | Description                     |
| ----------- | --------------------------- | ------------------------------- |
| Bytes       | `"dataType": "bytes"`       | Raw byte arrays (hashes, keys)  |
| Integer     | `"dataType": "integer"`     | Arbitrary precision integers    |
| String      | `"dataType": "string"`      | UTF-8 strings                   |
| List        | `"dataType": "list"`        | Ordered collections             |
| Constructor | `"dataType": "constructor"` | ADT variant with fields         |
| Union       | `"anyOf": [...]`            | Sum type with multiple variants |

### Constructor Indices

For redeemers with multiple variants, the `index` determines the constructor number:

```json
{
  "title": "ContinueCounting",
  "dataType": "constructor",
  "index": 0,           // ConStr0
  "fields": []
},
{
  "title": "StopCounting",
  "dataType": "constructor",
  "index": 1,           // ConStr1
  "fields": []
}
```

When building transactions, use `mConStr0([])` for `ContinueCounting` and `mConStr1([])` for `StopCounting`.

## Step 5: Generate TypeScript Code

### Option 1: VS Code Extension (Recommended)

Use the <Link href="https://marketplace.visualstudio.com/items/?itemName=sidan-lab.cardano-bar-vscode">Cardano-Bar VS Code extension</Link>:

1. Create a new TypeScript file (e.g., `offchain.ts`)
2. Open the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
3. Type `Parse blueprint to Typescript - Mesh` and select it
4. Select your `plutus.json` file

The extension generates a complete TypeScript module with:

* Type definitions for datums and redeemers
* Functions to get script code and addresses
* Parameter application helpers

### Option 2: Manual Implementation

Extract information directly from the blueprint:

```ts
import {
  applyParamsToScript,
  resolveScriptHash,
  serializePlutusScript,
} from "@meshsdk/core";

// Load the blueprint
import blueprint from "./plutus.json";

// Get the validator entry
const spendValidator = blueprint.validators.find(
  (v) => v.title === "spend.spending_logics_delegated.spend"
);

// Extract compiled code
const compiledCode = spendValidator.compiledCode;

// Apply parameters if needed
const withdrawalScriptHash = "9c9666ddc12fc42f0151cd029c150c7d410ede9fe3885c248c8c26a0";
const parameterizedScript = applyParamsToScript(compiledCode, [
  withdrawalScriptHash,
]);

// Get the script hash (policy ID for minting scripts)
const scriptHash = resolveScriptHash(parameterizedScript, "V3");

// Get the script address (for spending scripts)
const { address } = serializePlutusScript(
  { code: parameterizedScript, version: "V3" },
  undefined,  // stake credential
  "preprod"   // network
);
```

## Step 6: Use Generated Code in Transactions

### Building Datums

Construct datums matching the blueprint schema:

```ts
import { mConStr0, integer, byteString } from "@meshsdk/core";

// For a datum with count field
const spendingDatum = mConStr0([
  integer(0),  // count
]);

// For a complex oracle datum
const oracleDatum = mConStr0([
  byteString(appOwnerKeyHash),      // app_owner
  integer(1000),                     // app_expiry
  mPubKeyAddress(keyHash, stakeHash), // spending_validator_address
  byteString(policyId),              // state_thread_token_policy_id
]);
```

### Building Redeemers

Match the constructor index from definitions:

```ts
// ContinueCounting (index 0)
const continueRedeemer = mConStr0([]);

// StopCounting (index 1)
const stopRedeemer = mConStr1([]);
```

### Complete Transaction Example

```ts
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
import { getScript, getScriptHash, getDatum, getRedeemer } from "./offchain";

const provider = new BlockfrostProvider("YOUR_API_KEY");
const txBuilder = new MeshTxBuilder({ fetcher: provider });

// Get script information
const script = getScript("spend.spending_logics_delegated");
const scriptAddress = getScriptAddress("spend.spending_logics_delegated");

// Build transaction
const unsignedTx = await txBuilder
  .spendingPlutusScriptV3()
  .txIn(utxo.input.txHash, utxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(getRedeemer("ContinueCounting"))
  .txInScript(script.code)
  .txOut(outputAddress, outputValue)
  .changeAddress(walletAddress)
  .selectUtxosFrom(wallets)
  .complete();
```

## Complete Working Example

### Generated offchain.ts

```ts
import {
  applyParamsToScript,
  resolveScriptHash,
  serializePlutusScript,
  mConStr0,
  mConStr1,
  integer,
} from "@meshsdk/core";

// Import your blueprint
import blueprint from "./plutus.json";

// Type definitions
export type SpendingValidatorDatum = {
  count: number;
};

export type MyRedeemer = "ContinueCounting" | "StopCounting";

// Get validator by title
function findValidator(title: string) {
  const validator = blueprint.validators.find((v) => v.title.startsWith(title));
  if (!validator) throw new Error(`Validator ${title} not found`);
  return validator;
}

// Get parameterized script
export function getScript(validatorName: string, params: string[] = []) {
  const validator = findValidator(validatorName);
  let code = validator.compiledCode;

  if (params.length > 0) {
    code = applyParamsToScript(code, params);
  }

  return {
    code,
    hash: resolveScriptHash(code, "V3"),
  };
}

// Get script address
export function getScriptAddress(
  validatorName: string,
  params: string[] = [],
  network: "mainnet" | "preprod" = "preprod"
) {
  const script = getScript(validatorName, params);
  const { address } = serializePlutusScript(
    { code: script.code, version: "V3" },
    undefined,
    network
  );
  return address;
}

// Build datum
export function buildDatum(datum: SpendingValidatorDatum) {
  return mConStr0([integer(datum.count)]);
}

// Build redeemer
export function buildRedeemer(action: MyRedeemer) {
  switch (action) {
    case "ContinueCounting":
      return mConStr0([]);
    case "StopCounting":
      return mConStr1([]);
  }
}
```

### Usage in Application

```ts
import { getScript, getScriptAddress, buildDatum, buildRedeemer } from "./offchain";

// Get script with parameter
const withdrawalScriptHash = "abc123...";
const script = getScript("spend.delegating_spend", [withdrawalScriptHash]);

// Get address
const address = getScriptAddress("spend.delegating_spend", [withdrawalScriptHash]);

// Build datum and redeemer for transaction
const datum = buildDatum({ count: 0 });
const redeemer = buildRedeemer("ContinueCounting");
```

## Key Concepts Explained

### Parameter Application

Scripts with parameters in the blueprint require values before use:

```ts
// Blueprint shows parameter:
// "parameters": [{ "title": "oracle_nft", "schema": { "$ref": "#/definitions/PolicyId" }}]

// Apply the parameter
const parameterizedScript = applyParamsToScript(compiledCode, [oracleNftPolicyId]);
```

Applying parameters creates a new script with a new hash.

### Schema References

The `$ref` syntax points to definitions:

```json
"schema": { "$ref": "#/definitions/aiken~1crypto~1ScriptHash" }
```

The `~1` is JSON Pointer encoding for `/`, so this references `definitions["aiken/crypto/ScriptHash"]`.

## Exercises

1. **Parse a complex blueprint**: Create a vesting contract with owner and beneficiary fields. Generate the TypeScript types and verify they match.

2. **Multi-validator project**: Build a project with minting and spending validators. Use the blueprint to coordinate them in a single transaction.

3. **Automated testing**: Write a script that validates your off-chain code matches the blueprint definitions.

## Next Steps

You have learned:

* The structure of CIP-57 blueprints
* How to read preamble, validators, and definitions
* How to generate TypeScript code from blueprints
* How to use generated code in transactions

In the next lesson, you build a <Link href="/resources/cardano-course/07-vesting">vesting contract</Link> that locks funds until a specified time.

## Related Links

* <Link href="https://cips.cardano.org/cip/CIP-57">CIP-57: Plutus Blueprint</Link>
* <Link href="https://marketplace.visualstudio.com/items/?itemName=sidan-lab.cardano-bar-vscode">Cardano-Bar VS Code Extension</Link>
* <Link href="/apis/utilities/blueprints">Mesh SDK Blueprint Utilities</Link>


# Lesson 7: Vesting Contract
URL: /resources/cardano-course/07-vesting

Build a time-locked vesting contract that releases funds to a beneficiary after a specified period.

***

title: "Lesson 7: Vesting Contract"
description: "Build a time-locked vesting contract that releases funds to a beneficiary after a specified period."
------------------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Implement a time-locked vesting contract in Aiken
* Use validity ranges to enforce time constraints
* Differentiate between owner and beneficiary spending conditions
* Build deposit and withdrawal transactions with Mesh SDK
* Test vesting contracts with various scenarios

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/06-interpreting-blueprint">Lesson 6: Interpreting Blueprint</Link>
* An Aiken development environment set up
* A funded preprod wallet
* A Blockfrost API key

## Key Concepts

### What is a Vesting Contract?

A vesting contract locks funds until a specified time, then allows a designated beneficiary to withdraw them. Common use cases include:

* **Employee compensation**: Tokens vest over time to incentivize retention
* **Token launches**: Gradual release prevents market dumps
* **Escrow**: Time-based release for agreements

### Contract Requirements

| Actor           | Permissions                               |
| --------------- | ----------------------------------------- |
| **Owner**       | Can withdraw at any time                  |
| **Beneficiary** | Can withdraw only after the lockup period |

## Step 1: Define the Contract Types

Create the datum structure that stores vesting parameters:

```rs
// lib/vesting/types.ak

pub type VestingDatum {
  /// POSIX time in milliseconds when funds unlock
  lock_until: Int,
  /// Owner's public key hash (can withdraw anytime)
  owner: ByteArray,
  /// Beneficiary's public key hash (can withdraw after lock_until)
  beneficiary: ByteArray,
}
```

### Datum Fields

| Field         | Type        | Purpose                                          |
| ------------- | ----------- | ------------------------------------------------ |
| `lock_until`  | `Int`       | POSIX timestamp (milliseconds) when funds unlock |
| `owner`       | `ByteArray` | Public key hash of the fund depositor            |
| `beneficiary` | `ByteArray` | Public key hash of the designated recipient      |

## Step 2: Implement the Validator

Create the spending validator that enforces vesting rules:

```rs
// validators/vesting.ak

use aiken/crypto.{VerificationKeyHash}
use cardano/transaction.{OutputReference, Transaction}
use vesting/types.{VestingDatum}
use vodka/extra/list.{key_signed}
use vodka/extra/validity_range.{valid_after}

validator vesting {
  spend(
    datum_opt: Option<VestingDatum>,
    _redeemer: Data,
    _input: OutputReference,
    tx: Transaction,
  ) {
    expect Some(datum) = datum_opt

    // Owner can always withdraw
    // OR beneficiary can withdraw after lock time
    or {
      key_signed(tx.extra_signatories, datum.owner),
      and {
        key_signed(tx.extra_signatories, datum.beneficiary),
        valid_after(tx.validity_range, datum.lock_until),
      },
    }
  }

  else(_) {
    fail
  }
}
```

### Validation Logic

The contract allows spending when:

1. **Owner signature present**: The owner can withdraw at any time, no time check needed
2. **Beneficiary conditions met**: Both conditions must be true:
   * Transaction is signed by the beneficiary
   * Transaction validity range starts after `lock_until`

### Time Validation

Cardano transactions include validity intervals specifying when they can be executed. The ledger verifies these bounds before running scripts.

```rs
valid_after(tx.validity_range, datum.lock_until)
```

This checks that the transaction's lower bound is after the lock time. If true, we know the current time is at least `lock_until`.

## Step 3: Write Contract Tests

Test all valid and invalid spending scenarios:

```rs
// validators/vesting.ak (continued)

use mocktail.{
  complete, invalid_before, mock_pub_key_hash, mock_tx_hash,
  mocktail_tx, required_signer_hash, tx_in, tx_in_inline_datum,
}

const mock_owner = mock_pub_key_hash(0)
const mock_beneficiary = mock_pub_key_hash(1)
const mock_lock_time = 1000

fn mock_datum() -> VestingDatum {
  VestingDatum {
    lock_until: mock_lock_time,
    owner: mock_owner,
    beneficiary: mock_beneficiary,
  }
}

type VestingTest {
  is_owner_signed: Bool,
  is_beneficiary_signed: Bool,
  is_time_passed: Bool,
}

fn mock_tx(test: VestingTest) -> Transaction {
  let VestingTest { is_owner_signed, is_beneficiary_signed, is_time_passed } = test

  mocktail_tx()
    |> tx_in(True, mock_tx_hash(0), 0, [], mock_script_address(0, None))
    |> tx_in_inline_datum(True, mock_datum())
    |> required_signer_hash(is_owner_signed, mock_owner)
    |> required_signer_hash(is_beneficiary_signed, mock_beneficiary)
    |> invalid_before(is_time_passed, mock_lock_time + 1)
    |> complete()
}

// Success: Owner can always withdraw
test success_owner_withdraws() {
  let test = VestingTest {
    is_owner_signed: True,
    is_beneficiary_signed: False,
    is_time_passed: False,
  }
  vesting.spend("", Void, mock_utxo_ref(0, 0), mock_tx(test))
}

// Success: Beneficiary withdraws after time passes
test success_beneficiary_withdraws_after_lock() {
  let test = VestingTest {
    is_owner_signed: False,
    is_beneficiary_signed: True,
    is_time_passed: True,
  }
  vesting.spend("", Void, mock_utxo_ref(0, 0), mock_tx(test))
}

// Failure: Beneficiary cannot withdraw before time passes
test fail_beneficiary_too_early() {
  let test = VestingTest {
    is_owner_signed: False,
    is_beneficiary_signed: True,
    is_time_passed: False,
  }
  !vesting.spend("", Void, mock_utxo_ref(0, 0), mock_tx(test))
}

// Failure: Time passed but no signature
test fail_no_signature() {
  let test = VestingTest {
    is_owner_signed: False,
    is_beneficiary_signed: False,
    is_time_passed: True,
  }
  !vesting.spend("", Void, mock_utxo_ref(0, 0), mock_tx(test))
}
```

Run tests:

```bash
aiken check
```

## Step 4: Build and Deploy

Compile the contract:

```bash
aiken build
```

This generates `plutus.json` with the compiled validator.

## Step 5: Deposit Funds

Create a transaction that locks funds in the vesting contract.

### Setup

```ts
import {
  BlockfrostProvider,
  MeshTxBuilder,
  deserializeAddress,
  serializePlutusScript,
  mConStr0,
  integer,
  byteString,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import blueprint from "./plutus.json";

const provider = new BlockfrostProvider("YOUR_BLOCKFROST_API_KEY");

// Load the vesting script
const vestingValidator = blueprint.validators.find(
  (v) => v.title === "vesting.vesting.spend"
);
const scriptCbor = vestingValidator.compiledCode;

const script = serializePlutusScript(
  { code: scriptCbor, version: "V3" },
  undefined,
  "preprod"
);
```

### Define Vesting Parameters

```ts
// Lock funds for 1 minute from now
const lockUntilTimestamp = new Date();
lockUntilTimestamp.setMinutes(lockUntilTimestamp.getMinutes() + 1);
const lockUntilMs = lockUntilTimestamp.getTime();

// Amount to lock
const assets = [
  { unit: "lovelace", quantity: "10000000" }, // 10 ADA
];
```

### Build Deposit Transaction

```ts
// Initialize wallet
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "mnemonic", "here"],
});

const utxos = await wallet.getUtxosMesh();
const changeAddress = await wallet.getChangeAddressBech32();

// Get public key hashes
const { pubKeyHash: ownerPubKeyHash } = deserializeAddress(changeAddress);
const { pubKeyHash: beneficiaryPubKeyHash } = deserializeAddress(beneficiaryAddress);

// Build datum
const datum = mConStr0([
  integer(lockUntilMs),
  byteString(ownerPubKeyHash),
  byteString(beneficiaryPubKeyHash),
]);

// Build transaction
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

const unsignedTx = await txBuilder
  .txOut(script.address, assets)
  .txOutInlineDatumValue(datum)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Sign and submit
const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Deposit transaction hash:", txHash);
```

View the transaction on <Link href="https://preprod.cardanoscan.io/">CardanoScan Preprod</Link>.

## Step 6: Withdraw Funds

After the lock period, the beneficiary can withdraw.

### Find the Vesting UTXO

```ts
// Use the deposit transaction hash
const depositTxHash = "556f2bfcd447e146509996343178c046b1b9ad4ac091a7a32f85ae206345e925";
const utxos = await provider.fetchUTxOs(depositTxHash);
const vestingUtxo = utxos[0];
```

### Parse the Datum

```ts
import { deserializeDatum, SLOT_CONFIG_NETWORK, unixTimeToEnclosingSlot } from "@meshsdk/core";

// Define datum type for parsing
type VestingDatum = {
  fields: [
    { int: number },      // lock_until
    { bytes: string },    // owner
    { bytes: string },    // beneficiary
  ];
};

const datum = deserializeDatum<VestingDatum>(vestingUtxo.output.plutusData!);
const lockUntil = datum.fields[0].int;
```

### Calculate Validity Interval

```ts
// Transaction must be valid after the lock time
const invalidBefore = unixTimeToEnclosingSlot(
  Math.min(lockUntil, Date.now() - 15000),  // Use current time if already past lock
  SLOT_CONFIG_NETWORK.preprod
) + 1;
```

### Build Withdrawal Transaction

```ts
const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  verbose: true,
});

// Get beneficiary wallet info
const walletAddress = await beneficiaryWallet.getChangeAddress();
const { pubKeyHash } = deserializeAddress(walletAddress);
const inputUtxos = await beneficiaryWallet.getUtxos();
const collateral = (await beneficiaryWallet.getCollateral())[0];

const unsignedTx = await txBuilder
  // Spend from vesting script
  .spendingPlutusScriptV3()
  .txIn(
    vestingUtxo.input.txHash,
    vestingUtxo.input.outputIndex,
    vestingUtxo.output.amount,
    script.address
  )
  .spendingReferenceTxInInlineDatumPresent()
  .spendingReferenceTxInRedeemerValue("")  // Empty redeemer
  .txInScript(scriptCbor)

  // Output to beneficiary
  .txOut(walletAddress, [])

  // Collateral for script execution
  .txInCollateral(
    collateral.input.txHash,
    collateral.input.outputIndex,
    collateral.output.amount,
    collateral.output.address
  )

  // Time constraint
  .invalidBefore(invalidBefore)

  // Required signature
  .requiredSignerHash(pubKeyHash)

  // Standard transaction components
  .changeAddress(walletAddress)
  .selectUtxosFrom(inputUtxos)
  .complete();

const signedTx = await beneficiaryWallet.signTx(unsignedTx);
const txHash = await beneficiaryWallet.submitTx(signedTx);

console.log("Withdrawal transaction hash:", txHash);
```

## Complete Working Example

### Project Structure

```
vesting-contract/
  aiken-workspace/
    lib/
      vesting/
        types.ak
    validators/
      vesting.ak
    plutus.json
  offchain/
    deposit.ts
    withdraw.ts
```

### Key Transaction Methods

| Method                                         | Purpose                      |
| ---------------------------------------------- | ---------------------------- |
| `txOut(address, assets)`                       | Send funds to script address |
| `txOutInlineDatumValue(datum)`                 | Attach datum to output       |
| `spendingPlutusScriptV3()`                     | Start building script input  |
| `txIn(hash, index, amount, address)`           | Reference the script UTXO    |
| `spendingReferenceTxInInlineDatumPresent()`    | Indicate inline datum        |
| `spendingReferenceTxInRedeemerValue(redeemer)` | Provide redeemer             |
| `txInScript(cbor)`                             | Attach script for validation |
| `invalidBefore(slot)`                          | Set validity lower bound     |
| `requiredSignerHash(hash)`                     | Declare required signer      |

## Key Concepts Explained

### Validity Ranges and Time

Cardano uses slot numbers, not timestamps. Convert between them:

```ts
const slot = unixTimeToEnclosingSlot(timestampMs, SLOT_CONFIG_NETWORK.preprod);
```

Setting `invalidBefore` proves to the script that current time is at least the specified slot.

### Deterministic Execution

The script does not check the current time directly. Instead:

1. Transaction specifies validity bounds
2. Ledger verifies bounds before script execution
3. Script checks if bounds satisfy its requirements

This maintains determinism - the script always produces the same result for the same inputs.

## Exercises

1. **Gradual vesting**: Modify the contract to release 25% of funds every quarter instead of all at once.

2. **Cliff period**: Add a minimum wait time before any vesting begins.

3. **Cancellation**: Allow the owner to cancel vesting and reclaim funds before the lock period.

4. **Multiple beneficiaries**: Support splitting vested funds among multiple recipients.

## Next Steps

You have learned:

* How vesting contracts lock funds with time constraints
* How to use validity ranges for time-based logic
* How to build deposit and withdrawal transactions
* How to test vesting scenarios

In the next lesson, you build a <Link href="/resources/cardano-course/08-plutus-nft">Plutus NFT contract</Link> with auto-incrementing indices.

## Related Links

* <Link href="https://github.com/cardanobuilders/cardanobuilders.github.io/tree/main/codes/course-hello-cardano/03-vesting">Source Code on GitHub</Link>
* <Link href="https://preprod.cardanoscan.io/transaction/556f2bfcd447e146509996343178c046b1b9ad4ac091a7a32f85ae206345e925">Example Deposit Transaction</Link>
* <Link href="https://preprod.cardanoscan.io/transaction/13d6b2258680bbdf08f50a3bbc03e7ed674f5614844ce773fc191c9582282b04">Example Withdrawal Transaction</Link>
* <Link href="/apis/txbuilder">MeshTxBuilder API Reference</Link>


# Lesson 8: Plutus NFT Contract
URL: /resources/cardano-course/08-plutus-nft

Create an NFT minting contract with auto-incrementing indices using multiple validators.

***

title: "Lesson 8: Plutus NFT Contract"
description: "Create an NFT minting contract with auto-incrementing indices using multiple validators."
-------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Design a multi-validator NFT minting system
* Implement one-time minting policies for oracle tokens
* Use state thread tokens to maintain on-chain state
* Build transactions that interact with multiple scripts
* Prevent common vulnerabilities like unbounded value attacks

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/07-vesting">Lesson 7: Vesting Contract</Link>
* Understanding of minting and spending validators
* Familiarity with datum and state management

## Key Concepts

### What is a Plutus NFT?

A Plutus NFT uses smart contracts to enforce:

* **Non-fungibility**: Each token has a unique name
* **Controlled minting**: Only authorized parties can mint
* **Sequential naming**: Tokens have incrementing indices like "Collection (0)", "Collection (1)", etc.

### Architecture Overview

The system uses three validators working together:

| Validator            | Purpose                                            |
| -------------------- | -------------------------------------------------- |
| **Oracle NFT**       | One-time minting policy for the state thread token |
| **Oracle Validator** | Holds and updates the current NFT index            |
| **Plutus NFT**       | Mints new NFTs with the correct name               |

```
                    ┌─────────────────┐
                    │   Oracle NFT    │
                    │  (one-time)     │
                    └────────┬────────┘
                             │ creates
                             ▼
                    ┌─────────────────┐
                    │ Oracle Validator │◄──── stores count
                    │   (holds state)  │
                    └────────┬────────┘
                             │ reads count
                             ▼
                    ┌─────────────────┐
                    │   Plutus NFT    │──── mints "Collection (N)"
                    │  (minting)      │
                    └─────────────────┘
```

## Step 1: Create the Oracle NFT Policy

The oracle NFT is a one-time minting policy that creates the state thread token.

```rs
// validators/oracle_nft.ak

use cardano/assets.{PolicyId}
use cardano/transaction.{Input, OutputReference, Transaction}
use vodka/extra/value.{check_policy_only_burn}

pub type MintPolarity {
  RMint
  RBurn
}

validator oracle_nft(utxo_ref: OutputReference) {
  mint(redeemer: MintPolarity, policy_id: PolicyId, tx: Transaction) {
    when redeemer is {
      RMint -> {
        let Transaction { inputs, .. } = tx
        // Check if the specified UTXO is consumed
        let hash_equal = fn(input: Input) {
          input.output_reference == utxo_ref
        }
        list.any(inputs, hash_equal)
      }
      RBurn -> check_policy_only_burn(tx.mint, policy_id)
    }
  }

  else(_) {
    fail
  }
}
```

### How One-Time Minting Works

1. The `utxo_ref` parameter points to a specific UTXO
2. Minting requires consuming that exact UTXO
3. Once spent, the UTXO can never exist again
4. Therefore, minting can only happen once

The `RBurn` redeemer allows burning the oracle NFT later if needed.

## Step 2: Create the Oracle Validator

The oracle validator holds the state thread token and current NFT count.

### Define the Datum

```rs
// lib/plutus_nft/types.ak

use cardano/address.{Address}

pub type OracleDatum {
  count: Int,              // Current NFT index
  lovelace_price: Int,     // Price per NFT in lovelace
  fee_address: Address,    // Where fees go
}

pub type OracleRedeemer {
  MintPlutusNFT
  StopOracle
}
```

### Implement the Validator

```rs
// validators/oracle.ak

use cardano/assets.{PolicyId, flatten, from_lovelace}
use cardano/transaction.{InlineDatum, OutputReference, Transaction, find_input}
use plutus_nft/types.{MintPlutusNFT, OracleDatum, OracleRedeemer, StopOracle}
use vodka/extra/list.{
  inputs_at_with_policy, key_signed, outputs_at_with_policy,
}
use vodka/extra/value.{get_all_value_to, only_minted_token, value_geq}
use vodka/extra/address.{address_payment_key}

validator oracle {
  spend(
    datum_opt: Option<OracleDatum>,
    redeemer: OracleRedeemer,
    input: OutputReference,
    tx: Transaction,
  ) {
    let Transaction { mint, inputs, outputs, extra_signatories, .. } = tx

    expect Some(OracleDatum { count, lovelace_price, fee_address }) = datum_opt
    expect Some(own_input) = find_input(inputs, input)

    // Extract the oracle NFT policy from the input value
    expect [(oracle_nft_policy, _, _)] =
      list.filter(flatten(own_input.output.value), fn(x) { x.1st != "" })

    let own_address = own_input.output.address

    when
      (
        redeemer,
        inputs_at_with_policy(inputs, own_address, oracle_nft_policy),
        outputs_at_with_policy(outputs, own_address, oracle_nft_policy),
      )
    is {
      (MintPlutusNFT, [_], [only_output]) -> {
        // Ensure output value only contains oracle NFT and ADA (no spam)
        let is_output_value_clean = list.length(flatten(only_output.value)) == 2

        // Verify count is incremented
        let is_count_updated =
          only_output.datum == InlineDatum(
            OracleDatum { count: count + 1, lovelace_price, fee_address },
          )

        // Verify fee is paid
        let is_fee_paid =
          get_all_value_to(outputs, fee_address)
            |> value_geq(from_lovelace(lovelace_price))

        is_output_value_clean? && is_count_updated? && is_fee_paid?
      }

      (StopOracle, [_], _) -> {
        // Owner burns the oracle NFT to stop the collection
        let is_oracle_nft_burnt =
          only_minted_token(mint, oracle_nft_policy, "", -1)
        let owner_key = address_payment_key(fee_address)
        let is_owner_signed = key_signed(extra_signatories, owner_key)
        is_oracle_nft_burnt? && is_owner_signed?
      }

      _ -> False
    }
  }

  else(_) {
    fail
  }
}
```

### Preventing Unbounded Value Attack

The `is_output_value_clean` check prevents a vulnerability:

```rs
let is_output_value_clean = list.length(flatten(only_output.value)) == 2
```

Without this check, attackers could attach many tokens to the oracle UTXO, eventually making it unspendable due to transaction size limits. By requiring exactly 2 assets (ADA + oracle NFT), we prevent this attack.

## Step 3: Create the Plutus NFT Minting Policy

The NFT minting policy reads the current count from the oracle and mints a correctly named token.

```rs
// validators/plutus_nft.ak

use aiken/bytearray.{concat}
use cardano/assets.{PolicyId}
use cardano/transaction.{InlineDatum, Transaction}
use plutus_nft/types.{MintPolarity, OracleDatum, RBurn, RMint}
use vodka/extra/list.{inputs_with_policy}
use vodka/extra/value.{check_policy_only_burn, only_minted_token}
use vodka/extra/int.{convert_int_to_bytes}

validator plutus_nft(collection_name: ByteArray, oracle_nft: PolicyId) {
  mint(redeemer: MintPolarity, policy_id: PolicyId, tx: Transaction) {
    when redeemer is {
      RMint -> {
        let Transaction { inputs, mint, .. } = tx

        // Find the oracle input with the oracle NFT
        expect [auth_input] = inputs_with_policy(inputs, oracle_nft)
        expect InlineDatum(input_datum) = auth_input.output.datum
        expect OracleDatum { count, .. }: OracleDatum = input_datum

        // Build the expected token name: "CollectionName (N)"
        let asset_name =
          collection_name
            |> concat(" (")
            |> concat(convert_int_to_bytes(count))
            |> concat(")")

        // Verify exactly one token with the correct name is minted
        only_minted_token(mint, policy_id, asset_name, 1)
      }

      RBurn -> check_policy_only_burn(tx.mint, policy_id)
    }
  }

  else(_) {
    fail
  }
}
```

### Token Naming

The NFT name follows a predictable pattern:

```
"MyCollection (0)"
"MyCollection (1)"
"MyCollection (2)"
...
```

This is constructed by:

1. Taking the `collection_name` parameter
2. Appending " ("
3. Appending the count as a string
4. Appending ")"

## Step 4: Set Up the Oracle

Before minting NFTs, initialize the oracle with its state thread token.

```ts
import {
  BlockfrostProvider,
  MeshTxBuilder,
  applyParamsToScript,
  resolveScriptHash,
  serializePlutusScript,
  mOutputReference,
  mConStr0,
  mPubKeyAddress,
  deserializeAddress,
} from "@meshsdk/core";
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import blueprint from "./plutus.json";

const provider = new BlockfrostProvider("YOUR_BLOCKFROST_API_KEY");

// Initialize wallet
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "mnemonic"],
});

const utxos = await wallet.getUtxosMesh();
const collateral = (await wallet.getCollateral())[0];
const walletAddress = await wallet.getChangeAddressBech32();

// Select a UTXO to parameterize the one-time minting policy
const paramUtxo = utxos[0];
const param = mOutputReference(
  paramUtxo.input.txHash,
  paramUtxo.input.outputIndex
);

// Get oracle NFT compiled code and apply parameter
const oracleNftValidator = blueprint.validators.find(
  (v) => v.title === "oracle_nft.oracle_nft.mint"
);
const oracleNftScript = applyParamsToScript(oracleNftValidator.compiledCode, [param]);
const oracleNftPolicyId = resolveScriptHash(oracleNftScript, "V3");

// Get oracle validator address
const oracleValidator = blueprint.validators.find(
  (v) => v.title === "oracle.oracle.spend"
);
const oracleScript = serializePlutusScript(
  { code: oracleValidator.compiledCode, version: "V3" },
  undefined,
  "preprod"
);

// Build initial oracle datum
const { pubKeyHash, stakeCredentialHash } = deserializeAddress(walletAddress);
const lovelacePrice = 5000000; // 5 ADA per NFT

const txBuilder = new MeshTxBuilder({ fetcher: provider, verbose: true });

const unsignedTx = await txBuilder
  // Consume the parameter UTXO (enables one-time minting)
  .txIn(
    paramUtxo.input.txHash,
    paramUtxo.input.outputIndex,
    paramUtxo.output.amount,
    paramUtxo.output.address
  )
  // Mint the oracle NFT
  .mintPlutusScriptV3()
  .mint("1", oracleNftPolicyId, "")
  .mintingScript(oracleNftScript)
  .mintRedeemerValue(mConStr0([]))  // RMint
  // Send oracle NFT to oracle address with initial datum
  .txOut(oracleScript.address, [{ unit: oracleNftPolicyId, quantity: "1" }])
  .txOutInlineDatumValue(
    mConStr0([
      0,  // count starts at 0
      lovelacePrice,
      mPubKeyAddress(pubKeyHash, stakeCredentialHash),
    ])
  )
  // Collateral
  .txInCollateral(
    collateral.input.txHash,
    collateral.input.outputIndex,
    collateral.output.amount,
    collateral.output.address
  )
  .changeAddress(walletAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);

console.log("Oracle setup transaction:", txHash);
// Save paramUtxo info for later use
```

## Step 5: Mint an NFT

With the oracle set up, mint NFTs by updating the oracle state and minting the token.

```ts
import { stringToHex, parseDatumCbor, integer, conStr0 } from "@meshsdk/core";

// Helper to find UTXOs with a specific token
const getAddressUtxosWithToken = async (address: string, assetHex: string) => {
  const utxos = await provider.fetchAddressUTxOs(address);
  return utxos.filter((u) => {
    const assetAmount = u.output.amount.find((a) => a.unit === assetHex)?.quantity;
    return Number(assetAmount) >= 1;
  });
};

// Get current oracle data
const getOracleData = async () => {
  const oracleUtxo = (await getAddressUtxosWithToken(oracleScript.address, oracleNftPolicyId))[0];
  const oracleDatum = parseDatumCbor(oracleUtxo.output.plutusData!);

  return {
    nftIndex: oracleDatum.fields[0].int,
    lovelacePrice: oracleDatum.fields[1].int,
    feeCollectorAddress: serializeAddressObj(oracleDatum.fields[2], "preprod"),
    feeCollectorAddressObj: oracleDatum.fields[2],
    oracleUtxo,
  };
};

// Mint the NFT
const mintNft = async () => {
  const utxos = await wallet.getUtxosMesh();
  const collateral = (await wallet.getCollateral())[0];
  const walletAddress = await wallet.getChangeAddressBech32();

  const collectionName = "MyNFTCollection";

  // Get NFT minting script
  const nftValidator = blueprint.validators.find(
    (v) => v.title === "plutus_nft.plutus_nft.mint"
  );
  const nftScript = applyParamsToScript(nftValidator.compiledCode, [
    stringToHex(collectionName),
    oracleNftPolicyId,
  ]);
  const nftPolicyId = resolveScriptHash(nftScript, "V3");

  // Get current oracle state
  const { nftIndex, lovelacePrice, feeCollectorAddress, feeCollectorAddressObj, oracleUtxo } =
    await getOracleData();

  // Build token name
  const tokenName = `${collectionName} (${nftIndex})`;
  const tokenNameHex = stringToHex(tokenName);

  // Build updated oracle datum
  const updatedOracleDatum = conStr0([
    integer(nftIndex + 1),
    integer(lovelacePrice),
    feeCollectorAddressObj,
  ]);

  const txBuilder = new MeshTxBuilder({ fetcher: provider, verbose: true });

  // Spend the oracle UTXO
  txBuilder
    .spendingPlutusScriptV3()
    .txIn(
      oracleUtxo.input.txHash,
      oracleUtxo.input.outputIndex,
      oracleUtxo.output.amount,
      oracleUtxo.output.address
    )
    .txInRedeemerValue(mConStr0([]))  // MintPlutusNFT
    .txInScript(oracleValidator.compiledCode)
    .txInInlineDatumPresent()

    // Output oracle with updated state
    .txOut(oracleScript.address, [{ unit: oracleNftPolicyId, quantity: "1" }])
    .txOutInlineDatumValue(updatedOracleDatum, "JSON")

    // Mint the NFT
    .mintPlutusScriptV3()
    .mint("1", nftPolicyId, tokenNameHex)
    .mintingScript(nftScript)
    .mintRedeemerValue(mConStr0([]));  // RMint

  // Add CIP-25 metadata
  const assetMetadata = {
    name: tokenName,
    image: "ipfs://QmRzicpReutwCkM6aotuKjErFCUD213DpwPq6ByuzMJaua",
    mediaType: "image/jpg",
    description: "This NFT was minted by Mesh (https://meshjs.dev/).",
  };
  const metadata = { [nftPolicyId]: { [tokenName]: assetMetadata } };
  txBuilder.metadataValue(721, metadata);

  // Pay the fee
  txBuilder
    .txOut(feeCollectorAddress, [{ unit: "lovelace", quantity: lovelacePrice.toString() }])
    .txInCollateral(
      collateral.input.txHash,
      collateral.input.outputIndex,
      collateral.output.amount,
      collateral.output.address
    )
    .changeAddress(walletAddress)
    .selectUtxosFrom(utxos);

  const unsignedTx = await txBuilder.complete();
  const signedTx = await wallet.signTx(unsignedTx, false);
  const txHash = await wallet.submitTx(signedTx);

  console.log("NFT minted:", tokenName);
  console.log("Transaction hash:", txHash);
};
```

## Complete Working Example

### Project Structure

```
plutus-nft/
  aiken-workspace/
    lib/
      plutus_nft/
        types.ak
    validators/
      oracle_nft.ak
      oracle.ak
      plutus_nft.ak
    plutus.json
  offchain/
    setup-oracle.ts
    mint-nft.ts
```

### Transaction Flow

1. **Setup Oracle**
   * Consume parameter UTXO
   * Mint oracle NFT (one-time)
   * Create oracle UTXO with count=0

2. **Mint NFT**
   * Spend oracle UTXO (validates count increment, fee payment)
   * Mint NFT with name "Collection (N)"
   * Output oracle with count=N+1
   * Pay fee to collector

## Key Concepts Explained

### State Thread Token Pattern

The oracle NFT serves as a "state thread token":

* **Uniqueness**: Only one oracle NFT exists
* **Location tracking**: Find the current state by locating the NFT
* **Continuity**: The NFT must be carried forward in valid transactions

### Multi-Validator Coordination

The three validators work together:

1. **Oracle NFT**: Ensures the oracle can only be created once
2. **Oracle Validator**: Manages state updates and fee collection
3. **Plutus NFT**: Reads state and mints correctly named tokens

Each validator trusts the others through:

* Policy ID references
* Input/output validation
* Consistent datum structures

## Exercises

1. **Maximum supply**: Modify the oracle to enforce a maximum NFT count.

2. **Whitelist minting**: Add a whitelist of addresses allowed to mint before public sale.

3. **Dynamic pricing**: Implement a bonding curve where price increases with each mint.

4. **Batch minting**: Allow minting multiple NFTs in a single transaction.

## Next Steps

You have learned:

* How to design multi-validator systems
* How to implement one-time minting policies
* How to use state thread tokens for on-chain state
* How to prevent unbounded value attacks

In the next lesson, you explore <Link href="/resources/cardano-course/09-hydra">Hydra</Link> for Layer 2 scaling.

## Related Links

* <Link href="https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/plutus-nft">Mesh Plutus NFT Contract Source</Link>
* <Link href="/smart-contracts/plutus-nft">Mesh SDK Plutus NFT Documentation</Link>
* <Link href="https://cips.cardano.org/cips/cip25/">CIP-25: NFT Metadata Standard</Link>


# Lesson 9: Hydra End-to-End
URL: /resources/cardano-course/09-hydra

Implement Layer 2 scaling with the Hydra Head protocol for fast, low-cost transactions.

***

title: "Lesson 9: Hydra End-to-End"
description: "Implement Layer 2 scaling with the Hydra Head protocol for fast, low-cost transactions."
------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Understand the Hydra Head protocol and its benefits
* Set up Hydra nodes for a multi-party state channel
* Open, use, and close Hydra Heads
* Build applications that leverage Hydra for scalability
* Understand when to use Hydra vs Layer 1

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/08-plutus-nft">Lesson 8: Plutus NFT Contract</Link>
* Docker installed on your system
* Multiple funded preprod wallets
* Understanding of state channels conceptually

## Key Concepts

### What is Hydra?

Hydra is Cardano's Layer 2 scaling solution. It enables:

* **Instant finality**: Transactions confirm in milliseconds
* **Near-zero fees**: No on-chain fees for off-chain transactions
* **Full Plutus support**: Smart contracts work inside Hydra Heads
* **Isomorphic**: Same transaction format as Layer 1

### How Hydra Works

1. **Open a Head**: Participants lock funds on Layer 1
2. **Transact off-chain**: Process transactions instantly within the Head
3. **Close the Head**: Final state is committed back to Layer 1

```
Layer 1 (Cardano mainnet)
    │
    ├── Open Head ──────────────────► Lock funds
    │
    │   Layer 2 (Hydra Head)
    │   ┌────────────────────────┐
    │   │ TX → TX → TX → TX → TX │   Fast transactions
    │   └────────────────────────┘
    │
    ├── Close Head ─────────────────► Commit final state
    │
Layer 1 (Cardano mainnet)
```

### Hydra vs Layer 1

| Aspect       | Layer 1       | Hydra                     |
| ------------ | ------------- | ------------------------- |
| Finality     | 20+ seconds   | Milliseconds              |
| Throughput   | \~250 TPS     | 1000+ TPS per Head        |
| Fees         | Protocol fees | Near-zero                 |
| Availability | Always on     | Requires all participants |
| Trust        | Trustless     | Participants can abort    |

## Step 1: Understand the Architecture

A Hydra Head consists of:

* **Hydra Nodes**: One per participant, running the protocol
* **Cardano Node**: Connected to Layer 1 for opening/closing
* **Clients**: Applications that submit transactions to the Head

```
┌─────────────────────────────────────────────────────┐
│                    Hydra Head                        │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐        │
│  │  Node A  │◄─►│  Node B  │◄─►│  Node C  │        │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘        │
│       │              │              │               │
│  ┌────┴─────┐   ┌────┴─────┐   ┌────┴─────┐        │
│  │ Client A │   │ Client B │   │ Client C │        │
│  └──────────┘   └──────────┘   └──────────┘        │
└─────────────────────┬───────────────────────────────┘
                      │
              ┌───────┴───────┐
              │ Cardano Node  │
              │   (Layer 1)   │
              └───────────────┘
```

## Step 2: Set Up the Environment

### Prerequisites

Install the required software:

```bash
# Install Docker
# Follow instructions at https://docs.docker.com/get-docker/

# Verify installation
docker --version
docker-compose --version
```

### Clone the Hydra Repository

```bash
git clone https://github.com/input-output-hk/hydra.git
cd hydra
```

### Generate Keys

Each participant needs:

* A Cardano signing key (for Layer 1)
* A Hydra signing key (for the Head protocol)

```bash
# Generate Cardano keys
cardano-cli address key-gen \
  --signing-key-file alice.sk \
  --verification-key-file alice.vk

# Generate Hydra keys
hydra-node gen-hydra-key \
  --output-file alice-hydra
```

Repeat for each participant (Bob, Carol, etc.).

## Step 3: Configure Hydra Nodes

Create a configuration file for each participant:

```yaml
# alice.yaml
hydraNodeId: alice
host: 0.0.0.0
port: 5001
apiHost: 0.0.0.0
apiPort: 4001
monitoringPort: 6001
persistenceDir: ./alice-state
cardanoNodeSocket: /ipc/node.socket
cardanoSigningKey: ./alice.sk
hydraSigningKey: ./alice-hydra.sk
hydraVerificationKeys:
  - ./bob-hydra.vk
  - ./carol-hydra.vk
contestationPeriod: 60
```

Key configuration options:

| Option                  | Description                             |
| ----------------------- | --------------------------------------- |
| `hydraNodeId`           | Unique identifier for this node         |
| `port`                  | Port for Hydra protocol communication   |
| `apiPort`               | Port for client WebSocket connections   |
| `cardanoSigningKey`     | Layer 1 signing key                     |
| `hydraSigningKey`       | Hydra protocol signing key              |
| `hydraVerificationKeys` | Verification keys of other participants |
| `contestationPeriod`    | Time (seconds) to contest a close       |

## Step 4: Start the Hydra Network

### Using Docker Compose

Create a `docker-compose.yml`:

```yaml
version: "3.8"

services:
  cardano-node:
    image: inputoutput/cardano-node:latest
    volumes:
      - ./node-data:/data
      - ./ipc:/ipc
    environment:
      - NETWORK=preprod

  alice-hydra:
    image: ghcr.io/input-output-hk/hydra-node:latest
    depends_on:
      - cardano-node
    volumes:
      - ./alice-state:/state
      - ./keys:/keys
      - ./ipc:/ipc
    ports:
      - "4001:4001"
    command:
      - --config
      - /keys/alice.yaml

  bob-hydra:
    image: ghcr.io/input-output-hk/hydra-node:latest
    depends_on:
      - cardano-node
    volumes:
      - ./bob-state:/state
      - ./keys:/keys
      - ./ipc:/ipc
    ports:
      - "4002:4001"
    command:
      - --config
      - /keys/bob.yaml
```

Start the network:

```bash
docker-compose up -d
```

## Step 5: Open a Hydra Head

Connect to a Hydra node via WebSocket and send commands.

### Connect to the API

```ts
import WebSocket from "ws";

const ws = new WebSocket("ws://localhost:4001");

ws.on("open", () => {
  console.log("Connected to Hydra node");
});

ws.on("message", (data) => {
  const message = JSON.parse(data.toString());
  console.log("Received:", message);
});
```

### Initialize the Head

```ts
// Each participant sends Init
ws.send(JSON.stringify({ tag: "Init" }));
```

After all participants initialize, the Head moves to the "Initializing" state.

### Commit Funds

Each participant commits UTXOs to the Head:

```ts
// Commit a UTXO
ws.send(JSON.stringify({
  tag: "Commit",
  utxo: {
    "txhash#index": {
      address: "addr_test1...",
      value: { lovelace: 10000000 }
    }
  }
}));
```

After all commits, the Head opens automatically.

## Step 6: Transact in the Head

Once open, submit transactions directly to the Head.

### Build a Transaction

Use the same transaction format as Layer 1:

```ts
import { MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet } from "@meshsdk/wallet";

// Build transaction (same as Layer 1!)
const txBuilder = new MeshTxBuilder();
const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "1000000" }])
  .changeAddress(myAddress)
  .selectUtxosFrom(headUtxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
```

### Submit to the Head

```ts
// Send the transaction to the Head
ws.send(JSON.stringify({
  tag: "NewTx",
  transaction: {
    cborHex: signedTx
  }
}));
```

### Handle Confirmation

```ts
ws.on("message", (data) => {
  const message = JSON.parse(data.toString());

  if (message.tag === "TxValid") {
    console.log("Transaction confirmed:", message.transaction);
  }

  if (message.tag === "TxInvalid") {
    console.error("Transaction failed:", message.validationError);
  }
});
```

## Step 7: Close the Head

When finished, close the Head to commit the final state to Layer 1.

### Initiate Close

```ts
ws.send(JSON.stringify({ tag: "Close" }));
```

### Contestation Period

After closing, there is a contestation period where participants can dispute the final state. If no disputes occur, the Head finalizes.

### Fanout

After the contestation period, anyone can trigger the fanout:

```ts
ws.send(JSON.stringify({ tag: "Fanout" }));
```

This distributes the Head's final UTXOs back to Layer 1.

## Complete Working Example

### Project Structure

```
hydra-demo/
  docker-compose.yml
  keys/
    alice.sk
    alice.vk
    alice-hydra.sk
    alice-hydra.vk
    alice.yaml
    bob.sk
    bob.vk
    bob-hydra.sk
    bob-hydra.vk
    bob.yaml
  client/
    index.ts
    hydra-client.ts
```

### hydra-client.ts

```ts
import WebSocket from "ws";
import { MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoHeadlessWallet } from "@meshsdk/wallet";

export class HydraClient {
  private ws: WebSocket;
  private wallet: MeshCardanoHeadlessWallet;
  private headUtxos: Map<string, any> = new Map();

  constructor(nodeUrl: string, wallet: MeshCardanoHeadlessWallet) {
    this.ws = new WebSocket(nodeUrl);
    this.wallet = wallet;
    this.setupListeners();
  }

  private setupListeners() {
    this.ws.on("message", (data) => {
      const message = JSON.parse(data.toString());
      this.handleMessage(message);
    });
  }

  private handleMessage(message: any) {
    switch (message.tag) {
      case "HeadIsOpen":
        console.log("Head is open with UTXOs:", message.utxo);
        this.headUtxos = new Map(Object.entries(message.utxo));
        break;
      case "TxValid":
        console.log("Transaction confirmed");
        // Update local UTXO set
        break;
      case "HeadIsClosed":
        console.log("Head closed, contestation period started");
        break;
      case "HeadIsFinalized":
        console.log("Head finalized, funds returned to Layer 1");
        break;
    }
  }

  async init() {
    this.ws.send(JSON.stringify({ tag: "Init" }));
  }

  async commit(utxos: any) {
    this.ws.send(JSON.stringify({ tag: "Commit", utxo: utxos }));
  }

  async sendPayment(recipient: string, amount: string) {
    const txBuilder = new MeshTxBuilder();
    const myAddress = await this.wallet.getChangeAddressBech32();

    const unsignedTx = await txBuilder
      .txOut(recipient, [{ unit: "lovelace", quantity: amount }])
      .changeAddress(myAddress)
      .selectUtxosFrom(Array.from(this.headUtxos.values()))
      .complete();

    const signedTx = await this.wallet.signTx(unsignedTx, false);

    this.ws.send(JSON.stringify({
      tag: "NewTx",
      transaction: { cborHex: signedTx }
    }));
  }

  async close() {
    this.ws.send(JSON.stringify({ tag: "Close" }));
  }

  async fanout() {
    this.ws.send(JSON.stringify({ tag: "Fanout" }));
  }
}
```

## Key Concepts Explained

### Isomorphic Transactions

Hydra uses the same transaction format as Layer 1. This means:

* Existing tools work (MeshTxBuilder, etc.)
* Smart contracts work unchanged
* Developers do not need to learn new formats

### Contestation Period

The contestation period protects against dishonest closes:

1. Participant closes with an old state
2. Others see this and contest with the newer state
3. The chain accepts the latest valid state

Choose contestation period based on your use case:

* Shorter = faster finality, less protection
* Longer = more protection, slower finality

### Availability Requirements

All participants must be online for the Head to function. If one goes offline:

* New transactions cannot be processed
* The Head can still be closed
* Funds are never at risk

## Use Cases

| Use Case          | Why Hydra?                          |
| ----------------- | ----------------------------------- |
| **Gaming**        | Instant moves, no transaction fees  |
| **Micropayments** | Sub-cent payments become viable     |
| **DEX**           | High-frequency trading              |
| **Voting**        | Fast, cheap vote recording          |
| **IoT**           | High-throughput device interactions |

## Exercises

1. **Three-party Head**: Set up a Hydra Head with three participants and execute round-robin payments.

2. **Smart contract in Head**: Deploy a simple swap contract inside a Hydra Head.

3. **Benchmark throughput**: Measure how many transactions per second your Head can process.

## Next Steps

You have learned:

* How Hydra enables Layer 2 scaling
* How to set up and operate Hydra nodes
* How to open, transact in, and close Hydra Heads
* When to use Hydra for your applications

In the final lesson, you explore <Link href="/resources/cardano-course/10-web3-services">Web3 services</Link> for seamless user onboarding.

## Related Links

* <Link href="https://hydra.family/head-protocol/">Hydra Documentation</Link>
* <Link href="https://github.com/input-output-hk/hydra">Hydra GitHub Repository</Link>
* <Link href="https://hydra.family/head-protocol/docs/tutorial/">Hydra Tutorial</Link>


# Lesson 10: Web3 Services
URL: /resources/cardano-course/10-web3-services

Integrate wallet-as-a-service and transaction sponsorship for seamless user onboarding.

***

title: "Lesson 10: Web3 Services"
description: "Integrate wallet-as-a-service and transaction sponsorship for seamless user onboarding."
------------------------------------------------------------------------------------------------------

import Link from "fumadocs-core/link";

## Learning Objectives

By the end of this lesson, you will be able to:

* Understand wallet-as-a-service (WaaS) architecture
* Implement social login wallet creation
* Set up transaction sponsorship for gasless user experience
* Design onboarding flows that hide blockchain complexity
* Evaluate trade-offs between custody models

## Prerequisites

Before starting this lesson, ensure you have:

* Completed <Link href="/resources/cardano-course/09-hydra">Lesson 9: Hydra End-to-End</Link>
* A web application framework (Next.js, React, etc.)
* Understanding of authentication flows

## Key Concepts

### The Onboarding Challenge

Traditional blockchain onboarding requires users to:

1. Install a browser extension or mobile app
2. Understand and securely store seed phrases
3. Acquire native tokens (ADA) for transaction fees
4. Navigate unfamiliar wallet interfaces

Each step loses potential users. Web3 services eliminate these friction points.

### Wallet-as-a-Service (WaaS)

WaaS provides wallets without requiring users to manage keys directly:

| Feature         | Traditional Wallet            | WaaS                  |
| --------------- | ----------------------------- | --------------------- |
| Setup           | Install extension, write seed | Social login          |
| Key storage     | User's responsibility         | Distributed/encrypted |
| Recovery        | 24-word seed phrase           | Email/social recovery |
| User experience | Technical                     | Familiar              |

### Transaction Sponsorship

Transaction sponsorship allows developers to pay fees on behalf of users:

* Users transact without holding ADA
* Developers cover network costs
* Removes the "buy crypto first" barrier

## Step 1: Understand WaaS Architecture

### Shamir's Secret Sharing

Modern WaaS solutions use Shamir's Secret Sharing to distribute private keys:

```
Private Key splits into:
  Share 1: Stored on user's device
  Share 2: Encrypted on server
  Share 3: Recovery backup (optional)
```

Key reconstruction requires multiple shares, so:

* The server alone cannot access funds
* A lost device can be recovered
* Users maintain self-custody

### Security Model

```
┌─────────────────────────────────────────────────────┐
│                    Transaction Signing               │
│                                                      │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐        │
│  │  Share 1 │ + │  Share 2 │ = │ Full Key │        │
│  │ (Device) │   │ (Server) │   │(Temporary)│        │
│  └──────────┘   └──────────┘   └────┬─────┘        │
│                                      │              │
│                              ┌───────▼───────┐      │
│                              │  Sign TX in   │      │
│                              │ Isolated iFrame│      │
│                              └───────┬───────┘      │
│                                      │              │
│                              ┌───────▼───────┐      │
│                              │   Key Destroyed│      │
│                              │  After Signing │      │
│                              └───────────────┘      │
└─────────────────────────────────────────────────────┘
```

The full key:

* Only exists in memory briefly
* Lives in an isolated iframe
* Is destroyed immediately after signing

## Step 2: Integrate Wallet-as-a-Service

Use UTXOS WaaS to add social login wallets to your application.

### Installation

```bash
npm install @utxos/wallet-sdk
```

### Initialize the SDK

```ts
import { UTXOSWallet } from "@utxos/wallet-sdk";

const wallet = new UTXOSWallet({
  apiKey: "YOUR_UTXOS_API_KEY",
  network: "preprod",  // or "mainnet"
});
```

### Social Login Integration

```tsx
import { useState } from "react";
import { UTXOSWallet } from "@utxos/wallet-sdk";

export function WalletConnect() {
  const [wallet, setWallet] = useState<UTXOSWallet | null>(null);
  const [address, setAddress] = useState<string>("");

  async function connectWithGoogle() {
    const utxosWallet = new UTXOSWallet({
      apiKey: "YOUR_UTXOS_API_KEY",
      network: "preprod",
    });

    // Opens Google OAuth flow
    await utxosWallet.connectWithGoogle();

    // Get the wallet address
    const walletAddress = await utxosWallet.getAddress();

    setWallet(utxosWallet);
    setAddress(walletAddress);
  }

  async function connectWithEmail() {
    const utxosWallet = new UTXOSWallet({
      apiKey: "YOUR_UTXOS_API_KEY",
      network: "preprod",
    });

    // Sends magic link to email
    await utxosWallet.connectWithEmail("user@example.com");

    // Wait for user to click link...
  }

  return (
    <div>
      {!wallet ? (
        <div>
          <button onClick={connectWithGoogle}>
            Continue with Google
          </button>
          <button onClick={connectWithEmail}>
            Continue with Email
          </button>
        </div>
      ) : (
        <div>
          <p>Connected: {address}</p>
        </div>
      )}
    </div>
  );
}
```

### Sign Transactions

Use the WaaS wallet like any other wallet:

```ts
import { MeshTxBuilder } from "@meshsdk/core";

async function sendTransaction(wallet: UTXOSWallet) {
  const utxos = await wallet.getUtxos();
  const address = await wallet.getAddress();

  const txBuilder = new MeshTxBuilder();

  const unsignedTx = await txBuilder
    .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
    .changeAddress(address)
    .selectUtxosFrom(utxos)
    .complete();

  // Signs in isolated iframe using reconstructed key
  const signedTx = await wallet.signTx(unsignedTx);

  // Submit to blockchain
  const txHash = await wallet.submitTx(signedTx);

  return txHash;
}
```

### Export Keys

Users can export their private keys at any time:

```ts
async function exportPrivateKey(wallet: UTXOSWallet) {
  // Requires re-authentication
  const privateKey = await wallet.exportPrivateKey();

  // Display to user (they can import into any standard wallet)
  console.log("Your private key:", privateKey);
}
```

## Step 3: Implement Transaction Sponsorship

Transaction sponsorship eliminates the need for users to hold ADA.

### How Sponsorship Works

```
┌─────────────┐                    ┌─────────────┐
│    User     │                    │  Sponsor    │
│  (no ADA)   │                    │ (has ADA)   │
└──────┬──────┘                    └──────┬──────┘
       │                                  │
       │  1. Build transaction            │
       │  (no inputs from user)           │
       │                                  │
       │  2. Send to sponsor API ────────►│
       │                                  │
       │  3. Sponsor adds inputs ◄────────│
       │     and pays fees                │
       │                                  │
       │  4. User signs ─────────────────►│
       │                                  │
       │  5. Sponsor signs ◄──────────────│
       │                                  │
       │  6. Submit to blockchain         │
       ▼                                  ▼
```

### Configure Sponsorship

```ts
import { UTXOSSponsor } from "@utxos/sponsor-sdk";

const sponsor = new UTXOSSponsor({
  apiKey: "YOUR_UTXOS_SPONSOR_API_KEY",
  network: "preprod",
});
```

### Build a Sponsored Transaction

```ts
import { MeshTxBuilder } from "@meshsdk/core";

async function buildSponsoredTransaction(
  wallet: UTXOSWallet,
  sponsor: UTXOSSponsor
) {
  const userAddress = await wallet.getAddress();

  // Build transaction without user inputs
  const txBuilder = new MeshTxBuilder();

  const partialTx = await txBuilder
    .txOut(recipientAddress, [{ unit: "lovelace", quantity: "2000000" }])
    .changeAddress(userAddress)
    // No selectUtxosFrom - sponsor will provide inputs
    .complete({ noCoinSelection: true });

  // Send to sponsor to add inputs and fees
  const sponsoredTx = await sponsor.sponsorTransaction(partialTx);

  // User signs their part
  const userSignedTx = await wallet.signTx(sponsoredTx, true);

  // Sponsor signs and submits
  const txHash = await sponsor.submitSponsoredTransaction(userSignedTx);

  return txHash;
}
```

### Sponsorship Policies

Configure rules for what transactions to sponsor:

```ts
const sponsor = new UTXOSSponsor({
  apiKey: "YOUR_API_KEY",
  network: "preprod",
  policies: {
    // Maximum ADA to sponsor per transaction
    maxFeePerTx: 2_000_000,  // 2 ADA

    // Maximum daily sponsorship per user
    maxDailyPerUser: 10_000_000,  // 10 ADA

    // Allowed recipient addresses (optional)
    allowedRecipients: [
      "addr_test1qp...",  // Your application's addresses
    ],

    // Required metadata tags (optional)
    requiredMetadata: {
      app: "my-app",
    },
  },
});
```

## Step 4: Design the User Experience

### Registration Flow

```
┌─────────────────────────────────────────────────────┐
│                  App Landing Page                    │
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │        Get Started in Seconds               │    │
│  │                                             │    │
│  │  ┌─────────────┐  ┌─────────────────────┐   │    │
│  │  │   Google    │  │      Email          │   │    │
│  │  │   Sign In   │  │   Continue with     │   │    │
│  │  └─────────────┘  └─────────────────────┘   │    │
│  │                                             │    │
│  │  No wallet extension needed                 │    │
│  │  No seed phrases to remember               │    │
│  │  No crypto required to start               │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘
```

### First Transaction

```tsx
function FirstTransaction({ wallet, sponsor }) {
  const [status, setStatus] = useState("idle");

  async function handleClaim() {
    setStatus("processing");

    try {
      // User has no ADA, but sponsor covers fees
      const txHash = await buildSponsoredTransaction(wallet, sponsor);
      setStatus("success");
    } catch (error) {
      setStatus("error");
    }
  }

  return (
    <div>
      <h2>Claim Your Welcome NFT</h2>
      <p>Free for new users - no crypto needed!</p>

      <button onClick={handleClaim} disabled={status === "processing"}>
        {status === "processing" ? "Processing..." : "Claim Now"}
      </button>

      {status === "success" && (
        <p>NFT claimed! Check your collection.</p>
      )}
    </div>
  );
}
```

### Progressive Disclosure

Start simple, reveal complexity as users advance:

| User Stage   | Visible Features                      |
| ------------ | ------------------------------------- |
| **New**      | Social login, sponsored transactions  |
| **Active**   | Balance display, transaction history  |
| **Power**    | Export keys, connect external wallets |
| **Advanced** | Full wallet features, manual fees     |

## Complete Working Example

### Project Structure

```
web3-app/
  components/
    WalletProvider.tsx
    ConnectButton.tsx
    SponsoredAction.tsx
  hooks/
    useWallet.ts
    useSponsor.ts
  pages/
    index.tsx
```

### WalletProvider.tsx

```tsx
import { createContext, useContext, useState, ReactNode } from "react";
import { UTXOSWallet } from "@utxos/wallet-sdk";
import { UTXOSSponsor } from "@utxos/sponsor-sdk";

interface WalletContextType {
  wallet: UTXOSWallet | null;
  sponsor: UTXOSSponsor;
  connect: (method: "google" | "email", email?: string) => Promise<void>;
  disconnect: () => void;
  address: string;
  isConnected: boolean;
}

const WalletContext = createContext<WalletContextType | null>(null);

export function WalletProvider({ children }: { children: ReactNode }) {
  const [wallet, setWallet] = useState<UTXOSWallet | null>(null);
  const [address, setAddress] = useState("");

  const sponsor = new UTXOSSponsor({
    apiKey: process.env.NEXT_PUBLIC_SPONSOR_API_KEY!,
    network: "preprod",
  });

  async function connect(method: "google" | "email", email?: string) {
    const newWallet = new UTXOSWallet({
      apiKey: process.env.NEXT_PUBLIC_WALLET_API_KEY!,
      network: "preprod",
    });

    if (method === "google") {
      await newWallet.connectWithGoogle();
    } else if (email) {
      await newWallet.connectWithEmail(email);
    }

    const walletAddress = await newWallet.getAddress();
    setWallet(newWallet);
    setAddress(walletAddress);
  }

  function disconnect() {
    setWallet(null);
    setAddress("");
  }

  return (
    <WalletContext.Provider
      value={{
        wallet,
        sponsor,
        connect,
        disconnect,
        address,
        isConnected: !!wallet,
      }}
    >
      {children}
    </WalletContext.Provider>
  );
}

export function useWallet() {
  const context = useContext(WalletContext);
  if (!context) {
    throw new Error("useWallet must be used within WalletProvider");
  }
  return context;
}
```

### SponsoredAction.tsx

```tsx
import { useState } from "react";
import { MeshTxBuilder } from "@meshsdk/core";
import { useWallet } from "./WalletProvider";

interface SponsoredActionProps {
  recipientAddress: string;
  amount: string;
  onSuccess?: (txHash: string) => void;
}

export function SponsoredAction({
  recipientAddress,
  amount,
  onSuccess,
}: SponsoredActionProps) {
  const { wallet, sponsor, address, isConnected } = useWallet();
  const [loading, setLoading] = useState(false);
  const [txHash, setTxHash] = useState("");

  async function execute() {
    if (!wallet) return;

    setLoading(true);

    try {
      const txBuilder = new MeshTxBuilder();

      const partialTx = await txBuilder
        .txOut(recipientAddress, [{ unit: "lovelace", quantity: amount }])
        .changeAddress(address)
        .complete({ noCoinSelection: true });

      const sponsoredTx = await sponsor.sponsorTransaction(partialTx);
      const userSignedTx = await wallet.signTx(sponsoredTx, true);
      const hash = await sponsor.submitSponsoredTransaction(userSignedTx);

      setTxHash(hash);
      onSuccess?.(hash);
    } catch (error) {
      console.error("Transaction failed:", error);
    } finally {
      setLoading(false);
    }
  }

  if (!isConnected) {
    return <p>Please connect your wallet first.</p>;
  }

  return (
    <div>
      <button onClick={execute} disabled={loading}>
        {loading ? "Processing..." : "Execute (Sponsored)"}
      </button>

      {txHash && (
        <p>
          Success!{" "}
          <a
            href={`https://preprod.cardanoscan.io/transaction/${txHash}`}
            target="_blank"
            rel="noopener noreferrer"
          >
            View transaction
          </a>
        </p>
      )}
    </div>
  );
}
```

## Key Concepts Explained

### Self-Custody vs Convenience

WaaS provides a spectrum of custody models:

| Model                 | Key Control   | Recovery     | Convenience |
| --------------------- | ------------- | ------------ | ----------- |
| **Full self-custody** | User only     | Seed phrase  | Low         |
| **WaaS (SSS)**        | Distributed   | Social/email | High        |
| **Custodial**         | Provider only | Provider     | Highest     |

WaaS with Shamir's Secret Sharing offers the best balance: users maintain custody while enjoying familiar authentication.

### Sponsorship Economics

Consider these factors when designing sponsorship:

* **Cost per user**: Average transaction fees x transactions per session
* **Abuse prevention**: Rate limits, allowed actions, required authentication
* **Revenue model**: Freemium, subscription, or transaction-based

## Exercises

1. **Add Apple Sign-In**: Extend the wallet provider to support Apple authentication.

2. **Sponsorship dashboard**: Build an admin panel showing sponsorship usage and costs.

3. **Hybrid wallet**: Allow users to switch between WaaS and their own browser wallet.

## Course Completion

Congratulations! You have completed the Cardano Development Course.

You have learned:

* Wallet creation and transaction building
* Multi-signature transactions
* Aiken smart contract development
* Contract testing and optimization
* Blueprint interpretation and code generation
* Vesting and NFT contracts
* Hydra Layer 2 scaling
* Web3 services for user onboarding

### What to Build Next

Apply your skills to build:

* **DeFi protocols**: Lending, swapping, yield farming
* **NFT platforms**: Marketplaces, generative collections
* **DAOs**: Governance and treasury management
* **Gaming**: On-chain game logic, asset ownership
* **Identity**: Verifiable credentials, reputation systems

## Related Links

* <Link href="https://docs.utxos.dev/wallet/usage">UTXOS Wallet Documentation</Link>
* <Link href="https://docs.utxos.dev/sponsor/usage">UTXOS Sponsorship Documentation</Link>
* <Link href="/apis">Mesh SDK API Reference</Link>
* <Link href="https://discord.gg/meshsdk">Mesh Discord Community</Link>


# Cardano Development Course
URL: /resources/cardano-course

A comprehensive course for building Cardano applications with Mesh SDK and Aiken smart contracts.

***

title: "Cardano Development Course"
description: "A comprehensive course for building Cardano applications with Mesh SDK and Aiken smart contracts."
icon: AcademicCapIcon
---------------------

import Link from "fumadocs-core/link";
import { CourseSchema } from "@/components/seo";

<CourseSchema
  name="Cardano Development Course with Mesh SDK"
  description="A comprehensive free course for building Cardano applications with Mesh SDK and Aiken smart contracts. Learn wallet integration, transaction building, smart contract development, and Layer 2 scaling."
  provider="MeshJS"
  isAccessibleForFree={true}
  lessons={[
  { name: "Hello World", description: "Install Mesh SDK and learn wallet basics with sending lovelace" },
  { name: "Multi-signature Transactions", description: "Build multi-sig transactions for collaborative signing" },
  { name: "Aiken Contracts", description: "Introduction to Aiken smart contract development" },
  { name: "Contract Testing", description: "Testing strategies for smart contracts" },
  { name: "Avoid Redundant Validation", description: "Smart contract optimization patterns" },
  { name: "Interpreting Blueprint", description: "Understanding Aiken blueprints and CIP-57" },
  { name: "Vesting Contract", description: "Build a token vesting contract" },
  { name: "Plutus NFT Contract", description: "Create NFT minting contracts with Plutus" },
  { name: "Hydra End-to-End", description: "Layer 2 scaling with Hydra" },
  { name: "Web3 Services", description: "Wallet-as-a-service and transaction sponsorship" }
]}
/>

Master Cardano development through hands-on lessons. Each lesson builds on the previous one, taking you from basic wallet operations to advanced smart contract development.

## What You Will Learn

By completing this course, you will be able to:

* Build Cardano dApps using the Mesh SDK
* Create and deploy Aiken smart contracts
* Construct transactions and integrate wallet functionality
* Test and optimize smart contracts for production
* Mint NFTs and manage tokens on Cardano
* Implement Layer 2 scaling solutions with Hydra

## Prerequisites

Before starting this course, ensure you have:

* **Node.js v20+** installed on your machine
* Basic understanding of **TypeScript/JavaScript**
* A code editor (VS Code recommended)
* Familiarity with blockchain concepts (helpful but not required)

## Course Structure

### Getting Started

Start here if you are new to Cardano development:

* <Link href="/resources/cardano-course/01-wallet-send-lovelace">Lesson 1: Hello World</Link> - Set up Mesh SDK, create a wallet, and send your first transaction
* <Link href="/resources/cardano-course/02-multisig">Lesson 2: Multi-signature Transactions</Link> - Build transactions that require multiple signers

### Smart Contract Development

Learn the fundamentals of Aiken smart contract development:

* <Link href="/resources/cardano-course/03-aiken-contracts">Lesson 3: Aiken Contracts</Link> - Understand transaction contexts, validators, and script types
* <Link href="/resources/cardano-course/04-contract-testing">Lesson 4: Contract Testing</Link> - Write comprehensive tests using mock transactions
* <Link href="/resources/cardano-course/05-avoid-redundant-validation">Lesson 5: Avoid Redundant Validation</Link> - Optimize contracts by centralizing validation logic
* <Link href="/resources/cardano-course/06-interpreting-blueprint">Lesson 6: Interpreting Blueprint</Link> - Generate offchain code from Aiken blueprints

### Advanced Contracts

Build production-ready smart contracts:

* <Link href="/resources/cardano-course/07-vesting">Lesson 7: Vesting Contract</Link> - Create a time-locked fund release contract
* <Link href="/resources/cardano-course/08-plutus-nft">Lesson 8: Plutus NFT Contract</Link> - Mint unique NFTs with auto-incrementing indices

### Scaling and Services

Explore Layer 2 solutions and Web3 services:

* <Link href="/resources/cardano-course/09-hydra">Lesson 9: Hydra End-to-End</Link> - Implement state channels with the Hydra Head protocol
* <Link href="/resources/cardano-course/10-web3-services">Lesson 10: Web3 Services</Link> - Integrate wallet-as-a-service and transaction sponsorship

## Estimated Time

* **Total course duration:** 8-12 hours
* **Per lesson:** 30-60 minutes

## Get Help

If you encounter issues or have questions:

* Join the <Link href="https://discord.gg/meshsdk">Mesh Discord community</Link>
* Check the <Link href="/apis">Mesh SDK API documentation</Link>
* Review the <Link href="https://aiken-lang.org/">Aiken documentation</Link>

Ready to start? Begin with <Link href="/resources/cardano-course/01-wallet-send-lovelace">Lesson 1: Hello World</Link>.


# Coin Selection
URL: /resources/challenges/coin-selection

Fix UTXO selection errors in Cardano transactions with Mesh SDK's automatic coin selection.

***

title: "Coin Selection"
description: "Fix UTXO selection errors in Cardano transactions with Mesh SDK's automatic coin selection."
----------------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Solve Cardano Coin Selection with Mesh SDK"
  description="Implement effective coin selection for Cardano transactions using Mesh SDK's automatic UTXO selection algorithms."
  totalTime="PT8M"
  steps={[
  { name: "Install Mesh SDK", text: "Run npm install @meshsdk/core to add the Cardano SDK to your project." },
  { name: "Fetch available UTXOs", text: "Use wallet.getUtxosMesh() to retrieve all spendable UTXOs from the connected wallet." },
  { name: "Use selectUtxosFrom", text: "Pass UTXOs to MeshTxBuilder's selectUtxosFrom method for automatic optimal selection." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "What is coin selection in Cardano?",
    answer: "Coin selection is the algorithm that chooses which UTXOs to use as transaction inputs. Poor selection can cause failures, oversized transactions, wallet fragmentation, or unnecessarily locked tokens."
  },
  {
    question: "Why do I get 'insufficient funds' when my wallet has enough ADA?",
    answer: "This happens when ADA is distributed across UTXOs inefficiently. For example, 100 ADA spread across 50 small UTXOs might exceed transaction size limits. Or ADA might be locked alongside native tokens."
  },
  {
    question: "What coin selection algorithm does Mesh use?",
    answer: "Mesh implements largest-first selection with optimizations for minimizing transaction size, avoiding unnecessary token movements, meeting minimum UTXO requirements, and handling change efficiently."
  },
  {
    question: "Can bad coin selection cause wallet fragmentation?",
    answer: "Yes. Many small change outputs fragment your wallet over time, making future transactions harder to build. Mesh minimizes fragmentation by creating efficient change outputs."
  }
]}
/>

Coin selection determines which UTXOs fund your transaction. Poor selection causes failures, oversized transactions, and wallet fragmentation. Mesh handles this automatically.

## The challenge

### Why coin selection fails

| Cause              | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| Value distribution | 100 ADA as one UTXO vs 100 small UTXOs requires different strategies    |
| Token coupling     | Native tokens lock ADA - you can't access ADA without moving the tokens |
| Minimum values     | Every UTXO needs \~1-2 ADA minimum                                      |
| Size limits        | Too many inputs exceed 16KB transaction limit                           |

### Common mistakes

| Mistake              | Problem                                   |
| -------------------- | ----------------------------------------- |
| Greedy selection     | Largest first may not create valid change |
| Random selection     | Unpredictable sizes and frequent failures |
| Ignoring tokens      | Selecting UTXOs with unwanted tokens      |
| Poor change strategy | Creates many small UTXOs (fragmentation)  |

### Change output complexity

Change calculation is not simple subtraction:

* Must include tokens from inputs not being sent
* Must meet minimum UTXO value requirements
* May need multiple outputs for different token bundles
* Fee calculation creates circular dependency

***

## The solution

Mesh's `selectUtxosFrom()` handles all coin selection complexity.

### Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### Basic usage

```typescript
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("<your-api-key>");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .changeAddress(await wallet.getChangeAddressBech32())
  .selectUtxosFrom(await wallet.getUtxosMesh())
  .complete();
```

### What selectUtxosFrom does

| Action                     | Benefit                                              |
| -------------------------- | ---------------------------------------------------- |
| Minimizes transaction size | Fewer inputs = lower fees                            |
| Avoids token entanglement  | Prefers ADA-only UTXOs when possible                 |
| Satisfies minimums         | Ensures value covers outputs, fees, and valid change |
| Retries intelligently      | Alternative strategies if initial selection fails    |

***

## Common patterns

### Send multiple tokens

```typescript
const tx = await txBuilder
  .txOut(recipient, [
    { unit: "lovelace", quantity: "3000000" },
    { unit: policyId1 + assetName1, quantity: "50" },
    { unit: policyId2 + assetName2, quantity: "1" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Consolidate fragmented wallet

```typescript
const allUtxos = await wallet.getUtxos();
const totalLovelace = allUtxos.reduce((sum, utxo) =>
  sum + BigInt(utxo.output.amount.find(a => a.unit === "lovelace")?.quantity || 0),
  BigInt(0)
);

const tx = await txBuilder
  .txOut(changeAddress, [{
    unit: "lovelace",
    quantity: (totalLovelace - BigInt(500000)).toString()
  }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(allUtxos)
  .complete();
```

### Manual UTXO selection

When you need specific UTXOs:

```typescript
const specificUtxo = utxos.find(u => /* your criteria */);

const tx = await txBuilder
  .txIn(specificUtxo.input.txHash, specificUtxo.input.outputIndex)
  .txOut(recipient, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .complete();
```

***

## Handle selection failures

```typescript
async function buildTransaction(amount: string) {
  try {
    const utxos = await wallet.getUtxos();
    return await txBuilder
      .txOut(recipient, [{ unit: "lovelace", quantity: amount }])
      .changeAddress(await wallet.getChangeAddress())
      .selectUtxosFrom(utxos)
      .complete();
  } catch (error) {
    if (error.message.includes("Insufficient")) {
      throw new Error("Unable to build transaction. Try a smaller amount.");
    }
    throw error;
  }
}
```

***

## Prevent problems

### Avoid fragmentation

* Consolidate small UTXOs during low-fee periods
* Avoid transactions with many small outputs
* Use Mesh's automatic selection for efficient change

### Best practices

| Practice                        | Reason                      |
| ------------------------------- | --------------------------- |
| Fetch fresh UTXOs               | Avoid stale data            |
| Handle errors gracefully        | Provide clear user feedback |
| Test with various wallet states | Edge cases matter           |
| Monitor wallet health           | Watch for fragmentation     |

***

## Related topics

| Topic                | Link                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------- |
| UTXO model           | [/resources/challenges/utxo-model](/resources/challenges/utxo-model)                     |
| Transaction failures | [/resources/challenges/transaction-failures](/resources/challenges/transaction-failures) |
| Wallet integration   | [/resources/challenges/wallet-integration](/resources/challenges/wallet-integration)     |
| Transaction builder  | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder)     |


# Cardano Development Challenges
URL: /resources/challenges

Overcome common Cardano dApp development challenges. Learn how Mesh SDK solves UTXO complexity, wallet integration, and transaction failures.

***

title: "Cardano Development Challenges"
description: "Overcome common Cardano dApp development challenges. Learn how Mesh SDK solves UTXO complexity, wallet integration, and transaction failures."
------------------------------------------------------------------------------------------------------------------------------------------------------------

import { linksChallenges, metaChallenges } from "@/data/links-challenges";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Getting Started with Cardano dApp Development Using Mesh SDK"
  description="Learn how to overcome common Cardano development challenges by installing the Mesh TypeScript SDK and building your first transaction."
  totalTime="PT15M"
  steps={[
  { name: "Install Mesh SDK", text: "Run npm install @meshsdk/core @meshsdk/react to add the Cardano SDK to your project." },
  { name: "Set up a provider", text: "Configure a blockchain provider like Blockfrost or Koios to connect to the Cardano network." },
  { name: "Initialize your wallet", text: "Use MeshCardanoBrowserWallet or MeshCardanoHeadlessWallet to connect and manage user wallets." },
  { name: "Build your first transaction", text: "Use the MeshTxBuilder API to construct, sign, and submit transactions with automatic UTXO handling." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "What are the most common Cardano development challenges?",
    answer: "The most common challenges include transaction failures due to UTXO issues, understanding the UTXO model, wallet integration complexity, coin selection optimization, and the steep learning curve for smart contracts."
  },
  {
    question: "How does Mesh SDK help with Cardano development?",
    answer: "Mesh is a TypeScript SDK that abstracts low-level complexity with high-level APIs for transaction building, automatic UTXO management, pre-built React components, and full type safety."
  },
  {
    question: "Why do Cardano transactions fail more often than Ethereum transactions?",
    answer: "Cardano uses the UTXO model which requires explicit input selection and change handling. Transactions can fail if UTXOs are consumed concurrently, inputs are insufficient, or the transaction is too large. Mesh handles these automatically."
  },
  {
    question: "Is Cardano development harder than Ethereum development?",
    answer: "Cardano has a steeper initial learning curve due to the UTXO model. However, tools like Mesh SDK and comprehensive documentation significantly reduce this complexity."
  }
]}
/>

Cardano development presents unique challenges due to the extended UTXO model. This guide covers the five most common obstacles you encounter when building dApps, and shows how Mesh solves each one.

## The challenge

Cardano uses the UTXO (Unspent Transaction Output) model instead of Ethereum's account model. Your balance consists of discrete outputs that you must explicitly select and consume. This architectural difference creates several challenges:

| Aspect          | Ethereum                  | Cardano                             |
| --------------- | ------------------------- | ----------------------------------- |
| Balance         | Single number per address | Sum of discrete UTXOs               |
| Transactions    | Modify account state      | Consume and create UTXOs            |
| Concurrency     | Simple state updates      | Requires UTXO coordination          |
| Smart contracts | EVM with gas              | Plutus/Aiken with execution budgets |

## Common challenges at a glance

| Challenge                  | Root cause                           | Mesh solution                           |
| -------------------------- | ------------------------------------ | --------------------------------------- |
| Transaction failures       | UTXO selection, fee calculation      | Automatic handling in `MeshTxBuilder`   |
| UTXO complexity            | Discrete outputs instead of balances | `selectUtxosFrom()` abstracts selection |
| Wallet fragmentation       | Many small change outputs            | Optimized coin selection algorithms     |
| Fee calculation            | Circular dependency on tx size       | Iterative calculation in `complete()`   |
| Smart contract integration | Datums, redeemers, execution budgets | High-level APIs for script interaction  |

## Explore specific challenges

<div className="grid md:grid-cols-2 gap-6 items-stretch my-8">
  {linksChallenges.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

## Quick start

Get started in four steps.

### Step 1: Install Mesh

```bash
npm install @meshsdk/core @meshsdk/react
```

### Step 2: Configure a provider

```typescript
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<your-api-key>");
```

### Step 3: Connect a wallet

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");
```

### Step 4: Build and submit a transaction

```typescript
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(await wallet.getChangeAddressBech32())
  .selectUtxosFrom(await wallet.getUtxosMesh())
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);
```

## Best practices

Follow these practices to avoid common pitfalls:

* **Fetch fresh UTXOs** before building transactions to avoid conflicts
* **Use automatic UTXO selection** instead of manual input management
* **Handle errors gracefully** with user-friendly messages
* **Test on preprod** before deploying to mainnet
* **Use TypeScript** for compile-time error detection

## Why Mesh

| Feature                   | Benefit                                    |
| ------------------------- | ------------------------------------------ |
| TypeScript-first          | Type safety and IDE support                |
| Automatic UTXO management | No manual coin selection                   |
| Framework-agnostic        | Works with React, Svelte, Next.js, Node.js |
| Multiple providers        | Blockfrost, Koios, Maestro, Ogmios         |
| Active maintenance        | Regular updates for Cardano changes        |

## Related links

| Resource      | Link                                          |
| ------------- | --------------------------------------------- |
| Documentation | [/docs](/docs)                                |
| Discord       | [Join](https://discord.gg/dH48jH3BKa)         |
| GitHub        | [MeshJS/mesh](https://github.com/MeshJS/mesh) |
| Guides        | [/guides](/guides)                            |


# Learning Curve
URL: /resources/challenges/learning-curve

Overcome Cardano's learning curve with Mesh SDK's beginner-friendly TypeScript APIs.

***

title: "Learning Curve"
description: "Overcome Cardano's learning curve with Mesh SDK's beginner-friendly TypeScript APIs."
---------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Start Cardano Development with Mesh SDK"
  description="Begin Cardano dApp development using Mesh SDK's beginner-friendly APIs and progressive learning approach."
  totalTime="PT15M"
  steps={[
  { name: "Install Mesh SDK", text: "Run npm install @meshsdk/core @meshsdk/react to add the Cardano SDK." },
  { name: "Connect a wallet", text: "Use MeshCardanoBrowserWallet to connect any Cardano wallet with a single function call." },
  { name: "Build your first transaction", text: "Use MeshTxBuilder to construct and submit a simple ADA transfer." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "How hard is Cardano development?",
    answer: "Cardano has a steeper learning curve than Ethereum due to its UTXO model and native asset system. However, Mesh SDK significantly reduces the barrier with familiar JavaScript APIs that abstract complexity."
  },
  {
    question: "Do I need to learn Haskell for Cardano development?",
    answer: "No. You can build full dApps using JavaScript/TypeScript with Mesh SDK. For on-chain logic, Aiken offers familiar syntax without requiring Haskell knowledge."
  },
  {
    question: "What makes Cardano different from Ethereum?",
    answer: "Cardano's UTXO model versus Ethereum's account model is the main difference. Instead of updating balances, you spend and create discrete outputs. Native assets don't require smart contracts."
  },
  {
    question: "What should I learn first?",
    answer: "Start with wallet integration and simple transactions. This teaches the UTXO model practically. Then explore native assets, metadata, and finally smart contracts."
  }
]}
/>

Cardano has a steeper learning curve due to the UTXO model, native assets, and academic terminology. Mesh flattens this curve with intuitive APIs that let you build functional dApps immediately.

## The challenge

### UTXO mental model shift

| Ethereum (Accounts)         | Cardano (UTXO)                          |
| --------------------------- | --------------------------------------- |
| Single balance number       | Set of discrete outputs                 |
| Transactions modify balance | Transactions consume and create outputs |
| Partial spending possible   | Must consume entire UTXO, create change |
| Sequential processing       | Parallel transaction processing         |

### What makes it harder

| Challenge            | Impact                                  |
| -------------------- | --------------------------------------- |
| UTXO model           | Different from familiar account systems |
| Haskell roots        | Plutus smart contracts use Haskell      |
| Academic terminology | Datums, redeemers, lovelace             |
| Fragmented docs      | Multiple tools and approaches           |

***

## The solution

Mesh provides progressive complexity. Start simple, add advanced features as needed.

### Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### Connect a wallet

```tsx
import { CardanoWallet, MeshProvider, useWallet } from "@meshsdk/react";

function App() {
  const { connected } = useWallet();

  return (
    <MeshProvider>
      <CardanoWallet />
      {connected && <p>Wallet connected!</p>}
    </MeshProvider>
  );
}
```

### Build a transaction

```typescript
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(myAddress)
  .selectUtxosFrom(myUtxos)
  .complete();
```

You say "send 5 ADA to this address." Mesh handles UTXO selection, fee calculation, and change automatically.

***

## Recommended learning path

### Week 1: Wallets and transfers

| Topic             | What you learn               |
| ----------------- | ---------------------------- |
| Wallet connection | Addresses, connection state  |
| ADA transfers     | Transaction lifecycle, UTXOs |
| Balance checking  | UTXO aggregation             |

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const address = await wallet.getChangeAddressBech32();
const utxos = await wallet.getUtxosMesh();
```

### Week 2: Native assets

| Topic                    | What you learn  |
| ------------------------ | --------------- |
| Token transfers          | Asset structure |
| Minting                  | Policy scripts  |
| Multi-asset transactions | Token bundles   |

```typescript
const tx = await txBuilder
  .txOut(recipient, [
    { unit: "lovelace", quantity: "2000000" },
    { unit: policyId + assetName, quantity: "10" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Week 3: Metadata

| Topic                | What you learn |
| -------------------- | -------------- |
| Transaction metadata | On-chain data  |
| NFT metadata         | CIP-25, CIP-68 |
| Message standards    | CIP-20         |

```typescript
const tx = await txBuilder
  .txOut(recipient, [{ unit: "lovelace", quantity: "5000000" }])
  .metadataValue("674", { msg: ["Hello Cardano"] })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Week 4+: Smart contracts

| Topic            | What you learn       |
| ---------------- | -------------------- |
| Datums           | Script state storage |
| Redeemers        | Unlock conditions    |
| Script execution | Budgets, collateral  |

```typescript
const tx = await txBuilder
  .spendingPlutusScript("V2")
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInScript(scriptCbor)
  .txInDatumValue(datum)
  .txInRedeemerValue(redeemer)
  .complete();
```

***

## Key terminology

| Term      | Meaning                            | Mesh usage                                  |
| --------- | ---------------------------------- | ------------------------------------------- |
| Lovelace  | Smallest ADA unit (1M = 1 ADA)     | `{ unit: "lovelace", quantity: "1000000" }` |
| UTXO      | Unspent output - a "coin" to spend | `wallet.getUtxos()`                         |
| Datum     | Data attached to script output     | `txInDatumValue()`                          |
| Redeemer  | Input to unlock script output      | `txInRedeemerValue()`                       |
| Policy ID | Token collection identifier        | Part of asset unit string                   |

***

## Why Mesh makes it easier

### Familiar patterns

```typescript
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import { BlockfrostProvider } from "@meshsdk/core";

// Similar to ethers.js pattern
const provider = new BlockfrostProvider("<api-key>");
const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  mnemonic: ["your", "mnemonic", "words", "..."],
});
```

### Pre-built React components

```tsx
import { CardanoWallet, useWallet, useLovelace } from "@meshsdk/react";

function Dashboard() {
  const { connected } = useWallet();
  const lovelace = useLovelace();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Balance: {Number(lovelace) / 1_000_000} ADA</p>}
    </div>
  );
}
```

### TypeScript support

Full type definitions for IDE autocompletion and compile-time error catching.

***

## Learning resources

| Resource           | Link                                                     |
| ------------------ | -------------------------------------------------------- |
| Mesh Documentation | [/docs](/docs)                                           |
| Getting Started    | [/guides](/guides)                                       |
| Developer Portal   | [developers.cardano.org](https://developers.cardano.org) |
| Discord            | [Join](https://discord.gg/dH48jH3BKa)                    |

***

## Related topics

| Topic                | Link                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------- |
| UTXO model           | [/resources/challenges/utxo-model](/resources/challenges/utxo-model)                     |
| Wallet integration   | [/resources/challenges/wallet-integration](/resources/challenges/wallet-integration)     |
| Transaction failures | [/resources/challenges/transaction-failures](/resources/challenges/transaction-failures) |
| Beginner solutions   | [/resources/solutions/beginners](/resources/solutions/beginners)                         |


# Transaction Failures
URL: /resources/challenges/transaction-failures

Fix Cardano transaction failures with Mesh SDK's automatic UTXO selection and fee calculation.

***

title: "Transaction Failures"
description: "Fix Cardano transaction failures with Mesh SDK's automatic UTXO selection and fee calculation."
-------------------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Fix Cardano Transaction Failures with Mesh SDK"
  description="Resolve common Cardano transaction failures using Mesh SDK for automatic UTXO selection and fee calculation."
  totalTime="PT10M"
  steps={[
  { name: "Install Mesh SDK", text: "Run npm install @meshsdk/core @meshsdk/react to add the Cardano SDK." },
  { name: "Configure a provider", text: "Set up a blockchain provider like Blockfrost to fetch UTXOs and submit transactions." },
  { name: "Use MeshTxBuilder", text: "Replace manual transaction construction with MeshTxBuilder for automatic handling." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "Why does my transaction fail with 'insufficient funds' when I have enough ADA?",
    answer: "Your ADA may be spread across UTXOs that cannot be efficiently combined, or some UTXOs may be used in pending transactions. Mesh's automatic UTXO selection handles this."
  },
  {
    question: "What causes 'UTXO already spent' errors?",
    answer: "This occurs when a UTXO was consumed by another transaction. This is common when multiple transactions are built from stale wallet state. Fetch fresh UTXOs before building."
  },
  {
    question: "How do I fix 'transaction too large' errors?",
    answer: "Cardano has a 16KB transaction size limit. Large transactions with many inputs can exceed this. Mesh optimizes UTXO selection to minimize transaction size."
  },
  {
    question: "Can I prevent transaction failures?",
    answer: "Yes. Use proper UTXO management, fetch fresh wallet state before building, implement retry logic, and use Mesh SDK's automatic handling."
  }
]}
/>

Cardano transactions fail due to UTXO conflicts, insufficient inputs, incorrect fees, or size limits. Mesh eliminates most failures by automatically handling UTXO selection, fee estimation, and change calculation.

## Common failure causes

| Cause                 | Description                                        |
| --------------------- | -------------------------------------------------- |
| UTXO conflicts        | Another transaction consumed the UTXO you selected |
| Insufficient funds    | UTXOs don't sum to required value                  |
| Transaction too large | Exceeds 16KB size limit                            |
| Fee miscalculation    | Change output doesn't account for correct fee      |
| Invalid change        | Change output below minimum UTXO value             |
| Token entanglement    | ADA locked with tokens you can't move              |

***

## Why transactions fail

### UTXO conflicts

When you build a transaction, you select specific UTXOs. If another transaction consumes one first, your transaction becomes invalid.

Common scenarios:

* User clicks submit multiple times
* Backend processes concurrent requests
* Multiple browser tabs share the same wallet

### Insufficient funds with adequate balance

| Cause         | Why it happens                                 |
| ------------- | ---------------------------------------------- |
| Locked tokens | ADA is paired with native tokens               |
| Minimum UTXO  | Outputs must meet minimum value requirements   |
| Fee reduction | Fees reduce available balance                  |
| Fragmentation | Many small UTXOs create oversized transactions |

### Fee calculation complexity

Fees depend on transaction size, which depends on inputs, outputs, and witnesses. This circular dependency requires iterative solving.

***

## The solution

MeshTxBuilder handles all complexity automatically.

### Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### Basic usage

```typescript
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("<your-api-key>");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(await wallet.getChangeAddressBech32())
  .selectUtxosFrom(await wallet.getUtxosMesh())
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);
```

### What Mesh handles automatically

| Feature         | What it does                           |
| --------------- | -------------------------------------- |
| UTXO selection  | Chooses optimal inputs minimizing size |
| Fee calculation | Iteratively calculates exact fee       |
| Change handling | Creates valid change outputs           |
| Token routing   | Routes tokens to change if not sent    |
| Validation      | Catches errors before submission       |

***

## Handle remaining failures

Even with Mesh, some failures require application-level handling.

### Implement retry logic

```typescript
async function submitWithRetry(wallet, signedTx, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await wallet.submitTx(signedTx);
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
    }
  }
}
```

### Fetch fresh UTXOs

Always fetch UTXOs immediately before building:

```typescript
// Wrong: stale UTXOs
const cachedUtxos = await wallet.getUtxosMesh();
// ... time passes ...
const tx = await txBuilder.selectUtxosFrom(cachedUtxos).complete(); // May fail

// Correct: fresh UTXOs at transaction time
async function buildTransaction() {
  const freshUtxos = await wallet.getUtxosMesh();
  return await txBuilder.selectUtxosFrom(freshUtxos).complete();
}
```

### Prevent double-submission

```typescript
const [isSubmitting, setIsSubmitting] = useState(false);

async function handleSubmit() {
  if (isSubmitting) return;
  setIsSubmitting(true);
  try {
    const txHash = await submitTransaction();
  } catch (error) {
    showError(error.message);
  } finally {
    setIsSubmitting(false);
  }
}
```

### Handle errors gracefully

```typescript
try {
  const tx = await txBuilder
    .txOut(recipientAddress, amount)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(tx);
  const txHash = await wallet.submitTx(signedTx);
} catch (error) {
  if (error.message.includes("Insufficient")) {
    showError("Not enough ADA to complete this transaction");
  } else if (error.message.includes("User")) {
    showInfo("Transaction cancelled");
  } else {
    showError("Transaction failed. Please try again.");
  }
}
```

***

## Advanced patterns

### Multi-asset transactions

```typescript
const tx = await txBuilder
  .txOut(recipient, [
    { unit: "lovelace", quantity: "2000000" },
    { unit: policyId + assetName, quantity: "1" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Smart contract transactions

```typescript
const tx = await txBuilder
  .spendingPlutusScript(languageVersion)
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInScript(scriptCbor)
  .txInDatumValue(datum)
  .txInRedeemerValue(redeemer)
  .txOut(outputAddress, outputValue)
  .txInCollateral(collateralUtxo.input.txHash, collateralUtxo.input.outputIndex)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Best practices

| Practice                     | Reason                         |
| ---------------------------- | ------------------------------ |
| Fetch fresh UTXOs            | Avoid stale data and conflicts |
| Implement retry logic        | Handle transient failures      |
| Disable button during submit | Prevent double-submission      |
| Show clear error messages    | Help users understand failures |
| Test on preprod first        | Catch issues before mainnet    |

***

## Related topics

| Topic               | Link                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------ |
| UTXO model          | [/resources/challenges/utxo-model](/resources/challenges/utxo-model)                 |
| Coin selection      | [/resources/challenges/coin-selection](/resources/challenges/coin-selection)         |
| Wallet integration  | [/resources/challenges/wallet-integration](/resources/challenges/wallet-integration) |
| Transaction builder | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder) |


# UTXO Model
URL: /resources/challenges/utxo-model

Understand Cardano's UTXO model and how Mesh SDK simplifies UTXO management.

***

title: "UTXO Model"
description: "Understand Cardano's UTXO model and how Mesh SDK simplifies UTXO management."
-------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Work with Cardano's UTXO Model Using Mesh SDK"
  description="Learn to work with Cardano's UTXO model using Mesh SDK for automatic UTXO selection and change calculation."
  totalTime="PT15M"
  steps={[
  { name: "Understand UTXO basics", text: "Learn that UTXOs are discrete unspent outputs that must be fully consumed in transactions." },
  { name: "Install Mesh SDK", text: "Run npm install @meshsdk/core to add the Cardano SDK." },
  { name: "Use automatic UTXO selection", text: "Let MeshTxBuilder handle UTXO selection and change calculation automatically." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "What is the UTXO model?",
    answer: "UTXO stands for Unspent Transaction Output. Instead of accounts with balances, Cardano tracks discrete 'coins' that transactions consume entirely and create new ones. Your wallet balance is the sum of all UTXOs you control."
  },
  {
    question: "Why does Cardano use UTXO?",
    answer: "The UTXO model provides deterministic transaction validation, better parallelization for smart contracts, enhanced privacy through new addresses, and simpler verification since validity depends only on inputs."
  },
  {
    question: "How is Cardano's eUTXO different from Bitcoin's UTXO?",
    answer: "Cardano's extended UTXO adds datum (arbitrary data), smart contract validators, native multi-asset support, and reference scripts for more efficient contract execution."
  },
  {
    question: "Do I need to understand UTXOs to build Cardano dApps?",
    answer: "A basic understanding helps, but Mesh SDK abstracts most complexity. You can build functional dApps without deep UTXO knowledge."
  }
]}
/>

The UTXO (Unspent Transaction Output) model is Cardano's fundamental architecture. Unlike Ethereum's accounts, Cardano represents value as discrete outputs that you consume and recreate in each transaction. Mesh abstracts this complexity.

## The concept

### Ethereum: account model

```
Account: 0x123...
Balance: 100 ETH
```

Sending 10 ETH updates the number in place. Simple, but limits parallelization.

### Cardano: UTXO model

```
UTXO 1: 50 ADA (from tx abc123)
UTXO 2: 30 ADA (from tx def456)
UTXO 3: 20 ADA (from tx ghi789)
Total: 100 ADA
```

To send 10 ADA:

1. Select UTXOs as inputs (consumed entirely)
2. Create output for recipient (10 ADA)
3. Create change output (remaining minus fees)

Example: Using UTXO 2 (30 ADA) to send 10 ADA:

```
Inputs: UTXO 2 (30 ADA) - consumed entirely
Outputs:
  - Recipient: 10 ADA (new UTXO)
  - Change: ~19.8 ADA (new UTXO, minus fee)
```

UTXO 2 is destroyed. Two new UTXOs are created.

***

## Why UTXO

| Advantage                | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| Deterministic validation | Transaction validity depends only on inputs, not global state |
| Simple verification      | Light clients verify without tracking all accounts            |
| Natural parallelism      | Transactions on different UTXOs execute in parallel           |
| Privacy features         | New addresses per transaction complicate analysis             |
| Explicit resources       | Outputs declare contents; no unexpected state changes         |

***

## Extended UTXO (eUTXO)

Cardano extends Bitcoin's UTXO for smart contracts:

| Feature           | Purpose                                           |
| ----------------- | ------------------------------------------------- |
| Datums            | Arbitrary data attached to UTXOs for script state |
| Validators        | Scripts defining spending conditions              |
| Redeemers         | Arguments provided when spending script UTXOs     |
| Reference inputs  | Read UTXOs without consuming them                 |
| Reference scripts | On-chain scripts referenced by hash               |

Example UTXO with datum:

```typescript
{
  address: "addr_script1...",
  value: { lovelace: 5000000 },
  datum: { owner: "addr1...", deadline: 1234567 }
}
```

***

## How Mesh handles UTXOs

Mesh lets you describe intent instead of managing UTXOs manually.

### Basic transaction

```typescript
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("<your-api-key>");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .changeAddress(await wallet.getChangeAddressBech32())
  .selectUtxosFrom(await wallet.getUtxosMesh())
  .complete();

// Mesh automatically handles:
// - Optimal UTXO selection
// - Fee calculation
// - Change output creation
// - Minimum UTXO requirements
```

### What selectUtxosFrom does

Mesh selects UTXOs that:

* Satisfy required output value
* Minimize transaction size (fewer inputs = lower fees)
* Avoid unnecessary wallet fragmentation
* Handle tokens correctly (included in change if not sent)

### Native token handling

Tokens are bundled with ADA in UTXOs. Mesh handles this automatically:

```typescript
// Wallet has: UTXO 1 (10 ADA + 100 TokenA), UTXO 2 (5 ADA)
// You want to send 3 ADA

const tx = await txBuilder
  .txOut(recipient, [{ unit: "lovelace", quantity: "3000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

// Mesh selects UTXO 2 to avoid TokenA complexity
// Or ensures TokenA goes to change if UTXO 1 is needed
```

### Minimum UTXO requirements

Every UTXO needs minimum ADA (\~1-2 ADA depending on contents):

```typescript
const tx = await txBuilder
  .txOut(recipient, [
    { unit: policyId + assetName, quantity: "1" }
    // Mesh adds minimum required ADA automatically
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## View wallet UTXOs

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const utxos = await wallet.getUtxosMesh();

utxos.forEach(utxo => {
  console.log(`UTXO: ${utxo.input.txHash}#${utxo.input.outputIndex}`);
  console.log(`  Value: ${utxo.output.amount}`);
});
```

***

## Smart contract UTXOs

### Lock funds to script

```typescript
const tx = await txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .txOutDatumHashValue(datum)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Unlock funds from script

```typescript
const tx = await txBuilder
  .spendingPlutusScript(languageVersion)
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInScript(scriptCbor)
  .txInDatumValue(datum)
  .txInRedeemerValue(redeemer)
  .txOut(recipient, outputValue)
  .txInCollateral(collateralTxHash, collateralIndex)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Reference inputs

Read UTXO without consuming it:

```typescript
const tx = await txBuilder
  .readOnlyTxInReference(refTxHash, refIndex)
  .txOut(recipient, outputValue)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Common pitfalls

### UTXO fragmentation

Many small transactions create many small UTXOs. Consolidate periodically:

```typescript
const utxos = await wallet.getUtxos();
const total = utxos.reduce((sum, u) =>
  sum + BigInt(u.output.amount.find(a => a.unit === "lovelace")?.quantity || 0),
  BigInt(0)
);

const tx = await txBuilder
  .txOut(await wallet.getChangeAddress(), [
    { unit: "lovelace", quantity: total.toString() }
  ])
  .selectUtxosFrom(utxos)
  .complete();
```

### Concurrent transaction conflicts

Building multiple transactions from the same UTXOs causes conflicts:

```typescript
// Wrong: both use same UTXOs
const utxos = await wallet.getUtxos();
const tx1 = await txBuilder.selectUtxosFrom(utxos).complete();
const tx2 = await txBuilder.selectUtxosFrom(utxos).complete(); // Conflict!

// Correct: wait for confirmation, then fetch fresh UTXOs
```

### Token bundles

Tokens are always bundled with ADA. You must send minimum ADA with any token:

```typescript
const tx = await txBuilder
  .txOut(recipient, [
    { unit: "lovelace", quantity: "1500000" }, // Minimum ADA required
    { unit: tokenUnit, quantity: "50" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Related topics

| Topic                | Link                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Transaction failures | [/resources/challenges/transaction-failures](/resources/challenges/transaction-failures) |
| Coin selection       | [/resources/challenges/coin-selection](/resources/challenges/coin-selection)             |
| Wallet integration   | [/resources/challenges/wallet-integration](/resources/challenges/wallet-integration)     |
| Transaction builder  | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder)     |


# Wallet Integration
URL: /resources/challenges/wallet-integration

Connect any Cardano wallet to your dApp with Mesh SDK's unified API.

***

title: "Wallet Integration"
description: "Connect any Cardano wallet to your dApp with Mesh SDK's unified API."
-----------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Integrate Cardano Wallets Using Mesh SDK"
  description="Connect any Cardano wallet to your dApp using Mesh SDK's unified wallet API and pre-built React components."
  totalTime="PT10M"
  steps={[
  { name: "Install Mesh packages", text: "Run npm install @meshsdk/core @meshsdk/react to add wallet support." },
  { name: "Add CardanoWallet component", text: "Use the pre-built CardanoWallet React component for instant multi-wallet support." },
  { name: "Access wallet methods", text: "Use the useWallet hook to access connected wallet methods like getUtxosMesh, signTx, and submitTx." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "Why is Cardano wallet integration harder than Ethereum?",
    answer: "Cardano has multiple wallet providers (Eternl, Lace, Yoroi) with slight CIP-30 implementation differences. Unlike Ethereum's standardized window.ethereum, Cardano wallets register under different window.cardano properties."
  },
  {
    question: "What is CIP-30?",
    answer: "CIP-30 is the Cardano Improvement Proposal standardizing how dApps interact with wallets. It defines methods for connecting, signing transactions, and querying wallet state."
  },
  {
    question: "How do I detect installed Cardano wallets?",
    answer: "Mesh provides MeshCardanoBrowserWallet.getInstalledWallets() to automatically detect all installed CIP-30 compatible wallets without manual detection code."
  },
  {
    question: "Can I support all Cardano wallets with one integration?",
    answer: "Yes. Mesh SDK provides a unified API for all CIP-30 compatible wallets. The CardanoWallet component supports 10+ wallets out of the box."
  }
]}
/>

Wallet integration is complex due to multiple providers with varying CIP-30 implementations. Mesh provides a unified API that works with Eternl, Lace, Yoroi, and all CIP-30 wallets.

## The challenge

### CIP-30 variations

| Issue               | Description                               |
| ------------------- | ----------------------------------------- |
| Method availability | Some wallets skip optional methods        |
| Return formats      | Hex strings vs byte arrays                |
| Error handling      | Inconsistent error messages and codes     |
| Connection state    | Some persist across reloads, others don't |
| Network detection   | Different implementations                 |

### Cardano vs Ethereum

```javascript
// Cardano: each wallet registers separately
window.cardano.eternl
window.cardano.lace
window.cardano.yoroi

// Ethereum: mostly standardized
window.ethereum
```

***

## The solution

Mesh normalizes wallet differences with a unified API.

### Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### Option 1: CardanoWallet component

The fastest way to add wallet connectivity:

```tsx
import { CardanoWallet, MeshProvider } from "@meshsdk/react";

function App() {
  return (
    <MeshProvider>
      <CardanoWallet />
    </MeshProvider>
  );
}
```

This component handles:

* Wallet detection
* Selection dropdown
* Connection flow
* Address display
* Disconnect functionality

### Option 2: useWallet hook

For custom wallet UIs:

```tsx
import { useWallet } from "@meshsdk/react";

function WalletButton() {
  const { connected, wallet, connect, disconnect } = useWallet();

  if (!connected) {
    return <button onClick={() => connect("eternl")}>Connect</button>;
  }

  return (
    <div>
      <button onClick={handleTransaction}>Send</button>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}
```

### Option 3: MeshCardanoBrowserWallet class

For full control:

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

// Detect installed wallets
const wallets = MeshCardanoBrowserWallet.getInstalledWallets();

// Connect to specific wallet
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Unified API regardless of wallet
const utxos = await wallet.getUtxosMesh();
const address = await wallet.getChangeAddressBech32();
const balance = await wallet.getBalanceMesh();
```

***

## Common patterns

### Persist wallet connection

```tsx
import { useEffect } from "react";
import { useWallet } from "@meshsdk/react";

function WalletManager() {
  const { connected, connect, wallet } = useWallet();

  // Auto-connect on page load
  useEffect(() => {
    const saved = localStorage.getItem("connectedWallet");
    if (saved && !connected) connect(saved);
  }, []);

  // Save wallet choice
  useEffect(() => {
    if (connected && wallet) {
      localStorage.setItem("connectedWallet", wallet.walletId);
    }
  }, [connected, wallet]);

  return <CardanoWallet />;
}
```

### Validate network

```tsx
import { useWallet } from "@meshsdk/react";

function NetworkGuard({ children, requiredNetwork }) {
  const { wallet, connected } = useWallet();
  const [networkId, setNetworkId] = useState(null);

  useEffect(() => {
    if (connected) wallet.getNetworkId().then(setNetworkId);
  }, [connected, wallet]);

  if (connected && networkId !== requiredNetwork) {
    return <div>Please switch to {requiredNetwork === 1 ? "Mainnet" : "Testnet"}</div>;
  }

  return children;
}
```

### Handle errors

```tsx
async function connectWallet(walletId) {
  try {
    await connect(walletId);
  } catch (error) {
    if (error.message.includes("popup")) {
      showNotification("Please allow popups for wallet connection");
    } else if (error.message.includes("User")) {
      showNotification("Connection cancelled");
    } else {
      showNotification("Connection failed. Please try again.");
    }
  }
}
```

***

## Custom wallet UI

Build a branded wallet selector:

```tsx
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import { useWallet } from "@meshsdk/react";

function CustomWalletSelector() {
  const { connect, connected, wallet, disconnect } = useWallet();
  const installedWallets = MeshCardanoBrowserWallet.getInstalledWallets();

  if (connected) {
    return (
      <div className="wallet-connected">
        <span>Connected</span>
        <button onClick={disconnect}>Disconnect</button>
      </div>
    );
  }

  return (
    <div className="wallet-grid">
      {installedWallets.map((w) => (
        <button key={w.id} onClick={() => connect(w.id)}>
          <img src={w.icon} alt={w.name} />
          <span>{w.name}</span>
        </button>
      ))}
    </div>
  );
}
```

***

## Server-side wallets

For backend operations:

```typescript
import { MeshCardanoHeadlessWallet, AddressType } from "@meshsdk/wallet";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<api-key>");

const wallet = await MeshCardanoHeadlessWallet.fromMnemonic({
  networkId: 0,
  walletAddressType: AddressType.Base,
  fetcher: provider,
  submitter: provider,
  mnemonic: ["your", "mnemonic", "words", "..."],
});

// Same API as MeshCardanoBrowserWallet
const address = await wallet.getChangeAddressBech32();
const utxos = await wallet.getUtxosMesh();
```

***

## Wallet feature support

| Feature         | Support               |
| --------------- | --------------------- |
| Basic CIP-30    | All wallets           |
| Collateral      | Most wallets          |
| Multi-account   | Some wallets (Eternl) |
| Hardware wallet | Via extension         |

***

## Related topics

| Topic                | Link                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Transaction failures | [/resources/challenges/transaction-failures](/resources/challenges/transaction-failures) |
| UTXO model           | [/resources/challenges/utxo-model](/resources/challenges/utxo-model)                     |
| Coin selection       | [/resources/challenges/coin-selection](/resources/challenges/coin-selection)             |
| Wallet solutions     | [/resources/solutions/wallet-integration](/resources/solutions/wallet-integration)       |


# For Beginners
URL: /resources/solutions/beginners

Build Cardano dApps without blockchain expertise using Mesh SDK's beginner-friendly APIs.

***

title: "For Beginners"
description: "Build Cardano dApps without blockchain expertise using Mesh SDK's beginner-friendly APIs."
--------------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Start Cardano Development with Mesh SDK"
  description="Build your first Cardano dApp without prior blockchain experience."
  totalTime="PT15M"
  steps={[
  { name: "Install Mesh SDK", text: "Run npm install @meshsdk/core @meshsdk/react to add Cardano capabilities." },
  { name: "Add wallet connection", text: "Use the CardanoWallet component for one-click wallet connectivity." },
  { name: "Build your first transaction", text: "Use MeshTxBuilder to send ADA with just a few lines of code." },
  { name: "Test on preprod", text: "Connect to Cardano preprod testnet to test with free test ADA." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "Can I build Cardano dApps without blockchain experience?",
    answer: "Yes. Mesh SDK is designed for JavaScript developers without blockchain backgrounds. The APIs use familiar patterns like classes, async/await, and React hooks."
  },
  {
    question: "What programming knowledge do I need?",
    answer: "Basic JavaScript or TypeScript knowledge is sufficient. If you can build a React application, you can build Cardano dApps with Mesh."
  },
  {
    question: "How long does it take to learn?",
    answer: "Most developers can build their first transaction within an hour. The wallet connection takes minutes, and the transaction builder uses intuitive method chaining."
  },
  {
    question: "Do I need to understand UTXOs?",
    answer: "No. Mesh abstracts UTXO complexity. The SDK handles UTXO selection, change outputs, and transaction balancing automatically."
  }
]}
/>

Mesh SDK is designed for JavaScript developers new to Cardano. No blockchain expertise required. Use familiar patterns to build dApps in minutes.

## Quick start

### 1. Install Mesh

```bash
npm install @meshsdk/core @meshsdk/react
```

### 2. Add wallet connection

```tsx
import { MeshProvider, CardanoWallet } from "@meshsdk/react";

function App() {
  return (
    <MeshProvider>
      <CardanoWallet />
    </MeshProvider>
  );
}
```

### 3. Send your first transaction

```tsx
import { useWallet } from "@meshsdk/react";
import { MeshTxBuilder } from "@meshsdk/core";

function SendADA() {
  const { wallet, connected } = useWallet();

  const sendADA = async () => {
    const utxos = await wallet.getUtxos();
    const changeAddress = await wallet.getChangeAddress();

    const txBuilder = new MeshTxBuilder();
    const unsignedTx = await txBuilder
      .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
      .changeAddress(changeAddress)
      .selectUtxosFrom(utxos)
      .complete();

    const signedTx = await wallet.signTx(unsignedTx);
    const txHash = await wallet.submitTx(signedTx);
    console.log("Transaction:", txHash);
  };

  return (
    <button onClick={sendADA} disabled={!connected}>
      Send 5 ADA
    </button>
  );
}
```

***

## What makes Mesh beginner-friendly

| Feature              | Benefit                                               |
| -------------------- | ----------------------------------------------------- |
| Familiar patterns    | JavaScript classes, async/await, React hooks          |
| Automatic complexity | Fee calculation, UTXO selection handled automatically |
| Clear errors         | Helpful messages explain what went wrong              |
| Minimal setup        | No blockchain node, just npm install                  |
| Full documentation   | Guides and examples for every skill level             |

***

## Common tasks

### Connect a wallet

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

<CardanoWallet />

// Or use the hook
const { connected, wallet, connect, disconnect } = useWallet();
```

### Build a transaction

```typescript
const txBuilder = new MeshTxBuilder();
const unsignedTx = await txBuilder
  .txOut("addr...", [{ unit: "lovelace", quantity: "10000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Read blockchain data

```typescript
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("your-api-key");
const utxos = await provider.fetchAddressUTxOs("addr...");
```

***

## Recommended learning path

### Step 1: Wallet integration

```tsx
import { MeshProvider, CardanoWallet, useWallet } from "@meshsdk/react";

function App() {
  return (
    <MeshProvider>
      <Header />
    </MeshProvider>
  );
}

function Header() {
  const { connected, wallet } = useWallet();

  return (
    <header>
      <CardanoWallet />
      {connected && <WalletInfo wallet={wallet} />}
    </header>
  );
}
```

Learn: React context, wallet state, connection handling.

### Step 2: Simple transactions

```typescript
async function sendPayment(wallet, recipient, amount) {
  const utxos = await wallet.getUtxos();
  const changeAddress = await wallet.getChangeAddress();

  const txBuilder = new MeshTxBuilder();
  const unsigned = await txBuilder
    .txOut(recipient, [{ unit: "lovelace", quantity: amount }])
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signed = await wallet.signTx(unsigned);
  return await wallet.submitTx(signed);
}
```

Learn: Transaction building, signing, submission.

### Step 3: Token operations

```typescript
// Send existing tokens
txBuilder.txOut(recipient, [
  { unit: "policyId" + "tokenNameHex", quantity: "10" }
]);

// Mint new tokens
txBuilder
  .mint("1000", policyId, tokenNameHex)
  .mintingScript(forgingScript);
```

Learn: Asset structure, minting, multi-asset transactions.

### Step 4: Smart contracts

```typescript
import { mConStr0 } from "@meshsdk/core";

// Lock funds at script
txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "50000000" }])
  .txOutInlineDatumValue(mConStr0([]));

// Unlock funds
txBuilder
  .spendingPlutusScriptV2()
  .txIn(utxo.input.txHash, utxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(mConStr0([]))
  .txInScript(scriptCbor);
```

Learn: Datums, redeemers, script addresses.

***

## First projects

### NFT gallery

```tsx
import { useAssets } from "@meshsdk/react";

function NFTGallery() {
  const assets = useAssets();
  const nfts = assets?.filter(a => a.quantity === "1" && a.unit !== "lovelace");

  return (
    <div className="gallery">
      {nfts?.map(nft => (
        <NFTCard key={nft.unit} asset={nft} />
      ))}
    </div>
  );
}
```

### Payment button

```tsx
function PaymentButton({ amount, recipient }) {
  const { wallet, connected } = useWallet();

  const pay = async () => {
    const utxos = await wallet.getUtxos();
    const changeAddress = await wallet.getChangeAddress();

    const txBuilder = new MeshTxBuilder();
    const unsigned = await txBuilder
      .txOut(recipient, [{ unit: "lovelace", quantity: amount }])
      .changeAddress(changeAddress)
      .selectUtxosFrom(utxos)
      .complete();

    const signed = await wallet.signTx(unsigned);
    await wallet.submitTx(signed);
  };

  return (
    <button onClick={pay} disabled={!connected}>
      Pay {Number(amount) / 1_000_000} ADA
    </button>
  );
}
```

***

## Testing

### Use preprod testnet

1. Get test ADA from the [Cardano Testnet Faucet](https://docs.cardano.org/cardano-testnet/tools/faucet/)
2. Switch your wallet to preprod network
3. Test all functionality risk-free
4. Move to mainnet when confident

### Local development

No blockchain node required. Mesh connects to public infrastructure.

```bash
npm run dev
```

***

## Why beginners choose Mesh

| Reason                  | Details                                     |
| ----------------------- | ------------------------------------------- |
| Skip the deep dive      | Build first, learn concepts as needed       |
| Use familiar JavaScript | No new programming language                 |
| Working examples        | Copy, paste, modify                         |
| Clear error messages    | "Insufficient funds" not cryptographic dump |
| Community support       | Active Discord, no question too basic       |

***

## Related resources

| Resource                 | Link                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------ |
| Wallet integration       | [/resources/solutions/wallet-integration](/resources/solutions/wallet-integration)   |
| React components         | [/resources/solutions/react-components](/resources/solutions/react-components)       |
| Transaction builder      | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder) |
| Learning curve challenge | [/resources/challenges/learning-curve](/resources/challenges/learning-curve)         |
| Getting started guide    | [/guides](/guides)                                                                   |


# Mesh SDK Solutions
URL: /resources/solutions

Build Cardano dApps faster with Mesh SDK's production-ready tools for wallets, transactions, and smart contracts.

***

title: "Mesh SDK Solutions"
description: "Build Cardano dApps faster with Mesh SDK's production-ready tools for wallets, transactions, and smart contracts."
--------------------------------------------------------------------------------------------------------------------------------

import { linksSolutionsAeo, metaSolutionsAeo } from "@/data/links-solutions-aeo";
import { linksSolutions, metaSolutions } from "@/data/links-solutions";
import Link from "next/link";
import {
  Card,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Getting Started with Mesh SDK for Cardano Development"
  description="Install Mesh SDK and build your first Cardano dApp in minutes."
  totalTime="PT10M"
  steps={[
  { name: "Install Mesh packages", text: "Run npm install @meshsdk/core @meshsdk/react to add Mesh to your project." },
  { name: "Configure a blockchain provider", text: "Set up Blockfrost, Koios, or another provider to connect to Cardano." },
  { name: "Add wallet connection", text: "Use the CardanoWallet component or MeshCardanoBrowserWallet API for wallet connectivity." },
  { name: "Build and submit transactions", text: "Use MeshTxBuilder to construct transactions with automatic UTXO handling." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "What is Mesh SDK?",
    answer: "Mesh SDK is a comprehensive TypeScript toolkit for building Cardano applications. It provides high-level APIs that abstract UTXO complexity, pre-built wallet components, automatic transaction building, and smart contract integration."
  },
  {
    question: "How does Mesh compare to other Cardano tools?",
    answer: "Mesh stands out with TypeScript-first design, comprehensive documentation, production-ready components, automatic UTXO management, and consistent APIs across all wallet providers."
  },
  {
    question: "Does Mesh support all Cardano wallets?",
    answer: "Yes, Mesh supports all CIP-30 compatible wallets including Eternl, Lace, Yoroi, and more. The MeshCardanoBrowserWallet API provides consistent behavior regardless of wallet."
  },
  {
    question: "Is Mesh production-ready?",
    answer: "Yes. Mesh powers numerous production dApps on Cardano mainnet, from NFT marketplaces to DeFi protocols. Regular updates ensure compatibility with protocol changes."
  }
]}
/>

Mesh SDK simplifies Cardano dApp development with automatic UTXO management, unified wallet integration, and high-level APIs for smart contracts.

## Quick start

### 1. Install Mesh

```bash
npm install @meshsdk/core @meshsdk/react
```

### 2. Configure a provider

```typescript
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<your-api-key>");
```

### 3. Add wallet connection

```tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

function App() {
  const { connected } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Wallet connected!</p>}
    </div>
  );
}
```

### 4. Build transactions

```typescript
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder({ fetcher: provider, submitter: provider });
const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(await wallet.getChangeAddress())
  .selectUtxosFrom(await wallet.getUtxos())
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
```

***

## What Mesh solves

| Challenge            | Without Mesh                    | With Mesh                |
| -------------------- | ------------------------------- | ------------------------ |
| UTXO management      | Manual input/output tracking    | Automatic selection      |
| Wallet integration   | Provider-specific code          | Single unified API       |
| Transaction building | Low-level fee calculation       | Declarative builder      |
| Smart contracts      | Complex datum/redeemer handling | High-level APIs          |
| Learning curve       | Weeks to understand             | Production code in hours |

***

## Solution categories

<div className="grid md:grid-cols-2 gap-6 items-stretch my-8">
  {linksSolutionsAeo.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

***

## Why teams choose Mesh

| Benefit                     | Details                                    |
| --------------------------- | ------------------------------------------ |
| Fastest time to market      | Ship features in days, not weeks           |
| Comprehensive documentation | Guides with working examples               |
| Active maintenance          | Regular updates for protocol changes       |
| Production-proven           | Powers NFT marketplaces and DeFi protocols |
| Community support           | Discord, GitHub, experienced developers    |

***

## Advanced features

Beyond basic transactions, Mesh supports:

* **Smart contracts** - Plutus V1, V2, and Aiken with automatic datum/redeemer handling
* **Native tokens** - Mint, burn, transfer with CIP-25 and CIP-68 metadata
* **Multi-signature** - Treasury management and organizational controls
* **Staking** - Programmatic stake pool management
* **Governance** - DRep registration and proposal voting

***

## Products and services

<div className="grid md:grid-cols-2 gap-6 items-stretch my-8">
  {linksSolutions.map((card) => (
      <Link key={card.title} href={card.link} className="no-underline">
        <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
          <CardTitle className="font-heading">{card.title}</CardTitle>
          <CardDescription>{card.desc}</CardDescription>
        </Card>
      </Link>
    ))}
</div>

***

## Get help

| Resource           | Link                                                                             |
| ------------------ | -------------------------------------------------------------------------------- |
| GitHub Discussions | [github.com/MeshJS/mesh/discussions](https://github.com/MeshJS/mesh/discussions) |
| Discord            | [discord.gg/meshjs](https://discord.gg/meshjs)                                   |
| Documentation      | [/docs](/docs)                                                                   |
| Tutorials          | [/resources/tutorials](/resources/tutorials)                                     |

***

## Related challenges

| Challenge                                                          | Mesh solution                                 |
| ------------------------------------------------------------------ | --------------------------------------------- |
| [Transaction failures](/resources/challenges/transaction-failures) | Automatic fee calculation and UTXO management |
| [UTXO complexity](/resources/challenges/utxo-model)                | High-level APIs for payments                  |
| [Wallet integration](/resources/challenges/wallet-integration)     | Unified CIP-30 interface                      |
| [Coin selection](/resources/challenges/coin-selection)             | Optimized algorithms                          |
| [Learning curve](/resources/challenges/learning-curve)             | Familiar APIs and comprehensive docs          |


# React Components
URL: /resources/solutions/react-components

Production-ready React components for Cardano dApp development with Mesh SDK.

***

title: "React Components"
description: "Production-ready React components for Cardano dApp development with Mesh SDK."
--------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Add React Components with Mesh SDK"
  description="Integrate production-ready Cardano components into your React application in minutes."
  totalTime="PT5M"
  steps={[
  { name: "Install Mesh React", text: "Run npm install @meshsdk/react to add Cardano React components." },
  { name: "Add MeshProvider", text: "Wrap your application with MeshProvider to enable Mesh context." },
  { name: "Import components", text: "Import CardanoWallet, useWallet, or other components from @meshsdk/react." },
  { name: "Add to your UI", text: "Place components in your layout and customize as needed." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "What React components does Mesh provide?",
    answer: "Mesh provides CardanoWallet for wallet connection, useWallet hook for state management, useAssets for token display, useLovelace for ADA balance, and useAddress for address handling."
  },
  {
    question: "Are Mesh components customizable?",
    answer: "Yes. Mesh components accept styling props and can be customized through CSS. For complete control, build custom components using Mesh's hooks and utilities."
  },
  {
    question: "Do Mesh components work with Next.js?",
    answer: "Yes. Mesh React components work with Next.js, Create React App, Vite, and other React frameworks. For Next.js, ensure MeshProvider is added to your client-side layout."
  },
  {
    question: "What is MeshProvider?",
    answer: "MeshProvider is a React context provider that manages wallet state across your application. It enables hooks like useWallet to access wallet data anywhere without prop drilling."
  }
]}
/>

Mesh provides production-ready React components for Cardano dApps. Add wallet connectivity in minutes with pre-built components or build custom UIs with hooks.

## Quick start

```bash
npm install @meshsdk/react
```

### Add MeshProvider

```tsx
import { MeshProvider } from "@meshsdk/react";

function App() {
  return (
    <MeshProvider>
      <YourApp />
    </MeshProvider>
  );
}
```

### Add wallet connection

```tsx
import { CardanoWallet, useWallet, useLovelace } from "@meshsdk/react";

function Dashboard() {
  const { connected } = useWallet();
  const lovelace = useLovelace();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Balance: {Number(lovelace) / 1_000_000} ADA</p>}
    </div>
  );
}
```

***

## Available components

| Component       | Purpose                           |
| --------------- | --------------------------------- |
| `CardanoWallet` | Complete wallet connection UI     |
| `MeshProvider`  | Context provider for wallet state |

## Available hooks

| Hook          | Purpose                     |
| ------------- | --------------------------- |
| `useWallet`   | Wallet state and connection |
| `useLovelace` | ADA balance                 |
| `useAssets`   | Native tokens and NFTs      |
| `useAddress`  | Wallet addresses            |
| `useNetwork`  | Network detection           |

***

## CardanoWallet

The primary wallet connection component:

```tsx
import { CardanoWallet } from "@meshsdk/react";

// Basic usage
<CardanoWallet />

// With customization
<CardanoWallet
  label="Connect Wallet"
  onConnected={() => console.log("Connected!")}
  isDark={true}
/>
```

Features:

* Automatic wallet detection
* Selection dropdown
* Connection state management
* Address display
* Disconnect functionality

***

## useWallet hook

Access wallet state anywhere:

```tsx
import { useWallet } from "@meshsdk/react";

function WalletInfo() {
  const {
    connected,      // boolean
    connecting,     // boolean
    wallet,         // BrowserWallet instance
    name,           // connected wallet name
    connect,        // function to connect
    disconnect,     // function to disconnect
  } = useWallet();

  return (
    <div>
      {connected ? (
        <p>Connected to {name}</p>
      ) : (
        <button onClick={() => connect("eternl")}>Connect</button>
      )}
    </div>
  );
}
```

***

## useLovelace hook

Get the wallet's ADA balance:

```tsx
import { useLovelace } from "@meshsdk/react";

function Balance() {
  const lovelace = useLovelace();

  if (!lovelace) return null;

  const ada = Number(lovelace) / 1_000_000;
  return <p>{ada.toFixed(2)} ADA</p>;
}
```

***

## useAssets hook

Access native tokens and NFTs:

```tsx
import { useAssets } from "@meshsdk/react";

function TokenList() {
  const assets = useAssets();

  if (!assets) return <p>Loading...</p>;

  return (
    <ul>
      {assets.map((asset) => (
        <li key={asset.unit}>
          {asset.assetName}: {asset.quantity}
        </li>
      ))}
    </ul>
  );
}
```

***

## useAddress hook

Access wallet addresses:

```tsx
import { useAddress } from "@meshsdk/react";

function AddressDisplay() {
  const address = useAddress();

  if (!address) return null;

  return (
    <p title={address}>
      {address.slice(0, 8)}...{address.slice(-8)}
    </p>
  );
}
```

***

## useNetwork hook

Detect the connected network:

```tsx
import { useNetwork } from "@meshsdk/react";

function NetworkBadge() {
  const network = useNetwork();

  return (
    <span className={network === 1 ? "mainnet" : "testnet"}>
      {network === 1 ? "Mainnet" : "Testnet"}
    </span>
  );
}
```

***

## Custom wallet UI

Build fully custom wallet interfaces:

```tsx
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import { useWallet, useLovelace, useAssets } from "@meshsdk/react";

function CustomWalletPanel() {
  const { connected, wallet, connect, disconnect } = useWallet();
  const lovelace = useLovelace();
  const assets = useAssets();

  if (!connected) {
    const wallets = MeshCardanoBrowserWallet.getInstalledWallets();

    return (
      <div className="wallet-selector">
        <h3>Select Wallet</h3>
        {wallets.map(w => (
          <button key={w.id} onClick={() => connect(w.id)}>
            <img src={w.icon} alt="" width={24} />
            {w.name}
          </button>
        ))}
      </div>
    );
  }

  return (
    <div className="wallet-panel">
      <div className="balance">
        {(Number(lovelace) / 1_000_000).toFixed(2)} ADA
      </div>
      <div className="assets">
        {assets?.length} tokens
      </div>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}
```

***

## Framework setup

### Next.js

```tsx
// app/layout.tsx
"use client";

import { MeshProvider } from "@meshsdk/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MeshProvider>{children}</MeshProvider>
      </body>
    </html>
  );
}
```

### Vite / Create React App

```tsx
// main.tsx
import { MeshProvider } from "@meshsdk/react";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")).render(
  <MeshProvider>
    <App />
  </MeshProvider>
);
```

***

## Why use Mesh React components

| Benefit               | Details                                               |
| --------------------- | ----------------------------------------------------- |
| Save development time | Wallet detection, connection, error handling built-in |
| Production tested     | Used by major Cardano dApps                           |
| Consistent UX         | Users recognize familiar patterns                     |
| TypeScript first      | Full type definitions                                 |
| Customizable          | Start with defaults, customize as needed              |

***

## Related resources

| Resource            | Link                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------ |
| Wallet integration  | [/resources/solutions/wallet-integration](/resources/solutions/wallet-integration)   |
| Transaction builder | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder) |
| React documentation | [/react](/react)                                                                     |
| Wallet challenges   | [/resources/challenges/wallet-integration](/resources/challenges/wallet-integration) |


# Transaction Builder
URL: /resources/solutions/transaction-builder

Build Cardano transactions with automatic UTXO selection, fee calculation, and change handling using Mesh SDK.

***

title: "Transaction Builder"
description: "Build Cardano transactions with automatic UTXO selection, fee calculation, and change handling using Mesh SDK."
-----------------------------------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Build Cardano Transactions with Mesh SDK"
  description="Create and submit Cardano transactions with automatic UTXO selection, fee calculation, and change handling."
  totalTime="PT5M"
  steps={[
  { name: "Install Mesh core", text: "Run npm install @meshsdk/core to add transaction building capabilities." },
  { name: "Configure a provider", text: "Set up Blockfrost or another provider to fetch UTXOs and submit transactions." },
  { name: "Create MeshTxBuilder", text: "Initialize MeshTxBuilder with your provider." },
  { name: "Build and submit", text: "Define outputs, call complete(), then sign and submit." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "How does Mesh handle UTXO selection?",
    answer: "Mesh analyzes your outputs and selects optimal UTXOs from your wallet to cover the transaction. It considers token requirements, minimizes inputs, and handles change automatically."
  },
  {
    question: "Does Mesh calculate fees automatically?",
    answer: "Yes. When you call complete(), Mesh calculates the exact fee based on transaction size and protocol parameters."
  },
  {
    question: "Can I build complex multi-output transactions?",
    answer: "Yes. MeshTxBuilder supports multiple outputs, native tokens, metadata, smart contract interactions, and multi-signature requirements."
  },
  {
    question: "What happens if my transaction fails?",
    answer: "Mesh provides descriptive error messages for common issues like insufficient funds, invalid addresses, or missing collateral."
  }
]}
/>

MeshTxBuilder simplifies Cardano transaction construction. Specify outputs, and Mesh handles UTXO selection, fee calculation, and change management automatically.

## Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### Basic transaction

```typescript
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

const provider = new BlockfrostProvider("<your-api-key>");
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

const txBuilder = new MeshTxBuilder({
  fetcher: provider,
  submitter: provider,
});

const unsignedTx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(await wallet.getChangeAddressBech32())
  .selectUtxosFrom(await wallet.getUtxosMesh())
  .complete();

const signedTx = await wallet.signTx(unsignedTx, false);
const txHash = await wallet.submitTx(signedTx);
```

***

## Features

| Feature                  | Description                                    |
| ------------------------ | ---------------------------------------------- |
| Automatic UTXO selection | Optimal input selection based on outputs       |
| Fee calculation          | Precise fee using protocol parameters          |
| Change handling          | Automatic change output with correct address   |
| Native token support     | Send tokens with automatic minimum ADA         |
| Metadata                 | Attach transaction metadata                    |
| Smart contracts          | Interact with Plutus scripts                   |
| Multi-signature          | Create transactions requiring multiple signers |
| Validity intervals       | Set transaction validity windows               |

***

## Common patterns

### Send ADA

```typescript
const tx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Send native tokens

```typescript
const tx = await txBuilder
  .txOut(recipientAddress, [
    { unit: policyId + assetName, quantity: "1" },
    { unit: "lovelace", quantity: "2000000" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Send to multiple recipients

```typescript
const tx = await txBuilder
  .txOut(address1, [{ unit: "lovelace", quantity: "5000000" }])
  .txOut(address2, [{ unit: "lovelace", quantity: "3000000" }])
  .txOut(address3, [{ unit: "lovelace", quantity: "7000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Add metadata

```typescript
const tx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .metadataValue("674", { msg: ["Transaction message"] })
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Mint tokens

```typescript
const tx = await txBuilder
  .mint("1", policyId, tokenName)
  .mintingScript(mintingScript)
  .mintRedeemerValue(redeemer)
  .txOut(recipientAddress, [
    { unit: policyId + tokenName, quantity: "1" },
    { unit: "lovelace", quantity: "2000000" }
  ])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Interact with smart contracts

```typescript
const tx = await txBuilder
  .spendingPlutusScriptV2()
  .txIn(scriptUtxo.input.txHash, scriptUtxo.input.outputIndex)
  .txInInlineDatumPresent()
  .txInRedeemerValue(redeemer)
  .txInScript(script)
  .txOut(recipientAddress, scriptUtxo.output.amount)
  .txOutInlineDatumValue(newDatum)
  .requiredSignerHash(signerPkh)
  .changeAddress(changeAddress)
  .txInCollateral(collateralUtxo.input.txHash, collateralUtxo.input.outputIndex)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Advanced patterns

### Manual UTXO selection

```typescript
const tx = await txBuilder
  .txIn(specificUtxo.input.txHash, specificUtxo.input.outputIndex)
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .complete();
```

### Validity intervals

```typescript
const slot = await provider.resolveSlotNo("now");

const tx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .invalidBefore(slot)
  .invalidHereafter(slot + 600) // Valid for ~10 minutes
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Required signers

```typescript
const tx = await txBuilder
  .txOut(recipientAddress, [{ unit: "lovelace", quantity: "5000000" }])
  .requiredSignerHash(additionalSignerPkh)
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

***

## Error handling

```typescript
try {
  const tx = await txBuilder
    .txOut(recipientAddress, amount)
    .changeAddress(changeAddress)
    .selectUtxosFrom(utxos)
    .complete();

  const signedTx = await wallet.signTx(tx);
  const txHash = await wallet.submitTx(signedTx);
  console.log("Transaction submitted:", txHash);
} catch (error) {
  if (error.message.includes("Insufficient")) {
    showError("Not enough ADA to complete this transaction");
  } else if (error.message.includes("User")) {
    showInfo("Transaction cancelled");
  } else {
    showError("Transaction failed. Please try again.");
  }
}
```

***

## Integration with React

```tsx
import { useWallet } from "@meshsdk/react";
import { MeshTxBuilder, BlockfrostProvider } from "@meshsdk/core";

function SendButton({ recipient, amount }) {
  const { wallet } = useWallet();
  const provider = new BlockfrostProvider("<api-key>");

  async function handleSend() {
    const txBuilder = new MeshTxBuilder({
      fetcher: provider,
      submitter: provider,
    });

    const tx = await txBuilder
      .txOut(recipient, [{ unit: "lovelace", quantity: amount }])
      .changeAddress(await wallet.getChangeAddress())
      .selectUtxosFrom(await wallet.getUtxos())
      .complete();

    const signedTx = await wallet.signTx(tx);
    const txHash = await wallet.submitTx(signedTx);
    return txHash;
  }

  return <button onClick={handleSend}>Send {Number(amount) / 1_000_000} ADA</button>;
}
```

***

## Why MeshTxBuilder

| Benefit                    | Details                        |
| -------------------------- | ------------------------------ |
| Eliminates UTXO complexity | Describe what to send, not how |
| Prevents common errors     | Validates before submission    |
| Simplifies smart contracts | High-level APIs for scripts    |
| Protocol-aware             | Stays current with updates     |

***

## Related resources

| Resource                  | Link                                                                                     |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| Wallet integration        | [/resources/solutions/wallet-integration](/resources/solutions/wallet-integration)       |
| React components          | [/resources/solutions/react-components](/resources/solutions/react-components)           |
| Transaction failures      | [/resources/challenges/transaction-failures](/resources/challenges/transaction-failures) |
| UTXO model                | [/resources/challenges/utxo-model](/resources/challenges/utxo-model)                     |
| Transaction documentation | [/apis/txbuilder](/apis/txbuilder)                                                       |


# TypeScript-First Development
URL: /resources/solutions/typescript

Build Cardano dApps with complete type safety using Mesh SDK's comprehensive TypeScript definitions.

***

title: "TypeScript-First Development"
description: "Build Cardano dApps with complete type safety using Mesh SDK's comprehensive TypeScript definitions."
-------------------------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Set Up TypeScript Cardano Development with Mesh SDK"
  description="Configure a fully typed Cardano development environment using Mesh SDK's TypeScript-first architecture."
  totalTime="PT10M"
  steps={[
  { name: "Install Mesh packages", text: "Run npm install @meshsdk/core to add the fully-typed Cardano SDK to your project." },
  { name: "Configure TypeScript", text: "Ensure tsconfig.json has strict mode enabled for maximum type safety benefits." },
  { name: "Import typed modules", text: "Import MeshTxBuilder from @meshsdk/core and MeshCardanoBrowserWallet from @meshsdk/wallet." },
  { name: "Use IDE autocompletion", text: "Leverage IntelliSense to explore available methods and required parameters with full type hints." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "Does Mesh SDK have TypeScript support?",
    answer: "Mesh SDK is built TypeScript-first with comprehensive type definitions for all APIs. Every function, class, transaction type, and blockchain data structure is fully typed."
  },
  {
    question: "What TypeScript version is required for Mesh SDK?",
    answer: "Mesh SDK works with TypeScript 4.7 and above. We recommend using the latest TypeScript version for the best developer experience."
  },
  {
    question: "Can I use Mesh SDK with JavaScript?",
    answer: "Yes, Mesh SDK works with JavaScript projects. While you won't get compile-time type checking, most IDEs still provide autocompletion from the TypeScript definitions."
  },
  {
    question: "Are Cardano-specific types provided?",
    answer: "Yes, Mesh provides types for all Cardano primitives including UTxO, Asset, Address, Transaction, Datum, Redeemer, and more."
  }
]}
/>

Mesh SDK provides complete TypeScript definitions for all Cardano APIs. Catch errors at compile time, explore APIs through autocompletion, and build with confidence.

## Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### Configure TypeScript

```json
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}
```

### Build with types

```typescript
import { MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import type { UTxO, Asset } from "@meshsdk/core";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const utxos: UTxO[] = await wallet.getUtxosMesh();
const changeAddress: string = await wallet.getChangeAddressBech32();

const txBuilder = new MeshTxBuilder();
const unsignedTx = await txBuilder
  .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }])
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();

const signedTx = await wallet.signTx(unsignedTx);
```

***

## Features

| Feature                 | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| Complete type coverage  | Every API surface is fully typed                     |
| IDE autocompletion      | IntelliSense shows methods, parameters, return types |
| Compile-time validation | Catch errors before runtime                          |
| JSDoc documentation     | Usage examples appear in your editor                 |
| Cardano primitives      | UTxO, Asset, Address, Datum, Redeemer types          |
| Framework agnostic      | Works with React, Vue, Svelte, Node.js               |

***

## Type-safe patterns

### Transaction building

```typescript
import { MeshTxBuilder } from "@meshsdk/core";
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import type { UTxO, Asset } from "@meshsdk/core";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");
const utxos: UTxO[] = await wallet.getUtxosMesh();
const changeAddress: string = await wallet.getChangeAddressBech32();

const txBuilder = new MeshTxBuilder();

// TypeScript enforces string for address, Asset[] for amount
txBuilder.txOut(
  "addr_test1qz...",
  [{ unit: "lovelace", quantity: "5000000" }]
);

// Send native tokens
txBuilder.txOut("addr_test1qz...", [
  {
    unit: "policy_id_hex" + "asset_name_hex",
    quantity: "100"
  }
]);

const unsignedTx: string = await txBuilder
  .changeAddress(changeAddress)
  .selectUtxosFrom(utxos)
  .complete();
```

### Wallet APIs

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import type { UTxO, Asset } from "@meshsdk/core";

const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Typed return values
const address: string = await wallet.getChangeAddressBech32();
const networkId: number = await wallet.getNetworkId();
const utxos: UTxO[] = await wallet.getUtxosMesh();
const balance: Asset[] = await wallet.getBalanceMesh();

// UTxO type includes all fields
utxos.forEach(utxo => {
  console.log(utxo.input.txHash);      // string
  console.log(utxo.input.outputIndex); // number
  console.log(utxo.output.address);    // string
  console.log(utxo.output.amount);     // Asset[]
});
```

### Cardano data types

```typescript
import type {
  UTxO,
  Asset,
  PlutusScript,
  NativeScript,
  Data,
  Recipient
} from "@meshsdk/core";

// Asset type
const asset: Asset = {
  unit: "lovelace",
  quantity: "5000000"
};

// UTxO type
const utxo: UTxO = {
  input: {
    txHash: "abc123...",
    outputIndex: 0
  },
  output: {
    address: "addr_test1...",
    amount: [asset],
    dataHash: undefined,
    plutusData: undefined,
    scriptRef: undefined
  }
};

// Plutus script type
const script: PlutusScript = {
  version: "V2",
  code: "590abc..."
};
```

### Smart contracts

```typescript
import { MeshTxBuilder, mConStr0, mConStr1 } from "@meshsdk/core";
import type { Data } from "@meshsdk/core";

// Type-safe datum construction
const datum: Data = mConStr0([
  "owner_address",
  1000000n,
  mConStr1(["metadata"])
]);

// Typed redeemer
const redeemer: Data = mConStr0([]);

// Transaction with typed contract interaction
const txBuilder = new MeshTxBuilder();
txBuilder
  .txOut(scriptAddress, [{ unit: "lovelace", quantity: "10000000" }])
  .txOutInlineDatumValue(datum);
```

***

## Compile-time error catching

TypeScript catches mistakes before you run code:

```typescript
import { MeshTxBuilder } from "@meshsdk/core";

const txBuilder = new MeshTxBuilder();

// Error: Argument of type 'number' is not assignable to parameter of type 'string'
txBuilder.txOut("addr_test1...", [{ unit: "lovelace", quantity: 5000000 }]);

// Correct: quantity must be a string
txBuilder.txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }]);
```

***

## IDE features

| Feature             | Benefit                        |
| ------------------- | ------------------------------ |
| Hover documentation | See type definitions inline    |
| Autocompletion      | Discover methods as you type   |
| Parameter hints     | Know required arguments        |
| Go to Definition    | Jump to type sources           |
| Find All References | Track usage across codebase    |
| Safe refactoring    | Rename symbols with confidence |

***

## Recommended configuration

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

### Working with BigInt

```typescript
// BigInt for large values
const lovelace = 5000000n;
const quantity = BigInt("1000000000000");

// Convert to string for transaction methods
txBuilder.txOut(address, [{ unit: "lovelace", quantity: lovelace.toString() }]);
```

***

## Why TypeScript for Cardano

| Benefit                 | Details                                        |
| ----------------------- | ---------------------------------------------- |
| Prevent costly mistakes | Catch errors before transactions reach mainnet |
| Faster development      | IDE guidance instead of documentation lookup   |
| Team collaboration      | Types serve as living documentation            |
| Manage complexity       | Encode Cardano's rules in the type system      |

***

## Related resources

| Resource            | Link                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------ |
| Transaction builder | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder) |
| React components    | [/resources/solutions/react-components](/resources/solutions/react-components)       |
| Wallet integration  | [/resources/solutions/wallet-integration](/resources/solutions/wallet-integration)   |
| Learning curve      | [/resources/challenges/learning-curve](/resources/challenges/learning-curve)         |
| Getting started     | [/getting-started](/getting-started)                                                 |


# Wallet Integration
URL: /resources/solutions/wallet-integration

Add Cardano wallet connectivity in minutes with Mesh SDK's unified API for all CIP-30 wallets.

***

title: "Wallet Integration"
description: "Add Cardano wallet connectivity in minutes with Mesh SDK's unified API for all CIP-30 wallets."
-------------------------------------------------------------------------------------------------------------

import Link from "next/link";
import { HowToSchema, FAQSchema } from "@/components/seo";

<HowToSchema
  name="Integrate Cardano Wallets with Mesh SDK"
  description="Add wallet connectivity to any Cardano dApp in minutes using Mesh SDK's unified API and React components."
  totalTime="PT5M"
  steps={[
  { name: "Install Mesh packages", text: "Run npm install @meshsdk/core @meshsdk/react to add wallet support." },
  { name: "Wrap app with MeshProvider", text: "Add MeshProvider at the root to enable wallet context." },
  { name: "Add CardanoWallet component", text: "Place the CardanoWallet component for instant multi-wallet support." },
  { name: "Access wallet with useWallet", text: "Use the useWallet hook to access wallet state and methods." }
]}
/>

<FAQSchema
  faqs={[
  {
    question: "What is the fastest way to integrate Cardano wallets?",
    answer: "Mesh SDK provides the fastest integration. Install @meshsdk/react, wrap with MeshProvider, and add CardanoWallet. Multi-wallet support in under 5 minutes."
  },
  {
    question: "Does Mesh support all Cardano wallets?",
    answer: "Yes. Mesh supports all CIP-30 compatible wallets including Eternl, Lace, Yoroi, Typhon, and more. The unified API works identically across all wallets."
  },
  {
    question: "How do I detect installed wallets?",
    answer: "Use MeshCardanoBrowserWallet.getInstalledWallets() to get a list of all installed CIP-30 wallets with metadata including name, icon, and identifier."
  },
  {
    question: "Can I customize the wallet UI?",
    answer: "Yes. While CardanoWallet provides a ready-to-use component, you can build fully custom UIs using MeshCardanoBrowserWallet and useWallet hook."
  }
]}
/>

Mesh provides the fastest Cardano wallet integration. Add multi-wallet support with pre-built React components or build custom UIs with the unified API.

## Quick start

```bash
npm install @meshsdk/core @meshsdk/react
```

### 1. Add MeshProvider

```tsx
import { MeshProvider } from "@meshsdk/react";

function App() {
  return (
    <MeshProvider>
      <YourApp />
    </MeshProvider>
  );
}
```

### 2. Add wallet connection

```tsx
import { CardanoWallet } from "@meshsdk/react";

function Header() {
  return (
    <header>
      <Logo />
      <CardanoWallet />
    </header>
  );
}
```

### 3. Access wallet state

```tsx
import { useWallet } from "@meshsdk/react";

function Dashboard() {
  const { connected, wallet } = useWallet();

  if (!connected) return <p>Please connect your wallet</p>;

  return <WalletDashboard wallet={wallet} />;
}
```

***

## Features

| Feature              | Description                                         |
| -------------------- | --------------------------------------------------- |
| Universal support    | All CIP-30 wallets (Eternl, Lace, Yoroi, Typhon...) |
| Pre-built components | CardanoWallet handles everything                    |
| React hooks          | Reactive state management                           |
| Automatic detection  | Identifies all installed wallets                    |
| Normalized API       | Consistent methods across wallets                   |
| TypeScript           | Full type definitions                               |

***

## API options

### CardanoWallet component

Complete wallet UI in one component:

```tsx
<CardanoWallet
  label="Connect Wallet"
  onConnected={() => console.log("Connected!")}
  isDark={true}
/>
```

### useWallet hook

Access wallet state anywhere:

```tsx
const {
  connected,      // boolean
  wallet,         // BrowserWallet instance
  connect,        // function to connect
  disconnect,     // function to disconnect
  connecting,     // boolean
  name,           // wallet name
} = useWallet();
```

### MeshCardanoBrowserWallet class

For full control:

```typescript
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

// Detect installed wallets
const wallets = MeshCardanoBrowserWallet.getInstalledWallets();

// Connect to specific wallet
const wallet = await MeshCardanoBrowserWallet.enable("eternl");

// Unified API (Mesh format)
const utxos = await wallet.getUtxosMesh();
const address = await wallet.getChangeAddressBech32();
const balance = await wallet.getBalanceMesh();
```

***

## Common patterns

### Persist wallet connection

```tsx
import { useEffect } from "react";
import { useWallet } from "@meshsdk/react";

function WalletManager() {
  const { connected, connect, wallet } = useWallet();

  useEffect(() => {
    const saved = localStorage.getItem("preferredWallet");
    if (saved && !connected) connect(saved);
  }, []);

  useEffect(() => {
    if (connected && wallet) {
      localStorage.setItem("preferredWallet", wallet.walletId);
    }
  }, [connected]);

  return <CardanoWallet />;
}
```

### Validate network

```tsx
const networkId = await wallet.getNetworkId();
if (networkId !== 1) {
  throw new Error("Please switch to Mainnet");
}
```

### Handle errors

```tsx
try {
  await connect(walletId);
} catch (error) {
  if (error.message.includes("User")) {
    showToast("Connection cancelled");
  } else if (error.message.includes("popup")) {
    showToast("Please allow popups");
  } else {
    showToast("Failed to connect");
  }
}
```

***

## Custom wallet UI

```tsx
import { MeshCardanoBrowserWallet } from "@meshsdk/wallet";
import { useWallet } from "@meshsdk/react";

function CustomWalletButton() {
  const { connect, connected, disconnect, name } = useWallet();
  const wallets = MeshCardanoBrowserWallet.getInstalledWallets();

  if (connected) {
    return (
      <button onClick={disconnect}>
        Disconnect {name}
      </button>
    );
  }

  return (
    <div className="wallet-options">
      {wallets.map(w => (
        <button key={w.id} onClick={() => connect(w.id)}>
          <img src={w.icon} alt={w.name} />
          {w.name}
        </button>
      ))}
    </div>
  );
}
```

***

## Why choose Mesh for wallets

| Benefit               | Details                             |
| --------------------- | ----------------------------------- |
| One interface for all | No wallet-specific code             |
| Production tested     | Powers major Cardano dApps          |
| Actively maintained   | Updates for new wallets and changes |
| TypeScript support    | Full type definitions               |

***

## Related resources

| Resource                    | Link                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------ |
| Transaction builder         | [/resources/solutions/transaction-builder](/resources/solutions/transaction-builder) |
| React components            | [/resources/solutions/react-components](/resources/solutions/react-components)       |
| Wallet challenges           | [/resources/challenges/wallet-integration](/resources/challenges/wallet-integration) |
| BrowserWallet documentation | [/wallets/browserwallet](/wallets/browserwallet)                                     |


# Bitcoin Browser Wallet
URL: /apis/wallets/bitcoin/browser-wallet

Connect, query and sign with Bitcoin browser extension wallets (e.g. Xverse) via a unified API.

***

title: "Bitcoin Browser Wallet"
description: "Connect, query and sign with Bitcoin browser extension wallets (e.g. Xverse) via a unified API."
icon: BanknotesIcon
-------------------

`BitcoinBrowserWallet` wraps any installed Bitcoin browser extension and exposes a single, consistent API for connecting, querying balances, signing messages, and broadcasting transactions.
It communicates with extensions via the [Sats Connect](https://docs.xverse.app/sats-connect) protocol — no SDK dependency on the extension itself is required.

**Currently supported extensions:** Xverse

> **SSR / Next.js note** — All methods guard against server-side rendering. Calling any method outside a browser context throws a clear error. In Next.js, gate calls with `typeof window !== "undefined"` or place them inside `useEffect`.

***

## Get Installed Wallets

Returns the list of Bitcoin wallet extensions the user currently has installed.

```tsx
import { BitcoinBrowserWallet } from "@meshsdk/wallet";

const wallets = BitcoinBrowserWallet.getInstalledWallets();
// [{ id: "xverse", name: "Xverse", icon: "https://..." }]
```

***

## Connect Wallet

Opens the extension's approval popup and returns a connected `BitcoinBrowserWallet` instance.

```tsx
const wallet = await BitcoinBrowserWallet.enable("xverse");
```

### Persist session across page reloads

Pass `{ persist: true }` to save the wallet name in `localStorage`. On subsequent page loads the wallet reconnects **silently** (no popup) when `hasPersistedSession()` returns `true`.

```tsx
// First visit — shows popup
const wallet = await BitcoinBrowserWallet.enable("xverse", { persist: true });

// On every subsequent page load — silent reconnect
if (BitcoinBrowserWallet.hasPersistedSession()) {
  const wallet = await BitcoinBrowserWallet.enable("xverse", { persist: true });
}
```

### Restore silently

`restore()` is a one-liner alternative: it reads the persisted name and reconnects, returning `null` if nothing was saved or the extension is no longer available.

```tsx
const wallet = await BitcoinBrowserWallet.restore();
if (wallet) {
  // already connected — no popup shown
}
```

### Disconnect

Clears the persisted session so `restore()` returns `null` on the next load.

```tsx
wallet.disconnect();
```

***

## Get Network

```tsx
const network = await wallet.getNetwork();
// "Mainnet" | "Testnet4"
```

***

## Get Addresses

Returns the wallet's addresses for the requested purpose(s). Each address includes its public key, address type, and derivation purpose.

```tsx
import { AddressPurpose } from "@meshsdk/wallet";

const addresses = await wallet.getAddresses([
  AddressPurpose.Payment,   // P2WPKH (BIP-84)
  AddressPurpose.Ordinals,  // P2TR   (BIP-86)
]);
```

Example response:

```json
[
  {
    "address": "bc1q...",
    "publicKey": "02abc...",
    "purpose": "payment",
    "addressType": "p2wpkh",
    "walletType": "software"
  },
  {
    "address": "bc1p...",
    "publicKey": "02def...",
    "purpose": "ordinals",
    "addressType": "p2tr",
    "walletType": "software"
  }
]
```

***

## Get Accounts

Same as `getAddresses` but returns `BitcoinAccount` objects (identical shape, different semantic role — used when you need the full account record).

```tsx
const accounts = await wallet.getAccounts([AddressPurpose.Payment]);
```

***

## Get Balance

Returns confirmed, unconfirmed, and total balances **in satoshis** as strings.

```tsx
const balance = await wallet.getBalance();
// { confirmed: "100000", unconfirmed: "5000", total: "105000" }
```

***

## Fetch UTXOs

Returns all unspent outputs for the requested address purposes, each annotated with the owning address and purpose.

```tsx
const utxos = await wallet.fetchUTXOs([AddressPurpose.Payment]);
```

Example response:

```json
[
  {
    "txid": "abc123...",
    "vout": 0,
    "value": 50000,
    "address": "bc1q...",
    "purpose": "payment",
    "status": { "confirmed": true, "block_height": 840000 }
  }
]
```

***

## Get Transaction History

Returns paginated transaction history across the requested purposes, sorted newest-first (unconfirmed transactions appear first).

```tsx
const txs = await wallet.getTransactionHistory({
  purposes: [AddressPurpose.Payment],
  lastSeenTxid: "abc123...", // optional — for pagination
});
```

***

## Sign Message

Signs an arbitrary message using the [BIP-137](https://github.com/bitcoin/bips/blob/master/bip-0137.mediawiki) ECDSA compact format (65 bytes, base64-encoded).

```tsx
import { MessageSigningProtocols } from "@meshsdk/wallet";

const result = await wallet.signMessage(
  "bc1q...",           // address to sign with
  "Hello, Bitcoin!",  // message
  MessageSigningProtocols.ECDSA,
);

// {
//   signature: "H...(base64)",
//   messageHash: "...(hex)",
//   address: "bc1q...",
//   protocol: "ECDSA"
// }
```

***

## Verify Message

Verifies a BIP-137 ECDSA signature locally (no extension call). Returns a result object with `.valid`, an optional `.recoveredPublicKey`, and an optional `.reason` string on failure.

```tsx
const result = await wallet.verifyMessage(
  "bc1q...",
  "Hello, Bitcoin!",
  signatureBase64,
);

if (result.valid) {
  console.log("Signed by:", result.recoveredPublicKey);
} else {
  console.log("Invalid:", result.reason);
}
```

> Non-ECDSA / BIP-322 signatures (e.g. Taproot Schnorr) return `{ valid: false, reason: "..." }` rather than throwing.

***

## Sign Transfer

Prompts the user to sign and broadcast a transfer to one or more recipients in a single step.
Returns the broadcast **txid** (64-char hex).

```tsx
const txid = await wallet.signTransfer([
  { address: "bc1q...", amount: 10_000 }, // amount in satoshis
]);
// "a1b2c3..." (64-char txid)
```

Multi-recipient:

```tsx
const txid = await wallet.signTransfer([
  { address: "bc1q...", amount: 10_000 },
  { address: "bc1p...", amount: 25_000 },
]);
```

***

## Sign PSBT

Signs an externally-constructed Partially Signed Bitcoin Transaction (PSBT). The PSBT must be provided as a base64-encoded string.

```tsx
const result = await wallet.signPsbt({
  psbt: base64Psbt,
  signInputs: {
    "bc1q...": [0], // address → input indices to sign
  },
  broadcast: false, // set true to sign and broadcast in one call
});
// returns signed PSBT (base64) when broadcast=false
// returns txid when broadcast=true
```


# Bitcoin Headless Wallet
URL: /apis/wallets/bitcoin/headless-wallet

A fully self-custodial HD Bitcoin wallet for Node.js and browser environments — no extension required.

***

title: "Bitcoin Headless Wallet"
description: "A fully self-custodial HD Bitcoin wallet for Node.js and browser environments — no extension required."
icon: WalletIcon
----------------

`BitcoinHeadlessWallet` is a software HD wallet built on BIP-39 / BIP-32. It derives addresses, signs messages and transactions, fetches chain data, and broadcasts — all without requiring any browser extension.

It supports both **testnet** and **mainnet**, and can be initialized from a mnemonic phrase, BIP-39 entropy, or a raw private key.

> **Provider note** — Chain operations (`getBalance`, `fetchUTXOs`, `signTransfer`, `signPsbt` with `broadcast: true`) require an `IBitcoinProvider`. Ready-to-use implementations are available in `@meshsdk/provider`: `BlockstreamBitcoinProvider` (no API key) and `MaestroBitcoinProvider` (enterprise, API key required). See [Provider Setup](#provider-setup) below.

***

## Initialize Wallet

### From Mnemonic

The most common initialization path. Derives a BIP-84 (P2WPKH) and BIP-86 (P2TR) key tree from the phrase.

```ts
import { BitcoinHeadlessWallet } from "@meshsdk/wallet";
import { BlockstreamBitcoinProvider } from "@meshsdk/provider";

const provider = new BlockstreamBitcoinProvider("testnet"); // "mainnet" | "testnet"

const wallet = await BitcoinHeadlessWallet.fromMnemonic({
  network:  "Testnet4",   // "Mainnet" | "Testnet4"
  mnemonic: ["word1", "word2", "..."], // 12 or 24 BIP-39 words
  provider,               // optional — omit for offline / sign-only usage
  account:  0,            // optional BIP-32 account index (default 0)
  password: "",           // optional BIP-39 passphrase (default "")
});
```

### From Entropy

If you store entropy rather than the phrase itself:

```ts
const wallet = await BitcoinHeadlessWallet.fromEntropy({
  network:  "Mainnet",
  entropy:  "a1b2c3d4...", // 16–32 byte hex string (BIP-39 entropy)
  provider,
});
```

### From Private Key

For importing a single key (useful for testing or hardware-derived keys). Accepts either a 32-byte hex string or a WIF-encoded key.

```ts
// 32-byte hex
const wallet = await BitcoinHeadlessWallet.fromPrivateKey({
  network:    "Testnet4",
  privateKey: "0123456789abcdef...", // 64 hex chars
  provider,
});

// WIF
const wallet = await BitcoinHeadlessWallet.fromPrivateKey({
  network:    "Mainnet",
  privateKey: "5Kb8kLf9zgWQnogidDA76MzPL6TsZZY36hWXMssSzNydYXYB9KF",
  provider,
});
```

***

## Get Network

```ts
const network = await wallet.getNetwork();
// "Mainnet" | "Testnet4"
```

***

## Get Addresses

Returns the default receive addresses (index 0, external chain) for the requested purposes.

```ts
import { AddressPurpose } from "@meshsdk/wallet";

const addresses = await wallet.getAddresses([
  AddressPurpose.Payment,   // P2WPKH — BIP-84 path m/84'/0'/0'/0/0
  AddressPurpose.Ordinals,  // P2TR   — BIP-86 path m/86'/0'/0'/0/0
]);
```

Example response:

```json
[
  {
    "address": "tb1q...",
    "publicKey": "02abc...",
    "purpose": "payment",
    "addressType": "p2wpkh",
    "walletType": "software"
  }
]
```

***

## Get Accounts

Identical to `getAddresses` but returns `BitcoinAccount` objects.

```ts
const accounts = await wallet.getAccounts([AddressPurpose.Payment]);
```

***

## Get Balance

Sums confirmed and unconfirmed balances across all payment addresses. Returns values **in satoshis** as strings.

*Requires a provider.*

```ts
const balance = await wallet.getBalance();
// { confirmed: "100000", unconfirmed: "5000", total: "105000" }
```

***

## Fetch UTXOs

Returns UTXOs for all addresses under the requested purposes.

*Requires a provider.*

```ts
const utxos = await wallet.fetchUTXOs([AddressPurpose.Payment]);
// restrict to payment addresses only when building a send transaction
```

Each UTXO is annotated with `address` and `purpose`:

```json
[
  {
    "txid": "abc123...",
    "vout": 0,
    "value": 50000,
    "address": "tb1q...",
    "purpose": "payment",
    "status": { "confirmed": true, "block_height": 840000 }
  }
]
```

***

## Get Transaction History

Returns transactions across the requested purposes, sorted newest-first.

*Requires a provider.*

```ts
const txs = await wallet.getTransactionHistory({
  purposes:     [AddressPurpose.Payment],
  lastSeenTxid: "abc123...", // optional — for pagination
});
```

***

## Sign Message

Signs a message using [BIP-137](https://github.com/bitcoin/bips/blob/master/bip-0137.mediawiki) ECDSA compact format (deterministic via RFC 6979).
The signature is 65 bytes, base64-encoded.

```ts
import { MessageSigningProtocols } from "@meshsdk/wallet";

const result = await wallet.signMessage(
  "tb1q...",            // must be a managed address
  "Hello, Bitcoin!",
  MessageSigningProtocols.ECDSA,
);

// {
//   signature:   "H...(base64)",
//   messageHash: "...(hex)",
//   address:     "tb1q...",
//   protocol:    "ECDSA"
// }
```

> BIP-322 (Schnorr / Taproot) is not yet supported and will throw `UnsupportedProtocol`.

***

## Verify Message

Verifies a BIP-137 ECDSA signature locally. Returns a rich result object — no network call required.

```ts
const result = await wallet.verifyMessage(
  "tb1q...",
  "Hello, Bitcoin!",
  signatureBase64,
);

if (result.valid) {
  console.log("Signer public key:", result.recoveredPublicKey);
} else {
  console.log("Failed:", result.reason);
}
```

***

## Sign Transfer

Selects UTXOs, builds a PSBT, signs, and broadcasts in one call. Returns the broadcast **txid**.

*Requires a provider.*

```ts
const txid = await wallet.signTransfer([
  { address: "tb1q...", amount: 10_000 }, // satoshis
]);
// "a1b2c3..." (64-char txid)
```

Multi-recipient:

```ts
const txid = await wallet.signTransfer([
  { address: "tb1q...", amount: 10_000 },
  { address: "tb1p...", amount: 25_000 },
]);
```

**UTXO selection strategy:** largest-first.
**Fee rate:** fetched live from the provider (6-block target); falls back to 2 sat/vB if the fee API is unavailable.
**RBF:** all inputs use sequence `0xFFFFFFFD`.
**Dust:** change outputs below 546 sats are dropped.

***

## Sign PSBT

Signs an externally-constructed PSBT. Accepts a base64-encoded PSBT string. Useful for integrating with external transaction builders (e.g. `@scure/btc-signer`, `bitcoinjs-lib`).

```ts
const result = await wallet.signPsbt({
  psbt:      base64Psbt,
  broadcast: false, // true = sign + broadcast, returns txid
});
// returns signed PSBT (base64) when broadcast=false
// returns txid when broadcast=true
```

You can also specify which inputs to sign when not all inputs belong to this wallet:

```ts
const result = await wallet.signPsbt({
  psbt:       base64Psbt,
  signInputs: { "tb1q...": [0, 2] }, // address → input indices
  broadcast:  true,
});
```

***

## Address Derivation (HD-only)

These methods are available on `BitcoinHeadlessWallet` and are **not** available on browser extension wallets.

### Derive a Range of Addresses

```ts
const addresses = wallet.getAddressesByPurpose(
  AddressPurpose.Payment,
  0,   // start index (default 0)
  20,  // count (default 20)
  0,   // chain: 0 = external/receive, 1 = internal/change
);
// DerivedBitcoinAddress[] — includes derivationPath, change, index
```

### Find a Managed Address

Scans the derivation path to locate an address. Returns the full `DerivedBitcoinAddress` (with `change` and `index`) or `undefined`.

```ts
const found = wallet.findManagedAddress(
  "tb1q...",            // address to search for
  AddressPurpose.Payment,
  20,                   // maxGap (default 20)
);
```

***

## Export Extended Public Keys

Export account-level public keys for watch-only wallets or third-party tools.

```ts
// BIP-84 P2WPKH account key
// returns xpub (mainnet) or tpub (testnet)
const xpub = wallet.getAccountXpub();

// BIP-86 P2TR / Taproot account key
// returns xpub (mainnet) or tpub (testnet)
const taprootXpub = wallet.getTaprootXpub();

// BIP-84 with zpub/vpub version prefix
// returns zpub (mainnet) or vpub (testnet)
const zpub = wallet.getAccountZpub();
```

***

## Provider Setup

`@meshsdk/wallet` exports the `IBitcoinProvider` interface.
`@meshsdk/provider` ships two ready-to-use implementations:

| Provider                     | Package             | API key     | Network           |
| ---------------------------- | ------------------- | ----------- | ----------------- |
| `BlockstreamBitcoinProvider` | `@meshsdk/provider` | None (free) | mainnet / testnet |
| `MaestroBitcoinProvider`     | `@meshsdk/provider` | Required    | mainnet / testnet |

Both implement `IBitcoinProvider` and are plug-and-play with `BitcoinHeadlessWallet`.

### Blockstream (no API key)

Uses the public [Blockstream Esplora](https://github.com/Blockstream/esplora/blob/master/API.md) API — ideal for development, testing, and low-volume production.

```ts
import { BitcoinHeadlessWallet } from "@meshsdk/wallet";
import { BlockstreamBitcoinProvider } from "@meshsdk/provider";

const provider = new BlockstreamBitcoinProvider("testnet"); // "mainnet" | "testnet"

const wallet = await BitcoinHeadlessWallet.fromMnemonic({
  network:  "Testnet4",
  mnemonic: ["word1", "word2", "..."],
  provider,
});

const balance = await wallet.getBalance();
// { confirmed: "100000", unconfirmed: "0", total: "100000" }
```

### Maestro (API key required)

Uses [Maestro's](https://docs.gomaestro.org/bitcoin) Esplora-compatible Bitcoin API — enterprise-grade, higher rate limits, mempool monitoring.

```ts
import { BitcoinHeadlessWallet } from "@meshsdk/wallet";
import { MaestroBitcoinProvider } from "@meshsdk/provider";

const provider = new MaestroBitcoinProvider({
  apiKey:  "your-maestro-api-key",
  network: "mainnet", // "mainnet" | "testnet"
});

const wallet = await BitcoinHeadlessWallet.fromMnemonic({
  network:  "Mainnet",
  mnemonic: ["word1", "word2", "..."],
  provider,
});

const txid = await wallet.signTransfer([
  { address: "bc1q...", amount: 10_000 },
]);
```


# Bitcoin Wallets
URL: /apis/wallets/bitcoin

APIs for connecting to Bitcoin browser extension wallets and running self-custodial HD wallets in Node.js or the browser.

***

title: "Bitcoin Wallets"
description: "APIs for connecting to Bitcoin browser extension wallets and running self-custodial HD wallets in Node.js or the browser."
icon: BanknotesIcon
full: true
----------

import Link from "next/link";
import { Card, CardDescription, CardTitle } from "@/components/ui/card";

<div className="grid md:grid-cols-2 gap-6 items-stretch">
  <Link href="/apis/wallets/bitcoin/browser-wallet" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Bitcoin Browser Wallet</CardTitle>

      <CardDescription>
        Connect to Xverse and other Bitcoin browser extensions via a unified Sats Connect API.
      </CardDescription>
    </Card>
  </Link>

  <Link href="/apis/wallets/bitcoin/headless-wallet" className="no-underline">
    <Card className="h-full text-center hover:border-primary/50 transition-colors px-4 py-8">
      <CardTitle className="font-heading">Bitcoin Headless Wallet</CardTitle>

      <CardDescription>
        A fully self-custodial BIP-39 HD wallet for Node.js and browser — no extension required.
      </CardDescription>
    </Card>
  </Link>
</div>