Omnia.FidelitySDK 1.0.1

Fidelity SDK for .NET

C# 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 C# support with auto-generated contract bindings ✅ Async/Await - Modern async patterns for all operations ✅ Comprehensive Testing - 56+ test cases with MSTest framework ✅ Well Documented - XML documentation for IntelliSense support

Table of Contents

• Installation
• Quick Start
• Core Components
• Usage Examples
• Testing
• API Reference
• Building from Source
• Contributing
• License

Installation

NuGet Package Manager

Install-Package OmniaGroup.FidelitySDK

.NET CLI

dotnet add package OmniaGroup.FidelitySDK

PackageReference

<PackageReference Include="OmniaGroup.FidelitySDK" Version="1.0.0" />

Prerequisites

• .NET 9.0 or higher
• Access to an Ethereum-compatible blockchain (local node, testnet, or mainnet)
• Nethereum 4.12.0+ (automatically installed as dependency)

Quick Start

using OmniaGroup.FidelitySDK;
using System.Numerics;

// Initialize CircuitsManager with RPC URL and private key
string contractAddress = "0x..."; // Your deployed Circuits contract address
string rpcUrl = "http://localhost:8545";
string privateKey = "0x..."; // Your wallet private key

var manager = new CircuitsManager(contractAddress, rpcUrl, privateKey);

// Get circuit information
var numberOfCircuits = await manager.GetNumberOfCircuits();
Console.WriteLine($"Total circuits: {numberOfCircuits}");

// Check if a circuit is active
bool isActive = await manager.IsCircuitActive(new BigInteger(1));
Console.WriteLine($"Circuit 1 is active: {isActive}");

// Get circuit participants
var participants = await manager.GetCircuitPartecipants(new BigInteger(1));
Console.WriteLine($"Circuit 1 has {participants.Count} participants");

Core Components

CircuitsManager

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

• Circuit Operations: CreateCircuit(), ChangeCircuitStatus(), IsCircuitActive(), GetCircuits()
• User Operations: ActivateUser(), DeactivateUser(), IsUserActive(), GetPartecipant()
• Participation: JoinCircuit(), LeaveCircuit(), GetCircuitPartecipants()
• Governance: Propose(), CastVote(), RemoveVote(), ClosePropose()
• Queries: IsRegistered(), IsRegisteredToCircuit(), GetUserCircuit(), GetCircuitSize()

Contract Bindings

Auto-generated Nethereum bindings for smart contracts:

• Circuits - Main circuit management contract
• CircuitsActions - Circuit operation handlers

Usage Examples

Circuit Management

// Create a new circuit (requires CIRCUIT_ADMIN_ROLE)
string txHash = await manager.CreateCircuit();
Console.WriteLine($"Circuit created: {txHash}");

// Change circuit status
await manager.ChangeCircuitStatus(new BigInteger(1), new BigInteger(0));

// Get all circuit IDs
var circuitIds = await manager.GetCircuits();
foreach (var id in circuitIds)
{
    Console.WriteLine($"Circuit ID: {id}");
}

// Check circuit size
var size = await manager.GetCircuitSize(new BigInteger(1));
Console.WriteLine($"Circuit 1 size: {size}");

User Management

// Activate a user (requires CIRCUIT_ADMIN_ROLE)
var userId = new BigInteger(10);
string userAddress = "0x...";
await manager.ActivateUser(userId, userAddress);

// Check if user is active
bool isActive = await manager.IsUserActive(userId);
Console.WriteLine($"User {userId} is active: {isActive}");

// Check if user is registered
bool isRegistered = await manager.IsRegistered(userId);
Console.WriteLine($"User {userId} is registered: {isRegistered}");

// Get user information
var participant = await manager.GetPartecipant(userId);
Console.WriteLine($"User circuit: {participant.Circuit}");
Console.WriteLine($"User status: {participant.Status}");
Console.WriteLine($"User address: {participant.UserAddress}");

Circuit Participation

// Join a circuit
var userId = new BigInteger(10);
var circuitId = new BigInteger(1);
await manager.JoinCircuit(userId, circuitId);

// Check if user is registered to a specific circuit
bool isInCircuit = await manager.IsRegisteredToCircuit(userId, circuitId);
Console.WriteLine($"User {userId} is in circuit {circuitId}: {isInCircuit}");

// Check if user is registered and active
bool isActiveInCircuit = await manager.IsRegisteredToCircuitAndActive(userId, circuitId);
Console.WriteLine($"User {userId} is active in circuit {circuitId}: {isActiveInCircuit}");

// Get all participants with status
var participantsWithStatus = await manager.GetCircuitPartecipantsAndStatus(circuitId);
foreach (var p in participantsWithStatus)
{
    Console.WriteLine($"User {p.UserId}: Status={p.Status}, Address={p.UserAddress}");
}

// Leave circuit
await manager.LeaveCircuit(userId);

Governance

// Create a proposal (Ban=0, Unban=1)
var userAffected = new BigInteger(10);
var proposerId = new BigInteger(7);
var circuitId = new BigInteger(1);
uint proposalType = 0; // Ban proposal
await manager.Propose(userAffected, proposerId, circuitId, proposalType);

// Cast a vote
var voterId = new BigInteger(11);
var proposalId = new BigInteger(1);
await manager.CastVote(voterId, proposalId);

// Check if user has voted
bool hasVoted = await manager.HaveVoted(voterId, proposalId);
Console.WriteLine($"User {voterId} has voted on proposal {proposalId}: {hasVoted}");

// Check if proposal passed
bool passed = await manager.IsVotationPassed(proposalId);
Console.WriteLine($"Proposal {proposalId} passed: {passed}");

// Close proposal
await manager.ClosePropose(proposerId, proposalId);

Changing Signer

// Change the signing wallet
string newPrivateKey = "0x...";
manager.SetSigner(newPrivateKey);

// Or use a different RPC URL
manager.SetSigner(newPrivateKey, "https://mainnet.infura.io/v3/YOUR-PROJECT-ID");

// Get current Web3 instance
var web3 = manager.GetWeb3();

Testing

The SDK includes a comprehensive test suite with 66 test cases:

# Run all tests
cd solutions/sdk-csharp
dotnet test

# Run with detailed output
dotnet test --logger "console;verbosity=detailed"

# Run specific test categories
dotnet test --filter "TestCategory=Basic"
dotnet test --filter "TestCategory=Governance"
dotnet test --filter "TestCategory=EdgeCases"

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

API Reference

CircuitsManager Constructor

// Option 1: With Web3 instance
public CircuitsManager(string contractAddress, Web3 web3)

// Option 2: With RPC URL and private key
public CircuitsManager(string contractAddress, string rpcUrl, string privateKey)

Circuit Management Methods

User Management Methods

Participation Methods

Governance Methods

Manager Operations

Building from Source

# Clone the repository
git clone https://bitbucket.org/omniadev/fidelity-sdk-csharp.git
cd fidelity-sdk-csharp

# Restore dependencies
dotnet restore

# Build
dotnet build

# Run tests
dotnet test

# Pack as NuGet package
dotnet pack --configuration Release

The generated .nupkg file will be in bin/Release/.

Project Structure

sdk-csharp/sdk/
├── CircuitsManager.cs              # Main SDK class
├── Circuits/
│   ├── cs/
│   │   ├── Circuits.cs             # Auto-generated contract bindings
│   │   └── CircuitsActions.cs      # Contract action handlers
│   └── abi/
│       └── Circuits.json           # Contract ABI
├── Utility/
│   ├── EthersUtility.cs            # Ethereum utilities
│   └── TransactionHandler.cs       # Transaction helpers
├── FidelitySDK.csproj              # Project file with NuGet metadata
└── README.md                       # This file

Contributing

Contributions are welcome! Please ensure:

1. All tests pass (dotnet test)
2. Code follows C# conventions and style guidelines
3. New features include unit tests
4. XML documentation is provided for public APIs
5. README is updated if needed

License

ISC License

Copyright (c) 2024-2026 OmniaGroup

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Repository

• Git: https://bitbucket.org/omniadev/fidelity-sdk-csharp.git
• NuGet: https://www.nuget.org/packages/OmniaGroup.FidelitySDK

Author

OmniaGroup

Support

For questions and support, please open an issue in the repository or contact support@omniagroup.com.

Related Packages

• TypeScript/JavaScript SDK: sdk-blockchain-fidelity-ts on npm
• Smart Contracts: Available in the fidelity-circuits package