cardano-cli-plutus-scripts

This is a guidance skill. Provides templates and explanations. For execution, use
cardano-cli-plutus-scripts-operator
.

这是一个指南类技能。提供模板和解释。执行操作请使用
cardano-cli-plutus-scripts-operator
。

When to use

适用场景

Learning Plutus script transaction patterns
Understanding datums, redeemers, collateral
Getting templates for script interactions

学习Plutus脚本交易模式
理解datum、redeemer、collateral
获取脚本交互模板

Operating rules (must follow)

操作规则（必须遵守）

Confirm network and script version (V2/V3)
Never execute—only provide templates
Always include collateral handling
Use fresh protocol parameters

确认网络和脚本版本（V2/V3）
绝不执行——仅提供模板
必须包含collateral处理逻辑
使用最新的协议参数

Docker fallback mode

Docker备用模式

If

cardano-cli

is not installed locally, use the wrapper script in this skill folder to run cardano-cli inside Docker (the Cardano node container images include the CLI).

bash

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

Notes:

The wrapper mounts your current directory into the container as
```
/work
```
so files like
```
pparams.json
```
,
```
tx.body
```
,
```
datum.json
```
work normally.
If you have a local node socket, set
```
CARDANO_NODE_SOCKET_PATH
```
before running so
```
query
```
commands work.

Override the image with

CARDANO_DOCKER_IMAGE=ghcr.io/intersectmbo/cardano-node:<tag>

.

如果本地未安装

cardano-cli

，可使用本技能文件夹中的包装脚本在Docker内运行cardano-cli（Cardano节点容器镜像已包含该CLI工具）。

bash

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>

覆盖默认镜像。

Key concepts

核心概念

Script versions

脚本版本

V1 (Alonzo): Legacy, limited features
V2 (Babbage): Reference scripts, inline datums
V3 (Conway): Governance, simplified interface

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

Datum handling

Datum处理方式

Inline datum: Stored on-chain with UTxO
Datum hash: Only hash on-chain, provide full datum when spending
No datum: For some V3 scripts

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

Collateral

Required for all Plutus script transactions
Must be ADA-only UTxO
Forfeit if script fails unexpectedly
Typically 1-5 ADA sufficient

所有Plutus脚本交易都需要collateral
必须是仅包含ADA的UTxO
若脚本意外执行失败，collateral将被没收
通常1-5 ADA即可满足需求

Workflow templates

工作流模板

Lock funds at script address

将资金锁定到脚本地址

bash

undefined

bash

undefined

1. Derive script address

1. 生成脚本地址

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

2. Create datum file

2. 创建datum文件

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

3. Lock with inline datum

3. 使用内联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

签名并提交（请使用operator工具）

undefined

undefined

Spend from script

从脚本地址花费资金

bash

undefined

bash

undefined

1. Create redeemer

1. 创建redeemer文件

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

2. Build script spend

2. 构建脚本花费交易

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

签名（需使用抵押资产密钥）并提交（请使用operator工具）

undefined

undefined

With reference script

使用引用脚本

bash

undefined

bash

undefined

Script already on-chain at reference UTxO

脚本已存储在链上的引用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

undefined

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

undefined

Examples

示例

Example: Simple validator spend

示例：简单验证器花费

User request: "Spend from my always-succeeds script"

Response:

bash

undefined

用户请求： "从我的始终成功脚本中花费资金"

响应：

bash

undefined

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

=== 从始终成功脚本中花费资金 ===

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

1. Query script UTxO

1. 查询脚本地址的UTxO

cardano-cli conway query utxo
--address $SCRIPT_ADDR
--testnet-magic 1

Note the UTxO hash and index

记录UTxO哈希和索引

2. Query payment UTxOs (for collateral)

2. 查询支付地址的UTxO（用于抵押）

cardano-cli conway query utxo
--address $PAYMENT_ADDR
--testnet-magic 1

Select ADA-only UTxO for collateral

选择仅含ADA的UTxO作为抵押资产

3. Create redeemer (for always-succeeds, can be unit)

3. 创建redeemer（对于始终成功脚本，可使用空结构）

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

4. Build transaction

4. 构建交易

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)

5. 签名并提交（请使用operator工具）

undefined

undefined

Debugging

调试

Calculate execution costs

计算执行成本

bash

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

cat costs.json | jq .

bash

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

cat costs.json | jq .

Common failures

常见失败原因

ExUnitsTooBig: Script exceeds execution budget
CollateralNotFound: Missing or invalid collateral
DatumMismatch: Provided datum doesn't match hash
ScriptFailure: Validator returned False

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

Safety / key handling

安全/密钥处理

Test scripts on preprod/preview first
Use minimal collateral
Datum/redeemer are public—no secrets
Verify script hash after rebuilds

先在预生产/预览网络测试脚本
使用最少的抵押资产
Datum/redeemer是公开的——不要包含敏感信息
重新编译脚本后验证脚本哈希

References

参考资料

```
shared/PRINCIPLES.md
```
```
cardano-cli-plutus-scripts-operator
```
(for execution)
```
aiken-smart-contracts
```
(for writing validators)

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

cardano-cli-plutus-scripts

Original

Translation

cardano-cli-plutus-scripts

cardano-cli-plutus-scripts

When to use

适用场景

Operating rules (must follow)

操作规则（必须遵守）

Docker fallback mode

Docker备用模式

Key concepts

核心概念

Script versions

脚本版本

Datum handling

Datum处理方式

Collateral

Collateral

Workflow templates

工作流模板

Lock funds at script address

将资金锁定到脚本地址

1. Derive script address

1. 生成脚本地址

2. Create datum file

2. 创建datum文件

3. Lock with inline datum

3. 使用内联datum锁定资金

Sign and submit

签名并提交（请使用operator工具）

Spend from script

从脚本地址花费资金

1. Create redeemer

1. 创建redeemer文件

2. Build script spend

2. 构建脚本花费交易

Sign (with collateral key) and submit

签名（需使用抵押资产密钥）并提交（请使用operator工具）

With reference script

使用引用脚本

Script already on-chain at reference UTxO

脚本已存储在链上的引用UTxO中

Examples

示例

Example: Simple validator spend

示例：简单验证器花费

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

=== 从始终成功脚本中花费资金 ===

1. Query script UTxO

1. 查询脚本地址的UTxO

Note the UTxO hash and index

记录UTxO哈希和索引

2. Query payment UTxOs (for collateral)

2. 查询支付地址的UTxO（用于抵押）

Select ADA-only UTxO for collateral

选择仅含ADA的UTxO作为抵押资产

3. Create redeemer (for always-succeeds, can be unit)

3. 创建redeemer（对于始终成功脚本，可使用空结构）

4. Build transaction

4. 构建交易

5. Sign and submit (use operator skill)

5. 签名并提交（请使用operator工具）

Debugging

调试

Calculate execution costs

计算执行成本

Common failures

常见失败原因

Safety / key handling

安全/密钥处理

References

参考资料