Faucet: Implement test credit distribution system

[umwelt]

Context

Testnet users need test ZHTP tokens to interact with the system. Faucet distributes fixed amounts with rate limiting. This fulfills the Phase 1 deliverable: "Launch internal faucet / test credits for testers".

Scope

• API endpoint: POST /api/v1/faucet/request
• Rate limiting: 1 request per identity per 24 hours
• Fixed distribution: 100 ZHTP per request
• Faucet balance tracking and alerts
• CLI command: zhtp faucet request
• Statistics endpoint: GET /api/v1/faucet/stats

Dependencies

None - independent feature

Development Setup

Starting branch: feature/sid-integration (contains latest SID work)

Recommended workflow:

# Clone and checkout base branch
git checkout feature/sid-integration
git pull origin feature/sid-integration

# Create feature branch for this work
git checkout -b feature/faucet-system

# Work on implementation
# When done, push and create PR to merge back to feature/sid-integration
git push origin feature/faucet-system

Acceptance Criteria

• Faucet request endpoint validates identity
• Rate limiting enforced (24 hour cooldown)
• 100 ZHTP distributed per successful request
• Faucet balance decremented after distribution
• Alert when faucet balance < 10,000 ZHTP
• Stats endpoint shows: total distributed, requests today, remaining balance
• CLI command integrated
• Unit tests for rate limiting logic
• Integration tests for full flow
• API documentation

Technical Notes

• Store last request timestamp per identity
• Initialize faucet with 1,000,000 ZHTP
• Consider implementing CAPTCHA later for bot prevention
• Faucet should be a special system identity/wallet
• Existing wallet implementation: lib-identity/src/wallets/wallet_types.rs
• API handlers location: zhtp/zhtp/src/api/handlers/