From 2e4fe5fd29c3290c5664f05413a389c3694ce2a0 Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 11:52:22 +0800
Subject: [PATCH 1/7] docs: refine the doc framework
---
app/app.go | 2 +-
.../events.md} | 5 +
docs/api-sdk/grpc_rest.md | 87 ++++
docs/api-sdk/sdk.md | 8 +
docs/architecture/01-overview.md | 110 -----
docs/architecture/02-key_management.md | 49 --
.../05-storage-metadata-models.md | 417 ------------------
docs/architecture/readme.md | 16 -
docs/{tutorial/05-bank.md => cli/bank.md} | 0
docs/{tutorial/11-bridge.md => cli/bridge.md} | 0
docs/cli/cli.md | 71 +++
.../10-governance.md => cli/governance.md} | 3 +-
.../key-management.md} | 0
docs/cli/payment.md | 1 +
.../storage-provider.md} | 0
docs/cli/storage.md | 19 +
.../validator-staking.md} | 0
docs/core-concept/accounts.md | 32 ++
docs/core-concept/billing-payment.md | 27 ++
docs/core-concept/gas-fees.md | 48 ++
docs/core-concept/key_management.md | 72 +++
docs/core-concept/storage-metadata-models.md | 128 ++++++
docs/core-concept/transaction-lifecycle.md | 268 +++++++++++
docs/introduction/ecosystem-player.md | 55 +++
docs/introduction/overview.md | 62 +++
docs/introduction/state-world.md | 44 ++
.../token_economics.md} | 8 +-
.../billing_and_payment.md} | 0
.../consensus_and_staking.md} | 0
.../cross-chain.md} | 0
.../data_availability_challenge.md} | 0
.../governance.md} | 4 +-
.../storage_provider_management.md} | 3 +-
docs/readme.md | 16 +
docs/resources/resources.md | 26 ++
docs/run-node/interact-node.md | 163 +++++++
.../run-local-network.md} | 8 +-
docs/run-node/run-mainnet-node.md | 1 +
docs/run-node/run-testnet-node.md | 1 +
docs/tutorial/01-join-mainnet.md | 0
docs/tutorial/02-join-testnet.md | 0
docs/tutorial/06-storage.md | 18 -
docs/tutorial/08-payment.md | 0
docs/tutorial/readme.md | 16 -
readme.md | 4 +-
scripts/protoc-swagger-gen.sh | 2 +-
{docs => swagger-docs}/config.json | 0
{docs => swagger-docs}/docs.go | 0
{docs => swagger-docs}/static/openapi.yml | 0
{docs => swagger-docs}/static/swagger.yaml | 0
{docs => swagger-docs}/statik/init.go | 0
{docs => swagger-docs}/statik/statik.go | 0
.../swagger-ui/favicon-16x16.png | Bin
.../swagger-ui/favicon-32x32.png | Bin
{docs => swagger-docs}/swagger-ui/index.html | 0
.../swagger-ui/oauth2-redirect.html | 0
.../swagger-ui/swagger-ui-bundle.js | 0
.../swagger-ui/swagger-ui-bundle.js.map | 0
.../swagger-ui/swagger-ui-es-bundle-core.js | 0
.../swagger-ui-es-bundle-core.js.map | 0
.../swagger-ui/swagger-ui-es-bundle.js | 0
.../swagger-ui/swagger-ui-es-bundle.js.map | 0
.../swagger-ui-standalone-preset.js | 0
.../swagger-ui-standalone-preset.js.map | 0
.../swagger-ui/swagger-ui.css | 0
.../swagger-ui/swagger-ui.css.map | 0
.../swagger-ui/swagger-ui.js | 0
.../swagger-ui/swagger-ui.js.map | 0
68 files changed, 1151 insertions(+), 643 deletions(-)
rename docs/{architecture/11-events_and_api.md => api-sdk/events.md} (86%)
create mode 100644 docs/api-sdk/grpc_rest.md
create mode 100644 docs/api-sdk/sdk.md
delete mode 100644 docs/architecture/01-overview.md
delete mode 100644 docs/architecture/02-key_management.md
delete mode 100644 docs/architecture/05-storage-metadata-models.md
delete mode 100644 docs/architecture/readme.md
rename docs/{tutorial/05-bank.md => cli/bank.md} (100%)
rename docs/{tutorial/11-bridge.md => cli/bridge.md} (100%)
create mode 100644 docs/cli/cli.md
rename docs/{tutorial/10-governance.md => cli/governance.md} (99%)
rename docs/{tutorial/04-key-management.md => cli/key-management.md} (100%)
create mode 100644 docs/cli/payment.md
rename docs/{tutorial/07-storage-provider.md => cli/storage-provider.md} (100%)
create mode 100644 docs/cli/storage.md
rename docs/{tutorial/09-validator-staking.md => cli/validator-staking.md} (100%)
create mode 100644 docs/core-concept/accounts.md
create mode 100644 docs/core-concept/billing-payment.md
create mode 100644 docs/core-concept/gas-fees.md
create mode 100644 docs/core-concept/key_management.md
create mode 100644 docs/core-concept/storage-metadata-models.md
create mode 100644 docs/core-concept/transaction-lifecycle.md
create mode 100644 docs/introduction/ecosystem-player.md
create mode 100644 docs/introduction/overview.md
create mode 100644 docs/introduction/state-world.md
rename docs/{architecture/03-token_economics.md => introduction/token_economics.md} (83%)
rename docs/{architecture/06-billing_and_payment.md => modules/billing_and_payment.md} (100%)
rename docs/{architecture/08-consensus_and_staking.md => modules/consensus_and_staking.md} (100%)
rename docs/{architecture/07-cross-chain.md => modules/cross-chain.md} (100%)
rename docs/{architecture/10-data_availability_challenge.md => modules/data_availability_challenge.md} (100%)
rename docs/{architecture/09-governance.md => modules/governance.md} (95%)
rename docs/{architecture/04-storage_provider_management.md => modules/storage_provider_management.md} (99%)
create mode 100644 docs/readme.md
create mode 100644 docs/resources/resources.md
create mode 100644 docs/run-node/interact-node.md
rename docs/{tutorial/03-local-network.md => run-node/run-local-network.md} (97%)
create mode 100644 docs/run-node/run-mainnet-node.md
create mode 100644 docs/run-node/run-testnet-node.md
delete mode 100644 docs/tutorial/01-join-mainnet.md
delete mode 100644 docs/tutorial/02-join-testnet.md
delete mode 100644 docs/tutorial/06-storage.md
delete mode 100644 docs/tutorial/08-payment.md
delete mode 100644 docs/tutorial/readme.md
rename {docs => swagger-docs}/config.json (100%)
rename {docs => swagger-docs}/docs.go (100%)
rename {docs => swagger-docs}/static/openapi.yml (100%)
rename {docs => swagger-docs}/static/swagger.yaml (100%)
rename {docs => swagger-docs}/statik/init.go (100%)
rename {docs => swagger-docs}/statik/statik.go (100%)
rename {docs => swagger-docs}/swagger-ui/favicon-16x16.png (100%)
rename {docs => swagger-docs}/swagger-ui/favicon-32x32.png (100%)
rename {docs => swagger-docs}/swagger-ui/index.html (100%)
rename {docs => swagger-docs}/swagger-ui/oauth2-redirect.html (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-bundle.js (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-bundle.js.map (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-es-bundle-core.js (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-es-bundle-core.js.map (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-es-bundle.js (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-es-bundle.js.map (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-standalone-preset.js (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui-standalone-preset.js.map (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui.css (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui.css.map (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui.js (100%)
rename {docs => swagger-docs}/swagger-ui/swagger-ui.js.map (100%)
diff --git a/app/app.go b/app/app.go
index a6c7f2881..d64934dac 100644
--- a/app/app.go
+++ b/app/app.go
@@ -87,7 +87,7 @@ import (
"github.com/bnb-chain/greenfield/app/ante"
appparams "github.com/bnb-chain/greenfield/app/params"
- "github.com/bnb-chain/greenfield/docs"
+ "github.com/bnb-chain/greenfield/swagger-docs"
"github.com/bnb-chain/greenfield/version"
bridgemodule "github.com/bnb-chain/greenfield/x/bridge"
bridgemodulekeeper "github.com/bnb-chain/greenfield/x/bridge/keeper"
diff --git a/docs/architecture/11-events_and_api.md b/docs/api-sdk/events.md
similarity index 86%
rename from docs/architecture/11-events_and_api.md
rename to docs/api-sdk/events.md
index 4926f9aaf..30e0dd54d 100644
--- a/docs/architecture/11-events_and_api.md
+++ b/docs/api-sdk/events.md
@@ -34,3 +34,8 @@ Following are the events that the Greenfield blockchain emits, grouped by module
* [Storage](./proto/greenfield/storage/events.proto)
* [Staking](https://github.com/bnb-chain/gnfd-cosmos-sdk/blob/master/x/staking/spec/07_events.md)
+
+
+This [ADR](https://github.com/bnb-chain/greenfield-cosmos-sdk/blob/master/docs/architecture/adr-032-typed-events.md) also
+proposes adding affordances to emit and consume these events. For developers, they will only need to write `EventHandlers`
+which define the actions they desire to take.
\ No newline at end of file
diff --git a/docs/api-sdk/grpc_rest.md b/docs/api-sdk/grpc_rest.md
new file mode 100644
index 000000000..a7c30b82e
--- /dev/null
+++ b/docs/api-sdk/grpc_rest.md
@@ -0,0 +1,87 @@
+# gRPC, REST, and Tendermint Endpoints
+
+This document presents an overview of all the endpoints a node exposes: gRPC, REST as well as some other endpoints.
+
+## An Overview of All Endpoints
+
+Each node exposes the following endpoints for users to interact with a node, each endpoint is served on a different port.
+Details on how to configure each endpoint is provided in the endpoint's own section.
+
+* the gRPC server (default port: `9090`),
+* the REST server (default port: `1317`),
+* the Tendermint RPC endpoint (default port: `26657`).
+
+::: tip
+The node also exposes some other endpoints, such as the Tendermint P2P endpoint, or the
+[Prometheus endpoint](https://docs.tendermint.com/master/nodes/metrics.html#metrics),
+which are not directly related to the Cosmos SDK. Please refer to the
+[Tendermint documentation](https://docs.tendermint.com/master/tendermint-core/using-tendermint.html#configuration)
+for more information about these endpoints.
+:::
+
+## gRPC Server
+
+In the Greenfield, Protobuf is the main encoding library. This brings a wide range of Protobuf-based tools that can be
+plugged. One such tool is [gRPC](https://grpc.io), a modern open-source high performance RPC framework that has
+decent client support in several languages.
+
+The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC query requests and a broadcast transaction
+request. This server can be configured inside `~/.gnfd/config/app.toml`:
+
+* `grpc.enable = true|false` field defines if the gRPC server should be enabled. Defaults to `true`.
+* `grpc.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`)
+the server should bind to. Defaults to `0.0.0.0:9090`.
+
+:::tip
+`~/.gnfd` is the directory where the node's configuration and databases are stored.
+:::
+
+Once the gRPC server is started, you can send requests to it using a gRPC client. Some examples are given in our
+[Interact with the Node](../run-node/interact-node.md#using-grpc) tutorial.
+
+## REST Server
+
+Greenfield supports REST routes via gRPC-gateway.
+
+All routes are configured under the following fields in `~/.gnfd/config/app.toml`:
+
+* `api.enable = true|false` field defines if the REST server should be enabled. Defaults to `false`.
+* `api.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the
+server should bind to. Defaults to `tcp://0.0.0.0:1317`.
+* some additional API configuration options are defined in `~/.gnfd/config/app.toml`, along with comments,
+please refer to that file directly.
+
+### Swagger
+
+A [Swagger](https://swagger.io/) (or OpenAPIv2) specification file is exposed under the `/swagger` route on the API server.
+Swagger is an open specification describing the API endpoints a server serves, including description, input arguments,
+return types and much more about each endpoint.
+
+Enabling the `/swagger` endpoint is configurable inside `~/.gnfd/config/app.toml` via the `api.swagger` field, which is set to true by default.
+
+
+## Tendermint RPC
+
+Independently from the Cosmos SDK, Tendermint also exposes a RPC server. This RPC server can be configured by tuning
+parameters under the `rpc` table in the `~/.gnfd/config/config.toml`, the default listening address is `tcp://0.0.0.0:26657`.
+An OpenAPI specification of all Tendermint RPC endpoints is available [here](https://docs.tendermint.com/master/rpc/).
+
+Some Tendermint RPC endpoints are directly related to the Cosmos SDK:
+
+* `/abci_query`: this endpoint will query the application for state. As the `path` parameter, you can send the following strings:
+ * any Protobuf fully-qualified service method, such as `/cosmos.bank.v1beta1.QueryAllBalances`. The `data` field should then include the method's request parameter(s) encoded as bytes using Protobuf.
+ * `/app/simulate`: this will simulate a transaction, and return some information such as gas used.
+ * `/app/version`: this will return the application's version.
+ * `/store/{path}`: this will query the store directly.
+ * `/p2p/filter/addr/{port}`: this will return a filtered list of the node's P2P peers by address port.
+ * `/p2p/filter/id/{id}`: this will return a filtered list of the node's P2P peers by ID.
+* `/broadcast_tx_{aync,async,commit}`: these 3 endpoint will broadcast a transaction to other peers. CLI, gRPC and REST expose a way to broadcast transations, but they all use these 3 Tendermint RPCs under the hood.
+
+## Comparison Table
+
+| Name | Advantages | Disadvantages |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| gRPC | - can use code-generated stubs in various languages
- supports streaming and bidirectional communication (HTTP2)
- small wire binary sizes, faster transmission | - based on HTTP2, not available in browsers
- learning curve (mostly due to Protobuf) |
+| REST | - ubiquitous
- client libraries in all languages, faster implementation
| - only supports unary request-response communication (HTTP1.1)
- bigger over-the-wire message sizes (JSON) |
+| Tendermint RPC | - easy to use | - bigger over-the-wire message sizes (JSON) |
+
diff --git a/docs/api-sdk/sdk.md b/docs/api-sdk/sdk.md
new file mode 100644
index 000000000..aca6bfcdb
--- /dev/null
+++ b/docs/api-sdk/sdk.md
@@ -0,0 +1,8 @@
+# Greenfield Development Kit
+
+## Official SDK
+- [Official Go implementation SDK](https://github.com/bnb-chain/greenfield-go-sdk)
+- [Official JS implementation SDK](https://github.com/bnb-chain/gnfd-js-sdk)
+
+
+
diff --git a/docs/architecture/01-overview.md b/docs/architecture/01-overview.md
deleted file mode 100644
index c4a1fad63..000000000
--- a/docs/architecture/01-overview.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# Overview
-
-BNB Greenfield blockchain uses Proof-of-Stake based on Tendermint-consensus for its own network security. Blocks are
-created every 2 seconds on the Greenfield chain by a group of validators.
-
-BNB will be the gas and governance token on this blockchain. There is a native cross-chain bridge between the Greenfield
-blockchain and BSC. The initial BNB will be locked on BSC and re-minted on Greenfield. BNB and data operation primitives
-can flow between Greenfield and BSC.
-
-Total circulation of BNB will stay unchanged as it is now but flow among BNB Beacon Chain, BSC, and Greenfield.
-
-The validator election and governance are based on a proposal-vote mechanism, which is revised based on Cosmos SDK's
-governance module: anyone can create and propose to become a validator, and the election into the active set will be
-based on the stake ranking (initially new validators may request the existing validator set's votes to be qualified for
-election). As validators will host all the critical metadata and respond to all data operation transactions, they should
-run professionally in terms of performance and stability.
-
-To facilitate cross-chain operation and convenient asset management, the address format of the Greenfield blockchain
-will be fully compatible with BSC (and Ethereum). It also accepts EIP712 transaction signing and verification. These
-enable the existing wallet infrastructure to interact with Greenfield at the beginning naturally.
-
-## Ecosystem Players
-There are several player roles for the whole Greenfield ecosystem.
-
-
-Figure All Players of Greenfield
-
-### Greenfield Validators
-
-As a PoS blockchain, the Greenfield blockchain has its own validators.
-These validators are elected based on the Proof-of-Stake logic.
-
-These validators are responsible for the security of the Greenfield
-blockchain. They get involved in the governance and staking of the
-blockchain. They form a P2P network that is similar to other PoS
-blockchain networks.
-
-Meanwhile, they accept and process transactions to allow users to
-operate their objects stored on Greenfield. They maintain the metadata
-of Greenfield as the blockchain state, which is the control panel for
-both Storage Providers (SPs) and users. These two parties use and update
-these states to operate the object storage.
-
-Greenfield validators also have the obligation to run the relayer system
-for cross-chain communication with BSC.
-
-The network topology of Greenfield validators is similar to the existing
-secure validator setup of PoS blockchains. "Sentry Nodes" are used to
-defend against DDoS and provide a secure private network, as shown in
-the below diagram.
-
-
-Figure Greenfield Blockchain Network
-
-### Storage Providers (SPs)
-
-Storage Providers are professional individuals and organizations who run
-a series of services to provide data services based on the Greenfield
-blockchain.
-
-### Greenfield dApps
-
-Greenfield dApps are applications that provide functions based on
-Greenfield storage and its related economic traits to solve some
-problems of their users.
-
-## Greenfield Blockchain Data Storage
-All Greenfield validators have such active data in full (at least the latest state). Anyone can join the blockchain as
-full nodes to synchronize these data for free.
-
-These data are on-chain and can be only changed through transactions onto the Greenfield blockchain. It has several types
-as described below.
-
-### Accounts and Balance
-Each user has their "Owner Address" as the identifier for their owner account to "own" the data resources. There is
-another "payment account" type dedicated to billing and payment purposes and owned by owner addresses.
-
-Both owner accounts and payment accounts can hold the BNB balance on Greenfield. Users can deposit BNB from BSC, accept
-transfers from other users, and spend them on transaction gas and storage usage.
-
-### Validator and SP Metadata
-These are the basic information about the Greenfield validators and Greenfield SPs. SPs may have more information, as
-it has to publish their service information for users' data operations. There should be a reputation mechanism for SPs
-as well.
-
-### Storage Metadata
-The "storage metadata" includes size, ownership, checksum hashes, and distribution location among SPs. Similar to AWS S3,
-the basic unit of the storage is an "object", which can be a piece of binary data, text files, photos, videos, or any
-other format. Users can create their objects under their "bucket". A bucket is globally unique. The object can be referred
-to via the bucket name and the object ID. It can also be located by the bucket name, the prefix tag, and the object ID
-via off-chain facilitations.
-
-### Permission Metadata
-Data resources on Greenfield, such as the data objects and the buckets, all have access control, such as which address
-can create, read, list, or even execute the resources, and which address can grant/revoke these permissions.
-
-Two other data resources also have access control. One is "Group". A group represents a group of user addresses that have
-the same permissions to the same resources. It can be used in the same way as an address in the access control. Meanwhile,
-it requires permission too to change the group. The other is "payment account". They are created by the owner accounts.
-
-Here the access control is enforced by the SPs off-chain. People can test and challenge the SPs if they mess up the
-control. Slash and reward will happen to keep the SPs sticking to the principles.
-
-### Billing Metadata
-Users have to pay fees to store data objects on Greenfield. While each object enjoys a free quota to download by users
-who are permitted to, the excessive download will require extra data packages to be paid for the bandwidth. Besides
-the owner address, users can derive multiple "Payment Addresses" to pay these fees. Objects are stored under buckets,
-while each bucket can be associated with these payment addresses, and the system will charge these accounts for storing
-and/or downloading. Many buckets can share the same payment address. Such association information is also stored on
-chains with consensus as well.
\ No newline at end of file
diff --git a/docs/architecture/02-key_management.md b/docs/architecture/02-key_management.md
deleted file mode 100644
index a906358ba..000000000
--- a/docs/architecture/02-key_management.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Key Management
-
-The [greenfield-cosmos-sdk](https://github.com/bnb-chain/greenfield-cosmos-sdk) provides a flexible and secure way to manage private keys for blockchain applications. The `Keyring` interface is used to define the methods that a type needs to implement to be used as a key storage backend. This document provides an overview of the different backend options available and the supported sign algorithms.
-
-And to interact with BSC(BNB-smart-chain) more convinent and user-friendly, we add [EIP-712](https://eips.ethereum.org/EIPS/eip-712) support. Any Etherrum wallet could connect to a greenfield node and sign a EIP-712 transaction directly.
-
-## EIP-712 Support
-
-The greenfield chain supports and only supports EIP-712 structured transaction. To achieve this, the following changes have been made.
-
-1. An Ethereum-compatible RPC backend. Be noted that we only support necessacry methods to connect a wallet(`eth_chainId`, `eth_networkId`, `eth_blockNumber`, `eth_getBlockByNumber` and `eth_getBalance`). Other RPC methods are not implemented.
-2. Same signing algorithm(`eth_scep256k1`) as Ethereum.
-
-For developers, they can refer to [greenfield-go-sdk](https://github.com/bnb-chain/greenfield-go-sdk) and [greenfield-js-sdk](https://github.com/bnb-chain/greenfield-js-sdk) for more infos.
-
-## Keyring Interface
-
-The `Keyring` interface is the primary interface for key management in the greenfield-cosmos-sdk. It defines the methods that a type needs to implement to be used as a key storage backend. These methods include:
-
-- `Get`: retrieves a key by name.
-- `List`: lists all keys stored in the keyring.
-- `Delete`: deletes a key by name.
-- `Sign`: signs a message using a key.
-
-By implementing these methods, you can create a custom key storage backend that meets the specific needs of your application.
-
-## Backend Options
-
-The greenfield-cosmos-sdk provides several backend options for key storage. Each backend has its own strengths and weaknesses, and the choice of backend will depend on your specific use case. Here are the available options:
-
-1. **os**: The os backend uses the operating system's default credentials store to handle key storage operations securely. The keyring may be kept unlocked for the whole duration of the user session.
-
-2. **file**: This backend more closely resembles the previous keyring storage used prior to cosmos-sdk v0.38.1. It stores the keyring encrypted within the app's configuration directory. This keyring will request a password each time it is accessed, which may occur multiple times in a single command resulting in repeated password prompts.
-
-3. **kwallet**: This backend uses the KDE Wallet Manager as a credentials management application.
-
-4. **pass**: This backend uses the `pass` command line utility to store and retrieve keys.
-
-5. **test**: This backend stores keys insecurely to disk. It does not prompt for a password to be unlocked and should only be used for testing purposes.
-
-6. **memory**: This backend uses a transient storage. Keys are discarded when the process terminates or the type instance is garbage collected.
-
-## Supported Sign Algorithms
-
-The greenfield-cosmos-sdk supports as many sign algorithms as users want, but in Greenfield's context, we only support `eth_secp256k1` and `ed25519`. These algorithms were chosen for their security and compatibility with the Ethereum and Tendermint ecosystems.
-
-## Conclusion
-
-In conclusion, key management is a critical aspect of building secure blockchain applications. By understanding the available backend options and supported sign algorithms in the greenfield-cosmos-sdk, you can build applications that are both secure and user-friendly. The `Keyring` interface provides a flexible way to manage private keys, and by implementing the required methods, you can create a custom key storage backend that meets the specific needs of your application.
diff --git a/docs/architecture/05-storage-metadata-models.md b/docs/architecture/05-storage-metadata-models.md
deleted file mode 100644
index e377623ec..000000000
--- a/docs/architecture/05-storage-metadata-models.md
+++ /dev/null
@@ -1,417 +0,0 @@
-# Storage MetaData Models
-
-## Abstract
-Below are the basic data models for Greenfield storage:
-
-- bucket
-- object
-- group
-- permission
-
-These metadata are stored as blockchain state into the persistent storage of the Greenfield blockchain.
-
-## Concepts
-
-### Bucket
-
-Bucket is the unit to group storage "objects". BucketName has to be globally unique. Every user account can create a
-bucket. The account will become the "owner" of the bucket.
-
-Each bucket should be associated with its own Primary SP, and the payment accounts for Read and Store. The owner's
-address will be the default payment account.
-
-### Object
-
-Object is the basic unit to store data on Greenfield. The metadata for the object will be stored on the Greenfield
-blockchain:
-
-- name and ID
-- owner
-- bucket that hosts it
-- size and timestamps
-- content type
-- checkSums for the storage pieces
-- storage status
-- associated SP information
-
-Object metadata is stored with the bucket name as the prefix of the key. It is possible to iterate through all
-objects under the same bucket, but it may be a heavy-lifting job for a large bucket with lots of objects.
-
-### Group
-
-A Group is a collection of accounts with the same permissions. The group name is not allowed to be duplicated under the
-same user. However, a group can not create or own any resource. A group can not be a member of another group either.
-
-A resource can only have a limited number of groups associated with it for permissions. This ensures that the on-chain
-permission check can be finished within a constant time.
-
-## State
-
-The storage module keeps state of the following primary objects:
-
-* BucketInfo
-* ObjectInfo
-* GroupInfo
-
-These primary objects should be primarily stored and accessed by the `ID` which is a auto-incremented sequence. An
-additional indices are maintained per primary objects in order to compatibility with the S3 object storage.
-
-* BucketInfo: `0x11 | hash(bucketName) -> BigEndian(bucketId)`
-* ObjectInfo: `0x12 | hash(bucketName)_hash(objectName) -> BigEndian(objectId)`
-* GroupInfo: `0x13 | OwnerAddr_hash(groupName) -> BigEndian(groupId)`
-
-* BucketInfoById: `0x21 | BigEndian(bucketId) -> ProtoBuf(BucketInfo)`
-* ObjectInfoById: `0x22 | BigEndian(objectId) -> ProtoBuf(ObjectInfo)`
-* GroupInfoById: `0x23 | BigEndian(groupId) -> ProtoBuf(GroupInfo)`
-
-```protobuf
-message BucketInfo {
- // owner is the account address of bucket creator, it is also the bucket owner.
- string owner = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is a globally unique name of bucket
- string bucket_name = 2;
- // is_public define the highest permissions for bucket. When the bucket is public, everyone can get the object in it.
- bool is_public = 3;
- // id is the unique identification for bucket.
- string id = 4 [
- (cosmos_proto.scalar) = "cosmos.Uint",
- (gogoproto.customtype) = "Uint",
- (gogoproto.nullable) = false
- ];
- // source_type define the source of the bucket
- SourceType source_type = 5;
- // create_at define the block number when the bucket created.
- int64 create_at = 6;
- // payment_address is the address of the payment account
- string payment_address = 7 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // primary_sp_address is the address of the primary sp. Objects belongs to this bucket will never
- // leave this SP, unless you explicitly shift them to another SP.
- string primary_sp_address = 8 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // read_quota defines the traffic quota for read
- ReadQuota read_quota = 9;
- // payment_price_time TODO(Owen): refine the comments
- int64 payment_price_time = 10;
- // payment_out_flows
- repeated payment.OutFlowInUSD payment_out_flows = 11 [(gogoproto.nullable) = false];
-}
-
-message ObjectInfo {
- string owner = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is the name of the bucket
- string bucket_name = 2;
- // object_name is the name of object
- string object_name = 3;
- // id is the unique identifier of object
- string id = 4 [
- (cosmos_proto.scalar) = "cosmos.Uint",
- (gogoproto.customtype) = "Uint",
- (gogoproto.nullable) = false
- ];
- // payloadSize is the total size of the object payload
- uint64 payload_size = 5;
- // is_public define the highest permissions for object. When the object is public, everyone can access it.
- bool is_public = 6;
- // content_type define the format of the object which should be a standard MIME type.
- string content_type = 7;
- // create_at define the block number when the object created
- int64 create_at = 8;
- // object_status define the upload status of the object.
- ObjectStatus object_status = 9;
- // redundancy_type define the type of the redundancy which can be multi-replication or EC.
- RedundancyType redundancy_type = 10;
- // source_type define the source of the object.
- SourceType source_type = 11;
- // checksums define the root hash of the pieces which stored in a SP.
- repeated bytes checksums = 12;
- // secondary_sp_addresses define the addresses of secondary_sps
- repeated string secondary_sp_addresses = 13 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // lockedBalance
- string lockedBalance = 14 [
- (cosmos_proto.scalar) = "cosmos.Int",
- (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int"
- ];
-}
-
-message GroupInfo {
- // owner is the owner of the group. It can not changed once created.
- string owner = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // group_name is the name of group which is unique under an account.
- string group_name = 2;
- // source_type
- SourceType source_type = 3;
- // id is the unique identifier of group
- string id = 4 [
- (cosmos_proto.scalar) = "cosmos.Uint",
- (gogoproto.customtype) = "Uint",
- (gogoproto.nullable) = false
- ];
-}
-```
-
-### Params
-
-The storage module contains the following parameters,
-they can be updated with governance.
-
-```protobuf
-// Params defines the parameters for the module.
-message Params {
- // TODO: We should think more about the version-control of the storage params.
- option (gogoproto.goproto_stringer) = false;
-
- // max_segment_size is the maximum size of a segment. default: 16M
- uint64 max_segment_size = 1;
- // redundant_data_check_num is the num of data chunks of EC redundancy algorithm
- uint32 redundant_data_chunk_num = 2;
- // redundant_data_check_num is the num of parity chunks of EC redundancy algorithm
- uint32 redundant_parity_chunk_num = 3;
- // max_payload_size is the maximum size of the payload, default: 2G
- uint64 max_payload_size = 4;
-}
-```
-
-* the max_segment_size/redundant_data_chunk_num/redundant_parity_chunk_num is for redundancy algorithm
-* the max_payload_size is a limit on the size of objects uploaded by users
-
-## Keepers
-
-The storage module keeper provides access to query the parameters, bucketInfo, objectInfo, groupInfo and several
-interface for Create/Delete/Update the resources.
-
-
-## Messages
-
-### MsgCreateBucket
-
-Used to create bucket for user
-
-```protobuf
-message MsgCreateBucket {
- option (cosmos.msg.v1.signer) = "creator";
-
- // creator is the account address of bucket creator, it is also the bucket owner.
- string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is a globally unique name of bucket
- string bucket_name = 2;
- // is_public means the bucket is private or public. if private, only bucket owner or grantee can read it,
- // otherwise every greenfield user can read it.
- bool is_public = 3;
- // payment_address is an account address specified by bucket owner to pay the read fee. Default: creator
- string payment_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // primary_sp_address is the address of primary sp.
- string primary_sp_address = 6 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // primary_sp_approval is the approval info of the primary SP which indicates that primary sp confirm the user's request.
- Approval primary_sp_approval = 7;
- // read_quota
- ReadQuota read_quota = 8;
-}
-```
-
-### MsgDeleteBucket
-
-Used to delete bucket for user. It is important to note that you cannot delete a non-empty bucket.
-
-```protobuf
-message MsgDeleteBucket {
- option (cosmos.msg.v1.signer) = "operator";
-
- // creator is the account address of the grantee who has the DeleteBucket permission of the bucket to be deleted.
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-
- // bucket_name is the name of the bucket to be deleted.
- string bucket_name = 2;
-}
-```
-
-### MsgUpdateBucketInfo
-Used to update bucket info for user.
-
-```protobuf
-message MsgUpdateBucketInfo {
- option (cosmos.msg.v1.signer) = "operator";
-
- // operator is the account address of the operator
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-
- // bucket_name is the name of bucket which you'll update
- string bucket_name = 2;
-
- // read_quota is the traffic quota that you read from primary sp
- ReadQuota read_quota = 3;
-
- // payment_address is the account address of the payment account
- string payment_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-}
-```
-
-### MsgCreateObject
-
-Used to create object under a bucket for user.
-
-```protobuf
-message MsgCreateObject {
- option (cosmos.msg.v1.signer) = "creator";
-
- // creator is the account address of object uploader
- string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is the name of the bucket where the object is stored.
- string bucket_name = 2;
- // object_name is the name of object
- string object_name = 3;
- // payload_size is size of the object's payload
- uint64 payload_size = 4;
- // is_public means the bucket is private or public. if private, only bucket owner or grantee can access it,
- // otherwise every greenfield user can access it.
- bool is_public = 5;
- // content_type is a standard MIME type describing the format of the object.
- string content_type = 6;
- // primary_sp_approval is the approval info of the primary SP which indicates that primary sp confirm the user's request.
- Approval primary_sp_approval = 7;
- // expect_checksums is a list of hashes which was generate by redundancy algorithm.
- repeated bytes expect_checksums = 8;
- // redundancy_type can be ec or replica
- RedundancyType redundancy_type = 9;
- // expect_secondarySPs is a list of StorageProvider address, which is optional
- repeated string expect_secondary_sp_addresses = 10 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-}
-
-```
-### MsgDeleteObject
-
-Used to delete object for user.
-
-```protobuf
-message MsgDeleteObject {
- option (cosmos.msg.v1.signer) = "operator";
-
- // operator is the account address of the operator who has the DeleteObject permission of the object to be deleted.
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is the name of the bucket where the object which to be deleted is stored.
- string bucket_name = 2;
- // object_name is the name of the object which to be deleted.
- string object_name = 3;
-}
-
-```
-### MsgSealObject
-
-Used to seal object for storage provider.
-
-```protobuf
-message MsgSealObject {
- option (cosmos.msg.v1.signer) = "operator";
-
- // operator is the account address of primary SP
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is the name of the bucket where the object is stored.
- string bucket_name = 2;
- // object_name is the name of object to be sealed.
- string object_name = 3;
- // secondary_sp_addresses is a list of storage provider which store the redundant data.
- repeated string secondary_sp_addresses = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // secondary_sp_signatures is the signature of the secondary sp that can
- // acknowledge that the payload data has received and stored.
- repeated bytes secondary_sp_signatures = 5;
-}
-
-```
-### MsgCopyObject
-
-Used to copy object for user.
-
-```protobuf
-message MsgCopyObject {
- option (cosmos.msg.v1.signer) = "operator";
-
- // operator is the account address of the operator who has the CopyObject permission of the object to be deleted.
- string operator = 1;
- // src_bucket_name is the name of the bucket where the object to be copied is located
- string src_bucket_name = 2;
- // dst_bucket_name is the name of the bucket where the object is copied to.
- string dst_bucket_name = 3;
- // src_object_name is the name of the object which to be copied
- string src_object_name = 4;
- // dst_object_name is the name of the object which is copied to
- string dst_object_name = 5;
- // primary_sp_approval is the approval info of the primary SP which indicates that primary sp confirm the user's request.
- Approval dst_primary_sp_approval = 6;
-}
-```
-### MsgRejectSealObject
-
-Used to reject seal object for sp.
-
-```protobuf
-message MsgRejectSealObject {
- option (cosmos.msg.v1.signer) = "operator";
- // operator is the account address of the object owner
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is the name of the bucket where the object is stored.
- string bucket_name = 2;
- // object_name is the name of unsealed object to be reject.
- string object_name = 3;
-}
-```
-### MsgCancelCreateObject
-
-Used to cancel create object for user.
-
-```protobuf
-message MsgCancelCreateObject {
- option (cosmos.msg.v1.signer) = "operator";
- // operator is the account address of the operator
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // bucket_name is the name of the bucket
- string bucket_name = 2;
- // object_name is the name of the object
- string object_name = 3;
-}
-```
-### MsgCreateGroup
-
-Used to create group for user.
-
-```protobuf
-message MsgCreateGroup {
- option (cosmos.msg.v1.signer) = "creator";
-
- // owner is the account address of group owner who create the group
- string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // group_name is the name of the group. it's not globally unique.
- string group_name = 2;
- // member_request is a list of member which to be add or remove
- repeated string members = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-}
-```
-### MsgDeleteGroup
-
-Used to delete group for user.
-
-```protobuf
-message MsgDeleteGroup {
- option (cosmos.msg.v1.signer) = "operator";
-
- // operator is the account address of the operator who has the DeleteGroup permission of the group to be deleted.
- string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // group_name is the name of the group which to be deleted
- string group_name = 2;
-}
-
-```
-### MsgLeaveGroup
-
-Used to leave a group for group member
-
-```protobuf
-message MsgLeaveGroup {
- option (cosmos.msg.v1.signer) = "member";
-
- // member is the account address of the member who want to leave the group
- string member = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // group_owner is the owner of the group you want to leave
- string group_owner = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // group_name is the name of the group you want to leave
- string group_name = 3;
-}
-```
-
diff --git a/docs/architecture/readme.md b/docs/architecture/readme.md
deleted file mode 100644
index 44a16566f..000000000
--- a/docs/architecture/readme.md
+++ /dev/null
@@ -1,16 +0,0 @@
-## Overview
-This section dives into the internals of the Greenfield Blockchain implementation.
-
-### Table of Contents
-
-- [Overview](./01-overview.md)
-- [Key Management](./02-key_management.md)
-- [Token Economics](./03-token_economics.md)
-- [Storage Provider Management](./04-storage_provider_management.md)
-- [Storage Metadata Models](./05-storage-metadata-models.md)
-- [Billing and Payment](./06-billing_and_payment.md)
-- [Cross Chain](./07-cross-chain.md)
-- [Consensus and Staking](./08-consensus_and_staking.md)
-- [Governance](./09-governance.md)
-- [Data Availability Challenge](./10-data_availability_challenge.md)
-- [Event and API](./11-events_and_api.md)
\ No newline at end of file
diff --git a/docs/tutorial/05-bank.md b/docs/cli/bank.md
similarity index 100%
rename from docs/tutorial/05-bank.md
rename to docs/cli/bank.md
diff --git a/docs/tutorial/11-bridge.md b/docs/cli/bridge.md
similarity index 100%
rename from docs/tutorial/11-bridge.md
rename to docs/cli/bridge.md
diff --git a/docs/cli/cli.md b/docs/cli/cli.md
new file mode 100644
index 000000000..7b9d10997
--- /dev/null
+++ b/docs/cli/cli.md
@@ -0,0 +1,71 @@
+# Command-Line Interface
+
+## Command-Line Interface
+
+
+There is no set way to create a CLI, but Greenfield typically use the [Cobra Library](https://github.com/spf13/cobra).
+Building a CLI with Cobra entails defining commands, arguments, and flags. Commands understand the
+actions users wish to take, such as `tx` for creating a transaction and `query` for querying the application.
+Each command can also have nested subcommands, necessary for naming the specific transaction type.
+Users also supply **Arguments**, such as account numbers to send coins to, and [**Flags**](#flags) to modify various
+aspects of the commands, such as gas prices or which node to broadcast to.
+
+### Transaction Command
+Here is an example of a command a user might enter to interact with `gnfd` in order to send some tokens:
+
+```bash
+$ gnfd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000BNB--gas auto
+```
+
+The first four strings specify the command:
+
+* The subcommand `tx`, which contains all commands that let users create transactions.
+* The subcommand `bank` to indicate which module to route the command to `x/bank` module in this case).
+* The type of transaction `send`.
+
+The next two strings are arguments: the `from_address` the user wishes to send from, the `to_address` of the recipient,
+and the `amount` they want to send. Finally, the last few strings of the command are optional flags to indicate
+how much the user is willing to pay in fees.
+
+### Query Commands
+
+Queries are objects that allow users to retrieve information about the application's state.
+
+This `queryCommand` function adds all the queries available to end-users for the application. This typically includes:
+
+* **QueryTx** and/or other transaction query commands] from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
+* **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address.
+* **Validator command** from the Cosmos SDK rpc client tools, which displays the validator set of a given height.
+* **Block command** from the Cosmos SDK rpc client tools, which displays the block data for a given height.
+* **All module query commands the application is dependent on,
+
+Here is an example of a `queryCommand`:
+
+```shell
+## query the metadata of BNB
+$ gnfd q bank denom-metadata --node tcp://127.0.0.1:26750
+```
+
+## Environment variables
+
+Each flag is bound to it's respecteve named environment variable. Then name of the environment variable consist of two parts
+- capital case `basename` followed by flag name of the flag. `-` must be substituted with `_`.
+- For example flag `--home` for application with basename `GNFD` is bound to `GNFD_HOME`. It allows reducing
+the amount of flags typed for routine operations. For example instead of:
+
+```sh
+gnfd --home=./ --node= --chain-id="testchain-9000" --keyring-backend=test tx ... --from=
+```
+
+this will be more convenient:
+
+```sh
+# define env variables in .env, .envrc etc
+GNFD_HOME=
+GNFD_NODE=
+GNFD_CHAIN_ID="testchain-9000"
+GNFD_KEYRING_BACKEND="test"
+
+# and later just use
+gnfd tx ... --from=
+```
diff --git a/docs/tutorial/10-governance.md b/docs/cli/governance.md
similarity index 99%
rename from docs/tutorial/10-governance.md
rename to docs/cli/governance.md
index 9d50902b6..31c546244 100644
--- a/docs/tutorial/10-governance.md
+++ b/docs/cli/governance.md
@@ -1,5 +1,6 @@
-## Quick Start
+# Using gnfd command to interact with governance module
+## Quick Start
Start a local cluster:
diff --git a/docs/tutorial/04-key-management.md b/docs/cli/key-management.md
similarity index 100%
rename from docs/tutorial/04-key-management.md
rename to docs/cli/key-management.md
diff --git a/docs/cli/payment.md b/docs/cli/payment.md
new file mode 100644
index 000000000..ae9355464
--- /dev/null
+++ b/docs/cli/payment.md
@@ -0,0 +1 @@
+# Using gnfd command to interact with payment module (TODO)
diff --git a/docs/tutorial/07-storage-provider.md b/docs/cli/storage-provider.md
similarity index 100%
rename from docs/tutorial/07-storage-provider.md
rename to docs/cli/storage-provider.md
diff --git a/docs/cli/storage.md b/docs/cli/storage.md
new file mode 100644
index 000000000..fed1c71d7
--- /dev/null
+++ b/docs/cli/storage.md
@@ -0,0 +1,19 @@
+# Using gnfd command to interact with storage module
+
+## HeadBucket
+
+```shell
+gnfd query storage head-bucket [bucket-name] [flags]
+```
+
+## HeadObject
+
+```shell
+gnfd query storage head-object [bucket-name] [object-name] [flags]
+```
+
+# Others operations
+Interacting with the storage module involves a lot of interface interactions with the Storage Provider in order to
+complete tasks such as obtaining authentication information and sending request data. As a result, a single gnfd client
+cannot complete the entire process, such as obtaining an approval signature from the SP. Therefore, we
+recommend using more powerful [greenfield commands](https://github.com/bnb-chain/greenfield-cmd) to complete such transactions and queries.
\ No newline at end of file
diff --git a/docs/tutorial/09-validator-staking.md b/docs/cli/validator-staking.md
similarity index 100%
rename from docs/tutorial/09-validator-staking.md
rename to docs/cli/validator-staking.md
diff --git a/docs/core-concept/accounts.md b/docs/core-concept/accounts.md
new file mode 100644
index 000000000..2a34da092
--- /dev/null
+++ b/docs/core-concept/accounts.md
@@ -0,0 +1,32 @@
+# Accounts
+
+This document describes the in-built account and public key system of the Greenfield
+
+## Account Definition
+
+In the Greenfield, an _account_ designates a pair of _public key_ `PubKey` and _private key_ `PrivKey`.
+The `PubKey` can be derived to generate various `Addresses`, which are used to identify users (among other parties) in
+the application.
+
+## Signatures
+
+The principal way of authenticating a user is done using [digital signatures](https://en.wikipedia.org/wiki/Digital_signature).
+Users sign transactions using their own private key. Signature verification is done with the associated public key.
+For on-chain signature verification purposes, we store the public key in an `Account` object (alongside other data required
+for a proper transaction validation).
+
+In the node, all data is stored using Protocol Buffers serialization.
+
+Greenfield only supports `secp256k1` key schemes for creating digital signatures:
+
+| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) |
+| :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: |
+| `secp256k1` | 20 | 33 | yes | no |
+
+## Addresses
+
+`Addresses` and `PubKey`s are both public information that identifies actors in the application. `Account` is used to
+store authentication information. The basic account implementation is provided by a `BaseAccount` object.
+
+Unlike Cosmos SDK who defines 3 types of addresses: `AccAddress`,
+`ValAddress` and `ConsAddress`, Greenfield only use the `AccAddress`, and the address format follows [ERC-55](https://eips.ethereum.org/EIPS/eip-55).
\ No newline at end of file
diff --git a/docs/core-concept/billing-payment.md b/docs/core-concept/billing-payment.md
new file mode 100644
index 000000000..d9357a39b
--- /dev/null
+++ b/docs/core-concept/billing-payment.md
@@ -0,0 +1,27 @@
+# Billing and Payment
+
+Greenfield will charge the users in two parts. Firstly, every
+transaction will require gas fees to pay the Greenfield validator to
+write the metadata on-chain. Secondly, the SPs charge the users for
+their storage service. Such payment also happens on the Greenfield. This
+document is about the latter: how such off-chain service fees are billed
+and charged.
+
+There are two kinds of fees for the off-chain service: object storage
+fee and read fee:
+
+1. Every object stored on Greenfield is charged a fee based on its
+ size. The storage price is determined by the service providers.
+
+2. There is a free quota for users' objects to be read based on their
+ size, content types, and more. If exceeded, i.e. the object data
+ has been downloaded too many times, SP will limit the bandwidth
+ for more downloads. Users can raise their read quota to
+ get more download quota. The read quota price is determined by the
+ Primary Storage Provider users selected.
+
+The fees are paid on Greenfield in the style of
+"Stream" from users to the SPs at a constant rate. The fees are charged
+every second as they are used.
+
+For more tech details, please refer to the [stream payment module design](../modules/billing_and_payment.md).
\ No newline at end of file
diff --git a/docs/core-concept/gas-fees.md b/docs/core-concept/gas-fees.md
new file mode 100644
index 000000000..0614bfe90
--- /dev/null
+++ b/docs/core-concept/gas-fees.md
@@ -0,0 +1,48 @@
+# Gas and Fees
+
+This document describes how Greenfield charge fee to different transaction types.
+
+## Introduction to `Gas` and `Fees`
+
+In the Cosmos SDK, `gas` is a special unit that is used to track the consumption of resources during execution.
+
+However, on application-specific blockchains like Greenfield, the primary factor determining the transaction fee
+is no longer the computational cost of storage, but rather the incentive mechanism of Greenfield. For example,
+creating and deleting a storage object consumes similar I/O and computational resources, but Greenfield
+incentivizes users to delete unused storage objects to free up more storage space, resulting in much cheaper
+transaction fees for the latter.
+
+Therefore, we abandoned the gas meter design of cosmos-sdk and redesigned the gashub module to determine the gas
+consumption based on the type and content of the transaction, rather than the consumption of storage and computational resources.
+
+
+## GasHub
+All transaction types need to register their gas calculation logic to gashub. Currently, four types of calculation logic
+are supported:
+
+```go
+type MsgGasParams_FixedType struct {
+ FixedType *MsgGasParams_FixedGasParams
+}
+type MsgGasParams_GrantType struct {
+ GrantType *MsgGasParams_DynamicGasParams
+}
+type MsgGasParams_MultiSendType struct {
+ MultiSendType *MsgGasParams_DynamicGasParams
+}
+type MsgGasParams_GrantAllowanceType struct {
+ GrantAllowanceType *MsgGasParams_DynamicGasParams
+}
+```
+
+### Block Gas Meter
+
+`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit.
+
+However, Greenfield may charge a substantial fee for certain types of transactions, resulting in significant gas
+consumption. As a result, Greenfield does not impose any limitations on the gas usage of a block. Greenfield limits the
+block size to under 1MB in order to prevent excessively large blocks.
+
+## Fee Table
+TODO(coming soon)
+
diff --git a/docs/core-concept/key_management.md b/docs/core-concept/key_management.md
new file mode 100644
index 000000000..a315178bd
--- /dev/null
+++ b/docs/core-concept/key_management.md
@@ -0,0 +1,72 @@
+# Key Management
+
+The [greenfield-cosmos-sdk](https://github.com/bnb-chain/greenfield-cosmos-sdk) provides a flexible and secure way to
+manage private keys for blockchain applications. The `Keyring` interface is used to define the methods that a type needs
+to implement to be used as a key storage backend. This document provides an overview of the different backend
+options available and the supported sign algorithms.
+
+And to interact with BSC(BNB-smart-chain) more convinent and user-friendly, we add
+[EIP-712](https://eips.ethereum.org/EIPS/eip-712) support. Any Etherrum wallet could connect to
+a greenfield node and sign an EIP-712 transaction directly.
+
+## EIP-712 Support
+
+The greenfield chain supports and only supports EIP-712 structured transaction. These enable the existing wallet
+infrastructure to interact with Greenfield at the beginning naturally.
+
+To achieve this, the following changes have been made.
+
+1. An Ethereum-compatible RPC backend. Be noted that we only support necessacry methods to connect a
+ wallet(`eth_chainId`, `eth_networkId`, `eth_blockNumber`, `eth_getBlockByNumber` and `eth_getBalance`). Other RPC methods are not implemented.
+2. Same signing algorithm(`eth_scep256k1`) as Ethereum.
+
+For developers, they can refer to [greenfield-go-sdk](https://github.com/bnb-chain/greenfield-go-sdk) and
+[greenfield-js-sdk](https://github.com/bnb-chain/greenfield-js-sdk) for more infos.
+
+## Keyring Interface
+
+The `Keyring` interface is the primary interface for key management in the greenfield-cosmos-sdk. It defines the methods
+that a type needs to implement to be used as a key storage backend. These methods include:
+
+- `Get`: retrieves a key by name.
+- `List`: lists all keys stored in the keyring.
+- `Delete`: deletes a key by name.
+- `Sign`: signs a message using a key.
+
+By implementing these methods, you can create a custom key storage backend that meets the specific needs of your application.
+
+## Backend Options
+
+The greenfield-cosmos-sdk provides several backend options for key storage. Each backend has its own strengths and
+weaknesses, and the choice of backend will depend on your specific use case. Here are the available options:
+
+1. **os**: The os backend uses the operating system's default credentials store to handle key storage operations securely.
+The keyring may be kept unlocked for the whole duration of the user session.
+
+2. **file**: This backend more closely resembles the previous keyring storage used prior to cosmos-sdk v0.38.1. It
+stores the keyring encrypted within the app's configuration directory. This keyring will request a password each time
+it is accessed, which may occur multiple times in a single command resulting in repeated password prompts.
+
+3. **kwallet**: This backend uses the KDE Wallet Manager as a credentials management application.
+
+4. **pass**: This backend uses the `pass` command line utility to store and retrieve keys.
+
+5. **test**: This backend stores keys insecurely to disk. It does not prompt for a password to be unlocked and should
+only be used for testing purposes.
+
+6. **memory**: This backend uses a transient storage. Keys are discarded when the process terminates or the type
+instance is garbage collected.
+
+## Supported Sign Algorithms
+
+The greenfield-cosmos-sdk supports as many sign algorithms as users want, but in Greenfield's context, we only
+support `eth_secp256k1` and `ed25519`. These algorithms were chosen for their security and compatibility with the
+Ethereum and Tendermint ecosystems.
+
+## Conclusion
+
+In conclusion, key management is a critical aspect of building secure blockchain applications. By understanding
+the available backend options and supported sign algorithms in the greenfield-cosmos-sdk, you can build applications
+that are both secure and user-friendly. The `Keyring` interface provides a flexible way to manage private keys,
+and by implementing the required methods, you can create a custom key storage backend that meets the specific
+needs of your application.
diff --git a/docs/core-concept/storage-metadata-models.md b/docs/core-concept/storage-metadata-models.md
new file mode 100644
index 000000000..c051210fb
--- /dev/null
+++ b/docs/core-concept/storage-metadata-models.md
@@ -0,0 +1,128 @@
+# Storage MetaData Models
+
+The is designed to be as compatible as possible with popular Web2 and Web3 standards.
+It provides developers with similar API primitives and models as the most popular Web2 cloud storage: AWS s3.
+
+## Abstract
+Below are the basic data models for Greenfield storage:
+
+- bucket
+- object
+- group
+- permission
+
+These metadata are stored as blockchain state into the persistent storage of the Greenfield blockchain.
+
+## Concepts
+
+### Bucket
+
+Bucket is the unit to group storage "objects". BucketName has to be globally unique. Every user account can create several
+buckets. The account will become the "owner" of the bucket.
+
+Each bucket should be associated with its own Primary SP, and the payment accounts for Read and Store. The owner's
+address will be the default payment account.
+
+The prototype definition of a bucket:
+
+```protobuf
+message BucketInfo {
+ // owner is the account address of bucket creator, it is also the bucket owner.
+ string owner;
+ // bucket_name is a globally unique name of bucket
+ string bucket_name;
+ // is_public define the highest permissions for bucket. When the bucket is public, everyone can get the object in it.
+ bool is_public;
+ // id is the unique identification for bucket.
+ string id;
+ // source_type define the source of the bucket
+ SourceType source_type;
+ // create_at define the block number when the bucket created.
+ int64 create_at;
+ // payment_address is the address of the payment account
+ string payment_address;
+ // primary_sp_address is the address of the primary sp. Objects belongs to this bucket will never
+ // leave this SP, unless you explicitly shift them to another SP.
+ string primary_sp_address;
+ // read_quota defines the traffic quota for read
+ ReadQuota read_quota;
+ int64 payment_price_time;
+ // payment_out_flows, for billing;
+ repeated payment.OutFlowInUSD payment_out_flows;
+}
+```
+
+### Object
+
+Object is the basic unit to store data on Greenfield. The metadata for the object will be stored on the Greenfield
+blockchain:
+
+- name and ID
+- owner
+- bucket that hosts it
+- size and timestamps
+- content type
+- checkSums for the storage pieces
+- storage status
+- associated SP information
+
+Object metadata is stored with the bucket name as the prefix of the key. It is possible to iterate through all
+objects under the same bucket, but it may be a heavy-lifting job for a large bucket with lots of objects.
+
+The prototype definition of an objecy:
+
+```protobuf
+
+message ObjectInfo {
+ string owner;
+ // bucket_name is the name of the bucket
+ string bucket_name;
+ // object_name is the name of object
+ string object_name;
+ // id is the unique identifier of object
+ string id;
+ // payloadSize is the total size of the object payload
+ uint64 payload_size;
+ // is_public define the highest permissions for object. When the object is public, everyone can access it.
+ bool is_public;
+ // content_type define the format of the object which should be a standard MIME type.
+ string content_type;
+ // create_at define the block number when the object created
+ int64 create_at;
+ // object_status define the upload status of the object.
+ ObjectStatus object_status;
+ // redundancy_type define the type of the redundancy which can be multi-replication or EC.
+ RedundancyType redundancy_type;
+ // source_type define the source of the object.
+ SourceType source_type;
+ // checksums define the root hash of the pieces which stored in a SP.
+ repeated bytes checksums;
+ // secondary_sp_addresses define the addresses of secondary_sps
+ repeated string secondary_sp_addresses ;
+ // lockedBalance
+ string lockedBalance;
+}
+```
+
+### Group
+
+A Group is a collection of accounts with the same permissions. The group name is not allowed to be duplicated under the
+same user. However, a group can not create or own any resource. A group can not be a member of another group either.
+
+A resource can only have a limited number of groups associated with it for permissions. This ensures that the on-chain
+permission check can be finished within a constant time.
+
+The prototype definition of a group:
+
+```protobuf
+message GroupInfo {
+ // owner is the owner of the group. It can not changed once created.
+ string owner ;
+ // group_name is the name of group which is unique under an account.
+ string group_name;
+ // source_type
+ SourceType source_type;
+ // id is the unique identifier of group
+ string id;
+}
+```
diff --git a/docs/core-concept/transaction-lifecycle.md b/docs/core-concept/transaction-lifecycle.md
new file mode 100644
index 000000000..e835169c2
--- /dev/null
+++ b/docs/core-concept/transaction-lifecycle.md
@@ -0,0 +1,268 @@
+# Transaction Lifecycle
+
+This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition
+is described in a [different doc](https://github.com/bnb-chain/greenfield-cosmos-sdk/blob/master/docs/core/transactions.md).
+The transaction will be referred to as `Tx`. {synopsis}
+
+## Creation
+
+### Transaction Creation
+
+One of the main application interfaces is the command-line interface. The transaction `Tx` can be created by the user
+inputting a command in the following format from the [command-line](../cli/cli.md), providing the type of transaction
+in `[command]`, arguments in `[args]`, and configurations such as gas prices in `[flags]`:
+
+```bash
+gnfd tx [command] [args] [flags]
+```
+
+This command will automatically **create** the transaction, **sign** it using the account's private key, and **broadcast**
+it to the specified peer node.
+
+There are several required and optional flags for transaction creation. The `--from` flag specifies which [account](./accounts.md)
+the transaction is originating from. For example, if the transaction is sending coins, the funds will be drawn from the specified `from` address.
+
+#### Gas and Fees
+
+Additionally, there are several [flags](../cli/cli.md) users can use to indicate how much they are willing to pay in [fees](./gas-fees.md):
+
+* `--gas` refers to how much [gas](./gas-fees.md). Different from other cosmos blockchain where gas represents computational
+resources, on greenfield blockchain, the gas of a transaction is predefined. It is suggested to be estimated by providing `auto`
+as the value for `--gas`.
+* `--gas-prices` specifies how much the user is willing to pay per unit of gas, which can be one or multiple denominations of tokens.
+For example, `--gas-prices=5000000000BNB` means the user is willing to pay 5Gwei BNB per unit of gas.
+* `--fees` specifies how much in fees the user is willing to pay in total.
+* `--timeout-height` specifies a block timeout height to prevent the tx from being committed past a certain height.
+
+The ultimate value of the fees paid is equal to the gas multiplied by the gas prices. In other words, `fees = ceil(gas * gasPrices)`.
+Thus, since fees can be calculated using gas prices and vice versa, the users specify only one of the two.
+
+Later, validators decide whether or not to include the transaction in their block by comparing the given or calculated
+`gas-prices` to their local `min-gas-prices`. `Tx` will be rejected if its `gas-prices` is not high enough, so users
+are incentivized to pay more.
+
+#### CLI Example
+
+Users of the application `app` can enter the following command into their CLI to generate a transaction to send
+1000wei BNB from a `senderAddress` to a `recipientAddress`.
+
+```bash
+gnfd tx send 1000BNB --from --gas auto
+```
+
+#### Other Transaction Creation Methods
+
+The command-line is an easy way to interact with an application, but `Tx` can also be created using a
+[gRPC or REST interface](../api-sdk/grpc_rest.md) or some other entry point defined by the application developer.
+From the user's perspective, the interaction depends on the web interface or wallet they are using
+(e.g. creating `Tx` using [Lunie.io](https://lunie.io/#/) and signing it with a Ledger Nano S).
+
+## Addition to Mempool
+
+Each full-node (running Tendermint) that receives a `Tx` sends an [ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html#messages),
+`CheckTx`, to the application layer to check for validity, and receives an `abci.ResponseCheckTx`. If the `Tx` passes the
+checks, it is held in the nodes'[**Mempool**](https://docs.tendermint.com/master/tendermint-core/mempool/),
+an in-memory pool of transactions unique to each node, pending inclusion in a block - honest nodes will discard
+`Tx` if it is found to be invalid. Prior to consensus, nodes continuously check incoming transactions and gossip them to their peers.
+
+### Types of Checks
+
+The full-nodes perform stateless, then stateful checks on `Tx` during `CheckTx`, with the goal to
+identify and reject an invalid transaction as early on as possible to avoid wasted computation.
+
+**_Stateless_** checks do not require nodes to access state - light clients or offline nodes can do
+them - and are thus less computationally expensive. Stateless checks include making sure addresses
+are not empty, enforcing nonnegative numbers, and other logic specified in the definitions.
+
+**_Stateful_** checks validate transactions and messages based on a committed state. Examples
+include checking that the relevant values exist and can be transacted with, the address
+has sufficient funds, and the sender is authorized or has the correct ownership to transact.
+At any given moment, full-nodes typically have multiple versions
+of the application's internal state for different purposes. For example, nodes will execute state
+changes while in the process of verifying transactions, but still need a copy of the last committed
+state in order to answer queries - they should not respond using state with uncommitted changes.
+
+In order to verify a `Tx`, full-nodes call `CheckTx`, which includes both _stateless_ and _stateful_
+checks. Further validation happens later in the [`DeliverTx`](#delivertx) stage. `CheckTx` goes
+through several steps, beginning with decoding `Tx`.
+
+### Decoding
+
+When `Tx` is received by the application from the underlying consensus engine (e.g. Tendermint), it is still in
+its encoded `[]byte` form and needs to be unmarshaled in order to be processed. Then,
+the `runTx` function is called to run in `runTxModeCheck` mode, meaning the function will run all checks but
+exit before executing messages and writing state changes.
+
+### ValidateBasic
+
+Messages `sdk.Msg` are extracted from transactions (`Tx`). The `ValidateBasic` method of the `sdk.Msg`
+interface implemented by the module developer is run for each transaction.
+To discard obviously invalid messages, the `BaseApp` type calls the `ValidateBasic` method very early in the
+processing of the message in the `CheckTx` and `DeliverTx` transactions.
+`ValidateBasic` can include only **stateless** checks (the checks that do not require access to the state).
+
+### AnteHandler
+
+After the ValidateBasic checks, the `AnteHandler`s are run. Technically, they are optional, but in practice,
+they are very often present to perform signature verification, gas calculation, fee deduction and other
+core operations related to blockchain transactions.
+
+A copy of the cached context is provided to the `AnteHandler`, which performs limited checks specified
+for the transaction type. Using a copy allows the `AnteHandler` to do stateful checks for `Tx` without
+modifying the last committed state, and revert back to the original if the execution fails.
+
+### Gas
+
+The `Context`, which keeps a `GasMeter` that will track how much gas has been used during the execution of `Tx`,
+is initialized. The user-provided amount of gas for `Tx` is known as `GasWanted`. If `GasConsumed`,
+the amount of gas consumed so during execution, ever exceeds `GasWanted`, the execution will stop and the changes
+made to the cached copy of the state won't be committed. Otherwise, `CheckTx` sets `GasUsed` equal to `GasConsumed`
+and returns it in the result. After calculating the gas and fee values, validator-nodes check that the user-specified
+`gas-prices` is greater than their locally defined `min-gas-prices`.
+
+### Discard or Addition to Mempool
+
+If at any point during `CheckTx` the `Tx` fails, it is discarded and the transaction lifecycle ends
+there. Otherwise, if it passes `CheckTx` successfully, the default protocol is to relay it to peer
+nodes and add it to the Mempool so that the `Tx` becomes a candidate to be included in the next block.
+
+The **mempool** serves the purpose of keeping track of transactions seen by all full-nodes.
+Full-nodes keep a **mempool cache** of the last `mempool.cache_size` transactions they have seen, as a first line of
+defense to prevent replay attacks. Ideally, `mempool.cache_size` is large enough to encompass all
+of the transactions in the full mempool. If the mempool cache is too small to keep track of all
+the transactions, `CheckTx` is responsible for identifying and rejecting replayed transactions.
+
+Currently existing preventative measures include fees and a `sequence` (nonce) counter to distinguish
+replayed transactions from identical but valid ones. If an attacker tries to spam nodes with many
+copies of a `Tx`, full-nodes keeping a mempool cache will reject identical copies instead of running
+`CheckTx` on all of them. Even if the copies have incremented `sequence` numbers, attackers are
+disincentivized by the need to pay fees.
+
+Validator nodes keep a mempool to prevent replay attacks, just as full-nodes do, but also use it as
+a pool of unconfirmed transactions in preparation of block inclusion. Note that even if a `Tx`
+passes all checks at this stage, it is still possible to be found invalid later on, because
+`CheckTx` does not fully validate the transaction (i.e. it does not actually execute the messages).
+
+## Inclusion in a Block
+
+Consensus, the process through which validator nodes come to agreement on which transactions to
+accept, happens in **rounds**. Each round begins with a proposer creating a block of the most
+recent transactions and ends with **validators**, special full-nodes with voting power responsible
+for consensus, agreeing to accept the block or go with a `nil` block instead. Validator nodes
+execute the consensus algorithm, such as [Tendermint BFT](https://docs.tendermint.com/master/spec/consensus/consensus.html#terms),
+confirming the transactions using ABCI requests to the application, in order to come to this agreement.
+
+The first step of consensus is the **block proposal**. One proposer amongst the validators is chosen
+by the consensus algorithm to create and propose a block - in order for a `Tx` to be included, it
+must be in this proposer's mempool.
+
+## State Changes
+
+The next step of consensus is to execute the transactions to fully validate them. All full-nodes
+that receive a block proposal from the correct proposer execute the transactions by calling the ABCI functions
+`BeginBlock`, `DeliverTx` for each transaction,
+and `EndBlock`. While each full-node runs everything
+locally, this process yields a single, unambiguous result, since the messages' state transitions are deterministic and transactions are
+explicitly ordered in the block proposal.
+
+```text
+ -----------------------
+ |Receive Block Proposal|
+ -----------------------
+ |
+ v
+ -----------------------
+ | BeginBlock |
+ -----------------------
+ |
+ v
+ -----------------------
+ | DeliverTx(tx0) |
+ | DeliverTx(tx1) |
+ | DeliverTx(tx2) |
+ | DeliverTx(tx3) |
+ | . |
+ | . |
+ | . |
+ -----------------------
+ |
+ v
+ -----------------------
+ | EndBlock |
+ -----------------------
+ |
+ v
+ -----------------------
+ | Consensus |
+ -----------------------
+ |
+ v
+ -----------------------
+ | Commit |
+ -----------------------
+```
+
+### DeliverTx
+
+The `DeliverTx` ABCI function defined in `BaseApp` does the bulk of the
+state transitions: it is run for each transaction in the block in sequential order as committed
+to during consensus. Under the hood, `DeliverTx` is almost identical to `CheckTx` but calls the
+`runTx` function in deliver mode instead of check mode.
+Instead of using their `checkState`, full-nodes use `deliverState`:
+
+* **Decoding:** Since `DeliverTx` is an ABCI call, `Tx` is received in the encoded `[]byte` form.
+ Nodes first unmarshal the transaction, using the `TxConfig` defined in the app, then call `runTx` in `runTxModeDeliver`,
+ which is very similar to `CheckTx` but also executes and writes state changes.
+
+* **Checks and AnteHandler:** Full-nodes call `validateBasicMsgs` and `AnteHandler` again. This second check
+ happens because they may not have seen the same transactions during the addition to Mempool stage
+ and a malicious proposer may have included invalid ones. One difference here is that the
+ `AnteHandler` will not compare `gas-prices` to the node's `min-gas-prices` since that value is local
+ to each node - differing values across nodes would yield nondeterministic results.
+
+* **`MsgServiceRouter`:** While `CheckTx` would have exited, `DeliverTx` continues to run
+ `runMsgs` to fully execute each `Msg` within the transaction.
+ Since the transaction may have messages from different modules, `BaseApp` needs to know which module
+ to find the appropriate handler. This is achieved using `BaseApp`'s `MsgServiceRouter` so that it can be processed by
+ the module's Protobuf `Msg` service.
+
+* **`Msg` service:** Protobuf `Msg` service is responsible for executing each message in the `Tx` and causes
+ state transitions to persist in `deliverTxState`.
+
+* **PostHandlers:** `PostHandler`s run after the execution of the message. If they fail, the state change of `runMsgs`,
+ as well of `PostHandlers` are both reverted.
+
+* **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much
+ gas is being used; if execution completes, `GasUsed` is set and returned in the
+ `abci.ResponseDeliverTx`. If execution halts because `BlockGasMeter` or `GasMeter` has run out or something else goes
+ wrong, a deferred function at the end appropriately errors or panics.
+
+If there are any failed state changes resulting from a `Tx` being invalid or `GasMeter` running out,
+the transaction processing terminates and any state changes are reverted. Invalid transactions in a
+block proposal cause validator nodes to reject the block and vote for a `nil` block instead.
+
+### Commit
+
+The final step is for nodes to commit the block and state changes. Validator nodes
+perform the previous step of executing state transitions in order to validate the transactions,
+then sign the block to confirm it. Full nodes that are not validators do not
+participate in consensus - i.e. they cannot vote - but listen for votes to understand whether or
+not they should commit the state changes.
+
+When they receive enough validator votes (2/3+ _precommits_ weighted by voting power), full nodes commit to a new block to be added to the blockchain and
+finalize the state transitions in the application layer. A new state root is generated to serve as
+a merkle proof for the state transitions. Applications use the `Commit`
+ABCI method inherited from Baseapp; it syncs all the state transitions by
+writing the `deliverState` into the application's internal state. As soon as the state changes are
+committed, `checkState` start afresh from the most recently committed state and `deliverState`
+resets to `nil` in order to be consistent and reflect the changes.
+
+Note that not all blocks have the same number of transactions and it is possible for consensus to
+result in a `nil` block or one with none at all. In a public blockchain network, it is also possible
+for validators to be **byzantine**, or malicious, which may prevent a `Tx` from being committed in
+the blockchain. Possible malicious behaviors include the proposer deciding to censor a `Tx` by
+excluding it from the block or a validator voting against the block.
+
+At this point, the transaction lifecycle of a `Tx` is over: nodes have verified its validity,
+delivered it by executing its state changes, and committed those changes. The `Tx` itself,
+in `[]byte` form, is stored in a block and appended to the blockchain.
diff --git a/docs/introduction/ecosystem-player.md b/docs/introduction/ecosystem-player.md
new file mode 100644
index 000000000..c97ed946c
--- /dev/null
+++ b/docs/introduction/ecosystem-player.md
@@ -0,0 +1,55 @@
+## Ecosystem Players
+There are several player roles for the whole Greenfield ecosystem.
+
+
+Figure All Players of Greenfield
+
+### Greenfield Validators
+
+As a PoS blockchain, the Greenfield blockchain has its own validators.
+These validators are elected based on the Proof-of-Stake logic.
+
+These validators are responsible for the security of the Greenfield
+blockchain. They get involved in the governance and staking of the
+blockchain. They form a P2P network that is similar to other PoS
+blockchain networks.
+
+Meanwhile, they accept and process transactions to allow users to
+operate their objects stored on Greenfield. They maintain the metadata
+of Greenfield as the blockchain state, which is the control panel for
+both Storage Providers (SPs) and users. These two parties use and update
+these states to operate the object storage.
+
+The network topology of Greenfield validators is similar to the existing
+secure validator setup of PoS blockchains. "Sentry Nodes" are used to
+defend against DDoS and provide a secure private network, as shown in
+the below diagram.
+
+
+Figure Greenfield Blockchain Network
+
+### Greenfield Relayers
+The Greenfield Relayer is a bidirectional relaying tool that facilitates communication between
+Greenfield and BSC. This standalone process can only be run by Greenfield validators. The relayer
+independently monitors cross-chain events occurring on BSC and Greenfield, and persists them into
+a database. Once a few blocks confirm the event and reach finality, the relayer will sign a message
+using the BLS private key to confirm the event, and broadcast the signed event (known as "the vote")
+through the P2P network on the Greenfield network. Once enough votes from the Greenfield relayer are
+collected, the relayer will assemble a cross-chain package transaction and submit it to the BSC or
+Greenfield network.
+
+### Storage Providers (SPs)
+Storage Providers are professional individuals and organizations who run
+a series of services to provide data services based on the Greenfield
+blockchain.
+
+### Greenfield dApps
+Greenfield dApps are applications that provide functions based on
+Greenfield storage and its related economic traits to solve some
+problems of their users.
+
+## Participate in the Ecosystem
+- [Become A Validator](../cli/validator-staking.md): validators secure the Greenfield by validating and relaying transactions,
+ proposing, verifying and finalizing blocks.
+- [Become A Storage Provider](../cli/storage-provider.md): SPs store the objects' real data, i.e. the payload data. and get paid
+ by providing storage services.
\ No newline at end of file
diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md
new file mode 100644
index 000000000..8b99f5166
--- /dev/null
+++ b/docs/introduction/overview.md
@@ -0,0 +1,62 @@
+# Overview
+
+## What is the Greenfield Blockchain
+
+There are four important roles in the Greenfield ecosystem:
+
+1. **Greenfield Blockchain**. It is the core of Greenfield and is built on the Cosmos/Tendermint framework. The Greenfield
+ blockchain contains two categories of states "on-chain":
+ - Accounts and their BNB balance ledger.
+ - The metadata of the object storage system and SPs, the metadata of the objects stored on this storage system, and the
+ permission and billing information associated with this storage system.
+
+ Greenfield blockchain transactions can change the above states. These states and the transactions comprise the major
+ economic data of BNB Greenfield.
+
+2. **Storage Provider**. Storage Providers (SP) are storage service infrastructures that organizations or individuals provide
+ and the corresponding roles they play. They use Greenfield as the ledger and the single source of truth. Each SP can and
+ will respond to users' requests to write (upload) and read (download) data, and serve as the gatekeeper for user rights and
+ authentications.
+
+3. **Cross-chain Facilities**. Greenfield and BSC network natively support cross-chain communication, which means that BNB
+ can freely circulate between the two chains, and data assets can also be mapped from Greenfield to BSC. The cross-chain facilities
+ bring programmability to Greenfield.
+
+4. **Dapps**. When users want to create and use the data on Greenfield, they may interact with the BNB Greenfield Core
+ Infrastructure via BNB Greenfield dApps (decentralized applications). Greenfield provides a friendly smart contract
+ library on the cross-chain facility, which can be easily integrated into dapps.
+
+Technically, BNB Greenfield blockchain uses Proof-of-Stake based on Tendermint-consensus for its own network security.
+The validator election and governance are based on a proposal-vote mechanism, which is revised based on Cosmos SDK's
+governance module. Blocks are created every 2 seconds on the Greenfield chain by a group of validators.
+
+BNB will be the gas and governance token on this blockchain. The initial BNB will be locked on BSC and re-minted on Greenfield.
+BNB and data operation primitives can flow between Greenfield and BSC through cross-chain communication. Total circulation of
+BNB will stay unchanged as it is now but flow among BNB Beacon Chain, BSC, and Greenfield.
+
+
+## Why Greenfield Blockchain
+
+BNB Greenfield Blockchain is an infrastructure and ecosystem targeting to facilitate the decentralized data economy.
+It tries to achieve it by easing the process to store and manage data access and linking data ownership with the massive DeFi context of BSC.
+
+The core of the greenfield blockchain revolves around data and includes several aspects:
+
+1. **Decentralized storage of data**. Anyone or organization can register as a storage provider on the greenfield blockchain.
+As a ledger, the greenfield blockchain records the distribution of data stored on multiple SPs and coordinates data backup and recovery.
+2. **Data ownership**. Greenfield Blockchain can provide users with powerful data ownership management functions.
+Users can grant access, modify, create, delete, and even execute permissions to their data to other individuals or groups.
+On the greenfield blockchain, users truly achieve complete control over their own data.
+3. **Data assetization**. All data and access permissions on Greenfield can be mapped into NFT assets on the BSC network.
+Users' operations on these NFT assets, such as minting or burning, will ultimately be converted into changes in their data
+permissions on the greenfield blockchain through cross-chain technology. These NFT assets will follow the ERC721 and ERC1155 standards,
+maximizing the reuse of existing NFT browsers and markets on BSC.
+4. **Programmability of data ownership**.
+5. **Flow of data value**. Due to the assetization of data on BSC, the flow of data value is greatly promoted through various dapps.
+
+## Getting Started with the Greenfield Blockchain
+- Quick start with Greenfield Blockchain. (TODO)
+- Learn more about the ecosystem players of Greenfield. (TODO)
+- Learn more about the module design of Greenfield Blockchain. (TODO)
+- Building dapp from scratch with Greenfield. (TODO)
+- Becoming a player of Greenfield ecosystem. (TODO)
\ No newline at end of file
diff --git a/docs/introduction/state-world.md b/docs/introduction/state-world.md
new file mode 100644
index 000000000..7247e741f
--- /dev/null
+++ b/docs/introduction/state-world.md
@@ -0,0 +1,44 @@
+# State World of Greenfield Blockchain
+All Greenfield validators have such active data in full (at least the latest state). Anyone can join the blockchain as
+full nodes to synchronize these data for free.
+
+These data are on-chain and can be only changed through transactions onto the Greenfield blockchain. It has several types
+as described below.
+
+## Accounts and Balance
+Each user has their "Owner Address" as the identifier for their owner account to "own" the data resources. There is
+another "payment account" type dedicated to billing and payment purposes and owned by owner addresses.
+
+Both owner accounts and payment accounts can hold the BNB balance on Greenfield. Users can deposit BNB from BSC, accept
+transfers from other users, and spend them on transaction gas and storage usage.
+
+## Validator and SP Metadata
+These are the basic information about the Greenfield validators and Greenfield SPs. SPs may have more information, as
+it has to publish their service information for users' data operations. There should be a reputation mechanism for SPs
+as well.
+
+## Storage Metadata
+The "storage metadata" includes size, ownership, checksum hashes, and distribution location among SPs. Similar to AWS S3,
+the basic unit of the storage is an "object", which can be a piece of binary data, text files, photos, videos, or any
+other format. Users can create their objects under their "bucket". A bucket is globally unique. The object can be referred
+to via the bucket name and the object ID. It can also be located by the bucket name, the prefix tag, and the object ID
+via off-chain facilitations.
+
+## Permission Metadata
+Data resources on Greenfield, such as the data objects and the buckets, all have access control, such as which address
+can create, read, list, or even execute the resources, and which address can grant/revoke these permissions.
+
+Two other data resources also have access control. One is "Group". A group represents a group of user addresses that have
+the same permissions to the same resources. It can be used in the same way as an address in the access control. Meanwhile,
+it requires permission too to change the group. The other is "payment account". They are created by the owner accounts.
+
+Here the access control is enforced by the SPs off-chain. People can test and challenge the SPs if they mess up the
+control. Slash and reward will happen to keep the SPs sticking to the principles.
+
+## Billing Metadata
+Users have to pay fees to store data objects on Greenfield. While each object enjoys a free quota to download by users
+who are permitted to, the excessive download will require extra data packages to be paid for the bandwidth. Besides
+the owner address, users can derive multiple "Payment Addresses" to pay these fees. Objects are stored under buckets,
+while each bucket can be associated with these payment addresses, and the system will charge these accounts for storing
+and/or downloading. Many buckets can share the same payment address. Such association information is also stored on
+chains with consensus as well.
\ No newline at end of file
diff --git a/docs/architecture/03-token_economics.md b/docs/introduction/token_economics.md
similarity index 83%
rename from docs/architecture/03-token_economics.md
rename to docs/introduction/token_economics.md
index cafe1f68c..69dc8930b 100644
--- a/docs/architecture/03-token_economics.md
+++ b/docs/introduction/token_economics.md
@@ -33,11 +33,11 @@ total supply:
2. The transfer-in blockchain will unlock the amount from module account or contract and send it to target addresses.
3. Both networks will never mint BNB.
-Refer to [cross chain model](./07-cross-chain.md) to get more details about the mechanism.
+Refer to [cross chain model](../modules/cross-chain.md) to get more details about the mechanism.
## How to Participate in the Ecosystem
-- [Become A Validator](../tutorial/09-validator-staking.md): validators secure the Greenfield by validating and relaying transactions,
+- [Become A Validator](../cli/validator-staking.md): validators secure the Greenfield by validating and relaying transactions,
proposing, verifying and finalizing blocks.
-- [Become A Storage Provider](../tutorial/07-storage-provider.md): SPs store the objects' real data, i.e. the payload data. and get paid
+- [Become A Storage Provider](../cli/storage-provider.md): SPs store the objects' real data, i.e. the payload data. and get paid
by providing storage services.
-- [Store/Manage Data](../tutorial/06-storage.md): store and manage your data in a decentralized way, control and own it all by yourself.
+- [Store/Manage Data](../cli/storage.md): store and manage your data in a decentralized way, control and own it all by yourself.
diff --git a/docs/architecture/06-billing_and_payment.md b/docs/modules/billing_and_payment.md
similarity index 100%
rename from docs/architecture/06-billing_and_payment.md
rename to docs/modules/billing_and_payment.md
diff --git a/docs/architecture/08-consensus_and_staking.md b/docs/modules/consensus_and_staking.md
similarity index 100%
rename from docs/architecture/08-consensus_and_staking.md
rename to docs/modules/consensus_and_staking.md
diff --git a/docs/architecture/07-cross-chain.md b/docs/modules/cross-chain.md
similarity index 100%
rename from docs/architecture/07-cross-chain.md
rename to docs/modules/cross-chain.md
diff --git a/docs/architecture/10-data_availability_challenge.md b/docs/modules/data_availability_challenge.md
similarity index 100%
rename from docs/architecture/10-data_availability_challenge.md
rename to docs/modules/data_availability_challenge.md
diff --git a/docs/architecture/09-governance.md b/docs/modules/governance.md
similarity index 95%
rename from docs/architecture/09-governance.md
rename to docs/modules/governance.md
index 6e219ae58..32ce336f7 100644
--- a/docs/architecture/09-governance.md
+++ b/docs/modules/governance.md
@@ -7,8 +7,8 @@ The Greenfield BlockChain utilizes on-chain governance, which is achieved by ste
- Execution: After voting period, the votes are tallied and if proposal `passed`, the messages in the proposal will be executed
There are various types of proposals. Include but not limited to:
-- Proposals for creating and editing validators, staking rewards distribution, details as described in [staking_model](./08-consensus_and_staking.md)
-- Proposals for creating and removing storage provider which specified in [storage_provider_model](./04-storage_provider_management.md)
+- Proposals for creating and editing validators, staking rewards distribution, details as described in [staking_model](consensus_and_staking.md)
+- Proposals for creating and removing storage provider which specified in [storage_provider_model](storage_provider_management.md)
- Parameters change proposal for `Greenfield` modules
- Parameters change and upgrade proposals for `BSC` smart contracts
diff --git a/docs/architecture/04-storage_provider_management.md b/docs/modules/storage_provider_management.md
similarity index 99%
rename from docs/architecture/04-storage_provider_management.md
rename to docs/modules/storage_provider_management.md
index fc9e509e2..41258917c 100644
--- a/docs/architecture/04-storage_provider_management.md
+++ b/docs/modules/storage_provider_management.md
@@ -192,5 +192,4 @@ message MsgDeposit {
This message is expected to fail if:
* the storage provider is not existed
-* the deposit tokens are of a denom not specified as the deposit denom of sp module
-
+* the deposit tokens are of a denom not specified as the deposit denom of sp module
\ No newline at end of file
diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 000000000..08b147b4e
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,16 @@
+## Overview
+This section dives into the internals of the Greenfield Blockchain implementation.
+
+### Table of Contents
+
+- [Overview](introduction/overview.md)
+- [Key Management](core-concept/key_management.md)
+- [Token Economics](introduction/token_economics.md)
+- [Storage Provider Management](modules/storage_provider_management.md)
+- [Storage Metadata Models](core-concept/storage-metadata-models.md)
+- [Billing and Payment](modules/billing_and_payment.md)
+- [Cross Chain](modules/cross-chain.md)
+- [Consensus and Staking](modules/consensus_and_staking.md)
+- [Governance](modules/governance.md)
+- [Data Availability Challenge](modules/data_availability_challenge.md)
+- [Event](api-sdk/events.md)
\ No newline at end of file
diff --git a/docs/resources/resources.md b/docs/resources/resources.md
new file mode 100644
index 000000000..6bbf43a47
--- /dev/null
+++ b/docs/resources/resources.md
@@ -0,0 +1,26 @@
+## esources
+
+As GNFD is fully compatible with Cosmos, most of the development tools in the Cosmos ecosystem are also applicable to
+Greenfield. Here are some reference libraries, for a complete list please refer to [awesome-cosmos](https://github.com/cosmos/awesome-cosmos).
+
+### Block Explorers
+- [Big Dipper](https://bigdipper.live/) - [Source](https://github.com/forbole/big-dipper-2.0-cosmos)
+- [Ping.pub](https://ping.pub/) - [Source](https://github.com/ping-pub/explorer)
+
+## Monitoring
+* [Prometheus Exporter](https://github.com/node-a-team/Cosmos-IE) - An integrated Prometheus exporter for the Cosmos SDK.
+* [Chains Dashboard](https://github.com/zhangyelong/cosmos-dashboard) - A Grafana dashboard to monitor Cosmos SDK and Tendermint-based blockchain nodes.
+* [cosmos-exporter](https://github.com/solarlabsteam/cosmos-exporter) - A Prometheus scraper that fetches the data from a full node of a Cosmos-based blockchain via gRPC.
+* [missed-blocks-checker](https://github.com/solarlabsteam/missed-blocks-checker) - Monitor missed blocks for Cosmos-chain validators with support for notifications to Telegram and Slack.
+* [Nodes Checker](https://t.me/NodesGuru_bot) - Check your nodes status online, receive instant notification if something is wrong with your validator node.
+* [Tenderduty](https://github.com/blockpane/tenderduty) - Comprehensive monitoring tool for Tendermint chains. Its primary function is to alert a validator if they are missing blocks, and more.
+* [node-exporter](https://github.com/QuokkaStake/cosmos-node-exporter.git) - A Prometheus exporter to scrape data on your node sync status, Cosmovisor upgrades and GitHub version mismatches, useful for node operators and validators.
+* [wallets-exporter](https://github.com/QuokkaStake/cosmos-wallets-exporter.git) - A Prometheus exporter to scrape data on wallets balance, useful to get notified if your wallet balance is too low.
+
+## Indexers
+* [Cosmscan](https://github.com/cosmscan/cosmscan-go) - An indexer engine for Cosmos chains.
+
+### CLI
+* [iqlusioninc/tmkms](https://github.com/iqlusioninc/tmkms) - Key Management System for Tendermint validators.
+* [lens](https://github.com/strangelove-ventures/lens) - CLI tool to interact with any Cosmos chain supporting the core Cosmos-SDK modules.
+* [multisig](https://github.com/informalsystems/multisig) - CLI tool for managing multisig accounts on Cosmos SDK chains.
diff --git a/docs/run-node/interact-node.md b/docs/run-node/interact-node.md
new file mode 100644
index 000000000..eeb815c6b
--- /dev/null
+++ b/docs/run-node/interact-node.md
@@ -0,0 +1,163 @@
+# Interacting with the Node
+
+There are multiple ways to interact with a node: using the CLI, using gRPC or using the REST endpoints.
+
+## Using the CLI
+
+Now that your chain is running, it is time to try sending tokens from the first account you created to a second account.
+In a new terminal window, start by running the following query command:
+
+```bash
+gnfd query bank balances $MY_VALIDATOR_ADDRESS
+```
+
+You should see the current balance of the account you created, equal to the original balance of `BNB` you granted it minus the amount
+you delegated via the `gentx`. Now, create a second account:
+
+```bash
+gnfd keys add recipient --keyring-backend test
+
+# Put the generated address in a variable for later use.
+RECIPIENT=$(gnfd keys show recipient -a --keyring-backend test)
+```
+
+The command above creates a local key-pair that is not yet registered on the chain.
+An account is created the first time it receives tokens from another account. Now, run the following command to send tokens to the `recipient` account:
+
+```bash
+gnfd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000000BNB --keyring-backend test
+
+# Check that the recipient account did receive the tokens.
+gnfd query bank balances $RECIPIENT
+```
+
+## Using gRPC
+
+The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into
+various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport)
+can be plugged and replaced very easily.
+
+Since the code generation library largely depends on your own tech stack, we will only present three alternatives:
+
+* `grpcurl` for generic debugging and testing,
+* programmatically via Go,
+
+### grpcurl
+
+[grpcurl](https://github.com/fullstorydev/grpcurl) is like `curl` but for gRPC. It is also available as a Go library,
+but we will use it only as a CLI command for debugging and testing purposes.
+Follow the instructions in the previous link to install it.
+
+Assuming you have a local node running (either a localnet, or connected a live network), you should be able to run the
+following command to list the Protobuf services available (you can replace `localhost:9000` by the gRPC server endpoint
+of another node, which is configured under the `grpc.address` field inside `app.toml`:
+
+```bash
+grpcurl -plaintext localhost:9090 list
+```
+
+You should see a list of gRPC services, like `cosmos.bank.v1beta1.Query`. This is called reflection, which is a
+Protobuf endpoint returning a description of all available endpoints. Each of these represents a different
+Protobuf service, and each service exposes multiple RPC methods you can query against.
+
+In order to get a description of the service you can run the following command:
+
+```bash
+grpcurl \
+ localhost:9090 \
+ describe cosmos.bank.v1beta1.Query # Service we want to inspect
+```
+
+It's also possible to execute an RPC call to query the node for information:
+
+```bash
+grpcurl \
+ -plaintext
+ -d '{"address":"$MY_VALIDATOR"}' \
+ localhost:9090 \
+ cosmos.bank.v1beta1.Query/AllBalances
+```
+
+#### Query for historical state using grpcurl
+
+You may also query for historical data by passing some [gRPC metadata](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md)
+to the query: the `x-cosmos-block-height` metadata should contain the block to query. Using grpcurl as above, the command looks like:
+
+```bash
+grpcurl \
+ -plaintext \
+ -H "x-cosmos-block-height: 279256" \
+ -d '{"address":"$MY_VALIDATOR"}' \
+ localhost:9090 \
+ cosmos.bank.v1beta1.Query/AllBalances
+```
+
+Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response.
+
+### Programmatically via Go
+
+The following snippet shows how to query the state using gRPC inside a Go program. The idea is to create a gRPC connection,
+and use the Protobuf-generated client code to query the gRPC server.
+
+#### Install Greenfield GO-sdk
+
+Refer to [Go-sdk doc](https://github.com/bnb-chain/greenfield-go-sdk) to install the latest dependency.
+
+
+Init client without key manager, you should use it for only querying purpose.
+```go
+client := NewGreenfieldClient("localhost:9090", "greenfield_9000-121")
+
+query := banktypes.QueryBalanceRequest{
+ Address: "0x76d244CE05c3De4BbC6fDd7F56379B145709ade9",
+ Denom: "BNB",
+}
+res, err := client.BankQueryClient.Balance(context.Background(), &query)
+```
+
+Init client with key manager, for signing and sending tx
+```go
+keyManager, _ := keys.NewPrivateKeyManager("ab463aca3d2965233da3d1d6108aa521274c5ddc2369ff72970a52a451863fbf")
+gnfdClient := NewGreenfieldClient("localhost:9090",
+ "greenfield_9000-121",
+ WithKeyManager(km),
+ WithGrpcDialOption(grpc.WithTransportCredentials(insecure.NewCredentials()))
+)
+```
+
+
+## Using the REST Endpoints
+
+As described in the [gRPC guide](../api-sdk/grpc_rest.md), all gRPC services on the Cosmos SDK are made available for
+more convenient REST-based queries. The format of the URL path is based on the Protobuf service
+method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic.
+For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`.
+Request arguments are passed as query parameters.
+
+As a concrete example, the `curl` command to make balances request is:
+
+```bash
+curl \
+ -X GET \
+ -H "Content-Type: application/json" \
+ http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR
+```
+
+Make sure to replace `localhost:1317` with the REST endpoint of your node, configured under the `api.address` field.
+
+The list of all available REST endpoints is available as a Swagger specification file, it can be viewed at `localhost:1317/swagger`.
+Make sure that the `api.swagger` field is set to true in your `app.toml`.
+
+### Query for historical state using REST
+
+Querying for historical state is done using the HTTP header `x-cosmos-block-height`. For example, a curl command would look like:
+
+```bash
+curl \
+ -X GET \
+ -H "Content-Type: application/json" \
+ -H "x-cosmos-block-height: 279256"
+ http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR
+```
+
+Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response.
\ No newline at end of file
diff --git a/docs/tutorial/03-local-network.md b/docs/run-node/run-local-network.md
similarity index 97%
rename from docs/tutorial/03-local-network.md
rename to docs/run-node/run-local-network.md
index 2e92b0b0c..9836d650d 100644
--- a/docs/tutorial/03-local-network.md
+++ b/docs/run-node/run-local-network.md
@@ -1,7 +1,7 @@
-## Local Network
+# Run Local Network
This guide helps you create a validator node that runs the network locally for testing and other development-related purposes.
-### Prerequisites
+## Prerequisites
A computer running a Unix-like operating system (e.g., macOS, Linux)
Basic familiarity with the command line
@@ -21,7 +21,7 @@ cd greenfield
make build
```
-### Create Genesis File and Start the Network
+## Create Genesis File and Start the Network
Step 1: Initialize configuration files
@@ -87,7 +87,7 @@ Step 4: Launch your chain
./build/bin/gnfd start
```
-### Reference
+## Reference
The Greenfield chain is built using the `cosmos-sdk` and `Tendermint` core. There are various official configuration documents that can be referred to. These include:
1. [Quick scripts for running a local testnet](../../deployment/readme.md)
diff --git a/docs/run-node/run-mainnet-node.md b/docs/run-node/run-mainnet-node.md
new file mode 100644
index 000000000..05e2cbf7b
--- /dev/null
+++ b/docs/run-node/run-mainnet-node.md
@@ -0,0 +1 @@
+# Run Mainnet Node (coming soon)
diff --git a/docs/run-node/run-testnet-node.md b/docs/run-node/run-testnet-node.md
new file mode 100644
index 000000000..b2a88b270
--- /dev/null
+++ b/docs/run-node/run-testnet-node.md
@@ -0,0 +1 @@
+# Run Testnet Node (coming soon)
diff --git a/docs/tutorial/01-join-mainnet.md b/docs/tutorial/01-join-mainnet.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/tutorial/02-join-testnet.md b/docs/tutorial/02-join-testnet.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/tutorial/06-storage.md b/docs/tutorial/06-storage.md
deleted file mode 100644
index a85b40860..000000000
--- a/docs/tutorial/06-storage.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Using gnfd command to interact with storage module
-
-## HeadBucket
-
-```shell
-gnfd query storage head-bucket [bucket-name] [flags]
-```
-
-## HeadObject
-
-```shell
-gnfd query storage head-object [bucket-name] [object-name] [flags]
-```
-
-# Others operations
-
-This repo provides the command-line tool to createBucket, createObject, uploadObject, downloadObject and others
-operations. You can go to see [greenfiled-cmd](https://github.com/bnb-chain/greenfield-cmd) for details.
\ No newline at end of file
diff --git a/docs/tutorial/08-payment.md b/docs/tutorial/08-payment.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/tutorial/readme.md b/docs/tutorial/readme.md
deleted file mode 100644
index 9fb96b1b8..000000000
--- a/docs/tutorial/readme.md
+++ /dev/null
@@ -1,16 +0,0 @@
-## Overview
-This section provides the detailed usage of each module, runbook of testnet/mainnet, and rich examples.
-
-### Table of Contents
-
-- [Join the Mainnet](./01-join-mainnet.md)
-- [Join the Testnet](./02-join-testnet.md)
-- [Setup Private Network](./03-local-network.md)
-- [Key Management](./04-key-management.md)
-- [Bank](./05-bank.md)
-- [Storage](./06-storage.md)
-- [Storage Provider](./07-storage-provider.md)
-- [Payment](./08-payment.md)
-- [Validator and Staking](./09-validator-staking.md)
-- [Governance](./10-governance.md)
-- [Bridge](./11-bridge.md)
diff --git a/readme.md b/readme.md
index 18140b787..62284f9ba 100644
--- a/readme.md
+++ b/readme.md
@@ -76,7 +76,7 @@ $ bash ./deployment/localup/localup.sh stop
bash ./deployment/localup/localup.sh start 3
```
-More advanced script and command line usage, please refer to the [Tutorial](./docs/tutorial/readme.md).
+More advanced script and command line usage, please refer to the [Tutorial](docs/modules/tutorial/readme.md).
## Key Modules
@@ -94,7 +94,7 @@ And the following modules are in cosmos-sdk:
- `x/staking`: based on the Proof-of-Stake logic. The elected validators are responsible for the security of the Greenfield blockchain.
They get involved in the governance and staking of the blockchain.
-Refer to the [Architecture Design](./docs/architecture/readme.md) to dive deep into these modules.
+Refer to the [Architecture Design](swagger-docs/modules/readme.md) to dive deep into these modules.
## Join Testnet && Mainnet (coming soon..)
diff --git a/scripts/protoc-swagger-gen.sh b/scripts/protoc-swagger-gen.sh
index 429f817f0..fa5c29ce5 100755
--- a/scripts/protoc-swagger-gen.sh
+++ b/scripts/protoc-swagger-gen.sh
@@ -19,7 +19,7 @@ cd ..
# combine swagger files
# uses nodejs package `swagger-combine`.
# all the individual swagger files need to be configured in `config.json` for merging
-swagger-combine ./docs/config.json -o ./docs/static/swagger.yaml -f yaml --continueOnConflictingPaths true --includeDefinitions true
+swagger-combine ./swagger-docs/config.json -o ./swagger-docs/static/swagger.yaml -f yaml --continueOnConflictingPaths true --includeDefinitions true
# clean swagger files
rm -rf ./tmp-swagger-gen
\ No newline at end of file
diff --git a/docs/config.json b/swagger-docs/config.json
similarity index 100%
rename from docs/config.json
rename to swagger-docs/config.json
diff --git a/docs/docs.go b/swagger-docs/docs.go
similarity index 100%
rename from docs/docs.go
rename to swagger-docs/docs.go
diff --git a/docs/static/openapi.yml b/swagger-docs/static/openapi.yml
similarity index 100%
rename from docs/static/openapi.yml
rename to swagger-docs/static/openapi.yml
diff --git a/docs/static/swagger.yaml b/swagger-docs/static/swagger.yaml
similarity index 100%
rename from docs/static/swagger.yaml
rename to swagger-docs/static/swagger.yaml
diff --git a/docs/statik/init.go b/swagger-docs/statik/init.go
similarity index 100%
rename from docs/statik/init.go
rename to swagger-docs/statik/init.go
diff --git a/docs/statik/statik.go b/swagger-docs/statik/statik.go
similarity index 100%
rename from docs/statik/statik.go
rename to swagger-docs/statik/statik.go
diff --git a/docs/swagger-ui/favicon-16x16.png b/swagger-docs/swagger-ui/favicon-16x16.png
similarity index 100%
rename from docs/swagger-ui/favicon-16x16.png
rename to swagger-docs/swagger-ui/favicon-16x16.png
diff --git a/docs/swagger-ui/favicon-32x32.png b/swagger-docs/swagger-ui/favicon-32x32.png
similarity index 100%
rename from docs/swagger-ui/favicon-32x32.png
rename to swagger-docs/swagger-ui/favicon-32x32.png
diff --git a/docs/swagger-ui/index.html b/swagger-docs/swagger-ui/index.html
similarity index 100%
rename from docs/swagger-ui/index.html
rename to swagger-docs/swagger-ui/index.html
diff --git a/docs/swagger-ui/oauth2-redirect.html b/swagger-docs/swagger-ui/oauth2-redirect.html
similarity index 100%
rename from docs/swagger-ui/oauth2-redirect.html
rename to swagger-docs/swagger-ui/oauth2-redirect.html
diff --git a/docs/swagger-ui/swagger-ui-bundle.js b/swagger-docs/swagger-ui/swagger-ui-bundle.js
similarity index 100%
rename from docs/swagger-ui/swagger-ui-bundle.js
rename to swagger-docs/swagger-ui/swagger-ui-bundle.js
diff --git a/docs/swagger-ui/swagger-ui-bundle.js.map b/swagger-docs/swagger-ui/swagger-ui-bundle.js.map
similarity index 100%
rename from docs/swagger-ui/swagger-ui-bundle.js.map
rename to swagger-docs/swagger-ui/swagger-ui-bundle.js.map
diff --git a/docs/swagger-ui/swagger-ui-es-bundle-core.js b/swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js
similarity index 100%
rename from docs/swagger-ui/swagger-ui-es-bundle-core.js
rename to swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js
diff --git a/docs/swagger-ui/swagger-ui-es-bundle-core.js.map b/swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js.map
similarity index 100%
rename from docs/swagger-ui/swagger-ui-es-bundle-core.js.map
rename to swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js.map
diff --git a/docs/swagger-ui/swagger-ui-es-bundle.js b/swagger-docs/swagger-ui/swagger-ui-es-bundle.js
similarity index 100%
rename from docs/swagger-ui/swagger-ui-es-bundle.js
rename to swagger-docs/swagger-ui/swagger-ui-es-bundle.js
diff --git a/docs/swagger-ui/swagger-ui-es-bundle.js.map b/swagger-docs/swagger-ui/swagger-ui-es-bundle.js.map
similarity index 100%
rename from docs/swagger-ui/swagger-ui-es-bundle.js.map
rename to swagger-docs/swagger-ui/swagger-ui-es-bundle.js.map
diff --git a/docs/swagger-ui/swagger-ui-standalone-preset.js b/swagger-docs/swagger-ui/swagger-ui-standalone-preset.js
similarity index 100%
rename from docs/swagger-ui/swagger-ui-standalone-preset.js
rename to swagger-docs/swagger-ui/swagger-ui-standalone-preset.js
diff --git a/docs/swagger-ui/swagger-ui-standalone-preset.js.map b/swagger-docs/swagger-ui/swagger-ui-standalone-preset.js.map
similarity index 100%
rename from docs/swagger-ui/swagger-ui-standalone-preset.js.map
rename to swagger-docs/swagger-ui/swagger-ui-standalone-preset.js.map
diff --git a/docs/swagger-ui/swagger-ui.css b/swagger-docs/swagger-ui/swagger-ui.css
similarity index 100%
rename from docs/swagger-ui/swagger-ui.css
rename to swagger-docs/swagger-ui/swagger-ui.css
diff --git a/docs/swagger-ui/swagger-ui.css.map b/swagger-docs/swagger-ui/swagger-ui.css.map
similarity index 100%
rename from docs/swagger-ui/swagger-ui.css.map
rename to swagger-docs/swagger-ui/swagger-ui.css.map
diff --git a/docs/swagger-ui/swagger-ui.js b/swagger-docs/swagger-ui/swagger-ui.js
similarity index 100%
rename from docs/swagger-ui/swagger-ui.js
rename to swagger-docs/swagger-ui/swagger-ui.js
diff --git a/docs/swagger-ui/swagger-ui.js.map b/swagger-docs/swagger-ui/swagger-ui.js.map
similarity index 100%
rename from docs/swagger-ui/swagger-ui.js.map
rename to swagger-docs/swagger-ui/swagger-ui.js.map
From c520ac84facc71f72e71c57b883610ebac1d6988 Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 18:19:50 +0800
Subject: [PATCH 2/7] fix typo of docs
---
docs/api-sdk/events.md | 6 +++---
docs/api-sdk/grpc_rest.md | 8 ++++----
docs/cli/cli.md | 10 +++++-----
docs/cli/storage-provider.md | 2 +-
docs/core-concept/accounts.md | 6 +++---
docs/core-concept/gas-fees.md | 2 +-
docs/core-concept/key_management.md | 8 ++++----
docs/core-concept/storage-metadata-models.md | 2 +-
docs/core-concept/transaction-lifecycle.md | 17 ++++++++---------
docs/introduction/state-world.md | 2 +-
docs/modules/billing_and_payment.md | 2 +-
docs/modules/cross-chain.md | 4 ++--
docs/modules/storage_provider_management.md | 10 +++++-----
docs/resources/resources.md | 2 +-
docs/run-node/run-local-network.md | 8 ++++----
15 files changed, 44 insertions(+), 45 deletions(-)
diff --git a/docs/api-sdk/events.md b/docs/api-sdk/events.md
index 30e0dd54d..0a0c4263c 100644
--- a/docs/api-sdk/events.md
+++ b/docs/api-sdk/events.md
@@ -1,4 +1,4 @@
-# Greenfield blockchain events
+# Blockchain Events
There are two types of events doc:
1. Some old modules introduced in the cosmos-sdk don't emit typed events.
@@ -29,9 +29,9 @@ Following are the events that the Greenfield blockchain emits, grouped by module
* [Slashing](https://github.com/bnb-chain/gnfd-cosmos-sdk/blob/master/x/slashing/spec/06_events.md)
-* [SP](https://github.com/bnb-chain/greenfield/blob/develop/proto/greenfield/sp/events.proto)
+* [Storage Provider](https://github.com/bnb-chain/greenfield/blob/develop/proto/greenfield/sp/events.proto)
-* [Storage](./proto/greenfield/storage/events.proto)
+* [Storage](https://github.com/bnb-chain/greenfield/blob/master/proto/greenfield/storage/events.proto)
* [Staking](https://github.com/bnb-chain/gnfd-cosmos-sdk/blob/master/x/staking/spec/07_events.md)
diff --git a/docs/api-sdk/grpc_rest.md b/docs/api-sdk/grpc_rest.md
index a7c30b82e..122c36c1f 100644
--- a/docs/api-sdk/grpc_rest.md
+++ b/docs/api-sdk/grpc_rest.md
@@ -1,4 +1,4 @@
-# gRPC, REST, and Tendermint Endpoints
+# GRPC, REST, and Tendermint Endpoints
This document presents an overview of all the endpoints a node exposes: gRPC, REST as well as some other endpoints.
@@ -62,7 +62,7 @@ Enabling the `/swagger` endpoint is configurable inside `~/.gnfd/config/app.toml
## Tendermint RPC
-Independently from the Cosmos SDK, Tendermint also exposes a RPC server. This RPC server can be configured by tuning
+Independently of the Cosmos SDK, Tendermint also exposes an RPC server. This RPC server can be configured by tuning
parameters under the `rpc` table in the `~/.gnfd/config/config.toml`, the default listening address is `tcp://0.0.0.0:26657`.
An OpenAPI specification of all Tendermint RPC endpoints is available [here](https://docs.tendermint.com/master/rpc/).
@@ -75,12 +75,12 @@ Some Tendermint RPC endpoints are directly related to the Cosmos SDK:
* `/store/{path}`: this will query the store directly.
* `/p2p/filter/addr/{port}`: this will return a filtered list of the node's P2P peers by address port.
* `/p2p/filter/id/{id}`: this will return a filtered list of the node's P2P peers by ID.
-* `/broadcast_tx_{aync,async,commit}`: these 3 endpoint will broadcast a transaction to other peers. CLI, gRPC and REST expose a way to broadcast transations, but they all use these 3 Tendermint RPCs under the hood.
+* `/broadcast_tx_{aync,async,commit}`: these 3 endpoint will broadcast a transaction to other peers. CLI, gRPC and REST expose a way to broadcast transactions, but they all use these 3 Tendermint RPCs under the hood.
## Comparison Table
| Name | Advantages | Disadvantages |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| gRPC | - can use code-generated stubs in various languages
- supports streaming and bidirectional communication (HTTP2)
- small wire binary sizes, faster transmission | - based on HTTP2, not available in browsers
- learning curve (mostly due to Protobuf) |
| REST | - ubiquitous
- client libraries in all languages, faster implementation
| - only supports unary request-response communication (HTTP1.1)
- bigger over-the-wire message sizes (JSON) |
| Tendermint RPC | - easy to use | - bigger over-the-wire message sizes (JSON) |
diff --git a/docs/cli/cli.md b/docs/cli/cli.md
index 7b9d10997..86ff98d00 100644
--- a/docs/cli/cli.md
+++ b/docs/cli/cli.md
@@ -7,20 +7,20 @@ There is no set way to create a CLI, but Greenfield typically use the [Cobra Lib
Building a CLI with Cobra entails defining commands, arguments, and flags. Commands understand the
actions users wish to take, such as `tx` for creating a transaction and `query` for querying the application.
Each command can also have nested subcommands, necessary for naming the specific transaction type.
-Users also supply **Arguments**, such as account numbers to send coins to, and [**Flags**](#flags) to modify various
+Users also supply **Arguments**, such as account numbers to send coins to, and flags to modify various
aspects of the commands, such as gas prices or which node to broadcast to.
### Transaction Command
Here is an example of a command a user might enter to interact with `gnfd` in order to send some tokens:
```bash
-$ gnfd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000BNB--gas auto
+$ gnfd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000BNB --gas auto
```
The first four strings specify the command:
* The subcommand `tx`, which contains all commands that let users create transactions.
-* The subcommand `bank` to indicate which module to route the command to `x/bank` module in this case).
+* The subcommand `bank` to indicate which module to route the command to `x/bank` module in this case.
* The type of transaction `send`.
The next two strings are arguments: the `from_address` the user wishes to send from, the `to_address` of the recipient,
@@ -33,7 +33,7 @@ Queries are objects that allow users to retrieve information about the applicati
This `queryCommand` function adds all the queries available to end-users for the application. This typically includes:
-* **QueryTx** and/or other transaction query commands] from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
+* **QueryTx** and/or other transaction query commands from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
* **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address.
* **Validator command** from the Cosmos SDK rpc client tools, which displays the validator set of a given height.
* **Block command** from the Cosmos SDK rpc client tools, which displays the block data for a given height.
@@ -48,7 +48,7 @@ $ gnfd q bank denom-metadata --node tcp://127.0.0.1:26750
## Environment variables
-Each flag is bound to it's respecteve named environment variable. Then name of the environment variable consist of two parts
+Each flag is bound to its respective named environment variable. Then name of the environment variable consist of two parts
- capital case `basename` followed by flag name of the flag. `-` must be substituted with `_`.
- For example flag `--home` for application with basename `GNFD` is bound to `GNFD_HOME`. It allows reducing
the amount of flags typed for routine operations. For example instead of:
diff --git a/docs/cli/storage-provider.md b/docs/cli/storage-provider.md
index f774f43b2..126232b5c 100644
--- a/docs/cli/storage-provider.md
+++ b/docs/cli/storage-provider.md
@@ -7,7 +7,7 @@ Start a local chain with 1 validator and 1 Storage provider
$ bash ./deployment/localup/localup.sh all 1 1
```
-Export the accounts priv key of sp
+Export the accounts private key of sp
```shell
$ bash ./deployment/localup/localup.sh export_sp_privkey 1 1
diff --git a/docs/core-concept/accounts.md b/docs/core-concept/accounts.md
index 2a34da092..0f2c4ef01 100644
--- a/docs/core-concept/accounts.md
+++ b/docs/core-concept/accounts.md
@@ -19,9 +19,9 @@ In the node, all data is stored using Protocol Buffers serialization.
Greenfield only supports `secp256k1` key schemes for creating digital signatures:
-| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) |
-| :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: |
-| `secp256k1` | 20 | 33 | yes | no |
+| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) |
+|:-----------:|:-----------------------:|:--------------------------:|:-----------------------------------:|:-------------------------------:|
+| `secp256k1` | 20 | 33 | yes | no |
## Addresses
diff --git a/docs/core-concept/gas-fees.md b/docs/core-concept/gas-fees.md
index 0614bfe90..2fdc82f06 100644
--- a/docs/core-concept/gas-fees.md
+++ b/docs/core-concept/gas-fees.md
@@ -9,7 +9,7 @@ In the Cosmos SDK, `gas` is a special unit that is used to track the consumption
However, on application-specific blockchains like Greenfield, the primary factor determining the transaction fee
is no longer the computational cost of storage, but rather the incentive mechanism of Greenfield. For example,
creating and deleting a storage object consumes similar I/O and computational resources, but Greenfield
-incentivizes users to delete unused storage objects to free up more storage space, resulting in much cheaper
+incentives users to delete unused storage objects to free up more storage space, resulting in much cheaper
transaction fees for the latter.
Therefore, we abandoned the gas meter design of cosmos-sdk and redesigned the gashub module to determine the gas
diff --git a/docs/core-concept/key_management.md b/docs/core-concept/key_management.md
index a315178bd..397ab6dee 100644
--- a/docs/core-concept/key_management.md
+++ b/docs/core-concept/key_management.md
@@ -5,8 +5,8 @@ manage private keys for blockchain applications. The `Keyring` interface is used
to implement to be used as a key storage backend. This document provides an overview of the different backend
options available and the supported sign algorithms.
-And to interact with BSC(BNB-smart-chain) more convinent and user-friendly, we add
-[EIP-712](https://eips.ethereum.org/EIPS/eip-712) support. Any Etherrum wallet could connect to
+And to interact with BSC(BNB-smart-chain) more convenient and user-friendly, we add
+[EIP-712](https://eips.ethereum.org/EIPS/eip-712) support. Any Ethereum wallet could connect to
a greenfield node and sign an EIP-712 transaction directly.
## EIP-712 Support
@@ -16,7 +16,7 @@ infrastructure to interact with Greenfield at the beginning naturally.
To achieve this, the following changes have been made.
-1. An Ethereum-compatible RPC backend. Be noted that we only support necessacry methods to connect a
+1. An Ethereum-compatible RPC backend. Be noted that we only support necessary methods to connect a
wallet(`eth_chainId`, `eth_networkId`, `eth_blockNumber`, `eth_getBlockByNumber` and `eth_getBalance`). Other RPC methods are not implemented.
2. Same signing algorithm(`eth_scep256k1`) as Ethereum.
@@ -59,7 +59,7 @@ instance is garbage collected.
## Supported Sign Algorithms
-The greenfield-cosmos-sdk supports as many sign algorithms as users want, but in Greenfield's context, we only
+The greenfield-cosmos-sdk supports as many sign algorithms as users want, but in Greenfield context, we only
support `eth_secp256k1` and `ed25519`. These algorithms were chosen for their security and compatibility with the
Ethereum and Tendermint ecosystems.
diff --git a/docs/core-concept/storage-metadata-models.md b/docs/core-concept/storage-metadata-models.md
index c051210fb..3013427ef 100644
--- a/docs/core-concept/storage-metadata-models.md
+++ b/docs/core-concept/storage-metadata-models.md
@@ -69,7 +69,7 @@ blockchain:
Object metadata is stored with the bucket name as the prefix of the key. It is possible to iterate through all
objects under the same bucket, but it may be a heavy-lifting job for a large bucket with lots of objects.
-The prototype definition of an objecy:
+The prototype definition of an object:
```protobuf
diff --git a/docs/core-concept/transaction-lifecycle.md b/docs/core-concept/transaction-lifecycle.md
index e835169c2..3f60d04fb 100644
--- a/docs/core-concept/transaction-lifecycle.md
+++ b/docs/core-concept/transaction-lifecycle.md
@@ -37,9 +37,9 @@ For example, `--gas-prices=5000000000BNB` means the user is willing to pay 5Gwei
The ultimate value of the fees paid is equal to the gas multiplied by the gas prices. In other words, `fees = ceil(gas * gasPrices)`.
Thus, since fees can be calculated using gas prices and vice versa, the users specify only one of the two.
-Later, validators decide whether or not to include the transaction in their block by comparing the given or calculated
+Later, validators decide whether to include the transaction in their block by comparing the given or calculated
`gas-prices` to their local `min-gas-prices`. `Tx` will be rejected if its `gas-prices` is not high enough, so users
-are incentivized to pay more.
+are incentive to pay more.
#### CLI Example
@@ -72,7 +72,7 @@ identify and reject an invalid transaction as early on as possible to avoid wast
**_Stateless_** checks do not require nodes to access state - light clients or offline nodes can do
them - and are thus less computationally expensive. Stateless checks include making sure addresses
-are not empty, enforcing nonnegative numbers, and other logic specified in the definitions.
+are not empty, enforcing non-negative numbers, and other logic specified in the definitions.
**_Stateful_** checks validate transactions and messages based on a committed state. Examples
include checking that the relevant values exist and can be transacted with, the address
@@ -109,7 +109,7 @@ core operations related to blockchain transactions.
A copy of the cached context is provided to the `AnteHandler`, which performs limited checks specified
for the transaction type. Using a copy allows the `AnteHandler` to do stateful checks for `Tx` without
-modifying the last committed state, and revert back to the original if the execution fails.
+modifying the last committed state, and revert to the original if the execution fails.
### Gas
@@ -129,7 +129,7 @@ nodes and add it to the Mempool so that the `Tx` becomes a candidate to be inclu
The **mempool** serves the purpose of keeping track of transactions seen by all full-nodes.
Full-nodes keep a **mempool cache** of the last `mempool.cache_size` transactions they have seen, as a first line of
defense to prevent replay attacks. Ideally, `mempool.cache_size` is large enough to encompass all
-of the transactions in the full mempool. If the mempool cache is too small to keep track of all
+the transactions in the full mempool. If the mempool cache is too small to keep track of all
the transactions, `CheckTx` is responsible for identifying and rejecting replayed transactions.
Currently existing preventative measures include fees and a `sequence` (nonce) counter to distinguish
@@ -233,7 +233,7 @@ Instead of using their `checkState`, full-nodes use `deliverState`:
as well of `PostHandlers` are both reverted.
* **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much
- gas is being used; if execution completes, `GasUsed` is set and returned in the
+ gas is being used; if execution completes, `GasUsed` is set and returned to the
`abci.ResponseDeliverTx`. If execution halts because `BlockGasMeter` or `GasMeter` has run out or something else goes
wrong, a deferred function at the end appropriately errors or panics.
@@ -246,8 +246,7 @@ block proposal cause validator nodes to reject the block and vote for a `nil` bl
The final step is for nodes to commit the block and state changes. Validator nodes
perform the previous step of executing state transitions in order to validate the transactions,
then sign the block to confirm it. Full nodes that are not validators do not
-participate in consensus - i.e. they cannot vote - but listen for votes to understand whether or
-not they should commit the state changes.
+participate in consensus - i.e. they cannot vote - but listen for votes to understand whether they should commit the state changes.
When they receive enough validator votes (2/3+ _precommits_ weighted by voting power), full nodes commit to a new block to be added to the blockchain and
finalize the state transitions in the application layer. A new state root is generated to serve as
@@ -257,7 +256,7 @@ writing the `deliverState` into the application's internal state. As soon as the
committed, `checkState` start afresh from the most recently committed state and `deliverState`
resets to `nil` in order to be consistent and reflect the changes.
-Note that not all blocks have the same number of transactions and it is possible for consensus to
+Note that not all blocks have the same number of transactions, and it is possible for consensus to
result in a `nil` block or one with none at all. In a public blockchain network, it is also possible
for validators to be **byzantine**, or malicious, which may prevent a `Tx` from being committed in
the blockchain. Possible malicious behaviors include the proposer deciding to censor a `Tx` by
diff --git a/docs/introduction/state-world.md b/docs/introduction/state-world.md
index 7247e741f..6732df8c4 100644
--- a/docs/introduction/state-world.md
+++ b/docs/introduction/state-world.md
@@ -22,7 +22,7 @@ The "storage metadata" includes size, ownership, checksum hashes, and distributi
the basic unit of the storage is an "object", which can be a piece of binary data, text files, photos, videos, or any
other format. Users can create their objects under their "bucket". A bucket is globally unique. The object can be referred
to via the bucket name and the object ID. It can also be located by the bucket name, the prefix tag, and the object ID
-via off-chain facilitations.
+via off-chain facility.
## Permission Metadata
Data resources on Greenfield, such as the data objects and the buckets, all have access control, such as which address
diff --git a/docs/modules/billing_and_payment.md b/docs/modules/billing_and_payment.md
index 1d731a069..db421993c 100644
--- a/docs/modules/billing_and_payment.md
+++ b/docs/modules/billing_and_payment.md
@@ -265,7 +265,7 @@ The payment accounts have the below traits:
- The owner of a payment account is the user who creates it. The owner
can set it non-refundable. It's a one-way setting and can not be
- revoked. Thus users can set some objects as "public goods" which
+ revoked. Thus, users can set some objects as "public goods" which
can receive donations for storage and bandwidth while preserving
the ownership.
diff --git a/docs/modules/cross-chain.md b/docs/modules/cross-chain.md
index cb22c378d..696b5302d 100644
--- a/docs/modules/cross-chain.md
+++ b/docs/modules/cross-chain.md
@@ -30,7 +30,7 @@ The cross-chain model expects to achieve the following goals:
The native cross-chain bridge is maintained and secured by the
validators of Greenfield, via a new relayer system based on an
aggregated multisig scheme (more details in the later sections).
-Greenfield validators will run the relayers to facilitate the high
+Validators will run the relayers to facilitate the high
bandwidth and fast bridge.
BNB will be transferred from BSC to Greenfield as the first cross-chain
@@ -90,7 +90,7 @@ The communication layer is composed of a set of **Greenfield Relayers**:
### Resource Entity Mirror
The purposes of almost all the cross-chain packages are to change the
-state of the resource entities on the Greenfield blockchain. Thus the
+state of the resource entities on the Greenfield blockchain. Thus, the
below resource entities should be able to be mirrored on BSC:
1. Account
diff --git a/docs/modules/storage_provider_management.md b/docs/modules/storage_provider_management.md
index 41258917c..7d66c843d 100644
--- a/docs/modules/storage_provider_management.md
+++ b/docs/modules/storage_provider_management.md
@@ -14,7 +14,7 @@ storage network.
- Slash: The data stored on the SP will be challenged from time to time. When a challenge is successful, the SP will be
slashed, and deducted some tokens.
- Reputation: We will introduce a reputation system to evaluate SP's service quality. Users can choose one SP to store
- data based on it's reputation score.
+ data based on its reputation score.
- Exit: A SP can leave voluntarily by following some specific rules and get back the staked tokens. At the same time,
Greenfield can force it to exit when it has insufficient staked tokens or its reputation score is too low to meet
basic requirements as one SP.
@@ -23,8 +23,8 @@ storage network.
### Join the network
-SPs have to register themselves first by depositing on the Greenfield blockchain as their "Service Stake". Greenfield
-validators will go through a dedicated governance procedure to vote for the SPs of their election. SPs are encouraged to
+SPs have to register themselves first by depositing on the Greenfield blockchain as their "Service Stake".
+Validators will go through a dedicated governance procedure to vote for the SPs of their election. SPs are encouraged to
advertise their information and prove to the community their capability, as SPs have to provide a professional storage
system with high-quality SLA.
@@ -74,13 +74,13 @@ message StorageProvider {
option (gogoproto.equal) = false;
option (gogoproto.goproto_stringer) = false;
- // operator_address defines the address of the sp's operator; It also is the unqiue index key of sp.
+ // operator_address defines the address of the sp's operator; It also is the unique index key of sp.
string operator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// fund_address define the account address of the storage provider for deposit, remuneration.
string funding_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// seal_address define the account address of the storage provider for sealObject
string seal_address = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
- // approval_address define the account address of the storage provider for ack CreateBuclet/Object.
+ // approval_address define the account address of the storage provider for ack CreateBucket/Object.
string approval_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// total_deposit define the deposit token
string total_deposit = 5 [
diff --git a/docs/resources/resources.md b/docs/resources/resources.md
index 6bbf43a47..059c74ce4 100644
--- a/docs/resources/resources.md
+++ b/docs/resources/resources.md
@@ -1,4 +1,4 @@
-## esources
+## Resources
As GNFD is fully compatible with Cosmos, most of the development tools in the Cosmos ecosystem are also applicable to
Greenfield. Here are some reference libraries, for a complete list please refer to [awesome-cosmos](https://github.com/cosmos/awesome-cosmos).
diff --git a/docs/run-node/run-local-network.md b/docs/run-node/run-local-network.md
index 9836d650d..baf64df65 100644
--- a/docs/run-node/run-local-network.md
+++ b/docs/run-node/run-local-network.md
@@ -55,7 +55,7 @@ Before starting the chain, you need to populate the state with at least one acco
./build/bin/gnfd keys add relayer_bls --keyring-backend test --algo eth_bls
```
-2. Add the balances to genesis.json
+Step 2. Add the balances to genesis.json
Now that you have created a local account, go ahead and grant it some `BNB` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
```bash
@@ -66,7 +66,7 @@ RELAYER_BLS=$(./build/bin/gnfd keys show relayer_bls --keyring-backend test --ou
./build/bin/gnfd add-genesis-account ${RELAYER_ADDR} 100000000000000000000000000BNB
```
-3. Put generated Txs into genesis.json
+Step 3. Put generated Txs into genesis.json
Now that your account has some tokens, you need to add a validator to your chain.
```bash
@@ -74,14 +74,14 @@ Now that your account has some tokens, you need to add a validator to your chain
```
-Step 3: Configuring the Node Using app.toml and config.toml
+Step 4: Configuring the Node Using app.toml and config.toml
The program automatically generates two configuration files inside ~/.gnfd/config by default:
- config.toml: used to configure the Tendermint, learn more on [Tendermint's documentation](https://docs.tendermint.com/master/nodes/configuration.html),
- app.toml: generated by the Cosmos SDK, and used to configure your app, such as state pruning strategies, telemetry, gRPC and REST servers configuration, state sync...
-Step 4: Launch your chain
+Step 5: Launch your chain
```bash
./build/bin/gnfd start
From a27c44d1d05da96b6c29f7733bd3e2cd3e9d065c Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 18:59:47 +0800
Subject: [PATCH 3/7] add more docs
---
docs/core-concept/storage-metadata-models.md | 2 +-
docs/modules/consensus_and_staking.md | 4 +-
docs/{introduction => modules}/state-world.md | 0
docs/modules/storage-management.md | 304 ++++++++++++++++++
docs/readme.md | 51 ++-
5 files changed, 348 insertions(+), 13 deletions(-)
rename docs/{introduction => modules}/state-world.md (100%)
create mode 100644 docs/modules/storage-management.md
diff --git a/docs/core-concept/storage-metadata-models.md b/docs/core-concept/storage-metadata-models.md
index 3013427ef..736ae7a6d 100644
--- a/docs/core-concept/storage-metadata-models.md
+++ b/docs/core-concept/storage-metadata-models.md
@@ -1,6 +1,6 @@
# Storage MetaData Models
-The is designed to be as compatible as possible with popular Web2 and Web3 standards.
+The Greenfield is designed to be as compatible as possible with popular Web2 and Web3 standards.
It provides developers with similar API primitives and models as the most popular Web2 cloud storage: AWS s3.
## Abstract
diff --git a/docs/modules/consensus_and_staking.md b/docs/modules/consensus_and_staking.md
index ff676f048..d0c4d406a 100644
--- a/docs/modules/consensus_and_staking.md
+++ b/docs/modules/consensus_and_staking.md
@@ -57,4 +57,6 @@ The commission to the validator is paid when the validator is removed or when th
The commission is calculated and incremented at every `BeginBlock` operation to update accumulated fee amounts.
The rewards to a delegator are distributed when the delegation is changed or removed, or a withdrawal is requested.
-Before rewards are distributed, all slashes to the validator that occurred during the current delegation are applied.
\ No newline at end of file
+Before rewards are distributed, all slashes to the validator that occurred during the current delegation are applied.
+
+The detailed fee distribution rules is [described here](https://github.com/bnb-chain/greenfield-cosmos-sdk/blob/master/docs/spec/fee_distribution/f1_fee_distr.pdf)
\ No newline at end of file
diff --git a/docs/introduction/state-world.md b/docs/modules/state-world.md
similarity index 100%
rename from docs/introduction/state-world.md
rename to docs/modules/state-world.md
diff --git a/docs/modules/storage-management.md b/docs/modules/storage-management.md
new file mode 100644
index 000000000..cfde17dfc
--- /dev/null
+++ b/docs/modules/storage-management.md
@@ -0,0 +1,304 @@
+# Storage Management Module
+
+## Concepts
+
+### Bucket
+
+Bucket is the unit to group storage "objects". BucketName has to be globally unique. Every user account can create a
+bucket. The account will become the "owner" of the bucket.
+
+Each bucket should be associated with its own Primary SP, and the payment accounts for Read and Store. The owner's
+address will be the default payment account.
+
+### Object
+
+Object is the basic unit to store data on Greenfield. The metadata for the object will be stored on the Greenfield
+blockchain:
+
+- name and ID
+- owner
+- bucket that hosts it
+- size and timestamps
+- content type
+- checkSums for the storage pieces
+- storage status
+- associated SP information
+
+Object metadata is stored with the bucket name as the prefix of the key. It is possible to iterate through all
+objects under the same bucket, but it may be a heavy-lifting job for a large bucket with lots of objects.
+
+### Group
+
+A Group is a collection of accounts with the same permissions. The group name is not allowed to be duplicated under the
+same user. However, a group can not create or own any resource. A group can not be a member of another group either.
+
+A resource can only have a limited number of groups associated with it for permissions. This ensures that the on-chain
+permission check can be finished within a constant time.
+
+## State
+
+The storage module keeps state of the following primary objects:
+
+* BucketInfo
+* ObjectInfo
+* GroupInfo
+
+These primary objects should be primarily stored and accessed by the `ID` which is a auto-incremented sequence. An
+additional indices are maintained per primary objects in order to compatibility with the S3 object storage.
+
+* BucketInfo: `0x11 | hash(bucketName) -> BigEndian(bucketId)`
+* ObjectInfo: `0x12 | hash(bucketName)_hash(objectName) -> BigEndian(objectId)`
+* GroupInfo: `0x13 | OwnerAddr_hash(groupName) -> BigEndian(groupId)`
+
+* BucketInfoById: `0x21 | BigEndian(bucketId) -> ProtoBuf(BucketInfo)`
+* ObjectInfoById: `0x22 | BigEndian(objectId) -> ProtoBuf(ObjectInfo)`
+* GroupInfoById: `0x23 | BigEndian(groupId) -> ProtoBuf(GroupInfo)`
+
+### Params
+
+The storage module contains the following parameters,
+they can be updated with governance.
+
+| name | default value | meaning |
+|-------------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| MaxSegmentSize | 16M | The maximum size of the segment. The payload data of an object will split into several segment. Only the size of the last segment can be less than MaxSegmentSize, others is equals. |
+| RedundantDataChunkNum | 4 | The number of the data chunks in Erasure-Code algorithm. |
+| RedundantParityChunkNum | 2 | The number of the parity chunks in Erasure-Code algorithm. |
+| MaxPayloadSize | 2G | The maximum size of the payload data that allowed in greenfield storage network. |
+
+
+## Messages
+
+### MsgCreateBucket
+
+Used to create a bucket, a bucket is used to contain storage objects.
+
+```protobuf
+message MsgCreateBucket {
+ option (cosmos.msg.v1.signer) = "creator";
+
+ // creator is the account address of bucket creator, it is also the bucket owner.
+ string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // bucket_name is a globally unique name of bucket
+ string bucket_name = 2;
+ // is_public means the bucket is private or public. if private, only bucket owner or grantee can read it,
+ // otherwise every greenfield user can read it.
+ bool is_public = 3;
+ // payment_address is an account address specified by bucket owner to pay the read fee. Default: creator
+ string payment_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // primary_sp_address is the address of primary sp.
+ string primary_sp_address = 6 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // primary_sp_approval is the approval info of the primary SP which indicates that primary sp confirm the user's request.
+ Approval primary_sp_approval = 7;
+ // read_quota
+ ReadQuota read_quota = 8;
+}
+```
+
+### MsgDeleteBucket
+
+Used to delete bucket. It is important to note that you cannot delete a non-empty bucket.
+
+```protobuf
+message MsgDeleteBucket {
+ option (cosmos.msg.v1.signer) = "operator";
+
+ // creator is the account address of the grantee who has the DeleteBucket permission of the bucket to be deleted.
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+
+ // bucket_name is the name of the bucket to be deleted.
+ string bucket_name = 2;
+}
+```
+
+### MsgUpdateBucketInfo
+Used to update bucket info.
+
+```protobuf
+message MsgUpdateBucketInfo {
+ option (cosmos.msg.v1.signer) = "operator";
+
+ // operator is the account address of the operator
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+
+ // bucket_name is the name of bucket which you'll update
+ string bucket_name = 2;
+
+ // read_quota is the traffic quota that you read from primary sp
+ ReadQuota read_quota = 3;
+
+ // payment_address is the account address of the payment account
+ string payment_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+}
+```
+
+### MsgCreateObject
+
+Used to create an initial object under a bucket.
+
+```protobuf
+message MsgCreateObject {
+ option (cosmos.msg.v1.signer) = "creator";
+
+ // creator is the account address of object uploader
+ string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // bucket_name is the name of the bucket where the object is stored.
+ string bucket_name = 2;
+ // object_name is the name of object
+ string object_name = 3;
+ // payload_size is size of the object's payload
+ uint64 payload_size = 4;
+ // is_public means the bucket is private or public. if private, only bucket owner or grantee can access it,
+ // otherwise every greenfield user can access it.
+ bool is_public = 5;
+ // content_type is a standard MIME type describing the format of the object.
+ string content_type = 6;
+ // primary_sp_approval is the approval info of the primary SP which indicates that primary sp confirm the user's request.
+ Approval primary_sp_approval = 7;
+ // expect_checksums is a list of hashes which was generate by redundancy algorithm.
+ repeated bytes expect_checksums = 8;
+ // redundancy_type can be ec or replica
+ RedundancyType redundancy_type = 9;
+ // expect_secondarySPs is a list of StorageProvider address, which is optional
+ repeated string expect_secondary_sp_addresses = 10 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+}
+
+```
+### MsgDeleteObject
+
+Used to delete object that is no longer useful, the deleted storage object is not recoverable.
+
+```protobuf
+message MsgDeleteObject {
+ option (cosmos.msg.v1.signer) = "operator";
+
+ // operator is the account address of the operator who has the DeleteObject permission of the object to be deleted.
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // bucket_name is the name of the bucket where the object which to be deleted is stored.
+ string bucket_name = 2;
+ // object_name is the name of the object which to be deleted.
+ string object_name = 3;
+}
+
+```
+### MsgSealObject
+
+Storage provider seal an object once the underlying files are well saved by both primary and second SPs.
+
+```protobuf
+message MsgSealObject {
+ option (cosmos.msg.v1.signer) = "operator";
+
+ // operator is the account address of primary SP
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // bucket_name is the name of the bucket where the object is stored.
+ string bucket_name = 2;
+ // object_name is the name of object to be sealed.
+ string object_name = 3;
+ // secondary_sp_addresses is a list of storage provider which store the redundant data.
+ repeated string secondary_sp_addresses = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // secondary_sp_signatures is the signature of the secondary sp that can
+ // acknowledge that the payload data has received and stored.
+ repeated bytes secondary_sp_signatures = 5;
+}
+
+```
+### MsgCopyObject
+
+Used to copy an exact same object to another user.
+
+```protobuf
+message MsgCopyObject {
+ option (cosmos.msg.v1.signer) = "operator";
+
+ // operator is the account address of the operator who has the CopyObject permission of the object to be deleted.
+ string operator = 1;
+ // src_bucket_name is the name of the bucket where the object to be copied is located
+ string src_bucket_name = 2;
+ // dst_bucket_name is the name of the bucket where the object is copied to.
+ string dst_bucket_name = 3;
+ // src_object_name is the name of the object which to be copied
+ string src_object_name = 4;
+ // dst_object_name is the name of the object which is copied to
+ string dst_object_name = 5;
+ // primary_sp_approval is the approval info of the primary SP which indicates that primary sp confirm the user's request.
+ Approval dst_primary_sp_approval = 6;
+}
+```
+### MsgRejectSealObject
+
+A storage provider may reject to seal an object if it refuses to, or it can not because of unexpect error.
+
+```protobuf
+message MsgRejectSealObject {
+ option (cosmos.msg.v1.signer) = "operator";
+ // operator is the account address of the object owner
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // bucket_name is the name of the bucket where the object is stored.
+ string bucket_name = 2;
+ // object_name is the name of unsealed object to be reject.
+ string object_name = 3;
+}
+```
+### MsgCancelCreateObject
+
+User are able to cancel an initial object before it is sealed.
+
+```protobuf
+message MsgCancelCreateObject {
+ option (cosmos.msg.v1.signer) = "operator";
+ // operator is the account address of the operator
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // bucket_name is the name of the bucket
+ string bucket_name = 2;
+ // object_name is the name of the object
+ string object_name = 3;
+}
+```
+### MsgCreateGroup
+
+Used to create group.
+
+```protobuf
+message MsgCreateGroup {
+ option (cosmos.msg.v1.signer) = "creator";
+
+ // owner is the account address of group owner who create the group
+ string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // group_name is the name of the group. it's not globally unique.
+ string group_name = 2;
+ // member_request is a list of member which to be add or remove
+ repeated string members = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+}
+```
+### MsgDeleteGroup
+
+Used to delete group that is no longer used. Please note that the underlying members are not deleted yet.
+
+```protobuf
+message MsgDeleteGroup {
+ option (cosmos.msg.v1.signer) = "operator";
+
+ // operator is the account address of the operator who has the DeleteGroup permission of the group to be deleted.
+ string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // group_name is the name of the group which to be deleted
+ string group_name = 2;
+}
+
+```
+### MsgLeaveGroup
+
+A group member can choose to leave a group.
+
+```protobuf
+message MsgLeaveGroup {
+ option (cosmos.msg.v1.signer) = "member";
+
+ // member is the account address of the member who want to leave the group
+ string member = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // group_owner is the owner of the group you want to leave
+ string group_owner = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+ // group_name is the name of the group you want to leave
+ string group_name = 3;
+}
+```
diff --git a/docs/readme.md b/docs/readme.md
index 08b147b4e..236de4afa 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -3,14 +3,43 @@ This section dives into the internals of the Greenfield Blockchain implementatio
### Table of Contents
-- [Overview](introduction/overview.md)
-- [Key Management](core-concept/key_management.md)
-- [Token Economics](introduction/token_economics.md)
-- [Storage Provider Management](modules/storage_provider_management.md)
-- [Storage Metadata Models](core-concept/storage-metadata-models.md)
-- [Billing and Payment](modules/billing_and_payment.md)
-- [Cross Chain](modules/cross-chain.md)
-- [Consensus and Staking](modules/consensus_and_staking.md)
-- [Governance](modules/governance.md)
-- [Data Availability Challenge](modules/data_availability_challenge.md)
-- [Event](api-sdk/events.md)
\ No newline at end of file
+- Introduction
+ - [Overview](introduction/overview.md)
+ - [Ecosystem Players](introduction/ecosystem-player.md)
+ - [Token Economics](introduction/token_economics.md)
+- Core Concept
+ - [Accounts](core-concept/accounts.md)
+ - [Key Management](core-concept/key_management.md)
+ - [Gas Fee](core-concept/gas-fees.md)
+ - [Storage Metadata Models](core-concept/storage-metadata-models.md)
+ - [Billing and Payment](core-concept/billing-payment.md)
+ - [Transaction Lifecycle](core-concept/transaction-lifecycle.md)
+- Modules
+ - [State World](modules/state-world.md)
+ - [Storage Management](modules/storage-management.md)
+ - [Storage Provider](modules/storage_provider_management.md)
+ - [Billing and Payment](modules/billing_and_payment.md)
+ - [Cross Chain](modules/cross-chain.md)
+ - [Data Availability](modules/data_availability_challenge.md)
+ - [Consensus and Staking](modules/consensus_and_staking.md)
+ - [Governance](modules/governance.md)
+- API and SDK
+ - [Event and Indexer](api-sdk/events.md)
+ - [GRPC, REST, and Tendermint Endpoints](api-sdk/grpc_rest.md)
+ - [SDK](api-sdk/sdk.md)
+- Cli
+ - [Command-Line Interface](cli/cli.md)
+ - [Key Management](cli/key-management.md)
+ - [Bank](cli/bank.md)
+ - [Storage](cli/storage.md)
+ - [Storage Provider](cli/storage-provider.md)
+ - [Payment](cli/payment.md)
+ - [Validator Staking](cli/validator-staking.md)
+ - [Bridge](cli/bridge.md)
+ - [Governance](cli/governance.md)
+- Run Node
+ - [Run Local Network](run-node/run-local-network.md)
+ - [Run Testnet Node](run-node/run-testnet-node.md)
+ - [Run Mainnet Node](run-node/run-mainnet-node.md)
+ - [Interact with Node](run-node/interact-node.md)
+- [Resources](resources/resources.md)
From 5833c71db6899cc207db3ca72f946a1c483cca05 Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 19:30:19 +0800
Subject: [PATCH 4/7] docs: fix typo
---
docs/cli/bank.md | 2 +-
docs/core-concept/storage-metadata-models.md | 2 +-
docs/core-concept/transaction-lifecycle.md | 2 +-
docs/run-node/run-local-network.md | 4 ++--
4 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/cli/bank.md b/docs/cli/bank.md
index f95e5299d..f73eacd4a 100644
--- a/docs/cli/bank.md
+++ b/docs/cli/bank.md
@@ -9,7 +9,7 @@ supply of BNB in the application.
## Quick Start
-```
+```shell
## Start a local cluster
$ bash ./deployment/localup/localup.sh all 3
$ alias gnfd="./build/bin/gnfd"
diff --git a/docs/core-concept/storage-metadata-models.md b/docs/core-concept/storage-metadata-models.md
index 736ae7a6d..b6faabadf 100644
--- a/docs/core-concept/storage-metadata-models.md
+++ b/docs/core-concept/storage-metadata-models.md
@@ -1,4 +1,4 @@
-# Storage MetaData Models
+# Storage Metadata Models
The Greenfield is designed to be as compatible as possible with popular Web2 and Web3 standards.
It provides developers with similar API primitives and models as the most popular Web2 cloud storage: AWS s3.
diff --git a/docs/core-concept/transaction-lifecycle.md b/docs/core-concept/transaction-lifecycle.md
index 3f60d04fb..d42c4581b 100644
--- a/docs/core-concept/transaction-lifecycle.md
+++ b/docs/core-concept/transaction-lifecycle.md
@@ -2,7 +2,7 @@
This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition
is described in a [different doc](https://github.com/bnb-chain/greenfield-cosmos-sdk/blob/master/docs/core/transactions.md).
-The transaction will be referred to as `Tx`. {synopsis}
+The transaction will be referred to as `Tx`.
## Creation
diff --git a/docs/run-node/run-local-network.md b/docs/run-node/run-local-network.md
index baf64df65..8f0cdd5f0 100644
--- a/docs/run-node/run-local-network.md
+++ b/docs/run-node/run-local-network.md
@@ -9,9 +9,9 @@ Step 1: Install dependencies
The first step is to install the necessary dependencies, which include `Golang`, `Git`. Here are the steps to install them:
-Install Golang by following the instructions for your operating system on the official Golang website (https://golang.org/dl/).
+Install Golang by following the instructions for your operating system on the [official Golang website](https://golang.org/dl/).
-Install Git by following the instructions for your operating system on the official Git website (https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+Install Git by following the instructions for your operating system on the [official Git website](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
Build the Greenfield CLI tools by running the following command in your terminal:
From 203035e728240560fa1dd537a41e98d68cf86b7b Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 23:13:20 +0800
Subject: [PATCH 5/7] fix comments
---
docs/modules/{state-world.md => world-state.md} | 2 +-
docs/readme.md | 2 +-
x/storage/keeper/query.go | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
rename docs/modules/{state-world.md => world-state.md} (98%)
diff --git a/docs/modules/state-world.md b/docs/modules/world-state.md
similarity index 98%
rename from docs/modules/state-world.md
rename to docs/modules/world-state.md
index 6732df8c4..d83cf74a5 100644
--- a/docs/modules/state-world.md
+++ b/docs/modules/world-state.md
@@ -1,4 +1,4 @@
-# State World of Greenfield Blockchain
+# World State of Greenfield Blockchain
All Greenfield validators have such active data in full (at least the latest state). Anyone can join the blockchain as
full nodes to synchronize these data for free.
diff --git a/docs/readme.md b/docs/readme.md
index 236de4afa..11acc0e29 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -15,7 +15,7 @@ This section dives into the internals of the Greenfield Blockchain implementatio
- [Billing and Payment](core-concept/billing-payment.md)
- [Transaction Lifecycle](core-concept/transaction-lifecycle.md)
- Modules
- - [State World](modules/state-world.md)
+ - [State World](modules/world-state.md)
- [Storage Management](modules/storage-management.md)
- [Storage Provider](modules/storage_provider_management.md)
- [Billing and Payment](modules/billing_and_payment.md)
diff --git a/x/storage/keeper/query.go b/x/storage/keeper/query.go
index d1a056b8b..e468fad5f 100644
--- a/x/storage/keeper/query.go
+++ b/x/storage/keeper/query.go
@@ -3,13 +3,13 @@ package keeper
import (
"context"
+ "cosmossdk.io/math"
"github.com/cosmos/cosmos-sdk/store/prefix"
sdk "github.com/cosmos/cosmos-sdk/types"
"github.com/cosmos/cosmos-sdk/types/query"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
- "cosmossdk.io/math"
"github.com/bnb-chain/greenfield/x/storage/types"
)
From 944909c7521c3cf738b589f528bd008125724ec2 Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 23:21:50 +0800
Subject: [PATCH 6/7] rename swagger-docs to swagger
---
app/app.go | 2 +-
readme.md | 4 ++--
scripts/protoc-swagger-gen.sh | 2 +-
{swagger-docs => swagger}/config.json | 0
{swagger-docs => swagger}/docs.go | 0
{swagger-docs => swagger}/static/openapi.yml | 0
{swagger-docs => swagger}/static/swagger.yaml | 0
{swagger-docs => swagger}/statik/init.go | 0
{swagger-docs => swagger}/statik/statik.go | 0
.../swagger-ui/favicon-16x16.png | Bin
.../swagger-ui/favicon-32x32.png | Bin
{swagger-docs => swagger}/swagger-ui/index.html | 0
.../swagger-ui/oauth2-redirect.html | 0
.../swagger-ui/swagger-ui-bundle.js | 0
.../swagger-ui/swagger-ui-bundle.js.map | 0
.../swagger-ui/swagger-ui-es-bundle-core.js | 0
.../swagger-ui/swagger-ui-es-bundle-core.js.map | 0
.../swagger-ui/swagger-ui-es-bundle.js | 0
.../swagger-ui/swagger-ui-es-bundle.js.map | 0
.../swagger-ui/swagger-ui-standalone-preset.js | 0
.../swagger-ui/swagger-ui-standalone-preset.js.map | 0
{swagger-docs => swagger}/swagger-ui/swagger-ui.css | 0
.../swagger-ui/swagger-ui.css.map | 0
{swagger-docs => swagger}/swagger-ui/swagger-ui.js | 0
.../swagger-ui/swagger-ui.js.map | 0
25 files changed, 4 insertions(+), 4 deletions(-)
rename {swagger-docs => swagger}/config.json (100%)
rename {swagger-docs => swagger}/docs.go (100%)
rename {swagger-docs => swagger}/static/openapi.yml (100%)
rename {swagger-docs => swagger}/static/swagger.yaml (100%)
rename {swagger-docs => swagger}/statik/init.go (100%)
rename {swagger-docs => swagger}/statik/statik.go (100%)
rename {swagger-docs => swagger}/swagger-ui/favicon-16x16.png (100%)
rename {swagger-docs => swagger}/swagger-ui/favicon-32x32.png (100%)
rename {swagger-docs => swagger}/swagger-ui/index.html (100%)
rename {swagger-docs => swagger}/swagger-ui/oauth2-redirect.html (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-bundle.js (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-bundle.js.map (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-es-bundle-core.js (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-es-bundle-core.js.map (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-es-bundle.js (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-es-bundle.js.map (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-standalone-preset.js (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui-standalone-preset.js.map (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui.css (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui.css.map (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui.js (100%)
rename {swagger-docs => swagger}/swagger-ui/swagger-ui.js.map (100%)
diff --git a/app/app.go b/app/app.go
index d64934dac..f05a7521e 100644
--- a/app/app.go
+++ b/app/app.go
@@ -87,7 +87,7 @@ import (
"github.com/bnb-chain/greenfield/app/ante"
appparams "github.com/bnb-chain/greenfield/app/params"
- "github.com/bnb-chain/greenfield/swagger-docs"
+ "github.com/bnb-chain/greenfield/swagger"
"github.com/bnb-chain/greenfield/version"
bridgemodule "github.com/bnb-chain/greenfield/x/bridge"
bridgemodulekeeper "github.com/bnb-chain/greenfield/x/bridge/keeper"
diff --git a/readme.md b/readme.md
index 62284f9ba..ea3ff3dcb 100644
--- a/readme.md
+++ b/readme.md
@@ -76,7 +76,7 @@ $ bash ./deployment/localup/localup.sh stop
bash ./deployment/localup/localup.sh start 3
```
-More advanced script and command line usage, please refer to the [Tutorial](docs/modules/tutorial/readme.md).
+More advanced script and command line usage, please refer to the [Tutorial](docs/cli/cli.md).
## Key Modules
@@ -94,7 +94,7 @@ And the following modules are in cosmos-sdk:
- `x/staking`: based on the Proof-of-Stake logic. The elected validators are responsible for the security of the Greenfield blockchain.
They get involved in the governance and staking of the blockchain.
-Refer to the [Architecture Design](swagger-docs/modules/readme.md) to dive deep into these modules.
+Refer to the [docs](docs/readme.md) to dive deep into these modules.
## Join Testnet && Mainnet (coming soon..)
diff --git a/scripts/protoc-swagger-gen.sh b/scripts/protoc-swagger-gen.sh
index fa5c29ce5..c4e9ebfd7 100755
--- a/scripts/protoc-swagger-gen.sh
+++ b/scripts/protoc-swagger-gen.sh
@@ -19,7 +19,7 @@ cd ..
# combine swagger files
# uses nodejs package `swagger-combine`.
# all the individual swagger files need to be configured in `config.json` for merging
-swagger-combine ./swagger-docs/config.json -o ./swagger-docs/static/swagger.yaml -f yaml --continueOnConflictingPaths true --includeDefinitions true
+swagger-combine ./swagger/config.json -o ./swagger/static/swagger.yaml -f yaml --continueOnConflictingPaths true --includeDefinitions true
# clean swagger files
rm -rf ./tmp-swagger-gen
\ No newline at end of file
diff --git a/swagger-docs/config.json b/swagger/config.json
similarity index 100%
rename from swagger-docs/config.json
rename to swagger/config.json
diff --git a/swagger-docs/docs.go b/swagger/docs.go
similarity index 100%
rename from swagger-docs/docs.go
rename to swagger/docs.go
diff --git a/swagger-docs/static/openapi.yml b/swagger/static/openapi.yml
similarity index 100%
rename from swagger-docs/static/openapi.yml
rename to swagger/static/openapi.yml
diff --git a/swagger-docs/static/swagger.yaml b/swagger/static/swagger.yaml
similarity index 100%
rename from swagger-docs/static/swagger.yaml
rename to swagger/static/swagger.yaml
diff --git a/swagger-docs/statik/init.go b/swagger/statik/init.go
similarity index 100%
rename from swagger-docs/statik/init.go
rename to swagger/statik/init.go
diff --git a/swagger-docs/statik/statik.go b/swagger/statik/statik.go
similarity index 100%
rename from swagger-docs/statik/statik.go
rename to swagger/statik/statik.go
diff --git a/swagger-docs/swagger-ui/favicon-16x16.png b/swagger/swagger-ui/favicon-16x16.png
similarity index 100%
rename from swagger-docs/swagger-ui/favicon-16x16.png
rename to swagger/swagger-ui/favicon-16x16.png
diff --git a/swagger-docs/swagger-ui/favicon-32x32.png b/swagger/swagger-ui/favicon-32x32.png
similarity index 100%
rename from swagger-docs/swagger-ui/favicon-32x32.png
rename to swagger/swagger-ui/favicon-32x32.png
diff --git a/swagger-docs/swagger-ui/index.html b/swagger/swagger-ui/index.html
similarity index 100%
rename from swagger-docs/swagger-ui/index.html
rename to swagger/swagger-ui/index.html
diff --git a/swagger-docs/swagger-ui/oauth2-redirect.html b/swagger/swagger-ui/oauth2-redirect.html
similarity index 100%
rename from swagger-docs/swagger-ui/oauth2-redirect.html
rename to swagger/swagger-ui/oauth2-redirect.html
diff --git a/swagger-docs/swagger-ui/swagger-ui-bundle.js b/swagger/swagger-ui/swagger-ui-bundle.js
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-bundle.js
rename to swagger/swagger-ui/swagger-ui-bundle.js
diff --git a/swagger-docs/swagger-ui/swagger-ui-bundle.js.map b/swagger/swagger-ui/swagger-ui-bundle.js.map
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-bundle.js.map
rename to swagger/swagger-ui/swagger-ui-bundle.js.map
diff --git a/swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js b/swagger/swagger-ui/swagger-ui-es-bundle-core.js
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js
rename to swagger/swagger-ui/swagger-ui-es-bundle-core.js
diff --git a/swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js.map b/swagger/swagger-ui/swagger-ui-es-bundle-core.js.map
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-es-bundle-core.js.map
rename to swagger/swagger-ui/swagger-ui-es-bundle-core.js.map
diff --git a/swagger-docs/swagger-ui/swagger-ui-es-bundle.js b/swagger/swagger-ui/swagger-ui-es-bundle.js
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-es-bundle.js
rename to swagger/swagger-ui/swagger-ui-es-bundle.js
diff --git a/swagger-docs/swagger-ui/swagger-ui-es-bundle.js.map b/swagger/swagger-ui/swagger-ui-es-bundle.js.map
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-es-bundle.js.map
rename to swagger/swagger-ui/swagger-ui-es-bundle.js.map
diff --git a/swagger-docs/swagger-ui/swagger-ui-standalone-preset.js b/swagger/swagger-ui/swagger-ui-standalone-preset.js
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-standalone-preset.js
rename to swagger/swagger-ui/swagger-ui-standalone-preset.js
diff --git a/swagger-docs/swagger-ui/swagger-ui-standalone-preset.js.map b/swagger/swagger-ui/swagger-ui-standalone-preset.js.map
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui-standalone-preset.js.map
rename to swagger/swagger-ui/swagger-ui-standalone-preset.js.map
diff --git a/swagger-docs/swagger-ui/swagger-ui.css b/swagger/swagger-ui/swagger-ui.css
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui.css
rename to swagger/swagger-ui/swagger-ui.css
diff --git a/swagger-docs/swagger-ui/swagger-ui.css.map b/swagger/swagger-ui/swagger-ui.css.map
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui.css.map
rename to swagger/swagger-ui/swagger-ui.css.map
diff --git a/swagger-docs/swagger-ui/swagger-ui.js b/swagger/swagger-ui/swagger-ui.js
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui.js
rename to swagger/swagger-ui/swagger-ui.js
diff --git a/swagger-docs/swagger-ui/swagger-ui.js.map b/swagger/swagger-ui/swagger-ui.js.map
similarity index 100%
rename from swagger-docs/swagger-ui/swagger-ui.js.map
rename to swagger/swagger-ui/swagger-ui.js.map
From c0d780404ae9f3660c3046bf7a4b73e3c146c650 Mon Sep 17 00:00:00 2001
From: zjubfd <296179868@qq.com>
Date: Thu, 9 Mar 2023 23:26:13 +0800
Subject: [PATCH 7/7] fix golint
---
app/app.go | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/app/app.go b/app/app.go
index f05a7521e..d88a76fdb 100644
--- a/app/app.go
+++ b/app/app.go
@@ -87,7 +87,7 @@ import (
"github.com/bnb-chain/greenfield/app/ante"
appparams "github.com/bnb-chain/greenfield/app/params"
- "github.com/bnb-chain/greenfield/swagger"
+ docs "github.com/bnb-chain/greenfield/swagger"
"github.com/bnb-chain/greenfield/version"
bridgemodule "github.com/bnb-chain/greenfield/x/bridge"
bridgemodulekeeper "github.com/bnb-chain/greenfield/x/bridge/keeper"
