add cash incentives query

[bertinkfnd]

This pull request adds support for retrieving and handling cash incentives (platform volume and unlocked rewards) for a given wallet address in the indexer client. The main changes include implementing the getCashIncentives method, defining new types for the cash incentives data structures, and updating the server and client type definitions to support the new query.

Cash Incentives Feature Implementation:

• Added a new method getCashIncentives to IndexerBaseClient, which fetches and processes platform volume and unlocked rewards data for a wallet address.
• Introduced new client-side types in clientTypes.ts for cash incentives parameters, event metadata, platform/wallet data, and the response structure.

Server and Query Type Updates:

• Defined corresponding server-side types in serverTypes.ts for cash incentives queries, including request parameters, event structures, and response objects. [1] [2]
• Updated the server query type maps to include the new cash_incentives query. [1] [2]

Testing:

• Added a new test case to subaccountQueries.test.ts to verify that getCashIncentives returns the expected platform volume and rewards data per event and wallet summary.

contributes to ENGW-202

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[frankinkfnd]

@claude review once

[bertinkfnd]

@frankinkfnd syncing this up locally to make sure we have everything.

[claude]

LGTM — straightforward addition of a new read-only indexer query following the established pattern (getXPoints/getPoints).

Extended reasoning...

Overview

This PR adds a new getCashIncentives query method to IndexerBaseClient plus the corresponding client and server types, and a small E2E test. Total surface: one new method that forwards a wallet address to the indexer and maps the x18 string response into BigNumber fields, mirroring the shape used by adjacent methods like getXPoints and getPoints.

Security risks

None. The endpoint is read-only, takes a single Address param, and does no signing, no state mutation, and no privileged operation. Standard removeDecimals/toBigNumber conversions match neighboring queries.

Level of scrutiny

Low. This is a mechanical, self-contained SDK extension: new type declarations plus a query method that follows the existing translation pattern one-to-one. The E2E test asserts the full response shape.

Other factors

The bug hunting pass surfaced one nit: the JSDoc mentions an eventId param that doesn't exist on either the client or server params type. It's a doc-only defect with no runtime impact and has already been posted as an inline comment for the author to drop or wire up as they see fit — not a blocker for approval.

[claude]

🟡 The JSDoc for getCashIncentives says "If no eventId is provided, the latest event is returned," but no eventId field exists on GetIndexerCashIncentivesParams (only address) and IndexerServerCashIncentivesParams only accepts wallet_address. This appears to be stale copy from an earlier design — either drop the sentence or actually wire up eventId support if it was intended.

Extended reasoning...

What the bug is

The JSDoc block added at packages/indexer-client/src/IndexerBaseClient.ts:982-986 documents a parameter that does not exist:

/**
 * Retrieves cash incentives information (platform volume and unlocked rewards) for a given wallet address.
 * If no `eventId` is provided, the latest event is returned.
 * @param params
 */
async getCashIncentives(
  params: GetIndexerCashIncentivesParams,
): Promise<GetIndexerCashIncentivesResponse> {

Why the docstring is wrong

Tracing the type stack:

1. Client param type — GetIndexerCashIncentivesParams (clientTypes.ts:900-902) is defined as:

   export interface GetIndexerCashIncentivesParams {
     address: Address;
   }

   No eventId field.
2. Server param type — IndexerServerCashIncentivesParams (serverTypes.ts:249-251):

   export interface IndexerServerCashIncentivesParams {
     wallet_address: string;
   }

   No event_id field.
3. Implementation — the method only forwards wallet_address:

   const baseResponse = await this.query('cash_incentives', {
     wallet_address: params.address,
   });

   Nothing accepts or propagates an event ID.

Step-by-step proof

• A user reads the JSDoc and concludes: "I can call client.getCashIncentives({ address, eventId: 42 }) to filter to a single event, or omit eventId for the latest."
• They attempt client.getCashIncentives({ address, eventId: 42 }). TypeScript rejects this at compile time — eventId is not a property of GetIndexerCashIncentivesParams (Object literal may only specify known properties).
• Even if they cast around the type error, the method's body never reads params.eventId — only params.address is forwarded to the server. The server params type has no event_id field either, so the request would never carry the filter.
• The response always contains the full events array (see IndexerCashIncentivesEvent[]), never a single "latest" event — so the docstring's behavioral claim is doubly wrong.

Impact

Purely a documentation defect. It misleads SDK consumers about supported filtering, but no runtime path is affected and TypeScript will reject any attempt to use the phantom parameter. Behavior for the actual code path — { address } → full events list — is correct.

How to fix

Two options — pick whichever matches intent:

1. Drop the stale sentence (most likely correct — the method really does return all events):

   /**
    * Retrieves cash incentives information (platform volume and unlocked rewards) for a given wallet address.
    * @param params
    */

2. Wire up eventId support if the server actually accepts it: add eventId?: number to GetIndexerCashIncentivesParams, event_id?: number to IndexerServerCashIncentivesParams, and forward it in the query.

[frankinkfnd]

Lmk when you think it's good to publish, also take a look at e2e

[bertinkfnd]

Lmk when you think it's good to publish, also take a look at e2e

e2e looks like an issue with the linked signer account health.

[bertinkfnd]

@frankinkfnd We should be good to go here

[frankinkfnd]

0.25.0