@fordefi/web3-provider NPM

Overview

This provider class implements EIP-1193 powered by the Fordefi API.

It provides a request() function to execute JSON RPC methods, and it emits the relevant events.

Installation

Using yarn:

yarn add @fordefi/web3-provider

Using npm:

npm add --save @fordefi/web3-provider

Usage

Create a provider

Each instance manages a single address (vault) on a specific chain.

Follow the API Reference below for the available configuration options.

import { FordefiWeb3Provider, FordefiProviderConfig } from "@fordefi/web3-provider";

const config: FordefiProviderConfig = {
  chainId: 11155111,
  address: "0x1234567890123456789012345678901234567890",
  apiUserToken: process.env.FORDEFI_API_USER_TOKEN,
  apiPayloadSignKey: process.env.FORDEFI_API_PAYLOAD_SIGNING_KEY,
};

const provider = new FordefiWeb3Provider(config)

Connect

The spec requires a provider to be connected to submit requests.

This provider automatically connects to Fordefi when a new instance is constructed, and emits a connect event once communication with the Fordefi platform was established.

To subscribe to the event:

// callback to act upon a `connect` event
const onConnect = ({ chainId }: ProviderConnectInfo) => {
  console.log(`Connected to chain ${chainId}`);
}

// option 1: subscribe using a callback
provider.on('connect', onConnect);

// option 2: wait for a promise to be resolved
const result = await provider.waitForEmittedEvent('connect');
onConnect(result);
// or
provider
  .waitForEmittedEvent('connect')
  .then(onConnect);

For more details read the Events section.

Submit JSON RPC Requests

The request({ method, params }) method sends JSON RPC requests to the provider. It returns a promise that resolves to the result of the request.

All methods related to creating and/or signing transactions will resolve once the transaction was successfully signed by an API Signer.

An example of sending a transaction:

const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: '0x1234567890123456789012345678901234567890',
    to: '0x1234567890123456789012345678901234567890',
    value: '0x10000000000',
  }],
});

console.log(`Transaction hash: ${txHash}`);

API Reference

Configuration

(see FordefiProviderConfig interface)

interface FordefiProviderConfig {
  /**
   * Chain ID as a number or a named chain.
   *
   * For example, assuming Ethereum Sepolia chain:
   * - Numeric value: `EvmChainId.NUMBER_11155111` or `11155111`
   * - Named chain: `EvmChainUniqueId.ethereumSepolia` or 'evm_ethereum_sepolia'.
   */
  chainId: EvmChainId | EvmChainUniqueId;

  /**
   * EVM address.
   *
   * For example: '0x1234567890123456789012345678901234567890'.
   */
  address: Address;

  /**
   * Fordefi API user token (base64 encoded) issued via the Fordefi Web Console.
   * See: https://app.fordefi.com/user-management
   *
   * For example: 'eyJWthEAdEr.eyJwTPaYLoad.SiGNAtUrEBase64=='
   */
  apiUserToken: string;

  /**
   * Private key in PEM format used to sign the body of requests sent to the Fordefi API.
   * This is the content the private `.pem` file.
   * See: https://docs.fordefi.com/reference/pair-an-api-client-with-the-api-signer
   *
   * Example of a private ECDSA `.pem` file:
   * -----BEGIN EC PRIVATE KEY-----
   * PrivateKeyBase64==
   * -----END EC PRIVATE KEY-----
   */
  apiPayloadSignKey: string;
  
  /**
   * Fallback JSON-RPC HTTP node url.
   * Methods not implemented by this provider will pass through and be handled by this node.
   *
   * For example: 'https://rpc.sepolia.org'.
   */
  rpcUrl?: string;
  
  /**
   * Fordefi API base url (used for development), defaults to production API url.
   *
   * For example: 'https://api.fordefi.com'.
   */
  apiBaseUrl?: string;
}

Events

Subscribe to events using the on(eventName, callback) method:

// emitted once during the connection process with the `address` you provided.
provider.on('accountsChanged', (accounts: Address[]) => { /* handle event here */ });

// emitted once during connection process with the `chainId` you provided
provider.on('chainChanged', (chainId: string) => { /* handle event here */ });

// provider becomes connected
provider.on('connect', (connectInfo: ProviderConnectInfo) => { /* handle event here */ });

// provider becomes connected
provider.on('disconnect', (error: ProviderRpcError) => { /* handle event here */ });

Usubscribe from events using the removeListener(eventName, callback) method, and provide the event name and the callback function previously used to subscribe to the event. For example:

provider.removeListener('connect', onConnect);

The promisified waitForEmittedEvent(eventName) helper method returns a promise, that resolves once (following a single emitted event), with the event payload. For example:

provider
  .waitForEmittedEvent('connect')
  .then((connectInfo: ProviderConnectInfo) => {
    console.log(`Connected to chain ${connectInfo.chainId}`)
  });

Examples

Checkout usage examples in the e2e test.

About Fordefi

Fordefi is a blockchain security company that provides an institutional-grade MPC (Multi-Party Computation) non-custodial wallet specifically built for decentralized finance (DeFi).

Fordefi focuses on enhancing the security and efficiency of transactions in the DeFi space through the innovative use of MPC technology for key management and transaction signing, and by providing a secure and user-friendly interface through various clients: 1. Fordefi Browser Extension for interaction with dApps. 2. Fordefi Web Console for securely performing administrative operations such as setting up transaction policy rules and user management, which require approvals by a quorum of administrators. 3. Fordefi API for developers to interact with the Fordefi infrastructure.

Read more about Fordefi on the site and docs.