Refactor Monad StakingLens and add tests

Simplifies StakingLens by removing unused fields, fallback APY logic, and redundant comments. Updates validator and APY query functions to use the full validator set by default. Adds unit tests for StakingLens in test/monad/StakingLens.t.sol and updates documentation and justfile for Monad lens testing.

Author: 0xh3rman

README.md

@@ -1,46 +1,27 @@
 # Smart Contracts
 
-A collection of smart contracts for Gem Wallet.
+Gem Wallet deployment helpers and read lenses.
 
-- [src/hub_reader](src/hub_reader): A contract that simplify interacting with BSC Staking Hub
-- [src/stargate](src/stargate): A contract that allow to do onchain calls on destination chain after Stargate Bridge
+- `src/hub_reader`: BSC staking hub reader.
+- `src/stargate`: post-bridge call handler for Stargate V2.
+- `src/monad`: staking lens for Monad (precompile reader).
 
 ## Development
 
-1. Install [Foundry](https://book.getfoundry.sh/) and you're good to go.
-2. Configure `.env` using `.env.example` rpcs (if needed) and etherscan values, if you need to deploy the contract, you need to set `PRIVATE_KEY` as well.
+1) Install [Foundry](https://book.getfoundry.sh/).
+2) Copy `.env.example` to `.env` and fill RPCs (including `MONAD_RPC_URL`), scan keys, and `PRIVATE_KEY` for deploys.
 
-## Usage
+## Common Tasks
 
-### Build
+- Build: `forge build`
+- Lint/format: `forge lint && forge fmt`
+- Test: `forge test` (HubReader tests expect a live BSC RPC; the Monad lens tests are mocked)
 
-```shell
-forge build
-```
-
-### Test
-
-```shell
-forge test --rpc-url <your_rpc_url>
-```
-
-### Deploy
-
-```shell
-# deploy hub_reader
-just deploy-hub-reader
-```
-
-```shell
-# deploy stargate to all supported chains
-just deploy-stargate
-```
-
-```shell
-# deploy stargate to specific chain
-just deploy-stargate optimism
-```
+## Deploy
 
+- Hub Reader (BSC): `just deploy-hub-reader`
+- Stargate fee receiver: `just deploy-stargate optimism` (or another supported chain)
+- Monad staking lens: `just deploy-monad-staking`
 
 
 

justfile

@@ -9,6 +9,9 @@ build:
 test:
     forge test
 
+test-monad:
+    forge test --match-path test/monad/*
+
 deploy-stargate CHAIN_NAME:
     bash ./deploy/deploy-stargate.sh {{CHAIN_NAME}}
 

src/monad/StakingLens.sol

@@ -19,7 +19,7 @@ contract StakingLens {
     uint256 public constant MONAD_BLOCKS_PER_YEAR = 78_840_000;
     uint64 public constant APY_BPS_PRECISION = 10_000;
     uint64 public constant MONAD_BOUNDARY_BLOCK_PERIOD = 50_000;
-    uint64 public constant MONAD_EPOCH_SECONDS = MONAD_BOUNDARY_BLOCK_PERIOD * 2 / 5; // 0.4s block time
+    uint64 public constant MONAD_EPOCH_SECONDS = MONAD_BOUNDARY_BLOCK_PERIOD * 2 / 5; // 0.4s blocks
 
     enum DelegationState {
         Active,
@@ -33,8 +33,8 @@ contract StakingLens {
         uint8 withdrawId;
         DelegationState state;
         uint256 amount;
-        uint256 rewards; // unclaimed rewards only for Active entries
-        uint64 withdrawEpoch; // populated for withdrawals
+        uint256 rewards;
+        uint64 withdrawEpoch;
         uint64 completionTimestamp;
     }
 
@@ -46,7 +46,6 @@ contract StakingLens {
 
     struct ValidatorInfo {
         uint64 validatorId;
-        string name;
         uint256 stake;
         uint256 commission;
         uint64 apyBps;
@@ -60,10 +59,6 @@ contract StakingLens {
         uint256 commission;
     }
 
-    /**
-     * @notice Sum staked, pending, and reward balances for a delegator.
-     * @dev Same data the Rust provider assembles for staking_monad::get_monad_staking_balance.
-     */
     function getBalance(address delegator) external returns (uint256 staked, uint256 pending, uint256 rewards) {
         bool isDone;
         uint64 nextValId;
@@ -91,12 +86,6 @@ contract StakingLens {
         }
     }
 
-    /**
-     * @notice Get all delegation positions for a delegator, including withdrawals.
-     * @dev Emits one entry per state (active, activating, withdrawal requests).
-     *      Uses withdrawId as the tie-breaker so clients can build delegation_ids
-     *      compatible with the Rust client (address:withdrawId).
-     */
     function getDelegations(address delegator) external returns (DelegationPosition[] memory positions) {
         positions = new DelegationPosition[](MAX_POSITIONS);
         uint256 positionCount = 0;
@@ -233,10 +222,9 @@ contract StakingLens {
 
     /**
      * @notice Return validator stats plus APY for a set of validator ids.
-     * @param validatorIds If empty, uses the curated Monad validator list.
-     * @param fallbackApyBps Optional fallback APY (basis points) if the network or validator math returns zero.
+     * @param validatorIds If empty, uses the full Monad validator set.
      */
-    function getValidators(uint64[] calldata validatorIds, uint64 fallbackApyBps)
+    function getValidators(uint64[] calldata validatorIds)
         external
         returns (ValidatorInfo[] memory validators, uint64 networkApyBps)
     {
@@ -254,13 +242,9 @@ contract StakingLens {
             }
 
             uint64 validatorApy = _validatorApyBps(snapshot.stake, totalStake, snapshot.commission, networkApyBps);
-            if (validatorApy == 0) {
-                validatorApy = fallbackApyBps;
-            }
 
             validators[i] = ValidatorInfo({
                 validatorId: snapshot.validatorId,
-                name: uint256(snapshot.validatorId).toString(),
                 stake: snapshot.stake,
                 commission: snapshot.commission,
                 apyBps: validatorApy,
@@ -270,12 +254,10 @@ contract StakingLens {
     }
 
     /**
-     * @notice Return APYs for a set of validator ids, mirroring HubReader.getAPYs style.
-     * @param validatorIds If empty, uses the curated Monad validator list.
-     * @param fallbackApyBps Optional fallback APY (basis points) if the network or validator math returns zero.
+     * @notice Return APYs for a set of validator ids. Defaults to the full validator set when empty.
      */
     // forge-lint: disable-next-line(mixed-case-function)
-    function getAPYs(uint64[] calldata validatorIds, uint64 fallbackApyBps) external returns (uint64[] memory apysBps) {
+    function getAPYs(uint64[] calldata validatorIds) external returns (uint64[] memory apysBps) {
         uint64[] memory allValidatorIds = _allValidatorIds();
         uint64[] memory targetIds = validatorIds.length == 0 ? allValidatorIds : validatorIds;
 
@@ -286,12 +268,11 @@ contract StakingLens {
         for (uint256 i = 0; i < targetIds.length; ++i) {
             (ValidatorData memory snapshot, bool found) = _findValidator(data, targetIds[i]);
             if (!found) {
-                apysBps[i] = fallbackApyBps;
                 continue;
             }
 
             uint64 validatorApy = _validatorApyBps(snapshot.stake, totalStake, snapshot.commission, networkApyBps);
-            apysBps[i] = validatorApy > 0 ? validatorApy : fallbackApyBps;
+            apysBps[i] = validatorApy;
         }
     }
 

test/monad/StakingLens.t.sol

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.15;
+
+import {Test} from "forge-std/Test.sol";
+import {StakingLens} from "../../src/monad/StakingLens.sol";
+import {IStaking} from "../../src/monad/IStaking.sol";
+
+contract StakingLensTest is Test {
+    StakingLens private lens;
+    address private constant STAKING_PRECOMPILE = address(0x0000000000000000000000000000000000001000);
+
+    uint64[] private validatorIds;
+    uint256 private constant TOTAL_STAKE = 1e30;
+    uint256 private constant VALIDATOR_STAKE = TOTAL_STAKE / 2;
+
+    function setUp() public {
+        lens = new StakingLens();
+
+        validatorIds = new uint64[](2);
+        validatorIds[0] = 1;
+        validatorIds[1] = 2;
+
+        _mockConsensusSet();
+        _mockValidator(validatorIds[0], VALIDATOR_STAKE, 0);
+        _mockValidator(validatorIds[1], VALIDATOR_STAKE, 0);
+    }
+
+    function test_getAPYsUsesAllValidatorsWhenEmpty() public {
+        uint64[] memory apys = lens.getAPYs(new uint64[](0));
+
+        uint64 expected = _expectedNetworkApy();
+        assertEq(apys.length, validatorIds.length);
+        assertEq(apys[0], expected);
+        assertEq(apys[1], expected);
+    }
+
+    function test_getValidatorsReturnsNetworkApy() public {
+        (StakingLens.ValidatorInfo[] memory validators, uint64 networkApy) = lens.getValidators(new uint64[](0));
+
+        uint64 expected = _expectedNetworkApy();
+        assertEq(networkApy, expected);
+        assertEq(validators.length, validatorIds.length);
+        assertEq(validators[0].validatorId, validatorIds[0]);
+        assertEq(validators[0].apyBps, expected);
+        assertEq(validators[1].validatorId, validatorIds[1]);
+        assertEq(validators[1].apyBps, expected);
+    }
+
+    function _mockConsensusSet() internal {
+        bytes memory data = abi.encodeCall(IStaking.getConsensusValidatorSet, (0));
+        bytes memory result = abi.encode(true, uint32(0), validatorIds);
+        vm.mockCall(STAKING_PRECOMPILE, data, result);
+    }
+
+    function _mockValidator(uint64 validatorId, uint256 stake, uint256 commission) internal {
+        bytes memory data = abi.encodeCall(IStaking.getValidator, (validatorId));
+        bytes memory result = abi.encode(
+            address(0),
+            uint64(0),
+            stake,
+            uint256(0),
+            commission,
+            uint256(0),
+            uint256(0),
+            uint256(0),
+            uint256(0),
+            uint256(0),
+            bytes(""),
+            bytes("")
+        );
+        vm.mockCall(STAKING_PRECOMPILE, data, result);
+    }
+
+    function _expectedNetworkApy() internal view returns (uint64) {
+        uint256 annualRewards = lens.MONAD_BLOCK_REWARD() * lens.MONAD_BLOCKS_PER_YEAR();
+        uint256 apy = (annualRewards * lens.APY_BPS_PRECISION()) / TOTAL_STAKE;
+        // casting to uint64 is safe because APY basis points are intentionally capped within uint64 range
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return uint64(apy);
+    }
+}