Skip to main content

SIWX Default Usage

Quick Start​

Here is a quick guide to get started with the SIWX feature using the default implementation.

Installation​

npm install @reown/appkit-siwx

Usage​

import { createAppKit } from '@reown/appkit'
import { DefaultSIWX } from '@reown/appkit-siwx'

const appkit = createAppKit({
  // ... your configuration
  siwx: new DefaultSIWX()
})

You should now have the SIWX feature up and running in your Dapp.

The DefaultSIWX configuration will use the predefined components to handle the message generation, verification and storage of the sessions. You can customize the default implementation by providing your own components as in the following sections.

Customizing the Default Implementation​

The default implementation of SIWX is divided in three main components: SIWXMessenger, SIWXVerifier and SIWXStorage. The @reown/appkit-siwx package have defined options to fulfill the parts when initializing the DefaultSIWX configuration and you are also able to setup your own parts as required.

Predefined Components​

The @reown/appkit-siwx package provides some predefined components that you can use to quickly setup the DefaultSIWX configuration.

Check the latest components over the SIWX repository

Customizing components​

You may provide the parts to the DefaultSIWX configuration using the predefined components exposed by @reown/appkit-siwx package and customize the component params as needed.

import {
  DefaultSIWX,
  InformalMessenger,
  EIP155Verifier,
  SolanaVerifier,
  LocalStorage
} from '@reown/appkit-siwx'

const siwx = new DefaultSIWX({
  messenger: new InformalMessenger({
    domain: 'reown.com',
    uri: 'https://reown.com',
    getNonce: async () => Math.round(Math.random() * 10000).toString()
  }),
  verifiers: [new EIP155Verifier(), new SolanaVerifier()],
  storage: new LocalStorage({ key: '@appkit/siwx' })
})

Custom Components​

You may create your own components to handle the message generation, verification and storage of the sessions. The following sections will guide you through the process of creating your own components.

SIWXMessenger​

The SIWXMessenger is an abstract class which holds methods for generating the message to be signed.

Creating a Custom Messenger:​

You may extend the SIWXMessenger class adding the public attributes:

  • version: a string that represents the version of the messenger;
  • stringify: a method that receives the message data and returns a string to be signed.
import { SIWXMessenger } from '@reown/appkit-siwx'
import type { SIWXMessage } from '@reown/appkit-core'

export class MyMessenger extends SIWXMessenger {
  protected readonly version = '1'

  protected override stringify(params: SIWXMessage.Data): string {
    // Implement your message format here
    return `My message for ${params.accountAddress} on ${params.chainId}`
  }
}

SIWXVerifier​

The SIWXVerifier is an abstract class that defines the verification logic for the signed message.

Creating a Custom Verifier:​

You may extend the SIWXVerifier class adding the public attributes:

  • chainNamespace: a string that represents the chain namespace for the verifier;
  • verify: a method that receives the session data and returns a boolean indicating if the session is valid.
import { SIWXVerifier } from '@reown/appkit-siwx'
import type { SIWXSession } from '@reown/appkit-core'

export class MyVerifier extends SIWXVerifier {
  public readonly chainNamespace = 'eip155' // set the chain namespace for your verifier

  public async verify(session: SIWXSession): Promise<boolean> {
    // Implement your verification logic here
    return true
  }
}

SIWXStorage​

SIWXStorage is a interface that defines how the session data will be stored.

Creating a Custom Storage:​

You may implement the SIWXStorage interface with the following methods:

  • add: This method will be called to store a new single session that is verified;
  • set: This method must replace all the sessions in the storage with the new ones;
  • get: This method must return all the sessions stored for a specific chain and address. Is expected that the sessions are already verified;
  • delete: This method must delete all the sessions stored for a specific chain and address.
import type { SIWXSession } from '@reown/appkit-core'
import type { SIWXStorage } from '@reown/appkit-siwx'

export class MyStorage implements SIWXStorage {
  add(session: SIWXSession): Promise<void> {
    // Implement your logic to add a session
  }

  set(sessions: SIWXSession[]): Promise<void> {
    // Implement your logic to set sessions
  }

  get(chainId: CaipNetworkId, address: string): Promise<SIWXSession[]> {
    // Implement your logic to get sessions
    return []
  }

  delete(chainId: string, address: string): Promise<void> {
    // Implement your logic to delete a session
  }
}

Using custom components​

You may provide your custom components to the DefaultSIWX configuration.

If you omit any of the components, the default implementation will be used. Check here the default components.

import { DefaultSIWX, type SIWXStorage } from '@reown/appkit-siwx'

class MyDatabaseStorage implements SIWXStorage {
  // ...
}

const siwx = new DefaultSIWX({
  storage: new MyDatabaseStorage()
})