Skip to main content

What is ICRC Rosetta?

Intermediate
Rosetta

The ICRC Rosetta implementation allows for communication with ICRC-1 compatible ledgers through the Rosetta-API standard. Examples include the ckBTC ledger and the ckETH ledger.

The Rosetta API is a standardized specification for blockchain integrations developed by Coinbase. ICRC Rosetta provides a Rosetta-compliant interface specifically designed for ICRC-1 compatible tokens on the Internet Computer Protocol.

Key capabilities​

ICRC Rosetta enables:

  • Multi-token support: Connect to multiple ICRC-1 ledgers simultaneously (v2.1.0+).
  • Chain-key token integration: Native support for ckBTC, ckETH, and other chain-key tokens.
  • Custody platform integration: Standardized interface for wallet and custody providers.
  • Analytics and compliance: Access to comprehensive transaction and balance data.
  • DeFi application support: Reliable infrastructure for decentralized finance applications.

Supported tokens​

ICRC Rosetta works with any ICRC-1 compatible token, including:

Production tokens (mainnet)​

  • ckBTC (Chain-key Bitcoin): mxzaz-hqaaa-aaaar-qaada-cai.
  • ckETH (Chain-key Ethereum): ss2fx-dyaaa-aaaar-qacoq-cai.

Test tokens (mainnet)​

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

Supported operations​

ICRC Rosetta supports various operations through its APIs:

Token operations​

  • Account balance queries for multiple tokens.
  • Transaction history retrieval across different ledgers.
  • Transfer operations between accounts.
  • Multi-token transaction construction and submission.

Network operations​

  • Network status and configuration queries.
  • Token metadata retrieval (symbols, decimals, fees).
  • Block synchronization and monitoring.
  • Real-time balance updates.

Supported endpoints​

ICRC Rosetta implements the complete Rosetta specification including:

  • Data API: For querying blockchain data and account information.
  • Construction API: For creating and submitting transactions.
  • Network API: For network information and status.

For detailed endpoint documentation, see the Data API and Construction API sections.

Getting started​

To start using ICRC Rosetta, you'll need to set up a Rosetta node and configure it for the ICRC-1 ledgers you want to interact with. There are multiple deployment options available:

  • Docker deployment (recommended for most users).
  • Building from source (for development and customization).
  • Local cluster setup (for testing with monitoring tools).
  • Managed endpoints (no local setup required).

Test environment​

For testing and development, you can connect to the TICRC1 test token (3jkp5-oyaaa-aaaaj-azwqa-cai) that runs on mainnet but uses test tokens. Get free TICRC1 tokens from Validation Cloud's faucet to start experimenting with ICRC-1 functionality.

For detailed setup instructions, see the Running Rosetta guide.

Multi-token architecture​

ICRC Rosetta supports tracking multiple tokens simultaneously:

Database structure​

  • Each token maintains a separate SQLite database.
  • Database files are named after the canister ID (e.g., mxzaz-hqaaa-aaaar-qaada-cai.db).
  • Centralized logging with token-specific prefixes.

Network identification​

  • Each token uses its canister ID as the network identifier.
  • Rosetta calls must specify the target token's canister ID.
  • Single node can serve multiple token networks.

Requirements and limitations​

The ICRC Rosetta implementation has specific requirements and limitations:

Transaction timing requirement​

For transactions involving ICRC-1 tokens, the unsigned transaction must be created less than 24 hours before the network receives the signed transaction. This is due to the deduplication mechanism. Any submitted transaction that refers back to a transaction older than 24 hours is rejected to maintain operational efficiency.

Signature schemes​

The examples and documentation typically use:

  • Ed25519.
  • SECP256k1.

For the complete list of supported signature schemes, refer to the Rosetta specification.

Response format​

The integration software only replies with a subset of the potential responses that the specification supports. For example:

  • No UTXO features are implemented.
  • No UTXO messages appear in any software responses.

Network limitations​

  • Network support: All production and test tokens run on mainnet.
  • Test ledgers: Test tokens are available as separate ledgers on mainnet.
  • Default port: 8082 (different from ICP Rosetta's 8081).

Compliance​

Other than the 24-hour transaction timing requirement, the ICRC Rosetta API integration software:

  • Fully complies with all standard Rosetta endpoints.
  • Passes all rosetta-cli tests.
  • Accepts any valid Rosetta request.

Frequently asked questions​

How do I run an instance of ICRC Rosetta?​

The easiest way is to use the dfinity/ic-icrc-rosetta-api Docker image. See the Running Rosetta guide for detailed instructions on all deployment methods.

How do I connect to multiple tokens?​

Use the --multi-tokens flag with comma-separated canister IDs:

--multi-tokens mxzaz-hqaaa-aaaar-qaada-cai,ss2fx-dyaaa-aaaar-qacoq-cai

How do I connect to mainnet?​

Use the flag --network-type mainnet when starting your ICRC Rosetta node.

How do I know if the node has caught up?​

Look for these log entries for each token:

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

How do I persist synced block data?​

Mount the /data directory as a Docker volume:

docker volume create ic-icrc-rosetta
docker run \
    --volume ic-icrc-rosetta:/data \
    --publish 8082:8082 \
    --detach \
    dfinity/ic-icrc-rosetta-api \
    --multi-tokens-store-dir /data

Is ICRC Rosetta versioned?​

Yes, new versions are regularly published on DockerHub. It's recommended to use specific versions in production (e.g., dfinity/ic-icrc-rosetta-api:v2.1.0).

You can query the version using the /network/options endpoint:

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'

What's the default port?​

ICRC Rosetta listens on port 8082 by default (different from ICP Rosetta which uses 8081).

Can I track custom ICRC-1 tokens?​

Yes, ICRC Rosetta can connect to any ICRC-1 compatible ledger. Simply provide the canister ID of your custom token when starting the node.

How do I get test tokens for development?​

Use Validation Cloud's free faucet to get:

  • TICRC1 tokens for testing ICRC-1 functionality.
  • TESTICP tokens for testing ICP Rosetta.

These test tokens run on mainnet but are separate from production tokens, making them perfect for development and testing.