AffixIO SDK

Complete TypeScript SDK for AffixIO Zero-Knowledge Proof API. Full-featured with 100 circuits across 10 sectors, merchant payment engine, terminal SDK, and production-ready error handling.

Features

🎯 Core Capabilities

• ✅ 100 Complete Circuits - All zero-knowledge proof circuits across 10 sectors
• ✅ 10 Industry Sectors - Health, Motoring, Travel, Government, Ticketing, Education, Hospitality, Entertainment, Cross-Sector, Platform
• ✅ Merchant Payment Engine - High-level payment processing with offline support
• ✅ Merchant Terminal SDK - Complete terminal management and operations
• ✅ Complete API Client - All public endpoints covered
• ✅ WASM Support - Offline execution with WebAssembly
• ✅ Sandbox Mode - Test without API keys (free, never billed)
• ✅ TypeScript - Full type safety with comprehensive types
• ✅ Error Handling - Production-ready error management
• ✅ Offline Payments - Stateless, offline-capable payment processing
• ✅ Privacy-First - Zero-knowledge proofs for privacy-preserving operations

🔐 Zero-Knowledge Proof Circuits (100 Total)

Platform Core (13 circuits)

1. Simple Yes/No Decision Circuit - Minimal binary decision circuit
2. Yes/No Decision Circuit - Private loan approval automation
3. Eligibility Check Circuit - Privacy-preserving eligibility verification
4. Token Validation Circuit - Stateless access control with time-limited tokens
5. Consent Verification Circuit - GDPR/CCPA compliant consent verification
6. KYC Circuit - Identity verification without data storage
7. Composite Circuit - Multi-factor ZK logic with complex conditions
8. Audit Proof Circuit - Tamper-proof compliance logging
9. Proof Aggregation Circuit - Recursive ZK proofs and batch verification
10. Quantum-Safe Token Circuit - Post-quantum algorithms (Dilithium)
11. Offline Validation Circuit - Air-gapped verification for IoT
12. Mortgage Engine Circuit - Comprehensive mortgage decision engine
13. ZK Voting Circuit - Zero-knowledge voting with device verification

🏥 Health Sector (10 circuits)

Age Verification, Insurance Eligibility, Prescription Auth, Consent Verification, Score Threshold, Vaccination Status, Allergy Check, Blood Type Compatibility, Organ Donor Eligibility, Clinical Trial Eligibility

🚗 Motoring Sector (10 circuits)

License Validity, Insurance Proof, Ownership Verification, Clean Driving Record, Rental Age Check, Inspection Valid, Emissions Compliance, Mileage Verification, Finance Eligibility, Parking Permit

✈️ Travel Sector (10 circuits)

Booking Age, Passport Validity, Visa Eligibility, Insurance Coverage, Frequent Flyer, Vaccination Requirements, Residency Proof, Restriction Check, Hotel Loyalty, Group Eligibility

🏛️ Government Sector (10 circuits)

Voting Eligibility, Tax Bracket, Benefit Entitlement, Security Clearance, Residency Duration, Criminal Record, Military Service, Property Ownership, Professional License, Immigration Status

🎫 Ticketing Sector (10 circuits)

Age Entry, Student Discount, Senior Discount, Presale Access, Season Holder, Resale Auth, Group Booking, VIP Access, Disability Access, Local Resident

🎓 Education Sector (10 circuits)

Enrollment Verification, Academic Eligibility, Age Admission, Financial Aid, Degree Completion, Prerequisites Met, Attendance Threshold, Alumni Status, Research Grant, Library Access

🏨 Hospitality Sector (10 circuits)

Check-in Age, Loyalty Tier, Corporate Rate, Long-stay Resident, Agent Credentials, Group Booking, Wedding Package, Casino Player, Resort Pass, Referral Program

🎮 Entertainment Sector (10 circuits)

Family Plan, Age Restriction, Premium Membership, Geo Content Rights, Account Standing, Tournament Eligibility, Creator Verification, Beta Access, Parental Override, Device License

🔗 Cross-Sector (10 circuits)

Age Range, Credit Score Range, Income Bracket, Address Proof, Employment Status, Relationship Verification, Biometric Match, MFA Verification, Timestamp Proof, Data Consent

🏦 Merchant Payment Engine

High-level payment processing engine that handles all ZKP complexity internally:

• Simple API - just call processPayment()
• Automatic offline storage and sync
• Works online and offline
• Customizable authorization logic
• Custom storage support
• Background auto-sync

💳 Merchant Terminal SDK

Complete SDK for merchant terminal operations:

• Terminal registration and authentication
• Payment transaction processing
• Offline transaction sync
• Settlement operations
• Terminal status and configuration management

Installation

npm install @affixio/sdk

Quick Start

Sandbox Mode (No API Key Required)

import { AffixIO } from '@affixio/sdk';

const sdk = new AffixIO({
  sandbox: true // No API key needed!
});

// Execute Yes/No circuit
const result = await sdk.circuits.yesNo({
  userId: 'user123',
  rules: ['creditScore >= 650'],
  data: { creditScore: 720 }
}, true); // Use sandbox

console.log(result.decision); // true
console.log(result.verified); // true
console.log(result.proof); // Cryptographic proof

Authenticated Mode

import { AffixIO } from '@affixio/sdk';

const sdk = new AffixIO({
  apiKey: 'affix_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  orgId: 'org_xxxxxxxxxxxxxx',
  baseURL: 'https://api.affix-io.com'
});

// Platform circuits
const result = await sdk.circuits.eligibility({
  userId: 'user123',
  rules: ['purchaseAmount >= 100'],
  data: { purchaseAmount: 150 },
  consentHash: '0x...'
});

// Health sector - Age verification
const healthResult = await sdk.circuits.healthAgeVerification({
  userId: 'user123',
  value: 25,
  threshold: 18,
  metadata: { purpose: 'medical_consent' }
});

// Motoring sector - License validity
const motorResult = await sdk.circuits.motorLicenseValidity({
  userId: 'user456',
  value: 1,
  threshold: 1,
  metadata: { licenseNumber: 'DL12345' }
});

// Travel sector - Passport validity
const travelResult = await sdk.circuits.travelPassportValidity({
  userId: 'user789',
  value: 1,
  threshold: 1,
  metadata: { passportNumber: 'P12345678' }
});

console.log(result.decision);

Merchant Payment Engine

import { MerchantPaymentEngine } from '@affixio/sdk';

const engine = new MerchantPaymentEngine({
  terminalId: 'TERM-001',
  terminalSecret: 'term_...',
  apiKey: 'affix_...'
});

await engine.initialize();

const result = await engine.processPayment({
  amount: 25.99,
  customerId: 'customer-123',
  paymentMethod: 'nfc'
});

if (result.success) {
  console.log(`Payment processed: ${result.transactionId}`);
}

All Available Circuits

1. Simple Yes/No Decision Circuit

Minimal circuit for binary yes/no decisions with a single condition.

await sdk.circuits.simpleYesNo({
  userId: 'user123',
  rules: ['creditScore >= 650'],
  data: { creditScore: 720 }
}, true);

2. Yes/No Decision Circuit

Private loan approval automation and confidential logic processing.

await sdk.circuits.yesNo({
  userId: 'user123',
  rules: ['creditScore >= 650', 'debtRatio <= 0.4'],
  data: { creditScore: 720, debtRatio: 0.35 }
}, true);

3. Eligibility Check Circuit

ZK whitelist check and privacy-preserving eligibility verification.

await sdk.circuits.eligibility({
  userId: 'user123',
  rules: ['purchaseAmount >= 100'],
  data: { purchaseAmount: 150 },
  consentHash: '0x...'
}, true);

4. Token Validation Circuit

Stateless access control with cryptographically signed, time-limited tokens.

await sdk.circuits.tokenValidation({
  tokenSignature: '0x...',
  decision: 1,
  tokenExpiry: Math.floor(Date.now() / 1000) + 3600,
  currentTime: Math.floor(Date.now() / 1000)
}, true);

5. Consent Verification Circuit

GDPR and CCPA compliant consent verification using zero-knowledge proofs.

await sdk.circuits.consentVerification({
  userId: 'user123',
  consentHash: '0x...',
  consentPurpose: 'analytics',
  expiryTime: Math.floor(Date.now() / 1000) + 31536000,
  currentTime: Math.floor(Date.now() / 1000)
}, true);

6. KYC Circuit

Identity verification without data storage.

await sdk.circuits.kyc({
  userId: 'user123',
  rules: ['age >= 18', 'hasDocument == true'],
  data: { age: 25, hasDocument: true }
}, true);

7. Composite Circuit

Multi-factor ZK logic and complex condition verification.

await sdk.circuits.composite({
  userId: 'user123',
  rules: ['condition1', 'condition2'],
  data: { value1: 100, value2: 200 },
  logicOperator: 'AND',
  sourceResults: [1, 1]
}, true);

8. Audit Proof Circuit

Tamper-proof compliance logging with cryptographic audit trails.

await sdk.circuits.auditProof({
  decisionValue: 1,
  pseudonymisedId: '0x...',
  rulesHash: '0x...',
  timestamp: new Date().toISOString()
}, true);

9. Proof Aggregation Circuit

Recursive ZK proofs and batch verification.

await sdk.circuits.proofAggregation({
  proof1Hash: '0x...',
  proof2Hash: '0x...',
  proof3Hash: '0x...',
  source1Result: 1,
  source2Result: 1,
  source3Result: 1
}, true);

10. Quantum-Safe Token Circuit

Post-quantum algorithms for future-proof API security.

await sdk.circuits.quantumSafeToken({
  dilithiumSignature: '0x...',
  tokenExpiry: Math.floor(Date.now() / 1000) + 3600,
  decision: 1,
  currentTime: Math.floor(Date.now() / 1000)
}, true);

11. Offline Validation Circuit

Air-gapped verification and IoT security offline.

await sdk.circuits.offlineValidation({
  userId: 'user123',
  eligibilityData: 1,
  precomputedProof: '0x...',
  timestamp: new Date().toISOString()
}, true);

12. Mortgage Engine Circuit

Comprehensive mortgage decision engine with credit scoring, DTI, LTV, income verification, property valuation, and risk assessment. Banks use this for instant, privacy-preserving mortgage decisions.

await sdk.circuits.mortgageEngine({
  credit_score: 720,
  credit_history_months: 60,
  credit_utilization: 25,
  recent_inquiries: 2,
  annual_income: 100000,
  employment_months: 36,
  employment_stability: 85,
  monthly_debt_payments: 1500,
  property_value: 500000,
  down_payment: 100000,
  loan_amount: 400000,
  loan_term_months: 360,
  interest_rate: 3.5,
  bankruptcy_flag: 0,
  foreclosure_flag: 0,
  late_payments_12m: 0
}, true);

13. ZK Voting Circuit

Zero-knowledge voting for polls with physical device (OEM) support. Voters can prove they voted without revealing their choice. Supports device verification, eligibility checks, and time validation.

await sdk.circuits.zkVoting({
  voterId: 'voter123',
  pollId: 'poll456',
  voteChoice: 1,
  deviceSignature: '0x...',
  pollStartTime: Math.floor(Date.now() / 1000),
  pollEndTime: Math.floor(Date.now() / 1000) + 86400,
  currentTime: Math.floor(Date.now() / 1000)
}, true);

API Client Methods

Authentication

await sdk.client.register({ orgName: 'My Org', sector: 'finance' });
await sdk.client.login({ email: '[email protected]', password: '...' });
await sdk.client.registerUser({ orgName: 'My Org', email: '[email protected]', password: '...', name: 'John Doe' });
await sdk.client.forgotPassword('[email protected]');
await sdk.client.resetPassword(token, password);
await sdk.client.enable2FA(password);
await sdk.client.verify2FA(code);

Organization

await sdk.client.getOrganization();
await sdk.client.updateOrganization({ name: 'New Name' });

API Keys

await sdk.client.getAPIKeys();
await sdk.client.generateAPIKey({ name: 'My Key' });
await sdk.client.generateSandboxAPIKey(); // Free, never billed
await sdk.client.revokeAPIKey('key-id');

Data Sources

await sdk.client.registerDataSource({
  name: 'My Data Source',
  type: 'api',
  endpoint: 'https://api.example.com',
  authentication: { type: 'bearer', token: '...' }
});
await sdk.client.getDataSources();

Proofs

await sdk.client.generateProof({ userId: 'user123', rules: ['...'] });
await sdk.client.verifyProof({ proof: '0x...', publicInputs: {...} });

Tokens

await sdk.client.generateToken({
  decision: true,
  expiration: 3600,
  format: 'jwt'
});
await sdk.client.validateToken({ token: '...' });

Eligibility

await sdk.client.checkEligibility({
  userId: 'user123',
  rules: ['...'],
  data: {...}
});

Health Check

await sdk.client.healthCheck();
// or
await sdk.healthCheck();

Merchant Terminal SDK

Complete SDK for merchant terminal operations with offline ZKP support.

Terminal Registration

const terminal = await sdk.merchant.registerTerminal({
  terminalId: 'TERM-001',
  terminalName: 'Store Terminal 1',
  locationName: 'Main Store',
  terminalType: 'pos'
});

console.log(terminal.terminalSecret); // Save this securely!

Terminal Authentication

const auth = await sdk.merchant.authenticateTerminal({
  terminalId: 'TERM-001',
  terminalSecret: 'term_...'
});

sdk.merchant.setTerminalToken(auth.token);

Process Payment

const transaction = await sdk.merchant.processPayment({
  transactionId: 'txn_123',
  amount: 25.99,
  customerId: 'customer-123',
  currency: 'USD',
  paymentMethod: 'nfc'
});

Sync Transactions

const syncResult = await sdk.merchant.syncTransactions({
  transactions: [
    {
      transactionId: 'txn_123',
      proofData: {...},
      amount: 25.99,
      customerId: 'customer-123'
    }
  ]
});

Settlement

const settlement = await sdk.merchant.createSettlement({
  settlementDate: new Date().toISOString(),
  terminalId: 'TERM-001'
});

WASM Support

All circuits support WebAssembly (WASM) execution for:

• Fast Performance - Native-speed execution
• Offline Capability - Run circuits without network connection
• Browser Support - Works in modern browsers
• Node.js Support - Full Node.js compatibility
• Secure Sandboxing - Isolated execution environment

await sdk.circuits.yesNo({
  userId: 'user123',
  rules: ['creditScore >= 650'],
  data: { creditScore: 720 },
  wasmBasePath: './circuits' // Optional: custom WASM path
}, true);

Error Handling

Comprehensive error handling with typed error classes:

import { SDKError, APIError, CircuitExecutionError } from '@affixio/sdk';

try {
  const result = await sdk.circuits.yesNo({...});
} catch (error) {
  if (error instanceof CircuitExecutionError) {
    console.error('Circuit error:', error.message, error.details);
  } else if (error instanceof APIError) {
    console.error('API error:', error.statusCode, error.message);
  } else if (error instanceof SDKError) {
    console.error('SDK error:', error.code, error.message);
  }
}

Error Types

• SDKError - Base error class for all SDK errors
• APIError - HTTP API errors with status codes
• CircuitExecutionError - Circuit execution failures with details

Configuration

const sdk = new AffixIO({
  apiKey: 'affix_...',        // Optional (not needed for sandbox)
  baseURL: 'https://api.affix-io.com',  // Optional
  timeout: 30000,              // Request timeout in ms
  sandbox: true                // Use sandbox endpoints
});

// Update API key after initialization
sdk.setAPIKey('affix_new_key');

Utilities

Helper functions for common operations:

import { 
  generateRandomHex, 
  getCurrentTimestamp, 
  getFutureTimestamp,
  isValidAPIKeyFormat,
  formatCircuitInput,
  retry
} from '@affixio/sdk';

// Generate random hex string
const hash = generateRandomHex(64); // '0x...'

// Timestamps
const now = getCurrentTimestamp(); // Unix timestamp
const future = getFutureTimestamp(3600); // 1 hour from now

// Validate API key format
const isValid = isValidAPIKeyFormat('affix_...');

// Format circuit input
const formatted = formatCircuitInput({ userId: 'user123', rules: [...] });

// Retry with exponential backoff
const result = await retry(
  async () => await sdk.circuits.yesNo({...}),
  { maxRetries: 3, delay: 1000 }
);

Examples

See examples/ directory for complete examples:

• basic-usage.ts - Sandbox examples with all circuits
• authenticated-usage.ts - Authenticated API examples
• merchant-terminal-example.ts - Merchant terminal integration

Use Cases

Banking & Finance

• Mortgage approval decisions
• Loan eligibility verification
• Credit scoring
• KYC/AML compliance
• Risk assessment

Payments & Commerce

• Offline payment processing
• Merchant terminal integration
• Payment authorization
• Fraud prevention
• Transaction verification

Identity & Compliance

• KYC verification
• Identity verification
• Consent management (GDPR/CCPA)
• Audit trails
• Compliance reporting

Access Control

• Stateless access tokens
• Permission verification
• Resource access control
• Session validation

Voting & Governance

• Zero-knowledge voting
• Poll verification
• Device-based verification
• Anonymous participation proofs

Requirements

• Node.js 18+ or modern browser
• TypeScript 5.0+ (optional, but recommended)

License

MIT

Support

• Documentation: https://www.affix-io.com/docs
• Dashboard: https://dashboard.affix-io.com
• API: https://api.affix-io.com
• Email: [email protected]

Contributing

Contributions are welcome! Please see our contributing guidelines.

Built with ❤️ by AffixIO