From 867550dd8bf2cac0fc4cc7039c2e83c432947354 Mon Sep 17 00:00:00 2001 From: Zach Date: Fri, 22 Jun 2018 18:16:51 -0400 Subject: [PATCH] docs: update abci links (#1796) --- .gitignore | 1 - docs/abci-cli.md | 15 +++++++-------- abci/specification.md => docs/abci-spec.md | 2 +- docs/app-architecture.md | 2 +- docs/app-development.md | 14 +++++++------- docs/conf.py | 7 ------- docs/determinism.md | 2 -- docs/getting-started.md | 12 ++++-------- docs/how-to-read-logs.md | 2 +- docs/introduction.md | 10 +++++----- docs/spec/software/abci.md | 6 +++--- docs/specification/block-structure.rst | 6 ++---- docs/specification/validators.rst | 3 +-- docs/using-tendermint.md | 3 +-- 14 files changed, 33 insertions(+), 52 deletions(-) rename abci/specification.md => docs/abci-spec.md (99%) diff --git a/.gitignore b/.gitignore index e4107840b..bcfd36db1 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,6 @@ test/logs coverage.txt docs/_build docs/tools -docs/abci-spec.md *.log abci-cli abci/types/types.pb.go diff --git a/docs/abci-cli.md b/docs/abci-cli.md index 14095d162..d1ab696eb 100644 --- a/docs/abci-cli.md +++ b/docs/abci-cli.md @@ -10,15 +10,14 @@ Make sure you [have Go installed](https://golang.org/doc/install). Next, install the `abci-cli` tool and example applications: - go get -u github.com/tendermint/abci/cmd/abci-cli + go get github.com/tendermint/tendermint -If this fails, you may need to use [dep](https://github.com/golang/dep) to get vendored dependencies: - cd $GOPATH/src/github.com/tendermint/abci + cd $GOPATH/src/github.com/tendermint/tendermint make get_tools make get_vendor_deps - make install + make install_abci Now run `abci-cli` to see the list of commands: @@ -61,7 +60,7 @@ as `abci-cli` above. The kvstore just stores transactions in a merkle tree. Its code can be found -[here](https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go) +[here](https://github.com/tendermint/tendermint/blob/develop/abci/cmd/abci-cli/abci-cli.go) and looks like: func cmdKVStore(cmd *cobra.Command, args []string) error { @@ -124,7 +123,7 @@ response. The server may be generic for a particular language, and we provide a [reference implementation in -Golang](https://github.com/tendermint/abci/tree/master/server). See the +Golang](https://github.com/tendermint/tendermint/tree/develop/abci/server). See the [list of other ABCI implementations](./ecosystem.html) for servers in other languages. @@ -204,7 +203,7 @@ Now that we've got the hang of it, let's try another application, the "counter" app. Like the kvstore app, its code can be found -[here](https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go) +[here](https://github.com/tendermint/tendermint/blob/master/abci/cmd/abci-cli/abci-cli.go) and looks like: func cmdCounter(cmd *cobra.Command, args []string) error { @@ -301,7 +300,7 @@ But the ultimate flexibility comes from being able to write the application easily in any language. We have implemented the counter in a number of languages [see the -example directory](https://github.com/tendermint/abci/tree/master/example). +example directory](https://github.com/tendermint/tendermint/tree/develop/abci/example). To run the Node JS version, `cd` to `example/js` and run diff --git a/abci/specification.md b/docs/abci-spec.md similarity index 99% rename from abci/specification.md rename to docs/abci-spec.md index 25b9d7d0e..f9677f448 100644 --- a/abci/specification.md +++ b/docs/abci-spec.md @@ -3,7 +3,7 @@ ## Message Types ABCI requests/responses are defined as simple Protobuf messages in [this -schema file](https://github.com/tendermint/abci/blob/master/types/types.proto). +schema file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto). TendermintCore sends the requests, and the ABCI application sends the responses. Here, we provide an overview of the messages types and how they are used by Tendermint. Then we describe each request-response pair diff --git a/docs/app-architecture.md b/docs/app-architecture.md index 64b1a3794..401e28cca 100644 --- a/docs/app-architecture.md +++ b/docs/app-architecture.md @@ -47,4 +47,4 @@ See the following for more extensive documentation: - [Tendermint RPC Docs](https://tendermint.github.io/slate/) - [Tendermint in Production](https://github.com/tendermint/tendermint/pull/1618) - [Tendermint Basics](https://tendermint.readthedocs.io/en/master/using-tendermint.html) -- [ABCI spec](https://github.com/tendermint/abci/blob/develop/specification.md) +- [ABCI spec](https://github.com/tendermint/tendermint/blob/develop/abci/docs/abci-spec.md) diff --git a/docs/app-development.md b/docs/app-development.md index 488657670..0b6c402ef 100644 --- a/docs/app-development.md +++ b/docs/app-development.md @@ -49,7 +49,7 @@ The message protocol consists of pairs of requests and responses. Some messages have no fields, while others may include byte-arrays, strings, or integers. See the `message Request` and `message Response` definitions in [the protobuf definition -file](https://github.com/tendermint/abci/blob/master/types/types.proto), +file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto), and the [protobuf documentation](https://developers.google.com/protocol-buffers/docs/overview) for more details. @@ -72,9 +72,9 @@ Both can be tested using the `abci-cli` by setting the `--abci` flag appropriately (ie. to `socket` or `grpc`). See examples, in various stages of maintenance, in -[Go](https://github.com/tendermint/abci/tree/master/server), +[Go](https://github.com/tendermint/tendermint/tree/develop/abci/server), [JavaScript](https://github.com/tendermint/js-abci), -[Python](https://github.com/tendermint/abci/tree/master/example/python3/abci), +[Python](https://github.com/tendermint/tendermint/tree/develop/abci/example/python3/abci), [C++](https://github.com/mdyring/cpp-tmsp), and [Java](https://github.com/jTendermint/jabci). @@ -84,7 +84,7 @@ If GRPC is available in your language, this is the easiest approach, though it will have significant performance overhead. To get started with GRPC, copy in the [protobuf -file](https://github.com/tendermint/abci/blob/master/types/types.proto) +file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto) and compile it using the GRPC plugin for your language. For instance, for golang, the command is `protoc --go_out=plugins=grpc:. types.proto`. See the [grpc documentation for more details](http://www.grpc.io/docs/). @@ -125,12 +125,12 @@ received or a block is committed. It is unlikely that you will need to implement a client. For details of our client, see -[here](https://github.com/tendermint/abci/tree/master/client). +[here](https://github.com/tendermint/tendermint/tree/develop/abci/client). Most of the examples below are from [kvstore -application](https://github.com/tendermint/abci/blob/master/example/kvstore/kvstore.go), +application](https://github.com/tendermint/tendermint/blob/develop/abci/example/kvstore/kvstore.go), which is a part of the abci repo. [persistent_kvstore -application](https://github.com/tendermint/abci/blob/master/example/kvstore/persistent_kvstore.go) +application](https://github.com/tendermint/tendermint/blob/develop/abci/example/kvstore/persistent_kvstore.go) is used to show `BeginBlock`, `EndBlock` and `InitChain` example implementations. diff --git a/docs/conf.py b/docs/conf.py index 7d52a4932..0cfc05cdf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -197,10 +197,3 @@ copyfile('../DOCKER/README.md', tools_dir+'/docker.md') urllib.urlretrieve(tools_repo+tools_branch+'/tm-bench/README.md', filename=tools_dir+'/benchmarking.md') urllib.urlretrieve(tools_repo+tools_branch+'/tm-monitor/README.md', filename=tools_dir+'/monitoring.md') - -#### abci spec ################################# - -abci_repo = "https://raw.githubusercontent.com/tendermint/abci/" -abci_branch = "develop" - -urllib.urlretrieve(abci_repo+abci_branch+'/specification.md', filename='abci-spec.md') diff --git a/docs/determinism.md b/docs/determinism.md index 95958bb1f..2e23476c6 100644 --- a/docs/determinism.md +++ b/docs/determinism.md @@ -1,5 +1,3 @@ # On Determinism Arguably, the most difficult part of blockchain programming is determinism - that is, ensuring that sources of indeterminism do not creep into the design of such systems. - -See [this issue](https://github.com/tendermint/abci/issues/56) for more information on the potential sources of indeterminism. diff --git a/docs/getting-started.md b/docs/getting-started.md index 9767dae5a..8294d1e9b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -25,15 +25,11 @@ more info. Then run - go get -u github.com/tendermint/abci/cmd/abci-cli - -If there is an error, install and run the -[dep](https://github.com/golang/dep) tool to pin the dependencies: - - cd $GOPATH/src/github.com/tendermint/abci + go get github.com/tendermint/tendermint + cd $GOPATH/src/github.com/tendermint/tendermint make get_tools make get_vendor_deps - make install + make install_abci Now you should have the `abci-cli` installed; you'll see a couple of commands (`counter` and `kvstore`) that are example applications written @@ -132,7 +128,7 @@ of the ASCII of `abcd`. You can verify this in a python 2 shell by running `"61626364".decode('base64')` or in python 3 shell by running `import codecs; codecs.decode("61626364", 'base64').decode('ascii')`. Stay tuned for a future release that [makes this output more -human-readable](https://github.com/tendermint/abci/issues/32). +human-readable](https://github.com/tendermint/tendermint/issues/1794). Now let's try setting a different key and value: diff --git a/docs/how-to-read-logs.md b/docs/how-to-read-logs.md index 92f563cff..dd59d1848 100644 --- a/docs/how-to-read-logs.md +++ b/docs/how-to-read-logs.md @@ -103,7 +103,7 @@ little overview what they do. - `abci-client` As mentioned in [Application Development Guide](app-development.md#abci-design), Tendermint acts as an ABCI client with respect to the application and maintains 3 connections: mempool, consensus and query. The code used by Tendermint Core can - be found [here](https://github.com/tendermint/abci/tree/master/client). + be found [here](https://github.com/tendermint/tendermint/tree/develop/abci/client). - `blockchain` Provides storage, pool (a group of peers), and reactor for both storing and exchanging blocks between peers. - `consensus` The heart of Tendermint core, which is the diff --git a/docs/introduction.md b/docs/introduction.md index 419071dca..4503e195e 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -119,9 +119,9 @@ consensus engine, and provides a particular application state. ## ABCI Overview The [Application BlockChain Interface -(ABCI)](https://github.com/tendermint/abci) allows for Byzantine Fault -Tolerant replication of applications written in any programming -language. +(ABCI)](https://github.com/tendermint/tendermint/tree/develop/abci) +allows for Byzantine Fault Tolerant replication of applications +written in any programming language. ### Motivation @@ -159,7 +159,7 @@ Teaspoon). [Tendermint Core](https://github.com/tendermint/tendermint) (the "consensus engine") communicates with the application via a socket -protocol that satisfies the [ABCI](https://github.com/tendermint/abci). +protocol that satisfies the ABCI. To draw an analogy, lets talk about a well-known cryptocurrency, Bitcoin. Bitcoin is a cryptocurrency blockchain where each node @@ -187,7 +187,7 @@ core to the application. The application replies with corresponding response messages. The messages are specified here: [ABCI Message -Types](https://github.com/tendermint/abci#message-types). +Types](https://github.com/tendermint/tendermint/blob/develop/abci/README.md#message-types). The **DeliverTx** message is the work horse of the application. Each transaction in the blockchain is delivered with this message. The diff --git a/docs/spec/software/abci.md b/docs/spec/software/abci.md index 9c9e6a58b..613e181f0 100644 --- a/docs/spec/software/abci.md +++ b/docs/spec/software/abci.md @@ -4,14 +4,14 @@ ABCI is the interface between Tendermint (a state-machine replication engine) and an application (the actual state machine). The ABCI message types are defined in a [protobuf -file](https://github.com/tendermint/abci/blob/master/types/types.proto). +file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto). For full details on the ABCI message types and protocol, see the [ABCI -specificaiton](https://github.com/tendermint/abci/blob/master/specification.rst). +specification](https://github.com/tendermint/tendermint/blob/develop/docs/abci-spec.md). Be sure to read the specification if you're trying to build an ABCI app! For additional details on server implementation, see the [ABCI -readme](https://github.com/tendermint/abci#implementation). +readme](https://github.com/tendermint/tendermint/blob/develop/abci/README.md). Here we provide some more details around the use of ABCI by Tendermint and clarify common "gotchas". diff --git a/docs/specification/block-structure.rst b/docs/specification/block-structure.rst index 1569f6d96..7d8f3464c 100644 --- a/docs/specification/block-structure.rst +++ b/docs/specification/block-structure.rst @@ -58,8 +58,7 @@ validators `__. It represents the +that come from the ABCI application. It represents the state of the actual application, rather that the state of the blockchain itself. This means it's necessary in order to perform any business logic, such as verifying an account balance. @@ -144,8 +143,7 @@ Transaction ~~~~~~~~~~~ A transaction is any sequence of bytes. It is up to your -`ABCI `__ application to accept or -reject transactions. +ABCI application to accept or reject transactions. BlockID ~~~~~~~ diff --git a/docs/specification/validators.rst b/docs/specification/validators.rst index fb6bbbaca..085994f3d 100644 --- a/docs/specification/validators.rst +++ b/docs/specification/validators.rst @@ -26,8 +26,7 @@ There are two ways to become validator. 1. They can be pre-established in the `genesis state <./genesis.html>`__ -2. The `ABCI app responds to the EndBlock - message `__ with changes to the +2. The ABCI app responds to the EndBlock message with changes to the existing validator set. Committing a Block diff --git a/docs/using-tendermint.md b/docs/using-tendermint.md index e645b48bf..9e83683be 100644 --- a/docs/using-tendermint.md +++ b/docs/using-tendermint.md @@ -45,8 +45,7 @@ blocks are produced regularly, even if there are no transactions. See *No Empty Blocks*, below, to modify this setting. Tendermint supports in-process versions of the `counter`, `kvstore` and -`nil` apps that ship as examples in the [ABCI -repository](https://github.com/tendermint/abci). It's easy to compile +`nil` apps that ship as examples with `abci-cli`. It's easy to compile your own app in-process with Tendermint if it's written in Go. If your app is not written in Go, simply run it in another process, and use the `--proxy_app` flag to specify the address of the socket it is listening