A client library for Cardano in Java. This library simplifies the interaction with Cardano blockchain from a Java application.

Latest Stable Version

0.7.2

Preview Release

0.8.0-pre4 — Preview Documentation

Contributing - Branch Guidelines

We maintain three active branches for contributions. Please choose the appropriate branch based on the nature of your changes:

Development Branches

Branch	Purpose	Min. Java	What to Contribute
master	Next major release (0.8.0)	17+	New features, enhancements, breaking changes, and all documentation updates
release/0.7.x	Current stable release line	11+	Bug fixes and minor features (no breaking changes)
release/0.6.x	Maintenance only	11+	Critical bug fixes only

Contribution Guidelines

• For new features or breaking changes: Submit PRs to master
• For bug fixes (0.7.x compatible): Submit PRs to release/0.7.x
• For critical fixes (0.6.x): Submit PRs to release/0.6.x
• For documentation updates: Always submit to master (documentation site is published from master)

When in doubt about which branch to target, please open an issue for discussion or ask in our Discord.

More details --> Documentation

Recent Posts

• Introducing QuickTx API to build transactions
• Composable functions to build transactions
• Demo:- Test Aiken Smart Contract Using Java Offchain Code with Yaci DevKit

Tutorials

• Simple Ada transfer
• Multisig transfer using Native Script
• Governance Api

Old Posts

Note: Some of the APIs mentioned in the below posts are deprecated. Please refer to the latest documentation for the latest APIs.

• Call Plutus V2 contract from off-chain Java code
• Cardano-client-lib : A Java Library to interact with Cardano - Part I
• Cardano-client-lib: Transaction with Metadata in Java - Part II
• Cardano-client-lib: Minting a new Native Token in Java - Part III

Examples

Cardano-client-lib examples repository

JavaDoc

Modules

In 0.4.0 and later, the library has been divided into smaller modules. These modules can be added to a project based on requirement.

Group Id: com.bloxbean.cardano

For simple setup, you can use cardano-client-lib and one of the backend provider as dependency.

Modules	Artifact Id	Description
cardano-client-lib	cardano-client-lib	This is a top level module which includes all other modules except backend provider modules. (Recommended for most applications)
Backend Api	cardano-client-backend	Defines backend apis which are implemented by provider specific module.
Blockfrost Backend	cardano-client-backend-blockfrost	Provides integration with Blockfrost
Koios Backend	cardano-client-backend-koios	Provides integration with Koios
Ogmios/Kupo Backend	cardano-client-backend-ogmios	Provides integration with Ogmios and Kupo. Supported Apis : submitTransaction, evaluateTx, Kupo support (UtxoService)

For fine-grained dependency management, add one or more below modules as required.

Modules	Artifact Id	Description
common	cardano-client-common	Contains common utilities (HexUtil, JsonUtil, Cbor Utils etc). This module doesn't depend on any other module. Dependencies: None
crypto	cardano-client-crypto	Provides implementation for standards like Bip32, Bip39, CIP1852 and other crypto primitives Dependencies: common
address	cardano-client-address	Supports derivation of various types of Cardano addresses (Base, Enterprise, Pointer, Stake etc) Dependencies: common, crypto, common-spec
metadata	cardano-client-metadata	Provides simple api to generate and serialize generic metadata Dependencies: common, crypto
common-spec	cardano-client-common-spec	A small module with some common serialization classes (CDDL spec) Dependencies: common, crypto
transaction-spec	cardano-client-transaction-spec	Provides cbor serialization code for transactions (CDDL spec). Dependencies: common, common-spec, crypto, address, metadata, plutus
core	cardano-client-core	Cointains few common api like Account. Also contains high-level api like PaymentTransaction for backward compatibility. Dependencies: common, crypto, common-spec, address, metadata, transaction-spec, core-api, plutus, coinselection

Use as a library in a Java Project

For release binaries

For Maven, add the following dependencies to project's pom.xml

• Core module

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

• Backend modules
  • For backend support, use one of the following supported backend module

        <!-- For Blockfrost backend -->
        <dependency>
            <groupId>com.bloxbean.cardano</groupId>
            <artifactId>cardano-client-backend-blockfrost</artifactId>
            <version>0.7.1</version>
        </dependency>
        
         <!-- For Koios backend -->
        <dependency>
            <groupId>com.bloxbean.cardano</groupId>
            <artifactId>cardano-client-backend-koios</artifactId>
            <version>0.7.1</version>
        </dependency>
        
         <!-- For Ogmios / Kupo backend -->
        <dependency>
            <groupId>com.bloxbean.cardano</groupId>
            <artifactId>cardano-client-backend-ogmios</artifactId>
            <version>0.7.1</version>
        </dependency>

For Gradle, add the following dependencies to build.gradle

• Core Module

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

• Backend modules
  • For backend support, use one of the following supported backend module

//For Blockfrost
implementation 'com.bloxbean.cardano:cardano-client-backend-blockfrost:0.7.1'

//For Koios
implementation 'com.bloxbean.cardano:cardano-client-backend-koios:0.7.1'

//For Ogmios / Kupo
implementation 'com.bloxbean.cardano:cardano-client-backend-ogmios:0.7.1'

From 0.8.0-pre6 on, releases from master are also in the BloxBean Maven repository, https://repo.bloxbean.org/maven/releases, with the same files as on Maven Central.

For snapshot binaries

Development snapshots are in the BloxBean Maven repository, https://repo.bloxbean.org/maven/snapshots. They use master's snapshot version (the version in gradle.properties); each publication adds a newer timestamped build of that version, which Maven and Gradle resolve.

SNAPSHOT_VERSION : the version on the snapshot badge at the top (master's version in gradle.properties)

• For Maven, add the following dependencies and repository to project's pom.xml

    <dependencies>
        <dependency>
            <groupId>com.bloxbean.cardano</groupId>
            <artifactId>cardano-client-lib</artifactId>
            <version>{SNAPSHOT_VERSION}</version>
        </dependency>
        <dependency>
            <groupId>com.bloxbean.cardano</groupId>
            <artifactId>cardano-client-backend-blockfrost</artifactId>
            <version>{SNAPSHOT_VERSION}</version>
        </dependency>
    </dependencies>
    
    <repositories>
        <repository>
            <id>bloxbean-snapshots</id>
            <url>https://repo.bloxbean.org/maven/snapshots</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

• For Gradle, add the following dependencies and repository to build.gradle

repositories {
    mavenCentral()
    maven {
        url = uri('https://repo.bloxbean.org/maven/snapshots')
        mavenContent { snapshotsOnly() }
    }
}

dependencies {
    implementation 'com.bloxbean.cardano:cardano-client-lib:{SNAPSHOT_VERSION}'
    implementation 'com.bloxbean.cardano:cardano-client-backend-blockfrost:{SNAPSHOT_VERSION}'
}

Usages

This section highlights few key apis in the library. For detailed documentation, please visit Cardano Client Doc site.

Account API Usage

• Create a New Account

Account account = new Account();   //Create a Mainnet account

Account account = new Account(Networks.mainnet());   //Create a Mainnet account

Account account = new Account(Networks.testnet());  //Create a Testnet account

• Get base address, enterprise address, mnemonic

String baseAddress = account.baseAddress();  //Base address at index=0

String enterpriseAddress = account.account.enterpriseAddress();  //Enterprise address at index = 0

String mnemonic = account.mnemonic();  //Get Mnemonic

• Get Account from Mnemonic

String mnemonic = "...";
Account account = new Account(mnemonic);  //Create a Mainnet account from Mnemonic

Account account = new Account(Networks.testnet(), mnemonic); //Create a Testnet account from Mnemonic

Create Backend Service

//For Blockfrost
BackendService backendService =
                new BFBackendService(Constants.BLOCKFROST_TESTNET_URL, <BF_PROJECT_ID>);               

// For Koios
// BackendService backendService = new KoiosBackendService(KOIOS_TESTNET_URL);
        
FeeCalculationService feeCalculationService = backendService.getFeeCalculationService();
TransactionHelperService transactionHelperService = backendService.getTransactionHelperService();
TransactionService transactionService = backendService.getTransactionService();
BlockService blockService = backendService.getBlockService();
AssetService assetService = backendService.getAssetService();
UtxoService utxoService = backendService.getUtxoService();
MetadataService metadataService = backendService.getMetadataService();
EpochService epochService = backendService.getEpochService();
AddressService addressService = backendService.getAddressService();

Simple ADA Payment using QuickTx Api

        Tx tx1 = new Tx()
                .payToAddress(receiver1Addr, Amount.ada(1.5))
                .payToAddress(receiver2Addr, Amount.ada(2.5))
                .attachMetadata(MessageMetadata.create().add("This is a test message 2"))
                .from(sender1Addr);

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

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

Simple ADA Payment using Composable Functions Api

        // Define expected Outputs
        Output output1 = Output.builder()
                .address(receiverAddress1)
                .assetName(LOVELACE)
                .qty(adaToLovelace(10))
                .build();

        Output output2 = Output.builder()
                .address(receiverAddress2)
                .assetName(LOVELACE)
                .qty(adaToLovelace(20))
                .build();

        // Create a CIP20 message metadata
        MessageMetadata metadata = MessageMetadata.create()
                .add("First transfer transaction");

        // Define TxBuilder
        TxBuilder txBuilder = output1.outputBuilder()
                .and(output2.outputBuilder())
                .buildInputs(createFromSender(senderAddress, senderAddress))
                .andThen(metadataProvider(metadata))
                .andThen(balanceTx(senderAddress, 1));
        
        UtxoSupplier utxoSupplier = new DefaultUtxoSupplier(backendService.getUtxoService());
        ProtocolParamsSupplier protocolParamsSupplier = new DefaultProtocolParamsSupplier(backendService.getEpochService());

        //Build and sign the transaction
        Transaction signedTransaction = TxBuilderContext.init(utxoSupplier, protocolParamsSupplier)
                .buildAndSign(txBuilder, signerFrom(senderAccount));

        //Submit the transaction
        Result<String> result = backendService.getTransactionService().submitTransaction(signedTransaction.serialize());

ScriptHash

Example: 1

ScriptPubkey scriptPubkey = new ScriptPubkey("ad7a7b87959173fc9eac9a85891cc93892f800dd45c0544128228884")
String policyId = scriptPubkey.getPolicyId();

Example: 2

ScriptPubkey scriptPubkey1 = ...;
SecretKey sk1 = ...;

ScriptPubkey scriptPubkey2 = ...;
SecretKey sk2 = ...;

ScriptPubkey scriptPubkey3 = ...;
SecretKey sk3 = ...;

ScriptAtLeast scriptAtLeast = new ScriptAtLeast(2)
                .addScript(scriptPubkey1)
                .addScript(scriptPubkey2)
                .addScript(scriptPubkey3);

String policyId = scriptAtLeast.getPolicyId();

Metadata

MetadataMap productDetailsMap = MetadataBuilder.createMap()
                .put("code", "PROD-800")
                .put("slno", "SL20000039484");

MetadataList tagList = MetadataBuilder.createList()
                .add("laptop")
                .add("computer");

Metadata metadata = MetadataBuilder.createMetadata()
                .put(new BigInteger("670001"), productDetailsMap)
                .put(new BigInteger("670001"), productDetailsMap);

UtxoSelectionStrategy in High Level Api

The utxo selection strategy can be changed by providing a custom implementation of UtxoSelectionStrategy interface. By default, the transaction builder apis use DefaultUtxoSelectionStrategyImpl which finds all required utxos sequentially. But it may not be efficient for some use cases.

You can use a custom or different implementation of UtxoSelectionStrategy to change the default utxo selection behaviour. Out-of-box, the library provides two additional implementations of UtxoSelectionStrategy

• LargestFirstUtxoSelectionStrategy
• RandomImproveUtxoSelectionStrategy

UtxoSupplier, ProtocolPramsSupplier

You can get UtxoSupplier and ProtocolParamsSupplier from the backend service. Alternatively, you can create your own UtxoSupplier, ProtocolParamsSupplier and use it in the transaction builder api.

UtxoSupplier utxoSupplier = new DefaultUtxoSupplier(utxoService);
ProtocolParamsSupplier protocolParamsSupplier = new DefaultProtocolParamsSupplier(epochService);

Build from source and run integration tests

Prerequisites: Java 17+

Build

git clone https://github.com/bloxbean/cardano-client-lib.git

export JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF8
./gradlew clean build

Integration Tests

export BF_PROJECT_ID=<Blockfrost Preprod network Project Id>
./gradlew :integration-test:integrationTest -PBF_PROJECT_ID=${BF_PROJECT_ID}

Used by

• EASY1 Stake Pool Raffles
• Cardanotales
• Cardano Fans Raffles
• Cardano Fans Donation App
• adadomains.io
• ADAM - ADA Monitor APP
• ISR - Israeli Cardano Community
• MusicBox - CNFT Project
• Realfi.info - Portfolio Viewer
• nftio.io - NFT Explorer

Any questions, ideas or issues?

• Create a Github Discussion
• Create a Github Issue
• Discord Server

Sponsors :sparkling_heart:

Previous Sponsors :sparkling_heart:

If this project helps you reduce time to develop on Cardano or if you just want to support this project :

Support this project

Support from YourKit

YourKit has generously granted the BloxBean projects an Open Source licence to use their excellent Java Profiler.

YourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor.