Identity - Sybil Resistance

To be able to distribute free money while ensuring each unique person registers only once, we need to verify the liveness and uniqueness of people.

With the Identity service you can perform three actions:

  • Register and verify a new wallet address is owned by a live and unique person

  • Query the status of a wallet address

  • Delete the anonymized record of a person and unregister his wallet address

Install the javascript/react SDK

yarn install @gooddollar/web3sdk-v2

Register and verify a new wallet address

First, create the SDK: The first argument should be an ethers Web3Provider, since the user will need to sign his Identifier. Second argument is which environment and chain contract set to use.

import { ClaimSDK } from "@gooddollar/web3sdk-v2"

const sdk = new ClaimSDK(web3provider, "production" | "production-celo")

Then, trigger the signing request and get the link to redirect the user to the FaceVerification process and either open the link in a popup or redirect the user.

const firstName = "John"
const callbackUrl = "" // for native mobile this should be a deeplink
const popupMode = false
const chainId = 42220 // or 122 for fuse. 
try {
 const link = await sdk.generateFVLink(firstName,callbackUrl,popupMode, chainId)
 else window.location = link
catch(e) {
  console.log("User didn't sign his identifier")


function generateFVLink(firstName: string, callbackUrl?: string, popupMode = false, chainId?: number)
  • firstName - Display only. Used to greet user on the face verification screen.

  • callbackUrl (optional defaults to current window location) - In case of popupMode is true, then a POST call will be made to the callbackUrl. Otherwise, the user will be redirected to the callbackUrl.

  • popupMode (optional defaults to false)

    • If false, it is assumed user was redirected to the FaceVerification process and he will be redirected back to the callbackUrl with result params encoded in query string.

    • False should be used for mobile together with a deeplink callback.

    • If true it is assumed a popup window/tab was opened with the FaceVerification link. Once user finishes FV it will try to close the popup and make a POST call to the callback url with JSON encoded params in body.

  • chainId (optional) - Addresses will always be registered on all active chains. This simply marks on which chain the user was originally from. It can be used for invite campaigns and to prevent claiming invite rewards on multiple chains.

Callback Params

The callbackUrl will be called with two params containing the result of the FV process.

  • isVerified - true if user passed FV, false otherwise

  • reason - If isVerified is false this can contain an error message.

Query the status of a wallet address

Use the isAddressVerified method to query the status of a wallet directly from the Identity smart contract.

const isVerified = await sdk.isAddressVerified("0x66582D24FEaD72555adaC681Cc621caCbB208324")

Delete an identity record and unregister a wallet

Since no connection is kept between the identity record and a user's wallet in our database, to delete an identity the user has to send to our server his unique identifier (generated by signing a message). The backend will then unregister the wallet from the Identity contracts on all active chains. info

The user identity record will be deleted after 24 hours to prevent fraud. After 24 hours the user will also be able to register again.

const { success, error } = await sdk.deleteFVRecord()

React hooks

You can also use our react hooks to manage identity.

See the Claim/Identity react hooks code here. Storybook examples here. You will need to first setup our context provider as explained here.

Need a hand?

Fill out this form to request support:

Last updated