capped delegation to lessen surround voting probabilty - initial commit

README.md

@@ -222,3 +222,212 @@ You can verify transactions on both chains:
    ```bash
    torramd query tx 9308B24B2E78CB643493534CB164A9064D67F5DE2E83AFB9C8C78CF58D104B98 --output json | jq
    ```
+
+---
+
+## New vStaking Module
+
+New vstaking module will provide prevention of surround voting through max capping.
+
+This commit is a preventive measure to stop surround voting. Surround voting comes into picture when certain validators start
+getting favoured by delegators and hence can remain in active set and hence can affect chain. The commit introduces a max capping
+on each validator. This max capping will be a percentage of total bonded tokens at a particular instant.
+
+While delegating tokens to validators, if delegate amount will make ther current stake more than capped amount, delegation will not
+be successful. This will in turn, encourage delegators to delegate their tokens to other validators and preference of particular
+validators will be avoided.
+
+The capping percentage has default value of 10% when nothing is set explicitly.There are 2 ways to set it explicitly i.e.
+governance proposal and config.yml
+
+Basic logic:
+
+current stake of validator < max cap % total bonded tokens
+
+## Steps to test:
+
+**1] Download the code**
+
+    https://github.com/TorramLabs-Team/TorramChain.git
+
+    checkout to staking-slashing
+
+**2] Create binary**
+
+    make install
+
+**3] Run chain**
+
+    make init
+
+    torramd start --minimum-gas-prices 0.01torram
+
+**4] Functionality checking**
+
+    **Note**:- a) this testing is for single validator setup which is enabled partially by code, see comments
+
+               b) one needs to keep an eye on total bonded tokens and current stake to know when validator stake
+                  will reach beyon max value
+
+***Total bonded tokens***
+
+This will give the total bonded tokens, we will need this if we want to confirm the process
+
+Note: logs are available in the the chain logs with all the amounts so one can check that through below:
+
+      script -q -c "/home/si/go/bin/torramd start --minimum-gas-prices 0.01torram" /dev/stdout | sed -r 's/\x1B\[[0-9;]*[mK]//g' > /tmp/logs/torram_logs.txt
+
+      Above will record logs at /tmp/logs/torram_logs.txt
+
+```bash
+si@sid:~$ torramd q staking pool
+pool:
+  bonded_tokens: "1000000"
+  not_bonded_tokens: "0"
+si@sid:~$
+```
+
+***Validator details***
+
+This will give the validator address and stake
+
+```bash
+si@sid:~$ torramd q staking validators
+pagination:
+  total: "1"
+validators:
+- commission:
+    commission_rates:
+      max_change_rate: "10000000000000000"
+      max_rate: "200000000000000000"
+      rate: "100000000000000000"
+    update_time: "2025-03-12T05:29:57.942038614Z"
+  consensus_pubkey:
+    type: /cosmos.crypto.ed25519.PubKey
+    value: 1w2dIiSpYBzZuDgIvD9+FOciBNiYOw8e9fGQkWsOgBk=
+  delegator_shares: "1000000000000000000000000"
+  description:
+    moniker: test
+  min_self_delegation: "1"
+  operator_address: cosmosvaloper109y2nqs5ky78692accp8excva5ymmd9p8924pl
+  status: BOND_STATUS_BONDED
+  tokens: "1000000"
+  unbonding_time: "1970-01-01T00:00:00Z"
+si@sid:~$
+```
+
+***Delegation details***
+
+This will give delegation details to the concerned validator
+
+Note: Copy validator address from previous step
+
+```bash
+si@sid:~$ torramd q staking delegations-to cosmosvaloper109y2nqs5ky78692accp8excva5ymmd9p8924pl
+delegation_responses:
+- balance:
+    amount: "1000000"
+    denom: torram
+  delegation:
+    delegator_address: cosmos109y2nqs5ky78692accp8excva5ymmd9pz37qdv
+    shares: "1000000000000000000000000"
+    validator_address: cosmosvaloper109y2nqs5ky78692accp8excva5ymmd9p8924pl
+pagination:
+  total: "1"
+si@sid:~$ 
+si@sid:~$
+```
+
+***Create a delegator account***
+
+For delegations to validators
+
+Note: Copy validator address from previous step
+
+```bash
+si@sid:~$ torramd keys add torram-node-delegator --keyring-backend test
+
+- address: cosmos1q38ytm29p7jzcjm4wmaq7lvqy0da487mzyayvh
+  name: torram-node-delegator
+  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AmeiqTIXoCTOvQN0jvVN+qt30jtYppjPkIRI1WU6kLEV"}'
+  type: local
+
+
+**Important** write this mnemonic phrase in a safe place.
+It is the only way to recover your account if you ever forget your password.
+
+cube simple stairs host elder turtle path mercy room biology then uniform park follow shallow lumber lazy between grit extend immense possible enjoy paddle
+si@sid:~$
+```
+
+***Fund delegator***
+
+Note: Copy address from previous step
+
+```bash
+si@sid:~$ torramd tx bank send torram-node cosmos1q38ytm29p7jzcjm4wmaq7lvqy0da487mzyayvh 1000000torram --keyring-backend test --chain-id torram --from torram-node --gas-prices 1torram
+```
+
+***Check balance***
+
+```bash
+si@sid:~$ torramd query bank balances cosmos1q38ytm29p7jzcjm4wmaq7lvqy0da487mzyayvh
+balances:
+- amount: "1000000"
+  denom: torram
+pagination:
+  total: "1"
+si@sid:~$ 
+```
+
+***Delegate and check if delegation gets cancelled***
+
+Delegate tokens to validator and check if delegation gets cancelled once delegation amt amt makes stake above max stake
+
+Note: Since this is a single validator setup, there is provision in code to give offset to max cap so that testing can be done
+
+      With 1000000 total bonded tokens, 1000000 current stake of validator, 10% max cap, delegation will after 1000 tokens(approx)
+
+      For reference, see the query commands in starting and keep losgs open in another terminal
+
+```bash
+si@sid:~$ torramd tx staking delegate cosmosvaloper109y2nqs5ky78692accp8excva5ymmd9p8924pl 500torram --from torram-node-delegator --keyring-backend test --chain-id torram --gas-prices 1torram
+
+si@sid:~$ torramd tx staking delegate cosmosvaloper109y2nqs5ky78692accp8excva5ymmd9p8924pl 450torram --from torram-node-delegator --keyring-backend test --chain-id torram --gas-prices 1torram
+
+si@sid:~$ torramd tx staking delegate cosmosvaloper109y2nqs5ky78692accp8excva5ymmd9p8924pl 200torram --from torram-node-delegator --keyring-backend test --chain-id torram --gas-prices 1torram
+```
+
+Delegation should start failing from 3rd command above onwards because we have passed 1000 token mark
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+