tendermint staking RPCs

[onur-ozkan]

Each of the following RPC endpoints is supported for Tendermint and needs to be documented. Let me know if any specific field needs an explanation (e.g., what x, y, or z fields mean in the request or response).

• experimental::staking::delegate

Used to delegate user funds to a validator.

Example request:

{
  "userpass":"'$userpass'",
  "method":"experimental::staking::delegate",
  "mmrpc":"2.0",
  "params": {
    "coin": "ATOM",
    "staking_details": {
        "type": "Cosmos",
        "validator_address": "cosmosvaloper1c4k24jzduc365kywrsvf5ujz4ya6mwympnc4en",
        "amount": "0.777"
    }
  }
}

• experimental::staking::undelegate

Used to undelegate user funds from a validator. The undelegated amount will not be available in the user's account immediately due to an undelegation period, which can be checked using experimental::staking::query::ongoing_undelegations after undelegation.

Example request:

{
  "userpass":"'$userpass'",
  "method":"experimental::staking::undelegate",
  "mmrpc":"2.0",
  "params": {
    "coin": "ATOM",
    "staking_details": {
        "type": "Cosmos",
        "validator_address": "cosmosvaloper1c4k24jzduc365kywrsvf5ujz4ya6mwympnc4en",
        "amount": "0.777"
    }
  }
}

• experimental::staking::claim_rewards

Used to claim rewards earned from user delegations.

{
  "userpass":"'$userpass'",
  "method":"experimental::staking::claim_rewards",
  "mmrpc":"2.0",
  "params": {
    "coin": "ATOM",
    "claiming_details": {
        "type": "Cosmos",
        "validator_address": "cosmosvaloper1c4k24jzduc365kywrsvf5ujz4ya6mwympnc4en"
    }
  }
}

• experimental::staking::query::delegations

Used to retrieve information about user delegations.

Example request:

{
  "userpass":"'$userpass'",
  "method":"experimental::staking::query::delegations",
  "mmrpc":"2.0",
  "params": {
    "coin": "ATOM",
    "info_details": {
        "type": "Cosmos",
        "limit": 20,
        "page_number": 1
    }
  }
}

• experimental::staking::query::ongoing_undelegations

Used to retrieve information about user undelegations that are still pending due to the undelegation completion period.

Example request:

{
  "userpass":"'$userpass'",
  "method":"experimental::staking::query::ongoing_undelegations",
  "mmrpc":"2.0",
  "params": {
    "coin": "ATOM",
    "info_details": {
        "type": "Cosmos",
        "limit": 20,
        "page_number": 1
    }
  }
}

• experimental::staking::query::validators

Used to retrieve information about validators on the network.

Example request:

{
  "userpass":"'$userpass'",
  "method":"experimental::staking::query::validators",
  "mmrpc":"2.0",
  "params": {
    "coin": "ATOM",
    "info_details": {
        "type": "Cosmos",
        "filter_by_status": "Bonded",
        "limit": 20,
        "page_number": 1
    }
  }
}

To know more about filter_by_status, see this.

Default value for filter_by_status is "Bonded".

[smk762]

@onur-ozkan On attempting to stake IRIS, I get the following error when sending the raw trasnaction:
{ "error": "rpc:183] dispatcher_legacy:140] lp_coins:5276] tendermint_coin:3401] Tx deliver failed ExecTxResult { code: Err(11), data: b\"\", log: \"out of gas in location: WriteFlat; gasWanted: 187500, gasUsed: 188367: out of gas\", info: \"\", gas_wanted: 187500, gas_used: 188367, events: [Event { kind: \"coin_spent\", attributes: [EventAttribute { key: \"spender\", value: \"iaa1ev23fc700js5d7hvtw0785yfayaazpawn8phv4\", index: true }, EventAttribute { key: \"amount\", value: \"130539uiris\", index: true }] }, Event { kind: \"coin_received\", attributes: [EventAttribute { key: \"receiver\", value: \"iaa17xpfvakm2amg962yls6f84z3kell8c5l9mr3fv\", index: true }, EventAttribute { key: \"amount\", value: \"130539uiris\", index: true }] }, Event { kind: \"transfer\", attributes: [EventAttribute { key: \"recipient\", value: \"iaa17xpfvakm2amg962yls6f84z3kell8c5l9mr3fv\", index: true }, EventAttribute { key: \"sender\", value: \"iaa1ev23fc700js5d7hvtw0785yfayaazpawn8phv4\", index: true }, EventAttribute { key: \"amount\", value: \"130539uiris\", index: true }] }, Event { kind: \"message\", attributes: [EventAttribute { key: \"sender\", value: \"iaa1ev23fc700js5d7hvtw0785yfayaazpawn8phv4\", index: true }] }, Event { kind: \"tx\", attributes: [EventAttribute { key: \"fee\", value: \"130539uiris\", index: true }, EventAttribute { key: \"fee_payer\", value: \"iaa1ev23fc700js5d7hvtw0785yfayaazpawn8phv4\", index: true }] }, Event { kind: \"tx\", attributes: [EventAttribute { key: \"acc_seq\", value: \"iaa1ev23fc700js5d7hvtw0785yfayaazpawn8phv4/3\", index: true }] }, Event { kind: \"tx\", attributes: [EventAttribute { key: \"signature\", value: \"2ZCKnH+Hcxur+5x9Zujls29zrgZgQfZfSy2htnzXhztfd6XdE/WYruqavzsI9tElTmaeXhQP0jdBBMCKsZvsZg==\", index: true }] }], codespace: \"sdk\" }" }

I did do one successful delegation before this error though. Is there any way to do custom fee for delegations? or would a coins file update be needed?

Update:
Omer mentioned GLEECBTC/komodo-defi-framework#2282 should fix this once merged.

I've tried increasing to "gas_price": 0.8 in coins file, which also failed but now with a new error message:

{
    "error": "rpc:183] dispatcher_legacy:140] lp_coins:5276] tendermint_coin:3378] failed to decode Protobuf message: TxRaw.signatures: buffer underflow"
}

Around 30 mins later with value reduced to 0.5 as it was originally, and I was alble to send a delegation tx successfully, so this appears to be an intermittent issue. I was also able to "force-claim" a reward.

[smk762]

Using experimental::staking::delegate on tQTUM with the following format (which succeeds with Cosmos), returns an error:
Request:

{
    "userpass": "{{userpass}}",
    "method":"experimental::staking::delegate",
    "mmrpc":"2.0",
    "params": {
        "coin": "tQTUM",
        "staking_details": {
            "type": "Qtum",
            "validator_address": "qbgHcqxXYHVJZXHheGpHwLJsB5epDUtWxe",
            "amount": "8"
        }
    }
}

Response

{
    "mmrpc": "2.0",
    "error": "Error parsing request: missing field `address`",
    "error_path": "dispatcher",
    "error_trace": "dispatcher:122]",
    "error_type": "InvalidRequest",
    "error_data": "missing field `address`",
    "id": null
}

Changing validator_address to address returns an expected successful result.
@onur-ozkan ideally we should avoid this sort of inconsistency in method params. Though QTUM is not heavily used in the wallet, to maintain backwards compatibility we could accept both (but just document one). validator_address would be my choice as it is most descriptive (QTUM calls them "Super Stakers", but its the same thing).

[onur-ozkan]

Sure, that makes sense. I didn't wanted to change param names offensively but I guess we can do that as we marked these RPCs with the experimental prefix.

[smk762]

Unexpected response param value in delegations for tQTUM

{
    "mmrpc": "2.0",
    "result": {
        "staking_infos_details": {
            "type": "Qtum",
            "amount": "0",
            "staker": "qbgHcqxXYHVJZXHheGpHwLJsB5epDUtWxe",
            "am_i_staking": true,
            "is_staking_supported": true
        }
    },
    "id": null
}

This may be due to the following from QTUM docs:

Qtum treats delegated UTXOs by following these rules:

- UTXOs may only be used for staking after they mature (2000 confirmations)
- The Super Staker will set a minimum size of UTXOs to stake, defaulting to 100 QTUM. Delegated UTXOs below this amount - will be ignored.
- It is best practice (for optimum returns) to break UTXOs up into sizes of 100 to 200 QTUM each.

I only sent 8 tQTUM for delegation as my balance was < 100. Will source more and retry.

I also got an error on second attempt to delegate for QTUM:

{
    "mmrpc": "2.0",
    "error": "Already delegating to: qbgHcqxXYHVJZXHheGpHwLJsB5epDUtWxe",
    "error_path": "qtum_delegation",
    "error_trace": "qtum_delegation:236]",
    "error_type": "AlreadyDelegating",
    "error_data": "qbgHcqxXYHVJZXHheGpHwLJsB5epDUtWxe",
    "id": null
}

[smk762]

Trying to undelegate tQTUM also fails with

{
    "mmrpc": "2.0",
    "error": "Invalid payload: staking_details isn't supported for Qtum",
    "error_path": "lp_coins",
    "error_trace": "lp_coins:5160]",
    "error_type": "InvalidPayload",
    "error_data": {
        "reason": "staking_details isn't supported for Qtum"
    },
    "id": null
}

This was unexpected, because delegations returns a successful response (though with amount: 0 - see last post).

It succeed when removing the staking_details object from the request, further implying that amount is irrelevant to qtum staking. The generated transaction confirms this, as full balance was used.

I went back to remove the object from delegate, but that didnt work:

{
    "mmrpc": "2.0",
    "error": "Error parsing request: missing field `staking_details`",
    "error_path": "dispatcher",
    "error_trace": "dispatcher:122]",
    "error_type": "InvalidRequest",
    "error_data": "missing field `staking_details`",
    "id": null
}

This is a bit inconsistent. Regardless, if using the staking_details param without amount works for QTUM, but if not included for Cosmos, returns "Could not read gas_info. Error code: 6 Message: rpc error: code = Unknown desc = failed to execute message; message index: 0: invalid delegation amount: invalid request [cosmos/cosmos-sdk@v0.50.11-lsm/x/staking/keeper/msg_server.go:260] with gas used: '32440': unknown request"

I'll add notes around this in docs, but ideally we implement partial balance staking for QTUM so the amount value actually means something, and the value in delegations is accurate.