SelfBackendVerifier - API Reference

A backend verification class that validates zero-knowledge proofs generated by the Self mobile app.

Constructor

new SelfBackendVerifier(
  scope: string,
  endpoint: string,
  mockPassport: boolean = false,
  allowedIds: Map<AttestationId, boolean>,
  configStorage: IConfigStorage,
  userIdentifierType: UserIdType
)

Parameters

Parameter	Type	Description
scope	string	Your application's unique identifier. Must match the scope used in SelfAppBuilder. Max 30 characters.
endpoint	string	Your backend verification endpoint URL. Must be publicly accessible and match your frontend configuration.
mockPassport	boolean	false for real documents (mainnet), true for testing with mock documents (testnet). Default: false
allowedIds	Map<AttestationId, boolean>	Map of allowed document types. Key: attestation ID, Value: allowed status
configStorage	IConfigStorage	Configuration storage implementation that determines verification requirements.
userIdentifierType	UserIdType	Type of user identifier: 'uuid' or 'hex' (for blockchain addresses)

Methods

Validates zero-knowledge proofs from the Self mobile app.

async verify(
  attestationId: AttestationId,
  proof: VcAndDiscloseProof,
  pubSignals: BigNumberish[],
  userContextData: string
): Promise<VerificationResult>

Parameters

Parameter	Type	Description
attestationId	AttestationId	Document type identifier (1 = electronic passport, 2 = EU ID card, 3 = Aadhaar)
proof	VcAndDiscloseProof	Zero-knowledge proof object containing cryptographic proof arrays.
pubSignals	BigNumberish[]	Public signals from the zero-knowledge proof
userContextData	string	Hex-encoded string containing user context and configuration data

Return Value

The method returns a VerificationResult object with comprehensive verification details:

{
  attestationId: AttestationId;           // Document type that was verified
  isValidDetails: {
    isValid: boolean;                     // Overall cryptographic proof validity
    isMinimumAgeValid: boolean;           // Age requirement validation, false if minimum age check does not pass
    isOfacValid: boolean;                 // OFAC sanctions check result, true if in OFAC
  };
  forbiddenCountriesList: string[];       // Countries excluded from the proof
  discloseOutput: {                       // Disclosed document information
    nullifier: string;                    // Unique proof identifier (prevents reuse)
    forbiddenCountriesListPacked: string[];
    issuingState: string;                 // Country that issued the document
    name: string;                         // Full name (if disclosed)
    idNumber: string;                     // Document number
    nationality: string;                  // Nationality
    dateOfBirth: string;                  // Date of birth (if disclosed)
    gender: string;                       // Gender
    expiryDate: string;                   // Document expiry date
    olderThan: string;                    // Age verification result
    ofac: boolean[];                      // OFAC check results [passportNo, nameAndDob, nameAndYob]
  };
  userData: {
    userIdentifier: string;               // User identifier from context
    userDefinedData: string;              // Custom user data
  };
}

The method throws ConfigMismatchError when verification requirements don't match:

try {
  const result = await verifier.verify(attestationId, proof, pubSignals, userContextData);
  // Handle successful verification
} catch (error: any) {
  if (error.name === 'ConfigMismatchError') {
    console.error('Configuration mismatches:', error.issues);
    // error.issues contains detailed information about what failed
  } else {
    console.error('Verification error:', error);
  }
}

Common ConfigMismatch Types:

• InvalidId - Attestation ID not in allowedIds

• InvalidScope - Proof was generated for a different application

• InvalidRoot - Merkle root not found on blockchain

• InvalidForbiddenCountriesList - Countries don't match configuration

• InvalidMinimumAge - Age requirement mismatch

• InvalidTimestamp - Proof timestamp out of valid range (±1 day)

• ConfigNotFound - Configuration not found in storage

Types

VerificationConfig

{
  minimumAge?: number;                  // Minimum age requirement
  excludedCountries?: Country3LetterCode[];  // ISO 3-letter country codes to exclude
  ofac?: boolean;                       // Enable OFAC sanctions checking
}

VcAndDiscloseProof

{
  a: [BigNumberish, BigNumberish];
  b: [[BigNumberish, BigNumberish], [BigNumberish, BigNumberish]];
  c: [BigNumberish, BigNumberish];
}

AttestationId

Document type identifiers:

• 1 - Electronic passport

• 2 - Biometric ID card

• 3 - Aadhaar