Fidelity SDK

TypeScript SDK for interacting with the Fidelity Project smart contracts. Provides a type-safe interface for managing circuits, users, and decentralized governance on Ethereum-compatible blockchains.

Features

✅ Circuit Management - Create, activate, and manage circuits with full lifecycle control ✅ User Management - Register, activate, and deactivate users in the system ✅ Circuit Participation - Join and leave circuits with comprehensive tracking ✅ Governance System - Propose, vote on, and execute governance actions ✅ Role-Based Access Control - RBAC for administrative operations ✅ Type Safety - Full TypeScript support with generated contract bindings ✅ Comprehensive Testing - 58+ test cases across 5 test suites ✅ Well Documented - Complete API documentation and usage examples

Table of Contents

• Installation
• Quick Start
• Core Components
• Usage Examples
• Testing
• Documentation
• Contributing
• License

Installation

npm install sdk-blockchain-fidelity-ts

Prerequisites

• Node.js 14+ or higher
• TypeScript 5.0+
• Access to an Ethereum-compatible blockchain (local node, testnet, or mainnet)

Quick Start

import { ethers } from "ethers";
import { CircuitsManager } from "sdk-blockchain-fidelity-ts";

// Setup provider and wallet
const provider = new ethers.providers.JsonRpcProvider("http://localhost:8545");
const wallet = new ethers.Wallet("0x...", provider);

// Initialize CircuitsManager
const circuitsAddress = "0x..."; // Your deployed Circuits contract address
const manager = new CircuitsManager(circuitsAddress, wallet);

// Get circuit information
const circuits = await manager.getNumberOfCircuits();
console.log(`Total circuits: ${circuits}`);

// Check if a circuit is active
const isActive = await manager.isCircuitActive(1);
console.log(`Circuit 1 is active: ${isActive}`);

Core Components

CircuitsManager

The primary class for interacting with the Circuits smart contract. Provides methods for:

• Circuit Operations: Create, activate, deactivate circuits
• User Operations: Register, activate, deactivate users
• Participation: Join and leave circuits
• Governance: Create proposals, vote, and execute governance actions
• Queries: Get circuit information, user status, and participation data

TypeChain Bindings

The SDK includes auto-generated TypeChain bindings for all smart contracts:

• Circuits - Main circuit management contract
• CircuitGovernance - Governance system contract
• CircuitConnector - Circuit connection utilities
• UserManagement - User lifecycle management

Usage Examples

Circuit Management

// Create a new circuit (requires CIRCUIT_ADMIN_ROLE)
const createTx = await manager.createCircuit();
await createTx.wait();

// Change circuit status
await manager.changeCircuitStatus(1, 0); // circuitId=1, status=0

// Get all circuit IDs
const circuitIds = await manager.getCircuits();
console.log("Circuit IDs:", circuitIds);

User Management

// Register a new user
const registerTx = await manager.registerPartecipant();
await registerTx.wait();

// Check user registration status
const userId = 1;
const isRegistered = await manager.isRegistered(userId);
console.log(`User ${userId} is registered: ${isRegistered}`);

// Get user information
const participant = await manager.getPartecipant(userId);
console.log("User circuit:", participant.circuit);
console.log("User status:", participant.status);

Circuit Participation

// Join a circuit
const circuitId = 1;
const joinTx = await manager.joinCircuit(circuitId);
await joinTx.wait();

// Check circuit size
const size = await manager.getCircuitSize(circuitId);
console.log(`Circuit ${circuitId} has ${size} participants`);

// Leave a circuit
const leaveTx = await manager.leaveCircuit();
await leaveTx.wait();

Governance

// Create a governance proposal
const description = "Proposal to update circuit parameters";
const proposalTx = await manager.createProposal(description);
await proposalTx.wait();

// Vote on a proposal
const proposalId = 1;
const voteTx = await manager.voteProposal(proposalId, true); // true = approve
await voteTx.wait();

// Execute a proposal
const executeTx = await manager.executeProposal(proposalId);
await executeTx.wait();

Testing

The SDK includes a comprehensive test suite covering all functionality:

# Run all tests
npm run test_all

# Run specific test suites
npm run test_circuits_manager    # Basic CircuitsManager tests
npm run test_advanced            # Advanced integration tests
npm run test_governance          # Governance system tests
npm run test_integration         # Full integration tests
npm run test_edge_cases          # Edge case handling tests

Test coverage includes:

• Circuit lifecycle management
• User registration and activation
• Circuit participation flows
• Governance proposal workflows
• Role-based access control
• Edge cases and error handling

Documentation

For detailed documentation and advanced usage, see:

• CircuitsManager Usage Guide - Complete API reference with examples
• Test Guide - Guide for writing and running tests
• Test Suite Documentation - Overview of all test cases
• Quick Start Guide - Get started with testing

Project Structure

fidelity-sdk/
├── src/                      # Source code
│   ├── CircuitsManager.ts    # Main SDK class
│   └── index.ts              # Exports
├── typechain/                # Auto-generated contract bindings
├── test/                     # Test suites
│   ├── CircuitsManager.spec.ts
│   ├── CircuitsManager.Advanced.spec.ts
│   ├── Governance.spec.ts
│   ├── Integration.spec.ts
│   └── EdgeCases.spec.ts
├── build/                    # Compiled JavaScript output
└── README.md                 # This file

Building from Source

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run tests
npm run test_all

Contributing

Contributions are welcome! Please ensure:

1. All tests pass (npm run test_all)
2. Code follows the existing style
3. New features include tests
4. Documentation is updated

License

ISC License - see LICENSE file for details.

Repository

• Git: https://bitbucket.org/omniadev/sdk-blockchain-fidelity-ts.git
• Issues: https://bitbucket.org/omniadev/sdk-blockchain-fidelity-ts/issues

Author

OmniaGroup

Support

For questions and support, please open an issue in the repository.