feat: build username resolver API endpoint

[ryzen-xp]

📝 Description

Implement the most important user-facing API endpoint: resolving a username hash to its linked addresses. This endpoint powers the core use case of sending crypto to @username. It checks the database cache first and falls back to a live contract call.

✅ Requirements

• Create ResolverModule, ResolverController, ResolverService
• Implement GET /resolve/:usernameHash endpoint
• Service checks Username entity cache first; on miss calls resolve_stellar on core contract
• Response includes stellarAddress, chainAddresses (EVM, Bitcoin, Solana, Cosmos if set), owner, registeredAt
• Implement GET /resolve/:usernameHash/stellar for Stellar-only fast resolution
• Add NotFoundException with clear message when username hash not found on-chain
• Add UsernameHashDto with @IsString() and length validation using class-validator
• Write unit tests for service cache-hit and cache-miss paths

🎯 Acceptance Criteria

• GET /resolve/:usernameHash returns correct address data
• Cache-hit path does not call the contract
• Cache-miss path calls contract and saves result to database
• 404 returned for unknown username hash
• Input validated with class-validator
• Unit tests cover both cache paths and not-found case

📁 Expected files to change/structure

• backend/src/resolver/resolver.module.ts
• backend/src/resolver/resolver.controller.ts
• backend/src/resolver/resolver.service.ts
• backend/src/resolver/dto/resolve-username.dto.ts
• backend/src/resolver/resolver.service.spec.ts

---

Commit: feat: build username resolver API endpoint
Branch: feat/backend-resolver-api | Priority: HIGH | Difficulty: one-coffee

[AbuTuraab]

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

Hi,

I’d like to request assignment to this issue.

As a full-stack developer working actively in the Stellar ecosystem, I understand how important robust automation is for projects that combine Soroban smart contracts, backend services, and frontend applications. A reliable CI/CD pipeline is the backbone of safe contract development, deterministic builds, and predictable testnet releases.

During the previous waves of contributions, I worked on several Stellar-related repos where I resolved issues such as:
Frontend implementations.
Misconfigured GitHub Actions leading to failing builds
Missing or incomplete Soroban contract test pipelines
Frontend pipelines that didn’t catch build/lint errors
Inefficient caching (Rust, pnpm) that slowed down CI
Incorrect workflow permissions affecting deployment and artifact uploads
These issues helped me develop a strong sense of what healthy CI/CD should look like for blockchain projects.

Relevant Skills
Full-stack expertise with Soroban, Rust, TypeScript, and modern frontend tooling
Strong experience designing and maintaining GitHub Actions workflows
Familiar with contract testing, reproducible builds, and blockchain dev best practices
Experience with pnpm-based frontend CI pipelines (install, lint, type-check, build)
Comfortable implementing secure deployment flows, secret management, and workflow permission hardening
Confident in making pipelines faster and more reliable using smart caching strategies

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

[drips-wave]

Congratulations, @AbuTuraab! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on April 29, 2026.

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