Circles SDK Overview

The Circles SDK is a TypeScript library that allows you to integrate Circles protocol into your dApp to implement avatars, profiles, token transfers and build trust connections for your use-case. In backend, Circles SDK utilizes deployed hub contracts on Gnosis Chain, pathfinder for finding trust network paths and profile service.

As a developer, you can start from installing the core 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

Package	Purpose	Why Use It
@circles-sdk/abi-v1	Provides the ABI for Circles V1 contracts.	Interact with Circles V1 smart contracts for transfers, minting, and managing trust relations.
@circles-sdk/abi-v2	Provides the ABI for Circles V2 contracts.	Interact with Circles V2 smart contracts for advanced features like group avatars, inflationary/demurrage tokens.
@circles-sdk/data	Wrapper around the Circles RPC Query API.	Query Circles-related data (balances, trust relationships, transaction histories) without direct contract interaction.
@circles-sdk/profiles	Manages Circles avatar profiles (human, group, organization).	Retrieve and store avatar profiles, manage trust relations, and handle identity in the Circles ecosystem.
@circles-sdk/adapter-ethers	Adapter to connect Circles SDK with Ethers.js.	Leverage Ethers.js for signing and sending transactions, connecting to wallets, and interacting with contracts.
ethers	Library for interacting with Ethereum-based blockchains.	Simplify blockchain interactions like sending transactions, querying data, and working with smart contracts. We would be using ethers v6 version for Circles SDK.
multihashes	Handles multihash algorithms for decentralized file storage.	Ensure compatibility with IPFS and manage content-addressable storage for file integrity in decentralized systems.

Notes for Developers

• The SDK uses ethers.js v6 for Ethereum interactions. Make sure, you are using Ethers V6 in your actual project as well to avoid compatibility issues.

• Some features are specific to either v1 or v2 of the Circles protocol such as kind of avatars that exist on hub contract.

• The SDK includes TypeScript definitions for improved developer experience and type safety.

• When working with CIDs, the SDK provides utilities for handling both the raw bytes and base58-encoded formats.