Flow JVM SDK

The Flow JVM SDK is a library for JVM languages (e.g. Java, Kotlin) that provides utilities to interact with the Flow blockchain.

At the moment, this SDK includes the following features:

• Communication with the Flow Access API over gRPC
• Transaction preparation and signing
• Cryptographic key generation, parsing, and signing
• Marshalling & unmarshalling of JSON-Cadence
• DSL for creating, signing, and sending transactions and scripts

Installation

Use the configuration below to add this SDK to your project using Maven or Gradle.

Maven

<!--
    the following repository is required because the trusted data framework
    is not available on maven central.
 -->
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.nftco</groupId>
  <artifactId>flow-jvm-sdk</artifactId>
  <version>[VERSION HERE]</version>
</dependency>

Gradle

repositories {
    ...
    /*
        the following repository is required because the trusted data framework
        is not available on maven central.
    */
    maven { url 'https://jitpack.io' }
}

dependencies {
    api("com.nftco:flow-jvm-sdk:[VERSION HERE]")
}

Gradle (with test extensions)

plugins {
    ...
    id("java-test-fixtures")
}

repositories {
    ...
    /*
        the following repository is required because the trusted data framework
        is not available on maven central.
    */
    maven { url 'https://jitpack.io' }
}

dependencies {
    api("com.nftco:flow-jvm-sdk:[VERSION HERE]")
    testFixturesApi(testFixtures("com.nftco:flow-jvm-sdk:[VERSION HERE]"))
}

The jitpack.io repository is necessary to access some of the dependencies of this library that are not available on Maven Central.

Example usage

Check out the example repository for an example of how to use this SDK in a Java application.

Integration tests

Tests annotated with FlowEmulatorTest depend on the Flow Emulator, which is part of the Flow CLI to be installed on your machine.

TheFlowEmulatorTest extension may be used by consumers of this library as well to streamline unit tests that interact with the FLOW blockchian. The FlowEmulatorTest extension uses the local flow emulator to prepare the test environment for unit and integration tests. For example:

Setup dependency on the SDK:

plugins {
    id("java-test-fixtures")
}

repositories {
    /*
        the following repository is required because the trusted data framework
        is not available on maven central.
    */
    maven { url 'https://jitpack.io' }
}

dependencies {
    api("com.nftco:flow-jvm-sdk:[VERSION HERE]")
    
    // this allows for using the test extension
    testFixturesApi(testFixtures("com.nftco:flow-jvm-sdk:[VERSION HERE]"))
}

Write your blockchain tests:

@FlowEmulatorTest
class TransactionTest {

    @FlowTestClient
    lateinit var accessAPI: FlowAccessApi

    @FlowServiceAccountCredentials
    lateinit var serviceAccount: TestAccount

    @Test
    fun `Test something on the emnulator`() {
        val result = accessAPI.simpleFlowTransaction(
            serviceAccount.flowAddress,
            serviceAccount.signer
        ) {
            script {
                """
                    transaction(publicKey: String) {
                        prepare(signer: AuthAccount) {
                            let account = AuthAccount(payer: signer)
                            account.addPublicKey(publicKey.decodeHex())
                        }
                    }
                """
            }
            arguments {
                arg { string(newAccountPublicKey.encoded.bytesToHex()) }
            }
        }.sendAndWaitForSeal()
            .throwOnError()
        assertThat(result.status).isEqualTo(FlowTransactionStatus.SEALED)
    }
    
}

There are two ways to test using the emaultor:

• @FlowEmulatorProjectTest - this uses a flow.json file that has your configuration in it
• @FlowEmulatorTest - this creates a fresh and temporary flow configuration for each test

Also, the following annotations are available in tests as helpers:

• @FlowTestClient - used to inject a FlowAccessApi or AsyncFlowAccessApi into your tests
• @FlowServiceAccountCredentials - used to inject a TestAccount instance into your tests that contain the flow service account credentials
• @FlowTestAccount - used to automatically create an account in the emulator and inject a TestAccount instance containing the new account's credentials.

See ProjectTestExtensionsTest and TestExtensionsTest for examples.

Contribute to this SDK

This project is in the very early phase; all contributions are welcomed.

Read the contributing guide to get started.

Dependencies

This SDK requires Java Developer Kit (JDK) 8 or newer.

Credit

The Flow JVM SDK is maintained by @briandilley and @jereanon from The NFT Company.