Skip to content

README.md

Latest commit

 

History

History
283 lines (208 loc) · 12.5 KB

README.md

File metadata and controls

283 lines (208 loc) · 12.5 KB
Raw

arc-node-execution

This is a Reth-based execution layer (EL) implementation customized for the Arc Network.

It serves as the execution client that processes transactions, executes smart contracts, and maintains the blockchain state. Communication with the consensus layer (CL) is handled via the Engine API.

Table of Contents

Usage

a) Full Node

Minimal example with IPC (recommended for colocated execution and consensus):

arc-node-execution node \
  --chain=assets/localdev/genesis.json \
  --http --http.port=8545 \
  --ipcpath=/tmp/reth.ipc \
  --full

Full example with detailed configuration:

arc-node-execution node \
  --chain=assets/localdev/genesis.json \
  --datadir=/var/lib/arc-execution \
  --http --http.addr=0.0.0.0 --http.port=8545 \
  --http.api=eth,net,web3,txpool,trace,debug \
  --http.corsdomain="*" \
  --ws --ws.addr=0.0.0.0 --ws.port=8546 \
  --authrpc.addr=0.0.0.0 --authrpc.port=8551 --authrpc.jwtsecret=jwtsecret \
  --ipcpath=/tmp/reth.ipc \
  --metrics=0.0.0.0:9001 \
  --enable-arc-rpc \
  --full

Note: to generate a JWT (JSON web token), use the following command:

openssl rand -hex 32 | tr -d "\n" > "jwtsecret"

b) Unsafe RPC Node

Use RPC nodes to interact with the Arc network via API. While they don't participate in consensus, they stay fully synced with the latest state.

In this mode, consensus data is not verified. It is essential to only follow and synchronize with a trusted node.

# Download snapshot (this will help you sync much faster)
arc-node-execution download

arc-node-execution node \
  --unsafe-follow \
  --http --http.port=8545 \
  --http.api eth,net,web3,txpool,trace \
  --enable-arc-rpc \
  --minimal

Note: When running a node in RPC mode (as shown above), you do not need to run or download the consensus binary. The execution node will follow the network without participating in consensus.

c) RPC Node (with consensus verification)

For an RPC node with full consensus verification, run both the execution and consensus layers together. The --follow and --follow.endpoint flags are configured on arc-node-consensus, not this binary. See the Consensus Layer README for details on setting up a verified full node.

CLI Flags

For a complete list of available flags, see the Reth CLI reference or run:

arc-node-execution node --help

Custom flags

In addition to standard Reth flags, arc-node-execution provides the following custom flags:

Flag Default Environment Variable Description
--enable-arc-rpc false - Enable custom ARC RPC namespace (certificates, etc.)
--arc-rpc-upstream-url <URL> - ARC_RPC_UPSTREAM_URL Upstream malachite-app base URL for ARC RPC (e.g., http://127.0.0.1:31000). Only read if --enable-arc-rpc is set
--unsafe-follow [URL] - ARC_UNSAFE_FOLLOW_URL Run an RPC node (unsafe - no verification). Use without value for auto-config or specify WebSocket URL (e.g., ws://trusted-node:8546)
--invalid-tx-list-enable[=<bool>] true - Enable the invalid transaction list feature. Opt out with --invalid-tx-list-enable=false.
--invalid-tx-list-cap <CAPACITY> 100000 - Maximum capacity of the invalid tx list LRU cache. Only read if --invalid-tx-list-enable is true.
--arc.rpc.max-batch-entries <N> 100 - Maximum number of entries permitted in a JSON-RPC batch request. Oversized batches are rejected with JSON-RPC error -32600 before any per-entry handler runs. Must be >= 1.
--arc.builder.deadline <MS> Reth builder.deadline ARC_BUILDER_DEADLINE_MS Maximum transaction-selection duration in milliseconds. Overrides the equivalent Reth builder setting.
--arc.builder.wait-for-payload <BOOL> true ARC_BUILDER_WAIT_FOR_PAYLOAD Wait for in-flight payload building when engine_getPayload arrives early instead of racing an empty block.
--full - - Full-node pruning preset. Fully prunes sender recovery; keeps the last 237,600 blocks for all other segments. Also sets --prune.block-interval=128. Mutually exclusive with --minimal.
--minimal - - Minimal-storage pruning preset. Fully prunes sender recovery; keeps transaction lookup for 64 blocks, receipts for 64 blocks, account/storage history for 10,064 blocks, and block bodies for 237,600 blocks. Also sets --prune.block-interval=128. Mutually exclusive with --full.
--arc.expose-pending-txs false - Expose pending-tx RPCs. By default pending-tx subscriptions, filters, and pending-block queries are blocked — set this on trusted / internal nodes where exposing pending state is intentional.
--public-api false - Convenience flag for externally-exposed RPC nodes. Forces pending-tx hiding and warns if --http.api / --ws.api expose namespaces outside {eth, net, web3, rpc}. Conflicts with --arc.expose-pending-txs.
--arc.rpc.allow-unprotected-txs false - Accept pre-EIP-155 transactions through raw transaction submission RPC methods.
--arc.tx.relays <URLS> - ARC_TX_RELAYS Ordered comma-separated relay URLs for transaction failover. Conflicts with --rpc.forwarder.
--arc.tx.relays.timeout <DURATION> 10s ARC_TX_RELAYS_TIMEOUT Timeout for each transaction relay attempt. Accepts a duration or a number of seconds.
--txpool.rebroadcast-interval <SECONDS> 60 - Interval in seconds between transaction rebroadcast attempts. Set to 0 to disable.
--pprof.addr <ADDR> 0.0.0.0:6061 - Address for the pprof HTTP server.
--pprof.heap-prof false - Enable heap profiling when the binary is built with the pprof feature.

See Transaction Forwarding for relay ordering, timeout, and failure behavior.

Examples:

Enable ARC RPC namespace:

arc-node-execution node \
  --enable-arc-rpc \
  --arc-rpc-upstream-url http://localhost:31000 \
  --chain genesis.json

Override the invalid transaction list capacity (the feature is enabled by default):

arc-node-execution node \
  --invalid-tx-list-cap 50000 \
  --chain genesis.json

Disable the invalid transaction list:

arc-node-execution node \
  --invalid-tx-list-enable=false \
  --chain genesis.json

Tighten the JSON-RPC batch entry cap:

arc-node-execution node \
  --arc.rpc.max-batch-entries 25 \
  --chain genesis.json

Init

Initialize the database from a genesis file:

arc-node-execution init --chain=assets/localdev/genesis.json

This creates the genesis block and initializes the state database.

Database Commands

The db command provides database maintenance and debugging utilities.

For available database operations, run:

arc-node-execution db --help

Invalid Transaction List

The node includes an in-memory invalid transaction list (LRU) used to proactively reject known-bad transaction hashes and to add all currently pending transactions to the list in the event the payload builder panics. Enabled by default; opt out with --invalid-tx-list-enable=false.

Configuration:

Use the --invalid-tx-list-enable and --invalid-tx-list-cap flags (see Custom flags section above).

Behavior when enabled (default):

  • On payload builder panic, all pending transactions are added to the invalid tx list and removed from the mempool — resubmit them after investigating the panic
  • O(1) hash membership check during transaction validation
  • Metrics exposed: reth_arc_invalid_tx_list_size, reth_arc_invalid_tx_list_hits_total, reth_arc_invalid_tx_list_inserts_total, reth_arc_invalid_tx_list_batch_inserts_total

Behavior when disabled (--invalid-tx-list-enable=false):

  • No invalid tx list is created
  • No metrics are exposed
  • No hash quarantine: transactions are not rejected by hash during validation
  • On payload builder panic (or an unprocessable transaction), the pending/offending transactions are still removed from the mempool — only the hash quarantine and metrics are skipped

Example:

arc-node-execution node \
  --chain genesis.json \
  --invalid-tx-list-cap 10000

Operational Notes:

  • Setting --invalid-tx-list-cap 0 keeps the invalid tx list logically enabled (metrics + panic handling) but stores no hashes

Pending Txs Filter

By default, the node hides pending-tx RPCs. Pass --arc.expose-pending-txs to disable the filter on trusted / internal nodes. External / public-facing nodes should instead use --public-api, which also narrows the advised RPC surface.

When the filter is enabled (default, or enforced by --public-api):

Method or call Behavior
eth_subscribe("newPendingTransactions") Error -32001
eth_newPendingTransactionFilter Error -32001
eth_getBlockByNumber("pending") Returns null (success)

When the filter is disabled (--arc.expose-pending-txs):

All three methods bypass the middleware. Pending-block queries additionally depend on --rpc.pending-block (Arc default: none); to actually receive pending-block data, set --rpc.pending-block=full alongside --arc.expose-pending-txs.

Architecture

The execution layer is built on top of Reth, extending it with Arc-specific functionality:

  • Custom Precompiles - Native implementations for Arc-specific operations (native coin control, post-quantum signatures, system accounting).
  • Custom EVM Configuration - Specialized gas calculations and execution logic
  • Transaction Pool Enhancements - Custom validation
  • Block Executor - Optimized block execution with Arc-specific features

For architectural details, see the Architecture Guide.

Metrics

The execution layer exposes Prometheus metrics on the configured metrics endpoint (e.g., http://localhost:9001/metrics).

Key metric prefixes:

  • reth_* - Metrics emitted by this Reth-based execution binary
  • reth_arc_* - Arc-specific execution metrics

Arc-specific execution metrics:

Metric Type Description
reth_arc_node_version_info Gauge Node version information, labeled by version and git_commit.
reth_arc_payload_stage_duration_seconds Histogram Payload build stage duration, labeled by stage.
reth_arc_payload_total_duration_seconds Histogram Total payload build duration.
reth_arc_payload_build_outcome_total Counter Payload build outcome count, labeled by outcome.
reth_arc_tx_denylist_rejection_total Counter Transactions rejected during mempool validation because a transaction address is denylisted.
reth_arc_invalid_tx_list_size Gauge Current number of transaction hashes in the invalid transaction list.
reth_arc_invalid_tx_list_hits_total Counter Transactions rejected because their hash is in the invalid transaction list.
reth_arc_invalid_tx_list_inserts_total Counter Transaction hashes inserted into the invalid transaction list.
reth_arc_invalid_tx_list_batch_inserts_total Counter Batch insert operations into the invalid transaction list.

Development

Running Without Consensus (Mock Mode)

For execution-layer-only development and testing:

./scripts/localdev.mjs start

This runs the execution layer with a mock consensus layer for rapid iteration.

Further Reading