Skip to main content

Sign In With Ethereum

Web3Modal SDK provides a simple solution for integrating with "Sign In With Ethereum" (SIWE), a new form of authentication that enables users to control their digital identity with their Ethereum account. SIWE is a standard also known as EIP-4361.

Installation​

Install the Web3Modal SIWE package, additionally we also recommend installing siwe which will abstract a lot of the required logic.

npm i @web3modal/siwe siwe

Configure your SIWE Client​

With help of the siwe package we will create the required configuration for Web3Modal.

note

The nonce and verification process will be implemented in your backend. Read more.

import { SiweMessage } from 'siwe'
import { createSIWEConfig } from '@web3modal/siwe'
import type { SIWECreateMessageArgs, SIWEVerifyMessageArgs } from '@web3modal/siwe'

/* Function that creates a SIWE message */
function createMessage({ nonce, address, chainId }: SIWECreateMessageArgs){
  const message = new SiweMessage({
    version: '1',
    domain: window.location.host,
    uri: window.location.origin,
    address,
    chainId,
    nonce,
    statement: 'Sign in With Ethereum.'
  })

  return message.prepareMessage()
}

/* Function that returns the user's session */
async function getSession(){
  const session = await getSession()
  if (!session) throw new Error('Failed to get session!')

  const { address, chainId } = session

  return { address, chainId }
}

/* Use your SIWE server to verify if the message and the signature are valid */
async function verifyMessage({ message, signature }: SIWEVerifyMessageArgs){
  try {
    const isValid = await validateMessage({ message, signature })

    return isValid
  } catch (error) {
    return false
  }
},

/* Create a SIWE configuration object */
const siweConfig = createSIWEConfig({
  createMessage,
  getNonce,
  getSession,
  verifyMessage,
  signOut
})

Initialize Web3Modal with your siweConfig​

createWeb3Modal({
  //..
  siweConfig
})

SIWE Config Parameters​

getNonce () => Promise<string>​

The getNonce method functions as a safeguard against spoofing, akin to a CSRF token. The siwe package provides a generateNonce() helper, or you can utilize an existing CSRF token from your backend if available.

createMessage (args: SIWECreateMessageArgs) => string​

The official siwe package offers a straightforward method for generating an EIP-4361-compatible message, which can subsequently be authenticated using the same package. The nonce parameter is derived from your getNonce endpoint, while the address and chainId variables are sourced from the presently connected wallet.

verifyMessage (args: SIWEVerifyMessageArgs) => Promise<boolean>​

The verifyMessage method should lean on the siwe package's new

SiweMessage(message).validate(signature)

to ensure the message is valid, has not been tampered with, and has been appropriately signed by the wallet address.

getSession () => Promise<SIWESession | null>​

The backend session should store the associated address and chainId and return it via the getSession method.

signOut () => Promise<boolean>​

The users session can be destroyed calling signOut.

onSignIn (session?: SIWESession) => void​

Callback when user signs in (Optional).

onSignOut () => void​

Callback when user signs out (Optional).

signOutOnDisconnect boolean​

  • defaults to true

Whether or not to sign out when the user disconnects their wallet (Optional).