Added enhanements

Author: ehsan6sha

README.md

@@ -72,6 +72,19 @@ This section maps each business requirement to its implementation so the BA can
 | Deposit with sub-type breakdown | Supported | `addTokensDetailed(programId, amount, rewardType, note, subTypeIds, subTypeQtys)` — validates sub-type IDs exist and quantities sum to the deposit amount. Emits `DepositSubTypes` event. |
 | View sub-types | Supported | `getSubTypes(programId, rewardType)` returns all active sub-type IDs and names. |
 
+### Transfer Control Limit
+
+| Requirement | Status | Implementation |
+|-------------|--------|----------------|
+| Program owner specifies transfer control limit (0-100%) | Supported | `setTransferLimit(programId, limitPercent)` — admin sets a per-program percentage. Stored on-chain as `uint8`. |
+| Limit restricts Client transfers to parent | Supported | Enforced in `_transferToParentCore`. If SRP limit is 50% and client has 1200 points, max transfer is 600. To transfer 500, client must have at least 1000. |
+| Limit does NOT apply to TeamLeader or ProgramAdmin | Supported | Only `MemberRole.Client` is checked. Higher roles transfer freely. |
+| 0 = no restriction (default) | Supported | Default value is `0` (Solidity zero-init). Existing programs are unaffected — fully backward compatible. |
+| Different programs can have different limits | Supported | Per-program mapping: `mapping(uint32 => uint8) _transferLimits`. SRP at 50%, another at 25%, etc. |
+| Admin can view current limit | Supported | `getTransferLimit(programId)` returns the current percentage. Displayed on Programs detail page. |
+| UI shows transfer limit info | Supported | Programs page displays limit (e.g., "50%" or "None"). Tokens and Balance pages show info alert with max transferable amount when limit > 0. |
+| Admin can change limit | Supported | "Set Transfer Limit" button on Programs detail page (admin only) opens dialog with 0-100 input. |
+
 ### QA10 — Data Intelligence Reports
 
 | Requirement | Status | Implementation |
@@ -150,6 +163,15 @@ Members can transfer tokens back up the hierarchy to any parent in their chain.
 
 Deduction order: available balance -> expired time-locks -> unexpired time-locks -> permanently locked.
 
+#### Transfer Control Limit
+Each program can have a **Transfer Control Limit** (0-100%) that restricts how much a **Client** can transfer to their parent. The limit is calculated as a percentage of the client's **total balance** (available + permanently locked + time-locked).
+
+- **0% (default)**: No restriction — backward compatible with existing programs
+- **50%**: Client must have at least 2x the transfer amount (e.g., 1200 balance → max 600 transfer)
+- **100%**: Client can transfer their entire balance
+- Only applies to **Client** role — TeamLeaders and ProgramAdmins are not restricted
+- Set by Admin via `setTransferLimit(programId, limitPercent)`
+
 ### Withdraw
 Members withdraw available (unlocked) tokens to their wallet. Expired time-locks are automatically resolved during withdrawal.
 
@@ -183,7 +205,8 @@ Overview showing total programs count and a summary table of all programs (ID, C
 
 ### Programs (`/programs`)
 - **List view**: Table of all programs with ID, code, name, description, and status
-- **Detail view** (`/programs?id=1`): Program details, your balance breakdown, and member table with columns: Member ID, Wallet, Role, **Type**, Parent, Balance, Status, QR
+- **Detail view** (`/programs?id=1`): Program details (including **Transfer Limit**), your balance breakdown, and member table with columns: Member ID, Wallet, Role, **Type**, Parent, Balance, Status, QR
+- **Set Transfer Limit** (Admin only): Dialog to set the per-program transfer control limit (0-100%)
 - **Create Program** (Admin only): Dialog to create a new program with code, name, and description
 - **Add Program Admin** (Admin only): Assign a ProgramAdmin with wallet, member ID, and **member type**
 - **Add Member** (ProgramAdmin/TeamLeader): Add TeamLeaders or Clients with role and **member type** selection
@@ -199,7 +222,7 @@ Results show: Member ID, Wallet, Role, **Type**, Program, Parent, Balance, Statu
 Four-tab interface for token operations:
 1. **Deposit**: Approve and deposit FULA tokens with **reward type** selection and **note** field (128 chars)
 2. **Transfer to Sub-Member**: Send tokens to a sub-member with optional lock
-3. **Transfer to Parent**: Return tokens to a parent in the hierarchy
+3. **Transfer to Parent**: Return tokens to a parent in the hierarchy. Shows transfer limit info alert when the program has a limit configured.
 4. **Withdraw**: Withdraw available tokens to your wallet
 
 ### Balance Lookup (`/balance`)
@@ -209,7 +232,7 @@ Public page that does **not require wallet connection** for viewing. Enter a Mem
 - Balance breakdown (withdrawable, locked, time-locked) per program
 - Status in each program
 
-If the connected wallet matches the member's wallet, action panels appear for deposit (with **reward type** and **note**), transfer to parent, and withdraw.
+If the connected wallet matches the member's wallet, action panels appear for deposit (with **reward type** and **note**), transfer to parent (with **transfer limit** info), and withdraw.
 
 Shareable link format: `/balance?member=MEMBER_ID`
 

src/app/balance/page.tsx

@@ -11,7 +11,7 @@ import { useSearchParams } from "next/navigation";
 import { zeroAddress } from "viem";
 import { CONTRACTS, REWARDS_PROGRAM_ABI, MemberRoleLabels, MemberTypeLabels } from "@/config/contracts";
 import { toBytes12, fromBytes12, fromBytes8, shortenAddress, formatFula, formatContractError, fromBytes16 } from "@/lib/utils";
-import { useProgramCount, useProgram, useTransferToParent, useWithdraw, useApproveToken, useAddTokens, useRewardTypes } from "@/hooks/useRewardsProgram";
+import { useProgramCount, useProgram, useTransferToParent, useWithdraw, useApproveToken, useAddTokens, useRewardTypes, useTransferLimit } from "@/hooks/useRewardsProgram";
 import { OnChainDisclaimer } from "@/components/common/OnChainDisclaimer";
 import { QRCodeDisplay } from "@/components/common/QRCodeDisplay";
 import { QRScannerButton } from "@/components/common/QRScannerButton";
@@ -77,6 +77,7 @@ function OwnerActions({ memberWallet }: { memberWallet: string }) {
   const [parentTo, setParentTo] = useState("");
   const [parentAmount, setParentAmount] = useState("");
   const { transferBack, isPending: isTransBack, isConfirming: isTransBackConf, isSuccess: transBackSuccess, error: transBackError } = useTransferToParent();
+  const { data: transferLimitData } = useTransferLimit(pid);
 
   // Withdraw
   const [withdrawAmount, setWithdrawAmount] = useState("");
@@ -138,6 +139,11 @@ function OwnerActions({ memberWallet }: { memberWallet: string }) {
         {/* Transfer to Parent */}
         <Grid item xs={12} md={4}>
           <Typography variant="subtitle2" gutterBottom>Transfer to Parent</Typography>
+          {transferLimitData != null && Number(transferLimitData) > 0 && (
+            <Alert severity="info" sx={{ mb: 1 }}>
+              Transfer limit: <strong>{Number(transferLimitData)}%</strong> of total balance (Clients only).
+            </Alert>
+          )}
           <TextField label="Parent Wallet (optional)" value={parentTo} onChange={(e) => setParentTo(e.target.value)}
             fullWidth size="small" placeholder="0x... (empty = direct parent)" />
           <TextField label="Amount (FULA)" value={parentAmount} onChange={(e) => setParentAmount(e.target.value)}

src/app/programs/page.tsx

@@ -15,6 +15,7 @@ import { useUserRole, useMemberRole } from "@/hooks/useUserRole";
 import {
   useProgramCount, useProgram, useCreateProgram,
   useAssignProgramAdmin, useAddMember, useMemberBalance,
+  useTransferLimit, useSetTransferLimit,
 } from "@/hooks/useRewardsProgram";
 import { CONTRACTS, REWARDS_PROGRAM_ABI, MemberRoleLabels, MemberRoleEnum, MemberTypeLabels } from "@/config/contracts";
 import { fromBytes8, fromBytes12, shortenAddress, formatFula, isValidAddress, formatContractError } from "@/lib/utils";
@@ -99,9 +100,13 @@ function ProgramDetail({ programId }: { programId: number }) {
 
   const { assignProgramAdmin, isPending: isPendingPA, isConfirming: isConfirmingPA, isSuccess: isSuccessPA, error: errorPA } = useAssignProgramAdmin();
   const { addMember, isPending: isPendingM, isConfirming: isConfirmingM, isSuccess: isSuccessM, error: errorM } = useAddMember();
+  const { data: transferLimit } = useTransferLimit(programId);
+  const { setTransferLimit, isPending: isPendingTL, isConfirming: isConfirmingTL, isSuccess: isSuccessTL, error: errorTL } = useSetTransferLimit();
 
   const [openPA, setOpenPA] = useState(false);
   const [openMember, setOpenMember] = useState(false);
+  const [openTL, setOpenTL] = useState(false);
+  const [tlValue, setTlValue] = useState("");
   const [paWallet, setPaWallet] = useState("");
   const [paMemberId, setPaMemberId] = useState("");
   const [mWallet, setMWallet] = useState("");
@@ -144,7 +149,7 @@ function ProgramDetail({ programId }: { programId: number }) {
           <Box>
             <Typography variant="h4">{program.name}</Typography>
             <Typography color="text.secondary">
-              Code: {fromBytes8(program.code as `0x${string}`)} | ID: {program.id}
+              Code: {fromBytes8(program.code as `0x${string}`)} | ID: {program.id} | Transfer Limit: {transferLimit && Number(transferLimit) > 0 ? `${transferLimit}%` : "None"}
             </Typography>
             <Typography color="text.secondary">{program.description}</Typography>
           </Box>
@@ -155,6 +160,11 @@ function ProgramDetail({ programId }: { programId: number }) {
               Add Program Admin
             </Button>
           )}
+          {isAdmin && (
+            <Button variant="outlined" onClick={() => { setTlValue(String(transferLimit && Number(transferLimit) > 0 ? transferLimit : "")); setOpenTL(true); }}>
+              Set Transfer Limit
+            </Button>
+          )}
           {canAddMembers && (
             <Button variant="outlined" onClick={() => setOpenMember(true)}>
               Add Member
@@ -292,6 +302,29 @@ function ProgramDetail({ programId }: { programId: number }) {
           </Button>
         </DialogActions>
       </Dialog>
+
+      {/* Set Transfer Limit Dialog */}
+      <Dialog open={openTL} onClose={() => setOpenTL(false)} maxWidth="xs" fullWidth>
+        <DialogTitle>Set Transfer Limit</DialogTitle>
+        <DialogContent>
+          <Typography variant="body2" color="text.secondary" sx={{ mb: 2 }}>
+            Set the maximum percentage of balance a Client can transfer to their parent. Set to 0 for no limit.
+          </Typography>
+          <TextField label="Limit (%)" value={tlValue} onChange={(e) => setTlValue(e.target.value)}
+            fullWidth margin="normal" type="number" inputProps={{ min: 0, max: 100 }}
+            helperText="0 = no restriction, 50 = max 50% of balance" />
+          {errorTL && <Alert severity="error" sx={{ mt: 2 }}>{formatContractError(errorTL)}</Alert>}
+          {isSuccessTL && <Alert severity="success" sx={{ mt: 2 }}>Transfer limit updated!</Alert>}
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={() => setOpenTL(false)}>Cancel</Button>
+          <Button variant="contained"
+            onClick={() => setTransferLimit(programId, parseInt(tlValue) || 0)}
+            disabled={isPendingTL || isConfirmingTL}>
+            {isPendingTL || isConfirmingTL ? <CircularProgress size={20} /> : "Set Limit"}
+          </Button>
+        </DialogActions>
+      </Dialog>
     </Box>
   );
 }

src/app/tokens/page.tsx

@@ -11,7 +11,7 @@ import { readContract } from "wagmi/actions";
 import { zeroAddress } from "viem";
 import {
   useApproveToken, useAddTokens, useTransferToSubMember, useTransferToParent,
-  useWithdraw, useMemberBalance, useTokenBalance, useRewardTypes,
+  useWithdraw, useMemberBalance, useTokenBalance, useRewardTypes, useTransferLimit,
 } from "@/hooks/useRewardsProgram";
 import { formatFula, toBytes12, isValidAddress, formatContractError, fromBytes16 } from "@/lib/utils";
 import { OnChainDisclaimer } from "@/components/common/OnChainDisclaimer";
@@ -36,6 +36,9 @@ export default function TokensPage() {
   // Reward types
   const { data: rewardTypesData } = useRewardTypes();
 
+  // Transfer limit
+  const { data: transferLimitData } = useTransferLimit(pid);
+
   // Deposit state
   const [depositAmount, setDepositAmount] = useState("");
   const [depositRewardType, setDepositRewardType] = useState(0);
@@ -219,6 +222,14 @@ export default function TokensPage() {
           <Typography variant="body2" color="text.secondary" gutterBottom>
             Leave wallet empty to transfer to your direct parent.
           </Typography>
+          {transferLimitData != null && Number(transferLimitData) > 0 && (
+            <Alert severity="info" sx={{ mb: 2 }}>
+              This program limits Client transfers to <strong>{Number(transferLimitData)}%</strong> of total balance.
+              {balance && (
+                <> Your max transferable: <strong>{formatFula((balance[0] + balance[1] + balance[2]) * BigInt(Number(transferLimitData)) / BigInt(100))} FULA</strong></>
+              )}
+            </Alert>
+          )}
           <TextField label="Parent Wallet (optional)" value={parentTo} onChange={(e) => setParentTo(e.target.value)}
             fullWidth margin="normal" placeholder="0x... (leave empty for direct parent)" />
           <TextField label="Amount (FULA)" value={parentAmount} onChange={(e) => setParentAmount(e.target.value)}

src/config/contracts.ts

@@ -532,6 +532,33 @@ export const REWARDS_PROGRAM_ABI = [
       { name: "quantities", type: "uint128[]", indexed: false },
     ],
   },
+  // Transfer Control Limit
+  {
+    name: "setTransferLimit",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "programId", type: "uint32" },
+      { name: "limitPercent", type: "uint8" },
+    ],
+    outputs: [],
+  },
+  {
+    name: "getTransferLimit",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "programId", type: "uint32" }],
+    outputs: [{ type: "uint8" }],
+  },
+  {
+    name: "TransferLimitUpdated",
+    type: "event",
+    inputs: [
+      { name: "programId", type: "uint32", indexed: true },
+      { name: "oldLimit", type: "uint8", indexed: false },
+      { name: "newLimit", type: "uint8", indexed: false },
+    ],
+  },
 ] as const;
 
 // ERC20 ABI (minimal)

src/hooks/useRewardsProgram.ts

@@ -340,6 +340,33 @@ export function useAddSubType() {
   return { addSubType, isPending, isConfirming, isSuccess, error, hash };
 }
 
+export function useTransferLimit(programId: number) {
+  return useReadContract({
+    address: CONTRACTS.rewardsProgram,
+    abi: REWARDS_PROGRAM_ABI,
+    functionName: "getTransferLimit",
+    args: [programId],
+    query: { enabled: programId > 0 },
+  });
+}
+
+export function useSetTransferLimit() {
+  const { writeContract, data: hash, isPending, error } = useWriteContract();
+  const { isLoading: isConfirming, isSuccess } = useWaitForTransactionReceipt({ hash });
+  useRefetchOnSuccess(isSuccess);
+
+  const setTransferLimit = (programId: number, limitPercent: number) => {
+    writeContract({
+      address: CONTRACTS.rewardsProgram,
+      abi: REWARDS_PROGRAM_ABI,
+      functionName: "setTransferLimit",
+      args: [programId, limitPercent],
+    });
+  };
+
+  return { setTransferLimit, isPending, isConfirming, isSuccess, error, hash };
+}
+
 export function useAddTokensDetailed() {
   const { writeContract, data: hash, isPending, error } = useWriteContract();
   const { isLoading: isConfirming, isSuccess } = useWaitForTransactionReceipt({ hash });

src/lib/utils.ts

@@ -84,6 +84,8 @@ const ERROR_MAP: Record<string, string> = {
   InvalidMemberType: "Invalid member type.",
   InvalidRewardType: "Invalid reward type.",
   InvalidSubTypeData: "Invalid sub-type data.",
+  TransferExceedsLimit: "Transfer amount exceeds the program's transfer control limit.",
+  InvalidTransferLimit: "Transfer limit must be between 0 and 100.",
   InvalidAddress: "Invalid address provided.",
 };