Skip to main content

Nethereum.Circles

NuGet: Nethereum.Circles | Source: src/Nethereum.Circles/

Nethereum.Circles

Nethereum service library for interacting with Circles UBI (Universal Basic Income) protocol contracts on Gnosis Chain.

About Circles​

Circles is a decentralized digital currency protocol that implements a fair Universal Basic Income system. Key features include:

  • Universal Issuance: Every participant receives 1 CRC (Circles token) per hour automatically
  • Daily Burn Mechanism (Demurrage): All balances decrease by approximately 7% annually to ensure newly-created CRC remains valuable
  • Trust-Based Transactions: Users establish trust connections enabling token transfers through social networks
  • Group Currencies: Members can convert personal CRC into fungible group currencies for community commerce

The protocol operates on Gnosis Chain through smart contracts, with users maintaining complete self-custody of their funds.

Installation​

dotnet add package Nethereum.Circles

Core Components​

Contract Services​

The library provides generated contract services for all Circles V2 contracts:

  • HubService: Main hub contract for avatar registration, trust management, token minting, and transfers
  • DemurrageCirclesService: ERC20-wrapped Circles tokens with demurrage (time-value decay)
  • InflationaryCirclesService: ERC20-wrapped Circles tokens with inflationary representation
  • MigrationService: Contract for migrating from Circles V1 to V2
  • NameRegistryService: Service for avatar name registration

RPC Extensions​

Custom RPC methods for Circles-specific data queries:

  • GetTotalBalance / GetTotalBalanceV2: Get the total CRC balance for an avatar
  • CirclesQuery: Generic paginated query interface for Circles data
  • GetTransactionHistoryQuery: Paginated transaction history for an account
  • GetTrustRelationsQuery: Query trust relationships for an avatar
  • GetAvatarInfoQuery: Get avatar information including name, type, and token ID

Usage Examples​

Query Balance​

using Nethereum.Web3;
using Nethereum.JsonRpc.Client;
using Nethereum.Circles.RPC.Requests;

var client = new RpcClient(new Uri("https://rpc.aboutcircles.com/"));

// Get total balance (V2)
var getTotalBalanceV2 = new GetTotalBalanceV2(client);
string balance = await getTotalBalanceV2.SendRequestAsync("0xYourAvatarAddress");
Console.WriteLine($"Total Balance: {balance}");

Interact with Hub Contract​

using Nethereum.Web3;
using Nethereum.Circles.Contracts.Hub;

var web3 = new Web3("https://rpc.aboutcircles.com/");
var hubAddress = "0xc12C1E50ABB450d6205Ea2C3Fa861b3B834d13e8"; // Gnosis Chain V2 Hub

var hubService = new HubService(web3, hubAddress);

// Check if address is a human avatar
bool isHuman = await hubService.IsHumanQueryAsync("0xYourAddress");

// Check trust relationship
bool isTrusted = await hubService.IsTrustedQueryAsync("0xTruster", "0xTrustee");

// Calculate pending issuance for a human
var issuance = await hubService.CalculateIssuanceQueryAsync("0xHumanAddress");

Personal Mint with Gnosis Safe​

using Nethereum.Web3;
using Nethereum.GnosisSafe;
using Nethereum.Circles.Contracts.Hub;

var privateKey = "0x...";
var safeAddress = "0xYourSafeAddress";

var web3 = new Web3(new Nethereum.Web3.Accounts.Account(privateKey), "https://rpc.aboutcircles.com/");
var hubService = new HubService(web3, hubAddress);

// Configure to execute through Gnosis Safe
hubService.ChangeContractHandlerToSafeExecTransaction(safeAddress, privateKey);

// Mint personal Circles
await hubService.PersonalMintRequestAndWaitForReceiptAsync();

Query Transaction History​

using Nethereum.JsonRpc.Client;
using Nethereum.Circles.RPC.Requests;

var client = new RpcClient(new Uri("https://rpc.aboutcircles.com/"));
var transactionHistoryQuery = new GetTransactionHistoryQuery(client);

// Get first page
var transactions = await transactionHistoryQuery.SendRequestAsync("0xAvatarAddress", 100);

foreach (var tx in transactions.Response)
{
    Console.WriteLine($"Hash: {tx.TransactionHash}, Value: {tx.Value}, From: {tx.From}, To: {tx.To}");
}

// Get next page
transactions = await transactionHistoryQuery.MoveNextPageAsync(transactions);

Query Trust Relations​

using Nethereum.JsonRpc.Client;
using Nethereum.Circles.RPC.Requests;

var client = new RpcClient(new Uri("https://rpc.aboutcircles.com/"));
var trustQuery = new GetTrustRelationsQuery(client);

var trustRelations = await trustQuery.SendRequestAsync("0xAvatarAddress", 20);

foreach (var relation in trustRelations.Response)
{
    Console.WriteLine($"Trustee: {relation.Trustee}, Truster: {relation.Truster}");
}

Contract Addresses​

Gnosis Chain (Production)​

  • Hub V2: 0xc12C1E50ABB450d6205Ea2C3Fa861b3B834d13e8
  • RPC Endpoint: https://rpc.aboutcircles.com/

Chiado Testnet​

  • RPC Endpoint: https://chiado-rpc.aboutcircles.com

Dependencies​

  • Nethereum.Web3: Core Web3 functionality
  • Nethereum.GnosisSafe: For Safe-based transaction execution (optional)

References​