esaulpaugh/ethers-kt

Async, high-performance Kotlin library for interacting with EVM-based blockchains. Targeting JVM and Android platforms.

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.
  • 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: RPC calls can be batched together in a single call, reducing the number of round trips to the server.

🚀 Quickstart

Note

ethers-kt API is not yet stable and might be subject to change. It will be stabilized in the 1.0.0 release.

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 "0.5.0"
}

// 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:0.5.0"))

    // 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:

• web3j
• ethers-rs
• reth
• ethers-js

---

Proof of Work: 0x6b0f9ff6f53ec22d8d2d92b1beb193cdc523628951b5c81779fabce9f51db351