LogoLogo
  • ๐Ÿ‘‹Welcome to Common
    • ๐ŸฎProduct Features
  • ๐Ÿง‘โ€๐Ÿ’ปUser Sign Up + Sign In
    • ๐Ÿ”“Signing Up
      • Supported Wallets
      • SSO Explained
      • Joining a Community
      • Connecting a New Address
    • ๐Ÿ“ฑMobile Setup
    • โฉReferrals
    • ๐ŸšงUser Trust Levels
    • Manage Your Profile
      • Merge Accounts
      • User Notifications
        • Setting Up In App Notifications
        • Checkin In App Notifications
  • ๐Ÿ”ดLaunch
    • ๐Ÿš€Launchpad
    • ๐ŸŒŸLaunch a Community on Common
      • Discourse Import
    • ๐Ÿ“‡Index Ecosytem
  • ๐Ÿ—๏ธCommunity Setup
    • ๐Ÿ•ธ๏ธCustom Domain
    • ๐ŸŽŸ๏ธAdmin Capabilities
      • Community Profile
        • Stages Explained
      • Integrations
        • Directory
        • Snapshot
        • Webhooks
        • Discord
        • Community Stake
        • Terms of Service
        • Connecting an Existing Token to Your Community
          • Swaps
      • Topics
      • Admin + Moderators
      • Members & Groups
        • Creating Groups & Gating
          • Manging Groups
            • Viewing Gated Threads
        • Allowlist
      • Contests
      • Analytics
    • Community Layout
      • Forum
      • Side Navigation
    • Community Best Practices
      • Using Stages
      • Organizing Topics & Thresholds
      • Pinned Posts
  • Moderation
  • ๐Ÿ”ตEngage
    • ๐ŸงตCreating Threads
      • Thread Interactions
      • Thread Collaborators
      • Linking to Threads
    • ๐Ÿ”Gating
      • For Admins
      • For Users
    • ๐ŸฅฉCommunity Stake
      • Owning Community Stake
    • ๐Ÿ’ธCommon Contests
      • Enabling and Running Contests
      • Admin FAQs for Contests
      • User FAQs for Contests
    • ๐Ÿ’ฐFarcaster Contests
      • ๐Ÿค–Farcaster ContestBot
  • ๐ŸŸฃGovern
    • Governance
      • Snapshot Bi Directional Integration
        • Off-Chain Governance
      • What is Decentralized Governance?
        • Governance Frameworks
          • Compound Governor
          • Open Zeppelin Governor
          • Curve Governance
          • Multisig Governance
          • Snapshot Governance
      • Onchain vs. Off Chain
      • Delegating Votes
    • Treasury Management
  • ๐Ÿ’ปCommon Protocol
    • Developers
  • โœจCommon Aura
    • Common Aura
      • Season 1
        • Week 1
        • Week 2
        • Week 3
      • Quest Types
        • Twitter Quests
      • Commonly Asked Questions
  • ๐ŸฎCommunity
    • Common Brand Kit
    • X (Twitter)
    • Warpcaster
    • Common Community
    • Telegram
    • Discord
    • Zealy
  • โ›“โ›“ Protocol
    • Protocol Overview
    • Deployments
    • Contests
    • Launchpad
    • Referrals
Powered by GitBook
On this page
  • Common Protocol: Referral System Documentation
  • Introduction
  • Deployments
  • Events
  • Contract Details/Architecture
  • User Flows

Was this helpful?

  1. โ›“โ›“ Protocol

Referrals

I'll create comprehensive documentation for the Referrals system within the Common Protocol. Using the provided smart contract code, I'll follow the documentation standard you shared.

Common Protocol: Referral System Documentation

Introduction

The Referral System is a core component of the Common Protocol that enables communities to grow through incentive-aligned user acquisition. This system allows communities to reward users who bring in new members by providing them with a percentage of fees generated when new users participate in community activities.

Core Concepts:

  • Referral Tracking: Permanent association between referrers and new users at the namespace level

  • Fee Distribution: Automatic sharing of fees between the protocol and referrers

  • Role-based Access Control: Clearly defined permissions for managing the referral system

  • Hook Architecture: Integration with contest rewards via hooks to distribute referral fees

Deployments

Last Updated: April 23, 2025

Base Network

Contract Name
Address

ReferralFeeManager

0x9d3be262bed6f3a0aab4e97c0232071ef730632f

ReferralClaimHook

0x5fd4a4e28ef1eab1f74046ac15039ad05064345b

ReferralActionHook

0x4b6ecd9ecd73c38b5ba56f07c70ca122b9bdefbc

Events

Event Signatures Table

Event Name
Contract Name
Event Signature (topic0)

ReferralFeeManagerUpdated

ReferralClaimHook

0x9d85e94583b70b4c8eaa1380c1ab273059ef5262210c586dd9e3c971983af4e1

OwnershipTransferred

ReferralClaimHook

0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0

ContentRewardClaimed

ReferralClaimHook

0xe23ea816df6f7ed451d5e8be6dbca9bc76201d536ae4efd243376738328af7c0

ReferralSet

ReferralFeeManager

0x6a82ba25a343bab95b3518662f6499be99c97b63d87bafa38885aa3216fd567d

FeeSplitUpdated

ReferralFeeManager

0x5369a034ba5317502afd913e9ec49a3091a529f712e3d3b3e5c6f775db3b7d6b

ProtocolFeeDestinationUpdated

ReferralFeeManager

0xac4a732467bcd6f0a4628e9da8af90dfced86d76ca1dd0e124f494e5b88cb094

FeesDistributed

ReferralFeeManager

0xdeb4e2bedfdae1d261c2e1c3ce95284a9dac87d6e6f819aca53ebf88a6c67bb6

FeeDistributorAdded

ReferralFeeManager

0x70e0a2c1e15d36115ea07302475e5d10e5fefe2033bef9c0eaacf35c354d6e6e

FeeDistributorRemoved

ReferralFeeManager

0x02bc21baa5cb9bea5d80f12506ec4ea06e1e8ecb2a2cad32037067be5c434a84

OwnershipTransferred

ReferralFeeManager

0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0

BeneficiaryAdded

FeeManager (inherited)

0x938b2a24c98e4435ab4431d93e18a0ea23ca31bb21d914ab58d02f95a63b7a21

BeneficiaryRemoved

FeeManager (inherited)

0x386ca106f85a29171639b9914037e4b87900841c9193d3ce53b490a71ac27278

BeneficiaryUpdated

FeeManager (inherited)

0x7cfbcfebf6e794c4325d7c37e709ef0fe9f3eb464b52157b5ad7012a42aae631

ETH_FeeDistributed

FeeManager (inherited)

0xe64558d7aa0e8eae8b46cf4411eddbb6e8a66a555aaf7239549e887536d0cbb6

ERC20_FeeDistributed

FeeManager (inherited)

0xe8f9da4ef4ab6fa89f6a1957a21baef328c556a8e99b7e3966b3848c6aad42ba

Events By Contract

ReferralClaimHook

ReferralFeeManagerUpdated

  • Explanation: Emitted when the ReferralFeeManager address is updated

  • Parameters:

event ReferralFeeManagerUpdated(address indexed oldManager, address indexed newManager);
  • Called By: updateReferralFeeManager

OwnershipTransferred

  • Explanation: Emitted when ownership of the contract is transferred

  • Parameters:

event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
  • Called By: transferOwnership

ContentRewardClaimed

  • Explanation: Emitted when a content reward is claimed through the hook

  • Parameters:

event ContentRewardClaimed(address indexed winner, uint256 indexed position);
  • Called By: preClaimContentReward

Fee Distribution Mechanics:

  • The hook intercepts contest reward claims through the preClaimContentReward function

  • When the first position winner (id = 0) claims their reward, the hook triggers fee distribution

  • The hook identifies the namespace and contest token from the calling contest contract

  • It then calls the ReferralFeeManager to distribute any accumulated fees for that namespace and token

  • This ensures that referral fees are processed at the moment of reward distribution, creating a seamless user experience

ReferralFeeManager

ReferralSet

  • Explanation: Emitted when a referral relationship is established for a namespace

  • Parameters:

event ReferralSet(address indexed namespace, address indexed referral);
  • Called By: setReferral

FeeSplitUpdated

  • Explanation: Emitted when the fee split percentage is updated

  • Parameters:

event FeeSplitUpdated(uint256 newSplitPercentage);
  • Called By: setFeeSplit

ProtocolFeeDestinationUpdated

  • Explanation: Emitted when the protocol fee destination address is updated

  • Parameters:

event ProtocolFeeDestinationUpdated(address newDestination);
  • Called By: setProtocolFeeDestination

FeesDistributed

  • Explanation: Emitted when fees are distributed through the manager

  • Parameters:

event FeesDistributed(address indexed namespace, address indexed token, uint256 amount, address recipient, uint256 recipientAmount);
  • Called By: distributeFees

FeeDistributorAdded

  • Explanation: Emitted when a new fee distributor role is granted

  • Parameters:

event FeeDistributorAdded(address indexed newDistributor);
  • Called By: addFeeDistributor

FeeDistributorRemoved

  • Explanation: Emitted when a fee distributor role is revoked

  • Parameters:

event FeeDistributorRemoved(address indexed removedDistributor);
  • Called By: removeFeeDistributor

OwnershipTransferred

  • Explanation: Emitted when ownership of the contract is transferred

  • Parameters:

event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
  • Called By: setOwner

Thank you for pointing out these omissions. The updated table now includes all events from both the ReferralClaimHook and ReferralFeeManager contracts, as well as the events inherited from the FeeManager contract.

Contract Details/Architecture

ReferralFeeManager

Purpose: Manages the distribution of fees between referrers and the protocol, tracking referral relationships at the namespace level. This contract serves as the central registry for all referral relationships and handles fee splits between referrers and the protocol.

Key Functions:

  • Set and manage referral relationships between users and namespaces

  • Configure the fee split percentages between referrers and the protocol

  • Distribute accumulated fees to beneficiaries based on their assigned weights

  • Manage role-based access control for different system actions

Access Control Structure:

  • NAMESPACEFACTORYROLE: Allowed to set referral relationships for namespaces

  • FEEDISTRIBUTORROLE: Allowed to trigger fee distribution

  • OWNER_ROLE: Administrative role with permissions to update fee percentages and destinations

State Variables:

  • namespaceToReferral: Mapping that ties each namespace to its referrer

  • feeSplitPercentage: The percentage of fees allocated to referrers (in basis points)

  • protocolFeeDestination: Address that receives the protocol's share of fees

Rules:

  • Only addresses with the NAMESPACEFACTORYROLE can set referral relationships

  • Only addresses with the FEEDISTRIBUTORROLE can distribute fees

  • Only addresses with the OWNER_ROLE can update protocol fee destinations and fee splits

  • Fee split percentages must be valid (between 0-100%)

  • Each namespace can have only one referrer, once set it cannot be changed

  • The contract inherits from AccessControl to manage role-based permissions

Fee Distribution Logic:

  • When fees are received, they are split between the referrer and protocol based on feeSplitPercentage

  • If a namespace has a referrer, that referrer receives their share of fees

  • If no referrer exists, the entire fee goes to the protocol fee destination

  • Distribution supports both native currency (ETH) and ERC20 tokens

Constructor Parameters:

The constructor sets up the initial state of the contract, grants appropriate roles, and validates that all parameters meet the required constraints.

Parameter
Description
Requirements

namespaceFactory

Address of the namespace factory that will have permission to set referrals

Cannot be zero address

owner

Address of the initial contract owner

Cannot be zero address

initialFeeSplit

Initial percentage of fees allocated to referrers (0-100)

Must be between 0 and 100

initialProtocolFeeDestination

Initial address to receive protocol's share of fees

Cannot be zero address

Function Table:

Function Name
Input Parameters
Visibility
Events It Triggers
Description

setReferral

address namespace, address referral

External

ReferralSet

Associates a referrer with a namespace, creating a permanent referral relationship

setFeeSplit

uint256 percentage

External

FeeSplitUpdated

Sets the percentage of fees that go to referrers vs protocol

setProtocolFeeDestination

address destination

External

ProtocolFeeDestinationUpdated

Updates the address that receives protocol fees

addFeeDistributor

address distributor

External

FeeDistributorAdded

Grants an address permission to distribute fees

removeFeeDistributor

address distributor

External

FeeDistributorRemoved

Revokes fee distribution permission from an address

setOwner

address newOwner

External

OwnershipTransferred

Transfers ownership of the contract

distributeFees

address token, address namespace

External

FeesDistributed

Distributes accumulated fees to referrers and protocol

namespaceToReferral

address namespace

External

-

View function to get the referrer for a namespace

feeSplitPercentage

-

External

-

View function to get the current fee split percentage

protocolFeeDestination

-

External

-

View function to get the current protocol fee destination

hasRole

bytes32 role, address account

External

-

Checks if an account has a specific role

receive

-

External (payable)

-

Fallback function that allows the contract to receive ETH transactions

ReferralClaimHook

Purpose: Integrates with the Contest Governor to allow fee distribution to referrers when content rewards are claimed. This hook captures a portion of contest rewards and directs them to the appropriate referrers.

Key Functions:

  • Hook into contest reward distribution to capture referral fees

  • Pass referral fees to the ReferralFeeManager for distribution

  • Integrate with the Contest Governor's claim reward flow

Architecture:

  • Implements the IContestGovernorClaimHook interface

  • Maintains a reference to the ReferralFeeManager contract

  • Uses an ownership model for administrative functions

Integration Points:

  • Pre and post claim hooks for content rewards

  • Pre and post claim hooks for voter rewards

  • Direct interaction with ReferralFeeManager for fee distribution

Rules:

  • Only works with content from namespaces that have referrals set

  • Cannot modify the claim process, only observe and react to it

  • Maintains ownership controls for updating the ReferralFeeManager address

  • Does not interfere with the normal operation of reward distribution

Constructor Parameters:

Parameter
Description
Requirements

_referralFeeManager

Address of the ReferralFeeManager contract

Cannot be zero address

init_owner

Initial owner of the contract

Cannot be zero address

The constructor initializes the contract with references to the ReferralFeeManager and sets up the ownership structure.

Function Table:

Function Name
Input Parameters
Visibility
Events It Triggers
Description

preClaimContentReward

address winner, uint256 id

External

-

Called before contest rewards are claimed to prepare fee capture

updateReferralFeeManager

address manager

External

ReferralFeeManagerUpdated

Updates the reference to the ReferralFeeManager contract

transferOwnership

address newOwner

External

OwnershipTransferred

Transfers ownership of the contract

postClaimContentReward

address winner, uint256 id

External

ContentRewardClaimed

Called after claim to process referral fees

preClaimVoterReward

address voter, uint256 votingPower

External

-

Called before voter rewards are claimed

postClaimVoterReward

address voter, uint256 votingPower

External

-

Called after voter rewards are claimed

ReferralActionHook

Purpose: Integrates with bonding curve transactions to capture and distribute fees to referrers. This hook monitors token buy/sell actions to extract fees for referrers.

Key Functions:

  • Capture fees from token buy/sell transactions on bonding curves

  • Pass fees to ReferralFeeManager for distribution to referrers

  • Integrate with the bonding curve ecosystem

Architecture:

  • Implements the ICurveActionHook interface

  • Maintains references to relevant contracts (bonding curve, token manager, referral manager)

  • Uses an ownership model for administrative functions

Integration Points:

  • Post-buy hooks for token purchases

  • Post-sell hooks for token sales

  • Direct interaction with ReferralFeeManager for fee distribution

Token Flow:

  • When users buy/sell tokens through the bonding curve, fees are captured

  • The hook determines if the namespace has a referrer

  • If a referrer exists, appropriate fees are directed to the ReferralFeeManager

  • This creates a seamless integration between token trading and referral rewards

Rules:

  • Only the bonding curve contract can trigger hooks

  • Only works with namespaces that have referrals set

  • Cannot modify the buy/sell process, only observe and react to it

  • Maintains ownership controls for updating contract references

Function Table:

Function Name
Input Parameters
Visibility
Events It Triggers
Description

postBuyHook

address buyer, address namespace, uint256 id, uint256 amount, uint256 fee

External

-

Called after a token purchase to process referral fees

postSellHook

address seller, address namespace, uint256 id, uint256 amount, uint256 fee

External

-

Called after a token sale to process referral fees

setBondingCurveAddress

address curve

External

-

Updates the reference to the bonding curve contract

setTokenManager

address manager

External

-

Updates the reference to the token manager contract

setReferralManager

address manager

External

-

Updates the reference to the referral manager contract

newOwner

address owner

External

-

Updates the owner of the contract

User Flows

Setting Up a Referral Relationship

Flow Description: This process establishes a permanent referral relationship between a referrer and a namespace. When the namespace generates fees, a portion will be directed to the referrer.

Flow Steps:

  1. User A creates a new namespace through the NamespaceFactory

  2. During namespace creation, User A provides the address of the referrer (User B)

  3. The NamespaceFactory calls the ReferralFeeManager's setReferral function

  4. ReferralFeeManager records the referral relationship by mapping the namespace to the referrer

  5. All future fee-generating activities in this namespace will now allocate a portion to User B

Flow Chart:

User A                 NamespaceFactory               ReferralFeeManager
  โ”‚                           โ”‚                               โ”‚
  โ”‚   Create Namespace        โ”‚                               โ”‚
  โ”‚   with Referrer B         โ”‚                               โ”‚
  โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€-โ”€โ”€>โ”‚                               โ”‚
  โ”‚                           โ”‚                               โ”‚
  โ”‚                           โ”‚      setReferral              โ”‚
  โ”‚                           โ”‚      (namespace, B)           โ”‚
  โ”‚                           โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€>| Store:
  โ”‚                           โ”‚                               โ”‚ namespaceToReferral[namespace] = B
  โ”‚                           โ”‚                               โ”‚ 
  โ”‚                           โ”‚                               โ”‚
  โ”‚      Namespace Created    โ”‚                               โ”‚
  โ”‚<โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€-โ”€โ”€โ”‚                               โ”‚
  โ”‚                           โ”‚                               โ”‚

Fee Distribution Flow

Flow Description: When fees are collected from various activities (contests, token trades, etc.), they are distributed between the protocol fee destination and referrers according to the configured split.

Flow Steps:

  1. A fee-generating action occurs (e.g., token purchase, contest reward claim)

  2. The appropriate hook captures the fee and sends it to the ReferralFeeManager

  3. A distributor (any address with FEEDISTRIBUTORROLE) calls the distributeFees function

  4. ReferralFeeManager checks if the namespace has a referrer

  5. If a referrer exists, fees are split according to the configured percentage

  6. The referrer receives their portion, and the protocol fee destination receives the remainder

Flow Chart:

User                    Hook Contract              ReferralFeeManager          Beneficiaries  
  โ”‚                           โ”‚                           โ”‚                         โ”‚
  โ”‚   Fee-generating action   โ”‚                           โ”‚                         โ”‚
  โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€->โ”‚                           โ”‚                         โ”‚
  โ”‚                           โ”‚                           โ”‚                         โ”‚
  โ”‚                           โ”‚    Send fee to Manager    โ”‚                         โ”‚
  โ”‚                           โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€>โ”‚                         โ”‚
  โ”‚                           โ”‚                           โ”‚                         โ”‚
  โ”‚                           โ”‚                           โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
  โ”‚                           โ”‚                           โ”‚  โ”‚ 1. Check referral โ”‚  โ”‚
  โ”‚                           โ”‚                           โ”‚  โ”‚ 2. Calculate splitโ”‚  โ”‚
  โ”‚                           โ”‚                           โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
  โ”‚                           โ”‚                           โ”‚                         โ”‚
  โ”‚                           โ”‚                           โ”‚     Distribute fees     โ”‚
  โ”‚                           โ”‚                           โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€>โ”‚
  โ”‚                           โ”‚                           โ”‚                         โ”‚
  โ”‚      Action completed     โ”‚                           โ”‚                         โ”‚
  โ”‚<โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€-โ”‚                           โ”‚                         โ”‚
  โ”‚                           โ”‚                           โ”‚                         โ”‚
PreviousLaunchpad

Last updated 25 days ago

Was this helpful?