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:

  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:

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:

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:

Authentication Components#

JWT Token Structure#

The JWT tokens used for authentication contain the following standard claims:

ClaimDescriptionImplementation
sub (Subject)The Ethereum address of the authenticated userUser's wallet address
exp (Expiration Time)Token expiration timestampDerived from ExpiredAt parameter
iss (Issuer)Entity that issued the JWTSet 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:

  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:

Authentication Error Handling#

The system defines specific error constants for different authentication failure scenarios:

Error ConstantDescriptionHTTP Status Code
AuthenticationErrorGeneral authentication failure401 Unauthenticated
InvalidSignatureFormatMalformed or invalid signature format400 InvalidArgument
InvalidAuthenticationKeyInvalid JWT or signature401 Unauthenticated
InvalidAPIKeyProvided API key is not valid401 Unauthenticated
MalformedExpirationTimeInvalid expiration time format401 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#

  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:

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