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.
Available for Ethereum and Solana​
Ethereum
Warning: The Ethereum integration is in alpha and is subject to change.
Note: The React component uses ethers.js​
import { GatewayProvider } from "@civic/ethereum-gateway-react";
​
<GatewayProvider
  signer={signer}
  provider={provider}
  gatekeeperNetwork={gatekeeperNetwork}
  >
</GatewayProvider>
Property
Description
Type
signer
An ethers.js object representing the user's wallet.
Signer from ethers
provider
An ethers.js connection to the network. Can be undefined if not yet connected
Provider from ethers
gatekeeperNetwork
The address of the gatekeeper network. This needs to match the network within which the Civic gatekeeper issues tokens.
string (see Selecting a Pass Verification)
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:
import { useGateway } from "@civic/ethereum-gateway-react";
Requesting a gateway token
A function is provided to initiate a request for a new gateway token:
const { requestGatewayToken } = useGateway()
This could be triggered by a button, for example:
<button onclick={requestGatewayToken}>Validate your wallet</button>
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.
const { gatewayStatus, gatewayToken } = useGateway();
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/ethereum-gateway-react
gatewayToken
Represents the on-chain Ethereum 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/gateway-eth-ts
Solana
import { GatewayProvider } from "@civic/solana-gateway-react";
import { Connection, clusterApiUrl } from '@solana/web3.js';
​
<GatewayProvider
  connection={new Connection(clusterApiUrl("mainnet-beta"))}
  cluster="mainnet-beta"
  wallet={wallet}
  gatekeeperNetwork={gatekeeperNetwork}>
</GatewayProvider>
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
connection
A solana connection to any solana network, with a recommended commitment of 'processed'
Connection from @solana/web3.js
cluster
the Solana network to use, i.e. devnet, mainnet-beta, testnet. This defaults to mainnet-beta, so should be set if a different connection endpoint is used than mainnet-beta
string
gatekeeperSendsTransaction
The gatekeeper will send the transaction to the blockchain. Defaults to false. When false, the user will be prompted to sign and send the transaction. This is handled internally by the React Component. To customize this behavior the handleTransaction callback function needs to be provided
string
handleTransaction
An optional callback function that will invoked with a partially signed transaction for the user to sign and send to the blockchain when the property gatekeeperSendsTransaction is false.
(transaction: Transaction) => Promise<void>
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:
import { useGateway } from "@civic/solana-gateway-react";
Requesting a gateway token
A function is provided to initiate a request for a new gateway token:
const { requestGatewayToken } = useGateway()
This could be triggered by a button, for example:
<button onclick={requestGatewayToken}>Validate your wallet</button>
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.
const { gatewayStatus, gatewayToken } = useGateway();
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 their 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 their 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 their 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 their 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 2mo ago

Property	Description	Type
signer	An ethers.js object representing the user's wallet.	`Signer` from `ethers`
provider	An ethers.js connection to the network. Can be undefined if not yet connected	`Provider` from `ethers`
gatekeeperNetwork	The address of the gatekeeper network. This needs to match the network within which the Civic gatekeeper issues tokens.	`string` (see Selecting a Pass Verification)

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/ethereum-gateway-react`
gatewayToken	Represents the on-chain Ethereum 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/gateway-eth-ts`

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`
connection	A solana connection to any solana network, with a recommended commitment of 'processed'	`Connection` from `@solana/web3.js`
cluster	the Solana network to use, i.e. devnet, mainnet-beta, testnet. This defaults to mainnet-beta, so should be set if a different connection endpoint is used than mainnet-beta	`string`
gatekeeperSendsTransaction	The gatekeeper will send the transaction to the blockchain. Defaults to `false`. When `false`, the user will be prompted to sign and send the transaction. This is handled internally by the React Component. To customize this behavior the `handleTransaction` callback function needs to be provided	`string`
handleTransaction	An optional callback function that will invoked with a partially signed transaction for the user to sign and send to the blockchain when the property gatekeeperSendsTransaction is false.	`(transaction: Transaction) => Promise<void>`

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`

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.