From 0e87e5bdd8d82447b182686704f091bbbcdd4d65 Mon Sep 17 00:00:00 2001 From: rigel rozanski Date: Fri, 21 Jul 2017 08:23:45 -0400 Subject: [PATCH] more docs updates heavy in quarks folder --- README.md | 28 ++++++----- docs/quark/README.md | 45 ++++++++++-------- docs/quark/glossary.md | 33 +++++++------ docs/quark/stdlib.md | 103 +++++++++++++++++++++++------------------ 4 files changed, 114 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 964121e210..05e3512c60 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,15 @@ -# Basecoin +# Quark -_DISCLAIMER: Basecoin is not associated with Coinbase.com, an excellent Bitcoin/Ethereum service._ +Quark is an [ABCI application](https://github.com/tendermint/abci) designed to +be used with the [Tendermint consensus engine](https://tendermint.com/) to form +a Proof-of-Stake cryptocurrency. It also provides a general purpose framework +for extending the feature-set of the cryptocurrency by implementing plugins. -Basecoin is an [ABCI application](https://github.com/tendermint/abci) designed to be used with the [Tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. -It also provides a general purpose framework for extending the feature-set of the cryptocurrency -by implementing plugins. - -Basecoin serves as a reference implementation for how we build ABCI applications in Go, -and is the framework in which we implement the [Cosmos Hub](https://cosmos.network). -**It's easy to use, and doesn't require any forking** - just implement your plugin, import the basecoin libraries, -and away you go with a full-stack blockchain and command line tool for transacting. - -WARNING: Currently uses plain-text private keys for transactions and is otherwise not production ready. +Quark serves as a reference implementation for how we build ABCI applications +in Go, and is the framework in which we implement the [Cosmos +Hub](https://cosmos.network). **It's easy to use, and doesn't require any +forking** - just implement your plugin, import the quark libraries, and away +you go with a full-stack blockchain and command line tool for transacting. ## Prerequisites @@ -28,10 +26,10 @@ See the [install guide](/docs/guide/install.md) for more details. ## Guide -1. Getting started with the [Basecoin basics](/docs/guide/basecoin-basics.md) +1. Getting started with the [Quark basics](/docs/guide/basecoin-basics.md) 1. Learning to [use the plugin system](/docs/guide/basecoin-plugins.md) -1. More features of the [Basecoin tool](/docs/guide/basecoin-tool.md) -1. Learn how to use [InterBlockchain Communication (IBC)](/docs/guide/ibc.md) +1. More features of the [Quark tool](/docs/guide/basecoin-tool.md) +1. Learn how to use [Inter-Blockchain Communication (IBC)](/docs/guide/ibc.md) 1. See [more examples](github.com/tendermint/basecoin-examples) diff --git a/docs/quark/README.md b/docs/quark/README.md index bb53f7beb8..8ce84f2557 100644 --- a/docs/quark/README.md +++ b/docs/quark/README.md @@ -1,32 +1,39 @@ # Quark -Quarks are the building blocks of atoms. And in a similar vein, this -package is a framework for building the cosmos. It gives you all the tools -you need to quickly build up powerful abci applications to run on tendermint, -while also providing maximum flexibility to customize aspects of your -application (do you require fees, how do you want to log messages, do you -enable IBC, do you even have a cryptocurrency?) +Quarks are the fundamental building blocks of atoms, through which DNA, life, +and matter arise. Similarly this package is the core framework for constructing +the atom tokens which will power [The Cosmos Network](https://cosmos.network/). -However, when power and flexibility meet, the result is also some level of +The Quark framework affords you all the tools you need to rapidly develop +robust blockchains and blockchain applications which are interoperable with The +Cosmos Hub. Quark is an abstraction of [Tendermint](https://tendermint.com/) +which provides the core consensus engine for your blockchain. Beyond consensus, +Quark provides a blockchain development 'starter-pack' of common blockchain +modules while not enforcing their use thus giving maximum flexibility for +application customization (do you require fees, how do you want to log +messages, do you enable IBC, do you even have a cryptocurrency?) + +Disclaimer, when power and flexibility meet, the result is also some level of complexity and a learning curve. Here is an introduction to the core concepts -embedded in quarks, so you can apply them properly. +embedded in Quark. ## Inspiration -The basic concept came from years of web development. After decades of web -development, a number of patterns have arisen that enabled people to build -remote servers with APIs remarkably quickly and with high stability. -I think the ABCI app interface is similar to a web api (DeliverTx is like POST -and Query is like GET and SetOption is like the admin playing with the config -file). Here are some patterns that might be useful: +The basic concept came from years of web development. A number of patterns +have arisen in that realm of software which enable people to build remote +servers with APIs remarkably quickly and with high stability. The +[ABCI](https://github.com/tendermint/abci) application interface is similar to +a web API (DeliverTx is like POST and Query is like GET and `SetOption` is like +the admin playing with the config file). Here are some patterns that might be +useful: * MVC - separate data model (storage) from business logic (controllers) * Routers - easily direct each request to the appropriate controller * Middleware - a series of wrappers that provide global functionality (like authentication) to all controllers -* Modules (gems, package, ...) - people can write a self-contained package - with a given set of functionality, which can be imported and reused in - other apps +* Modules (gems, package, ...) - developers can write a self-contained package + with a given set of functionality, which can be imported and reused in other + apps Also, the idea of different tables/schemas in databases, so you can keep the different modules safely separated and avoid any accidental (or malicious) @@ -41,6 +48,6 @@ into various applications. * [Glossary of the terms](glossary.md) * [Standard modules](stdlib.md) * Guide to building a module -* Demo of cli tool +* Demo of CLI tool * IBC in detail -* Diagrams!!! +* Diagrams... Coming Soon! diff --git a/docs/quark/glossary.md b/docs/quark/glossary.md index 39e2e4514d..25bdad94a6 100644 --- a/docs/quark/glossary.md +++ b/docs/quark/glossary.md @@ -14,15 +14,15 @@ interacts with is the current state of the chain (key-value store), and it must have a deterministic action. The tx is the main piece of one request. We currently make heavy use of [go-wire](https://github.com/tendermint/go-wire) -and [go-data](https://github.com/tendermint/tmlibs/data) to provide binary and -json encodings and decodings for `struct` or interface` objects. Here, -encoding and decoding operations are designed to operate with interfaces nested -any amount times (like an onion!). There is one public `TxMapper` in the +and [data](https://github.com/tendermint/go-wire/tree/master/data) to provide +binary and json encodings and decodings for `struct` or interface` objects. +Here, encoding and decoding operations are designed to operate with interfaces +nested any amount times (like an onion!). There is one public `TxMapper` in the basecoin root package, and all modules can register their own transaction types there. This allows us to deserialize the entire tx in one location (even with types defined in other repos), to easily embed an arbitrary tx inside another -without specifying the type, and provide an automatic json -representation to provide to users (or apps) to inspect the chain. +without specifying the type, and provide an automatic json representation to +provide to users (or apps) to inspect the chain. Note how we can wrap any other transaction, add a fee level, and not worry about the encoding in our module any more? @@ -63,8 +63,9 @@ kv-store interface. One of the main arguments for blockchain is security. So while we encourage the use of third-party modules, all developers must be vigilant against -security holes. If you use the [stack](xxx) package, it will provide two -different types of compartmentalization security. +security holes. If you use the +[stack](https://github.com/tendermint/basecoin/tree/unstable/stack) package, it +will provide two different types of compartmentalization security. The first is to limit the working kv-store space of each module. When `DeliverTx` is called for a module, it is never given the entire data store, @@ -77,13 +78,15 @@ belonging to separate module. The second is to add permissions to the transaction context. The tx context can specify that the tx has been signed by one or multiple specific -[actors](XXX). A tx will only be executed if the permission requirements have -been fulfilled. For example the sender of funds must have signed, or 2 out of 3 -multi-signature actors must have signed a joint account. To prevent the -forgery of account signatures from unintended modules each permission is -associated with the module that granted it (in this case [auth](xxx)), and if a -module tries to add a permission for another module, it will panic. There is -also protection if a module creates a brand new fake context to trick the +[actors](https://github.com/tendermint/basecoin/blob/unstable/context.go#L18). +A tx will only be executed if the permission requirements have been fulfilled. +For example the sender of funds must have signed, or 2 out of 3 multi-signature +actors must have signed a joint account. To prevent the forgery of account +signatures from unintended modules each permission is associated with the +module that granted it (in this case +[auth](https://github.com/tendermint/basecoin/tree/unstable/modules/auth)), and +if a module tries to add a permission for another module, it will panic. There +is also protection if a module creates a brand new fake context to trick the downstream modules. (FREY - need to explain the technical element of this a bit more) diff --git a/docs/quark/stdlib.md b/docs/quark/stdlib.md index aac20a64c2..97965c9414 100644 --- a/docs/quark/stdlib.md +++ b/docs/quark/stdlib.md @@ -1,96 +1,106 @@ # Standard Library -The quarks framework comes with a number of standard modules that provide a lot -of common functionality that is useful to a wide variety of applications, -and also provide good examples to use when developing your own modules. Before -starting to write code, see if the functionality is already here. +The Quark framework comes bundled with a number of standard modules that +provide common functionality useful across a wide variety of applications. +Example usage of the modules is also provided. It is recommended to investigate +if desired functionality is already provided before developing new modules. ## Basic Middleware ### Logging -`modules.base.Logger` is a middleware that records basic info on CheckTx, -DeliverTx, and SetOption, along with timing in microseconds. It can be installed -standard at the top of all middleware stacks, or replace it with your own -Middleware if you want to record more custom information with each request. +`modules.base.Logger` is a middleware that records basic info on `CheckTx`, +`DeliverTx`, and `SetOption`, along with timing in microseconds. It can be +installed standard at the top of all middleware stacks, or replaced with your +own middleware if you want to record custom information with each request. ### Recovery -To avoid accidental panics (eg. bad go-wire decoding) killing the abci app, +To avoid accidental panics (e.g. bad go-wire decoding) killing the ABCI app, wrap the stack with `stack.Recovery`, which catches all panics and returns them as errors, so they can be handled normally. ### Signatures -The first layer of the tx contains the signatures to authorize it. This is then -verfied by `modules.auth.Signatures`. All tx may have one or multiple signatures -which are then processed and verified by this middleware and then passed down -the stack. +The first layer of the tx contains the signatures to authorize it. This is +then verified by `modules.auth.Signatures`. All tx may have one or multiple +signatures which are then processed and verified by this middleware and then +passed down the stack. ### Chain The next layer of a tx (in the standard stack) binds the tx to a specific chain with an optional expiration height. This keeps the tx from being replayed on -a fork or other such chain, as well as a partially signed multisig being delayed +a fork or other such chain, as well as a partially signed multi-sig being delayed months before being committed to the chain. This functionality is provided in `modules.base.Chain` ### Nonce -To avoid replay protection within one chain, we want a nonce associated -with each account. Rather than force everything to use coins as a payment,or force each module to implement its own replay protection, each tx is wraped with a nonce and -the account it belongs to. This must be one higher than the last request or -the request is rejected. This is implemented in `modules.nonce.ReplayCheck` +To avoid replay attacks, a nonce can be associated with each actor. A separate +nonce is used for each distinct group signers required for a transaction as +well as for each separate application and chain-id. This creates replay +protection cross-IBC and cross-plugins and also allows signing parties to not +be bound to waiting for a particular transaction to be completed before being +able to sign a separate transaction. -You can also take a look at the [design discussion](https://github.com/tendermint/basecoin/issues/160) + Rather than force each module to implement its own replay protection, a tx +stack may contain a nonce wrap and the account it belongs to. The nonce must +contain a signed sequence number which is incremented one higher than the last +request or the request is rejected. This is implemented in +`modules.nonce.ReplayCheck` + +If you're interested checkout this [design +discussion](https://github.com/tendermint/basecoin/issues/160). ### Fees -An optional feature, but useful on many chains, is charging a fee for every -transaction. A simple implementation of this is provided in -`modules.fee.SimpleFeeMiddleware`. A fee currency and minimum amount are -defined in the constructor (eg. in code). If the minimum amount is 0, then -the fee is optional. If it is above 0, then every tx with insufficient fee is -rejected. This fee is deducted from the payers account before executing any -other transaction. +An optional feature, but useful on many chains, is charging transaction fees. A +simple implementation of this is provided in `modules.fee.SimpleFeeMiddleware`. +A fee currency and minimum amount are defined in the constructor (eg. in code). +If the minimum amount is 0, then the fee is optional. If it is above 0, then +every tx with insufficient fee is rejected. This fee is deducted from the +payers account before executing any other transaction. -This module depends on the `coin` module. +This module is dependent on the `coin` module. ## Other Apps ### Coin -What would a crypto-currency be without tokens? The sendtx logic from basecoin -was extracted into one module, which is now optional, meaning most of the other -functionality would also work in a system with no built-in tokens, such as -a private network that provides another access control mechanism. +What would a crypto-currency be without tokens? The `SendTx` logic from earlier +implementations of basecoin was extracted into one module, which is now +optional, meaning most of the other functionality will also work in a system +with no built-in tokens, such as a private network that provides other access +control mechanisms. `modules.coin.Handler` defines a Handler that maintains a number of accounts -along with a set of various tokens, supporting multiple denominations. The -main access is `SendTx`, which can support any type of actor (other apps as -well as public key addresses), and is a building block for any other app that +along with a set of various tokens, supporting multiple token denominations. +The main access is `SendTx`, which can support any type of actor (other apps as +well as public key addresses) and is a building block for any other app that requires some payment solution, like fees or trader. ### Roles Roles encapsulates what are typically called N-of-M multi-signatures accounts in the crypto world. However, I view this as a type of role or group, which can -be the basis for building a permision system. For example, a set of people could -be called registrars, which can authorize a new IBC chain, and need eg. 2 out -of 7 signatures to approve it. +be the basis for building a permission system. For example, a set of people +could be called registrars, which can authorize a new IBC chain, and need eg. 2 +out of 7 signatures to approve it. Currently, one can create a role with `modules.roles.Handler`, and assume one of those roles by wrapping another transaction with `AssumeRoleTx`, which is processed by `modules.roles.Middleware`. Updating the set of actors in a role is planned in the near future. -### IBC +### Inter-Blockchain Communication (IBC) -IBC, or inter-blockchain communication, is the cornerstone of cosmos, and built -into the quark framework as a basic primative. To properly understand these -concepts requires a much longer explanation, but in short, the chain works -as a light-client to another chain and maintains input and output queue to -send packets with that chain. +IBC, is the cornerstone of The Cosmos Network, and is built into the quark +framework as a basic primitive. To fully grasp these concepts requires +a much longer explanation, but in short, the chain works as a light-client to +another chain and maintains input and output queue to send packets with that +chain. This mechanism allows blockchains to prove the state of their respective +blockchains to each other ultimately invoke inter-blockchain transactions. Most functionality is implemented in `modules.ibc.Handler`. Registering a chain is a seed of trust that requires verification of the proper seed (or genesis @@ -100,7 +110,7 @@ as the new header can be completely verified by the existing knowledge of the chain. Also, modules can initiate an outgoing IBC message to another chain by calling `CreatePacketTx` over IPC (inter-plugin communication) with a tx that belongs to their module. (This must be explicitly authorized by the -same module, so only the eg. coin module can authorize a sendtx to another +same module, so only the eg. coin module can authorize a `SendTx` to another chain). `PostPacketTx` can post a tx that was created on another chain along with the @@ -127,6 +137,7 @@ governance. ### Trader -Escrow, OTC option, Order book. Based on [basecoin-examples](https://github.com/tendermint/basecoin-examples/tree/develop/trader). This may be more appropriate -for an external repo. +Escrow, OTC option, Order book. Based on +[basecoin-examples](https://github.com/tendermint/basecoin-examples/tree/develop/trader). +This may be more appropriate for an external repo.