# Legacy Amino JSON REST

The irishub versions v1.0.0 (depends on Cosmos-SDK v0.41) and earlier provided REST endpoints to query the state and broadcast transactions. These endpoints are kept in irishub v1.0, but they are marked as deprecated, and will be removed after a few versions therefore call these endpoints legacy REST endpoints.

Some important information concerning all legacy REST endpoints:

• Most of these endpoints are backwards-comptatible. All breaking changes are described in the next section.
• In particular, these endpoints still output Amino JSON. Cosmos-SDK v0.41 introduced Protobuf as the default encoding library throughout the codebase, but legacy REST endpoints are one of the few places where the encoding is hardcoded to Amino.

# API Port, Activation and Configuration

All routes are configured under the following fields in ~/.iris/config/app.toml:

• api.enable = true|false field defines if the REST server should be enabled. Defaults to true.
• api.address = {string} field defines the address (really, the port, since the host should be kept at 0.0.0.0) the server should bind to. Defaults to tcp://0.0.0.0:1317.
• some additional API configuration options are defined in ~/.iris/config/app.toml, along with comments, please refer to that file directly.

# Legacy REST API Routes

The REST routes present in Irishub v0.16 and earlier are marked as deprecated via a HTTP deprecation header. They are still maintained to keep backwards compatibility, but will be removed after a few versions.

For application developers, Legacy REST API routes needs to be wired up to the REST server, this is done by calling the RegisterRESTRoutes function on the ModuleManager.

# Legacy REST Endpoint

# Breaking Changes in Legacy REST Endpoints (Contrast with Cosmos-SDK v0.39 and earlier versions)

¹: Transactions that don't support Amino serialization are the ones that contain one or more Msgs that are not registered with the Amino codec. Currently in the IRIShub, only IBC Msgs fall into this case.

# Migrating to New REST Endpoints (from Cosmos-SDK v0.39)

IRIShub API Endpoints

Tendermint API Endpoints

# Breaking changes in High Priority Endpoints for Queries

Here are the High Priority Endpoints for Queries

• Staking
  • Validators
  • Delegators
• Bank
  • Balances
• Gov
• Auth
• Distributions

# Bank

Endpoint Name: QueryBalance

• Endpoint Path: /bank/balances/{address}
• What Changed:
  • No Changes observed.
  • See coin cross-chain transfer source tracing for details on how on non-native IBC coins will written into the denom value. This will include a hash of source trace for each coin. The core decision if the hash should replace the denom or be prepended to the denom.

# Validators

Endpoint Name: QueryValidators

• Endpoint Path: /staking/validators

• What Changed:

  • The fields unbonding_height and jailed are no longer supported
  • The fields in description are now omit if empty. Rather than returning fields with empty strings. We now don't return the field if the validator has chosen not to configure it. For instance at launch, no validator will have a security contact filled out and the field will only appear once they do.

• Sample JSON:

  {
      "commission": {
          "commission_rates": {
              "max_change_rate": "0.000000000000000000",
              "max_rate": "0.000000000000000000",
              "rate": "0.000000000000000000"
          },
          "update_time": "1970-01-01T00:00:00Z"
      },
      "consensus_pubkey": "cosmosvalconspub1zcjduepqwuxd2yevzmsrmrjx2su8kdlk44eqfdzeqx27zejuen6m0nkcpzps0qavpw",
      "delegator_shares": "0.000000000000000000",
      "description": {
          "details": "security",
          "identity": "identity",
          "moniker": "moniker",
          "security_contact": "details",
          "website": "website"
      },
      "min_self_delegation": "1",
      "operator_address": "cosmosvaloper1pcpl7xhxq0wm72e9ljls2sxr5h3vqwytnq44sr",
      "status": 1,
      "tokens": "0",
      "unbonding_time": "1970-01-01T00:00:00Z"
  }
  

# Delegators

Endpoint Name: QueryDelegatorDelegations

• Endpoint Path: /staking/delegators/delegations

• What Changed:

  • balance now is no longer a number. It is a field with two values: amount and Denom
  • delegator_address is no longer a string. It’s a field called delegation with three values: delegator_address", "shares", "validator_address
  • The old field validator_address is no longer used. Two new fields validator_dst_address and validator_src_address replace this in the new redelegation field.

• Sample JSON:

  {
      "balance": {
          "amount": "5",
          "denom": "stake"
      },
      "delegation": {
          "delegator_address": "cosmos1n2k9ygw2ws9sg86mrx84pdcre5geqd5ugt44h0",
          "shares": "5.000000000000000000",
          "validator_address": "cosmosvaloper155998a4hv5kqvuxr9jryjxrtnlydvqu8c0cy03"
      }
  }
  

Endpoint Name: QueryRedelegations

• Endpoint Path: /staking/redelegations

• What Changed: The following old fields are now sub fields of a new field called redelegation_entry:

  • completion_time
  • initial_balance
  • shares_dst

• The old field creation_height is no longer supported.

• The following are new fields:

  • redelegation which holds the sub-fields.
    • delegator_address (new)
    • entries (new)
    • valdiator_dst_address
    • validator_src_address

• Sample JSON:

  {
      "entries": [
          {
              "balance": "5",
              "redelegation_entry": {
                  "completion_time": "1969-12-31T16:00:00-08:00",
                  "initial_balance": "5",
                  "shares_dst": "5.000000000000000000"
              }
          },
          {
              "balance": "5",
              "redelegation_entry": {
                  "completion_time": "1969-12-31T16:00:00-08:00",
                  "initial_balance": "5",
                  "shares_dst": "5.000000000000000000"
              }
          }
      ],
      "redelegation": {
          "delegator_address": "cosmos104yggz5x4ype50c59vu84ze2w36pc3swm2u698",
          "entries": null,
          "validator_dst_address": "cosmosvaloper1td8yl7g5662m0mpptaxjmcn9jtzvl0wgulvv23",
          "validator_src_address": "cosmosvaloper1gqv70e79a8q0yz5s5qhsjhdl2c79496faer0vz"
      }
  }
  

Endpoint Name: QueryUnbondingDelegation

• Endpoint Path: /staking/unbondingDelegation
• What Changed:
  • The old field creation_height is no longer supported

# Distributions

Endpoint Name: getQueriedValidatorOutstandingRewards

• Endpoint Path: /distribution/validators/{validatorAddr}/outstanding_rewards

• What Changed:

  • The new field rewards is the new root level field for the output

• Sample JSON:

  {
      "rewards": [
          {
              "denom": "mytoken",
              "amount": "3.000000000000000000"
          },
          {
              "denom": "myothertoken",
              "amount": "0.000000300000000000"
          }
      ]
  }
  

Endpoint Name: getQueriedValidatorCommission

• Endpoint Path: /distribution/validators/{validatorAddr}

• What Changed:

  • The new field commission is the new root level field for the output

• Sample JSON:

  {
      "commission": [
          {
              "denom": "token1",
              "amount": "4.000000000000000000"
          },
          {
              "denom": "token2",
              "amount": "2.000000000000000000"
          }
      ]
  }
  

Endpoint Name: getQueriedValidatorSlashes

• Endpoint Path: /distribution/validators/{validatorAddr}

• What Changed: No change

• Endpoint Name: getQueriedDelegationRewards

• Endpoint Path: /distribution/delegators/{delegatorAddr}/rewards

• What Changed: No change

# Generating and Signing Transactions (Fully Backward Compatible)

The same code as integrating with irishub-v0.16.3 mainnet. The transaction structure is as follows:

{
    "type": "cosmos-sdk/StdTx",
    "value": {
        "msg": [
            {
                "type": "cosmos-sdk/MsgSend",
                "value": {
                    "from_address": "iaa1rkgdpj6fyyyu7pnhmc3v7gw9uls4mnajvzdwkt",
                    "to_address": "iaa1q6t5439f0rkvkzl38m0f43e0kpv3mx7x2shlq8",
                    "amount": [
                        {
                            "denom": "uiris",
                            "amount": "1000000"
                        }
                    ]
                }
            }
        ],
        "fee": {
            "amount": [
                {
                    "denom": "uiris",
                    "amount": "30000"
                }
            ],
            "gas": "200000"
        },
        "signatures": null,
        "memo": "Sent via irishub client"
    }
}

Where the IRIShub address prefix uses iaa instead, which affects the fields:

• value.msg.value.from_adress
• value.msg.value.to_address

Denom uses uiris instead (1iris = 10⁶uiris), which affects fields:

• value.msg.value.amount.denom
• value.fee.amount.denom

# Broadcasting a transaction (Fully Backward Compatible)

The same code as integrating with irishub mainnet, call POST /txs to send a transaction, as the example below:

curl -X POST "http://localhost:1317/txs" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"tx\": {\"msg\":[{\"type\":\"cosmos-sdk/MsgSend\",\"value\":{\"from_address\":\"iaa1rkgdpj6fyyyu7pnhmc3v7gw9uls4mnajvzdwkt\",\"to_address\":\"iaa1q6t5439f0rkvkzl38m0f43e0kpv3mx7x2shlq8\",\"amount\":[{\"denom\":\"uiris\",\"amount\":\"1000000\"}]}}],\"fee\":{\"amount\":[{\"denom\":\"uiris\",\"amount\":\"30000\"}],\"gas\":\"200000\"},\"signatures\":[{\"pub_key\":{\"type\":\"tendermint/PubKeySecp256k1\",\"value\":\"AxGagdsRTKni/h1+vCFzTpNltwoiU7SwIR2dg6Jl5a//\"},\"signature\":\"Pu8yiRVO8oB2YDDHyB047dXNArbVImasmKBrm8Kr+6B08y8QQ7YG1eVgHi5OIYYclccCf3Ju/BQ78qsMWMniNQ==\"}],\"memo\":\"Sent via irishub client\"}, \"mode\": \"block\"}"

# Breaking Changes in Querying Transactions

# Tx

• Endpoint Name: QueryTx

• Endpoint Path: GET /txs&&GET /txs/{hash}

• What Changed:

  • Tags are no longer used; use the events field instead
  • The result field is no longer used, and the field in the original result is moved to the first level
  • The coin_flow field is no longer used

• Sample JSON:

  {
      "height": "5",
      "txhash": "E663768B616B1ACD2912E47C36FEBC7DB0E0974D6DB3823D4C656E0EAB8C679D",
      "data": "0A060A0473656E64",
      "raw_log": "[{\"events\":[{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"send\"},{\"key\":\"sender\",\"value\":\"iaa18awn3k70u05tlcul8w2qnl64g002uj4kjn93rn\"},{\"key\":\"module\",\"value\":\"bank\"}]},{\"type\":\"transfer\",\"attributes\":[{\"key\":\"recipient\",\"value\":\"iaa1w976a5jrhsj06dqmrh2x9qxzel74qtcmapklxc\"},{\"key\":\"sender\",\"value\":\"iaa18awn3k70u05tlcul8w2qnl64g002uj4kjn93rn\"},{\"key\":\"amount\",\"value\":\"1000000uiris\"}]}]}]",
      "logs": [
          {
              "events": [
                  {
                      "type": "message",
                      "attributes": [
                          {
                              "key": "action",
                              "value": "send"
                          },
                          {
                              "key": "sender",
                              "value": "iaa18awn3k70u05tlcul8w2qnl64g002uj4kjn93rn"
                          },
                          {
                              "key": "module",
                              "value": "bank"
                          }
                      ]
                  },
                  {
                      "type": "transfer",
                      "attributes": [
                          {
                              "key": "recipient",
                              "value": "iaa1w976a5jrhsj06dqmrh2x9qxzel74qtcmapklxc"
                          },
                          {
                              "key": "sender",
                              "value": "iaa18awn3k70u05tlcul8w2qnl64g002uj4kjn93rn"
                          },
                          {
                              "key": "amount",
                              "value": "1000000uiris"
                          }
                      ]
                  }
              ]
          }
      ],
      "gas_wanted": "200000",
      "gas_used": "69256",
      "tx": {
          "type": "cosmos-sdk/StdTx",
          "value": {
              "msg": [
                  {
                      "type": "cosmos-sdk/MsgSend",
                      "value": {
                          "from_address": "iaa18awn3k70u05tlcul8w2qnl64g002uj4kjn93rn",
                          "to_address": "iaa1w976a5jrhsj06dqmrh2x9qxzel74qtcmapklxc",
                          "amount": [
                              {
                                  "denom": "uiris",
                                  "amount": "1000000"
                              }
                          ]
                      }
                  }
              ],
              "fee": {
                  "amount": [
                      {
                          "denom": "uiris",
                          "amount": "30000"
                      }
                  ],
                  "gas": "200000"
              },
              "signatures": [],
              "memo": "",
              "timeout_height": "0"
          }
      },
      "timestamp": "2021-01-18T07:29:21Z"
  }