Hi everyone!
What is Substrate4j?
Substrate4j is a Java client library for interacting with Substrate-based chains like Polkadot, comparable to Polkadot-API, Subxt, and Polkadot.js, but for the Java ecosystem. I can say, without exaggeration, that it’s the most complete Java client available for the ecosystem today.
Links: forum post · project repo
I’ve been working on this project for the last two years: over 630 commits and more than 66,000 lines of code (excluding blank lines, comments, and generated client code). Lines of code isn’t a meaningful metric on its own, I just want to give a sense of the time and effort that has gone into this.
The library itself is essentially feature-complete. What’s left is API stabilization, some final polish, and, most importantly, documentation. To get it across the finish line and keep the project alive afterward, I need support from the community.
Why Substrate4j?
Solid tooling in every major language is one of the things that makes a blockchain ecosystem easy to build on. Java is one of the most widely used languages in the world, yet Polkadot has never had a complete, actively maintained Java client. A few attempts have been made over the years, but each was either abandoned early or never grew past a partial implementation. Other major blockchains, by contrast, have long had a solid, well-maintained Java client of their own.
Substrate4j aims to close that gap. Here’s how it compares to the existing options in Java:
| Substrate4j | polkaj | substrate-client-java | substrate-client-kotlin | Jot | |
|---|---|---|---|---|---|
| Last commit (maintenance) | last week | 5 years ago | 4 years ago | 5 years ago | 9 months ago |
| Generated full runtime |  |
 |
|
|
|
| Pure Java cryptography | |
|
|
|
|
| Supports new Polkadot JSON-RPC spec | |
|
|
|
|
-
Generated, full-runtime APIs Substrate4j’s entire runtime layer (types, storage, extrinsics, events, constants) is generated directly from chain metadata instead of handwritten. This means full runtime coverage out of the box, and much lower long-term maintenance, since supporting a runtime upgrade or a new chain is a matter of regenerating code, not rewriting by hand.
-
Pure Java cryptography Unlike other options, Substrate4j has zero native (JNI) dependencies. All the required cryptography, including Merlin and Schnorrkel, Cryptographic key pairs and BIP-39, was ported from Rust to pure Java, tested against the original upstream test suites. This keeps the library truly platform-independent and as simple to use as adding a single Maven dependency, with no native toolchain required.
-
New Polkadot JSON-RPC spec Substrate4j is the only Java client built on the new JSON-RPC spec, while every comparable tool still relies on the legacy API. This isn’t just about future-proofing: the new spec is what light clients like Smoldot were actually designed around, so Substrate4j is positioned to get the most out of light client usage without the friction the old protocol imposes.
Together, these mean Substrate4j isn’t just another partial Java option or a prototype, it puts Java on par with the few languages, like Rust, JavaScript and Dart, that already have a feature-rich, generated full runtime and well-maintained client.
The proposal
The main reason I’m posting this is to get community feedback before I submit a formal proposal, this is my first time going through this process, and I’d rather get input early than guess wrong.
The biggest open question for me is structure. Two years of work already went into getting Substrate4j to where it is today, but I’m new to this community and don’t have a track record here yet, so I’m hesitant to ask for retroactive funding for that work outright, it doesn’t feel like the right way to introduce myself. At the same time, the work is real and delivered, so I’d rather be upfront about wanting some recognition for it than pretend it doesn’t factor in.
What I’m confident asking for is a milestone-based proposal to finish what’s left: documentation, examples, outstanding bugs, and API stabilization. Whether some retroactive compensation can reasonably be folded into that same proposal is genuinely something I want the community’s take on, rather than something I want to just assume.
Deliverables & Scope
| # | Deliverable | Description |
|---|---|---|
| 1 | Documentation | API reference, getting-started guide, and usage docs covering core modules |
| 2 | Examples | A set of runnable example projects covering common use cases: querying storage, submitting extrinsics, subscribing to events. |
| 3 | API Stabilization | Review and finalize public API surface, fix outstanding bugs. |
| 4 | Implement and publish a Gradle plugin to generate the runtime from metadata | A Gradle plugin that connects to a node (or reads a metadata file) and generates a typed Substrate4j client for any chain at build time, so users can target any Substrate-based chain without waiting on a published client for it. Published on the Gradle Plugin Portal with a clean plugins { id(...) } integration and proper incremental build support. |
| 5 | Implement and publish a Maven plugin to generate the runtime from metadata | The same codegen capability, packaged as a standard Maven plugin (Mojo) for users on Maven-based projects. Published to Maven Central so it can be added directly via pom.xml plugin coordinates. |
Costs
Given that I’m new here and mindful of where the treasury and OpenGov stand right now, I’m also open to pricing this below the standard rate if that improves the odds of it landing well with the community. I care more about being able to keep working on and maintaining this project long-term than about maximizing this particular ask.
With all of that said, my proposed amount for the goals outlined above, including some retroactive compensation, is 30,000 USD. I believe this is a conservative request considering what has already been delivered, the project’s scope and maturity, the significant time and engineering effort invested, and the funding awarded to comparable projects. In my view, the amount does not fully reflect the work that has gone into building Substrate4J, but instead represents a pragmatic figure intended to support its continued development and maintenance.
That said, this number is intentionally on the lower end, chosen to maximize the odds of community acceptance and keep the project moving forward, not to reflect what I think the work is strictly worth. I see this figure as a basis for discussion, not a fixed demand, and I’d genuinely appreciate feedback on both the amount and the structure before I move to a full proposal.
Closing thoughts
I know the Polkadot ecosystem has seen tooling projects that started strong and then faded once the initial grant ran out. I don’t think pointing that out is unfair, it’s a real pattern, and it’s exactly the risk anyone reading this should be weighing. What I’d ask you to weigh against it is nearly two years of sustained, unfunded work, demonstrated by the commit history, rather than a promise of what I might build.
Java is one of the dominant languages in enterprise software, yet today it remains the one major ecosystem language without a serious, actively maintained client for Substrate.
I’m not asking the community to fund a vision. I’m asking it to help sustain and continue a project that’s already largely built and proven through consistent execution. My goal is to ensure Substrate4J remains a maintained, production-ready piece of infrastructure rather than becoming another abandoned repository in the ecosystem.
I believe this is a fair and conservative request, and I genuinely welcome feedback on both the proposal and the funding amount. Thank you for taking the time to read it, and, if you find the case convincing, I’d greatly appreciate your support.