cardano-foundation/hydra-java

Incubation project for Java client for Hydra L2 solution.

hydra-java

This is an incubator project, which simplifies working with Hydra from java applications. Hydra is an isomorphic state machine L2 network, which works seamlessly with Cardano.

Hydra

You can access documentation regarding Hydra here: https://hydra.family/head-protocol/. We recommend especially to follow QuickStart on devnet network (https://hydra.family/head-protocol/docs/getting-started/quickstart) and (https://hydra.family/head-protocol/docs/getting-started/demo/with-docker) as well as reading (https://hydra.family/head-protocol/docs/tutorial/using_hydra/using-hydra-part-3)

Hydra API specs: https://hydra.family/head-protocol/api-reference

Hydra State Machine Diagram: https://hydra.family/head-protocol/core-concepts/behavior

Requirements

• JDK17
• maven3

Building

git clone https://github.com/cardano-foundation/hydra-java
cd hydra-java
mvn clean install

Running integration tests

mvn clean verify -P with-integration-tests

Version Compatibility Matrix

Hydra Version	Library Version	Cardano Client Library Version	JDK VERSION
0.10.x	0.0.6	0.4.x	JDK 11
0.10.x	0.0.7	0.5.x	JDK 11
0.10.x	0.0.8	0.5.x	JDK 11
0.13.x	0.0.9	0.5.x	JDK 17
0.13.x	0.0.10	0.5.x	JDK 17

Dependency

<dependencies>
    <dependency>
        <groupId>org.cardanofoundation</groupId>
        <artifactId>hydra-java-core</artifactId>
        <version>0.0.10</version>
    </dependency>
    <dependency>
        <groupId>org.cardanofoundation</groupId>
        <artifactId>hydra-java-client</artifactId>
        <version>0.0.10</version>
    </dependency>
    <dependency>
        <groupId>org.cardanofoundation</groupId>
        <artifactId>hydra-java-cardano-client-lib-adapter</artifactId>
        <version>0.0.10</version>
    </dependency>
    <dependency>
        <groupId>org.cardanofoundation</groupId>
        <artifactId>hydra-java-reactive-reactor-client</artifactId>
        <version>0.0.10</version>
    </dependency>
</dependencies>

Project Missing features / functionality

The current version may not contain exactly what you need. If there is a missing feature / functionality, we happily accept pull requests. Ideally please discuss with us the idea first, file an issue and let's agree on design of it. Should pull request not be possible we are open to do the work for you provided the github issue is raised and documented well enough to understand it.

Additional Docs

• CODE_OF_CONDUCT.md
• SECURITY.md
• CONTRIBUTING.md
• CHANGELOG.md

Modules

Submodule	Goal / Description
hydra-java-core	main classes / code
hydra-java-client	low level web socket client
reactive-reactor-client	experimental request / response high level reactive client (using reactor)
cardano-client-lib-adapter	bindings to BloxBean's cardano-client lib
test-containers-support	utilities to assist in testing via test containers project

Example usage (client)

For examples please refer to integration tests in hydra-java-client and hydra-java-reactive-reactor-client projects.

hydra-java's Issues

Integration test using yaci-cardano-test library (with test containers)

Ideally we should have an integration test with an example contract using both MerkleTree in the off-chain and on-chain.

Cut out release to maven central

More hydra-client level integration tests

• open a head, create smart contract transaction, e.g. to mint a token and redeem it (gift card contract)
• open a head, create a few transactions, reconnect with history = 0
• open a head, create a few transactions, reconnect with history = 1 and check replaying of all past events
• open a head and generate a few invalid transactions / commands and check if they are handled properly
• open a head mint NFT and try to close and move snapshot to L1
• open a head and using getUtxO request and response validate that we handle those properly

HydraWebClient and HydraReactiveWebClient are missing support to submit L1 transactions via hydra-node proxy

Write a tutorial how to work with a library.

JavaDocs

Introduce reactive hydra client to avoid callback hell

Currently hydra level client is 'classic' in a sense that it uses listeners to notify about events. We would like to introduce another module to this project based on JDK9 or project react / RxJava which makes it easier to work with even based system based on callbacks by introducing more high level data structures (e.g. Mono, Flux, CompletableFuture, Publisher, etc).

Remove cardano-cli from HydraDevNet

What?
Currently we are working directly with cardano-cli in HydraDevNet class in hydra-java-test-containers-support module. Once BloxBean's Cardano Client Lib is released with version 0.5 and suppliers:local module is merged in, the plan is to replace initialising of the network away from CLI with Yaci and local cardano-node.

Motivation
cardano-cli is a command like tool, which sometimes introduces backwards incompatible changes. It never promises to keep the cli switches interface as it is not a proper contract.

Move cardano-client-lib to bloxbean (using suppliers sub-module)

Reactive Hydra Client integration tests using HydraDevNet helper from hydra-java-test-containers-support project

Hydra 0.13.x support

Work started here: #45