Skip to content

feat(referral): implement referral tier upgrade contract for volume-based reward increases (#1034) #1063

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Chucks1093 merged 1 commit into from
Oct 18, 2026
Merged

feat(referral): implement referral tier upgrade contract for volume-based reward increases (#1034) #1063

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions creator-keys/src/events.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1140,6 +1140,7 @@ pub const EARLY_ACCESS_MODE_CHANGED_EVENT_NAME: Symbol = symbol_short!("ea_mode"
pub const REFERRAL_REGISTERED_EVENT_NAME: Symbol = symbol_short!("ref_reg");
pub const REFERRAL_REWARD_ALLOCATED_EVENT_NAME: Symbol = symbol_short!("ref_rwd");
pub const REFERRAL_REWARDS_CLAIMED_EVENT_NAME: Symbol = symbol_short!("ref_clm");
pub const REFERRAL_TIER_UPGRADED_EVENT_NAME: Symbol = symbol_short!("tier_upg");
pub const KEYS_BURNED_EVENT_NAME: Symbol = symbol_short!("burned");
pub const SELF_FREEZE_APPLIED_EVENT_NAME: Symbol = symbol_short!("sf_add");
pub const SELF_FREEZE_LIFTED_EVENT_NAME: Symbol = symbol_short!("sf_del");
Expand Down Expand Up @@ -1474,6 +1475,20 @@ pub fn referral_rewards_claimed_topics() -> Symbol {
REFERRAL_REWARDS_CLAIMED_EVENT_NAME
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[contracttype]
pub struct ReferralTierUpgradedEvent {
pub referrer: Address,
pub old_tier: u32,
pub new_tier: u32,
pub volume: i128,
pub reward_rate_bps: u32,
}

pub fn referral_tier_upgraded_topics(referrer: &Address) -> (Symbol, Address) {
(REFERRAL_TIER_UPGRADED_EVENT_NAME, referrer.clone())
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[contracttype]
pub struct KeysBurnedEvent {
Expand Down
13 changes: 13 additions & 0 deletions docs/contract-event-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,5 +138,18 @@ Notes for indexers:
- `direction` is the `AlertDirection` enum, encoded as a `u32`: `0` = `Above`,
`1` = `Below`.

### Referral Tier Upgrade Events (#1034)

| Event Name | Topics (Index 0, 1) | Data Fields | Data Type |
| :--- | :--- | :--- | :--- |
| `tier_upg` | `(Symbol("tier_upg"), referrer)` | `referrer`, `old_tier`, `new_tier`, `volume`, `reward_rate_bps` | `struct ReferralTierUpgraded` |

Notes for indexers:

- `tier_upg` is emitted when a referrer's cumulative referred trade volume crosses a tier threshold.
- Tiers are ratchet-only (`Bronze` = 0, `Silver` = 1, `Gold` = 2) and never downgrade regardless of subsequent volume drops.
- `reward_rate_bps` reports the new reward rate in basis points (10,000 bps = 100%).

## Data Type Inconsistency
While the general preference is for `struct` payloads (like `register`), some high-frequency events like `buy` and `sell` use `tuples` for gas efficiency. Indexers should check the `contracttype` encoding to distinguish between map-based structs and array-based tuples.

Loading
Loading