Decimal normalization for production-scale deposits

[hoddukzoa12]

Summary

Q64.64 checked_mul overflow로 인해 현재 asset당 최대 ~740 토큰만 예치 가능.
Instruction handler 경계에서 decimal 정규화를 적용해 ~17.5억 토큰/asset 까지 확장.

Problem

• initialize_pool에서 w_norm_squared() → r² = radius.checked_mul(radius) 호출
• deposit D에 대해 r ≈ D × 2.366 (n=3), r² 가 Q64.64 i128 범위 초과
• 현재 workaround: deposit을 100 토큰으로 축소 (devnet bootstrap)

Solution: Decimal Normalization

온체인 instruction handler 진입/퇴출 경계에서 변환:

진입 (raw → normalized)

// instruction handler 시작부
let normalized = raw_amount / 10u64.pow(decimals as u32);
// FixedPoint 연산은 "1 token = 1.0" 단위로 수행

퇴출 (normalized → raw)

// instruction handler 종료부  
let raw_output = normalized_result * 10u64.pow(decimals as u32);

영향 받는 instruction handlers (4곳)

1. initialize_pool — initial_deposit_per_asset 정규화
2. add_liquidity — deposit amount 정규화
3. swap — input amount 정규화, output amount 역정규화
4. remove_liquidity — withdrawal amount 역정규화

내부 수학 변경 없음

• fixed_point.rs, sphere.rs, torus.rs 등 수학 모듈은 그대로 유지
• 기존 155 unit + 25 integration 테스트 영향 최소

Capacity After Fix

Decimals	Max tokens/asset	TVL 환산 (USD)
6 (USDC)	~1.75B	~$1.75B
9	~1.75M	N/A

Acceptance Criteria

• 4개 instruction handler에 decimal normalization 적용
• 1M 토큰 deposit으로 initialize_pool 성공
• 기존 cargo test 전체 통과
• 새 통합 테스트: large deposit → swap → withdraw round-trip

Context

• Devnet은 100 토큰/asset으로 부트스트랩 완료 (Deploy orbital program to devnet + bootstrap script #15)
• 프론트엔드 Swap UI (Swap UI page #18) 전에 처리 권장
• 미래 i256 마이그레이션으로 완전 해결 예정 (Post-Hackathon)

🤖 Generated with Claude Code

[hoddukzoa12]

Implemented in commit 3571194 on feat/devnet-deploy.

Changes (11 files, +251 −22):

• from_token_amount(raw, decimals) / to_token_amount(decimals) added to FixedPoint with round-half-up correction
• token_decimals: [u8; MAX_ASSETS] added to PoolState (carved from _reserved, net SIZE unchanged)
• Mint decimals read & uniform validation in initialize_pool
• All 6 instruction handlers + remove_liquidity normalized
• DecimalsMismatch error + 13 unit tests

Verification: 193 tests passed, anchor build success.

⚠️ Breaking: PoolState layout changed → devnet pool reinitialization required. update_policy IDL changed (pool account added).

Next: devnet redeploy + bootstrap with production-scale amounts (e.g., 1M tokens/asset).

[hoddukzoa12]

PR #56 uses from_token_amount/to_token_amount_floor with per-asset decimals (6 for USDC/USDT/PYUSD). Production-scale normalization for mixed-decimal pools deferred.