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

constructor

new ColonyEventManager(provider, options?)

Create a new 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

Parameters

NameTypeDescription
providerJsonRpcProviderAn ethers JsonRpcProvider
options?ColonyEventManagerOptionsOptional custom ColonyEventManagerOptions

Properties

eventSources

eventSources: EventSources


ipfs

ipfs: IpfsMetadata


provider

provider: JsonRpcProvider

Methods

createFilter

createFilter<T, N>(contract, 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

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(
colonyEvents.eventSources.Colony,
'DomainAdded(address,uint256)',
null,
{ fromBlock: 21830000 , toBlock: 21840000 },
);

Type parameters

NameTypeDescription
Textends ObjectNeeds to be a valid EventSource (i.e. from colonyEvents.eventSources)
Nextends string | number | symbolAn 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

NameTypeDescription
contractTA valid EventSource
eventNameNA valid event signature from the contract's filters object
address?stringAddress 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)
options?ObjectYou can define fromBlock and toBlock only once for all the filters given
options.fromBlock?BlockTag-
options.toBlock?BlockTag-

Returns

ColonyFilter

A ColonyFilter


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)

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(
colonyEvents.eventSources.Colony,
'DomainAdded(address,uint256)',
colonyAddress,
);

Type parameters

NameTypeDescription
Textends ObjectNeeds to be a valid EventSource (i.e. from colonyEvents.eventSources)
Nextends string | number | symbolAn 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

NameTypeDescription
contractTA valid EventSource
eventNamesN[]A list of valid event signatures from the contract's filters object
addressstringAddress of the contract that can emit this event

Returns

ColonyMultiFilter

A ColonyMultiFilter


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

Example

Retrieve and parse all DomainAdded events for a specific Colony contract

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

Type parameters

NameType
Textends MetadataType

Parameters

NameTypeDescription
filterColonyFilterA ColonyFilter. ColonyMultiFilters will not work

Returns

Promise<ColonyEvent<T>[]>

An array of ColonyEvents


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

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(
colonyEvents.eventSources.Colony,
'DomainAdded(address,uint256)',
colonyAddress,
);
const domainMetadata = colonyEvents.createMultiFilter(
colonyEvents.eventSources.Colony,
'DomainMetadata(address,uint256,string)',
colonyAddress,
);

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

Type parameters

NameType
Textends MetadataType

Parameters

NameTypeDescription
filtersColonyMultiFilter[]An array of ColonyMultiFilters. Normal ColonyFilters will not work
optionsObjectYou can define fromBlock and toBlock only once for all the filters given
options.fromBlock?BlockTagStarting block in which to look for this event - inclusive (default: 'latest')
options.toBlock?BlockTagEnding block in which to look for this event - inclusive (default: 'latest')

Returns

Promise<ColonyEvent<T>[]>

An array of ColonyEvents