Installation

This guide covers installing @snapshot-labs/sx and setting up your development environment for building governance applications.

Package Installation

NPM

npm install @snapshot-labs/sx

Yarn

yarn add @snapshot-labs/sx

PNPM

pnpm add @snapshot-labs/sx

Package Information

Package Name: @snapshot-labs/sx
Current Version: 0.1.10
License: MIT
Repository: github.com/snapshot-labs/sx-monorepo

Importing the Package

The SDK uses ES modules by default and also provides CommonJS support.

Import Everything

import * as sx from '@snapshot-labs/sx';

// Access clients
const client = new sx.clients.EvmEthereumSig(config);

// Access network configs
const network = sx.evmMainnet;

// Access utilities
const encoded = sx.utils.encoding.executionHash(...);

Import Specific Modules

import { clients, evmMainnet, starknetSepolia } from '@snapshot-labs/sx';

const evmClient = new clients.EvmEthereumSig({
  networkConfig: evmMainnet,
  manaUrl: 'https://mana.pizza'
});

const starknetClient = new clients.StarknetSig({
  networkConfig: starknetSepolia,
  manaUrl: 'https://mana.pizza'
});

Import Named Exports

import {
  clients,
  utils,
  getExecutionData,
  getEvmStrategy,
  getStarknetStrategy,
  getOffchainStrategy,
  evmMainnet,
  evmSepolia,
  starknetMainnet,
  offchainMainnet
} from '@snapshot-labs/sx';

Dependencies

The SDK has the following peer dependencies that you’ll need in your project:

For EVM Chains

npm install ethers@^5.8.0

The SDK uses ethers.js v5 for EVM interactions:

import { Wallet, providers } from 'ethers';
import { clients, evmMainnet } from '@snapshot-labs/sx';

const provider = new providers.JsonRpcProvider('https://rpc.snapshot.org/1');
const wallet = new Wallet(privateKey, provider);

const client = new clients.EvmEthereumTx({
  networkConfig: evmMainnet
});

For Starknet

npm install [email protected]

The SDK uses the starknet.js library:

import { Account, RpcProvider } from 'starknet';
import { clients, starknetMainnet } from '@snapshot-labs/sx';

const provider = new RpcProvider({
  nodeUrl: 'https://starknet-mainnet.public.blastapi.io'
});
const account = new Account(provider, address, privateKey);

const client = new clients.StarknetTx({
  networkConfig: starknetMainnet
});

Additional Dependencies

The SDK automatically includes these dependencies:

@ethersproject/* - Core Ethereum utilities (ABI, addresses, signing, etc.)
@openzeppelin/merkle-tree - Merkle tree utilities for whitelist strategies
@shutter-network/shutter-crypto - Privacy-preserving voting support
micro-starknet - Lightweight Starknet utilities

TypeScript Setup

The SDK is written in TypeScript and includes full type definitions.

TypeScript Configuration

Ensure your tsconfig.json has the following settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2020"],
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "resolveJsonModule": true
  }
}

Type Imports

The SDK exports comprehensive types for all data structures:

import type {
  // Client configuration types
  ClientConfig,
  ClientOpts,
  EvmNetworkConfig,
  StarknetNetworkConfig,
  OffchainNetworkEthereumConfig,
  // Action types
  Propose,
  Vote,
  UpdateProposal,
  // Envelope type for signed data
  Envelope,
  // Strategy and executor types
  Strategy,
  ExecutorType,
  ExecutionInput,
  // Network-specific types
  AddressConfig,
  SignatureData
} from '@snapshot-labs/sx';

Using Types in Your Code

import { clients, evmMainnet } from '@snapshot-labs/sx';
import type { ClientConfig, Propose, Envelope } from '@snapshot-labs/sx';

const config: ClientConfig = {
  networkConfig: evmMainnet
};

const proposeData: Propose = {
  space: '0x...',
  authenticator: '0x...',
  strategies: [{
    index: 0,
    address: '0x...',
    params: '0x'
  }],
  executionStrategy: {
    addr: '0x...',
    params: '0x'
  },
  metadataUri: 'ipfs://...'
};

Network Configurations

The SDK provides pre-configured settings for all supported networks.

EVM Networks

import {
  evmMainnet,      // Ethereum Mainnet
  evmSepolia,      // Ethereum Sepolia Testnet
  evmOptimism,     // Optimism
  evmPolygon,      // Polygon
  evmArbitrum,     // Arbitrum One
  evmBase,         // Base
  evmMantle,       // Mantle
  evmApe,          // ApeChain
  evmCurtis        // Curtis Testnet
} from '@snapshot-labs/sx';

// Each network config includes:
// - eip712ChainId: Chain ID for EIP-712 signing
// - blockTime: Average block time in seconds
// - maxPriorityFeePerGas: Gas settings
// - proxyFactory: Factory contract for deploying spaces
// - masterSpace: Master implementation contract
// - authenticators: Available authenticator contracts
// - strategies: Available voting strategy contracts
// - executionStrategiesImplementations: Available executor contracts

Starknet Networks

import {
  starknetMainnet,
  starknetSepolia
} from '@snapshot-labs/sx';

Offchain Networks

import {
  offchainMainnet,  // EIP-712 chainId: 1
  offchainGoerli    // EIP-712 chainId: 5
} from '@snapshot-labs/sx';

Custom Network Configuration

You can also create custom network configurations:

import type { EvmNetworkConfig } from '@snapshot-labs/sx';

const customNetwork: EvmNetworkConfig = {
  eip712ChainId: 1,
  blockTime: 12,
  proxyFactory: '0x...',
  masterSpace: '0x...',
  authenticators: {
    '0x...': { type: 'ethSig' }
  },
  strategies: {
    '0x...': { type: 'vanilla' }
  },
  executionStrategiesImplementations: {
    SimpleQuorumAvatar: '0x...'
  }
};

RPC Endpoints

You’ll need RPC endpoints to interact with blockchain networks.

Snapshot-Provided RPCs

import { providers } from 'ethers';

const ethMainnet = new providers.JsonRpcProvider('https://rpc.snapshot.org/1');
const ethSepolia = new providers.JsonRpcProvider('https://rpc.snapshot.org/11155111');
const optimism = new providers.JsonRpcProvider('https://rpc.snapshot.org/10');
const polygon = new providers.JsonRpcProvider('https://rpc.snapshot.org/137');
const arbitrum = new providers.JsonRpcProvider('https://rpc.snapshot.org/42161');
const base = new providers.JsonRpcProvider('https://rpc.snapshot.org/8453');

Third-Party RPC Providers

You can also use services like:

Infura: https://mainnet.infura.io/v3/YOUR_API_KEY
Alchemy: https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
Public RPCs: Various free options available

Mana Relayer URL

For gasless meta-transactions, you’ll need to configure the Mana relayer URL:

import { clients, evmMainnet } from '@snapshot-labs/sx';

const client = new clients.EvmEthereumSig({
  networkConfig: evmMainnet,
  manaUrl: 'https://mana.pizza'  // Production Mana instance
});

For development/testing:

const client = new clients.EvmEthereumSig({
  networkConfig: evmSepolia,
  manaUrl: 'http://localhost:3000'  // Local Mana instance
});

Verification

Verify your installation by running a simple test:

import { clients, evmMainnet } from '@snapshot-labs/sx';

const client = new clients.EvmEthereumSig({
  networkConfig: evmMainnet,
  manaUrl: 'https://mana.pizza'
});

console.log('SDK installed successfully!');
console.log('Network:', evmMainnet.eip712ChainId);
console.log('Client:', client.config.networkConfig.eip712ChainId);

Next Steps

Now that you have the SDK installed, explore:

SDK Overview - Understand the package structure
EVM Client - Start building with EVM chains
Starknet Client - Work with Starknet
Offchain Client - Implement gasless voting
Examples - Browse code examples

Overview

Clients

Utilities

Installation

Installation

Package Installation

NPM

Yarn

PNPM

Package Information

Importing the Package

Import Everything

Import Specific Modules

Import Named Exports

Dependencies

For EVM Chains

For Starknet

Additional Dependencies

TypeScript Setup

TypeScript Configuration

Type Imports

Using Types in Your Code

Network Configurations

EVM Networks

Starknet Networks

Offchain Networks

Custom Network Configuration

RPC Endpoints

Snapshot-Provided RPCs

Third-Party RPC Providers

Mana Relayer URL

Verification

Next Steps

Build docs developers (and LLMs) love

Overview

Clients

Utilities

​Installation

​Package Installation

​NPM

​Yarn

​PNPM

​Package Information

​Importing the Package

​Import Everything

​Import Specific Modules

​Import Named Exports

​Dependencies

​For EVM Chains

​For Starknet

​Additional Dependencies

​TypeScript Setup

​TypeScript Configuration

​Type Imports

​Using Types in Your Code

​Network Configurations

​EVM Networks

​Starknet Networks

​Offchain Networks

​Custom Network Configuration

​RPC Endpoints

​Snapshot-Provided RPCs

​Third-Party RPC Providers

​Mana Relayer URL

​Verification

​Next Steps

Build docs developers (and LLMs) love

Installation

Package Installation

NPM

Yarn

PNPM

Package Information

Importing the Package

Import Everything

Import Specific Modules

Import Named Exports

Dependencies

For EVM Chains

For Starknet

Additional Dependencies

TypeScript Setup

TypeScript Configuration

Type Imports

Using Types in Your Code

Network Configurations

EVM Networks

Starknet Networks

Offchain Networks

Custom Network Configuration

RPC Endpoints

Snapshot-Provided RPCs

Third-Party RPC Providers

Mana Relayer URL

Verification

Next Steps