Skip to content

Gradle#

Gradle is a build tool used for many JVM languages and frameworks. You can use it to set up and build Java and Kotlin projects, both client-side (for desktop or Android) or server-side applications (for example Spring).

Setting up the Gradle project#

The first step is setting up a plain Gradle project. How exactly this is done depends on the platform or framework you want to base on.

  • Android: Install Android Studio and create a new project with your preferred language
  • Spring: Use the Spring Initializr to create a new project with your preferred language, don't forget to select Gradle. Open the project in the IDE of your choice
  • For other frameworks, refer to their setup or starter guide

When that is done, you will find one or more build.gradle files that define parameters of your project, most important the libraries your project depends on. Search for a dependencies block (for Android, it is in app/build.gradle, for Spring in the root-level file). You need to add appkit here. Don't get confused with the dependencies block inside buildscripts, that's not for the project dependencies, but for dependencies Gradle needs to build the project.

For desktop and server-side applications, it is just one line to add.

implementation ('org.ergoplatform:ergo-appkit_2.11:4.0.6')

When you resync your project now, Gradle fetches Appkit and all needed libraries and add them to your classpath.

Things are a bit more complicated when targeting Android. Some older Android versions run an older version of Java, and while Appkit itself is compatible, some of the libraries it uses are not. So you need some more steps to do:

Make sure core library desugaring is enabled by checking if the app's build.gradle file contains the needed dependency and option as described here

Additionally, you have to tell gradle to exclude the libraries that are not compatible with Android, but to use compatible versions instead. That is done by changing the line above like this:

implementation ('org.ergoplatform:ergo-appkit_2.11:4.0.6') {
    exclude group: 'org.bouncycastle', module: 'bcprov-jdk15on'
    exclude group: 'org.bitbucket.inkytonik.kiama', module: 'kiama_2.11'
}
// kiama needs an own build for JRE7 compatibility
implementation "com.github.MrStahlfelge.kiama:core_2.11:2.1.1"
implementation "com.github.MrStahlfelge.kiama:library_2.11:2.1.1"
implementation "org.bouncycastle:bcprov-jdk15to18:1.66"

And there you go!

What to start with#

Now you have Appkit enabled in your project, but what can you do now? Appkit provides methods for the following tasks:

  • Fetch data from Ergo Explorer API
  • Interact with Ergo Node, both public and private methods
  • Build transactions and sign them
  • Helper methods to handle cryptographics like calculating PK addresses from secrets

So it is up to your plans what you will use! That's why here is just a brief starter on these topics

Ergo Explorer API#

All data available on the Ergo Explorer is available through an API as well. Appkit ships with classes defining this API to use with Retrofit. Get started with the following Kotlin code:

val retrofit = Retrofit.Builder()
            .baseUrl(RestApiErgoClient.defaultMainnetExplorerUrl)
            .addConverterFactory(GsonConverterFactory.create())
            .build()

val ergoApiService = retrofit.create(DefaultApi::class.java)

You can call Explorer API methods on the ergoApiService now. Check out Retrofit's documentation on how to interact with it.

Interact with Ergo node, build transactions and sign them#

While Ergo Explorer is a central service to request information without the need to have the full blockchain, an Ergo node is part of the decentralized blockchain network. The node offers methods to the public, for example submitting a new transaction, while there are also private methods for its owner only to be used with an API key. These methods can be accessed through a BlockchainContext that you can obtain with the following code:

    val ergoClient = RestApiErgoClient.create(
        nodeApiAddress,
        NetworkType.MAINNET,
        "", // for private methods, give API key here
        RestApiErgoClient.defaultMainnetExplorerUrl
    )
    ergoClient.execute { ctx: BlockchainContext ->
        // do something here with the blockchain context
    }

How to obtain the node address? A few known peers are listed on the node configuration file. Make sure to use the correct port to connect to the node API, it is 9053 for Mainnet (e.g. http://213.239.193.208:9053/).

Of course, the most interesting part here is to sign and send transactions with smart contracts. See below for examples.

Helper methods#

Appkit provides a lot of helper methods to ease a developer's life and not reinvent the wheel that already is in use. For example, you can construct an Ergo address from a mnemonic, or an ErgoTree from an address. Check out the following classes and their inline documentation: Address, BoxOperations, ErgoProverBuilder, Mnemonic, Parameters

Examples#

These examples will help you get started and understand the concepts better.