Use tracked Pool Escrows to filter token instance balances (V3.1)

[filo87]

Summary

Implement filtering of token instance balances using the tracked Pool Escrow dataset, so that pool escrow addresses are not treated as user-owned accounts. This will prevent negative balances and keep user-facing balance/position tables dedicated to user-owned addresses.

Background

• Pool escrows are created via poolEscrowFactory.newEscrow($poolId) and emit DeployPoolEscrow(poolId, address).
• The list of pool escrows can be retrieved by calling poolEscrowFactory.escrow($poolId) for all pool ids.
• For backwards compatibility we still maintain the vault.globalEscrow() ABI; this points to the pool escrow as well.
• Pool escrows have indefinite lifetime and can be assumed static for their pool.

Currently we track all token transfers and balances (including to/from pool escrows). That leads to:

• Accounts with negative balances in the position/balance table.
• A table intended for user-owned addresses containing escrow contract addresses, which is not desirable.

We already track pool escrows: they are persisted via the poolEscrowFactory:DeployPoolEscrow handler into the Escrow entity (see EscrowService and poolEscrowFactoryHandlers.ts). The missing piece is to use this dataset when processing token instance transfers so that pool escrow addresses are treated like the legacy globalEscrow (i.e. not as user accounts for balance purposes).

User story

As a consumer of the API
I want token instance balances and positions to reflect only user-owned addresses
So that I don’t see negative balances or escrow contracts in user-focused balance/position data.

Technical context

• Relevant handler: src/handlers/tokenInstanceHandlers.ts (see TODO at line 43: "Implement filtering based on poolEscrows for V3.1").
• Current behaviour: Only deployment.globalEscrow is used to decide if from/to is a “user account”. Other pool escrows are not excluded, so their movements are attributed as user balances and can produce negative balances.
• Data source for filtering: Use the existing Escrow table (populated by poolEscrowFactory:DeployPoolEscrow) to determine if an address is a pool escrow. Optionally keep using globalEscrow for backwards compatibility where applicable.

Acceptance criteria

• When processing tokenInstance:Transfer events, any address that is a pool escrow (present in the Escrow table for the relevant chain/context) is treated as non-user, same as globalEscrow.
• Balances and positions for user-owned addresses no longer show negative balances caused by transfers to/from pool escrows.
• The token instance handler uses the tracked Pool Escrow dataset (e.g. via EscrowService) to decide isFromUserAccount / isToUserAccount (or equivalent logic) instead of relying only on globalEscrow.
• Backwards compatibility with vault.globalEscrow() / deployment.globalEscrow is preserved where still required.

References

• Handler: src/handlers/tokenInstanceHandlers.ts (TODO at line 43).
• Pool escrow creation: src/handlers/poolEscrowFactoryHandlers.ts (DeployPoolEscrow → EscrowService.upsert).
• Escrow model and service: ponder.schema.ts (Escrow entity), src/services/EscrowService.ts.

Labels (suggested)

enhancement, v3.1, token-instance, pool-escrow