Skip to content

Appkit: A Library for Java/Scala/Kotlin Development of Ergo Applications

License

Notifications You must be signed in to change notification settings

ergoplatform/ergo-appkit

Repository files navigation

Appkit: SDK for writing applications interacting with Ergo blockchain

Maven Central CI Publish a release

Contents

Introduction

Ergo is a resilient blockchain platform for contractual money. In addition to Bitcoin-like blockchain architecture Ergo provides advanced contractual capabilities based on eUTXO model, which are not possible in Bitcoin.

Because of these capabilities numerous decentralized applications become possible.

Ergo Applications can avoid centralization of trust and instead rely on trust-less truly decentralized protocols which are implemented using Ergo contracts deployed on Ergo blockchain.

By its very nature, Ergo applications are both decentralized and cross-platform ranging from web applications running in browsers, mobile applications running on Android and iOS, standalone applications executing on Linux, MacOS or Windows to services deployed in cloud servers.

That said, it is very desirable to provide consistent programming model and APIs to facilitate all those application scenarios and platforms.

Ergo Appkit has idiomatic Java API and is written in Java/Scala. It is a thin wrapper around core components provided by ErgoScript interpreter and Ergo protocol implementations which are written in Scala. This gives easy access to core Ergo functionality such as generalized signatures based on sigma protocols, data serializers, address encodings etc.

Appkit is published on maven repository and cross compiled to both Java 7 and Java 8+ jars.

Supported platforms (iOS, Android, Desktop)

Appkit has been successfully used on Android, iOS and Desktop platforms in following scenarios:

  1. Appkit is compatible with GraalVM - a novel next generation approach to implement software which is reusable across several programming languages and execution environments. For example if Node.js application is run on GraalVM, then it can use Appkit to interact with Ergo Blockchain (see motivation for using Graal below).

  2. Using Appkit, Ergo applications can be written in one of the languages supported by GraalVM (i.e. Java, JavaScript, C/C++, Python, Ruby, R) and using this library applications can communicate with Ergo nodes via unified API and programming model provided by Appkit.

  3. Appkit based Ergo applications can be compiled into native code using native-image ahead of time compiler and then executed without Java VM with very fast startup time and lower runtime memory overhead compared to a Java VM. For example this allows to create very responsive command line utility applications such as ergo-tool.

  4. Appkit is used in Ergo Wallet App and hence can be used to develop Andoid, iOS and Desktop applications.

Setup

Maven

Appkit is Java/Scala library which is cross compiled by both Scala 2.11 and Scala 2.12 compilers. As a result it can run on JVMv7/Android (when it is built with Scala 2.11) and JVMv8 and above (when it is built with Scala 2.12).

Appkit is released on Maven Central and you can add it to your project with SBT, Maven or Gradle:

Maven:

<dependency>
    <groupId>org.ergoplatform</groupId>
    <artifactId>ergo-appkit_2.12</artifactId>
    <version>4.0.9</version>
</dependency>

Gradle:

 implementation 'org.ergoplatform:ergo-appkit_2.12:4.0.9'

(other examples on the Maven Central page).

As an alternative, you can download the jar file from the releases page and add it to your project manually.

Building locally

See Build instructions.

Using from non-JVM languages

GraalVM

In addition to Java, Appkit can be used to write Ergo applications in Scala, JavaScript, Python and Ruby and run those applications under GraalVM, which support cross language interoperability. Please see examples, Build instructions Java and GraalVM and GraalVM instructions.

Python

From Python, you can also use Appkit running in JVM context. Guide how to use Appkit from Python by bridging with JPype, or simply by using

 pip install ergpy

See ergpy project page for more information.

How to use

Using from JVM

Python

Repository organization

sub-module description
common Used in all other submodules and contain basic utility classes
java-client-generated Typed REST Java client generated from Swagger definition of Ergo node API
lib-api All Appkit Java interfaces which can be implemented elsewhere
lib-impl Implementation of Appkit interfaces using java-client-generated to connect to Ergo API
examples collection of simple Appkit example applications

Build locally

Build instructions Java and GraalVM

Projects that use Appkit

Appkit is a foundational non-opinionated library which can be used to create other libraries, Apps and tools. Here is the list of projects which use Appkit.

  • Official Ergo Wallet App - a cross-platform wallet for Ergo supporting Android, iOS (via RoboVM) and Desktop (via Kotlin Compose). Can be used as an example of cross-platform application using Appkit.
  • SigmaFi - A Decentralized P2P Financial Contracts on the Ergo blockchain.
  • ErgoMixer - a web application for mixing ergs and tokens based on Ergo platform
  • ergo-playgrounds - Run contracts + off-chain code in the browser
  • ErgoGravity - provides the required tools for Ergo platform to be integrated with Gravity network (gateway-proxy, ergo-susy-proxy, ergo-luport-executor, startup-script)
  • ergo-tool - a Command Line Interface application for Ergo
  • ergo-appkit-examples - Ergo Appkit Examples
  • ergo-android - Example Android application
  • ergo-faucet - A tool for gain some test tokens or Erg in mainnet or testnet network - ErgoFaucet is available here
  • ergo-jde - JSON dApp Environment (JDE)
  • Kiosk - a library on top of Ergo-Appkit for interacting with the Ergo Blockchain
  • ergo-mixer-demo - a non-interactive (and non-custodial) mixing scheme on top of the Ergo Platform blockchain
  • ergo-subpooling - a smart contract based mining pool for smaller miners and groups of friends
  • GetBlok-Plasma - An Ergo-Appkit based library providing an abstraction layer to easily interact with AVL Trees as an L2 Solution
  • ergo-python-appkit
  • scala-play-next-ergo - Scala Play with Ergo Appkit and NextJs
  • Add your project here by creating a PR