--- name: cardano-cli-plutus-scripts description: "Plutus script guidance: datums, redeemers, collateral, reference scripts. Templates only—use operator to execute." allowed-tools: - Read user-invocable: true --- # cardano-cli-plutus-scripts > **This is a guidance skill.** Provides templates and explanations. For execution, use `cardano-cli-plutus-scripts-operator`. ## When to use - Learning Plutus script transaction patterns - Understanding datums, redeemers, collateral - Getting templates for script interactions ## Operating rules (must follow) - Confirm network and script version (V2\/V3) - Never execute—only provide templates - Always include collateral handling - Use fresh protocol parameters ## Key concepts ### Script versions - **V1** (Alonzo): Legacy, limited features - **V2** (Babbage): Reference scripts, inline datums - **V3** (Conway): Governance, simplified interface ### Datum handling - **Inline datum**: Stored on-chain with UTxO - **Datum hash**: Only hash on-chain, provide full datum when spending - **No datum**: For some V3 scripts ### Collateral - Required for all Plutus script transactions - Must be ADA-only UTxO - Forfeit if script fails unexpectedly - Typically 1-5 ADA sufficient ## Workflow templates ### Lock funds at script address ```bash # 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 # \ --tx-out "$(cat script.addr)+5000000" \ --tx-out-inline-datum-file datum.json \ --change-address \ --out-file tx.unsigned # Sign and submit ``` ### Spend from script ```bash # 1. Create redeemer echo '{"constructor": 0, "fields": []}' > redeemer.json # 2. Build script spend cardano-cli conway transaction build \ --testnet-magic 1 \ --tx-in # \ --tx-in-script-file script.plutus \ --tx-in-inline-datum-present \ --tx-in-redeemer-file redeemer.json \ --tx-in-collateral # \ --tx-out + \ --change-address \ --out-file tx.unsigned # Sign (with collateral key) and submit ``` ### With reference script ```bash # Script already on-chain at reference UTxO cardano-cli conway transaction build \ --testnet-magic 1 \ --tx-in # \ --spending-tx-in-reference # \ --spending-plutus-script-v2 \ --spending-reference-tx-in-inline-datum-present \ --spending-reference-tx-in-redeemer-file redeemer.json \ --tx-in-collateral # \ --tx-out + \ --change-address \ --out-file tx.unsigned ``` ## Examples ### Example: Simple validator spend **User request:** "Spend from my always-succeeds script" **Response:** ```bash # === 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 #0 \ --tx-in-script-file always-succeeds.plutus \ --tx-in-inline-datum-present \ --tx-in-redeemer-file redeemer.json \ --tx-in-collateral #0 \ --tx-out "$PAYMENT_ADDR+4500000" \ --change-address $PAYMENT_ADDR \ --out-file tx.unsigned # 5. Sign and submit (use operator skill) ``` ## Debugging ### Calculate execution costs ```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 ## Safety \/ key handling - Test scripts on preprod\/preview first - Use minimal collateral - Datum\/redeemer are public—no secrets - Verify script hash after rebuilds ## References - `shared\/PRINCIPLES.md` - `cardano-cli-plutus-scripts-operator` (for execution) - `aiken-smart-contracts` (for writing validators)