Implement Incremental Graph Update Mechanism for Real-Time Node and Edge Additions to Wallet Graph

[Inkman007]

Description

The wallet graph in detection/wallet_graph.py is currently rebuilt from scratch on each scoring cycle. For large graphs (10,000+ wallets), a full rebuild takes several seconds and creates a gap in real-time detection. An incremental update mechanism would add new wallet nodes and trade edges to the existing graph without a full rebuild, enabling continuous real-time graph maintenance.

What needs to be built

• Add add_trade_edge(src_wallet, dst_wallet, trade) and remove_stale_edges(max_age_hours) methods to the graph builder in detection/wallet_graph.py.
• Implement an in-memory graph cache (detection/feature_cache.py already exists — extend it) that holds the current graph state and is updated incrementally.
• For GNN inference, implement a 2-hop subgraph extraction (get_ego_subgraph(wallet_id, hops=2)) that returns only the neighbourhood needed for a single wallet's embedding, avoiding full-graph reprocessing.
• Expose graph size metrics (nodes, edges, stale edge count) as Prometheus gauges.

Requirements

Functional

• Edge additions must be O(1) amortised per edge.
• Stale edge removal must run as a background scheduled task (GRAPH_STALE_EDGE_MAX_AGE_HOURS, default 168).
• Ego subgraph extraction must complete in < 10ms for wallets with up to 500 direct neighbours.

Testing

• Unit test: add 1000 edges incrementally; confirm graph is identical to one built from scratch with the same edges.
• Test: remove stale edges older than 1 hour; confirm the correct edges are removed.
• Performance test: ego subgraph extraction for a high-degree wallet (500 neighbours) completes in < 10ms.

Security

• Wallet IDs used as graph node keys must be normalised to lowercase Stellar address format to prevent duplicate nodes from capitalisation variants.

Documentation

• Add a section to docs/gnn_architecture.md explaining the incremental update strategy and the staleness policy.

Contributor guidance

Area of specialty: Graph data structures, Python (NetworkX or PyTorch Geometric), real-time systems.

How to contribute:

1. Comment describing your experience with incremental graph maintenance or dynamic graph algorithms.
2. Propose how to handle a trade that links two previously disconnected graph components.
3. PR must include the equivalence test (incremental == batch-built) and the ego subgraph performance test.

[ekwe7]

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

[teeschima]

@teeschima has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Good day boss, please assign this task to me. E.T.A 2HRS

ℹ️ Repo Maintainers: To accept this application, review their application or assign @teeschima to this issue.

[brite-side0]

@brite-side0 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

hello dear maintainer i would love to work on this task along side you sir so as to bring your project to production level.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @brite-side0 to this issue.

[Caneryy]

@Caneryy has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, I'd like to work on this issue please.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Caneryy to this issue.

[drips-wave]

Congratulations, @brite-side0! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @brite-side0: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🦊 GrantFox — @brite-side0 has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #203)
2. Your PR will be reviewed by the Ledger-Lenz maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@brite-side0's PR #360 was approved and merged by @Inkman007.

🏆 @brite-side0: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (503 total points). Track your full progress on GrantFox.

👏 Great work, @brite-side0! Keep contributing to Ledger-Lenz.