Skip to main content

What is ICRC Rosetta?

Intermediate
Tutorial

The ICRC Rosetta implementation allows for communication with the ICRC-1 compatible ledgers through the Rosetta-API standard. Examples include the ckBTC ledger and the ckETH ledger. This documentation covers the endpoints of the Data-API and the Construction-API.

Set up an ICRC Rosetta node​

You can set up a Rosetta API-compliant node for ICRC to interact with the Internet Computer and your ICRC-1 ledger of choice. For simplicity, these instructions will describe how to use a Docker image to create the integration with the Rosetta API. You can also build and run the binary using the source code.

If you don’t already have Docker in your environment, download and install the latest version.

To set up a ICRC Rosetta node:

Step 1: Install Docker and start the Docker daemon.​

The Docker daemon (dockerd) should automatically start when you reboot your computer. If you start the Docker daemon manually, the instructions vary depending on the local operating system.

Step 2: Pull the latest dfinity/ic-icrc-rosetta-api image from the Docker Hub.​

Run the following command:

docker pull dfinity/ic-icrc-rosetta-api

Step 3: Start the integration software.​

Run the following command: You will need to know the canister id of the ICRC-1 ledger you are trying to connect to. For example, to connect the to ckBTC ICRC-1 ledger with the canister id mxzaz-hqaaa-aaaar-qaada-cai which is running on mainnet, the following call could be used: 

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

This call specifies a port using --port which is used to publish through Docker. The default port if not specified is 8080. The default network is the testnet. This command starts the software on the local host and displays output similar to the following:

2024-04-11T08:03:55.720213Z  INFO rs/rosetta-api/icrc1/rosetta/src/main.rs:403: Starting Rosetta server
⠖ [00:02:10] [#############################>-----------------------------------------------------------------------------------------------------------------------------------------------------------------] (628.8s)

For further help on what the options for ICRC-Rosetta are, you can run the following command:

docker run \
    --interactive \
    --tty \
    --publish 8082:8082 \
    --rm \
    dfinity/ic-icrc-rosetta-api \
    --help

By default, this software does not connect to any ICRC-1 ledger canister running on the Internet Computer blockchain mainnet.

Currently, there is no ICRC-1 ledger running on the testnet. However, there are several test tokens running on mainnet such as ckTestBTC (mc6ru-gyaaa-aaaar-qaaaq-cai) and ckTestETH (apia6-jaaaa-aaaar-qabma-cai).

The first time you run the command, it might take some time for the node to catch up to the current link of the chain. When the node is caught up, you should see output similar to the following:

Synced Up to block height: 1357644

After that, ICRC Rosetta will update the account balances. Please wait for any queries that include fetching account balances until this process is done. The corresponding message you will see is:

Account Balances have been updated successfully

After completing this step, the node continues to run as a passive node that does not participate in block making.

Step 4: Open a new terminal window or tab and run the ps command to verify the status of the service.​

If you need to stop the service, press Ctrl-C. You might want to do this to change the canister identifier you are using, for example.

To test the integration after setting up the node, you will need to write a program to simulate a principal submitting a transaction or looking up an account balance.

Run the Rosetta node in production​

When you are finished testing, you should run the Docker image in production mode without the --interactive, --tty, and --rm command-line options. These command-line options are used to attach an interactive terminal session and remove the container, and are primarily intended for testing purposes. To run the software in a production environment, you can start the Docker image using the --detach option to run the container in the background and, optionally, specify the --volume command for storing blocks.

For more information about Docker command-line options, see the Docker reference documentation.

Requirements and limitations​

The integration software provided in the Docker image has one requirement that is not part of the standard Rosetta API specification.

For transactions involving ICRC-1 tokens, the unsigned transaction must be created less than 24 hours before the network receives the signed transaction. The reason for this is the deduplication mechanism which can be read up on here. Any submitted transaction that refers back to a too old transaction is rejected to maintain operational efficiency.

Other than this requirement, the Rosetta API integration software fully complies with all standard Rosetta endpoints and passes all of the rosetta-cli tests. The software can accept any valid Rosetta request. However, the integration software only prompts for transactions to be signed using Ed25519 and SECP256k1, rather than all the signature schemes listed, and only replies with a small subset of the potential responses that the specification supports. For example, the software doesn’t implement any of the UTXO features of Rosetta, so you won’t see any UTXO messages in any of the software responses.

How to use the Rosetta API

The interaction with the Rosetta node can be split in two different parts. The first part consists of fetching data from the ledger regarding blocks, transactions and balances. This part is called the data API. View the steps on how to interact with the data API. The second part is more complex. To allow users to sign transactions offline and send them back to Rosetta there are a few interactions that the user will have to follow with the Rosetta node. This part is called the flow of operations in the construction API. View an example of how to go through such a flow of operations. Although the example in this section corresponds to the ICP Rosetta, the flow of operations also applies to the ICRC Rosetta. The detailed commands for ICRC Rosetta will be discussed in this guide, but it is of benefit to the reader to first get familiar with the flow of operations.

Frequently asked questions​

The following questions come from the most commonly reported questions and blockers from the developer community regarding Rosetta integration with the Internet Computer.

The Rosetta node​

  • How do I connect the Rosetta node to the mainnet?​

    Use flags --network-type mainnet

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

    Search the Starting Rosetta API server startup log. There will be a log entry that says Synced Up to block height: XX. This message confirms that you are caught up with all blocks.

  • How to persist synced blocks data?​

    Mount the /data directory as a volume.

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

  • Is the Rosetta node versioned?​

    Yes, new versions are regularly published on DockerHub. It is recommended to use a specific version in production settings, e.g., dfinity/ic-icrc-rosetta-api:v1.0.0 You can query the version of a running Rosetta node using the /network/options endpoint.
$ curl -s -q -H 'Content-Type: application/json' -d '{
    "network_identifier": {
            "blockchain": "Internet Computer",
            "network": "mxzaz-hqaaa-aaaar-qaada-cai"
    },
    "metadata": {}
}' --location '0.0.0.0:8082/network/options' | jq '.version.node_version'

"1.0.0"