diff --git a/docs/products/hourglass-architecture.md b/docs/products/hourglass-architecture.md new file mode 100644 index 00000000..24e06be3 --- /dev/null +++ b/docs/products/hourglass-architecture.md @@ -0,0 +1,102 @@ +--- +sidebar_position: 5 +title: Architecture Overview +--- + +:::note +Hourglass is currently in public preview, and active development. +::: + +Hourglass is a task-based execution framework for building decentralized services (AVSs) requiring verifiable offchain compute. +Hourglass standardizes how developers define, distribute, execute, and verify compute tasks across decentralized operator networks. + +## Architecture + +[![](/img/hourglass-architecture_v.01.0.svg)](/img/hourglass-architecture_v.01.0.svg) + +## Onchain Components + +### TaskMailbox + +The `TaskMailbox` is an EigenLayer core contract deployed to Ethereum and each support L2 network, and is responsible for: + +* Allowing users and apps to create tasks. +* Managing the lifecycle of tasks. +* Verifying the results of tasks against the stake weight of the Operators in the Operator Set performing the work. +* Making the task verification results available for users and apps to query. +* Enabling AVSs to manage their TaskMailbox configurations. + +### TaskAVSRegistrar + +The `TaskAVSRegistrar` is a per-AVS EigenLayer middleware contract that is responsible for: + +* Handling Operator registration for specific Operator Sets of your AVS. +* Providing the offchain components with BLS public keys and socket endpoints for the Aggregator and Executor operators. + +The default `TaskAVSRegistrar` is a copy of the provided contract and works as provided. `TaskAVSRegistrar` can be extended +to include additional onchain logic for your use case. + +### AVSTaskHook + +The `AVSTaskHook` is a per-AVS EigenLayer Hourglass contract that is responsible for: + +* Validating the task lifecycle. +* Creating fee markets for your AVS. + +It's empty by default and works out of the box, but can be extended to include additional onchain validation logic for your AVS. + +### CertificateVerifier + +The `CertificateVerifier` is an EigenLayer core contract that is responsible for: + +* Verifying the validity of Operator certificates. +* Verifying stake threshold requirements for Operator Sets. + +## Offchain Components + +### Aggregator + +The Aggregator is responsible for: + +* Listening to events from the Mailbox contract on chain for new tasks +* Discovering Executors by querying the `AVSRegistrar` contract, retrieving their metadata containing a BLS public key and a socket (URL) endpoint that references the Executor's gRPC server. +* Distributing tasks to Executors by sending a gRPC request to the Executor's socket endpoint, including the task payload and a signature of the payload signed by the Aggregator. This enables the Executor to validate the message is coming from the expected Aggregator. +* Aggregating results from Executors until a signing threshold has been met. +* Publishing the result back to the Mailbox contract. + +### Executor + +The Executor is responsible for: + +* Launching and managing Performer containers that execute the tasks. +* Listening to gRPC requests from the Aggregator for new tasks. +* Forwarding the task to the correct Performer. +* Signing the result of the task with its BLS private key and sending it back to the Aggregator. + +### Performer + +The Performer is the component the AVS is responsible for building. At a high level, it is a simple gRPC server that listens +for tasks, runs them and returns the results to the Executor. + +The Hourglass framework provides all of the boilerplate and server code for your Performer; you simply need to fill in the logic to +handle tasks for your AVS. + +For information on how to implement an AVS using the Hourglass template, refer to [Implementing with Hourglass](implementing-with-hourglass.md). + +:::important +Rewards and Slashing are areas that Hourglass does not yet provide opinionated solutions for and must be implemented separately: + +* Rewards logic and distribution + + Hourglass does not include logic for how Operator rewards are calculated or distributed. Each AVS must design and + implement a reward model that aligns with its own incentives and application-specific goals. This logic can be implemented + onchain or offchain, but is out of scope for the Hourglass framework. + +* Slashing Logic and Handling + + Hourglass does not provide slashing mechanisms. AVS developers are responsible for defining how to detect operator misbehavior + and determine the conditions and consequences for slashing. This logic must be implemented independently of the Hourglass AVS + contracts and tooling. + +These areas are not part of the Hourglass framework and must be handled externally based on the specific needs of the AVS. +::: \ No newline at end of file diff --git a/docs/products/implementing-with-hourglass.md b/docs/products/implementing-with-hourglass.md new file mode 100644 index 00000000..30a2b690 --- /dev/null +++ b/docs/products/implementing-with-hourglass.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 5 +title: Using Hourglass to Implement Your AVS +--- + +## What Hourglass Provides + +The Hourglass template provides a basic structure for building an AVS with the Hourglass framework. It includes: + +* A stub of Go code for your Performer. +* Default `TaskAVSRegistrar` and `AVSTaskHook` AVS contracts that work out of the box. These contracts can be extended to add additional onchain logic. +* All dependent contracts required by the framework and the scripts to deploy them. The scripts are managed by the Devkit CLI. +* A docker-compose stack to run an Aggregator and Executor locally to test your AVS. +* Integration with the DevKit CLI. DevKit provides a streamlined, modular experience for scaffolding your projects, compiling, running local networks, and testing. + +## What You Need to Implement + +| Component | Purpose | Developer to Implement | Required or Optional | +|-----------------------------------------------------|-----------------------|----------------------------------------------|----------------------| +| `main.go` | Task logic | Write AVS-specific task processing | Required | +| Smart Contracts (`TaskAVSRegistrar`, `AVSTaskHook`) | Onchain AVS logic | Modify if you need custom onchain behavior | Optional | +| Config files (`.hourglass`, `.devkit`) | Runtime and CLI setup | Customize paths, images, and network | Optional | +| Task Input | Task testing | Create representative input data | Optional | +| `docker-compose.yml` | Local setup | Edit to match your environment | Optional | + +## Local Development and Testing + +### Task processing in main.go + +`main.go` implements the offchain binary run by Operators running the Hourglass Executor. That is, the core business logic +for processing tasks. It contains the business logic of the AVS and performs worked based on the tasks sent to it. + +The Hourglass Aggregator ingests tasks from the TaskMailbox and distributes work to Executors configured to run the AVS Performer. + +Performers execute the work and return the result to the Executor where the result is signed and returned to the Aggregator to +place in the outbox once the signing threshold is met. + +Minimal `VadildateTask` and `HandleTask`functions are provided in `main.go` to get you started. The code can be restructured +as needed for your AVS requirements. + +### AVS Onchain Logic in Contract + +The example `HelloWorld.sol` contract is included. Delete and replace with a contract implementing your AVS onchain logic. + +This contract provides the onchain coordination for your AVS linking offchain task processing with onchain validation. + +### Task Callback Logic in AVSTaskHook + +Extend `AVSTaskHooks` to include additional onchain logic to: +* Validate the task lifecycle. +* Create a fee market for your AVS. + +### Contract Deployment in DeployMyContracts.s.sol + +Wire up your contracts in `DeployMyContracts.s.sol`. This script is automatically called during `devkit avs devnet start`. + +## Deployment to Testnet + +### Operator Registration in TaskAVSRegistrar + +`TaskAVSRegistrar` defines which Operators can register as an Operator for your AVS to be an Aggregator and/or an Executor. + +:::tip +When running the devnet locally, Operators are set up by Hourglass and Operator registration does not need to be implemented. +::: + +For detailed information on the Hourglass framework, refer to the [Readme in the Hourglass repo](https://github.com/Layr-Labs/hourglass-avs-template). \ No newline at end of file diff --git a/static/img/hourglass-architecture_v.01.0.svg b/static/img/hourglass-architecture_v.01.0.svg new file mode 100644 index 00000000..c9c1b78a --- /dev/null +++ b/static/img/hourglass-architecture_v.01.0.svg @@ -0,0 +1 @@ + \ No newline at end of file