Sapphire Wagmi v2

A plugin for Wagmi v2 that provides seamless integration with the Oasis Sapphire network, enabling end-to-end encryption for transactions and gas estimations. This package wraps providers and connectors to automatically encrypt data when interacting with Sapphire networks.

Usage

Installation

Install the package along with required peer dependencies:

npm install @oasisprotocol/sapphire-wagmi-v2 wagmi@2.x viem@2.x
Copy

EIP-6963 Multi Injected Provider Discovery

Single chain - Sapphire

The primary way to use this library is by wrapping existing Wagmi connectors with wrapConnectorWithSapphire(). It is recommended to modify the connector name to differentiate it from "unwrapped" connectors. This works with any connector type (MetaMask, WalletConnect, Coinbase Wallet, etc.):

import { createConfig } from "wagmi";
import { sapphire, sapphireTestnet } from "wagmi/chains";
import { metaMask, walletConnect } from "@wagmi/connectors";
import {
  wrapConnectorWithSapphire,
  sapphireHttpTransport
} from "@oasisprotocol/sapphire-wagmi-v2";

export const wagmiConfig = createConfig({
  chains: [sapphire, sapphireTestnet],
  connectors: [
    wrapConnectorWithSapphire(
      metaMask,
      {
        id: 'metamask-sapphire',
        name: 'MetaMask (Sapphire)',
      }
    ),
    wrapConnectorWithSapphire(
      () => walletConnect({ projectId: 'your-project-id' }),
      {
        id: 'walletconnect-sapphire',
        name: 'WalletConnect (Sapphire)',
      }
    ),
  ],
  transports: {
    [sapphire.id]: sapphireHttpTransport(),
    [sapphireTestnet.id]: sapphireHttpTransport(),
    [sapphireLocalnet.id]: sapphireHttpTransport(),
  },
});
Copy

Multichain

For applications supporting both Sapphire and non-Sapphire networks, create separate connectors for each network. It's essential to avoid using encrypted connectors for non-Sapphire chains, and conversely, to ensure Sapphire chains use the appropriate encrypted connectors.

import { createConfig } from "wagmi";
import { sapphire, mainnet } from "wagmi/chains";
import { metaMask } from "@wagmi/connectors";
import {
  wrapConnectorWithSapphire,
  sapphireHttpTransport,
  sapphireLocalnet
} from "@oasisprotocol/sapphire-wagmi-v2";
import { http } from "wagmi";

export const wagmiConfig = createConfig({
  chains: [sapphire, sapphireLocalnet, mainnet],
  connectors: [
    // Regular MetaMask for non-Sapphire chains
    metaMask(),
    // Sapphire-wrapped MetaMask for Sapphire chains
    wrapConnectorWithSapphire(
      metaMask(),
      {
        id: 'metamask-sapphire',
        name: 'MetaMask (Sapphire)',
      }
    ),
  ],
  transports: {
    [sapphire.id]: sapphireHttpTransport(),
    [sapphireLocalnet.id]: sapphireHttpTransport(),
    [mainnet.id]: http(),
  },
});
Copy

EIP-1193 Injected provider

In your Wagmi config definition, wrap the injected provider for Sapphire using injectedWithSapphire().

import { createConfig } from "wagmi";
import { sapphire, sapphireTestnet } from "wagmi/chains";
import {
  injectedWithSapphire,
  sapphireHttpTransport,
  sapphireLocalnet
} from "@oasisprotocol/sapphire-wagmi-v2";

export const wagmiConfig = createConfig({
  multiInjectedProviderDiscovery: false,
  chains: [sapphire, sapphireTestnet, sapphireLocalnet],
  connectors: [injectedWithSapphire()],
  transports: {
    [sapphire.id]: sapphireHttpTransport(),
    [sapphireTestnet.id]: sapphireHttpTransport(),
    [sapphireLocalnet.id]: sapphireHttpTransport()
  },
});
Copy

View-calls data encryption

Use a public client with createPublicClient() and for read-only operations like querying blockchain data and calling view functions without requiring a wallet. The Sapphire transport is still necessary even for read operations to properly handle end-to-end encryption when accessing private contract state or making view calls that return encrypted data.

import {
  sapphireHttpTransport,
  wrapWalletClient,
  createSapphireSerializer,
  sapphireLocalnet
} from '@oasisprotocol/sapphire-wagmi-v2';
import { createWalletClient } from 'viem';

// Create a Sapphire-enabled HTTP transport
const transport = sapphireHttpTransport();

const client = await wrapWalletClient(
  createWalletClient({
    account,
    chain: sapphireLocalnet,
    transport: sapphireHttpTransport()
  })
);
Copy

For a complete example of how to use this library, please refer to our Wagmi example. In case you want to integrate with a 3rd wallet library, also see the Wagmi example for how to do so, as the example for Rainbowkit is provided.