feat: implement referral fees for Stonfi swapper

[NeOMakinG]

Description

Implements ShapeShift affiliate/referral fees for the Stonfi swapper on TON chain, allowing the DAO to earn fees from TON swaps.

This implementation follows the Stonfi Omniston referral fees documentation:

• Referral fees are passed to the Omniston SDK when requesting quotes
• Fees range from 0.01% to 1% (1-100 basis points)
• Uses flexibleReferrerFee: true to allow the protocol to optimize fees for better swap rates
• Fees are automatically routed to ShapeShift DAO treasury address

Issue (if applicable)

N/A - Feature implementation

Risk

Low Risk

• Changes are isolated to the Stonfi swapper implementation
• No modifications to existing transaction flows or wallet interactions
• Referral fee parameters are optional and gracefully handled (default to 0)
• Treasury address mapping follows existing patterns used by other swappers (Avnu, NearIntents, Cetus, Jupiter, etc.)
• Backend-only changes with no UI modifications

What protocols, transaction types, wallets or contract interactions might be affected by this PR?

• Protocol: Stonfi DEX on TON chain
• Transaction Types: TON swaps (both quotes and rates)
• Affected: Referral fee collection for ShapeShift DAO treasury

Testing

Engineering

Setup:

1. Replace DAO_TREASURY_TON with actual ShapeShift DAO TON treasury address
2. Ensure affiliateBps is configured in swap requests (inherited from CommonTradeQuoteInput)

Test Cases:

1. Quote with affiliate fees:

   • Request a TON swap quote with affiliateBps set (e.g., "30" for 0.3%)
   • Verify quote response includes referral fee information in stonfiSpecific
   • Check that referrerFeeUnits is populated

2. Quote without affiliate fees:

   • Request a quote with affiliateBps undefined or "0"
   • Verify quote still succeeds with referrerFeeBps: 0

3. Rate endpoint:

   • Test getTradeRate with and without affiliate fees
   • Verify rate calculations are correct

4. Treasury address resolution:

   • Verify getTreasuryAddressFromChainId(KnownChainIds.TonMainnet) returns TON treasury address
   • Check that address is properly formatted for Omniston SDK

Files Changed:

• packages/utils/src/treasury.ts - Added TON treasury address and chain ID
• packages/swapper/src/swappers/utils/helpers/helpers.ts - Added TON to treasury mapping
• packages/swapper/src/swappers/StonfiSwapper/utils/helpers.ts - Added conversion helpers
• packages/swapper/src/swappers/StonfiSwapper/swapperApi/getTradeQuote.ts - Implemented referral fees
• packages/swapper/src/swappers/StonfiSwapper/swapperApi/getTradeRate.ts - Implemented referral fees

Operations

• 🏁 My feature is behind a flag and doesn't require operations testing (yet)

Feature Flag: This implementation is automatically enabled when TON chain and Stonfi swapper are enabled. The existing TON/Stonfi feature flags control visibility.

Once Enabled:

• Swaps on TON via Stonfi will include affiliate fees
• Fees are sent to DAO treasury address configured in treasury.ts
• No user-facing UI changes - fees are handled transparently in the backend

Screenshots (if applicable)

https://tonscan.org/tx/65b02c611f58b9130241aca3e2191ec8e151eb4cc151a5c77b6fb1c02a48c33a

Done a swap from TON to USDC, got the referral fees in
N/A - Backend-only changes

---

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added affiliate and referrer fee support to trade quotes and rates, enabling dynamic fee configuration throughout the trading flow.
  • Extended Ton mainnet support with treasury address configuration for affiliate functionality.
  • Implemented fee conversion and address handling utilities to support the new affiliate fee infrastructure.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds affiliate/referrer fee support to the Stonfi swapper's trade quote and rate APIs. It introduces new helper functions for affiliate fee conversion and TON address mapping, and extends treasury configuration to support Ton mainnet lookups.

Changes

Cohort / File(s)	Summary
Stonfi Trade APIs packages/swapper/src/swappers/StonfiSwapper/swapperApi/getTradeQuote.ts, packages/swapper/src/swappers/StonfiSwapper/swapperApi/getTradeRate.ts	Added affiliateBps input parameter handling with referrer fee and address resolution. Wires referrerAddress (derived from treasury address in Omniston format) and referrerFeeBps into quote requests with flexibleReferrerFee enabled. TradeQuote and TradeRate outputs now include affiliateBps instead of hard-coded '0'.
Stonfi Helper Utilities packages/swapper/src/swappers/StonfiSwapper/utils/helpers.ts	Added two new helper functions: tonAddressToOmnistonAddress() for TON address conversion and affiliateBpsToNumber() for parsing affiliate fee strings with validation guards.
Treasury & Chain Support packages/swapper/src/swappers/utils/helpers/helpers.ts, packages/utils/src/treasury.ts	Extended treasury configuration for Ton mainnet by importing DAO_TREASURY_TON and adding it to the treasury chain mapping. Added TonMainnet to treasuryChainIds whitelist.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly Related PRs

• feat: enable butter same chain swaps #10202: Implements similar referrer/affiliate-fee wiring and treasury lookup patterns across different swapper implementations.
• fix: change starknet dao treasury address #11604: Also modifies packages/utils/src/treasury.ts to add chain-specific treasury entries.
• feat: add TON blockchain support #11625: Directly extends the same StonfiSwapper files with affiliated fee and treasury resolution logic.

Suggested Reviewers

• gomesalexandre

Poem

🐰 A swapper grows wise with each fee and address,
Affiliates flow through the Omniston mesh,
TON treasures mapped with helpers so fine,
Quote rates dancing in referral design! 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: implement referral fees for Stonfi swapper' directly and accurately summarizes the main objective of the changeset, which is adding referral/affiliate fee support to the Stonfi swapper.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch stonfi-ref

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gomesalexandre]

gm https://jam.dev/c/49574b36-ba02-4906-9656-3dfc774bea66