Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
February 22, 2023 13:11
February 22, 2023 13:11
February 15, 2022 13:07
January 6, 2023 09:01
February 22, 2023 13:11
March 12, 2019 11:29
March 26, 2019 09:11
February 2, 2022 14:23
February 22, 2023 13:11
February 22, 2023 13:11
February 22, 2023 13:11


Aquarius tests black Docker Build Status Maintainability Test Coverage PyPI GitHub contributors


What is Aquarius?

Aquarius is an off-chain, multi-chain cache for metadata that is published on chain, connected to an Elasticsearch database. Aquarius continually monitors the chains for MetadataCreated and MetadataUpdated events, processes these events and adds them to the database. The Aquarius API offers a convenient way to access the medatata without scanning the chain yourself.

Aquarius is part of the Ocean Protocol toolset. 🌊

How is metadata treated?

The metadata is published on-chain as such:

  • Metadata is first (optionally) compressed (using lzma) and (strongly recommended) encrypted, then published on-chain
  • The metadata on-chain is not kept in storage, but rather is captured in an event log named MetadataCreated
  • Aquarius defers to the Provider for encryption and decryption. Aquarius and Provider support utf-8 encoded strings. You can look into the encrypt/decrypt flows if you want to learn more, but you will generally not need to go in-depth just to use Aquarius.

For more details on working with OCEAN DIDs check out the DID concept documentation. The DDO Metadata documentation goes into more depth regarding metadata structure.

Components and architecture

Aquarius is a simple, lightweight scanner and API. It is built using Python, using the Flask framework.

The Aquarius API

Aquarius provides REST api to fetch the data from off-chain datastore. Please refer to file for details on the API itself.

The EventsMonitor

The events monitor runs continuously to retrieve and index the chain Metadata. It saves the results into an Elasticseach database. The monitor reads the events data argument, decompresses the metadata json object, then runs schema validation before saving it to the database. The monitor is highly customisable, and it consists of the following components:

  • an ElasticsearchInstance, configured through env variables
  • an associated MetadataContract, configured through the METADATA_CONTRACT_ADDRESS env variable
  • a Decryptor class that handles decompression and decryption on the chain data, through communication with Provider
  • a set of ALLOWED_PUBLISHERS, if such a restriction exists. You can set a limited number of allowed publisher addresses using this env variable.
  • a Purgatory, based on the ASSET_PURGATORY_URL and ACCOUNT_PURGATORY_URL env variables. These mark some assets as being in purgatory ("isInPurgatory": True), enabling restrictions for some assets or accounts.
  • a VeAllocate, based on the VEALLOCATE_URL and VEALLOCATE_UPDATE_INTERVAL env variables. This updates the veAllocation for datasets.
  • start blocks, if such defined using BFACTORY_BLOCK and METADATA_CONTRACT_BLOCK. These start blocks are coroborated with the last stored blocks per Elasticsearch, to avoid indexing multiple times

The EventsMonitor processes block chunks as defined using BLOCKS_CHUNK_SIZE. For each block, it retrieves all MetadataCreated and MetadataUpdated events, and these events are processed inside the MetadataCreatedProcessor and MetadataUpdatedProcessor classes. These processors run the following flow:

  • optionally check permissions with the RBAC_SERVER_URL and ALLOWED_PUBLISHERS
  • decompresses and optionally decrypts the asset metadata
  • checks whether the asset needs to be sent to purgatory
  • creates the JSON record and saves it in Elasticsearch
  • if a MetadataUpdated event is detected on an asset that does not exist in Elasticsearch already, then it is treated as a MetadataCreated event.

Aquarius Setup

The following environment variables are required for running Aquarius:

# URL of ethereum network.
# Recommendation: when connecting to an official network, create an Infura project id and set this
# to use the Infura url including the project id
  "", "wss://"

# Use this to run the EventsMonitor in a thread from the main Flask app
  accepted values:
    "0" to disable
    "1" to enable

# Run the EventsMonitor in a separate process, overrides `EVENTS_ALLOW`.
# This is only used when running in `docker` container
  accepted values:
    "0" to disable
    "1" to enable

# Start a HTTP server inside the events monitor. This is useful for K8 live probing. You must simply access the root endpoint on port 5001. IE: which will respond with 200 OK if the events thread is up.  Otherwise, there will be no response
  accepted values:
    "1" to enable

And these are optional

# Enables the Aquarius API. Default: 1, disable if you only want to use the events monitor, without exposing an API.

# Identify instance of Aquarius to Provider, when decrypting assets. Provider may allow or deny decryption based on this address.

# Path to the `address.json` file or any json file that has the deployed contracts addresses

# Specify the network name to use for reading the contracts addresses from the `ADDRESS_FILE`.
# If not set, the network name is derived from current network id or from the `EVENTS_RPC` value, by splitting out the wss://, http:// or https:// part and the suffixes

# Restrict metadata caching to publishers in this list. It is a list of publisher addresses.

# Metadata contract address. Use it if you want to overwrite values from ocean-contracts

# The block number of `Metadata` contract deployment

# if set to 1, read events from the first Metadata and BFactory block number, or a specific block number (used for debugging)

# When scanning for events, limit the chunk size. Infura accepts 10k blocks, but others will take only 1000 (default value)

# URLs of asset purgatory and account purgatory. If neither exists, the purgatory will not be processed. The list should be formatted as a list of dictionaries containing the address and reason. See for an example
# IMPORTANT.  If you are running multiple aquarius event monitors (for multiple chains), make sure that only one event-monitor will handle purgatory

# Customise purgatory update (refresh) time (in number of minutes)

# URL for getting the veAllocation list. If not exists, the veAllocate will not be processed. Possible values are: for mainnet and for goerli, because veOCEAN is deployed only on this networks. All other networks SHOULD NOT HAVE this defined.  The list should be formatted as a list of dictionaries containing chainID,nft_addr and ve_allocated

# Customise veAllocate update (refresh) time (in number of minutes)

# The URL of the RBAC Permissions Server. If set, Aquarius will check permissions with RBAC. Leave empty/unset to skip RBAC permission checks.

# Whether to start clean and reindex events on chain id

# Subgraph URLs in the form of a json-dumped string mapping chain_ids to subgraph urls.

# Process a queue with failed assets, e.g. retry where temporary network flukes or similar conditions caused a failure

# For how long to retry such an event, before giving up. Defaults to 2 weeks

# Customize sleep time for events monitor between checking for new events. Defaults to 30 seconds
# Customize sleep time for events monitor between queue processing. Defaults to 60 seconds
# Customize sleep time for events monitor between updating ve_allocate. Defaults to 300 seconds
# Customize sleep time for events monitor between checking for nft transfers. Defaults to 300 seconds
# Customize sleep time for events monitor between checking for purgatory lists. Defaults to 300 seconds

Running Aquarius for multiple chains

If you want to index multiple chains using a single Aquarius instance, that is possible. The OCEAN version of Aquarius uses this exact flow. To enable multi-chain indexing, these are the necessary steps:

  • Run one or more pods, with RUN_AQUARIUS_SERVER=1 , RUN_EVENTS_MONITOR=0 and EVENTS_ALLOW=0. This basically enables only the API part of Aquarius.
  • For each chain, start a pod with the following env variables:
    • Set RUN_EVENTS_MONITOR=1 and RUN_AQUARIUS_SERVER=0 (run only the EventsMonitor part of Aquarius)

A list of deployment values and schematics can be found here

VoilΓ ! You are now running a multi-chain Aquarius.

Using Aquarius


If you're developing a marketplace, you'll want to run Aquarius and several other components locally. The easiest way to do that is to use Barge. See the instructions in the Barge repository.

Learn about Aquarius API

Here is API documentation. You can find more details about the ontology of the metadata in the Ocean documentation.

If you have Aquarius running locally, you can find a Swagger API documentation at http://localhost:5000/api/docs or maybe

  • Tip 1: If that doesn't work, then try https.
  • Tip 2: If your browser shows the Swagger header across the top but says "Failed to load spec." then we found that, in Chrome, if we went to chrome://flags/#allow-insecure-localhost and toggled it to Enabled, then relaunched Chrome, it worked.

Running Aquarius locally

For testing purposes, running Aquarius from barge should suffice, but if you want to run your own version of Aquarius (with any configurations or alterations), you can do that by following the instructions in the developers documentation.


If you want to improve or customise Aquarius, you're our favourite kind of person! Go to the developers flow to learn more about how you can contribute.


Copyright 2022 Ocean Protocol Foundation Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.