npm package: @ingocollatz/sdk
Description: some bla
Latest version: 0.0.53

# 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](#installation)
- [Overview](#overview)
- [Getting Started](#getting-started)
- [Methods](#methods)
  - [`nethermindRpc`](#nethermindrpc)
  - [`fetchTransactionHistory`](#fetchtransactionhistory)
  - [`trust`](#trust)
  - [`getSafeBalance`](#getsafebalance)
  - [`mintUbi`](#mintubi)
  - [`transferUbi`](#transferubi)
  - [`signupPerson`](#signupperson)
  - [`signupOrganization`](#signuporganization)

## Installation

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

```bash
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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.