> For the complete documentation index, see [llms.txt](https://docs.fireflylabs.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fireflylabs.app/about-firefly-labs/core-architecture.md).

# Core Architecture

#### Firefly Bridge is a trust-minimized cross-chain messaging and asset transfer protocol. It supports both EVM and non-EVM chains without relying on wrapped tokens or external custodians.

***

### Architecture Design <a href="#architecture-design" id="architecture-design"></a>

Firefly’s architecture is purpose-built to enable **chain abstraction** — allowing developers to build applications that operate across chains without requiring users to understand, manage, or even think about which chain they are on.

It combines a maker-based relay model, deterministic smart contracts, and a progressively decentralized trust setup to support fast, secure, and chain-agnostic interactions.

**1. Maker-Based Relay**

Firefly uses a **Maker-based relay** system where designated Makers relay user intents from source to destination chains. Crucially, **no off-chain party controls user funds**. Instead:

* Makers submit transaction calldata, but contracts on the destination chain **verify + decide execution**
* All logic runs transparently—**no special keys, no privileged execution paths**
* Misbehavior is punished: slashing, removal, and full public visibility

This creates a bridge model where **execution is fast**, but still **trustlessly accountable**, and evolution toward cryptographic proof-based bridging is already underway via Merkle & ZK routes.

**2. Deterministic Smart Contracts**

All transaction logic is transparently executed 100% on-chain through Firefly’s immutable and auditable smart contracts.

* No off-chain computation
* No privileged actors
* Fully auditable, open-source logic

**3. Hybrid Trust Model**

Firefly prioritizes low-latency performance while evolving toward full trust minimization.

* **Short-term**: Rapid execution via trusted relayers with on-chain accountability
* **Mid-term**: Optional verification with Merkle or ZK proofs
* **Long-term**: Default zero-trust integrity through cryptographic proofs and decentralized validation

**4. Chain-Abstraction-Friendly by Design**

Every layer of Firefly is architected to support chain abstraction:

* **Unified contracts and messaging** abstract away chain-specific logic
* **Intelligent routing** ensures users get the fastest, lowest-cost path without needing to choose chains
* **Chain-agnostic execution**: Apps work seamlessly across L1s, L2s, appchains, and alt-VM networks
* **Designed to integrate with account abstraction**, smart wallets, and unified cross-chain identity

The result is a seamless development and user experience resembling a single-chain application — but powered by multichain infrastructure.

***

### Cross-Chain Asset Flow <a href="#cross-chain-asset-flow" id="cross-chain-asset-flow"></a>

Firefly’s transfer flow is designed to support not only secure bridging, but also intuitive, chainless UX for applications and end users.

**Step 1 – Initiation**

A user sends a message or locks assets on Chain A. Firefly standardizes this action into an abstract intent format.

**Step 2 – Relay**

A Maker observes the event and submits the resulting calldata to Chain B. Optimized routing logic selects the best Maker and route.

**Step 3 – Execution**

On the destination chain, Firefly smart contracts verify the message and execute the logic or release funds.

> This process is fully programmatic and runs entirely on-chain, enabling:
>
> * Seamless bridging without network switching
> * Chainless app flows such as cross-chain swaps, game logic, or function calls
> * Reliable messaging and execution with verified finality

***

### Security Features <a href="#security-features" id="security-features"></a>

Firefly is built from first principles for cryptographic security and economic accountability.

* ✅ All messages are verified on-chain
* ✅ No wrapped tokens, no third-party custody
* ✅ Relayers (Makers) stake capital and are subject to slashing for misbehavior
* ✅ Modular proof verification (Merkle/ZK) ensures extensible trust minimization
* ✅ Fraud detection, challenge-response, and deterministic contracts eliminate ambiguity


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fireflylabs.app/about-firefly-labs/core-architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.