TxPlan — YAML-Based Transactions

Preview — 0.8.0-preview1: APIs may change before stable release.

TxPlan provides a configuration-driven approach to defining Cardano transactions. Instead of writing Java code for every transaction, you can define transactions in YAML with variable substitution, context properties, and signer registry references — then execute them through the standard QuickTxBuilder pipeline.

Benefits

• Configuration-driven — define transactions in YAML files, separate from application code
• Variable resolution — use ${variable} placeholders for dynamic values
• Context properties — centralize fee payer, collateral, validity, and signer configuration
• Version control friendly — human-readable transaction definitions
• No extra dependency — TxPlan is part of the quicktx module

Dependency

TxPlan is included in the quicktx module. If you already use cardano-client-lib or cardano-client-quicktx, no additional dependency is needed.

dependencies {
    implementation 'com.bloxbean.cardano:cardano-client-lib:0.8.0-preview1'
}

Creating a TxPlan

From a Tx Object

Tx tx = new Tx()
        .from("addr_test1...")
        .payToAddress("addr_test1_receiver", Amount.ada(5));
 
TxPlan plan = TxPlan.from(tx)
        .feePayer("addr_test1_fee_payer")
        .validTo(2000L);
 
// Serialize to YAML
String yaml = plan.toYaml();

From YAML

TxPlan plan = TxPlan.from(yamlString);
 
// Access transactions
List<AbstractTx<?>> transactions = plan.getTxs();

YAML Format

Basic Structure

version: 1.0
variables:
  sender: addr_test1_sender_address
  receiver: addr_test1_receiver_address
  amount: 5000000
context:
  fee_payer: ${sender}
  valid_to_slot: 5000
transaction:
  - tx:
      from: ${sender}
      intents:
        - type: payment
          address: ${receiver}
          amounts:
            - unit: lovelace
              quantity: ${amount}

Variables

The variables section defines key-value pairs that can be referenced anywhere in the YAML using ${variable_name} syntax. Variables are resolved before deserialization.

variables:
  treasury: addr_test1_treasury
  alice: addr_test1_alice
  payment_amount: 10000000
  pool_id: pool1abc123

Context Properties

The context section configures transaction-level settings that apply to the QuickTxBuilder.TxContext.

Transaction Entries

Each entry in the transaction list contains a tx block with:

• from / from_ref — sender address or registry reference
• change_address — optional explicit change address
• change_datum / change_datum_hash — datum for change output (script transactions)
• inputs — script UTXO inputs with redeemers
• intents — transaction intents (payments, minting, staking, etc.)
• scripts — validator attachments

QuickTxBuilder Integration

Direct Composition

QuickTxBuilder builder = new QuickTxBuilder(backendService);
 
TxPlan plan = TxPlan.from(yamlString);
 
TxResult result = builder.compose(plan)
        .withSigner(SignerProviders.signerFrom(account))
        .completeAndWait();

With Variables

Important: Variables are resolved during TxPlan.from() — calling addVariable() after parsing only updates the variable map for toYaml() serialization. It does not re-resolve already-parsed transaction fields.

To use dynamic variables, set them in the YAML string before calling from():

String yaml = baseYaml
    .replace("${amount}", "10000000")
    .replace("${receiver}", dynamicReceiverAddress);
 
TxPlan plan = TxPlan.from(yaml);

Alternatively, define variables in the YAML variables section with their final values before parsing.

Complete Example

String yamlPlan = """
    version: 1.0
    variables:
      sender: addr_test1_sender
      receiver: addr_test1_receiver
    context:
      fee_payer: ${sender}
      valid_to_slot: 5000
    transaction:
      - tx:
          from: ${sender}
          intents:
            - type: payment
              address: ${receiver}
              amounts:
                - unit: lovelace
                  quantity: '5000000'
    """;
 
QuickTxBuilder builder = new QuickTxBuilder(backendService);
TxPlan plan = TxPlan.from(yamlPlan);
 
TxResult result = builder.compose(plan)
        .withSigner(SignerProviders.signerFrom(account))
        .completeAndWait();