Overview

Yaci Store is a modular, high-performance Cardano blockchain indexer and datastore that provides a flexible foundation for building blockchain applications.

At the core of Yaci Store are stores, which are essentially modules responsible for indexing specific types of data from the blockchain. Examples include transaction, UTXO, metadata, and staking stores, among many others. Some components require data from multiple stores, such as reward calculation (Ledger State calculation) and governance state calculation. We call these aggregates.

Yaci Store functions as both a standalone indexer and a library that can be integrated into any Spring Boot Java application to build custom indexers with only the required data. This approach is particularly useful for applications that need specific blockchain data or data from particular dApps without storing all blockchain information.

As a library, Yaci Store offers extensive customization options, allowing developers to build their own indexers and datastores tailored to their needs.

Yaci Store also ships with a default indexer that indexes all on-chain data and provides a comprehensive set of REST APIs to query the indexed information. Developers have the flexibility to disable stores they don’t need or turn off specific API endpoints when not required.

Starting with version 2.0.0-beta3, Yaci Store introduced a plugin system that allows developers to extend its functionality through custom plugins. These plugins can be written in MVEL (a simple expression language), JavaScript, or Python.

With the plugin system, non-Java developers can now customize Yaci Store’s default behavior at a granular level. This was something previously only possible for Java developers using Yaci Store as a library in their applications. This capability is quite powerful and opens up many possibilities.

Plugin Types

Yaci Store currently supports two types of plugins:

1. Storage Plugins

These plugins extend Yaci Store’s storage capabilities by customizing the default behavior of storage implementations. There are three types of storage plugins:

• Filter Plugin: Allows developers to filter what data to store
• Pre-Action Plugin: Enables data modification before storage
• Post-Action Plugin: Performs actions after data is stored (e.g., sending notifications or updating related data)

Storage plugins are attached to predefined storage extension points. You can find the complete list of storage extension points in Yaci Store in the plugin API guide.

2. Event Handler Plugins

Event handler plugins let you listen to any Yaci Store event and perform actions based on those events. Previously, this capability was exclusive to Java developers, but now non-Java developers can also write event handler plugins in MVEL, JavaScript, or Python.

The full list of supported events is available in the plugin API guide.

Getting Started with Yaci Store Plugin System

Distribution Options

Yaci Store comes with two distribution types:

1. Docker Distribution Zip
2. Jar Distribution Zip

For the latest documentation on the 2.0.0 release, visit store.yaci.xyz.

In this guide, we’ll focus on the Docker Distribution.

Prerequisites

1. Download the latest Yaci Store Docker Distribution Zip from the releases page
   Note: Always check for the latest release version.
2. File to download: yaci-store-docker-2.0.0-beta4.zip
3. Unzip the downloaded file to your preferred directory. This creates a folder named yaci-store-docker-2.0.0-beta4.

File Structure

The extracted directory contains:

• config/: Configuration files for Yaci Store
• application.properties: Main configuration file for customization
• env: Environment variables file
• plugins/scripts: Directory for custom plugins (create subdirectories for organized plugin management)
• yaci-store.sh: Main script to start Yaci Store and the PostgreSQL database

Enabling Plugin Support

Step 1: Edit config/application-plugin.yml

Enable plugin support by setting enabled to true:

store:
  plugins:
    enabled: true

Step 2: Enable JavaScript and Python Plugin Support (Optional)

If you plan to use JavaScript or Python plugins, edit config/env and uncomment:

JDK_JAVA_OPTIONS=${JDK_JAVA_OPTIONS} -Dloader.path=plugins,plugins/lib,plugins/ext-jars

Example Use Cases

Example 1: Store Metadata with Specific Labels

Our first use case demonstrates storing metadata with a specific label. Let’s say we want to store only metadata with the label “721”, which follows the Cardano CIP25 token metadata standard.

We’ll create a filter plugin that filters metadata based on the label using MVEL expressions.

Plugin Configuration:

Create a filter plugin and attach it to the metadata.save storage extension point:

Note: Storage extension points are predefined hooks in storage implementations where you can attach custom behavior through storage plugins (filter, pre-action, post-action). For a complete list of storage extension points and domain models, visit the Yaci Store documentation.

Replace the content in config/application-plugins.yml with the following to filter metadata based on label. The provided expression will be evaluated for each metadata domain object before saving. In this example, we're using an MVEL expression, which is the easiest way to write a filter. For complex filter logic, you can create a separate script file with a filter method, as we'll see in the next example.

store:
  plugins:
    enabled: true
    filters:
      metadata.save:
        - name: "NFT Metadata Filter"
          lang: mvel
          expression: label == "721"

Testing Configuration:

By default, application.properties is configured for public relays of the Preprod network, so we'll continue our example with that setup.

For testing purposes, you can set a custom start point instead of syncing from genesis. Edit config/application.properties:

# Add to config/application.properties
store.cardano.sync-start-slot=17558626
store.cardano.sync-start-blockhash=3b907cde82b21fb0511845072139aade67222a47c3dcbf90d1e6931b1ad1e30e

Starting Yaci Store:

Run the following command from the extracted directory:

./yaci-store.sh start

Monitoring Logs:

Check the logs to verify your plugin is working:

tail -f logs/yaci-store.log

Querying Indexed Metadata:

Once Yaci Store is running, query the indexed metadata:

./psql.sh

-- Set the schema
SET search_path TO yaci_store;

-- Check that only NFT metadata (label 721) is stored
SELECT tx_hash, label FROM transaction_metadata;

Now, before moving to the next example, let’s start with a fresh database:

1. Stop Yaci Store — This will stop both Yaci Store and the PostgreSQL database.

./yaci-store.sh stop

2. Remove the data folder

rm -rf db-data

Example 2: Index UTXOs for a Specific Address

This use case demonstrates creating plugins to index UTXOs for a specific address. We’ll store address-specific UTXOs in the address_utxo table and spent UTXOs in the tx_input table.

We’ll disable all other stores and enable only the UTXO store, then filter for UTXOs belonging to our target address.

Though it may appear simple, this use case has certain complexities. In this example, we’ll see how we can resolve those through plugins to demonstrate the flexibility the plugin framework provides.

Target Address:

We are going to index the UTXOs for the following address.

addr_test1wzc86g4ym366hkaphryqqvaptwznqkmk2gdqz9930u534pcx58ahw

General Configuration:

We’ll use the Preprod network. Since the default configuration already points to public Preprod relays, no network configuration changes are needed.

Step 1: Update config/application.properties

Add the following configuration to disable all stores except the UTXO store.

store.assets.enabled=false
store.blocks.enabled=false
store.epoch.enabled=false
store.metadata.enabled=false
store.mir.enabled=false
store.script.enabled=false
store.staking.enabled=false
store.transaction.enabled=false
store.utxo.enabled=true
store.governance.enabled=false

Step 2: Configure the target address and sync start point

address.filter=addr_test1wzc86g4ym366hkaphryqqvaptwznqkmk2gdqz9930u534pcx58ahw

Update/add the following sync start point. This point/block is just before the first transaction of this address on the Preprod network. To quickly check if our plugin works, let’s set the following point as our sync start point:

store.cardano.sync-start-slot=66258805
store.cardano.sync-start-blockhash=2fd08baed1b092e4dda22306082f317e692d280f1e30d23bf8c88b566cd72cfe

Step 3: Discord Webhook URL (Optional)

If you want Discord notifications for balance changes, add the following configuration. This is an optional step for this example. You can also use any webhook for notifications through other systems. The Yaci Store Plugin framework provides an http variable that can be used to invoke webhook URLs from within plugins.

discord.webhook.url=https://discord.com/api/webhooks/...

Required Plugins for This Use Case

To store only UTXOs for our specific address, we need these plugins:

1. Filter Plugin: Filters UTXOs by the configured address

2. Event Handler Plugin for CommitEvent: During initial sync, Yaci Store processes blocks in batches of 100, with parallel processing within each batch for better performance. All storage plugins execute in parallel, but after processing each batch, Yaci Store publishes a CommitEvent that's processed sequentially.

Why do we need this? While filtering address_utxo records is straightforward (each record has an address field), filtering tx_input records is more challenging since they don't contain address information. The tx_input table represents spent outputs, enabling us to identify unspent UTXOs.

In the CommitEvent handler (called at the end of every batch after all UTXOs and inputs are saved), we’ll delete extra tx_input records by checking against the address_utxo table and removing inputs that don't have corresponding entries.

Note: Though not used in this example, the CommitEvent’s blockCaches field is a list of blocks processed in that batch (100 blocks during initial sync, 1 block at tip). This could be useful for finding block or transaction-related data if required for other use cases.

3. RollbackEvent Plugin to reset last tx input slot: This tracks the point up to which we’ve already deleted additional tx_inputs. This point helps limit our query condition when scanning the tx_inputs table. During rollback, we need to reset this point to the rollback point.

4. Event Handler Plugin for Notifications (Optional): Send Discord notifications whenever there’s a balance change.

Plugin Configuration

Replace these three plugins in config/application-plugins.yml:

store:
  plugins:
    enabled: true
    exit-on-error: true

    filters:
      utxo.unspent.save:
        - name: Filter by address
          lang: mvel
          script: 
            file: /app/plugins/scripts/utxo.mvel
            function: filterByAddress

    event-handlers:
      CommitEvent:
        - name: "Delete additional tx inputs"
          lang: mvel
          script: 
            file: /app/plugins/scripts/utxo.mvel
            function: handleCommitEvent          
        - name: "Send Balance Change Notification"
          lang: mvel
          script: 
            file: /app/plugins/scripts/utxo.mvel
            function: sendDiscordNotificationOnBalanceChange
            
      RollbackEvent:
        - name: "Reset last_tx_input_slot"
          lang: mvel
          script: 
            file: /app/plugins/scripts/utxo.mvel
            function: handleRollbackEvent

In the plugins/scripts/ directory, create a utxo.mvel file with the following content:

/**
 * Yaci Store UTXO Plugin Script
 * This script provides functionality for filtering UTXOs by address before storing in address_utxo table.
 * It also remove extra tx_inputs records through handling commit events
 */

/**
 * Filters a list of UTXO items by a specific address
 * @param items - List of UTXO items to filter
 * @return List of filtered UTXOs that match the address filter
 */
def filterByAddress(items) {
    // Initialize empty list to store filtered results
    filteredUtxos = [];
    
    // Get the address filter from environment configuration
    address = env.getProperty("address.filter");
    
    // Iterate through all UTXO items and filter by owner address
    for (item: items) {
        if (item.ownerAddr == address) {
            filteredUtxos.add(item);
        }
    }
    
    // If any UTXOs were found, update global state and log the count
    if (filteredUtxos.size() > 0) {
        global_state.put("utxo.found", true);
    }
    
    return filteredUtxos;
}

/**
 * Handles commit events by cleaning up additional transaction inputs
 * 
 * Since tx_input records don't have address filtering and Yaci Store processes 
 * blocks in parallel batches (100 blocks during initial sync, 1 block at tip), tx_input 
 * records may be inserted before their corresponding UTXO entries in address_utxo table. 
 * The CommitEvent is published at the end of each batch and handlers are processed 
 * sequentially, making it the perfect place to delete orphaned tx_input records.
 * 
 * @param event - The commit event containing metadata like slot number
 */
def handleCommitEvent(event) {
    // Get the last processed slot from state, default to 0 if not set
    // In this case, we are using plugin state to store last_tx_input_slot
    last_tx_inputs_slot = global_state.get("last_tx_inputs_slot");
    if (last_tx_inputs_slot == null) {
        last_tx_inputs_slot = 0;
    }

    System.out.println("Deleting additional tx inputs after slot: " + last_tx_inputs_slot);

    // SQL query to delete orphaned tx_input records
    // Only deletes records that are not referenced by address_utxo table
    sql = "DELETE FROM tx_input ti " +
            "WHERE ti.spent_at_slot > :given_slot " +
            "AND NOT EXISTS ( " +
            "  SELECT 1 FROM address_utxo au " +
            "  WHERE au.tx_hash = ti.tx_hash " +
            "    AND au.output_index = ti.output_index " +
            ")";

    // Set parameters for the SQL query
    params = [ "given_slot" : last_tx_inputs_slot ];
    
    // Execute the delete operation and get count of deleted records
    count = named_jdbc.update(sql, params);

    // Log the number of deleted records if any were found
    if (count > 0) {
        System.out.println("Deleted " + count + " additional tx inputs.");
    }

    // Update the last processed slot to current event slot
    global_state.put("last_tx_inputs_slot", event.metadata.slot);
}

def handleRollbackEvent(event) {
    //Reset last_tx_input_slot
    System.out.println("Utxo by address plugin handleRollbackEvent: " + event.rollbackTo.slot);
    global_state.put("last_tx_inputs_slot", event.rollbackTo.slot);
}

def sendDiscordNotificationOnBalanceChange(event) {
    utxoFound = global_state.get("utxo.found");
    
    if (utxoFound != null && utxoFound) {
        global_state.remove("utxo.found");

        // Skip sending notification if not at tip yet
        if (!event.metadata.syncMode) {
            return;
        }

        address = env.getProperty("address.filter");    

        sql = "SELECT SUM(au.lovelace_amount) AS balance " +
            "FROM address_utxo au " +
            "WHERE au.owner_addr = :address " +
            "AND NOT EXISTS (SELECT 1 FROM tx_input ti WHERE ti.tx_hash = au.tx_hash AND ti.output_index = au.output_index)";

        params = [ "address" : address ];
        
        result = named_jdbc.queryForMap(sql, params);
        balance = result["balance"];

        discordUrl = env.getProperty("discord.webhook.url");

        jsonData = ["content": "💰 Unspent UTXO Balance: " + balance + " Lovelace at Block: " + event.metadata.block +"\n Address: " + address];
        response = http.postJson(discordUrl, jsonData, ["Content-Type": "application/json"]);
        System.out.println("Discord response: " + response);
    }
}

Running the Example

1. If you have an existing database, remove the db-data folder
2. Start Yaci Store:

./yaci-store.sh start

3. Check the log file in the logs folder to see if the sync is working properly.

4. After some time, verify the results:

./psql.sh

SET search_path TO yaci_store;
SELECT owner_addr FROM address_utxo;

You should only see UTXOs with our configured address as the owner_addr.

Alternative Languages

While this example uses MVEL, you can also write plugins in JavaScript or Python. JavaScript and Python plugins are currently in preview status, enabled through GraalVM polyglot support. The current Docker distribution bundles standard JDK 24, but future releases will include GraalVM JDK as an option for better JavaScript and Python plugin performance.

You can find JavaScript and Python versions of this plugin in the yaci-store-plugins repository. The function names remain the same across MVEL, JavaScript, and Python implementations.

Note: Unlike MVEL, in JavaScript and Python plugins, you cannot access fields directly through field names. You must use getter methods instead.

Wrong: event.metadata.slot
Correct: event.getMetadata().getSlot()

Debugging Tips

Console Output:

• MVEL: Use System.out.println()
• JavaScript: Use console.log()
• Python: Use print()

Exception Handling: Check the log file at logs/yaci-store.log. Exception stack traces can be lengthy, so scroll to the beginning to find the root cause.

For non-Java developers, the current logging approach might feel overwhelming. We plan to introduce a separate plugin log file in future versions to improve the debugging experience.

Conclusion

The Yaci Store plugin system democratizes Cardano blockchain indexing customization, making it accessible to developers regardless of their programming language background. Whether you’re filtering specific metadata, tracking address-specific UTXOs, or building complex event-driven workflows, the plugin system provides the flexibility you need without requiring Java expertise.

This is just the beginning — the plugin system opens up countless possibilities for customizing your blockchain data indexing workflow. Happy building!

Resources

Yaci Store GitHub: https://github.com/bloxbean/yaci-store
Yaci Store Doc: https://store.yaci.xyz/
Yaci Store Plugin repository: https://github.com/bloxbean/yaci-store-plugins

With the release of Cardano Client Lib 0.5.0-beta1, we now have a new transaction builder API known as QuickTx. This post aims to provide an overview of this new API and demonstrate its utility.

Historically, Cardano Client Lib began with a high-level API for building payment or token mint transactions. While this provided simplicity, it lacked flexibility and support for more advanced transactions, such as those involving smart contracts.

To bridge this gap, the Composable Functions API was later introduced, offering flexibility and supporting various transaction types. This API provided out-of-the-box composable functions and allowed developers to write their custom functions for the TxBuilder API. However, it compromised on simplicity.

Enter QuickTx. This new transaction builder API strikes a balance between simplicity and flexibility. It’s built upon the Composable Functions API and offers a more streamlined experience, supporting an extensive range of transactions. Those familiar with the Lucid JS library will notice many similarities.

High-Level Concepts — QuickTx

Before diving into examples, let’s first explore some foundational concepts of QuickTx.

QuickTx API revolves around two main classes — Tx and ScriptTx – to declare different parts of a transaction or transaction fragments. These fragments are later composed by a new builder class, QuickTxBuilder, to construct the final transaction.

1. Tx

This class is for transactions from regular (non-script) addresses. You can declaratively define a transaction from an address using this class. Each instance must have a unique sender. Transaction types for the Tx class include:

• Transfers (address-to-address, non-script to script for fund locking)
• Token operations (minting, burning)
• Stake address operations (registration, de-registration, delegation)
• Pool operations (registration, update, retirement)
• Reward withdrawal

2. ScriptTx

This class can be used for transactions where a script witness is needed, like for transactions from a script address. With one ScriptTx instance, multiple script calls (spending, minting, etc.) can be declared together.

3. QuickTxBuilder

This class allows composition of multiple Tx and ScriptTx instances to create the final transaction. Beyond building the transaction, QuickTxBuilder also supports transaction signing and submission. Through Txcontxt, callbacks like “postBalanceTx” and “preBalanceTx” allow insertion of custom TxBuilder functions for application-specific customization.

Enough theory, let’s delve into some examples.

Setup and Pre-requisites

Accounts

For transactions, we need accounts. Here, we’ll set up a few testnet accounts for our examples:

Account sender1 = new Account(Networks.testnet(), mnemonic);
String sender1Addr = sender1.baseAddress();

Account sender2 = new Account(Networks.testnet(), mnemonic);
String sender2Addr = sender2.baseAddress();

String receiver1 = new Account(Networks.testnet(), mnemonic).baseAddress();

You can use any of the public testnets, such as Preprod or Preview. Please send some test Ada from the corresponding testnet faucet.

Backend Service

Create a BackendService instance for any of the supported backends (Blockfrost, Koios, Ogmios/Kupo, etc.). Alternatively, you can create your own backend implementation by implementing supplier interfaces such as UtxoSupplier, ProtocolParamsSupplier, and TransactionProcessor. However, to keep this blog post simple, let’s use one of the out-of-the-box providers

var backendService = new BFBackendService(Constants.BLOCKFROST_PREPROD_URL, bfProjectId);

or

var backendService = new KoiosBackendService(KOIOS_PREPROD_URL);

or 

var backendService = new KupmiosBackendService(ogmiosUrl, kupoUrl)

Transactions with QuickTx

Having set up the account and backend service correctly, we are now prepared to submit our first transaction.

1. A Simple Transfer from Sender to Receiver

Send test Ada from sender1 to receiver1 and attach a CIP20 message as metadata.

• Declare a transaction to pay Ada to receiver1.

Tx tx = new Tx()
       .payToAddress(receiver1, Amount.ada(5))
       .attachMetadata(MessageMetadata.create().add("This is a test message"))
       .from(sender1Addr);

Note: The from field must be set for Tx

• Build and submit the transaction to Cardano network

QuickTxBuilder quickTxBuilder = new QuickTxBuilder(backendService);
Result<String> result = quickTxBuilder.compose(tx)
       .withSigner(SignerProviders.signerFrom(sender1))
       .complete();

The QuickTxBuilder class constructs the final transaction using tx, signs it, and submits it to a Cardano node through backend service. If the transaction is valid, result.getValue() returns the transaction hash. To wait for the transaction to be included in a block, utilize the completeAndWait function:

Result<String> result = quickTxBuilder.compose(tx)
       .withSigner(SignerProviders.signerFrom(sender1))
       .completeAndWait(System.out::println);

2. Send Transfer to Two Separate Addresses :- Composing Two Payments

Transfer test Ada from sender1 to receiver1 and from sender2 to receiver2 in one transaction.

• Declarations:

Tx tx1 = new Tx()
       .payToAddress(receiver1, Amount.ada(5))
       .from(sender1Addr);

Tx tx2 = new Tx()
       .payToAddress(receiver2, Amount.ada(4.5))
       .from(sender2Addr);

• Compose and submit:

Result<String> result = quickTxBuilder.compose(tx1, tx2)
       .feePayer(sender1Addr)
       .withSigner(SignerProviders.signerFrom(sender1))
       .withSigner(SignerProviders.signerFrom(sender2))
       .completeAndWait(System.out::println);

Note: The feePayer() method sets sender1Addr as the fee payer, a requisite step when merging multiple Tx transactions.

3. Token Minting

• Setup — Create a policy. Define asset name and quantity

Policy policy = PolicyUtil.createMultiSigScriptAtLeastPolicy("test_policy", 1, 1);
String assetName = "MyAsset";
BigInteger qty = BigInteger.valueOf(200);

• Declare minting transaction

In the code snippet below:

a. Create a new Tx.
b. Declare mintAsset with required information such as policyScript, asset, and the receiver address which will receive the newly minted token.
c. Define a ‘from’ address.

Tx tx = new Tx()
       .mintAssets(policy.getPolicyScript(), new Asset(assetName, qty), sender1Addr)
       .attachMetadata(MessageMetadata.create().add("Minting tx"))
       .from(sender1Addr);

• Build, Sign and Submit transaction

To build and submit a transaction, the steps are exactly the same. Use QuickTxBuilder to compose the Tx, and sign the transaction with both the sender1 account and the policy script.

Result<String> result = quickTxBuilder.compose(tx)
       .withSigner(SignerProviders.signerFrom(sender1))
       .withSigner(SignerProviders.signerFrom(policy))
       .completeAndWait(System.out::println);

4. Minting Tokens and Distributing to Two Addresses

• Declare transaction

BigInteger qty = BigInteger.valueOf(200);
Tx tx = new Tx()
          .mintAssets(policy.getPolicyScript(), new Asset(assetName, qty))
          .payToAddress(receiver1, Amount.asset(policy.getPolicyId(), assetName, 100))
          .payToAddress(receiver2, Amount.asset(policy.getPolicyId(), assetName, 100))
          .from(sender1Addr);

Mint 200 tokens and transfer 100 tokens each to receiver1 and receiver2.

5. Mint and Pay using Two Separate Senders

• Declare transactions

Tx tx1 = new Tx()
       .payToAddress(receiver1, Amount.ada(1.5))
       .mintAssets(policy.getPolicyScript(), new Asset(assetName, qty), receiver2)
       .from(sender1Addr);

Tx tx2 = new Tx()
       .payToAddress(receiver2, Amount.ada(3))
       .from(sender2Addr);

The first transaction (tx1) deducts 1.5 ADA from the sender1 address to pay receiver1, and it mints 200 new tokens which are also sent to receiver2.

The second transaction (tx2) pays receiver2 3 ADA.

• Compose to build transaction and submit

Result<String> result = quickTxBuilder.compose(tx1, tx2)
       .feePayer(sender1.baseAddress())
       .withSigner(SignerProviders.signerFrom(sender1))
       .withSigner(SignerProviders.signerFrom(sender2))
       .withSigner(SignerProviders.signerFrom(policy))
       .completeAndWait(System.out::println);

Both Tx instances are combined to construct the final transaction. Note that we are signing the transaction with three signers: Sender1, Sender2, and the policy script.

6. Stake Address Registration

For tasks like stake key registration, de-registration, and delegation, QuickTx significantly simplifies the process.

• Registering the stake address:

Tx tx = new Tx()
       .registerStakeAddress(sender1Addr)
       .from(sender1Addr);

Result<String> result = quickTxBuilder.compose(tx)
       .withSigner(SignerProviders.signerFrom(sender1))
       .completeAndWait(msg -> System.out.println(msg));

7. Stake Key De-Registration

The transaction below will deregister the stake key and send the deposit back to sender1Addr. To de-register stake key, sign with account’s stake key and for fee payment, sign with account.

 Tx tx = new Tx()
           .deregisterStakeAddress(sender1Addr)
           .from(sender1Addr);

 Result<String> result = quickTxBuilder.compose(tx)
           .withSigner(SignerProviders.signerFrom(sender1))
           .withSigner(SignerProviders.stakeKeySignerFrom(sender1))
           .completeAndWait(msg -> System.out.println(msg));

For delegation and reward withdrawal, you can use delegateTo and withdraw methods, respectively.

Script / Smart Contract Transactions

In this section, we will explore some basic examples of smart contract transactions using QuickTx. This is just an introduction, and I’ll provide a more detailed step-by-step guide later in a separate blog post.

Pr-requisites

For smart contract transactions, you need both a PlutusScript and a script address. You can obtain a contract address from a PlutusScript object using the AddressProvider.

PlutusV2Script plutusScript = PlutusV2Script.builder()
                                .type("PlutusScriptV2")
                                .cborHex("49480100002221200101")
                                .build();

The script above represents the well-known alwaysTrue script that always returns true. To retrieve the script address:

String scriptAddress = AddressProvider.getEntAddress(plutusScript, Networks.testnet()).toBech32();

Note: For mainnet addresses, use Networks.mainnet().

1. Lock Fund

To secure funds at a script address with inline datum, use the payToContract() method from the Tx class:

BigIntPlutusData datumData = BigIntPlutusData.of(40);

Tx tx = new Tx()
            .payToContract(scriptAddress, Amount.ada(10), datumData)
            .from(sender2Addr);

Result<String> txResult = quickTxBuilder.compose(tx)
                .withSigner(SignerProviders.signerFrom(sender2))
                .completeAndWait(System.out::println);

In the code above, we are attempting to lock 10 Ada and datum 40 at the script address. The secured Ada can now only be accessed via a smart contract or script transaction.

2. Unlock funds at a contract address

Initially, find the UTXO(s) where the value is locked. Use the ScriptUtxoFinders class to achieve this:

UtxoSupplier utxoSupplier = new DefaultUtxoSupplier(backendService.getUtxoService());
Optional<Utxo> optionalUtxo = ScriptUtxoFinders.findFirstByInlineDatum(utxoSupplier, scriptAddress, datumData);

Now create a ScriptTx instance:

PlutusData redeemer = PlutusData.unit(); //any data for this contract
ScriptTx scriptTx = new ScriptTx()
                          .collectFrom(optionalUtxo.get(), redeemer)
                          .payToAddress(receiver1, Amount.ada(10))
                          .attachSpendingValidator(plutusScript);

In the above snippet, the collectFrom() method declares the input utxo(s) for this script transaction. The second parameter of the collectFrom method accepts redeemer data.

Next, we transfer the unlocked funds to receiver1. Finally, a spending validator can be attached using the attachSpendingValidator method.

To partially transfer locked funds to a receiver, you can use the withChangeAddress(address, datum) method. This refunds the remaining amount either to the script address or to any other specified address.

You can now build and submit the transaction using the familiar QuickTxBuilder:

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

Remember, QuickTxBuilder automatically evaluates script transactions to calculate script cost by invoking the evaluateTx method from backend service.

However, for in-app script cost evaluations without backend service dependency, you can use AikenTransactionEvaluator.

ProtocolParamsSupplier protocolParamsSupplier = new DefaultProtocolParamsSupplier(backendService.getEpochService());
Result<String> result = quickTxBuilder.compose(scriptTx)
                .feePayer(sender1Addr)
                .withSigner(SignerProviders.signerFrom(sender1))
                .withTxEvaluator(new AikenTransactionEvaluator(utxoSupplier, protocolParamsSupplier))
                .completeAndWait(System.out::println);

Note: It’s possible to incorporate multiple script calls or attach multiple spending validators in one ScriptTx instance.

2. Mint tokens with Script

To mint tokens using PlutusScript, initiate a ScriptTx instance and invoke mintAsset(). The following example demonstrates minting three separate tokens:

ScriptTx scriptTx = new ScriptTx()
    .mintAsset(plutusScript1, asset1, BigIntPlutusData.of(1), receiver1)
    .mintAsset(plutusScript2, asset2, BigIntPlutusData.of(2), sender1Addr)
    .mintAsset(plutusScript3, asset3, BigIntPlutusData.of(3), receiver1)
    .withChangeAddress(sender1Addr);

Result<String> result1 = quickTxBuilder.compose(scriptTx)
    .feePayer(sender1Addr)
    .withSigner(SignerProviders.signerFrom(sender1))
    .completeAndWait(System.out::println);

With ScriptTx, you can also handle reference inputs and execute various transaction types.

Conclusion

Thank you for taking the time to go through this guide with me. Stay tuned for more in-depth tutorials on working with Cardano Client Lib. If you have any questions or feedback, please don’t hesitate to reach out.

Happy coding!

Resources

1. Cardano Client Lib GitHub — https://github.com/bloxbean/cardano-client-lib
2. Cardano Client Lib Docs — https://cardano-client.dev

In this post, I am going to explain how to monitor a local Cardano node’s mempool using Java or any JVM language. To do that we are going to use a small Java library called “Yaci” and we need an instance of Cardano node.

What’s Yaci ?

An opensource project which implements Cardano mini-protocol.

Mini-protocols are a set of protocols which are used to enable communication between different Cardano nodes. These protocols can also be used by other client applications like indexer, explorer, wallets to fetch data from a node and create their own data store. There are two categories: node-to-node and node-to-client. The node-to-client protocol suite is mostly for trusted clients like wallets and chain consumers.

Yaci implements most of the mini protocols including local transaction submission.

To find the list of mini-protocols currently supported by Yaci, please visit project’s GitHub page.

https://github.com/bloxbean/yaci#status

To simplify the usage of mini protocol, it also provides various high level apis for different scenarios. So Java developers don’t need to understand the low level protocol details. There are two types of high level apis

• Listener based

Using listener based apis, you can easily get callbacks for different events like new blocks, rollback etc.

• Reactive apis using https://projectreactor.io/

Using reactive apis, you can receive blocks data through a Flux and can compose functionalities using available operators like filter, map etc.

Usage Scenarios Examples :

The followings are few examples where Yaci can be used

• To listen real-time events from a node (Example: Token minting, Token minted for a policy, Transactions …)
• Receive block/transaction data and create your own data store or query layer
• Alert or notification based on events in blockchain
• Create your own indexer
• Implement a Tx submission service by submitting transactions to a local Cardano node or a remote node with node-to-client protocol exposed through a relay like “socat”

Mempool monitoring

As mentioned earlier, we will go through the steps required for local mempool monitoring.

Pre-requisites

1. Local Tx Monitor is a node-to-client protocol. Node-to-client protocols are exposed through Unix domain socket. So that a local trusted client can connect and access those info from Cardano node. But you can use a relay like “socat” to expose Unix domain socket through a TCP socket for remote clients.

Example :

socat TCP-LISTEN:31001,fork UNIX-CONNECT:/data/cardano/pre-prod/db/node.socket

The apis for local tx monitoring in yaci accepts both path host / port and local socket file.

2. Create a Java app and add Yaci dependency to it

<dependency>
     <groupId>com.bloxbean.cardano</groupId>
     <artifactId>yaci</artifactId>
     <version>0.1.2</version>
</dependency>

Note: Get the latest released version of Yaci from project’s GitHub.

As we will be getting transaction bytes from the mempool, we will use “cardano-client-lib” to get transaction hash and to de-serialize transaction. This is only required for our example.

<dependency>
      <groupId>com.bloxbean.cardano</groupId>
      <artifactId>cardano-client-lib</artifactId>
      <version>0.4.0</version>
</dependency>

Configure and start the connection

First we need to setup the connection to a Cardano node through node-to-client protocol. So let’s get the path to Cardano’s nodeSocketFile and network’s protocol magic.

 String nodeSocketFile = "~/cardano-node/preprod/db/node.socket";
 long protocolMagic = Constants.PREPROD_PROTOCOL_MAGIC;

Note: You can use com.bloxbean.cardano.yaci.core.common.Constant class to get protocol magics for public networks.

Alternatively, if the node-to-client protocol is exposed through a relay like “socat”, get host and port.

Now, create an instance of LocalClientProvider and start the client.
As LocalClientProvider supports both local state query and local tx monitor mini protocols, you can now execute supported queries on a node.

 LocalClientProvider localClientProvider = new LocalClientProvider(nodeSocketFile, protocolMagic);
 localClientProvider.start();

In the above code snippet, we are creating a local client and then starting the client.

Let’s get “LocalTxMonitorClient” from localClientProvider.

LocalTxMonitorClient localTxMonitorClient = localClientProvider.getTxMonitorClient();

Now we are ready to query the node.

Query Mempool Transactions

To get the list of transactions currently in the mempool, we need to first acquire a mempool snapshot and then query the snapshot. You can acquire and query in two method calls or just use “acquireAndGetMempoolTransactionsAsMono()” which wraps both steps in one method call.

In this example, let’s monitor the mempool in a loop. Acquire method is a blocking call, so the program waits there till the availability of new snapshot.

while (true) {
     // local tx monitor code
}

Let’s add the following code snippets in the above while(true) loop.

List<byte[]> txBytesList = localTxMonitorClient.acquireAndGetMempoolTransactionsAsMono().block();

The above code will acquire a new snapshot when available and return a list of transactions as bytes in a Mono. We are using “block()” to get the list of transactions through a blocking call.
Note: You should use Mono’s non-blocking api like “subscribe” in your application to avoid blocking.

Now that we have a list of transactions as bytes, we can loop through the list to get transaction hashes and de-serialize available transactions. This can be easily done using Cardano Client Lib.

for(byte[] txBytes: txBytesList) {
    String txHash = TransactionUtil.getTxHash(txBytes);
    System.out.println("Tx Hash >> " + txHash);

    Transaction transaction = Transaction.deserialize(txBytes);
    System.out.println("Tx Body >> " + transaction);
}

Finally, let’s get the mempool size and capacity. Local tx monitor also provides information like mempool capacity, size and no of txs.

The following code snippet is getting the mempool status. You can see that we are using “getMempoolSizeAndCapacity()” in the below code snippet. This method doesn’t acquire a new snapshot and it uses the already acquired snapshot in the previous call.
But if you want to acquire a new snapshot and query mempool status, then you can use “acquireAndGetMempoolSizeAndCapacity()”.

MempoolStatus mempoolStatus = localTxMonitorClient.getMempoolSizeAndCapacity().block();
System.out.println("Mem Pool >> " + mempoolStatus);

Our mempool monitoring app is now ready. Run this program and then submit few transactions to this node through another program or Cardano CLI, you should start seeing the transactions as soon as those are available in mempool.

Sample Output:

Waiting to acquire next snapshot ...
Mem Pool >> MempoolStatus(capacityInBytes=178176, sizeInBytes=0, numberOfTxs=0)
Waiting to acquire next snapshot ...
Tx Hash >> 4d7ce3ece2f9aa36550763753df3885344b1f15ea1e67dd7c9f3f49924f0f480
Tx Body >> Transaction(body=TransactionBody(inputs=[TransactionInput{transactionId=7e36a90a9b85902d5b42599f831d...
Waiting to acquire next snapshot ...

That’s it. We covered only one use case in this post, but Yaci provides different apis which can support many different types of use cases.

Here’s a list of few major high level apis in Yaci that you may find interesting

• BlockStreamer : Reactive api to start getting blocks from current tip or from a given point.
• BlockSync : Get latest block data starting from current tip through a listener.
• BlockRangeSync : Get blocks data from point-1 to poin-2 through a listener
• LocalTxSubmissionClient : To submit a transaction to Cardano node
• TipFinder : To find the tip through a simple method call

Full source code of mempool monitoring example

References:
1. Yaci : A Cardano Mini Protocols implementation in Java (https://github.com/bloxbean/yaci)

2. Cardano Client Lib : Cardano client library in Java (https://github.com/bloxbean/cardano-client-lib)

3. Yaci CLI : A CLI example using Yaci (https://github.com/bloxbean/yaci-cli)

In this post, we will go through the steps required to invoke a Plutus smart contract from a Java application using Cardano Client Lib.

Cardano-client-lib is a Java client library for Cardano blockchain. It simplifies the interaction with Cardano blockchain from Java applications. Using this library, you can perform various types of transactions including smart contract calls in a Java application.

Compatible version: Cardano Client Lib 0.3.0-beta2 and above

Plutus Contract Example

We will use a simple contract called “Sum Contract” as an example in this post. To validate, the sum contract checks the sum of 0..n, where n is the datum value. The caller can unlock the fund in a script output by guessing the correct sum.

While this is a very simple plutus contract, but through this example we will try to use some of the new exciting features available in Babbage era (after Vasil Hardfork).

1. Reference Inputs (CIP 31)
2. Inline Datums (CIP 32)
3. Reference Scripts (CIP 33)
4. Collateral Output (CIP 40)

So, in high level we will be going through the following steps :

1. Create a reference script output to attach a script to the output. This is part of CIP 33. With reference script output, we don’t need to send the script body in the spending transaction.
2. Send some fund to script address with inline datum. The fund will be locked in the script output. Inline datum is defined in CIP 32. So instead of storing datum hash, we can now store datum value directly in the output.
3. Finally, create a spending transaction to unlock fund in script output. In spending transaction, we will refer to the reference script output (step-1) as a reference input. This is part of CIP 31. Also, we are going to use collateral outputs (CIP 40) in the spending transaction.

Before going through our example, let’s discuss some basic concepts in Cardano Client Lib. For more details, you can check my previous posts.

Alternatively, you can jump to the section “Invoke Guess Sum Contract” if you are already aware of these concepts.

Composable Functions

A set of FunctionalInterface which can be used to implement composable functions. These functions are used to build various different types of transactions. The library provides many useful out-of-box implementations of these functions. Most of the commonly used functions are already there. If required, application developers can write their own functions and use them with other out of box functions.

The followings are the main FunctionalInterface

1. TxBuilder
2. TxOutputBuilder
3. TxInputBuilder
4. TxSigner

TxBuilder : This functional interface helps to transform a transaction object. The apply method in this interface takes a TxBuilderContext and a Transaction object as input parameters. The role of this function is to transform the input transaction object with additional attributes or update existing attributes.

TxOutputBuilder : This functional interface helps to build a TransactionOutput object and adds that to the transaction output list. The accept method in this interface takes a TxBuilderContext and a list of TransactionOutput.

TxInputBuilder : This functional interface is responsible to build inputs for the expected outputs.

TxSigner : This interface is responsible to provide transaction signing capability.

Backend Service and Supplier Interfaces

The library provides a backend service layer, which is required to build and submit transaction to Cardano blockchain. By default, it provides backend service implementations for Blockfrost, Koios etc.

But, if you want to use some other providers to build and submit transaction, you can easily do so by implementing following three simple interfaces :

1. ProtocolParameterSupplier :- Implement this functional interface to provide current protocol parameters. Protocol parameters are required to build the transaction.

public interface ProtocolParamsSupplier {
    ProtocolParams getProtocolParams();
}

2. UtxoSupplier:- This interface has only one method. Implement this interface to provide utxos which are required during transaction building.

3. TransactionProcessor :- Implement this interface to submit transaction to the Cardano blockchain.

public interface TransactionProcessor {

    Result<String> submitTransaction(byte[] cborData) throws ApiException;
}

Note: If you are using a supported backend provider like Blockfrost, you can just use the out-of-box backend service implementation.

Invoke Guess Sum Contract

In this section, we will go through the example step by step. You can also find the full source code of the example here.

Now, let’s start with some initialization steps.

Account setup

To submit any transaction to Cardano blockchain, we need an account to sign and pay transaction fee.

So, let’s see how to create a sender account object from a mnemonic phrase. We will be using this account to send fund to the script output and also to unlock the fund.

String senderMnemonic = "<24 words mnemonic phrase>";

Account sender = new Account(Networks.testnet(), senderMnemonic);

String senderAddress = sender.baseAddress();

Plutus V2 Script Object and Script address

We need to use the compiled version of our Sum contract script. The following code snippet shows how to initialize the PlutusV2Script instance and find the script address.

1. Create a reference script output

Now that we have an account and a script instance, we can build and submit a transaction to create a reference script output. The script body will be stored in the output on-chain.

Let’s first start with the expected output.

We want to create an output with script reference. For simplicity, we can set the lovelace amount in the output to 0. The library will automatically calculate the min required ada and set it accordingly. You can also see the sumScript is passed as parameter in scriptRef().

Now with the above expected output, let’s create an instance of TxBuilder using composable functions.

In the above code snippet, we are getting TxOutputBuilder from the expected output (scriptRefOutput) and then using createFromSender composable function, we are creating TxInputBuilder and finally, buildInputs method is using TxInputBuilder to return TxBuilder.

So in summary, we selected required TransactionInputs for our expected output.

In Line-3, we are using another composable function “balanceTx” to balance the transaction. This is a wrapper function which calls other low level functions like feeCalculation, changeOutputAdjustment to balance an unbalanced transaction. The “balanceTx” function takes two parameters, change address and no of signers.

Now, we can build the transaction using TxBuilder and submit it to Cardano network.

In Line-1, a TxBuilderContext is created using UtxoSupplier and ProtocolParamsSupplier as parameters. If you are using Blockfrost or Koios as provider, these implementation are provided out-of-box. But you can easily provide your own supplier implementations if required.

In Line-2, TxBuilderContext’s buildAndSign method is used to build and sign the transaction by applying the previously created TxBuilder instance (scriptRefTxBuilder) and the TxSigner instance for sender.

In Line-4, the signed transaction is then submitted through the backend service’s TransactionService implementation. Alternatively, you can use your own TransactionProcessor implementation to submit the transaction.

That’s it. Now we have an output with script body as script reference.

2. Send fund to script address with inline datum

Now it’s time to send some fund to the script address that we had generated earlier using the PlutusV2Script instance. We will set an integer as datum value for the output. But instead of setting datum hash, the datum value will be directly stored in the output.

This is a simple transaction like step-1 but with inline datum.

In Line-1, we are creating an integer type Plutus data which is used as inline datum. The datum value is 8.

In Line-3 to Line-8, the expected output is defined with the inline datum (8).

Line-10 to Line 17 are similar to step-1, where a transaction is built and signed by TxBuilder, TxBuilderContext and finally submitted through TransactionService.

Now, we have an output at the script address with some locked fund (4 ADA) .

In the next section, we are going to create a spending transaction to unlock the fund.

3. Create a spending transaction (script txn) to spend the locked fund

To spend the locked fund, let’s first find the output at the script address.

You can use one of the helper method in ScriptUtxoFinders class to find the required output.

In Line-1, we find the output using datum.

In Line-2 to Line-5, we are trying to find the claim amount from the output. It’s basically the lovelace value in this example.

Now, it’s time to find some collateral for our script transaction.

In Babbage era (after Vasil HF), we can also use an utxo with native tokens as collateral. The remaining lovelace amount and native tokens are sent back as collateral output. You can find more details about collateral outputs spec in CIP 40.

In the above code snippet, we are using UtxoSelectionStrategy to find an utxo with minimum 5 ADA for the collateral input. In this case, we are using LargestFirstUtxoSelectionStrategy implementation, but you can also use other implementations like DefaultUtxoSelectionStrategyImpl or RandomImproveSelectionStrategy.

Alternatively, you can also use DefaultUtxoSelector class by providing a predicate.

Now, let’s define the expected output and create a script call context.

Line-1 to Line-5, define an expected output with the claim amount and a receiver address.

In Line-7 to Line-8, we are creating a ScriptCallContext with all required data like script object, redeemer details and exunits.

Note that the redeemer value is set to 36 as the sum of our datum (0..8) is 36.
ExUnits value is set to 0 as we are going to evaluate the actual script cost later.

Also, we are not providing datum value as our script output has inline datum instead of datum hash.

Now we are ready to create our TxBuilder instance and then create & sign the transaction and finally submit to the Cardano network to unlock the locked value.

Line-1 & Line-2 : Use the expected output and create inputs from script utxo that we found in one of the previous step.

Line-3 : Add reference script output (from step-1) as reference input. This is part of CIP 31.

Line-4 : Create collateral and collateral outputs using collateral utxos. The sender address is used as change address for collateral outputs.

Line-5: Use ScriptCallContext instance that we created before to populate script call related attributes in the transaction.

Line-6 to Line-15 : Evaluate exact ExUints by invoking evaluateTx() of backend service. This can also be done as a separate step before building of transaction. But, please make sure it’s done before fee calculation or before balanceTx method call.

Line-22 to Line-28 : Now as usual, build the transaction and submit it to Cardano network.

That’s it. We successfully invoked our on-chain plutus contract from off-chain Java code using Cardano Client Lib.

Full source code

For more examples, you can check Cardano Client Example GitHub repo.

Resources

1. Cardano Client Lib GitHub Repo
2. Cardano Client Example Repo
3. New Composable functions to build transaction

Cardano-client-lib is a Java client library for Cardano blockchain. It simplifies the interaction with Cardano blockchain from a Java application. Using this library, you can perform various types of transactions in a Java application.

For example, you can do a transfer from one address to another, mint a token or an NFT and invoke a Plutus smart contract in Java.

In this post, I am going to explain the concept of newly introduced composable functions API.

In the next few posts of this series, I will go through specific examples from regular transfer to token minting to plutus contract calls using composable function apis.

If you are new to cardano-client-lib, it currently supports three types of apis to build / perform various transactions.

1. High Level API : Provides simple interfaces to do transfer and token minting transaction. But some complex transactions may not be possible through high-level API.
2. Low Level API : These are low level serialization api to build transaction for Cardano network. These APIs are flexible and good for complex scenarios. Basically, you can achieve any complexity with low level api, but at the same time these APIs are not beginner friendly.
3. Composable Functions : These APIs were introduced in v0.2.0-beta2 which provide a balance between simple interface and flexibility. Using out-of-box composable functions, you can achieve any complexity and at the same time, you can write your own composable functions to customize the behavior during transaction building.

So in this post, I am going to focus on the general concepts of composable functions in the library.

Composable Functions

The current version of the library provides a set of FunctionalInterface which can be used to implement composable functions. These functions can be used to build various different types of transactions. The library provides many useful out-of-box implementations of these functions.

The followings are the main FunctionalInterface

1. TxBuilder
2. TxOutputBuilder
3. TxInputBuilder
4. TxSigner

TxBuilder : This functional interface helps to transform a transaction object. The build method in this interface takes a TxBuilderContext and a Transaction object as input parameters. The role of this function is to transform the input transaction object with additional attributes or update existing attributes.

TxOutputBuilder : This functional interface helps to build a TransactionOutput object and add that to the transaction output list. The accept method in this interface takes a TxBuilderContext and a list of TransactionOutput.

TxInputBuilder : This functional interface is responsible to build inputs from the expected outputs.

TxSigner : This interface is responsible to provide transaction signing capability.

TxBuilderContext

Each function takes TxBuilderContext as the first input parameter. The main responsibility of TxBuilderContext is to provide context data like UtxoSupplier, ProtocolParamsSupplier, UtxoSelectionStrategy and some temporary data to the functions during the transaction building.

Function Helpers

The library provides many out-of-box functions through helper classes which help to build the transaction. So you don’t need to start from zero and the same time you can write your own functions if required.

In the current version of the library, the following helper classes are available

1. OutputBuilders : Provides a list of helper methods to create a TxOutputBuilder function which is used create a TransactionOutput from a TransactionOutput or Output object. The TxOutputBuilder functions verify min ada requirement and update the ada amount accordingly in the TransactionOutput.

Some of the helper methods available in this class are

- TxOutputBuilder createFromOutput(Output output)

- TxOutputBuilder createFromOutput(TransactionOutput txnOutput)

- TxOutputBuilder createFromMintOutput(Output output)

- TxOutputBuilder createFromMintOutput(TransactionOutput txnOutput)

You can combine multiple TxOutputBuilder using “and” method.

TxOutputBuilder txOutputBuilder = createFromOutput(output1)
                                     .and(createFromOutput(output2))

Note: For token minting transaction, to calculate min required ada in output accurately, mint outputs or createFromMintOutput() methods should be invoked after all regular outputs or createFromOutput() methods.

2. InputBuilders : Provides helper methods to create a TxInputBuilder function which is used to build required TransactionInput(s) from a list of TransactionOutput(s) using buildInputs() method of TxOutputBuilder.

TxBuilder txBuilder = txOutputBuilder1
                       .and(txOutputBuilder2)
                       .buildInputs(createFromSender(senderAddress, changeAddress))

Some of the helper methods available in this class are

- TxInputBuilder createFromSender(String sender, String changeAddress)

- TxInputBuilder createFromUtxos(List<Utxo> utxos)

- TxInputBuilder createFromUtxos(Supplier<List<Utxo>> supplier)

- TxInputBuilder createFromUtxos(List<Utxo> utxos, String changeAddress)

- TxInputBuilder createFromUtxos(List<Utxo> utxos, String changeAddress, Object datum)

- TxInputBuilder createFromUtxos(List<Utxo> utxos, String changeAddress, String datumHash)

3. MintCreators : It provides helper methods to create a TxBuilder function which is used to add multiasset minting related data to the Transaction object.

TxBuilder txBuilder = txOuputBuilder1
                        .and(txOuputBuilder2)
                        .and(createFromMintOutput(mintOutput))
                      .buildInputs(txInputBuilder)
                      .andThen(mintCreator(script, multiAsset)

Note: For minting transaction, a TxOutputBuilder specific to mint output is required. This can be done by calling one of the OutputBuilders.createFromMintOutput method.

Some of the helper methods available in this class are

- TxBuilder mintCreator(Script script, MultiAsset multiAsset)

- TxBuilder mintCreator(Script script, MultiAsset multiAsset, boolean inclScriptInAuxData)

4. AuxDataProviders : Provides helper methods to create a TxBuilder function which is used to add metadata to the Transaction object.

TxBuilder txBuilder = txOuputBuilder1
                        .and(txOuputBuilder2)
                      .buildInputs(txInputBuilder)
                      .andThen(metadataProvider(metadata))

5. CollateralBuilders : Provides helper methods to create a TxBuilder function which is used to add collateral(s) to the Transaction object in a plutus script transaction.

TxBuilder txBuilder = txOuputBuilder1
                        .and(txOuputBuilder2)
                      .buildInputs(txInputBuilder)
                      .andThen(collateralFrom(txHash, txIndex))

Some of the helper methods available in this class are

- TxBuilder collateralFrom(String txHash, int txIndex)

- TxBuilder collateralFrom(List<Utxo> utxos)

- TxBuilder collateralFrom(Supplier<List<Utxo>> supplier)

6. ScriptCallConextProviders : Provides helper methods to create a TxBuilder function which is used to add plutus script specific data to a Transaction object.

TxBuilder txBuilder = txOuputBuilder1
              .and(txOuputBuilder2)
           .buildInputs(txInputBuilder)
           .andThen(collateralFrom(txHash, txIndex))
           .andThen(createFromScriptCallContext(scriptCallContext))

Some of the helper methods available in this class are

- TxBuilder createFromScriptCallContext(ScriptCallContext sc)

- TxBuilder scriptCallContext(PlutusScript plutusScript, Utxo utxo,              T datum, K redeemerData,RedeemerTag tag, ExUnits exUnits)

- TxBuilder scriptCallContext(PlutusScript plutusScript, int scriptInputIndex, T datum, K redeemerData, RedeemerTag tag, ExUnits exUnits)

7. FeeCalculators : Provides helper methods to create TxBuilder function to calculate fee and update Transaction object accordingly.

TxBuilder txBuilder = txOuputBuilder1
                        .and(txOuputBuilder2)
                      .buildInputs(txInputBuilder)
                      .andThen(otherTxBuilder)
                      ...
                      .andThen(feeCalculator(changeAddress, noOfSigners))

Note: No of signers is required to calculate the fee accurately. For example, for a minting transaction with a policy script, min no of signers is 2. (Minting account, Policy script secret key)

Helper methods to create TxBuilder function in this helper class are

- TxBuilder feeCalculator(String changeAddress, int noOfSigners)

- TxBuilder feeCalculator(int noOfSigners, UpdateOutputFunction updateOutputWithFeeFunc)

8. ChangeOutputAdjustments : Provides helper methods to create TxBuilder function which can adjust the change output. This function is used to verify if the ada amount in change output satisfies min ada requirement. If not, it tries to get additional inputs and adjust the change output after the fee calculation. This function is used after feeCalculation function.

TxBuilder txBuilder = txOuputBuilder1
             .and(txOuputBuilder2)
             .buildInputs(txInputBuilder)
             .andThen(otherTxBuilder)
             ...
             .andThen(feeCalculator(changeAddress, noOfSigners))
             .andThen(adjustChangeOutput(senderAddress, changeAddress, noOfSigners))

9. SignerProviders : Provides helper methods to create TxSigner function to sign a transaction.

TxSigner signer = signerFrom(sender1, sender2, ..., sendern)
                   .andThen(signerFrom(secretKey1, ..., secretKeyn))

Some of the helper methods available in this class are

- TxSigner signerFrom(Account... signers)

- TxSigner signerFrom(SecretKey... secretKeys)

- TxSigner signerFrom(Policy... policies)

10. MinAdaCheckers : Provides a helper method to return MinAdaChecker function. MinAdaChecker function returns the additional lovelace amount required for a TransactionOutput to meet the min ada requirement. This function is used internally by implementations of other functions. You may not need to use this function directly.

Build and Sign Transaction

After TxBuilder is created by composing different functions, a Transaction object can be built and signed.

TxBuilder txBuilder = createFromOutput(output)
        .buildInputs(createFromSender(senderAddress, senderAddress))
        .andThen(metadataProvider(metadata))
        .andThen(feeCalculator(senderAddress, 1))
        .andThen(adjustChangeOutput(senderAddress, 1));

TxSigner signer = SignerProviders.signerFrom(sender);

/*** Create instance of UtxoSupplier & ProtocolParamsSupplier ***/
UtxoSupplier utxoSupplier = new         DefaultUtxoSupplier(backendService.getUtxoService());

ProtocolParamsSupplier protocolParamsSupplier = new DefaultProtocolParamsSupplier(backendService.getEpochService());

/**** Build and Sign in one step ****/
Transaction signedTxn = 
     TxBuilderContext.init(utxoSupplier, protocolParamsSupplier)
           .buildAndSign(txBuilder, signer);

/**** OR, Build Txn and then sign using signer *****/
Transaction transaction = 
      TxBuilderContext.init(utxoSupplier, protocolParamsSupplier)
           .build(txBuilder);

Transaction signedTxn = signer.sign(transaction);

Submit a transaction to Cardano network

Once a transaction is signed, you can submit it to the network using TransactionService.

Result<String> result =           transactionService.submitTransaction(signedTxn.serialize());

Add your own TxBuilder implementation

In some scenarios, you need to provide your own TxBuilder and other functions to transform the transaction object.

Example :
Right now, there is no TxBuilder function to set ttl parameter in the transaction object. But you can easily provide your own implementation to set ttl or add/update other parameters.

TxBuilder txBuilder = txOuputBuilder1
             .and(txOuputBuilder2)
             .buildInputs(txInputBuilder)
             .andThen(otherTxBuilder)
             .andThen((context, transaction) -> {
                   transaction.getBody().setTtl(100000);

                   //set or update other transaction parameters
             })
             .andThen(feeCalculator(changeAddress, noOfSigners))

So in summary, to use the composable function API, follow these below steps to build a transaction

1. Define expected outputs
2. Create one or more TxOutputBuilder from outputs
3. Create a TxInputBuilder which selects inputs for a sender
4. Step-1 to Step-3 can be repeated for multiple senders
5. Create additional TxBuilder(s) to add / update different attributes in the transaction.
6. Create TxSigner
7. Invoke TxBuilderContext.init() to initialize the context and then invoke buildAndSign() to build and sign the transaction.

In the next few posts of this series, I will go through specific examples from regular transfer to token minting to Plutus contract calls using composable function APIs.

Meanwhile, you can find different examples using composable functions in this GitHub repo

Resources

1. Cardano Client Lib Project GitHub
2. Cardano Client Example GitHub

Join Coinmonks Telegram Channel and Youtube Channel learn about crypto trading and investing

Also, Read

• Bookmap Review | 5 Best Crypto Exchanges in the USA
• The Best Crypto Hardware wallet | Bitbns Review
• 10 Best Crypto Exchange in Singapore | Buy AXS
• Red Dog Casino Review | Swyftx Review | CoinGate Review
• Best Crypto to Invest in India | WazirX P2P | Hi Dollar Review
• Best Crypto Trading bots in Canada | KuCoin Review
• Crypto Trading Signals for Huobi | HitBTC Review
• How to trade Futures on FTX Exchange | OKEx vs Binance

Cardano-client-lib: New composable functions to build transaction in Java— Part I was originally published in Coinmonks on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is the third part of cardano-client-lib series. In this post, I will explain how to create a new Native Token using Java. In this post also, we will be using Blockfrost backend api.

You can check Part I and Part II of this series before continuing with this post

1. Cardano-client-lib: A Java Library to interact with Cardano -Part I
2. Cardano-client-lib: Transaction with Metadata in Java- Part II

In Cardano, you can mint a new native token without writing a smart contract. Users can transact with ada, and an unlimited number of user-defined (custom) tokens natively.

Let’s create a new native token.

1. Project and account setup

If you have not setup your project yet, please follow the step-1 to step-6 from Part I.

2. Create a Policy Script & Policy Id

In Cardano, token minting policies are written using multi-signature scripts. This allows the asset controller to express conditions such as the need for specific token issuers to agree to mint new tokens, or to forbid minting tokens after a certain slot.

The library provides following classes to create different types of supported policies :

• ScriptPubKey
• ScriptAll
• ScriptAny
• ScriptAtLeast
• RequireTimeAfter
• RequireTimeBefore

You can build a very simple minting policy, which grants the right to mint tokens to a single key or build a complex policy by combining above classes.

In this post, we will create a simple policy, which grants the right to mint tokens to a single key.

Let’s create a key-pair which we can be used to create the policy.

Keys keys = KeyGenUtil.generateKey();
VerificationKey vkey = keys.getVkey();
SecretKey skey = keys.getSkey();

Create a ScriptPubKey, which grants the right to mint tokens to the above generated key.

ScriptPubkey scriptPubkey = ScriptPubkey.create(vkey);

We can now generate policy id from scriptPubKey object.

String policyId = scriptPubkey.getPolicyId();

3. Define our new native token using MultiAsset class

Create an instance of MultiAsset class. Use the policy id generated in previous step. Create an asset object with a custom name and token quantity.

MultiAsset multiAsset = new MultiAsset();
multiAsset.setPolicyId(policyId);
Asset asset = new Asset("TestCoin", BigInteger.valueOf(250000));
multiAsset.getAssets().add(asset);

4. Attach Metadata to Mint Token transaction (Optional)

If you want to attach some metadata to this token mint transaction, you can do so using Metadata apis provided by the library.

CBORMetadataMap tokenInfoMap
        = new CBORMetadataMap()
        .put("token", "Test Token")
        .put("symbol", "TTOK");

CBORMetadataList tagList
        = new CBORMetadataList()
        .add("tag1")
        .add("tag2");

Metadata metadata = new CBORMetadata()
        .put(new BigInteger("770001"), tokenInfoMap)
        .put(new BigInteger("770002"), tagList);

5. Create Token Minting request

Create a token minting transaction request using MintTransaction class.

MintTransaction mintTransaction =
        MintTransaction.builder()
                .sender(sender)
                .mintAssets(Arrays.asList(multiAsset))
                .policyScript(scriptPubkey)
                .policyKeys(Arrays.asList(skey))
                .build();

Note: Apart from setting the multiAsset object created in the step-3, we are also adding our policy script (scriptPubKey) and policy secret key (skey) which were generated in step-2.

If you don’t set policy script and policy keys, the token mint transaction will fail.

If the receiver field is not set, the minted token will be allocated to the sender account.

6. Calculate TTL (Time To Live) and fee

Calculate TTL

long ttl = blockService.getLastestBlock().getValue().getSlot() + 1000;

TransactionDetailsParams detailsParams =
        TransactionDetailsParams.builder()
                .ttl(ttl)
                .build();

Calculate fee and set the fee in mint transaction

BigInteger fee
         = feeCalculationService.calculateFee(mintTransaction,            detailsParams, metadata);

mintTransaction.setFee(fee);

7. Submit the Mint Token transaction

Finally, submit the token mint transaction using TransactionHelperService.

Result<String> result 
         = transactionHelperService.mintToken(mintTransaction,     detailsParams, metadata);

if(result.isSuccessful())
    System.out.println("Transaction Id: " + result.getValue());
else
    System.out.println("Transaction failed: " + result);

8. Check transaction details in Cardano Explorer

Now go to Cardano Testnet Explorer and check transaction details.

It may take some time for the transaction to be mined.

You should now see the minted token under the receiver’s address. (If no receiver is specified, under sender’s address)

9. Get details of our newly minted asset

First get asset id by combining previously generated policy id and then the HEX encoded value of our asset name.

String policyId = "abe83f0124320fc4e6f50605e7986390453bcc0c913c920a249545eb";
String assetName = HexUtil.encodeHexString("TestCoin".getBytes(StandardCharsets.UTF_8));

String assetId = policyId + assetName;

Then use AssetService to get asset details.

Result<Asset> asset = assetService.getAsset(assetId);
System.out.println(JsonUtil.getPrettyJson(asset.getValue()));

Output:

{
  "policy_id" : "abe83f0124320fc4e6f50605e7986390453bcc0c913c920a249545eb",
  "asset_name" : "54657374436f696e",
  "fingerprint" : "asset1uw2v9tzrp6ntvzc48l28j2jc2r4k569hxxk463",
  "quantity" : "4000",
  "initial_mint_tx_hash" : "d9da361f3e5237832cfcbdea16d440c9ea3e5026c7370c368291aafb5c2646a6"
}

10. Create complex policies by combining different script classes

In the below policy script example, we are creating a ScriptAll policy by combining RequireTimeBefore and ScriptAtLeast script.

//Key 1 - Single Key Policy
Tuple<ScriptPubkey, Keys> tuple1 = ScriptPubkey.createWithNewKey();
ScriptPubkey scriptPubkey1 = tuple1._1;
SecretKey sk1 = tuple1._2.getSkey();

//Key 2 - Single Key Policy
Tuple<ScriptPubkey, Keys> tuple2 = ScriptPubkey.createWithNewKey();
ScriptPubkey scriptPubkey2 = tuple2._1;
SecretKey sk2 = tuple2._2.getSkey();

//Key 3 - Single Key Policy
Tuple<ScriptPubkey, Keys> tuple3 = ScriptPubkey.createWithNewKey();
ScriptPubkey scriptPubkey3 = tuple3._1;
SecretKey sk3 = tuple3._2.getSkey();

//AtLeast policy with min-required key 2
ScriptAtLeast scriptAtLeast = new ScriptAtLeast(2)
        .addScript(scriptPubkey1)
        .addScript(scriptPubkey2)
        .addScript(scriptPubkey3);

long slot = getTtl();
RequireTimeBefore requireTimeBefore = new RequireTimeBefore(slot);

//Create the final ScriptAll policy by combining RequireTimeBefore and ScriptAtLeast
ScriptAll scriptAll = new ScriptAll()
        .addScript(requireTimeBefore)
        .addScript(
                scriptAtLeast
        );

You can print the the JSON value of Script object and store it in a file. The generated JSON object is compatible with cardano-cli command line tool.

Full source code:

Resources

1. Cardano-client-lib GitHub repository (https://github.com/bloxbean/cardano-client-lib)
2. Example Source code (https://github.com/bloxbean/cardano-client-examples)

In this post, we will see how you can create and post a transaction with metadata to Cardano network in a Java application using cardano-client-lib.

Cardano-client-lib is a Java library which provides support to create, sign and submit transaction to the Cardano network. Check Part-I of this series to know more about Cardano-client-lib and the other functionalities provided by this library.

In this post we will be using Blockfrost backend Api.

Cardano Metadata as defined in this blog :-

Metadata tells the story of a transaction and there are many ways to interact with this story. Developers can take advantage of metadata by embedding details directly into a transaction, and ada users can search for specific information in the Cardano Explorer. The data can be added directly, or, for larger amounts, it is possible to create a Merkle tree of the data and put the root hash of the Merkle tree on the blockchain. Once this is done, it can be proved that the data existed at a specific point of time and that it remains permanently on the chain for future reference.

Cardano-client-lib provides simple apis to create metadata. It also provides helpers to convert metadata to JSON and vice versa.

Let’s create a payment transaction and add some metadata to it.

1. Project and account setup

If you have not setup your project yet, please follow the step-1 to step-6 from Part I.

2. Create a metadata object

To create a metadata object, you have to start with CBORMetadata class. You can also use CBORMetadataMap and CBORMetadataList if you want to set the value as Map or List.

CBORMetadataMap productDetailsMap
        = new CBORMetadataMap()
        .put("code", "PROD-800")
        .put("slno", "SL20000039484");

CBORMetadataList tagList
        = new CBORMetadataList()
        .add("laptop")
        .add("computer");

Metadata metadata = new CBORMetadata()
        .put(new BigInteger("670001"), productDetailsMap)
        .put(new BigInteger("670002"), tagList);

In the above example, we are first creating a Map which contains code and serial no. We are then creating a List to hold multiple tags.

Finally, we are creating a Metadata object and setting productDetailsMap and tagList with metadata labels 670001, 670002 respectively.

You can create a multi-level nested structure, but the top-level object should be Metadata.

3. Create a transaction request object

As explained in the Part I, let’s create a transaction with PaymentTransaction class.

PaymentTransaction paymentTransaction =
          PaymentTransaction.builder()
                .sender(sender)
                .receiver(receiver)
                .amount(BigInteger.valueOf(20000000))
                .unit(LOVELACE)
                .build();

4. Calculate TTL (Time-to-Live)

Use BlockService to get the latest slot number and then calculate ttl.

long ttl = blockService.getLastestBlock().getValue().getSlot() + 1000;
TransactionDetailsParams detailsParams =
        TransactionDetailsParams.builder()
                .ttl(ttl)
                .build();

5. Calculate Fee

Use FeeCalculatorService to calculate fee. Make sure to send all three parameters “PaymentTransaction, TransactionDetailsParams and Metadata” to FeeCalculatorService.

Set the calculated fee in PaymentTransaction request.

BigInteger fee 
         = feeCalculationService.calculateFee(paymentTransaction,                   detailsParams, metadata);

paymentTransaction.setFee(fee);

6. Submit Transaction with Metadata

Now submit the transaction request to the network using TransactionHelperService.

Note: Make sure to pass “metadata” parameter in the transfer call.

Result<String> result
          = transactionHelperService.transfer(paymentTransaction,    detailsParams, metadata);

if(result.isSuccessful())
    System.out.println("Transaction Id: " + result.getValue());
else
    System.out.println("Transaction failed: " + result);

7. Check transaction details in Cardano Explorer

Now go to Cardano Testnet Explorer and check the transaction details.

It may take some time for the transaction to be mined.

Now you can see the metadata in Cardano explorer.

Metadata can be added to a Native token transfer in similar ways.

Metadata Helper Class

There are few helper classes which can be used to convert a JSON (No Schema) object to metadata format and vice-versa.

But the Json payload has to follow the format mentioned in this wiki.

JsonNoSchemaToMetadataConverter
MetadataToJsonNoSchemaConverter

Check also:

• Part I : Cardano-client-lib: A Java Library to interact with Cardano — Part I
• Part III : Cardano-client-lib: Minting a new Native Token in Java — Part III

Resources

• Cardano-client-lib GitHub repository (https://github.com/bloxbean/cardano-client-lib)
• Example Source code (https://github.com/bloxbean/cardano-client-examples)

Full Source code

Update: For latest “Getting Started Guide”, you can check this tutorial https://cardano-client.bloxbean.com/docs/gettingstarted/simple-transfer
The high level api used to build transaction in this post (from section #7) is no longer recommended. For flexibility, you should build the transactions using “Composable Functions api” mentioned in the above getting started guide.

In this post, I am going to introduce a Java library called “cardano-client-lib”. You can use this library in a Java application to interact with Cardano blockchain.

Why a Cardano Client Java Library ?

Currently, I am working on a project called “Cardano IntelliJ IDEA plugin (IntelliAda)”, which is a Catalyst Fund 3 funded project. You can check the Catalyst proposal here. When I started this project, I realized that there are client side libraries available for Cardano in languages like JavaScript, Rust (Cardano-serilization-lib), but I was not able find any Java library doing the similar thing without relying on cardano-cli (Cardano command line tool).

As Cardano IntelliJ Plugin is written in java, I need a client library in Java, so that I don’t need to rely on Cardano-cli tool inside the plugin to generate address, sign transaction and other operations. Because of that I started working on cardano-client-lib project to provide address generation, transaction serialization and signing support through a Java library.

The preview version (0.1.0) of this library in now available in Maven central repository, so you can use it in your java application.

This library also provides support to interact with Cardano blockchain to query blockchain and submit transactions through few simple Backend Apis. Currently, only one implementation available for Backend Api, which is for Blockfrost endpoint. More backends will be supported in future releases. (Cardano Wallet Backend, Cardano-ogmios ..)

The following key features are currently supported in this library

• Address Generation (Base Address, Enterprise Address)
• Build and serialize transaction to CBOR format
• Apis to build Metadata
• A converter to convert Metadata to Json (No Schema)
• Payment transaction (ADA, Native tokens) signing and submission to Cardano network (through Blockfrost Backend Api)
• Transaction with metadata
• Api to mint native tokens
• Apis to query Cardano blockchain through many Blockfrost backend apis (AddressService, AssetService, BlockService, EpochService,MetadataService, TransactionService …)

Current Limitations

• Currently, this library is using “Cardano-serialization-lib” rust library through JNI, mainly for address generation and transaction signing. So it bundles the platform dependent binaries of Cardano-serialization-lib in the Jar. Because of that, this library is currently supported only on the following platforms

- Apple MacOS (Intel and Apple Silicon)
- Linux (x86_64) (Ubuntu 18.04 and above or compatible …)
-Windows 64bits (x86_64)

Note: This limitation is temporary. The plan is to remove this dependency in the future release by implementing address generation and transaction signing natively in Java.

• The library doesn’t support any stake pool related operations. Though in future, stake pool related operations can be added.

Let’s see how we can use this library to create and post a transfer transaction with Ada.

1. Add cardano-client-lib dependency to your application

If you are using Maven,

<dependency>
    <groupId>com.bloxbean.cardano</groupId>
    <artifactId>cardano-client-lib</artifactId>
    <version>0.1.0</version>
</dependency>

If you are using Gradle,

implementation 'com.bloxbean.cardano:cardano-client-lib:0.1.0'

Note: You can check the latest released version in project’s GitHub.

2. Create a new Account

Account account = new Account(Networks.testnet());
String baseAddress = account.baseAddress();

3. Import from Mnemonic Phrase

Provide 24 words mnemonic phrase to derive the base account address.

String mnemonic = "behind hope swing table fat joy phone spoil response exercise dose fame mystery day food lens debate slam lawsuit board behind allow excuse extend";

Account account = new Account(Networks.testnet(), mnemonic);
String baseAddress = account.baseAddress();

4. Get Backend Service

Provide Blockfrost Cardano network and Project Id to get an instance of Blockfrost backend service.

Register at https://blockfrost.io/ to get a free account and a project id for Cardano Testnet.

BackendService backendService =
     BackendFactory.getBlockfrostBackendService(
        Constants.BLOCKFROST_TESTNET_URL, <project_id>);

5. Get Other services from Backend Service

The followings are the example of few major services you can get from BackendService. You can use these services to interact with Cardano blockchain.

a. Get an instance of TransactionHelperService to build a payment or token mint transaction and submit to the Cardano network.

TransactionHelperService txnHelperService 
               = backendService.getTransactionHelperService();

b. Get an instance of FeeCalculationService to calculate the estimated fees of a transaction.

FeeCalculationService feeCalcService 
                        = backendService.getFeeCalculationService();

c. Get TransactionService to query the blockchain for a transaction id.

TransactionService txnService
                        = backendService.getTransactionService();

d. Get BlockService to get the block information from the blockchain.

BlockService blockService = backendService.getBlockService();

e. Get an instance of AssetService to get Asset details.

AssetService assetService = backendService.getAssetService();

f. Get an instance of UtxoService to fetch Utxos.

UtxoService utxoService = backendService.getUtxoService()

g. Get an instance of MetadataService to fetch metdata

MetadataService metadataService 
                        = backendService.getMetadataService();

6. Top-up your account with test Ada

If you are on Cardano testnet, you can get some Testnet Ada token from the Testnet faucet here.

Note: You can use Account api to create new testnet accounts.

7. Create your first Ada Payment Transaction

Now that we have some test Ada tokens, we can create a payment transaction to transfer Ada from funded account to another account.

PaymentTransaction paymentTransaction =
        PaymentTransaction.builder()
             .sender(senderAccount) //Sender Account object
             .receiver(receiver)   // Receiver baseAddress as String
             .amount(BigInteger.valueOf(1500000))
             .unit(CardanoConstants.LOVELACE)
             .build();

Note: In the above transaction, we are trying to send 1.5 Ada (1500000 Lovelace) from sender’s account to receiver’s account.

8. Get the latest slot information and then calculate TTL (Time To Live)

In the below code snippet, we are getting the latest block through BlockService and then adding 1000 to the current slot number to calculate TTL.

long ttl = blockService.getLastestBlock().getValue().getSlot() + 1000;

9. Create a TransactionDetailsParams Object, set TTL and calculate the estimated fee using FeeCalculation service

TransactionDetailsParams detailsParams =
        TransactionDetailsParams.builder()
                .ttl(ttl)
                .build();

BigInteger fee 
     = feeCalculationService.calculateFee(paymentTransaction, detailsParams, null); 

10. Set the fee in the transaction request object

Now that we have estimated fee for our transaction, let’s set it in our PaymentTransaction request object.

paymentTransaction.setFee(fee);

11. Submit Transaction to the Cardano network

To submit the transaction to the network, you need to use TransactionHelperService. TransactionHelperService will get the required Utxos and then create the inputs and outputs accordingly before sending the transaction request to the network. It also calculates the min-ada required for each outputs.

Result<String> result 
          = transactionHelperService.transfer(paymentTransaction, detailsParams);

If everything is ok, you should get the result success status as “true” and result value as “Transaction id”.

if(result.isSuccessful())
    System.out.println("Transaction Id: " + result.getValue());
else
    System.out.println("Transaction failed: " + result);

Now wait for sometime, so that the our transaction is mined.

You can now go to Cardano Testnet Explorer to check the transaction details.

12. Transfer Native Token

To transfer native tokens from one account to another, you need to use the same PaymentTransaction api to build the native token transfer request and set the native token’s asset id in the “unit” field of the payment request. Other steps are exactly same.

PaymentTransaction paymentTransaction =
        PaymentTransaction.builder()
                .sender(senderAccount)
                .receiver(receiver)
                .amount(BigInteger.valueOf(3000))
                .unit("d11b0562dcac7042636c9dbb44897b38.......")
                .build();

//Calculate Ttl = Latest slot + 1000
long ttl = blockService
              .getLastestBlock().getValue().getSlot() + 1000;
TransactionDetailsParams detailsParams =
        TransactionDetailsParams.builder()
                .ttl(ttl)
                .build();

//Calculate fee
BigInteger fee 
      = feeCalculationService.calculateFee(paymentTransaction,            detailsParams, null);

//Set fee
paymentTransaction.setFee(fee);

Result<String> result 
            = transactionHelperService.transfer(paymentTransaction, detailsParams);

Check also :

• Part II : Cardano-client-lib: Transaction with Metadata in Java — Part II
• Part III : Cardano-client-lib: Minting a new Native Token in Java — Part III

Resources

• Cardano-client-lib GitHub repository (https://github.com/bloxbean/cardano-client-lib)
• Example Source code (https://github.com/bloxbean/cardano-client-examples)

Full Source Code:

In this post, I am going to explain how to retrieve Blocks / Transactions / Events data from any Web3 compatible blockchain (Ethereum, Aion, …) and publish to Kafka topics in real-time.

Kafka Connectors ?

Kafka Connectors are ready to use components, which can be used to import data from external systems to Kafka topics and export data from Kafka topics to external systems. Kafka Connectors are written using Kafka Connect framework, which is a set of Java Api provided by Kafka to write a connector.

There are two types of Kafka connectors :

• Source Connector : To collect data from an external system and publish into a Kafka topic
• Sink Connector : To deliver data from a Kafka topic to an external system

Most of the time, you don’t need to write your own connector. You can check at Confluent Hub if a connector available for your external system.

Kafka Web3 Source Connector

I will go through a Source Connector implementation, “Kafka Web3 Source Connector”. The source for this project can be found at https://github.com/satran004/kafka-web3-connector .

You may want to check the source code of this project to know how to write your own Kafka connector.

This source connector implementation can read blockchain data from a Web3 Jsonrpc endpoint and publish Blocks / Transactions / Events data to any Kafka topic.

There are two source connector implementations in this project:

1. Block Source Connector : com.bloxbean.kafka.connectors.web3.source.blocks.BlockSourceConnector
2. Event Logs Connector : com.bloxbean.kafka.connectors.web3.source.events.EventSourceConnector

Block Source Connector

You can use “Block Source Connector” to fetch blocks or transactions data from a web3 jsonrpc endpoint of a blockchain (Example: Ethereum, Aion) and publish the json data to a topic.

It supports two scenarios:

• Publish Blocks with Transaction data to one Kafka topic
• Publish Blocks with transaction ids to one topic and transaction details to another topic.

Event Logs Connector

This source connector can be used to retrieve smart contract event logs from a web3 compatible blockchain through it’s web3 jsonrpc endpoint and publish to Kafka topics.

It supports following scenarios

• Publish all event logs to a Kafka topic
• Apply event log filters and publish only matching event logs to a Kafka topic

You can use these connectors both in standalone and distributed mode.

For simplicity, I am providing the configuration for standalone mode in this post. For distributed mode configuration, you can refer to the “config” folder of this project.

How to Run In Standalone Mode From Source

> Check out the source from https://github.com/satran004/kafka-web3-connector

> Install Java 1.8 (Minimum) , Maven, Kafka on your machine

> Start Kafka server

Compile and build the package

$> mvn clean package

Run Block Source connector to fetch blocks from web3 json rpc endpoint

You can find a sample configuration for Block Connector in standalone mode under “config” folder. Here’s a sample configuration to fetch blocks from Aion blockchain. Similar configuration can be found for Ethereum blockchain under the same folder.

• Replace proper value for web3_rpc_url, start_block.
• If you want to publish blocks and transactions in to separate topics, update topic & transaction_topic properties accordingly. Otherwise, you can comment transaction_topic property.

Edit “config/connector-web3-blocks-source.properties”

###### connector-web3-blocks-source.properties   ######

name=bloxbean-web3-source-connector

connector.class=com.bloxbean.kafka.connectors.web3.source.blocks.BlockSourceConnector

tasks.max=1

web3_rpc_url=http://<host>:8545

topic=aion-blocks

#To publish transactions with blocks, comment the below line. #Otherwise, transactions will be published to the following topic
transaction_topic=aion-transactions

#Comma separated list of ignored fields from Block object.
ignore_block_fields=logsBloom,extraData

#Comma separated ist of ignored field from Transaction object. #Supported options: input
ignore_transaction_fields=input

start_block=4721700
block_time=10
no_of_blocks_for_finality=0

To run,

> Set KAFKA_HOME environment variable

$> export KAFKA_HOME=<path_to_kafka_installation_folder>

$> $KAFKA_HOME/bin/connect-standalone.sh config/connect-standalone.properties config/connector-web3-blocks-source.properties

If everything is working as expected, the connector will start fetching blocks in real-time and you should be seeing similar logs

[2020-07-16 12:46:32,467] INFO WorkerSourceTask{id=bloxbean-web3-source-connector-0} Source task finished initialization and start (org.apache.kafka.connect.runtime.WorkerSourceTask:200)
[2020-07-16 12:46:32,537] INFO Cluster ID: ri4jhQhdTCuB7RuCMLjbhQ (org.apache.kafka.clients.Metadata:365)
[2020-07-16 12:46:32,928] INFO Successfully fetched block : 4729045  (com.bloxbean.kafka.connectors.web3.source.blocks.BlockSourceTask:94)
[2020-07-16 12:46:32,983] INFO Successfully fetched block : 4729046  (com.bloxbean.kafka.connectors.web3.source.blocks.BlockSourceTask:94)

Now check the kafka topic for published messages

$> $KAFKA_HOME/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic aion-blocks --from-beginning

Note: Make sure the topic name in the above command is same as the topic name mentioned in the connector configuration file.

Run Event Logs Source connector to fetch Event Logs from web3 json rpc endpoint

You can find a sample configuration for Event Log Connector in standalone mode under “config” folder. Here’s a sample configuration to fetch events from Aion blockchain. Similar configuration can be found for Ethereum blockchain under the same folder.

The below configuration fetches all delegation events from Aion Staking Pool Registry contract. Check event_logs_filter_address & event_logs_filter_topics properties.

• You can customize event_logs_filter_* values according to your requirement.
• Provide value for web3_rpc_url property.
• Update topic, start_block property if required.

Edit “config/connector-web3-blocks-source.properties”

name=bloxbean-web3-events-source-connector
connector.class=com.bloxbean.kafka.connectors.web3.source.events.EventSourceConnector
tasks.max=1

web3_rpc_url=http://<host>:8545

topic=web3-events

start_block=6117319
block_time=10
no_of_blocks_for_finality=0

####################################################################################
# The following options are only applicable for EventsSourceConnector
####################################################################################
event_logs_filter_addresses=0xa008e42a76e2e779175c589efdb2a0e742b40d8d421df2b93a8a0b13090c7cc8

event_logs_filter_topics=0x41445344656c6567617465640000000000000000000000000000000000000000

####################################################################################
# Target kafka topic's key
# Comma separated list of following options
# Options: blockNumber, logIndex, address, topic, transactionHash, transactionIndex
# Default: transactionHash,logIndex
####################################################################################
#event_logs_kafka_keys=

To run,

> Set KAFKA_HOME environment variable

$> export KAFKA_HOME=<path_to_kafka_installation_folder>

$> $KAFKA_HOME/bin/connect-standalone.sh config/connect-standalone.properties config/connector-web3-events-source.properties

Subscribe to the event Kafka topic to see the fetched event log data in real-time.

Run the connector in distributed mode

To run the Kafka web3 source connectors in distributed mode, you can download the connector jar from the release section of the project or from target folder (if you are building from source).

https://github.com/satran004/kafka-web3-connector/releases/

Links :

• Kafka Web3 Connector Project — https://github.com/satran004/kafka-web3-connector

In this post, I am going to explain how to use Spock Framework to unit test Java smart contract. Spock is a Groovy based testing framework and an alternative to the traditional JUnit framework. By making use of Groovy, Spock introduces new and expressive ways of testing Java applications.

In this post, we will be covering a basic Spock test and a test using Spock’s “Data Driven Testing” feature. To know more about Spock Framework, you can check Spock’s documentation.

Another goal of this post is to showcase how easily any existing JVM frameworks or tools can be used in Smart Contract development.

If you would like to know how to write and run JUnit test for your Java smart contract, you can check this blog written by Shidokth.

In short, Avm provides a JUnit rule called “AvmRule” which can be used to test contracts on an embedded Avm. We are going to use this class in this post.

The source code for this sample can be found over on GitHub.

a. Create a Java Contract Project

To create a Java smart contact project with IntelliJ IDE and BloxBean’s Aion4j Plugin, you can follow the steps on this Aion doc page.

In this post, we will be writing a very simple contract to demonstrate how to setup Spock unit test. We are going to create a smart contract which returns the sum of two numbers. I have intentionally kept it very simple, as the goal is to show case the usage of Spock framework for contract testing, not how to write Java contract.

b. Remove default generated smart contract files

Once you have created a new Java smart contract project in IntelliJ, you can remove the default generated contract “HelloAvm.java” (under src/main/java folder) and the corresponding test class, “HelloAvmRuleTest.java” (under src/test/java folder).

c. pom.xml change

1. Open pom.xml file and add the following dependencies for Spock framework.

<dependency>
    <groupId>org.spockframework</groupId>
    <artifactId>spock-core</artifactId>
    <version>1.3-groovy-2.4</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.codehaus.groovy</groupId>
    <artifactId>groovy-all</artifactId>
    <version>2.4.17</version>
    <scope>test</scope>
</dependency>

2. We need to include the gmavenplus plugin in order to be able to compile and run our Spock groovy test scripts. Add the following plugin in plugins section.

<build>
  <plugins>
    ...
    ...
    
    <plugin>
       <groupId>org.codehaus.gmavenplus</groupId>
       <artifactId>gmavenplus-plugin</artifactId>
       <version>1.5</version>
       <executions>
        <execution>
            <goals>
                <goal>compile</goal>
                <goal>testCompile</goal>
            </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

d. Create contract Java file

Create a new Java class for our contract under source package. Let’s call it “SumContract.java”.

Add the following content to the contract source file.

import org.aion.avm.tooling.abi.Callable;

public class SumContract {

    @Callable
    public static int sum(int i, int j) {
        return i + j;
    }
    
}

Note: Don’t replace the package section in the original file.

This contract has only one method “sum” which returns the sum of two numbers.

The @Callable annotation needs to be there for all public contract methods.

e. Contract main class in pom.xml

Update pom.xml to include SumContract class name as contract.main.class. To do that, edit <contract.main.class> element to include fully qualified SumContract class name.

Example:

<properties>
...

<contract.main.class>org.aion4j.avm.sample.SumContract</contract.main.class>

</properties>

e. Create test class

We will be using Groovy to write our Spock test script.

• Create a folder called “groovy” under src/test folder.
• Create a new Groovy script, “SumContractTest.groovy” under src/test/groovy folder.

Note: Please make sure that the test groovy class name ends with “Test”, so that the Spock test script will be picked up during test run by maven sunfire plugin.

• “SumContractTest” groovy class should extend spock.lang.Specification. Each Spock class must extend this in order to make the framework available to it.

class SumContractTest extends Specification {

}

• Let’s add AvmRule as a ClassRule in our test class. Define a setup() which will be running before every test method.

@ClassRule
@Shared
private AvmRule avmRule = new AvmRule(true);
private Address from;
private Address dappAddr;

def setup() {
    from = avmRule.getPreminedAccount();
    byte[] dapp = avmRule.getDappBytes(org.aion4j.avm.sample.SumContract, null);
    dappAddr = avmRule.deploy(from, BigInteger.ZERO, dapp).getDappAddress();
}

Spock understands @org.junit.ClassRule annotations on @Shared fields. In setup(), we are deploying our SumContract class to an embedded Avm. This method gets called before every test method run.

• Our first test method checks the sum of two numbers, 4 and 5.

def "4 plus 5 should be equal to 9"() {

    when:
        byte[] txData = ABIUtil.encodeMethodArguments("sum", 5, 4);
        AvmRule.ResultWrapper result = avmRule.call(from, dappAddr, BigInteger.ZERO, txData);
        int sum = Integer.parseInt(String.valueOf(result.getDecodedReturnData()));

    then:
        sum == 9;

}

In the above test method, there are two blocks with labels “when” and “then”.

Inside “when” block, we are
- Preparing method call transaction data
- Calling contract method through AvmRule.call()
- Getting the decoded result

Inside “then” block, the actual result is compared with the expected result.

According to Spock’s documentation,

Spock has built-in support for implementing each of the conceptual phases of a feature method. To this end, feature methods are structured into so-called blocks. Blocks start with a label, and extend to the beginning of the next block, or the end of the method. There are six kinds of blocks: setup, when, then, expect, cleanup, and where blocks. Any statements between the beginning of the method and the first explicit block belong to an implicit setup block.

In Spock, what we refer to as a feature is somewhat synonymous to what we see as a test in JUnit.

• Let’s write out second feature method. The second test shows one of the powerful feature of Spock called “Data Driven Testing”.

def "a plus b should equal to expected" (int a, int b, int expected) {

    given:
        byte[] txData = ABIUtil.encodeMethodArguments("sum", a, b);
        AvmRule.ResultWrapper result = avmRule.call(from, dappAddr, BigInteger.ZERO, txData);
        int sum = Integer.parseInt(String.valueOf(result.getDecodedReturnData()));

    expect:
        sum == expected

    where:
        a | b | expected
        4 | 6 | 10
        9 | 2 | 11
        23| 21| 44

}

Essentially, data driven testing is when we test the same behavior multiple times with different parameters and assertions. A example of this would be testing the sum operation. Depending on the various permutations of operands, the result will be different.

This test method takes three parameters a (first operand), b (second operand) and expected (expected sum value).

In “given” block, the transaction data is prepared and contract method is called through AvmRule.call().
In “expect” block, the returned result is compared with the expected value.
In “where” block, we are providing a datatable for our test with different operand pairs and corresponding expected results.

As we can see, we just have a straightforward and expressive Data table containing all our parameters. The test is expressive, with a human-readable name, and pure expect and where block to break up the logical sections.

This is one of the advantage of Spock when compared to JUnit because the way Spock implements parameterized testing.

Spock also has it’s own mocking framework. So in case you want to use mock/stubs inside your tests, you don’t need to use a separate mocking library.

Run Tests

• Build your project and run tests

You can now run “mvn clean install” to build and run your tests. You can also directly run these tests from IntelliJ’s editor.

In this post, we have just scratched the surface. For more info about Spock framework, you can check Spock’s documentation page.

Resources

1. Sample Code : https://github.com/satran004/avm-samples/tree/master/SumContract-spock-sample
2. Spoke Framework : http://spockframework.org/
3. AVM GitHub : https://github.com/aionnetwork/avm
4. BloxBean : https://www.bloxbean.com/
5. Avm Smart Contract with IntelliJ IDE: https://docs.aion.network/docs/intellij-plugin