Circles is a decentralized protocol designed to create and distribute fair and social money through personal currencies. At the core of the Circles project lies a simple yet powerful principle:

"Every person receives one Circle every hour, unconditionally."

Circles uses smart contracts, deployed on Gnosis Chain, for creation of personal and group Avatars and their currencies (CRC). Circles as a network works via trust connection. To join Circles 2.0, you would require an invitation from a human/personal avatar. The pathfinder service is deployed to find the optimal path between trust connections to exchange personal and group currencies. Circles smart contracts are based on ERC1155 multi-token standard for both personal avatars and group avatars.

Every person receives 1 CRC every hour, hence 24 CRC per single day. Circles undergo daily demurrage at a rate equivalent to 7% per year. Issuance for past days accounts for this demurrage, ensuring fair distribution over time.

This documentation will guide developers in understanding Avatars and using the Circles SDK.

In addition to individual CRC currencies, Circles has introduced the concept of Group Avatars and Currencies. The idea behind Group currencies is to social-economic value amongst groups, without the geographical bounds of where groups are generated or created. Group avatar tokens can't be minted based on time, rather depends on personal collateral.

If you want to become a part of group, you would require to be invited to the group itself by the group admin. Invitation to groups would be that you are simply trusting a human avatar. Now, in order to mint the group tokens, as a group member (human avatar in the group) you would require to trust the group address so that you can start accepting the tokens. When you are trusting a human, you are also trusting their personal tokens. You can currently mint group tokens based on the quantity of total personal tokens (CRC).

The current mint policy allows you to mint group tokens based on your total personal CRC tokens quantity that you hold as a human. In other words, your personal tokens would be swapped for your group tokens.

Our developer documentation portal provides comprehensive guide to build using Circles SDK, SDK references, contract addresses, and code examples to help you integrate Circles into your applications and build upon our ecosystem.

Circles SDK

If you want to develop a server or client application that utilizes Circles, and allow you to utilize trust connection and personal/group currencies, then Circles SDK would be your entry point. Based on your need, you can pick to develop any avatar post initialization of SDK.

• Circles SDK package on npm

• Circles SDK source code

Circles Infrastructure

Circles Hub Contracts

Circles relies on hub contracts for V1 and V2 that you can utilize directly within applications. These deployed contracts exist on Gnosis Chain and are required by the SDK for configuration and initialization.

Here are the deployed addresses for V1 hub and V2 hub that you should consider for configuration or building tools on Circles protocol:

If you want to skip directly to setting up Circles SDK in your application, you can jump to the SDK Configuration Guide which covers all the setup parameters.

Join the Technical Community

To collaborate with fellow developers, ask questions, and share your insights, join our technical community channels on Discord, GitHub, and other platforms.

Join Telegram Group as a Hacker or a Developer.

The Circles SDK is a TypeScript library that allows you to integrate Circles protocol into your dApp to implement trust connections and offering the users of network to get socio-economic value.

As a developer, you can start from installing the SDK and supported packages.

Circles v2.0 SDK features :

npm i @circles-sdk/sdk

• Manage Signers: Use a contract runner (like MetaMask) to sign transactions.

• Circles Configuration: Set up Circles-specific configuration (contract addresses, RPC endpoints).

• Access Circles Data: Query data through the Circles RPC Query API, including balances, trust relations, and transaction histories.

• Support for Circles V1 and V2 Hubs: Interact with both V1 and V2 of Circles protocol hubs for contract-related operations,

• Pathfinder Client: Use the V1 and V2 Pathfinder for finding liquid paths in trust networks to facilitate transfers.

• Profile Management: Store and retrieve profiles (human, group, organization) via the Circles profile service.

• Avatar Management:

  • Retrieve avatars by their address.

  • Register human, group, and organization avatars in Circles V1 and V2.

• Invitation Handling: Accept invitations to join the Circles network by specifying an inviter and providing profile data.

Circles SDK dependency packages

Circles is a decentralized protocol with a social and economic value for humans, communities and groups. Circles is not a crypto startup or product in general, but a collective effort to bring a fair distribution model for the money created, owned and shared by people.

Explore our developer documentation, and join us in our mission to create a fair and sustainable economy for all.

Circles V2 Core Components

Circles is all about creating a fairer money system. Our current monetary system and most cryptocurrencies tend to benefit those with established wealth and market positions, making it challenging for newcomers to catch up. Wealth grows disproportionately for those already in the market, as time in the market often beats time to market.

Circles aims to solve this by ensuring equal opportunity for all. Each user continuously generates tokens at a rate of one Circle (CRC) per hour, regardless of when they join. Additionally, existing Circles incur a demurrage fee of 7% per year. By tying the issuance of tokens to time, a resource everyone has, Circles promotes fairness by giving everyone a chance to accumulate tokens and encouraging the active circulation of currency.

Issuance

Circles employs a unique token issuance mechanism where each user generates their own currency (CRC) at a steady rate of one token per hour. The minting rules are encoded in the so-called Hub, a token factory from which all individual Circles tokens are created.

Demurrage

All tokens are automatically demurred at a rate of 7% per year.

For human users, the demurrage is offset by the steady income of new CRC. Only after minting for 80 years (roughly a human lifespan) or through economic activity can a person become negatively affected by demurrage. Once the person dies, no new tokens are minted and all of the person's tokens are subjected to demurrage.

The following graph visualizes the balance of an account over time, assuming no economic activity and continuous minting of all CRC.

If understood as a tax, then the tax would be negative at first (you get money), but once your balance reaches the threshold of 125.000 Circles, it turns positive (you loose money).

Implementation

Circles v1 tokens adhere to the ERC20 token standard with added functionality for personal minting and a built-in allowance like mechanism for the Hub contract which is necessary to enable the path transfer functionality.

Circles v2 is built on the ERC1155 token standard. Here, the Hub uses a standard allowance to facilitate path transfers. The token metadata mimics as profile.

Dead man's switch

Circles v1 tokens have a built-in "dead man's switch" that permanently disables the minting of new tokens after 90 days of inactivity. This proved problematic, so in Circles v2, the mechanism was replaced by a limit that allows a maximum minting amount of 14 days' worth of Circles.

In both versions, minting can be stopped manually. This feature is used, for example, to ensure that users who migrate from v1 to v2 cannot mint in v1 before they are allowed to mint in v2.

The SDK is built around the concept of avatars. An avatar is a Circles user and is used to interact with other Avatars.

• New Circles users must sign up.

• For existing Circles users, you can simply get exisiting avatars by address.

Creating a new avatar

Prerequisites

• Metamask Plugin installed in browser

• Setup Gnosis Chain (Mainnet) and/or Chiado Chain (Testnet). Check out Gnosis Chain docs here.

• xDAI as gas token, check out Mainnet and Testnet Faucet

Install packages for CirclesSDK

If you have all prerequisites in place, start by installing the Circles SDK package and ethers v6 in your project using npm.

npm i @circles-sdk/sdk @circles-sdk/data @circles-sdk/utils @circles-sdk/profiles @circles-sdk/adapter-ethers ethers

1. Add imports

Then, import the necessary interfaces from the Circles SDK and Ethers.

import { CirclesConfig, Sdk } from '@circles-sdk/sdk';
import {BrowserProviderContractRunner} from "@circles-sdk/adapter-ethers"

2. Add CirclesConfig for SDK

CirclesConfig defines the configuration settings needed to set up the SDK. You provide an object that follows this structure when initializing the SDK.

Circles is available on Gnosis Chain and Chiado Testnet. You need to specify the correct contract addresses and service endpoints for each environment.

import type {CirclesConfig} from "@circles-sdk/sdk";

export const GnosisChainConfig: CirclesConfig = {
    circlesRpcUrl: "https://rpc.aboutcircles.com/",
    pathfinderUrl: "https://pathfinder.aboutcircles.com",
    v1HubAddress: "0x29b9a7fbb8995b2423a71cc17cf9810798f6c543",
    v2HubAddress: "0xc12C1E50ABB450d6205Ea2C3Fa861b3B834d13e8",
    nameRegistryAddress: "0xA27566fD89162cC3D40Cb59c87AAaA49B85F3474",
    migrationAddress: "0xD44B8dcFBaDfC78EA64c55B705BFc68199B56376",
    profileServiceUrl: "https://rpc.aboutcircles.com/profiles/",
};

import type {CirclesConfig} from "@circles-sdk/sdk";

export const circlesConfig: CirclesConfig = {
    circlesRpcUrl: "https://static.94.138.251.148.clients.your-server.de/rpc/",
    v1HubAddress: "0x29b9a7fbb8995b2423a71cc17cf9810798f6c543",
    v2HubAddress: "0x3D61f0A272eC69d65F5CFF097212079aaFDe8267",
    migrationAddress: "0x28141b6743c8569Ad8B20Ac09046Ba26F9Fb1c90",
    nameRegistryAddress: "0x8D1BEBbf5b8DFCef0F7E2039e4106A76Cb66f968",
    baseGroupMintPolicy: "0x79Cbc9C7077dF161b92a745345A6Ade3fC626A60",
    profileServiceUrl: "https://static.94.138.251.148.clients.your-server.de/profiles/",
};

3. Setup Provider and Signer

To setup provider and signer, we would utilize the Circles Adapter that is built to support transactions via ethers. Once you have already imported the BrowserProviderContractRunner , you would need to initialize it.

const adapter = new BrowserProviderContractRunner();
await adapter.init();

3. Initialize the Circles SDK

To initialize the CirclesSDK, we will pass on the CirclesConfig and Adapter to SDK instance.

const sdk = new Sdk (adapter,CirclesConfig,);

Once you have successfully created a SDK instance, you are all set to use Circles in your dApp. Let's learn more about the Circles SDK features and how you can use them on the next pages.\

Choose which Avatar would you like to build on

Circles is built around the ERC1155 token standard which allows tokens to have metadata. Since Circles is all about personal currency, it makes sense to utilize this metadata as a profile.

The profile data is stored in IPFS and the Circles avatar references the CIDv0 of the profile on-chain.

Profile schema

The schema is very simple and only has one required attribute:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 36,
      "description": "The name of the profile owner"
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "A description of the profile"
    },
    "previewImageUrl": {
      "type": "string",
      "format": "data-url",
      "pattern": "^data:image\\/(png|jpeg|jpg|gif);base64,",
      "description": "A base64-encoded image data URL for the profile preview"
    },
    "imageUrl": {
      "type": "string",
      "maxLength": 2000,
      "description": "A URL pointing to the profile image"
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

Profile picture

You can include a profile picture in the profile document (the previewImageUrl). If you choose to do so, make sure the picture you are using has the following properties:

1. Format: The image must be in PNG, JPEG, or GIF format.

2. Dimensions: The image must be exactly 256x256 pixels.

3. File size: The image must not exceed 150KB.

4. Encoding: The image must be base64 encoded and included as a data URL in the previewImageUrl field.

These requirements are enforced by the server to ensure consistency and performance across the platform.

  const img = new Image();
        img.src = reader.result as string;
        img.onload = () => {
          const canvas = document.createElement('canvas');
          const ctx = canvas.getContext('2d');
          const cropWidth = 256;
          const cropHeight = 256;

          if (ctx) {
            canvas.width = cropWidth;
            canvas.height = cropHeight;

            ctx.drawImage(img, 0, 0, cropWidth, cropHeight);

            const imageDataUrl = canvas.toDataURL('image/jpeg', 0.5);

            if (imageDataUrl.length > 150 * 1024) {
              console.warn('Image size exceeds 150 KB after compression');
            }

Here is a code example (Browser; TypeScript) that shows how you can prepare the previewImageUrl.

1. Creation of Personal/Human Avatars :

Circles v2.0 will allow you to join the network as a human with a token ERC 1155 standard. You would have a profile and would require to be invited to join the network and start minting personal CRC tokens.

The V2 Hub contract is the main smart contract that a user would interact. You would need a profile CID as well.

await avatar.inviteHuman(inviteeAddress);

const avatar = await sdk.acceptInvitation(inviterAddress,"Qm.....");
console.log(avatar.avatarInfo);

Incase, you don't have CID, you can use the Profile object and implicitly use the Circles pinning service to pin it:

const avatar = await sdk.acceptInvitation(inviterAddress, {
    name: "My profile name"
});
console.log(avatar.avatarInfo);

Get an existing avatar

If you have the address of an existing avatar, you can get an instance by calling sdk.getAvatar(address). It returns either an AvatarInterface instance or throws an error if the avatar can't be found.

const avatar = await sdk.getAvatar(avatarAddress);
console.log(avatar.avatarInfo);

1. Creation of Personal/Human Avatars :

Circles v2.0 allows you to join the network as a human with an ERC-1155 standard token. You would have a profile and would require to be invited to join the network and start minting personal CRC tokens.

The V2 Hub contract is the main smart contract that a user would interact. You would need a profile CID as well.

const avatar = await avatar.inviteHuman(inviteeAddress,"Hk.....");        //CID required

const avatar = await sdk.acceptInvitation(inviterAddress,"Qm.....");
console.log(avatar.avatarInfo);

Incase, you don't have CID, you can use the Profile object and implicitly use the Circles pinning service to pin it:

const avatar = await sdk.acceptInvitation(inviterAddress, {
    name: "My profile name"
});
console.log(avatar.avatarInfo);

2. Getting mintable amount for an avatar

This function will allow you to get maximum amount of CRC tokens that are available to mint at that point of time. Human avatars can mint only upto 24 personal Circles per day.

const mintableToken = await avatar.getMintableamount ()

3. Minting personal tokens :

This function will allow you to mint your personal CRC tokens

const mintTransaction = await sdk.personalMint();
console.log('Transaction successful, receipt:', mintTransaction);

When you become part of the Circles network, every person has their own personal Circles token and receives one Circle (CRC) per hour, unconditionally.

The trust network forms a social graph where each trust relationship acts as a link, allowing tokens to flow between individuals through these connections. This ensures that the value of Circles is supported by genuine social relationships, fostering a community-driven economy.

At the same time, this mechanism is an effective soft sybil protection, as it decentralises the verification process and relies on human judgment for trust, preventing fake accounts from compromising the network. Since the connections between Circles accounts have a limited capacity (defined by their balances of fungible tokens), this limits the impact of fake accounts that manage to get trusted by a credible member of the network to their direct surroundings.

Get mintable amount for an avatar

This function will allow you to get maximum amount of CRC tokens that are available to mint at that point of time. Human avatars can mint only upto 24 personal Circles per day.

const mintableToken = await avatar.getMintableamount();

Mint personal tokens :

This function will allow you to mint your personal CRC tokens

const mintTransaction = await avatar.personalMint();
console.log('Transaction successful, receipt:', mintTransaction);

Trust an avatar

This function allows an avatar to trust another avatar or multiple avatars. Trusting an avatar means you are willing to accept Circles that have been issued by them. Once trusted, Circles transfers from the trusted avatar are allowed.

const trustReceipt = await avatar.trust("AvatarAddress");
console.log(receipt);

Untrust an avatar

This function revokes trust from another avatar or multiple avatars. Once trust is revoked, the avatar will no longer accept Circles issued by the untrusted avatar. However, this will not impact Circles that were already received from the untrusted avatar.

const untrustReceipt = await avatar.untrust("AvatarAddress");
console.log(receipt);

Check if avatar trusts another Avatar

This function checks if the current avatar is trusted by another avatar. It can be used to verify whether another avatar is willing to accept Circles issued by the current avatar.

const isTrusted = await avatar.isTrustedBy("AvatarAddress");
console.log(isTrusted); // true or false

This function retrieves all trust relationships of the current avatar. It returns an array of trust relations indicating which avatars are trusted, which avatars trust the current avatar, and which relationships are mutual.

const trustRelations = await avatar.getTrustRelations();
trustRelations.forEach
    (relation => { 
        console.log(${relation.avatar1} ${relation.relation} ${relation.avatar2}); });

Get total balance of an avatar

This function fetches the total Circles balance of the avatar. It checks the balance from either the v1 or v2 versions of Circles, depending on which version the avatar is using.

const totalBalance = await avatar.getTotalBalance();
console.log(`Total Circles balance: ${totalBalance}`);

Get balances for an avatar

This function retrieves the avatar's token balances. Before calling this function, ensure that the system is initialized. It returns a promise that resolves to an array of TokenBalanceRow objects, each representing the balances for different tokens associated with the avatar in the current context.

const tokenBalances = await avatar.getBalances();
tokenBalances.forEach((balance) => {
  console.log(`Token: ${balance.token}, Balance: ${balance.amount}`);
});

Get a profile for the avatar

This function fetches the current profile associated with the avatar. If no profile exists, it will return undefined.

try {
  const profile = await avatar.getProfile();
  if (profile) {
    console.log("Avatar Profile:", profile);
  } else {
    console.log("No profile associated with this avatar.");
  }
} catch (error) {
  console.error("Error retrieving profile:", error);
}

Update metadata of the profile

This function updates the avatar's metadata by uploading a new content identifier (CID) to IPFS. The CID represents the new metadata for the avatar.

// IPFS CID for the new metadata
const cid = "QmYourIPFSCIDHere";

try {
  const receipt = await avatar.updateMetadata(cid);
  console.log("Metadata updated successfully:", receipt);
} catch (error) {
  console.error("Error updating metadata:", error);
}

Update profile of the avatar

This function updates the avatar’s profile and returns the IPFS CID of the newly updated profile.

const newProfile: Profile = {
  name: "Avatar Name",
  description: "Updated description for the avatar.",
  image: "ipfs://QmYourImageCIDHere", // Example IPFS image CID
};

try {
  const newCid = await avatar.updateProfile(newProfile);
  console.log("Profile updated successfully. New CID:", newCid);
} catch (error) {
  console.error("Error updating profile:", error);
}

Get Maximum amount of transferrable token

Utilizes the pathfinder to find the maximum Circles amount that can be transferred from this Avatar to the specified avatar. The address of the avatar passed would be the one to which the Circles will be transferred.

const maxTransferable = await avatar.getMaxTransferableAmount(toAvatarAddress)
console.log(`Maximum transferable amount: ${maxTransferable}`);

Transfer CRC tokens

This function will allow you to transfer CRC tokens to the avatars with a valid trust path. The maximum transferable amount can be lower than the avatar's balance depending on its trust relations and token holdings.

const transferReceipt = await avatar.transfer(recipientAddress, amountToTransfer);
console.log(`Transfer successful! Transaction receipt: ${transferReceipt}`);

You would be requiring to initialize the Circles data property to find groups and get memberships.

const data = sdk.data

Otherwise you can create an instance like this:

const circlesRpc = new CirclesRpc("https://chiado-rpc.aboutcircles.com");
const data = new CirclesData(circlesRpc);

Find Groups

• Functionality: This method allows you to fetch a list of groups from the Circles system, with options for pagination and filtering. This is useful for applications that need to display groups or for querying specific groups based on certain criteria.

• Parameters:

  • pageSize: A number specifying how many groups should be returned in the response.

  • params: An optional parameter that can include various filters for the query, such as group types or statuses.

const groupsPageSize = 10; // Define the maximum number of groups to return
const queryParams = { /* Example filter parameters */ };

try {
    const groupsQueryResult = await circles.data.findGroups(groupsPageSize, queryParams);
    console.log('Retrieved groups:', groupsQueryResult);
} catch (error) {
    console.error('Error fetching groups:', error);
}

Get group memberships

This method is designed to fetch all group memberships associated with a specific avatar. This is useful for applications that want to display or manage the groups that a user belongs to.

Parameters:

• avatar: A string representing the address of the avatar for which group memberships are being requested.

• pageSize: A number that specifies the maximum number of group memberships to return.

const avatarAddress = '0xYourAvatarAddress'; 
// The address of the avatar
const membershipsPageSize = 5; 
// Define the maximum number of memberships to return

try {
    const membershipsQueryResult = await circles.getGroupMemberships(avatarAddress, membershipsPageSize);
    console.log('Retrieved group memberships:', membershipsQueryResult);
} catch (error) {
    console.error('Error fetching group memberships:', error);
}

To create a group following the ERC1155 standard, which allows you to utilize personal tokens as a collateral and mint group tokens, you would require to call the following function.

Your wallet should not have been signed up as a different avatar and once connected to SDK would be registered as s a group avatar in Circles v2.

To invite group members, you need to trust them. Trusting them would simply mean that you are inviting them to join group and would be accepting their personal token as collateral. Now, once invited, a group member will require to trust the group avatar address so that they can mint the group tokens.

Invitation to the group

const trustReceipt = await groupAvatar.trust("AvatarAddress");
console.log(receipt);

Removal of the member from the group

const trustReceipt = await groupAvatar.untrust("AvatarAddress");
console.log(receipt);

You need to pass the profile and the address of the mint policy contract when calling the function.

import { GroupProfile, Profile, Profiles } from '@circles-sdk/profiles';

// When on Gnosis Chain use this ..
// const standardMintPolicy = "0x5Ea08c967C69255d82a4d26e36823a720E7D0317";

// When on Chiado use that ..
// const standardMintPolicy = "0xaD49f877021c73d00bE142b135c9AA67f0D8e9c6";

const mintPolicy = '0xYourMintPolicyContractAddress';
const groupProfile: GroupProfile = {
    name: 'Group Namw',
    symbol: 'Group Token Symbol',
    description: '',
    previewImageUrl: '',
    imageUrl: '',
    
    
};
const GroupAvatar = await circlesSDK?.registerGroupV2(mintPolicy, profile);

// Log the newly created group avatar details
console.log('New Group Avatar:', GroupAvatar);

Circles Profile specs

Incase, you want to check how to manage circles profiles, you can simply checkout this guide :

import React, { createContext, useState, useEffect, useCallback } from "react";
import { BrowserProviderContractRunner } from "@circles-sdk/adapter-ethers";
import { Sdk } from "@circles-sdk/sdk";

// Create a context for the Circles SDK
const CirclesSDKContext = createContext(null);

// Provider component to wrap around your application
export const CirclesSDK = ({ children }) => {
    const [sdk, setSdk] = useState(null);
    const [isConnected, setIsConnected] = useState(false);
    const [adapter, setAdapter] = useState(null);
    const [circlesProvider, setCirclesProvider] = useState(null);
    const [circlesAddress, setCirclesAddress] = useState(null);

    // Configuration for the Circles SDK on Gnosis Chain or use the sandbox version
    const gnosisChainConfig = {
        circlesRpcUrl: "https://rpc.aboutcircles.com/",
        pathfinderUrl: "https://pathfinder.aboutcircles.com",
        v1HubAddress: "0x29b9a7fbb8995b2423a71cc17cf9810798f6c543",
        v2HubAddress: "0xc12C1E50ABB450d6205Ea2C3Fa861b3B834d13e8",
        nameRegistryAddress: "0xA27566fD89162cC3D40Cb59c87AAaA49B85F3474",
        migrationAddress: "0xD44B8dcFBaDfC78EA64c55B705BFc68199B56376",
        profileServiceUrl: "https://rpc.aboutcircles.com/profiles/",
        };

    // Function to initialize the SDK
    const initSdk = useCallback(async () => {
        try {
            const adapter = new BrowserProviderContractRunner();
            await adapter.init(); // Initialize the adapter before using it
            
            setAdapter(adapter); // Set the adapter in the state

            const circlesProvider = adapter.provider;
            setCirclesProvider(circlesProvider); // Store the provider
            
            const circlesAddress = await adapter.address;
            setCirclesAddress(circlesAddress); // Set the address
            
            const sdk = new Sdk(chainConfig, adapter); // Pass the initialized adapter to the SDK
            setSdk(sdk); // Set the SDK in the state
            setIsConnected(true); // Update connection status
        } catch (error) {
            console.error("Error initializing SDK:", error);
        }
    }, []);

    useEffect(() => {
        initSdk(); // Call initSdk when the component mounts
    }, [initSdk]);

    // Provide the SDK context to child components
    return (
        <CirclesSDKContext.Provider value={{
            sdk,
            setIsConnected,
            isConnected,
            adapter,
            circlesProvider,
            circlesAddress,
            initSdk,
        }}>
            {children}
        </CirclesSDKContext.Provider>
    );
};

export default CirclesSDKContext;

To access the entire codebase for building frontend applications using React and Circles SDK, check out the Github repo here.

This method retrieves the total amount of Circles associated with the avatar, which can be either Personal Circles or Group Circles, depending on the calling context.

getTotalSupply: () => Promise<bigint>;

// Example of calling the getTotalSupply method
try {
    const totalSupply = await circles.getTotalSupply();
    console.log('Total Circles Supply:', totalSupply.toString());
} catch (error) {
    console.error('Error fetching total supply:', error);
}

Organizations are different from groups as you can't mint an organization token, use profiles and trust other avatars to receive tokens from them.

const registerV2Organization = async (sdk, profile) => {
    try {
        const avatar = await sdk.registerOrganizationV2(profile); // Call the V2 method
        console.log('V2 Organization Avatar:', avatar);
    } catch (error) {
        console.error('Error registering organization V2:', error);
    }
};

const registerLegacyOrganization = async (sdk) => {
    try {
        const avatar = await sdk.registerOrganization(); // Call the legacy method
        console.log('Legacy Organization Avatar:', avatar);
    } catch (error) {
        console.error('Error registering legacy organization:', error);
    }
};

Retrieve user profile data using the Profiles Nethermind plugin. You can:

• Create new user profiles

• Search existing profiles using parameters such as:

  • Name

  • CID (Content Identifier)

  • Description

  • Wallet Address

1. Create a Profile (POST request)

curl -X POST "https://rpc.aboutcircles.com/profiles/pin" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "John Doe",
           "description": "A blockchain developer",
           "previewImageUrl": "https://example.com/preview.jpg",
           "imageUrl": "https://example.com/image.jpg",
           "extensions": {
             "twitter": "@johndoe",
             "github": "johndoe"
           }
         }'

2. Get a Profile by CID (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/get?cid=Qm12345abcdef"

3. Get Multiple Profiles by CIDs (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/getBatch?cids=Qm12345abcdef,Qm678bbdj

4. Search Profiles by Name (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/search?name=John"

5. Search Profiles by Description (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/search?description=Circles"

6. Search Profiles by Address (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/search?address=0x1234567890abcdef"

7. Search Profiles by CID (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/search?CID=Qm12345abcdef"

8. Search Profiles with Multiple Criteria (GET request)

curl -X GET "https://rpc.aboutcircles.com/profiles/search?name=John&description=blockchain&address=0x1234567890abcdef&CID=Qm12345abcdef"

Subscribe

To subscribe, you need an initialized CirclesData class.

const circlesRpc = new CirclesRpc("https://rpc.aboutcircles.com/");
const data = new CirclesData(circlesRpc);

const circlesRpc = new CirclesRpc("https://static.94.138.251.148.clients.your-server.de/rpc/");
const data = new CirclesData(circlesRpc);

Then call the subscribeToEvents() method and supply the address of the avatar to subscribe to:

const avatarEvents = await data.subscribeToEvents("0x...");
avatarEvents.subscribe(event => {
    console.log(event);
});

If you want to subscribe to all events, call it without parameter:

const avatarEvents = await data.subscribeToEvents("0x...");
avatarEvents.subscribe(event => {
    console.log(event);
});

Query past events

If your client missed some events, you can query all events for a specific avatar in a block range.

const avatarEvents = await data.getEvents("0x..", 9000000, 10000000);

You can omit the last parameter (toBlock) to query from fromBlock to the latest block:

const avatarEvents = await data.getEvents("0x..", 10000000);

Event types

The above methods yield CirclesEvents. All events have at least the following base properties:

• $event: CirclesEventType One of the event types listed below

• blockNumber: number In which block the event occurred

• timestamp?: number When the event occurred

• transactionIndex: number The index of the transaction in the block

• logIndex: number The index of the log entry in the transaction

• transactionHash?: string The transaction hash

Here's a list of all event types. Please refer to the source code for the event properties.

export type CirclesEvent =

// CrcV1 Events

| CrcV1_HubTransfer
| CrcV1_Signup
| CrcV1_OrganizationSignup
| CrcV1_Trust
| CrcV1_Transfer

// CrcV2 Events

 | CrcV2_InviteHuman
 | CrcV2_PersonalMint
 | CrcV2_RegisterGroup
 | CrcV2_RegisterHuman
 | CrcV2_RegisterOrganization
 | CrcV2_Stopped
 | CrcV2_Trust
 | CrcV2_TransferSingle
 | CrcV2_Erc20WrapperTransfer
 | CrcV2_Erc20WrapperDeployed
 | CrcV2_URI
 | CrcV2_ApprovalForAll
 | CrcV2_TransferBatch
 | CrcV2_RegisterShortName
 | CrcV2_UpdateMetadataDigest
 | CrcV2_CidV0
 | CrcV2_StreamCompleted
 | CrcV2_CreateVault
 | CrcV2_GroupMintSingle
 | CrcV2_GroupMintBatch
 | CrcV2_GroupRedeem
 | CrcV2_GroupRedeemCollateralReturn
 | CrcV2_GroupRedeemCollateralBurn
 | CrcV2_DepositDemurraged
 | CrcV2_DepositInflationary
 | CrcV2_WithdrawDemurraged
 | CrcV2_WithdrawInflationary

Initialization

Most of the previously shown avatar methods internally use the CirclesData class with filters for the current avatar address. If you already have a configured Sdk instance, you can use the sdk.data property to access the class:

const data = sdk.data;

Otherwise you can create an instance like this:

const circlesRpc = new CirclesRpc("https://rpc.aboutcircles.com/");
const data = new CirclesData(circlesRpc);

const circlesRpc = new CirclesRpc("https://static.94.138.251.148.clients.your-server.de/rpc/");
const data = new CirclesData(circlesRpc);

Get avatar info

The getAvatarInfo(avatar: string): Promise<AvatarRow | undefined> method finds basic information about an avatar. This includes the signup timestamp, circles version, avatar type (human, organization or group), and token address/id as well as it's profile CID (if any).

This method is useful to check if an avatar exists before using .

const avatarInfo = await data.getAvatarInfo("0x...");
if (avatarInfo) {
   console.log("Avatar is signed up at Circles");
} else {
   console.log("Avatar is not signed up at Circles");
}

Get token info

The getTokenInfo(tokenId: string): Promise<TokenInfoRow | undefined> methods finds basic information about a Circles token. This includes the creation timestamp, circles version, token type (human or group) and the address of the avatar that created the token.

const tokenInfo = await data.getTokenInfo("0x...");
if (tokenInfo) {
   console.log("Token is a Circles token");
} else {
   console.log("Token is not a Circles token");
}

Get total balance (v1, v2)

The total Circles balance of an avatar is the sum of all it's personalized and group token holdings. It can be queried with the getTotalBalance(avatar:string): Promise<string> method. There is a separate method for each Circles version.

const totalBalanceV1 = await data.getTotalBalance("0x...");
const totalBalanceV2 = await data.getTotalBalanceV2("0x...");

Get detailed token balances (v1, v2)

In contrast to the above method, the getTokenBalances(avatar: string): Promise<TokenBalanceRow[]> method gives a detailed overview of an avatar's Circles holdings. As with the method above, this one also exists for both versions of the Circles protocol.

The result row contains the token, balance and the tokenOwner.

const detailedCirclesBalancesV1 = await data.getTokenBalances("0x...");
const detailedCirclesBalancesV2 = await data.getTokenBalancesV2("0x...");

Get transaction history

The getTransactionHistory(avatar: string, pageSize: number): CirclesQuery<TransactionHistoryRow> method can be used to query all incoming and outgoing Circles transfers from and to an avatar. This includes minting and transfers of personal and group Circles for v1 and v2.

The result rows have the following properties:

• timestamp When the transaction happened

• transactionHash

• version If the transaction happened in Circles v1 or v2

• operator (the operator that facilitated the transaction - v2 only)

• from the sender address

• to the receiver address

• id in v1: the token address, in v2: the token id

• value the transferred raw value for the given version (bigint)

• timeCircles a floating point number representation of the value for display purposes

• tokenAddress an address representation of the numeric tokenid (v2) or the actual erc20 token address of a v1 personal token

const query = data.getTransactionHistory("0x...", 25);
const hasResults = await query.queryNextPage();
if (!hasResults) {
   console.log("No transactions yet");
   return;
}

const rows = query.currentPage.results;
rows.forEach(row => console.log(row));

The results are ordered in descending order.

Get trust relations

The getTrustRelations(avatar: string, pageSize: number): CirclesQuery<TrustListRow> method can be used to query the effective trust events for an avatar. Already expired or removed trust relations are omitted from the results.

const trustsQuery = data.getTrustRelations("0x...", 25);
const hasResults = await query.queryNextPage();
if (!hasResults) {
   console.log("No trust events yet");
   return;
}

const rows = query.currentPage.results;
rows.forEach(row => console.log(row));

Get aggregated trust relations

In contrast to the above method, this method queries all relevant trust events and groups mutual trust events into a single row instead of one for each direction.

The result rows have the following properties:

• subjectAvatar The acting avatar

• relation The relation between the acting avatar and the one it's related to

• objectAvatar The other avatar

The possible relations are: trusts, trustedBy, mutuallyTrusts, and selfTrusts. The last one (selfTrusts) exists because, in Circles, every avatar trusts itself.

const trustRelations = await data.getAggregatedTrustRelations("0x..");
trustRelations.forEach(row => console.log(row));

Find groups

Circles groups have a name and symbol that's stored on-chain. You can use the findGroups(pageSize: number, params: GroupQueryParams): CirclesQuery<GroupRow> method to find groups by name or symbol.

The params parameter can be used to filter and order the result set by the name and symbol of a group.

export interface GroupQueryParams {
  nameStartsWith?: string;
  symbolStartsWith?: string;
  groupAddressIn?: string[];
  sortBy?: 'age_asc' | 'age_desc' | 'name_asc' | 'name_desc' | 'symbol_asc' | 'symbol_desc';
}

Use the method as following:

const query = data.findGroups(25, {
  nameStartsWith: "Test",
});

const hasResults = await query.queryNextPage();
if (!hasResults) {
   console.log("No trust events yet");
   return;
}

const rows = query.currentPage.results;
rows.forEach(row => console.log(row));

Get group memberships

You can query the group memberships of an avatar using the getGroupMemberships(avatar: string, pageSize: number): CirclesQuery<GroupMembershipRow> method to get a list of all groups an avatar is a member of.

The result rows contain the following properties: group, member, expiryTime.

const query = data.getGroupMemberships("0x...", 25);
const hasResults = await query.queryNextPage();
if (!hasResults) {
   console.log("No trust events yet");
   return;
}

const rows = query.currentPage.results;
rows.forEach(row => console.log(row));

Get invited users

Avatars can invite others to join Circles. The getInvitations(avatar: string, pageSize: number): CirclesQuery<InvitationRow> method returns a list of invitations sent by the specified avatar.

Th e result rows contain the follwing properties: timestamp, transactionHash, inviter, invited.

const query = data.getInvitations("0x...", 25);
const hasResults = await query.queryNextPage();
if (!hasResults) {
   console.log("No trust events yet");
   return;
}

const rows = query.currentPage.results;
rows.forEach(row => console.log(row));

Get invited by

You can query who invited an other avatar by calling getInvitedBy(avatar:string): Promise<string|undefined>. If the avatar wasn't invited, the method returns undefined.

const invitedBy = await data.getInvitedBy("0x...");

The previously shown CirclesData class returns CirclesQuery<T> objects for all paged query results. You can execute custom queries against all tables in the Circles index and filter with them.

Write a query

First you'll need to define a query. The basic structure of a query is the same as for a basic SQL select. It has the following fields:

• namespace: Used to distinguish between tables and views as well and to tell the tables of the two Circles version apart from each other.

• table: The name of the table you want to query.

• columns: A list of column names you want to select.

• filter: A list of filter conditions that must be met.

• sortOrder: Can be 'asc' or 'desc'.

• limit: How many rows to return (max: 1000).

Here is a query that reads all avatars with type group. Other avatar types you can try are human and organization.

Define a row type

You can define a type for the rows of your query, or just go with any if the type doesn't matter.

If you want to specify a custom type, it must extend the EventRow type. The EventRow type contains the blockNumber, transactionIndex and logIndex fields which are required for pagination.

Execute the query

To execute the query definition, you'll need a CirclesRpc instance. Create one and pass the Circles rpc url to the constructor.

Then create a CirclesQuery<MyGroupType> instance.

Call getNextPage() to retrieve the first page of the result set. You can then access the results through the currentPage property. This property includes the results themselves, along with firstCursor, lastCursor, limit, size, and sortOrder.

Add computed columns

You can extend the CirclesQuery with computed columns. Computed columns are defined by a callback that takes in the row and returns a new value. Here we convert the value of the previously queried cidV0Digest field (which is originally a hex-string) to a CID in Qm.. format.

The new column should be added to the custom type.

Then you can execute the query just like you did before. The calculated column function will be executed for each row in a page.

1. getAvatar

Gets an avatar instance by its address.

getAvatar: (avatarAddress: string, subscribe?: boolean) => Promise<Avatar>

• Parameters:

  • avatarAddress: The avatar’s wallet address.

  • subscribe: Optional, whether to subscribe to avatar events.

• Returns: A Promise that resolves to an Avatar instance.

Usage Example:

const avatar = await sdk.getAvatar("0x123...abc");

2. acceptInvitation

Accepts an invitation to join Circles using either CID or Profile.

acceptInvitation: (inviter: string, cidV0: string) => Promise<AvatarInterface>;
//or
acceptInvitation: (inviter: string, profile: Profile) => Promise<AvatarInterface>;

• Parameters:

  • inviter: The address of the inviting avatar.

  • cidV0: The CIDv0 of the avatar’s metadata (or profile data).

• Returns: A Promise resolving to an AvatarInterface.

Usage Example:

await sdk.acceptInvitation("0xInviterAddress", "QmProfileCID");

3. registerHuman

Registers the connected wallet as a human avatar in Circles V1.

registerHuman: () => Promise<AvatarInterface>

• Returns: A Promise resolving to an AvatarInterface, representing the registered human avatar.

Usage Example:

const humanAvatar = await sdk.registerHuman();

4. registerOrganization

Registers the connected wallet as an organization avatar in Circles V1.

registerOrganization: () => Promise<AvatarInterface>

• Returns: A Promise resolving to an AvatarInterface for the organization avatar.

Usage Example:

const organizationAvatar = await sdk.registerOrganization();

5. registerOrganizationV2

Registers the connected wallet as an organization avatar in Circles V2 with profile data.

registerOrganizationV2: (profile: Profile) => Promise<AvatarInterface>

• Parameters:

  • profile: A Profile object representing the organization’s profile.

• Returns: A Promise resolving to an AvatarInterface.

Usage Example:

const orgProfile = { name: "OrgName", description: "An example organization." };
const orgAvatarV2 = await sdk.registerOrganizationV2(orgProfile);

6. registerGroupV2

Registers the connected wallet as a group avatar in Circles V2 with profile data.

registerGroupV2: (mint: string, profile: GroupProfile) => Promise<AvatarInterface>

• Parameters:

  • mint: Address of the minting policy contract.

  • profile: A GroupProfile object containing group information.

• Returns: A Promise resolving to an AvatarInterface.

Usage Example:

const groupProfile = { name: "GroupName", description: "An example group." };
const groupAvatarV2 = await sdk.registerGroupV2("0xMintAddress", groupProfile);

7. migrateAvatar

Migrates a V1 avatar and its Circles holdings to V2.

migrateAvatar: (avatar: string, profile: Profile, trustRelations?: string[]) => Promise<void>

• Parameters:

  • avatar: The address of the avatar to migrate.

  • profile: Profile data of the avatar.

  • trustRelations: Optional, a list of trust relations to migrate.

• Returns: A Promise resolving to void.

Usage Example:

const profile = { name: "John Doe", description: "Human Avatar" };
await sdk.migrateAvatar("0xAvatarAddress", profile);

8. createOrUpdateProfile

Creates or updates a user profile in Circles.

UpdateProfile: (profile: Profile | string) => Promise<ContractTransactionReceipt>

• Parameters:

  • profile: A Profile object or a CID string pointing to the profile.

• Returns: A Promise that resolves to a ContractTransactionReceipt.

Usage Example:

const profileData = { name: "John Doe", description: "Developer" };
const receipt = await sdk.createOrUpdateProfile(profileData);

9. migrateV1Tokens

Migrates all V1 token holdings of an avatar to V2.

migrateV1Tokens: (avatar: string, tokens?: string[]) => Promise<void>

• Parameters:

  • avatar: The avatar whose tokens need to be migrated.

  • tokens: Optional list of token addresses.

• Returns: A Promise resolving to void.

Usage Example:

await sdk.migrateV1Tokens("0xAvatarAddress");

10. getInflationaryWrapper

Gets an inflationary wrapper for managing tokens.

getInflationaryWrapper: (wrapperAddress: string) => Promise<InflationaryCircles>

• Parameters:

  • wrapperAddress: Address of the inflationary wrapper contract.

• Returns: A Promise resolving to InflationaryCircles.

Usage Example:

const inflationaryWrapper = await sdk.getInflationaryWrapper("0xWrapperAddress");

11. getDemurragedWrapped

This function retrieves a demurrage wrapper, which is used to manage tokens that decrease in value over time (demurrage).

getDemurragedWrapper: (wrapperAddress: string) => Promise<DemurrageCircles>

Parameters:

• wrapperAddress: The address of the demurrage wrapper contract.

Returns : A Promise that resolves to an instance of DemurrageCircles.

Usage Example:

const demurrageWrapper = await sdk.getDemurragedWrapper("0xWrapperAddress");

Base Event: CirclesBaseEvent

This is the base type for all Circles events. It contains common metadata for all events.

• $event: CirclesEventType — The event type, defining which event occurred.

• blockNumber: number — The block number in which the event was logged.

• timestamp: number (optional) — The timestamp when the event occurred.

• transactionIndex: number — Index of the transaction in the block.

• logIndex: number — Index of the log within the transaction.

• transactionHash: string (optional) — The hash of the transaction that emitted this event.

CrcV1_HubTransfer

Triggered when a transfer of Circles tokens happens via the Circles Hub.

• $event: 'CrcV1_HubTransfer'

• from: string (optional) — Address sending the tokens.

• to: string (optional) — Address receiving the tokens.

• amount: bigint (optional) — Amount of tokens transferred.

CrcV1_Signup

Triggered when a new user signs up in the Circles system.

• $event: 'CrcV1_Signup'

• user: string (optional) — Address of the new user.

• token: string (optional) — The token assigned to the user.

CrcV1_OrganizationSignup

Triggered when an organization signs up.

• $event: 'CrcV1_OrganizationSignup'

• organization: string (optional) — Address of the organization.

CrcV1_Trust

Emitted when a trust relationship is created.

• $event: 'CrcV1_Trust'

• canSendTo: string (optional) — The address that can receive tokens from the user.

• user: string (optional) — The user creating the trust.

• limit: bigint (optional) — The limit up to which the user can send tokens.

CrcV1_Transfer

Triggered when a token transfer occurs in the Circles V1 system.

• $event: 'CrcV1_Transfer'

• tokenAddress: string (optional) — Address of the token.

• from: string (optional) — Address sending the tokens.

• to: string (optional) — Address receiving the tokens.

• amount: bigint (optional) — Amount of tokens transferred.

CrcV2_InviteHuman

Triggered when a human is invited to Circles.

• $event: 'CrcV2_InviteHuman'

• inviter: string (optional) — Address of the inviter.

• invited: string (optional) — Address of the invited human.

CrcV2_PersonalMint

Triggered when a personal minting event occurs.

• $event: 'CrcV2_PersonalMint'

• human: string (optional) — Address of the human minting tokens.

• amount: bigint (optional) — Amount of tokens minted.

• startPeriod: bigint (optional) — Start of the minting period.

• endPeriod: bigint (optional) — End of the minting period.

CrcV2_RegisterGroup

Triggered when a group is registered.

• $event: 'CrcV2_RegisterGroup'

• group: string (optional) — Address of the group.

• mint: string (optional) — Address of the mint.

• treasury: string (optional) — Address of the treasury.

• name: string (optional) — Name of the group.

• symbol: string (optional) — Symbol for the group.

CrcV2_RegisterHuman

Triggered when a human registers in Circles.

• $event: 'CrcV2_RegisterHuman'

• avatar: string (optional) — Avatar of the registered human.

• inviter: string (optional) — Address of the inviter.

CrcV2_RegisterOrganization

Triggered when an organization is registered.

• $event: 'CrcV2_RegisterOrganization'

• organization: string (optional) — Address of the organization.

• name: string (optional) — Name of the organization.

CrcV2_Stopped

Triggered when an avatar stops its activity.

• $event: 'CrcV2_Stopped'

• avatar: string (optional) — Avatar that stopped.

CrcV2_Trust

Triggered when a trust relationship is established in Circles V2.

• $event: 'CrcV2_Trust'

• truster: string (optional) — The address of the truster.

• trustee: string (optional) — The address of the trustee.

• expiryTime: bigint (optional) — Expiry time of the trust relationship.

CrcV2_TransferSingle

Triggered during a single token transfer in Circles V2.

• $event: 'CrcV2_TransferSingle'

• operator: string (optional) — Address of the operator.

• from: string (optional) — Address sending the token.

• to: string (optional) — Address receiving the token.

• id: bigint (optional) — ID of the token being transferred.

• value: bigint (optional) — Value of the token transferred.

CrcV2_URI

Triggered when a token's URI is updated.

• $event: 'CrcV2_URI'

• value: string (optional) — The new URI value.

• id: bigint (optional) — ID of the token with the updated URI.

CrcV2_ApprovalForAll

Triggered when an account gives or revokes permission to an operator.

• $event: 'CrcV2_ApprovalForAll'

• account: string (optional) — The account giving or revoking permission.

• operator: string (optional) — The operator being granted or revoked permission.

• approved: boolean (optional) — Whether the approval was granted (true) or revoked (false).

CrcV2_TransferBatch

Triggered during a batch transfer in Circles V2.

• $event: 'CrcV2_TransferBatch'

• batchIndex: number — Index of the batch.

• operator: string (optional) — Address of the operator.

• from: string (optional) — Address sending the tokens.

• to: string (optional) — Address receiving the tokens.

• id: bigint (optional) — ID of the token being transferred.

• value: bigint (optional) — Value of the tokens transferred.

CrcV2_RegisterShortName

Triggered when a short name is registered to an avatar.

• $event: 'CrcV2_RegisterShortName'

• avatar: string (optional) — Avatar registering the short name.

• shortName: bigint (optional) — The registered short name.

• nonce: bigint (optional) — The nonce of the registration.

CrcV2_UpdateMetadataDigest

Triggered when an avatar's metadata digest is updated.

• $event: 'CrcV2_UpdateMetadataDigest'

• avatar: string (optional) — Avatar updating the metadata.

• metadataDigest: Uint8Array (optional) — The new metadata digest.

CrcV2_CidV0

Triggered when an avatar's CID (Content Identifier) for metadata is updated.

• $event: 'CrcV2_CidV0'

• avatar: string (optional) — Avatar updating the CID.

• cidV0Digest: Uint8Array (optional) — The new CID v0 digest.

CrcV2_StreamCompleted

Triggered when a streaming payment or data transfer is completed.

• $event: 'CrcV2_StreamCompleted'

• operator: string (optional) — Address of the operator.

• from: string (optional) — Address sending the streamed payment.

• to: string (optional) — Address receiving the streamed payment.

• id: bigint (optional) — ID of the streamed token.

• amount: bigint (optional) — Total amount streamed.

CrcV2_CreateVault

Triggered when a vault is created.

• $event: 'CrcV2_CreateVault'

• vault: string (optional) — Address of the vault.

• token: string (optional) — Address of the token stored in the vault.

Circles Data class provides various methods to query and interact with Circles' data, such as balances, transaction history, trust relations, group memberships, and avatar information. It is built around the Circles RPC to facilitate communication with the blockchain and retrieve relevant data. The CirclesData class exposes methods for both CRCv1 and CRCv2 tokens, trust events, and group information, as well as subscriptions to events.

1. getTotalBalance

Gets the total CRC V1 balance of an address.

getTotalBalance(avatar: string, asTimeCircles?: boolean): Promise<string>

Parameters:

• avatar: The address to get the CRC balance for.

• asTimeCircles (optional): Return the balance as TimeCircles or not (default is true).

Returns: A Promise<string> representing the total balance.

Usage Example:

const balance = await circlesData.getTotalBalance("0xAvatarAddress");

2. getTotalBalanceV2

Gets the total CRC V2 balance of an address.

getTotalBalanceV2(avatar: string, asTimeCircles?: boolean): Promise<string>

Parameters:

• avatar: The address to get the CRC balance for.

• asTimeCircles (optional): Return the balance as TimeCircles or not (default is true).

Returns: A Promise<string> representing the total balance.

Usage Example:

const balanceV2 = await circlesData.getTotalBalanceV2("0xAvatarAddress");

3. getTokenBalances

Gets the detailed token balances of an address.

getTokenBalances(avatar: string): Promise<TokenBalanceRow[]>

Parameters:

• avatar: The address to get the token balances for.

Returns: A Promise<TokenBalanceRow[]> containing the token balances.

Usage Example:

const balances = await circlesData.getTokenBalances("0xAvatarAddress");

4. getTransactionHistory

Gets the transaction history of an address (incoming/outgoing transactions and CRC minting).

getTransactionHistory(avatar: string, pageSize: number): CirclesQuery<TransactionHistoryRow>

Parameters:

• avatar: The address to get the transaction history for.

• pageSize: The maximum number of transactions per page.

Returns: A CirclesQuery<TransactionHistoryRow> object.

Usage Example:

const history = await circlesData.getTransactionHistory("0xAvatarAddress", 10);

5. getTrustRelations

Gets the current incoming and outgoing trust relations of an address.

getTrustRelations(avatar: string, pageSize: number): CirclesQuery<TrustListRow>

Parameters:

• avatar: The address to get the trust list for.

• pageSize: The maximum number of trust relations per page.

Returns: A CirclesQuery<TrustListRow> object.

Usage Example:

const trustRelations = await circlesData.getTrustRelations("0xAvatarAddress", 10);

6. getAggregatedTrustRelations

Gets all trust relations of an avatar and groups mutual trust relations together.

getAggregatedTrustRelations(avatarAddress: string): Promise<TrustRelationRow[]>

Parameters:

• avatarAddress: The address to get the trust relations for.

Returns: A Promise<TrustRelationRow[]> representing the trust relations.

Usage Example:

const aggregatedTrust = await circlesData.getAggregatedTrustRelations("0xAvatarAddress");

7. getAvatarInfo

Gets basic information about an avatar.

getAvatarInfo(avatar: string): Promise<AvatarRow | undefined>

Parameters:

• avatar: The address to check.

Returns: A Promise<AvatarRow | undefined> with the avatar info or undefined if not found.

Usage Example:

const avatarInfo = await circlesData.getAvatarInfo("0xAvatarAddress");

8. getAvatarInfos

Gets basic information about multiple avatars.

getAvatarInfos(avatars: string[]): Promise<AvatarRow[]>

Parameters:

• avatars: The addresses to check.

Returns: A Promise<AvatarRow[]> containing avatar information.

Usage Example:

const avatarInfos = await circlesData.getAvatarInfos(["0xAvatar1", "0xAvatar2"]);

9. getTokenInfo

Gets the token info for a given token address.

getTokenInfo(address: string): Promise<TokenInfoRow | undefined>

Parameters:

• address: The address of the token.

Returns: A Promise<TokenInfoRow | undefined> with the token info or undefined if not found.

Usage Example:

const tokenInfo = await circlesData.getTokenInfo("0xTokenAddress");

10. subscribeToEvents

Subscribes to Circles events.

subscribeToEvents(avatar?: string): Promise<Observable<CirclesEvent>>

Parameters:

• avatar (optional): The avatar to subscribe to. If not provided, all events are subscribed to.

Returns: A Promise<Observable<CirclesEvent>> representing the event stream.

Usage Example:

const eventStream = await circlesData.subscribeToEvents("0xAvatarAddress");

11. getEvents

Gets the events for a given avatar in a block range.

getEvents(avatar?: string, fromBlock?: number, toBlock?: number, eventTypes?: string[], filters?: FilterPredicate[], sortAscending?: boolean): Promise<CirclesEvent[]>

Parameters:

• avatar (optional): The avatar to get the events for.

• fromBlock (optional): The starting block number.

• toBlock (optional): The ending block number.

• eventTypes (optional): Types of events to filter.

• filters (optional): Additional filter criteria.

• sortAscending (optional): Whether to sort events in ascending order.

Returns: A Promise<CirclesEvent[]> representing the events.

Usage Example:

const events = await circlesData.getEvents("0xAvatarAddress", 0, 100, ["Transfer"], [], true);

12. getInvitations

Gets the invitations sent by an avatar.

getInvitations(avatar: string, pageSize: number): CirclesQuery<InvitationRow>

Parameters:

• avatar: The avatar to get the invitations for.

• pageSize: The maximum number of invitations per page.

Returns: A CirclesQuery<InvitationRow> object.

Usage Example:

const invitations = await circlesData.getInvitations("0xAvatarAddress", 10);

13. getInvitedBy

Gets the avatar that invited the given avatar.

getInvitedBy(avatar: string): Promise<string | undefined>

Parameters:

• avatar: The address of the invited avatar.

Returns: A Promise<string | undefined> with the address of the inviting avatar or undefined if not found.

Usage Example:

const inviter = await circlesData.getInvitedBy("0xAvatarAddress");

14. findGroups

Gets the list of groups.

findGroups(pageSize: number, params?: GroupQueryParams): CirclesQuery<GroupRow>

Parameters:

• pageSize: The maximum number of groups per page.

• params (optional): Query parameters to filter groups.

Returns: A CirclesQuery<GroupRow> object.

Usage Example:

const groups = await circlesData.findGroups(10, { name: "ExampleGroup" });

15. getGroupMemberships

Gets the group memberships of an avatar.

getGroupMemberships(avatar: string, pageSize: number): CirclesQuery<GroupMembershipRow>

Parameters:

• avatar: The avatar to get the group memberships for.

• pageSize: The maximum number of group memberships per page.

Returns: A CirclesQuery<GroupMembershipRow> object.

Usage Example:

const memberships = await circlesData.getGroupMemberships("0xAvatarAddress", 10);

16. getMetadataCidForAddress

Gets the metadata CID for an address.

getMetadataCidForAddress(address: string): Promise<string | undefined>

Parameters:

• address: The address to get the metadata CID for.

Returns: A Promise<string | undefined> with the CID or undefined if not found.

Usage Example:

const metadataCid = await circlesData.getMetadataCidForAddress("0xAddress");

Here are some of the past hackathon projects built with Circles. You can use these as a reference or to get inspiration of what kind of applications to build.

1. EthGlobal Brussels 2024

BraceBuddy allows to onboard easily and in a fun way people to the Circles ecosystem with NFC!

Woleth is an easy to use EVM wallet embed into Telegram designed to build a Social Graph utilizing Circle's invite mechanism.

Famjam is a dapp that uses Circles to create a family currency to incentivize kids for good behaviour.

2. EthGlobal Singapore 2024

Voting with UBI is a dapp which implements a voting mechanism for DAOs by utilizing Circles group tokens.

ERC-1155

ERC-1155 is an Ethereum token standard that enables the efficient transfer and bundling of multiple fungible and non-fungible tokens in a single transaction. This multi-token standard allows for the creation of complex token systems, such as those used in gaming or supply chain management, where different types of tokens need to be managed simultaneously.

The standard introduces a new set of functions, including safeTransferFrom, safeBatchTransferFrom, and balanceOfBatch, which allow for the transfer and querying of multiple token balances in a single call. This reduces gas costs and simplifies token management compared to using multiple ERC-20 or ERC-721 contracts.

ERC-1155 tokens are identified by a unique combination of an address and an ID, allowing for the creation of an unlimited number of token types within a single contract. The standard also includes an optional metadata extension, enabling developers to associate additional information, such as images or descriptions, with each token type.

See also:

Externally-Owned Account

An externally-owned account (also known as EOA) is one of the two types of Ethereum accounts. A private key controls it; it has no code, and users can send messages by creating and signing Ethereum transactions.

See also:

Gasless Transaction

See also:

Network

A blockchain network is a collection of interconnected computers that utilize a blockchain protocol for communication. Decentralized networks allow users to send transactions, that are processed on a distributed ledger with a consensus mechanism ensuring the batching, verification, and acceptance of data into blocks. This structure enables the development of applications without the need for a central authority or server.

See also:

Owner

See also:

Relayer

See also:

Safe Wallet

Safe is a smart contract wallet that requires a minimum number of people to approve a transaction before it can occur (M-of-N). If for example you have 3 main stakeholders in your business, you are able to set up the wallet to require approval from 2 out of 3 (2/3) or all 3 people before the transaction is sent. This assures that no single person could compromise the funds.

See also:

Smart Account

Some common features that smart accounts offer to their users are:

• Multi-signature scheme

• Transaction batching

• Account recovery

Safe is one of the most trusted implementations of a smart account.

Transaction

See also:

Threshold

The threshold of a Safe account is a crucial configuration element that enables using Safe as a multi-signature smart account. It defines the number of required confirmations from the Safe owners a (Safe) transaction must have to be executable.

See also:

Wallet

A wallet is an interface or application that gives users control over their blockchain account. Wallets allow users to sign in to applications, read their account balance, send transactions, and verify their identity.

See also:

The Circles SDK provides a high-level interface for interacting with the Circles protocol, focusing on features like user profiles, avatars, token transfers, and contract interactions. It integrates with Circles V1 and V2 hubs, and enables registration, migration, and management of avatars and profiles.

Class: Sdk

This class implements the SdkInterface, which provides core functionality to interact with the Circles protocol.

The Sdk class implements the following interface:

Constructor

• Parameters:

  • contractRunner: An instance of SdkContractRunner, which is responsible for signing transactions.

  • config: Optional, an instance of CirclesConfig, containing chain-specific configurations (addresses and endpoints).

Additional Modules Used

• Avatar: Represents the Circles avatar with methods for interacting with its state.

• CirclesConfig: Holds chain-specific configurations such as contract addresses and RPC endpoints.

• Pathfinder: Provides routing for token transfers on the Circles network.

• Profiles: Manages avatar profiles within Circles.

• ContractTransactionReceipt: Used to manage transactions and their receipts on the Ethereum blockchain.