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
<GatewayProvider
4
wallet={wallet}
5
gatekeeperNetwork={gatekeeperNetwork}>
6
</GatewayProvider>
Copied!
Property
Description
Type
wallet
An object representing the user's wallet. This may be undefined if no wallet has been connected to the dApp yet.
An object with two properties ( see 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

The useGateway hook

The React component exposes states about the process of requesting a gateway token, as well as the token 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.
Statuses 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 Pass request is in progress (the wallet owner is undergoing KYC)
None
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 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.
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.
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
Last modified 10d ago
Copy link