Jae Kwon
+27
-11
@@ -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
|
||||
|
||||
+13
-44
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user