# boundless-xyz/boundless architecture

> Architecture diagram of the GitHub repository boundless-xyz/boundless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boundless-xyz/boundless
- Repository: https://github.com/boundless-xyz/boundless

## Overview

##### Project type and purpose
- Boundless is a monorepo providing a full-stack, on-chain marketplace platform and proof‐generation framework.
- It includes Solidity smart contracts, Rust SDK/CLI clients, multiple Rust microservices (broker, indexer, order‐stream API, slasher, order‐generator), zkVM guests for proof generation, and Pulumi infra code for AWS deployment.

##### File structure
- Top level:
- contracts/ → Solidity core contracts
- crates/ → Rust crates:
– boundless-market (SDK)
– boundless-cli (CLI)
– broker, indexer, order-stream, slasher, order-generator, distributor, bench, assessor, guest, etc.
- infra/ → Pulumi TypeScript projects per service (builder, broker, indexer, pipelines, prover, etc.)
- documentation/ → docs site code (React/MDX)
- Dockerfiles, CI workflows, environment templates, scripts, examples
- Patterns: microservices (each crate/`src/main.rs`), database migrations per service, AWS Lambda monitors, message‐ or event‐driven flows, layered request builders.

##### README for additional insights
- Confirms core components: contracts, SDK, CLI, prover samples
- Encourages using Foundry for contracts, Cargo for Rust crates
- Mentions RISC Zero toolchain for zkVM guests

a. Main components:
- Ethereum Network (e.g., Sepolia) hosting Boundless core contracts
- Clients: Boundless-CLI & SDK (boundless-market crate)
- Microservices:
– Broker: watches on-chain events, packs proof requests, sends to zkVM prover, submits fulfillments
– Indexer: subscribes to chain & broker events, writes to Postgres, powers dashboards
– Order-Stream API: WS/HTTP service reading from its DB, streaming order updates to UIs
– Slasher: scans expired/unfulfilled orders, triggers on-chain slashing
– Order-Generator: emits test/demo orders onto the system
– Distributor: (if used) coordinates distribution of fill events
- zkVM Prover Environment: RISC Zero guests (crates/guest & assessor) running in sandboxed processes or AWS Lambdas
- Storage & External Services:
– Databases (Postgres/SQLite) per service
– Object storage: S3, Pinata (NFT/metadata storage)
- CI/CD & Deployment: Pulumi infra provisioning AWS resources (RDS, Lambdas, ECS/EKS or EC2, S3, CodePipeline, Alarms, VPC)

b. Relationships & interactions:
1. CLI/SDK → JSON-RPC → Ethereum node → executes smart contract calls
2. Ethereum event logs → Broker monitors → enqueues proof jobs → Prover executes guests → returns proof → Broker submits transactions
3. Broker & chain events → Indexer listens → writes normalized data into its DB → used by dashboards (Grafana) and by Order-Stream API
4. Order-Stream service → reads its DB → serves WebSocket/HTTP streams to end-user applications
5. Slasher service → queries Indexer or on-chain state → triggers slashing TXs back to Ethereum
6. Order-Generator → publishes synthetic orders into Broker/Contracts to simulate traffic
7. Infrastructure: CI/CD pipelines (AWS CodePipeline / GitHub Actions) deploy new versions of microservices & infra
8. Documentation site served separately via static hosting (e.g., S3+CDN)

c. Architectural patterns & design principles:
- Microservices – each Rust crate is an independently deployable service with its own DB and migrations
- Event-driven & pub/sub – on-chain events trigger off-chain workflows (broker, indexer, slasher)
- Layered SDK request builder – boundless-market uses middleware layers (nonce, preflight, storage, gas)
- CQRS – write models (events) vs read models (indexer DB vs order-stream DB)
- Infrastructure as code (Pulumi) – strong infrastructure versioning & environment isolation

d. Key technologies & frameworks:
- Rust + Tokio + SQLx for services
- Foundry (Forge) for Solidity contracts
- RISC Zero for zkVM guest proofs
- Pulumi (TypeScript) for infra (AWS Lambdas, RDS, VPC, alarms)
- Docker & GitHub Actions for CI/CD
- Grafana for monitoring (dashboards in dockerfiles/grafana)

##### Final advice
- Be exhaustive: represent each Rust crate/service, database, external dependency, and infra resource
- Don’t over-simplify: capture the event triggers, proof lifecycle, and read vs write data paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        SDK["Boundless SDK\n(Rust crate)"]:::client
        CLI["Boundless CLI"]:::client
    end

    %% On-chain Blockchain
    subgraph "On-chain Blockchain"
        CONTRACTS["Smart Contracts\n(Ethereum)"]:::blockchain
        ETH["Ethereum Network\n(e.g., Sepolia)"]:::blockchain
    end

    %% Off-chain Services
    subgraph "Off-chain Services"
        BROKER["Broker Service"]:::rustServices
        INDEXER["Indexer Service"]:::rustServices
        ORDERSTREAM["Order-Stream API"]:::rustServices
        SLASHER["Slasher Service"]:::rustServices
        ORDERGEN["Order-Generator"]:::rustServices
        DISTRIBUTOR["Distributor"]:::rustServices
    end

    %% Prover Environment
    subgraph "zkVM Prover Environment"
        GUEST_ASS["Guest Assessor"]:::prov
        GUEST_UTIL["Guest Utilities"]:::prov
    end

    %% Storage & DB
    subgraph "Storage & DB"
        PG_BROKER["Postgres (Broker)"]:::storage
        PG_INDEXER["Postgres (Indexer)"]:::storage
        PG_ORDERSTREAM["Postgres (Order-Stream)"]:::storage
        S3["S3 / Pinata"]:::storage
    end

    %% Infrastructure
    subgraph "Infrastructure (AWS)" 
        INFRA_BOOTSTRAP["Infra Bootstrap"]:::infra
        INFRA_BUILDER["Builder Infra"]:::infra
        INFRA_PIPELINES["Broker Pipelines Infra"]:::infra
        INFRA_DISTRIBUTOR["Distributor Infra"]:::infra
        INFRA_INDEXER["Indexer Infra"]:::infra
        INFRA_ORDERGEN_INFRA["Order-Generator Infra"]:::infra
        INFRA_ORDERSTREAM_INFRA["Order-Stream Infra"]:::infra
        INFRA_SLASHER["Slasher Infra"]:::infra
        INFRA_PROVER["Prover Infra"]:::infra
        INFRA_SAMPLE["Sample/Demo Infra"]:::infra
        INFRA_UTIL["Misc Infra"]:::infra
    end

    %% Documentation & Dev Tools
    subgraph "Documentation & Dev Tools"
        DOCS["Documentation Site"]:::docs
        DOCKER_SERVICES["Dockerfiles"]:::infra
        DOCKER_GRAFANA["Grafana Dashboards"]:::infra
        EXAMPLES["Examples & Tutorials"]:::docs
    end

    %% Relationships
    SDK -->|JSON-RPC calls| ETH
    CLI -->|JSON-RPC calls| ETH
    ETH -->|deploys & emits events| CONTRACTS
    CONTRACTS -->|events| BROKER
    BROKER -->|enqueues proof jobs| GUEST_UTIL
    BROKER -->|submits txs| ETH
    GUEST_UTIL -->|runs proofs| GUEST_ASS
    GUEST_ASS -->|returns proofs| BROKER
    BROKER -->|publishes events| INDEXER
    ETH -->|events| INDEXER
    INDEXER -->|writes data| PG_INDEXER
    INDEXER -->|powers| ORDERSTREAM
    ORDERSTREAM -->|reads data| PG_ORDERSTREAM
    ORDERSTREAM -->|serves WS/HTTP| SDK
    SLASHER -->|queries state| INDEXER
    SLASHER -->|submits slashing TX| ETH
    ORDERGEN -->|publishes orders| BROKER
    DISTRIBUTOR -->|coordinates fills| BROKER

    %% Storage interactions
    BROKER -->|stores metadata| S3
    ORDERSTREAM -->|archives| S3

    %% Infra deployments
    INFRA_BOOTSTRAP --> INFRA_BUILDER
    INFRA_BOOTSTRAP --> INFRA_PIPELINES
    INFRA_BOOTSTRAP --> INFRA_DISTRIBUTOR
    INFRA_BOOTSTRAP --> INFRA_INDEXER
    INFRA_BOOTSTRAP --> INFRA_ORDERGEN_INFRA
    INFRA_BOOTSTRAP --> INFRA_ORDERSTREAM_INFRA
    INFRA_BOOTSTRAP --> INFRA_SLASHER
    INFRA_BOOTSTRAP --> INFRA_PROVER
    INFRA_BOOTSTRAP --> INFRA_SAMPLE
    INFRA_BOOTSTRAP --> INFRA_UTIL

    DOCKER_SERVICES -->|containerize| BROKER
    DOCKER_SERVICES -->|containerize| INDEXER
    DOCKER_SERVICES -->|containerize| ORDERSTREAM
    DOCKER_SERVICES -->|containerize| SLASHER
    DOCKER_SERVICES -->|containerize| ORDERGEN

    DOCS -->|hosted on| S3

    %% Click events
    click CONTRACTS "https://github.com/boundless-xyz/boundless/tree/main/contracts/"
    click SDK "https://github.com/boundless-xyz/boundless/tree/main/crates/boundless-market/"
    click CLI "https://github.com/boundless-xyz/boundless/tree/main/crates/boundless-cli/"
    click BROKER "https://github.com/boundless-xyz/boundless/tree/main/crates/broker/"
    click INDEXER "https://github.com/boundless-xyz/boundless/tree/main/crates/indexer/"
    click ORDERSTREAM "https://github.com/boundless-xyz/boundless/tree/main/crates/order-stream/"
    click SLASHER "https://github.com/boundless-xyz/boundless/tree/main/crates/slasher/"
    click ORDERGEN "https://github.com/boundless-xyz/boundless/tree/main/crates/order-generator/"
    click DISTRIBUTOR "https://github.com/boundless-xyz/boundless/tree/main/crates/distributor/"
    click GUEST_ASS "https://github.com/boundless-xyz/boundless/tree/main/crates/guest/assessor/"
    click GUEST_UTIL "https://github.com/boundless-xyz/boundless/tree/main/crates/guest/util/"
    click INFRA_BOOTSTRAP "https://github.com/boundless-xyz/boundless/tree/main/infra/bootstrap/"
    click INFRA_BUILDER "https://github.com/boundless-xyz/boundless/tree/main/infra/builder/"
    click INFRA_PIPELINES "https://github.com/boundless-xyz/boundless/tree/main/infra/pipelines/"
    click INFRA_DISTRIBUTOR "https://github.com/boundless-xyz/boundless/tree/main/infra/distributor/"
    click INFRA_INDEXER "https://github.com/boundless-xyz/boundless/tree/main/infra/indexer/"
    click INFRA_ORDERGEN_INFRA "https://github.com/boundless-xyz/boundless/tree/main/infra/order-generator/"
    click INFRA_ORDERSTREAM_INFRA "https://github.com/boundless-xyz/boundless/tree/main/infra/order-stream/"
    click INFRA_SLASHER "https://github.com/boundless-xyz/boundless/tree/main/infra/slasher/"
    click INFRA_PROVER "https://github.com/boundless-xyz/boundless/tree/main/infra/prover/"
    click INFRA_SAMPLE "https://github.com/boundless-xyz/boundless/tree/main/infra/sample/"
    click INFRA_UTIL "https://github.com/boundless-xyz/boundless/tree/main/infra/util/"
    click DOCS "https://github.com/boundless-xyz/boundless/tree/main/documentation/"
    click DOCKER_SERVICES "https://github.com/boundless-xyz/boundless/tree/main/dockerfiles/"
    click DOCKER_GRAFANA "https://github.com/boundless-xyz/boundless/tree/main/dockerfiles/grafana/"
    click EXAMPLES "https://github.com/boundless-xyz/boundless/tree/main/examples/"

    %% Styles
    classDef rustServices fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef blockchain fill:#FFA500,stroke:#333,stroke-width:1px
    classDef client fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef infra fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#98FB98,stroke:#333,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef prov fill:#E6E6FA,stroke:#333,stroke-width:1px
```
