Quickstart your wallet

This guide and the configuration sections are to help developers launch their own ecosystem wallet. If you're looking to use an existing ecosystem wallet SDK, please refer to the usage section and install the specific ecosystem package.

The Ecosystem SDK is the easiest way to create your ecosystem wallet. It comes with a code-splitting environment, all the necessary tools to make your wallet SDK a reality. It is the easier way to create your own ecosystem wallet.

The Ecosystem SDK has two main parts:

@openfort/ecosystem-js/client: The Client SDK that you will use to create your wallet SDK.
@openfort/ecosystem-js/core: The Core SDK that you will use to create your wallet UI. Fort also includes a React specific package @openfort/ecosystem-js/react that you can use to get started faster.

When you finish this quickstart, this is what you will have:

0. Requirements#

Your project will need some specific configuration to enable code splitting:

Typescript version 5.0.2 or higher.
TS Config needs to have compilerOptions.moduleResolution set to bundler.
Your code editor and project should have the same version of Typescript.

We'll be needed 2 main projects to create your Ecosystem SDK:

Wallet SDK: This is the SDK that developers will use to integrate your wallet into their applications.
Wallet UI: This is the UI that users will interact with when using your wallet.

1. Install the ecosystem SDK#

Under your wallet SDK folder, install the latest version of Ecosystem SDK using your package manager of choice:

You will need to install @openfort/ecosystem-js at both your wallet SDK and wallet UI projects.

Terminal

npm install @openfort/ecosystem-js

2. Creating your wallet SDK#

This is how developers will make your wallet available in their application.

The easiest way to get started is to create a Proxy object in order to map the already provided functionality of the Client SDK. You can nevertheless change or add new methods to fit your needs.

main.ts

package.json

tsconfig.json

import { AppMetadata, Client } from "@openfort/ecosystem-js/client";
class EcosystemWallet extends Client {
    // optional constructor arguments developers can pass to the wallet for UI customization (e.g. logo, name, etc.) https://openfort.xyz/docs/reference/ecosystem-js/interfaces/client.AppMetadata.html
    constructor(appMetadata?: AppMetadata) {
        super({
            baseConfig: {
                // URL where the wallet UI is hosted:
                ecosystemWalletDomain: 'https://id.sample.openfort.xyz',
                windowStrategy: 'iframe', // or 'popup'. Rendering strategy the wallet UI.
            },
            appMetadata,
            // Optional App Info
            appearance: {
                icon: 'data:image/....', // a data url schema, compliant with RFC-2397.
                logo: 'https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV', // a URI pointing to an image. The image SHOULD be a square with 96x96px minimum resolution.
                name: 'Ecosystem Wallet Name', // human-readable local alias of the Wallet Provider
                reverseDomainNameSystem: 'com.openfort.ecosystem.wallet', // domain name from the Domain Name System in reverse syntax
            }
        });
        return new Proxy(this, {
            get: (target, prop) => {
                if (prop in target) {
                    const value = target[prop as keyof EcosystemWallet];
                    return typeof value === 'function' ? value.bind(target) : value;
                }
                return undefined;
            }
        });
    }
}
export default EcosystemWallet;

You're all set! By running the build script you'll get a dist folder with the compiled code. You can now publish your package to npm and share it with the world.

You can check all the available client methods in the Client SDK reference.

Wallet SDK Sample

Complete sample including auth, transactions and session keys.

3. Choose your key management and account system#

The Ecosystem SDK is agnostic to the key management and transaction signing solution you choose to use, so you can use any wallet SDK you prefer.

The team behind the Ecosystem SDK has created also create an embedded signer solution that you can use to create non-custodial wallets, referred to as OpenfortProvider.

3.1. Setting up Openfort signer and auth management#

Navigate to the auth providers page on the Openfort dashboard by selecting your project and then clicking Auth providers Methods in the side bar in the players page. Select the account types you'd like users to be able to login with. For more information on how to enable social logins, check out the dashboard docs.

From the Openfort Dashboard for select your desired app, navigate to the developers page in the top bar. On the de tab, find the API keys section. Get your Openfort API keys, you will need it in the next step.

You will find two keys:

Publishable Key: This value can be safely exposed in a client-side environment.
Secret Key: This value should never be exposed in a client-side environment. It should be kept secure and used only in a server-side environment. Learn more on how to use it in the server-side guide. You can further secure it for production applications.

To generate non custodial wallets, you will need to create a Shield instance. At the API keys page, scroll down to the Shield section and click on the Create Shield keys button. A one time pop-up will appear with a variable called encryption share. Its very important that you store it safely. You will not be able to see it again.

Then, in your page, you will see two Shield keys:

Publishable Key: This value can be safely exposed in a client-side environment.
Secret Key: This value should never be exposed in a client-side environment.

4. Creating your wallet UI#

The wallet UI is how information is shown to wallet users. Under your wallet UI folder, install the latest version of Ecosystem SDK using your package manager of choice. Remember to comply with the requirements to benefit from code splitting.

To make things more concrete, we'll be using OpenfortProvider as the key management and account system. You can use any other wallet SDK you prefer.

@openfort/ecosystem-js SDK comes with a set of pre-built React components that you can use to create your wallet UI. To learn how to customize it further, head to the UI screens guide.

In your project, import the EcosystemProvider component and wrap your app with it. Concretely, the EcosystemProvider must wrap any component or page that will use the Ecosystem SDK in your react app. It is generally recommended to render it as close to the root of your application as possible.

For example, in a NextJS or Create React App project, you may wrap your components like so:

Install the required dependencies#

Terminal

npm install @openfort/ecosystem-js wagmi viem@2.x @tanstack/react-query

TypeScript is optional, but highly recommended.

Implementation#

Getting the ecosystem id

When creating your client SDK you need to add the ecosystem ID. It can be found in their dashboard at the settings section. The ecosystemWalletDomain is the domain where your wallet UI is hosted.

index.tsx

App.tsx

Loading.tsx

lib/Wagmi.ts

lib/Query.ts

// Set your publishable key, shield publishable key and ecosystem id. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.openfort.xyz/developers/api-keys
// See your ecosystem ID here: https://dashboard.openfort.xyz/settings/project/overview
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { BrowserRouter, useNavigate } from 'react-router-dom';
import { WagmiProvider } from 'wagmi';
import { QueryClientProvider } from '@tanstack/react-query';
import * as Wagmi from './lib/Wagmi';
import * as Query from './lib/Query'
import { EcosystemProvider, OpenfortProvider, RecoveryMethod } from '@openfort/ecosystem-js/react';
async function getShieldSession(accessToken:string):Promise<string> {
  // When using AUTOMATIC embedded signer recovery, an encryption session is required.
  // Sample encryption session generation backend: https://github.com/openfort-xyz/ecosystem-sample/tree/main/wallet-ui/backend
  const response = await fetch(`${process.env.REACT_APP_BACKEND_URL!}/api/protected-create-encryption-session`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  });
  if (!response.ok) {
    throw new Error('Failed to fetch shield session');
  }
  const data = await response.json();
  return data.session;
}
const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <Loading />,
  });
  return <Component {...args} />;
};
export default function Providers({children}: {children: React.ReactNode}) {
const nav = useNavigate()
return (
  <EcosystemProvider
    appName='Rapidfire ID'
    navigateTo={(appState) => {
      nav({
        pathname: appState?.to,
        search: appState?.search
      })
    }}
    theme='midnight'
    supportedChains={[80002, 11155111, 84532, 28122024, 3939, 2358]}
    logoUrl='https://purple-magnificent-bat-958.mypinata.cloud/ipfs/QmfQrh2BiCzugFauYF9Weu9SFddsVh9qV82uw43cxH8UDV'
  >
    <WagmiProvider config={Wagmi.config}>
      <QueryClientProvider
        client={Query.client}
      >
        <OpenfortProvider
          // If you're using third party authentication with Openfort (i.e. your own auth or providers like Firebase), set thirdPartyAuthentication to true.
          thirdPartyAuthentication={false}
          ecosystemId={process.env.REACT_APP_OPENFORT_ECOSYSTEM_ID!}
          onRedirectCallback={(appState) => {
            return nav(appState?.returnTo || window.location.pathname);
          }}
          publishableKey={process.env.REACT_APP_OPENFORT_PUBLIC_KEY!}
          // To choose your recovery method, set the recoveryMethod to either 'AUTOMATIC' or 'PASSWORD'
          // Learn more about configure embedded signers: https://openfort.xyz/docs/guides/react/wallets/embedded-signer
          embeddedSignerConfiguration={
            {
              shieldPublishableKey: process.env.REACT_APP_SHIELD_PUBLIC_KEY!,
              recoveryMethod: RecoveryMethod.AUTOMATIC,
              // If you're using AUTOMATIC recovery, you need to provide an encryption session. 
              // If you're only using PASSWORD recovery, you can remove this function.
              getEncryptionSessionFn(getAccessToken) {
                return getShieldSession(getAccessToken);
              }
            }
          }
        >
          {children}
        </OpenfortProvider>
      </QueryClientProvider>
    </WagmiProvider>
  </EcosystemProvider>
);
}

Components:

Check all the available OpenfortProvider configuration methods at OpenfortProvider SDK reference.
Check all the available EcosystemProvider configuration methods at EcosystemProvider SDK reference.

Configure Supported Chains#

As you can see above, its required that you configure Wagmi and the chains you plan on enabling for your wallet as well as supportedChains in the EcosystemProvider.

Note that, to enable transaction simulation through asset changes, the Ecosystem SDK internally requires the eth_simulateV1 JSON-RPC method, so you will need to provide an RPC endpoint that supports this method (or disable simulation through the EcosystemProvider using disableTransactionSimulation).

Wallet UI Sample

Sample wallet UI with all the necessary screens.