@colony/colony-js

<div align="center"> <img src="media/colonyJS_color.svg" width="600" /> </div>

Usage no npm install needed!

<script type="module">
  import colonyColonyJs from 'https://cdn.skypack.dev/@colony/colony-js';
</script>

README

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:

  1. Make sure you are using the exact same node version in colonyJS and the Dapp. Use nvm if possible

  2. Update the required submodules:

git submodule update --init --recursive
  1. Build colonyJS. In the colonyJS directory do:
npm run build
  1. Create an npm link in the colonyJS directory:
npm link
  1. Link to it in the Dapp directory:
npm link @colony/colony-js
  1. 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

  1. First, commit all your changes. Then run the tests:
npm test #just to be sure

  1. Adjust the version in package.json

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

npm install
  1. 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`!
  1. Tag the commit:
git tag v2.0.1 # here we use the `v`!
  1. Push the changes and tags:
git push && git push --tags
  1. Publish on npm:
npm publish --access=public

Done 🎊

To upgrade to a new colonyNetwork version

  1. Add the version to versions.ts in ColonyVersion as well as the network git tag to releaseMaps
  2. Add the git tag to src/constants.ts release map
  3. 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
  4. If needed: add new contracts that need clients to the contractsToBuild array in scripts/build-contracts.ts
  5. 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.

  1. Update the following lines in ColonyNetworkClient.ts to reflect the new version:
import { IColonyNetworkFactory } from '../contracts/X/IColonyNetworkFactory';
import { IColonyNetwork } from '../contracts/X/IColonyNetwork';
  1. 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:

  1. Add the new version and corresponding git tag for one or more extesions inside versions.ts
  2. Run npm run build-contracts -- this will build the network contracts for the extensions using typechain
  3. Run npm run build-clients -- this will build basic clients and addon files for your new extension versions
  4. 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