diff --git a/docs/1 Introduction/1 Introduction.md b/docs/1 Introduction/1 Introduction.md index cfadb18994..6932ed75d6 100644 --- a/docs/1 Introduction/1 Introduction.md +++ b/docs/1 Introduction/1 Introduction.md @@ -35,7 +35,7 @@ The following projects are using the technology: Cosmos modules are the foundational building blocks for building a blockchain. Modules can be created and shared with anyone. Each module plugs into the Cosmos SDK. Some of the modules are core building blocks for creating blockchains, while other modules enable new features. -Many of the live blockchains use multiple Cosmos modules. The foundational modules for starport are: `auth`, `bank`, `staking`, `params` and `supply`. We also recommend adding the `wasm` or the `evm` module, this allows you to deploy Web Assembly smart contracts to your blockchain. The `evm` module enables the Ethereum EVM to be used in your blockchain. Each module comes with clear documentation and codebase. If you wanted to make changes to a specific module, you can fork the module and change what suits your use case better. +Many of the live blockchains use multiple Cosmos modules. The foundational modules for starport are: `auth`, `bank`, `staking`, `params`, `capability`, `mint`, `governance`, `crisis`, `slashing`, `ibc`, `upgrade`, `evidence` and `supply`. We also recommend adding the `wasm` or the `evm` module, this allows you to deploy - Web Assembly for wasm, Solidity for evm - smart contracts to your blockchain. The `evm` module enables the Ethereum EVM to be used in your blockchain. Each module comes with clear documentation and codebase. If you want to make changes to a specific module, you can fork the module and change what suits your use case better. ## Summary diff --git a/docs/1 Introduction/5 Genesis File.md b/docs/1 Introduction/5 Genesis File.md index afa93087c1..f227e1fd50 100644 --- a/docs/1 Introduction/5 Genesis File.md +++ b/docs/1 Introduction/5 Genesis File.md @@ -12,8 +12,9 @@ With Starport you will create a genesis file from your `config.yml`, it typicall ```json { - "genesis_time": "2020-09-03T20:39:19.245733Z", + "genesis_time": "2021-01-15T12:43:55.453718Z", "chain_id": "blog", + "initial_height": "1", "consensus_params": { "block": { "max_bytes": "22020096", @@ -22,70 +23,18 @@ With Starport you will create a genesis file from your `config.yml`, it typicall }, "evidence": { "max_age_num_blocks": "100000", - "max_age_duration": "172800000000000" + "max_age_duration": "172800000000000", + "max_bytes": "1048576" }, "validator": { "pub_key_types": [ "ed25519" ] - } + }, + "version": {} }, "app_hash": "", "app_state": { - "supply": { - "supply": [] - }, - "blog": {}, - "genutil": { - "gentxs": [ - { - "type": "cosmos-sdk/StdTx", - "value": { - "msg": [ - { - "type": "cosmos-sdk/MsgCreateValidator", - "value": { - "description": { - "moniker": "mynode", - "identity": "", - "website": "", - "security_contact": "", - "details": "" - }, - "commission": { - "rate": "0.100000000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.010000000000000000" - }, - "min_self_delegation": "1", - "delegator_address": "cosmos1al6ytsuyhq3e0v0mcrq88sqwguqe02n2yjxuwj", - "validator_address": "cosmosvaloper1al6ytsuyhq3e0v0mcrq88sqwguqe02n2pxjfzp", - "pubkey": "cosmosvalconspub1zcjduepqg7sqkpgeqd0hnd025fztrlmzk0f3lrc8ea90cpfhz4cjq5m0h2rqkaxgd2", - "value": { - "denom": "stake", - "amount": "100000000" - } - } - } - ], - "fee": { - "amount": [], - "gas": "200000" - }, - "signatures": [ - { - "pub_key": { - "type": "tendermint/PubKeySecp256k1", - "value": "A4hHCwk6n8Dq0TAg+BA2vz8wbFsB0gg8WEtkbVnsi3P9" - }, - "signature": "tRvI8ypTM2z45jXJgFVQ2aJ0Q4Dz3KZW92MtYDl6OlgMXA4EA99eQPl6gzVskcOM3OB+OsKzmkX4AyyVrm4qOQ==" - } - ], - "memo": "3bea7947b66f99b1a6585c67456191859838b709@192.168.2.191:26656" - } - } - ] - }, "auth": { "params": { "max_memo_characters": "256", @@ -96,61 +45,246 @@ With Starport you will create a genesis file from your `config.yml`, it typicall }, "accounts": [ { - "type": "cosmos-sdk/Account", - "value": { - "address": "cosmos1al6ytsuyhq3e0v0mcrq88sqwguqe02n2yjxuwj", - "coins": [ - { - "denom": "stake", - "amount": "100000000" - }, + "@type": "/cosmos.auth.v1beta1.BaseAccount", + "address": "cosmos1ml7mett44vnvmxzku24ncujjl5gpztp4p3kag6", + "pub_key": null, + "account_number": "0", + "sequence": "0" + }, + { + "@type": "/cosmos.auth.v1beta1.BaseAccount", + "address": "cosmos17ahmvzxgvkl0ccacnpj0nwstalww68z0jrz89q", + "pub_key": null, + "account_number": "0", + "sequence": "0" + } + ] + }, + "bank": { + "params": { + "send_enabled": [], + "default_send_enabled": true + }, + "balances": [ + { + "address": "cosmos1ml7mett44vnvmxzku24ncujjl5gpztp4p3kag6", + "coins": [ + { + "denom": "stake", + "amount": "100000000" + }, + { + "denom": "token", + "amount": "1000" + } + ] + }, + { + "address": "cosmos17ahmvzxgvkl0ccacnpj0nwstalww68z0jrz89q", + "coins": [ + { + "denom": "token", + "amount": "500" + } + ] + } + ], + "supply": [], + "denom_metadata": [] + }, + "capability": { + "index": "1", + "owners": [] + }, + "coinz": {}, + "crisis": { + "constant_fee": { + "amount": "1000", + "denom": "stake" + } + }, + "distribution": { + "delegator_starting_infos": [], + "delegator_withdraw_infos": [], + "fee_pool": { + "community_pool": [] + }, + "outstanding_rewards": [], + "params": { + "base_proposer_reward": "0.010000000000000000", + "bonus_proposer_reward": "0.040000000000000000", + "community_tax": "0.020000000000000000", + "withdraw_addr_enabled": true + }, + "previous_proposer": "", + "validator_accumulated_commissions": [], + "validator_current_rewards": [], + "validator_historical_rewards": [], + "validator_slash_events": [] + }, + "evidence": { + "evidence": [] + }, + "genutil": { + "gen_txs": [ + { + "body": { + "messages": [ { - "denom": "token", - "amount": "1000" + "@type": "/cosmos.staking.v1beta1.MsgCreateValidator", + "description": { + "moniker": "mynode", + "identity": "", + "website": "", + "security_contact": "", + "details": "" + }, + "commission": { + "rate": "0.100000000000000000", + "max_rate": "0.200000000000000000", + "max_change_rate": "0.010000000000000000" + }, + "min_self_delegation": "1", + "delegator_address": "cosmos1ml7mett44vnvmxzku24ncujjl5gpztp4p3kag6", + "validator_address": "cosmosvaloper1ml7mett44vnvmxzku24ncujjl5gpztp4y9zgyf", + "pubkey": { + "@type": "/cosmos.crypto.ed25519.PubKey", + "key": "oHynTiWsRxbdwWAkJLFBk/T8TWiFATFrKWfxemP2AWw=" + }, + "value": { + "denom": "stake", + "amount": "100000000" + } } ], - "public_key": null, - "account_number": "0", - "sequence": "0" - } - }, - { - "type": "cosmos-sdk/Account", - "value": { - "address": "cosmos1s25rfpwsm23ene6krurgghre6u8dnyguku52nk", - "coins": [ + "memo": "9e5f3e69aab836337554f3f8699aec8ee7978360@192.168.178.23:26656", + "timeout_height": "0", + "extension_options": [], + "non_critical_extension_options": [] + }, + "auth_info": { + "signer_infos": [ { - "denom": "token", - "amount": "500" + "public_key": { + "@type": "/cosmos.crypto.secp256k1.PubKey", + "key": "Aidt5eKiDmfXiXy7el+zI+i0VyD34e3pOoOzI3ljWXKt" + }, + "mode_info": { + "single": { + "mode": "SIGN_MODE_DIRECT" + } + }, + "sequence": "0" } ], - "public_key": null, - "account_number": "0", - "sequence": "0" - } + "fee": { + "amount": [], + "gas_limit": "200000", + "payer": "", + "granter": "" + } + }, + "signatures": [ + "/bELv1NNgp7941Ux8Zz6T0x5yKqKMjbX2Q+TzPB7IAMdr680fkZGMGOm2F0bX9hK2lapCp+3RnGgmxhMG/bHUw==" + ] } ] }, - "bank": { - "send_enabled": true + "gov": { + "deposit_params": { + "max_deposit_period": "172800s", + "min_deposit": [ + { + "amount": "10000000", + "denom": "stake" + } + ] + }, + "deposits": [], + "proposals": [], + "starting_proposal_id": "1", + "tally_params": { + "quorum": "0.334000000000000000", + "threshold": "0.500000000000000000", + "veto_threshold": "0.334000000000000000" + }, + "votes": [], + "voting_params": { + "voting_period": "172800s" + } + }, + "ibc": { + "channel_genesis": { + "ack_sequences": [], + "acknowledgements": [], + "channels": [], + "commitments": [], + "receipts": [], + "recv_sequences": [], + "send_sequences": [] + }, + "client_genesis": { + "clients": [], + "clients_consensus": [], + "create_localhost": false + }, + "connection_genesis": { + "client_connection_paths": [], + "connections": [] + } + }, + "mint": { + "minter": { + "annual_provisions": "0.000000000000000000", + "inflation": "0.130000000000000000" + }, + "params": { + "blocks_per_year": "6311520", + "goal_bonded": "0.670000000000000000", + "inflation_max": "0.200000000000000000", + "inflation_min": "0.070000000000000000", + "inflation_rate_change": "0.130000000000000000", + "mint_denom": "stake" + } + }, + "params": null, + "slashing": { + "missed_blocks": [], + "params": { + "downtime_jail_duration": "600s", + "min_signed_per_window": "0.500000000000000000", + "signed_blocks_window": "100", + "slash_fraction_double_sign": "0.050000000000000000", + "slash_fraction_downtime": "0.010000000000000000" + }, + "signing_infos": [] }, "staking": { + "delegations": [], + "exported": false, + "last_total_power": "0", + "last_validator_powers": [], "params": { - "unbonding_time": "1814400000000000", - "max_validators": 100, + "bond_denom": "stake", + "historical_entries": 100, "max_entries": 7, - "historical_entries": 0, - "bond_denom": "stake" + "max_validators": 100, + "unbonding_time": "1814400s" }, - "last_total_power": "0", - "last_validator_powers": null, - "validators": null, - "delegations": null, - "unbonding_delegations": null, - "redelegations": null, - "exported": false - }, - "params": null + "redelegations": [], + "unbonding_delegations": [], + "validators": [] + }, + "transfer": { + "denom_traces": [], + "params": { + "receive_enabled": true, + "send_enabled": true + }, + "port_id": "transfer" + }, + "upgrade": {}, + "vesting": {} } } ``` diff --git a/docs/1 Introduction/6 Starport IBC.md b/docs/1 Introduction/6 Starport IBC.md index 71cbe5bacd..86a8e229a7 100644 --- a/docs/1 Introduction/6 Starport IBC.md +++ b/docs/1 Introduction/6 Starport IBC.md @@ -9,7 +9,7 @@ In order to communicate between chains, bootstrapping two blockchains with starp To start using IBC with Starport open up a [web-based development environment](https://gitpod.io/#https://github.com/tendermint/starport/), then scaffold and launch a Stargate chain: ``` -starport app github.com/foo/foo --sdk-version stargate +starport app github.com/foo/foo cd foo diff --git a/docs/2 Architecture/3 Standard Modules.md b/docs/2 Architecture/3 Standard Modules.md index e5fb05e5fc..e84c452474 100644 --- a/docs/2 Architecture/3 Standard Modules.md +++ b/docs/2 Architecture/3 Standard Modules.md @@ -16,9 +16,17 @@ These modules are - [Standard modules](#standard-modules) - [Auth](#auth) - [Bank](#bank) + - [Capability](#capability) - [Staking](#staking) + - [Mint](#mint) - [Distribution](#distribution) - [Params](#params) + - [Governance](#governance) + - [Crisis](#crisis) + - [Slashing](#slashing) + - [IBC](#ibc) + - [Upgrade](#upgrade) + - [Evidence](#evidence) - [Using modules](#using-modules) - [Summary](#summary) @@ -30,13 +38,22 @@ It introduces Gas and Fees as concepts in order to prevent the blockchain to blo The interface of an Account is defined as -```go -type BaseAccount struct { - Address AccAddress - Coins Coins - PubKey PubKey - AccountNumber uint64 - Sequence uint64 +```proto +// BaseAccount defines a base account type. It contains all the necessary fields +// for basic account functionality. Any custom account type should extend this +// type for additional functionality (e.g. vesting). +message BaseAccount { + option (gogoproto.goproto_getters) = false; + option (gogoproto.goproto_stringer) = false; + option (gogoproto.equal) = false; + + option (cosmos_proto.implements_interface) = "AccountI"; + + string address = 1; + google.protobuf.Any pub_key = 2 + [(gogoproto.jsontag) = "public_key,omitempty", (gogoproto.moretags) = "yaml:\"public_key\""]; + uint64 account_number = 3 [(gogoproto.moretags) = "yaml:\"account_number\""]; + uint64 sequence = 4; } ``` @@ -44,24 +61,48 @@ The `auth` module exposes the account keeper where accounts can be stored or cha _Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/auth/spec/README.md)_ + ## Bank The `bank` module has its name because it acts as the module that allows for token transfers and checks for the validity of each transfer. Furthermore, it is responsible for checking the whole supply of the chain, the sum of all account balances. _Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/bank/spec/README.md)_ + +## Capability + +Full implementation of the IBC specification requires the ability to create and authenticate object-capability keys at runtime (i.e., during transaction execution), as described in ICS 5. In the IBC specification, capability keys are created for each newly initialised port & channel, and are used to authenticate future usage of the port or channel. Since channels and potentially ports can be initialised during transaction execution, the state machine must be able to create object-capability keys at this time. + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/capability/spec/README.md)_ + + ## Staking The `staking` module allows for an advanced Proof of Stake system, where validators can be created and tokens delegated to validators. _Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/02_state_transitions.md#slashing)_ + +## Mint + +The minting mechanism is designed to allow for a flexible inflation rate determined by market demand targeting a particular bonded-stake ratio effect a balance between market liquidity and staked supply. + +It can be broken down in the following way: + +If the inflation rate is below the goal %-bonded the inflation rate will increase until a maximum value is reached +If the goal % bonded (67% in Cosmos-Hub) is maintained, then the inflation rate will stay constant +If the inflation rate is above the goal %-bonded the inflation rate will decrease until a minimum value is reached + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/mint/spec/README.md)_ + + ## Distribution The `distribution` module is responsible to distribute the inflation of a Token. When new Tokens get created, they get distributed to the validators and their respective delegators, with a potential commission the validator takes. Each validator can choose a commission of those Token when creating a validator, this commission is editable. _Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/distribution/spec/README.md)_ + ## Params The `params` module allows for a global parameter store in your blockchain application. It is designed to hold the chain parameters so that they can be changed during runtime by governance. It allows to upgrade the blockchain parameters via the `government` module and take effect on an agreed upon time when the majority of the shareholders decide to make a change. @@ -71,6 +112,64 @@ _Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/par Those modules are typically installed on default when using starport. There are a range of modules that are also part of the Cosmos SDK, additionally some other public modules have already reached a major level of usage and acceptance. We will look at more advanced modules in the next Chapter. + +## Governance + +The module enables Cosmos-SDK based blockchains to support an on-chain governance system. In this system, holders of the native staking token of the chain can vote on proposals on a 1 token 1 vote basis (from there it can be parameterized). Next is a list of features the module currently supports: + +- Proposal submission: Users can submit proposals with a deposit. Once the minimum deposit is reached, proposal enters voting period +- Vote: Participants can vote on proposals that reached MinDeposit +- Inheritance and penalties: Delegators inherit their validator's vote if they don't vote themselves. +- Claiming deposit: Users that deposited on proposals can recover their deposits if the proposal was accepted OR if the proposal never entered voting period. + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/gov/spec/README.md)_ + + +## Crisis + +The crisis module halts the blockchain under the circumstance that a blockchain invariant is broken. Invariants can be registered with the application during the application initialization process. + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/crisis/spec/README.md)_ + + +## Slashing + +The slashing module enables Cosmos SDK-based blockchains to disincentivize any attributable action by a protocol-recognized actor with value at stake by penalizing them ("slashing"). + +Penalties may include, but are not limited to: + +Burning some amount of their stake +Removing their ability to vote on future blocks for a period of time. +This module will be used by the Cosmos Hub, the first hub in the Cosmos ecosystem. + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/slashing/spec/README.md)_ + + +## IBC + +IBC allows to relay packets between chains and could be used with any compatible modules between two chains. +The `IBC` module, as Inter-blockchain Communication, enables for example sending native tokens between blockchains. +It is divided by a subset of specifications. + +_Read the [specifications](https://github.com/cosmos/cosmos-sdk/blob/master/x/ibc/spec/README.md)_ + + +## Upgrade + +`x/upgrade` is an implementation of a Cosmos SDK module that facilitates smoothly upgrading a live Cosmos chain to a new (breaking) software version. It accomplishes this by providing a BeginBlocker hook that prevents the blockchain state machine from proceeding once a pre-defined upgrade block time or height has been reached. + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/upgrade/spec/README.md)_ + + +## Evidence + +`x/evidence` is an implementation of a Cosmos SDK module, per ADR 009, that allows for the submission and handling of arbitrary evidence of misbehavior such as equivocation and counterfactual signing. + +The evidence module differs from standard evidence handling which typically expects the underlying consensus engine, e.g. Tendermint, to automatically submit evidence when it is discovered by allowing clients and foreign chains to submit more complex evidence directly. + +_Read the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/x/evidence/spec/README.md)_ + + ## Using modules With starport you can add a module with the command `starport module create modulename`. When adding a module manually to a blockchain application, it requires to edit the `app/app.go` and the `myappcli/main.go` with the according entries. Starport manages the code edits and additions for you conveniently. diff --git a/docs/2 Architecture/4 Writing Custom Modules.md b/docs/2 Architecture/4 Writing Custom Modules.md index 0ac1b52955..10a5d8b7c6 100644 --- a/docs/2 Architecture/4 Writing Custom Modules.md +++ b/docs/2 Architecture/4 Writing Custom Modules.md @@ -1,18 +1,26 @@ # Writing custom modules -Starport allows you to jump directly into creating your own module. With the before described `type` function you can add new types to your application. Under the hood, starport creates a handler, types and messages for you. +Starport allows you to jump directly into creating your own module. With the before described `type` function you can add new transaction types to your application. Under the hood, starport creates a handler, types and messages for you. Without using starport, you would need to manipulate these functions yourself. Here is what starport does when you add a `type`. Understanding what starport does might help in order to either add more complex structures or debug in case something does not work as it should. +## Proto + +When using the type command a Protobuffer definition is created for you in the `proto` directory. + +It contains messages for full CRUD (Create, Read, Update, Delete) operations for your created transaction type. + +## Module + Once you have created your starport blockchain application, you will have your own module resident of `yourapp/x/yourmodule`, it comes predefined with a couple of files and folders which deifne types, functions and messages of your module. ## Types The `types` folder defines structures of your golang blockchain application. Here you can define your basic or more advanced types which will later be data and functions usable on your blockchain. -Your basic `types` reside in `types/TypeModule.go`, define the fields and functions of your application. +The message types are defined in the file `types/messages_type`, or other functions that you are planning to use. -The message types are defined in the file `types/MsgCreateX`, or other functions that you are planning to use. +## Client There is a `rest` folder that takes care of the rest API that your module exposes. @@ -20,12 +28,12 @@ The `cli` folder with the contents take care of the Command line interface comma ## Frontend -Currently, Starport provides a basic Vue user interface that you can take inspiration from or use it as a starting point for your app. The source code is available inside the `vue` directory. Written in JavaScript you can hop directly into writing the frontend for your application. +Currently starport provides a basic Vue User-Interface that you can get inspired by or build ontop on. The source code is available in the `vue` folder. Written in JavaScript you can hop directly into writing the frontend for your application. [Learn more about Vue.](https://vuejs.org/) ## Summary - Starport bootstraps a module for you. -- You can change a module by modifying the files in `yourapp/x/`. -- Starport has a Vue frontend where you can start to work immediately. +- You can change a module by modifying the files in `yourapp/x/` or the `proto` diretory. +- Starport has a Vue frontend where you can start to work immediately. \ No newline at end of file