feat: implement foundation for emission splits in claim API

[spiceoogway]

Code Contribution

What Code Did You Write?

Implemented emission splits enforcement in the claim API, allowing configured splits to be automatically distributed when tokens are claimed.

⚠️ MAJOR UPDATE (Latest Commit): Comprehensive refactoring to extract claims and presale routes into separate modules for improved maintainability. See Refactoring Section below.

---

Key Changes

1. Original Implementation: Emission Splits in Claims

Updated createMintTransaction endpoint

• Query getEmissionSplits() to check for configured splits
• If splits exist: distribute the 90% claimers portion proportionally
• If no splits: fall back to 100% to creator (backwards compatible)
• Create token accounts for each split recipient
• Generate mint instructions for proportional distribution
• Store split metadata for validation in confirm step

Updated confirmClaim endpoint

• Replace creator-only check with hasClaimRights()
• Allow ANY wallet with emission split OR creator to initiate claims
• Claims distribute to ALL recipients according to configured splits
• Maintains security: validates user has claim rights before processing

Updated Response Types (types/server.ts)

• MintClaimResponseBody now includes splitRecipients array
• ConfirmClaimResponseBody now includes splitRecipients array
• Removed userTokenAccount (replaced with splitRecipients)
• Added adminAmount to show protocol fee

---

2. Refactoring: Route Extraction (Commit: b2757f6)

🎯 Goal: Improve code organization and maintainability without changing any logic.

Impact: api-server.ts reduced from 2,427 → 427 lines (-82% reduction)

New Files Created:

• ✅ lib/claimService.ts (182 lines) - Claim business logic and storage
• ✅ lib/presaleService.ts (139 lines) - Presale business logic and storage
• ✅ routes/claims.ts (929 lines) - 3 claim endpoints
• ✅ routes/presale.ts (1,232 lines) - 8 presale endpoints
• ✅ REFACTORING_VERIFICATION.md - Comprehensive verification report

What Was Moved:

api-server.ts (2,090 lines removed)
├── Claim handlers → routes/claims.ts
│   ├── GET /claims/:tokenAddress
│   ├── POST /claims/mint
│   └── POST /claims/confirm
├── Presale handlers → routes/presale.ts
│   ├── GET /presale/:tokenAddress/claims/:wallet
│   ├── POST /presale/:tokenAddress/claims/prepare
│   ├── POST /presale/:tokenAddress/claims/confirm
│   ├── GET /presale/:tokenAddress/stats
│   ├── GET /presale/:tokenAddress/bids
│   ├── POST /presale/:tokenAddress/bids
│   ├── POST /presale/:tokenAddress/launch
│   └── POST /presale/:tokenAddress/launch-confirm
├── Claim storage/locks → lib/claimService.ts
└── Presale storage/locks → lib/presaleService.ts

Verification Completed:

• ✅ All route URLs identical (no API changes)
• ✅ All business logic preserved exactly
• ✅ In-memory storage properly shared across modules
• ✅ TypeScript compilation passes
• ✅ Security comments preserved
• ✅ Error handling identical
• ✅ Database calls preserved

See REFACTORING_VERIFICATION.md for detailed line-by-line verification.

---

How It Works

Example: Token with 70/30 Split

User claims 1,000 tokens:

Total Claim: 1,000 tokens
├─ 900 tokens (90%) → Split among recipients
│   ├─ 630 tokens (70%) → Creator wallet
│   └─ 270 tokens (30%) → Team wallet
└─ 100 tokens (10%) → Protocol fee (admin)

Transaction Structure:

{
  success: true,
  transaction: "...",
  claimAmount: "1000",
  splitRecipients: [
    { wallet: "Creator123...", amount: "630", label: "Creator" },
    { wallet: "Team456...", amount: "270", label: "Team Member" }
  ],
  adminAmount: "100"
}

Backwards Compatibility:

• Tokens without splits: 100% goes to creator (as before)
• Uses hasClaimRights() fallback to creator_wallet
• Existing claim flow unchanged for non-split tokens

---

Authorization Flow

Before (PR #1 merged):

User → Is creator? → Yes → Allow claim → 90% to creator, 10% to admin
                  → No  → Reject

After (PR #3):

User → Has claim rights? → Yes → Allow claim → Distribute via splits
                        → No  → Reject

hasClaimRights() checks:
1. Does user have emission split > 0%? → Yes ✅
2. Is user the creator? → Yes ✅
3. Otherwise → No ❌

---

Security Considerations

✅ Authorization: Only wallets with claim rights can initiate claims
✅ Distribution: Claims distribute to ALL recipients regardless of who initiates
✅ Validation: Split percentages validated at database level (PR #1 trigger)
✅ Immutable: Once transaction is created, splits are fixed in metadata
✅ Atomic: All recipients receive tokens in single transaction
✅ Refactoring: Zero logic changes - code moved verbatim with structural changes only

---

Testing Strategy

Manual Testing Required:

1. ✅ Claim with splits configured (multiple recipients)
2. ✅ Claim without splits (falls back to creator)
3. ✅ Non-authorized wallet attempts claim (should fail)
4. ✅ Verify all recipients receive correct proportions
5. ✅ Verify admin always receives 10%

Test Scenarios:

-- Setup test split
INSERT INTO emission_splits (token_address, recipient_wallet, split_percentage, label)
VALUES 
  ('TEST_TOKEN', 'CREATOR_WALLET', 70.00, 'Creator'),
  ('TEST_TOKEN', 'TEAM_WALLET', 30.00, 'Team');

-- Test claim initiated by creator
-- Test claim initiated by team member
-- Both should distribute 70/30

---

Why Does This Matter?

Enables Collaborative Claims:

• Teams can fairly distribute rewards automatically
• No manual token transfers needed
• Transparent and auditable distribution
• Works seamlessly with existing claim infrastructure

Improved Code Organization (Refactoring):

• 82% reduction in api-server.ts size
• Clear separation of concerns
• Easier to maintain and test
• Better for onboarding new contributors

User Experience:

• ANY split recipient can trigger the claim
• All recipients receive tokens automatically
• Clear visibility into split distribution via response
• No additional steps or complexity for users

Technical Benefits:

• Leverages PR feat: emission splits + database refactoring (-28.6% lines) #1 database foundation
• Maintains backwards compatibility
• Clean separation of concerns
• Atomic transactions prevent partial distributions
• Modular architecture for future enhancements

---

Commits in This PR

1. da8deb5 - feat: implement emission splits in claim logic

   • Original emission split implementation

2. b2757f6 - refactor: extract claims and presale routes to separate modules

   • Comprehensive refactoring for maintainability
   • Zero logic changes, purely organizational
   • See REFACTORING_VERIFICATION.md for detailed verification

---

Checklist

• Code follows project style guidelines
• Build succeeds (TypeScript compiles)
• No merge conflicts with main
• Conventional commits (feat:, refactor: prefixes)
• Documentation in PR description
• Clear explanation of value
• Read CONTRIBUTING.md
• Backwards compatible with existing tokens
• Refactoring verified line-by-line (see REFACTORING_VERIFICATION.md)

---

Dependencies

Requires: PR #1 (Database Foundation) - ✅ MERGED

Enables: PR #4 (Claim UI) - Shows splits to users

---

Related Issues

Part of emission splits feature implementation.

Previous PRs:

• PR feat: emission splits + database refactoring (-28.6% lines) #1: ✅ Database foundation for emission splits
• PR Create ztoriomigration #2: ❌ Launch UI - CANCELLED

Upcoming PRs:

• PR Create ZC emissions to ztorio #4: Claim UI to display splits for transparency

---

Note: The ZC team currently reviews PRs and determines rewards. In the future, decision markets will determine merges and rewards.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com