feat: add per-principal fungible token transfer history endpoint

[rafa-stacks]

Adds a per-principal, per-token FT transfer history endpoint.

GET /extended/v3/principals/{principal}/transfers/ft/{asset_identifier}

{
  "total": 4,
  "limit": 20,
  "cursor": { "next": null, "previous": null, "current": "2:0:0:1" },
  "results": [
    {
      "sender": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "recipient": null,
      "amount": "1000",
      "transaction": { "tx_id": "0x…c2", "event_index": 1 },
      "block": { "height": 2, "hash": "0x…a2", "index_hash": "0x…b2", "time": 94869287, "tx_index": 0 }
    },
    {
      "sender": "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173",
      "recipient": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "amount": "12000000",
      "transaction": { "tx_id": "0x…c2", "event_index": 0 },
      "block": { "height": 2, "hash": "0x…a2", "index_hash": "0x…b2", "time": 94869287, "tx_index": 0 }
    },
    {
      "sender": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "recipient": "SP1JTCR202ECC6333N7ZXD7MK7E3ZTEEE1MJ73C60.pool-v1",
      "amount": "75250000",
      "transaction": { "tx_id": "0x…c1", "event_index": 1 },
      "block": { "height": 1, "hash": "0x…a1", "index_hash": "0x…b1", "time": 94869287, "tx_index": 0 }
    },
    {
      "sender": null,
      "recipient": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
      "amount": "250000000",
      "transaction": { "tx_id": "0x…c1", "event_index": 0 },
      "block": { "height": 1, "hash": "0x…a1", "index_hash": "0x…b1", "time": 94869287, "tx_index": 0 }
    }
  ]
}

[codecov]

Codecov Report

❌ Patch coverage is 98.60627% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/datastore/v3/pg-store-v3.ts	98.60%	2 Missing ⚠️
...1779800000012_ft-events-principal-asset-indexes.ts	97.43%	0 Missing and 1 partial ⚠️
src/api/routes/v3/principals.ts	98.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds per-principal, per-token fungible-token transfer history with cursor pagination.

Changes:

• Adds the v3 endpoint, schema, serializer, and datastore query.
• Adds optimized FT event indexes.
• Adds integration coverage for filtering, pagination, self-transfers, and reorgs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/api/v3/principal-ft-transfers.test.ts	Tests the new endpoint.
src/datastore/v3/types.ts	Defines the transfer database model.
src/datastore/v3/pg-store-v3.ts	Implements transfer retrieval and pagination.
src/api/serializers/v3/ft-transfers.ts	Serializes transfer records.
src/api/schemas/v3/entities/principal-ft-transfers.ts	Defines the response schema.
src/api/routes/v3/principals.ts	Registers the endpoint.
migrations/1779800000012_ft-events-principal-asset-indexes.ts	Adds query-supporting indexes.
migrations/1779800000011_ft-balances-token-balance-address-index.ts	Reformats migration documentation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.