Skip to main content

Local Proxy to Remote Solana


The Proxy local testing tutorial describes how to perform testing with a local Proxy to a local Solana node. This option can be useful for developers who want to debug their Solidity contracts by hosting both Proxy and Solana nodes locally. This page provides a tutorial that demonstrates how to transact from a local Proxy to a public, remote Solana.


Network configuration

  • The target Solana cluster is accessed via the locally-hosted Proxy.
  • Solana Testnet/Devnet/Mainnet is used, and the Proxy interacts with it through Neon EVM.

Set up a local Proxy

First, set up and host a Proxy locally as per the following steps. After executing these commands, the Proxy is available at http://localhost:9090/solana. This address and port are set by default.

Step 1: Docker

Docker images themselves are never "started" and never "running". The docker run command takes the Docker image as a template and produces a container from it. Before starting your Proxy container, you need to start service containers.

Make sure that you have a daemon running by executing the following command:

docker info

If you see something like this:

Can't connect to the Docker daemon at <docker.sock>. Is the docker daemon running?

run the daemon first:

sudo systemctl start docker

Step 2: Run the Database, Indexer, and Proxy services

In this step, you will create the services necessary for the function of the Proxy (including Database and Indexer services), as well as the Proxy service itself. These services, whose functions follow, are controlled by a docker-compose.yml file.

Database Services

This container aims to handle the database that stores all the relevant Ethereum processing metadata linked to each other: transactions, blocks, receipts, accounts, etc. This data is consumed by the Indexer service.

Currently, Neon EVM proxies are hard coded to work with PostgreSQL. To connect the Proxy to a database, you need to start a PostgreSQL container. The default settings are hard coded in the following docker-compose.yml file. If you want to use your Proxy with other settings, you need to register as an Operator so that Neon EVM can recognize your keys.

Only authorized Operators can change the settings of these parameters. Learn more about operating a Neon Proxy

Indexer service

The Indexer service indexes all the relevant Ethereum processing metadata consisting of signatures, transactions, blocks, receipts, accounts, etc. It gathers all this data from the Solana blockchain, filtering them by the EVM contract address. It enables us to provide our users with the Ethereum API.

Proxy service

The Proxy service is a core service that allows Ethereum-like transactions to be processed on Solana, taking full advantage of Solana-native functionality, including the ability to execute transactions in parallel.

The Neon EVM address is registered inside neonlabsorg/proxy, so the Proxy knows which Neon EVM is running in the Solana cluster. After executing this command, the Proxy will be available at http://localhost:9090/solana. This address and port are set by default.

Create and run services with Docker Compose

In order to create and run these services:

  1. Create a "keys" folder and put your allowlisted key into it. Note that the file with the Operator key should be named id.json.
mkdir keys
  1. Set the following environment variables
    • EVM_LOADER, i.e. the contract address for Neon EVM
      • For Devnet/Testnet, use: eeLSJgWzzxrqKv1UxtRVVH8FX3qCQWUs9QuAjJpETGU
      • For Mainnet, use: NeonVMyRX5GbCrsAHnUwx1nYYoJAtskU1bWUo6JGNyG
    • REVISION - neon proxy revision

For example,

export SOLANA_URL=
export REVISION=latest
  1. Download the docker-compose file. This file should be placed in the same folder with the keys/ directory.
  1. Start the local environment.
docker-compose -f docker-compose-remote-solana.yml up postgres dbcreation proxy indexer -d

If you want to destroy the local environment, run the following command:

docker-compose -f docker-compose-remote-solana.yml down

The console output should look like this:

Creating postgres ... done
Creating dbcreation ... done
Creating indexer ... done
Creating proxy ... done

Connect to a Solana cluster RPC endpoint

A Proxy connects to a public Solana cluster RPC endpoint depending on the SOLANA_URL value set. The following table shows the endpoint value that's set automatically based on the value of the CONFIG flag.

RPC endpoints


To use a different endpoint, you need to specify the variable -e SOLANA_URL='http://<Solana node RPC endpoint>' on the command line. For example, to use Devnet, add the flag -e SOLANA_URL=''.

When a Proxy is deployed, it generates a wallet containing a key pair. If you don't need the new wallet and want to use the keys you already have, you need to specify the path to your wallet on the command line.

Command Line Options

  • ~/.config/solana/id.json — absolute path to your key pair file stored locally
  • --name proxy — specifies the Proxy name
Was this page helpful?