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:

1. JWT-based authentication - Used for API access after initial authentication
2. 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:

• aggregator/auth.go3-50
• aggregator/auth.go103-167
• aggregator/auth.go170-187

Authentication Flow#

User Authentication#

The user authentication flow follows these steps:

1. 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

2. 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)

3. Token Issuance: Upon successful verification, a JWT token is issued to the user

4. Subsequent Requests: For all API requests, the user includes the JWT token in the authkey metadata field

Sources:

• aggregator/auth.go36-100
• aggregator/auth.go103-167

Operator Authentication#

The operator authentication flow is currently simplified:

1. Operators include an authorization header in their requests
2. The verifyOperator function validates this authorization against the operator's address
3. Currently, operator authentication enforcement is disabled via the enforceAuth flag set to false

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:

• aggregator/auth.go170-187

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:

• aggregator/auth.go84-92
• aggregator/auth.go122-139

Authentication Verification#

The system provides two main verification functions:

1. 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

2. 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:

• aggregator/auth.go103-167
• aggregator/auth.go170-187

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:

• core/auth/errors.go3-9
• aggregator/auth.go48-50
• aggregator/auth.go60-76

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:

• aggregator/aggregator.go264
• aggregator/auth.go36-100

Security Considerations#

1. JWT Secret: The system relies on a secure JWT secret (config.JwtSecret) for signing and verifying tokens
2. Signature Recovery: The system uses Ethereum's ECDSA signature recovery to validate signatures
3. Caching: The system caches smart wallet addresses to reduce Ethereum RPC calls, improving performance
4. 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:

• aggregator/auth.go21-31
• aggregator/auth.go151-162

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