-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into travis-migration-to-github-actions
- Loading branch information
Showing
5 changed files
with
174 additions
and
226 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Changelog | ||
| All notable changes to this project will be documented in this file. | ||
|
|
||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Lines starting with '#' are comments. | ||
| # Each line is a file pattern followed by one or more owners. | ||
|
|
||
| # These owners will be the default owners for everything in the repo. | ||
| * @adzialocha |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,246 +1,158 @@ | ||
| # Circles Core | ||
| <div align="center"> | ||
| <img width="80" src="https://raw.githubusercontent.com/CirclesUBI/.github/main/assets/logo.svg" /> | ||
| </div> | ||
|
|
||
| <p> | ||
| <a href="https://badge.fury.io/js/%40circles%2Fcore"> | ||
| <img src="https://badge.fury.io/js/%40circles%2Fcore.svg" alt="npm Version" height="18"> | ||
| <h1 align="center">circles-core</h1> | ||
|
|
||
| <div align="center"> | ||
| <strong> | ||
| Common methods to interact with the Circles ecosystem | ||
| </strong> | ||
| </div> | ||
|
|
||
| <br /> | ||
|
|
||
| <div align="center"> | ||
| <!-- npm --> | ||
| <a href="https://www.npmjs.com/package/@circles/core"> | ||
| <img src="https://img.shields.io/npm/v/@circles/core?style=flat-square&color=%23f14d48" height="18"> | ||
| </a> | ||
| <!-- Licence --> | ||
| <a href="https://github.com/CirclesUBI/circles-core/blob/main/LICENSE"> | ||
| <img src="https://img.shields.io/badge/license-APGLv3-orange.svg" alt="License" height="18"> | ||
| <img src="https://img.shields.io/github/license/CirclesUBI/circles-core?style=flat-square&color=%23cc1e66" alt="License" height="18"> | ||
| </a> | ||
| <a href="https://travis-ci.com/CirclesUBI/circles-core"> | ||
| <img src="https://api.travis-ci.com/CirclesUBI/circles-core.svg?branch=main" alt="Build Status" height="18"> | ||
| <!-- CI status --> | ||
| <a href="https://github.com/CirclesUBI/circles-core/actions/workflows/tests.yml"> | ||
| <img src="https://img.shields.io/github/workflow/status/CirclesUBI/circles-core/Run%20tests?label=tests&style=flat-square&color=%2347cccb" alt="CI Status" height="18"> | ||
| </a> | ||
| <!-- Discourse --> | ||
| <a href="https://aboutcircles.com/"> | ||
| <img src="https://img.shields.io/discourse/topics?server=https%3A%2F%2Faboutcircles.com%2F&style=flat-square&color=%23faad26" alt="chat" height="18"/> | ||
| </a> | ||
| <!-- Twitter --> | ||
| <a href="https://twitter.com/CirclesUBI"> | ||
| <img src="https://img.shields.io/twitter/follow/circlesubi.svg?label=follow+circles" alt="Follow Circles" height="18"> | ||
| <img src="https://img.shields.io/twitter/follow/circlesubi.svg?label=twitter&style=flat-square&color=%23f14d48" alt="Follow Circles" height="18"> | ||
| </a> | ||
| </p> | ||
|
|
||
| Common methods (sign up, transfer Circles, trust users, revoke trust) for clients & wallets to interact with the Circles ecosystem (Smart Contracts, Relay Service, Trust Graph API, etc.). | ||
|
|
||
| ## Documentation | ||
|
|
||
| Read the API specification and documentation here: https://circlesubi.github.io/circles-core | ||
|
|
||
| ## Requirements | ||
|
|
||
| - NodeJS | ||
| - web3.js | ||
|
|
||
| ## Installation | ||
|
|
||
| ``` | ||
| npm i @circles/core | ||
| ``` | ||
|
|
||
| Make sure you have all peer dependencies (`isomorphic-fetch` and `web3`) installed as well. | ||
|
|
||
| ## Usage | ||
| </div> | ||
|
|
||
| <div align="center"> | ||
| <h3> | ||
| <a href="https://circlesubi.github.io/circles-core/"> | ||
| API Docs | ||
| </a> | ||
| <span> | </span> | ||
| <a href="https://handbook.joincircles.net"> | ||
| Handbook | ||
| </a> | ||
| <span> | </span> | ||
| <a href="https://github.com/CirclesUBI/circles-core/releases"> | ||
| Releases | ||
| </a> | ||
| <span> | </span> | ||
| <a href="https://github.com/CirclesUBI/.github/blob/main/CONTRIBUTING.md"> | ||
| Contributing | ||
| </a> | ||
| </h3> | ||
| </div> | ||
|
|
||
| <br/> | ||
|
|
||
| This library provides common methods for JavaScript clients and wallets to interact with the [`circles-contracts`] and off-chain services. | ||
|
|
||
| [`circles-contracts`]: https://github.com/CirclesUBI/circles-contracts | ||
|
|
||
| ## 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 | ||
|
|
||
| [`safe-relay-service`]: https://github.com/CirclesUBI/safe-relay-service | ||
| [`graph`]: https://thegraph.com/explorer/subgraph/circlesubi/circles | ||
| [`circles-api`]: https://github.com/CirclesUBI/circles-api | ||
|
|
||
| ## Example | ||
|
|
||
| ```js | ||
| import CirclesCore from '@circles/core'; | ||
| import Web3 from 'web3'; | ||
|
|
||
| // Initialize web3 | ||
| const web3 = new Web3(); | ||
|
|
||
| // Initialize core | ||
| // Initialize core with default configs when running against local `circles-docker` setup | ||
| const core = new CirclesCore(web3, { | ||
| hubAddress: '0x..', | ||
| proxyFactoryAddress: '0x..', | ||
| safeMasterAddress: '0x..', | ||
| apiServiceEndpoint: 'https://..', | ||
| graphNodeEndpoint: 'https://..', | ||
| relayServiceEndpoint: 'https://..', | ||
| subgraphName: '...', | ||
| }); | ||
|
|
||
| // Create account | ||
| const account = web3.eth.accounts.create(); | ||
|
|
||
| // Define nice username for us | ||
| const username = 'margareth'; | ||
| const email = '[email protected]'; | ||
|
|
||
| // Generate a nonce to predict Safe address | ||
| const nonce = new Date().getTime(); | ||
|
|
||
| // Prepare Safe deployment and receive a predicted safeAddress | ||
| const safeAddress = await core.safe.prepareDeploy(account, { nonce }); | ||
|
|
||
| // Register username and connect it to Safe address | ||
| await core.user.register(account, { | ||
| nonce, | ||
| email, | ||
| safeAddress, | ||
| username, | ||
| }); | ||
|
|
||
| // Get our current trust network | ||
| const network = await core.trust.getNetwork(account, { safeAddress }); | ||
|
|
||
| // Resolve public addresses to user profiles | ||
| const users = await core.user.resolve(account, { | ||
| addresses: network.map((connection) => connection.safeAddress), | ||
| }); | ||
|
|
||
| // Search for a user via username | ||
| const users = await core.user.search(account, { | ||
| query: 'pand', | ||
| }); | ||
|
|
||
| // Example: Display our trust network | ||
| network.forEach((connection) => { | ||
| const user = users.find( | ||
| (item) => item.safeAddress === connection.safeAddress, | ||
| ); | ||
|
|
||
| if (connection.isOutgoing) { | ||
| console.log(`${user.username} accepts your Circles.`); | ||
| } | ||
|
|
||
| if (connection.isIncoming) { | ||
| console.log(`You accept Circles of ${user.username}.`); | ||
| } | ||
| }); | ||
|
|
||
| // Check if we have enough trust connections | ||
| const { isTrusted } = await core.trust.isTrusted({ | ||
| safeAddress, | ||
| hubAddress: '0xCfEB869F69431e42cdB54A4F4f105C19C080A601', | ||
| proxyFactoryAddress: '0xD833215cBcc3f914bD1C9ece3EE7BF8B14f841bb', | ||
| safeMasterAddress: '0xC89Ce4735882C9F0f0FE26686c53074E09B0D550', | ||
| apiServiceEndpoint: 'http://api.circles.local', | ||
| graphNodeEndpoint: 'http://graph.circles.local', | ||
| relayServiceEndpoint: 'http://relay.circles.local', | ||
| subgraphName: 'CirclesUBI/circles-subgraph', | ||
| }); | ||
|
|
||
| if (!isTrusted) { | ||
| console.log('Not enough trust connections yet ..'); | ||
| } else { | ||
| // Deploy Safe | ||
| await core.safe.deploy(account, { safeAddress }); | ||
| // Create existing account from private key which owns a Safe | ||
| const account = web3.eth.accounts.privateKeyToAccount('0x...'); | ||
|
|
||
| // Deploy Circles Token | ||
| await core.token.deploy(account, { safeAddress }); | ||
| } | ||
|
|
||
| // Change trust state with users | ||
| await core.trust.removeConnection(account, { | ||
| user: users[0].safeAddress, | ||
| canSendTo: safeAddress, | ||
| }); | ||
|
|
||
| // .. give user the permission to send their Token to you | ||
| await core.trust.addConnection(account, { | ||
| user: users[0].safeAddress, | ||
| canSendTo: safeAddress, | ||
| limitPercentage: 20, | ||
| }); | ||
|
|
||
| // Get list of my activities | ||
| const { activities } = await core.activity.getLatest(account, { | ||
| safeAddress, | ||
| }); | ||
|
|
||
| // Example: Display activities | ||
| const { ActivityTypes } = core.activity; | ||
|
|
||
| activities.forEach((activity) => { | ||
| const { timestamp, type, data } = activity; | ||
|
|
||
| if (type === ActivityTypes.HUB_TRANSFER) { | ||
| console.log( | ||
| `${timestamp} - ${ | ||
| data.from | ||
| } transferred ${data.value.toString()} Circles to ${data.to}`, | ||
| ); | ||
| } else if (type === ActivityTypes.ADD_CONNECTION) { | ||
| console.log( | ||
| `${timestamp} - ${data.limitPercentage} ${data.canSendTo} allowed ${data.send} to transfer Circles`, | ||
| ); | ||
| } else if (type === ActivityTypes.REMOVE_CONNECTION) { | ||
| console.log(`${timestamp} - ${data.canSendTo} untrusted ${data.user}`); | ||
| } else if (type === ActivityTypes.ADD_OWNER) { | ||
| console.log( | ||
| `${timestamp} - added ${data.ownerAddress} to ${data.safeAddress}`, | ||
| ); | ||
| } else if (type === ActivityTypes.REMOVE_OWNER) { | ||
| console.log( | ||
| `${timestamp} - removed ${data.ownerAddress} from ${data.safeAddress}`, | ||
| ); | ||
| } | ||
| }); | ||
|
|
||
| // Get current balance of all owned Circles Tokens | ||
| const tokenAddress = core.token.getAddress(account, { | ||
| safeAddress, | ||
| }); | ||
|
|
||
| const balance = await core.token.getBalance(account, { | ||
| safeAddress, | ||
| // Find out the address of the owned Safe | ||
| const [safeAddress] = await core.safe.getAddresses(account, { | ||
| ownerAddress: account.address, | ||
| }); | ||
|
|
||
| // Request my UBI | ||
| const payout = await core.token.checkUBIPayout(account, { | ||
| // Request Circles UBI payout | ||
| await core.token.requestUBIPayout(account, { | ||
| safeAddress, | ||
| }); | ||
| ``` | ||
|
|
||
| if (!payout.isZero()) { | ||
| await core.token.requestUBIPayout(account, { | ||
| safeAddress, | ||
| }); | ||
| } | ||
|
|
||
| // Transfer Circles to users (directly or transitively) | ||
| const txHash = await core.token.transfer(account, { | ||
| from: safeAddress, | ||
| to: users[0].safeAddress, | ||
| value: 350, | ||
| paymentNote: 'Thank you for the fish!', | ||
| }); | ||
|
|
||
| // Get the payment note of that transfer | ||
| const paymentNote = await core.token.getPaymentNote(account, { | ||
| transactionHash: txHash, | ||
| }); | ||
|
|
||
| // Get current Safe owners | ||
| await core.safe.getOwners(account, { | ||
| safeAddress, | ||
| }); | ||
| ## Installation | ||
|
|
||
| // .. or get the Safe connected to an owner | ||
| const [safeAddress] = await core.safe.getAddresses(account, { | ||
| ownerAddress: '0x123...', | ||
| }); | ||
| ```bash | ||
| npm i @circles/core | ||
| ``` | ||
|
|
||
| // Manage owners of my Safe | ||
| await core.safe.removeOwner(account, { | ||
| safeAddress, | ||
| ownerAddress: '0x123...', | ||
| }); | ||
| 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. | ||
|
|
||
| await core.safe.addOwner(account, { | ||
| safeAddress, | ||
| ownerAddress: '0x123...', | ||
| }); | ||
| ``` | ||
| [`isomorphic-fetch`]: https://www.npmjs.com/package/isomorphic-fetch | ||
| [`web3`]: https://www.npmjs.com/package/web3 | ||
|
|
||
| ## Development | ||
|
|
||
| `circles-core` is a JavaScript module, tested with [Jest](https://jestjs.io/), transpiled with [Babel](https://babeljs.io/) and bundled with [Rollup](https://rollupjs.org). | ||
| `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 dependencies | ||
| ```bash | ||
| # Install NodeJS dependencies | ||
| npm install | ||
|
|
||
| // Copy config file and edit it | ||
| # 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 test suite | ||
| # 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 | ||
| # Check code formatting | ||
| npm run lint | ||
|
|
||
| // Build it! | ||
| # Build it! | ||
| npm run build | ||
| ``` | ||
|
|
||
| [`Jest`]: https://jestjs.io | ||
| [`Babel`]: https://babeljs.io | ||
| [`Rollup`]: https://rollupjs.org | ||
| [`circles-docker`]: https://github.com/CirclesUBI/circles-docker | ||
|
|
||
| ## License | ||
|
|
||
| GNU Affero General Public License v3.0 `AGPL-3.0` | ||
| GNU Affero General Public License v3.0 [`AGPL-3.0`] | ||
|
|
||
| [`AGPL-3.0`]: https://github.com/CirclesUBI/circles-core/blob/main/LICENSE |
Oops, something went wrong.