🛠️Configuring SSX

SSX Configuration Guide

enableDaoLogin

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 provides an easy flow that users can take to either log in as themselves or on behalf of the multisig. Defaults to false.

enableDaoLogin: boolean;

Here is an example of how you enable it:

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

modules

SSX has modules to aggregate more features into the library. By default, all modules are disabled (false) except for the UserAuthorization module, which is mandatory.

modules: {
    settings?: boolean | SSXStorageModuleConfig;
};

SSXStorageModuleConfig: {
    prefix?: string;
    hosts?: Array<string>;
    autoCreateNewOrbit?: boolean;
};

Here is an example of how you enable it:

Storage Module

const ssx = new SSX({
  modules: {
    storage: {
      prefix: 'app-prefix',
      hosts: ['https://kepler.spruceid.xyz'],
      autoCreateNewOrbit: true,
    }
  }
});

For more information about the modules and the methods they enable, you can take a look at the modules' pages:

• UserAuthorization Module

• Storage Module

providers

SSX acts as a super-provider for your app to make multiple resources available to your app with minimal configuration: a web3 provider (to connect to your wallet), an RPC provider (to connect to blockchains), and a server provider (to connect to a server powered by SSX).

providers: {
    web3?: SSXProviderWeb3;
    server?: SSXProviderServer;
    rpc?: SSXRPCProvider;
}

providers.web3

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

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

providers: {
    web3?: {
        driver: BrowserProvider;
    }
};

Here is an example of how you enable it:

const ssx = new SSX({
    providers: { 
        web3: { 
            driver: window.ethereum 
        }
    }
});

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.

provider: {
    server?: {
        host: string;
        routes?: {
            nonce?: SSXServerRouteEndpointType;
            login?: SSXServerRouteEndpointType;
            logout?: SSXServerRouteEndpointType;
        };
    }
};

SSXServerRouteEndpointType: Partial<SSXRouteConfig> | AxiosRequestConfig | string;

SSXRouteConfig: {
    url?: string;
    method?: 'get' | 'post' | 'put' | 'delete';
    /** 
    * Custom Operation.
    * Replace the SSX function called with a function of your own
    **/
    customAPIOperation?(
        params: SSXClientSession | Record<string, any> | any
    ): Promise<any>;
}

Here is an example of how you use it:

Custom Paths

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

Custom Methods

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

Custom Operation

const ssx = new SSX({
    providers: { 
        server: { 
            host: 'http://localhost:3001' 
            routes: {
                nonce:  {
                    url: '/my-custom-nonce',
                    method: 'post',
                    customAPIOperation: () => {
                        return "custom-nonce"
                    }
                }
            }
        } 
    }
});

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

providers.rpc

SSX supports all JSON RPC providers that are currently supported by ethers, 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.

providers: {
    rpc?: {
        service: string;
        network: string;
        apiKey: string;
    }
};

Here is an example of how you enable it:

predefined

import { 
    SSXRPCProviders, 
    SSXInfuraProviderNetworks
} from '@spruceid/ssx-core';

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

custom

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

resolveEns

This field enables 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 (defaults to false) or an object.

resolveEns: boolean | SSXEnsConfig;

SSXEnsConfig: {
  /** Enable the ENS resolution on server instead of on client. */
  resolveOnServer?: boolean;
  /** ENS resolution options. True means resolve all. */
  resolve: {
    /** Enable ENS name/domain resolution. */
    domain?: boolean;
    /** Enable ENS avatar resolution. */
    avatar?: boolean;
  };
}

Here is an example of how you enable it:

boolean

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

const sessionWithENSData = ssx.signIn(); 

object

const ssx = new SSX({
    resolveEns: {
        resolveOnServer: false, // defaults to false
        resolve: {
            domain: true,
            avatar: false
        }
    }
});

const sessionWithENSData = ssx.signIn(); 

You can see how to resolve ENS data from other addresses anytime after the sign-in on resolveEns.

resolveLens

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

This field enables 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'.

resolveLens: boolean | 'onServer';

Here is an example of how you enable it:

boolean

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

const sessionWithLensData = ssx.signIn(); 

onServer

const ssx = new SSX({
    resolveLens: 'onServer'
});

const sessionWithLensData = ssx.signIn(); 

You can see how to resolve Lens data from other addresses anytime after the sign-in on resolveLens.

siweConfig

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

siweConfig: {
    address?: string;
    chainId?: string;
    domain?: string;
    nonce?: string;
    issuedAt?: string;
    expirationTime?: string;
    requestId?: string;
    notBefore?: string;
    resources?: Array<string>;
    statement?: string;
};

Here is an example of how you use it:

const ssx = new SSX({
  siweConfig: {
    statement: 'Sign in to use our service today!',
    requestId: 'unique-id-for-specific-purpose',
  },
});