Merge pull request #137 from JoinColony/feature/ipfs-metadata

Complete overhaul of Colony metadata parsing
JoinColony · Nov 14, 2022 · 536e0e0 · 536e0e0
2 parents deeed7e + b80037c
commit 536e0e0
Show file tree

Hide file tree

Showing 29 changed files with 1,747 additions and 376 deletions.
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -14,41 +14,63 @@
 
 ## Classes
 
+- [CloudflareReadonlyAdapter](classes/CloudflareReadonlyAdapter.md)
 - [Colony](classes/Colony.md)
 - [ColonyEventManager](classes/ColonyEventManager.md)
 - [ColonyNetwork](classes/ColonyNetwork.md)
 - [ColonyToken](classes/ColonyToken.md)
 - [MotionCreator](classes/MotionCreator.md)
+- [PinataAdapter](classes/PinataAdapter.md)
 - [VotingReputation](classes/VotingReputation.md)
 
 ## Interfaces
 
 - [ColonyEvent](interfaces/ColonyEvent.md)
+- [ColonyEventManagerOptions](interfaces/ColonyEventManagerOptions.md)
 - [ColonyFilter](interfaces/ColonyFilter.md)
 - [ColonyMultiFilter](interfaces/ColonyMultiFilter.md)
 - [Ethers6Filter](interfaces/Ethers6Filter.md)
 - [Ethers6FilterByBlockHash](interfaces/Ethers6FilterByBlockHash.md)
 - [EventSources](interfaces/EventSources.md)
+- [IpfsAdapter](interfaces/IpfsAdapter.md)
 
 ## Type Aliases
 
-### AnyMetadataValue
+### EventSource
 
-Ƭ **AnyMetadataValue**: `Static`<typeof `IPFS_METADATA`[[`MetadataKey`](README.md#metadatakey)]\>
+Ƭ **EventSource**: [`EventSources`](interfaces/EventSources.md)[keyof [`EventSources`](interfaces/EventSources.md)]
+
+An EventSource is essentially an _ethers_ contract, that we can keep track of
 
 ___
 
-### EventSource
+### MetadataEvent
 
-Ƭ **EventSource**: [`EventSources`](interfaces/EventSources.md)[keyof [`EventSources`](interfaces/EventSources.md)]
+Ƭ **MetadataEvent**: keyof typeof `IPFS_METADATA_EVENTS`
 
-An EventSource is essentially an _ethers_ contract, that we can keep track of
+___
+
+### MetadataEventValue
+
+Ƭ **MetadataEventValue**<`K`\>: `ReturnType`<typeof `IPFS_METADATA_PARSERS`[typeof `IPFS_METADATA_EVENTS`[`K`]]\>
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `K` | extends [`MetadataEvent`](README.md#metadataevent) |
 
 ___
 
-### MetadataKey
+### MetadataValue
 
-Ƭ **MetadataKey**: keyof typeof `IPFS_METADATA`
+Ƭ **MetadataValue**<`K`\>: `ReturnType`<typeof `IPFS_METADATA_PARSERS`[`K`]\>
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `K` | extends `MetadataType` |
 
 ## Functions
 

diff --git a/docs/api/classes/CloudflareReadonlyAdapter.md b/docs/api/classes/CloudflareReadonlyAdapter.md
@@ -0,0 +1,75 @@
+# Class: CloudflareReadonlyAdapter
+
+CloudflareReadonlyAdapter
+
+A Colony SDK IPFS adapter for Cloudflare IPFS (https://developers.cloudflare.com/web3/ipfs-gateway/). It only supports reading IPFS data from the Cloudflare gateway (not uploading or pinning files).
+
+This is the default IpfsAdapter used in Colony SDK. So in order to use this, you don't have to do anything.
+
+## Implements
+
+- [`IpfsAdapter`](../interfaces/IpfsAdapter.md)
+
+## Constructors
+
+### constructor
+
+• **new CloudflareReadonlyAdapter**()
+
+## Properties
+
+### name
+
+• **name**: `string` = `'CLOUDFLARE'`
+
+Name for the IpfsAdapter. All uppercase please
+
+#### Implementation of
+
+[IpfsAdapter](../interfaces/IpfsAdapter.md).[name](../interfaces/IpfsAdapter.md#name)
+
+## Methods
+
+### getIpfsUrl
+
+▸ **getIpfsUrl**(`cid`): `string`
+
+Should return the whole URL to an IPFS resource on the corresponding gateway (e.g. https://my-ipfs-gateway/ipfs/QmXxxxXXxxXxXxXxxxXXxxxXxXXx).
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `cid` | `string` | An IPFS hash (CID) |
+
+#### Returns
+
+`string`
+
+The URL to an ipfs resource
+
+#### Implementation of
+
+[IpfsAdapter](../interfaces/IpfsAdapter.md).[getIpfsUrl](../interfaces/IpfsAdapter.md#getipfsurl)
+
+___
+
+### uploadJson
+
+▸ **uploadJson**(): `Promise`<`string`\>
+
+Function to upload a JSON string to IPFS. Takes the string as an argument (use `JSON.stringify()` if needbe). Returns a promise that resolves to the IPFS hash (CID)
+
+**`Remarks`**
+
+This function should ideally **pin** your data on the relevant service.
+
+#### Returns
+
+`Promise`<`string`\>
+
+Promise to IPFS hash (CID)
+
+#### Implementation of
+
+[IpfsAdapter](../interfaces/IpfsAdapter.md).[uploadJson](../interfaces/IpfsAdapter.md#uploadjson)
diff --git a/docs/api/classes/Colony.md b/docs/api/classes/Colony.md
@@ -45,6 +45,54 @@ If this is not an option, Colony SDK might throw errors at certain points. Usage
 
 ## Methods
 
+### annotateTransaction
+
+▸ **annotateTransaction**(`txHash`, `annotationMsg`): `Promise`<[{ `agent?`: `string` ; `metadata?`: `string` ; `txHash?`: `string`  }, `ContractReceipt`]\>
+
+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.
+
+**`Remarks`**
+
+Requires an [IpfsAdapter](../interfaces/IpfsAdapter.md) that can upload and pin to IPFS. See its documentation for more information
+
+**`Example`**
+
+```typescript
+// Immediately executing async function
+(async function() {
+  // Annotate a motion transaction to pay ourselves a little bonus :)
+  await colony.annotateTransaction(
+     '0xf1940d38e0a74262643a75b0f826353d62a505aedd9c95ae5fb5da6856e4adb2',
+        'I am creating this motion because I think I deserve a little bonus'
+  );
+})();
+```
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `txHash` | `string` | Transaction hash of the transaction to annotate (within the Colony) |
+| `annotationMsg` | `string` | The text message you would like to annotate the transaction with |
+
+#### Returns
+
+`Promise`<[{ `agent?`: `string` ; `metadata?`: `string` ; `txHash?`: `string`  }, `ContractReceipt`]\>
+
+A tupel of event data and contract receipt
+
+**Event data**
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| `agent` | string | The address that is responsible for triggering this event |
+| `txHash` | BigNumber | The hash of the annotated transaction |
+| `metadata` | BigNumber | The IPFS hash (CID) of the metadata object |
+
+___
+
 ### claimFunds
 
 ▸ **claimFunds**(`tokenAddress?`): `Promise`<[{ `fee?`: `BigNumber` ; `payoutRemainder?`: `BigNumber` ; `token?`: `string`  }, `ContractReceipt`]\>
@@ -78,7 +126,7 @@ ___
 
 ### createTeam
 
-▸ **createTeam**(`metadataCid?`): `Promise`<[{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`, () => `Promise`<{ `domainColor`: `number` ; `domainName`: `string` ; `domainPurpose`: `string`  }\>] \| [{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`]\>
+▸ **createTeam**(`metadataCid?`): `Promise`<[{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`, () => `Promise`<`undefined` \| `DomainMetadata`\>] \| [{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`]\>
 
 Create a team within a Colony
 
@@ -94,7 +142,7 @@ Currently you can only add domains within the `Root` domain. This restriction wi
 
 #### Returns
 
-`Promise`<[{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`, () => `Promise`<{ `domainColor`: `number` ; `domainName`: `string` ; `domainPurpose`: `string`  }\>] \| [{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`]\>
+`Promise`<[{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`, () => `Promise`<`undefined` \| `DomainMetadata`\>] \| [{ `agent?`: `string` ; `domainId?`: `BigNumber` ; `fundingPotId?`: `BigNumber` ; `metadata?`: `string`  }, `ContractReceipt`]\>
 
 A tupel: `[eventData, ContractReceipt, getMetaData]`
 

diff --git a/docs/api/classes/ColonyEventManager.md b/docs/api/classes/ColonyEventManager.md
@@ -12,7 +12,7 @@ The API is subject to change as we find more applications for this
 
 ### constructor
 
-• **new ColonyEventManager**(`provider`)
+• **new ColonyEventManager**(`provider`, `options?`)
 
 Create a new ColonyEvents instance
 
@@ -26,6 +26,7 @@ the only provider that supports topic filtering by multiple addresses
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `provider` | `JsonRpcProvider` | An _ethers_ `JsonRpcProvider` |
+| `options?` | [`ColonyEventManagerOptions`](../interfaces/ColonyEventManagerOptions.md) | Optional custom [ColonyEventManagerOptions](../interfaces/ColonyEventManagerOptions.md) |
 
 ## Properties
 
@@ -35,9 +36,9 @@ the only provider that supports topic filtering by multiple addresses
 
 ___
 
-### ipfsMetadata
+### ipfs
 
-• **ipfsMetadata**: `IpfsMetadata`
+• **ipfs**: `IpfsMetadata`
 
 ___
 
@@ -149,7 +150,7 @@ ___
 
 ### getEvents
 
-▸ **getEvents**(`filter`): `Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)[]\>
+▸ **getEvents**(`filter`): `Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)<``"Annotation(address,bytes32,string)"`` \| ``"ColonyMetadata(address,string)"`` \| ``"DomainMetadata(address,uint256,string)"`` \| ``"Decision"`` \| ``"MISC"``\>[]\>
 
 Get events for a single filter
 
@@ -178,15 +179,15 @@ const domainAdded = colonyEvents.createFilter(
 
 #### Returns
 
-`Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)[]\>
+`Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)<``"Annotation(address,bytes32,string)"`` \| ``"ColonyMetadata(address,string)"`` \| ``"DomainMetadata(address,uint256,string)"`` \| ``"Decision"`` \| ``"MISC"``\>[]\>
 
 An array of [ColonyEvent](../interfaces/ColonyEvent.md)s
 
 ___
 
 ### getMultiEvents
 
-▸ **getMultiEvents**(`filters`, `options?`): `Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)[]\>
+▸ **getMultiEvents**(`filters`, `options?`): `Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)<``"Annotation(address,bytes32,string)"`` \| ``"ColonyMetadata(address,string)"`` \| ``"DomainMetadata(address,uint256,string)"`` \| ``"Decision"`` \| ``"MISC"``\>[]\>
 
 Get events for multiple filters across multiple addresses at once
 
@@ -231,6 +232,6 @@ const domainMetadata = colonyEvents.createMultiFilter(
 
 #### Returns
 
-`Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)[]\>
+`Promise`<[`ColonyEvent`](../interfaces/ColonyEvent.md)<``"Annotation(address,bytes32,string)"`` \| ``"ColonyMetadata(address,string)"`` \| ``"DomainMetadata(address,uint256,string)"`` \| ``"Decision"`` \| ``"MISC"``\>[]\>
 
 An array of [ColonyEvent](../interfaces/ColonyEvent.md)s
diff --git a/docs/api/classes/ColonyNetwork.md b/docs/api/classes/ColonyNetwork.md
@@ -28,13 +28,13 @@ const colonyNetwork = new ColonyNetwork(provider);
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `signerOrProvider` | `SignerOrProvider` | An _ethers_ compatible Signer or Provider instance |
-| `options?` | `NetworkClientOptions` | Pass in a custom ColonyNetwork address or Reputation Miner endpoint |
+| `options?` | `ColonyNetworkOptions` | Optional custom ColonyNetworkOptions |
 
 ## Properties
 
-### ipfsMetadata
+### ipfs
 
-• **ipfsMetadata**: `IpfsMetadata`
+• **ipfs**: `IpfsMetadata`
 
 ___
 

diff --git a/docs/api/classes/PinataAdapter.md b/docs/api/classes/PinataAdapter.md
@@ -0,0 +1,97 @@
+# Class: PinataAdapter
+
+PinataAdapter
+
+A Colony SDK IPFS adapter for Pinata (https://pinata.cloud). In order to use this, sign up for Pinata (if you haven't already) and generate a token. Then either supply this token when instantiating the class (example below) or provide it via the environment variable `COLONY_IPFS_PINATA_TOKEN`. Then provide an instance of this class to the [ColonyNetwork](ColonyNetwork.md) or ColonyEventManger classes (depending on your needs).
+
+**`Remarks`**
+
+DO NOT CHECK IN YOUR PINATA TOKEN INTO VERSION CONTROL AND **DO NOT EMBED IT INTO YOUR FRONTEND BUNDLE**.
+
+**`Example`**
+
+```typescript
+import { ColonyNetwork, PinataAdapter } from '@colony/sdk';
+const pinataAdapter = new PinataAdapter('YOUR_PINANTA_JWT_TOKEN');
+const colonyNetwork = new ColonyNetwork({ ipfsAdapter: pinataAdapter });
+```
+
+## Implements
+
+- [`IpfsAdapter`](../interfaces/IpfsAdapter.md)
+
+## Constructors
+
+### constructor
+
+• **new PinataAdapter**(`pinataToken?`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `pinataToken?` | `string` |
+
+## Properties
+
+### name
+
+• **name**: `string` = `'PINATA'`
+
+Name for the IpfsAdapter. All uppercase please
+
+#### Implementation of
+
+[IpfsAdapter](../interfaces/IpfsAdapter.md).[name](../interfaces/IpfsAdapter.md#name)
+
+## Methods
+
+### getIpfsUrl
+
+▸ **getIpfsUrl**(`cid`): `string`
+
+Should return the whole URL to an IPFS resource on the corresponding gateway (e.g. https://my-ipfs-gateway/ipfs/QmXxxxXXxxXxXxXxxxXXxxxXxXXx).
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `cid` | `string` | An IPFS hash (CID) |
+
+#### Returns
+
+`string`
+
+The URL to an ipfs resource
+
+#### Implementation of
+
+[IpfsAdapter](../interfaces/IpfsAdapter.md).[getIpfsUrl](../interfaces/IpfsAdapter.md#getipfsurl)
+
+___
+
+### uploadJson
+
+▸ **uploadJson**(`jsonString`): `Promise`<`string`\>
+
+Function to upload a JSON string to IPFS. Takes the string as an argument (use `JSON.stringify()` if needbe). Returns a promise that resolves to the IPFS hash (CID)
+
+**`Remarks`**
+
+This function should ideally **pin** your data on the relevant service.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `jsonString` | `string` | JSON string to upload (and pin) to IPFS |
+
+#### Returns
+
+`Promise`<`string`\>
+
+Promise to IPFS hash (CID)
+
+#### Implementation of
+
+[IpfsAdapter](../interfaces/IpfsAdapter.md).[uploadJson](../interfaces/IpfsAdapter.md#uploadjson)