Syndicate Appchains

This monorepo contains the complete Syndicate Appchains infrastructure stack. It includes the core components for building, deploying, and managing Syndicate appchains.

👾 Note to developers

If you wish to fork or build on top of the Syndicate Appchains stack, be mindful of potential rough edges or undocumented functionality in early versions of the software. While we aim to maintain semantic versioning (SemVer) in our releases, breaking changes may still occur.

Please reach out at https://syndicate.io/contact or create a Github issue in the repo for additional support.

📖 Documentation

For detailed documentation, architecture guides, and tutorials, visit docs.syndicate.io

🏗️ Architecture Overview

Syndicate Appchains enables the creation of custom blockchains that utilize a two-source chain architecture:

• Sequencing Chain: Stores transaction data and handles appchain sequencing
• Settlement Chain: Manages fund bridging from/to the rollup

This design provides cost-effective, customizable sequencing while leveraging the liquidity and security of existing blockchain networks.

🚀 Quick Start

Prerequisites

Ensure you have the following dependencies installed:

Dependency	Version	Installation
Rust Toolchain	1.88.0+	rustup.rs
Go	1.24.3+	golang.org
Foundry/Forge	1.3.1-stable	getfoundry.sh
Docker	28.2.2+	docker.com
abigen	1.15.11-stable+	go install github.com/ethereum/go-ethereum/cmd/abigen@latest
SP1 Toolchain	v5.0.5+	SP1 Documentation
NodeJS	v22.9.0+	nodejs.org
Yarn	1.22.22+	yarnpkg.com

Development Setup

1. Clone the repository and download submodules

   git clone https://github.com/syndicateio/syndicate-appchains.git
   cd syndicate-appchains
   git submodule update --init

2. Install development tools

   # Install pre-commit hooks
   pip install pre-commit
   pre-commit install
   
   # Install Rust utilities
   cargo install cargo-machete
   cargo install taplo-cli

3. Build the project

   # Build all Rust components
   cargo build
   
   # Build smart contracts
   cd synd-contracts
   forge build

🧪 Testing

# Run all tests
cargo nextest run --workspace

# Run specific component tests
cargo test -p synd-translator
cargo test -p synd-maestro

# Run smart contract tests
cd synd-contracts
forge test

🔧 Code Quality

Formatting and Linting

# Format Rust code
cargo +nightly fmt --all -- --unstable-features

# Run Clippy linter
cargo clippy --workspace --all-targets --all-features

# Format TOML files
taplo fmt "path/to/Cargo.toml"

# Check for unused dependencies
cargo machete

📁 Project Structure

syndicate-appchains/
├── synd-translator/         # Source chains data translation and slotting into mchain blocks
├── synd-maestro/            # Transaction management and Redis streams
├── synd-batch-sequencer/    # Transaction batching and submission
├── synd-chain-ingestor/     # Chain data ingestion and caching
├── synd-mchain/             # Mchain storage and RPC API
├── synd-contracts/          # Smart contracts
├── synd-withdrawals/        # TEE-based withdrawal system
│   ├── synd-enclave/        # Trusted Execution Environment enclave code
│   ├── synd-proposer/       # Proposer service that publishes signed state commitments on-chain
│   └── synd-tee-attestation-zk-proofs/  # ZK proof system for TEE attestation docs
├── test-framework/          # Integration testing
└── documentation/           # Deployment guides and configs

Core Components

Rust Services

• synd-translator: Reads block data from each source chain's ingestor, uses slotter logic to fit them into slots and transforms data into mchain blocks
• synd-maestro: Receives user appchain transactions and adds them to Redis streams (one stream per chain), where sequencers can read from. Handles transaction re-submission for re-orgs or sequencer failures
• synd-batch-sequencer: Reads from Redis transaction streams, batches/compresses transactions, then signs and publishes batches to the sequencing chain
• synd-chain-ingestor: Connects to source chains and builds a cache of (block_hash, timestamp) pairs for fast translator cold-sync. Reads new data from upstream RPC and forwards to translators
• synd-mchain: Stores mchain block data in RocksDB database. Implements the RPC API that rollup nodes expect when reading from Ethereum
• test-framework: Integration testing framework

Smart Contracts

• synd-contracts: Core system contracts including SystemConfig, AppchainFactory, Inbox/Outbox, and withdrawal system contracts

Withdrawal System

• synd-enclave: TEE (Trusted Execution Environment) component that receives block data from Ethereum L1, sequencing chain, and settlement chain, applies the rollup STF to derive rollup state, and signs state commitments enabling withdrawals
• synd-proposer: Connects TEE to settlement chain bridge. Feeds chain data to TEE enclave, obtains signed state commitments (sendRoot), and submits them to the TEEModule smart contract
• synd-tee-attestation-zk-proofs: Multi-component system for TEE attestation:
  • aws-nitro: Validates TEE attestation documents signed by Amazon's x509 root certificate
  • sp1: SP1-specific implementation for generating and verifying ZK proofs of AWS Nitro attestation
  • proof-submitter: CLI tool for fetching TEE attestation, generating SP1-based ZK proofs, and submitting on-chain

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (cargo test && cargo clippy)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow Rust coding standards and use cargo fmt and cargo clippy
• Write comprehensive tests for new features
• Update documentation for any API changes
• Ensure all tests and pre-commit hooks pass before submitting PRs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: docs.syndicate.io
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Audits

PDF reports for the latest audits are available in the audits directory.