# API Reference

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

## Constructor

```typescript
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`                  | <p>Type of user identifier: <code>'uuid'</code> or <code>'hex'</code> (for blockchain addresses)</p><p><br></p> |

## Methods

Validates zero-knowledge proofs from the Self mobile app.

```typescript
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, 4 = KYC) |
| 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:

```typescript
{
  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:

```typescript
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

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

### VcAndDiscloseProof

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

### AttestationId

Document type identifiers:

* `1` - Electronic passport
* `2` - Biometric ID card
* `3` - Aadhaar
* `4` - KYC (exported in `@selfxyz/core` as `KYC_ATTESTATION_ID`)