SDK Reference

TypeScript Types

Every type the SDK exports, in one place. All five SDK functions consume and return types from this list. Importing these directly gives you full autocomplete and end-to-end type safety.

Exported types

@africazk/identity types

// ────────────────────────────────────────────────────────────
// @africazk/identity — public types
// ────────────────────────────────────────────────────────────

export type IdType = 'NIN' | 'BVN'

export type Network = 'devnet' | 'mainnet-beta'

export type VerifyOptions = {
  idType: IdType
  idNumber: string         // 11-digit NIN or BVN
  dob: string              // YYYY-MM-DD
  backendUrl?: string      // override the default Althea backend
}

export type SignedCredential = {
  idHash: string           // Poseidon(idNumber)
  age: number              // derived from dob
  idType: 1 | 2            // 1 = NIN, 2 = BVN
  signature: {
    R8: [string, string]
    S: string
  }
  Ax: string               // Althea public key x
  Ay: string               // Althea public key y
}

export type ZKProof = {
  proof: {
    pi_a: [string, string, string]
    pi_b: [[string, string], [string, string], [string, string]]
    pi_c: [string, string, string]
    protocol: 'groth16'
    curve: 'bn128'
  }
  publicSignals: [string, string]
  // publicSignals[0] = valid (1 | 0)
  // publicSignals[1] = nullifier
}

export type SubmitResult = {
  txSignature: string
  nullifier: string
  attestationPDA: string
  nullifierPDA: string
  slot: number
}

export type AttestationStatus =
  | { verified: false }
  | {
      verified: true
      verifiedAt: number              // unix ms
      protocol: 'Althea-v1'
      attestationPDA: string
    }

// Errors thrown by the SDK
export class AfricaZKError extends Error {
  readonly code:
    | 'INVALID_INPUT'
    | 'BACKEND_FAILED'
    | 'CIRCUIT_FAILED'
    | 'PROOF_REJECTED'
    | 'DUPLICATE_NULLIFIER'
    | 'USER_REJECTED'
    | 'RPC_FAILED'
}

Importing

Every type above is a named export of @africazk/identity. Use the import type form so the types are erased at build time.

imports.ts

import type {
  VerifyOptions,
  SignedCredential,
  ZKProof,
  SubmitResult,
  AttestationStatus,
  IdType,
  Network,
} from '@africazk/identity'

import { AfricaZKError } from '@africazk/identity'

AttestationStatus is a discriminated union

The verified field narrows the type. Once you check status.verified, TypeScript knows the other fields are present.

narrowing.ts

const status = await checkAttestation(wallet, 'mainnet-beta')

if (status.verified) {
  // TS knows: status.verifiedAt, status.protocol, status.attestationPDA exist
  console.log(new Date(status.verifiedAt).toISOString())
}