@futureverse/react

Introduction

The Futureverse Platform provides a comprehensive set of building blocks that can be used by developers to create high-quality experiences for the open Metaverse. With a focus on an experience familiar to web2 users, but built with web3 fundamentals.

These building blocks are designed to enable developers to easily create custom applications, leveraging a wide range of powerful tools and technologies in web, Unity and mobile.

Authentication

The authentication solution offers experiences a solution for onboarding both Web2 and Web3 users into their experience.

It implements best practices for authentication on mobile devices and websites, which can maximise sign-in and sign-up conversion for your experience. It also handles tricky edge cases that can be security sensitive and error-prone to handle correctly.

Authentication integrates with the FuturePass custodial wallet and uses industry standards like OpenID Connect and OAuth 2.0 for a secure and uncomplicated onboarding experience.

FuturePass is already used in the following experiences:

Getting Started

Follow the below steps to install and integrate the library in your experience. If you prefer to dive directly into code, the examples and configuration from this document are also available in two demo apps:

Installation

npm

npm i @futureverse/experience-sdk @futureverse/react @futureverse/component-library --save

yarn

yarn add @futureverse/experience-sdk @futureverse/react @futureverse/component-library

Peer Dependencies

This library requires the following peer dependencies:

    "react": "^18.2.0",
    "@polkadot/api": "^10.9.1",
    "@polkadot/types": "^10.9.1",
    "@polkadot/util": "^12.6.1",
    "@polkadot/util-crypto": "^12.6.1",
    "@therootnetwork/api": "1.0.8",
    "@therootnetwork/api-types": "1.0.3",
    "@therootnetwork/extrinsic": "1.0.5",
    "@futureverse/component-library": "~0.2.0",
    "@futureverse/experience-sdk": "~0.11.0-alpha.1",
    "@futureverse/identity-contract-bindings": "~0.1.0",
    "@futureverse/rpc-kit": "~0.1.0",
    "@web3-react/eip1193": "^8.0.27-beta.0",
    "ethers": "5.7.2"

Caveats

Create React App

CRA has an ongoing issue with importing not fully specified ESM Modules. The easiest way to deal with it is to use this workaround. This doesn’t apply to the Experience Demo Next App.

Next.js

Please use:

experimental: {
    esmExternals: "false",
}

In your Next config.

App Router

This library does not officially support Next.js 14 using App Router at this time. However, you can use the solution from the official Next.js documentation to work around it.

Server-side Frameworks (SSR)

Due to nature of Web3 authentication, @futureverse/react operates on the client side. For users utilizing frameworks that support server-side rendering, such as Next.js, a dynamic import approach is necessary to ensure compatibility. This modification prevents the SDK from loading on the server side, which is crucial due to the browser-specific functionalities of the Xaman integration.

import dynamic from 'next/dynamic'
const FutureverseProvider = dynamic(() => import('@futureverse/react').then((mod) => mod.FutureverseProvider), {
  ssr: false,
})

This updated import method ensures that the FutureverseProvider is only loaded in the browser environment, thus bypassing SSR execution and aligning with the new SDK constraints. This approach helps maintain smooth operation and user experience across all platforms while leveraging the new capabilities provided by the Xaman Wallet integration.

To further clarify, the example provided above is specifically tailored for applications using Next.js. If you are utilizing other frameworks that support server-side rendering (SSR), similar adjustments will be necessary to ensure compatibility with the browser-only requirements of the new SDK.

For frameworks other than Next.js, you should similarly configure dynamic imports or equivalent mechanisms provided by your specific framework to prevent the SDK from loading during the server-side rendering process. Each framework may have its own method or syntax for handling such cases, so it is recommended to consult the official documentation of the framework for precise instructions on bypassing SSR.

This step is crucial to ensure that all browser-specific functionalities, particularly those related to the Xaman Wallet integration, operate flawlessly without attempting to execute in non-browser environments where they are not supported. By adapting your application's import and initialization logic accordingly, you can maintain a robust and efficient application architecture that leverages the full capabilities of the updated SDK.

Register your experience

Before using FutureverseProvider container you will need to register an OAuth2 client with the Futureverse Identity Provider using the Manage Clients Console:

Production: https://login.futureverse.app/manageclients
Development / Staging: https://login.futureverse.cloud/manageclients
Audit (Canary): https://login.futureverse.kiwi/manageclients

You will need to provide two arguments:

Client Name: the name of your application (e.g. futureverse-experience-demo). Don’t use any characters other than alphanumeric, - and _. This does not have to be unique, you can register again with the same name and you will receive a fresh set of credentials.
Redirect URLs: The URL in your application to redirect to after a successful login. Please make sure to include protocol in the URL (http for development, https for production). You can provide multiple URLs by separating them with a comma. This may be useful if e.g. you’d like to register localhost for local development and a deployed URL for your staging environment. For example: [http://localhost:3000/](http://localhost:3000/login)home,https://*-demo[.preview.com](http://futureverse.vercel.com/)/home,[https://futureverse-experience-demo.staging.com/home](https://identity-dashboard.futureverse.cloud/) would register localhost for local development, a wildcarded preview URL for dynamic deployments and a staging URL.

Note: wildcards in Redirect URLs are only available when registering using the Development portal listed above. When registering your app for production you need to provide full Redirect URLs.

Upon successful registration, you’ll be presented with a Client ID, Name and an Access Token. Make sure to save these. You will need the Client ID and the Redirect URL in your application to configure the FutureverseProvider. Treat them as any other secrets in your application (so don’t commit them with your code!).

Experience Name and Access Token are used to view and edit this registration, they’re not required in the codebase.

`FutureverseProvider` configuration

The core functionality is exposed through React Context, so you will need to wrap your application in a FutureverseProvider which has the following parameters:

Here's the corrected Markdown table:

Parameter	Description	Type
`stage`	This controls which set of constants will be available to use. If you have more than two stages in your project (e.g. staging or testing you can decide whether you’d like development or production constants).	'development', 'production'
`Web3Provider`	The Web3 Provider you’re using to interact with the blockchain in your app.	'wagmi'
`authClient`	An instance of FutureverseAuthClient with configured environment and any user state listeners.	See below for details.
`requiredChains`	An array of chains your application supports, required by WalletConnect. Defaults to ['ETHEREUM'] if left undefined. When picking chains, mainnet and testnet (Goerli or Porcini) are included.	['ETHEREUM'], ['TRN'], ['ETHEREUM', 'TRN']
`walletConnectProjectId`	Obtain it from WalletConnect Cloud, follow the instruction here
`isCustodialLoginEnabled`	Set to true if you want to allow Custodial Accounts in your experience. Available only with version `1.0.0` and higher.	boolean

`FutureverseAuthClient` configuration

FutureverseAuthClient has the following parameters:

Parameter	Description	Type
`clientId`	The client ID you obtained when integrating FuturePass Web SDK	string
`redirectUri`	The URI in your application that the successful authentication should redirect to. It’s the main URI you registered above.	string
`userStore` (optional)	This stores the user information in browser storage. Note: TTL for this store needs to be 7 days.	Storage
`environment`	An object containing the following properties:	object
`chain`	The TRN chain you want to interact with	`mainnet` / `porcini`
`idpURL`	The identity provider URL you want to interact with.	See below
`signerURL`	The signer URL you want to interact with.	See below

While the environment object is configurable and it can be especially useful if you’d like to point the app to a specific chain regardless of the stage you’re running in, in most cases it’s best to use one of the provided environments from the @futureverse/experience-sdk package:

sdk.ENVIRONMENTS.staging - for use with testnet and staging Custodial Signer and Identity Provider services. Use this for staging and development builds.
sdk.ENVIRONMENTS.audit - for use only in specific cases as advised by the FuturePass team
sdk.ENVIRONMENTS.production - for use with mainnet and production Custodial Signer and Identity Provider services. Use this for the production build.

IMPORTANT: staging and audit may be volatile, so never depend on them for your production build. The services may become unavailable without warning, the data can be cleared. It is purely for development and testing purposes.

Note: Make sure to use the right client ID from the step “Register your experience” above. E.g. if you register your experience using the Development / Staging service and try to use it with your environment set to sdk.ENVIRONMENTS.production the service will respond with invalid client error.

Auth client user state listeners

Additionally, you can register listeners for user state changes on the FutureverseAuthClient. The UserState can be:

SignedIn
SignedOut
SignInFailed

One common use case for a listener is to disable silent authentication on SignedOut.

Example

import * as React from 'react'
import {
  FutureverseAuthClient,
  FutureverseProvider,
  TrnApiProvider,
  UserState,
} from '@futureverse/react'
import * as fvSdk from '@futureverse/experience-sdk'

export default function MyFutureverseExperience(): JSX.Element {
  const authClient = React.useMemo(() => {
    const client = new FutureverseAuthClient({
      clientId: <YOUR CLIENT ID>,
      environment: process.env.NODE_ENV === 'production'
					? fvSdk.ENVIRONMENTS.production
					: fvSdk.ENVIRONMENTS.development,
      redirectUri: <YOUR REDIRECT URI>,
			responseType: 'code' // required for Custodial Auth
    })

		// This is not necessary, just an example of adding an user state change listener
    client.addUserStateListener(userState => {
      if (userState === UserState.SignedOut) {
        sessionStorage.setItem(<YOUR SILENT AUTH STORAGE FLAG KEY>, 'disabled')
      }
    })
    return client
  }, [])

  return (
      <FutureverseProvider
          stage={
            config.public.environment.stage === 'production'
             ? 'production'
             : 'development'
          }
          authClient={authClient}
          Web3Provider="wagmi"
          walletConnectProjectId={config.public.walletConnectProjectId}
					isCustodialLoginEnabled={true | false} // required for Custodial Auth
        >
          <Component {...pageProps} />
        </FutureverseProvider>
  )
}

Experience can pass in custom cookie UserStore like following:

    const client = new FutureverseAuthClient({
      clientId: <YOUR CLIENT ID>,
      environment: process.env.NODE_ENV === 'production'
					? fvSdk.ENVIRONMENTS.production
					: fvSdk.ENVIRONMENTS.development,
      redirectUri: <YOUR REDIRECT URI>,
			responseType: 'code' // required for Custodial Auth,
			userStore: new CookieStorage({
        path: '/',
        sameSite: 'Strict',
        domain: (() => {
          return `.<YOUR HOSTNAME>`
        })(),
        expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
      })
    })

Authentication flow

The default authentication flow employs a client-side PKCE grant. All the details of handling that flow are abstracted as part of the library except mounting a callback handler.

Mounting a callback handler

Add a route for handling the OAuth2 redirect (your redirectUri). This is where your application will redirect on success.
Create the useSignInHandler hook and call it where you want the authentication to be performed. Common places are in the Navigation or your Index route.

import { useFutureverse, UserState } from '@futureverse/react'
import * as React from 'react'

export function useSignInHandler() {
  const { login, authClient } = useFutureverse()

  React.useEffect(() => {
    const userStateChange = (userState: UserState) => {
      if (userState === UserState.SignedIn) {
        // The user has successfully signed in, redirect them somewhere
      }

      if (userState === UserState.SignedOut) {
        // The user is not signed in, so do it
        login()
      }

      if (userState === UserState.SignInFailed) {
        // The sign is failed, either show an error or try again
      }
    }

    authClient.addUserStateListener(userStateChange)
    return () => {
      authClient.removeUserStateListener(userStateChange)
    }
  }, [account, authClient, login, router])
}

Silent authentication

Silent authentication is a process where a user is authenticated without their direct involvement, typically after an initial login, improving the user experience by avoiding unnecessary login prompts.

To enable silent authentication, pass an options object to login function and provide the { silent: true, targetEOA: <ADDRESS OF LOGGED IN USER> } properties.

The silent property should be set to true only if a user is (TODO)

Example

import { useFutureverse, UserState } from '@futureverse/react'
import * as React from 'react'
import * as wagmi from 'wagmi'

export const FV_AUTH_SILENT_LOGIN_KEY = 'fvAuthSilentLogin'
export const FV_AUTH_PREV_PATH_KEY = 'fvAuthPrevPath'

function Home() {
  const { login, authClient } = useFutureverse()
  const { address: accountAddress } = wagmi.useAccount()

  React.useEffect(() => {
    const userStateChange = (userState: UserState) => {
      if (userState === UserState.SignedIn) {
        sessionStorage.setItem(FV_AUTH_SILENT_LOGIN_KEY, 'enabled')
        const prevPath = sessionStorage.getItem(FV_AUTH_PREV_PATH_KEY)
        someRedirectFunction(prevPath ?? '/home')
      }
      if (userState === UserState.SignedOut) {
        const silentAuth = sessionStorage.getItem(FV_AUTH_SILENT_LOGIN_KEY)
        const isSilent = silentAuth !== 'disabled'
        if (!isSilent) {
          sessionStorage.setItem(FV_AUTH_PREV_PATH_KEY, router.pathname)
          someRedirectFunction('/')
        }
        login(isSilent ? { silent: true, targetEOA: accountAddress ?? null } : undefined)
      }
      if (userState === UserState.SignInFailed) {
        someRedirectFunction('/')
        sessionStorage.setItem(FV_AUTH_SILENT_LOGIN_KEY, 'disabled')
        login()
      }
    }
    authClient.addUserStateListener(userStateChange)
    return () => {
      authClient.removeUserStateListener(userStateChange)
    }
  }, [accountAddress, authClient, login])
}

export default Home

Logging in and logging out

With the callback handler mounted, we can now start authenticating our users. Invoking login will display the standard Futureverse login prompt, offering a range of different login methods to the user. Here the user can choose to login / signup using an existing wallet or by letting us create and manage a wallet on their behalf (Coming Soon!).

If you configured the useSignInHandler hook as described above, the log in modal will pop up automatically if the user is not logged in. login and logout functions from useFutureverse give you a fine-grained control over the process.

function FutureverseExperienceDemo() {
  const { login } = useFutureverse()

  return (
    <button
      onClick={() => {
        login()
      }}
    >
      Login!
    </button>
  )
}

Accessing the user session

To access the user session query the user property on useFutureverse which will be available as long as the user is logged in.

function FutureverseExperienceDemo() {
  const { userSession } = useFutureverse()

  if (userSession != null) {
		return <>You are logged in!</>
	}

  return {
		<>Not logged in</>
	}
}

ID Token

ID token is a JSON Web Token (JWT) that is issued by identity provider to a client application as part of the user authentication process. The ID token serves as a proof of the user's identity and is used by the client application to obtain basic profile information about the user.

The payload of an ID token typically includes a set of claims about the authentication of an end-user by an Authorisation Server.

Here is the table described the claims that are included in an ID token payload according to the different login type:

Login Type	Claim	Description	Optional
Custodial and non-Custodial	`sub`	A locally unique and never reassigned identifier within the Issuer for the End-User	No
Custodial and non-Custodial	`eoa`	The externally owned account derived from public key	No
Custodial and non-Custodial	`futurepass`	The FuturePass account address associated with this account	No
Custodial and non-Custodial	`chainId`	The block chain id	No
Custodial and non-Custodial	`nonce`	A string value used to associate a Client session with an ID Token, and to mitigate replay attacks	No
Custodial and non-Custodial	`at_hash`	A hash value verifies the integrity and authenticity of the access token	No
Custodial and non-Custodial	`aud`	Intended audience for the ID token	No
Custodial and non-Custodial	`exp`	The expiration time on or after which the ID token MUST NOT be accepted for processing	No
Custodial and non-Custodial	`iat`	The time at which the ID token was issued	No
Custodial and non-Custodial	`iss`	The issuer of the response	No
Custodial	`auth_time`	The time when the authentication occurred	Yes
Custodial and non-Custodial	`custodian`	self for non-custodial, fv for custodial	No
Custodial (Google and Facebook)	`email`	When logged in with Google, this is the user's email address. The value of this claim may not be unique to the Google account used to log in, and could change over time.	Yes

When logged in with Facebook, this is the user's primary email address listed on their profile. If there is no valid email address is available, this claim is not included in the ID token.

Because the email may not be present, the experiences should not use this claim as the primary identifier to link to the user’s record.

Web3 Integration

The <FutureverseProvider/> container wraps the app in a given web3 react provider library (wagmi by default.) Interacting with web3 apis is thus simply a matter of using the web3 react provider library’s API as per usual. This is true both for custodial and non-custodial logons.

If you need a finer gained control or want to wrap your application in a different web3 react provider, you can set the noWagmi option <FutureverseProvider ... noWagmi/>. This enables you to wrap your application in any web3 react library, however, in order to get login working you’ll have to provide a custom LoginAdapter. This login adapter enables the Futureverse sign in code to sign the challenges it needs to in order to prove ownership over an account.

import { useFutureverse } from '@futureverse/react'
import { useAccount, useBalance } from 'wagmi'

function Home() {
  const { login, logout, userSession } = useFutureverse()
  const account = useAccount()
  const accountBalance = useBalance({
    address: account.address,
  })

  return (
    <div>
      Home Route
      {userSession == null ? (
        <button
          onClick={() => {
            login()
          }}
        >
          Log In
        </button>
      ) : (
        <div>
          <p>User EOA: {userSession.eoa}</p>
          <p>User Chain ID: {userSession.chainId}</p>
          <p>User Balance: {accountBalance.data?.formatted ?? 'loading'} ETH</p>
          <button
            onClick={() => {
              logout()
            }}
          >
            Log Out
          </button>
        </div>
      )}
    </div>
  )
}

export default Home

Accessing Futureverse Constants

The Futureverse-specific constants are available as:

const { CONSTANTS } = useFutureverse()

These constants will be matching the stage you defined when configuring FutureverseProvider (either development or production).

There are four categories of constants:

CONTRACTS - all relevant Futureverse contract addresses
CHAINS - Ethereum Mainnet, Ethereum Goerli Testnet, The Root Network Mainnet and The Root Network Porcini Testnet
ENDPOINTS - all relevant Futureverse endpoint (e.g. the Asset Indexer)
MISC - miscellaneous.

For example, you could use the CHAINS constant to get the chain ID of The Root Network and fetch the balance of XRP using Wagmi, like so:

import { useFutureverse } from '@futureverse/react'
import { useAccount, useBalance } from 'wagmi'

function Home() {
  const { CONSTANTS } = useFutureverse()

  const xrpBalanceOnTrn = useBalance({
    address: account.address,
    chainId: CONSTANTS.CHAINS.TRN.id,
  })

  return (
    <div>
      <p>User Balance: {xrpBalanceOnTrn.data?.formatted ?? 'loading'} ETH</p>
    </div>
  )
}

export default Home

Wagmi Signer caveat

The wagmi useSinger returns null after refreshing the page. To access the provider and signer, use the following hook:

export function useConfigSigner() {
  const { data: signer } = useSigner()
  const provider = useProvider()
  const { isDisconnected } = useAccount()
  const { userSession, loginModal } = useFutureverse()
  const { disconnect } = useDisconnect()

  /**
   * This helps avoid the situation where the wagmi wallet can be connected, but
   * FuturePass is not.
   */
  useEffect(() => {
    if (!isDisconnected && !loginModal && !userSession) disconnect()
  }, [isDisconnected, userSession, loginModal, disconnect])

  useEffect(() => {
    // provider and signer are available here
  }, [provider, signer])
}

Xaman Wallet integration

Starting from version 1.0.0 Xaman Wallet is one of the authentication options available to all experiences. The authentication is handled automatically by this SDK. See below for signing and sending transactions.

Asset management

An integral part of any experience is being able to fetch assets that a user owns and allowing them to interact with them within an experience.

Users may fetch assets and token balances by utilising available hooks within the @futureverse/react library or manually through the FV graph. All react hooks have been built using an apollo query interface and allow for caching, custom configuration and more.

We recommend using useTrnApi hook and following the types and JSDocs for signing and sending transactions. The SDK automatically recognises the authentication type and handles the wallet connection and blockchain interaction.

Fetching

Use hooks within @futureverse/react library
Alternatively, use the FV graph directly

Display balance

Use hooks with @futureverse/react to retrieve token balances and display them how you like
Alternatively, use the FV graph directly

Bridging

Wagmi/Web3 JS
TRN /polkadot client
Use useTrnApi hook and its methods

Sending - coming soon

Wagmi/Web3 JS
TRN /polkadot client
Use useTrnApi hook and its methods

@futureverse/react

@futureverse/react

Introduction

Authentication

Getting Started

Installation

Peer Dependencies

Caveats

Create React App

Next.js

App Router

Server-side Frameworks (SSR)

Register your experience

`FutureverseProvider` configuration

`FutureverseAuthClient` configuration

Auth client user state listeners

Example

Authentication flow

Mounting a callback handler

Silent authentication

Example

Logging in and logging out

Accessing the user session

ID Token

Web3 Integration

Accessing Futureverse Constants

Wagmi Signer caveat

Xaman Wallet integration

Asset management

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@futureverse/react

@futureverse/react

Introduction

Authentication

Getting Started

Installation

Peer Dependencies

Caveats

Create React App

Next.js

App Router

Server-side Frameworks (SSR)

Register your experience

FutureverseProvider configuration

FutureverseAuthClient configuration

Auth client user state listeners

Example

Authentication flow

Mounting a callback handler

Silent authentication

Example

Logging in and logging out

Accessing the user session

ID Token

Web3 Integration

Accessing Futureverse Constants

Wagmi Signer caveat

Xaman Wallet integration

Asset management

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`FutureverseProvider` configuration

`FutureverseAuthClient` configuration

Weekly Downloads