global_keeper.gno

  1package referral
  2
  3import (
  4	"chain"
  5)
  6
  7var gReferralKeeper ReferralKeeper
  8
  9// EventRegisterFailed is emitted when an authorized non-empty write fails.
 10// Successful non-empty writes emit the RegisterReferral event.
 11const EventRegisterFailed = "ReferralRegistrationFailed"
 12
 13func init() {
 14	if gReferralKeeper == nil {
 15		gReferralKeeper = NewKeeper()
 16	}
 17}
 18
 19// GetReferral returns the referral address string stored for the given address.
 20//
 21// Parameters:
 22//   - addr: address string whose referral relationship is queried.
 23//
 24// Returns:
 25//   - referral: stored referrer address string, or an empty string when no valid referral is found.
 26func GetReferral(addr string) string {
 27	referral, err := gReferralKeeper.get(address(addr))
 28	if err != nil {
 29		return ""
 30	}
 31	return referral.String()
 32}
 33
 34// HasReferral reports whether the given address has a stored referral.
 35//
 36// Parameters:
 37//   - addr: address string whose referral relationship is checked.
 38//
 39// Returns:
 40//   - hasReferral: true when a referral record exists; false when it is absent or invalid.
 41func HasReferral(addr string) bool {
 42	_, err := gReferralKeeper.get(address(addr))
 43	return err == nil
 44}
 45
 46// IsEmpty reports whether the referral keeper contains no referral records.
 47//
 48// Returns:
 49//   - empty: true when the keeper store has zero referral records.
 50func IsEmpty() bool {
 51	return gReferralKeeper.isEmpty()
 52}
 53
 54// GetLastOpTimestamp returns the last non-removal registration or update timestamp for an address.
 55//
 56// Parameters:
 57//   - addr: address string whose last non-removal operation is queried.
 58//
 59// Returns:
 60//   - timestamp: Unix timestamp of the last successful registration or update.
 61//   - error: nil when a timestamp exists; otherwise an invalid-address or ErrNotFound error.
 62func GetLastOpTimestamp(addr string) (int64, error) {
 63	return gReferralKeeper.getLastOpTimestamp(address(addr))
 64}
 65
 66// ContractAddress returns the address of the referral contract.
 67// Use this address as the referral parameter in TryRegister to remove an existing referral.
 68//
 69// Returns:
 70//   - address: referral contract address string, used as the removal sentinel.
 71func ContractAddress() string {
 72	return selfAddress.String()
 73}
 74
 75// TryRegister attempts to register, update, or remove a referral.
 76//
 77// Parameters:
 78//   - cur: Current realm context; callers use cross(cur) when crossing into this realm.
 79//   - addr: address whose referral relationship is read or changed.
 80//   - referral: empty string for a read, ContractAddress() to remove, or a candidate referrer address string.
 81//
 82// Returns:
 83//   - effectiveReferral: stored referrer after the operation or fallback; empty when none is stored.
 84//
 85// Empty input is treated as a read and returns the stored referrer without
 86// authorization, rate-limit checks, or event emission.
 87// Non-empty input requires an authorized caller.
 88func TryRegister(cur realm, addr address, referral string) string {
 89	if referral == "" {
 90		return GetReferral(addr.String())
 91	}
 92
 93	caller := cur.Previous().Address()
 94	assertValidCaller(caller)
 95
 96	result, err := gReferralKeeper.register(addr, address(referral))
 97	if err != nil {
 98		chain.Emit(
 99			EventRegisterFailed,
100			"address", addr.String(),
101			"error", err.Error(),
102		)
103
104		return GetReferral(addr.String())
105	}
106
107	chain.Emit(
108		"RegisterReferral",
109		"prevAddr", caller.String(),
110		"address", addr.String(),
111		"referral", result.String(),
112	)
113
114	return result.String()
115}