ethers-kt

ethers-kt is an async, high-performance Kotlin library for interacting with EVM-based blockchains. It targets JVM and Android platforms.

Features:

High Performance: Optimized types and code to minimize the number of allocations and copying.
Clean Abstractions: Intuitive, extensible, and easy to use.
Async: RPC requests are async by default, with helper functions for awaiting results.
Safe: RPC calls return an error object in case of failure, instead of throwing an exception.
Smart contract bindings:
- Generate type-safe smart contract bindings from JSON-ABI files or from Foundry projects.
- Complete support: events (anonymous), custom errors, structs, receive and fallback functions.
- Custom errors can be resolved from any source (e.g. generated bindings, 4byte directory, etc...).
- Payable and non-payable functions/constructors.
Batch RPC calls:
- Batch JSON-RPC: RPC calls can be batched together in a single request, reducing the number of round trips to the server.
- Multicall: Aggregate multiple smart contract calls into a single call via Multicall3 contract.

🚀 Quickstart

All releases are published to Maven Central. Changelog of each release can be found under Releases.

It's recommended to define BOM platform dependency to ensure that ethers-kt artifacts are compatible with each other.

plugins {
    id("io.kriptal.ethers.abigen-plugin") version "1.2.1"
}

// default values
ethersAbigen {
    directorySource("src/main/abi")
    outputDir = "generated/source/ethers/main/kotlin"
}

// Define a maven repository where the library is published
repositories {
    mavenCentral()

    // for snapshot versions, use the following repository
    //maven { url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/") }
}

dependencies {
    // Define a BOM and its version
    implementation(platform("io.kriptal.ethers:ethers-bom:1.2.1"))

    // Define any required artifacts without version
    implementation("io.kriptal.ethers:ethers-abi")
    implementation("io.kriptal.ethers:ethers-core")
    implementation("io.kriptal.ethers:ethers-providers")
    implementation("io.kriptal.ethers:ethers-signers")
}

To interact with the chain, you need to create a Provider instance, which is the main entry point for all RPC calls.

// create a provider, using a websocket as underlying transport
val provider = Provider.fromUrl("<WS_URL>").unwrap()

// query the latest block number
val startBlockNum = provider.getBlockNumber().sendAwait().unwrap()
println("Starting at block $startBlockNum")

// subscribe to new blocks, blocking the calling thread. Use "forEachAsync" to stream without blocking the caller.
provider.subscribeNewHeads().sendAwait().unwrap().forEach {
    println("New Block: ${it.number}, ${it.number - startBlockNum} blocks since start")
}

📦 Structure

Code is structured into multiple modules, each categorized by its purpose. Below is a brief overview of each module. For a more in-depth explanation, please refer to the individual module's README.md.

abi: Provides ABI primitives with encoding/decoding logic for all types supported by the EVM.
abigen: Code for generating type-safe smart contract bindings from JSON-ABI files.
abigen-plugin: Gradle plugin for generating smart contract bindings during the build process.
core: Contains optimized base types.
crypto: Includes cryptographic utilities for signing and verifying ECDSA signatures on the secp256k1 curve.
ens: Full support for ENS names and avatars, with wildcard resolution and offchain resolution via CCIP-Read.
providers: Logic for interacting with JSON-RPC API using various transports (HTTP, WebSocket).
rlp: Handles the encoding and decoding of RLP.
signers: Code for transaction/message signing, allowing multiple signing key sources: hardware wallet, mnemonic or raw private key.

🙋‍♂️ Contributing

We are happy to have you here! Opportunities to get involved with ethers-kt are open to everyone, no matter your level of expertise. Please check the CONTRIBUTING.md to get started. To chat with fellow contributors, join our Discord channel.

Before submitting a PR make sure to format the code and run all checks using the following command:

./gradlew ktlintFormat check

Need help❓

First, check if any of the README files under each module answers your question. If the answer is not there please don't open an issue.

Instead, you can:

ask on Discord.
open a thread under Discussions.

❤️ Acknowledgements

This library has been made possible thanks to the inspiration provided by the following projects:

Proof of Work: 0x6b0f9ff6f53ec22d8d2d92b1beb193cdc523628951b5c81779fabce9f51db351

Kr1ptal / ethers-kt

readme