Skip to main content

Running ICRC Rosetta

Intermediate
Rosetta

There are several ways to run ICRC Rosetta depending on your use case and requirements. This guide covers all available deployment methods for connecting to ICRC-1 compatible ledgers like ckBTC and ckETH.

The easiest way to run ICRC Rosetta is using the official Docker image. This method is recommended for most users.

Prerequisites

  • Docker installed and running.
  • Docker daemon started.
  • ICRC-1 ledger canister IDs you want to connect to.

Step 1: Pull the latest image

docker pull dfinity/ic-icrc-rosetta-api

Step 2: Run the container

Multi-token tracking (v2.1.0+)

Connect to multiple ICRC-1 ledgers simultaneously:

docker run \
--interactive \
--tty \
--publish 8082:8082 \
--rm \
dfinity/ic-icrc-rosetta-api \
--port 8082 \
--network-type mainnet \
--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai,ss2fx-dyaaa-aaaar-qacoq-cai \
--multi-tokens-store-dir /data

This example connects to both ckBTC (mxzaz-hqaaa-aaaar-qaada-cai) and ckETH (ss2fx-dyaaa-aaaar-qacoq-cai) ledgers.

Single token tracking (legacy)

Connect to a single ICRC-1 ledger:

docker run \
--interactive \
--tty \
--publish 8082:8082 \
--rm \
dfinity/ic-icrc-rosetta-api \
--port 8082 \
--network-type mainnet \
--ledger-id mxzaz-hqaaa-aaaar-qaada-cai \
--store-file /data/db.sqlite

Step 3: Production deployment

For production environments, run without interactive flags and persist data:

# Create a volume for data persistence
docker volume create ic-icrc-rosetta

# Run in production mode with multi-token support
docker run \
--volume ic-icrc-rosetta:/data \
--publish 8082:8082 \
--detach \
dfinity/ic-icrc-rosetta-api \
--port 8082 \
--network-type mainnet \
--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai,ss2fx-dyaaa-aaaar-qacoq-cai \
--multi-tokens-store-dir /data

Common ledger canister IDs

Mainnet tokens

  • ckBTC: mxzaz-hqaaa-aaaar-qaada-cai.
  • ckETH: ss2fx-dyaaa-aaaar-qacoq-cai.

Test tokens (on mainnet)

  • TICRC1 (Test ICRC token): 3jkp5-oyaaa-aaaaj-azwqa-cai.
  • ckTestBTC: mc6ru-gyaaa-aaaar-qaaaq-cai.
  • ckTestETH: apia6-jaaaa-aaaar-qabma-cai.

Get free TICRC1 test tokens from Validation Cloud's faucet to start testing ICRC Rosetta without using real tokens.

Docker versioning

It's recommended to use specific versions in production:

docker run \
--publish 8082:8082 \
--detach \
dfinity/ic-icrc-rosetta-api:v2.1.0 \
--port 8082 \
--network-type mainnet \
--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai

Check available versions on DockerHub.

Getting help

View all available options:

docker run \
--rm \
dfinity/ic-icrc-rosetta-api \
--help

Build from source

You can build and run ICRC Rosetta directly from the Internet Computer source code.

Prerequisites

  • Bazel build system.
  • Internet Computer repository cloned locally: git clone https://github.com/dfinity/ic.git.

Building and running

# Clone the IC repository (if not already done)
git clone https://github.com/dfinity/ic.git
cd ic

# Build and run ICRC Rosetta
bazel run //rs/rosetta-api/icrc1:ic-icrc-rosetta-api -- \
--port 8082 \
--network-type mainnet \
--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai \
--multi-tokens-store-dir /tmp/icrc-rosetta-data

This method gives you the latest development version and allows for custom modifications.

Local cluster

For development and testing purposes, you can set up a complete local Kubernetes cluster with monitoring tools that includes ICRC Rosetta.

The local cluster setup provides:

  • Minikube-based Kubernetes cluster.
  • Prometheus and Grafana for monitoring.
  • cAdvisor for container metrics.
  • Both ICP and ICRC1 Rosetta services.

Prerequisites

The deployment script will help install missing dependencies:

  • Docker.
  • Minikube.
  • kubectl.
  • Helm.

Deploying production images

# Clone the IC repository
git clone https://github.com/dfinity/ic.git
cd ic/rs/rosetta-api/local/cluster

# Deploy with default configuration
./deploy.sh

# Deploy with specific ICRC1 ledger
./deploy.sh --icrc1-ledger mxzaz-hqaaa-aaaar-qaada-cai

Deploying local images

First, build the containers from within the dev container:

# Enter dev container
./ci/container/container-run.sh

# Build ICRC1 Rosetta
bazel build //rs/rosetta-api/icrc1:icrc_rosetta_image.tar
mv bazel-bin/rs/rosetta-api/icrc1/icrc_rosetta_image.tar /tmp

# Exit dev container
exit

Then deploy the local images:

./deploy.sh --local-icrc1-image-tar /tmp/icrc_rosetta_image.tar

Monitoring with Grafana

Access Grafana at http://localhost:3000 with:

  • Username: admin.
  • Password: admin.

Import the dashboard using the rosetta_load_dashboard.json file in the cluster directory.

Validation Cloud

For those who prefer not to run Rosetta locally, Validation Cloud offers managed ICRC Rosetta endpoints that you can use for learning, development, and production.

Features

  • Managed infrastructure (no local setup required).
  • Global distribution with multi-region support.
  • 99.99% uptime SLA.
  • 24/7 customer support.
  • SOC 2 Type 2 compliance.

Getting started

  1. Visit Validation Cloud ICP page.
  2. Sign up for an account.
  3. Choose between Free tier (50M Compute Units) or Scale plan (unlimited).
  4. Get your API endpoint and start building.

Supported APIs

  • ICRC API for token interactions.
  • Access to chain-key token ledgers (ckBTC, ckETH).
  • Multi-token support.

This option is useful for:

  • Quick prototyping and learning.
  • Development without local infrastructure setup.
  • Production applications that prefer managed services.

Verification and testing

Regardless of the deployment method, you can verify your ICRC Rosetta node is working:

Check node status

curl -H "Content-Type: application/json" \
-d '{
"network_identifier": {
"blockchain": "Internet Computer",
"network": "mxzaz-hqaaa-aaaar-qaada-cai"
}
}' \
-X POST http://localhost:8082/network/status

Check version

curl -H "Content-Type: application/json" \
-d '{
"network_identifier": {
"blockchain": "Internet Computer",
"network": "mxzaz-hqaaa-aaaar-qaada-cai"
}
}' \
-X POST http://localhost:8082/network/options | jq '.version.node_version'

Wait for sync

Look for these messages in the logs to confirm synchronization:

Synced Up to block height: XXXXX
Account Balances have been updated successfully

Understanding the logs

ICRC Rosetta logs include token-specific prefixes for multi-token deployments:

INFO sync{token=ckBTC-mxzaz}: Fully synched to block height: 2365800
INFO sync{token=ckETH-ss2fx}: Fully synched to block height: 801941

The sync{token=...} prefix indicates which tracked token is generating the logs.

Requirements and limitations

  • Transaction timing: Unsigned transactions must be created less than 24 hours before submission due to the deduplication mechanism.
  • Signature schemes: Examples typically use Ed25519 and SECP256k1.
  • Default port: 8082 (vs 8081 for ICP Rosetta).
  • Network support: Mainnet (test ledgers are also available on mainnet).
  • Data persistence: Mount /data directory as a volume for Docker deployments.
  • Database files: Each token uses a separate SQLite database when using multi-token mode.

Common configuration examples

ckBTC only

docker run -p 8082:8082 --detach \
dfinity/ic-icrc-rosetta-api \
--network-type mainnet \
--ledger-id mxzaz-hqaaa-aaaar-qaada-cai

ckBTC + ckETH

docker run -p 8082:8082 --detach \
dfinity/ic-icrc-rosetta-api \
--network-type mainnet \
--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai,ss2fx-dyaaa-aaaar-qacoq-cai

Test tokens for development

# TICRC1 test token only
docker run -p 8082:8082 --detach \
dfinity/ic-icrc-rosetta-api \
--network-type mainnet \
--ledger-id 3jkp5-oyaaa-aaaaj-azwqa-cai

# Multiple test tokens
docker run -p 8082:8082 --detach \
dfinity/ic-icrc-rosetta-api \
--network-type mainnet \
--multi-tokens 3jkp5-oyaaa-aaaaj-azwqa-cai,mc6ru-gyaaa-aaaar-qaaaq-cai,apia6-jaaaa-aaaar-qabma-cai