NeoFS N3 oracle

This article is a new episode of a multi-part series to get familiar with NeoFS and its features. Today we will look at N3 oracles and how NeoFS objects may be accessed from smart contracts. This article consists of two parts. The first part describes oracle concepts and NeoFS integration. The latter part is an enhanced example of NeoFS N3 oracle usage for dApp.

N3 Oracle

Blockchain cannot obtain information from the external network, and Oracle solves this problem. As a gateway for smart contracts to communicate with the outside world, Oracle opens a window to the outside world for blockchain. You can read more about N3 oracles here.

N3 supports both HTTP oracle and NeoFS oracle. Smart contract developers get the same interface to access WEB and NeoFS data, so it is easy to use. The only difference is the URI scheme.

NeoFS URI consists of neofs scheme, Container ID, and Object ID, both encoded in Base58.

Here is a small checklist to try NeoFS oracle yourself:

1. Create a container and upload a JSON object. Attention! Make sure that oracle nodes have read access. To do so, make your container public or read-only with -basic-acl public or --basic-acl readonly CLI arguments. Read more about NeoFS CLI operations in our first article.
2. Deploy smart contract with oracle access. Neo-go has a great example of such contract.
3. Invoke method with oracle call. In neo-go example invoke Request or FilteredRequest methods. When the oracle answer will persist on chain, the result will be printed out in node logs.

Enhanced oracle example

Consider a multiplayer dApp game with an item shop. These items hold ID, description, title, price, and other game parameters. JSON is a convenient human-readable format, however, JSON files may become quite large. NeoFS can be used as a storage for such files.

{ "store": {
    "item": [
      { "id": 1,
        "category": "clothing",
        "title": "Aloha Shirt",
        "price": 700
      },
      { "id": 2,
        "category": "clothing",
        "title": "Pearl Tee",
        "price": 400
      },
      { "id": 3,
        "category": "headgear",
        "title": "Fugu Bell Hat",
        "price": 1700
      },
      { "id": 4,
        "category": "headgear",
        "title": "Splash Goggles",
        "price": 2800
      },
      { "id": 5,
        "category": "shoes",
        "title": "Cherry Kicks",
        "price": 2400
      },
      { "id": 6,
        "category": "shoes",
        "title": "Red Hi-Tops",
        "price": 1800
      }
    ]
  }
}

This JSON file may be reused both in the game itself and at dApp server-side (game logic and transactions). The game fetches data from gates or directly from NeoFS network. Smart contract game logic reads parts of this large JSON via the oracle. Here is a brief example of such game logic contract.

Consider Purchase contract method that updates the balance of the player. The contract updates the storage by subtracting item price from the player’s balance. To do that Purchase method looks for the price attribute of the item with provided ID. N3 oracle supports JSONPath to filter output.

Then Purchase method encodes execution context (item ID and username) and sends oracle transaction.

When N3 oracle gets the response, it calls the oracle callback method in the contract. Callback checks if oracle response is found and if so, it parses it. Callback method decodes execution context from above and parses string output to integer value.

In the end, contract updates storage state:

Full contract source code available here.

To test it, check the balance of Marie's account.

Then purchase item for Marie by invoking Purchase method:

As soon as the oracle answer will persist, the callback function will update storage. Item with ID=1 costs 700 points, so the updated balance will be 3300.

From this article, you learned about N3 oracles and how developers can use them to access and process data from NeoFS inside smart contracts. In next articles, we will cover other ways to integrate apps and dApps with NeoFS. Find out more about NeoFS HTTP gates next time!