πŸš€Getting started with the SDK

This guide will help you get started with the Circles SDK. It shows how to use the Circles SDK with MetaMask.

1. Prerequisites

Install MetaMask and add Gnosis Chain & Chiado testnet

You'll need the MetaMask Plug-In installed in your browser: https://metamask.io/

Once installed, you can check out the official gnosis chain docs to get ChainID and RPC URL. Or you can quickly utilise the deep link for Gnosis mainnet and Chiado testnet .

You should use Chiado if you want to test a preview version of Circles v2. If you want to build with Circles v1, use Gnosis Chain instead.

Get some xDAI for paying gas fees

To send transactions you will need a small amount of xDai in order to pay for gas fees. You can get get xDAI tokens from mainnet and testnet faucet, depending on the need.

2. Install packages

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

  • npm i ethers

  • npm i @circles-sdk/sdk@0.4.0 @circles-sdk/data@0.4.0

2. Add imports

Then, import the necessary classes from the Circles SDK and ethers.

import {Sdk, ChainConfig, SdkContractRunner} from "@circles-sdk/sdk";
import {BrowserProvider} from "ethers";

3. Chain specific configuration

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

Choose from the following options, and copy & paste the selected chainConfig to your code.

The Gnosis Chain mainnet is the production chain for Circles. It currently only has the v1 contracts deployed.

const chainConfig: ChainConfig = {
    pathfinderUrl: 'https://pathfinder.aboutcircles.com',
    circlesRpcUrl: "https://rpc.helsinki.aboutcircles.com",
    v1HubAddress: "0x29b9a7fbb8995b2423a71cc17cf9810798f6c543"
};

4. Create a contract runner

A SdkContractRunner represents a way for the Sdk to sign messages and send them to the chain.

For the purpose of this guide, we'll show you two variants. One uses the window.ethereum object (as provided e.g. by MetaMask), the other uses a private key hex string.

Here's how you can create one from the window.ethereum object that MetaMask provides.

async function getRunner() : Promise<SdkContractRunner> {
    const w: any = window;
    const browserProvider = new BrowserProvider(w.ethereum);
    const signer = await browserProvider.getSigner();
    const address = await signer.getAddress();
    
    return {
        runner: signer,
        address: address
    };
}

5. Initialize the Circles SDK

It's time to initialize the SDK using the ChainConfig and SdkContractRunner objects from above.

async function getSdk() {
    const runner = await getRunner();
    return new Sdk(chainConfig, runner);
}

6. Use the SDK

You can now create an instance of the SDK by calling getSdk(). If you're using React you can e.g. store this instance in a Context to make it available in your application.

const sdk = await getSdk();

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.

Full example

Here's the full code for Svelte and React for you to copy & paste:

<script lang="ts">
    import {Sdk, type ChainConfig, type SdkContractRunner} from "@circles-sdk/sdk";
    import {BrowserProvider} from "ethers";
    import {onMount} from "svelte";

    let avatarAddress = "0xb235B56b91eccb9DbdF811D7b5C45c363AcaE98D";
    let avatarType = "";

    const chainConfig: ChainConfig = {
        pathfinderUrl: 'https://pathfinder.aboutcircles.com',
        circlesRpcUrl: "https://rpc.helsinki.aboutcircles.com",
        v1HubAddress: "0x29b9a7fbb8995b2423a71cc17cf9810798f6c543"
    };

    async function getRunner(): Promise<SdkContractRunner> {
        const w: any = window;
        const browserProvider = new BrowserProvider(w.ethereum);
        const signer = await browserProvider.getSigner();
        const address = await signer.getAddress();

        return {
            runner: signer,
            address: address
        };
    }

    async function getSdk() {
        const runner = await getRunner();
        return new Sdk(chainConfig, runner);
    }

    onMount(async () => {
        const sdk = await getSdk();
        const avatar = await sdk.getAvatar(avatarAddress);

        avatarType = avatar.avatarInfo?.type;
    });
</script>
<p>
    Avatar {avatarAddress} is {avatarType}
</p>

Last updated