arns-service

Koa microservice that facilities the ArNS Portal.

Getting Started

Requirements:

nvm
yarn
docker

Running Locally

Starting the service:

nvm use
yarn
cp .env.sample .env (and update values)
yarn start:dev

You can check the service is running by running the command:

curl localhost:3000/healthcheck
{"timestamp":"2023-04-13T13:33:38.299Z","status":200,"message":"Hello world."}

Docker

Build and run the latest image:

docker run -e GATEWAY_HOST=arweave.net -p 3000:3000 ghcr.io/ar-io/arns-service:latest

You can run on a different port by changing the -e PORT=3000 -p 3000:3000 to -e PORT=4000 -p 4000:4000, for example, or specify a .env file with --env-file flag.

Profiles

The service can be run with different profiles to facilitate different environments. The following profiles are supported:

test: runs the service and other containers for executing integration tests
litestream: runs the service with Litestream for syncing SQLite data to S3

To run the service with a profile, you can use the --profile flag:

docker compose --env-file .env --profile litestream up --build

Warp

The service leverages Warp SDK to retrieve, evaluate and cache contract state. To request a contract state, run:

curl localhost:3000/v1/contract/${CONTRACT_ID}

e.g.

curl localhost:3000/v1/contract/bLAgYxAdX2Ry-nt6aH2ixgvJXbpsEYm28NgJgyqfs-U

For more advanced features of Warp caching and state evaluation (e.g. D.R.E nodes), refer to the Warp documentation.

SQLite

This service uses the warp-contracts-sqlite for storing contract state. The sqlite database is stored in the ./cache directory. To clear the Warp cache, run:

rm -rf ./cache

Evaluation Options

By default, the service will load Contract-Manifest tags for state evaluation.

Syncing State

Similar to D.R.E nodes, the service can be configured to sync state for a given contract. This is useful for contracts with large number of interactions that may take a long time to evaluate locally. To sync state from this service via Warp, you can use syncState() with the /v1/contract/${CONTRACT_ID} endpoint:

const contract = await warp
  .contract(CONTRACT_TX_ID)
  .setEvaluationOptions(evaluationOptions)
  .syncState(`https://api.arns.app/v1/contract/${CONTRACT_TX_ID}`, {
    validity: true,
  });

Configuration

The service can be configured using environment variables. The following environment variables are supported:

PORT: the port on which the service should listen. Defaults to 3000 if not set.
GATEWAY_PORT: the gateway port used to evaluate Smartcontract state.
GATEWAY_PROTOCOL: the gateway protocol (http | https) to evaluate Smartcontract state.
GATEWAY_HOST: the gateway host used to evaluate Smartcontract state (e.g ar-io.dev or 127.0.0.1 for arlocal).
GATEWAY_HOST: the gateway used to evaluate Smartcontract state.
LOG_LEVEL: the log level to display (using [Winston] log levels - e.g. info, debug)
LOG_FORMAT: the log format to use when printing logs (e.g. json, simple)
WARP_LOG_LEVEL: the log level to display for Warp SDK (using [Winston] log levels - e.g. info, debug)
PREFETCH_CONTRACTS: boolean to enable/disable prefetching of contracts on startup. Defaults to true.
PREFETCH_CONTRACT_IDS: comma separated list of contract IDs to prefetch on startup
ARNS_CONTRACT_TX_ID: the ArNS contract transaction ID. Defaults to bLAgYxAdX2Ry-nt6aH2ixgvJXbpsEYm28NgJgyqfs-U and when PREFETCH_CONTRACTS is true, will be prefetched on startup.
BLOCKLISTED_CONTRACT_IDS: comma separated list of contract IDs to block evaluation. These contracts will return 403 when requested.

You can cp .env.sample .env and modify them locally.

Integration Tests

Integration tests are used to validate endpoints and response payloads. Then can be run locally via:

Run the service locally against the test environment:

yarn dotenv -e .env.test yarn start:watch

In a separate terminal, run the integration tests:

yarn test:integration:local

or entirely via docker compose:

yarn test:docker

Swagger

Swagger is used for endpoint documentation and testing. When running the service, you can load the Swagger UI in your browser at:

http://localhost:3000/api-docs

For production, the Swagger UI is available at https://api.arns.app/api-docs

Contributions

Build to interfaces
Integration tests take precedent over unit tests
Use conventional commits for commit messages
Use prettier for code formatting
Use eslint for linting
Use swagger for API documentation