Skip to content

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

License

Notifications You must be signed in to change notification settings

Kr1ptal/ethers-kt

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

❤️ Acknowledgements

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


Proof of Work: 0x6b0f9ff6f53ec22d8d2d92b1beb193cdc523628951b5c81779fabce9f51db351