docs(specs): fungible module docs (#680)

* docs(specs): fungible module

* fix: skip messages.md if no messages

---------

Co-authored-by: brewmaster012 <88689859+brewmaster012@users.noreply.github.com>

Makefile

@@ -127,6 +127,10 @@ proto:
 	@sh ./scripts/protoc-gen-openapi.sh
 .PHONY: proto
 
+specs:
+	@go run ./scripts/gen-spec.go
+.PHONY: specs
+
 ###############################################################################
 ###                                Docker Images                             ###
 ###############################################################################

docs/spec/crosschain/messages.md

@@ -38,8 +38,8 @@ key, participant and operator addresses, finalized and keygen heights).
 If the vote passes, the information about the TSS key is recorded on chain
 and the status of the keygen is set to "success".
 
-Fails if the keygen does not exist or if the keygen has been already
-completed.
+Fails if the keygen does not exist, the keygen has been already
+completed, or the keygen has failed.
 
 Only node accounts are authorized to broadcast this message.
 

docs/spec/fungible/messages.md

@@ -2,6 +2,25 @@
 
 ## MsgDeployFungibleCoinZRC20
 
+Deploys a fungible coin from a connected chains as a ZRC20 on ZetaChain.
+
+If this is a gas coin, the following happens:
+
+* ZRC20 contract for the coin is deployed
+* contract address of ZRC20 is set as a token address in the system
+contract
+* ZETA tokens are minted and deposited into the module account
+* setGasZetaPool is called on the system contract to add the information
+about the pool to the system contract
+* addLiquidityETH is called to add liquidity to the pool
+
+If this is a non-gas coin, the following happens:
+
+* ZRC20 contract for the coin is deployed
+* The coin is added to the list of foreign coins in the module's state
+
+Only the admin policy account is authorized to broadcast this message.
+
 ```proto
 message MsgDeployFungibleCoinZRC20 {
 	string creator = 1;
@@ -17,6 +36,10 @@ message MsgDeployFungibleCoinZRC20 {
 
 ## MsgRemoveForeignCoin
 
+Removes a coin from the list of foreign coins in the module's state.
+
+Only the admin policy account is authorized to broadcast this message.
+
 ```proto
 message MsgRemoveForeignCoin {
 	string creator = 1;

docs/spec/fungible/overview.md

@@ -0,0 +1,27 @@
+# Overview
+
+The `fungible` facilitates the deployment of fungible tokens of connected
+blockchains (called "foreign coins") on ZetaChain.
+
+Foreign coins are represented as ZRC20 tokens on ZetaChain.
+
+When a foreign coin is deployed on ZetaChain, a ZRC20 contract is deployed, a
+pool is created, liquidity is added to the pool, and the foreign coin is added
+to the list of foreign coins in the module's state.
+
+The module contains the logic for:
+
+- Deploying a foreign coin on ZetaChain
+- Deploying a system contract, Uniswap and wrapped ZETA
+- Depositing to and calling omnichain smart contracts on ZetaChain from
+  connected chains (`DepositZRC20AndCallContract` and `DepositZRC20`)
+
+the module depends heavily on the
+[protocol contracts](https://github.com/zeta-chain/protocol-contracts).
+
+## State
+
+The `fungible` module keeps track of the following state:
+
+- System contract address
+- A list of foreign coins

readme.md

@@ -1,43 +1,75 @@
 # ZetaChain
 
-ZetaChain is an EVM-compatible L1 blockchain that enables omnichain, generic smart contracts and messaging between any blockchain.
+ZetaChain is an EVM-compatible L1 blockchain that enables omnichain, generic
+smart contracts and messaging between any blockchain.
 
 ## Prerequisites
 
-* [Go](https://golang.org/doc/install) 1.19
-* [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/) (optional, for running tests locally)
-* [buf](https://buf.build/) (optional, for processing protocol buffer files)
-* [jq](https://stedolan.github.io/jq/download/) (optional, for running scripts)
+- [Go](https://golang.org/doc/install) 1.19
+- [Docker](https://docs.docker.com/install/) and
+  [Docker Compose](https://docs.docker.com/compose/install/) (optional, for
+  running tests locally)
+- [buf](https://buf.build/) (optional, for processing protocol buffer files)
+- [jq](https://stedolan.github.io/jq/download/) (optional, for running scripts)
 
 ## Components of ZetaChain
 
-ZetaChain is built with [Cosmos SDK](https://github.com/cosmos/cosmos-sdk), a modular framework for building blockchain and [Ethermint](https://github.com/evmos/ethermint), a module that implements EVM-compatibility.
+ZetaChain is built with [Cosmos SDK](https://github.com/cosmos/cosmos-sdk), a
+modular framework for building blockchain and
+[Ethermint](https://github.com/evmos/ethermint), a module that implements
+EVM-compatibility.
 
-* [zeta-node](https://github.com/zeta-chain/zeta-node) (this repository) contains the source code for the ZetaChain node (`zetacored`) and the ZetaChain client (`zetaclientd`).
-* [protocol-contracts](https://github.com/zeta-chain/protocol-contracts) contains the source code for the Solidity smart contracts that implement the core functionality of ZetaChain.
+- [zeta-node](https://github.com/zeta-chain/zeta-node) (this repository)
+  contains the source code for the ZetaChain node (`zetacored`) and the
+  ZetaChain client (`zetaclientd`).
+- [protocol-contracts](https://github.com/zeta-chain/protocol-contracts)
+  contains the source code for the Solidity smart contracts that implement the
+  core functionality of ZetaChain.
 
 ## Building the source code
 
 ```
 make install
 ```
 
-This command will install the `zetacoded` and `zetaclientd` binaries in your `$GOPATH/bin` directory.
+This command will install the `zetacoded` and `zetaclientd` binaries in your
+`$GOPATH/bin` directory.
 
 ## Making changes to the source code
 
-After making changes to any of the protocol buffer files, run the following command to generate the Go files:
+After making changes to any of the protocol buffer files, run the following
+command to generate the Go files:
 
 ```
 make proto
 ```
 
-This command will use `buf` to generate the Go files from the protocol buffer files and move them to the correct directories inside `x/`. It will also generate an OpenAPI spec.
+This command will use `buf` to generate the Go files from the protocol buffer
+files and move them to the correct directories inside `x/`. It will also
+generate an OpenAPI spec.
+
+### Generate documentation
+
+To generate the documentation, run the following command:
+
+```
+make specs
+```
+
+This command will run a script to update the modules' documentation. The script
+uses static code analysis to read the protocol buffer files and identify all
+Cosmos SDK messages. It then search the source code for the corresponding
+message handler functions and retrieves the documentation for those functions.
+Finally, it creates a `messages.md` file for each module, which contains the
+documentation for all the messages in that module.
 
 ## Running tests
 
-To check that the source code is working as expected, refer to the manual on how to [run the smoke test](./contrib/localnet/README.md).
+To check that the source code is working as expected, refer to the manual on how
+to [run the smoke test](./contrib/localnet/README.md).
 
 ## Community
 
-[Twitter](https://twitter.com/zetablockchain) | [Discord](https://discord.com/invite/zetachain) | [Telegram](https://t.me/zetachainofficial) | [Website](https://zetachain.com)
+[Twitter](https://twitter.com/zetablockchain) |
+[Discord](https://discord.com/invite/zetachain) |
+[Telegram](https://t.me/zetachainofficial) | [Website](https://zetachain.com)

scripts/gen-spec.go

@@ -84,6 +84,10 @@ func processProtoFile(path string, outputBaseDir string) error {
 		}),
 	)
 
+	if len(messageMap) == 0 {
+		return nil
+	}
+
 	if packageName != "" && len(msgServices) > 0 {
 		outputDir := filepath.Join(outputBaseDir, getLastSegmentOfPackageName(packageName))
 		err = os.MkdirAll(outputDir, 0750)

x/fungible/keeper/msg_server_deploy_fungible_coin_zrc_4.go

@@ -12,6 +12,24 @@ import (
 	zetaObserverTypes "github.com/zeta-chain/zetacore/x/observer/types"
 )
 
+// Deploys a fungible coin from a connected chains as a ZRC20 on ZetaChain.
+//
+// If this is a gas coin, the following happens:
+//
+// * ZRC20 contract for the coin is deployed
+// * contract address of ZRC20 is set as a token address in the system
+// contract
+// * ZETA tokens are minted and deposited into the module account
+// * setGasZetaPool is called on the system contract to add the information
+// about the pool to the system contract
+// * addLiquidityETH is called to add liquidity to the pool
+//
+// If this is a non-gas coin, the following happens:
+//
+// * ZRC20 contract for the coin is deployed
+// * The coin is added to the list of foreign coins in the module's state
+//
+// Only the admin policy account is authorized to broadcast this message.
 func (k msgServer) DeployFungibleCoinZRC20(goCtx context.Context, msg *types.MsgDeployFungibleCoinZRC20) (*types.MsgDeployFungibleCoinZRC20Response, error) {
 	ctx := sdk.UnwrapSDKContext(goCtx)
 	if msg.Creator != k.zetaobserverKeeper.GetParams(ctx).GetAdminPolicyAccount(zetaObserverTypes.Policy_Type_deploy_fungible_coin) {

x/fungible/keeper/msg_server_remove_foreign_coin.go

@@ -9,6 +9,9 @@ import (
 	zetaObserverTypes "github.com/zeta-chain/zetacore/x/observer/types"
 )
 
+// Removes a coin from the list of foreign coins in the module's state.
+//
+// Only the admin policy account is authorized to broadcast this message.
 func (k msgServer) RemoveForeignCoin(goCtx context.Context, msg *types.MsgRemoveForeignCoin) (*types.MsgRemoveForeignCoinResponse, error) {
 	ctx := sdk.UnwrapSDKContext(goCtx)
 	if msg.Creator != k.zetaobserverKeeper.GetParams(ctx).GetAdminPolicyAccount(zetaObserverTypes.Policy_Type_deploy_fungible_coin) {