From f68764945e1b7df6b3850eef210c35a686b4f972 Mon Sep 17 00:00:00 2001
From: scorpioborn <97235353+scorpioborn@users.noreply.github.com>
Date: Tue, 28 Nov 2023 09:19:37 +0300
Subject: [PATCH 1/3] docs: subaccount docs update

---
 docs/specs/SubAccount/01_Overview.md          |  2 +-
 docs/specs/SubAccount/02_Concepts.md          |  8 ++--
 docs/specs/SubAccount/03_State.md             | 37 ++++++++++++++-----
 docs/specs/SubAccount/04_State_Transitions.md | 22 +++++------
 docs/specs/SubAccount/05_Messages.md          | 20 +++++++---
 docs/specs/SubAccount/06_Events.md            |  1 +
 6 files changed, 58 insertions(+), 32 deletions(-)

diff --git a/docs/specs/SubAccount/01_Overview.md b/docs/specs/SubAccount/01_Overview.md
index 18a2730a..e667c84d 100644
--- a/docs/specs/SubAccount/01_Overview.md
+++ b/docs/specs/SubAccount/01_Overview.md
@@ -1,5 +1,5 @@
 # **Overview**
 
-The Sub Account module is responsible for creating, and funding a special accounts nemed `subaccount` that have different address from ther main(owner) account, this type of account fund/refund is only allowed by this module transaction endpoints and event the owner is not able to transfer any funds from this account manually using the `bank` module.
+The Sub Account module is responsible for creating, and funding a special accounts named `subaccount` that have different address from the main(owner) account, this type of account fund/refund is only allowed by this module transaction endpoints and events, the owner is not able to transfer any funds from this account manually using the `bank` module.
 
 Reward module uses this module's methods internally to grant rewards to corresponding sub account of the reward receiver main account.
diff --git a/docs/specs/SubAccount/02_Concepts.md b/docs/specs/SubAccount/02_Concepts.md
index 13f8d6b7..49779a59 100644
--- a/docs/specs/SubAccount/02_Concepts.md
+++ b/docs/specs/SubAccount/02_Concepts.md
@@ -4,9 +4,9 @@ Sub Account module is tasked with create, topup and fund/refund of a sub account
 
 ## **Sub Account**
 
-Sub Account is a special type of account that manipulating its balance can be done by the blockchain code logic and nobody can use `bank` or `staking` modules to transfer or use the subaccount balance to delegate.
+Sub Account is a special type of account that manipulating its balance can be done by the blockchain code logic and nobody can use `bank` or `staking` modules to transfer or use the `subaccount` balance to delegate.
 
-> There is a One(None)-To-One relationship between a subaccount and its owner account, so a normal account is able to have a subaccount associated with it or no subaccount associated.
+> There is a One(None)-To-One relationship between a `subaccount` and its owner account, so a normal account is able to have a `subaccount` associated with it or no `subaccount` associated.
 
 ## **TopUp**
 
@@ -18,8 +18,8 @@ Sub Account unlocked balance can be withdrawn to the owner's account balance. th
 
 ## **Wager**
 
-Using the subaccount module transaction message interfaces, the owner is able to wager using the sub account module's balance.
+Using the `subaccount` module transaction message interfaces, the owner is able to wager using the sub account module's balance, it concludes automatic withdrawal of unlocked and locked balance of the `subaccount` then use the main account address and balance to place a bet.
 
 ## **HouseDeposit/Withdraw**
 
-Using the subaccount module transaction message interfaces, the owner is able to deposit/withdraw to the house module using the sub account module's balance.
+Using the `subaccount` module transaction message interfaces, the owner is able to deposit/withdraw to the house module using the sub account module's balance.
diff --git a/docs/specs/SubAccount/03_State.md b/docs/specs/SubAccount/03_State.md
index c0ff21f2..547b3943 100644
--- a/docs/specs/SubAccount/03_State.md
+++ b/docs/specs/SubAccount/03_State.md
@@ -5,18 +5,35 @@
 State in sub account module is defined by its KVStore. This KVStore has five prefixes:
 
 1. Sub account sequential ID store to track the last generated ID of the sub accounts.
-2. Sub account owner, that makes a 1-1 relation between main account and the subaccount.
-3. Sub account address, enable the blockchain to get the subaccount info by subaccount address itself.
-4. Locked balance of each subaccount address at a certain time.
-5. Locked balance of each subaccount.
+2. Sub account owner, that makes a 1-1 relation between main account and the `subaccount`.
+3. Sub account address, enable the blockchain to get the `subaccount` info by `subaccount` address itself.
+4. Locked balance of each `subaccount` address at a certain time.
+5. Locked balance of each `subaccount`.
 
-### **Balance**
+## **Params**
+
+1. `wager_enabled`: determines if  the wager via `subaccount` is enabled or not.
+2. `deposit_enabled`: determines if  the deposit to be a house via `subaccount` is enabled or not.
+
+```proto
+// Params defines the parameters for the module.
+message Params { 
+  option (gogoproto.goproto_stringer) = false;
+
+  // wager_enabled is enable/disable status of wager feature.
+  bool wager_enabled = 1;
+  // deposit_enabled is enable/disable status of deposit feature.
+  bool deposit_enabled = 2;
+}
+```
+
+### **AccountSummary**
 
 This type contains the current state of the sub account balance.
 
 ```proto
-// Balance defines the balance of a subaccount.
-message Balance {
+// AccountSummary defines the balance of a subaccount.
+message AccountSummary {
   // deposited_amount keeps track of how much was deposited so far in the
   // subaccount.
   string deposited_amount = 1 [
@@ -32,8 +49,8 @@ message Balance {
   ];
 
   // withdrawn_amount keeps track of how much was withdrawn in the account after
-  // locked coins become free.
-  string withdrawm_amount = 3 [
+  // locked coins become unlocked.
+  string withdrawn_amount = 3 [
     (gogoproto.customtype) = "cosmossdk.io/math.Int",
     (gogoproto.nullable) = false
   ];
@@ -47,7 +64,7 @@ message Balance {
 }
 ```
 
-### **LockerBalance**
+### **LockedBalance**
 
 This type contains the locked balance state of a sub account.
 
diff --git a/docs/specs/SubAccount/04_State_Transitions.md b/docs/specs/SubAccount/04_State_Transitions.md
index 00f3624c..0390eccd 100644
--- a/docs/specs/SubAccount/04_State_Transitions.md
+++ b/docs/specs/SubAccount/04_State_Transitions.md
@@ -7,7 +7,7 @@ This section defines the state transitions of the Sub Account module's KVStore i
 When this is processed:
 
 - Sum the unlock balances according to the input locked balances.
-- Check if there is an existing subaccount for the proposed owner address.
+- Check if there is an existing `subaccount` for the proposed owner address.
 - Generate new account using account module of the Cosmos-SDK.
 - Transfer the calculated balance to the newly created account.
 - Set Sub account owner in the state.
@@ -21,7 +21,7 @@ When this is processed:
 When this is processed:
 
 - Sum the unlock balances according to the input locked balances.
-- Get subaccount by owner address from the state.
+- Get `subaccount` by owner address from the state.
 - Increase the deposited amount of the balance.
 - Set locked balance in the state.
 - Set balance in the state.
@@ -32,10 +32,10 @@ When this is processed:
 
 When this is processed:
 
-- Get Subaccount by Owner Address from the state.
+- Get `subaccount` by Owner Address from the state.
 - Call bet module's method to prepare the bet object.
-- Get subaccount balance from the state.
-- Deduct the bet amount from the sub account balance.
+- Get `subaccount` balance from the state.
+- Withdraw `subaccount` locked/unlocked balance according to the input proportion.
 - Call bet module's wager method to set the bet.
 - Set the new balance of the sub account module in the state.
 
@@ -45,9 +45,9 @@ When this is processed:
 
 When this is processed:
 
-- Get Subaccount by Owner Address from the state.
-- Get subaccount balance from the state.
-- Call house module's method to parse the ticket and valudate.
+- Get `subaccount` by Owner Address from the state.
+- Get `subaccount` balance from the state.
+- Call house module's method to parse the ticket and validate.
 - Deduct the deposit amount from the sub account balance.
 - Call house module's Deposit method to set the participation.
 - Set the new balance of the sub account module in the state.
@@ -56,9 +56,9 @@ When this is processed:
 
 When this is processed:
 
-- Get Subaccount by Owner Address from the state.
-- Get subaccount balance from the state.
-- Call house module's method to parse the ticket and valudate.
+- Get `subaccount` by Owner Address from the state.
+- Get `subaccount` balance from the state.
+- Call house module's method to parse the ticket and validate.
 - Return the withdrawal amount from the sub account balance.
 - Call house module's Deposit method to set the participation.
 - Set the new balance of the sub account module in the state.
diff --git a/docs/specs/SubAccount/05_Messages.md b/docs/specs/SubAccount/05_Messages.md
index a7f45e3b..b9b30f5b 100644
--- a/docs/specs/SubAccount/05_Messages.md
+++ b/docs/specs/SubAccount/05_Messages.md
@@ -39,10 +39,11 @@ message MsgCreate {
   // creator is the msg signer.
   string creator = 1;
 
-  // sub_account_owner is the owner of the subaccount.
-  string sub_account_owner = 2;
+  // owner is the owner of the subaccount.
+  string owner = 2;
 
   // locked_balances is the list of balance locks.
+  // Fixme: why this attribute needs to be repeated?
   repeated LockedBalance locked_balances = 3 [ (gogoproto.nullable) = false ];
 }
 
@@ -60,10 +61,12 @@ message MsgTopUp {
   // creator is the msg signer.
   string creator = 1;
 
-  // sub_account is the subaccount address.
-  string sub_account = 2;
+  // address is the subaccount address.
+  string address = 2;
 
   // locked_balances is the list of balance locks.
+  // Fixme: Are we sending multiple balance update together? If not, then only
+  // locked balance should be enough
   repeated LockedBalance locked_balances = 3 [ (gogoproto.nullable) = false ];
 }
 
@@ -93,9 +96,14 @@ message MsgWithdrawUnlockedBalancesResponse {}
 The user is able to wager using the sub account balance.
 
 ```proto
-// MsgPlaceBet wraps the MsgPlaceBet message. We need it in order not to have
+// MsgWager wraps the MsgWager message. We need it in order not to have
 // double interface registration conflicts.
-message MsgWager { sgenetwork.sge.bet.MsgWager msg = 1; }
+message MsgWager {
+  // creator is the subaccount owner.
+  string creator = 1;
+  // ticket is the jwt ticket data.
+  string ticket = 2;
+}
 
 // MsgBetResponse wraps the MsgPlaceBetResponse message. We need it in order not
 // to have double interface registration conflicts.
diff --git a/docs/specs/SubAccount/06_Events.md b/docs/specs/SubAccount/06_Events.md
index 77ec69be..361b34e4 100644
--- a/docs/specs/SubAccount/06_Events.md
+++ b/docs/specs/SubAccount/06_Events.md
@@ -58,6 +58,7 @@ The Sub Account module emits the following events
 |:---------------------:|:---------------------:|:---------------------------------:|
 | subacc_house_deposit  | creator               |  {creator}                        |
 | subacc_house_deposit  | subacc_depositor      |  {subacc_depositor}               |
+| subacc_house_deposit  | subacc_deposit_fee    |  {feeAmount}                      |
 | subacc_house_deposit  | deposit_market_index  |  {market_uid#participation_index} |
 | message               | module                |  subaccount                       |
 | message               | action                |  subacc_house_deposit             |

From b30c4bedd0ddd842398b07da840e4dd2c1f290e5 Mon Sep 17 00:00:00 2001
From: scorpioborn <97235353+scorpioborn@users.noreply.github.com>
Date: Tue, 28 Nov 2023 09:20:13 +0300
Subject: [PATCH 2/3] docs: rewards update

---
 docs/specs/Reward/01_Overview.md          |   2 +-
 docs/specs/Reward/02_Concepts.md          |  16 +-
 docs/specs/Reward/03_Accounts.md          |   6 +-
 docs/specs/Reward/04_State.md             | 238 +++++++++++++++++-----
 docs/specs/Reward/05_State_Transitions.md |  21 +-
 docs/specs/Reward/06_Messages.md          | 149 +++++++++-----
 docs/specs/Reward/07_Events.md            |  20 +-
 7 files changed, 332 insertions(+), 120 deletions(-)

diff --git a/docs/specs/Reward/01_Overview.md b/docs/specs/Reward/01_Overview.md
index 856d255f..cc9e336a 100644
--- a/docs/specs/Reward/01_Overview.md
+++ b/docs/specs/Reward/01_Overview.md
@@ -2,4 +2,4 @@
 
 The Reward module is responsible for Campaign state management and reward validation and application.
 
-To grant rewards, this module uses `subaccount` module methods to TopUp the subaccount balance.
+To grant rewards, this module uses `subaccount` module methods to TopUp the sub account balance and withdraw it when there is a withdraw request or wager or house deposit.
diff --git a/docs/specs/Reward/02_Concepts.md b/docs/specs/Reward/02_Concepts.md
index cac93cd7..86e8f85a 100644
--- a/docs/specs/Reward/02_Concepts.md
+++ b/docs/specs/Reward/02_Concepts.md
@@ -1,6 +1,6 @@
 # **Concepts**
 
-Reward module is tasked with create and update of campaigns and reward application (allocation). the user can create a campaign through commandline or singing and broadcasting the campaign create message.
+Reward module is tasked with create and update of campaigns and reward application (allocation). the user can create a campaign through command-line or singing and broadcasting the campaign create message.
 
 ## **Campaign**
 
@@ -8,18 +8,16 @@ Campaigns are being distinguished by their UID, We can have multiple campaigns w
 
 ## **Reward Types**
 
-### **Signup**
+### **SignUp Rewards**
+
+#### **1. SignUp**
 
 This reward can be given when a user is creating an account by signing up in system, the reward is in `subaccount` balance and can be used for betting or be the house functionalities.
 
-### **Referral**
+#### **2. Referral**
 
 This reward can be given when a user is referring another new user to the system, the referrer and referee reward is in `subaccount` balance and can be used for betting or be the house functionalities.
 
-### **Affiliation**
-
-This reward can be given when an influencer or advertiement entity brings an amount of attention to the platform, responsible user account will be rewarded.
-
-### **No Loss Bets**
+#### **3. Affiliation**
 
-This reward can be given when a user, do not win any bet for a 10 sequential bets.
+This reward can be given when an influencer or advertisement entity brings an amount of attention to the platform, responsible user account will be rewarded.
diff --git a/docs/specs/Reward/03_Accounts.md b/docs/specs/Reward/03_Accounts.md
index 2a321315..f7f1a9ac 100644
--- a/docs/specs/Reward/03_Accounts.md
+++ b/docs/specs/Reward/03_Accounts.md
@@ -2,10 +2,10 @@
 
 There is one account in the Reward module.
 
-- Reward Pool: This account holds the reward amount transferred from the campaign funder to the `reward_pool` module account.
+- Reward Pool: This account holds the reward amount transferred from the campaign `funder` to the `reward_pool` module account.
 
 During the campaign creation the pool amount will be transferred to the reward pool module account.
 
-## Apply Reward Transfer
+## **Grant Reward Transfer**
 
-The reward would be transferred to the reward receiver main account (or sub account).
+The reward would be transferred to the reward receiver main account (or sub account) according to the ticket payload of the grant reward transaction endpoint.
diff --git a/docs/specs/Reward/04_State.md b/docs/specs/Reward/04_State.md
index 07be41ea..b485fd35 100644
--- a/docs/specs/Reward/04_State.md
+++ b/docs/specs/Reward/04_State.md
@@ -12,45 +12,77 @@ The Reward model in the Proto files is as below:
 
 1. `creator`: is the creator account(message signer of the CreateCampaign).
 2. `uid`: is the universal unique identifier of the campaign.
-3. `funder_address`: The account address that is responsible for paying the campaing pool balance.
+3. `promoter`: The account address that is responsible for paying the campaign pool balance.
 4. `start_ts`: The time that campaign would be started and receive apply reward message.
 5. `end_ts`: The time that campaign would be ended and is not able tor receive apply reward message.
-6. `reward_type`: Defines the type of reward that is defined for the campaign.
-7. `reward_defs`: Definitions of the payable rewards receivers and amounts.
-8. `pool`: Information of the current pool balance.
+6. `reward_category`: Defines the general category of reward that is defined for the campaign.
+7. `reward_type`: Defines the type of reward that is defined for the campaign.
+8. `reward_amount_type`: Defines the type of reward amount allocation that is defined for the campaign.
+9. `reward_amount`: Defines the amount of reward that is defined for the campaign to be granted to main or sub account.
+10. `pool`: Information of the current pool balance.
+11. `is_active`: Is active/inactive status of the campaign.
+12. `claims_per_category`: Maximum number of reward grant transaction per category.
+13. `meta`: Contains a string metadata that can be a simple description or a json.
 
 ```proto
 // Campaign is type for defining the campaign properties.
 message Campaign {
   // creator is the address of campaign creator.
   string creator = 1;
+
+  // uid is the unique identifier of a campaign.
   string uid = 2 [
     (gogoproto.customname) = "UID",
     (gogoproto.jsontag) = "uid",
     json_name = "uid"
   ];
-  string funder_address = 3;
+
+  // promoter is the address of campaign promoter.
+  // Funds for the campaign would be deducted from this account.
+  string promoter = 3;
+
   // start_ts is the start timestamp of a campaign.
   uint64 start_ts = 4 [
     (gogoproto.customname) = "StartTS",
     (gogoproto.jsontag) = "start_ts",
     json_name = "start_ts"
   ];
+
   // end_ts is the end timestamp of a campaign.
   uint64 end_ts = 5 [
     (gogoproto.customname) = "EndTS",
     (gogoproto.jsontag) = "end_ts",
     json_name = "end_ts"
   ];
-  // reward_type is the type of defined reward.
-  RewardType reward_type = 6;
-  // reward_defs is the list of definitions of the campaign rewards.
-  repeated Definition reward_defs = 7 [ (gogoproto.nullable) = false ];
-  // pool is the tracker of pool funds of the campaign.
-  Pool pool = 8 [ (gogoproto.nullable) = false ];
+
+  // reward_category is the category of reward.
+  RewardCategory reward_category = 6;
+
+  // reward_type is the type of reward.
+  RewardType reward_type = 7;
+
+  // amount_type is the type of reward amount.
+  RewardAmountType reward_amount_type = 8;
+
+  // reward_amount is the amount defined for a reward.
+  RewardAmount reward_amount = 9;
+
+  // pool is the tracker of campaign funds.
+  Pool pool = 10 [ (gogoproto.nullable) = false ];
+
+  // is_active is the flag to check if the campaign is active or not.
+  bool is_active = 11;
+
+  // claims_per_category is the number of times a user can claim a
+  // reward for category of this campaign.
+  uint64 claims_per_category = 12;
+
+  // meta is the metadata of the campaign.
+  // It is a stringified base64 encoded json.
+  string meta = 13;
 }
 
-// Pool is the type for the campaign funding pool.
+// Pool tracks funds assigned and spent to/for a campaign.
 message Pool {
   string total = 1 [
     (gogoproto.customtype) = "cosmossdk.io/math.Int",
@@ -64,62 +96,160 @@ message Pool {
   ];
 }
 
-// Definition is the type for reward declaration for a campaign.
-message Definition {
-  ReceiverType rec_type = 1;
-  ReceiverAccType rec_acc_type = 2;
-  string amount = 3 [
-    (gogoproto.customtype) = "cosmossdk.io/math.Int",
-    (gogoproto.nullable) = false,
-    (gogoproto.moretags) = "yaml:\"amount\""
-  ];
-  uint64 unlock_ts = 4 [
-    (gogoproto.customname) = "UnlockTS",
-    (gogoproto.jsontag) = "unlock_ts",
-    json_name = "unlock_ts"
-  ];
-}
+// RewardType defines supported types of rewards in reward module.
+enum RewardCategory {
+  // the invalid or unknown
+  REWARD_CATEGORY_UNSPECIFIED = 0;
 
-// Receiver is the type for reward receiver properties.
-message Receiver {
-  ReceiverType rec_type = 1;
-  string addr = 2;
+  // signup reward
+  REWARD_CATEGORY_SIGNUP = 1;
+
+  // referral reward
+  REWARD_CATEGORY_REFERRAL = 2;
+
+  // affiliate reward
+  REWARD_CATEGORY_AFFILIATE = 3;
+
+  // bet refunds
+  REWARD_CATEGORY_BET_REFUND = 4;
+
+  // milestone reward
+  REWARD_CATEGORY_MILESTONE = 5;
+
+  // bet discounts
+  REWARD_CATEGORY_BET_DISCOUNT = 6;
+
+  // other rewards
+  REWARD_CATEGORY_OTHER = 7;
 }
 
 // RewardType defines supported types of rewards of reward module.
 enum RewardType {
   // the invalid or unknown
   REWARD_TYPE_UNSPECIFIED = 0;
+
   // signup reward
   REWARD_TYPE_SIGNUP = 1;
+
+  // referral signup reward
+  REWARD_TYPE_REFERRAL_SIGNUP = 2;
+
+  // affiliate signup reward
+  REWARD_TYPE_AFFILIATE_SIGNUP = 3;
+
   // referral reward
-  REWARD_TYPE_REFERRAL = 2;
-  // affiliation reward
-  REWARD_TYPE_AFFILIATION = 3;
-  // noloss bets reward
-  REWARD_TYPE_NOLOSS_BETS = 4;
+  REWARD_TYPE_REFERRAL = 4;
+
+  // affiliate reward
+  REWARD_TYPE_AFFILIATE = 5;
+
+  // bet refunds
+  REWARD_TYPE_BET_REFUND = 6;
+
+  // milestone reward
+  REWARD_TYPE_MILESTONE = 7;
+
+  // bet discounts
+  REWARD_TYPE_BET_DISCOUNT = 8;
+
+  // other rewards
+  REWARD_TYPE_OTHER = 9;
 }
 
-// ReceiverAccType defines supported types account types for reward
-// distribution.
-enum ReceiverAccType {
+// RewardType defines supported types of rewards of reward module.
+enum RewardAmountType {
   // the invalid or unknown
-  RECEIVER_ACC_TYPE_UNSPECIFIED = 0;
-  // main account
-  RECEIVER_ACC_TYPE_MAIN = 1;
-  // sub account
-  RECEIVER_ACC_TYPE_SUB = 2;
+  REWARD_AMOUNT_TYPE_UNSPECIFIED = 0;
+
+  // Fixed amount
+  REWARD_AMOUNT_TYPE_FIXED = 1;
+
+  // Business logic defined amount
+  REWARD_AMOUNT_TYPE_LOGIC = 2;
+
+  // Percentage of bet amount
+  REWARD_AMOUNT_TYPE_PERCENTAGE = 3;
 }
+```
 
-// ReceiverType defines all of reward receiver types in the system.
-enum ReceiverType {
-  // the invalid or unknown
-  RECEIVER_TYPE_UNSPECIFIED = 0;
-  // single receiver account
-  RECEIVER_TYPE_SINGLE = 1;
-  // referrer
-  RECEIVER_TYPE_REFERRER = 2;
-  // referee
-  RECEIVER_TYPE_REFEREE = 3;
+## **Reward**
+
+1. `uid`: is the unique universal identifier of the granted reward.
+2. `creator`: is the creator account(message signer of the CreateCampaign).
+3. `receiver`: is the string address of the main account.
+4. `campaign_uid`: is the unique identifier of the associated campaign.
+5. `reward_amount`: is the amount to be deducted from main and sub account balances.
+6. `source_uid`: is the source of reward grant universal unique identifier.
+7. `meta`: is the metadata related to the granted reward, can be a string or json.
+
+```proto
+// Reward is the type for transaction made to reward a user
+// based on users eligibility.
+message Reward {
+
+  // uid is the unique identifier for a reward.
+  string uid = 1 [
+    (gogoproto.customname) = "UID",
+    (gogoproto.jsontag) = "uid",
+    json_name = "uid"
+  ];
+
+  // creator is the address of the account that invokes the reward transaction.
+  string creator = 2;
+
+  // receiver is the address of the account that receives the reward.
+  string receiver = 3;
+
+  // campaign_uid is the unique identifier of the campaign.
+  string campaign_uid = 4 [
+    (gogoproto.customname) = "CampaignUID",
+    (gogoproto.jsontag) = "campaign_uid",
+    json_name = "campaign_uid"
+  ];
+
+  // reward_amount is the amount of the reward.
+  RewardAmount reward_amount = 7 [
+    (gogoproto.customname) = "RewardAmount",
+    (gogoproto.jsontag) = "reward_amount",
+    json_name = "reward_amount"
+  ];
+
+  // source_uid is the address of the source.
+  // It is used to identify the source of the reward.
+  // For example, the source uid of a referral signup
+  // reward is the address of the referer.
+  string source_uid = 8 [
+    (gogoproto.customname) = "SourceUID",
+    (gogoproto.jsontag) = "source_uid",
+    json_name = "source_uid"
+  ];
+
+  // meta is the metadata of the campaign.
+  // It is a stringified base64 encoded json.
+  string meta = 12;
+}
+
+// RewardAmount
+message RewardAmount {
+  // main_account_reward amount transferred to main account address
+  string main_account_amount = 1 [
+    (gogoproto.customtype) = "cosmossdk.io/math.Int",
+    (gogoproto.nullable) = false,
+    (gogoproto.moretags) = "yaml:\"main_account_amount\""
+  ];
+
+  // sub_account reward amount transferred to subaccount address
+  string subaccount_amount = 2 [
+    (gogoproto.customtype) = "cosmossdk.io/math.Int",
+    (gogoproto.nullable) = false,
+    (gogoproto.moretags) = "yaml:\"subaccount_amount\""
+  ];
+
+  // unlock_period is the period after which the reward is unlocked.
+  uint64 unlock_period = 3 [
+    (gogoproto.customname) = "UnlockPeriod",
+    (gogoproto.jsontag) = "unlock_period",
+    json_name = "unlock_period"
+  ];
 }
 ```
diff --git a/docs/specs/Reward/05_State_Transitions.md b/docs/specs/Reward/05_State_Transitions.md
index 1845e3ff..bc02f7f8 100644
--- a/docs/specs/Reward/05_State_Transitions.md
+++ b/docs/specs/Reward/05_State_Transitions.md
@@ -11,25 +11,30 @@ When this is processed:
 ```go
 newCampaign := &types.Campaign{
     Creator:            msg.Creator,
-    FunderAddress:      msg.ticket.FunderAddress,
     UID:                msg.UID,
+    Promoter:           msg.ticket.Promoter,
     StartTS:            msg.ticket.StartTs,
     EndTS:              msg.ticket.EndTs,
+    RewardCategory:     msg.ticket.RewardCategory,
     RewardType:         msg.ticket.RewardType,
-    RewardDefs:         msg.ticket.RewardDefs,
-    Pool:               Pool{ Total: msg.Ticket.PoolAmount },
+    reward_amount_type: msg.ticket.RewardAmountType,
+    reward_amount:      msg.ticket.RewardAmount,
+    Pool:               Pool{ Total: msg.Ticket.TotalFunds },
+    is_active:          msg.ticket.IsActive,
+    claims_per_category:msg.ticket.ClaimsPerCategory,
+    meta:               msg.ticket.Meta,
 }
 ```
 
 ---
 
-## **Apply Reward**
+## **Grant Reward**
 
 When this is processed:
 
 - If the corresponding campaign exists and is not expired, continue the process.
 
-- Calculate reward distribution according to the reward definitions of the campaign and the reward type.  
+- Calculate reward distribution according to the reward amounts defined int the campaign and the reward type and category.  
 
 - Validate availability of the pool balance for the campaign.
 
@@ -37,4 +42,10 @@ When this is processed:
 
 - Update the campaign pool according to the distribution.
 
+- Set Reward into the module state.
+
+- Set Reward by receiver into the module state.
+
+- Set Reward by campaign into the module state.
+
 > Note: The reward application modifies the campaign pool balance and accounts balances, but does not store reward application in the module state.
diff --git a/docs/specs/Reward/06_Messages.md b/docs/specs/Reward/06_Messages.md
index 16739699..d033dd89 100644
--- a/docs/specs/Reward/06_Messages.md
+++ b/docs/specs/Reward/06_Messages.md
@@ -5,12 +5,14 @@ handler endpoints is as follows
 
 ```proto
 service Msg {
-  // CreateCampaign is campaign create message endpoint.
+  // CreateCampaign is a method to create a campaign
   rpc CreateCampaign(MsgCreateCampaign) returns (MsgCreateCampaignResponse);
-  // UpdateCampaign is campaign update message endpoint.
+  // UpdateCampaign is a method to update campaign
   rpc UpdateCampaign(MsgUpdateCampaign) returns (MsgUpdateCampaignResponse);
-  // ApplyReward is reward application message endpoint.
-  rpc ApplyReward(MsgApplyReward) returns (MsgApplyRewardResponse);
+  // WithdrawCampaignFunds is method to withdraw funds from the campaign
+  rpc WithdrawFunds(MsgWithdrawFunds) returns (MsgWithdrawFundsResponse);
+  // GrantReward is method to allocate rewards
+  rpc GrantReward(MsgGrantReward) returns (MsgGrantRewardResponse);
 }
 ```
 
@@ -19,14 +21,20 @@ service Msg {
 Within this message, the user specifies the campaign information they wish to create.
 
 ```proto
-// MsgCreateCampaign is campaign create message type.
+// MsgCreateCampaign is msg to create a reward campaign
 message MsgCreateCampaign {
-  // creator is the address of creator account.
+  // creator is the address of campaign creator account.
   string creator = 1;
-  // uid is the uinque identifier of the campaign.
+  // uid is the unique identifier of the campaign.
   string uid = 2;
+  // total_funds is the total funds allocated to the campaign.
+  string total_funds = 3 [
+    (gogoproto.customtype) = "cosmossdk.io/math.Int",
+    (gogoproto.nullable) = false,
+    (gogoproto.moretags) = "yaml:\"total_funds\""
+  ];
   // ticket is the payload data.
-  string ticket = 3;
+  string ticket = 4;
 }
 
 // MsgCreateCampaignResponse campaign create message response type.
@@ -37,19 +45,20 @@ message MsgCreateCampaignResponse {}
 
 ```json
 {
- "funder_address": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
+ "promoter": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
  "start_ts": 1695970800,
  "end_ts": 1727593200,
- "type": 3,
-    "reward_defs": [
-        {
-            "rec_type": 1,
-            "amount": "100",
-            "rec_acc_type": 1,
-            "unlock_ts": 0
-        }
-    ],
- "pool_amount": "1000",
+ "category": 1,
+ "reward_type": 1,
+ "reward_amount_type": 1,
+ "reward_amount": {
+  "main_account_amount": "100",
+  "sub_account_amount": "100",
+  "unlock_period": 136318754373
+ },
+ "is_active": true,
+ "claims_per_category": 1,
+ "meta": "custom metadata",
  "exp": 1667863498866062000,
  "iat": 1667827498,
  "iss": "Oracle",
@@ -57,61 +66,109 @@ message MsgCreateCampaignResponse {}
 }
 ```
 
-## **MsgApplyReward**
+## **MsgUpdateCampaign**
+
+Within this message, the user specifies the campaign information they wish to update.
+
+```proto
+// MsgUpdateCampaign is campaign update message type.
+message MsgUpdateCampaign {
+  // creator is the address of creator account.
+  string creator = 1;
+  // uid is the unique identifier of the campaign.
+  string uid = 2;
+  // topup_funds is the topup funds to increase the pool balance of the
+  // campaign.
+  string topup_funds = 3 [
+    (gogoproto.customtype) = "cosmossdk.io/math.Int",
+    (gogoproto.nullable) = false,
+    (gogoproto.moretags) = "yaml:\"topup_funds\""
+  ];
+  // ticket is the payload data.
+  string ticket = 4;
+}
+
+// MsgUpdateCampaignResponse campaign update message response type.
+message MsgUpdateCampaignResponse {}
+```
+
+### **Sample Update Campaign ticket**
+
+```json
+{
+ "end_ts": 1727593200,
+ "is_active": true,
+ "exp": 1667863498866062000,
+ "iat": 1667827498,
+ "iss": "Oracle",
+ "sub": "UpdateCampaign"
+}
+```
+
+## **MsgGrantReward**
 
 Within this message, the user specifies the reward application information they wish to apply.
 
 ```proto
-// MsgApplyReward is apply reward message type.
-message MsgApplyReward {
+// MsgGrantReward is execute reward message type.
+message MsgGrantReward {
   // creator is the address of creator account.
   string creator = 1;
-  // campaign_uid is the uinque identifier of the campaign.
-  string campaign_uid = 2;
+  // uid is the unique identifier of the reward.
+  string uid = 2;
+  // campaign_uid is the unique identifier of the reward campaign.
+  string campaign_uid = 3;
   // ticket is the payload data.
-  string ticket = 3;
+  string ticket = 4;
 }
 
 // MsgApplyRewardResponse apply reward message response type.
 message MsgApplyRewardResponse {}
 ```
 
-### **Sample Apply Reward ticket**
-
-Note: Signup, Affiliation, and noloss bets rewards needs this format of payload.
+### **Sample Grant Reward ticket**
 
 ```json
 {
- "receiver": {
-    "rec_type": 1,
-    "addr": "sge1w77wnncp6w6llqt0ysgahpxjscg8wspw43jvtd"
+ "common": {
+  "receiver": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
+  "source_uid": "source uid",
+  "meta": "custom grant metadata"
  },
  "exp": 1667863498866062000,
  "iat": 1667827498,
  "iss": "Oracle",
- "sub": "ApplyReward"
+ "sub": "GrantReward"
+}
+```
+
+## **MsgWithdrawFunds**
+
+Within this message, the user specifies the reward application information they wish to apply.
+
+```proto
+// MsgWithdrawFunds is withdraw funds message type.
+message MsgWithdrawFunds {
+  // creator is the address of creator account.
+  string creator = 1;
+  // uid is the unique identifier of the reward campaign.
+  string uid = 2;
+  // ticket is the payload data.
+  string ticket = 3;
 }
+
+// MsgWithdrawFundsResponse withdraw funds message response type.
+message MsgWithdrawFundsResponse {}
 ```
 
-Note: Referral reward needs this format of payload.
+### **Sample Withdraw funds ticket**
 
 ```json
 {
- "receivers": [
-  {
-    "rec_type": 2,
-    "addr": "sge1w77wnncp6w6llqt0ysgahpxjscg8wspw43jvtd"
-  },
-  {
-    "rec_type": 3,
-    "addr": "sge1afdqdea8r2uh0ujn8l62fw7plvagzqgcmph40n"
-  }
- ],
+ "promoter": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
  "exp": 1667863498866062000,
  "iat": 1667827498,
  "iss": "Oracle",
- "sub": "ApplyReward"
+ "sub": "WithdrawFunds"
 }
 ```
-
-Note: All of the definitions of the campaign `reward_defs` should be defined in the `receiver`/`receivers`.
diff --git a/docs/specs/Reward/07_Events.md b/docs/specs/Reward/07_Events.md
index 85370145..89543703 100644
--- a/docs/specs/Reward/07_Events.md
+++ b/docs/specs/Reward/07_Events.md
@@ -26,13 +26,29 @@ The Bet module emits the following events
 
 ---
 
-## *MsgApplyReward*
+## *MsgWithdrawFunds*
+
+| **Type**                   | **Attribute Key**         | **Attribute Value**   |
+|----------------------------|---------------------------|-----------------------|
+| withdraw_funds             | creator                   | {creator}             |
+| withdraw_funds             | uid                       | {uid}                 |
+| message                    | module                    | reward                |
+| message                    | action                    | withdraw_funds        |
+| message                    | sender                    | {creator}             |
+
+---
+
+## *MsgGrantReward*
 
 | **Type**                   | **Attribute Key**         | **Attribute Value**              |
 |----------------------------|---------------------------|----------------------------------|
 | apply_reward               | creator                   | {creator}                        |
 | apply_reward               | campaign_uid              | {campaign_uid}                   |
-| distributions              | distributions             | {yaml string of distributions}   |
+| apply_reward               | reward_uid                | {reward_uid}                     |
+| apply_reward               | promoter                  | {promoter}                       |
+| apply_reward               | main_acc_amount           | {main_acc_amount}                |
+| apply_reward               | sub_acc_amount            | {sub_acc_amount}                 |
+| apply_reward               | sub_acc_unlock_period     | {sub_acc_unlock_period}          |
 | message                    | module                    | reward                           |
 | message                    | action                    | apply_reward                     |
 | message                    | sender                    | {creator}                        |

From 5a56f8eb5fe23a9e3780f0ffef8acaf98c765c42 Mon Sep 17 00:00:00 2001
From: scorpioborn <97235353+scorpioborn@users.noreply.github.com>
Date: Mon, 11 Dec 2023 15:18:37 +0300
Subject: [PATCH 3/3] docs: ticked payload of reward grant

---
 docs/specs/Reward/02_Concepts.md |   6 +-
 docs/specs/Reward/03_Accounts.md |   2 +-
 docs/specs/Reward/06_Messages.md | 107 ++++++++++++++++++++++++++++++-
 3 files changed, 109 insertions(+), 6 deletions(-)

diff --git a/docs/specs/Reward/02_Concepts.md b/docs/specs/Reward/02_Concepts.md
index 86e8f85a..c20183ac 100644
--- a/docs/specs/Reward/02_Concepts.md
+++ b/docs/specs/Reward/02_Concepts.md
@@ -16,8 +16,8 @@ This reward can be given when a user is creating an account by signing up in sys
 
 #### **2. Referral**
 
-This reward can be given when a user is referring another new user to the system, the referrer and referee reward is in `subaccount` balance and can be used for betting or be the house functionalities.
+This reward can be given when a user is referred by another user to the system, the referee reward is in `subaccount` balance and can be used for betting or be the house functionalities.
 
-#### **3. Affiliation**
+### **Referral**
 
-This reward can be given when an influencer or advertisement entity brings an amount of attention to the platform, responsible user account will be rewarded.
+This reward can be given when a user is referring another new user to the system, the referrer reward is in `subaccount` balance and can be used for betting or be the house functionalities.
diff --git a/docs/specs/Reward/03_Accounts.md b/docs/specs/Reward/03_Accounts.md
index f7f1a9ac..71085561 100644
--- a/docs/specs/Reward/03_Accounts.md
+++ b/docs/specs/Reward/03_Accounts.md
@@ -2,7 +2,7 @@
 
 There is one account in the Reward module.
 
-- Reward Pool: This account holds the reward amount transferred from the campaign `funder` to the `reward_pool` module account.
+- Reward Pool: This account holds the reward amount transferred from the campaign `promoter` to the `reward_pool` module account.
 
 During the campaign creation the pool amount will be transferred to the reward pool module account.
 
diff --git a/docs/specs/Reward/06_Messages.md b/docs/specs/Reward/06_Messages.md
index d033dd89..9c17ee46 100644
--- a/docs/specs/Reward/06_Messages.md
+++ b/docs/specs/Reward/06_Messages.md
@@ -126,15 +126,118 @@ message MsgGrantReward {
 message MsgApplyRewardResponse {}
 ```
 
-### **Sample Grant Reward ticket**
+### MsgGrantRewardTicket Payloads
+
+#### Common ticket payload type
+
+This is a common type that should be present in all of the ticket payloads
+
+```proto
+// RewardPayloadCommon
+message RewardPayloadCommon {
+  // receiver is the address of the account that receives the reward.
+  string receiver = 1;
+
+  // source_uid is the address of the source.
+  // It is used to identify the source of the reward.
+  // For example, the source uid of a referral signup reward is the address of
+  // the referer.
+  string source_uid = 2 [
+    (gogoproto.customname) = "SourceUID",
+    (gogoproto.jsontag) = "source_uid",
+    json_name = "source_uid"
+  ];
+
+  // meta is the metadata of the campaign.
+  // It is a stringified base64 encoded json.
+  string meta = 3;
+}
+```
+
+#### **1. Individual Signup**
+
+```proto
+// GrantSignupRewardPayload is the type for signup reward grant payload.
+message GrantSignupRewardPayload {
+  // common is the common properties of a reward
+  RewardPayloadCommon common = 2 [ (gogoproto.nullable) = false ];
+}
+```
+
+##### **Sample Signup Grant Reward ticket**
+
+The `source_uid` should be empty.
+
+```json
+{
+ "common": {
+  "receiver": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
+  "source_uid": "",
+  "meta": "custom grant metadata"
+ },
+ "exp": 1667863498866062000,
+ "iat": 1667827498,
+ "iss": "Oracle",
+ "sub": "GrantReward"
+}
+```
+
+#### **2. Referral Sign Up**
+
+The `source_uid` is the address of the referrer.
+
+```proto
+// GrantSignupRewardPayload is the type for signup reward grant payload.
+message GrantSignupRewardPayload {
+  // common is the common properties of a reward
+  RewardPayloadCommon common = 2 [ (gogoproto.nullable) = false ];
+}
+```
+
+### **Sample Referral Signup Grant Reward ticket**
+
+```json
+{
+ "common": {
+  "receiver": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
+  "source_uid": "{account address of the referrer}",
+  "meta": "custom grant metadata"
+ },
+ "exp": 1667863498866062000,
+ "iat": 1667827498,
+ "iss": "Oracle",
+ "sub": "GrantReward"
+}
+```
+
+#### **2. Referral**
+
+- The `source_uid` should be empty.
+- The `referee` should contain the address of referee who already claimed their signup referral reward.
+
+```proto
+// GrantSignupReferrerRewardPayload is the type for signup referrer reward grant
+// payload.
+message GrantSignupReferrerRewardPayload {
+  // common is the common properties of a reward
+  RewardPayloadCommon common = 1 [ (gogoproto.nullable) = false ];
+
+  // referee is the address of the account that used this referrer address as
+  // source_uid
+  string referee = 2;
+}
+```
+
+#### **Sample Referral Grant Reward ticket**
 
 ```json
 {
  "common": {
   "receiver": "sge1rk85ptmy3gkphlp6wyvuee3lyvz88q6x59jelc",
-  "source_uid": "source uid",
+  "source_uid": "",
   "meta": "custom grant metadata"
  },
+ "referee": "{account address of the referee who has already claimed their reward}",
  "exp": 1667863498866062000,
  "iat": 1667827498,
  "iss": "Oracle",