Plutus API

The Plutus API provides comprehensive functionality for interacting with Plutus smart contracts on the Cardano blockchain. It includes support for Plutus scripts (V1, V2, V3) and data serialization with type safety.

Key Features

• Plutus Script Support: Complete support for V1, V2, and V3 script versions
• Data Serialization: Convert between Java objects and PlutusData
• Type Safety: Strong typing for Plutus data structures

Core Classes

PlutusScript Classes

• PlutusV1Script: Plutus V1 script implementation
• PlutusV2Script: Plutus V2 script implementation
• PlutusV3Script: Plutus V3 script implementation

PlutusData Classes

• PlutusData: Base interface for all Plutus data types
• BigIntPlutusData: Integer data representation
• BytesPlutusData: Byte string data representation
• ListPlutusData: List data representation
• MapPlutusData: Map data representation

Usage Examples

Creating Plutus Scripts

Create different versions of Plutus scripts:

// Create Plutus V2 Script (most common)
PlutusV2Script v2Script = PlutusV2Script.builder()
        .type("PlutusScriptV2")
        .cborHex("590a4d590a4a0100003333...")
        .build();

// Create Plutus V3 Script (latest)
PlutusV3Script v3Script = PlutusV3Script.builder()
        .type("PlutusScriptV3")
        .cborHex("590b5e590b5b0100003333...")
        .build();

System.out.println("Scripts created successfully");

Loading Plutus Scripts from a Blueprint (CIP-57)

Smart contract compilers like Aiken and Scalus produce a plutus.json blueprint file following the CIP-57 standard. This file contains a compiledCode field for each validator, which is single-encoded CBOR hex. CCL’s PlutusScript objects require double-encoded CBOR, and the PlutusBlueprintUtil class handles this conversion automatically.

A typical plutus.json looks like this:

{
  "preamble": {
    "title": "aiken-lang/hello_world",
    "version": "1.0.0",
    "plutusVersion": "v3"
  },
  "validators": [
    {
      "title": "hello_world.spend",
      "compiledCode": "58ad0100003232322..."
    }
  ]
}

Option A: Direct conversion with PlutusBlueprintUtil

If you already have the compiledCode hex string and know the Plutus version, you can convert it directly:

import com.bloxbean.cardano.client.plutus.blueprint.PlutusBlueprintUtil;
import com.bloxbean.cardano.client.plutus.blueprint.model.PlutusVersion;

String compiledCode = "58ad0100003232322..."; // from plutus.json validators[].compiledCode

PlutusScript plutusScript = PlutusBlueprintUtil.getPlutusScriptFromCompiledCode(
        compiledCode, PlutusVersion.v3);

This performs double CBOR encoding internally and returns the appropriate PlutusV1Script, PlutusV2Script, or PlutusV3Script instance.

Option B: Load the full blueprint with PlutusBlueprintLoader

For a more streamlined approach, load the entire plutus.json and extract scripts by validator title:

import com.bloxbean.cardano.client.plutus.blueprint.PlutusBlueprintLoader;
import com.bloxbean.cardano.client.plutus.blueprint.model.PlutusContractBlueprint;

// Load the blueprint from classpath
InputStream is = getClass().getResourceAsStream("/plutus.json");
PlutusContractBlueprint blueprint = PlutusBlueprintLoader.loadBlueprint(is);

// Extract a PlutusScript by validator title
PlutusScript plutusScript = blueprint.getPlutusScript("hello_world.spend");

Using the loaded script with QuickTx

ScriptTx in 0.7.x and the 0.8.0 previews

ScriptTx is the API for script transactions in the stable 0.7.x releases, where it isn’t deprecated. In the 0.8.0 previews it’s deprecated, because every operation is also available on Tx. On a preview, you can replace new ScriptTx() with new Tx() and add .from(senderAddress). See Unified Tx API.

Once you have a PlutusScript, use it with ScriptTx the same way as a manually created script:

QuickTxBuilder quickTxBuilder = new QuickTxBuilder(backendService);

ScriptTx scriptTx = new ScriptTx()
        .collectFrom(utxo, redeemer)
        .payToAddress(receiverAddress, Amount.ada(10))
        .attachSpendingValidator(plutusScript);

Result<String> result = quickTxBuilder.compose(scriptTx)
        .feePayer(senderAddress)
        .withSigner(SignerProviders.signerFrom(senderAccount))
        .completeAndWait(System.out::println);

See also:

• Plutus Blueprint Code Generation — generate type-safe Java bindings from a blueprint using annotations
• Aiken Integration — Script cost evaluation and parameterized contracts
• Scalus Integration — Script cost evaluation and parameterized contracts

Working with PlutusData

Create and manipulate PlutusData structures:

// Create integer data
PlutusData intData = BigIntPlutusData.of(BigInteger.valueOf(42));

// Create string data (as bytes)
PlutusData stringData = BytesPlutusData.of("Hello Cardano".getBytes());

// Create list data (varargs)
PlutusData listData = ListPlutusData.of(intData, stringData);

// Create map data
MapPlutusData mapData = new MapPlutusData();
mapData.put(BytesPlutusData.of("key".getBytes()), intData);

System.out.println("PlutusData structures created");

Best Practices

Type Safety

// Use type-safe PlutusData creation
public PlutusData createTypeSafePlutusData() {
    // Prefer specific types over generic PlutusData
    PlutusData intData = BigIntPlutusData.of(BigInteger.valueOf(100));
    PlutusData bytesData = BytesPlutusData.of("data".getBytes());

    // Validate data before use
    if (intData instanceof BigIntPlutusData) {
        BigInteger value = ((BigIntPlutusData) intData).getValue();
        System.out.println("Integer value: " + value);
    }

    return intData;
}