From 0c2d862e660d1213c7d8fa20f831ced8b411117b Mon Sep 17 00:00:00 2001 From: Willian Mitsuda Date: Sat, 15 Jan 2022 23:21:39 -0300 Subject: [PATCH] Add docs for ots_search* methods --- docs/custom-jsonrpc.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/custom-jsonrpc.md b/docs/custom-jsonrpc.md index b8d814a..6083a2f 100644 --- a/docs/custom-jsonrpc.md +++ b/docs/custom-jsonrpc.md @@ -8,7 +8,9 @@ They are all used by Otterscan, but we are documenting them here so others can t We take an incremental approach when design the APIs, so there may be some methods very specific to Otterscan use cases, others that look more generic. -## Why don't you use _Some Product XXX_ for Otterscan? And why shouldn't I? +## FAQ + +### Why don't you use _Some Product XXX_ for Otterscan? And why shouldn't I? If you are happy using _Some Product XXX_, go ahead. @@ -22,6 +24,14 @@ Implementing everything in-node allows you to plug a dapp directly to your node > Take Otterscan as an example, **ALL** you need is Otterscan itself (a SPA, can be served by any static provider) and our modified Erigon's rpcdaemon. +### But your API doesn't scale and it is slower than _Some Product XXX_!!! + +Not everyone needs to serve thousands of request per second. Go ahead and use _Some Product XXX_. + +Some people just want to run standalone development tools and calculating some data on-the-fly works fine for single user local apps. + +Even so, we may introduce custom indexes for some operations in future if there is such demand, so you may opt-in for a better performance by spending more disk space. + ## Method summary All methods are prefixed with the `ots_` namespace in order to make it clear it is vendor-specific and there is no name clash with other same-name implementations. @@ -159,6 +169,25 @@ These are address history navigation methods. They are similar, the difference i They are paginated, you **MUST** inform the page size. Some addresses like exchange addresses or very popular DeFi contracts like Uniswap Router will return millions of results. +Parameters: + +`address` - The ETH address to be searched. +`blockNumber` - It searches for occurrences of `address` starting from `blockNumber` (inclusive). A value of `0` means you want to search from the most recent block (`ots_searchTransactionsBefore`) or from the genesis (`ots_searchTransactionsAfter`). +`pageSize` - How many transactions it may return. See the detailed explanation about this parameter bellow. + +Returns: + +`object` containing two attributes: + +- `txs` - An array of objects representing the transaction results. The results are returned sorted from the most recent to the older one (descending order). +- `receipts` - An array of objects containing the transaction receipts for the transactions returned in the `txs` attribute. +- `firstPage` - Boolean indicating this is the first page. It should be `true` when calling `ots_searchTransactionsBefore` with `blockNumber` == 0 (search from `latest`); because the results are in descending order, the search from the most recent block is the "first" one. It should also return `true` when calling `ots_searchTransactionsAfter` with a `blockNumber` which results in no more transactions after the returned ones because it searched forward up to the tip of the chain. +- `lastPage` - Boolean indicating this is the last page. It should be `true` when calling `ots_searchTransactionsAfter` with `blockNumber` == 0 (search from genesis); because the results are in descending order, the genesis page is the "last" one. It should also return `true` when calling `ots_searchTransactionsBefore` with a `blockNumber` which results in no more transactions before the returned ones because it searched backwards up to the genesis block. + +There is a small gotcha regarding `pageSize`. If there are less results than `pageSize`, they are just returned as is. + +But if there are more than `pageSize` results, they are capped by the last found block. For example, let's say you are searching for Uniswap Router address and it already found 24 matches; it then looks at the next block containing this addresses occurrences and there are 5 matches inside the block. They are all returned, so it returns 30 transaction results. The caller code should be aware of this. + ### `ots_getTransactionBySenderAndNonce` Given a sender address and a nonce, returns the tx hash or `null` if not found. It returns only the tx hash on success, you can use the standard `eth_getTransactionByHash` after that to get the full transaction data.