Skip to content

Reward

Jump to bottom
wowok-ai edited this page May 15, 2024 · 1 revision

Reward is used to provide rewards to those who meet different conditions (guard), such as consensus on order breach, airdrops, and lucky money, etc.

Definition

struct Reward<phantom T:key + store> has key {
    id: UID,
    description: String,
    // List of rewards that can be claimed
    rewards: LinkedTable, 
    // Window time for claiming. After this time, rewards cannot be claimed, and authorized personnel can reclaim the rewards
    time_expire: u64,
    // The number of reward portions that can be claimed by meeting the guard condition; key-value pairs of guard id and reward portions
    guard: VecMap<address, u8>, 
    // List of addresses that have claimed and the number of portions claimed. Key-value pairs of claimed address and claimed portions
    has_claimed: sui_table::Table<address, Claimed>,
    // List of sponsors who have deposited rewards. Key-value pairs of sponsor address and sponsored portions
    sponsor: sui_table::Table<ID, u64>,
    // Total number of reward portions (including claimed)
    index: u64, 
    // Whether the guard is locked (no one can modify it)
    bLockedGuard: bool, 
    // Whether the same address is allowed to claim multiple times (default is false)
    bAllowRepeatClaim: bool, 
    // Operational permission
    permission: address,
}

struct Claimed has drop, store {
    portions: u32, // portions claimed
    count: u32, // may be > 1, if reward.bAllowRepeatClaim = true
}

// Maximum number of rewards in reward.rewards; claiming reduces this number, depositing increases it
const MAX_REWARD_COUNT: u64 = 600;

Operations

Launch reward (shared object)

create<T: key + store>(reward: Reward<T>) : address

Deposit rewards

deposit<T: key + store>(reward: &mut Reward<T>, deposits: vector<T>, ctx: &mut TxContext)

Claim a reward. If reward guard is set, claim_with_passport must be used

claim<T: key + store>(reward: &mut Reward<T>, clock: &Clock, ctx: &mut TxContext)

Claim a reward. The number of reward portions is set by the guard that matches the passport

claim_with_passport<T: key + store>(passport: &mut Passport, reward: &mut Reward<T>, clock: &Clock, ctx: &mut TxContext)

Set a new permission. The operation permission must satisfy being the builder of the old permission.

permission_set<T: key + store>(reward: &mut Reward<T>, old: &Permission, new: &Permission, ctx: &mut TxContext)

[Permission index: 240] Create a new Reward

new<T: key + store>(description: String, minutes_duration: u64, clock: &Clock, permission: &Permission, ctx: &mut TxContext) : Reward<T>

[Permission index: 241] Reclaim rewards, must satisfy being after the demand.time_expire time

refund<T: key + store>(reward: &mut Reward<T>, clock: &Clock, permission: &Permission, ctx: &mut TxContext)

[Permission index: 242] Extend the claim time window; minutes_expand: the number of minutes to extend

time_expand<T: key + store>(reward: &mut Reward<T>, minutes_expand: u64, permission: &Permission, ctx: &mut TxContext)

[Permission index: 243] Add guard and its corresponding reward portions; if reward.bLockedGuard is true, the operation fails

guard_add<T: key + store>(reward: &mut Reward<T>, guard: &Guard, portions: u8, permission: &Permission, ctx: &mut TxContext)

[Permission index: 244] Remove guard; if reward.bLockedGuard is true, the operation fails

guard_remove<T: key + store>(reward: &mut Reward<T>, guards: vector<address>, permission: &Permission, ctx: &mut TxContext)
guard_remove_all<T: key + store>(reward: &mut Reward<T>, permission: &Permission, ctx: &mut TxContext)

[Permission index: 245] Set the description

description_set<T: key + store>(reward: &mut Reward<T>, description: String, permission: &Permission, ctx: &mut TxContext)

[Permission index: 246] Set reward.bLockedGuard to true; cannot be modified to false again

guard_lock<T: key + store>(reward: &mut Reward<T>, permission: &Permission, ctx: &mut TxContext)

[Permission index: 247] Set reward.bAllowRepeatClaim, whether the same address is allowed to claim multiple times (default is false)

allow_repeat_claim<T: key + store>(reward: &mut Reward<T>, permission: &Permission, bAllowRepeatClaim: bool, ctx: &mut TxContext)

Operations with passport

new_with_passport<T:key + store>(passport:&mut Passport, description:String, minutes_duration:u64, clock:&Clock, permission:&Permission, ctx:&mut TxContext) : Reward<T> 
refund_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, clock:&Clock, permission:&Permission, ctx:&mut TxContext) 
time_expand_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, minutes_expand:u64, permission:&Permission, ctx:&mut TxContext)
guard_add_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, guard:&Guard, portions:u8, permission:&Permission, ctx:&mut TxContext)
guard_remove_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, guards:vector<address>, permission:&Permission, ctx:&mut TxContext)
guard_remove_all_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, permission:&Permission, ctx:&mut TxContext) 
description_set_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, description:String, permission:&Permission, ctx:&mut TxContext)
guard_lock_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, permission:&Permission, ctx:&mut TxContext) 
allow_repeat_claim_with_passport<T:key + store>(passport:&mut Passport, reward:&mut Reward<T>, permission:&Permission, bAllowRepeatClaim:bool, ctx:&mut TxContext)

On-chain query for Guard

[Query: 1] Reward permission [address]; input: none

[Query: 2] The current number of reward portions available for claiming [u64]; input: none

[Query: 3] Total supplied reward portion [u64]; input: none

[Query: 4] The number of guards [u64]; input: none

[Query: 5] Whether a certain guard is used [bool]; input: guard id [address]

[Query: 6] The number of reward portions corresponding to a certain guard [u64]; must satisfy [Query: 5]. input: guard id [address]

[Query: 7] reward.time_expire [u64]. input: none

[Query: 8] Whether a certain address has already claimed [bool]; input: user address [address]

[Query: 9] The number of reward portions claimed by a certain address [u64]; must satisfy [Query: 8]. input: user address [address]

[Query: 10] The number of addresses that have claimed rewards [u64]; input: none

[Query: 11] Whether a certain address is a sponsor [bool]; input: user address [address]

[Query: 12] The total number of reward portions sponsored by a certain sponsor [u64]; must satisfy [Query: 11]. input: user address [address]

[Query: 13] The number of sponsors [u64]; input: none

[Query: 14] Reward.bAllowRepeatClaim [bool]; input: none

[Query: 15] The number of times a certain address has claimed rewards [u64]; must satisfy [Query: 8]. input: user address [address]

Errors

181004: Already claimed
181006: Nothing left to claim
181008: Exceeded reward.time_expire
181010: Refund must be after the reward.time_expire time
181014: Portions must be greater than 0
181018: Guard is locked
181020: The number of reward.rewards has reached the maximum
Clone this wiki locally