Merge pull request #180 from tendermint/feature/rige-docs
Feature/rige docs
This commit is contained in:
commit
fb4266249e
28
README.md
28
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)
|
||||
|
||||
|
||||
|
|
|
@ -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. For example, 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!
|
||||
|
|
|
@ -1,31 +1,33 @@
|
|||
# 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. This is mainly to provide
|
||||
a background and general understanding of the different words and concepts
|
||||
that are used. Other documents will explain in more detail how to combine
|
||||
these concepts to build a particular application.
|
||||
This glossary defines many terms used throughout documentation of Quark. If
|
||||
there is every a concept that seems unclear, check here. This is mainly to
|
||||
provide a background and general understanding of the different words and
|
||||
concepts that are used. Other documents will explain in more detail how to
|
||||
combine these concepts to build a particular application.
|
||||
|
||||
## Transaction
|
||||
## Transaction (tx)
|
||||
|
||||
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.
|
||||
validate and perform an action on the blockchain. The only other data that it
|
||||
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 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.
|
||||
We currently make heavy use of [go-wire](https://github.com/tendermint/go-wire)
|
||||
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.
|
||||
|
||||
Note how we can wrap any other transaction, add a fee level, and not worry
|
||||
about the encoding in our module any more?
|
||||
|
||||
```Go
|
||||
```golang
|
||||
type Fee struct {
|
||||
Fee coin.Coin `json:"fee"`
|
||||
Payer basecoin.Actor `json:"payer"` // the address who pays the fee
|
||||
|
@ -33,54 +35,68 @@ type Fee struct {
|
|||
}
|
||||
```
|
||||
|
||||
## Context
|
||||
## Context (ctx)
|
||||
|
||||
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.
|
||||
As a request passes through the system, it may pick up information such as the
|
||||
authorization it has received from another middleware, or the block height the
|
||||
request runs at. In order to carry this information between modules it is
|
||||
saved to the context. further, it all information must be deterministic 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.
|
||||
To be able to provide proofs to Tendermint, we keep all data in one key-value
|
||||
(kv) store which is indexed with a merkle tree. This allows for the easy
|
||||
generation of a root hash and proofs for queries without requiring complex
|
||||
logic inside each module. Standardization of this process also allows powerful
|
||||
light-client tooling as any store data may be verified on the fly.
|
||||
|
||||
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.
|
||||
The largest limitation of the current implemenation of the kv-store is that
|
||||
interface that the application must use can only `Get` and `Set` single data
|
||||
points. This said, there are some data structures like queues and range
|
||||
queries that are available in `state` package. These provide higher-level
|
||||
functionality in a standard format, but have not yet been integrated into the
|
||||
kv-store interface.
|
||||
|
||||
## 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 use of third-party modules, all developers must be vigilant against
|
||||
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 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 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,
|
||||
but rather only its own prefixed subset of the store. This is achieved by
|
||||
prefixing all keys transparently with `<module name> + 0x0`, using the null
|
||||
byte as a separator. Since the module name must be a string, no malicious
|
||||
naming scheme can ever lead to a collision. Inside a module, we can
|
||||
write using any key value we desire without the possibility that we
|
||||
have modified data belonging to separate module.
|
||||
|
||||
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.
|
||||
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](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. Each context enforces
|
||||
the rules on how to make child contexts, and the stack middleware builder
|
||||
enforces that the context passed from one level to the next is a valid
|
||||
child of the original one.
|
||||
|
||||
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....)
|
||||
These security measures ensure that modules can confidently write to their
|
||||
local section of the database and trust the permissions associated with the
|
||||
context, without concern of interference 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
|
||||
|
||||
|
@ -89,19 +105,19 @@ into an internal format that is more convenient, but unable to travel over the
|
|||
wire. The basic interface for any code that modifies state is the `Handler`
|
||||
interface, which provides four methods:
|
||||
|
||||
```Go
|
||||
```golang
|
||||
Name() string
|
||||
CheckTx(ctx Context, store state.KVStore, tx Tx) (Result, error)
|
||||
DeliverTx(ctx Context, store state.KVStore, tx Tx) (Result, error)
|
||||
SetOption(l log.Logger, store state.KVStore, module, key, value string) (string, error)
|
||||
```
|
||||
|
||||
Note the `Context`, `Store`, and `Tx` as principal carriers of information. And
|
||||
that Result is always success, and we have a second error return for errors
|
||||
(which is much more standard go that `res.IsErr()`)
|
||||
Note the `Context`, `KVStore`, and `Tx` as principal carriers of information.
|
||||
And that Result is always success, and we have a second error return
|
||||
for errors (which is much more standard golang that `res.IsErr()`)
|
||||
|
||||
The `Handler` interface is designed to be the basis for all modules that
|
||||
execute transaction, and this can provide a large degree of code
|
||||
execute transactions, and this can provide a large degree of code
|
||||
interoperability, much like `http.Handler` does in golang web development.
|
||||
|
||||
## Middleware
|
||||
|
@ -110,16 +126,16 @@ Middleware is a series of processing steps that any request must travel through
|
|||
before (and after) executing the registered `Handler`. Some examples are a
|
||||
logger (that records the time before executing the tx, then outputs info -
|
||||
including duration - after the execution), of a signature checker (which
|
||||
unwraps the tx by one layer, verifies signatutes, and adds the permissions to
|
||||
unwraps the tx by one layer, verifies signatures, and adds the permissions to
|
||||
the Context before passing the request along).
|
||||
|
||||
In keeping with the standardazation of `http.Handler` and inspired by the
|
||||
In keeping with the standardization of `http.Handler` and inspired by the
|
||||
super minimal [negroni](https://github.com/urfave/negroni/blob/master/README.md)
|
||||
package, we just provide one more `Middleware` interface, which has an extra
|
||||
`next` parameter, and a `Stack` that can wire all the levels together (which
|
||||
also gives us a place to perform isolation of each step).
|
||||
|
||||
```Go
|
||||
```golang
|
||||
Name() string
|
||||
CheckTx(ctx Context, store state.KVStore, tx Tx, next Checker) (Result, error)
|
||||
DeliverTx(ctx Context, store state.KVStore, tx Tx, next Deliver) (Result, error)
|
||||
|
@ -128,19 +144,20 @@ also gives us a place to perform isolation of each step).
|
|||
|
||||
## Modules
|
||||
|
||||
A module is a set of functionality that is more or less self-sufficient. It
|
||||
usually contains the following pieces:
|
||||
A module is a set of functionality which should be typically designed as
|
||||
self-sufficient. Common elements of a module are:
|
||||
|
||||
* transaction types (either end transactions, or transaction wrappers)
|
||||
* custom error codes
|
||||
* data models (to persist in the kv store)
|
||||
* data models (to persist in the kv-store)
|
||||
* handler (to handle any end transactions)
|
||||
* middleware (to handler any wrapper transactions)
|
||||
|
||||
To enable a module, you must add the appropriate middleware (if any) to the
|
||||
stack in main.go, as well as adding the handler (if any) to the dispatcher.
|
||||
One the stack is compiled into a `Handler`, then all tx are handled by the
|
||||
proper module.
|
||||
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`,
|
||||
then each tx is handled by the appropriate module.
|
||||
|
||||
## Dispatcher
|
||||
|
||||
|
@ -163,47 +180,49 @@ This all seems a bit of magic, but really just making use of the other magic
|
|||
thing you need to remember is to use the following pattern, then all the tx
|
||||
will be properly routed:
|
||||
|
||||
```Go
|
||||
```golang
|
||||
const (
|
||||
NameCoin = "coin"
|
||||
TypeSend = NameCoin + "/send"
|
||||
)
|
||||
```
|
||||
|
||||
## IPC (Inter-Plugin Communication)
|
||||
## Inter-Plugin Communication (IPC)
|
||||
|
||||
But wait, there's more... since we have isolated all the modules from each
|
||||
other, we need to allow some way for them to interact in a controlled fashion.
|
||||
Some examples are the `fee` middleware, which wants to deduct coins from
|
||||
the calling account (in the `coin` module), or a vote that requires a payment.
|
||||
One example is the `fee` middleware, which wants to deduct coins from the
|
||||
calling account and can accomplished most easilty with the `coin` module.
|
||||
|
||||
If we want to make a call from the middleware, this is relatively simple.
|
||||
The middleware already has a handle to the `next` Handler, which will
|
||||
execute the rest of the stack. It can simple create a new SendTx and pass
|
||||
it down the stack. If it returns success, then do the rest of the processing
|
||||
(and send the original tx down the stack), otherwise abort.
|
||||
If we want to make a call from the middleware, this is relatively simple. The
|
||||
middleware already has a handle to the `next` Handler, which will execute the
|
||||
rest of the stack. It can simple create a new SendTx and pass it down the
|
||||
stack. If it returns success, then do the rest of the processing (and send the
|
||||
original tx down the stack), otherwise abort.
|
||||
|
||||
However, if one `Handler` inside the `Dispatcher` wants to do this, it
|
||||
becomes more complex. The solution is that the `Dispatcher` accepts not
|
||||
a `Handler`, but a `Dispatchable`, which looks like a middleware, except
|
||||
that the `next` argument is a callback to the dispatcher to execute a
|
||||
sub-transaction. If a module doesn't want to use this functionality,
|
||||
it can just implement `Handler` and call `stack.WrapHandler(h)` to convert
|
||||
it to a `Dispatchable` that never uses the callback.
|
||||
However, if one `Handler` inside the `Dispatcher` wants to do this, it becomes
|
||||
more complex. The solution is that the `Dispatcher` accepts not a `Handler`,
|
||||
but a `Dispatchable`, which looks like a middleware, except that the `next`
|
||||
argument is a callback to the dispatcher to execute a sub-transaction. If a
|
||||
module doesn't want to use this functionality, it can just implement `Handler`
|
||||
and call `stack.WrapHandler(h)` to convert it to a `Dispatchable` that never
|
||||
uses the callback.
|
||||
|
||||
One example of this is the counter app, which can optionally accept a payment.
|
||||
If the tx contains a payment, it must create a SendTx and pass this to the
|
||||
dispatcher to deduct the amount from the proper account. Take a look at
|
||||
[counter plugin](https://github.com/tendermint/basecoin/blob/unstable/docs/guide/counter/plugins/counter/counter.go) for a better idea.
|
||||
[counter
|
||||
plugin](https://github.com/tendermint/basecoin/blob/unstable/docs/guide/counter/plugins/counter/counter.go)
|
||||
for a better idea.
|
||||
|
||||
## Permissions
|
||||
|
||||
This system requires a more complex permissioning system to allow the modules
|
||||
to have limited access to each other. Also to allow more types of permissions
|
||||
than simple public key signatures. So, rather than just use an address to
|
||||
identify who is performing an action, we can use a more complex structure:
|
||||
IPC requires a more complex permissioning system to allow the modules to have
|
||||
limited access to each other. Also to allow more types of permissions than
|
||||
simple public key signatures. So, rather than just use an address to identify
|
||||
who is performing an action, we can use a more complex structure:
|
||||
|
||||
```Go
|
||||
```golang
|
||||
type Actor struct {
|
||||
ChainID string `json:"chain"` // this is empty unless it comes from a different chain
|
||||
App string `json:"app"` // the app that the actor belongs to
|
||||
|
@ -211,32 +230,70 @@ type Actor struct {
|
|||
}
|
||||
```
|
||||
|
||||
Here, the `Actor` abstracts any address that can authorize actions, hold funds,
|
||||
or initiate any sort of transaction. It doesn't just have to be a pubkey on
|
||||
this chain, it could stem from another app (such as multi-sig account), or even
|
||||
another chain (via IBC)
|
||||
|
||||
`ChainID` is to be used for IBC, which is discussed below, but right now focus
|
||||
on `App` and `Address`. For a signature, the App is `auth`, and any modules can
|
||||
check to see if a specific public key address signed like this
|
||||
`ctx.HasPermission(auth.SigPerm(addr))`. However, we can also authorize a
|
||||
tx with `roles`, which handles multi-sig accounts, it checks if there were
|
||||
enough signatures by checking as above, then it can add the role permission like
|
||||
`ctx = ctx.WithPermissions(NewPerm(assume.Role))`
|
||||
on `App` and `Address`. For a signature, the App is `auth`, and any modules
|
||||
can check to see if a specific public key address signed like this
|
||||
`ctx.HasPermission(auth.SigPerm(addr))`. However, we can also authorize a tx
|
||||
with `roles`, which handles multi-sig accounts, it checks if there were enough
|
||||
signatures by checking as above, then it can add the role permission like `ctx
|
||||
= ctx.WithPermissions(NewPerm(assume.Role))`
|
||||
|
||||
In addition to permissioning, the Actors are addresses just like public key
|
||||
addresses. So one can create a mulit-sig role, then send coin there, which
|
||||
can only be moved upon meeting the authorization requirements from that module.
|
||||
`coin` doesn't even know the existence of `roles` and one could build any
|
||||
other sort of module to provide permissions (like bind the outcome of an
|
||||
election to move coins or to modify the accounts on a role).
|
||||
addresses. So one can create a mulit-sig role, then send coin there, which can
|
||||
only be moved upon meeting the authorization requirements from that module.
|
||||
`coin` doesn't even know the existence of `roles` and one could build any other
|
||||
sort of module to provide permissions (like bind the outcome of an election to
|
||||
move coins or to modify the accounts on a role).
|
||||
|
||||
One idea (not implemented) is to provide scopes on the permissions. Right now,
|
||||
if I sign a tx to one module, it can pass it on to any other module over IPC
|
||||
with the same permissions. It could move coins, vote in an election, or
|
||||
anything else. Ideally, when signing, one could also specify the scope(s) that
|
||||
this signature authorizes. The [oauth protocol](https://api.slack.com/docs/oauth-scopes)
|
||||
also has to deal with a similar problem, and maybe could provide some inspiration.
|
||||
this signature authorizes. The [oauth
|
||||
protocol](https://api.slack.com/docs/oauth-scopes) also has to deal with a
|
||||
similar problem, and maybe could provide some inspiration.
|
||||
|
||||
|
||||
## Replay Protection
|
||||
|
||||
Is implemented as middleware. Rigel can add more info here. Or look
|
||||
at [the github issue](https://github.com/tendermint/basecoin/issues/160)
|
||||
In order to prevent [replay
|
||||
attacks](https://en.wikipedia.org/wiki/Replay_attack) a multi account nonce system
|
||||
has been constructed as a module, which can be found in
|
||||
`modules/nonce`. By adding the nonce module to the stack, each
|
||||
transaction is verified for authenticity against replay attacks. This is
|
||||
achieved by requiring that a new signed copy of the sequence number which must
|
||||
be exactly 1 greater than the sequence number of the previous transaction. A
|
||||
distinct sequence number is assigned per chain-id, application, and group of
|
||||
signers. Each sequence number is tracked as a nonce-store entry where the key
|
||||
is the marshaled list of actors after having been sorted by chain, app, and
|
||||
address.
|
||||
|
||||
```golang
|
||||
// Tx - Nonce transaction structure, contains list of signers and current sequence number
|
||||
type Tx struct {
|
||||
Sequence uint32 `json:"sequence"`
|
||||
Signers []basecoin.Actor `json:"signers"`
|
||||
Tx basecoin.Tx `json:"tx"`
|
||||
}
|
||||
```
|
||||
|
||||
By distinguishing sequence numbers across groups of Signers, multi-signature
|
||||
Actors need not lock up use of their Address while waiting for all the members
|
||||
of a multi-sig transaction to occur. Instead only the multi-sig account will
|
||||
be locked, while other accounts belonging to that signer can be used and signed
|
||||
with other sequence numbers.
|
||||
|
||||
By abstracting out the nonce module in the stack, entire series of transactions
|
||||
can occur without needing to verify the nonce for each member of the series. An
|
||||
common example is a stack which will send coins and charge a fee. Within Quark
|
||||
this can be achieved using separate modules in a stack, one to send the coins
|
||||
and the other to charge the fee, however both modules do not need to check the
|
||||
nonce. This can occur as a separate module earlier in the stack.
|
||||
|
||||
## IBC (Inter-Blockchain Communication)
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in New Issue