Agglayer

The Agglayer (Aggregation layer) provides a common language for secure, atomic, interoperability among heterogeneous chains. (WIP)

---

Table of Contents

• Overview
• Repository Structure
• Prerequisites
  • Succinct Prover Network
  • Software Requirements
  • Hardware Requirements
• Installation
• Running the Pessimistic Proof Test Suite
• Development
• Support
• Resources
• License

Overview

Agglayer is the Rust-based service designed to:

1. Receive updates from Agglayer-connected chains
2. Verify their validity
3. Send them to the L1 for final settlement.

To find out more about Agglayer, please visit the more detailed documentation.

Warning

• Some of the content in this section discusses technology in development and not ready for release. As such, all APIs and configuration are subject to change. The code is still being audited, so please contact the Polygon team if you would like to use it in production.

Repository Structure

The crates and their functions within the Agglayer repo are as follows:

Crate	Description
agglayer-aggregator-notifier	Contains implementations for Certifier which applies new Certificate on top of an existing state and computes the proof, as well as EpochPacker, which handles the packing of an epoch
agglayer-certificate-orchestrator	Manages the orchestration and handling of certificates; also handles current_epoch, which allows non-orchestrators to push a proven certificate
agglayer-clock	Defines the pace of the Agglayer in terms of epoch with support for two clocks: time (for testing) and block (for listening for L1 blocks)
agglayer-config	Manages configuration settings and parameters for Agglayer components
agglayer-contracts	Contains smart contracts and related logic
agglayer-gcp-kms	Provides integration with GCP's Key Management Service for secure key handling
agglayer-node	Responsible for spawning and running the different components of the node
agglayer-prover-types	Defines data structures and types used by the prover
agglayer-prover	Responsible for running everything related to the prover
agglayer-signer	Manages signing operations
agglayer-storage	Contains two layers: a physical layer for abstracting RocksDB and a logic layer for exposing the interface to other crates so that they may interact with the storage
agglayer-telemetry	Handles telemetry and monitoring functionalities
agglayer-types	Defines common data types and structures
agglayer	The CLI for interacting with the Agglayer
pessimistic-proof-program	Implements the pessimistic proof program
pessimistic-proof-test-suite	Provides a suite of tests for validating the functionality of the pessimistic proof program
pessimistic-proof	Contains the core logic and implementation of the pessimistic proof mechanism

Prerequisites

Before working with the repository, you’ll need the following:

Succinct Prover Network

You’ll need to submit a unique Ethereum address to Succinct for access to their proving network. To get access:

1. Follow the instructions here to use Foundry to generate a new private key or retrieve an existing one.
2. Apply for access for the public address associated with your private key to Succinct Network here.

Software Requirements

• Rustup (stable)
• protoc
• nextest
• cargo-make
• cargo-insta
• Go

Hardware Recommendations

With SP1, you do not need to generate proofs locally on your machine.

However, if you’d like to run a prover locally (not recommended), you’ll need roughly 40-50GB of available RAM.

Installation

To install the Agglayer repository, please run the following:

git clone https://github.com/agglayer/agglayer
cd agglayer

To build Agglayer locally, please run:

cargo build

Running the Pessimistic Proof Test Suite

To run the Pessimistic Proof Test Suite with test inputs in Native Rust Execution, please run the following:

cargo test --package pessimistic-proof-test-suite

You can find the test inputs here: ./agglayer/crates/pessimistic-proof-test-suite

Modifying and building the Pessimistic Proof

By default, the committed pre-compiled ELF binary is used. Modifications in PP code will not be automatically reflected in the binary. We use docker-based deterministic build to compile the proof. Therefore, docker has to be present on the system for the build to work if PP rebuild is enabled.

Building PP one-off

The following command rebuilds the PP and updates some snapshot tests that depend on it. It requires cargo-make to be installed:

cargo make pp-elf

Turning on automatic PP rebuild

This option makes the standard commands like cargo build, cargo run etc. rebuild the PP automatically any time it changes as if it were a normal part of the build. It is enabled by setting the AGGLAYER_ELF_BUILD environment variable to update.

export AGGLAYER_ELF_BUILD=update

Note: Rust suppresses the output of build scripts by default. As a result, the build may appear stuck on the pessimistic-proof crate while the PP is being rebuilt.

In the update mode, the proof will be rebuilt and the cached ELF will be updated. There is also the build mode which leaves the cached ELF intact. It is mostly useful for debugging, the update is more suitable for regular development.

To get automatic rebuilds by default, set the variable in the shell init script.

Proof versioning policy

The proof binary to use is uniquely identified by a vkey selector on the L1. The selector is derived from the major version of the pessimistic-proof-program package. This version must be bumped between releases / deployments.

There is a snapshot test that will fail once the proof vkey changes to prompt the developers to consider whether a version bump is needed. Once that is determined and the package version is updated (or not updated, as appropriate), the new vkey is accepted by running:

cargo make pp-accept-vkey-change

Running SP1 Proof Generation Locally (Not Recommended)

The Succinct Prover Network is the best way to generate Pessimistic Proofs for Agglayer.

For those with the hardware and know-how, however, you can run the Pessimistic Proof program in a local SP1 Prover with the following commands:

cargo run --package pessimistic-proof-test-suite --bin ppgen

Running Integration Tests

Prerequisites

To run the integration tests, you'll need to build the contracts image first, and then run the tests with the integration profile:

1. Clone the contracts repository:

   git clone https://github.com/agglayer/agglayer-contracts

2. Build the contracts Docker image:

   cd agglayer-contracts
   npm install
   npm run dockerv2:contracts:all

Running the tests

Once the prerequisites are ready, you can now return to the main agglayer directory and run the integration tests:

cargo nextest run --workspace -P integrations --no-fail-fast --retries 2

Potential issues

Note that, due to the use of docker, sometimes there are leftover containers that cause issues with the integration tests. In this case, just delete any container you might have, and rerun the integration tests. You may also need to rebuild the contracts Docker image, if there have been updates there.

Also, there are quite a few intermittent failures in the tests, that can be helped thanks to the suggested --retries 2.

Finally, --no-fail-fast is useful to start the integration tests and then come back after a coffee to see all the failing tests: a full run of integration test takes around ten minutes on a Macbook M4 Pro.

Development

Contributions are very welcomed, the guidelines are currently not available (WIP)

Support

Feel free to open an issue if you have any feature request or bug report.

Resources

License

Copyright (c) 2024 PT Services DMCC

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

The SPDX license identifier for this project is MIT OR Apache-2.0.