Teams building enterprise blockchain applications typically discover a common pattern: the smart contract is the easy part. The hard engineering lies in everything around the contract, reliably getting transactions onto the chain, handling failures and retries, receiving and acting on chain events, managing signing keys at scale, and connecting the chain to the rest of your enterprise stack.
Web3 Middleware is the Kaleido product layer that solves exactly this class of problem. It sits between your enterprise applications and the blockchain, providing a managed, auditable, and configurable integration layer so that your teams can focus on building business logic rather than re-implementing blockchain infrastructure plumbing from scratch.
Web3 Middleware is not a "blockchain SDK wrapper." It is a runtime platform: a continuously operating set of services that manages the full transaction lifecycle, from the moment your application calls an API, through signing and submission, to finality confirmation and event delivery back to your systems.
At a practical level, Web3 Middleware handles five responsibilities that are tedious and error-prone to build yourself:
The product has two generations, both in production:
The sections that follow walk through each of these in detail.
To understand Web3 Middleware's role, it helps to see where it sits within the broader Kaleido platform. The platform is structured in three layers that build on each other:
Your enterprise applications interact with the platform through Web3 Middleware APIs, not directly with the blockchain. This is a deliberate architectural choice: it means your application code does not need to understand chain-specific RPC mechanics, nonce management, gas pricing, finality models, or event log encoding. All of that complexity is absorbed by the middleware layer.
FireFly v2 Connectors are the current generation of Kaleido's Web3 Middleware. They are designed around a principle that is simple to state but genuinely difficult to implement well: every blockchain ecosystem has its own transaction model, its own event format, its own finality semantics, and its own fee mechanics, and your business logic should be isolated from all of that.
A Connector is a configured integration stack for a specific blockchain network. It exposes a consistent API surface to your application regardless of which chain it is connected to, while handling all chain-specific behavior internally.
At its core, every connector handles two complementary data flows:
These two flows are where most custom blockchain integration code lives in non-platform implementations. Web3 Middleware provides them as configurable infrastructure, not custom code your team must write and maintain.
Each connector is assembled from a small set of configurable resource types. Connector Flows define the processing stages for an operation, for example, a transaction submission flow covers gas estimation, policy evaluation, key resolution, signing, and broadcast. Configuration Profiles attach a named set of behavioral parameters to a flow instance: confirmation thresholds, gas strategy, retry policy. Event Streams subscribe to filtered on-chain activity and route decoded events to a flow for further processing. Together these resources give you a connector that behaves exactly as your use case requires, without writing custom chain integration code.
Every connector exposes two classes of API, and understanding the difference is important for how you build against the platform.
Chain Standard APIs are pre-built, typed REST interfaces that model the universal operations for a given blockchain, deploy a contract, call a read function, send a transaction. They are implemented as workflows that invoke connector flows as subflows, so they are fully auditable and configurable. Each exposes an OpenAPI (Swagger) view and is ready to use immediately after your connector is configured. For the majority of interactions with a well-known chain, no further setup is required.
Custom APIs are generated from your own smart contract's ABI. You upload a build artifact or paste an ABI, select the connector flows to route through, name the API, and the platform produces a typed REST interface scoped to that specific contract's functions. This is how your application calls its business logic on-chain, through a versioned, auditable API, rather than constructing raw transactions manually.
A core design goal of the v2 connector architecture is universal chain connectivity, the ability to add new ecosystems without redesigning the integration pattern. The connector framework supports both EVM and non-EVM chains through the same model.
The practical implication is that the same application architecture, the same connector flows, the same event stream patterns, the same API design approach, can be deployed across different chains. You are not writing a new integration for each network.
The Workflow Engine is one of the most powerful and least immediately obvious components of Web3 Middleware. On the surface, it looks like a transaction sequencing tool. In practice, it is the mechanism that allows blockchain operations to be embedded in broader enterprise business processes without custom integration code.
The core idea is straightforward: rather than calling a smart contract directly from application code and then managing the side effects yourself, you define a workflow that describes the full sequence of steps required to complete a business operation. The platform executes that workflow reliably, with retry semantics, audit logging, and failure handling built in.
The most common use of the workflow engine is orchestrating operations that write state to the blockchain. A typical workflow for a token transfer might look like this:
Each step is discrete: it performs a single action, returns a status code (Continue, Error, or Return), and passes its output into a shared context that subsequent steps can read. This pipeline model means business logic that would otherwise require careful error handling and rollback logic across multiple services becomes a declarative configuration managed by the platform.
The workflow engine is equally important for processing activity that originates on-chain. When the event stream picks up an on-chain event, a transfer detected, a contract state change, a block confirmed, it can trigger a workflow rather than simply logging the occurrence. This is how you build reliable, event-driven backend processes on top of blockchain activity.
Consider a deposit scenario: a customer sends tokens to a monitored address. The event stream detects the transfer. Rather than just recording it, a workflow fires: first checking block confirmations (pending state), then running a KYT (Know Your Transaction) screen via an external API, then updating the internal ledger, then sending a notification. Each step runs in the platform, with full audit logging, rather than in fragile application code.
Some business processes span multiple blockchain events and take seconds, minutes, or hours to complete. The workflow engine supports long-running flows, processes that can wait for an external event, a human approval, or a time-based condition before proceeding to the next step. This is the basis for multi-party coordination patterns such as DvP (Delivery vs Payment) settlement, where two legs of a trade must both confirm before the trade is marked complete.
This capability is what distinguishes the platform from simple webhook-based event listeners. A webhook fires and forgets. A long-running workflow maintains state, handles partial failures, and guarantees exactly-once completion of complex multi-step processes, even across system restarts.
Workflows can call out to the following integration targets within a step:
HTTP/HTTPS requests, any REST endpoint, including your own internal services, external compliance APIs, Oracle feeds, or notification systems.
WebSocket endpoints, for streaming data integration within a workflow step.
Kaleido platform services, including the Key Manager, Policy Engine, and Smart Contract APIs.
External code runtimes, custom business logic written in TypeScript, Go, Java, or .NET can be invoked as hosted modules within a workflow step.
This makes the workflow engine the natural place to implement the integration between your blockchain operations and your existing enterprise systems (ERP, treasury, trading, payments), without building custom middleware.
Transaction management in blockchain systems is deceptively complex. What looks like a single operation, "send a transaction", is actually a multi-stage process with multiple failure modes at each stage. Web3 Middleware handles all of this automatically, but understanding what it is doing explains why building this yourself is a non-trivial engineering investment.
Every outbound transaction passes through the following stages, all managed by the platform:
Most blockchain integrations break under production load because transaction failure modes are numerous and varied: network congestion that causes a transaction to sit in the mempool, gas price underestimates that prevent inclusion, RPC endpoint timeouts, node sync issues, and chain reorganizations. The platform handles each of these scenarios:
Gas price too low, automatic resubmission with an increased gas price (gas bumping) after a configurable timeout.
RPC endpoint failure, automatic failover to a secondary endpoint.
Chain reorganization, detection of reorgs via block hash comparison; reverting transactions to a pending state when their containing block is reorganized out of the canonical chain.
Submission timeout, configurable TTL per transaction type; expired transactions are marked as failed with a full audit record.
The result is that your application receives clean, reliable lifecycle events, submitted, pending, confirmed, failed, rather than having to build its own logic to detect and recover from each of these failure modes.
One of the most common operational issues in high-throughput blockchain integrations is nonce management. Ethereum and EVM-compatible chains require every transaction from an address to have a strictly sequential nonce. If two transactions are submitted with the same nonce, one will be dropped. If a gap occurs in the sequence, all subsequent transactions are stuck until the gap is filled.
Web3 Middleware manages nonces centrally for each signing address: reserving them at prepare time, tracking outstanding transactions, and handling resubmission correctly. This is what enables high-throughput transaction processing from a single address without nonce collisions, and why building a high-throughput integration without platform support requires significant engineering effort.
Enterprise applications typically need to react to on-chain activity in real time: crediting an account when a deposit is detected, updating a record when a transfer confirms, triggering a downstream process when a contract state changes. The Event Stream infrastructure in Web3 Middleware handles all the low-level mechanics of listening to a blockchain, block polling, log filtering, ABI decoding, and deduplication, so your application receives typed, ordered event objects rather than raw on-chain data.
Your application configures a listener by specifying which contract address and event type to monitor. Events are delivered in block order via webhooks or WebSocket connections, with duplicates suppressed.
One of the most underappreciated challenges in building on blockchain is handling finality correctly. On probabilistic finality chains such as Ethereum mainnet, a transaction that appears confirmed can be reorganized out of the canonical chain. Web3 Middleware lets you configure finality rules per chain and per use case: how many block confirmations are required before an event is treated as final, and what action to take for events that arrive before that threshold. You can maintain a pending state, trigger an early notification, and then take the confirmed action once the threshold is met, all as declarative configuration, not custom code.
Before events can be decoded and typed APIs generated, the platform needs to know your contract's interface. The Smart Contract Manager handles this: it accepts uploaded ABIs or full build artifacts from Solidity toolchains, manages contract deployments and versioning, and generates the typed REST APIs used by connectors. Deploy a contract through the Smart Contract Manager and the typed API is immediately available to your connector and workflow configurations, no manual ABI parsing, no handwritten client code.
Every transaction that leaves your system must be signed. Web3 Middleware handles this through the Key Manager, a cross-platform component that abstracts over the underlying key storage technology and ensures that signing happens securely, auditably, and in the right place in your architecture.
The Key Manager is designed to work with the key storage technology you already use or require for compliance. It supports software-managed keys in a secure enclave for development and lower-sensitivity operations, and integrates natively with Hardware Security Modules (HSMs) for production institutional deployments. Natively supported HSM vendors include Thales Luna, IBM OSO, Fortanix, AWS CloudHSM, GCP Cloud HSM, Azure Key Vault, and HashiCorp Vault.
For HSMs not on this list, the platform provides a Remote Signing Module (RSM), a lightweight component you deploy co-located with your HSM. The RSM validates signing payloads and authorizes the hardware to sign without Kaleido ever having access to private key material. This also supports air-gapped and offline signing models for governance keys or ultra-high-value assets.
When a workflow reaches a signing step, the Key Manager resolves the appropriate key for that operation based on the wallet identity configured in the workflow. It then signs the transaction payload and returns the signed transaction to the connector flow for submission. Your application code never touches private key material, it calls a workflow, and the platform handles the complete signing path internally.
Policy evaluation is co-located with the signing step: before the Key Manager authorizes a signature, the Policy Engine evaluates the transaction context. A policy denial stops signing before it occurs, not after, ensuring that compliance controls cannot be bypassed at the application layer.
Kaleido does not generate or hold private keys on behalf of customers under any deployment model. Keys are generated within the customer's chosen secure environment. In HSM-backed configurations, generation occurs within the hardware security boundary.
Enterprise blockchain deployments are rarely unconstrained. Most operations are subject to business rules: transfer limits, investor eligibility checks, counterparty screening, jurisdiction restrictions, multi-party approval requirements. These rules need to be enforced reliably, not depended upon being implemented consistently in application code.
Web3 Middleware integrates the Kaleido Policy Engine, based on Open Policy Agent (OPA) with the Rego policy language, as a first-class component of the transaction pipeline.
Policy is evaluated before transaction signing. This is a critical design choice: by the time a signing step executes, policy has already approved or rejected the operation. A policy denial stops the transaction before it reaches the chain, before gas is spent, and before any on-chain state changes.
Policy evaluation runs at the RSM, co-located with the signing hardware. This means the policy decision cannot be bypassed by a compromise at the application tier, the HSM will only sign if the RSM's policy evaluation approves.
Policies in the platform are not simple rule tables. They are authored as code (Rego), strongly versioned, and can evaluate against rich transaction context including:
Policy changes are themselves subject to governance controls: a new policy version requires approval before it takes effect. This prevents a rogue configuration change from bypassing the controls it was meant to enforce.
FireFly v1.x is the original generation of Kaleido Web3 Middleware, built on the Hyperledger FireFly open-source project, the leading open-source framework for enterprise blockchain development. Many production deployments run on FireFly v1.x, particularly those with EVM network integrations established before the v2 connector architecture was introduced.
FireFly v1.x provides three integrated capabilities:
FireFly Core, the central orchestration runtime for building and scaling secure Web3 applications, providing the data model, API layer, event distribution, and plugin architecture.
Transaction Manager, robust, customizable management of transaction lifecycle: submission, retry, nonce sequencing, confirmation tracking, and error handling for EVM networks.
Private Data Manager, secure storage and transfer of off-chain data via IPFS integration, enabling data to be shared privately within a business network while maintaining a reference on-chain.
The v2 connector architecture extends and generalizes what FireFly v1.x did for EVM chains. FireFly v1.x remains the appropriate choice for teams with existing EVM deployments that are built on its programming model. FireFly v2 Connectors are the recommended architecture for new deployments, particularly those requiring multi-chain connectivity, non-EVM chain support, or the full composability of the v2 workflow engine.
Both product versions are fully supported and maintained on the Kaleido platform. They are not competing options, they represent successive generations that serve different points on the maturity curve.
The components described in this document combine to enable a class of enterprise blockchain applications that would be prohibitively complex to build and maintain without platform support. A few representative patterns:
A financial institution issues tokenized securities on a private Hyperledger Besu network for settlement, while simultaneously maintaining a public token representation on Ethereum mainnet for secondary market liquidity. Web3 Middleware connectors handle both chains through the same API model, event streams consolidate on-chain activity into a single activity feed, and the workflow engine coordinates operations that span both networks. No bespoke per-chain integration code required.
A payments operator processes thousands of stablecoin transfers per hour across multiple customer wallets. Web3 Middleware handles nonce management to prevent collisions, gas price management to keep transactions flowing during network congestion, and confirmation tracking to provide reliable settled-versus-pending state. The Policy Engine enforces per-customer transfer limits and triggers manual review for transactions above threshold. All events are logged to a queryable audit trail.
A logistics operator deploys a smart contract representing a shipment's provenance chain. Each custody transfer, inspection event, and delivery confirmation is a transaction submitted through a connector workflow that calls the smart contract and simultaneously calls an HTTP endpoint to update the ERP system. The event stream provides a counterparty-facing API for verifiers to track the chain of custody without needing direct chain access.
A central securities depository runs a Delivery-versus-Payment settlement process across two chains: securities delivery on a private permissioned chain, cash settlement on a CBDC network. The workflow engine manages the long-running settlement flow, monitoring for both legs of the trade, handling the case where one leg confirms but the other fails, and triggering the required reversal or retry procedures. Exactly-once execution semantics ensure each settlement action occurs once even in the face of system restarts.
If you are evaluating Kaleido Web3 Middleware for a specific integration, the most useful starting point is to identify the two data flows you need: which transactions do you need to submit to the chain, and which on-chain events do you need to react to? These two questions have concrete answers in the connector and event stream configuration model, and the Kaleido team is well-placed to help you map your requirements onto the platform's building blocks.
Your guide to everything from asset tokenization to zero knowledge proofs
Download Now
Learn how Swift, the world’s leading provider of secure financial messaging services, utilizes Kaleido in its CBDC Sandbox project.
Download Now
.png)
