docs: add the overview of architecture && cross chain (#67)

.github/workflows/e2e-test.yml

@@ -54,6 +54,8 @@ jobs:
         cat ./deployment/localup/.env
     - name: run local chain
       run:  bash ./deployment/localup/localup.sh all 1 1
+    - name: check sp
+      run: bash ./deployment/localup/localup.sh sp_check 1 1
     - name: run e2e test
       run: |
         make e2e_test

docs/architecture/01-overview.md

@@ -0,0 +1,110 @@
+# 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.
+
+<div align="center"><img src="../asset/01-All%20Players%20of%20Greenfield.jpg"  height="80%" width="80%"></div>
+<div align="center"><i>Figure All Players of Greenfield</i></div>
+
+### 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.
+
+<div align="center"><img src="../asset/02-Greenfield%20Blockchain%20Network.jpg"  height="80%" width="80%"></div>
+<div align="center"><i>Figure Greenfield Blockchain Network</i></div>
+
+### 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.

docs/architecture/07-cross-chain.md

@@ -0,0 +1,175 @@
+# Cross Chain
+
+The real power of the Greenfield ecosystem lies in that the platform is not only designed to store the data, but also to
+support the creation of value based on the data assets and its related economy.
+
+The asset traits of the data are firstly established on the permissions, e.g. the permission to read the data. When 
+this right is disconnected from the data itself, they become tradable assets and enlarge the value of the data. This 
+can be amplified when the data itself can be executable (a new type of "Smart Code"), interact with each other, and 
+generate new data. This creates a lot of room to imagine building a new, data-intensive, trustless computing environment.
+
+Secondly, the data permissions can be transferred cross-chain onto BSC and become digital assets there. This creates a 
+variety of possibilities to integrate these assets with the existing DeFi protocols and models on BSC.
+
+This gets even further enhanced by the smart contracts on BSC, which enjoy the same address format as accounts on the 
+Greenfield blockchain and can be the owners of the data objects and inherit different permissions. This will unleash 
+many new business opportunities based on the data and its operations.
+
+## Cross-Chain with BSC
+
+The cross-chain model expects to achieve the following goals:
+
+- integratable with the existing systems: try to reuse the current
+  infrastructure and dApps as much as possible, such as NFT
+  Marketplace, data indexing, and blockchain explorers.
+
+- programmable: dApps can define how they want to wrap the assets from Greenfield.
+
+- secure and recoverable.
+
+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
+bandwidth and fast bridge.
+
+BNB will be transferred from BSC to Greenfield as the first cross-chain
+action. The initial validator set of Greenfield at the genesis will
+first lock a certain amount of BNB into the "Greenfield Token Hub"
+contract on BSC. This contract will also be used as part of the native
+bridge for BNB transferring after the genesis. These initial locked BNB
+will be used as the self-stake of validators and early days gas fees.
+
+## Framework
+
+<div align="center"><img src="../asset/03-Cross-chain%20Architecture.jpg"  height="80%" width="80%"></div>
+<div align="center"><i>Figure Cross-chain Architecture</i></div>
+
+The bottom layer is a cross-chain **Communication Layer**, which focuses
+on primitive communication package handling and verification. The middle
+layer implements the **Resource Mirror**. It is responsible for managing
+the resource assets that are defined on Greenfield but mirrored onto
+BSC. The top layer is the **Application Layer**, which are the smart
+contracts implemented by community developers on BSC to operate the
+mirrored resource entities with their primitives; Greenfield does not have
+such an application layer since itself does not provide programmability yet.
+The real dApps will have some part in this Application Layer and also
+interact with Greenfield Core and all sorts of supporting infrastructures.
+
+Because of the asymmetric framework, BSC focuses more on the
+application/control plane, while Greenfield is the data plane. To avoid
+state racing, the following rules are introduced:
+
+- Any resources that are initiated to create by BSC can only be controlled by BSC.
+
+- Any resources that are controlled by BSC can not transfer control rights to Greenfield.
+
+- Any resources that are controlled by Greenfield can transfer control rights to BSC.
+
+## Communication Layer
+
+The communication layer is composed of a set of **Greenfield Relayers**:
+
+- Each validator should run a relayer. Each relayer possesses a BLS
+  private key, with the address of the key stored on-chain as part
+  of the validator's mandatory information.
+
+- The relayer watches all cross-chain events happen on BSC and the
+  Greenfield blockchain independently. After enough blocks of
+  confirmation to reach finality, the relayer will sign a message by
+  the BLS key to confirm the events, and broadcast the signing
+  attestment, which is called "the vote", through a p2p network to
+  other relayers.
+
+- Once enough votes from the relayer are collected, the relayer will
+  assemble a cross-chain package transaction and submit it to BSC or
+  Greenfield network.
+
+## Resource Mirror Layer
+
+### 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
+below resource entities should be able to be mirrored on BSC:
+
+1. Account
+
+2. BNB
+
+3. Bucket
+
+4. Object
+
+5. Group
+
+The account mapping is natural: as BSC and Greenfield use the same
+address scheme. The same address values on both sides mean the same
+account. They do not require an actual mirror.
+
+BNB is a natively pegged token from the genesis of Greenfield. The
+"Token Hub" contract is a smart contract built on BSC to ensure
+that Greenfield cannot inflate BNB and secure the total circulation of
+BNB.
+
+Bucket, Object, and Group are mirrored onto BSC as NFTs of a new BEP
+revised from the ERC-721 standard. These NFTs have corresponding
+metadata information for the resources. The ownerships of the NFTs on
+BSC stand for the ownerships of these resources on Greenfield. As these
+ownerships are not transferable on Greenfield, these NFTs are not
+transferable on BSC.
+
+### Cross-Chain Operating Primitives
+
+A few series of cross-chain primitives are defined for dApps to call to
+operate on these resource entities.
+
+It is worth highlighting that smart contracts can call these primitives
+in a similar way as EOAs.
+
+Accounts
+
+- create payment accounts on BSC
+
+BNB:
+
+- transfer bidirectionally between BSC and Greenfield among accounts
+  (including even payment accounts)
+
+Bucket:
+
+- create a bucket on BSC
+
+- mirror bucket from Greenfield to BSC
+
+Object:
+
+- mirror object from Greenfield to BSC
+
+- create an object on BSC
+
+- grant/revoke permissions of objects on BSC to accounts/groups
+
+- copy objects on BSC
+
+- Kick off the execution of an object on BSC
+
+- associate buckets to payment accounts on BSC
+
+Group:
+
+- mirror group from Greenfield to BSC
+
+- create a group on BSC
+
+- change group members on BSC
+
+- leave a group on BSC
+
+Once these primitives are called by EOA or smart contracts, the
+predefined events will be emitted. Greenfield Relayers should pick up
+these events and relay them over to Greenfield and BSC. As the change
+will happen asynchronously, there will be specific cross-chain packages
+for acknowledgments or errors, which can trigger a callback. The caller
+of the primitives should pay the fees upfront for cross-chain operations
+and also for the potential callback. More details are discussed in Part 3.

docs/architecture/readme.md

@@ -3,7 +3,7 @@ This section dives into the internals of the Greenfield Blockchain implementatio
 
 ### Table of Contents
 
-- [Framework](./01-framework.md)
+- [Overview](./01-overview.md)
 - [Key Management](./02-key_management.md)
 - [Token Economics](./03-token_economics.md)
 - [Storage Provider Management](./04-storage_provider_management.md)