SSX
  • SSX
  • ⚡SSX Quickstart
    • SSX Server Quickstart
  • 🛠️Configuring SSX
    • Configuring SSX Server
    • Configuring SSX with React
    • Configuring SSX for Serverless
  • 📊Accessing the SSX Dashboard
  • 📈Scaling SSX Server
  • Tutorials
    • Moving From SIWE to SSX
    • Using SSX with Auth.js
    • Using SSX with NextAuth
    • Build a Token-Gated Dapp
    • From Email Login to SIWE
  • appendix
    • DAO Login Workflow
    • SSX: How It Works
  • Reference
    • SSX API Reference
      • configoverrides
      • extrafields
      • isssxalchemyprovider
      • isssxankrprovider
      • isssxcloudflareprovider
      • isssxcustomprovider
      • isssxetherscanprovider
      • isssxinfuraprovider
      • isssxpocketprovider
      • issxconnected
        • afterconnecthookspromise
        • aftersignin
        • api
        • applyextensions
        • builder
        • config
        • extensions
        • isextensionenabled
        • provider
        • signin
        • signout
        • ssxserverlogin
        • ssxservernonce
      • siweconfig
      • ssx
        • constructor
        • address
        • chainid
        • connection
        • resolveens
        • rpcproviders
        • session
        • signin
        • signout
      • ssxalchemyprovider
      • ssxalchemyprovidernetworks
      • ssxankrprovider
      • ssxankrprovidernetworks
      • ssxclientconfig
        • enabledaologin
        • providers
        • resolveens
        • siweconfig
      • ssxclientproviders
        • rpc
        • server
        • web3
      • ssxclientsession
      • ssxcloudflareprovider
      • ssxconfig
        • enabledaologin
        • providers
        • resolveens
        • siweconfig
      • ssxconnected
        • constructor
        • afterconnecthookspromise
        • aftersignin
        • api
        • applyextensions
        • builder
        • config
        • extensions
        • isextensionenabled
        • provider
        • signin
        • signout
        • ssxserverlogin
        • ssxservernonce
      • ssxcustomprovider
      • ssxensconfig
        • resolve
        • resolveonserver
      • ssxensdata
        • avatarurl
        • domain
      • ssxensresolveoptions
        • avatar
        • domain
      • ssxetherscanprovider
      • ssxetherscanprovidernetworks
      • ssxextension
        • afterconnect
        • aftersignin
        • defaultactions
        • extrafields
        • namespace
        • targetedactions
      • ssxgenericprovider
      • ssxinfuraprovider
      • ssxinfuraprovidernetworks
      • ssxinfuraproviderprojectsettings
      • ssxinit
        • constructor
        • connect
        • extend
      • ssxpocketprovider
      • ssxpocketprovidernetworks
      • ssxproviders
        • rpc
        • server
        • web3
      • ssxproviderserver
      • ssxproviderweb3
        • driver
      • ssxrpcprovider
      • ssxrpcproviders
      • ssxserverhost
      • ssxserverroutes
        • login
        • logout
        • nonce
      • ssxsession
    • SSX Core API Reference
      • configoverrides
      • extrafields
      • getprovider
      • isssxalchemyprovider
      • isssxankrprovider
      • isssxcloudflareprovider
      • isssxcustomprovider
      • isssxetherscanprovider
      • isssxinfuraprovider
      • isssxpocketprovider
      • issxconnected
        • afterconnecthookspromise
        • aftersignin
        • api
        • applyextensions
        • builder
        • config
        • extensions
        • isextensionenabled
        • provider
        • signin
        • signout
        • ssxserverlogin
        • ssxservernonce
      • siweconfig
      • ssxalchemyprovider
      • ssxalchemyprovidernetworks
      • ssxankrprovider
      • ssxankrprovidernetworks
      • ssxclientconfig
        • enabledaologin
        • providers
        • resolveens
        • siweconfig
      • ssxclientproviders
        • rpc
        • server
        • web3
      • ssxclientsession
      • ssxcloudflareprovider
      • ssxcookieoptions
        • httponly
        • samesite
        • secure
        • signed
      • ssxcustomprovider
      • ssxensconfig
        • resolve
        • resolveonserver
      • ssxensdata
        • avatarurl
        • domain
      • ssxensresolveoptions
        • avatar
        • domain
      • ssxetherscanprovider
      • ssxetherscanprovidernetworks
      • ssxeventlogtypes
      • ssxexpresssessionstoreprovider
      • ssxextension
        • afterconnect
        • aftersignin
        • defaultactions
        • extrafields
        • namespace
        • targetedactions
      • ssxgenericprovider
      • ssxinfuraprovider
      • ssxinfuraprovidernetworks
      • ssxinfuraproviderprojectsettings
      • ssxlog
      • ssxlogfields
        • content
        • timestamp
        • type
        • userid
      • ssxmetricsprovider
      • ssxpocketprovider
      • ssxpocketprovidernetworks
      • ssxpost
      • ssxproviderserver
      • ssxproviderweb3
        • driver
      • ssxredissessionstoreprovider
      • ssxresolveens
      • ssxrpcprovider
      • ssxrpcproviders
      • ssxserverconfig
        • providers
        • signingkey
        • usesecurecookies
      • ssxserverhost
      • ssxserverproviders
        • metrics
        • rpc
        • sessionconfig
      • ssxserverroutes
        • login
        • logout
        • nonce
      • ssxsessionstoreconfig
        • sessionoptions
        • store
    • SSX Server API Reference
      • isssxalchemyprovider
      • isssxankrprovider
      • isssxcloudflareprovider
      • isssxcustomprovider
      • isssxetherscanprovider
      • isssxinfuraprovider
      • isssxpocketprovider
      • ssxalchemyprovider
      • ssxalchemyprovidernetworks
      • ssxankrprovider
      • ssxankrprovidernetworks
      • ssxauthenticated
      • ssxcloudflareprovider
      • ssxcookieoptions
        • httponly
        • samesite
        • secure
        • signed
      • ssxcustomprovider
      • ssxensdata
        • avatarurl
        • domain
      • ssxensresolveoptions
        • avatar
        • domain
      • ssxetherscanprovider
      • ssxetherscanprovidernetworks
      • ssxeventlogtypes
      • ssxexpressmiddleware
      • ssxexpresssessionstoreprovider
      • ssxgenericprovider
      • ssxhttpmiddleware
      • ssxinfuraprovider
      • ssxinfuraprovidernetworks
      • ssxinfuraproviderprojectsettings
      • ssxlogfields
        • content
        • timestamp
        • type
        • userid
      • ssxmetricsprovider
      • ssxpocketprovider
      • ssxpocketprovidernetworks
      • ssxredissessionstoreprovider
      • ssxrpcprovider
      • ssxrpcproviders
      • ssxserver
        • constructor
        • generatenonce
        • getexpresssessionconfig
        • log
        • login
        • logout
        • provider
        • resolveens
        • session
      • ssxserverconfig
        • providers
        • signingkey
        • usesecurecookies
      • ssxserverproviders
        • metrics
        • rpc
        • sessionconfig
      • ssxserverroutes
        • login
        • logout
        • nonce
      • ssxsessionstoreconfig
        • sessionoptions
        • store
    • SSX Serverless API Reference
      • isssxalchemyprovider
      • isssxankrprovider
      • isssxcloudflareprovider
      • isssxcustomprovider
      • isssxetherscanprovider
      • isssxinfuraprovider
      • isssxpocketprovider
      • ssxalchemyprovider
      • ssxalchemyprovidernetworks
      • ssxankrprovider
      • ssxankrprovidernetworks
      • ssxcloudflareprovider
      • ssxcustomprovider
      • ssxensdata
        • ensavatarurl
        • ensname
      • ssxensresolveoptions
        • avatar
        • domain
      • ssxetherscanprovider
      • ssxetherscanprovidernetworks
      • ssxeventlogtypes
      • ssxgenericprovider
      • ssxinfuraprovider
      • ssxinfuraprovidernetworks
      • ssxinfuraproviderprojectsettings
      • ssxlogfields
        • content
        • timestamp
        • type
        • userid
      • ssxpocketprovider
      • ssxpocketprovidernetworks
      • ssxrpcprovider
      • ssxrpcproviders
      • ssxserver
        • constructor
        • generatenonce
        • getnonce
        • log
        • me
        • provider
        • resolveens
        • session
        • signin
        • signout
      • ssxserverconfig
        • daologin
        • providers
      • ssxserverproviders
        • metrics
        • rpc
      • ssxserverroutes
        • login
        • logout
        • nonce
      • ssxsessioncrudconfig
        • create
        • delete
        • retrieve
        • update
      • ssxsessiondata
        • daologin
        • ens
        • signature
        • siwemessage
Powered by GitBook
On this page
  • Overview
  • Enabling DAO Login
  • Customizing Fields in the SIWE Message
  • Config Options
  • SSX-Client Configuration Options
  • SSX-Server Configuration Options

Was this helpful?

Edit on GitHub

Configuring SSX

SSX Configuration Guide

PreviousSSX Server QuickstartNextConfiguring SSX Server

Last updated 2 years ago

Was this helpful?

Overview

SSX works on both server and client without configuration. However, you can access a robust feature set by enabling and configuring some available options.

Below are a few examples and explanations of the configuration options:

Enabling DAO Login

SSX enables an easy way for users to sign in on behalf of a Gnosis Safe multisig on your platform that they have been delegated access to. It that users can take to either log in as themselves or on behalf of the multisig. Here is an example of how you enable that field:

const buttonHandlerWeb3ModalGnosis = async () => {
    const ssx = new SSX({
      enableDaoLogin: true,
    });
    await ssx.signIn();
};

Customizing Fields in the SIWE Message

SSX enables developers an easy way to configure the fields of their Sign-in with Ethereum (SIWE) message using the option. This option allows you to overwrite the fields found in the SIWE message. This option can allow you to create SIWE messages that may not be valid in specific environments, so use this option with care.

const buttonHandlerWeb3ModalGnosis = async () => {
    const ssx = new SSX({
      siweConfig: {
        statement: "Sign in to use our service today!"
        requestId: "unique-id-for-specific-purpose",
      },
    });
    await ssx.signIn();
};

Config Options

SSX-Client Configuration Options

const ssx = new SSX({
    enableDaoLogin: true,
});

This is an optional field to enable ENS resolution when signing in. After the sign-in, the ENS data will be available with all other session data. resolveEns can be a boolean (default to false) or an object.

/* resolve ENS domain and avatar on client */
const ssx = new SSX({
  resolveEns: true
});

// OR

/* resolve ENS domain and/or avatar on client or server */
const ssx = new SSX({
  resolveEns: {
    resolveOnServer: true, // false as default
    resolve: {
      domain: true,
      avatar: false
    }
  }
});

/* You can resolve ENS at any time even if you
 * don't want to enable ENS resolution globally */
 const ensData = await ssx.resolveEns("0xADDRESS", {
    domain: false,
    avatar: true,
  });

resolveLens

This is an optional field to enable Lens profile resolution when signing in. After a user signs-in, the Lens data will be available with all other session data. resolveLens can be a boolean (default to false) or 'onServer'.

/* resolve Lens profiles on client */
const ssx = new SSX({
  resolveLens: true
});

// OR

/* resolve Lens profiles on server */
const ssx = new SSX({
  resolveLens: 'onServer'
});

/* You can resolve Lens profiles at any time even if you
 * don't want to enable Lens resolution globally */
 const lensProfiles = await ssx.resolveLens("0xADDRESS");

siweConfig

const ssx = new SSX({
    siweConfig: { requestId: "some_id" },
});

providers

SSX then manages this wallet connection, creates and displays the Sign-in with Ethereum message, and handles signed messages.

const ssx = new SSX({
    providers: { web3: { driver: await web3modal.connect() } },
});

providers.server

The server field is an optional reference to a corresponding server running ssx-server. Providing the host field enables automatic communication with the server to establish sessions upon successful SIWE signing.

ssx and ssx-server have default paths configured for the endpoints (nonce: '/ssx-nonce', login: '/ssx-login' and logout: '/ssx-logout'), but you can override it by providing the property routes. It isn't necessary to override all of them, you can only override one of them.

For more information on configuring ssx-server, check out the SSX Quickstart:

const ssx = new SSX({
    providers: { 
        server: { 
            host: 'http://localhost:3001' 
            routes: {
                nonce: '/ssx-custom-nonce',
                login: '/ssx-custom-login',
                logout: '/ssx-custom-logout',
            }
        } 
    }
});

Additionally, you can override the configuration of the API Request for any of the routes. This allows you make any custom request to an endpoint to get the nonce, login, or logout.

const ssx = new SSX({
    providers: { 
        server: { 
            host: 'http://localhost:3001' 
            routes: {
                nonce:  {
                    url: '/ssx-custom-nonce',
                    method: 'post'
                }
            }
        } 
    }
});
import { SSX, SSXRPCProviders, SSXInfuraProviderNetworks } from '@spruceid/ssx-server';

const ssx = new SSX({
    providers: {
      rpc: {
        service: SSXRPCProviders.SSXInfuraProvider,
        network: SSXInfuraProviderNetworks.MAINNET,
        apiKey: process.env.INFURA_API_KEY ?? "",
      },
    },
});

// OR 

const ssx = new SSX({
    providers: {
      rpc: {
        service: "infura",
        network: "homestead",
        apiKey: process.env.INFURA_API_KEY ?? "",
      },
    },
});

// RPC usage example
const rpcExample = async () => {
  await ssx.signIn();
  const address = ssx.address()
  const userbalance = await ssx.provider.getBalance(address);
  const currentBlock = await ssx.provider.getBlockNumber();
}

SSX-Server Configuration Options

SSX Server supports multiple server configurations. To explore setting a specific server environment with SSX, check out Configuring SSX Server

This is an optional, string field. It is the key that is used to sign cookies to prevent cookie tampering on the client. The server will issue unsigned cookies if this field is not provided. It is recommended for production environments.

const ssx = new SSXServer({
  signingKey: process.env.SSX_SIGNING_KEY,
});

This is an optional, boolean field. It adds extra protection to your cookies by changing their attributes to be more secure. This defaults to true in production environments.

Setting this tofalse is insecure and not recommended for production environments!

const ssx = new SSXServer({
  useSecureCookies: true,
});

providers

If you are using enableDaoLogin at your front-end application you will need to also setup a provider for the SSXServer. By doing so you will also have access to that provider in any of your routes by getting req.ssx.provider, which will also make it easier if you have to make any RPC calls to a node.

import { SSXServer } from "@spruceid/ssx-server";

const ssx = new SSXServer({
  providers: {
    metrics: { service: "ssx", apiKey: process.env.SSX_API_KEY },
  },
});
import { SSXServer } from "@spruceid/ssx-server";

const ssx = new SSXServer({
  providers: {
    rpc: { service: "infura", apiKey: process.env.INFURA_API_KEY },
  },
});

// later...
const currentBlock = await ssx.provider.getBlockNumber();
import { SSXServer } from "@spruceid/ssx-server";

const ssx = new SSXServer({
  providers: {
    sessionConfig: {
      sessionOptions: {
        // ex: Recognize cookies signed by other keys
        secret: [process.env.SSX_SIGNING_KEY, process.env.OTHER_COOKIE_KEY]
      },
      store: (session) => {
        // ex: dynamodb for session store [connect-dynamodb](https://www.npmjs.com/package/connect-dynamodb)
        const DynamoDBStore = require('connect-dynamodb')(session);
        const dynamoDBoptions = {}; // configure to connect
        return new DynamoDBStore(dynamoDBoptions)
      },
    },
  },
});

The configuration options for SSX are defined and include: enableDaoLogin, providers, and siweConfig.

SSX has support for lookup on the Smart Contract, used by Gnosis Safe, built in. This enables a user to sign in on behalf of a Gnosis Safe, or any other address that has delegated access to that user. Enabling enableDaoLogin prompts the user to select if they want to sign in with their Externally Owned Account (their wallet) or on behalf of an address they are a delegee of. A detailed explanation of the DAO Login Workflow is available .

This feature is available for Polygon Mainnet and Mumbai Testnet. Visit the for more information.

siweConfig is a field that lets you set default values for SIWE messages. These values will overwrite fields that are automatically generated by SSX and could lead to invalid messages if misconfigured. Valid options can be found .

SSX acts as a super-provider for your dapp to make multiple resources available to your dapp with minimal configuration: (to connect to your wallet), (to connect to blockchains) and (to connect to a server using ssx).

Dapps interact with the Ethereum network by accessing the , which is usually injected into the browser by an Ethereum wallet. SSX works with any wallet by connecting to the wallet's implementation of , which is passed to the config as seen below.

For issues talking to custom endpoints, the options available in the are valid configuration options and can be used to modify the requests that ssx sends.

SSX Server supports all JSON RPC providers that are currently supported by , requiring only the credentials from the desired provider to instantiate it. The SSX library provides valid enumerated options for various RPC providers, but developers can also just use the valid strings, as seen below. A list of supported RPC providers can be found .

The configuration options for ssx-server are defined and include: signingKey, useSecureCookies, and providers.

Metrics is an optional, object field. It contains the service, ssx, and the apiKey that is used when sending metrics to the . This ties your server instance and its metrics and logs to your platform account.

SSX Server supports all JSON RPC providers that are currently supported by , requiring only the credentials from the desired provider to instantiate it.

This optional field is for managing the session store. It includes a field and a store connector function. Under the hood, SSX connects to session stores that implement and uses the same configuration options to do so. These fields are automatically set by your SSX configuration

The store connector is a function that is run on initialization that initializes and connects to the session store being used. It should return a configured instance of a store. An example implementation using .

If providers.sessionConfig is not provided, SSX Server defaults to using an in-memory store that resets with the server. It is recommended to use a . Check out to learn more.

🛠️
here
enableDaoLogin
DelegationRegistry
here
resolveEns
Lens docs
here
providers.web3
Ethereum JavaScript provider API
Web3Provider
Axios Request Config
providers.rpc
ethers
here
here
signingKey
useSecureCookies
providers.metrics
SSX Dashboard
providers.rpc
ethers
providers.sessionConfig
sessionOptions
express-session's EventEmitter API
provides an easy flow
siweConfig
a web3 provider
an RPC provider
a server provider
compatible persistent store
SSX and Redis of this is available here
Scaling SSX Server