diff --git a/docs/graphics/README.md b/docs/graphics/README.md new file mode 100644 index 0000000000..aefc54550e --- /dev/null +++ b/docs/graphics/README.md @@ -0,0 +1,13 @@ +# Usage + +Graphics can be imported and edited with the draw.io tool: +https://www.draw.io/?mode=github + +Images can be exported from the draw.io directly to this github repo. +All diagrams are saved to the single .xml file. To export each infographic +select the relevant elements and then export to .png using the following settings: + +- Selection Only +- Crop +- Zoom: 200% +- Borderwidth: 20 diff --git a/docs/graphics/datastore.png b/docs/graphics/datastore.png new file mode 100644 index 0000000000..c659c87631 Binary files /dev/null and b/docs/graphics/datastore.png differ diff --git a/docs/graphics/dispatcher.png b/docs/graphics/dispatcher.png new file mode 100644 index 0000000000..424a87b94a Binary files /dev/null and b/docs/graphics/dispatcher.png differ diff --git a/docs/graphics/infographic.xml b/docs/graphics/infographic.xml new file mode 100644 index 0000000000..a2165cd16e --- /dev/null +++ b/docs/graphics/infographic.xml @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/docs/graphics/middleware.png b/docs/graphics/middleware.png new file mode 100644 index 0000000000..eea0692f01 Binary files /dev/null and b/docs/graphics/middleware.png differ diff --git a/docs/graphics/overview-framework.png b/docs/graphics/overview-framework.png new file mode 100644 index 0000000000..c9d507dce5 Binary files /dev/null and b/docs/graphics/overview-framework.png differ diff --git a/docs/graphics/overview-security.png b/docs/graphics/overview-security.png new file mode 100644 index 0000000000..c507a9cee5 Binary files /dev/null and b/docs/graphics/overview-security.png differ diff --git a/docs/graphics/permission.png b/docs/graphics/permission.png new file mode 100644 index 0000000000..1dd0f2a2b8 Binary files /dev/null and b/docs/graphics/permission.png differ diff --git a/docs/graphics/tx.png b/docs/graphics/tx.png new file mode 100644 index 0000000000..7318c43a10 Binary files /dev/null and b/docs/graphics/tx.png differ diff --git a/docs/quark/README.md b/docs/quark/README.md index ea2ce0bfee..bfdd7cc3d1 100644 --- a/docs/quark/README.md +++ b/docs/quark/README.md @@ -45,6 +45,7 @@ into various applications. ## Further reading +* [Quark overview](overview.md) * [Glossary of the terms](glossary.md) * [Standard modules](stdlib.md) * Guide to building a module diff --git a/docs/quark/glossary.md b/docs/quark/glossary.md index 16a0b8a098..5d014c3777 100644 --- a/docs/quark/glossary.md +++ b/docs/quark/glossary.md @@ -156,7 +156,7 @@ self-sufficient. Common elements of a module are: To enable a module, you must add the appropriate middleware (if any) to the stack in `main.go` for the client application (Quark default: `basecli/main.go`), as well as adding the handler (if any) to the dispatcher -(Quark default: `app/app.go). Once the stack is compiled into a `Handler`, +(Quark default: `app/app.go`). Once the stack is compiled into a `Handler`, then each tx is handled by the appropriate module. ## Dispatcher diff --git a/docs/quark/overview.md b/docs/quark/overview.md new file mode 100644 index 0000000000..46a1c22960 --- /dev/null +++ b/docs/quark/overview.md @@ -0,0 +1,105 @@ +# Quark Overview + +The quark middleware design optimizes flexibility and security. The framework +is designed around a modular execution stack which allows applications to mix +and match modular elements as desired. Along side, all modules are permissioned +and sandboxed to reduce + +For more explanation please see the [standard +library](https://github.com/tendermint/basecoin/blob/infographic/docs/quark/stdlib.md) +and +[glossary](https://github.com/tendermint/basecoin/blob/infographic/docs/quark/glossary.md) +documentation. + +For a more interconnected schematics see these +[framework](https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/overview-framework.png) +and +[security](https://github.com/tendermint/basecoin/blob/infographic/docs/graphics/overview-security.png) +overviews. + +## Framework Overview + +### Transaction (tx) + +Each tx passes through the middleware stack which can be defined uniquely by +each application. From the multiple layers of tx, each middleware may strip +off one level, like an onion. As so, the transaction must be constructed to +mirror the execution stack, and each middleware should allow embedding an +arbitrary tx for the next layer in the stack. + + + +### Execution Stack + +Middleware components allow for code reusability and integrability. A standard +set of middleware are provided and can be mix-and-matched with custom +middleware. Some of the [standard +library](https://github.com/tendermint/basecoin/blob/infographic/docs/quark/stdlib.md) +middlewares provided in this package include: + - Logging + - Recovery + - Signatures + - Chain + - Nonce + - Fees + - Roles + - Inter-Blockchain-Communication (IBC) + + As a part of stack execution the state space provided to each middleware is +isolated (see [Data Store](overview.md#data-store)). When executing the stack, +state-recovery points (checkpoints) can be assigned for stack execution of +`CheckTx` or `DeliverTx`. This means, that all state changes will be reverted +to the checkpoint state on failure when either being run as a part of `CheckTx` +or `DeliverTx`. Example usage of the checkpoints is when we may want to deduct +a fee even if the end business logic fails, under this situation we would add +the DeliverTx Checkpoint to after the fee middleware but before the business +logic. This diagram displays a typical process flow through an execution stack. + + + +### Dispatcher + +The dispatcher handler aims to allow for reusable business logic. As a +transaction is passed to the end handler, the dispatcher routes the logic to +the correct module. To use the dispatcher tool all transaction types must +first be registered with the dispatcher. Once registered the middleware stack +or any other handler can call the dispatcher to execute a transaction. +Similarity to the execution stack, when executing a transaction the dispatcher +isolates the state space available to the designated module (see [Data +Store](overview.md#data-store)). + + + +## Security Overview + +### Permission + +Each application is run in a sandbox to isolate security risks. When +interfacing between applications, if a one of those application is compromised +the entire network should still be secure. This is achieved through actor +permissioning whereby each chain, account, or application can provided a +designated permission for the transaction context to perform a specific action. + +Context is passed through the middleware and dispatcher, allowing one to add +permissions on this app-space, and check current permissions. + + + +### Data Store + +The entire merkle tree can access all data. When we call a module (or +middleware), we give them access to a subtree corresponding to their app. This +is achieved through the use of unique prefix assigned to each module. From the +module's perspective it is no different, the module need-not have regard for +the prefix as it is assigned outside of the modules scope. For example, if a +module named `foo` wanted to write to the store it could save records under the +key `bar` however the dispatcher would register that record in the persistent +state under `foo/bar`. Next time the `foo` app was called that record would be +accessible to it under the assigned key `bar`. This effectively makes app +prefixing invisible to each module while preventing each module from affecting +each other module. Under this model no two registered modules are permitted to +have the same namespace. + + + +