Fordefi Web3 Provider
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
The full API reference is available on the Fordefi Web3 Provider docs site.
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: 11155111.
* - Named chain: 'evm_ethereum_sepolia'.
*/
chainId: number | string;
/**
* 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;
/**
* Total duration in ms of polling for transaction lifecycle status changed after a transaction was submitted. By default, it would stop after 24 hours.
*/
timeoutDurationMs?: number;
/**
* Duration in ms between checks for transaction lifecycle status updates after a transaction was submitted. The minimum value is 500, and by default it's 5000.
*/
pollingIntervalMs?: number;
}
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:
- Fordefi Browser Extension for interaction with dApps.
- 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.
- Fordefi API for developers to interact with the Fordefi infrastructure.