Implement loyalty reward program contracts (#9)

* implement deposit_pool and reward_pool for loyalty reward program

* define loyalty token

* unify variables/methods naming

* update deploy script and documents

Author: LKY-stephen

README.md

@@ -1,6 +1,6 @@
 # Talus Token Project
 
-This repository contains the smart contracts for the Talus Token project on Sui blockchain, featuring a custom token and a decentralized faucet for token distribution.
+This repository contains the smart contracts for the Talus Token project on Sui blockchain, featuring a custom token, a decentralized faucet for token distribution, a deposit pool for yield generation, and a reward pool for loyalty incentives.
 
 ## Prerequisites
 
@@ -13,8 +13,10 @@ This repository contains the smart contracts for the Talus Token project on Sui
 
 ```
 talus-token/
-├── talus/             # Talus token implementation
+├── talus/             # US token (Coin) 
 ├── faucet/            # Bi-directional faucet contract
+├── loyalty/           # Loyalty token
+├── deposit_pool/      # Deposit pool and reward pool contracts
 └── deploy.sh          # Deployment script
 ```
 
@@ -26,18 +28,66 @@ A custom token implementation on the Sui blockchain.
 ### Faucet Module
 The faucet module implements a faucet that enables exchanging between target token (e.g. TALUS) and base token (e.g. SUI) at a configurable exchange rate. Key features include:
 
-- Configurable exchange rate between two token for test net so the Sybil attack resistance is based on supply of base token
+- Configurable exchange rate between two tokens for test net so the Sybil attack resistance is based on supply of base token
 - Percentage-based withdrawal limits to prevent draining
 - Ability to inject additional liquidity
 - Simple interface for minting and refunding
 
+### Deposit Pool Module
+
+The deposit pool module allows users to deposit base tokens and earn loyalty tokens as rewards. Users can lock their tokens for different time periods with varying APY rates. Key features include:
+
+- Multiple lock terms with configurable APY
+- Early withdrawal support (configurable)
+- Pending withdrawal period (optional)
+- Admin-controlled reward pool integration
+- Receipts for each deposit, enabling precise reward calculation
+
+#### Usage
+
+```move
+// Initialize a deposit pool
+let treasury_cap = // ... obtain Loyalty token treasury cap
+let base_apy = 5; // 5% APY
+let early_withdrawal = true;
+let withdrawal_pending_days = 2;
+deposit_pool::deposit_pool::initiate<Base, Loyalty>(
+    treasury_cap, base_apy, early_withdrawal, withdrawal_pending_days, ctx
+);
+
+// Deposit base tokens
+deposit_pool::deposit_pool::deposit(pool, base_coin, term_days, clock, recipient, ctx);
+
+// Withdraw and claim rewards
+deposit_pool::deposit_pool::withdrawal(pool, receipt, clock, ctx);
+```
+
+### Reward Pool Module
+
+The reward pool module manages reward pools and allows users to claim rewards by spending loyalty tokens. Pools can be refreshed with more rewards, and events are emitted for transparency.
+
+#### Usage
+
+```move
+// Create a new reward pool
+let reward_coin = // ... obtain reward tokens
+let rate = 10; // 10 Loyalty tokens per reward token
+deposit_pool::reward_program::new_reward_pool<Loyalty, Reward>(reward_coin, rate, ctx);
+
+// Add more rewards to the pool
+deposit_pool::reward_program::reward_fresh(pool, additional_reward_coin);
+
+// Claim rewards by spending loyalty tokens
+deposit_pool::reward_program::claim(pool, loyalty_token, policy, ctx);
+```
+
 ## Deployment
 
 The project includes an automated deployment script that:
 1. Starts a local Sui node if remote rpc is not provided
 2. Sets up the environment
-3. Publishes both contracts
-4. Initializes the faucet with initial liquidity
+3. Publishes all contracts
+4. Initializes the faucet and deposit pool with initial liquidity
 
 To deploy:
 ```bash
@@ -79,16 +129,17 @@ faucet::refund(faucet, talus_coin, ctx);
 faucet::inject(faucet, additional_talus, ctx);
 ```
 
-### Security Features
+## Security Features
 
-The faucet includes several security measures:
+The contracts include several security measures:
 - Withdrawal limits (configurable percentage) prevent large withdrawals
 - Fixed exchange rates prevent manipulation
 - Shared object model ensures equal access
 - Idempotent deployment process
 - Retry mechanisms for faucet operations
+- Admin controls for deposit pool and reward pool configuration
 
-### Configuration
+## Configuration
 
 Default values in deployment:
 - Total Supply: 10^19 tokens

deploy.sh

@@ -1,56 +1,36 @@
 #!/bin/bash
-SUI="sui"
-TOTAL_AMOUNT="10^19"
-
-# Helper function for large number calculations
-_calculate() {
-    echo "scale=0; $1" | bc
-}
 
-DEFAULT_INIT=$(_calculate "$TOTAL_AMOUNT/2")
+set -euo pipefail
 
-# Add user input for RPC and alias
-read -p "Enter RPC URL (default: http://127.0.0.1:9000): " RPC_URL
-read -p "Enter environment alias (default: local): " ENV_ALIAS
-read -p "Enter initial amount (default: $DEFAULT_INIT (half)): " INIT_AMOUNT
-read -p "Enter exhcnage rate Talus/Sui (default: 10): " EXCHANGE_RATE
-read -p "Enter max withdrawal ratio every time (default: 50 (0~100)): " WITHDRAWAL_PCT
-read -p "Deploy and initialize faucet? (y/N): " DEPLOY_FAUCET
-
-
-# Set default values if no input provided
-RPC_URL=${RPC_URL:-"http://127.0.0.1:9000"}
-ENV_ALIAS=${ENV_ALIAS:-"local"}
-EXCHANGE_RATE=${EXCHANGE_RATE:-10}
-WITHDRAWAL_PCT=${WITHDRAWAL_PCT:-50}
-DEPLOY_FAUCET=${DEPLOY_FAUCET:-"n"}
+###########################################
+# Configuration Variables
+###########################################
+SUI="sui"
+TOTAL_SUPPLY="10^19"  # Changed from TOTAL_AMOUNT
+INITIAL_SPLIT_AMOUNT=0  # Changed from SPLIT_AMOUNT
+BASE_APY=2
 
-if [ -z "$INIT_AMOUNT" ]; then
-    SPLIT_AMOUNT=$DEFAULT_INIT
-else
-    SPLIT_AMOUNT=$(_calculate "$TOTAL_AMOUNT-$INIT_AMOUNT")
-fi
+###########################################
+# Helper Functions
+###########################################
 
-# Setup client if needed
-if ! $SUI client active-env | grep -q "$ENV_ALIAS"; then
-    echo "Setting up client with RPC: $RPC_URL and alias: $ENV_ALIAS"
-    $SUI client new-env --alias "$ENV_ALIAS" --rpc "$RPC_URL"
-    $SUI client switch --env "$ENV_ALIAS"
-fi
+# Calculate large numbers using bc
+_calculate_amount() {  # Changed from _calculate
+    echo "scale=0; $1" | bc
+}
 
 # Helper functions for idempotency
 _checkProcess() {
     pgrep -f "$1" >/dev/null
     return $?
 }
 
-# Run a command in the background.
+# Run a command in the background
 _evalBg() {
     eval "$@" &>/dev/null & disown;
 }
 
-
-# Get faucet coins if needed with retry
+# Get faucet coins with retry mechanism
 _getFaucetCoins() {
     local max_attempts=5
     local attempt=1
@@ -80,7 +60,40 @@ _getFaucetCoins() {
     done
 }
 
-# Start node if not running
+###########################################
+# User Input Configuration
+###########################################
+
+# Calculate default initialization amount
+DEFAULT_INIT=$(_calculate_amount "$TOTAL_SUPPLY/2")
+
+# Collect user inputs with descriptive prompts
+read -p "Enter RPC URL (default: http://127.0.0.1:9000): " RPC_URL
+read -p "Enter environment alias (default: local): " ENV_ALIAS
+read -p "Enter faucet source size (default: $DEFAULT_INIT (half)): " INIT_AMOUNT
+read -p "Enter exchange rate Talus/Sui (default: 10): " EXCHANGE_RATE
+read -p "Enter max withdrawal ratio every time (default: 50 (0~100)): " WITHDRAWAL_PCT
+read -p "Deploy and initialize faucet? (y/N): " DEPLOY_FAUCET
+
+# Set default values for configuration
+RPC_URL=${RPC_URL:-"http://127.0.0.1:9000"}
+ENV_ALIAS=${ENV_ALIAS:-"local"}
+EXCHANGE_RATE=${EXCHANGE_RATE:-10}
+WITHDRAWAL_PCT=${WITHDRAWAL_PCT:-50}
+DEPLOY_FAUCET=${DEPLOY_FAUCET:-"n"}
+
+###########################################
+# Environment Setup
+###########################################
+
+# Configure Sui client environment if not already set
+if ! $SUI client active-env | grep -q "$ENV_ALIAS"; then
+    echo "Setting up client with RPC: $RPC_URL and alias: $ENV_ALIAS"
+    $SUI client new-env --alias "$ENV_ALIAS" --rpc "$RPC_URL"
+    $SUI client switch --env "$ENV_ALIAS"
+fi
+
+# Start local node if not running
 if ! _checkProcess "$SUI start"; then
     echo "Starting Node"
     start_node="RUST_LOG=\"off,sui_node=error\" $SUI start --with-faucet --force-regenesis"
@@ -91,49 +104,152 @@ else
     echo "Node already running"
 fi
 
+###########################################
+# Token Deployment
+###########################################
+
+# Get active address
 echo "get address"
 USER=$($SUI client active-address)
 echo "Active address: \"$USER\""
 
-# Get faucet coins if needed
+# Ensure we have gas
 if ! $SUI client gas | grep -q "0x"; then
     _getFaucetCoins
 fi
 
+# Deploy main token contract
 echo "Publishing Token contract:"
-TokenContractID=$($SUI client publish --gas-budget 300000000 ./talus --json| jq -r ".objectChanges[] | select(.packageId) | .packageId")
-TalusCoin=$($SUI client balance --with-coins --json | jq -r '.[0][][1][] | select(.coinType | contains("::us::US")) | .coinObjectId')
+TOKEN_CONTRACT_ID=$($SUI client publish ./talus --json| jq -er ".objectChanges[] | select(.packageId) | .packageId")
+TALUS_COIN=$($SUI client balance --with-coins --json | jq -er '.[0][][1][] | select(.coinType | contains("::us::US")) | .coinObjectId')
 sleep 3
-echo "Token Contract at: \"$TokenContractID\""
-echo "Talus coin at : \"$TalusCoin\""
+echo "Token Contract at: \"$TOKEN_CONTRACT_ID\""
+echo "Talus coin at : \"$TALUS_COIN\""
 
-echo "Split coin"
-splitres=$($SUI client split-coin --coin-id $TalusCoin --amounts $SPLIT_AMOUNT --gas-budget 10000000)
+###########################################
+# Faucet Deployment (Optional)
+###########################################
 
-# Only deploy faucet if requested
 if [[ "${DEPLOY_FAUCET,,}" =~ ^(y|yes)$ ]]; then
+    # Calculate split amounts for faucet
+    if [ -z "$INIT_AMOUNT" ]; then
+        SPLIT_AMOUNT=$DEFAULT_INIT
+    else
+        SPLIT_AMOUNT=$(_calculate_amount "$TOTAL_SUPPLY-$INIT_AMOUNT")
+    fi
+
+    echo "Split coin"
+    _spliter=$($SUI client split-coin --coin-id $TALUS_COIN --amounts $SPLIT_AMOUNT)
+    
+    # Deploy and initialize faucet
     echo "Publishing Faucet Contract:"
-    FaucetContractID=$($SUI client publish --gas-budget 30000000 ./faucet --json | jq -r ".objectChanges[] | select(.packageId) | .packageId")
+    FaucetContractID=$($SUI client publish ./faucet --json | jq -er ".objectChanges[] | select(.packageId) | .packageId")
     sleep 3
     echo "Faucet contract at: \"$FaucetContractID\""
 
     echo "Initiate faucet"
-    FaucetID=$($SUI client call --package $FaucetContractID --module faucet --function initiate \
-        --type-args $TokenContractID::us::US --type-args 0x2::sui::SUI \
-        --args $TalusCoin --args $EXCHANGE_RATE --args $WITHDRAWAL_PCT \
-        --json | jq -r '.objectChanges[] | select(.type == "created") |.objectId')
+    FaucetID=$($SUI client call --package $FaucetContractID --module faucet --function new \
+        --type-args $TOKEN_CONTRACT_ID::us::US --type-args 0x2::sui::SUI \
+        --args $TALUS_COIN --args $EXCHANGE_RATE --args $WITHDRAWAL_PCT \
+        --json | jq -er '.objectChanges[] | select(.type == "created") |.objectId')
     echo "faucet at: $FaucetID"
 else
     echo "Skipping faucet deployment"
 fi
 
-# echo "test mint"
+###########################################
+# Loyalty Program Setup
+###########################################
+
+# Prepare coins for reward pool
+sleep 3
+echo "Split coin for reward pool"
+TALUS_COIN=$($SUI client balance --with-coins --json | jq -er '.[0][][1][] | select(.coinType | contains("::us::US")) | .coinObjectId')
+RESERVE_SIZE=$(_calculate_amount "($TOTAL_SUPPLY*85/100)-$SPLIT_AMOUNT")
+_spliter=$($SUI client split-coin --coin-id $TALUS_COIN --amounts $RESERVE_SIZE)
+
+# Deploy Loyalty Token Contract
+echo "Deploy Loyalty Token Contract"
+script=$($SUI client publish ./loyalty --json) 
+LoyaltyTokenContractID=$(echo $script | jq -er '.objectChanges[] | select(.packageId) | .packageId')
+LoyaltyTreasuryCap=$(echo $script | jq -er '.objectChanges[] | select(.objectType!= null and(.objectType | contains("TreasuryCap<"))) | .objectId')
+
+# Deploy reward pool and Deposit Pool
+sleep 3
+echo "Deploy reward pool and Deposit Pool"
+LoyaltyProgramContractID=$($SUI client publish ./deposit_pool --json | jq -er ".objectChanges[] | select(.packageId) | .packageId")
+sleep 3
+echo "Loyalty Program Contract at: \"$LoyaltyProgramContractID\""
+echo "Loyalty Token Contract at: \"$LoyaltyTokenContractID\""
+echo "Loyalty Token Cap at: \"$LoyaltyTreasuryCap\""
+
+# Initialize reward pool
+echo "Init reward pool and Deposit Pool"
+script=$($SUI client call --package $LoyaltyProgramContractID --module deposit_pool --function new \
+        --type-args $TOKEN_CONTRACT_ID::us::US --type-args $LoyaltyTokenContractID::loyalty::LOYALTY \
+        --args $LoyaltyTreasuryCap --args $BASE_APY --args false --args 0 \
+        --json)
+ADMIN_CAP=$(echo $script| jq -er '.objectChanges[] | select(.objectType!= null and(.objectType | contains("AdminCap"))) | .objectId')
+DEPOSIT_POOL=$(echo $script| jq -er '.objectChanges[] | select(.objectType!= null and(.objectType | contains("DepositPool"))) | .objectId')
+echo "Pool at: $DEPOSIT_POOL"
+echo "admin cap at $ADMIN_CAP"
+
+# Setup Reward Pool
+sleep 3
+echo "initiate reward pool"
+REWARD_POOL=$($SUI client call --package $LoyaltyProgramContractID --module reward_pool --function new \
+        --type-args $LoyaltyTokenContractID::loyalty::LOYALTY \
+        --type-args $TOKEN_CONTRACT_ID::us::US  \
+        --args $TALUS_COIN --args 1 --json | jq -er '.objectChanges[] | select(.objectType!= null and(.objectType | contains("RewardPool"))) | .objectId')
+
+sleep 3
+echo "reward pool at $REWARD_POOL"
+echo "register reward pool"
+
+# Register reward pool
+PolicyID=$($SUI client call --package $LoyaltyProgramContractID --module deposit_pool --function add_reward_program \
+        --type-args $LoyaltyProgramContractID::reward_pool::RewardProgram \
+        --type-args $TOKEN_CONTRACT_ID::us::US \
+        --type-args $LoyaltyTokenContractID::loyalty::LOYALTY \
+        --args $DEPOSIT_POOL --args $ADMIN_CAP \
+        --gas-budget 30000000 --json| jq -er '.objectChanges[] | select(.objectType!= null and(.objectType | contains("TokenPolicy"))) | .objectId' )
+        
+echo "Policy at $PolicyID"
+
+###########################################
+# Test Commands (Commented Out)
+###########################################
+
+# Test mint
 # $SUI client call --package $FaucetContractID --module faucet --function mint \
 #         --type-args $TokenContractID::us::US --type-args 0x2::sui::SUI \
-#         --args $FaucetID --args <sui coin id> \
+#         --args $FaucetID --args 0x2aecc575afe2859ddd56710c70f9c76845efbb3b4721f30438b60a815814b752 \
 #         --dry-run
+
 # echo "test refund"
 # $SUI client call --package $FaucetContractID --module faucet --function refund \
 #         --type-args $TokenContractID::us::US --type-args 0x2::sui::SUI \
 #         --args $FaucetID --args <talus coin id> \
-#         --dry-run
+#         --dry-run
+
+# echo "Test deposit to pool"
+#  $SUI client call --package $LoyaltyProgramContractID --module deposit_pool \
+#          --function deposit \
+#          --type-args $TokenContractID::us::US \
+#          --type-args $LoyaltyTokenContractID::loyalty::LOYALTY \
+#          --args $DEPOSIT_POOL \
+#          --args <us coin id> \
+#          --args 0 --args $USER --args 0x6 --dry-run
+
+# echo "Test withdrawal from pool"
+# $SUI client call --package $LoyaltyProgramContractID --module deposit_pool --function withdraw \
+#         --type-args $TokenContractID::us::US --type-args $LoyaltyTokenContractID::loyalty::LOYALTY \
+#         --args $DEPOSIT_POOL --args <receipt_nft_id> \
+#         --gas-budget 10000000
+
+# echo "Test claim reward"
+# $SUI client call --package $LoyaltyProgramContractID --module reward_program \
+#         --function claim \
+#         --type-args $LoyaltyTokenContractID::loyalty::LOYALTY \ 
+#         --type-args $TokenContractID::us::US 
+#         --args $DEPOSIT_POOL --args <token id> --args $PolicyID \