certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
cosmos-sdk/docs/light/api.md

20 KiB
Raw Blame History

Cosmos Hub (Gaia-Lite) LCD API

This document describes the API that is exposed by the specific Light Client Daemon (LCD) implementation of the Cosmos Hub (Gaia). Those APIs are exposed by a REST server and can easily be accessed over HTTP/WS (websocket) connections.

The complete API is comprised of the sub-APIs of different modules. The modules in the Cosmos Hub (Gaia-Lite) API are:

Error messages my change and should be only used for display purposes. Error messages should not be used for determining the error type.

ICS0 - TendermintAPI

Exposes the same functionality as the Tendermint RPC from a full node. It aims to have a very similar API.

POST /txs

  • URL: /txs
  • Query Parameters:
    • ?return={sync|async|block}:
      • return=sync: Waits for the transaction to pass CheckTx
      • return=async: Returns the request immediately after it is received by the server
      • return=block: waits for for the transaction to be committed in a block
  • POST Body:
{
  "transaction": "string",
  "return": "string",
}
  • Returns on success:
{
    "rest api":"2.0",
    "code":200,
    "error":"",
    "result":{
	"code":0,
	"hash":"0D33F2F03A5234F38706E43004489E061AC40A2E",
	"data":"",
	"log":""
    }
}

ICS1 - KeyAPI

This API exposes all functionality needed for key creation, signing and management.

GET /keys

  • URL: /keys
  • Functionality: Gets a list of all the keys.
  • Returns on success:
{
    "rest api":"1.0",
    "code":200,
    "error":"",
    "result":{
        "account":[
           {
                "name":"monkey",
                "address":"cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
                "pub_key":"cosmospub1zcjduc3q8s8ha96ry4xc5xvjp9tr9w9p0e5lk5y0rpjs5epsfxs4wmf72x3shvus0t"
            },
            {
                "name":"test",
                "address":"cosmos1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
                "pub_key":"cosmospub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
            }
        ],
        "block_height":5241
    }
}

POST /keys

  • URL: /keys
  • Functionality: Create a new key.
  • POST Body:
{
  "name": "string",
  "password": "string",
  "seed": "string",
}

Returns on success:

{
    "rest api":"1.0",
    "code":200,
    "error":"",
    "result":{
        "seed":"crime carpet recycle erase simple prepare moral dentist fee cause pitch trigger when velvet animal abandon"
    }
}

GET /keys/{name}

  • URL : /keys/{name}
  • Functionality: Get the information for the specified key.
  • Returns on success:
{
    "rest api":"1.0",
    "code":200,
    "error":"",
    "result":{
        "name":"test",
            "address":"cosmos1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
            "pub_key":"cosmospub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
    }
}

PUT /keys/{name}

  • URL : /keys/{name}
  • Functionality: Change the encryption password for the specified key.
  • PUT Body:
{
  "old_password": "string",
  "new_password": "string",
}
  • Returns on success:
{
    "rest api":"2.0",
    "code":200,
    "error":"",
    "result":{}
}

DELETE /keys/{name}

  • URL: /keys/{name}
  • Functionality: Delete the specified key.
  • DELETE Body:
{
  "password": "string",
}
  • Returns on success:
{
    "rest api":"1.0",
    "code":200,
    "error":"",
    "result":{}
}

POST /keys/{name}/recover

  • URL: /keys/{name}/recover
  • Functionality: Recover your key from seed and persist it encrypted with the password.
  • POST Body:
{
  "password": "string",
  "seed": "string",
}
  • Returns on success:
{
    "rest api":"1.0",
    "code":200,
    "error":"",
    "result":{
        "address":"BD607C37147656A507A5A521AA9446EB72B2C907"
    }
}

GET /auth/accounts/{address}

  • URL: /auth/accounts/{address}
  • Functionality: Query the information of an account .
  • Returns on success:
{
    "rest api":"1.0",
    "code":200,
    "error":"",
    "result":{
        "address": "82A57F8575BDFA22F5164C75361A21D2B0E11089",
        "public_key": "PubKeyEd25519{A0EEEED3C9CE1A6988DEBFE347635834A1C0EBA0B4BB1125896A7072D22E650D}",
        "coins": [
            {"atom": 300},
            {"photon": 15}
        ],
        "account_number": 1,
        "sequence": 7
    }
}

POST /auth/tx/sign

  • URL: /auth/tx/sign
  • Functionality: Sign a transaction without broadcasting it.
  • Returns on success:
{
    "rest api": "1.0",
    "code": 200,
    "error": "",
    "result": {
        "type": "auth/StdTx",
        "value": {
            "msg": [
                {
                    "type": "cosmos-sdk/Send",
                    "value": {
                        "inputs": [
                            {
                                "address": "cosmos1ql4ekxkujf3xllk8h5ldhhgh4ylpu7kwec6q3d",
                                "coins": [
                                    {
                                        "denom": "steak",
                                        "amount": "1"
                                    }
                                ]
                            }
                        ],
                        "outputs": [
                            {
                                "address": "cosmos1dhyqhg4px33ed3erqymls0hc7q2lxw9hhfwklj",
                                "coins": [
                                    {
                                        "denom": "steak",
                                        "amount": "1"
                                    }
                                ]
                            }
                        ]
                    }
                }
            ],
            "fee": {
                "amount": [
                    {
                        "denom": "",
                        "amount": "0"
                    }
                ],
                "gas": "2742"
            },
            "signatures": [
                {
                    "pub_key": {
                        "type": "tendermint/PubKeySecp256k1",
                        "value": "A2A/f2IYnrPUMTMqhwN81oas9jurtfcsvxdeLlNw3gGy"
                    },
                    "signature": "MEQCIGVn73y9QLwBa3vmsAD1bs3ygX75Wo+lAFSAUDs431ZPAiBWAf2amyqTCDXE9J87rL9QF9sd5JvVMt7goGSuamPJwg==",
                    "account_number": "1",
                    "sequence": "0"
                }
            ],
            "memo": ""
        }
    }
}

POST /auth/tx/broadcast

  • URL: /auth/broadcast
  • Functionality: Broadcast a transaction.
  • Returns on success:
{
    "rest api": "1.0",
    "code": 200,
    "error": "",
    "result":
    {
        "check_tx": {
            "log": "Msg 0: ",
            "gasWanted": "2742",
            "gasUsed": "1002"
        },
        "deliver_tx": {
            "log": "Msg 0: ",
            "gasWanted": "2742",
            "gasUsed": "2742",
            "tags": [
                {
                    "key": "c2VuZGVy",
                    "value": "Y29zbW9zMXdjNTl6ZXU3MmNjdnp5ZWR6ZGE1N3pzcXh2eXZ2Y3poaHBhdDI4"
                },
                {
                    "key": "cmVjaXBpZW50",
                    "value": "Y29zbW9zMTJ4OTNmY3V2azg3M3o1ejZnejRlNTl2dnlxcXp1eDdzdDcwNWd5"
                }
            ]
        },
        "hash": "784314784503582AC885BD6FB0D2A5B79FF703A7",
        "height": "5"
    }
}

ICS20 - TokenAPI

The TokenAPI exposes all functionality needed to query account balances and send transactions.

GET /bank/balance/{account}

  • URL: /bank/balance/{account}
  • Functionality: Query the specified account's balance.
  • Returns on success:
{
    "rest api":"2.0",
    "code":200,
    "error":"",
    "result": {
        "atom":1000,
        "photon":500,
        "ether":20
    }
}

POST /bank/transfers

  • URL: /bank/transfers
  • Functionality: Create a transfer in the bank module.
  • POST Body:
{
  "amount": [
    {
      "denom": "string",
      "amount": 64,
    }
  ],
  "name": "string",
  "password": "string",
  "chain_id": "string",
  "account_number": 64,
  "sequence": 64,
  "gas": 64,
}
  • Returns on success:
{
    "rest api":"2.0",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO:<JSON sign bytes for the transaction>"
    }
}

ICS21 - StakingAPI

The StakingAPI exposes all functionality needed for validation and delegation in Proof-of-Stake.

GET /stake/delegators/{delegatorAddr}

  • URL: /stake/delegators/{delegatorAddr}
  • Functionality: Get all delegations (delegation, undelegation) from a delegator.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result": {
        "atom":1000,
        "photon":500,
        "ether":20
    }
}

GET /stake/delegators/{delegatorAddr}/validators

  • URL: /stake/delegators/{delegatorAddr}/validators
  • Functionality: Query all validators that a delegator is bonded to.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{}
}

GET /stake/delegators/{delegatorAddr}/validators/{validatorAddr}

  • URL: /stake/delegators/{delegatorAddr}/validators/{validatorAddr}
  • Functionality: Query a validator that a delegator is bonded to
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{}
}

GET /stake/delegators/{delegatorAddr}/txs

  • URL: /stake/delegators/{delegatorAddr}/txs
  • Functionality: Get all staking txs (i.e msgs) from a delegator.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

POST /stake/delegators/{delegatorAddr}/delegations

  • URL: /stake/delegators/{delegatorAddr}/delegations
  • Functionality: Submit or edit a delegation.
  • POST Body:
{
  "name": "string",
  "password": "string",
  "chain_id": "string",
  "account_number": 64,
  "sequence": 64,
  "gas": 64,
  "delegations": [
    {
      "delegator_addr": "string",
      "validator_addr": "string",
      "delegation": {
        "denom": "string",
        "amount": 1234
      }
    }
  ],
  "begin_unbondings": [
    {
      "delegator_addr": "string",
      "validator_addr": "string",
      "shares": "string",
    }
  ],
  "complete_unbondings": [
    {
      "delegator_addr": "string",
      "validator_addr": "string",
    }
  ],
  "begin_redelegates": [
    {
      "delegator_addr": "string",
      "validator_src_addr": "string",
      "validator_dst_addr": "string",
      "shares": "string",
    }
  ],
  "complete_redelegates": [
    {
      "delegator_addr": "string",
      "validator_src_addr": "string",
      "validator_dst_addr": "string",
    }
  ]
}
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

GET /stake/delegators/{delegatorAddr}/delegations/{validatorAddr}

  • URL: /stake/delegators/{delegatorAddr}/delegations/{validatorAddr}
  • Functionality: Query the current delegation status between a delegator and a validator.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

GET /stake/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}

  • URL: /stake/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}
  • Functionality: Query all unbonding delegations between a delegator and a validator.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

GET /stake/validators

  • URL: /stake/validators
  • Functionality: Get all validator candidates.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

GET /stake/validators/{validatorAddr}

  • URL: /stake/validators/{validatorAddr}
  • Functionality: Query the information from a single validator.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

GET /stake/parameters

  • URL: /stake/parameters
  • Functionality: Get the current value of staking parameters.
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
      "inflation_rate_change": 1300000000,
      "inflation_max": 2000000000,
      "inflation_min": 700000000,
      "goal_bonded": 6700000000,
      "unbonding_time": "72h0m0s",
      "max_validators": 100,
      "bond_denom": "atom"
    }
}

GET /stake/pool

  • URL: /stake/pool
  • Functionality: Get the current value of the dynamic parameters of the current state (i.e Pool).
  • Returns on success:
{
    "rest api":"2.1",
    "code":200,
    "error":"",
    "result":{
      "loose_tokens": 0,
      "bonded_tokens": 0,
      "inflation_last_time": "1970-01-01 01:00:00 +0100 CET",
      "inflation": 700000000,
      "date_last_commission_reset": 0,
      "prev_bonded_shares": 0,
    }
}

ICS22 - GovernanceAPI

The GovernanceAPI exposes all functionality needed for casting votes on plain text, software upgrades and parameter change proposals.

GET /gov/proposals

  • URL: /gov/proposals
  • Functionality: Query all submited proposals
  • Response on Success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
     "proposals":[
         "TODO"
      ]
    }
}

POST /gov/proposals

  • URL: /gov/proposals
  • Functionality: Submit a proposal
  • POST Body:
{
    "base_req": {
        // Name of key to use
    	"name": "string",
    	// Password for that key
    	"password": "string",
    	"chain_id": "string",
    	"account_number": 64,
    	"sequence": 64,
    	"gas": 64
    },
  	// Title of the proposal
  	"title": "string",
  	// Description of the proposal
    "description": "string",
  	// PlainTextProposal supported now. SoftwareUpgradeProposal and other types may be supported soon
  	"proposal_type": "string",
  	// A cosmos address
  	"proposer": "string",
  	"initial_deposit": [
        {
            "denom": "string",
            "amount": 64,
      	}
  	]
}
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
      "TODO": "TODO",
    }
}

GET /gov/proposals/{proposal-id}

  • URL: /gov/proposals/{proposal-id}
  • Functionality: Query a proposal
  • Response on Success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
        "proposal_id": 1,
        "title": "Example title",
        "description": "a larger description with the details of the proposal",
        "proposal_type": "Text",
        "proposal_status": "DepositPeriod",
        "tally_result": {
            "yes": 0,
            "abstain": 0,
            "no": 0,
            "no_with_veto": 0
        },
        "submit_block": 5238512,
        "total_deposit": {"atom": 50},
    	"voting_start_block": -1
    }
}

POST /gov/proposals/{proposal-id}/deposits

  • URL: /gov/proposals/{proposal-id}/deposits
  • Functionality: Submit or rise a deposit to a proposal in order to make it active
  • POST Body:
{
    "base_req": {
    	"name": "string",
    	"password": "string",
    	"chain_id": "string",
        "account_number": 0,
    	"sequence": 0,
    	"gas": "simulate"
  },
  "depositer": "string",
  "amount": 0,
}
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
      "TODO": "TODO",
    }
}

GET /gov/proposals/{proposal-id}/deposits/{address}

  • URL: /gov/proposals/{proposal-id}/deposits/{address}
  • Functionality: Query a validator's deposit to submit a proposal
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
        "amount": {"atom": 150},
        "depositer": "cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
        "proposal-id": 16
    }
}

GET /gov/proposals/{proposal-id}/tally

  • URL: /gov/proposals/{proposal-id}/tally
  • Functionality: Get the tally of a given proposal.
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result": {
        "yes": 0,
        "abstain": 0,
        "no": 0,
        "no_with_veto": 0
    }
}

GET /gov/proposals/{proposal-id}/votes

  • URL: /gov/proposals/{proposal-id}/votes
  • Functionality: Query all votes from a specific proposal
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result": [
        {
            "proposal-id": 1,
        	"voter": "cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
        	"option": "no_with_veto"
    	},
        {
            "proposal-id": 1,
        	"voter": "cosmos1849m9wncrqp6v4tkss6a3j8uzvuv0cp7f75lrq",
        	"option": "yes"
    	},
    ]
}

POST /gov/proposals/{proposal-id}/votes

  • URL: /gov/proposals/{proposal-id}/votes
  • Functionality: Vote for a specific proposal
  • POST Body:
{
	"base_req": {
    	"name": "string",
    	"password": "string",
    	"chain_id": "string",
    	"account_number": 0,
    	"sequence": 0,
    	"gas": "simulate"
  	},
    // A cosmos address
  	"voter": "string",
  	// Value of the vote option `Yes`, `No` `Abstain`, `NoWithVeto`
  	"option": "string",
}
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
      "TODO": "TODO",
    }
}

GET /gov/proposals/{proposal-id}/votes/{address}

  • URL : /gov/proposals/{proposal-id}/votes/{address}
  • Functionality: Get the current Option submited by an address
  • Returns on success:
{
    "rest api":"2.2",
    "code":200,
    "error":"",
    "result":{
        "proposal-id": 1,
        "voter": "cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
        "option": "no_with_veto"
    }
}

ICS23 - SlashingAPI

The SlashingAPI exposes all functionalities needed to slash (i.e penalize) validators and delegators in Proof-of-Stake. The penalization is a fine of the staking coin and jail time, defined by governance parameters. During the jail period, the penalized validator is "jailed".

GET /slashing/validator/{validatorAddr}/signing-info

  • URL: /slashing/validator/{validatorAddr}/signing-info
  • Functionality: Query the information from a single validator.
  • Returns on success:
{
    "rest api":"2.3",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}

POST /slashing/validators/{validatorAddr}/unjail

  • URL: /slashing/validators/{validatorAddr}/unjail
  • Functionality: Submit a message to unjail a validator after it has been penalized.
  • POST Body:
{
  // Name of key to use
  "name": "string",
  // Password for that key
  "password": "string",
  "chain_id": "string",
  "account_number": 64,
  "sequence": 64,
  "gas": 64,
}
  • Returns on success:
{
    "rest api":"2.3",
    "code":200,
    "error":"",
    "result":{
     "transaction":"TODO"
    }
}