How boundless-xyz/boundless works
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