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

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.

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

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'

For snapshot binaries

SNAPSHOT_VERSION : 0.8.0-SNAPSHOT (Please verify the latest snapshot 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>snapshots-repo</id>
            <url>https://central.sonatype.com/repository/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 {
    ...
    maven {
        url "https://central.sonatype.com/repository/maven-snapshots"
    }
}

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.