A client library for Cardano in Java. This library simplifies the interaction with Cardano blockchain from a Java application.
Note: Some of the APIs mentioned in the below posts are deprecated. Please refer to the latest documentation for the latest APIs.
Cardano-client-lib examples repository
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 |
core-api | cardano-client-core-api | Contains core apis, model classes and utils Dependencies: common, transaction-spec |
plutus | cardano-client-plutus | Provides plutus specific apis and serialization implementation. Dependencies: common, common-spec |
annotation-processor | cardano-client-annotation-processor | Annotation processor for POJO <--> PlutusData. Dependencies: plutus |
quicktx | cardano-client-quicktx | Provides QuickTx TX builder APIs. A declarative API to build and submit transactions. Dependencies: core, function, backend |
function | cardano-client-function | Provides Composable Function Apis. A simple, flexible way to build transactions through re-usable functions. Dependencies: core |
coinselection | cardano-client-coinselection | Provides Coin selection algorithms. Dependencies: common, core-api |
cip | cardano-client-cip | A umbrella module which provides a simple way to get available cip implementations (cip25, cip8 etc.) Dependencies: cip8, cip20, cip25, cip27, cip30 |
cip8 | cardano-client-cip8 | CIP 8 - Message Signing Dependencies: common, crypto |
cip20 | cardano-client-cip20 | CIP 20 - Transaction message/comment metadata Dependencies: metadata |
cip25 | cardano-client-cip25 | CIP 25 - Media NFT Metadata Standard Dependencies: metadata |
cip27 | cardano-client-cip27 | CIP 27 - CNFT Community Royalties Standard Dependencies: cip25 |
cip30 | cardano-client-cip30 | CIP 30 - Cardano dApp-Wallet Web Bridge Dependencies: cip8, core |
cip67 | cardano-client-cip67 | CIP 67 - Asset Name Label Registry Dependencies: crypto, common |
cip68 | cardano-client-cip68 | CIP 68 - Datum Metadata Standard Dependencies: cip67, cip25, plutus, transaction-spec |
ogmios-supplier | cardano-client-ogmios-supplier | Provides Ogmios specific implementation for ProtocolParamsSupplier and TransactionProcessor. |
kupo-supplier | cardano-client-kupo-supplier | Provides Kupo specific implementation for UtxoSupplier. |
For Maven, add the following dependencies to project's pom.xml
<dependency>
<groupId>com.bloxbean.cardano</groupId>
<artifactId>cardano-client-lib</artifactId>
<version>0.5.1</version>
</dependency>
<!-- For Blockfrost backend -->
<dependency>
<groupId>com.bloxbean.cardano</groupId>
<artifactId>cardano-client-backend-blockfrost</artifactId>
<version>0.5.1</version>
</dependency>
<!-- For Koios backend -->
<dependency>
<groupId>com.bloxbean.cardano</groupId>
<artifactId>cardano-client-backend-koios</artifactId>
<version>0.5.1</version>
</dependency>
<!-- For Ogmios / Kupo backend -->
<dependency>
<groupId>com.bloxbean.cardano</groupId>
<artifactId>cardano-client-backend-ogmios</artifactId>
<version>0.5.1</version>
</dependency>
For Gradle, add the following dependencies to build.gradle
implementation 'com.bloxbean.cardano:cardano-client-lib:0.5.1'
//For Blockfrost
implementation 'com.bloxbean.cardano:cardano-client-backend-blockfrost:0.5.1'
//For Koios
implementation 'com.bloxbean.cardano:cardano-client-backend-koios:0.5.1'
//For Ogmios / Kupo
implementation 'com.bloxbean.cardano:cardano-client-backend-ogmios:0.5.1'
SNAPSHOT_VERSION : 0.5.2-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://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
repositories {
...
maven {
url "https://oss.sonatype.org/content/repositories/snapshots"
}
}
implementation 'com.bloxbean.cardano:cardano-client-lib:{SNAPSHOT_VERSION}'
implementation 'com.bloxbean.cardano:cardano-client-backend-blockfrost:{SNAPSHOT_VERSION}'
This section highlights few key apis in the library. For detailed documentation, please visit Cardano Client Doc site.
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
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,
// 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
```java
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);
// 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());
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();
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);
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
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);
Prerequisites: Java 11
git clone https://github.com/bloxbean/cardano-client-lib.git
export JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF8
./gradlew clean build
export BF_PROJECT_ID=<Blockfrost Preprod network Project Id>
./gradlew :integration-test:integrationTest -PBF_PROJECT_ID=${BF_PROJECT_ID}
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.