@vauban/glacis-sdk

TypeScript SDK for Glacis Protocol -- post-quantum Proof of Humanity on Starknet.

Installation

npm install @vauban/glacis-sdk

Quick Start

import { GlacisClient } from '@vauban/glacis-sdk';

const glacis = new GlacisClient({ network: 'starknet-sepolia' });

// Check if a wallet is a verified human (free on-chain read)
const isHuman = await glacis.isVerifiedHuman('0x03C31f...');
console.log(isHuman); // true or false

API Reference

GlacisClient

Constructor

const glacis = new GlacisClient({
  network: 'starknet-sepolia',      // or 'starknet-mainnet'
  providerUrl: '...',                // optional: custom RPC endpoint
  contractAddress: '0x...',          // optional: custom verifier address
  attestationTokenAddress: '0x...',  // optional: custom attestation address
});

isVerifiedHuman(wallet: string): Promise<boolean>

Check if a wallet has a valid, non-expired, non-revoked human attestation. Free on-chain read.

const isHuman = await glacis.isVerifiedHuman('0x03C31f...');

getScopedIdentity(wallet: string, appDomain: string): Promise<string>

Get the scoped pseudonym for a wallet in your application domain. Different apps see different pseudonyms for the same user, preventing cross-app tracking.

const pseudonym = await glacis.getScopedIdentity('0x03C31f...', 'my-dapp');

getAttestationExpiry(wallet: string): Promise<Date | null>

Get the attestation expiration date. Returns null if no attestation exists.

const expiry = await glacis.getAttestationExpiry('0x03C31f...');
if (expiry && expiry > new Date()) {
  console.log(`Verified until ${expiry.toISOString()}`);
}

getAttestationInfo(wallet: string): Promise<AttestationInfo>

Get full attestation details in a single call.

const info = await glacis.getAttestationInfo('0x03C31f...');
// { verified: true, expired: false, revoked: false, expiry: Date }

getAttestationDetails(wallet: string): Promise<AttestationDetails | null>

Get attestation details: verification status, mint timestamp, and TTL. Returns null if no attestation exists.

const details = await glacis.getAttestationDetails('0x03C31f...');
if (details) {
  console.log(`Minted: ${new Date(details.timestamp * 1000).toISOString()}`);
  console.log(`TTL: ${details.ttl}s, Verified: ${details.verified}`);
}

canClaimAirdrop(wallet: string): Promise<AirdropEligibility>

Check if a wallet is eligible for a Glacis-gated airdrop. Combines verification, expiry, and revocation checks.

const result = await glacis.canClaimAirdrop('0x03C31f...');
// { eligible: true } or { eligible: false, reason: 'expired' | 'revoked' | 'not_found' | 'not_verified' }

submitProof(account: Account, submission: ProofSubmission): Promise<TransactionResult>

Submit a STARK proof to the GlacisVerifier contract. Requires a starknet.js Account for signing.

import { Account, RpcProvider } from 'starknet';

const provider = new RpcProvider({ nodeUrl: '...' });
const account = new Account(provider, address, privateKey);

const result = await glacis.submitProof(account, {
  proof: [...],        // STARK proof felts
  nullifier: '0x...',  // deterministic nullifier
  pseudonym: '0x...',  // scoped pseudonym
  caKeyHash: '0x...',  // CA key identifier
});
console.log(result.transactionHash);

Network Configuration

The SDK ships with built-in configurations for Sepolia and mainnet:

| Network | Contracts | RPC | |---------|-----------|-----| | starknet-sepolia | Pre-configured | sepolia.rpc.vauban.tech | | starknet-mainnet | Pre-configured | rpc.vauban.tech |

Override any default with constructor options.

Error Handling

import { GlacisError, NetworkError, ContractError, TransactionError } from '@vauban/glacis-sdk';

try {
  await glacis.isVerifiedHuman(wallet);
} catch (err) {
  if (err instanceof NetworkError) {
    // RPC connection failed
  } else if (err instanceof ContractError) {
    // Contract call failed
  } else if (err instanceof TransactionError) {
    // Transaction submission failed
  }
}

License

MIT