Skip to content

Commit

Permalink
[Docs] Add a debugging tip: using transaction hashes (#786)
Browse files Browse the repository at this point in the history
## Summary

Added a debugging tip to the documentation on using transaction hashes
to get more details when a transaction does not seem to have taken
effect, e.g. when staking a new service returns a transaction (TX) hash
but the service does not appear after a few blocks.

## Issue

Debugging the process of adding a new service can be simplified using
the debugging tip being added in this PR.

## Type of change

Select one or more:

- [ ] New feature, functionality or library
- [ ] Bug fix
- [ ] Code health or cleanup
- [x] Documentation
- [ ] Other (specify)

## Testing

- [x] **Documentation**: `make docusaurus_start`; only needed if you
make doc changes

## Sanity Checklist

- [ ] I have tested my changes using the available tooling
- [ ] I have commented my code
- [ ] I have performed a self-review of my own code; both comments &
source code
- [ ] I create and reference any new tickets, if applicable
- [ ] I have left TODOs throughout the codebase, if applicable

---------

Co-authored-by: Daniel Olshansky <olshansky.daniel@gmail.com>
  • Loading branch information
adshmh and Olshansk authored Sep 11, 2024
1 parent 88a9197 commit ecf74ce
Showing 1 changed file with 77 additions and 1 deletion.
78 changes: 77 additions & 1 deletion docusaurus/docs/develop/developer_guide/debug_tips.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ If you have a tip you'd like to share with others, please open a PR to add it he
- [`itest` Example](#itest-example)
- [TODO: pprof](#todo-pprof)
- [TODO: dlv](#todo-dlv)

- [`poktrolld query tx` - Investigating Failed Transactions](#poktrolld-query-tx---investigating-failed-transactions)
- [`poktrolld query tx` Example](#poktrolld-query-tx-example)

## `itest` - Investigating Flaky Tests

We developed a tool called `itest` to help with debugging flaky tests. It runs
Expand All @@ -39,6 +41,80 @@ test in the `pkg/client/tx` 50 times in total (5 consecutive tests over 10 runs)
make itest 5 10 ./pkg/client/tx/... -- -run TxClient_SignAndBroadcast_Succeeds
```

## `poktrolld query tx` - Investigating Failed Transactions

_tl;dr Submitted Transaction != Committed Transaction_

After a transaction (e.g. staking a new service) is successfully sent to an RPC node, we have to wait
until the next block, when a proposer will try to commit to the network's state, to see if its valid.
If the transaction's (TX) state transition is invalid, it will not be committed.

In other words, receiving a transaction (TX) hash from the `poktrolld` CLI doesn't mean it was committed.
However, the transaction (TX) hash can be used to investigate the failed transaction.

### `poktrolld query tx` Example

The following is an example of `poktrolld query tx` in action to investigate a failed transaction.
In this example, the command to add a new service is executed as follows, returning the TX hash shown.
However, the service does not appear in the list of services when querying the full node.

```bash
poktrolld tx service add-service "svc1" "service1" 1 --from $SUPPLIER_ADDRESS --chain-id=poktroll
```

The TX hash is returned by the above command:

```bash
txhash: 9E4CA2B72FCD6F74C771A5B2289CEACED30C2717ABEA4330E12543D3714D322B
```

To investigate this issue, the following command is used to get the details of the transaction:

```bash
poktrolld query tx \
--type=hash 9E4CA2B72FCD6F74C771A5B2289CEACED30C2717ABEA4330E12543D3714D322B \
--node https://shannon-testnet-grove-seed-rpc.poktroll.com
```

Which shows the following log entry:

```bash
info: ""
logs: []
raw_log: 'failed to execute message; message index: 0: account has 100000 uPOKT, but
the service fee is 1000000000 uPOKT: not enough funds to add service'
```

The output above shows the cause of the transaction failure: `insufficient funds`. Fixing this by adding
more funds to the corresponding supplier account will allow the transaction to result in the expected
state transition.

:::note

If you are reading this and the `9E4CA...` hash is no longer valid, we may have done a re-genesis of
TestNet at this point. Please consider updating with a new one!

:::

:::tip

`poktrolld query tx` supports an `--output` flag which can have the values text or json. This can be useful for programatic querying or in combination with tools like `jq`, e.g.:

```bash
poktrolld query tx \
--type=hash 9E4CA2B72FCD6F74C771A5B2289CEACED30C2717ABEA4330E12543D3714D322B \
--node https://shannon-testnet-grove-seed-rpc.poktroll.com \
--output json | jq .raw_log
```

The above command will produce the following output:

```bash
"failed to execute message; message index: 0: account has 100000 uPOKT, but the service fee is 1000000000 uPOKT: not enough funds to add service"
```

:::

### TODO: pprof

### TODO: dlv

0 comments on commit ecf74ce

Please sign in to comment.