@civic/solana-gateway-react v1.0.2

Gateway React Component

• Getting started
• API Documentation
• Contributing

Overview

This purpose of this library is to provide an easy way to request a Gateway Token from a decentralised Application (dApp).

Getting started

1. Install the component

npm i @civic/solana-gateway-react

or

yarn add @civic/solana-gateway-react

2. Include the gateway context

Surround any code that needs access to the gateway token with:

import { GatewayProvider } from "@civic/solana-gateway-react";

<GatewayProvider
  wallet={wallet}
  gatekeeperNetwork={gatekeeperNetwork}>
</GatewayProvider>

where:

• wallet contains publicKey and signTransaction (see below)
• gatekeeperNetwork is a Solana PublicKey provided by the dApp, orderbook or market instance on-chain.

3. Accessing or requesting the gateway token

The component will automatically look for a gateway token on chain. To access it once created:

import { useGateway } from "@civic/solana-gateway-react";

const { gatewayToken } = useGateway()

If the wallet does not have a gateway token, request it using requestGatewayToken:

const { requestGatewayToken } = useGateway()

For example, by connecting it to a button component:

<button onclick={requestGatewayToken}>Validate your wallet</button> 

Advanced Usage

The example below shows an example GatewayStatus component that will update, and show the token address, once present.

import React from 'react';
import logo from './logo.png';
import {GatewayProvider, useGateway, GatewayStatus} from "@civic/solana-gateway-react";

function GatewayStatus() {
  const { wallet } = useWallet(); // provided by your dApp
  const { status, requestGatewayToken, gatewayToken } = useGateway();

  return (
    <div>
      <h3>Request Status: { GatewayStatus[status] }</h3>
      { gatewayToken && <h4>GatewayToken: {gatewayToken.publicKey.toBase58()}</h4>}
      <button onClick={requestGatewayToken}>Request Gateway Token</button>
    </div>
  );
}

// use it in your app
function MyGatewayAwareUI() {
  const { wallet } = useWallet(); // provided by your dApp
  const { market } = useMarket(); // provided by your dApp

  return (
    <GatewayProvider wallet={wallet} gatekeeperNetwork={market.gatekeeperNetwork}>
      <GatewayStatus/>
    </GatewayProvider>
  )
}

API Documentation

GatewayProvider

The GatewayProvider is a React component that gives children access to the GatewayContext through the useGateway function.

This component holds the state for a given gateway token or gateway token request.

export type GatewayProviderProps = {
  wallet: WalletAdapter | undefined | null, // the wallet connected to the dApp, can be null initially pre-user wallet connection
  gatekeeperNetwork: PublicKey | undefined, // the gatekeeper network public key address
  stage?: string, // optionally set Civic gatekeeper stage (testing only), defaults to 'prod'
  clusterUrl?: string // optionally pass a Solana cluster URL, defaults to solana mainnet
  wrapper?: React.FC<WrapperProps>; // a react element that the dApp can wrap the iframe in to allow custom dApp styling
  logo?: string, // optional url of your logo that will be shown, if set, during verification
  statusPollingFrequencyMS?: number // how often the component should poll the gatekeeper for status
}

GatewayStatus

The GatewayStatus is an enum that reveals the state of the requested Gateway Token.

export enum GatewayStatus {
  UNKNOWN,       // the wallet or gatekeeper network is not set
  CHECKING,      // the blockchain is being queried to find an existing gateway token
  NOT_REQUESTED, // then token has not been requested
  COLLECTING_USER_INFORMATION,   // the token request is in progress (the wallet owner is undergoing KYC)
  IN_REVIEW,     // the token has been requested and civic gatekeeper is reviewing the request
  FAILED,        // an error occurred on issuance of the token
  REJECTED,       // the token issuance request was rejected
  REVOKED,        // the token has been revoked
  FROZEN,         // the token has been frozen
  EXPIRED,        // the token expiry has passed - refresh is needed (will happen automatically)
  ACTIVE,         // the token has been issued successfully and is in an active state
  ERROR,          // something went wrong
}

WalletAdapter

The wallet passed to the GatewayProvider must implement the WalletAdapter interface by providing a publicKey (this will be linked with the GatewayToken), and a 'sign' function to prove wallet ownership:

export interface WalletAdapter {
  publicKey: PublicKey;
  signTransaction: (transaction: Transaction) => Promise<Transaction>;
}

useGateway

Any component wrapped by GatewayProvider can access the state and useful functions of the GatewayProvider through this function.

Returns the current context values for the GatewayContext by exposing the following properties.

export type GatewayProps = {
  requestGatewayToken: () => Promise<void>, // starts off gateway token process
  gatewayStatus: GatewayStatus, // normally a value from a React hook state, defaults to GatewayStatus.UNKNOWN
  gatewayToken?: GatewayToken, // the current GatewayToken used in the dApp
  stage?: string, // optionally set Civic gatekeeper stage (testing only), defaults to 'prod'
  clusterUrl?: string, // optionally pass a Solana cluster URL, defaults to solana mainnet
  statusPollingFrequencyMS?: number // how often the component should poll the gatekeeper for status
  complianceSrcUrl?: string // the compliance URL in use - set internally via stage
}

const gatewayProps: GatewayProps = useGateway();

Wrapper

You can customize how the verification flow is displayed by providing a custom wrapper.

...
const customWrapperStyle: CSS.Properties = {
  backgroundColor: 'rgba(0,0,0,1)',
  position: 'fixed',
  zIndex: 999,
  width: '100%',
  height: '100%',
  overflow: 'auto',
  paddingTop: '5%'
}

const customWrapperContentStyle: CSS.Properties = {
  backgroundColor: '#fefefe',
  margin: 'auto',
  width: '90%', 
  position: 'relative',
}

export const CustomWrapper: React.FC = ({ children = null }) => {
  return (
    <div style={customWrapperStyle}>
      <div style={customWrapperContentStyle}>
        <img style={{ maxWidth: '20%' }} src={logo} className="app-logo" alt="logo"/>
        {children}
      </div>
    </div>
  )
}

Contributing

Building the project and running the sample app:

yarn start

Runs the app in the development mode.\ Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.\ You will also see any lint errors in the console.

yarn test

Launches the test runner in the interactive watch mode.\ See the section about running tests for more information.

yarn build

Builds the app for production to the build folder.\ It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.\ Your app is ready to be deployed!