tx-indexer is a tool designed to index TM2 chain data and serve it over RPC, facilitating efficient data retrieval and
management in Tendermint2 networks.
- JSON-RPC 2.0 Specification Server: Utilizes the JSON-RPC 2.0 standard for request / response handling.
- HTTP and WS Support: Handles both HTTP
POSTrequests and WebSocket connections. - 2-Way WS Communication: Subscribe and receive data updates asynchronously over WebSocket connections.
- Concurrent Chain Indexing: Utilizes asynchronous workers for fast and efficient indexing. Data is available for serving as soon as it is fetched from the remote chain.
- Embedded Database: Features PebbleDB for quick on-disk data access and migration.
This section guides you through setting up and running the tx-indexer.
- Clone the Repository
git clone https://github.com/gnolang/tx-indexer.git- Build the binary
cd tx-indexer
make build- Run the indexer
./build/tx-indexer start --remote https://rpc.gno.land:443 --db-path indexer-dbor:
go run cmd/main.go cmd/start.go cmd/waiter.go start --remote https://rpc.gno.land:443 --db-path indexer-dbThe --remote flag specifies the JSON-RPC URL of the chain the indexer should index, and the --db-path specifies the
on-disk location for the indexed data.
Point --remote at whichever chain you want to index. https://rpc.gno.land:443 is
mainnet (gnoland-1); testnets are renamed and replaced every few weeks, so look the
current one up in Gno networks
rather than hardcoding a hostname.
Note: the websocket endpoint exposed is always: ws://<listen-address>/ws, where <listen-address> is set via the --listen-address flag when starting the indexer (default: 0.0.0.0:8546).
For a full list of available features and flags, execute the --help command:
> ./build/tx-indexer start --help
DESCRIPTION
Starts the indexer service
USAGE
start [flags]
Starts the indexer service, which includes the fetcher and JSON-RPC server
FLAGS
-client-ip-header string the header trusted to carry the client address the request log names and the client limits count by, such as CF-Connecting-IP or X-Forwarded-For; unset, the address the request came from
-client-ip-trusted-hops 1 the number of trusted proxies appending to --client-ip-header: the client address is that many entries from the right of its list
-client-time-budget 0s the most indexer time a client may hold, the wall time its GraphQL and JSON-RPC requests take, off at 0, the default; set with --client-time-budget-refill and --query-deadline
-client-time-budget-refill 0s the indexer time a client regains per minute, above 0 with --client-time-budget
-cors-allowed-origins * a comma-separated list of origins allowed to make cross-origin requests to the GraphQL and JSON-RPC endpoints, or "*" to allow any origin
-db-path indexer-db the absolute path for the indexer DB (embedded)
-disable-introspection=false disable GraphQL introspection queries if needed. This will cause malfunctions when using the GraphQL playground
-graphql-token-limit 4000 the most tokens a GraphQL document may hold, refused before it is validated, over HTTP and WebSocket alike; 0 for no limit
-http-rate-limit 0 the maximum HTTP requests allowed per minute per client address, as --client-ip-header reads it, an IPv6 one by its /64, unlimited by default
-listen-address 0.0.0.0:8546 the IP:PORT URL for the indexer JSON-RPC server
-log-format console the format of the log lines: console, columns for people to read, or json, one object per line for log pipelines to parse
-log-level info the log level for the CLI output
-max-chunk-size 100 the range for fetching blockchain data by a single worker
-max-slots 100 the amount of slots (workers) the fetcher employs
-metrics-listen-address string the IP:PORT address to serve the Prometheus metrics on, at /metrics, apart from the public endpoints; off by default
-query-deadline 0s the maximum time a GraphQL or JSON-RPC request may run before it is answered with a deadline error, unlimited by default; subscriptions are exempt
-remote http://127.0.0.1:26657 the JSON-RPC URL of the Gno chain
-request-log=false log one line per GraphQL root field or JSON-RPC call served, at info: its operation, status, duration, rows and client address, never its arguments
-supply-denoms ugnot comma-separated denominations whose supply (total/spendable/locked) is tracked and served by getSupplyBefore any service starts, the indexer loads the chain genesis into its database: the genesis block, so indexing can start from height 0, and the genesis balances, where the vesting schedules the supply endpoint needs live. This happens once per database — every later start reads what it needs from the DB and never fetches the genesis document again.
Two consequences worth knowing when running it:
- The indexer will not start if it cannot bootstrap the genesis. It retries while the node is unreachable, and fails outright against a node that does not serve a readable gno genesis. Earlier versions logged the failure and indexed anyway, at the cost of a missing block 0.
- A database is bound to its chain. The chain ID is stored alongside the genesis and checked against the node on
every start, so pointing
--remoteat a different network while reusing--db-pathrefuses to start rather than mixing two chains' data. Use a separate--db-pathper chain.
--query-deadline bounds how long one GraphQL or JSON-RPC request may run. A list query filters rows as it reads
them, and its 10000 element cap counts the rows it returns rather than the rows it reads, so a filter that matches
little can read the whole chain on every call. The deadline is off (0s) by default; set it to a Go duration such as
10s.
A transaction list (getTransactions, transactions) that runs past it answers no rows and an error naming it: the
rows read so far can end inside a block. Narrow the block height range and retry.
{
"errors": [
{
"message": "query deadline exceeded (10s); narrow the block height range",
"path": ["getTransactions"],
"extensions": { "code": "QUERY_DEADLINE_EXCEEDED", "queryDeadline": "10s" }
}
],
"data": { "getTransactions": null }
}A block list (getBlocks, blocks) answers the same error beside the blocks it read before the deadline. A block row
is a whole block, so resume past the last height returned: above it ascending, below it descending.
Over JSON-RPC, getGasPrice, the one method that scans a block range, answers the same message with code -32000,
and the same code and queryDeadline in the error's data. The calls of a batch share one deadline: those not yet
run when it passes answer the error without running.
The deadline bounds time, not CPU: the list fields of one GraphQL query run in parallel, so a query naming several can keep as many cores busy for the length of the deadline.
Subscriptions, over GraphQL or the /ws endpoint, last as long as their connection and are not bounded; each JSON-RPC
call sent over /ws is. /health and /ready are not bounded.
--metrics-listen-address serves Prometheus metrics at /metrics on a listener of its own, apart from the GraphQL and
JSON-RPC endpoints, so it can stay on a private interface. It is off by default, and the indexer then collects none.
A request is one GraphQL root query field or one JSON-RPC call: a batch counts each of its calls. Its api label is
graphql or jsonrpc, and its operation label the field or the method. No label carries a client address or a
request's arguments.
| Metric | Type | Labels | Value |
|---|---|---|---|
tx_indexer_requests_total |
counter | api, operation, status |
requests served; status is ok (partial answers included), error, or deadline (--query-deadline) |
tx_indexer_requests_refused_total |
counter | api, reason |
requests the client limits refused, by reason: client_time_budget or http_rate_limit; never served |
tx_indexer_request_duration_seconds |
histogram | api, operation |
the time a request takes, the fields of the rows it answers included |
tx_indexer_rows_scanned_total |
counter | api, operation |
the blocks and transactions read from the database, the ones a filter or an index window then drops included |
tx_indexer_rows_returned_total |
counter | api, operation |
the blocks and transactions answered |
tx_indexer_requests_in_flight |
gauge | api, operation |
the requests being served |
tx_indexer_indexed_height |
gauge | the latest block height written to the database | |
tx_indexer_chain_height |
gauge | the chain's latest block height, as last read from the node | |
tx_indexer_fetch_errors_total |
counter | stage |
failed reads from the node: of its latest height (chain_height), or of a range of blocks (range) |
tx_indexer_fetch_retries_total |
counter | the block ranges fetched again after their fetch failed |
The Go runtime's (go_*) and the process's (process_*) metrics are served beside them. A subscription's stream is
not counted, as it lasts as long as its connection: a GraphQL subscription is left out, and a JSON-RPC subscribe call
counts for its answer alone. Neither is a request that runs no operation: a GraphQL document that does not validate, or
a JSON-RPC call that is not valid JSON-RPC 2.0 or names a method that does not exist.
A GraphQL list answered in part counts as ok, with an error beside its rows: one cut at its element cap, or one short
of a row that failed to decode. A block list the query deadline cuts short counts as deadline, though it answers the
blocks it read.
A lookup of one block or transaction, by height, index or hash, counts as one row scanned whether it finds its row or not: a miss reads the database all the same.
The rows scanned for each row returned tell how much reading a filter costs:
rate(tx_indexer_rows_scanned_total[5m]) / rate(tx_indexer_rows_returned_total[5m]).
The lag behind the chain, in blocks, is tx_indexer_chain_height - tx_indexer_indexed_height. The chain's height is read
once per fetch round, and not while every fetch slot is busy catching up, so it can trail the chain; a node that stops
answering leaves it as it last was, so watch tx_indexer_fetch_errors_total{stage="chain_height"} beside the lag. That
counter also counts the genesis bootstrap's failed reads of the node's status, so a node down when the indexer starts
shows there too.
The indexer logs to stderr, at --log-level, in the format --log-format names. console, the default, writes columns
for people to read: the time, the level, the logger, the caller and the message, then the fields as one JSON object.
2026-10-28T10:01:28.290+0100 INFO requests observe/observe.go:148 served request {"api": "jsonrpc", "operation": "getBlock", "status": "ok", "duration": "25.791µs", "rows-scanned": 1, "rows-returned": 0, "client": "127.0.0.1"}
json writes one JSON object per line, for a log pipeline to parse: its level, its time under ts, in RFC 3339 with
all nine digits of nanoseconds and in UTC, its logger, caller and msg, then each field as a key of its own. A line
at warn or above carries its stack trace under stacktrace, but a stdlib line, which carries one from error up: any
client can cause a stdlib warning.
{"level":"info","ts":"2026-10-28T10:41:26.526435000Z","logger":"requests","caller":"observe/observe.go:148","msg":"served request","api":"jsonrpc","operation":"getBlock","status":"ok","duration":"29.791µs","rows-scanned":1,"rows-returned":0,"client":"127.0.0.1"}Each line names the logger it came from: a service's (fetcher, http-server, graphql, pebble, requests, ...),
or start for the start command's own lines, the error that ends a run among them. The HTTP servers' own errors, a
GraphQL resolver's panic and pebble's messages go through the logger too, at error for the errors, at fatal for pebble's
fatal ones. A dependency's line through Go's standard log package is logged under stdlib, at warn.
A line at error marks the indexer's own failure. What a client alone causes is at warn or below: a failed WebSocket upgrade, a WebSocket closed before its answer.
Four kinds of line stay outside the logger, as plain text on stderr:
- an error raised before the logger exists: a flag that does not parse, an unknown log level or format, a
--query-deadline,--client-ip-trusted-hopsor--graphql-token-limitout of range, or a time budget set inconsistently; - the error that ends a run when
--log-levelis above error, which leaves it out of the log, and a failed sync of the log at the stop; - a Go runtime crash outside any recover;
- on macOS, the fork notice of libmdbx, a library gno links in:
rthc_afterfork:… drown … rthc entries.
--request-log logs one line at info per request served, the same requests the metrics count: its api, operation
and status, its duration, its rows-scanned and rows-returned, and the client address. It never logs a
request's arguments: a GraphQL query's variables or a JSON-RPC call's params. It is off by default, as it adds a line
per call of every client and their addresses to the log.
Each request a client limit refuses adds one line at info too, refused request: its client and api, the reason
(client_time_budget or http_rate_limit), its retry-after, and the status refused.
The client address is the address the request came from, which behind a proxy is the proxy's. --client-ip-header
names a header the proxies in front of the indexer fill with the client's address instead:
- behind Cloudflare,
CF-Connecting-IP, which Cloudflare sets to the client's address; - behind load balancers,
X-Forwarded-For. Each appends the address it was reached from, and the client can write anything to the left of those entries, so--client-ip-trusted-hopscounts the load balancers and the client address is that many entries from the right, 1 by default.
A header that is missing, holds fewer entries, or holds no IP address there leaves the address the request came from.
An entry's port, which some proxies append (203.0.113.7:51234, [2001:db8::1]:443), is dropped.
Trust a header only if every request reaches the indexer through the proxies that set it: one that reaches it directly
writes the header it likes.
Two limits, each off by default, keep one client from holding the indexer from the others. Both apply to the API
endpoints alone, JSON-RPC's / and /ws and GraphQL's /graphql/query: /health, /ready and the playground are
never refused, so a load balancer's health checks always reach the indexer. /ready answers from a check of the node
made at most once a second, so however many requests it gets, it costs the node one status call a second. /ready
answers 500 while the node is not ready, and /health while the store cannot answer its height.
Both count each client under its client address, the one the request log names: the address the request came from, or
the one --client-ip-header reads behind --client-ip-trusted-hops trusted proxies. A header the client sets itself,
such as X-Real-IP or X-Forwarded-For when no proxy is trusted, never names a client. An IPv6 client is counted under
its /64, the block one end site is given, so moving across its addresses leaves it one client. Behind a proxy, set
--client-ip-header: without it, every client is the proxy, and shares the proxy's limits.
The count limit, --http-rate-limit, caps the requests a client sends per minute. One past it is answered 429, with
Retry-After: 60 and {"error": "too many requests"}. It counts HTTP requests: a WebSocket connection counts once, at
its upgrade.
The time budget, --client-time-budget with --client-time-budget-refill, caps the indexer time a client holds: the
wall time its requests take, its body's upload, its parsing and its validation included, from the moment the indexer
starts serving one until its answer is written; over a WebSocket, a document that fails validation until its errors are
made, just before they are written. A client starts with the whole budget and regains the refill each minute, never past
the budget. A request is admitted while the client's balance is above zero, and charged its wall time once served.
Each request in flight also holds one --query-deadline of its client's balance while it runs: a client holds at most
⌈budget ÷ deadline⌉ requests in flight, however many it sends at once. Size the budget for the parallelism a client may
have. The deadline bounds a query's execution, not its upload, its parsing, its validation or the writing of its answer,
so what a request overdraws its client's balance by is what those take beyond the deadline; the token limit below
bounds the parsing and the validation. The budget needs --query-deadline, and the start refuses one without it, as it
refuses a budget with a refill of 0, which would leave a client that spent its budget refused for good, and a refill
without a budget. Either flag at 0s, its default, is off. The budget counts wall time, not CPU, as the deadline does.
Over a WebSocket, each GraphQL operation or JSON-RPC call is charged to the client that opened the connection, and holds
its share of the balance while it runs. A GraphQL operation is admitted before its document is parsed: a client over its
budget has nothing parsed, and parsing and validating a document are charged, an invalid one included. A subscription's
start is admitted and charged so too; once started, its stream holds nothing. A JSON-RPC message holding only
subscribe and unsubscribe calls is neither charged nor refused. The upgrade itself is never refused.
A request the budget refuses is answered 429, with Retry-After, the whole seconds until its client's balance is back
above zero, or 1 when the balance is above zero and its requests in flight alone refuse it, since only one of them
ending admits it, and its API's error, in the shape of the query deadline's:
{
"errors": [
{
"message": "client time budget exhausted; retry in 12s",
"extensions": { "code": "CLIENT_TIME_BUDGET_EXHAUSTED", "retryAfterSeconds": 12 }
}
],
"data": null
}Over JSON-RPC, a refused request is answered one error with code -32005, and the same code and retryAfterSeconds
in the error's data, naming no call: its body is left unread, so a refusal costs the same whatever the client sent.
A query refused over a WebSocket answers the same error. A message refused over JSON-RPC's WebSocket is answered under
each call's ID, a batch as a batch: the connection caps a message at 512 bytes, and a client that multiplexes calls
over it needs their IDs.
The indexer remembers a client only while its balance is below the budget or a request of its is in flight: the clients active within one refill of the budget.
To size the budget, read the request log: the sum of a client's duration over a minute is about the indexer time it
used, though a GraphQL query's root fields run in parallel and can add up to more than the request took. For example,
--query-deadline 30s --client-time-budget 60s --client-time-budget-refill 30s lets a client run two 30 s queries at
once, and once it has spent its budget, regain 30 s a minute: one 30 s query a minute, or thirty of one second.
Both limits count their refusals in tx_indexer_requests_refused_total, by api and reason, and with --request-log
on, log each.
The GraphQL token limit, --graphql-token-limit, caps the tokens a GraphQL document may hold, over HTTP and WebSocket
alike, and refuses a longer one before validating it: validating a document takes time that grows faster than the
document, and the limit bounds it. It is 4000 by default, four times the 860 tokens of the widest legitimate query, one
naming every filter field and every returned field of getTransactions once; 0 lifts it. The limit counts the
document alone, not its variables: a client that filters on a long list, such as an _or of many entries, passes the
list as a variable. A refused document is answered as any document that does not parse: exceeded token limit of 4000.
Whatever the limit, an invalid document is answered at most the first 100 errors of each validation rule, then one
saying the rest of that rule's are left out, as
more than 100 OverlappingFieldsCanBeMerged errors; the rest are left out: the errors of a document can grow with the
square of its fields, the answer does not.
The indexer provides a GraphQL endpoint for querying blockchain data (transactions, blocks) and subscribing to real-time events:
Endpoint:
http://<listen-address>/graphql/query
Playground (Interactive UI):
http://<listen-address>/graphql
The playground includes built-in documentation for available queries, fields, and filters.
Note: Introspection is enabled by default --disable-introspection=false; disable it only if security is a priority (Playground won’t work).
- Mainnet Playground —
gnoland-1
Testnets each run their own indexer at indexer.<network>.testnets.gno.land/graphql;
see Gno networks for whichever is
current.
{
getTransactions(where: { messages: { value: { MsgAddPackage: {} } } }) {
index
hash
block_height
gas_used
messages {
route
typeUrl
value {
__typename
... on MsgAddPackage {
creator
package {
name
path
}
}
}
}
}
}subscription {
getBlocks(where: {}) {
height
version
chain_id
time
proposer_address_raw
}
}Total, spendable (what data aggregators call the circulating supply) and locked supply, served from the indexer's
background snapshot (see getSupply); only the denoms from --supply-denoms are tracked.
{
getSupply(denom: "ugnot") {
denom
height
total
spendable
locked
}
}Please take note that the indexer JSON-RPC server adheres to the JSON-RPC 2.0 standard for request and response processing.
Fetches a specific block from the chain.
- Params: Decimal block number (
int64) as a string. - Response: Base64 encoded, Amino encoded binary of the block.
Example request:
{
"id": 1,
"jsonrpc": "2.0",
"method": "getBlock",
"params": ["10"]
}Example response:
{
"result": "CsQCCgt2MS4wLjAtcmMuMBIFdGVzdDMYFCILCJm2/aYGELbF420wBEJICiDi4yHZq+xnUtXDDS73aW9PN9yg4r+B0W0PiB2vmaVlSBIkCAISIJG6uIRyUVyoP447ASEpBUwdUaub/eGmJPxSGeA5lbpzSiCOHonO/bm5CFQW8X24a4Qn+SpJyHerFyaAO7TxMPqrgFog92nrytGOQMQp15Sdl3MG3GaeGdyRMAnaA1rGBVil/QhiIPdp68rRjkDEKdeUnZdzBtxmnhnckTAJ2gNaxgVYpf0IaiC4qGdcWYZSTGBBIl/XuiBtgs1cOjdQQ/BC/N12jhWS7HIgDxA96fJ6yy6vIQOGwa29idxYcNSsumetioI2N9SZObyCAShnMXd5cmU0Z3I3bjgyZXpmcGRoZzNueHlwank5Y2FnOXFwa3U1eDZtGpQCCkgKIOLjIdmr7GdS1cMNLvdpb0833KDiv4HRbQ+IHa+ZpWVIEiQIAhIgkbq4hHJRXKg/jjsBISkFTB1Rq5v94aYk/FIZ4DmVunMSxwEIAhASIkgKIOLjIdmr7GdS1cMNLvdpb0833KDiv4HRbQ+IHa+ZpWVIEiQIAhIgkbq4hHJRXKg/jjsBISkFTB1Rq5v94aYk/FIZ4DmVunMqCwiZtv2mBhC2xeNtMihnMXd5cmU0Z3I3bjgyZXpmcGRoZzNueHlwank5Y2FnOXFwa3U1eDZtQkBhkidOtSLpPWcKhDmUwKNHVNAOHzuVntpNwFx0KDPwauTfZRRqoNiwPp7E812FNLNBT3bfS4U3C73SrMuDJZwE",
"jsonrpc": "2.0",
"id": 1
}If no block is found (not yet indexed), null as the response result is returned:
{
"result": null,
"jsonrpc": "2.0",
"id": 1
}Fetches the specified transaction result from storage.
- Params: Base64 hash of the transaction
- Response: Base64 encoded, Amino encoded binary of the transaction result
Example request:
{
"id": 1,
"jsonrpc": "2.0",
"method": "getTxResult",
"params": ["AP9YX+QXrIByqonIqStod8G9EI5AMiUZhsXk58wr0ws="]
}Example response:
{
"result": "CIjaGRqVEwrfEQoML3ZtLm1fYWRkcGtnEs4RCihnMTludmNrZ2QzY2trZmp6cDUyczc0Z2N4czA5dHduczc1amVucXk1EqERCgdjYXB0YWluEhdnbm8ubGFuZC9yL2RlbW8vY2FwdGFpbhr8EAoJR1JDMjAuZ25vEu4QcGFja2FnZSBjYXB0YWluDQoNCmltcG9ydCAoDQoJInN0ZCINCgkic3RyaW5ncyINCg0KCSJnbm8ubGFuZC9wL2RlbW8vZ3JjL2dyYzIwIg0KCSJnbm8ubGFuZC9wL2RlbW8vdWZtdCINCgkiZ25vLmxhbmQvci9kZW1vL3VzZXJzIg0KKQ0KDQp2YXIgKA0KCWNhcHRhaW4gICpncmMyMC5BZG1pblRva2VuDQoJYWRtaW4gc3RkLkFkZHJlc3MgPSAiZzE5bnZja2dkM2Nra2ZqenA1MnM3NGdjeHMwOXR3bnM3NWplbnF5NSINCikNCg0KZnVuYyBpbml0KCkgew0KCWNhcHRhaW4gPSBncmMyMC5OZXdBZG1pblRva2VuKCJDUE4iLCAiY2FwdGFpbiIsIDYpDQoJY2FwdGFpbi5NaW50KGFkbWluLCA2OTAwMDAwMDAwMCkgLy8gQGFkbWluaXN0cmF0b3INCn0NCg0KLy8gbWV0aG9kIHByb3hpZXMgYXMgcHVibGljIGZ1bmN0aW9ucy4NCi8vDQoNCi8vIGdldHRlcnMuDQoNCmZ1bmMgVG90YWxTdXBwbHkoKSB1aW50NjQgew0KCXJldHVybiBjYXB0YWluLlRvdGFsU3VwcGx5KCkNCn0NCg0KZnVuYyBCYWxhbmNlT2Yob3duZXIgdXNlcnMuQWRkcmVzc09yTmFtZSkgdWludDY0IHsNCgliYWxhbmNlLCBlcnIgOj0gY2FwdGFpbi5CYWxhbmNlT2Yob3duZXIuUmVzb2x2ZSgpKQ0KCWlmIGVyciAhPSBuaWwgew0KCQlwYW5pYyhlcnIpDQoJfQ0KCXJldHVybiBiYWxhbmNlDQp9DQoNCmZ1bmMgQWxsb3dhbmNlKG93bmVyLCBzcGVuZGVyIHVzZXJzLkFkZHJlc3NPck5hbWUpIHVpbnQ2NCB7DQoJYWxsb3dhbmNlLCBlcnIgOj0gY2FwdGFpbi5BbGxvd2FuY2Uob3duZXIuUmVzb2x2ZSgpLCBzcGVuZGVyLlJlc29sdmUoKSkNCglpZiBlcnIgIT0gbmlsIHsNCgkJcGFuaWMoZXJyKQ0KCX0NCglyZXR1cm4gYWxsb3dhbmNlDQp9DQoNCi8vIHNldHRlcnMuDQoNCmZ1bmMgVHJhbnNmZXIodG8gdXNlcnMuQWRkcmVzc09yTmFtZSwgYW1vdW50IHVpbnQ2NCkgew0KCWNhbGxlciA6PSBzdGQuR2V0T3JpZ0NhbGxlcigpDQoJY2FwdGFpbi5UcmFuc2ZlcihjYWxsZXIsIHRvLlJlc29sdmUoKSwgYW1vdW50KQ0KfQ0KDQpmdW5jIEFwcHJvdmUoc3BlbmRlciB1c2Vycy5BZGRyZXNzT3JOYW1lLCBhbW91bnQgdWludDY0KSB7DQoJY2FsbGVyIDo9IHN0ZC5HZXRPcmlnQ2FsbGVyKCkNCgljYXB0YWluLkFwcHJvdmUoY2FsbGVyLCBzcGVuZGVyLlJlc29sdmUoKSwgYW1vdW50KQ0KfQ0KDQpmdW5jIFRyYW5zZmVyRnJvbShmcm9tLCB0byB1c2Vycy5BZGRyZXNzT3JOYW1lLCBhbW91bnQgdWludDY0KSB7DQoJY2FsbGVyIDo9IHN0ZC5HZXRPcmlnQ2FsbGVyKCkNCgljYXB0YWluLlRyYW5zZmVyRnJvbShjYWxsZXIsIGZyb20uUmVzb2x2ZSgpLCB0by5SZXNvbHZlKCksIGFtb3VudCkNCn0NCg0KLy8gYWRtaW5pc3RyYXRpb24uDQoNCmZ1bmMgTWludChhZGRyZXNzIHVzZXJzLkFkZHJlc3NPck5hbWUsIGFtb3VudCB1aW50NjQpIHsNCgljYWxsZXIgOj0gc3RkLkdldE9yaWdDYWxsZXIoKQ0KCWFzc2VydElzQWRtaW4oY2FsbGVyKQ0KCWNhcHRhaW4uTWludChhZGRyZXNzLlJlc29sdmUoKSwgYW1vdW50KQ0KfQ0KDQpmdW5jIEJ1cm4oYWRkcmVzcyB1c2Vycy5BZGRyZXNzT3JOYW1lLCBhbW91bnQgdWludDY0KSB7DQoJY2FsbGVyIDo9IHN0ZC5HZXRPcmlnQ2FsbGVyKCkNCglhc3NlcnRJc0FkbWluKGNhbGxlcikNCgljYXB0YWluLkJ1cm4oYWRkcmVzcy5SZXNvbHZlKCksIGFtb3VudCkNCn0NCg0KLy8gcmVuZGVyLg0KLy8NCg0KZnVuYyBSZW5kZXIocGF0aCBzdHJpbmcpIHN0cmluZyB7DQoJcGFydHMgOj0gc3RyaW5ncy5TcGxpdChwYXRoLCAiLyIpDQoJYyA6PSBsZW4ocGFydHMpDQoNCglzd2l0Y2ggew0KCWNhc2UgcGF0aCA9PSAiIjoNCgkJcmV0dXJuIGNhcHRhaW4uUmVuZGVySG9tZSgpDQoJY2FzZSBjID09IDIgJiYgcGFydHNbMF0gPT0gImJhbGFuY2UiOg0KCQlvd25lciA6PSB1c2Vycy5BZGRyZXNzT3JOYW1lKHBhcnRzWzFdKQ0KCQliYWxhbmNlLCBfIDo9IGNhcHRhaW4uQmFsYW5jZU9mKG93bmVyLlJlc29sdmUoKSkNCgkJcmV0dXJuIHVmbXQuU3ByaW50ZigiJWRcbiIsIGJhbGFuY2UpDQoJZGVmYXVsdDoNCgkJcmV0dXJuICI0MDRcbiINCgl9DQp9DQoNCmZ1bmMgYXNzZXJ0SXNBZG1pbihhZGRyZXNzIHN0ZC5BZGRyZXNzKSB7DQoJaWYgYWRkcmVzcyAhPSBhZG1pbiB7DQoJCXBhbmljKCJyZXN0cmljdGVkIGFjY2VzcyIpDQoJfQ0KfRIRCIDaxAkSCjUwMDAwdWdub3Qafgo6ChMvdG0uUHViS2V5U2VjcDI1NmsxEiMKIQKN1aylL3JWIoeyByEGcAo2LPJv6HVMI+vneCMVg3YUjRJAfVXpl28frJh0hcJQSO6Vrbpx339p+hf9nuaMx44/Sa984DsstdGuIfZbBo9osUnfSocCw/i84rEsIzGnQ9Hb6SIeRGVwbG95ZWQgdGhyb3VnaCBwbGF5Lmduby5sYW5kIp4dCpIdChQKEi9zdGQuSW50ZXJuYWxFcnJvciL5HHJlY292ZXJlZDogcGFja2FnZSBhbHJlYWR5IGV4aXN0czogZ25vLmxhbmQvci9kZW1vL2NhcHRhaW4Kc3RhY2s6Cmdvcm91dGluZSA2MCBbcnVubmluZ106CnJ1bnRpbWUvZGVidWcuU3RhY2soKQoJL3Vzci9sb2NhbC9nby9zcmMvcnVudGltZS9kZWJ1Zy9zdGFjay5nbzoyNCArMHg2NQpnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3Mvc2RrLigqQmFzZUFwcCkucnVuVHguZnVuYzEoKQoJL29wdC9idWlsZC9wa2dzL3Nkay9iYXNlYXBwLmdvOjc0MyArMHgyY2QKcGFuaWMoezB4YmU1NmMwLCAweGMwMGZjMWRkMDB9KQoJL3Vzci9sb2NhbC9nby9zcmMvcnVudGltZS9wYW5pYy5nbzo4ODQgKzB4MjEyCmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9zZGsvdm0uKCpWTUtlZXBlcikuQWRkUGFja2FnZShfLCB7ezB4ZjYyMTQwLCAweGMwMDk5YmUyNzB9LCAweDIsIHsweGY2MWIwOCwgMHhjMDBmYzFjOWYwfSwgezB4ZjYyMmM4LCAweGMwMDU2YTQ0MjB9LCB7MHhjMDI0YTljOTgwLCAweDV9LCAuLi59LCAuLi4pCgkvb3B0L2J1aWxkL3BrZ3Mvc2RrL3ZtL2tlZXBlci5nbzoxMzggKzB4Njg1CmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9zZGsvdm0udm1IYW5kbGVyLmhhbmRsZU1zZ0FkZFBhY2thZ2Uoe199LCB7ezB4ZjYyMTQwLCAweGMwMDk5YmUyNzB9LCAweDIsIHsweGY2MWIwOCwgMHhjMDBmYzFjOWYwfSwgezB4ZjYyMmM4LCAweGMwMDU2YTQ0MjB9LCB7MHhjMDI0YTljOTgwLCAweDV9LCAuLi59LCAuLi4pCgkvb3B0L2J1aWxkL3BrZ3Mvc2RrL3ZtL2hhbmRsZXIuZ286NDYgKzB4MmM1CmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9zZGsvdm0udm1IYW5kbGVyLlByb2Nlc3Moe199LCB7ezB4ZjYyMTQwLCAweGMwMDk5YmUyNzB9LCAweDIsIHsweGY2MWIwOCwgMHhjMDBmYzFjOWYwfSwgezB4ZjYyMmM4LCAweGMwMDU2YTQ0MjB9LCB7MHhjMDI0YTljOTgwLCAweDV9LCAuLi59LCAuLi4pCgkvb3B0L2J1aWxkL3BrZ3Mvc2RrL3ZtL2hhbmRsZXIuZ286MjcgKzB4MjI1CmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9zZGsuKCpCYXNlQXBwKS5ydW5Nc2dzKF8sIHt7MHhmNjIxNDAsIDB4YzAwOTliZTI3MH0sIDB4MiwgezB4ZjYxYjA4LCAweGMwMGZjMWM5ZjB9LCB7MHhmNjIyYzgsIDB4YzAwNTZhNDQyMH0sIHsweGMwMjRhOWM5ODAsIDB4NX0sIC4uLn0sIC4uLikKCS9vcHQvYnVpbGQvcGtncy9zZGsvYmFzZWFwcC5nbzo2NDQgKzB4NDJmCmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9zZGsuKCpCYXNlQXBwKS5ydW5UeCgweGMwMDAxYTQyMDAsIDB4MiwgezB4YzAwNDNkYjUwMCwgMHg5OTUsIF99LCB7ezB4YzAxMzBhOWM0MCwgMHgxLCAweDF9LCB7MHg5ODk2ODAsIHt7MHhjMDBlZjJjNjg1LCAuLi59LCAuLi59fSwgLi4ufSkKCS9vcHQvYnVpbGQvcGtncy9zZGsvYmFzZWFwcC5nbzo4MjMgKzB4OTA1CmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9zZGsuKCpCYXNlQXBwKS5EZWxpdmVyVHgoMHgwPywge3t9LCB7MHhjMDA0M2RiNTAwPywgMHgwPywgMHgwP319KQoJL29wdC9idWlsZC9wa2dzL3Nkay9iYXNlYXBwLmdvOjU4MCArMHgxN2QKZ2l0aHViLmNvbS9nbm9sYW5nL2duby9wa2dzL2JmdC9hYmNpL2NsaWVudC4oKmxvY2FsQ2xpZW50KS5EZWxpdmVyVHhBc3luYygweGMwMTNiNzY1NDAsIHt7fSwgezB4YzAwNDNkYjUwMD8sIDB4MD8sIDB4MD99fSkKCS9vcHQvYnVpbGQvcGtncy9iZnQvYWJjaS9jbGllbnQvbG9jYWxfY2xpZW50LmdvOjgyICsweDEwMwpnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L3Byb3h5LigqYXBwQ29ubkNvbnNlbnN1cykuRGVsaXZlclR4QXN5bmMoMHgwPywge3t9LCB7MHhjMDA0M2RiNTAwPywgMHgwPywgMHgwP319KQoJL29wdC9idWlsZC9wa2dzL2JmdC9wcm94eS9hcHBfY29ubi5nbzo3MyArMHgyNgpnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L3N0YXRlLmV4ZWNCbG9ja09uUHJveHlBcHAoezB4ZjYzMGEwLCAweGMwMTNiN2MwZjB9LCB7MHhmNjU1NzAsIDB4YzAxM2I2MzZmMH0sIDB4YzAwZjY3NTZjMCwgezB4ZjZhYWYwLCAweGMwMDAxMTliNDB9KQoJL29wdC9idWlsZC9wa2dzL2JmdC9zdGF0ZS9leGVjdXRpb24uZ286MjUzICsweDhkYQpnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L3N0YXRlLigqQmxvY2tFeGVjdXRvcikuQXBwbHlCbG9jayhfLCB7ezB4Y2Y0ZGQwLCAweGJ9LCB7MHhjZjRkZDAsIDB4Yn0sIHsweDAsIDB4MH0sIHsweGMwMTNiNGZhZjAsIDB4NX0sIDB4MzM2ODMsIC4uLn0sIC4uLikKCS9vcHQvYnVpbGQvcGtncy9iZnQvc3RhdGUvZXhlY3V0aW9uLmdvOjEwMiArMHgxMTUKZ2l0aHViLmNvbS9nbm9sYW5nL2duby9wa2dzL2JmdC9jb25zZW5zdXMuKCpDb25zZW5zdXNTdGF0ZSkuZmluYWxpemVDb21taXQoMHhjMDA3Y2M0YzAwLCAweDMzNjg0KQoJL29wdC9idWlsZC9wa2dzL2JmdC9jb25zZW5zdXMvc3RhdGUuZ286MTM0OCArMHg5N2UKZ2l0aHViLmNvbS9nbm9sYW5nL2duby9wa2dzL2JmdC9jb25zZW5zdXMuKCpDb25zZW5zdXNTdGF0ZSkudHJ5RmluYWxpemVDb21taXQoMHhjMDA3Y2M0YzAwLCAweDMzNjg0KQoJL29wdC9idWlsZC9wa2dzL2JmdC9jb25zZW5zdXMvc3RhdGUuZ286MTI3NiArMHgzMTMKZ2l0aHViLmNvbS9nbm9sYW5nL2duby9wa2dzL2JmdC9jb25zZW5zdXMuKCpDb25zZW5zdXNTdGF0ZSkuZW50ZXJDb21taXQuZnVuYzEoKQoJL29wdC9idWlsZC9wa2dzL2JmdC9jb25zZW5zdXMvc3RhdGUuZ286MTIyMiArMHg5NwpnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L2NvbnNlbnN1cy4oKkNvbnNlbnN1c1N0YXRlKS5lbnRlckNvbW1pdCgweGMwMDdjYzRjMDAsIDB4MzM2ODQsIDB4MCkKCS9vcHQvYnVpbGQvcGtncy9iZnQvY29uc2Vuc3VzL3N0YXRlLmdvOjEyNTMgKzB4YjAzCmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9iZnQvY29uc2Vuc3VzLigqQ29uc2Vuc3VzU3RhdGUpLmFkZFZvdGUoMHhjMDA3Y2M0YzAwLCAweGMwMDlhNDgyODAsIHsweDAsIDB4MH0pCgkvb3B0L2J1aWxkL3BrZ3MvYmZ0L2NvbnNlbnN1cy9zdGF0ZS5nbzoxNjQxICsweDkxMwpnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L2NvbnNlbnN1cy4oKkNvbnNlbnN1c1N0YXRlKS50cnlBZGRWb3RlKDB4YzAwN2NjNGMwMCwgMHg0YjQ0MjY/LCB7MHgwPywgMHhjMDBiODE3YmYwP30pCgkvb3B0L2J1aWxkL3BrZ3MvYmZ0L2NvbnNlbnN1cy9zdGF0ZS5nbzoxNDg0ICsweDI3CmdpdGh1Yi5jb20vZ25vbGFuZy9nbm8vcGtncy9iZnQvY29uc2Vuc3VzLigqQ29uc2Vuc3VzU3RhdGUpLmhhbmRsZU1zZygweGMwMDdjYzRjMDAsIHt7MHhmNWJhYTA/LCAweGMwMWM0OWZiZDg/fSwgezB4MD8sIDB4ZWRkMzI1ZTU2P319KQoJL29wdC9idWlsZC9wa2dzL2JmdC9jb25zZW5zdXMvc3RhdGUuZ286NjkxICsweDNhOApnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L2NvbnNlbnN1cy4oKkNvbnNlbnN1c1N0YXRlKS5yZWNlaXZlUm91dGluZSgweGMwMDdjYzRjMDAsIDB4MCkKCS9vcHQvYnVpbGQvcGtncy9iZnQvY29uc2Vuc3VzL3N0YXRlLmdvOjY1MCArMHg0NTcKY3JlYXRlZCBieSBnaXRodWIuY29tL2dub2xhbmcvZ25vL3BrZ3MvYmZ0L2NvbnNlbnN1cy4oKkNvbnNlbnN1c1N0YXRlKS5PblN0YXJ0Cgkvb3B0L2J1aWxkL3BrZ3MvYmZ0L2NvbnNlbnN1cy9zdGF0ZS5nbzozNDQgKzB4NGRjChCA2sQJGIq9Cw==",
"jsonrpc": "2.0",
"id": 1
}If no transaction result is found (not yet indexed, or transaction not committed yet), null as the response result is
returned:
{
"result": null,
"jsonrpc": "2.0",
"id": 1
}Returns the supply of a tracked denomination at a recent chain height, split by spendability: how much of it exists
(total), how much of that the genesis vesting schedules still lock (locked), and the difference (spendable),
which is what data aggregators call the circulating supply.
- Params:
denom, a tracked denomination, e.g.ugnot - Response:
{ denom, height, total, spendable, locked }, amounts as strings
The figures come from a background snapshot the indexer refreshes on its own schedule (every 10 seconds), so requests
never reach the chain. The snapshot covers only the denoms listed in --supply-denoms (default ugnot): the total is
read from the chain's per-denom supply counter, and the locked portion is computed from the vesting schedules in the
chain genesis, evaluated at the snapshot's block time. Locked is not clamped to each account's live balance, so for
accounts that spent below their schedule through fees it can exceed what they still hold; in exchange a refresh reads
one counter per denom instead of one balance per vesting account. Schedules sharing a vesting window are summed and
evaluated as one, so a refresh costs the same whether the genesis holds ten vesting accounts or millions; the summed
figure can be lower than a per-account evaluation by less than one unit of the denom per account. Locked never
exceeds the total, so total = spendable + locked always holds. All figures in a snapshot were read at the same
height, in one batched query. If a refresh fails, the last good snapshot keeps serving.
Example request:
{
"id": 1,
"jsonrpc": "2.0",
"method": "getSupply",
"params": ["ugnot"]
}Example response:
{
"result": {
"denom": "ugnot",
"height": 1337,
"total": "1000000000000",
"spendable": "700000000000",
"locked": "300000000000"
},
"jsonrpc": "2.0",
"id": 1
}Creates a filter for new block events, to notify when a new block arrives.
To check if the state has changed, call the getFilterChanges endpoint.
- Params: no params
- Response: the filter ID (
string)
Example request:
{
"id": 1,
"jsonrpc": "2.0",
"method": "newBlockFilter",
"params": []
}Example response:
{
"result": "c77000bb-700c-41b9-830c-e8b35bdef246",
"jsonrpc": "2.0",
"id": 1
}Polling method for a filter, which returns an array of events that have occurred since the last poll.
Filters that are inactive (not polled) for 5min are automatically cleaned up.
- Params: the filter ID (
string) - Response: array containing filter data.
- In case of a block filter, the response is an array of base64 encoded, Amino binary block headers
Example request:
{
"id": 1,
"jsonrpc": "2.0",
"method": "getFilterChanges",
"params": ["c77000bb-700c-41b9-830c-e8b35bdef246"]
}Example response:
{
"result": [
"Cgt2MS4wLjAtcmMuMBIFdGVzdDMYstoZIgsI9teBrQYQ4f+cJzDgH0JICiCOeRC+O7eSKWElYfr3roazF9A23Wvk2AvSWfhU1If41BIkCAISIOmJytoey1P0ZF1/oZUs7Pa7ytV5WJrh41s2PxvWHc4mSiDU0XJ+JFOgK7vm2fVLL29BtwKOGfkv+JxHB1sdgeoSwVog92nrytGOQMQp15Sdl3MG3GaeGdyRMAnaA1rGBVil/QhiIPdp68rRjkDEKdeUnZdzBtxmnhnckTAJ2gNaxgVYpf0IaiC4qGdcWYZSTGBBIl/XuiBtgs1cOjdQQ/BC/N12jhWS7HIggbuwi7zCzwlQP7PCb9EXN2EG7738FHbXIgYPWxBlakiCAShnMXd5cmU0Z3I3bjgyZXpmcGRoZzNueHlwank5Y2FnOXFwa3U1eDZt",
"Cgt2MS4wLjAtcmMuMBIFdGVzdDMYtNoZIgsIs9iBrQYQ7cjnLDDgH0JICiC9pNnvamowMWsgZczqQ6V5J0YoHNYZWCwFvSFV88+j3xIkCAISIATruI4Rl6mfRoS6GzjaE0aCpWZaYNssV1E+8xRlrDStSiAwCZMWNPsjNM/2fOv37CTjuTPqKW71C5xuBnhEVO5a5Fog92nrytGOQMQp15Sdl3MG3GaeGdyRMAnaA1rGBVil/QhiIPdp68rRjkDEKdeUnZdzBtxmnhnckTAJ2gNaxgVYpf0IaiC4qGdcWYZSTGBBIl/XuiBtgs1cOjdQQ/BC/N12jhWS7HIggbuwi7zCzwlQP7PCb9EXN2EG7738FHbXIgYPWxBlakiCAShnMXd5cmU0Z3I3bjgyZXpmcGRoZzNueHlwank5Y2FnOXFwa3U1eDZt"
],
"jsonrpc": "2.0",
"id": 1
}Uninstalls a filter with the given filter ID.
- Params: the filter ID (
string) - Response:
trueif the filter was successfully uninstalled, otherwisefalse(boolean)
Example request:
{
"id": 1,
"jsonrpc": "2.0",
"method": "uninstallFilter",
"params": ["c77000bb-700c-41b9-830c-e8b35bdef246"]
}Example response:
{
"result": true,
"jsonrpc": "2.0",
"id": 1
}Starts a subscription to a specific event. Only available over WS connections.
Available events:
-
newHeads- fires a notification each time a new header is appended to the chain -
Params: the event type [
newHeads] (string) -
Response: the subscription ID (
string) (initial response), then event data (see example below)- For
newHeadsevents, the result is a base64 encoded, Amino binary block header
- For
Since this endpoint is only supported over WS connections, it will write data directly to the client.
Example request (over WS):
{
"id": 1,
"jsonrpc": "2.0",
"method": "subscribe",
"params": ["newHeads"]
}Example initial response (over WS):
{
"result": "b8934e81-5758-4249-8953-da90aa777ef9",
"jsonrpc": "2.0",
"id": 1
}Example response when a newHeads event happens (over WS):
{
"params": {
"result": "CscCCgt2MS4wLjAtcmMuMBIFdGVzdDMYyNoZIgsIld2BrQYQouHxZjDgH0JICiALMxWpa/sfrgj51bcYbSgeqSOz0taKXLKCYPIMlE/xjBIkCAISIBIVcZZiQcME2mT2GnLIhbmGWrixQpiH+cGaI9Iqo6ggSiDj49aFmYNf78eBsV6deyeeebleL38O8Ov8/XSgbCalxVog92nrytGOQMQp15Sdl3MG3GaeGdyRMAnaA1rGBVil/QhiIPdp68rRjkDEKdeUnZdzBtxmnhnckTAJ2gNaxgVYpf0IaiC4qGdcWYZSTGBBIl/XuiBtgs1cOjdQQ/BC/N12jhWS7HIggbuwi7zCzwlQP7PCb9EXN2EG7738FHbXIgYPWxBlakiCAShnMXd5cmU0Z3I3bjgyZXpmcGRoZzNueHlwank5Y2FnOXFwa3U1eDZtGpYCCkgKIAszFalr+x+uCPnVtxhtKB6pI7PS1opcsoJg8gyUT/GMEiQIAhIgEhVxlmJBwwTaZPYacsiFuYZauLFCmIf5wZoj0iqjqCASyQEIAhDG2hkiSAogCzMVqWv7H64I+dW3GG0oHqkjs9LWilyygmDyDJRP8YwSJAgCEiASFXGWYkHDBNpk9hpyyIW5hlq4sUKYh/nBmiPSKqOoICoLCJXdga0GEKLh8WYyKGcxd3lyZTRncjduODJlemZwZGhnM254eXBqeTljYWc5cXBrdTV4Nm1CQH5b0jjU1gW8mC+zuCyIPy5xjrfRMSNEvFcHoOjXzc4aEgcW5cYXamXv0WLw2g5RFim2qmgjHnuQorU1YXnWDgw=",
"subscription": "b8934e81-5758-4249-8953-da90aa777ef9"
},
"jsonrpc": "2.0",
"method": "subscription"
}Cancels an existing subscription so that no further events are sent. Only available over WS connections.
- Params: the subscription ID (
string) - Response: A boolean value indicating if the subscription was canceled successfully (
boolean)
Example request (over WS):
{
"id": 1,
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": ["b8934e81-5758-4249-8953-da90aa777ef9"]
}Example response (over WS):
{
"result": true,
"jsonrpc": "2.0",
"id": 1
}