NeoFS Storage Node Deploy

5 min readJun 11, 2021

Data in NeoFS is stored on storage nodes that are distributed across the globe. Everyone can be a part of NeoFS storage network the same way as anyone can be a part of N3 network by deploying its node.

Economic model of NeoFS provides two sources of income for storage nodes: basic income and data audit payments. Basic income settlements happen once in epoch for all available objects in storage nodes based on global basic income rate controlled by the committee. Data audit is triggered if data owner creates special storage group objects in the container and they are paid for according to price attribute of storage node. Learn more about it in NeoFS Specification.

In this paper, we will go through all the steps to deploy your storage node in N3 testnet.


  • amd64 Linux machine with public IP address,
  • docker v20.10.2 or older,
  • docker-compose v1.25.5 or older,
  • NeoFS CLI v0.21.1
  • N3 testnet compatible wallet app (we will use neo-go v0.95.2 in our examples).

NeoFS Node v0.21.1 is N3 testnet RC3 compatible.

Prepare keys and wallets

Start our journey by generating a private key for the storage node. You can generate one with NeoFS CLI.

Now there is storage.key file with 32-byte private key, that can be used as a private key of the N3 wallet. Therefore, we can create wallet file and import WIF.

Receive testnet GAS

To deploy node to NeoFS network we need to make a deposit to a storage node address. Deposit is being used to:

  • generate side-chain GAS for storage node, so it can send a bootstrap transaction,
  • filter out “free” nodes that can affect the network.

In the previous step, we generated a wallet for the storage node. N3 testnet has a faucet service which transfers up to 500 GAS to any testnet wallet.

Use wallet address from above and check if assets have been successfully transferred.

Make deposit

Deposit is made by transferring GAS directly to NeoFS contract. In N3 Testnet, NeoFS contract is deployed at the address NadZ8YfvkddivcFFkztZgfwxZyKf1acpRF. You can transfer any amount of GAS under 9000

neo-go wallet nep17 transfer -r -w keys/storage_wallet.json --from NdisEtkGKNsmkQXFTM5NjEiJYiQ1Vxe5iW --to NadZ8YfvkddivcFFkztZgfwxZyKf1acpRF --token GAS --amount 10

You don’t need to use storage wallet to make a deposit to another NeoFS account. You may simply specify script hash of deposit receiver in data argument of NEP17 transaction (add hash160:{address} at the end of neo-go command).

Deposit transaction triggers side-chain GAS emission, so that storage node can use it for bootstrap. Therefore, you do not need to think about any additional transactions or actions to bootstrap the node.

Configure storage node

We have prepared configured image of storage node and docker-compose file for easy setup. Get config directory from neofs-node repository.

In the node_config.env file we need to specify:

  • storage node network address
  • UN/LOCODE attribute.

In the docker-compose file we need to specify:

  • path to storage dir,
  • path to the key file.

Path to storage dir

NeoFS objects will be stored on your machine. By default docker-compose has been configured to store objects in named docker volume neofs_storage. You can specify directory and all objects will be stored there:

- /home/username/neofs/rc3/storage:/storage

Network address

Specify your public IP address or domain name with the open port in NODE_ADDRESS and BIND_ADDRESS config values in the node_config.env file. The first address used for the public announcement in the network map. The second used to open the connection listening socket on your machine. By default keep these addresses the same.


UN/LOCODE attribute

UN/LOCODE is a database of locations used by NeoFS to control data placement geographically. Find suitable LOCODE (from the link above) for your storage node and set it in the node_config.env.


You can check LOCODE by using NeoFS LOCODE database dump.

$ neofs-cli util locode info --db ./locode_db --locode 'RU LED' Country: Russia 
Location: Saint Petersburg (ex Leningrad)
Continent: Europe 5Subdivision: [SPE] Sankt-Peterburg
Coordinates: 59.53, 30.15

Start and maintain storage node

Now, our docker-compose file should look like this.

---version: "2.4"
image: nspccdev/neofs-storage-testnet:0.21.1
container_name: neofs-testnet
env_file: node_config.env
network_mode: host
restart: always
- /home/username/neofs/rc3/storage:/storage
- /home/username/neofs/rc3/keys/storage.key:/node.key
stop_signal: SIGINT
image: victoriametrics/vmagent:v1.61.0
env_file: node_config.env
container_name: vmagent
- '-promscrape.config=/configs/prometheus.yml'
- '-remoteWrite.url='
network_mode: host
restart: always
- ./prometheus.yml:/configs/prometheus.yml

In testnet we collect storage metrics with vmagent to improve network performance before N3 release.

Start up

To start the storage node in the background, run this command:

$ docker-compose up -d

That’s it! It takes about an hour to enter network map. You can monitor status with NeoFS CLI.

$ neofs-cli control healthcheck -k storage.key -r
Network status: ONLINE
Health status: READY
$ neofs-cli netmap snapshot -k storage.key -r


Node’s logs are available in docker-compose.

$ docker logs neofs-testnet

Default log level is INFO but you can set it to debug in docker-compose.



The best way to shut down the node is to move it to offline mode and then stop docker image. To send node to offline mode use NeoFS CLI.


In this article, we have covered the most basic node setup. With these steps, you will be able to become a part of NeoFS storage network in N3 testnet. Provide storage resources to increase network capacity and use it for your data and dApps with N3 Oracles and NeoFS HTTP Gates.

In our next articles, we will cover economic model overview for storage node owners and data providers with examples of how to spend, earn and withdraw GAS back to your main chain wallet.

Stay tuned and we’ll see you soon at the upcoming hackathon!