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.
The best place to learn about FireFly is in the documentation.
There you will find our Getting Started Guide, which will get you a running FireFly network of Supernodes on your local machine in a few minutes.
Your development environment will come with:
FireFly CLI | FireFly Explorer UI | FireFly Sandbox |
---|---|---|
![]() |
![]() |
![]() |
Hyperledger FireFly has a pluggable microservices architecture. Everything is pluggable, from the Blockchain technology, token ERC standards, and custom smart contracts, all the way to the event distribution layer and private database.
So if there aren't yet instructions for making FireFly a Supernode for your favorite blockchain technology - don't worry. There is almost certainly a straightforward path to plugging it in that will save you from re-building all the plumbing for your blockchain application from scratch.
There are lots of places you can contribute, regardless of whether your skills are front-end, backend-end, or full-stack.
Check out our Contributor Guide, and welcome!.
You are currently in the "core" repository, which is written in Go and hosts the API Server and central orchestration engine. Here you will find plugin interfaces to microservice connectors written in a variety of languages like TypeScript and Java, as well as heavy-lifting runtime components.
Other repositories you might be interested in containing those microservice components, user experiences, CLIs and samples.
Note that only open source repositories and plugins are listed below
- Transaction Manager - https://github.com/hyperledger/firefly-transaction-manager
- RLP & ABI encoding, KeystoreV3 utilities and secp256k1 signer runtime - https://github.com/hyperledger/firefly-signer
- FFCAPI reference connector for EVM Chains - https://github.com/hyperledger/firefly-evmconnect
- Public EVM compatible chains: Learn more in the documentation
- Permissioned Ethereum connector - https://github.com/hyperledger/firefly-ethconnect
- Private/permissioned: Hyperledger Besu / Quorum
- Hyperledger Fabric connector - https://github.com/hyperledger/firefly-fabconnect
- Tezos connector - https://github.com/hyperledger/firefly-tezosconnect
- Corda connector starter: https://github.com/hyperledger/firefly-cordaconnect
- CorDapp specific customization is required
- Tokens ERC20/ERC721 - https://github.com/hyperledger/firefly-tokens-erc20-erc721
- Tokens ERC1155 - https://github.com/hyperledger/firefly-tokens-erc1155
- HTTPS Data Exchange - https://github.com/hyperledger/firefly-dataexchange-https
- Command Line Interface (CLI) - https://github.com/hyperledger/firefly-cli
- Explorer UI - https://github.com/hyperledger/firefly-ui
- Node.js SDK - https://github.com/hyperledger/firefly-sdk-nodejs
- Sandbox / Exerciser - https://github.com/hyperledger/firefly-sandbox
- Samples - https://github.com/hyperledger/firefly-samples
- FireFly Performance CLI: https://github.com/hyperledger/firefly-perf-cli
- Helm Charts for Deploying to Kubernetes: https://github.com/hyperledger/firefly-helm-charts
ββββββββββββ βββββββββββββββββ
β cmd ββββ€ firefly [Ff]β - CLI entry point
ββββββββββββ β β - Creates parent context
β β - Signal handling
βββββββ¬ββββββββββ
β
ββββββββββββ βββββββ΄ββββββββββ - HTTP listener (Gorilla mux)
β internal ββββ€ api [As]β * TLS (SSL), CORS configuration etc.
ββββββββββββ β server β * WS upgrade on same port
β β - REST route definitions
βββββββ¬ββββββββββ * Simple routing logic only, all processing deferred to orchestrator
β
βββββββ΄ββββββββββ - REST route definition framework
β openapi [Oa]β * Standardizes Body, Path, Query, Filter semantics
β spec | - OpenAPI 3.0 (Swagger) generation
βββββββ¬ββββββββββ * Including Swagger. UI
β
βββββββ΄ββββββββββ - WebSocket server
β [Ws]β * Developer friendly JSON based protocol business app development
β websockets β * Reliable sequenced delivery
βββββββ¬ββββββββββ * _Event interface [Ei] supports lower level integration with other compute frameworks/transports_
β
βββββββ΄ββββββββββ - Extension point interface to listen for database change events
β admin [Ae]β * For building microservice extensions to the core that run externally
β events | * Used by the Transaction Manager component
βββββββ¬ββββββββββ * Filtering to specific object types
β
βββββββ΄ββββββββββ - Core data types
β fftypes [Ft]β * Used for API and Serialization
β β * APIs can mask fields on input via router definition
βββββββ¬ββββββββββ
β
βββββββ΄ββββββββββ - Core runtime server. Initializes and owns instances of:
β [Or]β * Components: Implement features
βββββββββ¬ββββ€ orchestrator β * Plugins: Pluggable infrastructure services
β β β β - Exposes actions to router
β β βββββββββββββββββ * Processing starts here for all API calls
β β
β Components: Components do the heavy lifting within the engine
β β
β β βββββββββββββββββ - Integrates with Blockchain Smart Contract logic across blockchain technologies
β βββββ€ contract [Cm]β * Generates OpenAPI 3 / Swagger definitions for smart contracts, and propagates to network
β β β manager β * Manages listeners for native Blockchain events, and routes those to application events
β β βββββββββββββββββ * Convert to/from native Blockchain interfaces (ABI etc.) and FireFly Interface [FFI] format
β β
β β βββββββββββββββββ - Maintains a view of the entire network
β βββββ€ network [Nm]β * Integrates with network permissioning [NP] plugin
β β β map β * Integrates with broadcast plugin
β β βββββββββββββββββ * Handles hierarchy of member identity, node identity and signing identity
β β
β β βββββββββββββββββ - Broadcast of data to all parties in the network
β βββββ€ broadcast [Bm]β * Implements dispatcher for batch component
β β β manager | * Integrates with shared storage interface [Ss] plugin
β β βββββββββββββββββ * Integrates with blockchain interface [Bi] plugin
β β
β β βββββββββββββββββ - Send private data to individual parties in the network
β βββββ€ private [Pm]β * Implements dispatcher for batch component
β β β messaging | * Integrates with the data exchange [Dx] plugin
β β ββββββββ¬βββββββββ * Messages can be pinned and sequenced via the blockchain, or just sent
β β β
β β ββββββββ΄βββββββββ - Groups of parties, with isolated data and/or blockchains
β β β group [Gm]β * Integrates with data exchange [Dx] plugin
β β β manager β * Integrates with blockchain interface [Bi] plugin
β β βββββββββββββββββ
β β
β β βββββββββββββββββ - Private data management and validation
β βββββ€ data [Dm]β * Implements dispatcher for batch component
β β β manager β * Integrates with data exchange [Dx] plugin
β β ββββββββ¬βββββββββ * Integrates with blockchain interface [Bi] plugin
β β β
β β ββββββββ΄βββββββββ - JSON data schema management and validation (architecture extensible to XML and more)
β β β json [Jv]β * JSON Schema validation logic for outbound and inbound messages
β β β validator β * Schema propagation
β β ββββββββ¬βββββββββ * Integrates with broadcast plugin
β β β
β β ββββββββ΄βββββββββ - Binary data addressable via ID or Hash
β β β blobstore [Bs]β * Integrates with data exchange [Dx] plugin
β β β β * Hashes data, and maintains mapping to payload references in blob storage
β β βββββββββββββββββ * Integrates with blockchain interface [Bi] plugin
β β
β β βββββββββββββββββ - Download from shared storage
β βββββ€ shared [Sd]β * Parallel asynchronous download
β β β download β * Resilient retry and crash recovery
β β βββββββββββββββββ * Notification to event aggregator on completion
β β
β β βββββββββββββββββ
β βββββ€ identity [Im] β - Central identity management service across components
β β β manager β * Resolves API input identity + key combos (short names, formatting etc.)
β β β β * Resolves registered on-chain signing keys back to identities
β β βββββββββββββββββ * Integrates with Blockchain Interface and pluggable Identity Interface (TBD)
β β
β β βββββββββββββββββ - Keeps track of all operations performed against external components via plugins
β βββββ€ operation [Om]β * Updates database with inputs/outputs
β β β manager β * Provides consistent retry semantics across plugins
β β βββββββββββββββββ
β β
β β βββββββββββββββββ - Private data management and validation
β βββββ€ event [Em]β * Implements dispatcher for batch component
β β β manager β * Integrates with data exchange [Dx] plugin
β β ββββββββ¬βββββββββ * Integrates with blockchain interface [Bi] plugin
β β β
β β ββββββββ΄βββββββββ - Handles incoming external data
β β β [Ag]β * Integrates with data exchange [Dx] plugin
β β β aggregator β * Integrates with shared storage interface [Ss] plugin
β β β β * Integrates with blockchain interface [Bi] plugin
β β β β - Ensures valid events are dispatched only once all data is available
β β ββββββββ¬βββββββββ * Context aware, to prevent block-the-world scenarios
β β β
β β ββββββββ΄βββββββββ - Subscription manager
β β β [Sm]β * Creation and management of subscriptions
β β β subscription β * Creation and management of subscriptions
β β β manager β * Message to Event matching logic
β β ββββββββ¬βββββββββ
β β β
β β ββββββββ΄βββββββββ - Manages delivery of events to connected applications
β β β event [Ed]β * Integrates with data exchange [Dx] plugin
β β β dispatcher β * Integrates with blockchain interface [Bi] plugin
β β βββββββββββββββββ
β β
β β βββββββββββββββββ - Token creation/transfer initiation, indexing and coordination
β βββββ€ asset [Am]β * Fungible tokens: Digitized value/settlement (coins)
β β β manager β * Non-fungible tokens: NFTs / globally uniqueness / digital twins
β β βββββββββββββββββ * Full indexing of transaction history
β β [REST/WebSockets]
β β βββββββ΄ββββββββββββββ ββββββββββββ ββ
β β β ERC-20 / ERC-721 βββββ€ ERC-1155 βββββ€ Simple framework for building token connectors
β β βββββββββββββββββββββ ββββββββββββ ββ
β β
β β βββββββββββββββββ
β βββββ€ sync / [Sa] β - Sync/Async Bridge
β β β async bridge β * Provides synchronous request/reply APIs
β β β β * Translates to underlying event-driven API
β β βββββββββββββββββ
β β
β β βββββββββββββββββ - Aggregates messages and data, with rolled up hashes for pinning
β βββββ€ batch [Ba]β * Pluggable dispatchers
β β β manager β - Database decoupled from main-line API processing
β β β β * See architecture diagrams for more info on active/active sequencing
β β ββββββββ¬βββββββββ - Manages creation of batch processor instances
β β β
β β ββββββββ΄βββββββββ - Short lived agent spun up to assemble batches on demand
β β β batch [Bp]β * Coupled to an author+type of messages
β β β processor β - Builds batches of 100s messages for efficient pinning
β β β β * Aggregates messages and data, with rolled up hashes for pinning
β β βββββββββββββββββ - Shuts down automatically after a configurable inactivity period
β ... more TBD
β
Plugins: Each plugin comprises a Go shim, plus a remote agent microservice runtime (if required)
β
β βββββββββββββββββ - Blockchain Interface
βββββββββββββ€ [Bi]β * Transaction submission - including signing key management
β β blockchain β * Event listening
β β interface β * Standardized operations, and custom on-chain coupling
β βββββββ¬ββββββββββ
β β
β βββββββββββββββββββββββ¬ββββββββββββββββββββ¬-ββββββββββββββββββββ
β βββββββ΄ββββββββββ βββββββββ΄ββββββββ βββββββββ΄βββββββββ βββββββββ΄βββββββββ
β β ethereum β β fabric β β corda/cordapps β β tezos β
β βββββββ¬ββββββββββ βββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββ
β [REST/WebSockets]
β βββββββ΄βββββββββββββββββββββ ββββββββββββββββββββββββββ ββ
β β transaction manager [Tm] βββββ€ Connector API [ffcapi] βββββ€ Simple framework for building blockchain connectors
β ββββββββββββββββββββββββββββ ββββββββββββββββββββββββββ ββ
β
β βββββββββββββββββ - Token interface
βββββββββββββ€ tokens [Ti]β * Standardizes core concepts: token pools, transfers, approvals
β β interface β * Pluggable across token standards
β βββββββββββββββββ * Supports simple implementation of custom token standards via microservice connector
β [REST/WebSockets]
β βββββββ΄ββββββββββββββ ββββββββββββ ββ
β β ERC-20 / ERC-721 βββββ€ ERC-1155 βββββ€ Simple framework for building token connectors
β βββββββββββββββββββββ ββββββββββββ ββ
β
β βββββββββββββββββ - P2P Content Addressed Filesystem
βββββββββββββ€ shared [Si]β * Payload upload / download
β β storage β * Payload reference management
β β interface β
β βββββββ¬ββββββββββ
β β
β ββββββββββ ... extensible to any shared storage system, accessible to all members
β βββββββ΄ββββββββββ
β β ipfs β
β βββββββββββββββββ
β
β βββββββββββββββββ - Private Data Exchange
βββββββββββββ€ data [Dx]β * Blob storage
β β exchange β * Private secure messaging
β βββββββ¬ββββββββββ * Secure file transfer
β β
β βββββββββββββββββββββββ¬ββββββββββ ... extensible to any private data exchange tech
β βββββββ΄ββββββββββ βββββββββ΄ββββββββ
β β https / MTLS β β Kaleido β
β βββββββββββββββββ βββββββββββββββββ
β
β βββββββββββββββββ - API Authentication and Authorization Interface
βββββββββββββ€ api auth [Aa]β * Authenticates security credentials (OpenID Connect id token JWTs etc.)
β β β * Extracts API/user identity (for identity interface to map)
β βββββββ¬ββββββββββ * Enforcement point for fine grained API access control
β β
β βββββββββββββββββββββββ¬ββββββββββ ... extensible other single sign-on technologies
β βββββββ΄ββββββββββ βββββββββ΄ββββββββ
β β apikey β β jwt β
β βββββββββββββββββ βββββββββββββββββ
β
β βββββββββββββββββ - Database Interactions
βββββββββββββ€ database [Di]β * Create, Read, Update, Delete (CRUD) actions
β β interface β * Filtering and update definition interface
β βββββββ¬ββββββββββ * Migrations and Indexes
β β
β ββββββββββ ... extensible to NoSQL (CouchDB / MongoDB etc.)
β βββββββ΄ββββββββββ
β β sqlcommon β
β βββββββ¬ββββββββββ
β βββββββββββββββββββββββββ¬βββββββββ ... extensible other SQL databases
β βββββββ΄ββββββββββ βββββββββ΄βββββββββ
β β postgres β β sqlite3 β
β βββββββββββββββββ ββββββββββββββββββ
β
β βββββββββββββββββ - Connects the core event engine to external frameworks and applications
βββββββββββββ€ event [Ei]β * Supports long-lived (durable) and ephemeral event subscriptions
β β interface β * Batching, filtering, all handled in core prior to transport
β βββββββ¬ββββββββββ * Interface supports connect-in (websocket) and connect-out (broker runtime style) plugins
β β
β βββββββββββββββββββββββββ¬ββββββββββ ... extensible to additional event buses (Kafka, NATS, AMQP etc.)
β βββββββ΄ββββββββββ βββββββββ΄βββββββββ
β β websockets β β webhooks β
β βββββββββββββββββ ββββββββββββββββββ
β ... more TBD
Additional utility frameworks
βββββββββββββββββ - REST API client
β rest [Re]β * Provides convenience and logging
β client β * Standardizes auth, config and retry logic
βββββββββββββββββ * Built on Resty
βββββββββββββββββ - WebSocket client
β wsclient [Wc]β * Provides convenience and logging
β β * Standardizes auth, config and reconnect logic
βββββββββββββββββ * Built on Gorilla WebSockets
βββββββββββββββββ - Translation framework
β i18n [In]β * Every translations must be added to `en_translations.json` - with an `FF10101` key
β β * Errors are wrapped, providing extra features from the `errors` package (stack etc.)
βββββββββββββββββ * Description translations also supported, such as OpenAPI description
βββββββββββββββββ - Logging framework
β log [Lo]β * Logging framework (logrus) integrated with context based tagging
β β * Context is used throughout the code to pass API invocation context, and logging context
βββββββββββββββββ * Example: Every API call has an ID that can be traced, as well as a timeout
βββββββββββββββββ - Configuration
β config [Co]β * File and Environment Variable based logging framework (viper)
β β * Primary config keys all defined centrally
βββββββββββββββββ * Plugins integrate by returning their config structure for unmarshaling (JSON tags)