Developer FAQs

Answers to common questions about running, customizing, and integrating with OpenScan.AI. If your question isn’t covered here, reach out via the contact form.

How do I run my own OpenScan.AI explorer?

The easiest way is Explorer-as-a-Service: the OpenScan.AI team hosts and manages your instance for you. Get in touch via the contact form. If you prefer to self-host, the available methods are listed in Deployment.

How do I speed up my self-hosted instance?

OpenScan.AI can be resource intensive. If your instance is running slowly:

  • Clear the cache — the application cache is cleared on restart by running: sudo systemctl restart explorer.service
  • Increase the memory limit for indexers using the INDEXER_MEMORY_LIMIT ENV variable if indexing is slow.
  • Increase the number of CPUs if CPU is running at 100% on the web app server.
  • Increase the memory if memory consumption is high on the web app server.
  • Increase the number of CPUs and/or the memory on the database server if consumption is high.

Instructions for accessing and upgrading CPUs/memory will differ based on your setup. If you are running OpenScan.AI on AWS, these settings can be accessed through your AWS services portal.

I want to use the latest version, how do I download it?

Clone the relevant repository from github.com/OpenScanAI and check out the release tag you want:

Terminal window
git clone https://github.com/OpenScanAI/<repository>.git -b <version>

How do I customize the coin symbol / name?

Exchange rates coin name

Specify the coin name for the exchange rates fetcher with the COIN ENV variable. OpenScan.AI uses the COIN environment variable to pull the associated market data from the CoinMarketCap or CoinGecko API and provide pricing data throughout the application.

Displayed coin symbol

To set the displayed coin symbol, the instance maintainer should set the COIN_NAME runtime environment variable:

Terminal window
export COIN_NAME=XDC

How do I manage deployment with AWS CodeDeploy?

  1. Visit CodeDeploy in AWS. You will see a list of your deployments. Select the deployment id to view details: https://console.aws.amazon.com/codesuite/codedeploy/deployments?region=us-east-1
  2. Deployment status consists of several steps. Once step 2 is complete (the application is installed on replacement instances), you manually reroute traffic. Click the Reroute traffic button to initiate.
  3. Once traffic is rerouted, you’ll be asked to terminate the original instance. Click the Terminate button to initiate.
  4. Once complete, use the public DNS address of the Amazon EC2 instance to view the explorer in a web browser. (To get the public DNS value, choose your Amazon EC2 instance in the Amazon EC2 console and look for the value in Public DNS in the Description tab).

What’s the best way to deploy to AWS?

Currently the best existing way is through Docker Compose. A Kubernetes deployment is also available for larger production setups.

How do I replace missing assets/version numbers?

Missing assets

  1. Find the public IP of the corresponding instance in the EC2 → Instances section of the AWS Dashboard.
  2. Connect to the host via SSH: ssh -i <host.pem> ec2-user@<public_ip>, where <host.pem> is the host’s private key file and <public_ip> is the public IP of the host.
  3. Go to the assets folder: cd /opt/app/apps/block_scout_web/priv/static
  4. Add missing assets there or to the ./images folder depending on what is missing, then refresh the explorer page. For example, if favicon.ico is missing in ./images, just copy it from the root assets folder: cp favicon.ico ./images/.

Missing version in the footer

The app version number should be in the footer of the instance.

  1. Connect to the host via SSH as above.
  2. Go to the layout folder: /opt/app/apps/block_scout_web/lib/block_scout_web/templates/layout
  3. Open the _footer.html.eex footer template in your favorite text editor, e.g. nano ./_footer.html.eex, and fix the line <% version = version() %> (near the bottom of the file) with a hardcoded new version, for example <% version = 'v1.3.3-beta' %>, and save.
  4. Restart the instance with sudo systemctl restart explorer.service.

How do I fix the Gettext.Error?

You may receive this error after making changes to a specific application in the umbrella project:

(Gettext.Error) translation with msgid '...<msg_here>...' has a non-empty msgstr

To update gettext, run the following command in the app’s folder where the changes were made:

  1. Go to the ./apps/name_of_app folder where the changes were made.
  2. Run mix gettext.extract --merge
  3. Repeat for other app folders as required.

More information on Gettext is available here.

How do I update the UI?

For updates like adding elements/links etc. you will need to change .eex templates. When changing .eex templates you don’t need to rebuild: run the application in dev mode (MIX_ENV=dev), change the template, and you’ll see changes on the fly. When changing js/scss while running the application, you need to run mix phx.digest to apply the changes.

How can I view smart contracts using RPC?

Use the JSON-RPC listcontracts endpoint. For example, to view verified contracts on XDCScan, use the following query (pagination is available):

Terminal window
curl -X GET \
  "https://xdcscan.io/api?module=contract&action=listcontracts&page=1&offset=50&filter=verified" \
  -H "accept: application/json"

Why are Market Cap/Token Price stats wrong?

One common cause is the CoinGecko API refusing requests without an API key. Configure a CoinGecko (or CoinMarketCap) API key on your instance via the exchange-rate environment variables to restore price and market-cap data.

How do I verify contracts via an API?

There are several ways:

How do I disable exchange rates?

Change the Explorer.ExchangeRates variable from enabled: true to enabled: false:

config :explorer, Explorer.ExchangeRates, enabled: false, store: :ets

How can I migrate verified contracts between databases?

You may want to do this if you are creating a new instance or resyncing a new node.

  1. Back up the smart_contracts table.
  2. Restore this table following the resync.

Can I set the RPC variable to a normal http(s) url?

Yes you can. The ETHEREUM_JSONRPC_HTTP_URL variable can be set to any URL — it does not need to be localhost. The client variant env variable (ETHEREUM_JSONRPC_VARIANT) should be specified in either case.

Do I need to enable websockets?

No, it is not required. If websockets are disabled, leave the ETHEREUM_JSONRPC_WS_URL env var empty or unset it.

How do I fix the error “execution timeout at pushGasToTopCall”?

Try increasing the time for the ETHEREUM_JSONRPC_DEBUG_TRACE_TRANSACTION_TIMEOUT ENV variable. The default is 5 seconds.

How do I fix the Unknown Private Network error?

In a self-hosted or locally deployed instance, when attempting a write transaction on a verified contract, the following errors may appear:

Unauthorized

“You connected to Unknown Private Network chain in the wallet, but the current instance of the explorer is for Unknown Private Network chain”

“No ‘from’ address specified in neither the given options, nor the default options.”

To troubleshoot:

  • Check that you set the correct CHAIN_ID env variable (for the XDC Network this is 50).
  • Check the correct value for NETWORK_ID.

Is there an env variable for the favicon?

Yes, the FAVICON_MASTER_URL ENV accepts a URL to a jpg/png/svg image.

Does a self-hosted OpenScan.AI explorer support ERC-1155?

Yes, OpenScan.AI supports ERC-20, ERC-721, ERC-1155, and ERC-404 token standards. See Token Support.

What Linux distro do you recommend for manual deployment?

Ubuntu 24.04 — it is the distribution exercised by our CI.

Is there a way to step through the code (debugging) using VS Code?

We recommend using ElixirLS, which provides Elixir support and a debugger.

I’d like to customize OpenScan.AI. Is there any docs or tutorial on that?

A large amount of customization is available by setting environment variables — see Environment Variables and the backend ENV reference.

Can I use a Cryptorank API v2 key for price fetching?

No, the exchange-rate fetcher uses a dedicated endpoint. Contact Cryptorank for an API key.

How do I connect to a local RPC node from a Docker Compose instance?

Use host.docker.internal instead of 127.0.0.1, e.g. http://host.docker.internal:8545/.

The footer can be customized with the NEXT_PUBLIC_FOOTER_LINKS frontend ENV variable.

Edit page on github
User FAQ