diff --git a/docs/developing/dev_environment/solana_cluster/cluster_installation.md b/docs/developing/dev_environment/solana_cluster/cluster_installation.md index a61718ca..0dc3e492 100644 --- a/docs/developing/dev_environment/solana_cluster/cluster_installation.md +++ b/docs/developing/dev_environment/solana_cluster/cluster_installation.md @@ -1,47 +1,372 @@ --- -title: Setting up local Solana Cluster +title: Setting Up the Local Neon EVM Environment --- -*This guide describes how to install, configure and test the local Solana cluster with Neon EVM on-board. It helps new developers to create their own environment and run Ethereum programs, wrapped into Neon EVM. All you need is to follow this guide step by step.* +*This step-by-step guide describes how to install, configure, and test the local Solana cluster with Neon EVM onboard. It will help new developers create their own environment and run Ethereum programs wrapped into the Neon EVM.* -The [Neon EVM](https://neon-labs.org/) is a solution that performs transaction execution outside layer 1. The development process can be run on any modern Linux or Mac system, though this document is based on Ubuntu 20.04 experience. +The [Neon EVM](https://neon-labs.org/) is a solution that performs transaction execution outside layer 1. The development process can be run on any modern Linux or Mac system, though this document is based on an Ubuntu 20.04 experience. + +All the services in the **`Neon EVM environment`** presented by the docker-compose configuration files can be interchangeably substituted with their experimental versions in order to develop and test each service independently. To resolve issues, the Neon engineer has to be able to replace any service with a customized one according to the current requirements. You are welcome to change the following `docker-compose` configuration files based on your needs. Also, you can bring them altogether in a single docker-compose file, it is important to provide dependencies according to the following sequence. + +Before you start to build your local environment, make sure you have all the [prerequisites](#prerequisites). ## Prerequisites -* [Docker](https://docs.docker.com/engine/install/ubuntu/) -* [Docker-compose](https://docs.docker.com/compose/install/) -* A Chromium-based browser for [Metamask](https://metamask.io/) and [Remix](https://remix.ethereum.org/) -* [Node.js/npm](https://www.w3schools.com/nodejs/nodejs_npm.asp) +- **Docker** — for docker installation, please follow instructions at: https://docs.docker.com/engine/install/ubuntu/ +- **Docker Compose** — Docker Compose is required to start up containers at: https://docs.docker.com/compose/install/ +- **Solana Tool Suite** — for interaction with Solana, we need to install Solana CLI Tools: https://docs.solana.com/ru/cli/install-solana-cli-tools +- A Chromium-based **browser** — for [MetaMask](https://metamask.io/) and [Remix](https://remix.ethereum.org/) +* **Node package manager** — [Node.js/npm](https://www.w3schools.com/nodejs/nodejs_npm.asp) to interact with he Neon EVM with [Web3](https://www.npmjs.com/package/web3) and [Eth](https://www.npmjs.com/package/web3-eth) modules. -## Setting up the Solana Cluster +## Setting up the Neon Local Workspace Environment -All you need to have the Solana Cluster with Neon EVM on board is to deploy multi-container environment with [the following compose file](docker-compose-local.yml) and of course you should have `docker` and `docker-container` apps installed. +Currently, the most flexible way is to use the set of independent docker containers sharing the common external network. To create the network called **`local`** that will be used over the docker containers, just input the following command: -```sh -$ docker-compose -f docker-compose-local.yml up -d -Creating solana ... done -Creating postgres ... done -Creating evm_loader ... done -Creating proxy ... done -$ ls ./solana_state -ledger run +```bash +docker network create local ``` -Once you deploy the environment you'll have the Solana RPC endpoint working from the docker container at the 9090 port. -The folder named "solana_state" will be created as well, it contains the solana's ledger to keep the state over restarts. If you need to reset the ledger just remove this folder and it'll be recreated after next-time running docker-compose. +If you want to bind some ports from the service to the host machine to be able to connect them and work with a service independently, just extend a `docker-compose.yml` configurations with the `ports` instruction. For example, you can bind the Solana (8899, 8900)- or Proxy (9090)-related ports to the host machine this way. + +After establishing the local network, it's time to start the following containers: + +
1. Solana validator service + +This service presents the Solana validator running inside the container + +Once you deploy the environment, you'll have the Solana RPC endpoint working from the docker container at the 9090 port. The folder named "solana_state" will be created as well. It contains the Solana ledger to keep the state over restarts. If you need to reset the ledger, just remove this folder and it'll be recreated the next time you run docker-compose. + +#### docker-compose.yml + + version: "3" + services: + solana: + container_name: solana + image: neonlabsorg/solana:${SOLANA_REVISION:-v1.9.12-testnet} + environment: + SOLANA_URL: http://solana:8899 + RUST_LOG: solana_runtime::system_instruction_processor=trace,solana_runtime::message_processor=debug,solana_bpf_loader=debug,solana_rbpf=debug + expose: + - 8899 + - 8900 + networks: + - net + healthcheck: + test: [ CMD-SHELL, "solana cluster-version -u http://solana:8899" ] + interval: 5s + timeout: 10s + retries: 10 + start_period: 10s + volumes: + - "./solana_state:/opt/solana/config/" + + networks: + net: + external: yes + name: local + +#### How to run it in bash + + $ docker-compose -f solana/docker-compose.yml pull + $ docker-compose -f solana/docker-compose.yml up -d + +
+ +
2. EVM loader service + +This container helps deploy the Neon EVM base contract onto Solana that listens for incoming connections on the port 8899 + +#### docker-compose.yml + + version: "3" + + services: + evm_loader: + container_name: evm_loader + image: neonlabsorg/evm_loader:latest + environment: + - SOLANA_URL=http://solana:8899 + networks: + - net + command: bash -c "create-test-accounts.sh 1 && deploy-evm.sh && /opt/spl-token create-account HPsV9Deocecw3GeZv1FkAPNCBRfuVyfw9MMwjwRe1xaU && /opt/spl-token mint HPsV9Deocecw3GeZv1FkAPNCBRfuVyfw9MMwjwRe1xaU 1000000000 --owner /opt/ evm_loader-keypair.json -- HX14J4Pp9CgSbWP13Dtpm8VLJpNxMYffLtRCRGsx7Edv" + + networks: + net: + external: yes + name: local + +#### How to Run It in Bash + + $ docker-compose -f evm-loader/docker-compose.yml pull + $ docker-compose -f evm-loader/docker-compose.yml up +
+ +
3. 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. + +#### docker-compose.yml + + version: "3" + + services: + postgres: + container_name: postgres + image: postgres:14.0 + command: postgres -c 'max_connections=1000' + environment: + POSTGRES_DB: neon-db + POSTGRES_USER: neon-proxy + POSTGRES_PASSWORD: neon-proxy-pass + hostname: postgres + healthcheck: + test: [ CMD-SHELL, "pg_isready -h postgres -p 5432" ] + interval: 5s + timeout: 10s + retries: 10 + start_period: 5s + networks: + - net + ports: + - "127.0.0.1:5432:5432" + + dbcreation: + container_name: dbcreation + image: neonlabsorg/proxy:latest + environment: + SOLANA_URL: http://solana:8899 + POSTGRES_DB: neon-db + POSTGRES_USER: neon-proxy + POSTGRES_PASSWORD: neon-proxy-pass + POSTGRES_HOST: postgres + entrypoint: proxy/run-dbcreation.sh + networks: + - net + depends_on: + postgres: + condition: service_healthy + + + networks: + net: + external: yes + name: local + +#### How to Run It in Bash + + $ docker-compose -f postgres/docker-compose.yml pull + $ docker-compose -f postgres/docker-compose.yml up -d + +
+ + +
4. 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 also makes it possible to provide our users with the Ethereum API according to the data provided by the whole known operators. + +#### docker-compose.yml + + version: "3" + + services: + indexer: + container_name: indexer + image: neonlabsorg/proxy:latest + environment: + SOLANA_URL: http://solana:8899 + POSTGRES_DB: neon-db + POSTGRES_USER: neon-proxy + POSTGRES_HOST: postgres + POSTGRES_PASSWORD: neon-proxy-pass + CONFIG: ci + START_SLOT: LATEST + hostname: indexer + entrypoint: proxy/run-indexer.sh + networks: + - net + + networks: + net: + external: yes + name: local + +#### How To Run It in Bash + + $ docker-compose -f indexer/docker-compose.yml pull + $ docker-compose -f indexer/docker-compose.yml up -d + +
+ +
5. Proxy service +The Proxy service is a core service that allows Ethereum-like transactions to be processed on [Solana](https://docs.solana.com/introduction), taking full advantage of the functionality native to Solana, including the ability to execute transactions in parallel. It's available on 9090 port. + +#### docker-compose.yml + + version: "3" + + services: + proxy: + container_name: proxy + image: neonlabsorg/proxy:latest + environment: + - POSTGRES_DB=neon-db + - POSTGRES_USER=neon-proxy + - POSTGRES_PASSWORD=neon-proxy-pass + - POSTGRES_HOST=postgres + - SOLANA_URL=http://solana:8899 + - EXTRA_GAS=5000 + - EVM_LOADER=53DfF883gyixYNXnM7s5xhdeyV8mVk9T4i2hGV9vG9io + - CONFIG=ci + - LOG_NEON_CLI_DEBUG=YES + - USE_COMBINED_START_CONTINUE=yes + - NEON_CLI_TIMEOUT=60 + - NEW_USER_AIRDROP_AMOUNT=0 + - WRITE_TRANSACTION_COST_IN_DB=NO + - START_SLOT=LATEST + - PERM_ACCOUNT_LIMIT=16 + hostname: proxy + entrypoint: ./proxy/run-proxy.sh + ports: + - "9090:9090" + expose: + - "9090" + networks: + - net + + networks: + net: + external: yes + name: local + +#### How to Run It in Bash + + $ docker-compose -f proxy/docker-compose.yml pull + $ docker-compose -f proxy/docker-compose.yml up -d + +
+ + +
6. Faucet service +The Faucet service provides the liquidity in `NEON` to all the accounts that are mentioned in the incoming requests. + +#### docker-compose.yml + + version: "3" + + services: + + faucet: + container_name: faucet + image: neonlabsorg/faucet:local + environment: + - FAUCET_RPC_BIND=0.0.0.0 + - FAUCET_RPC_PORT=3333 + - SOLANA_URL=http://solana:8899 + - NEON_ETH_MAX_AMOUNT=50000 + - EVM_LOADER=53DfF883gyixYNXnM7s5xhdeyV8mVk9T4i2hGV9vG9io + - FAUCET_RPC_ALLOWED_ORIGINS=["https://neonswap.live"] + - FAUCET_WEB3_ENABLE=false + - FAUCET_SOLANA_ENABLE=true + - NEON_OPERATOR_KEYFILE=/opt/faucet/id.json + - SOLANA_COMMITMENT=confirmed + entrypoint: /opt/faucet/faucet --config /opt/proxy/faucet.conf run + ports: + - 3333:3333 + expose: + - "3333" + networks: + - net + + networks: + net: + external: yes + name: local + +#### How to Run It in Bash + + $ docker-compose -f faucet/docker-compose.yml pull + $ docker-compose -f faucet/docker-compose.yml up -d + +
+ + +
7. Full test suite service + +The full test suite provides in general the [OpenZeppelin tests](https://docs.openzeppelin.com/learn/writing-automated-tests) to make sure the infrastructure deployed by this guide works properly. At the end, the `full test suite` outputs the result in the following form: + + Full test passing - 1743 + Full test threshold - 1700 + Check if 1743 is greater or equal 1700 + +#### full_test_suite/docker-compose.yml + + version: "3" + + services: + + full_test_suite: + container_name: ${FTS_CONTAINER_NAME:-full_test_suite} + image: ${FTS_IMAGE:-neonlabsorg/full_test_suite:develop} + entrypoint: ./run-full-test-suite.sh 2>/dev/null + environment: + - NETWORK_NAME=${NETWORK_NAME} + - PROXY_URL=${PROXY_URL} + - NETWORK_ID=${NETWORK_ID} + - REQUEST_AMOUNT=${REQUEST_AMOUNT} + - FAUCET_URL=${FAUCET_URL} + - USE_FAUCET=${USE_FAUCET} + - SOLANA_URL=${SOLANA_URL} + - FTS_USERS_NUMBER=${FTS_USERS_NUMBER} + - FTS_JOBS_NUMBER=${FTS_JOBS_NUMBER} + + networks: + - net + + networks: + net: + external: yes + name: local + +#### full_test_suite/local.env + + NETWORK_NAME=local + PROXY_URL=http://proxy:9090/solana + NETWORK_ID=111 + REQUEST_AMOUNT=20000 + FAUCET_URL=http://faucet:3333/request_neon + USE_FAUCET=true + SOLANA_URL=http://solana:8899 + FTS_USERS_NUMBER=15 + FTS_JOBS_NUMBER=8 + +#### How to Run It in Bash + + $ docker-compose -f full_test_suite/docker-compose.yml pull + $ docker-compose -f full_test_suite/docker-compose.yml --env-file full_test_suite/local.env up + +
## Logs -To look for events or errors that you can be interested in just run the `docker logs` for either `solana` or `proxy` container: +After following the previous steps, you will have four running containers for the Neon EVM local environment: **solana**, **`postgres`**, **`proxy`**, **`indexer`**: + +``` +49c864f47ccd neonlabsorg/solana:v1.9.12-testnet "./run.sh" About an hour ago Up About an hour (healthy) 8003/udp, 0.0.0.0:8899-8900->8899-8900/tcp, :::8899-8900->8899-8900/tcp, 9900/tcp solana +92f6b4492894 neonlabsorg/proxy:latest "./proxy/run-proxy.sh" 46 hours ago Up About an hour 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp proxy +932d4d860629 neonlabsorg/proxy:latest "proxy/run-indexer.sh" 46 hours ago Up About an hour 9090/tcp indexer +5a7df37069fc postgres:14.0 "docker-entrypoint.s…" 47 hours ago Up About an hour (healthy) 127.0.0.1:5432->5432/tcp postgres +``` + +To look for events or errors, just run the `docker logs` for either the `solana` or `proxy` container: ```sh $ docker logs -f solana 2>&1 | grep -v "Program Vote111111111111111111111111111111111111111" $ docker logs -f proxy ``` -## Remix and Metamask with Neon EVM +## Remix and MetaMask with the Neon EVM -Setup the "Metamask" Chromium extension to connect to the proxy via Custom RPC at `http://localhost:9090/solana`. The following image describes how to set up the local Solana connection: +Set up the "MetaMask" Chromium extension to connect to the proxy via Custom RPC at `http://localhost:9090/solana`. The following image describes how to set up the local Solana connection:
@@ -49,9 +374,9 @@ Setup the "Metamask" Chromium extension to connect to the proxy via Custom RPC a
-Worth remarking is that once you create or import new account in metamask there some NEONs will be airdropped onto it. +Note: Once you create or import a new account in MetaMask, some NEONs will be airdropped into it. -Open Remix (also in Chromium) and select `Injected Web3` environment. You can deploy EVM-wrapped smart contracts on Solana and invoke instructions: +Open Remix (also in Chromium) and select `Injected Web3` environment. You can deploy EVM-wrapped smart contracts on Solana and input these instructions:
@@ -59,13 +384,11 @@ Open Remix (also in Chromium) and select `Injected Web3` environment. You can de
+## Truffle Suite with Neon EVM +Truffle is a popular platform to deploy and test Solidity programs. This section shows you how to check the compatibility of the Neon EVM and the Truffle suite. -## Truffle suite with Neon EVM - -Truffle is a popular platform to deploy and test solidity programs. This section is to check Neon EVM and truffle suite compatibility. - -In the new terminal, create a truffle project and deploy contracts into EVM: +In the new terminal, create a Truffle project and deploy contracts into EVM: ```sh $ sudo npm install -g truffle @@ -74,9 +397,9 @@ $ truffle init $ npm install web3 @truffle/hdwallet-provider ``` -### Common truffle settings +### Common Truffle Settings -Put your `truffle-config.js` into the truffle root: +Put your `truffle-config.js` into the Truffle root: ```sh $ echo 'const Web3 = require("web3"); @@ -107,7 +430,7 @@ module.exports = { };' > truffle-config.js ``` -### Contract creating +### Contract Creation Create a trivial contract at `contracts/Storage.sol`: @@ -131,7 +454,7 @@ contract Storage { ### Testing -You can now start testing `Storage` invocations with truffle facility: +You can now start testing `Storage` invocations with Truffle facility: ```sh $ echo 'const Storage = artifacts.require("Storage"); @@ -154,13 +477,13 @@ contract("Storage", (accounts) => { $ truffle test test/Storage.test.js --network solana ``` -### Possible problems +### Possible Problems -If for some reasons you remove the Solana container and run it again then all related accounts, stored in foreign systems, get invalid from that moment. That's why you need to re-run proxy container and reset the state of Metamask and truffle as well, to make all relations consistent. +If for some reasons you remove the Solana container and run it again, then all related accounts stored in foreign systems get invalid from that moment. That's why you need to re-run the proxy container and reset the state of MetaMask and Truffle as well, to make all relations consistent. -To reset the metamask state, follow the steps `Settings`, `Advanced`, `Reset Account`, . +To reset the MetaMask state, follow the steps at `Settings`, `Advanced`, `Reset Account`. -The truffle state can be reset by redeploying in the following way: +The Truffle state can be reset by redeploying it in the following way: ```sh $ truffle compile --network solana --reset @@ -168,4 +491,4 @@ $ truffle compile --network solana --reset --- -*Welcome to deploy your solidity programs on [Solana](https://solana.com) driven [Neon EVM](https://neon-labs.org/)*. +*Deploy your Solidity programs on the [Solana](https://solana.com)-driven [Neon EVM](https://neon-labs.org/)*. diff --git a/docs/developing/dev_environment/solana_cluster/docker-compose-local.yml.md b/docs/developing/dev_environment/solana_cluster/docker-compose-local.yml.md deleted file mode 100644 index a54bbdf8..00000000 --- a/docs/developing/dev_environment/solana_cluster/docker-compose-local.yml.md +++ /dev/null @@ -1,100 +0,0 @@ -```yml -version: "3" - -services: - solana: - container_name: solana - image: neonlabsorg/solana:v1.7.9-testnet - environment: - SOLANA_URL: http://solana:8899 - RUST_LOG: solana_runtime::system_instruction_processor=trace,solana_runtime::message_processor=debug,solana_bpf_loader=debug,solana_rbpf=debug - networks: - - net - healthcheck: - test: [ CMD-SHELL, "solana cluster-version -u http://solana:8899" ] - interval: 5s - timeout: 10s - retries: 10 - start_period: 10s - volumes: - - "./solana_state:/opt/solana/config/" - - evm_loader: - container_name: evm_loader - image: neonlabsorg/evm_loader:latest - environment: - - SOLANA_URL=http://solana:8899 - networks: - - net - depends_on: - solana: - condition: service_healthy - command: bash -c "create-test-accounts.sh 1 && deploy-evm.sh" - - postgres: - container_name: postgres - image: postgres:14.0 - command: postgres -c 'max_connections=1000' - environment: - POSTGRES_DB: neon-db - POSTGRES_USER: neon-proxy - POSTGRES_PASSWORD: neon-proxy-pass - hostname: postgres - healthcheck: - test: [ CMD-SHELL, "pg_isready -h postgres -p 5432" ] - interval: 5s - timeout: 10s - retries: 10 - start_period: 5s - networks: - - net - - proxy: - container_name: proxy - image: neonlabsorg/proxy:latest - environment: - SOLANA_URL: http://solana:8899 - POSTGRES_DB: neon-db - POSTGRES_USER: neon-proxy - POSTGRES_PASSWORD: neon-proxy-pass - POSTGRES_HOST: postgres - NEW_USER_AIRDROP_AMOUNT: 100 - LOG_SENDING_SOLANA_TRANSACTION: "YES" - LOG_NEON_CLI_DEBUG: "YES" - EVM_LOADER: 53DfF883gyixYNXnM7s5xhdeyV8mVk9T4i2hGV9vG9io - depends_on: - postgres: - condition: service_healthy - evm_loader: - condition: service_completed_successfully - ports: - - 127.0.0.1:9090:9090 - networks: - - net - entrypoint: proxy/run-test-proxy.sh - - indexer: - container_name: indexer - image: neonlabsorg/proxy:latest - environment: - SOLANA_URL: http://solana:8899 - POSTGRES_DB: neon-db - POSTGRES_USER: neon-proxy - POSTGRES_PASSWORD: neon-proxy-pass - POSTGRES_HOST: postgres - WRITE_TRANSACTION_COST_IN_DB: Nope - CONFIG: local - hostname: indexer - depends_on: - postgres: - condition: service_healthy - evm_loader: - condition: service_completed_successfully - networks: - - net - entrypoint: proxy/run-indexer.sh - -networks: - net: -``` - diff --git a/sidebars.js b/sidebars.js index e2c259f6..b5455d91 100644 --- a/sidebars.js +++ b/sidebars.js @@ -38,7 +38,7 @@ module.exports = { label: 'Setting up environment', items: [ 'developing/dev_environment/choosing_proxy', 'developing/dev_environment/connect_to_solana_via_proxy', - 'developing/dev_environment/solana_cluster/cluster_installation' ] + { type: 'doc', label: 'Local Neon EVM environment', id: 'developing/dev_environment/solana_cluster/cluster_installation' } ] }, { type: 'category', label: 'Deploying dApps', @@ -51,7 +51,7 @@ module.exports = { }, { type: 'category', label: 'Using Utilities', - items: [ { type: 'link', label: 'NeonScan', href: "https://neonscan.'org/" }, + items: [ { type: 'link', label: 'NeonScan', href: "https://neonscan.org/" }, 'developing/utilities/neonpass', 'developing/utilities/neonswap' ] } ]