https://github.com/avaprotocol/eigenlayer-avs
AvaProtocol Ethereum Automation Build on EigenLayer
https://github.com/avaprotocol/eigenlayer-avs
eigenlayer eigenlayer-avs eigenlayer-operators ethereum
Last synced: 2 months ago
JSON representation
AvaProtocol Ethereum Automation Build on EigenLayer
- Host: GitHub
- URL: https://github.com/avaprotocol/eigenlayer-avs
- Owner: AvaProtocol
- Created: 2024-04-05T17:47:32.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-29T08:38:15.000Z (5 months ago)
- Last Synced: 2026-01-29T22:29:55.423Z (5 months ago)
- Topics: eigenlayer, eigenlayer-avs, eigenlayer-operators, ethereum
- Language: Go
- Homepage: https://avaprotocol.org
- Size: 76.9 MB
- Stars: 79
- Watchers: 1
- Forks: 75
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Ava Protocol Automation On Ethereum
> **Latest Update**: Enhanced with structured error system (ErrorCode enum) and improved operator reconnection logic for better reliability.
The Ava Protocol AVS can be compiled directly using Go version 1.22+. Ensure you have the appropriate version of Go installed on your development environment.
Check Go version:
```
go version
```
Compile Ava Protocol AVS:
```
go build -o ap-avs
```
Then you can run `ap-avs` binary. We make an effort to use pure Go so you can also cross compile for any supported architecture that the Go compiler support.
## Run operator
Check how to run an [operator docs](docs/Operator.md)
### Run aggregator
To run the aggregator, use the following command:
```
ap-avs aggregator
```
Note: The Ava Protocol team currently manages the aggregator, and the communication IP address between the operator and the aggregator is hardcoded in the operator.
### Fee Estimation
See [docs/FEE_ESTIMATION.md](docs/FEE_ESTIMATION.md) for the fee pricing model, configuration, and implementation details.
#### Benefits
- **Dynamic Pricing**: Change rates without code deployments
- **Environment-Specific**: Different rates for dev/staging/production
- **A/B Testing**: Test different pricing models
- **Backward Compatible**: Works without any configuration changes
- **Partial Overrides**: Only specify rates you want to change
- **Zero Disruption**: Existing configurations continue to work
# How it works
## User wallet
For each owner we deploy a ERC6900 wallet to schedule task and approve spending
to user wallet.
Each task type has its equivalent modular code to re-present its condition
and their actual execution.
## Aggregator
Aggregator accepts RPC request from client to submit Task Payload. Currently, aggregator is managed and run by Ava Protocol team.
Periodically, aggregator combine the task submission, update our internal
storage and a zkSNARK proof will be write back to our TaskManager contract.
Aggregator also accept task condition check result from operator, perform quorum
and consensus check, then write the result back and flag that a task is good to
run.
### Aggregator Address
The aggregator is currently run and managed by the Ava Protocol team. Depend on
testnet or mainnet, you would need to point your operator to the right address
in the operator config file.
#### Sepolia Testnet
- aggregator-sepolia.avaprotocol.org:2206
- [https://api-explorer-sepolia.avaprotocol.org/](https://api-explorer-sepolia.avaprotocol.org/)
#### Mainnet
- aggregator.avaprotocol.org:2206
- [https://api-explorer.avaprotocol.org/](https://api-explorer.avaprotocol.org/)
## Operators
Operators communicates with aggregators through RPC. It requests task data from aggregator, it performs condition execution to check whether a task can be trigger. The result is then sent back to aggregator.
For task is ok to run, the operator will executed them. The detail of how task
is triggering through our ERC6900 modular wallet will come soon.
## Ava Protocol operator address
Currently, Ava Protocol has deployed our operator on the testnet. Community members can run their own operator and register for Ava Protocol AVS service, or they can delegate their tokens to the Ava Protocol operator.
### Testnet
- Ava Protocol's operator: [0x997e5d40a32c44a3d93e59fc55c4fd20b7d2d49d](https://sepolia.eigenlayer.xyz/operator/0x997e5d40a32c44a3d93e59fc55c4fd20b7d2d49d).
### Mainnet
- Ava Protocol's operator: [0xc6B87cc9e85b07365b6aBEfff061F237F7cf7Dc3](https://etherscan.io/address/0xc6B87cc9e85b07365b6aBEfff061F237F7cf7Dc3)
## Telemetry Dashboard
Operator that is connected to Ava Protocol aggregator can also check their
operator on our telemetry dashboard as below
### Testnet
https://aggregator-sepolia.avaprotocol.org/telemetry
### Mainnet
https://aggregator.avaprotocol.org/telemetry
## Branching Strategy
All feature branches and pull requests must target the `staging` branch. The `main` branch is only updated by merging `staging` → `main` after migration checks pass. Never open a PR directly against `main`.
## Migration Guide
Before merging changes from `staging` to `main`, ensure any storage structure changes are properly migrated:
1. **Check for Storage Changes**
```bash
# First checkout staging branch
git checkout staging
# Compare with main to detect storage changes
go run scripts/compare_storage_structure.go main
```
2. **When Migration is Needed**
- Storage key format changes
- Non-backward-compatible data structure changes
- Required field additions (without `omitempty`)
- Field type changes
- Field removals
- **Protobuf message structure changes** (manual analysis required)
- **Trigger/node output format changes** (manual analysis required)
3. **Migration Process**
**For Go Struct Changes (Automated):**
```bash
# First checkout staging branch
git checkout staging
# Compare with main to detect storage changes
go run scripts/compare_storage_structure.go main
# If changes are detected, generate a migration file
go run scripts/migration/create_migration.go main
```
**For Protobuf Changes (Manual Analysis Required):**
```bash
# Compare protobuf changes between branches
git diff origin/main..staging protobuf/
# Analyze for breaking changes in:
# - Trigger output structures (e.g., timestamp -> data field)
# - Node input/output formats (e.g., input field removal)
# - Manual trigger structure changes (boolean -> ManualTrigger)
# - Contract ABI format changes (string -> array)
```
4. **Migration Types**
**Automated Migration (Go Structs):**
The migration script will:
- Create a timestamped migration file in `./migrations`
- Include detected changes as comments
- Provide example migration code
- Add the migration to `Migrations` slice in `./migrations/migrations.go`
**Manual Migration (Protobuf Changes):**
- Create migration file manually following existing patterns
- Focus on data cleanup rather than backward compatibility
- Cancel/remove incompatible workflows and executions
- Clear cached data that needs regeneration
5. **No Migration Needed For**
- Adding fields with `omitempty` JSON tags
- Runtime-only changes
- Backward-compatible modifications
- New optional protobuf fields
6. **Active Migrations**
Current active migrations that will run on deployment:
- `20250603-183034-token-metadata-fields` - TokenMetadata struct field additions
- `20250128-120000-protobuf-structure-cleanup` - v1.9.6 protobuf structure cleanup
- Cancels workflows with incompatible trigger structures
- Removes executions with old trigger output formats
- Cleans cached data for regeneration
- **Impact**: Workflows with old manual triggers or loop/filter nodes will be canceled
> **Important**: Always run migrations before merging to `main`. For protobuf changes, manual analysis is required as the automated scripts may not detect all breaking changes.
> **v1.9.6 Note**: The protobuf structure cleanup migration will cancel workflows with incompatible structures. Ensure critical workflows are backed up before deployment.
# Development guide
View docs/Development.md
## Testing
### Test Configuration
For integration tests that require interaction with blockchain networks, you need to configure test credentials:
#### Required Environment Variables
```bash
# Owner EOA wallet of testing smart wallets (must have funds on test networks)
OWNER_EOA=
# Test network endpoints
SEPOLIA_RPC=https://your-sepolia-rpc-endpoint
SEPOLIA_BUNDLER_RPC=https://your-sepolia-bundler-endpoint
```
#### Security Notice
⚠️ **SECURITY WARNING**:
- Never use private keys containing real funds for testing
- Use dedicated test keys funded only with testnet tokens
- The fallback private key (all 1's) is insecure and only for development
- Always configure proper test keys via environment variables or config files
#### Test Key Setup
1. Generate a new private key for testing (or use an existing test key)
2. Fund the corresponding address with testnet tokens (Sepolia ETH, test USDC, etc.)
3. Set the `OWNER_EOA` environment variable or add it to your config
4. Ensure the key has sufficient balance for test transactions
## Testing
### Standard Tests
The Makefile includes two primary test configurations:
```bash
# Default test suite
go test -race -buildvcs -vet=off ./...
# Verbose test output
go test -v -race -buildvcs ./...
```
### Enhanced Test Output
For improved test result formatting, use `gotestfmt`:
1. Install the formatter:
```bash
go install github.com/gotesttools/gotestfmt/v2/cmd/gotestfmt@latest
```
2. Run once in the current terminal session to make Bash scripts more robust and error-aware.
```bash
set -euo pipefail
```
3. Run tests with formatted output:
Run all tests with complete output:
```base
go test -v ./...
```
or, run selected test cases:
```bash
go test -json -run ^TestRestRequestErrorHandling$ ./... 2>&1 | gotestfmt --hide=all
```
The `--hide=all` flag suppresses output for skipped and successful tests, showing only failures. For more output configuration options, see the [gotestfmt documentation](https://github.com/GoTestTools/gotestfmt?tab=readme-ov-file#how-do-i-make-the-output-less-verbose).
=======
## Linting and Code Quality
### Running the linter
```bash
# Install golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.55.2
# Run the linter
golangci-lint run ./...
# Or use the Makefile target
make audit
```
### Best practices for running linters
- Run linters before committing code to catch issues early
- Configure your IDE to run linters on save for immediate feedback
- Include linting in CI/CD pipelines to enforce code quality standards
- Fix linting issues as they arise rather than letting them accumulate
### Get all Github CI/CD failures
The script is configured in Makefile, so run the below command to retrieve failed tests.
`make cicd-failed RUN_ID=16632516768`
Example output:
```
make cicd-failed RUN_ID=16632516768
--- FAIL: TestEventTriggerQueriesBasedMultipleContracts (0.07s)
--- FAIL: TestEventTriggerQueriesBasedMultipleContracts/Transfer_FROM_target_address_(any_token) (0.00s)
--- FAIL: TestEventTriggerQueriesBasedMultipleContracts/Transfer_TO_target_address_(any_token) (0.00s)
```
## Dependencies
## Update Protobuf Definitions
When you modify any `.proto` files (primarily `protobuf/avs.proto` or `protobuf/node.proto`), you need to regenerate the corresponding Go bindings.
### Prerequisites
1. **Install `protoc` (the protobuf compiler):**
If you don't have it, download it from the [protobuf releases page](https://github.com/protocolbuffers/protobuf/releases) and ensure it's in your system's `PATH`.
2. **Install Go plugins for `protoc`:**
These commands will install the necessary Go code generators for protobuf messages and gRPC services. Ensure your `$GOPATH/bin` or `$HOME/go/bin` is in your system `PATH`.
```bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```
### Generation Command
After installing the prerequisites, run the following Make target from the project root:
```bash
make protoc-gen
```
### Expected File Structure & Go Package
- **Proto source files:** Reside in the `protobuf/` directory (e.g., `protobuf/avs.proto`, `protobuf/node.proto`).
- **`go_package` option:** Both `avs.proto` and `node.proto` use `option go_package = "github.com/AvaProtocol/EigenLayer-AVS/protobuf;avsproto";`.
- This directs `protoc-gen-go` to generate files that will be part of the Go package aliased as `avsproto`.
- The import path for this package in your Go code will be `github.com/AvaProtocol/EigenLayer-AVS/protobuf` (assuming `github.com/AvaProtocol/EigenLayer-AVS` is your module name from `go.mod`).
- **Generated Go files:** The `make protoc-gen` command is configured (via `--go_out=.` and the `go_package` option) to place the generated `*.pb.go` and `*_grpc.pb.go` files directly into the `protobuf/` directory.
- Example: `protobuf/avs.pb.go`, `protobuf/node.pb.go`.
- All these generated files will contain the Go package declaration: `package avsproto`.
### Using the Generated Code in Go
To use the generated types and gRPC clients/servers in your Go code, import the package as follows:
```go
import (
// ... other imports
avspb "github.com/AvaProtocol/EigenLayer-AVS/protobuf" // Use a suitable alias like avspb
)
func main() {
req := &avspb.IdReq{Id: "test-id"}
// ... use other types like avspb.Task, avspb.AggregatorClient, etc.
}
```
**Important:** If you change the `go_package` option in the `.proto` files or the output paths in the `Makefile`, you will likely need to update the import paths in your Go codebase accordingly.
## Testing Bundler Connectivity
The Ava Protocol uses ERC-4337 bundlers for smart wallet transactions. You can test bundler connectivity using the following commands:
### Basic Connectivity Test
Test if the bundler is responding:
```bash
curl -X POST https://bundler-sepolia.avaprotocol.org/rpc?apikey= \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
```
**Expected Response:**
```json
{"jsonrpc": "2.0", "id": 1, "result": "0xaa36a7"}
```
### ERC-4337 EntryPoint Support
Check which EntryPoint contracts the bundler supports:
```bash
curl -X POST https://bundler-sepolia.avaprotocol.org/rpc?apikey= \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_supportedEntryPoints","params":[],"id":1}'
```
**Expected Response:**
```json
{"jsonrpc": "2.0", "id": 1, "result": ["0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108", "0x0000000071727De22E5E9d8BAf0edAc6f37da032", "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"]}
```
### Gas Estimation Test
Test UserOp gas estimation (will fail for non-deployed accounts, which is expected):
```bash
curl -X POST https://bundler-sepolia.avaprotocol.org/rpc?apikey= \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_estimateUserOperationGas","params":[{"sender":"0x69bb9251D3c2066DcF7aDAFe3E7CE36E76990617","nonce":"0x0","initCode":"0x","callData":"0x","callGasLimit":"0x0","verificationGasLimit":"0x0","preVerificationGas":"0x0","maxFeePerGas":"0x0","maxPriorityFeePerGas":"0x0","paymasterAndData":"0x","signature":"0x"},"0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"],"id":1}'
```
**Expected Response (for non-deployed account):**
```json
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32500, "message": "AA20 account not deployed"}}
```
### User Operation Debugging Scripts
Query and debug user operations using the provided scripts:
```bash
# Query specific user operation by hash
./scripts/query_userop.sh 0x1234567890abcdef... [status|receipt|both]
# Debug bundler connectivity and health
./scripts/bundler_debug.sh
# Search recent user operations (requires SEPOLIA_RPC)
export SEPOLIA_RPC=https://sepolia.infura.io/v3/YOUR_KEY
./scripts/search_recent_userops.sh [sender_address] [blocks_back]
```
### Troubleshooting
- **Connection refused**: Check network connectivity and firewall settings
- **401 Unauthorized**: Verify the API key in the bundler URL
- **Parse error**: Check JSON formatting and Content-Type header
- **AA20 account not deployed**: Normal for testing with random addresses
- **Method not found**: Bundler may not support that specific ERC-4337 method
## Getting started
Coming soon
## Contract address
### Holesky Testnet (Deprecated)
| Name | Address |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| ProxyAdmin | [`0x26CF7A7DF7d1E00D83A5Ca24385f697a3ca4577d`](https://holesky.etherscan.io/address/0x26CF7A7DF7d1E00D83A5Ca24385f697a3ca4577d) |
| ServiceManager | [`0xEA3E82F9Ae371A6a372A6DCffB1a9bD17e0608eF`](https://holesky.etherscan.io/address/0xEA3E82F9Ae371A6a372A6DCffB1a9bD17e0608eF) |
| RegistryCoordinator | [`0x90c6d6f2A78d5Ce22AB8631Ddb142C03AC87De7a`](https://holesky.etherscan.io/address/0x90c6d6f2A78d5Ce22AB8631Ddb142C03AC87De7a) |
| BLSApkRegistry | [`0x6752F8BeeE5BF45c9d11FDBC4F8aFfF879925585`](https://holesky.etherscan.io/address/0x6752F8BeeE5BF45c9d11FDBC4F8aFfF879925585) |
| IndexRegistry | [`0x298a5d3C8F8Db30E8292C9e2BF92292de469C8FF`](https://holesky.etherscan.io/address/0x298a5d3C8F8Db30E8292C9e2BF92292de469C8FF) |
| OperatorStateRetriever | [`0xb7bb920538e038DFFEfcB55caBf713652ED2031F`](https://holesky.etherscan.io/address/0xb7bb920538e038DFFEfcB55caBf713652ED2031F) |
| PauserRegistry | [`0x3A8ea6e4202CdDe4a9e0cCE19c4Dc1739ba2cF0b`](https://holesky.etherscan.io/address/0x3A8ea6e4202CdDe4a9e0cCE19c4Dc1739ba2cF0b) |
| StakeRegistry | [`0x7BacD5dd5A7C3acf8bf1a3c88fB0D00B68EE626A`](https://holesky.etherscan.io/address/0x7BacD5dd5A7C3acf8bf1a3c88fB0D00B68EE626A) |
| ApConfig | [`0xb8abbb082ecaae8d1cd68378cf3b060f6f0e07eb`](https://holesky.etherscan.io/address/0xb8abbb082ecaae8d1cd68378cf3b060f6f0e07eb) |
### Sepolia Testnet
| Name | Address |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| ProxyAdmin | [`0x122c2D0Af2042ec0a6676d4dFd4d0c66dc40DDcf`](https://sepolia.etherscan.io/address/0x122c2D0Af2042ec0a6676d4dFd4d0c66dc40DDcf) |
| ServiceManager | [`0x80D492e1002F9C24b26179a024B8aA871fEbBC9D`](https://sepolia.etherscan.io/address/0x80D492e1002F9C24b26179a024B8aA871fEbBC9D) |
| RegistryCoordinator | [`0xcA95381802FD1398d5BF2D01243210cFb3a2b3BD`](https://sepolia.etherscan.io/address/0xcA95381802FD1398d5BF2D01243210cFb3a2b3BD) |
| BLSApkRegistry | [`0xC7fe896a9f0529b0e2B8193EBaf911BcD9d84A3F`](https://sepolia.etherscan.io/address/0xC7fe896a9f0529b0e2B8193EBaf911BcD9d84A3F) |
| IndexRegistry | [`0xdb8771619A7c2b9050CE66321A0652BC889399c2`](https://sepolia.etherscan.io/address/0xdb8771619A7c2b9050CE66321A0652BC889399c2) |
| OperatorStateRetriever | [`0x070E0ABE8407eb4727fC7C5284bdc1e5E5CBf605`](https://sepolia.etherscan.io/address/0x070E0ABE8407eb4727fC7C5284bdc1e5E5CBf605) |
| PauserRegistry | [`0x3b36CE97b7fdf2571354679130a80F9E1450679b`](https://sepolia.etherscan.io/address/0x3b36CE97b7fdf2571354679130a80F9E1450679b) |
| StakeRegistry | [`0x6dFAdB7E0ff7CAC8682f9C733890150210206E05`](https://sepolia.etherscan.io/address/0x6dFAdB7E0ff7CAC8682f9C733890150210206E05) |
| ApConfig | [`0xFf2E98967A8607F9Acd5CC9024cC5dE5DF0D60a3`](https://sepolia.etherscan.io/address/0xFf2E98967A8607F9Acd5CC9024cC5dE5DF0D60a3) |
### Ethereum Mainnet
| Name | Address |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| ProxyAdmin | [`0x5989934D31f7f397511f105B7E4175a06B7A517F`](https://etherscan.io/address/0x5989934D31f7f397511f105B7E4175a06B7A517F) |
| ServiceManager | [`0x18343Aa10e3D2F3A861e5649627324aEAD987Adf`](https://etherscan.io/address/0x18343Aa10e3D2F3A861e5649627324aEAD987Adf) |
| RegistryCoordinator | [`0x8DE3Ee0dE880161Aa0CD8Bf9F8F6a7AfEeB9A44B`](https://etherscan.io/address/0x8DE3Ee0dE880161Aa0CD8Bf9F8F6a7AfEeB9A44B) |
| BLSApkRegistry | [`0xB58687fF303C8e92C28a484342755d3228081d45`](https://etherscan.io/address/0xB58687fF303C8e92C28a484342755d3228081d45) |
| IndexRegistry | [`0xc6A464e39d4fA5013D61295501c7cCd050d76612`](https://etherscan.io/address/0xc6A464e39d4fA5013D61295501c7cCd050d76612) |
| OperatorStateRetriever | [`0xb3af70D5f72C04D1f490ff49e5aB189fA7122713`](https://etherscan.io/address/0xb3af70D5f72C04D1f490ff49e5aB189fA7122713) |
| PauserRegistry | [`0xeec585186c37c517030ba371deac5c17e728c135`](https://etherscan.io/address/0xeec585186c37c517030ba371deac5c17e728c135) |
| StakeRegistry | [`0x363b3604fE8c2323a98c00906115c8b87a512a12`](https://etherscan.io/address/0x363b3604fE8c2323a98c00906115c8b87a512a12) |
| TaskManager | [`0x940f62f75cbbbd723d37c9171dc681dfba653b49`](https://etherscan.io/address/0x940f62f75cbbbd723d37c9171dc681dfba653b49) |
| ApConfig | [`0x9c02dfc92eea988902a98919bf4f035e4aaefced`](https://etherscan.io/address/0x9c02dfc92eea988902a98919bf4f035e4aaefced) |