Authentication
This document describes the authentication and authorization mechanisms implemented in the EigenLayer-AVS system.
This document describes the authentication and authorization mechanisms implemented in the EigenLayer-AVS system. The authentication system secures communication between clients, operators, and the aggregator service using JWT (JSON Web Tokens) and Ethereum signature verification.
Overview#
The EigenLayer-AVS implements two primary authentication methods:
- JWT-based authentication - Used for API access after initial authentication
- Ethereum signature verification - Used for initial authentication and proof of ownership
These mechanisms ensure that only authorized entities can access protected endpoints and perform operations within the system.
Sources:
Authentication Flow#
User Authentication#
The user authentication flow follows these steps:
-
Initial Authentication: User sends a request to
GetKey
with either:- An existing JWT token (for renewal)
- A cryptographic signature proving ownership of their Ethereum address
-
Signature Verification: If using signature-based authentication:
- The system generates a message template containing URI, Chain ID, timestamps, and wallet address
- The signature is validated to ensure it was created by the private key controlling the claimed address
- The EIP-191 personal sign format is supported (signature format with v=27/28)
-
Token Issuance: Upon successful verification, a JWT token is issued to the user
-
Subsequent Requests: For all API requests, the user includes the JWT token in the
authkey
metadata field
Sources:
Operator Authentication#
The operator authentication flow is currently simplified:
- Operators include an
authorization
header in their requests - The
verifyOperator
function validates this authorization against the operator's address - Currently, operator authentication enforcement is disabled via the
enforceAuth
flag set tofalse
This design allows for backward compatibility with operators running older versions (pre-1.3) where authentication isn't enforced. The system plans to enable enforcement once all operators have updated to version 1.3.0 or higher.
Sources:
Authentication Components#
JWT Token Structure#
The JWT tokens used for authentication contain the following standard claims:
Claim | Description | Implementation |
---|---|---|
sub (Subject) | The Ethereum address of the authenticated user | User's wallet address |
exp (Expiration Time) | Token expiration timestamp | Derived from ExpiredAt parameter |
iss (Issuer) | Entity that issued the JWT | Set to constant auth.Issuer |
Additional security is provided by validating:
- The signing algorithm is HMAC with SHA-256 (
HS256
) - The token is signed with the server's secret key
Sources:
Authentication Verification#
The system provides two main verification functions:
-
verifyAuth
- Validates user JWT tokens:- Extracts the JWT from the request metadata
- Verifies the token signature and algorithm
- Extracts the user's Ethereum address from the claims
- Loads the user's default smart wallet address (with caching)
- Returns a populated
User
model
-
verifyOperator
- Validates operator authorization:- Extracts the authorization header from request metadata
- Currently bypassed by the
enforceAuth = false
flag - Will eventually verify the operator's credentials against their address
Sources:
Authentication Error Handling#
The system defines specific error constants for different authentication failure scenarios:
Error Constant | Description | HTTP Status Code |
---|---|---|
AuthenticationError | General authentication failure | 401 Unauthenticated |
InvalidSignatureFormat | Malformed or invalid signature format | 400 InvalidArgument |
InvalidAuthenticationKey | Invalid JWT or signature | 401 Unauthenticated |
InvalidAPIKey | Provided API key is not valid | 401 Unauthenticated |
MalformedExpirationTime | Invalid expiration time format | 401 Unauthenticated |
These error constants provide consistent and informative responses when authentication fails.
Sources:
Integration with the Aggregator Service#
The authentication system is integrated with the Aggregator service through the RPC server. When the Aggregator starts, it initializes various components including the RPC server, which handles authentication for incoming requests.
Sources:
Security Considerations#
- JWT Secret: The system relies on a secure JWT secret (
config.JwtSecret
) for signing and verifying tokens - Signature Recovery: The system uses Ethereum's ECDSA signature recovery to validate signatures
- Caching: The system caches smart wallet addresses to reduce Ethereum RPC calls, improving performance
- Temporary Authentication Bypass: There's a temporary bypass for operator authentication (
enforceAuth = false
) to support backward compatibility
Future improvements may include:
- Full enforcement of operator authentication
- Enhanced rate limiting
- Additional authentication methods
Sources:
Related Pages#
For more information about other components that interact with the authentication system:
- For details on the Aggregator service, see Aggregator
- For information about the RPC Server implementation, see RPC Server
- For more about Operator functionality, see Operator
Feature this wiki to auto refresh weekly
Try DeepWiki on your private codebase with Devin