From 5fa668a94d7ea02a18306a40dc9bb8f9fd69dd64 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Mon, 28 Aug 2017 17:35:04 -0400 Subject: [PATCH 01/10] docs: typo in basecoin-basics --- docs/guide/basecoin-basics.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/guide/basecoin-basics.md b/docs/guide/basecoin-basics.md index d57d4e316..cb91b1e11 100644 --- a/docs/guide/basecoin-basics.md +++ b/docs/guide/basecoin-basics.md @@ -320,7 +320,6 @@ To remove all the files created and refresh your environment (e.g., if starting ```shelldown[end-of-tutorials] basecli reset_all rm -rf ~/.basecoin -rm -rf ~/.basecoin ``` ## Conclusion From 71283673de1e0ffa8f70005bd356185610e049e3 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Mon, 28 Aug 2017 19:45:19 -0400 Subject: [PATCH 02/10] docs: minor edits throughout --- docs/quark/glossary.md | 158 ++++++++++++++++++++--------------------- docs/quark/overview.md | 57 +++++++-------- docs/quark/stdlib.md | 77 ++++++++------------ 3 files changed, 135 insertions(+), 157 deletions(-) diff --git a/docs/quark/glossary.md b/docs/quark/glossary.md index 5d014c377..a9b5ce3b1 100644 --- a/docs/quark/glossary.md +++ b/docs/quark/glossary.md @@ -1,28 +1,29 @@ # Glossary -This glossary defines many terms used throughout documentation of Quark. If +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 +concepts that are used. Other documents will explain in more detail how to combine these concepts to build a particular application. -## Transaction (tx) +## 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 (key-value store), and -it must have a deterministic action. The tx is the main piece of one request. +it must have a deterministic action. The transaction is the main piece of one +request. 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. +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? @@ -39,54 +40,54 @@ type Fee struct { 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. +request runs at. In order to carry this information between modules it is +saved to the context. Further, all information must be deterministic from +the context in which the request runs (based on the transaction and the block +it was included in) and can be used to validate the transaction. ## Data 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 +In order 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 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 +points. That 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 +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](https://github.com/tendermint/basecoin/tree/unstable/stack) +security holes. If you use the +[stack](https://github.com/cosmos/cosmos-sdk/tree/master/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, but rather only its own prefixed subset of the store. This is achieved by prefixing all keys transparently with ` + 0x0`, using the null -byte as a separator. Since the module name must be a string, no malicious +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 is to add permissions to the transaction context. The tx context -can specify that the tx has been signed by one or multiple specific +The second is to add permissions to the transaction context. The transaction +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 +A transactions 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)), +[auth](https://github.com/cosmos/cosmos-sdk/tree/master/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 +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 @@ -94,7 +95,7 @@ child of the original one. 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, +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....) @@ -102,7 +103,7 @@ memory space of the application, then get worried....) The ABCI interface is handled by `app`, which translates these data structures 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` +wire. The basic interface for any code that modifies state is the `Handler` interface, which provides four methods: ```golang @@ -123,11 +124,11 @@ interoperability, much like `http.Handler` does in golang web development. ## Middleware 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 signatures, and adds the permissions to -the Context before passing the request along). +before (and after) executing the registered `Handler`. Some examples are a +logger (that records the time before executing the transaction, then outputs +info - including duration - after the execution), of a signature checker (which +unwraps the transaction by one layer, verifies signatures, and adds the +permissions to the Context before passing the request along). In keeping with the standardization of `http.Handler` and inspired by the super minimal [negroni](https://github.com/urfave/negroni/blob/master/README.md) @@ -154,31 +155,31 @@ self-sufficient. Common elements of a module are: * middleware (to handler any wrapper transactions) To enable a module, you must add the appropriate middleware (if any) to the -stack in `main.go` for the client application (Quark default: +stack in `main.go` for the client application (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. +(default: `app/app.go`). Once the stack is compiled into a `Handler`, +then each transaction is handled by the appropriate module. ## Dispatcher We usually will want to have multiple modules working together, and need to -make sure the correct transactions get to the correct module. So we have have -`coin` sending money, `roles` creating multi-sig accounts, and `ibc` following -other chains all working together without interference. +make sure the correct transactions get to the correct module. So we have the +`coin` sending money, `roles` to create multi-sig accounts, and `ibc` for +following other chains all working together without interference. After the chain of middleware, we can register a `Dispatcher`, which also -implements the `Handler` interface. We then register a list of modules with +implements the `Handler` interface. We then register a list of modules with the dispatcher. Every module has a unique `Name()`, which is used for -isolating its state space. We use this same name for routing tx. Each tx -implementation must be registed with go-wire via `TxMapper`, so we just look -at the registered name of this tx, which should be of the form +isolating its state space. We use this same name for routing transactions. +Each transaction implementation must be registed with go-wire via `TxMapper`, +so we just look at the registered name of this tx, which should be of the form `/xxx`. The dispatcher grabs the appropriate module name from the tx name and routes it if the module is present. -This all seems a bit of magic, but really just making use of the other magic -(go-wire) that we are already using, rather than add another layer. The only -thing you need to remember is to use the following pattern, then all the tx -will be properly routed: +This all seems like a bit of magic, but really we're just making use of go-wire +magic that we are already using, rather than add another layer. For all the +transactions to be properly routed, the only thing you need to remember is to +use the following pattern: ```golang const ( @@ -192,34 +193,31 @@ const ( 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. One example is the `fee` middleware, which wants to deduct coins from the -calling account and can accomplished most easilty with the `coin` module. +calling account and can be accomplished most easily 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. +To make a call from the middleware, we the `next` Handler, which will execute +the rest of the stack. It can create a new SendTx and pass it down the +stack. If it returns success, do the rest of the processing (and send the +original transaction 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`, +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 +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. +If the transaction 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/cosmos/cosmos-sdk/blob/master/docs/guide/counter/plugins/counter/counter.go)for a better idea. ## Permissions 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 +limited access to each other and also to allow more types of permissions than +simple public key signatures. Rather than just use an address to identify who is performing an action, we can use a more complex structure: ```golang @@ -235,28 +233,26 @@ 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))` +`ChainID` is for IBC, discussed below. Let's 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))` -In addition to permissioning, the Actors are addresses just like public key +In addition to the permissions schema, 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). -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. +One idea - not yet implemented - is to provide scopes on the permissions. +Currently, if I sign a transaction 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. ## Replay Protection @@ -264,7 +260,7 @@ similar problem, and maybe could provide some inspiration. 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 +`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 @@ -290,11 +286,11 @@ 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 +common example is a stack which will send coins and charge a fee. Within the SDK 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) -Wow, this is a big topic. Also a WIP. Add more here... +Stay tuned! diff --git a/docs/quark/overview.md b/docs/quark/overview.md index 83a807580..7ae5ad3f0 100644 --- a/docs/quark/overview.md +++ b/docs/quark/overview.md @@ -6,35 +6,34 @@ and match modular elements as desired. Along side, all modules are permissioned and sandboxed to isolate modules for greater application security. For more explanation please see the [standard -library](https://github.com/tendermint/basecoin/blob/unstable/docs/quark/stdlib.md) +library](stdlib.md) and -[glossary](https://github.com/tendermint/basecoin/blob/unstable/docs/quark/glossary.md) +[glossary](glossary.md) documentation. For a more interconnected schematics see these -[framework](https://github.com/tendermint/basecoin/blob/unstable/docs/graphics/overview-framework.png) +[framework](../graphics/overview-framework.png) and -[security](https://github.com/tendermint/basecoin/blob/unstable/docs/graphics/overview-security.png) +[security](../graphics/overview-security.png) overviews. ## Framework Overview -### Transaction (tx) +### Transactions -Each tx passes through the middleware stack which can be defined uniquely by -each application. From the multiple layers of tx, each middleware may strip -off one level, like an onion. As so, the transaction must be constructed to -mirror the execution stack, and each middleware should allow embedding an -arbitrary tx for the next layer in the stack. +Each transaction passes through the middleware stack which can be defined +uniquely by each application. From the multiple layers of tx, each middleware +may strip off one level, like an onion. As such, the transaction must be +constructed to mirror the execution stack, and each middleware module should +allow embedding an arbitrary tx for the next layer in the stack. - + ### Execution Stack Middleware components allow for code reusability and integrability. A standard set of middleware are provided and can be mix-and-matched with custom -middleware. Some of the [standard -library](https://github.com/tendermint/basecoin/blob/unstable/docs/quark/stdlib.md) +middleware. Some of the [standardlibrary](stdlib.md) middlewares provided in this package include: - Logging - Recovery @@ -45,37 +44,37 @@ middlewares provided in this package include: - Roles - Inter-Blockchain-Communication (IBC) - As a part of stack execution the state space provided to each middleware is +As a part of stack execution the state space provided to each middleware is isolated (see [Data Store](overview.md#data-store)). When executing the stack, -state-recovery points (checkpoints) can be assigned for stack execution of -`CheckTx` or `DeliverTx`. This means, that all state changes will be reverted -to the checkpoint state on failure when either being run as a part of `CheckTx` +state-recovery check-points can be assigned for stack execution of `CheckTx` +or `DeliverTx`. This means, that all state changes will be reverted to the +checkpoint state on failure when either being run as a part of `CheckTx` or `DeliverTx`. Example usage of the checkpoints is when we may want to deduct -a fee even if the end business logic fails, under this situation we would add -the DeliverTx Checkpoint to after the fee middleware but before the business +a fee even if the end business logic fails; under this situation we would add +the `DeliverTx` checkpoint after the fee middleware but before the business logic. This diagram displays a typical process flow through an execution stack. - + ### Dispatcher -The dispatcher handler aims to allow for reusable business logic. As a +The dispatcher handler aims to allow for reusable business logic. As a transaction is passed to the end handler, the dispatcher routes the logic to -the correct module. To use the dispatcher tool all transaction types must +the correct module. To use the dispatcher tool, all transaction types must first be registered with the dispatcher. Once registered the middleware stack or any other handler can call the dispatcher to execute a transaction. -Similarity to the execution stack, when executing a transaction the dispatcher +Similarly to the execution stack, when executing a transaction the dispatcher isolates the state space available to the designated module (see [Data Store](overview.md#data-store)). - + ## Security Overview ### Permission Each application is run in a sandbox to isolate security risks. When -interfacing between applications, if a one of those application is compromised +interfacing between applications, if a one of those applications is compromised the entire network should still be secure. This is achieved through actor permissioning whereby each chain, account, or application can provided a designated permission for the transaction context to perform a specific action. @@ -83,7 +82,7 @@ designated permission for the transaction context to perform a specific action. Context is passed through the middleware and dispatcher, allowing one to add permissions on this app-space, and check current permissions. - + ### Data Store @@ -93,13 +92,11 @@ is achieved through the use of unique prefix assigned to each module. From the module's perspective it is no different, the module need-not have regard for the prefix as it is assigned outside of the modules scope. For example, if a module named `foo` wanted to write to the store it could save records under the -key `bar` however the dispatcher would register that record in the persistent +key `bar`, however, the dispatcher would register that record in the persistent state under `foo/bar`. Next time the `foo` app was called that record would be accessible to it under the assigned key `bar`. This effectively makes app prefixing invisible to each module while preventing each module from affecting each other module. Under this model no two registered modules are permitted to have the same namespace. - - - + diff --git a/docs/quark/stdlib.md b/docs/quark/stdlib.md index 97965c941..465dc3d4d 100644 --- a/docs/quark/stdlib.md +++ b/docs/quark/stdlib.md @@ -1,9 +1,9 @@ # Standard Library -The Quark framework comes bundled with a number of standard modules that +The Cosmos-SDK 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. +See examples below. It is recommended to investigate if desired +functionality is already provided before developing new modules. ## Basic Middleware @@ -22,18 +22,18 @@ 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 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. +The first layer of the transaction contains the signatures to authorize it. +This is then verified by `modules.auth.Signatures`. All transactions 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 multi-sig being delayed -months before being committed to the chain. This functionality is provided in -`modules.base.Chain` +The next layer of a transaction (in the standard stack) binds the transaction +to a specific chain with a block height that has an optional expiration. This +keeps the transactions from being replayed on 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 @@ -44,22 +44,22 @@ 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. - 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` +Rather than force each module to implement its own replay protection, a +transaction 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). +discussion](https://github.com/cosmos/cosmos-sdk/issues/160). ### Fees -An optional feature, but useful on many chains, is charging transaction fees. A -simple implementation of this is provided in `modules.fee.SimpleFeeMiddleware`. +An optional - but useful - feature 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 +every transaction with insufficient fee is rejected. This fee is deducted from the payers account before executing any other transaction. This module is dependent on the `coin` module. @@ -82,7 +82,7 @@ requires some payment solution, like fees or trader. ### Roles -Roles encapsulates what are typically called N-of-M multi-signatures accounts +Roles encapsulate 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 permission system. For example, a set of people could be called registrars, which can authorize a new IBC chain, and need eg. 2 @@ -95,7 +95,7 @@ a role is planned in the near future. ### Inter-Blockchain Communication (IBC) -IBC, is the cornerstone of The Cosmos Network, and is built into the quark +IBC, is the cornerstone of The Cosmos Network, and is built into the Cosmos-SDK 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 @@ -105,39 +105,24 @@ 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 block), and this generally requires approval of an authorized registrar (which -may be a multi-sig role). Updating a registered chain can be done by anyone, +may be a multi-sig role). Updating a registered chain can be done by anyone, 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 +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 chain). -`PostPacketTx` can post a tx that was created on another chain along with the -merkle proof, which must match an already registered header. If this chain -can verify the authenticity, it will accept the packet, along with all the -permissions from the other chain, and execute it on this stack. This is the +`PostPacketTx` can post a transaction that was created on another chain along +with the merkle proof, which must match an already registered header. If this +chain can verify the authenticity, it will accept the packet, along with all +the permissions from the other chain, and execute it on this stack. This is the only way to get permissions that belong to another chain. These various pieces can be combined in a relay, which polls for new packets on one chain, and then posts the packets along with the new headers on the other chain. -## Planned Apps - -### Staking - -Straight-forward PoS as used for cosmos. -Based on [basecoin-stake](https://github.com/tendermint/basecoin-stake) - -### Voting - -Simple elections that can authorize other tx, like roles. A building block for -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. +## Example Apps +See the [Cosmos Academy](https://github.com/cosmos/cosmos-academy) for example applications. From 8ba41d718cb4d7f99ca58f8968450ffdf9582851 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Mon, 28 Aug 2017 19:46:57 -0400 Subject: [PATCH 03/10] docs: move API draft to architecture directory --- docs/{rest/API_draft.md => architecture/API.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{rest/API_draft.md => architecture/API.md} (100%) diff --git a/docs/rest/API_draft.md b/docs/architecture/API.md similarity index 100% rename from docs/rest/API_draft.md rename to docs/architecture/API.md From f2fcfba3e3bd1f5d745e74da5a7a1d819137d350 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Mon, 28 Aug 2017 20:10:48 -0400 Subject: [PATCH 04/10] move & edit content from quarks/readme --- README.md | 10 +++++++- docs/quark/README.md | 54 -------------------------------------------- 2 files changed, 9 insertions(+), 55 deletions(-) delete mode 100644 docs/quark/README.md diff --git a/README.md b/README.md index 71df4da94..4d8b59b23 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,17 @@ Branch | Tests | Coverage | Report Card develop | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/develop/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/develop)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/master)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) -The Cosmos SDK 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 +The Cosmos SDK is the core framework for constructing +the atom tokens which will power [The Cosmos Network](https://cosmos.network/). It 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. +This SDK affords you all the tools you need to rapidly develop +robust blockchains and blockchain applications which are interoperable with The +Cosmos Hub. It is 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? + Within this repository, the `basecoin` app 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 libraries, and away you go with a full-stack blockchain and command line tool for transacting. diff --git a/docs/quark/README.md b/docs/quark/README.md deleted file mode 100644 index bfdd7cc3d..000000000 --- a/docs/quark/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# Quark - -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/). - -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 Quark. - -## Inspiration - -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, ...) - 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) -overwriting of data. - -Not all of these can be pulled one-to-one in the blockchain world, but they do -provide inspiration to provide orthogonal pieces that can easily be combined -into various applications. - -## Further reading - -* [Quark overview](overview.md) -* [Glossary of the terms](glossary.md) -* [Standard modules](stdlib.md) -* Guide to building a module -* Demo of CLI tool -* IBC in detail -* Diagrams... Coming Soon! From 287bf8a503c59e49d1d2b4c67cdec0b35eee51fc Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Mon, 28 Aug 2017 20:27:03 -0400 Subject: [PATCH 05/10] move sdk files out of quarks directory --- docs/{quark => }/glossary.md | 0 docs/{quark => }/overview.md | 0 docs/{quark => }/stdlib.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename docs/{quark => }/glossary.md (100%) rename docs/{quark => }/overview.md (100%) rename docs/{quark => }/stdlib.md (100%) diff --git a/docs/quark/glossary.md b/docs/glossary.md similarity index 100% rename from docs/quark/glossary.md rename to docs/glossary.md diff --git a/docs/quark/overview.md b/docs/overview.md similarity index 100% rename from docs/quark/overview.md rename to docs/overview.md diff --git a/docs/quark/stdlib.md b/docs/stdlib.md similarity index 100% rename from docs/quark/stdlib.md rename to docs/stdlib.md From 2c3e5ff5b79c51a8f6d4f6b4eeb4a84d2db1d835 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Tue, 29 Aug 2017 13:34:42 -0400 Subject: [PATCH 06/10] docs: set correct graphics link --- docs/overview.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index 7ae5ad3f0..d3c989920 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -12,9 +12,9 @@ and documentation. For a more interconnected schematics see these -[framework](../graphics/overview-framework.png) +[framework](graphics/overview-framework.png) and -[security](../graphics/overview-security.png) +[security](graphics/overview-security.png) overviews. ## Framework Overview @@ -27,7 +27,7 @@ may strip off one level, like an onion. As such, the transaction must be constructed to mirror the execution stack, and each middleware module should allow embedding an arbitrary tx for the next layer in the stack. - + ### Execution Stack @@ -54,7 +54,7 @@ a fee even if the end business logic fails; under this situation we would add the `DeliverTx` checkpoint after the fee middleware but before the business logic. This diagram displays a typical process flow through an execution stack. - + ### Dispatcher @@ -67,7 +67,7 @@ Similarly to the execution stack, when executing a transaction the dispatcher isolates the state space available to the designated module (see [Data Store](overview.md#data-store)). - + ## Security Overview @@ -82,7 +82,7 @@ designated permission for the transaction context to perform a specific action. Context is passed through the middleware and dispatcher, allowing one to add permissions on this app-space, and check current permissions. - + ### Data Store @@ -99,4 +99,4 @@ prefixing invisible to each module while preventing each module from affecting each other module. Under this model no two registered modules are permitted to have the same namespace. - + From 9249173a37a7bf28f9fda444b7f382c89ec77a88 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Tue, 29 Aug 2017 13:55:43 -0400 Subject: [PATCH 07/10] README; move banner image to docs/graphics --- README.md | 2 +- .../graphics/cosmos-sdk-image.png | Bin 2 files changed, 1 insertion(+), 1 deletion(-) rename cosmos-sdk-image.png => docs/graphics/cosmos-sdk-image.png (100%) diff --git a/README.md b/README.md index 4d8b59b23..d78ba93f6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Cosmos SDK -![banner](cosmos-sdk-image.png) +![banner](docs/graphics/cosmos-sdk-image.png) [![version](https://img.shields.io/github/tag/cosmos/cosmos-sdk.svg)](https://github.com/cosmos/cosmos-sdk/releases/latest) [![API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk?status.svg diff --git a/cosmos-sdk-image.png b/docs/graphics/cosmos-sdk-image.png similarity index 100% rename from cosmos-sdk-image.png rename to docs/graphics/cosmos-sdk-image.png From 49665dd4923f6e31996dcd91a698f8debd873a6e Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Tue, 29 Aug 2017 13:59:59 -0400 Subject: [PATCH 08/10] readme: improve wording --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d78ba93f6..728c4de2c 100644 --- a/README.md +++ b/README.md @@ -13,16 +13,18 @@ Branch | Tests | Coverage | Report Card develop | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/develop/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/develop)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/master)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) -The Cosmos SDK is the core framework for constructing -the atom tokens which will power [The Cosmos Network](https://cosmos.network/). It 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 +The Cosmos SDK is the middleware platform which the [Cosmos](https://cosmos.network) HUB is constructed from. The HUB is a blockchain (or, internet of blockchains) in which the atom supply resides. The atos supply is defined at genesis and can change based on the rules of the HUB. + +Under the hood, the Cosmos SDK 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. This SDK affords you all the tools you need to rapidly develop robust blockchains and blockchain applications which are interoperable with The Cosmos Hub. It is 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? +application customization. For example, does your app require fees, how do you +want to log messages, do you enable IBC, do you even have a cryptocurrency? In +this way, the Cosmos SDK is the **Rails of cryptocurrencies**. Within this repository, the `basecoin` app 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 libraries, and away you go with a full-stack blockchain and command line tool for transacting. From 15a7fa2eacc8db79dfd4f1e319416dc1b27f72d5 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Tue, 29 Aug 2017 17:13:34 -0400 Subject: [PATCH 09/10] docs: address comments & other updates --- README.md | 3 +-- docs/architecture/API.md | 2 +- docs/glossary.md | 14 +++++++------- docs/guide/basecoin-plugins.md | 12 ++++++------ docs/guide/install.md | 9 ++++----- docs/overview.md | 11 ++++++----- docs/stdlib.md | 8 ++++---- 7 files changed, 29 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 728c4de2c..1cf56c64a 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,7 @@ application customization. For example, does your app require fees, how do you want to log messages, do you enable IBC, do you even have a cryptocurrency? In this way, the Cosmos SDK is the **Rails of cryptocurrencies**. -Within this repository, the `basecoin` app 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 libraries, and away -you go with a full-stack blockchain and command line tool for transacting. +Within this repository, the `basecoin` app 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 libraries, and away you go with a full-stack blockchain and command line tool for transacting. ## Prerequisites diff --git a/docs/architecture/API.md b/docs/architecture/API.md index 0721c1a99..ddabc8a8c 100644 --- a/docs/architecture/API.md +++ b/docs/architecture/API.md @@ -14,7 +14,7 @@ By default we will serve on `http://localhost:2024`. CORS will be disabled by d The MVP will allow us to move around money. This involves the following functions: -## Construct an unsigned tx +## Construct an unsigned transaction `POST /build/send` diff --git a/docs/glossary.md b/docs/glossary.md index a9b5ce3b1..dc6e641d3 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -20,10 +20,10 @@ 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. +types there. This allows us to deserialize the entire transaction 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? @@ -172,9 +172,9 @@ implements the `Handler` interface. We then register a list of modules with the dispatcher. Every module has a unique `Name()`, which is used for isolating its state space. We use this same name for routing transactions. Each transaction implementation must be registed with go-wire via `TxMapper`, -so we just look at the registered name of this tx, which should be of the form -`/xxx`. The dispatcher grabs the appropriate module name from - the tx name and routes it if the module is present. +so we just look at the registered name of this transaction, which should be +of the form `/xxx`. The dispatcher grabs the appropriate module +name from the tx name and routes it if the module is present. This all seems like a bit of magic, but really we're just making use of go-wire magic that we are already using, rather than add another layer. For all the diff --git a/docs/guide/basecoin-plugins.md b/docs/guide/basecoin-plugins.md index 36655b56b..9fb74840e 100644 --- a/docs/guide/basecoin-plugins.md +++ b/docs/guide/basecoin-plugins.md @@ -79,7 +79,7 @@ both use the same library of commands, including one for signing and broadcasting `SendTx`. Counter transactions take two custom inputs, a boolean argument named `valid`, -and a coin amount named `countfee`. The transaction is only accepted if both +and a coin amount named `countfee`. The transaction is only accepted if both `valid` is set to true and the transaction input coins is greater than `countfee` that the user provides. @@ -126,11 +126,11 @@ them. Of course, we can also expose queries on our plugin: countercli query counter ``` -Tada! We can now see that our custom counter plugin tx went through. You -should see a Counter value of 1 representing the number of valid transactions. -If we send another transaction, and then query again, we will see the value -increment. Note that we need the sequence number here to send the coins -(it didn't increment when we just pinged the counter) +Tada! We can now see that our custom counter plugin transactions went through. +You should see a Counter value of 1 representing the number of valid +transactions. If we send another transaction, and then query again, we will +see the value increment. Note that we need the sequence number here to send the +coins (it didn't increment when we just pinged the counter) ```shelldown[4] countercli tx counter --name cool --countfee=2mycoin --sequence=2 --valid diff --git a/docs/guide/install.md b/docs/guide/install.md index c9ade8c78..15954a797 100644 --- a/docs/guide/install.md +++ b/docs/guide/install.md @@ -4,14 +4,14 @@ If you aren't used to compile go programs and just want the released version of the code, please head to our [downloads](https://tendermint.com/download) page to get a pre-compiled binary for your platform. -On a good day, basecoin can be installed like a normal Go program: +Usually, Cosmos SDK can be installed like a normal Go program: ``` -go get -u github.com/tendermint/basecoin/cmd/... +go get -u github.com/cosmos/cosmos-sdk/cmd/... ``` -In some cases, if that fails, or if another branch is required, -we use `glide` for dependency management. +If the dependencies have been updated with breaking changes, +or if another branch is required, `glide` is used for dependency management. Thus, assuming you've already run `go get` or otherwise cloned the repo, the correct way to install is: @@ -30,4 +30,3 @@ If you need another branch, make sure to run `git checkout ` before `make all`. And if you switch branches a lot, especially touching other tendermint repos, you may need to `make fresh` sometimes so glide doesn't get confused with all the branches and versions lying around. - diff --git a/docs/overview.md b/docs/overview.md index d3c989920..96c6d6852 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -19,13 +19,14 @@ overviews. ## Framework Overview -### Transactions +### Transactions (tx) Each transaction passes through the middleware stack which can be defined -uniquely by each application. From the multiple layers of tx, each middleware -may strip off one level, like an onion. As such, the transaction must be -constructed to mirror the execution stack, and each middleware module should -allow embedding an arbitrary tx for the next layer in the stack. +uniquely by each application. From the multiple layers of transaction, each +middleware may strip off one level, like an onion. As such, the transaction +must be constructed to mirror the execution stack, and each middleware module +should allow an arbitrary transaction to be embedded for the next layer in +the stack. diff --git a/docs/stdlib.md b/docs/stdlib.md index 465dc3d4d..805678f18 100644 --- a/docs/stdlib.md +++ b/docs/stdlib.md @@ -108,10 +108,10 @@ block), and this generally requires approval of an authorized registrar (which may be a multi-sig role). Updating a registered chain can be done by anyone, 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 -chain). +by calling `CreatePacketTx` over IPC (inter-plugin communication) with a +transaction 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 chain). `PostPacketTx` can post a transaction that was created on another chain along with the merkle proof, which must match an already registered header. If this From c9a620d10746006f61fe4a73db0cfafbe3fb742e Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Thu, 31 Aug 2017 13:33:46 -0400 Subject: [PATCH 10/10] docs: address moar comments & re-add (modified) inspiration --- README.md | 28 ++++++++++++++++++++++- docs/glossary.md | 8 +++---- docs/guide/counter/cmd/countercli/main.go | 16 +++++++------ docs/overview.md | 6 ++--- 4 files changed, 43 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 1cf56c64a..f47ab92a7 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Branch | Tests | Coverage | Report Card develop | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/develop/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/develop)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/master)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) -The Cosmos SDK is the middleware platform which the [Cosmos](https://cosmos.network) HUB is constructed from. The HUB is a blockchain (or, internet of blockchains) in which the atom supply resides. The atos supply is defined at genesis and can change based on the rules of the HUB. +The Cosmos SDK is the middleware platform which the [Cosmos Hub](https://cosmos.network) is constructed from. The Hub is a blockchain (or, internet of blockchains) in which the Atom supply resides. The Atoms supply is defined at genesis and can change based on the rules of the Hub. Under the hood, the Cosmos SDK 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. @@ -49,3 +49,29 @@ See the [install guide](/docs/guide/install.md) for more details. * See [more examples](https://github.com/cosmos/cosmos-academy) To deploy a testnet, see our [repository of deployment tools](https://github.com/tendermint/tools). + +# Inspiration + +The basic concept for this SDK comes 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 while `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, etc) - developers can write a self-contained package + with a given set of functionality, which can be imported and reused in other + apps + +Also at play is the concept of different tables/schemas in databases, thus you can +keep the different modules safely separated and avoid any accidental (or malicious) +overwriting of data. + +Not all of these can be compare one-to-one in the blockchain world, but they do +provide inspiration for building orthogonal pieces that can easily be combined +into various applications. diff --git a/docs/glossary.md b/docs/glossary.md index dc6e641d3..ba6bb72ec 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -21,9 +21,9 @@ 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 transaction 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. +(even with types defined in other repos), to easily embed an arbitrary transaction +inside another without specifying the type, and provide an automatic json +representation allowing for 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? @@ -163,7 +163,7 @@ then each transaction is handled by the appropriate module. ## Dispatcher We usually will want to have multiple modules working together, and need to -make sure the correct transactions get to the correct module. So we have the +make sure the correct transactions get to the correct module. So we have `coin` sending money, `roles` to create multi-sig accounts, and `ibc` for following other chains all working together without interference. diff --git a/docs/guide/counter/cmd/countercli/main.go b/docs/guide/counter/cmd/countercli/main.go index 184b222aa..4bd49b99d 100644 --- a/docs/guide/counter/cmd/countercli/main.go +++ b/docs/guide/counter/cmd/countercli/main.go @@ -12,6 +12,7 @@ import ( "github.com/cosmos/cosmos-sdk/client/commands/proxy" "github.com/cosmos/cosmos-sdk/client/commands/query" "github.com/cosmos/cosmos-sdk/client/commands/seeds" + txcmd "github.com/cosmos/cosmos-sdk/client/commands/txs" bcount "github.com/cosmos/cosmos-sdk/docs/guide/counter/cmd/countercli/commands" authcmd "github.com/cosmos/cosmos-sdk/modules/auth/commands" @@ -21,15 +22,16 @@ import ( noncecmd "github.com/cosmos/cosmos-sdk/modules/nonce/commands" ) -// BaseCli represents the base command when called without any subcommands -var BaseCli = &cobra.Command{ +// CounterCli represents the base command when called without any subcommands +var CounterCli = &cobra.Command{ Use: "countercli", - Short: "Light client for tendermint", - Long: `Basecli is an version of tmcli including custom logic to -present a nice (not raw hex) interface to the basecoin blockchain structure. + Short: "Example app built using the Cosmos SDK", + Long: `Countercli is a demo app that includes custom logic to +present a formatted interface to a custom blockchain structure. + +This is a useful tool and also serves to demonstrate how to configure +the Cosmos SDK to work for any custom ABCI app, see: -This is a useful tool, but also serves to demonstrate how one can configure -tmcli to work for any custom abci app. `, } diff --git a/docs/overview.md b/docs/overview.md index 96c6d6852..b77307379 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -34,7 +34,7 @@ the stack. Middleware components allow for code reusability and integrability. A standard set of middleware are provided and can be mix-and-matched with custom -middleware. Some of the [standardlibrary](stdlib.md) +middleware. Some of the [standard library](stdlib.md) middlewares provided in this package include: - Logging - Recovery @@ -47,7 +47,7 @@ middlewares provided in this package include: As a part of stack execution the state space provided to each middleware is isolated (see [Data Store](overview.md#data-store)). When executing the stack, -state-recovery check-points can be assigned for stack execution of `CheckTx` +state-recovery checkpoints can be assigned for stack execution of `CheckTx` or `DeliverTx`. This means, that all state changes will be reverted to the checkpoint state on failure when either being run as a part of `CheckTx` or `DeliverTx`. Example usage of the checkpoints is when we may want to deduct @@ -75,7 +75,7 @@ Store](overview.md#data-store)). ### Permission Each application is run in a sandbox to isolate security risks. When -interfacing between applications, if a one of those applications is compromised +interfacing between applications, if one of those applications is compromised the entire network should still be secure. This is achieved through actor permissioning whereby each chain, account, or application can provided a designated permission for the transaction context to perform a specific action.