84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
|
# 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...
|