feat: track exact block of staking rewards

[Copilot]

Summary

This PR implements tracking of exact block heights for staking rewards, so users can see the actual reward amount without having to calculate differences between staking snapshots.

Features

1. Exact Block Staking Rewards

• Added STAKING_REWARD counterparty constant for staking rewards
• Implemented binary search to find the exact block where staking balance changed
• Gap detection between staking snapshots automatically fills with precise reward records

2. Balance Change API Improvements

• Added exclude_snapshots query parameter to filter out SNAPSHOT and STAKING_SNAPSHOT records
• Useful for getting only actual balance changes (transactions and rewards)

3. Bug Fixes

• Fixed NEAR token tracking: NEAR was only being added to the tokens list when it was empty. Now NEAR is always included regardless of other discovered tokens (like intents tokens)
• Fixed SNAPSHOT for unchanged balances: When seeding initial balance, if the balance hasnt changed within the lookback window, a SNAPSHOT record is created at the lookback boundary instead of failing to find a receipt

API Changes

/api/balance-changes

New query parameter:

• exclude_snapshots (boolean, optional) - When true, excludes SNAPSHOT and STAKING_SNAPSHOT records

Example:

curl "http://localhost:3000/api/balance-changes?account_id=your-account.near&exclude_snapshots=true"

Staking Reward Record Example

{
  "id": 3167,
  "block_height": 182449384,
  "block_time": "2026-01-24T00:19:08.761126Z",
  "token_id": "staking:astro-stakers.poolv1.near",
  "counterparty": "STAKING_REWARD",
  "amount": "0.040456086036518156197191",
  "balance_before": "1029.479523405233304042477556",
  "balance_after": "1029.519979491269822198674747"
}

Record Types

Token Type	Counterparty	Description
near	account address	NEAR token transfer with counterparty
near	SNAPSHOT	Initial balance snapshot (no transaction)
ft-contract.near	account address	Fungible token transfer
intents.near:nep141:*	account address	Intents token transfer
staking:pool.near	STAKING_SNAPSHOT	Epoch boundary snapshot
staking:pool.near	STAKING_REWARD	Exact block of staking reward

Implementation Details

1. track_and_fill_staking_rewards() - Main entry point that creates epoch snapshots and fills gaps
2. find_staking_gaps() - Detects gaps between staking snapshots with different balances
3. fill_staking_gap() - Binary search to find exact block of balance change
4. insert_staking_reward() - Creates STAKING_REWARD record at exact block

Tests

• test_find_staking_gaps - Gap detection between staking snapshots
• test_insert_staking_reward - Staking reward record insertion
• test_track_and_fill_staking_rewards - End-to-end staking reward tracking
• test_near_snapshot_with_existing_intents_tokens - Validates NEAR tracking fix

Files Changed

• src/handlers/balance_changes/account_monitor.rs - Always include NEAR in tokens list
• src/handlers/balance_changes/gap_filler.rs - SNAPSHOT for unchanged balances in lookback window
• src/handlers/balance_changes/staking_rewards.rs - New gap filling and reward tracking
• src/routes/balance_changes.rs - Added exclude_snapshots filter
• tests/balance_collection_integration_test.rs - Test for NEAR + intents fix
• tests/staking_rewards_test.rs - Tests for staking gap filling

---

• Fixes [Task] Track exact block of staking rewards #105

[petersalomonsen]

@race-of-sloths include

[race-of-sloths]

@copilot Thank you for your contribution! Your pull request is now a part of the Race of Sloths!
Weekly streak is on the road, smart strategy! Secure your streak with another PR!

Current status: waiting for merge

Reviewer	Score
@petersalomonsen	5

Your contribution is much appreciated with a final score of 5!
You have received 50 Sloth points for this contribution

@petersalomonsen received 25 Sloth Points for reviewing and scoring this pull request.

What is the Race of Sloths

Race of Sloths is a friendly competition where you can participate in challenges and compete with other open-source contributors within your normal workflow

For contributors:

• Tag @race-of-sloths inside your pull requests
• Wait for the maintainer to review and score your pull request
• Check out your position in the Leaderboard
• Keep weekly and monthly streaks to reach higher positions
• Boast your contributions with a dynamic picture of your Profile

For maintainers:

• Score pull requests that participate in the Race of Sloths and receive a reward
• Engage contributors with fair scoring and fast responses so they keep their streaks
• Promote the Race to the point where the Race starts promoting you
• Grow the community of your contributors

Feel free to check our website for additional details!

Bot commands

• For contributors
  • Include a PR: @race-of-sloths include to enter the Race with your PR
• For maintainers:
  • Invite contributor @race-of-sloths invite to invite the contributor to participate in a race or include it, if it's already a runner.
  • Assign points: @race-of-sloths score [1/2/3/5/8/13] to award points based on your assessment.
  • Reject this PR: @race-of-sloths exclude to send this PR back to the drawing board.
  • Exclude repo: @race-of-sloths pause to stop bot activity in this repo until @race-of-sloths unpause command is called

[petersalomonsen]

@race-of-sloths score 5