# protocol-monorepo: the contracts and SDKs behind Superfluid > The Superfluid protocol monorepo holds the Ethereum contracts, the JavaScript SDKs, the metadata package, the subgraph and a fuzzing harness in one repository, with a mix of AGPL and MIT terms across the packages. It suits developers building streaming payment or real-time finance applications on Ethereum. **superfluid-org/protocol-monorepo** — Superfluid Protocol Monorepo: the specification, implementations, peripherals and development kits. - Repository: https://github.com/superfluid-org/protocol-monorepo - Website: https://superfluid.org - Stars: 904 · Forks: 271 - Language: TypeScript - License: NOASSERTION - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/superfluid-org-protocol-monorepo ## What the protocol is trying to change about payments The stated goal is given in one sentence and it is a design position rather than a feature list. The Superfluid Protocol is a framework that realizes the real-time finance vision where user accounts are connected together, and transactions can happen between user accounts instantaneously as a result. Instantaneous is the operative word. The conventional model of a crypto payment is a transfer of a token from one address to another, which means the sender has to decide an amount and the recipient receives a lump sum at a moment in time. A real-time framework turns that into a stream, where a sender opens a flow and value moves continuously until it is closed, and the recipient sees the balance grow. The repository implements the protocol as Ethereum contracts and also contains a JavaScript SDK for developing Web3 applications using it. The published packages are named @superfluid-finance/ethereum-contracts, @superfluid-finance/metadata, @superfluid-finance/sdk-core, @superfluid-finance/sdk-redux, @superfluid-finance/hot-fuzz, @superfluid-finance/subgraph and @superfluid-finance/js-sdk. The ecosystem around it is linked from the readme, with the app, the documentation site and the homepage, and the project describes itself as the contracts and resources for the protocol rather than as a library, which is the right framing for a repository that contains a specification, implementations, peripherals and development kits at once. ## Seven packages with three different licences The package list is the clearest way to understand the project, and the licence split is the first thing to notice. The ethereum-contracts package carries the AGPL v3 badge and is described as the EVM contracts implementation for the Superfluid Protocol, with the invitation to peek under the hood in the contracts package if you are interested. The metadata package is MIT and holds contract addresses, subgraph URLs and other metadata for the protocol. The sdk-core package is MIT and is described as an application framework for interacting with the Superfluid Protocol without Solidity knowledge, which is a precise statement of who it is for. The sdk-redux package is also MIT and is an application framework for building front-end applications that interact with the protocol. The hot-fuzz package is AGPL v3 and is a wrapper of Echidna with additional helpers for fuzzing Superfluid smart contract applications, including Super Apps. The subgraph package is AGPL v3 and is the official subgraph for the protocol. The js-sdk package is MIT but is fully deprecated, with the instruction to use sdk-core instead and the last release available on a separate branch. So a front-end team and a contracts team in the same organisation are working under different licence terms, and the AGPL packages are the ones where a distribution question can arise. ## The JS SDK is retired in favour of sdk-core and sdk-redux The deprecation is handled explicitly, which saves anyone starting on this project from reading old tutorials. The js-sdk package is marked as fully deprecated with a warning to use sdk-core instead, and the last release of js-sdk is on a branch named release-js-sdk-stable. That naming tells you how the maintainers handle the transition, keeping a frozen branch so existing deployments keep working while new work goes to the replacement. The two successors cover different layers. sdk-core is the framework for interacting with the protocol without needing to write Solidity, which is the piece a backend or a script needs, and sdk-redux is the framework for building front-end applications that interact with the protocol, which is the piece a web application needs. Splitting them this way means a backend service that only needs to open a stream does not pull in a front-end state library, and it means a front-end team that has no backend can work entirely in the browser. The api surface of each is not described in the readme, so the practical way to assess them is the documentation site rather than the repository. ## Hardhat, truffle and a fairly heavy development stack The root package metadata shows how much machinery sits behind these packages, and it is a lot. The development dependencies include hardhat at a pinned 2.27.2 along with hardhat-deploy, hardhat-verify, hardhat-web3 and the chai matchers and ethers plugins for it. Truffle is also present at 5.11.5, which is unusual, and it comes with the HD wallet provider. Typechain and the hardhat typechain plugin generate contract bindings from the Solidity sources, and web3 and the ethers v5 typechain are both there, so the project supports two client stacks in parallel. The Solidity side is linted with solhint, the JavaScript with eslint using the typescript-eslint parser and a set of plugins including import and prettier, and the code is formatted with prettier and prettier-eslint. Coverage is handled by nyc and reported to codecov, and the packages carry their own coverage flags in the readme badges. The root package is private and names itself as a monorepo, and it pins the toolchain: ```json "name": "@superfluid-org/protocol-monorepo", "packageManager": "yarn@4.18.0", "private": true, ``` Lerna at 8.2.4 handles orchestration, and syncpack for keeping dependency versions consistent across the workspace, which is the tool that stops two packages in a monorepo from depending on incompatible versions of the same dependency. There is also a flake.nix and a default.nix for Nix users, a .devcontainer, husky for git hooks and a shellcheckrc for shell scripts. ## Fuzzing the contracts with Echidna is a first class package The hot-fuzz package is the one that says something about how the project is built rather than what it sells. It is a wrapper of Echidna, the property-based fuzzer, with additional helpers for fuzzing Superfluid smart contract applications, including Super Apps. For a protocol whose entire value proposition is moving value continuously between accounts, property-based fuzzing is the right tool, because the interesting failures are sequences of operations rather than single calls, and a human writing test cases will not enumerate the sequences. The helpers exist because the Superfluid contract surface has preconditions and invariants that a generic fuzzer would trip over constantly, so the wrapper encodes the domain knowledge needed to make random sequences meaningful. The package is AGPL, which is consistent with a tool that is part of the security story of the protocol rather than a convenience wrapper. The subgraph package is AGPL as well and is the official indexer for the protocol, which is how an application reads historical stream data rather than reading chain state directly. ## The metadata package is the one most integrations actually need Underrated in most monorepo reviews, the metadata package is likely to be the one an integrator touches first. It holds contract addresses, subgraph URLs and other metadata for the Superfluid Protocol, and it is MIT licensed, so it can be consumed without the licence complications of the AGPL packages. Its practical role is the one every multi-network deployment needs, namely knowing where the contracts live and where the subgraph is deployed, without hardcoding addresses in your own codebase. The release history shows the metadata package on its own version line, with metadata@v1.6.5 published on 2026-10-01 and metadata@v1.6.4 on 2026-08-26, and the ethereum-contracts package on a separate line with ethereum-contracts@v1.15.3 from the same day as v1.6.5. That per-package tagging is the important structural fact about this monorepo, since it means a consumer can pin the contracts at one version and the metadata at another without being forced onto a single monorepo-wide release, and it also means that a release of the metadata package carries no contract changes with it. The repository itself has no single version, its root package is private with a placeholder version of 0.0.0, and the default branch is dev rather than main. ## Conclusion protocol-monorepo is a good fit for a team building a streaming payments application or a Super App on Ethereum, since the contracts, the client libraries and the metadata live together and the SDK layer exists precisely so an application can be written without Solidity. It is the wrong place to start if you only need to read balances or move tokens once, since a plain ERC-20 client does the job. It is also the wrong dependency if you need a single stable version, because the release tags are per package, the default branch is dev, and the js-sdk line is explicitly deprecated in favour of sdk-core. Before adopting a package, check which licence applies to it, since the contracts, the subgraph and the fuzzer are AGPL while the SDKs and the metadata are MIT, and note that the licence field on the repository says GitHub cannot classify it. The last push was on 2026-10-17 and the most recent tagged releases are metadata@v1.6.5 and ethereum-contracts@v1.15.3, both from 2026-10-01. ## FAQ ### What is the Superfluid protocol-monorepo? It is the Superfluid Protocol monorepo holding the specification, implementations, peripherals and development kits. The protocol is a framework for real-time finance where user accounts are connected and transactions happen instantaneously between them, and this repository implements it as Ethereum contracts and ships a JavaScript SDK for building Web3 applications on it. ### Should I use js-sdk or sdk-core? Use sdk-core. The js-sdk package is fully deprecated, with an explicit warning to use sdk-core instead, and its last release lives on a separate branch called release-js-sdk-stable. sdk-core is the application framework for interacting with the protocol without Solidity knowledge, while sdk-redux is the front-end framework for browser applications. ### What licences apply to the Superfluid packages? They differ by package. The ethereum-contracts, hot-fuzz and subgraph packages are AGPL v3, while metadata, sdk-core, sdk-redux and the deprecated js-sdk are MIT. The licence field on the repository says GitHub cannot classify it, so the per-package terms in each package are the ones to read. ### What does the hot-fuzz package do? It is a wrapper of Echidna with additional helpers for fuzzing Superfluid smart contract applications, including Super Apps. That makes it a property-based testing harness rather than a set of example tests, which suits a protocol where the interesting failures are sequences of value-moving operations. ### What is the metadata package for? It holds contract addresses, subgraph URLs and other metadata for the Superfluid Protocol, under the MIT licence. It is released on its own version line, with metadata@v1.6.5 published on 2026-10-01, so consumers can pin it independently of the contracts package. ## Sources - [Issues](https://github.com/superfluid-org/protocol-monorepo/issues) - [Project website](https://superfluid.org) - [README](https://github.com/superfluid-org/protocol-monorepo/blob/dev/README.md) - [Releases](https://github.com/superfluid-org/protocol-monorepo/releases) - [superfluid-org/protocol-monorepo on GitHub](https://github.com/superfluid-org/protocol-monorepo) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/superfluid-org-protocol-monorepo