Fix issues 1183, 1234, 1222, 1236

[Miss-shelby]

Closes #1183 Closes #1234 Closes #1222 Closes #1236

Description

This pull request introduces a batch of critical reliability, architecture, and correctness improvements across the backend API, frontend clients, and smart contracts. These updates address multiple high-priority issues to ensure consistent mathematical operations, centralized validation, and predictable API behavior.

What's Included

1. Decimal-Aware Smart Contract Math (Closes #1183)

• Resolved a critical math bug in multitoken.rs where operations mixed token amounts across different precisions (e.g., XLM at 7 decimals vs. USDC at 6/18 decimals).
• All cross-token math operations and leaderboard score calculations have been updated to properly normalize units and respect decimals, ensuring minimums and scores are now evaluated accurately.

2. Idempotency Key Support for Mutating API Endpoints (Closes #1222)

• Added strict Idempotency-Key header support to all mutating endpoints (POST, PUT, PATCH, DELETE).
• Prevents race conditions and duplicate operations: The first request is processed and its response is cached via Redis. Any subsequent duplicate requests within the TTL automatically return the cached response, while attempts to reuse a key with a modified payload will immediately throw a 422 Unprocessable Entity.

3. Standardized Stellar Address Validation (Closes #1234)

• Implemented a centralized Zod validation schema utilizing the official Stellar SDK for all public keys.
• Addresses are now properly trimmed, checksum-validated, and normalized uniformly across the application before they are stored or compared, preventing edge-case parsing bugs.

4. Structured API Error Codes (Closes #1236)

• Refactored AppError.ts and the global errorHandler.ts to emit stable, machine-readable error codes alongside human-readable messages.
• Unexpected errors are now securely wrapped and logged internally, guaranteeing that system stack traces never leak to the client while providing a consistent error envelope for frontend integration.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Refactor (code maintenance and architectural improvements)

Testing & Verification

• Unit and integration tests cover the new decimal math logic in the smart contracts.
• E2E idempotency logic verified simulating network-retry loops.
• All mutating endpoints behave deterministically when provided with identical or spoofed idempotency keys.
• Zod refinement pipelines have been tested against valid and invalid Stellar network addresses.

---