reorg docs/sdk and move stuff from docs/guide/sdk
This commit is contained in:
Ethan Buchman
parent
5573beffa7
commit
d95cb82741
|
|
@ -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
|
||||
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
<https://github.com/golang/go/issues/23161>
|
||||
- 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
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue