Ethers v6 error on listening to contracts documentation

[jpiabrantes]

Suggestion

In this page

it says:

filter = contract.filters.Transfer("ethers.eth")
contract.on(filter, (from, to, amount, event) => {
  // `to` will always be equal to the address of "ethers.eth"
});

I think you meant that from will always be equal to the address of "ethers.eth".

But also my callback is just receiving a single argument: ContractEventPayload.

contract.on(contract.filters.Transfer(userAddress), (payload) => {
    console.log(payload.args[0]); // from = to userAddress
    console.log(payload.args[1]); // to
    console.log(payload.args[2]); // value
});

This was really hard to figure out!

I am getting ethers from: https://cdnjs.cloudflare.com/ajax/libs/ethers/6.13.5/ethers.umd.min.js

[chainide-agent-bob]

Thank you for reporting this issue!

After reviewing the code, I've identified a documentation error that needs to be fixed.

The current example in the documentation has conflicting information:

• The comment states: "Listen for any Transfer to 'ethers.eth'"
• However, the code contract.filters.Transfer("ethers.eth") actually filters for transfers FROM ethers.eth, not TO it

This is because in ERC-20 Transfer events, the parameters are ordered as:

event Transfer(address indexed from, address indexed to, uint256 value);

To correctly filter for transfers TO ethers.eth as the comment suggests, the code should be:

filter = contract.filters.Transfer(null, "ethers.eth")

Reference:
You can find the relevant code in the documentation source here:
docs.wrm/getting-started.wrm lines 421-425
and
docs.wrm/getting-started.wrm line 465

Regarding the ContractEventPayload in v6, this is a valid feature. The v6 implementation supports two callback patterns:

• Destructured arguments: (from, to, amount, event) => {}
• Single payload object: (payload) => { /* access payload.args, payload.log, etc. */ }

I've created a PR that corrects the example to match the intended behavior described in the comment, ensuring the documentation is accurate and consistent.

Thanks for bringing this to our attention!

[jpiabrantes]

The v6 implementation supports two callback patterns:

That wording is misleading. When the first arg is a filter object like contract.filters.Transfer(userAddress) then we get a Single payload object. If the first arg is a string like "Transfer" then we get destructured arguments.