Quickstart Guide for Circles SDK
This guide will help you get started with the Circles SDK. It shows how to use the Circles SDK with MetaMask.
Last updated
Was this helpful?
This guide will help you get started with the Circles SDK. It shows how to use the Circles SDK with MetaMask.
Last updated
Was this helpful?
Prerequisites
Browser wallet such as Metamask or Rabby Wallet
Setup or add as your network for wallet. Check out Gnosis Chain docs .
Some xDAI token for paying gas fees. Check out Faucet
If you have all prerequisites in place, start by installing the Circles SDK package and ethers v6 in your project using npm.
Then, import the necessary interfaces from the Circles SDK and Ethers.
circlesConfig
: Contains predefined configurations, such as contract addresses for different environments (production version).
Sdk
: The main Circles SDK class, which provides methods to interact with the protocol, including token transfers, trust relationships, and contract interactions.
Since we are using browser-based wallets like Rabby and MetaMask, we will import the BrowserProviderContractRunner
adapter, which connects the Circles SDK with Ethers.js, enabling smart contract interactions through a browser-based Ethereum provider.
CirclesConfig
for SDKCirclesConfig
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 for production and sandbox version. You need to specify the correct contract addresses and service endpoints for each environment.
v2PathfinderUrl
The URL for the V2 Pathfinder service (if using V2).
pathfinderUrl
The URL for the Pathfinder service (used in V1).
circlesRpcUrl
The URL for the Circles RPC service
profileServiceUrl
The URL for the profile service that manages user profiles in Circles.
v1HubAddress
The contract address for the Circles V1 Hub.
v2HubAddress?
The contract address for the Circles V2 Hub.
nameRegistryAddress
The address of the name registry contract.
migrationAddress
The address used for migrating avatars and tokens from V1 to V2.
baseGroupMintPolicy
The address of the minting policy used for group avatars in Circles.
coreMemberGroupDeployer
Circles contracts are deployed on Gnosis Chain mainnet. The below config is for applications that would be built in production environment.
Circles contracts are deployed on the Gnosis Chain mainnet. The following configuration is intended for production-ready applications.
You can seamlessly import the production-ready smart contract addresses directly from the Circles SDK, as they are already hardcoded within the SDK.
The circlesConfig
object provides predefined contract addresses and service endpoints required for seamless integration with Circles on Gnosis Chain. It adheres to the CirclesConfig
type from the Circles SDK.
CirclesConfig
type from Circles SDK along with deployed contracts:RINGS is a sandbox version of the Circles protocol designed for testing the Circles SDK without worrying about production requirements. If you are a builder or developer working on Circles for a hackathon and want to understand how the overall mechanics function, this is the place to start.
The only change you need to make to your codebase is updating the Circles configuration addresses to the sandbox contract addresses.
Once you have configured the sandbox addresses in your config.ts
,you can proceed with setting up the provider and signer as mentioned below.
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.
To initialize the CirclesSDK, we will pass on the circlesConfig
and Adapter
to SDK instance.
Once you have successfully created a SDK instance, you are all set to use Circles in your dApp.
To quickly summarize how the entire setup of Circles SDK would look like if you are writing a script etc.
If you are building dApps on Circles SDK for hackathon or want to check sandbox deployments, then follow to setup sandbox configuration for using the SDK.
Voila you're done with Circles SDK setup. Now, you can support Circles profiles and choose the Avatars that you would like to integrate and support their additional functions.
Personal / Human Avatars
ERC-1155 standard avatars, which allows you to mint your personal Circles token (CRC) every hour, accumulating 24 CRC per day with an applied demurrage of 7%.
Group Avatars
Created by an owner, these avatars allow groups to trust human avatars within the group. Group tokens are utilized by collateralizing personal tokens, following the ERC-1155 standard.
Organization Avatars
As an organization, you are an avatar without any minting of new tokens. With your name and metadata file, which will be used for identification and can trust other avatars to receive Circles, with all owned Circles earned by avatars rather than minted.