Skip to main content

​
Overview

GenLayer Points uses Web3 authentication via MetaMask wallet. Your Ethereum wallet address serves as your unique identifier in the system.

​
What You Need

MetaMask Required: You must have MetaMask or a compatible Web3 wallet installed in your browser.
  • MetaMask browser extension
  • An Ethereum wallet address
  • Connection to any Ethereum-compatible network

​
Authentication Process

1

Click Connect Wallet

Locate the “Connect Wallet” button in the top-right corner of the navigation bar.
2

Select Your Wallet

Choose MetaMask or your preferred Web3 wallet from the wallet selector modal.
3

Authorize Connection

MetaMask will prompt you to:
  • Select which account(s) to connect
  • Approve the connection request
4

Sign the Message

You’ll be asked to sign a message to prove wallet ownership. This message:
  • Contains a unique nonce (expires in 5 minutes)
  • Includes the domain and timestamp
  • Does not cost gas - it’s a free signature
  • Never shares your private key
5

Session Created

Once signed, you’re authenticated! Your session will:
  • Remain active for extended periods
  • Auto-refresh every 5 minutes
  • Persist across browser tabs

​
Sign-In With Ethereum (SIWE)

The authentication uses the SIWE standard (EIP-4361), which provides:
  • Secure authentication without passwords
  • Wallet-based identity - your address is your login
  • Tamper-proof signatures verified on the backend
  • Session management via secure cookies

​
Sample SIWE Message

points.genlayer.com wants you to sign in with your Ethereum account:
0x1234567890abcdef1234567890abcdef12345678

Sign in with Ethereum to GenLayer Testnet Contributions

URI: https://points.genlayer.com
Version: 1
Chain ID: 4221
Nonce: abc123xyz789
Issued At: 2025-03-03T10:30:00.000Z

​
Authentication Flow Details

​
Backend Verification

  1. Frontend requests a nonce from /api/auth/nonce/
  2. User signs the SIWE message with their wallet
  3. Signed message is sent to /api/auth/login/
  4. Backend verifies:
    • Signature matches the Ethereum address
    • Nonce is valid and not expired
    • Nonce hasn’t been used before
  5. Session cookie is created on success

​
Session Management

Your session automatically refreshes every 5 minutes to keep you logged in.
  • Sessions use secure HTTP-only cookies
  • Session data stored server-side
  • Frontend never sees raw session tokens
  • Automatic logout on wallet disconnect

​
Wallet Account Switching

Switching accounts in MetaMask will automatically log you out and prompt re-authentication with the new account.
When you switch accounts:
  1. System detects the account change
  2. Current session is invalidated
  3. You’re prompted to sign in with the new account
  4. New session is created for the new address

​
Network Changes

Changing networks in MetaMask will reload the page to reset the application state.
This ensures:
  • Consistent application state
  • Proper network configuration
  • No stale data from previous network

​
Troubleshooting

​
”MetaMask is not installed”

Solution: Install the MetaMask browser extension

​
”Connection rejected”

Solution: Click “Connect Wallet” again and approve the connection request in MetaMask

​
”Signature verification failed”

Possible causes:
  • Wrong account selected in MetaMask
  • Signature was cancelled
  • Network connectivity issues
Solution: Try connecting again

​
”Authentication expired, please try again”

Cause: The nonce expired (5 minute limit) Solution: Click “Connect Wallet” to get a fresh nonce

​
Session Not Persisting

Possible causes:
  • Browser blocking third-party cookies
  • Incognito/private browsing mode
  • Browser extensions blocking cookies
Solution:
  • Allow cookies for the Points domain
  • Use regular browsing mode
  • Check browser extension settings

​
Security Features

​
What’s Protected

  • Nonce Expiration: Each nonce expires after 5 minutes
  • One-time Use: Nonces can only be used once
  • Signature Verification: Backend verifies all signatures cryptographically
  • Session Cookies: HTTP-only, Secure flag enabled in production
  • Address Validation: All addresses normalized to lowercase

​
What’s NOT Shared

Your private keys never leave your wallet. The signature process is handled entirely by MetaMask.
  • Private keys
  • Seed phrases
  • Transaction signing capability
  • Wallet permissions beyond address visibility

​
Multiple Devices

You can be logged in on multiple devices simultaneously. Each device maintains its own session.
  • Each browser/device has independent sessions
  • Logging out on one device doesn’t affect others
  • Session refresh is per-device

​
Manual Logout

1

Open Account Menu

Click your address/name in the top-right corner
2

Click Disconnect

Select “Disconnect” from the dropdown menu
3

Session Cleared

Your session is immediately invalidated on both frontend and backend

​
Next Steps

Create Your Profile

Set up your display name and node version after connecting

Submit Contributions

Start tracking your contributions to GenLayer

Build docs developers (and LLMs) love

Get started for freeTalk to us