Merge pull request #68 from WeAreAmaze/docs

Docs

docs/SUMMARY.md

@@ -0,0 +1,28 @@
+# AMC docs
+
+1. [Introduction](./intro.md)
+1. [Installation](./installation/installation.md)
+   1. [Pre-Built Binaries](./installation/binaries.md)
+   1. [Docker](./installation/docker.md)
+   1. [Build from Source](./installation/source.md)
+   1. [Build for ARM devices](./installation/build-for-arm-devices.md)   
+1. [Run a Node](./run/run-a-node.md)
+   1. [Mainnet or official testnets](./run/mainnet.md)
+   1. [Private testnet](./run/private-testnet.md)
+   1. [Metrics](./run/observability.md)
+   1. [Transaction types](./run/transactions.md)
+   1. [Ports](./run/ports.md)
+   1. [Troubleshooting](./run/troubleshooting.md)
+1. [Interacting with AMCover JSON-RPC](./jsonrpc/intro.md)
+   1. [eth](./jsonrpc/eth.md)
+   1. [web3](./jsonrpc/web3.md)
+   1. [net](./jsonrpc/net.md)
+   1. [txpool](./jsonrpc/txpool.md)
+   1. [debug](./jsonrpc/debug.md)
+   1. [trace](./jsonrpc/trace.md)
+   1. [admin](./jsonrpc/admin.md)
+   1. [rpc](./jsonrpc/rpc.md)
+1. [CLI Reference](./cli/cli.md)   
+1. [Developers](./developers/developers.md)
+   1. [Code Submission Standards](./developers/codesubmission.md)
+   2. [Contribute](./developers/contribute.md)

docs/cli/cli.md

@@ -0,0 +1,98 @@
+# CLI Reference
+
+The AMC node is operated via the CLI by running the `amc` command. To stop it, press `ctrl-c`. You may need to wait a bit as amc down existing p2p connections or other cleanup tasks.
+
+However, amc has more commands than that:
+
+```bash
+amc --help
+```
+
+See below for the full list of commands.
+
+## Commands
+
+```
+$ amc --help
+NAME:
+   amc - AmazeChain system
+
+USAGE:
+   amc [global options] command [command options] [arguments...]
+
+VERSION:
+   0.01.1-36074172
+
+COMMANDS:
+   wallet   Manage AmazeChain presale wallets
+   account  Manage accounts
+   export   Export AmazeChain data
+   help, h  Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --account.allow.insecure.unlock  Allow insecure account unlocking when account-related RPCs are exposed by http (default: false)
+   --account.keystore value         Directory for the keystore (default = inside the datadir)
+   --account.lightkdf               Reduce key-derivation RAM & CPU usage at some expense of KDF strength (default: false)
+   --account.password value         Password file to use for non-interactive password input
+   --account.unlock value           Comma separated list of accounts to unlock
+   --authrpc                        Enable the AUTH-RPC server (default: false)
+   --authrpc.addr value             Listening address for authenticated APIs
+   --authrpc.jwtsecret value        Path to a JWT secret to use for authenticated RPC endpoints
+   --authrpc.port value             Listening port for authenticated APIs (default: 0)
+   --blockchain value               Loading a Configuration File
+   --data.dir value                 data save dir (default: "./amc/")
+   --engine.etherbase value         consensus etherbase
+   --engine.miner                   miner (default: false)
+   --engine.type value              consensus engine (default: "APosEngine")
+   --help, -h                       show help (default: false)
+   --http                           Enable the HTTP json-rpc server (default: false)
+   --http.addr value                HTTP server listening interface (default: "127.0.0.1")
+   --http.api value                 API's offered over the HTTP-RPC interface
+   --http.corsdomain value          Comma separated list of domains from which to accept cross origin requests (browser enforced)
+   --http.port value                HTTP server listening port (default: "20012")
+   --ipcpath value                  Filename for IPC socket/pipe within the data dir (explicit paths escape it) (default: "amc.ipc")
+   --log.compress                   logger file compress (default: false)
+   --log.level value                logger output level (value:[debug,info,warn,error,dpanic,panic,fatal]) (default: "debug")
+   --log.maxAge value               logger file max age (default: 30)
+   --log.maxBackups value           logger file max backups (default: 10)
+   --log.maxSize value              logger file max size M (default: 10)
+   --log.name value                 logger file name and path (default: "amc.log")
+   --metrics                        Enable metrics collection and reporting (default: false)
+   --metrics.addr value             Enable stand-alone metrics HTTP server listening interface. (default: "127.0.0.1")
+   --metrics.port value             Metrics HTTP server listening port.
+Please note that --metrics.addr must be set to start the server. (default: 6060)
+   --node.key value                                           node private
+   --p2p.allowlist value                                      The CIDR subnet for allowing only certain peer connections. Using "public" would allow only public subnets. Example: 192.168.0.0/16 would permit connections to peers on your local network only. The default is to accept all connections.
+   --p2p.bootstrap value [ --p2p.bootstrap value ]            bootstrap node info
+   --p2p.bootstrap-node value [ --p2p.bootstrap-node value ]  The address of bootstrap node. Beacon node will connect for peer discovery via DHT.  Multiple nodes can be passed by using the flag multiple times but not comma-separated. You can also pass YAML files containing multiple nodes.
+   --p2p.denylist value [ --p2p.denylist value ]              The CIDR subnets for denying certainty peer connections. Using "private" would deny all private subnets. Example: 192.168.0.0/16 would deny connections from peers on your local network only. The default is to accept all connections.
+   --p2p.host-dns value                                       The DNS address advertised by libp2p. This may be used to advertise an external DNS.
+   --p2p.host-ip value                                        The IP address advertised by libp2p. This may be used to advertise an external IP.
+   --p2p.key value                                            private key of p2p node
+   --p2p.limit.block-batch value                              The amount of blocks the local peer is bounded to request and respond to in a batch. (default: 64)
+   --p2p.limit.block-burst-factor value                       The factor by which block batch limit may increase on burst. (default: 2)
+   --p2p.limit.block-limiter-period value                     Period to calculate expected limit for a single peer. (default: 5)
+   --p2p.listen value [ --p2p.listen value ]                  p2p listen address
+   --p2p.local-ip value                                       The local ip address to listen for incoming data.
+   --p2p.max-peers value                                      The max number of p2p peers to maintain. (default: 5)
+   --p2p.metadata value                                       The file containing the metadata to communicate with other peers.
+   --p2p.min-sync-peers value                                 The required number of valid peers to connect with before syncing. (default: 1)
+   --p2p.no-discovery                                         Enable only local network p2p and do not connect to cloud bootstrap nodes. (default: false)
+   --p2p.peer value [ --p2p.peer value ]                      Connect with this peer. This flag may be used multiple times.
+   --p2p.priv-key value                                       The file containing the private key to use in communications with other peers.
+   --p2p.relay-node value                                     The address of relay node. The beacon node will connect to the relay node and advertise their address via the relay node to other peers
+   --p2p.static-id                                            Enables the peer id of the node to be fixed by saving the generated network key to the default key path. (default: true)
+   --p2p.tcp-port value                                       The port used by libp2p. (default: 61016)
+   --p2p.udp-port value                                       The port used by discv5. (default: 61015)
+   --pprof                                                    Enable the pprof HTTP server (default: false)
+   --pprof.block                                              Turn on block profiling (default: false)
+   --pprof.maxcpu value                                       setup number of cpu (default: 0)
+   --pprof.mutex                                              Turn on mutex profiling (default: false)
+   --pprof.port value                                         pprof HTTP server listening port (default: 0)
+   --version, -v                                              print the version (default: false)
+   --ws                                                       Enable the WS-RPC server (default: false)
+   --ws.addr value                                            WS-RPC server listening interface
+   --ws.api value                                             API's offered over the WS-RPC interface
+   --ws.origins value                                         Origins from which to accept websockets requests
+   --ws.port value                                            WS-RPC server listening port (default: "20013")
+```

docs/developers/codesubmission.md

@@ -0,0 +1,42 @@
+# Code Submission Standards
+
+This document outlines the code submission and version control standards, with the code repository being managed based on git.
+
+Branching Model
+The code repository adopts a branching model for management, with the main branches as follows:
+- master
+- develop
+- feature/xxxx
+- hotfix
+
+There are two primary branches in the repository:
+master
+This is the product's main code branch, maintaining a stable codebase for external use. Direct work on this master branch is not allowed; instead, work should be done on other specified, independent feature branches (we will talk about this shortly). Not directly committing changes to the master branch is also a common rule in many workflows.
+
+develop
+The development branch is the base branch for any new development. When you start a new feature branch, it will be based on development. Additionally, this branch also collects all completed features, waiting to be integrated into the master branch.
+
+These two branches are known as long-term branches. They will exist throughout the entire lifecycle of the project. Other branches, such as those for features or releases, are only temporary. They are created as needed and deleted once they have completed their task.
+
+feature
+The feature is used for the development of functionalities and features.
+
+Feature Development
+The feature development process is as follows:
+1. Start a new feature
+   Each time a new feature is started, branch off from develop with a feature/xxx branch. Once the feature is completed, merge it back into develop.
+2. Feature submission
+   After the feature development is completed, the developer submits a pull request, waits for code review, and after passing the review, merges into the develop branch and deletes the feature/xxx branch.
+
+Managing Releases
+Release management is another very important topic in version control.
+Creating a Release
+When you think the code in the "develop" branch is now a mature release version, which means: first, it includes all new features and necessary fixes; second, it has been thoroughly tested. If both points are satisfied, then it's time to start generating a new release:
+1. Merge the develop branch into master.
+2. Tag the current master and issue the corresponding release version.
+
+hotfix
+Often, just a few hours or days after a release version has been fully tested, some minor errors may be discovered. In this case, we need to create a hotfix branch:
+1. Branch off from the main branch to make the hotfix.
+2. Submit a pull request and wait for code review.
+3. After the review, merge into both the master and develop branches.

docs/developers/contribute.md

@@ -0,0 +1,2 @@
+# Contribute
+amc has docs specifically geared for developers and contributors, including documentation on the structure and architecture of amc, the general workflow we employ, and other useful tips. You can find these docs here. Check out our contributing guidelines here.

docs/developers/developers.md

@@ -0,0 +1,3 @@
+# Developers
+
+amc is composed of several packages that can be used in standalone projects. If you are interested in using one or more of the packages, you can get an overview of them in the developer docs, or take a look at the crate docs.

docs/installation/binaries.md

@@ -0,0 +1,10 @@
+# Binaries
+
+Archives of pre-compiled binary files ready for Windows, macOS, and Linux are available. They are static executables. Users of platforms not explicitly listed below should download one of these archives.
+
+If you use macOS Homebrew or Linuxbrew, you can install amc from Amaze's homebrew tap:
+
+```text
+brew install amazechain/amc
+```
+

docs/installation/build-for-arm-devices.md

@@ -0,0 +1,76 @@
+# Building for ARM devices
+
+amc can be built for and run on ARM devices, but there are several considerations to be taken into account beforehand.
+
+## CPU Architecture
+
+First, you must have a 64-bit CPU and Operating System, otherwise some of the project dependencies will not be able to compile or be executed.
+
+## Memory Layout on AArch64
+
+Then, you must setup the virtual memory layout in such a way that the user space is sufficiently large.
+From [the Linux Kernel documentation](https://www.kernel.org/doc/html/v5.3/arm64/memory.html#:~:text=AArch64%20Linux%20uses%20either%203,for%20both%20user%20and%20kernel.), you can see that the memory layout with 4KB pages and a level-3 translation table limits the user space to 512GB, which is too low for AMCto sync on Ethereum mainnet.
+
+## ARM Board Virtual Memory Limitation
+
+### Issue Description
+
+Some ARM boards are equipped with only 3-level paging, which imposes a virtual memory limitation of 256GB for user space on Linux. This limitation can be a challenge for running applications like "reth", as the MDBX (Memory-mapped Database eXtreme) library requires a larger virtual memory allocation by design.
+
+### Understanding the Limitation
+
+To determine if a specific ARM board is affected by this virtual memory limitation:
+
+1. **Check Specifications:** When considering an ARM board, review its specifications for information on paging levels. Boards with 3-level paging may have a 256GB virtual memory limit.
+
+2. **Manufacturer Documentation:** Consult the official ARM board documentation for details on supported paging levels.
+
+3. **Community Discussions:** Search online ARM and Linux forums for insights into virtual memory limitations of specific boards.
+
+### Additional Context
+
+According to MDBX documentation, changing this upper bound, which dictates the maximum size the database can reach, is a costly operation. Therefore, a reasonably large value was chosen. Given that the upper bound is currently set to 4TB, the assumption was that growth to 3TB might occur relatively soon. If the upper bound size is set to only 342GB, then "reth" cannot store more than 342GB of data, which is insufficient for a full sync.
+
+It's worth noting that on x86_64 architecture, there is a 48-bit address space divided in half between user space and the kernel, providing each with 128TB of address space. In contrast, AArch64 architecture features a user space address space of 512GB and a kernel address space of 256TB.
+
+Some newer versions of ARM architecture offer support for Large Virtual Address space, but enabling this requires running with a 64KB page size. The specifics of how to enable this functionality might vary.
+
+### Additional Resources
+
+- [ARM developer documentation](https://developer.arm.com/documentation/ddi0406/cb/Appendixes/ARMv4-and-ARMv5-Differences/System-level-memory-model/Virtual-memory-support)
+- [ARM Community Forums](https://community.arm.com)
+
+## Build amc
+
+If both your CPU architecture and memory layout are valid, the instructions for building amc will not differ from the standard process.
+
+## Troubleshooting
+
+> If you ever need to recompile the Linux Kernel because the official OS images for your ARM board don't have the right memory layout configuration, you can use [the Armbian build framework](https://github.com/armbian/build).
+
+### Failed to open database
+
+This error is raised whenever MBDX can not open a database due to the limitations imposed by the memory layout of your kernel. If the user space is limited to 512GB, the database will not be able to grow below this size.
+
+You will need to recompile the Linux Kernel to fix the issue.
+
+A simple and safe approach to achieve this is to use the Armbian build framework to create a new image of the OS that will be flashed to a storage device of your choice - an SD card for example - with the following kernel feature values:
+- **Page Size**: 64 KB
+- **Virtual Address Space Size**: 48 Bits
+
+To be able to build an Armbian image and set those values, you will need to:
+- Clone the Armbian build framework repository
+```shell
+git clone https://github.com/armbian/build
+cd build
+```
+- Run the compile script with the following parameters:
+```shell
+./compile.sh \
+BUILD_MINIMAL=yes \
+BUILD_DESKTOP=no \
+KERNEL_CONFIGURE=yes \
+CARD_DEVICE="/dev/sdX" # Replace sdX with your own storage device
+```
+- From there, you will be able to select the target board, the OS release and branch. Then, once you get in the **Kernel Configuration** screen, select the **Kernel Features options** and set the previous values accordingly.
+- Wait for the process to finish, plug your storage device into your board and start it. You can now download or install AMCand it should work properly.