On-Chain Affiliates & Fee Sharing
Relevant source files
The following files were used as context for generating this wiki page:
- src/lib/db/migrations/2025_09_24_001_affiliates.sql
- src/lib/db/queries/affiliate.ts
- src/app/[locale]/admin/affiliate/page.tsx
- src/app/[locale]/(platform)/settings/rewards/page.tsx/settings/rewards/page.tsx)
- src/app/[locale]/(platform)/settings/_components/SettingsAffiliateContent.tsx/settings/_components/SettingsAffiliateContent.tsx)
- src/app/[locale]/admin/affiliate/_components/AdminAffiliateOverview.tsx
- src/app/[locale]/admin/affiliate/_components/AdminAffiliateContentClient.tsx
The On-Chain Affiliates & Fee Sharing system provides a decentralized infrastructure for tracking referrals and distributing trading fees to partners. It enables platform operators to incentivize growth by sharing a percentage of the operator fees generated by referred users. The system leverages on-chain data for volume and fee calculations while maintaining an off-chain attribution database to manage relationships and generate unique referral identities.
Sources: README.md, src/lib/db/migrations/2025_09_24_001_affiliates.sql:1-12, src/app/[locale]/admin/affiliate/_components/AdminAffiliateContentClient.tsx:64-70
Architecture and Data Attribution
The system's core is the attribution of a user to an affiliate. This is handled through a referral record that links a user_id to an affiliate_user_id. When a user trades, the platform identifies the associated affiliate to calculate potential fee shares.
Referral Data Model
The affiliate_referrals table serves as the primary registry for these relationships. Each user can be referred by exactly one affiliate.
Affiliate Identity Generation
Affiliates are identified by unique alphanumeric codes. The system provides logic to ensure these codes are unique across the platform before assigning them to a user's profile.
- Code Generation: Uses 4 random bytes converted to a hex string.
- Collision Avoidance: Retries up to 10 times to find an unused code.
- Storage: The code is stored directly on the
userstable in theaffiliate_codefield.
Sources: src/lib/db/queries/affiliate.ts:9-88
Referral Logic and Enforcement
The system implements several constraints to maintain the integrity of the affiliate program, including self-referral prevention and first-touch or update logic.
Referral Recording Flow
The recording process involves updating the affiliate_referrals table and the referred_by_user_id field on the users table.
Key Functions
| Function | Purpose |
|---|---|
ensureUserAffiliateCode | Checks for an existing code or generates a new one for a user. |
getAffiliateByCode | Retrieves affiliate profile data using a specific hex code. |
getAffiliateByReference | Finds an affiliate by either their code or their username. |
recordReferral | Links a user to an affiliate while preventing self-referrals. |
Sources: src/lib/db/queries/affiliate.ts:90-243
Fee Distribution and Statistics
Fee sharing is calculated based on the volume of trades made by referred users. The commission is typically a percentage of the "operator fees" taken at trade execution rather than a percentage of the total trade volume.
Statistical Computation
The system uses SQL functions to aggregate performance metrics for affiliates:
- Total Referrals: Count of records in
affiliate_referrals. - Active Referrals: Count of unique referred users who have placed orders.
- Volume: Sum of
maker_amountfrom orders associated with the affiliate.
Sources: src/lib/db/migrations/2025_09_24_001_affiliates.sql:31-71
Admin Fee Configuration
Administrators can configure the share rates for the platform. These settings are stored in the platform's general settings repository.
| Configuration Field | Description |
|---|---|
affiliateShareBps | The percentage (in basis points) of operator fees shared with the affiliate. |
builderTakerFeeShareBps | The taker fee share for the platform builder. |
builderMakerFlatFeeBps | The flat maker fee share for the platform builder. |
Sources: src/app/[locale]/admin/affiliate/_components/AdminAffiliateContentClient.tsx:14-25, src/app/[locale]/admin/affiliate/page.tsx:90-100
User Experience and Interfaces
Affiliate Dashboard
Users can track their performance through the Rewards settings page. This interface includes:
- Referral URL: A link in the format
/r/[username_or_code]. - Performance Chart: A time-series visualization of affiliate fees and resolution rewards.
- Recent Referrals: A list of users joined via the affiliate's link, including their usernames and join dates.
Sources: src/app/[locale]/(platform)/settings/rewards/page.tsx:162-185, src/app/[locale]/(platform)/settings/_components/SettingsAffiliateContent.tsx:216-240
Admin Overview
The administrative interface provides a high-level view of all affiliate activity across the platform, allowing operators to identify top-performing partners.
Technical Implementation Details
Database Integration
The system utilizes Drizzle ORM for database interactions. SQL functions are used for heavy aggregations to ensure performance when calculating stats for many affiliates simultaneously.
CREATE OR REPLACE FUNCTION get_affiliate_stats(target_user_id CHAR(26))
RETURNS TABLE (total_referrals BIGINT, active_referrals BIGINT, volume NUMERIC)
LANGUAGE SQL STABLE AS
$$
SELECT
(SELECT COUNT(*) FROM affiliate_referrals WHERE affiliate_user_id = target_user_id),
(SELECT COUNT(DISTINCT user_id) FROM orders WHERE affiliate_user_id = target_user_id),
(SELECT SUM(maker_amount) FROM orders WHERE affiliate_user_id = target_user_id);
$$;
Sources: src/lib/db/migrations/2025_09_24_001_affiliates.sql:31-50
Security and Permissions
Row Level Security (RLS) is enabled on affiliate tables. Access is restricted to the service_role to prevent users from manipulating referral data directly, ensuring that attribution remains a server-side and administrative function.
Sources: src/lib/db/migrations/2025_09_24_001_affiliates.sql:19-27
Summary
The On-Chain Affiliates & Fee Sharing module enables a trustless partnership ecosystem. By combining off-chain referral tracking with on-chain fee data, the platform provides transparent and verifiable rewards for affiliates. Operators retain full control over the percentage of fees shared, while users benefit from an automated tracking and rewards claiming process.