Mesh SDK Transaction Skill

AI-assisted Cardano transaction building using MeshTxBuilder from @meshsdk/transaction.

Package Info

npm install @meshsdk/transaction
# or
npm install @meshsdk/core  # includes transaction + wallet + provider

Quick Reference

Task	Method Chain
Send ADA	`txIn() -> txOut() -> changeAddress() -> complete()`
Mint tokens (Plutus)	`mintPlutusScriptV3() -> mint() -> mintingScript() -> mintRedeemerValue() -> ...`
Mint tokens (Native)	`mint() -> mintingScript() -> ...`
Script spending	`spendingPlutusScriptV3() -> txIn() -> txInScript() -> txInDatumValue() -> txInRedeemerValue() -> ...`
Stake delegation	`delegateStakeCertificate(rewardAddress, poolId)`
Withdraw rewards	`withdrawal(rewardAddress, coin) -> withdrawalScript() -> withdrawalRedeemerValue()`
Governance vote	`vote(voter, govActionId, votingProcedure)`
DRep registration	`drepRegistrationCertificate(drepId, anchor?, deposit?)`

Constructor Options

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

const txBuilder = new MeshTxBuilder({
  fetcher?: IFetcher,      // For querying UTxOs (e.g., BlockfrostProvider)
  submitter?: ISubmitter,  // For submitting transactions
  evaluator?: IEvaluator,  // For script execution cost estimation
  serializer?: IMeshTxSerializer,  // Custom serializer
  selector?: IInputSelector,       // Custom coin selection
  isHydra?: boolean,       // Hydra L2 mode (zero fees)
  params?: Partial<Protocol>,  // Custom protocol parameters
  verbose?: boolean,       // Enable logging
});

Completion Methods

Method	Async	Balanced	Use Case
`complete()`	Yes	Yes	Production - auto coin selection, fee calculation
`completeSync()`	No	No	Testing - requires manual inputs/fee
`completeUnbalanced()`	No	No	Partial build for inspection
`completeSigning()`	No	N/A	Add signatures after complete()

Files

TRANSACTION.md - Complete API reference
PATTERNS.md - Common transaction recipes
AIKEN-MAPPING.md - Aiken smart contract type → MeshTxBuilder mapping
TROUBLESHOOTING.md - Error solutions

Key Concepts

Fluent API

All methods return this for chaining:

txBuilder
  .txIn(hash, index)
  .txOut(address, amount)
  .changeAddress(addr)
  .complete();

Script Versions

Choose the version matching the script's Plutus version:

Version	Era	When to Use
V1	Alonzo	Legacy scripts only
V2	Babbage	Existing Babbage-era scripts
V3	Conway	New scripts (current era, default choice)

LanguageVersion type = "V1" | "V2" | "V3"

Each script context has two equivalent calling styles — static shortcuts and dynamic version:

Context	Static Shortcut	Dynamic Version
Spending	`spendingPlutusScriptV3()`	`spendingPlutusScript("V3")`
Minting	`mintPlutusScriptV3()`	`mintPlutusScript("V3")`
Withdrawal	`withdrawalPlutusScriptV3()`	`withdrawalPlutusScript("V3")`
Voting	`votePlutusScriptV3()`	`votePlutusScript("V3")`

Default to V3 for new Conway-era scripts. Only use V2/V1 for scripts compiled against those specific Plutus versions.

Data Types (Datum & Redeemer Formats)

Datum and redeemer values accept three formats via the type parameter:

"Mesh" (default) — Use alternative, NOT constructor:

import { mConStr0, mConStr1 } from '@meshsdk/common';

// Mesh Data type uses "alternative" for ConstrPlutusData
const datum = { alternative: 0, fields: [42, "deadbeef"] };
// Or use helper: mConStr0([42, "deadbeef"])
// mConStr1([...]) for constructor index 1, etc.

.txOutInlineDatumValue(datum)           // default type is "Mesh"
.txOutInlineDatumValue(datum, "Mesh")   // explicit

"JSON" — Cardano-CLI format, uses constructor:

import { conStr0, integer, byteString, pubKeyAddress } from '@meshsdk/common';

// JSON format uses "constructor" with typed field wrappers
const datum = conStr0([integer(42), byteString("deadbeef")]);
// Equivalent to: { constructor: 0, fields: [{ int: 42 }, { bytes: "deadbeef" }] }

.txOutInlineDatumValue(datum, "JSON")   // MUST specify "JSON"

"CBOR" — Pre-serialized hex:

.txOutInlineDatumValue("d8799f182aff", "CBOR")

Convention from real MeshJS contracts:

Scenario	Format	Helpers	Type Parameter
Datums (always)	JSON	`conStr0()`, `integer()`, `pubKeyAddress()`	`"JSON"` (explicit)
Redeemers (empty, no fields)	Mesh	`mConStr0([])`, `mConStr1([])`	omit (default `"Mesh"`)
Redeemers (with fields)	JSON	`conStr0()` + typed wrappers	`"JSON"` + `DEFAULT_REDEEMER_BUDGET`
Redeemers (unused/`Data` type)	N/A	`""` (empty string)	omit

Note: Some contracts use Mesh format (mConStr0) for simple datums without a type parameter. Both formats work — the critical rule is matching the type parameter to the format.

See AIKEN-MAPPING.md for complete Aiken type → Mesh data mapping.

CRITICAL: If you omit the type parameter, the default is "Mesh". Using { constructor: 0, ... } without specifying "JSON" will cause errors.

Reference Scripts

Use *TxInReference() methods to reference scripts stored on-chain instead of including them in the transaction (reduces tx size/fees).

Important Notes

Change address required - complete() fails without changeAddress()
Collateral required - Script transactions need txInCollateral()
Order matters - Call spendingPlutusScriptV3() BEFORE txIn() for script inputs
Coin selection - Provide UTxOs via selectUtxosFrom() for auto-selection
Datum format - Default "Mesh" type uses { alternative: 0 }, NOT { constructor: 0 }. Use "JSON" type for { constructor: 0 } (cardano-cli format)
Script version - Default to V3 for Conway-era scripts. Match the Plutus version the script was compiled with

mesh-transaction