Colony SDK browser demo - connecting to MetaMask
11 |Click the button to connect to MetaMask
12 | 13 |Colony SDK browser demo - events
11 |Listen to Colony Events as they unfold...
12 | 13 | 14 | 15 |Colony SDK browser demo - basic
11 |Let's check the CLNY funding for a Colony
12 | 15 | 16 |Colony SDK browser demo - create a team, move funds and make a payment
11 |1) Let's connect to the Colony first Make sure you have the FUNDING and 12 | ADMINISTRATION permissions in the Root domain of that Colony
13 | 14 | 15 |2) Next we create a team
16 | 17 |3) We need to move some funds to the new team. Make sure the root colony has at least 18 | about 1 unit of the Colony's native token (see message below after connecting)
19 | 20 |4) Then, within that team, send someone some of the Colony's native tokens
21 | 22 | 23 |Colony SDK browser demo - local deployment - check the MetaColony's funding
11 |First make sure that the Colony contracts are deployed locally and the Reputation Oracle is set up. See here for 13 | more 14 | information
15 |We'll be using wallet address 0xb77D57F4959eAfA0339424b83FcFaf9c15407461 to connect to the locally deployed 16 | MetaColony. Any transaction will automatically be signed as we have the private key hardcoded. No connection 17 | to 18 | MetaMask is needed.
19 |Let's check the CLNY funding for the local MetaColony. Make sure to provide the 20 | correct 21 | address given in the `etherrouter-address.json` in the `colonyNetwork` directory.
22 | 23 | 24 | 25 |Colony SDK browser demos
11 |See colonySDK and colonyStarter for more information.
13 |Check out the source code for the examples here.
15 |These demos interact with LIVE Colonies on Gnosis chain. We recommend to use the Colony 16 | RPC endpoint directly.
17 |-
18 |
- 19 | Basic example (fetching funds from a Colony) 20 | 21 |
- 22 | MetaMask example (connecting to MetaMask) 23 | 24 |
- 25 | Advanced example (creating a domain within a Colony) 26 | 27 |
- 28 | Events example (listening to Colony events) 29 | 30 |
- 31 | Motion workflow (connecting to a Demo Colony) 32 | 33 |
These demos interact with a local development RPC endpoint (see here on how to set 36 | it up). MetaMask is not needed, the examples provide a wallet account.
37 |-
38 |
- 39 | Basic example for local setup 40 | 41 |
- 42 | Reputation example (get reputation for a user) 43 | 44 |
- 45 | Motion workflow 46 | 47 |
Colony SDK browser demo - local deployment - make a payment in the MetaColony and check the user's reputation 11 |
12 |First make sure that the Colony contracts are deployed locally and the Reputation Oracle is set 15 | up.
16 |We'll be using wallet address 0xb77D57F4959eAfA0339424b83FcFaf9c15407461 to connect to the locally deployed 17 | MetaColony. This address was used to deploy the MetaColony locally and is the "owner" of it. Any transaction 18 | will automatically be signed as we have the private key hardcoded. No connection to MetaMask is needed.
19 |1) Let's connect to the ColonyNetwork first Paste in the address from the 20 | `etherrouter-address.json` in the `colonyNetwork` directory
21 | 22 | 23 |2) Then, we mint some CLNY and fund the MetaColony with it (make it at least 24 | 10!)
25 | 26 | 27 |3) Next, we pay someone for a task in the MetaColony's root team (in the MetaColony's native token CLNY - 28 | that's important!)
29 | 30 | 31 |4) Jump forward in time - Reputation is awarded in cycles. In our case it's set to 1 hour. As we have full 32 | control over our local blockchain, Ganache allows us to travel to the future! Fasten your seatbelts, here we
33 |Instructions: 34 |
-
35 |
- i) Press the button 36 |
- ii) Wait for the message
✅ New reputation hash confirmed
to appear in your console (reputation 37 | oracle)
38 | - iii) Press the button again 39 |
- iv) Wait for the above message again 40 |
- v) Then go to the next step 41 |
Note: We're using Ganache's evm_increaseTime and evm_mine methods to first increase the block time artificially by one hour and then force a 48 | block to mine. This will trigger the local reputation oracle/miner to award the pending reputation. We have to do 49 | that twice, if the reputation oracle was just started for the first time.
50 |5) Ask the oracle for the user's reputation
51 | 52 |Colony SDK browser demo - Motion workflow
11 |Using wallet address
12 |1) Let's connect to the Colony first For testing, it is beneficial to set the period 13 | length of the motion phases to very low values (e.g. 2 minutes)
14 | 15 | 16 |2) Now we approve some of the CLNY of the above wallet for the Colony and the VotingReputation 17 | staking, 18 | which will remove it from the user's wallet (you only need to do this once for this example)
19 | 20 | 21 |3) Then, we create a motion to pay some of the native token to Carol: 22 | 0x42b9f8673a9187952a5dF24132eEa04268a14BCC (this will also incur reputation if the motion passes) (must be less than the amount that is in the Colony's root team!) 24 |
25 | 26 | 27 |4) Next, we look at the motion more closely
28 | 29 | 30 |You will see the domainId in which the motion was created, the altTarget (which is the OneTxPayment extension in 31 | this case, as we want to execute the `pay` function on it), the encoded action and the stakes remaining for 32 | activation.
33 |5) Okay, now we're ready to stake. Feel free to stake any amount, then get the motion again and see how it 34 | goes up :)
35 | 36 | 37 | 38 |6) We can also simulate voting. For that, we activate both sides by staking the required amount on both 39 | sides from a single address. That usually won't happen in the wild (except if someone wants to force voting for 40 | some 41 | reason). Stake on both sides and then get the motion data to see if remainingYayStakes and 42 | remainingNayStakes are both 0.0 43 |
44 | 45 | 46 |7) Reveal the vote After the voting phase is over the votes can be revealed. Only if a vote is revealed it 47 | is counted and the voting reward is paid out
48 | 49 |8) If the motion was successful, we can finalize it. In our example we can only finalize it if we wait 50 | long 51 | enough after staking was only activated for Yay or if we voted for Yay.
52 | 53 |
6 | 
7 |
8 |
9 | [](https://discord.gg/feVZWwysqM)
10 |
11 | # Colony SDK
12 |
13 | The Colony SDK is under heavy development by the community and will be an easy-to-use interface for the Colony Network contracts, providing simple functions that hide the dark magic going on under the hood of ColonyJS.
14 | It covers _everything_ the dApp can do, so you'll be able to run your DAO entirely programmatically 👩💻
15 |
16 | Colony SDK also includes a variety of examples to get you up and building with Colony in no time!
17 |
18 | ## Quickstart
19 |
20 | ```javascript
21 | import { providers } from 'ethers';
22 | import { ColonyNetwork, toEth } from '@colony/sdk';
23 |
24 | // If MetaMask is installed there will be an `ethereum` object on the `window`
25 | // NOTE: Make sure MetaMask is connected to Gnosis chain (see https://www.xdaichain.com/for-users/wallets/metamask/metamask-setup)
26 | const provider = new providers.Web3Provider(window.ethereum);
27 |
28 | // Get the Colony's XDAI funding in the ROOT pot (id 1)
29 | const start = async () => {
30 | // This will try to connect the page to MetaMask
31 | await provider.send('eth_requestAccounts', []);
32 | // Create a new connection to the Colony Network contracts using the MetaMask "wallet"
33 | const colonyNetwork = await ColonyNetwork.init(provider.getSigner());
34 | // Connect to the MetaColony (this could be replaced with your own colony using `colonyNetwork.getColony(COLONY_ADDRESS)`)
35 | const metaColony = await colonyNetwork.getMetaColony();
36 | // Get the CLNY funding for the MetaColony (CLNY is it's native token)
37 | const funding = await metaColony.getBalance();
38 | // The funding will be in wei (x * 10^18), so we format into a readable string using the `toEth` function
39 | alert('MetaColony balance is ' + toEth(funding) + ' CLNY');
40 | };
41 |
42 | start();
43 | ```
44 |
45 | ## Documentation
46 |
47 | [🖺 Click here for docs!](https://docs.colony.io/colonysdk)
48 |
49 | ## Running the examples
50 |
51 | First, clone this repo:
52 | ```bash
53 | git clone https://github.com/JoinColony/colonySDK.git
54 | ```
55 |
56 | Then install all the required dependencies (this will install [ethers.js](https://docs.ethers.io/v5/) and [colonyJS](https://github.com/JoinColony/colonyJS) as well as some required development dependencies):
57 |
58 | ```bash
59 | npm install
60 | ```
61 |
62 | Then you can run the examples:
63 |
64 | ### Node.js
65 |
66 | ```bash
67 | npm run examples:node
68 | ```
69 |
70 | ### Browser (vanilla JS example)
71 |
72 | ```bash
73 | npm run examples:browser
74 | ```
75 |
76 | ### Some notes
77 |
78 | These examples will run on Gnosis chain. If you'd like to make transactions, you will need some XDAI. Reach out to us in our [Discord](https://discord.gg/feVZWwysqM) if you're having trouble starting out.
79 |
80 | ## Development
81 |
82 | ### Prerequisites
83 |
84 | - Node `>=16.0.0`
85 |
86 | _You may find it helpful to use [Node Version Manager (`nvm`)](https://github.com/nvm-sh/nvm) to manage Node versions._
87 |
88 | ### Creating a new release
89 |
90 | colonySDK is using [`release-it`](https://github.com/release-it/release-it) to create new releases. To create and publish a new release, commit your changes, then execute
91 |
92 | ```bash
93 | npm run release -- SEMVER_TAG # SEMVER_TAG is major, minor, patch
94 | ```
95 |
96 | If you don't supply a `GITHUB_TOKEN` environment variable, `release-it` will open a browser window and pre-populate the corresponding release input fields for you.
97 |
98 | **Frequent commits and descriptive commit messages** will help when `release-it` tries to autogenerate the changelog.
99 |
100 | ### Contribute
101 |
102 | _Are you interested in contributing?_ Check out the following document for more information:
103 |
104 | - [Contributing](CONTRIBUTING.md)
105 |
--------------------------------------------------------------------------------
/docs/getting-started/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 1
3 | description: A stupidly short guide to get started with Colony development
4 | ---
5 |
6 | import Tabs from '@theme/Tabs';
7 | import TabItem from '@theme/TabItem';
8 |
9 | # Start Building
10 |
11 | ## Prerequisites
12 |
13 | * NodeJS v 16.15.0 is installed on your system (use [`nvm`](https://github.com/nvm-sh/nvm) for changing NodeJS versions on the fly)
14 | * A JavaScript/TypeScript project with a `package.json` and the `@colony/sdk` and `ethers` packages installed.
15 |
16 | :::tip
17 | To get started even faster, use our [**`Colony Starter`**](https://github.com/JoinColony/colonyStarter) template. It's just a matter of cloning the repository and running `npm run serve` to get to the first working example. Follow the guide after the link for more information.
18 | :::
19 |
20 | ## Installation
21 |
22 | It's as easy as
23 |
24 | ```bash
25 | npm install ethers @colony/sdk
26 | ```
27 |
28 | You'll need `ethers` v5.x as a dependency in your project.
29 |
30 | ## Connecting to Colony on Gnosis Chain
31 |
32 |
7 | Colony SDK browser demo - local deployment - Motion workflow
11 |First make sure that the Colony contracts are deployed locally and the Reputation Oracle is set 14 | up.
15 |We'll be using wallet address 0xb77D57F4959eAfA0339424b83FcFaf9c15407461 to connect to the locally 16 | deployed MetaColony. This address was used to deploy the MetaColony locally and is the "owner" of it. Any 17 | transaction will automatically be signed as we have the private key hardcoded. No connection to MetaMask is 18 | needed. 19 |
20 |1) Let's connect to the ColonyNetwork first Paste in the address from the 21 | `etherrouter-address.json` in the `colonyNetwork` directory
22 |This will also set up the Motions&Disputes extension in the MetaColony with testing settings as well as 23 | distribute 24 | an initial amount of reputation and CLNY to the two addresses we're using for this example: 25 | 0xb77D57F4959eAfA0339424b83FcFaf9c15407461 and 0x9df24e73f40b2a911eb254a8825103723e13209c. 26 |
27 | 28 | 29 |2) Now we install the VotingReputation extension and bootstrap some reputation (you only need to 30 | do 31 | this once for this example)
32 | 33 |3) Now we approve some of the CLNY of 0xb77D57F4959eAfA0339424b83FcFaf9c15407461 for the Colony and 34 | the 35 | VotingReputation staking, which will remove it from the user's wallet (you only need to do this 36 | once for this example) 37 |
38 | 39 |4) Jump forward in time - When we connected to the Colony above, the two addresses mentioned were awarded 40 | some reputation. It is awarded in cycles; in our case it's set to 1 hour. As we have full control over our local 41 | blockchain, Ganache allows us to travel to the future! Fasten your seatbelts, here we go (take 43 | a look at the console for the reputation oracle!)!
44 |Instructions: 45 |
-
46 |
- i) Press the button 47 |
- ii) Wait for the message
✅ New reputation hash confirmed
to appear in your console (reputation 48 | oracle)
49 | - iii) Press the button again 50 |
- iv) Wait for the above message again 51 |
- v) Then go to the next step 52 |
Note: We're using Ganache's evm_increaseTime and evm_mine methods to first increase the block time artificially by one hour and then force a 59 | block to mine. This will trigger the local reputation oracle/miner to award the pending reputation. We have to do 60 | that twice, if the reputation oracle was just started for the first time.
61 |5) Then, we create a motion to pay some CLNY to a third address: 62 | 0x27ff0c145e191c22c75cd123c679c3e1f58a4469 (this will also incur reputation if the motion passes) (make it less than 100!) 64 |
65 | 66 | 67 |6) Next, we look at the motion more closely
68 | 69 | 70 |You will see the domainId in which the motion was created, the altTarget (which is the OneTxPayment extension in 71 | this case, as we want to execute the `pay` function on it), the encoded action and the stakes remaining for 72 | activation.
73 |7) Okay, now we're ready to stake. Feel free to stake any amount, then get the motion again and see how it 74 | goes up :)
75 | 76 | 77 | 78 |8) We can also simulate voting. For that, we activate both sides by staking the required amount on both 79 | sides from a single address. That usually won't happen in the wild (except if someone wants to force voting for 80 | some 81 | reason). Stake on both sides and then get the motion data to see if remainingYayStakes and 82 | remainingNayStakes are both 0.0 83 |
84 | 85 | 86 |9) Reveal the vote After the voting phase is over (you will need to wait ~6 87 | minutes 88 | - we are forwarding time again for that), the votes can be revealed. Only if a vote is revealed it is counted and 89 | the voting reward is paid out
90 | 91 |10) If the motion was successful, we can finalize it. In our example we can only finalize it if we wait 92 | long 93 | enough (~6min - the time is forwarded again when you press the button) after staking was only activated for Yay or 94 | if we voted for Yay.
95 | 96 |