Quickstart

To implement Self in your app, you need to implement it in both your front-end and back-end. The front-end will generate a QR code containing all the information relative to your app and what you are requesting users to disclose. The back-end will verify proofs and manage nullifiers.

🚧 Deeplinking is WIP. If you want to implement Self in a mobile application, please contact us.

Implement SelfBackendVerifier in your back-end

Requirements

• Node v 16

Install dependencies

npm install @selfxyz/core 

For yarn, use the following command:

yarn add @selfxyz/core 

Set up Environment Variables

Create an .env file or add to your existing file the following environment variables:

CELO_RPC_URL=https://forno.celo.org 
SCOPE=myDappName 

Set Up SelfBackendVerifier

In your api folder or verify.ts file you can start setting up the SelfBackendVerifier in the verify.ts file.

import { SelfBackendVerifier } from '@selfxyz/core';

const selfBackendVerifier = new SelfBackendVerifier(
    process.env.CELO_RPC_URL as string,
    process.env.SCOPE as string,
);

SelfBackendVerifier requires two arguments: mode and scope.

• rpcUrl an RPC URL, use for example Celo's free RPC endpoint https://forno.celo.org

• scope is simply an identifier for your app, choose a simple one in standard ASCII.

Methods - Disclosing passport data

Now you can call methods from the SelfBackendVerifier to ask users to disclose specific passport data.

// Set the methods for the verifier.
selfBackendVerifier.setMinimumAge(21);

Find all methods available here:

Method Name	Description
setMinimumAge(age: number)	Set the minimum age for verification.
setNationality(nationality: string)	Set the nationality for verification.
excludeCountries(...countries: string[])	Set excludes specified countries from verification. At most 40. You can use countryCodes from '@selfxyz/core'
enablePassportNoOfacCheck()	Enables OFAC check for passport numbers. Default false.
enableNameAndDobOfacCheck()	Enables OFAC check for name and date of birth. Default false.
enableNameAndYobOfacCheck()	Enables OFAC check for name and year of birth. Default false.

Working with Country Codes

The SDK provides a countryCodes object for referencing ISO country codes:

import { countryCodes } from '@selfxyz/core';

// Examples of usage
const iranCode = countryCodes.IRN;  // "Iran"
const northKoreaCode = countryCodes.PRK;  // "North Korea"

// Use in excludeCountries
selfBackendVerifier.excludeCountries(
  countryCodes.IRN,
  countryCodes.PRK,
  countryCodes.SYR
);

Verification

Now you can do the verification. For that you can all the verify function.

import { SelfVerificationResult } from '@selfxyz/core';

const result: SelfVerificationResult = await selfBackendVerifier.verify(request.body.proof, request.body.publicSignals);

This is the structure of the result SelfVerificationResul:

export interface SelfVerificationResult {
  // Check if the whole verification has succeeded
  isValid: boolean;
  isValidDetails: {
    // Verifies that the proof is generated under the expected scope.
    isValidScope: boolean;
    // Checks that the attestation identifier in the proof matches the expected value.
    isValidAttestationId: boolean;
    // Verifies the cryptographic validity of the proof.
    isValidProof: boolean;
    // Ensures that the revealed nationality is correct (when nationality verification is enabled).
    isValidNationality: boolean;
  };
  // User Identifier which is included in the proof
  userId: string;
  // Application name which is shown as scope
  application: string;
  // A cryptographic value used to prevent double registration or reuse of the same proof.
  nullifier: string;
  // Revealed data by users
  credentialSubject: {
    // Merkle root which is used to generate proof.
    merkle_root?: string;
    // Proved identity type, for passport this value is fixed as 1.
    attestation_id?: string;
    // Date when the proof is generated
    current_date?: string;
    // Revealed issuing state in the passport
    issuing_state?: string;
    // Revealed name in the passport
    name?: string;
    // Revealed passport number in the passport
    passport_number?: string;
    // Revealed nationality in the passport
    nationality?: string;
    // Revealed date of birth in the passport
    date_of_birth?: string;
    // Revealed gender in the passport
    gender?: string;
    // Revealed expiry date in the passport
    expiry_date?: string;
    // Result of older than
    older_than?: string;
    // Result of passport number ofac check
    // Gives true if the user passed the check (is not on the list),
    // false if the check was not requested or if the user is in the list
    passport_no_ofac?: boolean;
    // Result of name and date of birth ofac check
    name_and_dob_ofac?: boolean;
    // Result of name and year of birth ofac check
    name_and_yob_ofac?: boolean;
  };
  proof: {
    // Proof which is used for this verification
    value: {
      proof: Groth16Proof;
      publicSignals: PublicSignals;
    };
  };

This is the format the API returns:

response: {
    200: t.Object({
        status: t.String(),
        result: t.Boolean(),
    }),
    500: t.Object({
        status: t.String(),
        result: t.Boolean(),
        message: t.String(),
    }),
},

Example API implementation

This is how an example API implementation would look like

try {
  const result = await selfBackendVerifier.verify(request.body.proof, request.body.publicSignals);
  return {
    status: 'success',
    result: result.isValid,
  };
} catch (error) {
  return {
    status: 'error',
    result: false,
    message: error instanceof Error ? error.message : 'Unknown error',
  };
}

Your whole verify.ts file should look like this now

import { NextApiRequest, NextApiResponse } from 'next';
import { getUserIdentifier, SelfBackendVerifier, countryCodes } from '@selfxyz/core';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    try {
      const { proof, publicSignals } = req.body;

      if (!proof || !publicSignals) {
        return res.status(400).json({ message: 'Proof and publicSignals are required' });
      }

      // Extract user ID from the proof
      const userId = await getUserIdentifier(publicSignals);
      console.log("Extracted userId:", userId);

      // Initialize and configure the verifier
      const selfBackendVerifier = new SelfBackendVerifier(
        'https://forno.celo.org',
        'my-application-scope'
      );
      
      // Configure verification options
      selfBackendVerifier.setMinimumAge(18);
      selfBackendVerifier.excludeCountries(
        countryCodes.IRN,   // Iran
        countryCodes.PRK    // North Korea
      );
      selfBackendVerifier.enableNameAndDobOfacCheck();

      // Verify the proof
      const result = await selfBackendVerifier.verify(proof, publicSignals);
      
      if (result.isValid) {
        // Return successful verification response
        return res.status(200).json({
          status: 'success',
          result: true,
          credentialSubject: result.credentialSubject
        });
      } else {
        // Return failed verification response
        return res.status(400).json({
          status: 'error',
          result: false,
          message: 'Verification failed',
          details: result.isValidDetails
        });
      }
    } catch (error) {
      console.error('Error verifying proof:', error);
      return res.status(500).json({
        status: 'error',
        result: false,
        message: error instanceof Error ? error.message : 'Unknown error'
      });
    }
  } else {
    return res.status(405).json({ message: 'Method not allowed' });
  }
}

Implement QRCodeGenerator into your front-end

QRCodeGenerator is a React component for generating QR codes for Self passport verification.

Installation

npm install @selfxyz/qrcode

For yarn, use the following command:

yarn add @selfxyz/qrcode

Basic Usage

1. Import the SelfQRcodeWrapper component

import SelfQRcodeWrapper, { SelfAppBuilder } from '@selfxyz/qrcode';
import { v4 as uuidv4 } from 'uuid';

2. Create a SelfApp instance using SelfAppBuilder

// Generate a unique user ID
const userId = uuidv4();

// Create a SelfApp instance using the builder pattern
const selfApp = new SelfAppBuilder({
  appName: "My App",
  scope: "my-app-scope", 
  endpoint: "https://myapp.com/api/verify",
  logoBase64: "base64EncodedLogo", // Optional
  userId,
  // Optional disclosure requirements
  disclosures: {
    // DG1 disclosures
    issuing_state: true,
    name: true,
    nationality: true,
    date_of_birth: true,
    passport_number: true,
    gender: true,
    expiry_date: true,
    // Custom verification rules
    minimumAge: 18,
    excludedCountries: ["IRN", "PRK"],
    ofac: true,
  },
}).build();

3. Render the QR code component

function MyComponent() {
  return (
    <SelfQRcodeWrapper
      selfApp={selfApp}
      onSuccess={() => {
        console.log('Verification successful');
        // Perform actions after successful verification
      }}
      darkMode={false} // Optional: set to true for dark mode
      size={300} // Optional: customize QR code size (default: 300)
    />
  );
}

SelfQRcodeWrapper wraps SelfQRcode to prevent server-side rendering when using nextjs. When not using nextjs, SelfQRcode can be used instead.

SelfApp Configuration

The SelfAppBuilder allows you to configure your application's verification requirements:

Parameter	Type	Required	Description
appName	string	Yes	The name of your application
scope	string	Yes	A unique identifier for your application
endpoint	string	Yes	The endpoint that will verify the proof
logoBase64	string	No	Base64-encoded logo to display in the Self app
userId	string	Yes	Unique identifier for the user
disclosures	object	No	Disclosure and verification requirements

Disclosure Options

The disclosures object can include the following options:

Option	Type	Description
issuing_state	boolean	Request disclosure of passport issuing state
name	boolean	Request disclosure of the user's name
nationality	boolean	Request disclosure of nationality
date_of_birth	boolean	Request disclosure of birth date
passport_number	boolean	Request disclosure of passport number
gender	boolean	Request disclosure of gender
expiry_date	boolean	Request disclosure of passport expiry date
minimumAge	number	Verify the user is at least this age
excludedCountries	string[]	Array of country codes to exclude
ofac	boolean	Enable OFAC compliance check

Component Props

The SelfQRcodeWrapper component accepts the following props:

Prop	Type	Required	Default	Description
selfApp	SelfApp	Yes	-	The SelfApp configuration object
onSuccess	() => void	Yes	-	Callback function executed on successful verification
websocketUrl	string	No	WS_DB_RELAYER	Custom WebSocket URL for verification
size	number	No	300	QR code size in pixels
darkMode	boolean	No	false	Enable dark mode styling
children	React.ReactNode	No	-	Custom children to render

Complete Example

Here's a complete example of how to implement the Self QR code in a React application:

'use client';

import React, { useState, useEffect } from 'react';
import SelfQRcodeWrapper, { SelfAppBuilder } from '@selfxyz/qrcode';
import { v4 as uuidv4 } from 'uuid';

function VerificationPage() {
  const [userId, setUserId] = useState<string | null>(null);

  useEffect(() => {
    // Generate a user ID when the component mounts
    setUserId(uuidv4());
  }, []);

  if (!userId) return null;

  // Create the SelfApp configuration
  const selfApp = new SelfAppBuilder({
    appName: "My Application",
    scope: "my-application-scope",
    endpoint: "https://myapp.com/api/verify",
    userId,
    disclosures: {
      // Request passport information
      name: true,
      nationality: true,
      date_of_birth: true,
      
      // Set verification rules
      minimumAge: 18,
      excludedCountries: ["IRN", "PRK", "RUS"],
      ofac: true,
    },
  }).build();

  return (
    <div className="verification-container">
      <h1>Verify Your Identity</h1>
      <p>Scan this QR code with the Self app to verify your identity</p>
      
      <SelfQRcodeWrapper
        selfApp={selfApp}
        onSuccess={() => {
          // Handle successful verification
          console.log("Verification successful!");
          // Redirect or update UI
        }}
        size={350}
      />
      
      <p className="text-sm text-gray-500">
        User ID: {userId.substring(0, 8)}...
      </p>
    </div>
  );
}

export default VerificationPage;

Example

For a more comprehensive and interactive example, please refer to the playground.

Verification Flow

1. Your application displays the QR code to the user

2. The user scans the QR code with the Self app

3. The Self app guides the user through the passport verification process

4. The proof is generated and sent to your verification endpoint

5. Upon successful verification, the onSuccess callback is triggered

The QR code component displays the current verification status with an LED indicator and changes its appearance based on the verification state.