NeoFS N3 TestNet Release and First Episode of NeoFS Beginner’s Guide

Following the recent launch of the N3 TestNet, we are excited to announce an updated NeoFS test environment deployment. All users are invited to test out NeoFS and experience its features.

In this initial stage, we have deployed NeoFS on the N3 TestNet so that anyone can take advantage of storing objects on real distributed NeoFS network instances. Simply upload your objects and then access them anywhere through the NeoFS CLI or N3 smart contracts, powered by oracles.

To make it simple for non-developers, we also launched our updated HTTP gateway for anyone. We will show how to use HTTP gateway in the next article.

Soon, S3 gateway service will also be made available; and it will become possible for any user to run a storage node on their own machines. We also expect full support for the NeoFS API in the RC2 version of NeoGUI, providing a more convenient interface for the full range of storage actions.

This article is the first episode of a multi-part series to get familiar with NeoFS and it’s features. We will cover requirements as well as the first set of storage actions like putting and retrieving your first objects.

Enjoy and stay tuned for further updates!

Introduction

NeoFS is a distributed, decentralized object storage platform developed by Neo SPCC.

NeoFS nodes are organized in a peer-to-peer network that takes care of storing and distributing data. Any Neo user may participate in the network and get paid for providing storage resources to other users or store their data in NeoFS and pay a competitive price for it. Data is stored reliably, with the decentralized architecture and flexible storage policies ensuring a transparent data placement process.

NeoFS also offers a native gRPC Application Programming Interface (API) and popular protocol gateways such as AWS S3, HTTP, and FUSE. These allows developers to easily integrate their existing applications without rewriting their code. Using this set of features, it is possible, for example, to use a dApp’s smart contract to manage digital assets that are too large for on-chain storage and manage their access permissions, while allowing users to access that data using a regular web browser or mobile application. NeoFS makes use of the Neo network GAS token as a system currency to pay for storage and earn for providing network storage.

To learn more about the advantages of NeoFS in comparison to other distributed storage networks, check out the comparison articles below:

• Comparison with Filecoin
• Comparison with Storj

NeoFS Components

NeoFS is a part of Neo network. It is managed by Neo Governance procedures and integrated through smart contracts and oracles.

Deposit and withdrawal of GAS tokens to the NeoFS account are secured by the main smart contracts on Neo MainNet, which are also used to provide the list of Inner Ring nodes. At the same time, all NeoFS internal banking and data audit results are located on the NeoFS Neo sidechain. The sidechain also contains NeoFS network service contracts such as the Network Map contract, Container contract, Balance contract, Data Audit contract, and Reputation contract. This approach allows us to avoid the overhead of processing a significant number of NeoFS internal transactions on the Neo blockchain network; it also makes Inner Ring nodes completely anonymous — no need to disclose them to other network nodes.

First steps in NeoFS

Create Wallet

Let’s start with NeoFS СLI description and how to take the first steps.
First of all, you need to create a wallet and request N3 Testnet GAS tokens.

• Get Neo-Go (will be used here) or Neo-CLI to work with N3 Network.
  Neo-Go’s latest releases are available here.

wget https://github.com/nspcc-dev/neo-go/releases/download/v0.94.0/neo-go-linux-amd64 -O neo-go
chmod +x 
./neo-go --version

• Create N3 wallet and check your address.

neo-go wallet init -w new_wallet.json -a

• To get wallet information and WIF, you can use such command as:

neo-go wallet dump -w new_wallet.json
neo-go wallet export -w new_wallet.json --decrypt {ADDRESS}

Now you can request N3 Testnet GAS via the NGD N3 TestNet faucet.

1. Open NEO3 Testnet Faucet and request GAS
2. Check your address here to see that everything is done correctly

Make a Deposit

To make a deposit to the NeoFS account, execute the transfer method to the NeoFS Smart Contract address.

neo-go wallet nep17 transfer -w {wallet} -r {NEO_ENDPOINT} --from {address} --to {NEOFS_CONTRACT_ADDRESS} --token GAS --amount {amount} hash160:{address}

• {wallet} — path to your N3 wallet
• {address} — N3 address
• {NEO_ENDPOINT} — any N3 node (e.g., https://rpc1.n3.nspcc.ru:20331)
• {NEOFS_CONTRACT_ADDRESS} — NeoFS contract address is NadZ8YfvkddivcFFkztZgfwxZyKf1acpRF in the current N3 Testnet version
• {amount} — number of gas tokens to add to the NeoFS balance

Let’s see the example for our wallet:

Now, look at your N3 balance:

As you see, we have transferred 100 GAS + network fee for a smart contract calling.

Check NeoFS balance

To work with NeoFS, install NeoFS CLI.
Get it binary from the latest release here.

wget https://github.com/nspcc-dev/neofs-node/releases/download/v0.18.0/neofs-cli-linux-amd64.tar.gz -O neofs-cli.tar.gz
tar -xf neofs-cli.tar.gz
chmod +x neofs-cli

To get NeoFS balance, execute the command below

neofs-cli -r {NEOFS_ENDPOINT} -k {WIF} accounting balance

• {NEOFS_ENDPOINT} — any NeoFS node (e.g., st1.storage.fs.neo.org:8080)
• {WIF} — private key in hex, WIF, or file path to .key file

For example:

Create your first container

In NeoFS, users put their data into Containers. Containers are like folders in a file system or buckets in Amazon’s S3 but with Storage Policy attached. Storage Policy is set up by the user and defines how objects in this container should be stored.

The policy can use nodes attributes as follows, “Store data in three different countries on two different continents in three copies on nodes with SSD disks and good reputation.” Storage nodes will do their best to keep data in accordance with this policy. Otherwise, they will not get paid for their service.

To create a container, one has to set Storage Policy via neofs-cli command. We will describe the storage policy in more detail in the following articles. For now, we will give a simple example of storing several copies of data on random storage nodes. For instance, to store an object in 3 copies, we should declare such policy as REP 3.

In our example, we will use predefined private, public-read, or public-read-write basic Access Control Lists (ACL) rules. A detailed description of ACL will be available in a separate article soon. In a public container, everyone can read and write objects to the container; in a private container, only the owner of the container can execute read and write operations. In a read-only container, only the owner can write to the container, but anyone can read data from it.

Let’s create a public container.

To do it, we should execute neofs-cli command as follows:

neofs-cli -r {NEOFS_ENDPOINT} -k {WIF} container create --policy "REP 3" --basic-acl public-read --await

It can take some time to process transaction on N3 Testnet.

Container ID for your data is Ec1fAsQbstaVbUHboEEgtFNguCpyBKfTqhcV7NmjVSoJ. Once the container is created, we can upload data to the NeoFS network.

Upload a cat to NeoFS

Let’s get a cute cat picture: cat.png. To put the object in our container, we should execute the neofs-cli command. We can also add some user headers to the object to run search operations by specific filters in the future. We want to set img_type as cat and my_attr as cute.

neofs-cli -r {NEOFS_ENDPOINT} -k {WIF} object put --file {FILE_PATH} --cid {CONTAINER_ID}

Get your cat or share it with friends

To get the object, you can use the command with either any key (in case of public container) or an owner key (in case of private container):

neofs-cli {NEOFS_ENDPOINT} -k {WIF} object get --cid {CONTAINER_ID} --oid {OBJECT_ID} --file {PATH_TO_FILE}

Now open and check out your cat picture!

Search for objects with some specific attributes in the container

To run search operation you can use different filters by meta information of the objects. For example, you can filter objects by attributes declared in the previous steps:

Conclusion

Today, you have taken your first steps in NeoFS and tried the simplest object operations. Our next articles will cover how to use Storage Policies, set complex ACLs and exceptions for them, how to work with S3 gates, and more. Be with us and enjoy your storage experience.

Remember, though, that it is Testnet. If you have any problems, mail us via ops@nspcc.ru or file issues on Github. Also, be aware that depending on the capacity of the test network and production needs, we can periodically clear all data stored in N3 TestNet.

Disclaimer:
The service is designed for individuals 18 years of age or older. As a user of the service, you undertake to follow these terms of service and be responsible for all activities and content you post/upload. In addition to following these terms of service, you are responsible for adhering to all applicable local and national laws. NEO SPCC is not responsible for the content uploaded by users.