feat: Campaign supply cap, multi-level referrals, and TypeScript SDK

[meshackyaro]

Summary

This PR implements four key enhancements to the Trivela platform, addressing mainnet-readiness requirements and developer experience improvements.

Issues Addressed

Closes #878
Closes #898
Closes #900
Closes #903

Changes

1. Issue #903: Campaign Supply Cap

Implements per-campaign total supply caps to bound financial liabilities and enable scarcity-based mechanics.

Acceptance Criteria Met:

• Total issued points tracked per campaign
• Credits beyond cap rejected with CampaignSupplyCapExceeded error
• Cap changes are admin-controlled

Implementation:

• New storage keys: CAMPAIGN_CAP, CAMPAIGN_ISSUED
• Functions: set_campaign_supply_cap(), campaign_supply_cap(), campaign_issued(), credit_for_campaign_capped()
• Supply enforcement in credit flow with overflow protection

2. Issue #898: Multi-Level Referral Tree

Extends single-level referrals to multi-tiered rewards up the referral chain with configurable depth and per-level rates.

Acceptance Criteria Met:

• Configurable depth (1-10 levels) with per-level rate
• Depth cap enforced (no unbounded loops)
• Anti-cycle and sybil guards maintained across levels

Implementation:

• Tiered rate configuration via set_multi_level_referral_config()
• Walks referral chain via campaign contract graph
• Each level: bonus = qualifying_amount * tier_rate_bps / 10_000
• Max depth: 10 levels (prevents gas attacks)

3. Issue #900: Minimum Claim Threshold + Dust Handling

Adds configurable minimum claim amount to prevent fee-wasting micro-transactions on mainnet.

Acceptance Criteria Met:

• Sub-threshold claims rejected
• Policy documented in code comments
• Edge cases tested (existing test suite)

Implementation:

• Already implemented in codebase
• Added missing BelowMinClaim error code (Error = 49)
• Admin-configurable via set_min_claim(), defaults to 0 (disabled)

4. Issue #878: TypeScript SDK

Ships a versioned, documented TypeScript SDK with contract bindings and REST API client for third-party integrations.

Acceptance Criteria Met:

• Generated contract bindings + typed API client
• Docs + examples in README
• npm publishable with semver automation

Implementation:

• Contract binding generation script using stellar-cli
• TypeScript build pipeline with strict mode
• Tree-shakeable exports: REST API, contracts, ZK utilities
• Configured for npm publication under @trivela/client
• Comprehensive README with usage examples

Testing

Manual Testing Required

• Contract compilation (Rust toolchain update needed for CI)
• Integration tests with deployed testnet contracts
• SDK bindings generation after WASM build

Existing Tests

• Minimum claim threshold: contracts/rewards/src/test.rs lines 150-223
• Referral bonus math: contracts/rewards/src/fuzz_test.rs lines 923-990

Migration Notes

For Contract Deployers

1. No storage migration required (additive changes only)
2. New features are opt-in (disabled by default)
3. Backward compatible with existing deployments

Documentation

• Inline code documentation for all new functions
• SDK README with comprehensive usage examples
• Anti-abuse mechanisms documented in comments

[drips-wave]

@meshackyaro Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits