@fordefi/web3-provider

Fordefi Web3 Provider

• Overview
• Installation
• Usage
  • Create a provider
  • Connect
  • Submit JSON RPC Requests
• API Reference
  • Configuration
  • Events
• Examples
• About Fordefi

Overview

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

It provides a request() function to execute JSON RPC methods and 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 has been 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, see Events.

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 has been successfully signed by an API Signer.

This sample code shows you how to send a transaction:

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

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

API Reference

Configuration

For details, see the 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.