nexus

command module

v0.7.22 Latest Latest Go to latest Published: Jan 12, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/oasisprotocol/nexus

Links

Open Source Insights

README ¶

Oasis Nexus

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 v2.4.0
```
- 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.

Source Files ¶

View all Source files

main.go

Directories ¶

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

Path	Synopsis
analyzer Package analyzer defines the analyzer API.	Package analyzer defines the analyzer API.
aggregate_stats Package aggregate_stats implements the aggregate stats analyzer.	Package aggregate_stats implements the aggregate stats analyzer.
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.
consensus/static Package static contains static data for the consensus analyzer.	Package static contains static data for the consensus analyzer.
consensus_accounts_list Package consensus_accounts_list implements the consensus accounts list analyzer.	Package consensus_accounts_list implements the consensus accounts list analyzer.
evmabi Package evmabi implements the common EVM ABI specs.	Package evmabi implements the common EVM ABI specs.
evmabibackfill Package evmabibackfill implements the EVM ABI backfill analyzer.	Package evmabibackfill implements the EVM ABI backfill analyzer.
evmcontractcode Package evmcontractcode implements the EVM contract code analyzer.	Package evmcontractcode implements the EVM contract code analyzer.
evmnfts Package evmnfts implements the EVM NFTs analyzer.	Package evmnfts implements the EVM NFTs analyzer.
evmnfts/ipfsclient Package ipfsclient implements a simple IPFS client.	Package ipfsclient implements a simple IPFS client.
evmnfts/multiproto Package multiproto implements a multi-protocol file fetcher.	Package multiproto implements a multi-protocol file fetcher.
evmtokenbalances Package evmtokenbalances implements the EVM token balances analyzer.	Package evmtokenbalances implements the EVM token balances analyzer.
evmtokens Package evmtokens implements the analyzer for the evm_tokens module.	Package evmtokens implements the analyzer for the evm_tokens module.
evmverifier Package evmverifier implements the EVM contract verifier analyzer.	Package evmverifier implements the EVM contract verifier analyzer.
evmverifier/sourcify Package sourcify implements a client for the Sourcify Server API.	Package sourcify implements a client for the Sourcify Server API.
httpmisc Package httpmisc contains options that are common to a few places that use HTTP.	Package httpmisc contains options that are common to a few places that use HTTP.
item Package item implements the generic item based analyzer.	Package item implements the generic item based analyzer.
metadata_registry Package metadata_registry implements the metadata registry analyzer.	Package metadata_registry implements the metadata registry analyzer.
neby_prices Package nebyprices implements the Neby prices analyzer.	Package nebyprices implements the Neby prices analyzer.
node_stats Package nodestats implements the node stats analyzer.	Package nodestats implements the node stats analyzer.
pubclient
queries Package queries defines the SQL queries used by the analyzer.	Package queries defines the SQL queries used by the analyzer.
rofl Package rofl implements an analyzer that tracks ROFL apps and their instances.	Package rofl implements an analyzer that tracks ROFL apps and their instances.
rofl/instance_transactions Package instancetransactions implements an analyzer that extracts transactions submitted by ROFL instances.	Package instancetransactions implements an analyzer that extracts transactions submitted by ROFL instances.
roflmarket Package roflmarket implements an analyzer that tracks ROFL market providers, their instances and their offers.	Package roflmarket implements an analyzer that tracks ROFL market providers, their instances and their offers.
runtime Package runtime implements the analyzer for the accounts module.	Package runtime implements the analyzer for the accounts module.
runtime/abiparse Package abiparse implements a parser for Ethereum ABI.	Package abiparse implements a parser for Ethereum ABI.
runtime/encryption Package encryption defines the types for encryption envelopes.	Package encryption defines the types for encryption envelopes.
runtime/evm Package evm implements the EVM client.	Package evm implements the EVM client.
runtime/firstactivitybackfill Package firstactivitybackfill implements the first_activity backfill analyzer.	Package firstactivitybackfill implements the first_activity backfill analyzer.
runtime/static Package static contains static data for the analyzer.	Package static contains static data for the analyzer.
uncategorized
util Package util contains utility analyzer functionality.	Package util contains utility analyzer functionality.
util/addresses Package addresses implements utilities for working with addresses.	Package addresses implements utilities for working with addresses.
util/eth Package eth contains utilities for EVM.	Package eth contains utilities for EVM.
validatorstakinghistory Package validatorstakinghistory implements the validator staking history analyzer.	Package validatorstakinghistory implements the validator staking history analyzer.
api Package api defines the server API types.	Package api defines the server API types.
v1 Package v1 implements the Nexus API v1.	Package v1 implements the Nexus API v1.
v1/types Package types defines the types for the API.	Package types defines the types for the API.
cache
httpproxy Package httpproxy implements a simple HTTP proxy that caches responses.	Package httpproxy implements a simple HTTP proxy that caches responses.
kvstore Package kvstore implements a key-value store.	Package kvstore implements a key-value store.
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.
bisect command
common Package common implements common nexus command options.	Package common implements common nexus command options.
common Package common defines common types for the Nexus project.	Package common defines common types for the Nexus project.
config 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/common/crypto/pvss Package pvss implements a PVSS backed commit-reveal scheme loosely based on the Scalable Randomness Attested by Public Entities protocol by Casudo and David.	Package pvss implements a PVSS backed commit-reveal scheme loosely based on the Scalable Randomness Attested by Public Entities protocol by Casudo and David.
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/api/transaction
v21.1.1/consensus/api/transaction/results
v21.1.1/consensus/api/transaction/testvectors
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/api/events
v22.2.11/consensus/api/transaction
v22.2.11/consensus/api/transaction/results
v22.2.11/consensus/api/transaction/testvectors
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/runtime/client/api
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/api/events
v24.0/consensus/api/transaction
v24.0/consensus/api/transaction/results
v24.0/consensus/api/transaction/testvectors
v24.0/consensus/cometbft/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/churp
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.
log Package log implements support for structured logging.	Package log implements support for structured logging.
metrics Package metrics contains the prometheus infrastructure.	Package metrics contains the prometheus infrastructure.
storage Package storage defines storage interfaces.	Package storage defines storage interfaces.
client Package client defines the types for storage client responses.	Package client defines the types for storage client responses.
client/queries Package queries defines the SQL queries used by the storage client.	Package queries defines the SQL queries used by the storage client.
migrations Package migrations contains embedded database migration files.	Package migrations contains embedded database migration files.
oasis Package oasis implements the source storage interface backed by oasis-node.	Package oasis implements the source storage interface backed by oasis-node.
oasis/connections Package connections implements a gRPC connection wrapper.	Package connections implements a gRPC connection wrapper.
oasis/nodeapi Package nodeapi defines the types used by Nexus to represent the data returned by the node API.	Package nodeapi defines the types used by Nexus to represent the data returned by the node API.
oasis/nodeapi/cobalt Package cobalt implements the Cobalt consensus API.	Package cobalt implements the Cobalt consensus API.
oasis/nodeapi/damask Package damask implements a Damask consensus API.	Package damask implements a Damask consensus API.
oasis/nodeapi/eden Package eden implements the Eden consensus API.	Package eden implements the Eden consensus API.
oasis/nodeapi/file Package file implements a file-backed consensus API.	Package file implements a file-backed consensus API.
oasis/nodeapi/history Package history implements a consensus API for historical data.	Package history implements a consensus API for historical data.
postgres Package postgres implements the target storage interface backed by PostgreSQL.	Package postgres implements the target storage interface backed by PostgreSQL.
postgres/testutil Package testutil provides utilities for testing the postgres client.	Package testutil provides utilities for testing the postgres client.
tests
statecheck