From 70d33176728abe576f1c4224f555f55c7794445d Mon Sep 17 00:00:00 2001 From: jgo121 Date: Mon, 4 Dec 2023 10:59:06 +0800 Subject: [PATCH] add contributing, devnotes, update readme --- CONTRIBUTING.md | 88 +++++++++++++++++++++++ DEVNOTES.md | 172 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 182 ++++++++---------------------------------------- 3 files changed, 288 insertions(+), 154 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 DEVNOTES.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..cf50b672 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing + +- [Contributing](#contributing) + - [Overview](#overview) + - [Kira Improvement Proposal (KIP)](#kira-improvement-proposal-kip) + - [Testing](#testing) + - [Pull Requests](#pull-requests) + - [Requesting Reviews](#requesting-reviews) + - [Changelog](#changelog) + - [Dependencies](#dependencies) + - [Protobuf](#protobuf) + - [Branching Model and Release](#branching-model-and-release) + +## Overview + +Contributing to this repo can mean many things such as participating in +discussion or proposing code changes. +Following the processes outlined in this document will lead to the best +chance of getting changes merged into the codebase. + +## Kira Improvement Proposal (KIP) + +When proposing an architecture decision for Gaia, please start by opening an [issue](https://github.com/cosmos/gaia/issues/new/choose) or a [discussion](https://github.com/cosmos/gaia/discussions/new) with a summary of the proposal. Once the proposal has been discussed and there is rough alignment on a high-level approach to the design, you may either start development, or write an ADR. + +If your architecture decision is a simple change, you may contribute directly without writing an ADR. However, if you are proposing a significant change, please include a corresponding ADR. + +To create an ADR, follow the [template](./docs/architecture/adr-template.md) and [doc](./docs/architecture/README.md). If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/gaia/tree/main/docs/architecture). + +### Testing + +Tests can be executed by running `make test` at the top level of the Sekai repository. + +### Pull Requests + +Before submitting a pull request: + +- synchronize your branch with the latest `master` branch and resolve any arising conflicts, `git fetch origin/master && git merge origin/master` +- run `make install`, `make test`, to ensure that all checks and tests pass. + +### Requesting Reviews + +In order to accommodate the review process, the author of the PR should be in contact with Sekai repo maintainers. + +### Changelog + +Changelog keeps the changes made as part of releases. The logs are kept on [CHANGELOG](./CHANGELOG.md). + +## Dependencies + +We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage +dependency versions. + +The main branch of every Cosmos repository should just build with `go get`, +which means they should be kept up-to-date with their dependencies so we can +get away with telling people they can just `go get` our software. + +When dependencies in Sekai's `go.mod` are changed, it is generally accepted practice +to delete `go.sum` and then run `go mod tidy`. + +Since some dependencies are not under our control, a third party may break our +build, in which case we can fall back on `go mod tidy -v`. + +## Protobuf + +We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along with [gogoproto](https://github.com/cosmos/gogoproto) to generate code for use in sekai. + +For deterministic behavior around Protobuf tooling, everything is containerized using Docker. Make sure to have Docker installed on your machine, or head to [Docker's website](https://docs.docker.com/get-docker/) to install it. + +To generate the protobuf stubs, you can run `make proto-gen`. + +## Branching Model and Release + +Sekai branches should be one of `feature/{feature-description}` or `bugfix/{bugfix-description}` to join CI/CD process. + +Sekai follows [semantic versioning](https://semver.org). + +To release a new version + +- Set a new sekai version on [`types/constants.go`](types/constants.go) +- Add relevant information on [`RELEASE.md`](RELEASE.md) +- Push the code to the branch +- The bot automatically creates release branch `release/vx.x.x` as configured in [`types/constants.go`](types/constants.go) and raise the PR from working branch to release branch automatically +- Check CI/CD pass on the PR +- Get manual review +- Get the PR merged into release branch +- New PR into master is raised after release branch PR merge +- Check CI/CD pass on the PR +- Merge into master diff --git a/DEVNOTES.md b/DEVNOTES.md new file mode 100644 index 00000000..022bed03 --- /dev/null +++ b/DEVNOTES.md @@ -0,0 +1,172 @@ +## Install bash-utils + +Bash-utils is a KIRA tool that helps to simplify shell scripts and various bash commands that you might need to run + +``` +# Install bash-utils.sh KIRA tool to make downloads faster and easier +TOOLS_VERSION="v0.0.12.4" && mkdir -p /usr/keys && FILE_NAME="bash-utils.sh" && \ + if [ -z "$KIRA_COSIGN_PUB" ] ; then KIRA_COSIGN_PUB=/usr/keys/kira-cosign.pub ; fi && \ + echo -e "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/IrzBQYeMwvKa44/DF/HB7XDpnE+\nf+mU9F/Qbfq25bBWV2+NlYMJv3KvKHNtu3Jknt6yizZjUV4b8WGfKBzFYw==\n-----END PUBLIC KEY-----" > $KIRA_COSIGN_PUB && \ + wget "https://github.com/KiraCore/tools/releases/download/$TOOLS_VERSION/${FILE_NAME}" -O ./$FILE_NAME && \ + wget "https://github.com/KiraCore/tools/releases/download/$TOOLS_VERSION/${FILE_NAME}.sig" -O ./${FILE_NAME}.sig && \ + cosign verify-blob --key="$KIRA_COSIGN_PUB" --signature=./${FILE_NAME}.sig ./$FILE_NAME && \ + chmod -v 555 ./$FILE_NAME && ./$FILE_NAME bashUtilsSetup "/var/kiraglob" && . /etc/profile && \ + echoInfo "Installed bash-utils $(bash-utils bashUtilsVersion)" +``` + +## Quick setup from Releases + +```bash +# TBD +``` + +## Set environment variables + +```sh +sh env.sh +``` + +# Get version info + +[scripts/commands/version.sh](scripts/commands/version.sh) + +# Adding more validators + +[scripts/commands/adding-validators.sh](scripts/commands/adding-validators.sh) + +## Set ChangeTxFee permission + +[scripts/commands/set-permission.sh](scripts/commands/set-permission.sh) + +## Set network properties + +[scripts/commands/set-network-properties.sh](scripts/commands/set-network-properties.sh) + +## Set Execution Fee + +[scripts/commands/set-execution-fee.sh](scripts/commands/set-execution-fee.sh) + +## Upsert token rates + +[scripts/commands/upsert-token-rates.sh](scripts/commands/upsert-token-rates.sh) + +## Upsert token alias + +[scripts/commands/upsert-token-alias.sh](scripts/commands/upsert-token-alias.sh) + +# Fee payment in foreign currency + +[scripts/commands/foreign-fee-payments.sh](scripts/commands/foreign-fee-payments.sh) + +# Fee payment in foreign currency returning failure - execution fee in foreign currency + +[scripts/commands/foreign-fee-payments-failure-return.sh](scripts/commands/foreign-fee-payments-failure-return.sh) + +## Query permission of an address + +[scripts/commands/query-permission.sh](scripts/commands/query-permission.sh) + +## Query network properties + +[scripts/commands/query-network-properties.sh](scripts/commands/query-network-properties.sh) + +## Query execution fee + +[scripts/commands/query-execution-fee.sh](scripts/commands/query-execution-fee.sh) + +# Query token alias + +[scripts/commands/query-token-alias.sh](scripts/commands/query-token-alias.sh) + +# Query token rate + +[scripts/commands/query-token-rate.sh](scripts/commands/query-token-rate.sh) + +# Query validator account + +[scripts/commands/query-validator.sh](scripts/commands/query-validator.sh) + +# Query for current frozen / unfronzen tokens + +**Notes**: these values are valid only when specific network property is enabled +[scripts/commands/query-frozen-token.sh](scripts/commands/query-frozen-token.sh) + +# Query poor network messages + +[scripts/commands/query-poor-network-messages.sh](scripts/commands/query-poor-network-messages.sh) + +# Query signing infos per validator's consensus address + +[scripts/commands/query-signing-infos.sh](scripts/commands/query-signing-infos.sh) + +# Common commands for governance process + +[scripts/commands/governance/common.sh](scripts/commands/governance/common.sh) + +### Set permission via governance process + +[scripts/commands/governance/assign-permission.sh](scripts/commands/governance/assign-permission.sh) + +## Upsert token alias via governance process + +[scripts/commands/governance/upsert-token-alias.sh](scripts/commands/governance/upsert-token-alias.sh) + +## Upsert token rates via governance process + +[scripts/commands/governance/upsert-token-rates.sh](scripts/commands/governance/upsert-token-rates.sh) + +# Commands for poor network management via governance process + +[scripts/commands/governance/poor-network-messages.sh](scripts/commands/governance/poor-network-messages.sh) + +# Freeze / unfreeze tokens via governance process + +[scripts/commands/governance/token-freeze.sh](scripts/commands/governance/token-freeze.sh) + +# Set network property proposal via governance process + +[scripts/commands/governance/set-network-property.sh](scripts/commands/governance/set-network-property.sh) + +# Set application upgrade proposal via governance process + +[scripts/commands/governance/upgrade-plan.sh](scripts/commands/governance/upgrade-plan.sh) + +Export the status of chain before halt (should kill the daemon process at the time of genesis export) +[scripts/commands/export-state.sh](scripts/commands/export-state.sh) + +The script for creating new chain from exported state should be written or manual edition process is required. +`ChainId` should be modified in this process. + +For now, upgrade process requires manual conversion from old genesis to new genesis. +At each time of upgrade, genesis upgrade command will be built and infra could run the command like `sekaid genesis-migrate` + +Note: state export command is not exporting the upgrade plan and if all validators run with exported genesis with the previous binary, consensus failure won't happen. + +# Identity registrar + +[scripts/commands/identity-registrar.sh](scripts/commands/identity-registrar.sh) + +# Unjail via governance process + +Modify genesis json to have jailed validator for Unjail testing +Add jailed validator key to kms. + +```sh + sekaid keys add jailed_validator --keyring-backend=test --home=$HOME/.sekaid --recover + "dish rather zoo connect cross inhale security utility occur spell price cute one catalog coconut sort shuffle palm crop surface label foster slender inherit" +``` + +[scripts/commands/governance/unjail-validator.sh](scripts/commands/governance/unjail-validator.sh) + +# New genesis file generation process from exported version + +In order to manually generate new genesis file when the hard fork is activated, following steps should be taken: + +1. Export current genesis, e.g: sekaid export --home= +2. Change chain-id to new_chain_id as indicated by the upgrade plan +3. Replace current upgrade plan in the app_state.upgrade with next plan and set next plan to null + +Using a command it can be done in this way. + +1. sekaid export > exported-genesis.json +2. sekaid new-genesis-from-exported exported-genesis.json new-genesis.json --json-minimize=true diff --git a/README.md b/README.md index d79262e5..d5e07b85 100644 --- a/README.md +++ b/README.md @@ -41,175 +41,49 @@ EOL cosign verify-blob --key=$KIRA_COSIGN_PUB--signature=./.sig ./ ``` -## Install bash-utils +## Features -Bash-utils is a KIRA tool that helps to simplify shell scripts and various bash commands that you might need to run +### Core modules for consensus -``` -# Install bash-utils.sh KIRA tool to make downloads faster and easier -TOOLS_VERSION="v0.0.12.4" && mkdir -p /usr/keys && FILE_NAME="bash-utils.sh" && \ - if [ -z "$KIRA_COSIGN_PUB" ] ; then KIRA_COSIGN_PUB=/usr/keys/kira-cosign.pub ; fi && \ - echo -e "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/IrzBQYeMwvKa44/DF/HB7XDpnE+\nf+mU9F/Qbfq25bBWV2+NlYMJv3KvKHNtu3Jknt6yizZjUV4b8WGfKBzFYw==\n-----END PUBLIC KEY-----" > $KIRA_COSIGN_PUB && \ - wget "https://github.com/KiraCore/tools/releases/download/$TOOLS_VERSION/${FILE_NAME}" -O ./$FILE_NAME && \ - wget "https://github.com/KiraCore/tools/releases/download/$TOOLS_VERSION/${FILE_NAME}.sig" -O ./${FILE_NAME}.sig && \ - cosign verify-blob --key="$KIRA_COSIGN_PUB" --signature=./${FILE_NAME}.sig ./$FILE_NAME && \ - chmod -v 555 ./$FILE_NAME && ./$FILE_NAME bashUtilsSetup "/var/kiraglob" && . /etc/profile && \ - echoInfo "Installed bash-utils $(bash-utils bashUtilsVersion)" -``` - -## Quick setup from Releases - -```bash -# TBD -``` - -## Set environment variables - -```sh -sh env.sh -``` - -# Get version info - -[scripts/commands/version.sh](scripts/commands/version.sh) - -# Adding more validators - -[scripts/commands/adding-validators.sh](scripts/commands/adding-validators.sh) - -## Set ChangeTxFee permission - -[scripts/commands/set-permission.sh](scripts/commands/set-permission.sh) - -## Set network properties - -[scripts/commands/set-network-properties.sh](scripts/commands/set-network-properties.sh) - -## Set Execution Fee - -[scripts/commands/set-execution-fee.sh](scripts/commands/set-execution-fee.sh) - -## Upsert token rates - -[scripts/commands/upsert-token-rates.sh](scripts/commands/upsert-token-rates.sh) - -## Upsert token alias - -[scripts/commands/upsert-token-alias.sh](scripts/commands/upsert-token-alias.sh) - -# Fee payment in foreign currency - -[scripts/commands/foreign-fee-payments.sh](scripts/commands/foreign-fee-payments.sh) - -# Fee payment in foreign currency returning failure - execution fee in foreign currency - -[scripts/commands/foreign-fee-payments-failure-return.sh](scripts/commands/foreign-fee-payments-failure-return.sh) - -## Query permission of an address - -[scripts/commands/query-permission.sh](scripts/commands/query-permission.sh) - -## Query network properties - -[scripts/commands/query-network-properties.sh](scripts/commands/query-network-properties.sh) +- staking +- slashing +- evidence +- distributor -## Query execution fee +### Basic modules -[scripts/commands/query-execution-fee.sh](scripts/commands/query-execution-fee.sh) +- spending +- tokens +- ubi -# Query token alias +### Liquid staking -[scripts/commands/query-token-alias.sh](scripts/commands/query-token-alias.sh) +- multistaking -# Query token rate +### Derivatives -[scripts/commands/query-token-rate.sh](scripts/commands/query-token-rate.sh) +- basket +- collectives -# Query validator account +### Governance -[scripts/commands/query-validator.sh](scripts/commands/query-validator.sh) +- gov -# Query for current frozen / unfronzen tokens +### Layer2 -**Notes**: these values are valid only when specific network property is enabled -[scripts/commands/query-frozen-token.sh](scripts/commands/query-frozen-token.sh) - -# Query poor network messages - -[scripts/commands/query-poor-network-messages.sh](scripts/commands/query-poor-network-messages.sh) - -# Query signing infos per validator's consensus address - -[scripts/commands/query-signing-infos.sh](scripts/commands/query-signing-infos.sh) - -# Common commands for governance process - -[scripts/commands/governance/common.sh](scripts/commands/governance/common.sh) - -### Set permission via governance process - -[scripts/commands/governance/assign-permission.sh](scripts/commands/governance/assign-permission.sh) - -## Upsert token alias via governance process - -[scripts/commands/governance/upsert-token-alias.sh](scripts/commands/governance/upsert-token-alias.sh) - -## Upsert token rates via governance process - -[scripts/commands/governance/upsert-token-rates.sh](scripts/commands/governance/upsert-token-rates.sh) - -# Commands for poor network management via governance process - -[scripts/commands/governance/poor-network-messages.sh](scripts/commands/governance/poor-network-messages.sh) - -# Freeze / unfreeze tokens via governance process - -[scripts/commands/governance/token-freeze.sh](scripts/commands/governance/token-freeze.sh) - -# Set network property proposal via governance process - -[scripts/commands/governance/set-network-property.sh](scripts/commands/governance/set-network-property.sh) - -# Set application upgrade proposal via governance process - -[scripts/commands/governance/upgrade-plan.sh](scripts/commands/governance/upgrade-plan.sh) - -Export the status of chain before halt (should kill the daemon process at the time of genesis export) -[scripts/commands/export-state.sh](scripts/commands/export-state.sh) - -The script for creating new chain from exported state should be written or manual edition process is required. -`ChainId` should be modified in this process. - -For now, upgrade process requires manual conversion from old genesis to new genesis. -At each time of upgrade, genesis upgrade command will be built and infra could run the command like `sekaid genesis-migrate` - -Note: state export command is not exporting the upgrade plan and if all validators run with exported genesis with the previous binary, consensus failure won't happen. - -# Identity registrar - -[scripts/commands/identity-registrar.sh](scripts/commands/identity-registrar.sh) - -# Unjail via governance process - -Modify genesis json to have jailed validator for Unjail testing -Add jailed validator key to kms. - -```sh - sekaid keys add jailed_validator --keyring-backend=test --home=$HOME/.sekaid --recover - "dish rather zoo connect cross inhale security utility occur spell price cute one catalog coconut sort shuffle palm crop surface label foster slender inherit" -``` +- layer2 -[scripts/commands/governance/unjail-validator.sh](scripts/commands/governance/unjail-validator.sh) +### Fees -# New genesis file generation process from exported version +- feeprocessing -In order to manually generate new genesis file when the hard fork is activated, following steps should be taken: +### Utilities & Upgrade -1. Export current genesis, e.g: sekaid export --home= -2. Change chain-id to new_chain_id as indicated by the upgrade plan -3. Replace current upgrade plan in the app_state.upgrade with next plan and set next plan to null +- custody +- recovery +- genutil +- upgrade -Using a command it can be done in this way. +## Contributing -1. sekaid export > exported-genesis.json -2. sekaid new-genesis-from-exported exported-genesis.json new-genesis.json --json-minimize=true +Check out [contributing.md](./CONTRIBUTING.md) for our guidelines & policies for how we develop the Kira chain. Thank you to all those who have contributed!