Skip to main content

Sign In With Ethereum

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

One-Click Auth

One-Click Auth represents a key advancement within WalletConnect v2, streamlining the user authentication process in AppKit by enabling them to seamlessly connect with a wallet and sign a SIWE message with just one click.

Connecting a wallet, proving control of an address with an off-chain signature, authorizing specific actions. These are the kinds of authorizations that can be encoded as "ReCaps". ReCaps are permissions for a specific website or dapp that can be compactly encoded as a long string in the message you sign and translated by any wallet into a straight-forward one-sentence summary. WalletConnect uses permissions expressed as ReCaps to enable a One-Click Authentication.

Pre-requisites

In order for SIWE to work, you need to have a backend to communicate with. This backend will be used to generate a nonce, verify messages and handle sessions. More info here

Configure your SIWE Client

// siweConfig.ts

import {
createSIWEConfig,
formatMessage,
type SIWEVerifyMessageArgs,
type SIWECreateMessageArgs
} from '@web3modal/siwe-react-native';

export const siweConfig = createSIWEConfig({
getNonce: async (): Promise<string> => {
// The getNonce method functions as a safeguard
// against spoofing, akin to a CSRF token.

return await api.getNonce();
},
verifyMessage: async ({ message, signature, cacao }: SIWEVerifyMessageArgs): Promise<boolean> => {
try {
// This function ensures the message is valid,
// has not been tampered with, and has been appropriately
// signed by the wallet address.

const isValid = await api.verifyMessage({ message, signature, cacao })

return isValid
} catch (error) {
return false
}
},
getSession: async (): Promise<SIWESession | null> => {
// The backend session should store the associated address and chainId
// and return it via the `getSession` method.

const session = await api.getSession()
if (!session) throw new Error('Failed to get session!')

const { address, chainId } = session

return { address, chainId }
},
signOut: (): Promise<boolean> => {
try {
// The users session must be destroyed when calling `signOut`.

await api.signOut();
return true;
} catch {
return false
}
},
createMessage: ({ address, ...args }: SIWECreateMessageArgs): string => {
// Method for generating an EIP-4361-compatible message.

return formatMessage(args, address)
},
getMessageParams: () => {
// Parameters to create the SIWE message internally.
// More info in https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-222.method

return {
domain: 'your domain',
uri: 'your uri',
chains: [1,137], // array of chain ids
statement: 'Please sign with your account',
iat: new Date().toISOString()
}
},
})

Initialize AppKit with your siweConfig

Add the siwe configuration in createWeb3Modal initialization

import { siweConfig } from './siweConfig.ts'

createWeb3Modal({
//..
siweConfig
})

SIWE Config reference

interface SIWEConfig {
/** Required **/
getNonce: () => Promise<string>
createMessage: (args: SIWECreateMessageArgs) => string
verifyMessage: (args: SIWEVerifyMessageArgs) => Promise<boolean>
getSession: () => Promise<SIWESession | null>
signOut: () => Promise<boolean>

/** Required for One-Click Auth **/
getMessageParams `() => Promise<{ domain: string, uri: string, chains: number[], statement: string }>


/** Optional **/

// Callback when user signs in
onSignIn?: (session?: SIWESession) => void

// Callback when user signs out
onSignOut?: () => void

// Defaults to true
enabled?: boolean

// In milliseconds, defaults to 5 minutes
nonceRefetchIntervalMs?: number

// In milliseconds, defaults to 5 minutes
sessionRefetchIntervalMs?: number

// Defaults to true
signOutOnDisconnect?: boolean

// Defaults to true
signOutOnAccountChange?: boolean

// Defaults to true
signOutOnNetworkChange?: boolean
}

Exported functions

verifySignature

Verify a SIWE signature. Internally it calls your backend verification method.

import { verifySignature } from '@web3modal/siwe-react-native'

const isValid = await verifySignature({ address, message, signature, chainId, projectId })

getChainIdFromMessage

Get the chain ID from the SIWE message.

import { getChainIdFromMessage } from '@web3modal/siwe-react-native'

const chainId = getChainIdFromMessage(message)

getAddressFromMessage

Get the address from the SIWE message.

import { getAddressFromMessage } from '@web3modal/siwe-react-native'

const address = getAddressFromMessage(message)