Start quark docs

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)

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 `<module name> + 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...