feat: adding package events to receive contract events

[ReinhardHatko]

Adds package events for watching contract events using the chain-client underneath.
Also supports watching events from best or finalized blocks.

Closes #81

[charlesHetterich]

Can you update the PR description with a sample of how a consumer would use this? I would like to see how this integrates with the existing flows/packages from an end-user's perspective.

If possible it would be great to show a sample without this package and then one with this package, so that the value of this is clear.

[ReinhardHatko]

All that is contained in detail in the readme. Short example:

import { dam } from "./descriptors/dam.js"; // Ink codegen output

const client = new EventClient();
await client.connect();

const sub = client.import { dam } from "./descriptors/dam.js"; // Ink codegen output

const client = new EventClient();
await client.connect();

const sub = client.watchContractEvent(dam, CONTRACT_ADDRESS, (event, meta) => {
  console.log(event.type, event.value);
  console.log(`Block #${meta.block.number}`);
});

// Later
sub.unsubscribe();
client.destroy();
```(dam, CONTRACT_ADDRESS, (event, meta) => {
  console.log(event.type, event.value);
  console.log(`Block #${meta.block.number}`);
});

// Later
sub.unsubscribe();
client.destroy();

If no descriptors are available, there is also a watchRawContractEvent. The main addition of the lib is that using papi, you can subscribe to best blocks.

[UtkarshBhardwaj007]

@ReinhardHatko , can you add this to the contracts package? Events should live there, no?

[ReinhardHatko]

Hey Utkarsh,

The events package should remain separate from contracts. While the current implementation is scoped to contract events, this is a pragmatic constraint, not a design choice.

The reason it's contract-only today is a limitation in how chain-client exposes papi's API: papi's typed .watch() only supports finalized blocks, so best-block subscriptions require the unsafeApi via getClient(descriptor).getUnsafeApi(). This ties the implementation to specific chain descriptors (asset hub), making a generic event watcher impractical without changes upstream.

To remove that limitation, we should do:

1. chain-client exposes getUnsafeApi() on its typed API objects, removing the need to import descriptors and call getClient() directly.
2. The events package generalizes its watchFinalized / watchAtBest internals to work with arbitrary pallet events, not just Revive.ContractEmitted.
3. contracts can later depend on events to offer convenience APIs like contract.onEvent(...), so wiring up the contract address and Ink decoding automatically while delegating the subscription machinery to events.

Integrating it into contracts now would hide reusable subscription infrastructure inside a domain-specific package, making it harder to extract later.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	95.45% (🎯 90%)	1850 / 1938
🔵	Statements	95.05% (🎯 90%)	1940 / 2041
🔵	Functions	96.89% (🎯 90%)	406 / 419
🔵	Branches	89.54% (🎯 90%)	942 / 1052

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/events/src/client.ts	74.78%	60%	90.47%	76.31%	34-48, 107, 119, 254-255, 267, 284-313, 322
packages/events/src/errors.ts	100%	100%	100%	100%
packages/events/src/filter.ts	100%	100%	100%	100%
packages/events/src/watch.ts	96.66%	92.85%	100%	100%	34

Generated in workflow #200 for commit 14ecfca by the Vitest Coverage Report Action