@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.

For local development and testing changes before publishing, see the Local Development Guide.

License

MIT License - see LICENSE file for details.

Support

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