The Fuel indexer is a standalone service that can be used to index various components of the blockchain. These indexable components include blocks, transactions, receipts, and state within the Fuel network, allowing for high-performance read-only access to the blockchain for advanced dApp use-cases.
Want to get started right away? Check out our Quickstart!
For Users
Users of the Fuel indexer project include dApp developers looking to write flexible data-based backends for their dApp frontends, as well as index operators who are interested in managing one or many indexer projects for dApp developers.
Dependencies
fuelup
- We use fuelup in order to get the binaries produced by services in the Fuel ecosystem. Fuelup will install binaries related to the Fuel node, the Fuel indexer, the Fuel orchestrator (forc), and other components.
- fuelup can be downloaded here.
WebAssembly
Two additonal cargo components will be required to build your indexers: wasm-snip
and the wasm32-unknown-unknown
target.
- To install
wasm-snip
:
cargo install wasm-snip
To install the wasm32-unknown-unknown
target via rustup
:
rustup target add wasm32-unknown-unknown
IMPORTANT: Users on Apple Silicon macOS systems may experience trouble when trying to build WASM modules due to its
clang
binary not supporting WASM targets. If encountered, you can install a binary with better support from Homebrew (brew install llvm
) and instructrustc
to leverage it by setting the following environment variables:
AR=/opt/homebrew/opt/llvm/bin/llvm-ar
CC=/opt/homebrew/opt/llvm/bin/clang
forc-index
Plugin
The primary way of developing Fuel indexers for end users is via the forc-index
plugin. The forc-index
plugin, is a CLI tool that is bundled with Fuel's primary CLI tooling interface, forc
("Fuel Orchestrator").
As mentioned in the dependencies section, the forc-index
plugin is made available once you download fuelup
.
If you've successfully gone through the Quickstart, you should already have forc-index
installed and available in your PATH
.
forc index check
Check to see which indexer components you have installed.
forc index check
forc index new
Create new indexer project at the provided path.
forc index new --namespace my_org_name
forc index init
Create a new indexer project at the provided path. If no path is provided the current working directory will be used.
forc index init --namespace my_org_name
forc index build
Build the indexer in the current directory.
forc index build
forc index deploy
Deploy a given indexer project to a particular endpoint
forc index deploy --url https://indexer.fuel.network
forc index remove
Kill a running indexer.
forc index remove --url https://indexer.fuel.network
forc index auth
Authenticate against an indexer service.
forc index auth --url https://indexer.fuel.network
forc index start
Start the indexer service.
forc index start
Schema
The Fuel indexer uses data models derived from GraphQL schema types in order to persist data to a database backend.
schema {
query: QueryRoot
}
type QueryRoot {
account: Account
}
type Account {
id: ID!
address: Address! @unique
}
Modules
Within the context of the Fuel indexer, WebAssembly (WASM) modules are binaries that are compiled to a wasm32-unknown-unknown
target, which can then be deployed to a running indexer service.
WebAssembly (WASM) modules
There are a few points that Fuel indexer users should know when using WASM:
-
WASM modules are only used if the execution mode specified in your manifest file is
wasm
. -
Developers should be aware of what things may not work off-the-shelf in a module: file I/O, thread spawning, and anything that depends on system libraries. This is due to the technological limitations of WASM as a whole; more information can be found here.
-
As of this writing, there is a small bug in newly built Fuel indexer WASM modules that produces a WASM runtime error due to an errant upstream dependency. For now, a quick workaround requires the use of
wasm-snip
to remove the errant symbols from the WASM module. More info can be found in the related script here.
IMPORTANT: Users on Apple Silicon macOS systems may experience trouble when trying to build WASM modules due to its
clang
binary not supporting WASM targets. If encountered, you can install a binary with better support from Homebrew (brew install llvm
) and instructrustc
to leverage it by setting the following environment variables:
export AR=/opt/homebrew/opt/llvm/bin/llvm-ar
export CC=/opt/homebrew/opt/llvm/bin/clang
For Contributors
Contributors of the Fuel indexer project are devs looking to help backends for their dApps.
Dev Dependencies
docker
IMPORTANT: Docker is not required to run the Fuel indexer.
- We use Docker to produce reproducible environments for users that may be concerned with installing components with large sets of dependencies (e.g. PostgreSQL).
- Docker can be downloaded here.
Database
At this time, the Fuel indexer requires the use of a database. We currently support a single database option: PostgreSQL. PostgreSQL is a database solution with a complex feature set and requires a database server.
PostgreSQL
Note: The following explanation is for demonstration purposes only. A production setup should use secure users, permissions, and passwords.
On macOS systems, you can install PostgreSQL through Homebrew. If it isn't present on your system, you can install it according to the instructions. Once installed, you can add PostgreSQL to your system by running brew install postgresql
. You can then start the service through brew services start postgresql
. You'll need to create a database for your indexed data, which you can do by running createdb [DATABASE_NAME]
. You may also need to create the postgres
role; you can do so by running createuser -s postgres
.
For Linux-based systems, the installation process is similar. First, you should install PostgreSQL according to your distribution's instructions. Once installed, there should be a new postgres
user account; you can switch to that account by running sudo -i -u postgres
. After you have switched accounts, you may need to create a postgres
database role by running createuser --interactive
. You will be asked a few questions; the name of the role should be postgres
and you should elect for the new role to be a superuser. Finally, you can create a database by running createdb [DATABASE_NAME]
.
In either case, your PostgreSQL database should now be accessible at postgres://postgres@localhost:5432/[DATABASE_NAME]
.
SQLx
- After setting up your database, you should install
sqlx-cli
in order to run migrations for your indexer service. - You can do so by running
cargo install sqlx-cli --features postgres
. - Once installed, you can run the migrations by running the following command after changing
DATABASE_URL
to match your setup.
Building from Source
Clone repository
git clone git@github.com:FuelLabs/fuel-indexer.git && cd fuel-indexer/
Run migrations
PostgreSQL migrations
cd packages/fuel-indexer-database/postgres
DATABASE_URL=postgres://postgres@localhost sqlx migrate run
Start the service
cargo run --bin fuel-indexer
If no configuration file or other options are passed, the service will default to a
postgres://postgres@localhost
database connection.
Testing
Fuel indexer tests are currently broken out by a database feature flag. In order to run tests with a PostgreSQL backend, use --features postgres
.
Further, the indexer uses end-to-end (E2E) tests. In order to trigger these end-to-end tests, you'll want to use the e2e
features flag: --features e2e
.
All end-to-end tests also require the use of a database feature. For example, to run the end-to-end tests with a Posgres backend, use
--features e2e,postgres
.
Default tests
cargo test --locked --workspace --all-targets
End-to-end tests
cargo test --locked --workspace --all-targets --features e2e,postgres
trybuild
tests
For tests related to the meta-programming used in the Fuel indexer, we use trybuild
.
RUSTFLAGS='-D warnings' cargo test -p fuel-indexer-macros --locked
Contributing
If you're interested in contributing PRs to make the Fuel indexer a better project, feel free to read our contributors document.
Read the book
Whether you're a user or a contributor, for more detailed info on how the Fuel indexer service works, make sure you read the book.