The Gateway Provider

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.
1
import { GatewayProvider } from "@civic/solana-gateway-react";
2
​
3
const clusterUrl = // Solana RPC endpoint;
4
​
5
<GatewayProvider
6
  wallet={wallet}
7
  gatekeeperNetwork={gatekeeperNetwork}
8
  clusterUrl={clusterUrl}
9
  >
10
</GatewayProvider>
Copied!
Property
Description
Type
wallet
An object representing the user's wallet. This may be undefined if a wallet hasn't been connected to the dApp yet.
{
  publicKey,  signTransaction 
} (see definitions below)
wallet.publicKey
The user wallet's public key
PublicKey from @solana/web3.js
 wallet.signTransaction
A function that asks the user's wallet to sign a transaction.
(transaction: Transaction) => Promise<Transaction>
where Transaction is from @solana/web3.js
gatekeeperNetwork
The public key of the gatekeeper network. This needs to match the network within which the Civic gatekeeper issues tokens. 
PublicKey from @solana/web3.js
clusterUrl
The React Component requires you to pass in a Solana RPC endpoint. 
string
cluster
If the RPC endpoint passed as clusterUrl is not pointing to mainnet-beta, you must specify the cluster. Supported are "devnet" and "testnet". This is so that Civic's servers generate a transaction for the correct cluster.
string
The useGateway hook
The React component exposes the process status of a gateway token request, as well as the token status itself. It also provides a function to request a new gateway token. These can be accessed through the useGateway hook:
1
import { useGateway } from "@civic/solana-gateway-react";
Copied!
Requesting a gateway token
A function is provided to initiate a request for a new gateway token:
1
const { requestGatewayToken } = useGateway()
Copied!
This could be triggered by a button, for example:
1
<button onclick={requestGatewayToken}>Validate your wallet</button> 
Copied!
Calling this function should open an iframe connected to the Civic Gatekeeper, which will guide the user through a flow to verify their identity and other prerequisites:
Reading the gateway state
Besides the refreshGatewayToken function, the useGateway hook also exposes some state variables to indicate the status of the Civic Pass request flows and the state of the token itself.
1
const { gatewayStatus, gatewayToken } = useGateway();
Copied!
Property
Description
Type
gatewayStatus
Indicates the overall status of the Civic Pass. This should ideally displayed to the user. Some states are linked to an on-chain gateway token, while others indicate progress or error conditions during which a gateway token might not exist. 
GatewayStatus from @civic/solana-gateway-react
gatewayToken
Represents the on-chain Solana structure for the gateway token. This will only be defined if the on-chain token is ACTIVE and dApp usage should be allowed.
If the token does not exist or is in a non-active state (e.g. Frozen), this state variable will be undefined . The dApp could disable certain parts of the UI when gatewayToken is undefined to prevent dApp usage.
This complements the on-chain Rust check, but should not replace it.  
GatewayToken from @identity.com/solana-gateway-ts
The Gateway Status
The following is a list of all the possible states of the Civic Pass
Statuses where a Civic Pass exists
Status
Description
Behaviour when triggered
ACTIVE
The Civic Pass is Active. The user can trade.
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
EXPIRED
The Civic Pass has expired An IP check and proof of wallet ownership are required to refresh it.
Proof of wallet ownership is automatically initiated
FROZEN
The Pass has been frozen, for example because the user connected from a blocked IP
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
REVOKED
The Pass has been revoked, for example because the user connected from a banned IP
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
Status where a Civic Pass may not exist yet
Status
Description
Behaviour when triggered
UNKNOWN
No user wallet is connected or no gatekeeper network set
None
CHECKING
Checking whether a Pass exists for the connected wallet.
None
NOT_REQUESTED
The wallet is connected but no Pass has been requested yet. 
Opens the Civic Pass modal dialog and initiates the token request flow
COLLECTING_USER_INFORMATION
The required user information is being collected. Depending on the  Network configured, this ranges from a simple CAPTCHA to full KYC.
Opens the Civic Pass modal dialog and resumes the collection of the required information.
VALIDATING_USER_INFORMATION 
The user's identity information has been collected successfully and is being verified.

This status is only available when KYC is in progress and only when the user has chosen to do KYC via on his browser. I.e. not relevant for the Ignite Pass that is used  with CandyMachine v2.
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
USER_INFORMATION_VALIDATED
The user's identity has been validated.

This status is only available when KYC is in progress and only when the user has chosen to do KYC via on his browser. I.e. not relevant for the Ignite Pass that is used  with CandyMachine v2.
Opens the Civic Pass modal dialog and asks the user to re-authenticate so that the request process can proceed.
USER_INFORMATION_REJECTED
The user's identity verification request has been rejected.

This status is only available when KYC is in progress and only when the user has chosen to do KYC via on his browser. I.e. not relevant for the Ignite Pass that is used with CandyMachine v2.
Opens the Civic Pass modal displaying the reasons for the rejection ( for example blurry document scan).
CONFIRM_WALLET_TRANSACTION
The user needs to confirm wallet ownership on their wallet
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
IN_REVIEW
The Civic Pass has been requested and the Gatekeeper is reviewing the request
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
Status when the user is going through identity verification on his browser
Modal for CONFIRM_WALLET_TRANSACTION status
Error statuses
Status
Description
Behaviour when triggered
LOCATION_NOT_SUPPORTED
The user's location is not currently supported
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
ERROR
There was an unexpected error requesting a Civic Pass.
Opens the Civic Pass modal dialog and the user can restart the process.
REJECTED
The token requests has been rejected by the Gatekeeper
Opens the Civic Pass modal dialog with a user-friendly explanation of the status.
Modal for LOCATION_NOT_SUPPORTED
The Identity Button
Client Sent Transactions
Last modified 6d ago
Copy link
Contents
The useGateway hook