Jovay RPC Node Deployment and Management Manual

Version Release History

Release Date	Product Version	Build Version	Docker Image	Description
2026.09.02	0.15.0	0.15.0-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.15.0-rc1	Adds BatchV3-compatible L1 message processing and V30-gated L1 message signature verification. Standard RPC nodes only require an image upgrade.
2026.06.26	0.14.0	0.14.0-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.14.0-rc1	Introduces State Derivation and hardens RPC behavior for oversized `eth_call` input and interrupted WebSocket subscriptions. Standard RPC nodes only require an image upgrade. Release notes.
2026.05.12	0.13.0	0.13.0-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.13.0-rc1	Optimized historical state query caching, greatly reducing memory usage and startup time
2026.04.03	0.12.1	0.12.1-rc2	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.12.1-rc2	Fix an issue where, under a special EIP-7702 case, the RPC node could fork from the consensus node
2026.04.03	0.12.1	0.12.1-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.12.1-rc1	Support EIP-7702
2026.02.05	0.11.1	0.11.1-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.11.1-rc1	Fix create contract nonce when value is not enough, fix modexp crash for invalid input
2026.02.05	0.11.0	0.11.0-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.11.0-rc1	Add support for debug_traceCall, migrate spec version management to a system contract, and apply relayer fixes and optimizations based on Zellic audit recommendations.
2026.01.06	0.10.0	0.10.0-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.10.0-rc1	Support deploy Multicall3, create2 factory with non-EIP-155 raw transaction. Fix issues of eth_debugTraceTransaction. Introducing more cross-chain and asset security validations.
2025.12.17	0.9.0	0.9.0-rc6	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.9.0-rc6	Fix the batch RPC request id mismatch issue, including edge cases. This release supersedes rc4 and is the recommended version for production use.
2025.12.17	0.9.0	0.9.0-rc4	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.9.0-rc4	Fix the issue of mismatched request id in batch RPC. Known issues remain in some batch RPC edge cases. Recommended to upgrade to rc6.
2025.12.12	0.9.0	0.9.0-rc3	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.9.0-rc3	Fix eth_call with invalid block; Support non-root deployment
2025.12.01	0.9.0	0.9.0-rc2	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.9.0-rc2	Fix batchrpc, debug_traceTransaction
2025.11.21	0.9.0	0.9.0-rc1	jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.9.0-rc1	First release for external RPC node

Current release image

The current RPC node release is v0.15.0-rc1:

Item	Value
Image	`jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.15.0-rc1`
Digest	`sha256:612c692655744444f512ef084ff2365c1ec26594d67ade01b8163250442e5c3a`
OS / Architecture	`linux/amd64`

RPC node deployment

Jovay RPC node can be deployed using a Docker image. Before deployment, please ensure that the machine specifications meet the required standards.

This guide provides detailed instructions for setting up the node. Once deployed, you can use this RPC node to connect to the Jovay network, synchronize the latest Jovay blocks, query historical block states, simulate transactions, and send transactions to the Jovay network.

Prerequisites

Recommended hardware specifications

Component	Specification
CPU	16 cores, 2.7GHz or faster
Memory	128G
Storage	1TB(for mainnet)/2TB(for testnet) SSD with at least 350MiB/s bandwidth and 10000 IOPS
Storage Growth Rate	50GB/month
Network Bandwidth	500 Mbps
Open Files Limit	ulimit -n (≥ 655350)

System requirements

Docker Engine (>= 27.3.1)
Docker Compose (>= 2.29.7)

privilege requirement

Versions before 0.9.0-rc3 must run with the root user.
Starting from 0.9.0-rc3, run with a non-root user is supported:
1. The host user must belong to the docker group so that it have permission to use Docker.
2. Inside the container, the processes run as a user with a fixed uid=1000 and gid=1000. So ensure that the deploy directory are writable by the user with uid=1000 or group with uid=1000.
Enable privileged mode for the Docker container (optional, but convenient for attaching with gdb inside the container at runtime).

network accessibility

Ensure that your network can reach the Jovay Network. The endpoint is specified in Section 2.2.2.3.

Jovay testnet

HTTP: alb-ism8q21lfjeen07hq3.ap-southeast-1.alb.aliyuncsslbintl.com
P2P: 43.106.17.221:52399, 3.106.17.221:52398

Jovay mainnet

HTTP: alb-cnjrn9zqms3o5flehu.cn-hongkong.alb.aliyuncsslbintl.com
P2P: 47.83.131.74:52398, 47.83.131.74:52399

Deployment Steps

Prepare workspace

Create workspace dictionary.

bash

export Build_Version=0.15.0-rc1
export Docker_Image=jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:${Build_Version}
export Release=${Build_Version}
export DEPLOY_DIR=${deploy_jovay_rpc_path}

mkdir $DEPLOY_DIR
cd $DEPLOY_DIR

Refer to Section 1 to get the ${Build_Version}.

Prepare configuration

initial configuration

The configuration is included in the released docker image, and the default settings work out of the box. For easier modification, consider extracting the configuration to the host and mounting it into the container, so you can edit the configuration directly on the host.

bash

cd $DEPLOY_DIR
docker create --name temp_container ${Docker_Image}
docker cp temp_container:/opt/l2_deploy/conf ./
docker rm temp_container

Refer to Section 1 to get the ${Docker_Image}.

genesis file and spec version file

The genesis file defines the initial state of the Jovay Network. All nodes joining the Jovay network must use an identical genesis file to ensure they start synchronization from the exact same point.
The spec version file records the complete protocol changes of the Jovay network. All nodes must use the same spec version file and update it synchronously during network protocol upgrades.

Both files are officially released and maintained by the Jovay Network team. Copy them to the conf directory using the commands below.

Jovay testnet

yaml

# get the genesis file
url_genesis="http://dl-testnet.jovay.io/snapshot/genesis.conf"
md5_genesis="1b6ad3d9fa67a596ca094e89bd2280ee"
dst_genesis="$DEPLOY_DIR/conf/genesis.aldaba-ng.conf"
wget $url_genesis -O genesis.conf
# check md5 then put the genesis file to conf dir
echo "$md5_genesis genesis.conf" | md5sum -c - && mv genesis.conf $dst_genesis

# get the version file
url_version="http://dl-testnet.jovay.io/snapshot/VERSION_epoch26280"
md5_version="994db44ba74a280efe44efdcd3f4422d"
dst_version="$DEPLOY_DIR/conf/VERSION"
wget $url_version -O VERSION
# check md5 then put the version file to conf dir
echo "$md5_version VERSION" | md5sum -c - && mv VERSION $dst_version

Jovay mainnet

yaml

# get the genesis file
url_genesis="http://dl.jovay.io/snapshot/genesis.conf"
md5_genesis="502c910cbc21137c606621622fe67d28"
dst_genesis="$DEPLOY_DIR/conf/genesis.aldaba-ng.conf"
wget $url_genesis -O genesis.conf
# check md5 then put the genesis file to conf dir
echo "$md5_genesis genesis.conf" | md5sum -c - && mv genesis.conf $dst_genesis

# get the version file
url_version="http://dl.jovay.io/snapshot/VERSION_epoch16905"
md5_version="3b8bfc464d24c101e0b407aeba200345"
dst_version="$DEPLOY_DIR/conf/VERSION"
wget $url_version -O VERSION
# check md5 then put the version file to conf dir
echo "$md5_version VERSION" | md5sum -c - && mv VERSION $dst_version

docker-compose.yml

prepare docker compose file for jovay rpc node. if run as non-root user:

Make sure the user (1000:1000) has write permission to $DEPLOY_DIR (including all its subdirectories and files).
Add "user: 1000:1000" to the docker-compose.yml file.

docker-compose.yml for Jovay testnet rpc node

yaml

services:
  rpc-node:
    image: ${Docker_Image}
    container_name: jovay-rpc
    stop_grace_period: 300s
    environment:
      - SEQUENCER_ADVERTISE_NODE_URL=alb-ism8q21lfjeen07hq3.ap-southeast-1.alb.aliyuncsslbintl.com:80
      - EXTERNAL_CLB_PRE_EXPOSERPC_URL=noise_tcp://43.106.17.221:52399?2d655725a449ef9f5f1b048d596736c0e4aaaac3fd9b6bd3f7eef5dee8517d7d;noise_tcp://43.106.17.221:52398?c9664991ff25fd390f10d29c1e024594067f4e00ef470388e89f29bd9a403d23
    privileged: true
    ports:
      - "18100:18100"  # HTTP port (client_http_port)
      - "18200:18200"  # WebSocket port (client_ws_port)
      - "19000:19000"  # Node communication port
    volumes:
      - $DEPLOY_DIR/data:/opt/l2_deploy/light/data
      - $DEPLOY_DIR/log:/opt/l2_deploy/light/log
      - $DEPLOY_DIR/conf:/opt/l2_deploy/conf
      - $DEPLOY_DIR/conf/VERSION:/opt/l2_deploy/bin/VERSION
    restart: "no"

docker-compose.yml for Jovay mainnet rpc node

yaml

services:
  rpc-node:
    image: ${Docker_Image}
    container_name: jovay-rpc
    stop_grace_period: 300s
    environment:
      - SEQUENCER_ADVERTISE_NODE_URL=alb-cnjrn9zqms3o5flehu.cn-hongkong.alb.aliyuncsslbintl.com:80
      - EXTERNAL_CLB_PRE_EXPOSERPC_URL=noise_tcp://47.83.131.74:52398?842016e6eb94da561b1b4c856e08bf71cd70c05ea847e934b8be1d5a74a979f8;noise_tcp://47.83.131.74:52399?ce08efde90a7970d18dd6763fdc68d19a24084fd7c8cf67a68a19e943b30c5e3
    privileged: true
    ports:
      - "18100:18100"  # HTTP port (client_http_port)
      - "18200:18200"  # WebSocket port (client_ws_port)
      - "19000:19000"  # Node communication port
    volumes:
      - $DEPLOY_DIR/data:/opt/l2_deploy/light/data
      - $DEPLOY_DIR/log:/opt/l2_deploy/light/log
      - $DEPLOY_DIR/conf:/opt/l2_deploy/conf
      - $DEPLOY_DIR/conf/VERSION:/opt/l2_deploy/bin/VERSION
    restart: "no"

Refer to Section 1 to get the ${Docker_Image}. "privileged: true" is not compulsory, which is convenient for attaching with gdb inside the container at runtime.

Start the node

bash

cd $DEPLOY_DIR
docker-compose up -d

After starting the container, watch the container’s standard output:

bash

docker logs -f jovay-rpc

Once you see App Initialize succeed, the rpc node has started successfully.

After that, you can monitor block production and transaction activity via log/profile.log.

Verify synchronization

After launching your node, using the following command to checking the current block height.

bash

curl 127.0.0.1:18100/ \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'

The node will begin synchronizing from block height 0x0.

If you wish to accelerate synchronization and quickly catch up to the latest chain state, consider bootstrapping your node from a trusted snapshot state provided by the Jovay Network team.

For detailed instructions on how to initialize your node using a snapshot, refer to the next section.

Fast Sync via State Snapshot

Ensure you have completed the deployment described in Section 1, so that the metadata and identity keys are ready.

Follow these steps to bootstrap from latest snapshot:

✅ Download snapshot dataset

⚠️ WARNING: Only use snapshots from offical channels. Verify checksums before deployment.

These snapshots are for standard RPC nodes. For State Derivation Sequencers, use the SD snapshots.

Download and verify the snapshot for your network:

Jovay testnet

bash

# File: 20261022_47857436.tar.gz (≈134.3 GiB)
# MD5: 5ba5ef22207db6d4a3a17b08b68e106a
# Block Height: 47857436
wget -c https://dl-testnet.jovay.io/snapshot/20261022_47857436.tar.gz
echo '5ba5ef22207db6d4a3a17b08b68e106a  20261022_47857436.tar.gz' | md5sum -c -

Jovay mainnet

bash

# File: 20261022_13640174.tar.gz (≈18.4 GiB)
# MD5: 8d4115f3ff3bf22f501f219acab770e7
# Block Height: 13640174
wget -c https://dl.jovay.io/snapshot/20261022_13640174.tar.gz
echo '8d4115f3ff3bf22f501f219acab770e7  20261022_13640174.tar.gz' | md5sum -c -

Note: Check for the latest version matching your network.
The naming format of the snapshot is Date_BlockHeight.tar.gz.

🧯 Stop container

bash

cd $DEPLOY_DIR
docker-compose down

🧹 Replace local data with snapshot

bash

# Remove existing unsynced data
rm -rf $DEPLOY_DIR/data/public
rm -rf $DEPLOY_DIR/data/history_kvdbs

# decompress snapshot to data dir
tar -zxvf <snapshot_file_name>.tar.gz -C $DEPLOY_DIR/data/

🚀 Restart node

bash

cd $DEPLOY_DIR
docker-compose up -d

The startup time when using a snapshot can be relatively long, depending on the number of historical blocks and the size of the state data.

On Jovay testnet, the current snapshot takes about 30 minutes to start. On Jovay mainnet, it will be much faster.

When you see the following two log entries in log/aldaba.log, it indicates that the snapshot has finished loading and the node will start syncing blocks:

bash

HandleConsensusedResultAfterInit] stable block
CheckSyncStatus] start sync

On-click deployment

To make deployment easier, we provide a one-click deployment script that allows you to conveniently do the following:

fresh-genesis – start from genesis and sync from block 0
fresh-snapshot – fresh deployment: use genesis first to generate metadata, then replace data with a snapshot and restart

If the host user is root or has UID=1000, and the jovay-rpc container is also started with the same user, this script can help you complete all deployment and startup tasks. Otherwise, you need to create the deployment directory in advance that meets the permission requirements, and adjust the permissions again after extract the init configuration files from images.

bash

# Download Jovay on-click deploy script
# MD5: 4e8a71d952db82a2e81daf8b5599ca15
wget -c http://dl-testnet.jovay.io/snapshot/jovay_rpc_deploy.sh
# Run it, then just follow the prompts to make your selections.
./jovay_rpc_deploy.sh

Upgrade RPC node to v0.15.0-rc1

This procedure applies to upgrades from v0.14.x to v0.15.0-rc1. If your node is older than v0.14.x, follow the required intermediate release instructions or contact the Jovay team before upgrading.

The v0.15.0-rc1 RPC node adds BatchV3-compatible L1 message processing and V30-gated L1 message signature verification. Upgrade all RPC nodes before the network operator activates V30 and BatchV3.

For a standard external RPC node, this is an image-only upgrade:

Preserve the existing data/, log/, and conf/ mounts.
Do not replace the snapshot or delete chain data.
Do not update conf/VERSION; protocol versions are managed by the system contract.
Do not enable state_derivation_mode or configure the L1 message Relayer address locally.

1. Record the current deployment

The RPC service is temporarily unavailable while its container is recreated. For production deployments, remove the node from the load balancer or upstream traffic entry first, and upgrade nodes one at a time.

bash

export DEPLOY_DIR=${deploy_jovay_rpc_path}
export Build_Version=0.15.0-rc1
export Docker_Image=jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:${Build_Version}

cd "$DEPLOY_DIR"
docker inspect --format '{{.Config.Image}}' jovay-rpc
cp docker-compose.yml "docker-compose.yml.bak.$(date +%Y%m%d%H%M%S)"

Record the current image printed by docker inspect; it is required if a coordinated rollback becomes necessary.

2. Pull and verify the release image

bash

docker pull "$Docker_Image"

docker buildx imagetools inspect "$Docker_Image"

Confirm that the image is linux/amd64 and its digest is:

text

sha256:612c692655744444f512ef084ff2365c1ec26594d67ade01b8163250442e5c3a

3. Update the image and recreate the container

Update the rpc-node service image in docker-compose.yml to:

yaml

services:
  rpc-node:
    image: jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc:0.15.0-rc1

On Linux, you can replace the existing l2-rpc image tag with:

bash

cd "$DEPLOY_DIR"
sed -i 's#\(jovay-release-registry.cn-hongkong.cr.aliyuncs.com/jovay/l2-rpc\):[^[:space:]]*#\1:'"${Build_Version}"'#g' docker-compose.yml
docker compose up -d

docker compose up -d recreates the container while preserving the mounted data, logs, and configuration.

4. Verify the upgrade

bash

# Confirm the target image and container status
docker inspect --format '{{.Config.Image}}' jovay-rpc
docker ps --filter name=jovay-rpc

# Confirm successful startup and continued synchronization
docker logs --tail 200 jovay-rpc
tail -f "$DEPLOY_DIR/log/profile.log" | grep 'Tag: UpdateStableBlock'

The container has initialized when App Initialize succeed appears. Confirm that the stable block height continues to increase, then query JSON-RPC:

bash

curl 127.0.0.1:18100/ \
  -X POST \
  -H 'Content-Type: application/json' \
  --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'

grep -iE 'error|fail|fatal' "$DEPLOY_DIR/log/aldaba.log" | tail -50

Repeat eth_blockNumber after a short interval and confirm that the height is increasing. Restore the node to the load balancer or upstream traffic only after these checks pass.

Rollback

If the node cannot start or catch up, first confirm whether V30 and BatchV3 have already been activated. Before activation, or during a rollback coordinated with the Jovay team, restore the previously recorded image in docker-compose.yml and recreate the container:

bash

cd "$DEPLOY_DIR"
docker compose up -d

Do not independently roll back to a pre-v0.15.0 image after V30 and BatchV3 have been activated. The old image does not implement the required protocol rules. Contact the Jovay team and use a network-compatible image or a coordinated network rollback procedure. Do not delete data/public or data/history_kvdbs during this upgrade or rollback unless the Jovay team explicitly instructs you to do so.

RPC node management

Stop node

bash

cd $DEPLOY_DIR
docker-compose down

Start node

bash

cd $DEPLOY_DIR
docker-compose up -d

Update configuration

Modify configuration files in host directory:

bash

cd $DEPLOY_DIR
# Edit conf/global.conf as needed

Restart node:

bash

docker compose -f $DEPLOY_DIR/docker-compose.yml restart

Check node liveness

You can verify node liveness by querying the block height through the eth_blockNumber API. If the node fails to return the current block height, or the block height does not increase over a period of time, this indicates a liveness problem with the node.

Query block height

Syncing status can be checked by eth_syncing json rpc method.

Request payloda:

yaml

curl 127.0.0.1:18100/ \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'

View logs

You can primarily monitor the node status through the following two log files:

log/profile.log: Profiling information of blocks and transactions.
log/aldaba.log: Default log file containing runtime information from all modules.

RPC node monitoring

We use the Prometheus and Grafana to monitor Jovay RPC Node metrics. but the full deployment and integration process has not yet been fully verified and will be documented later.

Jovay RPC Node Deployment and Management Manual ​

Version Release History ​

Current release image ​

RPC node deployment ​

Prerequisites ​

Recommended hardware specifications ​

System requirements ​

privilege requirement ​

network accessibility ​

Deployment Steps ​

Prepare workspace ​

Prepare configuration ​

initial configuration ​

genesis file and spec version file ​

docker-compose.yml ​

Start the node ​

Verify synchronization ​

Fast Sync via State Snapshot ​

✅ Download snapshot dataset ​

🧯 Stop container ​

🧹 Replace local data with snapshot ​

🚀 Restart node ​

On-click deployment ​

Upgrade RPC node to v0.15.0-rc1 ​

1. Record the current deployment ​

2. Pull and verify the release image ​

3. Update the image and recreate the container ​

4. Verify the upgrade ​

Rollback ​

RPC node management ​

Stop node ​

Start node ​

Update configuration ​

Check node liveness ​

Query block height ​

View logs ​

RPC node monitoring ​

Jovay RPC Node Deployment and Management Manual

Version Release History

Current release image

RPC node deployment

Prerequisites

Recommended hardware specifications

System requirements

privilege requirement

network accessibility

Deployment Steps

Prepare workspace

Prepare configuration

initial configuration

genesis file and spec version file

docker-compose.yml

Start the node

Verify synchronization

Fast Sync via State Snapshot

✅ Download snapshot dataset

🧯 Stop container

🧹 Replace local data with snapshot

🚀 Restart node

On-click deployment

Upgrade RPC node to v0.15.0-rc1

1. Record the current deployment

2. Pull and verify the release image

3. Update the image and recreate the container

4. Verify the upgrade

Rollback

RPC node management

Stop node

Start node

Update configuration

Check node liveness

Query block height

View logs

RPC node monitoring