The Indexer is an API that provides search capabilities for Algorand on-chain data. Data is written by Conduit to populate a PostgreSQL compatible database.
Development is done using the Go Programming Language, the version is specified in the project's go.mod file.
Run make to build Indexer, the binary is located at cmd/algorand-indexer/algorand-indexer.
All recommendations here should be used as a starting point. Further benchmarking should be done to verify performance is acceptible for any application using Indexer.
- Database: Postgres 14
For a simple deployment the following configuration works well:
- Network: Indexer, Conduit, Algod and PostgreSQL should all be on the same network.
- Indexer: 1 CPU and 1GB of ram. Scale up for systems with high query volume.
- Conduit + Algod: 4 CPU and 8 GB of ram.
- Storage: algod follower nodes, 40 GiB, 3000 IOPS minimum.
- Deployments allocating less ram might work in conjunction with GOMEMLIMIT for Algod (and even Conduit). This configuration is not tested, so use with caution and monitor closely.
- Database: When hosted on AWS a
db.r5.xlargeinstance works well.
A database with replication can be used to scale read volume. Configure a single Conduit writer with multiple Indexer readers.
Indexer is part of the sandbox private network configurations, which you can use to get started.
- Search and filter accounts, transactions, assets, and asset balances with many different parameters.
- Pagination of results.
- Enriched transaction and account data:
- Confirmation round (block containing the transaction)
- Confirmation time
- Signature type
- Close amounts
- Create/delete rounds.
- Human readable field names instead of the space optimized protocol level names.
Contributions welcome! Please refer to our CONTRIBUTING document.
Configure Indexer with a PostgreSQL compatible database. Conduit should be used to populate the database and one or more Indexer daemons can be run to serve the API. For further isolation, a readonly user can be created for the database.
~$ algorand-indexer daemon --data-dir /tmp --postgres "user=readonly password=YourPasswordHere {other connection string options for your database}"
The Postgres backend does specifically note the username "readonly" and changes behavior to avoid writing to the database. But the primary benefit is that Postgres can enforce restricted access to this user. This can be configured with:
CREATE USER readonly LOGIN PASSWORD 'YourPasswordHere';
REVOKE ALL ON ALL TABLES IN SCHEMA public FROM readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly;When --token your-token is provided, an authentication header is required. For example:
~$ curl localhost:8980/transactions -H "X-Indexer-API-Token: your-token"
The Indexer has the ability to selectively enable or disable parameters for endpoints. Disabling a "required" parameter will result in the entire endpoint being disabled while disabling an "optional" parameter will cause an error to be returned only if the parameter is provided.
The Indexer has a default set of disabled parameters. To view the disabled parameters issue:
~$ algorand-indexer api-config
This will output ONLY the disabled parameters in a YAML configuration. To view all parameters (both enabled and disabled) issue:
~$ algorand-indexer api-config --all
Below is a snippet of the output from algorand-indexer api-config:
/v2/accounts:
optional:
- currency-greater-than: disabled
- currency-less-than: disabled
/v2/assets/{asset-id}/transactions:
optional:
- note-prefix: disabled
- tx-type: disabled
- sig-type: disabled
- before-time: disabled
- after-time: disabled
- currency-greater-than: disabled
- currency-less-than: disabled
- address-role: disabled
- exclude-close-to: disabled
- rekey-to: disabled
required:
- asset-id: disabled
Seeing this we know that the /v2/accounts endpoint will return an error if either currency-greater-than or currency-less-than is provided. Additionally, because a "required" parameter is provided for /v2/assets/{asset-id}/transactions then we know this entire endpoint is disabled. The optional parameters are provided so that you can understand what else is disabled if you enable all "required" parameters.
NOTE: An empty parameter configuration file results in all parameters being ENABLED.
For more information on disabling parameters see the Disabling Parameters Guide.
The /metrics endpoint is configured with the --metrics-mode option and configures if and how Prometheus formatted metrics are generated.
There are different settings:
| Setting | Description |
|---|---|
| ON | Metrics for each REST endpoint in addition to application metrics. |
| OFF | No metrics endpoint. |
| VERBOSE | Separate metrics for each combination of query parameters. This option should be used with caution, there are many combinations of query parameters which could cause extra memory load depending on usage patterns. |
One can set the maximum number of connections allowed in the local connection pool by using the --max-conn setting. It is recommended to set this number to be below the database server connection pool limit.
If the maximum number of connections/active queries is reached, subsequent connections will wait until a connection becomes available, or timeout according to the read-timeout setting.
Settings can be provided from the command line, a configuration file, or an environment variable
| Command Line Flag (long) | (short) | Config File | Environment Variable |
|---|---|---|---|
| postgres | P | postgres-connection-string | INDEXER_POSTGRES_CONNECTION_STRING |
| data-dir | i | data | INDEXER_DATA |
| pidfile | pidfile | INDEXER_PIDFILE | |
| server | S | server-address | INDEXER_SERVER_ADDRESS |
| token | t | api-token | INDEXER_API_TOKEN |
| metrics-mode | metrics-mode | INDEXER_METRICS_MODE | |
| logfile | f | logfile | INDEXER_LOGFILE |
| loglevel | l | loglevel | INDEXER_LOGLEVEL |
| max-conn | max-conn | INDEXER_MAX_CONN | |
| write-timeout | write-timeout | INDEXER_WRITE_TIMEOUT | |
| read-timeout | read-timeout | INDEXER_READ_TIMEOUT | |
| max-api-resources-per-account | max-api-resources-per-account | INDEXER_MAX_API_RESOURCES_PER_ACCOUNT | |
| max-transactions-limit | max-transactions-limit | INDEXER_MAX_TRANSACTIONS_LIMIT | |
| default-transactions-limit | default-transactions-limit | INDEXER_DEFAULT_TRANSACTIONS_LIMIT | |
| max-accounts-limit | max-accounts-limit | INDEXER_MAX_ACCOUNTS_LIMIT | |
| default-accounts-limit | default-accounts-limit | INDEXER_DEFAULT_ACCOUNTS_LIMIT | |
| max-assets-limit | max-assets-limit | INDEXER_MAX_ASSETS_LIMIT | |
| default-assets-limit | default-assets-limit | INDEXER_DEFAULT_ASSETS_LIMIT | |
| max-balances-limit | max-balances-limit | INDEXER_MAX_BALANCES_LIMIT | |
| default-balances-limit | default-balances-limit | INDEXER_DEFAULT_BALANCES_LIMIT | |
| max-applications-limit | max-applications-limit | INDEXER_MAX_APPLICATIONS_LIMIT | |
| default-applications-limit | default-applications-limit | INDEXER_DEFAULT_APPLICATIONS_LIMIT | |
| enable-all-parameters | enable-all-parameters | INDEXER_ENABLE_ALL_PARAMETERS |
The command line arguments always take priority over the config file and environment variables.
~$ ./algorand-indexer daemon --data-dir /tmp --pidfile /var/lib/algorand/algorand-indexer.pid --postgres "host=mydb.mycloud.com user=postgres password=password dbname=mainnet"`
The Indexer data directory is the location where the Indexer can store and/or load data needed for configuration. The data directory is effectively stateless, so it does not need to be persisted across deployments as long as the configuration is supplied.
It is a required argument for Indexer daemon operation. Supply it to the Indexer via the --data-dir/-i flag.
For more information on the data directory see Indexer Data Directory.
The Indexer will scan the data directory at startup and load certain configuration files if they are present. The files are as follows:
indexer.yml- Indexer Configuration Fileapi_config.yml- API Parameter Enable/Disable Configuration File
NOTE: It is not allowed to supply both the command line flag AND have an auto-loading configuration file in the data directory. Doing so will result in an error.
To see an example of how to use the data directory to load a configuration file check out the Disabling Parameters Guide.
Environment variables are also available to configure indexer. Environment variables override settings in the config file and are overridden by command line arguments.
The same indexer configuration from earlier can be made in bash with the following:
~$ export INDEXER_POSTGRES_CONNECTION_STRING="host=mydb.mycloud.com user=postgres password=password dbname=mainnet"
~$ export INDEXER_PIDFILE="/var/lib/algorand/algorand-indexer.pid"
~$ export INDEXER_DATA="/tmp"
~$ ./algorand-indexer daemon
Default values are placed in the configuration file. They can be overridden with environment variables and command line arguments.
The configuration file must named indexer.yml and placed in the data directory (see above). The filepath may be set on the CLI using --configfile or -c but this functionality is deprecated.
Here is an example indexer.yml file:
postgres-connection-string: "host=mydb.mycloud.com user=postgres password=password dbname=mainnet"
pidfile: "/var/lib/algorand/algorand-indexer.pid"
Place this file in the data directory (/tmp/data-dir in this example) and supply it to the Indexer daemon:
~$ ./algorand-indexer daemon --data-dir /tmp/data-dir
/lib/systemd/system/algorand-indexer.service can be partially overridden by creating /etc/systemd/system/algorand-indexer.service.d/local.conf. The most common things to override will be the command line and pidfile. The overriding local.conf file might be this:
[Service]
ExecStart=
ExecStart=/usr/bin/algorand-indexer daemon --data-dir /tmp --pidfile /var/lib/algorand/algorand-indexer.pid --postgres "host=mydb.mycloud.com user=postgres password=password dbname=mainnet"
PIDFile=/var/lib/algorand/algorand-indexer.pid
The systemd unit file can be found in source at misc/systemd/algorand-indexer.service
Note that the service assumes an algorand group and user. If the Algorand package has already been installed on the same machine, this group and user has already been created. However, if the Indexer is running stand-alone, the group and user will need to be created before starting the daemon:
adduser --system --group --home /var/lib/algorand --no-create-home algorand
Once configured, turn on your daemon with:
sudo systemctl enable algorand-indexer
sudo systemctl start algorand-indexerIf you wish to run multiple indexers on one server under systemd, see the comments in /lib/systemd/system/[email protected] or misc/systemd/[email protected]
If Conduit is deployed with a clustered database using multiple readers behind a load balancer, query discrepancies are possible due to database replication lag. Users should check the current-round response field and be prepared to retry queries when stale data is detected.
Different application workloads will require different custom indices in order to make queries perform well. More information is available in PostgresqlIndexes.md.
The order transactions are returned in depends on whether or not an account address filter is used.
When searching by an account, results are returned most recent first. The intent being that a wallet application would want to display the most recent transactions. A special index is used to make this case performant.
For all other transaction queries, results are returned oldest first. This is because it is the physical order they would normally be written in, so it is going to be faster.
If you were previously using Indexer 2.x you will need to reconfigure your deployment to include Conduit. The data loading component has moved from Indexer 2.x to Conduit.
See the Indexer 2.x to 3.x Migration FAQ for common questions.
Additional info around configuring Conduit can be found here.