Merge pull request #217 from terra-money/feat/feeshare-spec

docs(v2.8): feeshare module specs

x/feeshare/README.md

@@ -3,9 +3,9 @@
 This module is a heavily modified fork of [evmos/x/revenue](https://github.com/evmos/evmos/tree/main/x/revenue).
 A big thanks go to the original authors.
 
-[FeeShare Spec](spec/README.md)
+For information on the module, read the [FeeShare Spec](spec/README.md). 
 
----
+## Guides
 
-> [Register a Contract](spec/00_register.md)
-> [Update Conrtact Withdraw Address](spec/00_update.md)
+- [Register a Contract](spec/00_register.md)
+- [Update Contract Withdraw Address](spec/00_register.md#update-a-contracts-withdrawal-address)

x/feeshare/post/post.go

@@ -25,10 +25,10 @@ func NewFeeSharePayoutDecorator(fs FeeShareKeeper, bk BankKeeper, wk customwasmk
 	}
 }
 
-// FeeSharePostHandler if the feeshare module is neabled
+// FeeSharePostHandler if the feeshare module is enabled
 // takes the total fees paid for each transaction and
-// split these fees equaly between all the contacts
-// involved in the transactin based on the module params.
+// split these fees equally between all the contacts
+// involved in the transaction based on the module params.
 func (fsd FeeSharePayoutDecorator) PostHandle(
 	ctx sdk.Context,
 	tx sdk.Tx,
@@ -61,7 +61,7 @@ func (fsd FeeSharePayoutDecorator) PostHandle(
 }
 
 // FeeSharePayout takes the total fees paid for a transaction and
-// split these fees equaly between all the contacts involved in the
+// split these fees equally between all the contacts involved in the
 // transaction based on the module params.
 func (fsd FeeSharePayoutDecorator) FeeSharePayout(ctx sdk.Context, txFees sdk.Coins, devShares sdk.Dec, allowedDenoms []string) (err error) {
 	executedContracts, found := fsd.wasmKeeper.GetExecutedContractAddresses(ctx)

x/feeshare/spec/00_register.md

@@ -1,6 +1,10 @@
 # Register a contract
 
-`junod tx feeshare register [contract_bech32] [withdraw_bech32] --from [key]`
+Use this guide to register your contract. For a more in-depth guide on registering, visit the [Terra Docs feeshare tutorial](https://docs.terra.money/develop/guides/register-feeshare)
+
+## Using terrad
+
+`terrad tx feeshare register [contract_bech32] [withdraw_bech32] --from [key]`
 
 Registers the withdrawal address for the given contract.
 
@@ -24,8 +28,14 @@ This command can only be run by the admin of the contract. If there is no admin,
 withdraw_bech32 can not be the community pool (distribution) address. This is a limitation of the way the SDK handles this module account
 ```
 
-```text
-For contracts created or administered by a contract factory, the withdrawal address can only be the same as the contract address. This can be registered by anyone, but it's unchangeable. This is helpful for SubDAOs or public goods to save fees in the treasury.
+# Update a Contract's Withdrawal Address
+
+This can be changed at any time, as long as the sender still the admin or creator of the contract:
 
-If you create a contract like this, it's best to create an execution method for withdrawing fees to an account. To do this, you'll need to save the withdrawal address in the contract's state before uploading a non-migratable contract.
+`terrad tx feeshare update [contract] [new_withdraw_address]`
+
+## Update Exception
+
+```text
+This can not be done if the contract was created from or is administered by another contract (a contract factory). There is not currently a way for a contract to change its own withdrawal address directly.
 ```

x/feeshare/spec/01_concepts.md

@@ -6,22 +6,37 @@ order: 1
 
 ## FeeShare
 
-The FeeShare module is a revenue-per-transaction model, which allows developers to get paid for deploying their decentralized applications (dApps) on Juno. This helps developers to generate revenue every time a user interacts with their contracts on the chain. This registration is permissionless to sign up for and begin earning fees from. By default, 50% of all transaction fees for Execute Messages are shared. This can be changed by governance and implemented by the `x/feeshare` module.
+The FeeShare module enables the splitting of revenue from transaction fees between validators and registered smart contracts. Developers can register their smart contracts and every time someone interacts with a registered smart contract, the contract deployer or their assigned withdrawal account receives a part of the transaction fees. By default, 50% of all transaction fees for Execute Messages are shared. This parameter can be changed by governance and implemented by the `x/feeshare` module.
 
 ## Registration
 
-Developers register their contract applications to gain their cut of fees per execution. Any contract can be registered by a developer by submitting a signed transaction. After the transaction is executed successfully, the developer will start receiving a portion of the transaction fees paid when a user interacts with the registered contract. The developer can have the funds sent to their wallet, a DAO, or any other wallet address on the Juno Network.
+Contracts must register to receive their allocation of fees. Registration is permissionless, and is completed by submitting a signed registration transaction. After the transaction is executed successfully, the withdrawal address stipulated  during registration will start receiving a portion of the transaction fees paid when a user interacts with the registered contract. A withdrawal address can be any address. 
 
 ::: tip
- **NOTE**: If your contract is part of a development project, please ensure that the deployer of the contract (or the factory/DAO that deployed the contract) is an account that is owned by that project. This avoids the situation, that an individual deployer who leaves your project could become malicious.
+ **NOTE**: If your contract is part of a development project, please ensure that the deployer of the contract is an account that is owned by that project and not just an individual contributor, who could become malicious. 
 :::
 
-## Fee Distribution
+## Fees
+
+Registered contracts will earn a portion of the transaction fee after registering their contracts. Only [Wasm Execute Txs](https://github.com/CosmWasm/wasmd/blob/main/proto/cosmwasm/wasm/v1/tx.proto#L115-L127) (`MsgExecuteContract`) are eligible for feesharing.
+
+Users pay transaction fees to pay to interact with smart contracts and execute transactions. When a transaction is executed, the entire fee amount (`gas limit * gas price`) is sent to the `FeeCollector` module account during the [Cosmos SDK AnteHandler](https://docs.cosmos.network/main/modules/auth/#antehandlers) execution.
+
+If a transaction's fees are not denominated in a coin permitted by the `AllowedDenoms` parameter, there is no payout to involved contracts.  If a user sends a message and it does not interact with any contracts (ex: bankSend), then the entire fee is sent to the `FeeCollector` as expected.
+
+### Fee distribution
+
+
+After collecting fees, the `FeeCollector` sends 50% of the total collected transaction fees divided equally among the withdrawal addresses of any contract involved in the transaction. 
+
+The original FeeShare module implementation only rewarded registered contracts that took part in the execution of a transaction. However, this approach has been modified to reward *any* registered contract that participates in a transaction. 
+
+All registered contracts involved in a transaction will receive an equal portion of the FeeShare allocation (currently set to 50%). For example, if a transaction involves the participation of 5 contracts, and 3 of them are registered, each registered contract will receive 1/3 of the 50% FeeShare allocation to their withdrawer addresses. 
+
+This equitable distribution is achieved by wrapping the official WASM module in a [custom implementation](../../wasm/README.md) that keeps track of all contracts involved in a transaction. When a contract is executed, the custom WASM module keeps track of each participating contract address in a list. When the transaction is completed, the `PostHandler` from the FeeShare module distributes the rewards between the listed participants, and the `PostHandler` from the custom WASM module removes the contract addresses from the store.
+
+
 
-As described above, developers will earn a portion of the transaction fee after registering their contracts. To understand how transaction fees are distributed, we will look at the following in detail:
 
-* The transactions eligible are only [Wasm Execute Txs](https://github.com/CosmWasm/wasmd/blob/main/proto/cosmwasm/wasm/v1/tx.proto#L115-L127) (`MsgExecuteContract`).
 
-### WASM Transaction Fees
 
-Users pay transaction fees to pay to interact with smart contracts on Juno. When a transaction is executed, the entire fee amount (`gas limit * gas price`) is sent to the `FeeCollector` module account during the [Cosmos SDK AnteHandler](https://docs.cosmos.network/main/modules/auth/#antehandlers) execution. After this step, the `FeeCollector` sends 50% of the funds and splits them between contracts that were executed on the transaction. If the fees paid are not accepted by governance, there is no payout to the developers (for example, niche base tokens) for tax purposes. If a user sends a message and it does not interact with any contracts (ex: bankSend), then the entire fee is sent to the `FeeCollector` as expected.

x/feeshare/spec/05_post.md

@@ -0,0 +1,33 @@
+<!--
+order: 5
+-->
+
+# Post
+
+The FeeShare module uses the post handler to distribute fees between developers and the community.
+
+## FeeShare 
+
+The [Post Decorator](/x/feeshare/post/post.go) executes custom logic after each successful WasmExecuteMsg transaction. All fees paid by a user for transaction execution are sent to the `FeeShare` module account before being redistributed to the registered contracts.
+
+If the `x/feeshare` module is disabled or the Wasm Execute Msg transaction targets an unregistered contract, the handler returns `nil`, without performing any actions. In this case, 100% of the transaction fees remain in the `FeeCollector` module, to be distributed elsewhere.
+
+If the `x/feeshare` module is enabled and a Wasm Execute Msg transaction targets a registered contract, the handler sends a percentage of the transaction fees (paid by the user) to the withdraw address set for that contract, or splits the fee equally among any contract involved in the transaction.
+
+1. The user submits an Execute transaction (`MsgExecuteContract`) to a smart contract and the transaction is executed successfully
+2. Check if
+   * fees module is enabled
+   * the smart contract is registered to receive fee split
+
+3. Calculate developer fees according to the `DeveloperShares` parameter.
+4. Check which denominations governance allows fees to be paid in.
+5. Check which contracts the user executed that also have been registered.
+6. Calculate the total amount of fees to be paid to the developer(s). If multiple contracts are involved in a transaction, the 50% reward is split evenly between all registered withdrawal addresses.
+7. Distribute the remaining amount in the `FeeCollector` to validators according to the [SDK  Distribution Scheme](https://docs.cosmos.network/main/modules/distribution/03_begin_block.html#the-distribution-scheme).
+
+
+## Custom Wasm
+
+In order to distribute an equal share of fees to all contrcts involved in a transaction, a [custom Wasm module](../../wasm/README.md) was developed. 
+
+The custom Wasm module keeps track of all contracts involved in a transaction. When a contract is executed, the custom Wasm module keeps track of each participating contract address in a list. When the transaction is completed, the `PostHandler` from the FeeShare module distributes the rewards between the listed participants, and the `PostHandler` from the custom Wasm module removes the contract addresses from the store.

x/feeshare/spec/08_clients.md

@@ -6,10 +6,10 @@ order: 8
 
 ## Command Line Interface
 
-Find below a list of `junod` commands added with the  `x/feeshare` module. You can obtain the full list by using the `junod -h` command. A CLI command can look like this:
+Find below a list of `terrad` commands added with the  `x/feeshare` module. You can obtain the full list by using the `terrad -h` command. A CLI command can look like this:
 
 ```bash
-junod query feeshare params
+terrad query feeshare params
 ```
 
 ### Queries

x/feeshare/spec/README.md

@@ -9,17 +9,19 @@ parent:
 
 ## Abstract
 
-This document specifies the internal `x/feeshare` module of Juno Network.
+This document specifies the internal `x/feeshare` module, which was originally developed by the Juno Network. This documentation is a fork of the [original documentation](https://github.com/CosmosContracts/juno/tree/main/x/feeshare/spec). 
 
-The `x/feeshare` module enables the Juno to support splitting transaction fees between the community and smart contract deployer. This aims to increase the adoption of Juno by offering a new way of income for CosmWasm smart contract developers. Developers can register their smart contracts and every time someone interacts with a registered smart contract, the contract deployer or their assigned withdrawal account receives a part of the transaction fees.
+This custom implementation of the `x/feeshare` module enables the splitting of revenue from transaction fees between validators and registered smart contracts. Developers can register their smart contracts and every time someone interacts with a registered smart contract, the contract deployer or their assigned withdrawal account receives a part of the transaction fees. If multiple contracts are involved in a transaction, the FeeShare revenue is split evenly between all registered contracts that participated in the transaction. 
 
 ## Contents
 
 1. **[Concepts](01_concepts.md)**
 2. **[State](02_state.md)**
 3. **[State Transitions](03_state_transitions.md)**
 4. **[Transactions](04_transactions.md)**
-5. **[Hooks](05_hooks.md)**
+5. **[Post](05_post.md)**
 6. **[Events](06_events.md)**
 7. **[Parameters](07_parameters.md)**
 8. **[Clients](08_clients.md)**
+
+

x/wasm/README.md

@@ -0,0 +1,7 @@
+# Custom WASM module
+
+This module is a wrapper for the official WASM module, used to extend the functionality of the FeeShare module. The original FeeShare module implementation only rewarded registered contracts that took part in the execution of a transaction. However, this approach has been modified using the Custom WASM module wrapper to reward all registered contracts that participate in a transaction. 
+
+When a contract is executed, the custom WASM module keeps track of each participating contract address in a list. When the transaction is completed, the `PostHandler` from the FeeShare module distributes the rewards between the listed participants, and the `PostHandler` from the custom WASM module removes the contract addresses from the store.
+
+For more information on the FeeShare module, visit the [Feeshare spec](../feeshare/spec/README.md).