Skip to main content

Class: ColonyEventManager

The ColonyEvents class is a wrapper around ethers's event implementations to make it easier to track and fetch Colony related events. It works by creating specific filters that can keep track of event sources and map filters to their respective events. This allows for easy parsing of event data, without necessarily knowing the contract that emitted it.

Remarks​

The API is subject to change as we find more applications for this

Constructors​

new ColonyEventManager()​

new ColonyEventManager(provider, options?): ColonyEventManager

Create a new ColonyEvents instance

Parameters​

provider​

JsonRpcProvider

An ethers JsonRpcProvider

options?​

ColonyEventManagerOptions

Optional custom ColonyEventManagerOptions

Returns​

ColonyEventManager

A ColonyEvents instance

Remarks​

As opposed to the ColonyNetwork class, this constructor needs an ethers JsonRpcProvider (or a subclass of it) as it's the only provider that supports topic filtering by multiple addresses

Properties​

ipfs​

ipfs: IpfsMetadata

provider​

provider: JsonRpcProvider

Methods​

createEventSource()​

createEventSource\<T>(contractFactory): T

Create an event source to create filters with

This method can be used to instantiate contract event sources from virtually any TypeChain ContractFactory (has to have the .connect() method) that can then be used with the EventManager. Best to use with the contracts from @colony/events as they all are compatible

Type Parameters​

• T extends BaseContract

Parameters​

contractFactory​

ContractFactory\<T>

A TypeChain compatible contract factory

Returns​

T

An event source contract (it's just an ethers Contract)

Example​

Create an event source from the IColonyEventsFactory

import { ColonyEventManager } from '@colony/sdk';
import { IColonyEvents__factory as ColonyEventsFactory } from '@colony/events';

const manager = new ColonyEventManager(provider);
// Event source that can be plugged into a filter creation method
const colonyEventSource = manager.createEventSource(ColonyEventsFactory);

createFilter()​

createFilter\<T, N>(eventSource, eventName, address?, params?, options?): ColonyFilter

Create a ColonyFilter that keeps track of its event source

To create a ColonyFilter, we need to not only give it the topics and addresses as required by ethers Filters, but also the actual source contract of that Filter. Like this we can keep track of the source contract interface to parse the event data when it's emitted

Type Parameters​

• T extends BaseContract & object

Needs to be a valid EventSource (i.e. from colonyEvents.eventSources)

• N extends string | number | symbol

An event signature as defined in the ethers contract's filters object. See the ColonyJS documentation for a list of all available contracts and events

Parameters​

eventSource​

T

eventName​

N

A valid event signature from the contract's filters object

address?​

string

Address of the contract that can emit this event. Will listen to any contract if not provided

params?​

Parameters\<T["filters"][N]>

Parameters to filter by for the event. Has to be indexed in the contract (see ethers Event Filters)

options?​

You can define fromBlock and toBlock only once for all the filters given (default for both is latest)

fromBlock​

BlockTag

toBlock​

BlockTag

Returns​

ColonyFilter

A ColonyFilter

Remarks​

We can do that as we do not have ambiguous events across our contracts, so we will always be able to find the right contract to parse the event data later on

Example​

Filter for all DomainAdded events between block 21830000 and 21840000 (across all deployed ColonyNetwork contracts)

 const domainAdded = colonyEvents.createFilter(
   colonyEventSource,
   'DomainAdded(address,uint256)',
   null,
   { fromBlock: 21830000 , toBlock: 21840000  },
);

createMultiFilter()​

createMultiFilter\<T, N>(contract, eventNames, address?): ColonyMultiFilter

Create a ColonyMultiFilter that keeps track of its event source and can work alongside other filters in getMultiEvents

The ColonyMultiFilter works much like the ColonyFilter, just that we have to specify an address of the contract which emits this event. Furthermore, no fromBlock or toBlock requirements can be given (that is done on a global level in getMultiEvents)

Type Parameters​

• T extends BaseContract & object

Needs to be a valid EventSource (i.e. from colonyEvents.eventSources)

• N extends string | number | symbol

An event signature as defined in the ethers contract's filters object. See the ColonyJS documentation for a list of all available contracts and events

Parameters​

contract​

T

A valid EventSource

eventNames​

N[]

A list of valid event signatures from the contract's filters object

address?​

string

Address of the contract that can emit this event. Will listen to any contract if not provided

Returns​

ColonyMultiFilter

A ColonyMultiFilter

Remarks​

We can do that as we do not have ambiguous events across our contracts, so we will always be able to find the right contract to parse the event data later on. Note that ColonyMultiFilter does not allow for params to be passed in.

Example​

Filter for all DomainAdded events for a specific Colony contract

const domainAdded = colonyEvents.createFilter(
  colonyEventSource,
  'DomainAdded(address,uint256)',
  colonyAddress,
);

getEvents()​

getEvents\<T>(filter): Promise\<ColonyEvent\<T>[]>

Get events for a single filter

Gets events for an individual filter and automatically parses the data if possible

Type Parameters​

• T extends MetadataType

Parameters​

filter​

ColonyFilter

A ColonyFilter, ColonyMultiFilters will not work

Returns​

Promise\<ColonyEvent\<T>[]>

An array of ColonyEvents

Example​

Retrieve and parse all DomainAdded events for a specific Colony contract

const domainAdded = colonyEvents.createFilter(
   colonyEventSource,
  'DomainAdded(address,uint256)',
  colonyAddress,
);
// Immediately executing async function
(async function() {
  const events = await colonyEvents.getEvents(domainAdded);
})();

getMultiEvents()​

getMultiEvents\<T>(filters, options?): Promise\<ColonyEvent\<T>[]>

Get events for multiple filters across multiple addresses at once

All the filters are connected by a logical OR, i.e. it will find ALL given events for ALL the given contract addresses This is handy when you want to listen to a fixed set of events for a lot of different contracts

Type Parameters​

• T extends MetadataType

Parameters​

filters​

An array of ColonyMultiFilters. Normal ColonyFilters will not work

ColonyMultiFilter | ColonyMultiFilter[]

options?​

You can define fromBlock and toBlock only once for all the filters given (default for both is latest)

fromBlock​

BlockTag

toBlock​

BlockTag

Returns​

Promise\<ColonyEvent\<T>[]>

An array of ColonyEvents

Remarks​

fromBlock and toBlock properties of the indivdual filters will be ignored

Example​

Retrieve and parse all DomainAdded and DomainMetadata events for a specific ColonyNetwork contract. Note that we're using createMultiFilter here. The two colonyAddresses could also be different

const domainAdded = colonyEvents.createMultiFilter(
  colonyEventSource,
  'DomainAdded(address,uint256)',
  colonyAddress,
);
const domainMetadata = colonyEvents.createMultiFilter(
  colonyEventSource,
  'DomainMetadata(address,uint256,string)',
  colonyAddress,
);

// Immediately executing async function
(async function() {
  const events = await colonyEvents.getMultiEvents([domainAdded, domainMetadata]);
})();