nexus

command module
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 28, 2024 License: Apache-2.0 Imports: 1 Imported by: 0

README

Oasis Nexus

ci-lint ci-test

The official indexer for the Oasis Network. Nexus continuously fetches blockchain data from one or more oasis nodes and related sources (Sourcify, Oasis Metadata Registry, ...), parses the data and stores it into a heavily indexed SQL database, and provides a JSON-based web API to access the data.

Nexus aims to serve as the backend for explorers and wallets, notably the official Oasis Explorer and Oasis Wallet.

Docker Development

You can build and run Oasis Nexus with docker compose. Keep reading to get started, or take a look at our Docker docs for more detail.

Configuration

Download the current network's genesis document to the docker/node/etc directory. You will need this to run the Oasis Node container.

Build

From the repository root, you can run:

make docker
Run

From the repository root, you can run:

make start-docker

The analyzer will run DB migrations on start (i.e. create empty tables) based on files in storage/migrations.

Query

Now you can query the Oasis Nexus API

curl -X GET http://0.0.0.0:8008/v1

For a full list of endpoints see our API docs.

Local Development

Below are instructions for running Oasis Nexus locally, without Docker.

Oasis Node

You will need to run a local node for development purposes. You will need to set the Unix socket in the config/local-dev.yaml file while running an instance of Oasis Nexus. For example, this will be unix:/node/data/internal.sock in Docker.

Note: A newly created node takes a while to fully sync with the network. The Oasis team has a node that is ready for internal use; if you are a member of the team, ask around to use it and save time.

Database

You will need to run a local PostgreSQL DB.

For example, you can start a local Docker instance of Postgres with:

make postgres

and later browse the DB with

make psql
Nexus

You should be able to make nexus and run ./nexus --config config/local-dev.yml from the repository root. This will start the analyzers and the HTTP server, but you can start each of the constituent services independently as well. See ./nexus --help for more details.

Once Nexus has started, you can query the Oasis Nexus API

curl -X GET http://localhost:8008/v1

Debugging note: A lot of indexing happens when parsing the genesis data. To see what SQL statements genesis is converted into, run nexus with NEXUS_DUMP_GENESIS_SQL=/tmp/genesis.sql. The SQL will be written to the indicated file, provided that genesis hasn't been parsed into the DB yet. The easiest way to achieve the latter is to wipe the DB.

Code Quality Tools / Dependencies

Here are our recommendations for getting the tools that make lint and make fmt use. None of these are strictly needed to compile Nexus or even to create a PR, but without them, you're at the mercy of CI.

  • golangci-lint: use their curl | sh installer. They explain that the tool is in dependency hell and any more structured distribution of it might not work.

    curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh \
    | sh -s -- -b $(go env GOPATH)/bin v1.55.1
    
    • gofumpt: go install mvdan.cc/gofumpt@latest

      Note: CI uses gofumpt through golangci-lint, so if there's any discrepancy, look up what gofumpt version golangci-lint uses. Beware that we might not be on the latest golangci-lint either.

    • goimports: go install golang.org/x/tools/cmd/goimports@latest

      Note: CI uses goimports through golangci-lint, so if there's any discrepancy, look up what golang.org/x/tools version golangci-lint uses. Beware that we might not be on the latest golangci-lint either.

  • gitlint: pip install gitlint

    For linting commit messages. Used by git hooks and make lint-git.

  • gh: brew install gh or see official instructions for Linux. After installation, gh auth login.

    GitHub CLI. Used by git hooks.

  • punch.py: pip install punch.py

    Keeps track of the most recently released version.

  • prettier: npm install --save-dev --save-exact -g prettier

    For rewrapping (and some other normalization?) of Markdown files (including changelogs) and commit messages. Used by git hooks and recommended as autoformatter in your text editor (setup not covered here).

Name Origin

"Nexus" is a Latin word, meaning "connection or series of connections linking two or more things". Similarly, Oasis Nexus connects off-chain products with the Oasis blockchain.

Documentation

Overview

Oasis block indexer implementation.

Directories

Path Synopsis
block
Package block implements the generic block based analyzer.
Package block implements the generic block based analyzer.
consensus
Package consensus implements an analyzer for the consensus layer.
Package consensus implements an analyzer for the consensus layer.
item
Package item implements the generic item based analyzer.
Package item implements the generic item based analyzer.
util
Package util contains utility analyzer functionality.
Package util contains utility analyzer functionality.
api
v1
cache
cmd
Package cmd implements commands for the processor executable.
Package cmd implements commands for the processor executable.
analyzer
Package analyzer implements the `analyze` sub-command.
Package analyzer implements the `analyze` sub-command.
api
Package api implements the api sub-command.
Package api implements the api sub-command.
common
Package common implements common nexus command options.
Package common implements common nexus command options.
Package config enables config file parsing.
Package config enables config file parsing.
coreapi
v21.1.1/beacon/api
Package api implements the random beacon and time keeping APIs.
Package api implements the random beacon and time keeping APIs.
v21.1.1/consensus/api
Package consensus provides the implementation agnostic consensus backend.
Package consensus provides the implementation agnostic consensus backend.
v21.1.1/consensus/genesis
Package genesis provides consensus config flags that should be part of the genesis state.
Package genesis provides consensus config flags that should be part of the genesis state.
v21.1.1/genesis/api
Package api defines the Oasis genesis block.
Package api defines the Oasis genesis block.
v21.1.1/governance/api
Package api implements the governance APIs.
Package api implements the governance APIs.
v21.1.1/keymanager/api
Package api implements the key manager management API and common data types.
Package api implements the key manager management API and common data types.
v21.1.1/registry/api
Package api implements the runtime and entity registry APIs.
Package api implements the runtime and entity registry APIs.
v21.1.1/roothash/api
Package api implements the root hash backend API and common datastructures.
Package api implements the root hash backend API and common datastructures.
v21.1.1/roothash/api/block
Package block implements the roothash block and header.
Package block implements the roothash block and header.
v21.1.1/roothash/api/commitment
Package commitment defines a roothash commitment.
Package commitment defines a roothash commitment.
v21.1.1/roothash/api/message
Package message implements the supported runtime messages.
Package message implements the supported runtime messages.
v21.1.1/scheduler/api
Package api defines the committee scheduler API.
Package api defines the committee scheduler API.
v21.1.1/staking/api
Package api implements the staking backend API.
Package api implements the staking backend API.
v21.1.1/staking/api/token
Package token implements the token-related parts of the staking API.
Package token implements the token-related parts of the staking API.
v22.2.11/beacon/api
Package api implements the random beacon and time keeping APIs.
Package api implements the random beacon and time keeping APIs.
v22.2.11/common/node
Package node implements common node identity routines.
Package node implements common node identity routines.
v22.2.11/consensus/api
Package api provides the implementation agnostic consensus API.
Package api provides the implementation agnostic consensus API.
v22.2.11/consensus/genesis
Package genesis provides consensus config flags that should be part of the genesis state.
Package genesis provides consensus config flags that should be part of the genesis state.
v22.2.11/genesis/api
Package api defines the Oasis genesis block.
Package api defines the Oasis genesis block.
v22.2.11/governance/api
Package api implements the governance APIs.
Package api implements the governance APIs.
v22.2.11/keymanager/api
Package api implements the key manager management API and common data types.
Package api implements the key manager management API and common data types.
v22.2.11/registry/api
Package api implements the runtime and entity registry APIs.
Package api implements the runtime and entity registry APIs.
v22.2.11/roothash/api
Package api implements the root hash backend API and common datastructures.
Package api implements the root hash backend API and common datastructures.
v22.2.11/roothash/api/block
Package block implements the roothash block and header.
Package block implements the roothash block and header.
v22.2.11/roothash/api/commitment
Package commitment defines a roothash commitment.
Package commitment defines a roothash commitment.
v22.2.11/roothash/api/message
Package message implements the supported runtime messages.
Package message implements the supported runtime messages.
v22.2.11/scheduler/api
Package api defines the committee scheduler API.
Package api defines the committee scheduler API.
v22.2.11/staking/api
Package api implements the staking backend API.
Package api implements the staking backend API.
v22.2.11/staking/api/token
Package token implements the token-related parts of the staking API.
Package token implements the token-related parts of the staking API.
v22.2.11/upgrade/api
Package api defines the interface exporting the upgrade infrastructure's functionality.
Package api defines the interface exporting the upgrade infrastructure's functionality.
v24.0/beacon/api
Package api implements the random beacon and time keeping APIs.
Package api implements the random beacon and time keeping APIs.
v24.0/common/node
Package node implements common node identity routines.
Package node implements common node identity routines.
v24.0/consensus/api
Package api provides the implementation agnostic consensus API.
Package api provides the implementation agnostic consensus API.
v24.0/consensus/genesis
Package genesis provides consensus config flags that should be part of the genesis state.
Package genesis provides consensus config flags that should be part of the genesis state.
v24.0/genesis/api
Package api defines the Oasis genesis block.
Package api defines the Oasis genesis block.
v24.0/governance/api
Package api implements the governance APIs.
Package api implements the governance APIs.
v24.0/keymanager/api
Package api implements the key manager management API and common data types.
Package api implements the key manager management API and common data types.
v24.0/keymanager/secrets
Package api implements the key manager management API and common data types.
Package api implements the key manager management API and common data types.
v24.0/registry/api
Package api implements the runtime and entity registry APIs.
Package api implements the runtime and entity registry APIs.
v24.0/roothash/api
Package api implements the root hash backend API and common datastructures.
Package api implements the root hash backend API and common datastructures.
v24.0/roothash/api/block
Package block implements the roothash block and header.
Package block implements the roothash block and header.
v24.0/roothash/api/commitment
Package commitment defines a roothash commitment.
Package commitment defines a roothash commitment.
v24.0/roothash/api/message
Package message implements the supported runtime messages.
Package message implements the supported runtime messages.
v24.0/scheduler/api
Package api defines the committee scheduler API.
Package api defines the committee scheduler API.
v24.0/staking/api
Package api implements the staking backend API.
Package api implements the staking backend API.
v24.0/staking/api/token
Package token implements the token-related parts of the staking API.
Package token implements the token-related parts of the staking API.
v24.0/upgrade/api
Package api defines the interface exporting the upgrade infrastructure's functionality.
Package api defines the interface exporting the upgrade infrastructure's functionality.
v24.0/vault/api
Package api implements the vault backend API.
Package api implements the vault backend API.
Package log implements support for structured logging.
Package log implements support for structured logging.
Package metrics contains the prometheus infrastructure.
Package metrics contains the prometheus infrastructure.
Package storage defines storage interfaces.
Package storage defines storage interfaces.
client
Types for storage client responses.
Types for storage client responses.
oasis
Package oasis implements the source storage interface backed by oasis-node.
Package oasis implements the source storage interface backed by oasis-node.
oasis/nodeapi
Due to the (sometimes breaking) changes in the types used by different evolutions of oasis-core over the Cobalt, Damask, and Eden upgrades, Nexus defines its own set of internal types here.
Due to the (sometimes breaking) changes in the types used by different evolutions of oasis-core over the Cobalt, Damask, and Eden upgrades, Nexus defines its own set of internal types here.
postgres
Package postgres implements the target storage interface backed by PostgreSQL.
Package postgres implements the target storage interface backed by PostgreSQL.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL