@verdikta/common

Shared utilities for Verdikta blockchain integration. This package provides common functionality for interacting with the Verdikta decentralized AI arbitration platform.

Overview

Verdikta is a blockchain platform built on Base/ETH designed for decentralized AI-adjudicated judgements. This package contains the core utilities needed to interact with Verdikta arbiters, parse manifests, and handle IPFS operations.

Installation

npm install @verdikta/common

Quick Start

Simple Usage

const { parseManifest, validateRequest } = require('@verdikta/common');

// Parse a manifest from an extracted archive
const result = await parseManifest('/path/to/extracted/archive');

// Validate a request object
await validateRequest(requestObject);

Advanced Usage with Configuration

const { createClient } = require('@verdikta/common');

const verdikta = createClient({
  ipfs: {
    pinningKey: 'your-pinata-api-key',
    timeout: 45000
  },
  logging: {
    level: 'debug',
    file: true
  }
});

const { manifestParser, archiveService, ipfsClient } = verdikta;

// Use the configured services
const archive = await archiveService.getArchive('QmYourCIDHere');
const manifest = await manifestParser.parse('/path/to/archive');

Individual Class Usage

const { IPFSClient, ManifestParser, Logger } = require('@verdikta/common');

const logger = new Logger({ level: 'info' });
const ipfsClient = new IPFSClient({ 
  pinningKey: 'your-api-key',
  timeout: 30000 
}, logger);
const manifestParser = new ManifestParser(ipfsClient, logger);

API Reference

Factory Function

createClient(config?)

Creates a configured Verdikta client with all services initialized.

Parameters:

• config (optional): Configuration object

Returns: Object with initialized services:

• manifestParser: ManifestParser instance
• archiveService: ArchiveService instance
• ipfsClient: IPFSClient instance
• validator: Validator utilities
• logger: Logger instance
• config: Merged configuration

Core Classes

ManifestParser

Parses Verdikta manifest files and handles multi-CID operations.

Methods:

• parse(extractedPath): Parse a single manifest
• parseMultipleManifests(extractedPaths, cidOrder): Parse multiple manifests
• constructCombinedQuery(primaryManifest, bCIDManifests, addendumString?): Combine manifests into a query

ArchiveService

Handles archive operations and IPFS integration.

Methods:

• getArchive(cid): Fetch archive from IPFS or test fixtures
• extractArchive(archiveData, extractionPath): Extract archive to filesystem

IPFSClient

Provides IPFS connectivity with retry logic and multiple gateways.

Methods:

• fetchFromIPFS(cid): Fetch content from IPFS
• uploadToIPFS(data, filename?): Upload content to IPFS

Logger

Configurable logging with Winston.

Methods:

• info(message, meta?): Log info level
• error(message, meta?): Log error level
• warn(message, meta?): Log warning level
• debug(message, meta?): Log debug level

Validation

validator

Provides Joi-based validation for manifests and requests.

Methods:

• validateManifest(manifest): Validate manifest structure
• validateRequest(request): Validate request object

Configuration

Default Configuration

{
  ipfs: {
    gateway: 'https://ipfs.io',
    pinningService: 'https://api.pinata.cloud',
    pinningKey: process.env.IPFS_PINNING_KEY || '',
    timeout: 30000,
    retryOptions: {
      retries: 5,
      factor: 2,
      minTimeout: 1000,
      maxTimeout: 15000,
      randomize: true
    }
  },
  logging: {
    level: process.env.LOG_LEVEL || 'info',
    console: true,
    file: false
  },
  temp: {
    dir: process.env.TEMP_DIR || './tmp'
  }
}

Environment Variables

• IPFS_PINNING_KEY: Your IPFS pinning service API key
• LOG_LEVEL: Logging level (debug, info, warn, error)
• TEMP_DIR: Temporary directory for file operations

Testing

Credential-Aware Testing System

This package features an intelligent testing system that adapts based on credential availability:

# Automatic mode detection
npm test

# Check current test mode
npm run test:check

# Force specific modes
npm run test:mocked  # No credentials required
npm run test:full    # Requires IPFS_PINNING_KEY

🎭 Mocked Mode (default without credentials):

• Uses Jest mocks for HTTP calls
• Loads mock files from test fixtures
• Safe for CI/CD environments
• Fast execution

🔑 Full Mode (when IPFS_PINNING_KEY is set):

• Makes real IPFS network calls
• Tests actual retry logic and gateway failover
• Validates real-world performance
• Comprehensive integration testing

Running Tests

npm test              # Credential-aware (auto-detects mode)
npm run test:watch    # Watch mode
npm run test:coverage # With coverage report
npm run test:modes    # Compare both mocked and full modes

For full testing with real IPFS:

export IPFS_PINNING_KEY="your_pinata_api_key"
npm run test:full

See test/README.md for detailed testing documentation.

Examples

See the examples/ directory for complete usage examples.

Documentation

Additional documentation is available in the docs/ directory:

• Manifest Specification
• Manifest Changes Summary

Contributing

Contributions are welcome! Please follow the existing code style and include tests for new features.

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please use the GitHub issues tracker.