Skip to content

Commit

Permalink
docs: improve existing docs (ethereum#300)
Browse files Browse the repository at this point in the history 
* docs: add Travis and Gitter badges

* docs: make some correction on existing docs

Co-authored-by: meowsbits <b5c6@protonmail.com>

* docs: markdown fixes to achieve both mkdocs and GitHub flavor support

* docs: move installation and build info from README to /docs

* README.md: add some quick links to docs from README

Date: 2021-01-15 07:00:09-06:00
Signed-off-by: meows <b5c6@protonmail.com>

Co-authored-by: meowsbits <b5c6@protonmail.com>
  • Loading branch information
@ziogaschr @meowsbits
ziogaschr and meowsbits authored Jan 15, 2021
1 parent cf71560 commit 1702569
Show file tree
Hide file tree
Showing 15 changed files with 537 additions and 272 deletions.
111 changes: 7 additions & 104 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,110 +52,13 @@ Ellaism users are asked to switch to

## Documentation

- CoreGeth documentation is available [here](https://etclabscore.github.io/core-geth).
- Further go-ethereum documentation about can be found [here](https://geth.ethereum.org/docs/).
- Developers interested in writing documentation, please find documentation about documentation [here](./docs/developers/documentation.md).

## Install

### Pre-built executable

If you just want to download and run `geth` or any of the other tools here, this is the quickest and simplest way.

Binary archives are published at https://github.com/etclabscore/core-geth/releases. Find the latest one for your OS, download it, (check the SHA sum), unarchive it, and run!

### With Docker

All runnable examples below are for images limited to `geth`. For images including the full suite of
tools available from this source, use the Docker Hub tag prefix `alltools.`, like `etclabscore/core-geth:alltools.latest`, or the associated Docker file directly `./Dockerfile.alltools`.

#### `docker run`

One of the quickest ways to get Ethereum up and running on your machine is by using
Docker:

```shell
$ docker run -d \
--name core-geth \
-v $LOCAL_DATADIR:/root \
-p 30303:30303 \
-p 8545:8545 \
etclabscore/core-geth \
--classic \
--rpc --rpcport 8545
```

This will start `geth` in fast-sync mode with a DB memory allowance of 1GB just as the
above command does. It will also create a persistent volume in your `$LOCAL_DATADIR` for
saving your blockchain, as well as map the default devp2p and JSON-RPC API ports.

Do not forget `--http.addr 0.0.0.0`, if you want to access RPC from other containers
and/or hosts. By default, `geth` binds to the local interface and RPC endpoints is not
accessible from the outside.


#### `docker pull`

Docker images are automatically [published on Docker Hub](https://hub.docker.com/r/etclabscore/core-geth/tags).

##### Image: `latest`

Image `latest` is built automatically from the `master` branch whenever it's updated.

```shell
$ docker pull etclabscore/core-geth:latest
```

##### Image: `<tag>`

Repository tags like `v1.2.3` correspond to Docker tags like __`version-1.2.3`__.

An example:
```shell
$ docker pull etclabscore/core-geth:version-1.11.1
```

#### `docker build`

You can build a local docker image directly from the source:

```shell
$ git clone https://github.com/etclabscore/core-geth.git
$ cd core-geth
$ docker build -t=core-geth .
```

Or with all tools:

```shell
$ docker build -t core-geth-alltools -f Dockerfile.alltools .
```

### Build from source

#### Dependencies

- Make sure your system has __Go__ installed. Version 1.13+ is recommended. https://golang.org/doc/install
- Make sure your system has a C compiler installed. For example, with Linux Ubuntu:

```shell
$ sudo apt-get install -y build-essential
```

#### Source

Once the dependencies have been installed, it's time to clone and build the source:

```shell
$ git clone https://github.com/etclabscore/core-geth.git
$ cd core-geth
$ make all
$ ./build/bin/geth --help
```

## Documentation

For further documentation resources, please visit [./docs](./docs).
- CoreGeth documentation is available [here](https://etclabscore.github.io/core-geth).
+ Getting Started [Installation](https://etclabscore.github.io/core-geth/getting-started/installation) and [CLI](https://etclabscore.github.io/core-geth/getting-started/run-cli)
+ [JSONRPC API](https://etclabscore.github.io/core-geth/apis/jsonrpc-apis)
+ [Developers](https://etclabscore.github.io/core-geth/developers/build-from-source)
+ [Tutorials](https://etclabscore.github.io/core-geth/tutorials/private-network)
- Further [ethereum/go-ethereum](https://github.com/ethereum/go-ethereum) documentation about can be found [here](https://geth.ethereum.org/docs/).
- Documentation about documentation lives [here](./docs/developers/documentation.md).

## Contribution

Expand Down
39 changes: 22 additions & 17 deletions docs/apis/jsonrpc-apis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ hide:
## Programmatically interfacing `geth` nodes

As a developer, sooner rather than later you'll want to start interacting with `geth` and the
Ethereum network via your own programs and not manually through the console. To aid
this, `geth` has built-in support for a JSON-RPC based APIs ([standard APIs](https://github.com/ethereum/wiki/wiki/JSON-RPC)
and [`geth` specific APIs](https://github.com/ethereum/go-ethereum/wiki/Management-APIs)).
Ethereum Classic network via your own programs and not manually through the console. To aid
this, `geth` has built-in support for a JSON-RPC based APIs ([standard APIs](https://eth.wiki/json-rpc/API)
and [`geth` specific APIs](https://geth.ethereum.org/docs/rpc/server)).
These can be exposed via HTTP, WebSockets and IPC (UNIX sockets on UNIX based
platforms, and named pipes on Windows).

Expand All @@ -21,16 +21,19 @@ you'd expect.

HTTP based JSON-RPC API options:

* `--rpc` Enable the HTTP-RPC server
* `--rpcaddr` HTTP-RPC server listening interface (default: `localhost`)
* `--rpcport` HTTP-RPC server listening port (default: `8545`)
* `--rpcapi` API's offered over the HTTP-RPC interface (default: `eth,net,web3`)
* `--rpccorsdomain` Comma separated list of domains from which to accept cross origin requests (browser enforced)
* `--http` Enable the HTTP-RPC server
* `--http.addr` HTTP-RPC server listening interface (default: `localhost`)
* `--http.port` HTTP-RPC server listening port (default: `8545`)
* `--http.api` API's offered over the HTTP-RPC interface (default: `eth,net,web3`)
* `--http.corsdomain` Comma separated list of domains from which to accept cross origin requests (browser enforced)
* `--ws` Enable the WS-RPC server
* `--wsaddr` WS-RPC server listening interface (default: `localhost`)
* `--wsport` WS-RPC server listening port (default: `8546`)
* `--wsapi` API's offered over the WS-RPC interface (default: `eth,net,web3`)
* `--wsorigins` Origins from which to accept websockets requests
* `--ws.addr` WS-RPC server listening interface (default: `localhost`)
* `--ws.port` WS-RPC server listening port (default: `8546`)
* `--ws.api` API's offered over the WS-RPC interface (default: `eth,net,web3`)
* `--ws.origins` Origins from which to accept websockets requests
* `--graphql` Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if an HTTP server is started as well.
* `--graphql.corsdomain` Comma separated list of domains from which to accept cross origin requests (browser enforced)
* `--graphql.vhosts ` Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
* `--ipcdisable` Disable the IPC-RPC server
* `--ipcapi` API's offered over the IPC-RPC interface (default: `admin,debug,eth,miner,net,personal,shh,txpool,web3`)
* `--ipcpath` Filename for IPC socket/pipe within the datadir (explicit paths escape it)
Expand All @@ -39,10 +42,12 @@ You'll need to use your own programming environments' capabilities (libraries, t
connect via HTTP, WS or IPC to a `geth` node configured with the above flags and you'll
need to speak [JSON-RPC](https://www.jsonrpc.org/specification) on all transports. You
can reuse the same connection for multiple requests!
Here you can check the available [JSON-RPC calls](https://playground.open-rpc.org/?schemaUrl=https://gist.githubusercontent.com/ziogaschr/c51916d70ca5304bb3e3abf4dcd518ca/raw/8079eafd8de6436bd3e4ab6c9df0db64c25cd1a6/core-geth_rpc-discovery_1.11.21-unstable.json).

**Note: Please understand the security implications of opening up an HTTP/WS based
transport before doing so! Hackers on the internet are actively trying to subvert
Ethereum nodes with exposed APIs! Further, all browser tabs can access locally
running web servers, so malicious web pages could try to subvert locally available
APIs!**
!!! Attention

Please understand the security implications of opening up an HTTP/WS based
transport before doing so! Hackers on the internet are actively trying to subvert
Ethereum nodes with exposed APIs! Further, all browser tabs can access locally
running web servers, so malicious web pages could try to subvert locally available
APIs!
71 changes: 39 additions & 32 deletions docs/apis/openrpc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,37 +8,44 @@ hide:
## Discovery

CoreGeth supports [OpenRPC's Service Discovery method](https://spec.open-rpc.org/#service-discovery-method), enabling efficient and well-spec'd JSON RPC interfacing and tooling. This method follows the established JSON RPC patterns, and is accessible via HTTP, WebSocket, IPC, and console servers. To use this method:
```shell
$ curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"rpc.discover","params":[],"id":1}'
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"openrpc": "1.0.10",
"info": {
"description": "This API lets you interact with an EVM-based client via JSON-RPC",
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"title": "Ethereum JSON-RPC",
"version": "1.0.0"
},
"servers": [],
"methods": [
{
"description": "Returns the version of the current client",
"name": "web3_clientVersion",
"params": [],
"result": {
"description": "client version",
"name": "clientVersion",
"schema": {
"type": "string"
}

!!! Example

```shell
$ curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"rpc_discover","params":[],"id":1}'
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"openrpc": "1.0.10",
"info": {
"description": "This API lets you interact with an EVM-based client via JSON-RPC",
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"title": "Ethereum JSON-RPC",
"version": "1.0.0"
},
"summary": "current client version"
},
"servers": [],
"methods": [
{
"description": "Returns the version of the current client",
"name": "web3_clientVersion",
"params": [],
"result": {
"description": "client version",
"name": "clientVersion",
"schema": {
"type": "string"
}
},
"summary": "current client version"
},

[...]
```

!!! Tip "Better representation of the discovery result at the OpenRPC playground"

[...]
```
You can see an example use case of the discovery service in the respective [OpenRPC Playground](https://playground.open-rpc.org/?schemaUrl=https://gist.githubusercontent.com/ziogaschr/c51916d70ca5304bb3e3abf4dcd518ca/raw/8079eafd8de6436bd3e4ab6c9df0db64c25cd1a6/core-geth_rpc-discovery_1.11.21-unstable.json).
8 changes: 4 additions & 4 deletions docs/core/alltools.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ hide:

## Executables

The go-ethereum project comes with several wrappers/executables found in the `cmd`
The core-geth project comes with several wrappers/executables found in the `cmd`
directory, and which, with `make all`, will be built to `./build/bin/`.

| Command | Description |
| :----------: | ------------- |
| **`geth`** | Our main Ethereum CLI client. It is the entry point into the Ethereum network (main-, test- or private net), capable of running as a full node (default), archive node (retaining all historical state) or a light node (retrieving data live). It can be used by other processes as a gateway into the Ethereum network via JSON RPC endpoints exposed on top of HTTP, WebSocket and/or IPC transports. `geth --help` and the [CLI Wiki page](https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options) for command line options. |
| `abigen` | Source code generator to convert Ethereum contract definitions into easy to use, compile-time type-safe Go packages. It operates on plain [Ethereum contract ABIs](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI) with expanded functionality if the contract bytecode is also available. However, it also accepts Solidity source files, making development much more streamlined. Please see our [Native DApps](https://github.com/ethereum/go-ethereum/wiki/Native-DApps:-Go-bindings-to-Ethereum-contracts) wiki page for details. |
| **`geth`** | Our main Ethereum Classic CLI client. It is the entry point into the Ethereum network (main-, test- or private net), capable of running as a full node (default), archive node (retaining all historical state) or a light node (retrieving data live). It can be used by other processes as a gateway into the Ethereum network via JSON RPC endpoints exposed on top of HTTP, WebSocket and/or IPC transports. `geth --help` and the [CLI page](../run-cli/#command-line-options) for command line options. |
| `abigen` | Source code generator to convert Ethereum contract definitions into easy to use, compile-time type-safe Go packages. It operates on plain [Ethereum contract ABIs](https://docs.soliditylang.org/en/develop/abi-spec.html) with expanded functionality if the contract bytecode is also available. However, it also accepts Solidity source files, making development much more streamlined. Please see our [Native DApps](https://geth.ethereum.org/docs/dapp/native-bindings) wiki page for details. |
| `bootnode` | Stripped down version of our Ethereum client implementation that only takes part in the network node discovery protocol, but does not run any of the higher level application protocols. It can be used as a lightweight bootstrap node to aid in finding peers in private networks. |
| `evm` | Developer utility version of the EVM (Ethereum Virtual Machine) that is capable of running bytecode snippets within a configurable environment and execution mode. Its purpose is to allow isolated, fine-grained debugging of EVM opcodes (e.g. `evm --code 60ff60ff --debug`). |
| `gethrpctest` | Developer utility tool to support our [ethereum/rpc-test](https://github.com/ethereum/rpc-tests) test suite which validates baseline conformity to the [Ethereum JSON RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC) specs. Please see the [test suite's readme](https://github.com/ethereum/rpc-tests/blob/master/README.md) for details. |
| `gethrpctest` | Developer utility tool to support the [ethereum/rpc-test](https://github.com/ethereum/rpc-tests) test suite which validates baseline conformity to the [Ethereum JSON RPC](https://eth.wiki/json-rpc/API) specs. Please see the [test suite's readme](https://github.com/ethereum/rpc-tests/blob/master/README.md) for details. |
| `rlpdump` | Developer utility tool to convert binary RLP ([Recursive Length Prefix](https://github.com/ethereum/wiki/wiki/RLP)) dumps (data encoding used by the Ethereum protocol both network as well as consensus wise) to user-friendlier hierarchical representation (e.g. `rlpdump --hex CE0183FFFFFFC4C304050583616263`). |
2 changes: 1 addition & 1 deletion docs/core/evmc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ EVMC does not. EVMC only supports the Fork configurations supported by ethereum/
Thus, the implementation at core-geth of EVMC requires a somewhat arbitrary mapping of granular features as keys toggling
entire Ethereum fork configurations.

The following code snippet, taken from `./core/vm/evmc.go`, handles this translation.
The following code snippet, taken from [`./core/vm/evmc.go`](https://github.com/etclabscore/core-geth/blob/master/core/vm/evmc.go#L301-L327), handles this translation.

```go
// getRevision translates ChainConfig's HF block information into EVMC revision.
Expand Down
Loading

0 comments on commit 1702569

Please sign in to comment.