Skip to content

About

An indexer for the VeWorld wallets

Resources

Stars

5 stars

Watchers

3 watching

Forks

Latest commit

 

History

1,402 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

VeWorld Indexer

Security Checks Badge

Test, Publish & Deploy

Prerequisites

  • Docker
  • Java (v21)

GitHub Packages Authentication (optional)

Normal builds resolve dependencies from Maven Central and do not require credentials. GitHub Packages credentials are only needed when resolving a dependency version that has not reached Maven Central yet, such as a SNAPSHOT or pre-release org.vechain:indexer-core.

For local Gradle builds, create a GitHub Personal Access Token (classic) with the read:packages scope and add the following to ~/.gradle/gradle.properties:

gpr.user=your-github-username
gpr.key=your-github-pat

For Docker builds, put those same properties in gradle/docker.gradle.properties or pass another readable file with GRADLE_PROPERTIES_FILE=/path/to/gradle.properties make build-image. The default Docker properties file is git-ignored and excluded from the Docker build context.

Getting Started

  • To see a list of all available commands, run make help
  • After starting the application, the swagger will be made available at http://localhost:8080

Option 1: Docker only

  • Copy env files for the two packages ./package/<package>/.env.example to ./package/<package>/.env and fill in the values for your environment. They should work as-is for docker

  • Run:

make start

Option 2: Docker + IntelliJ (Recommended for debugging)

  • No need to copy the environment files if you are using IntelliJ. The default variables should connect to the infrastructure using localhost variables
  • Run:
make pg-up

img.png

  • Go to IndexerApplication.kt inside IntelliJ and run/debug:

Connecting to PostgreSQL

Every indexer writes to PostgreSQL. make pg-up starts it on localhost:5432 as database vechain; roles indexer and api, both with password password. make pg-psql opens a shell, make pg-clean drops the data.

Features

There are 6 indexers and 6 corresponding APIs. Each indexer can be run in isolation or all together. There is no dependency between indexers for this reason. Each indexer and API pair can be enabled using the corresponding spring profile.

  • transactions - enabled with transactions profile
  • nfts - enabled with nfts profile
  • transfers - enabled with transfers profile
  • history - enabled with history profile

As you can see from the list above, the block indexer offers the option to proxy to the Thor node. This is useful if you want the convenience of the Block endpoints without the overhead of indexing the data.

Testing

  • Run all the tests:
make test

Package Testing

  • There are 4 packages that can be tested (api, common, e2e, indexer)
  • This will run all tests in a package (unit, integration and E2E)
  • Run (example for api):
make test-api
make test-common
make test-indexer
make test-e2e

E2E

  • Running E2E tests will spin up all the docker infrastructure before the test and tears it down after completion. This is useful for testing the entire system, but it is slow. If you need to debug these tests, it is recommended to spin up the network manually using make clean start and remove the tasks preE2e and postE2e tasks in ./packages/e2e/build.gradle.kts (here)

API Schema Tests

Use the schema-driven harness when you need to validate the public API in a deployed environment. It fetches the OpenAPI document from /api-docs, runs Schemathesis-based checks across every documented operation, and fails if any response exceeds 2 000 ms (override by setting MAX_RESPONSE_MILLISECONDS).

  • Local run: packages/api/scripts/run_api_schema_tests.sh [dead|live|<base-url>] [--base-url <base-url>] (defaults to the dead environment). Install schemathesis locally first, for example pip install "schemathesis>=3.19,<4".
  • Both colours are reached through CloudFront; the ALB hostnames themselves accept nothing but distribution traffic. Dead is https://mainnet.dead.veworld.vechain.org and https://testnet.dead.veworld.vechain.org, which follow the colour swap automatically.
  • GitHub Action: trigger API Tests from the Actions tab and choose the target environment, or provide a full base URL override. The workflow uses the same script and publishes Schemathesis logs and JUnit XML as artifacts.

API Regression Tests

Compares every documented operation between a network's live colour (baseline) and its dead colour (candidate), so a release is checked against the API it replaces.

  • Pick the network, not the URLs: API Regression Tests takes network (mainnet or testnet), and packages/api/scripts/networks.py resolves both colours and the Thor node from it.
  • Each network brings its own chain data. test_values.json holds what is network-independent — ignored paths, page sizes, enum filters — and test_values.<network>.json holds that chain's addresses and ids, laid over it at run time. Most values are re-seeded from the live colour before each run; the files are the fallback.
  • Run a subset with tests: a suite name (stargate, b3tr, transfers, …) or a path regex. packages/api/scripts/run_regression_tests.sh --list-suites prints the names; empty runs all 92 operations.
  • Local run: NETWORK=testnet packages/api/scripts/run_regression_tests.sh --path-filter stargate. Set RATE_LIMIT_BYPASS_TOKEN so the WAF does not throttle a full run.

Disaster Recovery

RDS keeps 7 days of automated snapshots of every Postgres instance. Recovery of a colour is a restore from the other colour's newest snapshot, which the workflow below drives.

Dead Prod Restore Workflow

For snapshot-native recovery of the current dead prod color, use the Restore Dead Prod From Live Snapshots workflow. It rebuilds the dead colour's Postgres instances from the live colour's newest automated RDS snapshots.

RDS cannot restore into an existing instance, so each one is replaced from the snapshot under the same identifier — that is the only operation allowed to destroy a Postgres instance, and every other plan is refused by a guard in Plan or Apply Terraform. A net whose live instance does not exist yet is skipped, leaving the dead colour's own data alone. A restored instance lazy-loads its pages from S3, so the job starts a pg-prewarm ECS task per net and reports its ARN; reads stay slow until it stops, which takes hours on mainnet.

This workflow does not stop or start ECS services. The dead environment must already be quiesced before restore. Use the Stop or Start Dead Prod Environment Services workflow first, then run the restore, then start services again once the restore summary looks correct.

Recommended sequence:

  1. Run Stop or Start Dead Prod Environment Services with stop.
  2. Run Restore Dead Prod From Live Snapshots. To restore Postgres from a specific snapshot — a manual one taken before a risky operation, or a rehearsal against the dead colour's own data — pass it as pg_snapshot_main / pg_snapshot_test.
  3. Review the restore summary artifact: the RDS snapshot and prewarm task per net.
  4. Run Stop or Start Dead Prod Environment Services with start.
  5. Run the schema or regression tests against the dead environment before switching traffic.

Content-Addressed Images

An image's identity is the hash of its Docker build context, printed by make content-hash (.github/workflows/scripts/content_hash.sh). Each service is hashed separately over the shared build files plus packages/common and its own package, which is what .dockerignore lets into the context.

The PR build resolves the hash with the default branch's copy of that script, so a branch cannot rename its own content into a tag a later release would reuse. It pushes content.<hash> to GHCR and points pr.<n>.<sha> at it. A release build re-tags the same manifest instead of building whenever that hash is already published — so a terraform-, workflow- or docs-only release does no Docker work at all, and a release that touched only the API leaves the indexer image alone.

A deploy carries this through: it reads the tag each service is actually running on the target colour — resolved through the ECS service, because a task definition family's latest revision may be one no rollout ever completed — hashes that tag's tree, and pins the service to it when the hash matches the release. Only services that changed are promoted to ECR and only their task definitions move, so the deploy has no diff for the rest. Terraform receives the four tags (net x service) as image_version_override rather than an in-place edit of the environment yaml. The step summary lists what was pinned and why.

APP_VERSION is therefore not baked into the image; it comes from the ECS task definition at runtime, so cutting a new version does not change image content. The trade-off is that a release reusing an image does not pick up new Alpine packages — the base image tag is in the hash, so a Renovate base bump is what refreshes them. Dispatch the GHCR publish with force_rebuild to rebuild without one.

Deployment & Testing

To deploy, run the Deploy workflow from the version tag you want to deploy, leaving target at auto. Both networks deploy together. The run works out which colour the release should go to and pauses at a Confirm job whose name states the plan, for example "Deploy v.1.2.3 to prod-green (dead), restoring from prod-blue snapshots first". The Plan Release job summary has the reasoning and the per-service image tags. Approve it to proceed. To do something else, reject it (nothing has been applied) and re-dispatch with target set to live or dead.

The plan follows three rules:

  • A running dead colour is the one being staged, so it gets the release.
  • A cold dead colour and an indexer unchanged against live: live takes the release directly, with no indexing gap.
  • A cold dead colour and a changed indexer: the dead colour gets the release after its Postgres instances are restored from the latest live snapshots. A changed indexer on live pauses indexing while it restarts, and a cold colour's data is stale.

target: live is refused for a changed indexer. skip_restore only skips the restore: the colour indexes on from whatever its Postgres instances hold, which for a stopped colour is a stale checkpoint, not genesis. A reindex from genesis is an indexer.version bump (see AGENTS.md "Triggering an Indexer Resync"), not a skipped restore.

One deploy applies every stack — shared infra, observability, the CloudFront distributions, the restore when needed, and the application — in dependency order, so a stack with no change is a no-op rather than a run someone has to remember. AGENTS.md "One Deploy Applies Every Stack" has the order and the reasoning.

After a dead deploy: the DNS switch

A deploy to the dead colour finishes with a Next steps summary. Traffic stays where it was until you run the Switch Live Environment workflow with network all, which also publishes the draft release.

Do that once every indexer on both networks reports fully synced; the summary links the Grafana "blocks behind" panel for that colour and the dead API's indexed head (https://mainnet.dead.veworld.vechain.org/api/v1/blocks?size=1 and the testnet equivalent). A restored colour catches up in hours; a reindex from genesis takes days. If in doubt about which colour is currently live, run the Identify Live/Dead Environments workflow with the default arguments.

Following the DNS switch, please wait at least 48 hours before tearing down the old live (now dead) environment. This is to allow any remote DNS caches to update to the new live environment.

Testing

The dead colour doubles as a testing environment: it is an exact replica of live, database included. To put a release on it regardless of what the plan would pick, dispatch the Deploy workflow with target: dead. A cold colour is restored from the live snapshots first unless skip_restore is ticked. Merging to main deploys nothing. While the dead colour is running, auto sends every release to it, so tear it down or switch to it when testing is done.

Environment Tear-down

When testing is complete, or when a DNS switch has migrated traffic from one environment to the other, the dead environment can be safely torn down until needed again. To do this, run the Cluster Destroy workflow, and select the appropriate environment when prompted.

Leave the dead CloudFront workspace in place. A torn-down colour leaves its origin record pointing at a placeholder, so the distributions return errors until the colour is redeployed — but they cost nothing idle, and keeping them avoids re-issuing the certificate every cycle.

Further details on the CICD process can be found here

About

An indexer for the VeWorld wallets

Resources

Stars

5 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages