Implementing Rosetta Data API of VeChainThor BlockChain
- Clone the repo
git clone https://github.com/vechain/rosetta.git
cd rosettaThe project uses a multi-stage Docker build process for optimal deployment. This configuration:
- Builds the Thor binary and Node.js application in separate stages
- Mounts a local data directory for persistence
- Exposes all necessary ports for the Rosetta API and Thor node
- Sets up environment variables for network type and run mode
To use docker-compose:
# Build and start the container
docker-compose up -d
# View logs
docker-compose logs -f rosetta-server
# Stop the container
docker-compose downThe configuration can be customized by modifying the docker-compose.yml file:
- Change the data directory path in the volumes section
- Modify the exposed ports if needed
- Adjust environment variables (NETWORK and MODE)
- Update the build context if needed
version: '3.8'
services:
rosetta-server:
build:
context: .
volumes:
- ./data:/data # Points to your local directory
ports:
- "8080:8080" # Rosetta API
- "8669:8669" # Thor node
- "11235:11235" # P2P
- "11235:11235/udp" # P2P UDP
environment:
- NETWORK=main
- MODE=online
restart: unless-stoppedRosetta can send one client ID header on every call it makes to the thor node, so a node gateway can attribute or authenticate the traffic. It is off by default, and then nothing changes.
CLIENT_ID_HEADER: the header name, for examplex-client-id.CLIENT_ID_DEFAULT: the value sent on node calls Rosetta makes on its own: the startup check and head tracking over HTTP and websocket.
On node calls made while serving a request, Rosetta forwards the request's value of that header. A request without the header sends none; Rosetta does not fill in the default for it.
environment:
- NETWORK=main
- MODE=online
- CLIENT_ID_HEADER=x-client-id
- CLIENT_ID_DEFAULT=internal/rosetta- The request's value is kept per request and added to each node call at send time. It is never stored on a shared HTTP client, so one caller's value does not appear on another caller's node calls.
- Rosetta caches some node responses and merges identical node calls that are in flight at the same time. A request served from cache makes no node call, and a merged call carries the client ID of the request that started it. If the node rejects calls without a client ID, a caller can therefore get an error from a merged call started by a request that had none.
- Because of that caching and merging, the header is suited to attribution and to authenticating Rosetta to the node, not to per-caller authorization enforced by the node. Authenticate and authorize callers before they reach Rosetta.
- Header names that would break the node call (
host,content-length,content-type,transfer-encoding,connection,upgrade,accept,sec-websocket-*) are refused with a warning. Header values are never logged.
Tests are grouped in three categories. All of them run against Rosetta with an embedded thor solo node (NETWORK=custom):
| Category | Location | Command | What it checks |
|---|---|---|---|
| Unit | tests/unit |
npm run test:unit |
Runs without docker or a thor node. Covers the client ID header (CLIENT_ID_HEADER, CLIENT_ID_DEFAULT). |
| Static API | tests/e2e/api |
npm run test:api |
Calls every endpoint, including error paths, and validates the responses against the Rosetta spec schema. Values are not checked. |
| Solo cross-check | tests/e2e/solo |
npm run test:solo |
Compares response values and logic with the thor node API: blocks, balances, operations derived from receipts, constructed vs. packed transactions, fees. |
| rosetta-cli flow | tests/rosetta-cli |
npm run test:rosetta-cli:solo / :test / :main |
Runs rosetta-cli against thor solo (check:construction and check:data), testnet or mainnet (check:data on recent blocks). See rosetta-cli Validation. |
| SDK conformance | tests/sdk-conformance |
npm run test:sdk-conformance |
Records every request/response of the static API and solo tests, then checks each against rosetta-sdk-go v0.8.3 (the SDK rosetta-cli is built on): strict decoding into the SDK types (no unknown or missing fields) plus the SDK server/client asserters. Requires Go. |
# Install dependencies and build the Rosetta image (thor is compiled from source)
npm ci
docker compose build
# Static API + solo cross-check tests (same as `npm test`)
npm run test:e2enpm run test:e2e, test:api and test:solo start a fresh environment once per run and stop it afterwards. Set E2E_REUSE_ENV=1 to run against an environment that is already up (NETWORK=custom MODE=online docker compose up -d) and keep it running, which is faster while iterating.
The tests and tests/rosetta-cli/run.sh solo use their own compose project (rosetta-e2e) and data dir (./.e2e_data), so a node started with npm run start:* in ./rosetta_data is left untouched. Both bind port 8080, so stop that node before running the tests.
Tests for confirmed, not yet fixed bugs are declared with knownBug (tests/e2e/utils/knownBug.ts): they pass while the bug exists and fail once it is fixed. Run with E2E_KNOWN_BUGS=run to see the actual failures.
To test Rosetta against a specific Thor branch or version, use the THOR_REPO and THOR_VERSION build arguments:
# Test against a specific Thor branch
THOR_REPO=https://github.com/vechain/thor.git \
THOR_VERSION=your-branch-name \
docker compose build --no-cache
# Then run tests
npm run test:e2eNote: Build arguments (THOR_REPO, THOR_VERSION) must be set during docker compose build, not when starting containers. They determine which Thor version gets compiled into the image.
# Start services with default Thor
npm run start:custom
# Stop services
npm run stop
# View logs
docker compose logs -f rosetta-server
# Clean everything and rebuild
docker compose down -v
rm -rf ./rosetta_data/*
docker compose build --no-cacherosetta-cli checks the implementation against the Rosetta spec. check:construction builds, signs and broadcasts VET and VTHO transfers; check:data syncs the chain and reconciles every balance it sees. Configurations live in rosetta-cli-conf/ (solo, testnet, mainnet).
tests/rosetta-cli/run.sh <solo|test|main> builds the Rosetta image and a Linux rosetta-cli image (rosetta-cli-conf/bin/rosetta-cli is a macOS arm64 binary), runs the checks and stops what it started:
| Command | Network | Checks | Setup |
|---|---|---|---|
npm run test:rosetta-cli:solo |
thor solo, fresh chain | check:construction, then check:data from genesis |
Rosetta with an embedded thor solo node (docker compose). Runs in CI. |
npm run test:rosetta-cli:test |
testnet | check:data on the last BLOCKS blocks (default 500) |
Rosetta only, connected to NODE_URL (default https://testnet.vechain.org). |
npm run test:rosetta-cli:main |
mainnet | check:data on the last BLOCKS blocks (default 50) |
Rosetta only, connected to NODE_URL (default https://mainnet.vechain.org). |
npm run test:rosetta-cli:solo
BLOCKS=200 NODE_URL=http://localhost:8669 npm run test:rosetta-cli:main # a local, synced mainnet nodetestnet and mainnet are checked on a window of recent blocks rather than the whole chain: the check finishes in minutes, and the historical balance lookups stay within the state that a pruned node still keeps. Testnet carries few transactions, hence the larger default window; the script warns when a window contains no balance change to reconcile.
Set SKIP_BUILD=1 to reuse existing images and REUSE_ENV=1 to use a Rosetta that is already running on port 8080. Results are written to cli-data/<solo|test|main>/.
Note: VTHO has a dynamic balance exemption because it accrues every block, so rosetta-cli does not reconcile VTHO balances. VTHO correctness is covered by the solo cross-check tests in tests/e2e/solo/account.solo.test.ts instead.
This implementation is meant to cover this reference.
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /account/balance | Yes | Get an Account Balance | online |
| POST | /account/coins | No |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /block | Yes | Get a Block | online |
| POST | /block/transaction | Yes | Get a Block Transaction | online |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /call | No | Make a Network-Specific Procedure Call |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /construction/combine | Yes | Create Network Transaction from Signatures | online & offline |
| POST | /construction/derive | Yes | Derive an AccountIdentifier from a PublicKey | online & offline |
| POST | /construction/hash | Yes | Get the Hash of a Signed Transaction | online & offline |
| POST | /construction/metadata | Yes | Get Metadata for Transaction Construction | online |
| POST | /construction/parse | Yes | Parse a Transaction | online & offline |
| POST | /construction/payloads | Yes | Generate an Unsigned Transaction and Signing Payloads | online & offline |
| POST | /construction/preprocess | Yes | Create a Request to Fetch Metadata | online & offline |
| POST | /construction/submit | Yes | Submit a Signed Transaction | online |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /events/blocks | Yes | [INDEXER] Get a range of BlockEvents | online |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /mempool | Yes | Get All Pool Transactions from the Node | |
| POST | /mempool/transaction | Yes | Get a Pool Transaction from the Node |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /network/list | Yes | Get List of Available Networks | online & offline |
| POST | /network/options | Yes | Get Network Options | online & offline |
| POST | /network/status | Yes | Get Network Status | online |
| Method | Endpoint | Implemented | Description | Mode |
|---|---|---|---|---|
| POST | /search/transactions | Yes | [INDEXER] Search for Transactions | online |
- VeChain Rosetta implement support Fee Delegation (VIP-191).
- The exchange will transfer currencies from hot wallet to the safe cold wallet from time to time. When there's not enough VTHO in the hot wallet or want to transfer all currencies includ VTHO, the exchange can use VIP191 function to pay the transaction fee.
- Step 1: Create a VIP191 payload
Create a VIP191 payload, add FeeDelegation operation to operations, account is fee delegator address, amount.value default 0.
{
"network_identifier": {
"blockchain": "vechainthor",
"network": "test"
},
"operations": [
{
"operation_identifier": {
"index": 0,
"network_index": 0
},
"type": "Transfer",
"status": "None",
"account": {
"address": "0x16277a1ff38678291c41d1820957c78bb5da59ce"
},
"amount": {
"value": "10000",
"currency": {
"symbol": "VET",
"decimals": 18
},
"metadata": {}
}
},
{
"operation_identifier": {
"index": 0,
"network_index": 1
},
"type": "Transfer",
"status": "None",
"account": {
"address": "0xc05c334533c673582616ac2bf404b6c55efa1087"
},
"amount": {
"value": "-10000",
"currency": {
"symbol": "VET",
"decimals": 18
},
"metadata": {}
}
},
{
"operation_identifier": {
"index": 0,
"network_index": 2
},
"type": "FeeDelegation",
"status": "None",
"account": {
"address": "0x4251630dc820e90a5a6d14d79cac7acb93917983"
},
"amount": {
"value": "-210000000000000000",
"currency": {
"symbol": "VTHO",
"decimals": 18,
"metadata": {
"contractAddress": "0x0000000000000000000000000000456E65726779"
}
},
"metadata": {}
}
}
]
}- Step 2: Call /construction/preprocess
When calling /construction/preprocess use VIP191 payloads, the api will return options and two required_public_keys, the first is transaction origin's public key,the second is fee delegation payer's public key.
{
"options": {
"clauses": [
{
"to": "0x16277a1ff38678291c41d1820957c78bb5da59ce",
"value": "10000",
"data": "0x00"
}
]
},
"required_public_keys": [
{
"address": "0xc05c334533c673582616ac2bf404b6c55efa1087"
},
{
"address": "0x4251630dc820e90a5a6d14d79cac7acb93917983"
}
]
}- Step 3: Call /construction/metadata
Use step 2 return value to call /construction/metadata, the api will calculate the gas online, return metadata and suggested_fee.
{
"metadata": {
"blockRef": "0x00d88b4ab127a39e",
"chainTag": 39,
"gas": 25200
},
"suggested_fee": [
{
"value": "2520000000",
"currency": {
"symbol": "VTHO",
"decimals": 18,
"metadata": {
"contractAddress": "0x0000000000000000000000000000456E65726779"
}
}
}
]
}- Step 4: Call /construction/payloads
{
"network_identifier": {
"blockchain": "vechainthor",
"network": "test"
},
"operations": [
{
"operation_identifier": {
"index": 0,
"network_index": 0
},
"type": "Transfer",
"status": "None",
"account": {
"address": "0x16277a1ff38678291c41d1820957c78bb5da59ce"
},
"amount": {
"value": "10000",
"currency": {
"symbol": "VET",
"decimals": 18
},
"metadata": {}
}
},
{
"operation_identifier": {
"index": 0,
"network_index": 1
},
"type": "Transfer",
"status": "None",
"account": {
"address": "0xc05c334533c673582616ac2bf404b6c55efa1087"
},
"amount": {
"value": "-10000",
"currency": {
"symbol": "VET",
"decimals": 18
},
"metadata": {}
}
},
{
"operation_identifier": {
"index": 0,
"network_index": 2
},
"type": "FeeDelegation",
"status": "None",
"account": {
"address": "0x4251630dc820e90a5a6d14d79cac7acb93917983"
},
"amount": {
"value": "-210000000000000000",
"currency": {
"symbol": "VTHO",
"decimals": 18,
"metadata": {
"contractAddress": "0x0000000000000000000000000000456E65726779"
}
},
"metadata": {}
}
}
],
"metadata": {
"blockRef": "0x00d88b4ab127a39e",
"chainTag": 39,
"gas": 25200
},
"public_keys": [
{
"hex_bytes": "02d992bd203d2bf888389089db13d2d0807c1697091de377998efe6cf60d66fbb3",
"curve_type": "secp256k1"
},
{
"hex_bytes": "03a7e5b27bf35f3b1a863851a02b4d722927cd12f92bfb21f69c81c22fc4a1c6d3",
"curve_type": "secp256k1"
}
]
}The api will return unsigned_transaction and payloads.
{
"unsigned_transaction": "0xf85d278800d88b4ab127a39e81b4dad99416277a1ff38678291c41d1820957c78bb5da59ce822710808262708827c7571b85f5271594c05c334533c673582616ac2bf404b6c55efa1087944251630dc820e90a5a6d14d79cac7acb93917983",
"payloads": [
{
"address": "0xc05c334533c673582616ac2bf404b6c55efa1087",
"hex_bytes": "3fec5f2cfdd172e1372879992644513578a9917355488e23d5abf846990c1fe2",
"signature_type": "ecdsa_recovery"
},
{
"address": "0x4251630dc820e90a5a6d14d79cac7acb93917983",
"hex_bytes": "16ff81dd942a6e42c6a352dbcf5615693c3659feb35cdc177d27a2851b73ee40",
"signature_type": "ecdsa_recovery"
}
]
}- Step 5: Sign with transaction orgin and fee delegation payer private keys and call
/construction/combine
{
"network_identifier": {
"blockchain": "vechainthor",
"network": "test"
},
"unsigned_transaction": "0xf85d278800d852ba843f1d4181b4dad99416277a1ff38678291c41d1820957c78bb5da59ce8227108082627088556581012357229594c05c334533c673582616ac2bf404b6c55efa1087944251630dc820e90a5a6d14d79cac7acb93917983",
"signatures": [
{
"signing_payload": {
"address": "0xc05c334533c673582616ac2bf404b6c55efa1087",
"hex_bytes": "3fec5f2cfdd172e1372879992644513578a9917355488e23d5abf846990c1fe2",
"signature_type": "ecdsa_recovery"
},
"public_key": {
"hex_bytes": "02d992bd203d2bf888389089db13d2d0807c1697091de377998efe6cf60d66fbb3",
"curve_type": "secp256k1"
},
"signature_type": "ecdsa_recovery",
"hex_bytes": "4ad82781abf5866020c9bf6a7b07f94ba4bb9e95ac1ca3c858ded24c08b6856213589bac265f656a87da255b855cfab9a96020d450593df2481015188ae7927000"
},
{
"signing_payload": {
"address": "0x4251630dc820e90a5a6d14d79cac7acb93917983",
"hex_bytes": "16ff81dd942a6e42c6a352dbcf5615693c3659feb35cdc177d27a2851b73ee40",
"signature_type": "ecdsa_recovery"
},
"public_key": {
"hex_bytes": "036aafc0aa461c6b2de2ca8a254ebc6685946a08dd7656dbb935ce4ce5cfac355b",
"curve_type": "secp256k1"
},
"signature_type": "ecdsa_recovery",
"hex_bytes": "7d6df64de2c4084b7809bdeba85784c6d031dd943e96271ac1cd22f3da9b5c3f2e610ec2d50e576583cff2d386fd6f7069b2883ca023b6000575ec0fcf4ddc9800"
}
]
}