circles-core

Common methods to interact with the Circles ecosystem

API Docs | Handbook | Releases | Contributing

This library provides common methods for JavaScript clients and wallets to interact with the circles-contracts and off-chain services.

Features

• Interact with circles-contracts and off-chain services like safe-relay-service, graph and circles-api
• Register and maintain user accounts and organizations
• Create and search off-chain data like transfer descriptions, usernames and profile pictures
• Trust other users in the network and retreive trust network
• List owned Circles tokens and their current balance
• Show last activities like transfers, trusts and Safe ownership changes
• Calculate transitive transfer steps to send Circles
• Update the Version of the Safe contract to v1.3.0

Example

import CirclesCore from '@circles/core';
import Web3 from 'web3';

// Initialize web3
const web3 = new Web3();

// Initialize core with default configs when running against local `circles-docker` setup
const core = new CirclesCore(web3, {
  hubAddress: '0xCfEB869F69431e42cdB54A4F4f105C19C080A601',
  proxyFactoryAddress: '0x9b1f7F645351AF3631a656421eD2e40f2802E6c0',
  safeMasterAddress: '0x59d3631c86BbE35EF041872d502F218A39FBa150',
  apiServiceEndpoint: 'http://api.circles.local',
  pathfinderServiceEndpoint: 'http://pathfinder.circles.local',
  pathfinderType: 'server', // other option: 'cli'
  graphNodeEndpoint: 'http://graph.circles.local',
  databaseSource: 'graph',
  relayServiceEndpoint: 'http://relay.circles.local',
  subgraphName: 'circlesubi/circles-subgraph',
  fallbackHandlerAddress: '0x67B5656d60a809915323Bf2C40A8bEF15A152e3e',
});

// Create existing account from private key which owns a Safe
const account = web3.eth.accounts.privateKeyToAccount('0x...');

// Find out the address of the owned Safe
const [safeAddress] = await core.safe.getAddresses(account, {
  ownerAddress: account.address,
});

// Request Circles UBI payout
await core.token.requestUBIPayout(account, {
  safeAddress,
});

Installation

npm i @circles/core

Make sure you have all peer dependencies isomorphic-fetch and web3 installed as well. Check out the circles-docker repository for running your code locally against Circles services during development.

Development

circles-core is a JavaScript module, tested with Jest, transpiled with Babel and bundled with Rollup. Most of the tests are designed to test end-to-end against all external services and require a running circles-docker environment to work in your development setup.

# Install NodeJS dependencies
npm install

# Copy config file and edit variables according to your needs.
# When running against the default docker setup no changes are required here
cp .env.example .env

# Run e2e test suite. Make sure services are running in the background
# via `circles-docker` repository
npm run test

# Run tests automatically during development when changes have been made
npm run test:watch

# Check code formatting
npm run lint

# Build it!
npm run build

License

GNU Affero General Public License v3.0 AGPL-3.0