[Pre-Proposal] Substrate4J: Completing and Sustaining a Java Client for the Polkadot Ecosystem

[mhrsalehi]

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.

[mhrsalehi]

It’s been about six weeks since I posted this and I haven’t gotten any feedback. Not sure if that means people are fine with it, or if it just didn’t reach anyone, or if there’s no real interest in a Java client right now. Any of those would be good to know.

Before I submit this on-chain, I really need some feedback, on anything, amount, deliverables, retroactive part, whatever you think will help me a lot to decide what to do next.

[jobyreuben]

Not commenting on Substrate4j itself, but this post reminded me of a much bigger problem.

Polkadot is dead. Please move on.

Substrate isn’t. Substrate is genuinely great technology, probably Parity’s best innovations (yet a DSL only). And the funniest part is that Substrate is so neutral and portable that it may end up outliving the very ecosystem that created it.

To the OP: honestly, you may never get funding without the blessing of W3F, Parity, or the (same) people behind Chaos DAO. That’s just how this ecosystem has ended up working sadly. So if you’re waiting for the same people to validate and fund something whose value is ultimately Substrate itself, you might be waiting forever.

And we’ve seen the movie already over years.

Someone builds something → “this benefits Polkadot/Substrate” → treasury funding → resources get consumed → enthusiasm evaporates → project disappears/moves somewhere else → everyone pretends this was somehow a surprise.

Meanwhile Polkadot keeps losing users, transactions, liquidity and actual ecosystem gravity.

And the response?

“Okay, let’s build an even more technically impressive protocol.”

Now JAM.

Bro, we couldn’t get people to use the first version itself.

There is this weird collective refusal to accept that technical superiority (as brainwashed) doesn’t magically manufacture users, liquidity, applications or economic activity.

And that’s why I actually think Substrate has a better future than Polkadot.

To the OP: Build for the community. Don’t make the existence of your project conditional on getting a blessing from W3F, Parity or some treasury committee who handles a majority of the validators by themselves, acknowledging it as decentralized (the irony!).

Because the funny part is:

Your Substrate project might still be here after Polkadot is gone, JAM is forgotten, and everyone finally stops posting cope threads about “the next phase of the ecosystem”

At some point you have to stop watering the corpse and start looking at the useful parts left behind.

Polkadot can die. Substrate can live.

Reap the ashes.

[mhrsalehi]

It’s sad to say, but Polkadot does look like it’s dying, or at least stalling badly. Just look at the recent market: chains like Ethereum are up over 30% in the last month, while Polkadot has essentially gone nowhere over the same period. And it’s not just price, projects have been moving off Polkadot to other platforms.

You may well be right about W3F/Parity’s grip on governance, I honestly don’t know enough to say either way, but this is seems to be correct, Polkadot appears to be far more centralized in practice than I had assumed.

this part I can’t agree with more:

Meanwhile Polkadot keeps losing users, transactions, liquidity and actual ecosystem gravity.
And the response?
“Okay, let’s build an even more technically impressive protocol.”

In fact, that is close to the reason I started this project. At the time, there was no complete Java client for Polkadot, there still isn’t, aside from Substrate4j. I saw the cost of that gap firsthand at my last job, at a crypto exchange, where our entire stack was Java, which is the norm for most exchanges. Integrating Polkadot took noticeably more time and effort than it should have, purely because the tooling wasn’t there. In an industry that moves as fast as crypto, that kind of friction directly slows adoption and pushes users elsewhere, while other major blockchains had good Java support from early on.

So I don’t really understand the instinct to build an even more complex protocol when you haven’t managed to get people/developer to use the one you already have.

Maintaining and continuing this project is genuinely what I want to do, I built it from scratch single-handedly, and I’m proud of what it’s become, It was a real challenge, and this is why it matters to me. But maintaining something like this alone, with no support at all, is very hard to sustain long-term.

And it’s frustrating, honestly, to see so many projects get large treasury payouts and then quietly get abandoned, while something as fundamental as language tooling, and I think most people would agree it’s fundamental, gets ignored, not even a comment or a piece of feedback. I deliberately asked for far less than I think this is worth, specifically because of where Polkadot’s treasury currently stand, just to give this a realistic chance of being approved so I can keep working on it.

[jobyreuben]

I’m glad you’re agreeing with some of these uncomfortable truths.

And honestly, Substrate4J is exactly the kind of thing that should exist independently of Polkadot.

But then you look at where they’re taking JAM and it becomes difficult to take some of this seriously.

This whole “transactionless computation / pause and resume” thing is being presented like some magical new invention. Come on. Operating systems, runtimes and schedulers have been doing suspend/resume, continuations, coroutines, stack switching and similar things for decades.

The actual hard problem is making it deterministic, efficiently metered and practical at the protocol level. In my opinion its a fool’s errand (but Gavin sympathizers will still be in denial) like a Rube-Goldberg Machine. The underlying concept itself isn’t revolutionary (And that’s the ultimate reason they chose RISV over wasm - not some elaborate technical propaganda they are pushing btw)

And then we get to the funniest part: the memory footprint.

If you’re going to suspend computation and resume it later, obviously the relevant state has to exist somewhere. JAM validators need to keep this coherent state footprint in memory, so now we’re apparently going to solve the problem with a special token called JAMKB, representing the scarce state footprint.

And everyone knows the public reaction to JAMKB.

So now it’s:

new VM → new execution model → new memory model → new economics → new token.

And also I could state multitudes of technical reasons why JAM will be considered a joke for people who deeply understand systems design (not for the sympathizers at their central organization)

This is exactly what I mean when I say a wishful technical excellence doesn’t automatically translate into adoption. History will repeat itself and will never be merciful.

You have someone here who spent two years building the Java tooling that actual developers and exchanges can use, because he personally ran into the integration problem, and he’s struggling to even get feedback.

But apparently there’s plenty of energy available for inventing increasingly complicated protocol machinery (again fool’s errand) and then creating an economic system around the machinery.

And this is also why I wouldn’t build Substrate4J around the assumption that Parity-W3F funding will save it (I mean the treasury via proxies / benami such as ChaosDAO).

Because looking at the direction they’re taking, I honestly don’t think they’re planning to seriously invest in Substrate long-term. They are moving toward JAM.

So why would they fund the ecosystem around the thing they’re gradually moving away from?

Build Substrate4J for Substrate users, not for whoever happens to control the Polkadot treasury today.

And having said all that, I do sympathize with you.

Maintaining something this technically heavy, especially something you’ve built largely from scratch, is a massive burden. Two years of work, and tens of thousands of lines of code isn’t something you casually throw away (that too JAVA - should be a nightmare right?).

I hope you can talk directly with W3F or Parity and find out whether they actually have an interest in keeping this alive.

I’ve been through something similar myself. I built a completely new staking framework from scratch, the kind of thing I genuinely think would make some Parity devs jealous if they ever actually took the time to look at it.

But they won’t and they never will. Period.

And the mere fact that I got essentially no interest from the people who should have cared made me shift my focus away from a system that I increasingly saw as failing.

So I genuinely sympathize with you.

Don’t let their lack of interest convince you that the work has no value. It may just mean you’re building for people who are already moving on.

Polkadot can die. JAM can come and go.

Substrate is the part worth making survive.