CirclesSDK Documentation

The CirclesSDK provides a comprehensive and convenient interface to interact with the Circles Universal Basic Income (UBI) protocol. With this SDK, developers can seamlessly integrate the functionality of the Circles UBI protocol into their applications.

Table of Contents

• Installation
• Overview
• Getting Started
• Methods
  • nethermindRpc
  • fetchTransactionHistory
  • trust
  • getSafeBalance
  • mintUbi
  • transferUbi
  • signupPerson
  • signupOrganization

Installation

To get started with the CirclesSDK, ensure that you've installed the SDK package via your favorite package manager.

yarn add @ingocollatz/circles-sdk

Overview

The SDK exposes a CirclesSdk class that encapsulates various functionalities of the Circles UBI protocol:

• Fetching balances and transaction history.
• Executing transactions and handling Safe transactions.
• Managing trust relations.
• Minting UBI tokens.
• Transferring UBI tokens.
• Signing up as a person or organization on the Circles Hub.

Getting Started

Initialize the CirclesSdk class by providing the necessary dependencies:

import { CirclesSdk } from "@ingocollatz/circles-sdk";

const sdk = new CirclesSdk(safeInstance, abiEncoderInstance);

Where safeInstance is an instance of the Safe and abiEncoderInstance is the ABI Encoder required for encoding contract call data.

Methods

nethermindRpc({ method, params })

Makes a JSON-RPC call to the Nethermind node using a specified method and parameters.

This feature is still under development and only returns hex strings as balances. It will be updated to return the correct data types in the future.

Parameters:

• method: The RPC method to be called. Possible methods include:
  • "circles_getTotalBalance"
  • "circles_getTokenBalances"
  • "circles_getTrustRelations"
  • "circles_getHubTransfers"
  • "circles_getCrcTransfers"

Returns:

The result from the RPC call.

Example:

const result = await sdk.nethermindRpc({
  method: "circles_getTotalBalance",
  params: ["0xYourAddressHere"],
});
console.log(result);

fetchTransactionHistory({ limit, offset, type, lastUbiPayout, trustConnections, unit })

Fetches the transaction history of a Safe based on the provided filtering criteria.

Returns:

A list of transaction notifications.

Example:

const history = await sdk.fetchTransactionHistory({
  limit: 10,
  offset: 0,
  type: "TRANSFER",
  unit: "tc"
});
console.log(history);

trust(address, limit)

Establishes a trust relationship between the current user's address and another provided address.

Returns:

A transaction receipt upon successful trust establishment.

Examples:

Using Ethers:

import { ethers } from "ethers";
import { CirclesSdkEthersFactory } from "@ingocollatz/sdk-ethers-adapter";
const provider = new ethers.providers.JsonRpcProvider(SdkConfig._rpcUrl);
const signerAddress = new ethers.Wallet(PRIVATE_KEY_1, provider);
const circlesSdk = await CirclesSdkEthersFactory.withExistingSafe(
  ethers,
  signerAddress,
  SAFE_ADDRESS_ORGANIZATION
);
circlesSdk.trust(address, limit);

Using Web3:

import Web3 from "web3";
import HDWalletProvider from "@truffle/hdwallet-provider";
import { CirclesSdkWeb3Factory } from "@ingocollatz/sdk-web3-adapter";
const web3 = new Web3();
const provider = new HDWalletProvider({
  privateKeys: [PRIVATE_KEY_1.slice(2)],
  providerOrUrl: SdkConfig._rpcUrl,
});
web3.setProvider(<any>provider);
const signerAddress = provider.getAddress();
const circlesSdk = await CirclesSdkWeb3Factory.withExistingSafe(web3, signerAddress, SAFE_ADDRESS_ORGANIZATION);
circlesSdk.trust(address, limit);
provider.engine.stop();

getSafeBalance({ unit })

Fetches the CRC balance of a Safe from the Circles UBI subgraph.

Returns:

The total balance of the Safe and balances of each token held by the Safe.

Examples:

Using Ethers:

import { CirclesSdk } from "@ingocollatz/circles-sdk";
import { EthersAbiEncoder } from "@ingocollatz/sdk-ethers-adapter";
import { ethers } from "ethers";
import { EthersAdapter } from "@safe-global/protocol-kit";

const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
const safe = await Safe.create({
  ethAdapter: new EthersAdapter({
    ethers,
    signerOrProvider: provider,
  }),
  safeAddress: SAFE_ADDRESS_USER,
});
const abiEncoder = new EthersAbiEncoder();
const circlesSdk = new CirclesSdk(safe, abiEncoder);
const safeBalance = await circlesSdk.getSafeBalance({ unit: "tc" });

console.log(`Safe balance for ${SAFE_ADDRESS_USER}: `, safeBalance);

Using Web3:

import { CirclesSdk } from "@ingocollatz/circles-sdk";
import Web3 from "web3";
import Safe, { Web3Adapter } from "@safe-global/protocol-kit";
import { Web3AbiEncoder } from "@ingocollatz/sdk-web3-adapter";

const web3 = new Web3(new Web3.providers.HttpProvider(RPC_URL));
const safe = await Safe.create({
  ethAdapter: new Web3Adapter({
    web3: new Web3(new Web3.providers.HttpProvider(RPC_URL)),
    signerAddress: PUBLIC_KEY_1,
  }),
  safeAddress: SAFE_ADDRESS_USER,
});
const abiEncoder = new Web3AbiEncoder(web3);
const circlesSdk = new CirclesSdk(safe, abiEncoder);
const safeBalance = await circlesSdk.getSafeBalance({ unit: "tc" });

console.log(`Safe balance for ${SAFE_ADDRESS_USER}: `, safeBalance);

mintUbi()

Mints UBI tokens for the user.

Returns:

A transaction receipt upon successful minting.

Examples:

Using Web3:

import Web3 from "web3";
import HDWalletProvider from "@truffle/hdwallet-provider";
import { PRIVATE_KEY_1, SAFE_ADDRESS_USER } from "../config";
import { CirclesSdkWeb3Factory } from "@ingocollatz/sdk-web3-adapter";

const web3 = new Web3();
const provider = new HDWalletProvider({
  privateKeys: [PRIVATE_KEY_1.slice(2)],
  providerOrUrl: SdkConfig._rpcUrl,
});

web3.setProvider(<any>provider);
const signerAddress = provider.getAddress();
const circlesSdk = await CirclesSdkWeb3Factory.withExistingSafe(web3, signerAddress, SAFE_ADDRESS_USER);
circlesSdk.mintUbi();
provider.engine.stop();

Using Ethers:

import { ethers } from "ethers";
import { PRIVATE_KEY_1, SAFE_ADDRESS_USER } from "../config";
import { CirclesSdkEthersFactory } from "@ingocollatz/sdk-ethers-adapter";

const provider = new ethers.providers.JsonRpcProvider(SdkConfig._rpcUrl);
const signerAddress = new ethers.Wallet(PRIVATE_KEY_1, provider);
const circlesSdk = await CirclesSdkEthersFactory.withExistingSafe(
  ethers,
  signerAddress,
  SAFE_ADDRESS_USER
);
circlesSdk.mintUbi();

Returns:

A transaction receipt upon successful minting.

transferUbi(senderSafeAddress, recipientSafeAddress, amount)

Transfers UBI tokens between two Safes.

Returns:

A transaction receipt upon successful transfer.

Examples:

Using Ethers:

import { ethers } from "ethers";
import {
  PRIVATE_KEY_1,
  SAFE_ADDRESS_ORGANIZATION,
  SAFE_ADDRESS_USER,
} from "../config";
import { CirclesSdkEthersFactory } from "@ingocollatz/sdk-ethers-adapter";
import { tcToCrc } from "@circles/timecircles";
import { SdkConfig } from "@ingocollatz/sdk";

const provider = new ethers.providers.JsonRpcProvider(SdkConfig._rpcUrl);
const signerAddress = new ethers.Wallet(PRIVATE_KEY_1, provider);
const senderSafeAddress = SAFE_ADDRESS_USER;
const recipientSafeAddress = SAFE_ADDRESS_ORGANIZATION;
const tcAmount = "1";
const crcAmount = tcToCrc(Date.now(), parseFloat(tcAmount));
const mintAmountInWei = ethers.utils.parseUnits(crcAmount.toString(), 18).toString();

const circlesSdk = await CirclesSdkEthersFactory.withExistingSafe(ethers, signerAddress, senderSafeAddress);
circlesSdk.transferUbi(senderSafeAddress, recipientSafeAddress, mintAmountInWei);

Using Web3:

import Web3 from "web3";
import HDWalletProvider from "@truffle/hdwallet-provider";
import {
  PRIVATE_KEY_1,
  SAFE_ADDRESS_ORGANIZATION,
  SAFE_ADDRESS_USER,
} from "../config";
import { tcToCrc } from "@circles/timecircles";
import { CirclesSdkWeb3Factory } from "@ingocollatz/sdk-web3-adapter";
import { SdkConfig } from "@ingocollatz/sdk";

const web3 = new Web3();
const provider = new HDWalletProvider({
  privateKeys: [PRIVATE_KEY_1.slice(2)],
  providerOrUrl: SdkConfig._rpcUrl,
});
web3.setProvider(<any>provider);
const safeSigner = provider.getAddress();
const senderSafeAddress = SAFE_ADDRESS_USER;
const recipientSafeAddress = SAFE_ADDRESS_ORGANIZATION;
const tcAmount = "1";
const crcAmount = tcToCrc(Date.now(), parseFloat(tcAmount));
const mintAmountInWei = web3.utils.toWei(crcAmount.toString(), "ether");

const CirclesSdk = await CirclesSdkWeb3Factory.withExistingSafe(web3, safeSigner, senderSafeAddress);
CirclesSdk.transferUbi(senderSafeAddress, recipientSafeAddress, mintAmountInWei);

provider.engine.stop();

This section contains the description and examples of how to use the transferUbi method with both ethers.js and web3js.

Returns:

A transaction receipt upon successful transfer.

signupPerson()

Registers the user as a person within the hub.

Returns:

A transaction receipt upon successful signup.

signupOrganization()

Registers the user as an organization within the hub.

Returns:

A transaction receipt upon successful signup.