nanoreth

Hyperliquid archive node based on reth.

⚠️ IMPORTANT: System Transactions Appear as Pseudo Transactions

Deposit transactions from 0x222..22 to user addresses are intentionally recorded as pseudo transactions. This change simplifies block explorers, making it easier to track deposit timestamps. Ensure careful handling when indexing.

Prerequisites

Building NanoReth from source requires Rust and Cargo to be installed:

$ curl https://sh.rustup.rs -sSf | sh

How to run (mainnet)

The current state of the block files comprise of millions of small objects totalling over 20 Gigs and counting. The "requester pays" option means you will need a configured aws environment, and you could incur charges which varies according to destination (ec2 versus local).

1. this will backfill the existing blocks from Hyperliquid's EVM S3 bucket:

   use our rust based s3 tool wrapper to optimize your download experience - read more

   chmod +x ./etc/evm-block-sync/s3sync-runner.sh
   ./etc/evm-block-sync/s3sync-runner.sh

   or use the conventional aws cli

   aws s3 sync s3://hl-mainnet-evm-blocks/ ~/evm-blocks \
     --request-payer requester \
     --exact-timestamps \                  
     --size-only \                        
     --only-show-errors

2. $ make install - this will install the NanoReth binary.

3. Start NanoReth which will begin syncing using the blocks in ~/evm-blocks:

   $ reth node --http --http.addr 0.0.0.0 --http.api eth,ots,net,web3 --ws --ws.addr 0.0.0.0 --ws.origins '*' --ws.api eth,ots,net,web3 --ingest-dir ~/evm-blocks --ws.port 8545

4. Once the node logs stops making progress this means it's caught up with the existing blocks.

   Stop the NanoReth process and then start Goofys: $ goofys --region=ap-northeast-1 --requester-pays hl-mainnet-evm-blocks evm-blocks

   Goofys will mount the AWS S3 bucket into ~/evm-blocks and save new blocks as they are added to the bucket.

   You can now restart NanoReth using the same command as above:

   $ reth node --http --http.addr 0.0.0.0 --http.api eth,ots,net,web3 --ws --ws.addr 0.0.0.0 --ws.origins '*' --ws.api eth,ots,net,web3 --ingest-dir ~/evm-blocks --ws.port 8545

How to run (mainnet) (with local block sync)

You can choose to source blocks from your local instance of hl-node instead of relying on an s3 replica. This will require you to first have a hl-node outputting blocks prior to running the initial s3 sync, the node will prioritise locally produced blocks with a fallback to s3. This method will allow you to reduce the need to rely on goofys.

It is recommended that you periodically sync evm-blocks from s3 so you have a fallback in case your hl-node fails, as hl-node will not backfill evm blocks.

# Run your local hl-node (make sure output file buffering is disabled)
# Make sure evm blocks are being produced inside evm_block_and_receipts
$ hl-node run-non-validator --replica-cmds-style recent-actions --serve-eth-rpc --disable-output-file-buffering

# Fetch EVM blocks (Initial sync)
$ aws s3 sync s3://hl-mainnet-evm-blocks/ ~/evm-blocks --request-payer requester # one-time

# Run node (with local-ingest-dir arg)
$ make install
$ reth node --http --http.addr 0.0.0.0 --http.api eth,ots,net,web3 \
    --ws --ws.addr 0.0.0.0 --ws.origins '*' --ws.api eth,ots,net,web3 --ingest-dir ~/evm-blocks --local-ingest-dir <path-to-your-hl-node-evm-blocks-dir> --ws.port 8545

How to run (testnet)

Testnet is supported since block 21304281.

Note

To run testnet locally, you will need:

• git lfs
• rust toolchain

# Get testnet genesis at block 21304281
$ cd ~
$ git clone https://github.com/sprites0/hl-testnet-genesis
$ git -C hl-testnet-genesis lfs pull
$ zstd --rm -d ~/hl-testnet-genesis/*.zst

# Now return to where you have cloned this project to continue
$ cd -

# prepare your rust toolchain
$ rustup install 1.82 # (this corresponds with rust version in our Cargo.toml)
$ rustup default 1.82

# Init node
$ make install
$ reth init-state --without-evm --chain testnet --header ~/hl-testnet-genesis/21304281.rlp \
  --header-hash 0x5b10856d2b1ad241c9bd6136bcc60ef7e8553560ca53995a590db65f809269b4 \
  ~/hl-testnet-genesis/21304281.jsonl --total-difficulty 0 

# Run node
$ reth node --chain testnet --http --http.addr 0.0.0.0 --http.api eth,ots,net,web3 \
    --ws --ws.addr 0.0.0.0 --ws.origins '*' --ws.api eth,ots,net,web3 --ingest-dir ~/evm-blocks --ws.port 8546