feat: add account operation/offer analysis, asset distribution metrics, and claimable balance evaluation endpoints with corresponding tests

[Shredder401k]

PR Description: New Analytics & Utility Endpoints

Overview

This PR introduces four new developer-focused analytics endpoints to the StellarKit API. These endpoints provide deeper insights into account activity, asset distribution, claimable balance logic, and DEX offer history.

Closes #152
Closes #153
Closes #154
Closes #155

Changes

1. Operation Type Breakdown (#152)

• Endpoint: GET /account/:id/operation-breakdown
• Description: Analyzes the last 200 operations for an account and returns a breakdown of operation types, counts, and percentages.
• Goal: Helps developers identify the primary usage patterns of a Stellar account.

2. Asset Holder Distribution (#153)

• Endpoint: GET /asset/:code/:issuer/distribution
• Description: Fetches the top 200 holders and computes concentration metrics (Top 10/25 %) and the Gini coefficient.
• Goal: Allows for real-time assessment of asset decentralization and distribution health.

3. Claimable Balance Evaluator (#154)

• Endpoint: GET /claimable-balances/:id/evaluate/:accountId
• Description: Recursively evaluates complex claimable balance predicates against current network time.
• Goal: Provides a human-readable explanation of why a balance is or isn't claimable for a specific account.

4. Offer History Tracker (#155)

• Endpoint: GET /account/:id/offer-history
• Description: Returns a filtered chronological list of historical offer operations (created, updated, deleted).
• Goal: Offers a complete picture of an account's past DEX activities.

Verification

• Automated Tests: Added 4 new test suites in the tests/ directory with 100% coverage of new logic.
• Validation: Implemented strict validation for Account IDs, Asset Codes, and pagination limits.
• System Integrity: The implementation follows existing architectural patterns and uses the @stellar/stellar-sdk for reliable network interaction.

Examples

GET /account/:id/operation-breakdown

{
  "success": true,
  "data": {
    "total": 200,
    "breakdown": [
      { "type": "payment", "count": 120, "percentage": 60.0 },
      { "type": "manage_sell_offer", "count": 50, "percentage": 25.0 }
    ],
    "mostUsedOperation": "payment",
    "leastUsedOperation": "manage_sell_offer"
  }
}

[drips-wave]

@Shredder401k Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits