From a77213e6c5ec4326cf1e1564fbf3e60a56239663 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Wed, 3 Jan 2018 00:48:00 +0000 Subject: [PATCH] update readme, closes #134 --- README.md | 95 +++++++++++++++++++++++++++++++++++----- cmd/abci-cli/abci-cli.go | 6 ++- 2 files changed, 87 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2d8dbee9..a785ce76 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,15 @@ Previously, the ABCI was referred to as TMSP. The community has provided a number of addtional implementations, see the [Tendermint Ecosystem](https://tendermint.com/ecosystem) +## Install + +``` +go get github.com/tendermint/abci +cd $GOPATH/src/github.com/tendermint/abci +make get_vendor_deps +make install +``` + ## Implementation We provide three implementations of the ABCI in Go: @@ -24,19 +33,21 @@ We provide three implementations of the ABCI in Go: - GRPC Note the GRPC version is maintained primarily to simplify onboarding and prototyping and is not receiving the same -attention to security and performance as the others. +attention to security and performance as the others ### In Process The simplest implementation just uses function calls within Go. This means ABCI applications written in Golang can be compiled with TendermintCore and run as a single binary. +See the [examples](#examples) below for more information. + ### Socket (TSP) ABCI is best implemented as a streaming protocol. The socket implementation provides for asynchronous, ordered message passing over unix or tcp. Messages are serialized using Protobuf3 and length-prefixed. -Protobuf3 doesn't have an official length-prefix standard, so we use our own. The first byte represents the length of the big-endian encoded length. +Protobuf3 doesn't have an official length-prefix standard, so we use our own. The first byte represents the length of the big-endian encoded length. For example, if the Protobuf3 encoded ABCI message is `0xDEADBEEF` (4 bytes), the length-prefixed message is `0x0104DEADBEEF`. If the Protobuf3 encoded ABCI message is 65535 bytes long, the length-prefixed message would be like `0x02FFFF...`. @@ -55,22 +66,82 @@ For instance, `abci-cli test` will run a test sequence against a listening serve It can also be used to run some example applications. See [the documentation](http://tendermint.readthedocs.io/en/master/) for more details. -### Example Apps +### Examples -Multiple example apps are included: -- the `abci-cli counter` application, which illustrates nonce checking in txs -- the `abci-cli dummy` application, which illustrates a simple key-value Merkle tree -- the `abci-cli dummy --persistent` application, which augments the dummy with persistence and validator set changes +Check out the variety of example applications in the [example directory](example/). +It also contains the code refered to by the `counter` and `dummy` apps; these apps come +built into the `abci-cli` binary. -### Install +#### Counter +The `abci-cli counter` application illustrates nonce checking in transactions. It's code looks like: + +```golang +func cmdCounter(cmd *cobra.Command, args []string) error { + + app := counter.NewCounterApplication(flagSerial) + + logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) + + // Start the listener + srv, err := server.NewServer(flagAddrC, flagAbci, app) + if err != nil { + return err + } + srv.SetLogger(logger.With("module", "abci-server")) + if err := srv.Start(); err != nil { + return err + } + + // Wait forever + cmn.TrapSignal(func() { + // Cleanup + srv.Stop() + }) + return nil +} ``` -go get github.com/tendermint/abci -cd $GOPATH/src/github.com/tendermint/abci -make get_vendor_deps -make install + +and can be found in [this file](cmd/abci-cli/abci-cli.go). + +#### Dummy + +The `abci-cli dummy` application, which illustrates a simple key-value Merkle tree + +```golang +func cmdDummy(cmd *cobra.Command, args []string) error { + logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) + + // Create the application - in memory or persisted to disk + var app types.Application + if flagPersist == "" { + app = dummy.NewDummyApplication() + } else { + app = dummy.NewPersistentDummyApplication(flagPersist) + app.(*dummy.PersistentDummyApplication).SetLogger(logger.With("module", "dummy")) + } + + // Start the listener + srv, err := server.NewServer(flagAddrD, flagAbci, app) + if err != nil { + return err + } + srv.SetLogger(logger.With("module", "abci-server")) + if err := srv.Start(); err != nil { + return err + } + + // Wait forever + cmn.TrapSignal(func() { + // Cleanup + srv.Stop() + }) + return nil +} ``` +and can be found in [this file](cmd/abci-cli/abci-cli.go). + ## Specification See the [spec file](specification.rst) for more information. diff --git a/cmd/abci-cli/abci-cli.go b/cmd/abci-cli/abci-cli.go index 909aa5de..d3f5950f 100644 --- a/cmd/abci-cli/abci-cli.go +++ b/cmd/abci-cli/abci-cli.go @@ -327,8 +327,10 @@ func cmdTest(cmd *cobra.Command, args []string) error { func() error { return servertest.DeliverTx(client, []byte{0x00, 0x02}, code.CodeTypeOK, nil) }, func() error { return servertest.DeliverTx(client, []byte{0x00, 0x03}, code.CodeTypeOK, nil) }, func() error { return servertest.DeliverTx(client, []byte{0x00, 0x00, 0x04}, code.CodeTypeOK, nil) }, - func() error { return servertest.DeliverTx(client, []byte{0x00, 0x00, 0x06}, code.CodeTypeBadNonce, nil) }, - func() error { return servertest.Commit(client, []byte{0, 0, 0, 0, 0, 0, 0, 5})}, + func() error { + return servertest.DeliverTx(client, []byte{0x00, 0x00, 0x06}, code.CodeTypeBadNonce, nil) + }, + func() error { return servertest.Commit(client, []byte{0, 0, 0, 0, 0, 0, 0, 5}) }, }) }