more docs updates heavy in quarks folder
This commit is contained in:
rigel rozanski
parent
dfe2aa9ebe
commit
0e87e5bdd8
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 (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!
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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
Block a user