Skip to content
This repository has been archived by the owner on May 8, 2023. It is now read-only.

Commit

Permalink
Merge pull request #143 from JoinColony/feat/dapp-functions
Browse files Browse the repository at this point in the history 
Add missing dapp functions
  • Loading branch information
@chmanie
chmanie authored Dec 19, 2022
2 parents 690c517 + 61f6dd1 commit a5eea23
Show file tree
Hide file tree
Showing 12 changed files with 1,090 additions and 61 deletions.
10 changes: 10 additions & 0 deletions docs/api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,16 @@ ___
| :------ | :------ |
| `K` | extends [`MetadataType`](enums/MetadataType.md) |

## Variables

### DecisionMotionCode

• `Const` **DecisionMotionCode**: ``"0x12345678"``

Identifies a motion as a decision

Usually there's no need to use this directly. Use [VotingReputation.createDecision](classes/VotingReputation.md#createdecision) instead.

## Functions

### addressesAreEqual
Expand Down
281 changes: 278 additions & 3 deletions docs/api/classes/Colony.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,11 @@ If this is not an option, Colony SDK might throw errors at certain points. Usage

### annotateTransaction

▸ **annotateTransaction**(`txHash`, `annotationMetadata`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"annotateTransaction"``, { `agent?`: `string` ; `metadata?`: `string` ; `txHash?`: `string` }, [`Annotation`](../enums/MetadataType.md#annotation)\>
▸ **annotateTransaction**(`txHash`, `metadata`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"annotateTransaction"``, { `agent?`: `string` ; `metadata?`: `string` ; `txHash?`: `string` }, [`Annotation`](../enums/MetadataType.md#annotation)\>

Annotate a transaction with IPFS metadata to provide extra information

This will annotate a transaction with an arbitrary text message. This only really works for transactions that happened within this Colony. This will upload the text string to IPFS and connect the transaction to the IPFS hash accordingly.
This will annotate a transaction with an arbitrary text message. This only really works for transactions that happened within this Colony. This will connect the transaction to the (optionally generated) IPFS hash accordingly.

**`Remarks`**

Expand Down Expand Up @@ -86,7 +86,7 @@ If [AnnotationMetadata](../interfaces/AnnotationMetadata.md) is provided directl
| Name | Type | Description |
| :------ | :------ | :------ |
| `txHash` | `string` | Transaction hash of the transaction to annotate (within the Colony) |
| `annotationMetadata` | `string` \| [`AnnotationMetadata`](../interfaces/AnnotationMetadata.md) | The annotation metadata you would like to annotate the transaction with (or an IPFS CID pointing to valid metadata) |
| `metadata` | `string` \| [`AnnotationMetadata`](../interfaces/AnnotationMetadata.md) | The annotation metadata you would like to annotate the transaction with (or an IPFS CID pointing to valid metadata) |

#### Returns

Expand All @@ -102,6 +102,49 @@ A transaction creator
| `txHash` | BigNumber | The hash of the annotated transaction |
| `metadata` | BigNumber | The IPFS hash (CID) of the metadata object |

**Metadata** (can be obtained by calling and awaiting the `getMetadata` function)

| Property | Type | Description |
| :------ | :------ | :------ |
| `annotationMsg` | string | Free form text message to annotate the transaction with |

___

### awardReputation

▸ **awardReputation**(`address`, `amount`, `team?`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"emitDomainReputationReward"``, { `agent?`: `string` ; `amount?`: `BigNumber` ; `skillId?`: `BigNumber` ; `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

Award reputation to a user within a team

Use with care. An imbalance of native tokens and reputation might influence your governance process negatively

**`Remarks`**

Only users with *Root* role are allowed to award reputation

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `address` | `string` | `undefined` | Address of user to award reputation |
| `amount` | `BigNumberish` | `undefined` | Amount of reputation to award |
| `team` | `BigNumberish` | `Id.RootDomain` | Team to award reputation in (defaults to Root team) |

#### Returns

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"emitDomainReputationReward"``, { `agent?`: `string` ; `amount?`: `BigNumber` ; `skillId?`: `BigNumber` ; `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `agent` | string | The address that is responsible for triggering this event |
| `user` | string | User who was awarded reputation |
| `skillId` | BigNumber | Corresponding skillId to the team |
| `amount` | BigNumber | Amount that was awarded |

___

### claimFunds
Expand Down Expand Up @@ -284,6 +327,167 @@ A transaction creator

___

### editColony

▸ **editColony**(`metadata`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"editColony"``, { `agent?`: `string` ; `metadata?`: `string` }, [`Colony`](../enums/MetadataType.md#colony)\>

Edit a colony's metadata

**`Remarks`**

This will overwrite all exisiting metadata!

**`Example`**

```typescript
// Immediately executing async function
(async function() {
// Edit the metadata of a colony
// (forced transaction example)
// (also notice that this requires an upload-capable IPFS adapter)
await colony.edit({
colonyDisplayName: 'My super cool Colony',
}).tx();
})();
```

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `metadata` | `string` \| [`ColonyMetadata`](../interfaces/ColonyMetadata.md) | The team metadata you would like to add (or an IPFS CID pointing to valid metadata). If [ColonyMetadata](../interfaces/ColonyMetadata.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

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"editColony"``, { `agent?`: `string` ; `metadata?`: `string` }, [`Colony`](../enums/MetadataType.md#colony)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `colonyId` | BigNumber | Auto-incremented integer id of the colony |
| `colonyAddress` | string | Address of the newly deployed colony contract |
| `token` | string | Address of the token that is used as the colony's native token |
| `metadata` | string | IPFS CID of metadata attached to this transaction |

**Metadata** (can be obtained by calling and awaiting the `getMetadata` function)

| Property | Type | Description |
| :------ | :------ | :------ |
| `colonyDisplayName` | string | The name that should be displayed for the colony |
| `colonyAvatarHash` | string | An IPFS hash for a Colony logo (make it 200x200px) |
| `colonyTokens` | string[] | A list of additional tokens that should be in the colony's "address book" |

___

### editTeam

▸ **editTeam**(`metadata`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"editDomain"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `metadata?`: `string` }, [`Domain`](../enums/MetadataType.md#domain)\>

Edit a team (domain) within a Colony with team details as metadata

**`Remarks`**

This will overwrite all exisiting metadata!

**`Example`**

```typescript
import { TeamColor } from '@colony/sdk';

// Immediately executing async function
(async function() {
// Edit team of the butter-passers
// (forced transaction example)
// (also notice that this requires an upload-capable IPFS adapter)
await colony.editTeam({
domainName: 'Purple Butter-passers',
domainColor: TeamColor.Purple,
domainPurpose: 'To pass purple butter',
}).tx();
})();
```

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `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

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"editDomain"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `metadata?`: `string` }, [`Domain`](../enums/MetadataType.md#domain)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `agent` | string | The address that is responsible for triggering this event |
| `domainId` | BigNumber | Integer domain id of the created team |
| `metadata` | string | IPFS CID of metadata attached to this transaction |

**Metadata** (can be obtained by calling and awaiting the `getMetadata` function)

| Property | Type | Description |
| :------ | :------ | :------ |
| `domainName` | string | The human readable name assigned to this team |
| `domainColor` | string | The color assigned to this team |
| `domainPurpose` | string | The purpose for this team (a broad description) |

___

### enterRecoveryMode

▸ **enterRecoveryMode**(): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"enterRecoveryMode"``, { `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

Put the colony into Recovery Mode

In Recovery Mode, no actions are possible on the colony. Only users who have the special *Recovery* role can put a colony into this mode

**`Remarks`**

Be aware that to exit Recovery Mode a quorum of 50% is needed of all users who have the *Recovery* role

#### Returns

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"enterRecoveryMode"``, { `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `user` | string | The address of the user who activated Recovery Mode |

___

### exitRecoveryMode

▸ **exitRecoveryMode**(): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"exitRecoveryMode"``, { `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

Exit Recovery Mode

In Recovery Mode, no actions are possible on the colony. Only users who have the special *Recovery* role can execute this method. If you have multiple users with the *Recovery* role, at least 50% of the users have to execute this method for the Colony to leave Recovery Mode

#### Returns

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"exitRecoveryMode"``, { `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `user` | string | The address of the user who initiated the exit of Recovery Mode |

___

### getBalance

▸ **getBalance**(`tokenAddress?`, `teamId?`): `Promise`<`BigNumber`\>
Expand Down Expand Up @@ -653,6 +857,43 @@ Heads up!* This event is emitted for every role that was set

___

### smiteReputation

▸ **smiteReputation**(`address`, `amount`, `team?`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"emitDomainReputationPenalty"``, { `agent?`: `string` ; `amount?`: `BigNumber` ; `skillId?`: `BigNumber` ; `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

Smite (remove) reputation from a user within a team

Use with care. An imbalance of native tokens and reputation might influence your governance process negatively

**`Remarks`**

Only users with *Arbitration* role are allowed to award reputation

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `address` | `string` | `undefined` | Address of user to smite reputation |
| `amount` | `BigNumberish` | `undefined` | Amount of reputation to remove |
| `team` | `BigNumberish` | `Id.RootDomain` | Team to remove reputation in (defaults to Root team) |

#### Returns

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"emitDomainReputationPenalty"``, { `agent?`: `string` ; `amount?`: `BigNumber` ; `skillId?`: `BigNumber` ; `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `agent` | string | The address that is responsible for triggering this event |
| `user` | string | User who was awarded reputation |
| `skillId` | BigNumber | Corresponding skillId to the team |
| `amount` | BigNumber | Amount that was removed (will be negative) |

___

### unsetRoles

▸ **unsetRoles**(`address`, `roles`, `teamId?`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"setUserRoles"``, { `agent?`: `string` ; `domainId?`: `BigNumber` ; `role?`: `number` ; `setTo?`: `boolean` ; `user?`: `string` }, [`MetadataType`](../enums/MetadataType.md)\>
Expand Down Expand Up @@ -701,6 +942,40 @@ It will then become available under `colony.ext`

___

### upgrade

▸ **upgrade**(`toVersion?`): [`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"upgrade"``, { `newVersion?`: `BigNumber` ; `oldVersion?`: `BigNumber` }, [`MetadataType`](../enums/MetadataType.md)\>

Upgrade a colony to the next or a custom version

This method upgrades the colony to a specified version or, if no version is provided to the next higher version.

**`Remarks`**

* Only users with *Root* role are allowed to upgrade a colony (or an extension with appropriate permissions)
* Downgrading of colonies is not possible

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `toVersion?` | `BigNumberish` | Specify a custom version to upgrade the colony to |

#### Returns

[`ColonyTxCreator`](ColonyTxCreator.md)<`ColonyClientV10`, ``"upgrade"``, { `newVersion?`: `BigNumber` ; `oldVersion?`: `BigNumber` }, [`MetadataType`](../enums/MetadataType.md)\>

A transaction creator

**Event data**

| Property | Type | Description |
| :------ | :------ | :------ |
| `oldVersion` | BigNumber | Version of the colony before the upgrade |
| `newVersion` | BigNumber | Version of the colony after the upgrade |

___

### getLatestSupportedVersion

▸ `Static` **getLatestSupportedVersion**(): ``10``
Expand Down
10 changes: 5 additions & 5 deletions docs/api/classes/ColonyNetwork.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,9 @@ ___

▸ **createColony**(`tokenAddress`, `label`, `metadata`): [`MetaTxCreator`](MetaTxCreator.md)<`ColonyNetworkClient`, ``"createColony(address,uint256,string,string)"``, { `agent`: `string` ; `colonyAddress`: `string` ; `colonyId`: `BigNumber` ; `metadata`: `string` ; `token`: `string` }, [`Colony`](../enums/MetadataType.md#colony)\>

Create a new Colony with metadata
Create a new colony with metadata

Creates a new Colony with IPFS metadata. To edit metadata at a later point you can call the Colony.editColony method.
Creates a new colony with IPFS metadata. To edit metadata at a later point you can call the [Colony.editColony](Colony.md#editcolony) method.

**`Remarks`**

Expand All @@ -68,7 +68,7 @@ import { Tokens } from '@colony/sdk';
colonyAvatarHash: 'QmS26o1Cmsrx7iw1SSFGEcy22TVDq6VmEZ4XNjpWFyaKUe',
// List of token addresses that the Colony should be initialized with (can be changed later) - excluding ETH and the native token from above
colonyTokens: [Tokens.CLNY],
}).force();
}).tx();
})();
```

Expand Down Expand Up @@ -107,7 +107,7 @@ A transaction creator

Create a new Colony without metadata

Creates a new Colony without IPFS metadata. To add metadata at a later point you can call the Colony.editColony method.
Creates a new Colony without IPFS metadata. To add metadata at a later point you can call the [Colony.editColony](Colony.md#editcolony) method.

**`Remarks`**

Expand All @@ -123,7 +123,7 @@ There is more to creating a fully functional colony that can be used within the
await colonyNetwork
// Use USDC on Gnosis chain as the native token
.createColony('0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83')
.force();
.tx();
})();
```

Expand Down
Loading

0 comments on commit a5eea23

Please sign in to comment.