🛡️ VeriChain Node.js SDK v2.4.1

🔐 Authentication Required

As of v2.4.0, all API endpoints require authentication with an API key.

Get your API key:

• Demo/Dev: vchain_demo_key_12345
• Production: Generate in VeriChain Dashboard → Settings → API Keys

What's New in v2.4.1:

• ✅ Added warnings when API key is not provided
• ✅ Updated all examples with authentication
• ✅ Improved documentation for production use

Legal-grade accountability system for AI decisions with real-time bias prevention, legal explainability, and automated compliance auditing.

🚀 Features

Core Features

• ✅ Decision Recording - Cryptographically signed audit trails
• ✅ Blockchain Anchoring - Immutable proof on Polygon
• ✅ Certificate Generation - Legal-grade PDF certificates

Advanced Features (NEW!)

• ⚖️ ATHENA - Legal Explainability (GDPR Art. 22 compliant)
• 📊 HELIOS - Auto Audit Package (GDPR, EU AI Act, SOC 2, ISO 27001)
• ⚡ ARES - Real-time Bias Interception (<1ms analysis)

📦 Installation

npm install verichain

🎯 Quick Start

Basic Decision Recording

import { VeriChainClient } from 'verichain';

const client = new VeriChainClient('http://localhost:8000');

// Submit a decision
const result = await client.submitDecision({
  decision_id: 'LOAN_001',
  outcome: 'approved',
  input_data: { credit_score: 750, age: 35 },
  explanation: 'Good credit history'
});

console.log('Decision certified:', result.certificate_id);

ARES - Real-time Bias Check

import { AresClient } from 'verichain';

// ⚠️ API key REQUIRED for production
const ares = new AresClient(
  'http://localhost:8000',
  'vchain_your_key_here'  // Get from dashboard
);

// Check for bias BEFORE making decision
const result = await ares.analyze({
  name: 'Maria Garcia',
  age: 23,
  gender: 'female',
  race: 'hispanic',
  credit_score: 780
});

console.log(`Bias score: ${(result.analysis.bias_score * 100).toFixed(1)}%`);
console.log(`Action: ${result.analysis.action}`);  // allow, warn, block
console.log(`Analysis time: ${result.analysis.analysis_time_ms.toFixed(2)}ms`);

ATHENA - Legal Explanation

import { AthenaClient } from 'verichain';

// ⚠️ API key REQUIRED for production
const athena = new AthenaClient(
  'http://localhost:8000',
  'vchain_your_key_here'  // Get from dashboard
);

// Generate citizen-level explanation
const explanation = await athena.explain(
  'LOAN_001',
  'citizen',  // or 'regulator', 'legal'
  'json'
);

// Download PDF
const pdf = await athena.explainPdf(
  'LOAN_001',
  'citizen',
  'explanation.pdf'
);

HELIOS - Compliance Audit

import { HeliosClient } from 'verichain';

// ⚠️ API key REQUIRED for production
const helios = new HeliosClient(
  'http://localhost:8000',
  'vchain_your_key_here'  // Get from dashboard
);

// Generate GDPR report
const report = await helios.generateReport('org_123', 'gdpr');

// Generate full audit package (all 4 standards)
const auditPackage = await helios.generatePackage('org_123');

console.log('Package ID:', auditPackage.package_id);
console.log('Reports:', Object.keys(auditPackage.reports));

📚 Complete Workflow Example

import { VeriChainClient, AresClient, AthenaClient, HeliosClient } from 'verichain';

// ⚠️ IMPORTANT: Use API key for production
const API_KEY = 'vchain_your_key_here';  // Get from dashboard

// Initialize clients with API key
const verichain = new VeriChainClient('http://localhost:8000', API_KEY);
const ares = new AresClient('http://localhost:8000', API_KEY);
const athena = new AthenaClient('http://localhost:8000', API_KEY);
const helios = new HeliosClient('http://localhost:8000', API_KEY);

// 1. Check for bias BEFORE decision
const decisionData = {
  name: 'John Doe',
  age: 35,
  credit_score: 750
};

const simulation = await ares.simulate(decisionData);
if (simulation.simulation.would_be_blocked) {
  console.log('❌ Decision would be blocked - too much bias!');
  process.exit(1);
}

// 2. Submit decision
const result = await verichain.submitDecision({
  decision_id: 'LOAN_001',
  outcome: 'approved',
  input_data: decisionData
});

// 3. Generate legal explanation
const explanation = await athena.explain(result.decision_id, 'citizen');

// 4. Generate compliance audit
const audit = await helios.generatePackage('org_123');

console.log('✅ Complete workflow finished!');

🔧 API Reference

VeriChainClient

Core client for decision recording and verification.

const client = new VeriChainClient(apiUrl);

// Submit decision
await client.submitDecision(decision);

// Verify decision
await client.verifyDecision(decisionId);

// Get statistics
await client.getStats();

AresClient

Real-time bias interception (<1ms).

const client = new VeriChainClient(apiUrl)

• apiUrl (string, optional): Base URL of VeriChain API. Default: http://localhost:8000

Methods

submitDecision(decision)

Submit a decision to VeriChain.

Parameters:

• decision (Object): Decision data

Returns: Promise with decision_id

verifyDecision(decisionId)

Verify a decision.

Parameters:

• decisionId (string): Decision ID

Returns: Promise with verification result

getLedgerStats()

Get ledger statistics.

Returns: Promise with ledger stats

getStats()

Get system statistics.

Returns: Promise with system stats

getAnchors()

Get list of anchors.

Returns: Promise of anchors

hashData(data)

Hash data using SHA-256.

Parameters:

• data (any): Data to hash

Returns: string (hex-encoded hash)

health()

Check API health.

Returns: Promise with health status

Examples

Complete Example

import VeriChainClient from 'verichain';

async function main() {
  const client = new VeriChainClient();

  // Check health
  const health = await client.health();
  console.log('API Status:', health.status);

  // Submit decision
  const decision = {
    issuer: 'bank001',
    model_id: 'loan_approval',
    model_version: 'v1.0',
    input: {
      customer_id: 'C12345',
      loan_amount: 100000,
      annual_income: 75000
    },
    outcome: 'approved',
    risk_score: 35
  };

  const result = await client.submitDecision(decision);
  console.log('✅ Decision recorded:', result.decision_id);

  // Verify immediately
  const verification = await client.verifyDecision(result.decision_id);
  console.log('✅ Verification:', verification.valid ? 'VALID' : 'INVALID');

  // Get stats
  const stats = await client.getStats();
  console.log('📊 Stats:', stats);
}

main().catch(console.error);

Error Handling

try {
  const result = await client.submitDecision(decision);
  console.log('Success:', result);
} catch (error) {
  console.error('Error:', error.message);
}

License

MIT

Support

For issues and questions, please visit: https://github.com/verichain/verichain