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

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 (use builder pattern)
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;
}