mesh-transaction

Mesh SDK 交易技能

使用 @meshsdk/transaction 中的 MeshTxBuilder，借助 AI 构建 Cardano 交易。

包信息

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

快速参考

任务	方法链
发送 ADA	txIn() -> txOut() -> changeAddress() -> complete()
铸造代币（Plutus）	mintPlutusScriptV3() -> mint() -> mintingScript() -> mintRedeemerValue() -> ...
铸造代币（原生）	mint() -> mintingScript() -> ...
脚本花费	spendingPlutusScriptV3() -> txIn() -> txInScript() -> txInDatumValue() -> txInRedeemerValue() -> ...
质押委托	delegateStakeCertificate(rewardAddress, poolId)
提取奖励	withdrawal(rewardAddress, coin) -> withdrawalScript() -> withdrawalRedeemerValue()
治理投票	vote(voter, govActionId, votingProcedure)
DRep 注册	drepRegistrationCertificate(drepId, anchor?, deposit?)

构造函数选项

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
});

完成方法

方法	异步	已平衡	使用场景
complete()	是	是	生产环境——自动选择币、计算费用
completeSync()	否	否	测试——需要手动提供输入和费用
completeUnbalanced()	否	否	部分构建，以便检查
completeSigning()	否	不适用	在 complete() 后添加签名

文件

• TRANSACTION.md - 完整的 API 参考
• PATTERNS.md - 常见交易方案
• AIKEN-MAPPING.md - Aiken 智能合约类型 → MeshTxBuilder 映射
• TROUBLESHOOTING.md - 错误解决方案

核心概念

流式 API

所有方法都会返回 this，以便链式调用：

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

脚本版本

选择与脚本 Plutus 版本相匹配的版本：

版本	时代	使用场景
V1	Alonzo	仅用于旧版脚本
V2	Babbage	用于现有的 Babbage 时代脚本
V3	Conway	用于新脚本（当前时代，默认选择）

LanguageVersion 类型 = "V1" | "V2" | "V3"

每种脚本上下文都有 两种等效的调用方式——静态快捷方法和动态版本：

上下文	静态快捷方法	动态版本
花费	spendingPlutusScriptV3()	spendingPlutusScript("V3")
铸造	mintPlutusScriptV3()	mintPlutusScript("V3")
提取	withdrawalPlutusScriptV3()	withdrawalPlutusScript("V3")
投票	votePlutusScriptV3()	votePlutusScript("V3")

新的 Conway 时代脚本默认使用 V3。 只有针对特定 Plutus 版本编译的脚本才使用 V2/V1。

数据类型（Datum 和 Redeemer 格式）

Datum 和 Redeemer 值可通过 type 参数接受三种格式：

"Mesh"（默认）——使用 alternative，不要使用 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 格式，使用 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"——预序列化十六进制数据：

.txOutInlineDatumValue("d8799f182aff", "CBOR")

真实 MeshJS 合约中的惯例：

场景	格式	辅助函数	类型参数
Datum（始终如此）	JSON	conStr0()、integer()、pubKeyAddress()	"JSON"（显式指定）
Redeemer（空，无字段）	Mesh	mConStr0([])、mConStr1([])	省略（默认值为 "Mesh"）
Redeemer（包含字段）	JSON	conStr0() + 类型化包装器	"JSON" + DEFAULT_REDEEMER_BUDGET
Redeemer（未使用／Data 类型）	不适用	""（空字符串）	省略

注意： 某些合约对不带类型参数的简单 Datum 使用 Mesh 格式（mConStr0）。两种格式都可用——关键规则是 类型参数必须与格式相匹配。

完整的 Aiken 类型 → Mesh 数据映射，请参阅 AIKEN-MAPPING.md。

重要： 如果省略类型参数，默认值为 "Mesh"。未指定 "JSON" 就使用 { constructor: 0, ... } 会导致错误。

引用脚本

使用 *TxInReference() 方法引用链上存储的脚本，而不是将它们包含在交易中（可减少交易大小和费用）。

重要说明

1. 必须设置找零地址 - 不调用 changeAddress()，complete() 会失败
2. 必须设置抵押品 - 脚本交易需要 txInCollateral()
3. 调用顺序很重要 - 对于脚本输入，先调用 spendingPlutusScriptV3()，再调用 txIn()
4. 币选择 - 通过 selectUtxosFrom() 提供 UTxO，以便自动选择
5. Datum 格式 - 默认的 "Mesh" 类型使用 { alternative: 0 }，而不是 { constructor: 0 }。对于 { constructor: 0 }（cardano-cli 格式），请使用 "JSON" 类型
6. 脚本版本 - 对于 Conway 时代的脚本，默认使用 V3。请确保与编译脚本时使用的 Plutus 版本一致