Merge pull request #140 from JoinColony/feature/create-colony

Add functions necessary to create a colony
JoinColony · Dec 6, 2022 · 9de580e · 9de580e
2 parents 95950eb + ffa2523
commit 9de580e
Show file tree

Hide file tree

Showing 40 changed files with 1,752 additions and 235 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -5,7 +5,8 @@
         "@colony/eslint-config-colony"
     ],
     "plugins": [
-        "@typescript-eslint"
+        "@typescript-eslint",
+        "eslint-plugin-tsdoc"
     ],
     "env": {
         "browser": true,
@@ -22,12 +23,12 @@
                 ]
             }
         ],
-        "no-unused-vars": "off",
+        "no-dupe-class-members": "off",
         "no-redeclare": "off",
+        "no-shadow": "off",
+        "no-unused-vars": "off",
         "no-use-before-define": "off",
-        "no-dupe-class-members": "off",
         "@typescript-eslint/no-unused-vars": "error",
-        "no-shadow": "off",
         "@typescript-eslint/no-shadow": [
             "error"
         ],
@@ -44,7 +45,8 @@
                     "examples/browser/src/*.ts"
                 ]
             }
-        ]
+        ],
+        "tsdoc/syntax": "warn"
     },
     "overrides": [
         {

diff --git a/docs/api/README.md b/docs/api/README.md
@@ -6,13 +6,15 @@
 
 ## Enumerations
 
+- [ColonyLabelSuffix](enums/ColonyLabelSuffix.md)
 - [ColonyRole](enums/ColonyRole.md)
 - [Extension](enums/Extension.md)
 - [Id](enums/Id.md)
 - [MetaTxBroadCasterEndpoint](enums/MetaTxBroadCasterEndpoint.md)
 - [MetadataType](enums/MetadataType.md)
 - [MotionState](enums/MotionState.md)
 - [Network](enums/Network.md)
+- [SupportedExtension](enums/SupportedExtension.md)
 - [TeamColor](enums/TeamColor.md)
 - [Vote](enums/Vote.md)
 
@@ -23,6 +25,7 @@
 - [ColonyEventManager](classes/ColonyEventManager.md)
 - [ColonyNetwork](classes/ColonyNetwork.md)
 - [ColonyToken](classes/ColonyToken.md)
+- [OneTxPayment](classes/OneTxPayment.md)
 - [PinataAdapter](classes/PinataAdapter.md)
 - [TxCreator](classes/TxCreator.md)
 - [VotingReputation](classes/VotingReputation.md)
@@ -33,9 +36,11 @@
 - [ColonyEvent](interfaces/ColonyEvent.md)
 - [ColonyEventManagerOptions](interfaces/ColonyEventManagerOptions.md)
 - [ColonyFilter](interfaces/ColonyFilter.md)
+- [ColonyMetadata](interfaces/ColonyMetadata.md)
 - [ColonyMultiFilter](interfaces/ColonyMultiFilter.md)
 - [ColonyNetworkOptions](interfaces/ColonyNetworkOptions.md)
 - [ColonyTopic](interfaces/ColonyTopic.md)
+- [DomainMetadata](interfaces/DomainMetadata.md)
 - [Ethers6Filter](interfaces/Ethers6Filter.md)
 - [Ethers6FilterByBlockHash](interfaces/Ethers6FilterByBlockHash.md)
 - [EventSources](interfaces/EventSources.md)

diff --git a/docs/api/classes/Colony.md b/docs/api/classes/Colony.md
@@ -42,9 +42,9 @@ ___
 
 ___
 
-### SupportedVersions
+### supportedVersions
 
-▪ `Static` **SupportedVersions**: ``10``[]
+▪ `Static` **supportedVersions**: ``10``[]
 
 The currently supported Colony version. If a Colony is not on this version it has to be upgraded.
 If this is not an option, Colony SDK might throw errors at certain points. Usage of ColonyJS is advised in these cases
@@ -70,12 +70,12 @@ If [AnnotationMetadata](../interfaces/AnnotationMetadata.md) is provided directl
 (async function() {
 
   // Create a motion to pay 10 of the native token to some (maybe your own?) address
-  // (forced transaction example)
   const [, { transactionHash }] = await colony.ext.oneTx.pay(
     '0xb77D57F4959eAfA0339424b83FcFaf9c15407461',
     w`10`,
   ).motion();
   // Annotate the motion transaction with a little explanation :)
+  // (forced transaction example)
   await colony.annotateTransaction(
      transactionHash,
      { annotationMsg: 'I am creating this motion because I think I deserve a little bonus' },
@@ -173,7 +173,7 @@ import { TeamColor } from '@colony/sdk';
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `metadata` | `string` \| `DomainMetadata` | The team metadata you would like to add (or an IPFS CID pointing to valid metadata). If DomainMetadata is provided directly (as opposed to a [CID](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) for a JSON file) this requires an [IpfsAdapter](../interfaces/IpfsAdapter.md) that can upload and pin to IPFS (like the [PinataAdapter](PinataAdapter.md)). See its documentation for more information. |
+| `metadata` | `string` \| [`DomainMetadata`](../interfaces/DomainMetadata.md) | The team metadata you would like to add (or an IPFS CID pointing to valid metadata). If [DomainMetadata](../interfaces/DomainMetadata.md) is provided directly (as opposed to a [CID](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) for a JSON file) this requires an [IpfsAdapter](../interfaces/IpfsAdapter.md) that can upload and pin to IPFS (like the [PinataAdapter](PinataAdapter.md)). See its documentation for more information. |
 
 #### Returns
 
@@ -361,6 +361,57 @@ A Team object
 
 ___
 
+### installExtension
+
+▸ **installExtension**(`extension`): [`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"installExtension"``, { `colony?`: `string` ; `extensionId?`: `string` ; `version?`: `BigNumber`  }, [`MetadataType`](../enums/MetadataType.md)\>
+
+Install an extension for a colony
+
+Valid extensions can be found here: [SupportedExtension](../enums/SupportedExtension.md)
+
+**`Remarks`**
+
+Be aware that some extensions need some extra setup steps (like the `initialise` method on `VotingReputation`).
+After an extension was installed, `colony.updateExtensions()` needs to be called (see example)
+
+**`Example`**
+
+```typescript
+// Immediately executing async function
+(async function() {
+  // Install the OneTxPayment extension for Colony
+  // (forced transaction example)
+  await colony.installExtension(
+    SupportedExtension.oneTx,
+  ).force();
+  // Update the extensions in the colony
+  await colony.updateExtensions();
+  console.info(colony.ext.oneTx.address);
+})();
+```
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `extension` | [`SupportedExtension`](../enums/SupportedExtension.md) | Name of the extension you'd like to install |
+
+#### Returns
+
+[`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"installExtension"``, { `colony?`: `string` ; `extensionId?`: `string` ; `version?`: `BigNumber`  }, [`MetadataType`](../enums/MetadataType.md)\>
+
+A [TxCreator](TxCreator.md)
+
+**Event data**
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| `extensionId` | string | Id (name) of the extension (e.g. `OneTxPayment`) |
+| `colony` | string | The address of the colony on which the extension was installed |
+| `version` | BigNumber | The version of the extension that was installed |
+
+___
+
 ### makeArbitraryTransaction
 
 ▸ **makeArbitraryTransaction**(`target`, `action`): [`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"makeArbitraryTransactions"``, `Record`<`string`, `unknown`\>, [`MetadataType`](../enums/MetadataType.md)\>
@@ -463,3 +514,131 @@ A [TxCreator](TxCreator.md)
 | `toPot` | BigNumber | The target funding pot |
 | `amount` | BigNumber | The amount that was transferred |
 | `token` | string | The token address being transferred |
+
+___
+
+### setRoles
+
+▸ **setRoles**(`address`, `roles`, `teamId?`): [`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"setUserRoles"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `role?`: `number` ; `setTo?`: `boolean` ; `user?`: `string`  }, [`MetadataType`](../enums/MetadataType.md)\>
+
+Set (award) roles to a user/contract
+
+**`Remarks`**
+
+Existing roles will be kept. Use [unsetRoles](Colony.md#unsetroles) to remove roles
+
+**`Example`**
+
+```typescript
+import { ColonyRole } from '@colony/sdk';
+
+// Immediately executing async function
+(async function() {
+  // Give Administration and Root role to address 0xb794f5ea0ba39494ce839613fffba74279579268 (in Root team)
+  // (forced transaction example)
+  await colony.setRoles(
+    '0xb794f5ea0ba39494ce839613fffba74279579268',
+    [ColonyRole.Administration, ColonyRole.Root],
+  ).force();
+})();
+```
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `address` | `string` | `undefined` | Address of the wallet or contract to give the roles to |
+| `roles` | [`ColonyRole`](../enums/ColonyRole.md) \| [`ColonyRole`](../enums/ColonyRole.md)[] | `undefined` | Role or array of roles to award |
+| `teamId` | `BigNumberish` | `Id.RootDomain` | Team to apply the role(s) in |
+
+#### Returns
+
+[`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"setUserRoles"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `role?`: `number` ; `setTo?`: `boolean` ; `user?`: `string`  }, [`MetadataType`](../enums/MetadataType.md)\>
+
+A [TxCreator](TxCreator.md)
+
+**Event data**
+Heads up!* This event is emitted for every role that was set
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| `agent` | string | The address that is responsible for triggering this event |
+| `user` | string | Address of the user who was awarded the role |
+| `domainId` | BigNumber | The team the role was awarded for |
+| `role` | number | The number of the role that was awarded. Use `ColonyRole[role]` to get the title of the role |
+| `setTo` | number | Whether the role was awarded or removed |
+
+___
+
+### unsetRoles
+
+▸ **unsetRoles**(`address`, `roles`, `teamId?`): [`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"setUserRoles"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `role?`: `number` ; `setTo?`: `boolean` ; `user?`: `string`  }, [`MetadataType`](../enums/MetadataType.md)\>
+
+Unset (remove) roles from a user/contract
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `address` | `string` | `undefined` | Address of the wallet or contract to remove the roles from |
+| `roles` | [`ColonyRole`](../enums/ColonyRole.md) \| [`ColonyRole`](../enums/ColonyRole.md)[] | `undefined` | Role or array of roles to remove |
+| `teamId` | `BigNumberish` | `Id.RootDomain` | Team to apply the role(s) in |
+
+#### Returns
+
+[`TxCreator`](TxCreator.md)<`ColonyClientV10`, ``"setUserRoles"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `role?`: `number` ; `setTo?`: `boolean` ; `user?`: `string`  }, [`MetadataType`](../enums/MetadataType.md)\>
+
+A [TxCreator](TxCreator.md)
+
+**Event data**
+Heads up!* This event is emitted for every role that was unset
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| `agent` | string | The address that is responsible for triggering this event |
+| `user` | string | Address of the user of which the role was removed |
+| `domainId` | BigNumber | The team the role was removed for |
+| `role` | number | The number of the role that was removed. Use `ColonyRole[role]` to get the title of the role |
+| `setTo` | number | Whether the role was awarded or removed |
+
+___
+
+### updateExtensions
+
+▸ **updateExtensions**(): `Promise`<`void`\>
+
+Refresh colony extensions
+
+Call this function after a new extension was installed.
+It will then become available under `colony.ext`
+
+#### Returns
+
+`Promise`<`void`\>
+
+___
+
+### getLatestSupportedVersion
+
+▸ `Static` **getLatestSupportedVersion**(): ``10``
+
+#### Returns
+
+``10``
+
+___
+
+### init
+
+▸ `Static` **init**(`colonyNetwork`, `colonyClient`): `Promise`<[`Colony`](Colony.md)\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `colonyNetwork` | [`ColonyNetwork`](ColonyNetwork.md) |
+| `colonyClient` | `ColonyClientV10` |
+
+#### Returns
+
+`Promise`<[`Colony`](Colony.md)\>
diff --git a/docs/api/classes/ColonyEventManager.md b/docs/api/classes/ColonyEventManager.md
@@ -89,7 +89,7 @@ Filter for all `DomainAdded` events between block 21830000 and 21840000 (across
 | `eventName` | `N` | A valid event signature from the contract's `filters` object |
 | `address?` | `string` | Address of the contract that can emit this event |
 | `params?` | `Parameters`<`T`[``"filters"``][`N`]\> | Parameters to filter by for the event. Has to be indexed in the contract (see _ethers_ [Event Filters](https://docs.ethers.io/v5/api/contract/contract/#Contract--filters)) |
-| `options?` | `Object` | You can define `fromBlock` and `toBlock` only once for all the filters given |
+| `options?` | `Object` | You can define `fromBlock` and `toBlock` only once for all the filters given (default for both is `latest`) |
 | `options.fromBlock?` | `BlockTag` | - |
 | `options.toBlock?` | `BlockTag` | - |
 
@@ -238,9 +238,9 @@ const domainMetadata = colonyEvents.createMultiFilter(
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `filters` | [`ColonyMultiFilter`](../interfaces/ColonyMultiFilter.md)[] | An array of [ColonyMultiFilter](../interfaces/ColonyMultiFilter.md)s. Normal [ColonyFilter](../interfaces/ColonyFilter.md)s will not work |
-| `options` | `Object` | You can define `fromBlock` and `toBlock` only once for all the filters given |
-| `options.fromBlock?` | `BlockTag` | Starting block in which to look for this event - inclusive (default: 'latest') |
-| `options.toBlock?` | `BlockTag` | Ending block in which to look for this event - inclusive (default: 'latest') |
+| `options` | `Object` | You can define `fromBlock` and `toBlock` only once for all the filters given (default for both is `latest`) |
+| `options.fromBlock?` | `BlockTag` | - |
+| `options.toBlock?` | `BlockTag` | - |
 
 #### Returns