Add connected-wallet earnings and game-performance stats page

Start by inspecting ui/src/pages, ui/src/hooks, ui/src/utils/convertUtils.ts, the existing wallet connection hooks, and table/list components. First verify whether an existing reporting or indexer endpoint supplies the required historical data; done means a connected-wallet-only /earnings page with accurate summaries, history, analytics, filters, loading and error states, and component/query tests without changing poker or fee logic.

Summary

Create a user-facing earnings and analytics page showing rake and Sit & Go entry-fee income generated by games created by the connected wallet.

This ticket is for displaying existing game and earnings data. It must not change any poker, rake, fee, payout, settlement, refund, or game-state logic.

Core ownership rule

Only include earnings from tables or Sit & Go games created by the connected wallet.

The creator is identified by the game’s existing root:

Game.creator

The page must not:

• Allow the user to enter another wallet address
• Provide wallet-address search
• Accept another address through a route or query parameter
• Show games created by another wallet
• Provide any earnings-recipient or payout controls
• Change where rake or fees are paid

The wallet shown on the page is always the currently connected wallet.

Related Sit & Go fee ticket

Sit & Go entry fees are implemented and tracked separately in:

• [block52/poker-vm#2118](https://github.com/block52/poker-vm/issues/2118)

Issue #2118 defines the SNG fee behavior, including:

• entry_fee in the chain/protobuf model
• entryFee in the generated TypeScript SDK
• Flat entry fee per successful player join
• Entry fee taken from the player’s buy-in
• Net buy-in passed to the prize pool and PVM
• Fee paid to the table creator
• sng_entry_fee_collected event
• USDC base-unit storage
• Two-decimal-place USDC display
• Existing-SNG backward compatibility

This stats page should display the resulting data from #2118.

This ticket must not duplicate or modify the implementation in #2118.

Page route

Add:

/earnings

Add an “Earnings” or “My Earnings” navigation item when a wallet is connected.

If no wallet is connected, show a connect-wallet prompt instead of earnings data.

Terminology

Use the following language:

• Game creator: the wallet in Game.creator
• Cash-game rake: rake collected from cash-game hands
• SNG entry fee: the flat fee defined by #2118
• Gross SNG fees: all entry fees collected from successful joins
• Refunded fees: entry fees returned through an authoritative refund record, if available
• Net SNG fees: collected fees minus confirmed refunds
• Game/Table ID: gameId in TypeScript and game_id in APIs/events

Do not call gameId a “table address” unless it is confirmed to be an actual on-chain address.

Wallet behavior

Use the existing connected-wallet address.

The page must:

• Display the shortened connected address
• Provide a copy-address action
• Load games where creator equals the connected wallet
• Clear old results immediately when the wallet changes
• Refetch using the newly connected wallet
• Clear displayed results when the wallet disconnects
• Prevent an in-flight request for the previous wallet from replacing the new wallet’s results

This restriction applies to the page experience. It is not a claim that public blockchain data is private.

Data sources

Use existing chain, SDK, API, and indexer data where available.

Creator games

Use the root game creator to determine whether a game belongs on the page.

Relevant existing fields include:

• gameId
• creator
• format
• variant
• gameOptions
• currentPlayers
• createdAt
• updatedAt

Relevant reference:

• poker-vm/sdk/src/types/game.ts

Cash-game rake

The game state exposes rakeCollected, but this is associated with the current hand and resets when a new hand begins.

Do not treat the currently observed rakeCollected value as lifetime earnings.

Historical rake totals must come from existing persisted/indexed rake settlement data. If such data is not currently exposed to the UI, create a separate linked reporting/indexer ticket rather than changing game logic in this ticket.

Sit & Go fees

Use the data produced by #2118.

The authoritative event is:

sng_entry_fee_collected

With:

• game_id
• player
• amount
• recipient

For the creator’s earnings page:

• Associate the event with its game.
• Confirm that the game’s creator matches the connected wallet.
• Use the event amount as the collected fee.
• Do not calculate actual fees as entryFee × maxPlayers.
• Do not count a configured fee until a successful fee event exists.
• Do not count failed joins.
• If authoritative refund records exist, subtract them from net earnings.
• Do not guess that a fee was refunded based only on game status.

Timestamps

Use authoritative block or indexer timestamps for:

• Game opened
• Fee collected
• Rake collected
• Game completed
• Game deleted
• Game force-closed

If a historical timestamp is unavailable, display “Unavailable.” Do not substitute the current time.

Game status

Use authoritative status returned by the data source.

Possible displayed statuses include:

• Waiting
• Registration
• In progress
• Finished
• Deleted
• Force closed

Do not hardcode every game as waiting.

Do not invent a cancelled status unless the data source reports an actual cancellation state or event.

Required reporting interface

The page needs a reporting response containing the connected creator’s games and earnings.

Use an existing indexer endpoint if one already provides this information.

If a new reporting endpoint is required, track it separately from this UI ticket. A suitable response would include:

• Connected creator address
• Summary totals
• Creator game history
• Cash-rake records
• SNG fee records
• Fee-refund records where available
• Pagination
• Indexer synchronization height
• Last-updated timestamp

The UI must not reconstruct financial history by periodically observing live game state.

Page layout

Header

Show:

• “My Earnings”
• Connected wallet
• Last updated time
• Refresh action

Do not show an address-search control.

Summary cards

Show:

• Total earnings
• Cash-game rake
• SNG entry fees
• Cash games that generated rake
• SNGs that generated fees
• Raked hands
• Fee-paying SNG entries

Where refund data is available:

Total earnings = settled cash rake + collected SNG fees - refunded SNG fees

Do not count the following as earnings:

• Cash-game pot volume
• Player buy-ins
• SNG prize pools
• Net buy-ins sent to the prize pool
• Player winnings
• Configured but uncollected fees
• Maximum possible fees
• Failed SNG joins
• Rake that was not settled

Earnings-over-time chart

Show creator earnings over time.

Allow grouping by:

• Day
• Week
• Month

Allow series for:

• Total earnings
• Cash-game rake
• SNG fees

The chart must use settlement timestamps rather than game-creation timestamps.

Creator game history

Show every available game created by the connected wallet, including games that earned zero rake or fees.

Recommended columns:

• Game/Table ID
• Format
• Status
• Opened
• Closed or completed
• Blinds or SNG buy-in
• Hands or fee-paying entrants
• Rake earned
• SNG fees earned
• Total earnings

Provide a copy action for the full Game/Table ID.

Cash-game detail

For each available rake record, show:

• Hand number
• Blind level
• Pot amount where available
• Rake earned
• Settlement timestamp
• Transaction hash where available

Sit & Go detail

For each sng_entry_fee_collected record, show:

• Game/Table ID
• Joining player
• SNG buy-in
• Entry fee
• Collection timestamp
• Transaction hash where available
• Refunded status where authoritative refund data exists

Blind-level performance

Group cash-game performance by small blind/big blind combination.

Show:

• Blind level
• Games created
• Raked hands
• Total rake
• Average rake per raked hand

Include the number of games and hands so users can judge the sample size.

SNG buy-in performance

Group SNG performance by buy-in amount.

Show:

• Buy-in
• Entry fee
• Unique SNGs
• Fee-paying entries
• Gross fees collected
• Refunded fees where available
• Net fees earned
• Average fees per SNG

Use successful fee records rather than maximum player capacity.

Filters

Provide filters for:

• Date range
• Cash games
• Sit & Go games
• Game status
• Blind level
• SNG buy-in

Do not provide a creator-wallet filter.

Currency handling

Source financial values should remain integer strings in USDC base units.

The UI should:

• Convert values for display only
• Show the USDC label
• Follow the existing buy-in display convention
• Display the SNG entry fee with two decimal places, as confirmed in #2118
• Avoid JavaScript floating-point arithmetic for totals
• Use the project’s existing amount-formatting utilities where possible

Page states

Provide clear states for:

• Wallet disconnected
• Loading
• No games created
• Games created but no earnings
• No results for the selected filters
• Partial historical data
• Indexer synchronizing
• Data unavailable
• Request failed, with retry
• Wallet changed during loading

The partial-data message should explain that some older game or settlement information may not have been indexed.

UI implementation areas

Expected UI work includes:

• New /earnings page
• Navigation entry
• Earnings API client
• TypeScript response types
• Connected-wallet query hook
• Summary cards
• Earnings-over-time chart
• Creator game table
• Game detail view
• Blind-level aggregation view
• SNG buy-in aggregation view
• Filters
• Loading and empty states
• Mobile layout
• Component and query tests

Likely UI references:

• ui/src/pages
• ui/src/hooks
• ui/src/utils/convertUtils.ts
• Existing wallet connection hooks
• Existing USDC formatting utilities
• Existing table/list components

The poker-vm repository is a reference for DTO and event terminology only. No PVM or game-engine changes are part of this ticket.

Acceptance criteria

Scope

• This ticket only implements the stats/earnings page and its data integration.
• No rake, fee, payout, refund, PVM, or game-state rules are changed.
• SNG fee mechanics remain owned by #2118.
• Missing reporting/indexer capabilities are tracked in separate linked issues.

Wallet restriction

• The page uses the connected wallet automatically.
• Only games whose root creator matches the connected wallet are displayed.
• There is no wallet-address search field.
• Another address cannot be supplied through the URL.
• Switching wallets immediately clears the previous results.
• Disconnecting clears displayed earnings.
• Stale requests cannot display the previous wallet’s data.

Earnings accuracy

• Cash rake comes from authoritative historical settlement data.
• Current-hand rakeCollected is not treated as lifetime earnings.
• SNG fees come from sng_entry_fee_collected.
• One successful fee event is treated as one collected entry fee.
• Configured or projected fees are not counted as earnings.
• Failed joins are not counted.
• Confirmed refunds are deducted when refund records are available.
• Summary totals equal the displayed underlying records.
• Currency totals avoid floating-point errors.

Game history

• Games created by the connected wallet are displayed.
• Zero-earning games are included when historical data is available.
• Game/Table ID uses gameId/game_id.
• Status comes from authoritative data.
• Missing values display as unavailable rather than invented values.
• Closed and completed games remain visible when supplied by the reporting source.

Analytics

• Earnings can be viewed over time.
• Cash-game earnings can be compared by blind level.
• SNG earnings can be compared by buy-in.
• Every performance comparison includes a sample size.
• Date and game-format filters update totals and details consistently.
• Pagination and sorting produce stable results.

UX

• Loading, empty, partial-data, and error states are implemented.
• The page works on mobile.
• Tables and controls are keyboard accessible.
• Dates are locale-aware.
• Currency labels are explicit.
• Game IDs and transaction hashes can be copied or opened where supported.

Edge cases

Test:

• Connected wallet has created no games
• Games exist but earned no rake or fees
• SNG has a zero entry fee
• SNG has configured fees but no successful joins
• Multiple fee-paying joins in one SNG
• Failed join
• Refunded fee where refund data is available
• Cash game with rake disabled
• Cash game with no raked hands
• Deleted empty game
• Force-closed cash game
• Missing historical timestamp
• Missing pot or hand details
• Partial indexer history
• Duplicate indexed event
• Indexer lag
• Wallet switch during an active request
• Wallet disconnection while results are visible
• Financial totals exceeding JavaScript safe integer precision

Out of scope

• Changing game logic
• Changing rake calculation
• Changing SNG fee calculation
• Changing prize-pool or payout logic
• Changing refund behavior
• Changing game lifecycle rules
• Changing PVM behavior
• Changing the fee or rake recipient
• Adding an alternative recipient wallet
• Searching another wallet
• Player profit/loss or bankroll analytics
• Tax reporting
• Fiat conversion
• Earnings per hour without reliable active-duration data