diff --git a/docs/basics.md b/docs/basics.md index 4599e2bd7f..ec5dd82e71 100644 --- a/docs/basics.md +++ b/docs/basics.md @@ -11,6 +11,7 @@ users to issue new coins. Here we explain the concepts of the SDK using Basecoin as an example. + ## Transactions and Messages The SDK distinguishes between transactions and messages. @@ -19,11 +20,12 @@ A message is the core input data to the application. A transaction is a message wrapped with authentication data, like cryptographic signatures. + ### Messages Users can create messages containing arbitrary information by implementing the `Msg` interface: -``` +```golang type Msg interface { // Return the message type. @@ -66,7 +68,7 @@ but this is mostly for convenience and not type-safe. For instance, the `Basecoin` message types are defined in `x/bank/tx.go`: -``` +```golang type SendMsg struct { Inputs []Input `json:"inputs"` Outputs []Output `json:"outputs"` @@ -80,7 +82,7 @@ type IssueMsg struct { Each specifies the addresses that must sign the message: -``` +```golang func (msg SendMsg) GetSigners() []crypto.Address { addrs := make([]crypto.Address, len(msg.Inputs)) for i, in := range msg.Inputs { @@ -99,7 +101,7 @@ func (msg IssueMsg) GetSigners() []crypto.Address { A transaction is a message with additional information for authentication: -``` +```golang type Tx interface { Msg @@ -125,7 +127,7 @@ type Tx interface { The `tx.GetSignatures()` method returns a list of signatures, which must match the list of addresses returned by `tx.Msg.GetSigners()`. The signatures come in a standard form: -``` +```golang type StdSignature struct { crypto.PubKey // optional crypto.Signature @@ -147,13 +149,14 @@ Transactions can also specify the address responsible for paying the transaction The standard way to create a transaction from a message is to use the `StdTx`: -``` +```golang type StdTx struct { Msg Signatures []StdSignature } ``` + ### Encoding and Decoding Transactions Messages and transactions are designed to be generic enough for developers to specify their own encoding schemes. @@ -163,7 +166,7 @@ for instance Ethereum. When initializing an application, a developer must specify a `TxDecoder` function which determines how an arbitrary byte array should be unmarshalled into a `Tx`: -``` +```golang type TxDecoder func(txBytes []byte) (Tx, error) ``` @@ -173,7 +176,7 @@ to be registered ahead of type. Registration happens on a `Codec` object, so as For instance, in `Basecoin`, we wish to register the `SendMsg` and `IssueMsg` types: -``` +```golang cdc.RegisterInterface((*sdk.Msg)(nil), nil) cdc.RegisterConcrete(bank.SendMsg{}, "cosmos-sdk/SendMsg", nil) cdc.RegisterConcrete(bank.IssueMsg{}, "cosmos-sdk/IssueMsg", nil) @@ -183,6 +186,7 @@ Note how each concrete type is given a name - these name determines the types un A registered type will always use the same prefix-bytes, regardless of what interface it is satisfying. For more details, see the [go-wire documentation](). + ## Context The SDK uses a `Context` to propogate common information across functions. The `Context` is modelled @@ -195,11 +199,12 @@ may be necessary for processing a transaction. Many methods on SDK objects receive a context as the first argument. + ## Handlers Transaction processing in the SDK is defined through `Handler` functions: -``` +```golang type Handler func(ctx Context, tx Tx) Result ``` @@ -211,9 +216,20 @@ some subset of the store. Access to substores is managed using capabilities - when a handler is initialized, it is passed capability keys that determine which parts of the store it can access. - TODO: example + ## Store -## App +- IAVLStore: Fast balanced dynamic Merkle store. + - supports iteration. +- MultiStore: multiple Merkle tree backends in a single store + - allows using Ethereum Patricia Trie and Tendermint IAVL in same app +- Provide caching for intermediate state during execution of blocks and transactions (including for iteration) +- Historical state pruning and snapshotting. +- Query proofs (existence, absence, range, etc.) on current and retained historical state. + + +## BaseApp + +TODO diff --git a/docs/design.md b/docs/design.md index e67324fc8c..55d0c8f943 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,62 +1,31 @@ ## Design philosphy The design of the Cosmos SDK is based on the principles of "cababilities systems". - TODO If you see this on the sdk2 branch, it's because I'm still expanding this high-level section. Sections: * Introduction - - Note to skip to Basecoin example to dive into code. + - Note to skip to Basecoin example to dive into code. * Capabilities systems - - http://www.erights.org/elib/capability/ode/ode.pdf + - Need for module isolation + - Capability is implied permission + - http://www.erights.org/elib/capability/ode/ode.pdf * Tx & Msg * MultiStore + - MultiStore is like a filesystem + - Mounting an IAVLStore * Context & Handler * AnteHandler - - Fees - - Authentication + - Handling Fee payment + - Handling Authentication * Accounts and x/auth -* AccountStore + - sdk.Account + - auth.BaseAccount + - auth.AccountMapper * Wire codec - - vs encoding/json - - vs protobuf + - vs encoding/json + - vs protobuf * Dummy example * Basecoin example * Conclusion - -## ###################################### -## TODO bring the below up. - -### Store - -- Fast balanced dynamic Merkle tree for storing application state -- Support multiple Merkle tree backends in a single store - - allows using Ethereum Patricia Trie and Tendermint IAVL in same app -- Support iteration -- Provide caching for intermediate state during execution of blocks and transactions (including for iteration) -- Retain some amount of recent historical state -- Allow many kinds of proofs (exists, absent, range, etc.) on current and retained historical state - -### ABCI Application - -- Simple connector between developer's application logic and the ABCI protocol -- Simplify discrepancy between DeliverTx and CheckTx -- Handles ABCI handshake logic and historical state -- Provide simple hooks to BeginBlock and EndBlock - -### Transaction Processing - -- Transactions consist of composeable messages -- Processing via series of handlers that handle authenticate, deduct fees, transfer coins, etc. -- Developers control tx encoding - - Default go-wire - - Must be able to write eg. Ethermint using the SDK with Ethereum-native transaction encoding -- Handler access to the store is restricted via capabilities and interfaces -- Context object holds - -### Data Types - -- Default Ethereum-style Account -- Default multi-asset Coins -