diff --git a/docs/sdk/README.md b/docs/sdk/README.md new file mode 100644 index 000000000..059970cb2 --- /dev/null +++ b/docs/sdk/README.md @@ -0,0 +1,29 @@ +# Cosmos SDK Documentation + +- [Overview](overview) + - [Overview](overview/overview.md) - An overview of the Cosmos-SDK + - [The Object-Capability Model](overview/capabilities.md) - + - [Application Architecture](overview/apps.md) - Understanding SDK + application architecture +- [Install](install.md) - Install the SDK library and example applications +- [Core](core) + - [The Store](core/store.md) - How to work with the database + - [Messages](core/messages.md) - Messages contain the content of a transaction + - [Handlers](core/handlers.md) - Handlers are the workhorse of the app! + - [Amino](core/amino.md) - Amino is the primary serialization library used in the SDK + - [Accounts](core/accounts.md) - Accounts are the prototypical object kept in the store + - [Transactions](core/transactions.md) - Transactions wrap messages and provide authentication + - [Keepers](core/keepers.md) - Keepers are the interfaces between handlers +- [Modules](modules) + - [Bank](modules/bank.md) + - [Staking](modules/staking.md) + - [Slashing](modules/slashing.md) + - [Provisions](modules/provisions.md) + - [Governance](modules/governance.md) + - [IBC](modules/ibc.md) +- [Clients](clients) + - [Running a Node](clients/node.md) + - [Key Management](clients/keys.md) - Managing user keys + - [CLI](clients/cli.md) - Queries and transactions via command line + - [Light Client Daemon](clients/lcd.md) - Queries and transactions via REST + API diff --git a/docs/sdk/clients/key-management.md b/docs/sdk/clients/key-management.md new file mode 100644 index 000000000..1474989b9 --- /dev/null +++ b/docs/sdk/clients/key-management.md @@ -0,0 +1,7 @@ +# Key Management + +Here we cover many aspects of handling keys within the Cosmos SDK +framework. + +// TODO add relevant key discussion +(related https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/encoding.md#public-key-cryptography) diff --git a/docs/sdk/clients/lcd-rest-api.yaml b/docs/sdk/clients/lcd-rest-api.yaml new file mode 100644 index 000000000..a39b7bf08 --- /dev/null +++ b/docs/sdk/clients/lcd-rest-api.yaml @@ -0,0 +1,781 @@ +swagger: '2.0' +info: + version: '1.1.0' + title: Light client daemon to interface with Cosmos baseserver via REST + description: Specification for the LCD provided by `gaiacli advanced rest-server` + + +securityDefinitions: + kms: + type: basic + +paths: + /version: + get: + summary: Version of the light client daemon + description: Get the version of the LCD running locally to compare against expected + responses: + 200: + description: Plaintext version i.e. "v0.5.0" + /node_version: + get: + summary: Version of the connected node + description: Get the version of the SDK running on the connected node to compare against expected + responses: + 200: + description: Plaintext version i.e. "v0.5.0" + /node_info: + get: + description: Only the node info. Block information can be queried via /block/latest + summary: The propertied of the connected node + produces: + - application/json + responses: + 200: + description: Node status + schema: + type: object + properties: + pub_key: + $ref: '#/definitions/PubKey' + moniker: + type: string + example: 159.89.198.221 + network: + type: string + example: gaia-2 + remote_addr: + type: string + listen_addr: + type: string + example: 192.168.56.1:26656 + version: + description: Tendermint version + type: string + example: 0.15.0 + other: + description: more information on versions + type: array + items: + type: string + /syncing: + get: + summary: Syncing state of node + description: Get if the node is currently syning with other nodes + responses: + 200: + description: '"true" or "false"' + + /keys: + get: + summary: List of accounts stored locally + produces: + - application/json + responses: + 200: + description: Array of accounts + schema: + type: array + items: + $ref: '#/definitions/Account' + post: + summary: Create a new account locally + consumes: + - application/json + parameters: + - in: body + name: account + description: The account to create + schema: + type: object + required: + - name + - password + - seed + properties: + name: + type: string + password: + type: string + seed: + type: string + responses: + 200: + description: Returns address of the account created + /keys/seed: + get: + summary: Create a new seed to create a new account with + produces: + - application/json + responses: + 200: + description: 16 word Seed + schema: + type: string + /keys/{name}: + parameters: + - in: path + name: name + description: Account name + required: true + type: string + get: + summary: Get a certain locally stored account + produces: + - application/json + responses: + 200: + description: Locally stored account + schema: + $ref: "#/definitions/Account" + 404: + description: Account is not available + put: + summary: Update the password for this account in the KMS + consumes: + - application/json + parameters: + - in: body + name: account + description: The new and old password + schema: + type: object + required: + - new_password + - old_password + properties: + new_password: + type: string + old_password: + type: string + responses: + 200: + description: Updated password + 401: + description: Password is wrong + 404: + description: Account is not available + delete: + summary: Remove an account + consumes: + - application/json + parameters: + - in: body + name: account + description: The password of the account to remove from the KMS + schema: + type: object + required: + - password + properties: + password: + type: string + responses: + 200: + description: Removed account + 401: + description: Password is wrong + 404: + description: Account is not available +# /accounts/send: + # post: + # summary: Send coins (build -> sign -> send) + # security: + # - sign: [] + # requestBody: + # content: + # application/json: + # schema: + # type: object + # properties: + # fees: + # $ref: "#/definitions/Coins" + # outputs: + # type: array + # items: + # type: object + # properties: + # pub_key: + # $ref: "#/definitions/PubKey" + # amount: + # type: array + # items: + # $ref: "#/definitions/Coins" + # responses: + # 202: + # description: Tx was send and will probably be added to the next block + # 400: + # description: The Tx was malformated + + /accounts/{address}: + parameters: + - in: path + name: address + description: Account address in bech32 format + required: true + type: string + get: + summary: Get the account balances + produces: + - application/json + responses: + 200: + description: Account balances + schema: + $ref: "#/definitions/Balance" + 204: + description: There is no data for the requested account. This is not a 404 as the account might exist, just does not hold data. + /accounts/{address}/send: + parameters: + - in: path + name: address + description: Account address in bech32 format + required: true + type: string + post: + summary: Send coins (build -> sign -> send) + security: + - kms: [] + consumes: + - application/json + parameters: + - in: body + name: account + description: The password of the account to remove from the KMS + schema: + type: object + properties: + name: + type: string + password: + type: string + amount: + type: array + items: + $ref: "#/definitions/Coins" + chain_id: + type: string + squence: + type: number + responses: + 202: + description: Tx was send and will probably be added to the next block + 400: + description: The Tx was malformated + /blocks/latest: + get: + summary: Get the latest block + produces: + - application/json + responses: + 200: + description: The latest block + schema: + $ref: "#/definitions/Block" + /blocks/{height}: + parameters: + - in: path + name: height + description: Block height + required: true + type: number + get: + summary: Get a block at a certain height + produces: + - application/json + responses: + 200: + description: The block at a specific height + schema: + $ref: "#/definitions/Block" + 404: + description: Block at height is not available + /validatorsets/latest: + get: + summary: Get the latest validator set + produces: + - application/json + responses: + 200: + description: The validator set at the latest block height + schema: + type: object + properties: + block_height: + type: number + validators: + type: array + items: + $ref: "#/definitions/Validator" + /validatorsets/{height}: + parameters: + - in: path + name: height + description: Block height + required: true + type: number + get: + summary: Get a validator set a certain height + produces: + - application/json + responses: + 200: + description: The validator set at a specific block height + schema: + type: object + properties: + block_height: + type: number + validators: + type: array + items: + $ref: "#/definitions/Validator" + 404: + description: Block at height not available + # /txs: + # parameters: + # - in: query + # name: tag + # schema: + # type: string + # example: "coin.sender=EE5F3404034C524501629B56E0DDC38FAD651F04" + # required: true + # - in: query + # name: page + # description: Pagination page + # schema: + # type: number + # default: 0 + # - in: query + # name: size + # description: Pagination size + # schema: + # type: number + # default: 50 + # get: + # summary: Query Tx + # responses: + # 200: + # description: All Tx matching the provided tags + # content: + # application/json: + # schema: + # type: array + # items: + # $ref: "#/definitions/Tx" + # 404: + # description: Pagination is out of bounds + # /txs/sign: + # post: + # summary: Sign a Tx + # description: Sign a Tx providing locally stored account and according password + # security: + # - sign: [] + # requestBody: + # content: + # application/json: + # schema: + # $ref: "#/definitions/TxBuild" + # responses: + # 200: + # description: The signed Tx + # content: + # application/json: + # schema: + # $ref: "#/definitions/TxSigned" + # 401: + # description: Account name and/or password where wrong + # /txs/broadcast: + # post: + # summary: Send signed Tx + # requestBody: + # content: + # application/json: + # schema: + # $ref: "#/definitions/TxSigned" + # responses: + # 202: + # description: Tx was send and will probably be added to the next block + # 400: + # description: The Tx was malformated + /txs/{hash}: + parameters: + - in: path + name: hash + description: Tx hash + required: true + type: string + get: + summary: Get a Tx by hash + produces: + - application/json + responses: + 200: + description: Tx with the provided hash + schema: + $ref: "#/definitions/Tx" + 404: + description: Tx not available for provided hash + # /delegates: + # parameters: + # - in: query + # name: delegator + # description: Query for all delegates a delegator has stake with + # schema: + # $ref: "#/definitions/Address" + # get: + # summary: Get a list of canidates/delegates/validators (optionally filtered by delegator) + # responses: + # 200: + # description: List of delegates, filtered by provided delegator address + # content: + # application/json: + # schema: + # type: array + # items: + # $ref: "#/definitions/Delegate" + # /delegates/bond: + # post: + # summary: Bond atoms (build -> sign -> send) + # security: + # - sign: [] + # requestBody: + # content: + # application/json: + # schema: + # type: array + # items: + # type: object + # properties: + # amount: + # $ref: "#/definitions/Coins" + # pub_key: + # $ref: "#/definitions/PubKey" + # responses: + # 202: + # description: Tx was send and will probably be added to the next block + # 400: + # description: The Tx was malformated + # /delegates/unbond: + # post: + # summary: Unbond atoms (build -> sign -> send) + # security: + # - sign: [] + # requestBody: + # content: + # application/json: + # schema: + # type: array + # items: + # type: object + # properties: + # amount: + # $ref: "#/definitions/Coins" + # pub_key: + # $ref: "#/definitions/PubKey" + # responses: + # 202: + # description: Tx was send and will probably be added to the next block + # 400: + # description: The Tx was malformated + # /delegates/{pubkey}: + # parameters: + # - in: path + # name: pubkey + # description: Pubkey of a delegate + # required: true + # schema: + # type: string + # example: 81B11E717789600CC192B26F452A983DF13B985EE75ABD9DD9E68D7BA007A958 + # get: + # summary: Get a certain canidate/delegate/validator + # responses: + # 200: + # description: Delegate for specified pub_key + # content: + # application/json: + # schema: + # $ref: "#/definitions/Delegate" + # 404: + # description: No delegate found for provided pub_key + # /delegates/{pubkey}/bond: + # parameters: + # - in: path + # name: pubkey + # description: Pubkey of a delegate + # required: true + # schema: + # type: string + # example: 81B11E717789600CC192B26F452A983DF13B985EE75ABD9DD9E68D7BA007A958 + # post: + # summary: Bond atoms (build -> sign -> send) + # security: + # - sign: [] + # requestBody: + # content: + # application/json: + # schema: + # type: object + # properties: + # amount: + # $ref: "#/definitions/Coins" + # responses: + # 202: + # description: Tx was send and will probably be added to the next block + # 400: + # description: The Tx was malformated + # /delegates/{pubkey}/unbond: + # parameters: + # - in: path + # name: pubkey + # description: Pubkey of a delegate + # required: true + # schema: + # type: string + # example: 81B11E717789600CC192B26F452A983DF13B985EE75ABD9DD9E68D7BA007A958 + # post: + # summary: Unbond atoms (build -> sign -> send) + # security: + # - sign: [] + # requestBody: + # content: + # application/json: + # schema: + # type: object + # properties: + # amount: + # $ref: "#/definitions/Coins" + # responses: + # 202: + # description: Tx was send and will probably be added to the next block + # 400: + # description: The Tx was malformated + +definitions: + Address: + type: string + description: bech32 encoded addres + example: cosmosaccaddr:zgnkwr7eyyv643dllwfpdwensmgdtz89yu73zq + ValidatorAddress: + type: string + description: bech32 encoded addres + example: cosmosvaladdr:zgnkwr7eyyv643dllwfpdwensmgdtz89yu73zq + PubKey: + type: string + description: bech32 encoded public key + example: cosmosaccpub:zgnkwr7eyyv643dllwfpdwensmgdtz89yu73zq + ValidatorPubKey: + type: string + description: bech32 encoded public key + example: cosmosvalpub:zgnkwr7eyyv643dllwfpdwensmgdtz89yu73zq + Coins: + type: object + properties: + denom: + type: string + example: steak + amount: + type: number + example: 50 + Hash: + type: string + example: EE5F3404034C524501629B56E0DDC38FAD651F04 + Tx: + type: object + properties: + type: + type: string + enum: + - stake/delegate + data: + type: object + TxChain: + type: object + properties: + type: + type: string + default: chain/tx + data: + type: object + properties: + chain_id: + type: string + example: gaia-2 + expires_at: + type: number + example: 0 + tx: + type: object + properties: + type: + type: string + default: nonce + data: + type: object + properties: + sequence: + type: number + example: 0 + signers: + type: array + items: + type: object + properties: + chain: + type: string + example: '' + app: + type: string + default: sigs + addr: + $ref: "#/definitions/Address" + tx: + $ref: "#/definitions/Tx" + TxBuild: + type: object + properties: + type: + type: string + default: sigs/one + data: + type: object + properties: + tx: + $ref: "#/definitions/Tx" + signature: + type: object + properties: + Sig: + type: string + default: '' + Pubkey: + type: string + default: '' + TxSigned: + type: object + properties: + type: + type: string + default: sigs/one + data: + type: object + properties: + tx: + $ref: "#/definitions/Tx" + signature: + type: object + properties: + Sig: + type: string + example: 81B11E717789600CC192B26F452A983DF13B985EE75ABD9DD9E68D7BA007A958 + Pubkey: + $ref: "#/definitions/PubKey" + Account: + type: object + properties: + name: + type: string + example: Main Account + address: + $ref: "#/definitions/Address" + pub_key: + $ref: "#/definitions/PubKey" + Balance: + type: object + properties: + height: + type: number + example: 123456 + coins: + type: array + items: + $ref: "#/definitions/Coins" + credit: + type: array + items: + type: object + BlockID: + type: object + properties: + hash: + $ref: "#/definitions/Hash" + parts: + type: object + properties: + total: + type: number + example: 0 + hash: + $ref: "#/definitions/Hash" + Block: + type: object + properties: + header: + type: object + properties: + chain_id: + type: string + example: gaia-2 + height: + type: number + example: 1 + time: + type: string + example: '2017-12-30T05:53:09.287+01:00' + num_txs: + type: number + example: 0 + last_block_id: + $ref: "#/definitions/BlockID" + total_txs: + type: number + example: 35 + last_commit_hash: + $ref: "#/definitions/Hash" + data_hash: + $ref: "#/definitions/Hash" + validators_hash: + $ref: "#/definitions/Hash" + consensus_hash: + $ref: "#/definitions/Hash" + app_hash: + $ref: "#/definitions/Hash" + last_results_hash: + $ref: "#/definitions/Hash" + evidence_hash: + $ref: "#/definitions/Hash" + txs: + type: array + items: + $ref: "#/definitions/Tx" + evidence: + type: array + items: + type: object + last_commit: + type: object + properties: + blockID: + $ref: "#/definitions/BlockID" + precommits: + type: array + items: + type: object + Validator: + type: object + properties: + address: + $ref: '#/definitions/ValidatorAddress' + pub_key: + $ref: "#/definitions/ValidatorPubKey" + power: + type: number + example: 1000 + accum: + type: number + example: 1000 +# Added by API Auto Mocking Plugin +host: virtserver.swaggerhub.com +basePath: /faboweb1/Cosmos-LCD-2/1.0.0 +schemes: + - https diff --git a/docs/sdk/accounts.md b/docs/sdk/core/accounts.md similarity index 100% rename from docs/sdk/accounts.md rename to docs/sdk/core/accounts.md diff --git a/docs/sdk/amino.md b/docs/sdk/core/amino.md similarity index 100% rename from docs/sdk/amino.md rename to docs/sdk/core/amino.md diff --git a/docs/sdk/handlers.md b/docs/sdk/core/handlers.md similarity index 100% rename from docs/sdk/handlers.md rename to docs/sdk/core/handlers.md diff --git a/docs/sdk/keepers.md b/docs/sdk/core/keepers.md similarity index 100% rename from docs/sdk/keepers.md rename to docs/sdk/core/keepers.md diff --git a/docs/sdk/messages.md b/docs/sdk/core/messages.md similarity index 100% rename from docs/sdk/messages.md rename to docs/sdk/core/messages.md diff --git a/docs/sdk/store.md b/docs/sdk/core/store.md similarity index 81% rename from docs/sdk/store.md rename to docs/sdk/core/store.md index 46616a8eb..b0ebb306c 100644 --- a/docs/sdk/store.md +++ b/docs/sdk/core/store.md @@ -52,3 +52,18 @@ cat KVStore are stored separately in catDB with the prefix of disambiguate store items from other items of non-storage concern. + +## + +Mounting an IAVLStore +TODO: + +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. diff --git a/docs/sdk/transactions.md b/docs/sdk/core/transactions.md similarity index 100% rename from docs/sdk/transactions.md rename to docs/sdk/core/transactions.md diff --git a/docs/sdk/install.md b/docs/sdk/install.md new file mode 100644 index 000000000..bafdfc4bd --- /dev/null +++ b/docs/sdk/install.md @@ -0,0 +1,59 @@ +# Install + +The fastest and easiest way to install the Cosmos SDK binaries +is to run [this script](https://github.com/cosmos/cosmos-sdk/blob/develop/scripts/install_sdk_ubuntu.sh) on a fresh Ubuntu instance. Similarly, you can run [this script](https://github.com/cosmos/cosmos-sdk/blob/develop/scripts/install_sdk_bsd.sh) on a fresh FreeBSD instance. Read the scripts before running them to ensure no untrusted connection is being made, for example we're making curl requests to download golang. Also read the comments / instructions carefully (i.e., reset your terminal after running the script). + +Cosmos SDK can be installed to +`$GOPATH/src/github.com/cosmos/cosmos-sdk` like a normal Go program: + +``` +go get github.com/cosmos/cosmos-sdk +``` + +If the dependencies have been updated with breaking changes, or if +another branch is required, `dep` is used for dependency management. +Thus, assuming you've already run `go get` or otherwise cloned the repo, +the correct way to install is: + +``` +cd $GOPATH/src/github.com/cosmos/cosmos-sdk +make get_tools +make get_vendor_deps +make install +make install_examples +``` + +This will install `gaiad` and `gaiacli` and four example binaries: +`basecoind`, `basecli`, `democoind`, and `democli`. + +Verify that everything is OK by running: + +``` +gaiad version +``` + +you should see: + +``` +0.17.3-a5a78eb +``` + +then with: + +``` +gaiacli version +``` +you should see the same version (or a later one for both). + +## Update + +Get latest code (you can also `git fetch` only the version desired), +ensure the dependencies are up to date, then recompile. + +``` +cd $GOPATH/src/github.com/cosmos/cosmos-sdk +git fetch -a origin +git checkout VERSION +make get_vendor_deps +make install +``` diff --git a/docs/sdk/overview.md b/docs/sdk/overview.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/sdk/overview/apps.md b/docs/sdk/overview/apps.md new file mode 100644 index 000000000..01210cb66 --- /dev/null +++ b/docs/sdk/overview/apps.md @@ -0,0 +1,70 @@ +# Apps in the SDK + +The SDK has multiple levels of "application": the ABCI app, the BaseApp, the BasecoinApp, and now your App. + +## ABCI App + +The basic ABCI interface allowing Tendermint to drive the applications state machine with transaction blocks. + +## BaseApp + +Implements an ABCI App using a MultiStore for persistence and a Router to handle transactions. +The goal is to provide a secure interface between the store and the extensible state machine +while defining as little about that state machine as possible (staying true to the ABCI). + +BaseApp requires stores to be mounted via capabilities keys - handlers can only access +stores they're given the key for. The BaseApp ensures all stores are properly loaded, cached, and committed. +One mounted store is considered the "main" - it holds the latest block header, from which we can find and load the +most recent state ([TODO](https://github.com/cosmos/cosmos-sdk/issues/522)). + +BaseApp distinguishes between two handler types - the `AnteHandler` and the `MsgHandler`. +The former is a global validity check (checking nonces, sigs and sufficient balances to pay fees, +e.g. things that apply to all transaction from all modules), the later is the full state transition function. +During CheckTx the state transition function is only applied to the checkTxState and should return +before any expensive state transitions are run (this is up to each developer). It also needs to return the estimated +gas cost. +During DeliverTx the state transition function is applied to the blockchain state and the transactions +need to be fully executed. + +BaseApp is responsible for managing the context passed into handlers - +it makes the block header available and provides the right stores for CheckTx and DeliverTx. + +BaseApp is completely agnostic to serialization formats. + +## Basecoin + +Basecoin is the first complete application in the stack. +Complete applications require extensions to the core modules of the SDK to actually implement handler functionality. +The native extensions of the SDK, useful for building Cosmos Zones, live under `x`. +Basecoin implements a `BaseApp` state machine using the `x/auth` and `x/bank` extensions, +which define how transaction signers are authenticated and how coins are transferred. +It should also use `x/ibc` and probably a simple staking extension. + +Basecoin and the native `x` extensions use go-amino for all serialization needs, +including for transactions and accounts. + +## Your Cosmos App + +Your Cosmos App is a fork of Basecoin - copy the `examples/basecoin` directory and modify it to your needs. +You might want to: + +- add fields to accounts +- copy and modify handlers +- add new handlers for new transaction types +- add new stores for better isolation across handlers + +The Cosmos Hub takes Basecoin and adds more stores and extensions to handle additional +transaction types and logic, like the advanced staking logic and the governance process. + +## Ethermint + +Ethermint is a new implementation of `BaseApp` that does not depend on Basecoin. +Instead of `cosmos-sdk/x/` it has its own `ethermint/x` based on `go-ethereum`. + +Ethermint uses a Patricia store for its accounts, and an IAVL store for IBC. +It has `x/ante`, which is quite similar to Basecoin's but uses RLP instead of go-amino. +Instead of `x/bank`, it has `x/eth`, which defines the single Ethereum transaction type +and all the semantics of the Ethereum state machine. + +Within `x/eth`, transactions sent to particular addresses can be handled in unique ways, +for instance to handle IBC and staking. diff --git a/docs/sdk/overview/capabilities.md b/docs/sdk/overview/capabilities.md new file mode 100644 index 000000000..ded5928a9 --- /dev/null +++ b/docs/sdk/overview/capabilities.md @@ -0,0 +1,118 @@ +Overview +======== + +The SDK design optimizes flexibility and security. The framework is +designed around a modular execution stack which allows applications to +mix and match elements as desired. In addition, all modules are +sandboxed for greater application security. + +Framework Overview +------------------ + +### Object-Capability Model + +When thinking about security, it's good to start with a specific threat +model. Our threat model is the following: + + We assume that a thriving ecosystem of Cosmos-SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules. + +The Cosmos-SDK is designed to address this threat by being the +foundation of an object capability system. + + The structural properties of object capability systems favor + modularity in code design and ensure reliable encapsulation in + code implementation. + + These structural properties facilitate the analysis of some + security properties of an object-capability program or operating + system. Some of these — in particular, information flow properties + — can be analyzed at the level of object references and + connectivity, independent of any knowledge or analysis of the code + that determines the behavior of the objects. As a consequence, + these security properties can be established and maintained in the + presence of new objects that contain unknown and possibly + malicious code. + + These structural properties stem from the two rules governing + access to existing objects: + + 1) An object A can send a message to B only if object A holds a + reference to B. + + 2) An object A can obtain a reference to C only + if object A receives a message containing a reference to C. As a + consequence of these two rules, an object can obtain a reference + to another object only through a preexisting chain of references. + In short, "Only connectivity begets connectivity." + +See the [wikipedia +article](https://en.wikipedia.org/wiki/Object-capability_model) for more +information. + +Strictly speaking, Golang does not implement object capabilities +completely, because of several issues: + +- pervasive ability to import primitive modules (e.g. "unsafe", "os") +- pervasive ability to override module vars + +- data-race vulnerability where 2+ goroutines can create illegal + interface values + +The first is easy to catch by auditing imports and using a proper +dependency version control system like Dep. The second and third are +unfortunate but it can be audited with some cost. + +Perhaps [Go2 will implement the object capability +model](https://github.com/golang/go/issues/23157). + +#### What does it look like? + +Only reveal what is necessary to get the work done. + +For example, the following code snippet violates the object capabilities +principle: + + type AppAccount struct {...} + var account := &AppAccount{ + Address: pub.Address(), + Coins: sdk.Coins{{"ATM", 100}}, + } + var sumValue := externalModule.ComputeSumValue(account) + +The method "ComputeSumValue" implies a pure function, yet the implied +capability of accepting a pointer value is the capability to modify that +value. The preferred method signature should take a copy instead. + + var sumValue := externalModule.ComputeSumValue(*account) + +In the Cosmos SDK, you can see the application of this principle in the +basecoin examples folder. + + // File: cosmos-sdk/examples/basecoin/app/init_handlers.go + package app + + import ( + "github.com/cosmos/cosmos-sdk/x/bank" + "github.com/cosmos/cosmos-sdk/x/sketchy" + ) + + func (app *BasecoinApp) initRouterHandlers() { + + // All handlers must be added here. + // The order matters. + app.router.AddRoute("bank", bank.NewHandler(app.accountMapper)) + app.router.AddRoute("sketchy", sketchy.NewHandler()) + } + +In the Basecoin example, the sketchy handler isn't provided an account +mapper, which does provide the bank handler with the capability (in +conjunction with the context of a transaction run). + +### Capabilities systems + +TODO: + +- Need for module isolation +- Capability is implied permission +- Link to thesis + diff --git a/docs/sdk/overview/overview.md b/docs/sdk/overview/overview.md new file mode 100644 index 000000000..9da8c233b --- /dev/null +++ b/docs/sdk/overview/overview.md @@ -0,0 +1,34 @@ +# Overview + +The Cosmos-SDK is a framework for building Tendermint ABCI applications in +Golang. It is designed to allow developers to easily create custom interoperable +blockchain applications within the Cosmos Network. + +We envision the SDK as the `npm`-like framework to build secure blockchain applications on top of Tendermint. + +To achieve its goals of flexibility and security, the SDK makes extensive use of +the [object-capability +model](https://en.wikipedia.org/wiki/Object-capability_model) +and the [principle of least +privelege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). + +For an introduction to object-capabilities, see this [article](http://habitatchronicles.com/2017/05/what-are-capabilities/). + +## Languages + +The Cosmos-SDK is currently writen in [Golang](https://golang.org/), though the +framework could be implemented similarly in other languages. +Contact us for information about funding an implementation in another language. + +## Directory Structure + +The SDK is laid out in the following directories: + +- `baseapp`: Defines the template for a basic [ABCI](https://cosmos.network/whitepaper#abci) application so that your Cosmos-SDK application can communicate with the underlying Tendermint node. +- `client`: CLI and REST server tooling for interacting with SDK application. +- `examples`: Examples of how to build working standalone applications. +- `server`: The full node server for running an SDK application on top of + Tendermint. +- `store`: The database of the SDK - a Merkle multistore supporting multiple types of underling Merkle key-value stores. +- `types`: Common types in SDK applications. +- `x`: Extensions to the core, where all messages and handlers are defined. diff --git a/docs/spec/README.md b/docs/spec/README.md index 4b58baf9e..1b9f52385 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -6,7 +6,7 @@ the Cosmos Hub. NOTE: the specifications are not yet complete and very much a work in progress. - [Store](store) - The core Merkle store that holds the state. -- [Auth](auth) - The structure and authnentication of accounts and transactions. +- [Auth](auth) - The structure and authentication of accounts and transactions. - [Bank](bank) - Sending tokens. - [Governance](governance) - Proposals and voting. - [IBC](ibc) - Inter-Blockchain Communication (IBC) protocol.