Tezos Kotlin SDK

A Kotlin library to interact with the Tezos blockchain.

Use Cases

The Tezos Kotlin SDK ships with tools that can be used to:

General

• convert a Base58 encoded string to bytes and vice versa

Michelson/Micheline

• parse or create a Micheline JSON string
• pack and unpack Micheline
• convert Micheline to typed Michelson and vice versa

Operations

• create an unsigned or signed Tezos operation
• forge and unforge an operation
• sign an operation and verify the signature

RPC

• interact with a Tezos node
• estimate the operation fee

Contract

• read a contract's storage
• read BigMaps
• prepare contract calls

Modules Overview

The Tezos Kotlin SDK is a multi-module project. It has been designed to allow its users to use only the required minimum of functionality that meets their needs, thus optimizing the amount of redundant and unwanted code and dependencies. The library modules can be divided into 3 categories:

• Core
• Plugin
• Default Provider

Core Modules

The core modules are the basis for other modules. They are required for the SDK to work as expected.

Core Module	Description	Module Dependencies
:tezos-core	Provides base Tezos types and actions that can be performed on them.	✖️

Plugin Modules

The plugin modules are optional and come with additional functionality. They should be registered in the appropriate core components before use.

Plugin Module	Description	Module Dependencies
:tezos-michelson	Provides Michelson and Micheline types and actions, e.g. pack/unpack.	:tezos-core
:tezos-operation	Provides Tezos Operation structures as defined in the P2P message format and actions that can be performed on them, e.g. forge/unforge and sign/verify.	:tezos-core :tezos-michelson
:tezos-rpc	Provides a Tezos RPC client which should be used to interact with Tezos nodes.	:tezos-core :tezos-michelson :tezos-operation
:tezos-contract	Provides a Tezos contract handler which should be used to interact with Tezos contracts.	:tezos-core :tezos-michelson :tezos-operation :tezos-rpc

Default Provider Modules

The default provider modules are optional and come with default implementations of various components that can be provided externally.

Default Provider Module	Description	Module Dependencies
:tezos-crypto:bouncycastle	Uses BouncyCastle to satisfy the cryptographic requirements.	:tezos-core
:tezos-http:ktor	Uses Ktor to provide an HTTP client.	:tezos-rpc

Setup

To add the Tezos Kotlin SDK into your project:

1. Make sure the JitPack repository is included in your root build.gradle file:

Groovy

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

Kotlin

allprojects {
  repositories {
    ...
    maven("https://jitpack.io")
  }
}

2. Add the dependencies:

Groovy

dependencies {
  def tezos_version = "x.y.z"

  // REQUIRED, :tezos-core
  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-core:$tezos_version"

  // optional modules
  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-michelson:$tezos_version"
  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-operation:$tezos_version"
  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-rpc:$tezos_version"
  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-contract:$tezos_version"

  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-crypto-bouncycastle:$tezos_version"
  implementation "com.github.airgap-it.tezos-kotlin-sdk:tezos-http-ktor:$tezos_version"
  
  ---

  // alternatively, all modules
  implementation "com.github.airgap-it:tezos-kotlin-sdk:$tezos_version"
}

Kotlin

dependencies {
  val tezosVersion = "x.y.z"

  // REQUIRED, :tezos-core
  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-core:$tezosVersion")

  // optional modules
  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-michelson:$tezosVersion")
  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-operation:$tezosVersion")
  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-rpc:$tezosVersion")
  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-contract:$tezosVersion")

  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-crypto-bouncycastle:$tezosVersion")
  implementation("com.github.airgap-it.tezos-kotlin-sdk:tezos-http-ktor:$tezosVersion")
  
  ---

  // alternatively, all modules
  implementation("com.github.airgap-it:tezos-kotlin-sdk:$tezosVersion")
}

ProGuard and R8

The Tezos Kotlin SDK internally uses various libraries that may require custom ProGuard rules. If you are using ProGuard or R8, please follow the guides listed below to make sure your project works correctly with mentioned modules after obfuscation:

Module	Rules
:tezos-michelson	ProGuard rules for Kotlin Serialization
:tezos-rpc	ProGuard rules for Kotlin Serialization
:tezos-http:ktor	ProGuard rules for Kotlin Serialization

Documentation

A high level guide on how to use the library can be found in the docs. To try out the library in action, see the samples.

The code documentation can be build from the root of the project with the buildDocs Gradle task:

$ ./gradlew buildDocs 
> # output: build/docs