Custom Indexer Template

Live Example

Create Aptos Dapp Custom Indexer Dapp Template

The custom indexer template provides a starter dapp with all the necessary infrastructure to build a full stack app with custom indexer support.

The Custom Indexer template provides:

  1. Folder structure - A pre-made dapp folder structure with src for frontend, contract for Move contract and indexer for custom indexer.
  2. Dapp infrastructure - All required dependencies a dapp needs to start building on the Aptos network.
  3. Wallet Info implementation - Pre-made WalletInfo components to demonstrate how one can read info from a connected wallet.
  4. Message board functionality - Pre-made MessageBoard component to create, update and read messages from the Move smart contract.
  5. Analytics dashboard - A pre-made Analytics component to show the number of messages created and updated.
  6. Point program - A minimal example to show you how to define a point program based on events (e.g. create message, update message) and show that on the analytics dashboard, with sorting.

Generate the custom indexer template

On your terminal, navigate to the directory you want to work in and run:

Follow the CLI prompts.

Publish the Move Contract

If you are using the Testnet network, you will need to fund a module publisher account manually through the faucet web view on https://aptos.dev/en/network/faucet and then fill out the MODULE_PUBLISHER_ACCOUNT_PRIVATE_KEY and MODULE_PUBLISHER_ACCOUNT_ADDRESS in your project .env file.

On the project root folder, run the below command to publish the contract.

You will have to confirm the gas fee in the console.

This command will:

  1. Publish the contract to chain.
  2. Set the VITE_MODULE_ADDRESS in the .env file to set the contract object address.

Create a postgres database

Sign up for Neon postgres (our cloud Postgres provider) and create a new project. Find the connection string in Neon console’s quickstart section (it should look like postgresql://username:password@host/neondb?sslmode=require) and set it in the .env file as DATABASE_URL.

If you want to run the database locally, you can follow this tutorial to run a postgres database in a docker container.

Setup the database

Everything here should be run in the indexer folder.

Install Rust.

Install diesel cli to run migrations.

Run all pending database migrations. This will create all the tables in the database.

In case you want to revert all migrations to delete all tables because you want to re-index all data.

In case you want to make any change to the database, you can add a new migration.

Sign up for Aptos Build

Sign up for Aptos Build, create a new project, and get the API token.

Build the indexer as a docker container

In the indexer folder, make a copy of example.config.yaml and rename it to config.yaml. Fill in the following:

  • starting_version: The tx version (Aptos concept, similar to block height) from which you want to start indexing
  • postgres_connection_string: The connection string of the postgres database. DO NOT include the ?sslmode=require because diesel doesn’t recognize it correctly; instead we handle it in the code
  • contract_address: The address of the Move contract
  • auth_token: Aptos Build API token

Build the docker image targeting linux/amd64 as we will eventually push the image to Artifact Registry and deploy it to Cloud Run, which only supports linux/amd64.

Run the indexer locally

You can run the docker container locally to make sure it works. Mac supports linux/amd64 emulation so you can run the x86 docker image on Mac.

Re-indexing

Do not ever try to backfill the data, as data like user statistics is incremental. If you backfill (e.g. processing same event twice), you will get wrong statistics. So please always revert all migrations and re-index from the first tx your contract deployed.

Revert all migrations, this should stop the indexer by making it panic if indexer is running on the cloud.

Run all migrations again.

Follow the guide below to re-build the indexer docker image and redeploy it to cloud run or run it locally.

Run the frontend

Building the frontend

The boilerplate template utilizes React as the frontend framework and Vite as the development tool, and is styled with Tailwind CSS and shadcn/ui. All dapp components should be added into the components folder and it is recommended to create a page folder to hold all future pages in your project.

Writing a Move contract

The boilerplate template comes with a contract folder that holds all Move smart contract related files. Under the sources folder you will find a *.move file with a super basic implementation of a Move module that stores a message and updates it. This is to help you get started with writing your own Smart Contract.

Smart contract and frontend communication

For a frontend to submit a transaction to a smart contract, it needs to call an entry function. The boilerplate provides you with an entry-functions folder to hold all your dapp entry function requests. Additionaly, for a frontend to fetch data from a smart contract, it needs to submit a request to a view function. The boilerplate provides you with a view-functions folder to hold all your dapp view function requests.

Ready for Mainnet

If you started your dapp on testnet, and you are happy with your testing, you will want to get the dapp on mainnet.

To publish the smart contract on mainnet, we need to change some configuration.

Open the .env file and:

Note: Make sure you have created an existing account on the Aptos mainnet

  1. Change the APP_NETWORK value to mainnet
  2. Update the MODULE_PUBLISHER_ACCOUNT_ADDRESS to be the existing account address
  3. Update the MODULE_PUBLISHER_PRIVATE_KEY to be the existing account private key
  4. Run npm run move:publish to publish your move module on Aptos mainnet.

API Key

  1. If you are using an API Key, make sure to update the NEXT_PUBLIC_APTOS_API_KEY with your MAINNET API Key.
  2. If you are not using an API Key, make sure to create one and update the NEXT_PUBLIC_APTOS_API_KEY with your API Key.

Deploy to a live server

create-aptos-dapp provides an npm command to easily deploy the static site to Vercel.

At the root of the folder, simply run

Then, follow the prompts. Please refer to Vercel docs to learn more about the Vercel CLI

If you are looking for different services to deploy the static site to, create-aptos-dapp utilizes Vite as the development tool, so you can follow the Vite deployment guide. In a nutshell, you would need to:

  1. Run npm run build to build a static site
  2. Run npm run preview to see how your dapp would look like on a live server
  3. Next, all you need is to deploy your static site to a live server, there are some options for you to choose from and can follow this guide on how to use each