Package architecture decisions for a lightweight core?

[mpizenberg]

I’m currently using evolution-sdk in an application (https://github.com/mpizenberg/Tessera) and I’m trying to split out of the app the re-usable core parts for other applications implementing the cip-179 (there is at least one other). This includes types and pure functions. With all side effects moved outside of the cip-179 core.

It would be really valuable for this initiative to be able to re-use cardano types and important core functions, such as cbor codec and others. But without having the heavy Effect sub-dependencies.

Currently, depending on evolution sdk, pulls in 60MB of Effect ecosystem dependencies (@effect/cluster, @effect/sql, @effect/rpc, @effect/workflow, @effect/platform-node, ...). I don’t know the evolution sdk codebase, but is it possible that all of these dependencies are only needed for the IO parts, like the providers implementations and such?

It’s already good that tree shaking get rids of all that at compilation time, but I’m still always wanting to minimize the dependency surface, both for efficiency and for op-sec reasons. Let me know your thoughts about this.

[solidsnakedev]

Good question. From a quick look at the source, your instinct that the heavy deps live in the IO layer seems to line up:

• The pure core (CBOR codec, Address, Transaction, the schema/type modules, crypto) appears to import only effect core plus @noble/* and @scure/*. I didn't see any @effect/platform* in those files.
• @effect/platform shows up only in the provider internals (Kupo/Ogmios/Blockfrost/Koios), and they seem to go through the fetch-based FetchHttpClient.
• The @effect/cluster / @effect/rpc / @effect/sql / @effect/workflow surface looks like it traces back to @effect/platform-node (it pins them as peer deps, which npm 7+ auto-installs), rather than to the core itself.

So a couple of threads that might be worth exploring, if you want to dig in:

• Whether @effect/platform-node is actually needed by the published package, or whether the providers are self-contained on @effect/platform's fetch client.
• Whether the core (effect + noble + scure) could be consumed separately from the providers for a CIP-179 core, given the layering already seems to lean that way.

I haven't verified either fully, so take these as starting points rather than conclusions. Curious what you find if you look into it.

@emmanuel-musau you've been in this area lately, might be one you find interesting to look into.

[mpizenberg]

The "for op-sec reasons" is getting more and more real with the supply chain attacks hitting npm every odd day

[mpizenberg]

Any news on a split of the pure parts, with low dependency count, as a potential separate package?

[emmanuel-musau]

Some progress here: #532 drops three dependencies the package never imports, the main one being @effect/platform-node, which was pulling in the whole @effect/cluster / rpc / sql subtree (plus @parcel/watcher and its native binaries) through its peer dependencies. A fresh install goes from 55 resolved packages to 23, with no source or API change.

That leaves @effect/platform, which only the provider internals use. I'll follow up with the details of what splitting that off would involve.

[emmanuel-musau]

Follow up on the @effect/platform half.

Only 5 of the 222 files in the package touch @effect/platform, all of them provider internals. What forces it on everyone is sdk/client/internal/Providers.ts importing all four providers statically at the top — index.ts exports Client, Client pulls in Providers, so importing anything from the package root loads Blockfrost, Koios, Kupmios and Maestro whether you touch a provider or not. I tried making @effect/platform an optional peer dependency to confirm, and it breaks the root import for everyone rather than just provider users, so I left it alone.

If providers loaded on use instead of on import, the rest falls out without needing a separate package. I tested that tree: core-only resolves to 10 packages and ~49MB with no native binaries, and Address / CBOR work fine on it through the subpath imports.

Two ways to get there:

1. await import() inside Providers. Simple, but .withBlockfrost() and friends become async — breaking for anyone using a provider.
2. Keep the sync signature and move the import inside the returned Provider's methods. ProviderEffect is all Effect-returning and Provider is EffectToPromiseAPI<ProviderEffect>, so the work is already deferred and nothing in the public shape changes. More plumbing though — around nine methods across four providers, plus .effect and the promise path.

I'd go with 2, happy to take it on.

[mpizenberg]

I don’t think there is any advantage of trying to be smart with the imports in a single package, over breaking it into another providers package outside of core. It makes it simpler for people using the library to understand its dependency tree. It is a breaking change, but a clean one. And you might as well pack it with other improvements you might have in store for evolution-sdk.

[emmanuel-musau]

@solidsnakedev

[mpizenberg]

For example #539 could likely be a breaking change for the provider side of the package. One more reason to split it out of a core.

[solidsnakedev]

Thanks for pushing on this, the supply chain point is fair.

I'd rather keep a single package. #539 doesn't need a split: the Koios schemas are internal, so that fix changes no public API. And loading providers lazily only shrinks the install if @effect/platform becomes an optional peer, which breaks provider users who upgrade without adding it.

The simpler route is to drop @effect/platform entirely. The providers use it only as a fetch wrapper: three helpers in HttpUtils.ts on top of FetchHttpClient, plus one error class in Blockfrost. Rewriting those on the global fetch removes the dependency for everyone, with no API change. Together with #532, that gives every install the core-only tree @emmanuel-musau measured.

@emmanuel-musau, want to take that on once #532 lands?