cardano-cli-plutus-scripts

cardano-cli-plutus-scripts

**这是一项指导技能。**提供模板和说明。执行操作请使用 cardano-cli-plutus-scripts-operator。

使用场景

• 学习 Plutus 脚本交易模式
• 了解 datum、redeemer 和抵押品
• 获取脚本交互模板

操作规则（必须遵守）

• 确认网络和脚本版本（V2/V3）
• 绝不执行操作——仅提供模板
• 始终包含抵押品处理
• 使用最新的协议参数

Docker 后备模式

如果本地未安装 cardano-cli，请使用此技能文件夹中的包装脚本，通过 Docker 运行容器内的 cardano-cli（Cardano 节点容器镜像包含 CLI）。

chmod +x {baseDir}/scripts/cardano-cli.sh
{baseDir}/scripts/cardano-cli.sh version

注意：

• 包装脚本会将当前目录挂载到容器中的 /work，因此 pparams.json、tx.body、datum.json 等文件可以正常使用。
• 如果你有本地节点套接字，请在运行前设置 CARDANO_NODE_SOCKET_PATH，以便 query 命令正常工作。
• 使用 CARDANO_DOCKER_IMAGE=ghcr.io/intersectmbo/cardano-node:<tag> 覆盖镜像。

核心概念

脚本版本

• V1（Alonzo）：旧版，功能有限
• V2（Babbage）：引用脚本、内联 datum
• V3（Conway）：治理、简化的接口

Datum 处理

• 内联 datum：与 UTxO 一起存储在链上
• Datum 哈希：链上仅存储哈希，花费时需提供完整 datum
• 无 datum：适用于部分 V3 脚本

抵押品

• 所有 Plutus 脚本交易都必须提供
• 必须是仅包含 ADA 的 UTxO
• 脚本意外失败时将被没收
• 通常 1-5 ADA 就足够

工作流模板

将资金锁定到脚本地址

# 1. Derive script address
cardano-cli conway address build \
  --payment-script-file script.plutus \
  --testnet-magic 1 \
  --out-file script.addr

# 2. Create datum file
echo '{"constructor": 0, "fields": []}' > datum.json

# 3. Lock with inline datum
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <utxo>#<index> \
  --tx-out "$(cat script.addr)+5000000" \
  --tx-out-inline-datum-file datum.json \
  --change-address <payment-addr> \
  --out-file tx.unsigned

# Sign and submit

从脚本花费

# 1. Create redeemer
echo '{"constructor": 0, "fields": []}' > redeemer.json

# 2. Build script spend
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <script-utxo>#<index> \
  --tx-in-script-file script.plutus \
  --tx-in-inline-datum-present \
  --tx-in-redeemer-file redeemer.json \
  --tx-in-collateral <collateral-utxo>#<index> \
  --tx-out <recipient>+<amount> \
  --change-address <payment-addr> \
  --out-file tx.unsigned

# Sign (with collateral key) and submit

使用引用脚本

# Script already on-chain at reference UTxO
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <script-utxo>#<index> \
  --spending-tx-in-reference <ref-script-utxo>#<index> \
  --spending-plutus-script-v2 \
  --spending-reference-tx-in-inline-datum-present \
  --spending-reference-tx-in-redeemer-file redeemer.json \
  --tx-in-collateral <collateral>#<index> \
  --tx-out <recipient>+<amount> \
  --change-address <payment-addr> \
  --out-file tx.unsigned

示例

示例：花费简单的验证器

用户请求：“从我的始终成功脚本中花费”

回复：

# === Spend from Always-Succeeds Script ===

SCRIPT_ADDR=$(cat script.addr)
PAYMENT_ADDR=$(cat base.addr)

# 1. Query script UTxO
cardano-cli conway query utxo \
  --address $SCRIPT_ADDR \
  --testnet-magic 1
# Note the UTxO hash and index

# 2. Query payment UTxOs (for collateral)
cardano-cli conway query utxo \
  --address $PAYMENT_ADDR \
  --testnet-magic 1
# Select ADA-only UTxO for collateral

# 3. Create redeemer (for always-succeeds, can be unit)
echo '{"constructor": 0, "fields": []}' > redeemer.json

# 4. Build transaction
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <script-utxo>#0 \
  --tx-in-script-file always-succeeds.plutus \
  --tx-in-inline-datum-present \
  --tx-in-redeemer-file redeemer.json \
  --tx-in-collateral <collateral-utxo>#0 \
  --tx-out "$PAYMENT_ADDR+4500000" \
  --change-address $PAYMENT_ADDR \
  --out-file tx.unsigned

# 5. Sign and submit (use operator skill)

调试

计算执行成本

cardano-cli conway transaction build \
  ... \
  --calculate-plutus-script-cost costs.json

cat costs.json | jq .

常见故障

• ExUnitsTooBig：脚本超出执行预算
• CollateralNotFound：缺少或抵押品无效
• DatumMismatch：提供的 datum 与哈希不匹配
• ScriptFailure：验证器返回 False

安全 / 密钥处理

• 先在 preprod/preview 上测试脚本
• 使用最少的抵押品
• Datum/redeemer 都是公开的——不要放入秘密
• 重新构建后验证脚本哈希

参考资料

• shared/PRINCIPLES.md
• cardano-cli-plutus-scripts-operator（用于执行）
• aiken-smart-contracts（用于编写验证器）