WalletCache keys only the public key while WalletRepository stores user_id and public_key: two identities, one cache namespace

[usmanimamu17-create]

Problem

WalletCache._key (app/services/wallet_cache.py):

def _key(self, address: str) -> str:
    return f"wallet:{address}"

WalletRepository (app/repositories/wallet_repository.py) provides both get_by_user_id and get_by_public_key, and the wallet model has two stable identities (user_id unique, public_key unique). The cache only indexes by address, so:

• A user-id lookup can never hit the cache (the gap tracked separately), and
• The address-keyed entry is written from user-id reads (_fetch_wallet does cache.set(wallet.public_key, ...)), meaning the cache stores the same wallet object under the address key even though that entry is only consulted by address lookups.

Consequences:

• Cache entries and DB identity can diverge: if a wallet is re-linked (same user, new address — link_wallet allows this), the old address key retains the stale wallet indefinitely until TTL, while the DB has the new mapping; an address-based read (get_balance) can return the pre-relink wallet.
• The namespace conflates two lookup directions: there is no way to invalidate "all keys for user X" (no invalidate_prefix usage from WalletRegistry), so relink/update paths cannot clear the affected entries.
• TTLCache.invalidate_prefix exists in app/utils/cache.py as the house pattern for this, but WalletCache has no prefix-invalidation at all.

Root cause

The cache was designed around the address lookup only, and the write/read paths never reconciled the two-key identity model.

Why this is architecturally hard

1. The durable fix is either two namespaces (wallet:{address}, wallet:user:{user_id}) with invalidation on every write path in WalletRepository/WalletRegistry, or a single canonical key with lookup-by-index — a data-model decision with cache-coherence implications.
2. Relink semantics (link_wallet changing the address for a user) require invalidating both the old and new address keys plus the user key atomically; Redis multi/pipe is the mechanism, and the ordering with the DB commit matters.
3. Tests must cover the relink scenario (old address stale, new address fresh, user lookup fresh) — none exist today.

Proposed design

Add a user-id key namespace, invalidate both namespaces on every create/link/update, implement WalletCache.invalidate_prefix mirroring TTLCache, and add relink tests asserting no stale reads.

Acceptance criteria

Service

• User-id and address lookups are cache-coherent after relink/update.
• All wallet writes invalidate the affected cache keys.

Tests

• A relink test asserts old-address staleness is bounded and new lookups are fresh.
• Existing wallet tests pass.

Out of scope

The user-id cache gap (tracked separately) and simulated balances (tracked separately).

Getting started

pytest tests/test_wallet_persistence.py -q
make typecheck

Good first files to read: app/services/wallet_cache.py, app/services/wallet_registry.py, app/repositories/wallet_repository.py.

[Grants268]

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

I would like to work on this issue

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

[Andy8370]

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

Hello, this issue caught my interest, and after reviewing the requirements, I believe I can make the necessary changes. Please consider assigning it to me.

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

[Escelit]

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

Please assign me I can deliver an excellent work

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

[ajiterusam]

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

Hello Maintainer, I’ve gone through the issue description and I’m confident I can handle it effectively. I’d appreciate it if you could assign the issue to me.

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

[frankrichard99]

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

I would like to work on this issue

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

[Femaleotaku]

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

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

This touches Python and Redis, which I have hands-on experience with. I'll implement this following the existing conventions in the codebase, with tests covering the new behavior.

Looking forward to contributing — please assign this issue to me.

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

[drips-wave]

Congratulations, @Femaleotaku! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Femaleotaku: 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 🌊