Skip to main content

Browser Support

This page provides guidance for developers looking to build confidential dApps on Sapphire that work across different web browsers and integrate with wallets, including Metamask. It covers supported libraries, best practices for secure transactions, and quick steps for using the libraries.

Supported Libraries​

LibraryPackageAPI ReferenceSource
Sapphire TypeScript Wrapper@oasisprotocol/sapphire-paratimeAPIGitHub
Ethers v6@oasisprotocol/sapphire-ethers-v6APIGitHub
Viem@oasisprotocol/sapphire-viem-v2APIGitHub
Wagmi@oasisprotocol/sapphire-wagmi-v2APIGitHub

Choosing the Right Library​

Many browser-based dApps can use the lightweight Sapphire TypeScript wrapper if they rely entirely on the injected EIP-1193 wallet provider (e.g. window.ethereum) to communicate with and sign transactions on Sapphire. If you already use an EVM-frontend library, use our library-specific packages for Ethers, Viem or Wagmi.

Example: Starter project

If your project includes both a smart contract backend and a web frontend, you can explore our demo-starter repository. It provides a working example using React as well as a Vue branch.

Transaction encryption​

When using the supported libraries, ensure that all transactions containing sensitive information are encrypted. Encryption is essential to safeguard user data and ensure privacy. To verify that a transaction is encrypted, you can check the transaction details on the Oasis Block Explorer for the corresponding network (Localnet, Testnet, or Mainnet). Look for a green lock icon next to the transaction, which indicates that it is securely encrypted.

Check Calldata Encryption Programmatically

You can check programmatically if calldata is encrypted by using isCalldataEnveloped(), which is part of @oasisprotocol/sapphire-paratime.

View-Call Authentication

For authenticated view calls, make sure to visit the View-Call Authentication chapter to learn about the proper authentication procedures.

Lightweight Sapphire TypeScript Wrapper​

This shows a quick way to use Sapphire TypeScript Wrapper to encrypt transactions, for more info see @oasisprotocol/sapphire-paratime.

Usage​

Install the library with your favorite package manager

npm install @oasisprotocol/sapphire-paratime

After installing the library, find your Ethereum provider and wrap it using wrapEthereumProvider.

import { wrapEthereumProvider } from '@oasisprotocol/sapphire-paratime';

const provider = wrapEthereumProvider(window.ethereum);
Example: Hardhat boilerplate

Our maintained Hardhat boilerplate uses the Sapphire TypeScript Wrapper to enable confidential transactions in development. Find the code in the Sapphire ParaTime examples repository.

Ethers v6​

This shows a quick way to use Ethers v6 to encrypt transactions, for more info see @oasisprotocol/sapphire-ethers-v6.

Usage​

Install the library with your favorite package manager

npm install 'ethers@6.x' '@oasisprotocol/sapphire-ethers-v6'

After installing the library, find your Ethereum provider and wrap it using wrapEthersSigner.

import { BrowserProvider } from 'ethers';
import { wrapEthersSigner } from '@oasisprotocol/sapphire-ethers-v6';

const signer = wrapEthersSigner(
  new BrowserProvider(window.ethereum).getSigner()
);

Viem​

This shows a quick way to use Viem to encrypt transactions, for more info see @oasisprotocol/sapphire-viem-v2.

Usage​

Install the library with your favorite package manager

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

After installing the library, wrap the WalletClient with wrapWalletClient.

import { createWalletClient } from 'viem'
import { english, generateMnemonic, mnemonicToAccount } from 'viem/accounts';
import { sapphireLocalnet, sapphireHttpTransport, wrapWalletClient } from '@oasisprotocol/sapphire-viem-v2';

const account = mnemonicToAccount(generateMnemonic(english));

const walletClient = await wrapWalletClient(createWalletClient({
	account,
	chain: sapphireLocalnet,
	transport: sapphireHttpTransport()
}));
Viem Example

You can find more example code demonstrating how to use the library in our Hardhat-Viem example.

Wagmi​

This shows a quick way to use Wagmi to encrypt transactions, for more info see @oasisprotocol/sapphire-wagmi-v2.

Usage​

Install the library with your favorite package manager

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

After installing the library, use the Sapphire specific connector and transports.

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

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

For a complete example of how to use this library, please refer to our Wagmi example.