colonyJS

colonyJS is a JavaScript library with a simple and predictable interface for application-layer integrations with the colonyNetwork smart contracts. To learn more about Colony, you can visit colony.io or read the White Paper.

This software is in ALPHA state. The API is subject to change (but shouldn't really).

Documentation

The documentation is automatically generated using TypeDoc. It's pretty alpha right now. You should check out the getColonyNetworkClient function in ColonyNetworkClient and the docs for the extended colony contracts clients/Colony/ColonyClientVX.

Get Started

import { getColonyNetworkClient, Network } = from '@colony/colony-js';
import { Wallet } from 'ethers';
import { JsonRpcProvider } from 'ethers/providers';

// For local connections (run an Ethereum node on port 8545);
const provider = new JsonRpcProvider();

// Put in your local network address here (deployed ether router address)
const networkAddress = '0xdabbad00';

(async () => {
  // Get a wallet instance
  const wallet = new Wallet(
    // This is a private key that is generated by the colony network ganache instance
    '0x0355596cdb5e5242ad082c4fe3f8bbe48c9dba843fe1f99dd8272f487e70efae',
    provider,
  );

  // Check out the logs to see the wallet address
  console.log('Wallet Address:', wallet.address);

  // Get a network client instance
  const networkClient = await getColonyNetworkClient(
    Network.Local,
    wallet,
    // The address of the locally deployed EtherRouter!
    { networkAddress: '0xdabbad00' }
  );

  // Check out the logs to see the network address
  console.log('Network Address:', networkClient.address);

  // Get the colony client for the Meta Colony
  const colonyClient = await networkClient.getColonyClient(1);

  console.log('Meta Colony address:', colonyClient.address);
})()
  .then(() => process.exit())
  .catch(error => console.error(error));

Contributing

We welcome all contributions to colonyJS! See Contributing for more information.

Development

Local development

Using just npm you can link the built colonyJS files to your Dapp when developing new features in colonyJS while trying them out immediately in your dev-environment.

To do that:

Make sure you are using the exact same node version in colonyJS and the Dapp. Use nvm if possible
Update the required submodules:

git submodule update --init --recursive

Build colonyJS. In the colonyJS directory do:

npm run build

Create an npm link in the colonyJS directory:

npm link

Link to it in the Dapp directory:

npm link @colony/colony-js

Then do a regular install in the Dapp directory:

npm install

To overwrite the link again just specify a version that exists on npm:

npm install @colony/colony-js@^3.0.0

If that doesn't remove it, just remove the folder in node_modules

To release a new version

First, commit all your changes. Then run the tests:

npm test #just to be sure

Adjust the version in package.json
Let npm adjust the version in package-lock.json:

npm install

Commit the npm package files. Use the version set in the package.json (make sure to follow the version pattern):

git add pack*
git commit -m '2.0.1' # no `v`!

Tag the commit:

git tag v2.0.1 # here we use the `v`!

Push the changes and tags:

git push && git push --tags

Publish on npm:

npm publish --access=public

Done 🎊

To upgrade to a new colonyNetwork version

Add the version to versions.ts in ColonyVersion as well as the network git tag to releaseMaps
Add the git tag to src/constants.ts release map
Optional: If you are tracking a development branch instead of a static tag or commit, make sure to pull the latest changes, otherwise the contracts generated will be exactly the same as your last ones -- this is a step often forgotten when using a dev version
If needed: add new contracts that need clients to the contractsToBuild array in scripts/build-contracts.ts
Run

npm run build-contracts

This will create a new folder: src/contracts/X containing all the type definitions you'll need to implement the new colony client.

Update the following lines in ColonyNetworkClient.ts to reflect the new version:

import { IColonyNetworkFactory } from '../contracts/X/IColonyNetworkFactory';
import { IColonyNetwork } from '../contracts/X/IColonyNetwork';

Update all the other contract imports in the non-colony clients, even if they haven't been upgraded (just in case). Then make adjustments to the clients to reflect the contract changes (typescript will tell you, where to make changes). Also add necessary helper functions (e.g. withProofs functions) for newly added methods. The newly added methods and their required roles can be found in this file (and by diffing the generated interface files).

To add new extension contract versions:

Add the new version and corresponding git tag for one or more extesions inside versions.ts
Run npm run build-contracts -- this will build the network contracts for the extensions using typechain
Run npm run build-clients -- this will build basic clients and addon files for your new extension versions
If you need extra methods added to your client (helpers like withProofs), add them inside the Addon file that you'll find in the client's folder (don't forget to also add the estimate method)

Eg:

'/src/clients/Extensions/OneTxPayment/1/OneTxPaymentClient.ts' // the OneTxPayment extension client
'/src/clients/Extensions/OneTxPayment/1/OneTxPaymentClientAddons.ts' // the OneTxPayment extension client addons

License

GPL-3.0

arlav/colonyJS