Referral

Referral system for tracking user relationships.

Overview

Manages referral relationships between users. Non-removal writes have a 24-hour cooldown per user.

Global Functions

TryRegister(cur realm, addr address, referral string) string

Attempts to register, update, or remove a referral relationship and returns the effective referrer string.

• An empty referral only reads and returns the user's current referrer. It does not require authorization or emit an event.
• An authorized non-empty write that fails emits ReferralRegistrationFailed and returns the currently stored referrer.
• Passing ContractAddress() as referral removes the relationship and returns an empty string. The zero address is not the removal sentinel and is invalid.

GetReferral(addr string) string

Returns the referral address for the given address. Returns empty string if not found.

HasReferral(addr string) bool

Returns true if the given address has a referral.

IsEmpty() bool

Returns true if no referrals exist in the system.

GetLastOpTimestamp(addr string) (int64, error)

Returns the last non-removal registration or update timestamp for the address. Returns ErrNotFound if no such operation has been recorded.

ContractAddress() string

Returns the address of the referral contract. Pass this value as referral to remove an existing relationship.

Gnoweb

Render("") explains the registration interval and removal behavior. Render("address/<address>") shows the current referrer and last registration or update time in UTC. Missing records and unsupported paths return 404.

Usage

Registering or Updating a Referral

 1package example
 2
 3import (
 4    "gno.land/r/gnoswap/referral/v1"
 5)
 6
 7// RegisterUserReferral registers or updates a referral relationship.
 8// The returned string is the effective referrer.
 9func RegisterUserReferral(cur realm, userAddr, referrerAddr address) string {
10    return referral.TryRegister(cross(cur), userAddr, referrerAddr.String())
11}

Removing a Referral

 1package example
 2
 3import (
 4    "gno.land/r/gnoswap/referral/v1"
 5)
 6
 7// RemoveUserReferral removes the referral relationship for a user.
 8func RemoveUserReferral(cur realm, userAddr address) string {
 9    return referral.TryRegister(cross(cur), userAddr, referral.ContractAddress())
10}

Querying Referrals

 1package example
 2
 3import (
 4    "gno.land/r/gnoswap/referral/v1"
 5)
 6
 7// GetUserReferrer returns the referrer address for a user.
 8// Returns empty string if no referral exists.
 9func GetUserReferrer(userAddr string) string {
10    return referral.GetReferral(userAddr)
11}
12
13// CheckUserHasReferral returns true if the user has a registered referral.
14func CheckUserHasReferral(userAddr string) bool {
15    return referral.HasReferral(userAddr)
16}

Rate Limiting

• Non-removal registrations and updates are limited to one operation per 24 hours per address.
• Passing the referral contract's own address removes a relationship and bypasses the rate-limit check.
• Removal does not overwrite the previous non-removal timestamp, so immediate re-registration can still be rejected while that timestamp is within the cooldown.

Events

• RegisterReferral is emitted for every successful non-empty write, including creation, update, and removal.
• ReferralRegistrationFailed is emitted when an authorized non-empty write fails.
• Empty referral queries do not emit events.

Security

• One referral per address
• Self-referrals are rejected
• Non-empty writes require an authorized caller
• The referral contract's own address is the removal sentinel; the zero address is invalid