doc(pallet-dao): create council/farmers proposal (#859)

substrate-node/pallets/pallet-dao/creating_motion_council.md

@@ -0,0 +1,108 @@
+# Creating a motion for council members to vote on
+
+Such council motion is ruled by [pallet Collective](https://paritytech.github.io/substrate/master/pallet_collective/index.html).
+Only a council member can propose a motion for council members to vote on.
+
+## Step 1: Go to Polkadot UI
+
+Open the Polkadot JS UI in your browser:
+
+*   devnet:   https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.dev.grid.tf#/explorer
+*   qanet:    https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.qa.grid.tf#/explorer
+*   testnet:  https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.test.grid.tf#/explorer
+*   mainnet:  https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.grid.tf#/explorer
+
+## Step 2: Propose a council motion
+
+*   Make sure the council member account is registered on the Polkadot browser extension
+*   Go to `Motions` ->  `Propose motion`
+*   Make sure the council member account is selected
+
+## Step 3: Fill motion
+
+The motion must include the following arguments:
+
+*   `threshold`: number of votes that determine if the motion can be approved (`nb Yes votes >= threshold`) or disapproved (`nb No votes > nb of council members - threshold`). Make sure to set it greater or equal to `3/5` in proportion of total number of council members (see [approval](#approval) section).
+*   `proposal`: call/extrinsic to execute on chain. See complete list of extrinsics eligible to be executed by a council approval above. Also, all arguments of selected extrinsic must be filled.
+
+![fill](./img/fill_motion_council.png)
+
+## Step 4: Propose motion
+
+Make sure you have enought funds for transaction fee, click on `Propose` and submit the transaction.
+If succeeded you should be able to see the motion in `Propose` section with its corresponding index and details.
+
+! Remark: Once a motion is created it cannot be altered or removed !
+
+![list](./img/list_motion_council.png)
+
+## Step 5: Vote for motion
+
+Once the motion started a council member can vote for it by clicking on `Vote`, selecting `Vote Nay` or `Vote Aye` and `Sign and Submit` the transaction.
+
+![vote](./img/vote_motion_council.png)
+
+## Step 6: Close motion
+
+After the motion ends (duration is 2 hours) or, before it, if a `threshold` approval or disapproval condition is reached, it can be manually closed by a council member by clicking on `Close`.
+
+## Approval
+
+Once the motion is closed it is removed from list and the `proposal` extrinsic is executed on chain in case of approval.
+
+! Remark: When the extrinsic is executed there is no guaranty of success. Indeed, all extrinsics callable by a council approval (see list below) require a number of `Yes` votes which is greater or equal to `3/5` in proportion of total number of council members. A `BadOrigin` error message will be received if this condition is not reached !
+
+## List of extrincics requiring a council approval
+
+### tfgridModule
+
+*   `setStorageVersion()` (sets a storage version on pallet)
+*   `setFarmCertification()` (sets a certification type on a farm)
+*   `setNodeCertification()` (sets a certification type on a node)
+*   `createPricingPolicy()` (create a pricing policy)
+*   `updatePricingPolicy()` (update a pricing policy by id)
+*   `createFarmingPolicy()` (create a farming policy)
+*   `setFarmDedicated()` (mark a farm as dedicated, this enabled dedicated nodes on that farm)
+*   `forceResetFarmIp()` (resets a farm IP's contract id in case of an issue)
+*   `setConnectionPrice()` (price defined in musd, 0.08 -> 800)
+*   `addNodeCertifier()` (an account to be allowed to certify nodes)
+*   `removeNodeCertifier()` (an account to be removed as node certifier)
+*   `updateFarmingPolicy()` (update a farming policy by id)
+*   `attachPolicyToFarm()` (attaches a farming policy limit to a specific farm)
+*   `setZosVersion()` (sets ZOS version)
+
+### smartContractModule
+
+*   `approveSolutionProvider()` (approves a solution provider)
+*   `changeBillingFrequency()` (changes the billing frequency)
+
+### tftBridgeModule
+
+*   `addBridgeValidator()`
+*   `removeBridgeValidator()`
+*   `setFeeAccount()`
+*   `setWithdrawFee()`
+*   `setDepositFee()`
+
+### tftPriceModule
+
+*   `setMinTftPrice()` (sets lower bound for on chain TFT price)
+*   `setMaxTftPrice()` (sets upper bound for on chain TFT price)
+
+### validator
+
+*   `approveValidator()` (approves a validator request)
+*   `removeValidator()` (removes a validator)
+
+### councilMembership
+
+*   `addMember()` (adds a new council member)
+*   `removeMember()` (removes a council member)
+*   `swapMember()`
+*   `resetMembers()`
+*   `setPrime()`
+*   `clearPrime()`
+
+### runtimeUpgrade
+
+*   `runtimeUpgrade.setCode()` (new runtime wasm)

substrate-node/pallets/pallet-dao/creating_proposal_farmers.md

@@ -0,0 +1,109 @@
+# Creating a proposal for farmers to vote on
+
+Only a council member can create a proposal for farmers to vote on.
+
+## Step 1: Go to Polkadot UI
+
+Open the Polkadot JS UI in your browser:
+
+*   devnet:  https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.dev.grid.tf%2Fws#/explorer
+*   qanet:   https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.qa.grid.tf%2Fws#/explorer
+*   testnet: https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.test.grid.tf%2Fws#/explorer
+*   mainnet: https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftfchain.grid.tf%2Fws#/explorer
+
+## Step 2: Open proposal
+
+*   Go to `Developer` -> `Extrinsics`
+*   Make sure the council member account is selected
+*   Select `dao` -> `propose()` extrinsic
+
+## Step 3: Fill proposal
+
+The proposal must include the following arguments:
+
+*   `threshold`: minimal number of farmer votes required to be able to close proposal before its end.
+*   `action`: call/extrinsic to execute on chain. If there is no call to be executed (which is usually the case) then `system` -> `remark()` should be set.
+*   `description`: a small description of what the proposal is about.
+*   `link`: a link to a more elaborate explanation of the proposal.
+*   `duration`: optional duration of the proposal after beeing created (default is 7 days, max value is 30 days), expressed in number of blocks (1 block = 6 sec).
+
+![fill](./img/fill_proposal_farmers.png)
+
+## Step 4: Submit proposal
+
+Make sure you have enought funds for transaction fee and submit the proposal.
+If succeeded you should be able to [track the proposal](#check-proposal).
+
+! Remark: Once a proposal is created it cannot be altered or removed !
+
+![submit](./img/submit_proposal_farmers.png)
+
+## Step 5: Closing proposal
+
+After the proposal ends or, before it, if number of votes reached `threshold`, it can be manually closed by a council member.
+
+*   Go to `Developer` -> `Extrinsics`
+*   Make sure the council member account is selected
+*   Select `dao` -> `close()` extrinsic
+*   Fill `proposalHash` and `proposalIndex` (can be found in [list of active proposals](#check-proposal)) and submit transaction
+
+![close](./img/close_proposal_farmers.png)
+
+## Approval
+
+Once closed the proposal is removed from list and the action, if any, is executed on chain in case of approval.
+Since each farmer vote is weighted by the corresponding farm capacity (`weight = 2 * (sum of CU of all nodes) + (sum of SU of all nodes)`), approval is obtained when `Yes` votes quantity is strictly greater than `No` votes quantity.
+
+## Check proposal
+
+You can check if proposal was created.
+
+*   Go to `Developer` -> `Chain state` -> `dao` -> `proposalList()` to get the hash list of active proposals
+
+![list](./img/list_proposal_farmers.png)
+
+*   With the given hash, go to  `Developer` -> `Chain state` -> `dao` -> `proposals()` to see proposal index/description/link
+
+![index](./img/index_proposal_farmers.png)
+
+*   With the given hash, go to  `Developer` -> `Chain state` -> `dao` -> `proposalOf()` to see proposal action
+
+![action](./img/action_proposal_farmers.png)
+
+*   With the given hash, go to  `Developer` -> `Chain state` -> `dao` -> `voting()` to see ongoing voting status
+
+![voting](./img/voting_proposal_farmers.png)
+
+## Farmer voting
+
+Once proposal is created farmers can vote for it.
+
+*   Go to `Developer` -> `Extrinsics`
+*   Make sure the farmer account is selected.
+*   Select `dao` -> `vote()` extrinsic
+
+The vote must include the following arguments:
+
+*   `farmId`: the farm id of the farmer
+*   `proposalHash`: the hash of the proposal (can be found in [list of active proposals](#check-proposal))
+*   `approve`: `Yes` or `No` the farmer approves the proposal
+
+![vote](./img/vote_proposal_farmers.png)
+
+Further considerations:
+
+*   Vote is per farm so in case farmer owns other farms he could repeat the process for all of them.
+*   Vote can be changed at any moment until the proposal is closed.
+*   Farmer can also vote via TF Dashboard in DAO section.
+
+## Council member veto
+
+At any moment of the proposal, a council member can veto it.
+3 council vetos will result in disapproving the proposal.
+
+*   Go to `Developer` -> `Extrinsics`
+*   Make sure the council member account is selected
+*   Select `dao` -> `veto()` extrinsic
+*   Fill `proposalHash` (can be found in [list of active proposals](#check-proposal)) and submit transaction
+
+![veto](./img/veto_proposal_farmers.png)