# Hyperledger FireFly: one API over many blockchains > FireFly is what the Hyperledger project calls the first open source Supernode, a Go stack that puts one REST and WebSocket API in front of digital assets, data flows and blockchain transactions across EVM chains, Fabric, Tezos, Cardano and Corda. The core repository is only one part of it, and the plugin layer is where the real work of adding a chain happens. **hyperledger-firefly/firefly** — Hyperledger FireFly is the first open source Supernode: a complete stack for enterprises to build and scale secure Web3 applications. The FireFly API for digital assets, data flows, and blockchain transactions makes it radically faster to build production-ready apps on popular chains and protocols. - Repository: https://github.com/hyperledger-firefly/firefly - Website: https://hyperledger-firefly.github.io/firefly/ - Stars: 603 · Forks: 252 - Language: Go - License: Apache-2.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/hyperledger-firefly-firefly ## What a Supernode is meant to be Hyperledger FireFly is described as the first open source Supernode: a complete stack for enterprises to build and scale secure Web3 applications. The FireFly API for digital assets, data flows and blockchain transactions is what the project says makes it faster to build production-ready applications on popular chains and protocols. The word Supernode is doing the load-bearing work in that description, and it is worth being precise about what the code does rather than what the marketing implies. The core repository is written in Go and hosts the API server and the central orchestration engine. It also contains the plugin interfaces to microservice connectors written in a variety of languages such as TypeScript and Java, along with the heavy-lifting runtime components. So the unit of deployment is a node that holds state and exposes an API, and a deployment of FireFly is a network of those nodes. A Supernode is not a library you import and it is not a single process that talks to one chain. It is a service with a persistent store, a WebSocket event interface, and a set of connectors to the chains and protocols underneath. That shape is the reason the project exists in this form. The problem it addresses is that every blockchain exposes a different API, a different event model and a different notion of an asset, and an application that spans several of them ends up with the plumbing written several times. FireFly's claim is that you write against one API and one event model, and the differences are handled by plugins. ## Everything is pluggable, including the parts you might assume are fixed The technical architecture section says that FireFly has a pluggable microservices architecture, and that everything is pluggable, from the blockchain technology, token ERC standards and custom smart contracts, all the way to the event distribution layer and the private database. That is an unusually broad claim, and the README handles it directly: if there are not yet instructions for making FireFly a Supernode for your favourite blockchain technology, there is almost certainly a straightforward path to plugging it in that saves you from rebuilding all the plumbing for your blockchain application from scratch. The repository list is where the claim gets tested, and it is worth reading as a map of the ecosystem rather than as a list of links. For blockchain connectivity there is a Transaction Manager, a signer repository carrying RLP and ABI encoding, KeystoreV3 utilities and a secp256k1 signer runtime, an FFCAPI reference connector for EVM chains, a permissioned Ethereum connector for Hyperledger Besu and Quorum, a Fabric connector, a Tezos connector, a Cardano connector, and a Corda connector starter, with the note that CorDapp specific customisation is required for that last one. Token standards have their own repositories for ERC20 and ERC721 together, and separately for ERC1155. Private data has an HTTPS data exchange connector. And the developer ecosystem has its own set of repositories: a command line interface, the Explorer UI, a Node.js SDK, a sandbox and exerciser, samples, a performance CLI, and Helm charts for deploying to Kubernetes. The Corda connector is the entry to read carefully, because it is the one that says starter and requires custom work, and the rest are listed as finished connectors. ## The core repository is a layered pipeline, and the diagram says so The README includes an ASCII map of the FireFly Core code hierarchy, and it is the most informative paragraph in the document because it shows where each responsibility sits. The entry point is cmd, which creates the parent context and handles signals, and it hands off to the internal tree. Inside internal, the api server is an HTTP listener using Gorilla mux, with TLS and CORS configuration, and it upgrades WebSocket connections on the same port. Its responsibility is defined narrowly as REST route definitions and simple routing logic only, with all processing deferred to the orchestrator. That separation is the point of the design. The API layer does not implement behaviour, it translates HTTP into internal calls, which is what makes the OpenAPI specification layer possible on top of it: a REST route definition framework that standardises body, path, query and filter semantics and generates OpenAPI 3.0 with a Swagger UI, including the Swagger user interface. Beside it sits the WebSocket server, described as a developer friendly JSON based protocol for business application development, with reliable sequenced delivery, and an event interface for subscription. So there are three layers visible here: the API server that speaks HTTP and WebSocket, the OpenAPI specification layer that defines routes once and generates the documentation, and the orchestrator underneath that actually does the work. Everything else in the repository, the database plugins, the blockchain plugins, the shared storage plugins, the event distribution, is reached through that structure rather than around it. ## The build tells you what the project actually depends on The module file describes the core's dependencies, and reading it tells you what kind of system this is. It requires Go 1.26.0 with a toolchain of go1.26.4. The direct dependencies are a mix of infrastructure and domain concerns. On the infrastructure side there is gorilla/mux for routing and gorilla/websocket for the event socket, golang-migrate/migrate for schema changes, lib/pq and mattn/go-sqlite3 for the two database engines, prometheus/client_golang for metrics, and spf13/cobra with spf13/viper for the command line and configuration. On the domain side there is the OpenAPI generator kin-openapi, a JSON Schema validator, an SQL query builder in squirrel, and two of FireFly's own sibling repositories, common and signer. The two database drivers are the interesting detail. The core supports Postgres and SQLite, and the Makefile sets CGO_ENABLED=0 with a comment that FireFly is expected to compile with CGO disabled, which is a constraint for a project that also depends on go-sqlite3. The Makefile shows the shape of the development loop. The test target runs the go tool against the internal, pkg, cmd, doc-site and ffconfig trees with coverage, an atomic cover mode and a 45 second timeout, and the coverage target renders an HTML report from the profile. Linting is golangci-lint with a five minute timeout, and mocks are generated with mockery rather than written by hand, with a makemock function that takes a package, an interface name and an output package, and it is invoked for the websocket client, the blockchain plugin and its callbacks, the core operation callbacks, the database plugin and its callbacks, and the shared storage plugin. That list of mocked interfaces is a compact description of the plugin seams, which is exactly the extension surface the architecture section describes. ## Getting a local network running in minutes The best place to learn is the documentation, and the entry point is the Getting Started Guide, which the README says will get you a running FireFly network of Supernodes on your local machine in a few minutes. That guide is where the install steps live, since the README does not carry a command line for it. What the README does show is the shape of the development environment you get, in a three column table: the FireFly CLI, the FireFly Explorer UI, and the FireFly Sandbox, each with a link to its own documentation section. The Sandbox is described as the exerciser, a tool for driving the network without deploying anything permanent. So a first session has three moving parts. The CLI is what you talk to, the Explorer is the user interface for inspecting what the network has done, and the Sandbox is where you can experiment. The container build is documented in the repository, and it is a good indicator of how the project is packaged. The Dockerfile has several stages. The FireFly builder stage takes a builder image, installs a toolchain of make, gcc, build-base, curl and git under apk, and then runs make build. The Fabric builder stage is separate and takes a platform argument, vendors the Go modules of the smart contract, downloads a Hyperledger Fabric release tarball, points FABRIC_CFG_PATH at it, and packages the chaincode with the peer lifecycle chaincode package command. The Solidity builder is a third stage for the EVM side. The FireFly builder stage is short enough to read in full: ```dockerfile FROM $FIREFLY_BUILDER_TAG AS firefly-builder ARG BUILD_VERSION ARG GIT_REF RUN apk add --no-cache \ make>=4.4.1-r2 \ gcc>=14.2.0-r4 \ build-base>=0.5-r3 \ curl>=8.14.1-r2 \ git>=2.47.3-r0 WORKDIR /firefly ``` The stages are per target platform, which is a good sign for a project that has to build for several architectures. The repository also carries a Dockerfile, a docker_build.sh, a manifest.json and a manifestgen.sh, and the top level has a .golangci.yml, a CODEOWNERS file, a MAINTAINERS.md, a SECURITY.md and a .trivyignore for vulnerability scanning of the images. The release history shows a project that ships steadily: v1.5.0 on 2026-08-04, with v1.5.0-rc.1 and v1.5.0-rc.2 in the weeks before it, and the last push to the repository on 2026-10-20. ## Where FireFly is the wrong tool The first limitation is that FireFly is a distributed system before it is a library, and the deployment cost follows from that. A network of Supernodes means a persistent database, a message transport, an event interface and a connector per chain, and the Helm charts and sandbox exist because the thing is meant to be run rather than imported. For an application that touches exactly one chain, this is a large amount of infrastructure for what the chain's own client library would do in a page of code. The second limitation is the abstraction's own edge. FireFly deliberately hides the chains' native interfaces behind one API, and that is a strength when you have several chains and a liability when you need something specific. A chain feature with no FireFly equivalent is either a plugin you write or a capability you do not have, and the Corda connector, which is explicitly a starter requiring CorDapp specific customisation, is the visible example of that boundary. The third limitation is that the API and the event model are FireFly's, not the chain's. An application that has to interoperate with another system expecting a specific chain's event format will need a translation layer, and the WebSocket protocol is described as a developer friendly JSON based protocol for business application development, which is a FireFly protocol rather than a chain protocol. The real alternative is to write the integrations directly against each chain's SDK and normalise in your own code. The difference in approach is that FireFly moves the normalisation into a distributed platform that you operate, with a plugin interface, a database, an orchestrator and an event bus, while the direct approach keeps the normalisation in your application where you can see and test it. For a multi-chain enterprise deployment where several teams consume the same assets and the same events, FireFly's central model is the better fit, because the normalisation is done once and everyone reads the same event stream. For a small team with one or two chains, the direct approach is smaller, easier to debug and has one fewer thing to keep running. ## Conclusion Adopt FireFly if your application needs to talk to more than one blockchain through one API and one event model, and if you can live with running a network of Supernodes rather than a library. Do not adopt it for a single-chain application, because the multi-chain plumbing is the product and it is more than you would otherwise need, and do not adopt it if you need the chain's own client libraries, since FireFly deliberately abstracts them away. Before you commit, read the core code hierarchy in the README to see how the API server, orchestrator, WebSocket layer and plugins are separated, and check the connector list for the chain you actually need, because the Corda connector is explicitly a starter requiring CorDapp specific customisation. ## FAQ ### What is Hyperledger FireFly? It is described as the first open source Supernode, a complete stack for enterprises to build and scale secure Web3 applications, with an API for digital assets, data flows and blockchain transactions. The core repository is written in Go and hosts the API server and the central orchestration engine, with plugin interfaces to microservice connectors in languages such as TypeScript and Java. ### Which blockchains can FireFly connect to? The project lists connectors for EVM chains through an FFCAPI reference connector, permissioned Ethereum for Hyperledger Besu and Quorum, Hyperledger Fabric, Tezos, Cardano, and a Corda connector starter that requires CorDapp specific customisation. Token connectors exist for ERC20 and ERC721 together and for ERC1155, and there is an HTTPS data exchange connector for private data. ### How do I get a local FireFly network running? The README points at the Getting Started Guide in the documentation, which is where the install steps are, and says it gets a running network of Supernodes on your local machine in a few minutes. The development environment it produces consists of the FireFly CLI, the FireFly Explorer UI and the FireFly Sandbox for exercising the network. ### What does the FireFly core repository contain? It contains the API server and the central orchestration engine, with the cmd tree as the CLI entry point that creates the parent context and handles signals, an internal tree containing the HTTP and WebSocket server built on Gorilla mux, an OpenAPI 3.0 route definition framework with Swagger generation, and the plugin interfaces for blockchain, database and shared storage connectors, whose mocks are generated with mockery. ### Is Hyperledger FireFly still being developed? The repository is not archived and the last push was on 2026-10-20. Recent releases include v1.5.0 from 2026-08-04 along with the v1.5.0-rc.1 and v1.5.0-rc.2 candidates before it, and the project is Apache-2.0 licensed with a Chinese README maintained alongside the English one. ## Sources - [hyperledger-firefly/firefly on GitHub](https://github.com/hyperledger-firefly/firefly) - [License: Apache-2.0](https://github.com/hyperledger-firefly/firefly/blob/main/LICENSE) - [Project website](https://hyperledger-firefly.github.io/firefly/) - [README](https://github.com/hyperledger-firefly/firefly/blob/main/README.md) - [Releases](https://github.com/hyperledger-firefly/firefly/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hyperledger-firefly-firefly