Gasp Monorepo

Warning: For testnet use only. Not production-ready.

Project Overview

Gasp is a Layer 2 solution utilizing Eigen Layer for security and consensus:

Component	Directory	Description
Gasp ETH Contract	contracts/	Handles ERC20 deposits and withdrawals on Ethereum
Sequencer	sequencer/	Processes transactions and submits them to the collator
Collator	gasp-node/	Builds L2 blocks using Substrate framework
Updater	updater/	Monitors Eigen Layer tasks and submits results to ETH contract
Aggregator & Task Manager	avs-aggregator/	Generates tasks and aggregates operator results
Gasp AVS	gasp-avs/	Decentralized operators that verify Merkle roots and re-execute blocks
Ferry Services	ferry-deposit/, ferry-withdrawal/	Handle cross-chain asset transfers
Stash	stash/	Node.js service for data management
Eigen ETH Contracts	contracts/lib/eigenlayer-contracts/	Manages storage Merkle roots and operator lists

Setup Guide

Prerequisites

• Foundry: Required for running local testnet

  curl -L https://foundry.paradigm.xyz | bash
  foundryup

• Rust Toolchain: Required for Rust-based services

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Go Toolchain: With zap-pretty for logging

  go install github.com/maoueh/zap-pretty@latest

• Proto & Moon: For toolchain and task management

  # Install proto for toolchain management
  bash <(curl -fsSL https://moonrepo.dev/install/proto.sh)
  
  # Run `proto install` to install toolchain dependencies and setup your machine for development
  proto install

• Docker Compose: For running multi-container setup See Docker Compose installation instructions for platform-specific instructions

Development Setup

1. Clone and initialize submodules:

   git clone https://github.com/gasp-xyz/gasp-monorepo.git
   cd gasp-monorepo
   git submodule update --init --recursive

2. Setup Git hooks with Husky:

   # Proto will automatically install dependencies and set up Husky
   yarn run postinstall

   Our repository uses:

   • Husky for Git hooks
   • commitlint for validating commit messages using the Conventional Commits standard

3. Follow the contribution guidelines for branch naming and commit formats

Proto Shell Activation (Optional)

For an optimized development experience in a complex monorepo with multiple toolchains (Rust, Go, Node.js), you can set up Proto's shell activation. This is particularly helpful as switching between services with different toolchain requirements can become cumbersome:

1. Add shell activation to your profile:

   # For Bash (~/.bashrc)
   eval "$(proto activate bash)"
   
   # For Zsh (~/.zshrc)
   eval "$(proto activate zsh)"

2. Restart your terminal or source your profile file

Benefits for Gasp monorepo development:

• Handles automatic switching between multiple toolchains when navigating between service directories
• Recognizes not only .prototools files but also .nvmrc files for Node.js version management
• Automatically loads and exports the correct environment variables for each service
• Ensures all developers use identical toolchain versions across the codebase
• Prevents the common "wrong version" issues when working with multiple services

The different services in our monorepo (Go-based avs-aggregator, Rust-based sequencer, Node.js-based ferry services) each require specific tool versions and configurations. With Proto shell activation, these are managed automatically as you navigate through the codebase.

Note: Shell activation should be added after all PATH modifications in your shell profile, as any PATH changes made after the activation line will be lost when activation triggers. For detailed setup instructions for different shells and additional options, see the Proto Activate Command documentation.

For general information on Proto workflows, see the Proto Workflows documentation.

Running Locally

Using Docker Compose

# Build Docker images
moon :build-image-local

# Start all services (for M1/M2 Macs, disable Rosetta emulation in Docker Desktop)
docker compose up -d

# Tear down
docker compose down -v

Technical Architecture

AVS Architecture

The architecture of the AVS contains:

• Eigenlayer core contracts
• AVS contracts
  • ServiceManager - Will eventually contain slashing logic
  • TaskManager - Handles task creation and responses
  • Registry contracts - Manages operator registration
• Task Generator - Creates tasks for block verification (currently part of the aggregator)
• Aggregator - Collects and verifies BLS signatures from operators
• Gasp AVS Operators - Execute blocks and provide signatures

AVS Task Flow

1. Task Generator publishes tasks to the createNewTask function, specifying block numbers and quorum thresholds
2. Registered operators (with minimum 1 delegated token) execute the specified blocks
3. Operators sign results using BN254 curve and send signatures to the aggregator
4. Aggregator collects signatures and posts aggregated responses that meet threshold requirements
5. Responses within the response window enter dispute resolution (not yet implemented)

Stake Updates

AVS Registry contracts have a stale view of operator shares in the delegation manager contract. To update the stake table, operators need to periodically call the StakeRegistry.updateStakes() function. Currently, we use an internal script to handle this manually.

Integration Testing

For detailed testing instructions, see the integration tests README.

AVS Node Specification

Gasp AVS nodes are being developed to comply with the Eigenlayer AVS Node Specification, which requires:

• Implementation of the AVS Node API
• Implementation of Eigen prometheus metrics

Contributing

Please read CONTRIBUTING.md for details on our development workflow, branch strategy, and release process.