diff --git a/docs/quark/README.md b/docs/quark/README.md new file mode 100644 index 0000000000..94412b1ad9 --- /dev/null +++ b/docs/quark/README.md @@ -0,0 +1,41 @@ +# 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?) + +However, 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. + +## 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: + +* 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 + +Also, the idea of different tables/schemas in databases, so you can keep the +different modules safely separated and avoid any accidental (or malicious) +overwriting of data. + +Not all of these can be pulled one-to-one in the blockchain world, but they do +provide inspiration to provide orthogonal pieces that can easily be combined +into various applications. + +## Further reading + +* [Glossary of the terms](glossary.md) diff --git a/docs/quark/glossary.md b/docs/quark/glossary.md new file mode 100644 index 0000000000..91162b4033 --- /dev/null +++ b/docs/quark/glossary.md @@ -0,0 +1,83 @@ +# Glossary + +This defines many of the terms that are used in the other documents. If there +is every a concept that seems unclear, check here. + +## Transaction + +A transaction is a packet of binary data that contains all information to +validate and perform an action on the blockchain. The only other data that +it interacts with is the current state of the chain (kv store), and it must +have a deterministic action. The transaction is the main piece of one request. + +We currently make heavy use of go-wire and go-data to provide automatic binary +and json encodings (and decodings) for objects, even when they embed many +interfaces inside. 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 specific type, and provide an automatic json representation to provide to +users (or apps) to inspect the chain. + +## Context + +As the request passes through the system, it can pick up information, that must +be carried along with it. Like the authorized it has received from another +middleware, or the block height it runs at. This is all deterministic +information from the context in which the request runs (based on the tx and +the block it was included in) and can be used to validate the tx. + +## Data Store + +To be able to provide proofs to tendermint, we keep all data in one key-value +store, indexed with a merkle tree. This allows us to easily provide a root +hash and proofs for queries without requiring complex logic inside each +module. Standarizing this also allows powerful light-client tooling as it knows +how to verify all data in the store. + +The downside is there is one quite simple interface that the application has +to `Get` and `Set` data. There is not even a range query. Although there are +some data structures like queues and range queries that are also in the `state` +package to provide higher-level functionality in a standard format. + +## Isolation + +One of the main arguments for blockchain is security. So while we encourage +the use of third-party modules, we must be vigilant against security holes. +If you use the `stack` package, it will provide two different types of +sandboxing for you. + +The first step, is that when `DeliverTx` is called on a module, it is never +given the entire data store, but rather only its own prefixed section. This +is achieved by prefixing all keys transparently with ` + 0x0`, +using the null byte as a separator. Since module name must be a string, no +clever naming scheme can lead to a collision. Inside the module, we can write +anywhere we want, without worry that we have to touch some data that is not ours. + +The second step involves the permissions in the context. The context can say +that this tx was signed by eg. Rigel. But if any module can add that permission, +it would be too easy to forge accounts. Thus, each permission is associated +with the module that granted it (in this case `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. + +This means that modules can confidently write to their local section of the +database and trust the permissions associated with the context, without concern +of interferance from other modules. (Okay, if you see a bunch of C-code in +the module traversing through all the memory space of the application, then +get worried....) + +## Handler + +## Middleware + +## Modules + +## Dispathcer + +## IPC (Inter-Plugin Communication) + +## IBC (Inter-Blockchain Communication) + +Wow, this is a big topic. Also a WIP. Add more here...