Skip to content

Connect to the TRON Network

The TRON network is mainly divided into four environments:

  • Mainnet
  • Nile Testnet
  • Shasta Testnet (currently does not support node joining)
  • Private Network

This guide explains how to configure the java-tron client to connect to these networks, covering basic network configuration, node discovery, node connection, log and node status verification, and how to troubleshoot connection issues.

This is an operational configuration guide. For how the P2P network works internally (architecture, block synchronization, and broadcast protocols), see P2P Network Deep Dive.

Basic Network Configuration

You can connect a java-tron node to a specific network by modifying the following key items in the current Mainnet config file.

Network ID

The P2P Network ID (node.p2p.version) specifies the network you want to join. Mainnet configuration:

node {
  ...
  p2p {
    version = 11111        # Mainnet
  }
  ...
}

In particular:

  • Mainnet: version = 11111
  • Nile Testnet: version = 201910292
  • Shasta Testnet: version = 1
  • Private Network: Custom value (set to a different ID)

Genesis Block

The genesis.block configuration must be consistent with other nodes in the target network, otherwise the node will not be able to connect to peers. Mainnet configuration:

genesis.block = {
  # Reserve balance
  assets = [
    {
      accountName = "Zion"
      accountType = "AssetIssue"
      address = "TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"
      balance = "99000000000000000"
    },
    {
      accountName = "Sun"
      accountType = "AssetIssue"
      address = "TXmVpin5vq5gdZsciyyjdZgKRUju4st1wM"
      balance = "0"
    },
    {
      accountName = "Blackhole"
      accountType = "AssetIssue"
      address = "TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy"
      balance = "-9223372036854775808"
    }
  ]
  witnesses = [
    {
      address: THKJYuUmMKKARNf7s2VT51g5uPY6KEqnat,
      url = "http://GR1.com",
      voteCount = 100000026
    },
    {
      address: TVDmPWGYxgi5DNeW8hXrzrhY8Y6zgxPNg4,
      url = "http://GR2.com",
      voteCount = 100000025
    },
    {
      address: TWKZN1JJPFydd5rMgMCV5aZTSiwmoksSZv,
      url = "http://GR3.com",
      voteCount = 100000024
    },
    {
      address: TDarXEG2rAD57oa7JTK785Yb2Et32UzY32,
      url = "http://GR4.com",
      voteCount = 100000023
    },
    {
      address: TAmFfS4Tmm8yKeoqZN8x51ASwdQBdnVizt,
      url = "http://GR5.com",
      voteCount = 100000022
    },
    {
      address: TK6V5Pw2UWQWpySnZyCDZaAvu1y48oRgXN,
      url = "http://GR6.com",
      voteCount = 100000021
    },
    {
      address: TGqFJPFiEqdZx52ZR4QcKHz4Zr3QXA24VL,
      url = "http://GR7.com",
      voteCount = 100000020
    },
    {
      address: TC1ZCj9Ne3j5v3TLx5ZCDLD55MU9g3XqQW,
      url = "http://GR8.com",
      voteCount = 100000019
    },
    {
      address: TWm3id3mrQ42guf7c4oVpYExyTYnEGy3JL,
      url = "http://GR9.com",
      voteCount = 100000018
    },
    {
      address: TCvwc3FV3ssq2rD82rMmjhT4PVXYTsFcKV,
      url = "http://GR10.com",
      voteCount = 100000017
    },
    {
      address: TFuC2Qge4GxA2U9abKxk1pw3YZvGM5XRir,
      url = "http://GR11.com",
      voteCount = 100000016
    },
    {
      address: TNGoca1VHC6Y5Jd2B1VFpFEhizVk92Rz85,
      url = "http://GR12.com",
      voteCount = 100000015
    },
    {
      address: TLCjmH6SqGK8twZ9XrBDWpBbfyvEXihhNS,
      url = "http://GR13.com",
      voteCount = 100000014
    },
    {
      address: TEEzguTtCihbRPfjf1CvW8Euxz1kKuvtR9,
      url = "http://GR14.com",
      voteCount = 100000013
    },
    {
      address: TZHvwiw9cehbMxrtTbmAexm9oPo4eFFvLS,
      url = "http://GR15.com",
      voteCount = 100000012
    },
    {
      address: TGK6iAKgBmHeQyp5hn3imB71EDnFPkXiPR,
      url = "http://GR16.com",
      voteCount = 100000011
    },
    {
      address: TLaqfGrxZ3dykAFps7M2B4gETTX1yixPgN,
      url = "http://GR17.com",
      voteCount = 100000010
    },
    {
      address: TX3ZceVew6yLC5hWTXnjrUFtiFfUDGKGty,
      url = "http://GR18.com",
      voteCount = 100000009
    },
    {
      address: TYednHaV9zXpnPchSywVpnseQxY9Pxw4do,
      url = "http://GR19.com",
      voteCount = 100000008
    },
    {
      address: TCf5cqLffPccEY7hcsabiFnMfdipfyryvr,
      url = "http://GR20.com",
      voteCount = 100000007
    },
    {
      address: TAa14iLEKPAetX49mzaxZmH6saRxcX7dT5,
      url = "http://GR21.com",
      voteCount = 100000006
    },
    {
      address: TBYsHxDmFaRmfCF3jZNmgeJE8sDnTNKHbz,
      url = "http://GR22.com",
      voteCount = 100000005
    },
    {
      address: TEVAq8dmSQyTYK7uP1ZnZpa6MBVR83GsV6,
      url = "http://GR23.com",
      voteCount = 100000004
    },
    {
      address: TRKJzrZxN34YyB8aBqqPDt7g4fv6sieemz,
      url = "http://GR24.com",
      voteCount = 100000003
    },
    {
      address: TRMP6SKeFUt5NtMLzJv8kdpYuHRnEGjGfe,
      url = "http://GR25.com",
      voteCount = 100000002
    },
    {
      address: TDbNE1VajxjpgM5p7FyGNDASt3UVoFbiD3,
      url = "http://GR26.com",
      voteCount = 100000001
    },
    {
      address: TLTDZBcPoJ8tZ6TTEeEqEvwYFk2wgotSfD,
      url = "http://GR27.com",
      voteCount = 100000000
    }
  ]
  timestamp = "0" # Genesis block timestamp, milli seconds
  parentHash = "0xe58f33f9baf9305dc6f82b9f1934ea8f0ade2defb951258d50167028c780351f"
}

Node Discovery

Enable Node Discovery

Node discovery is enabled or disabled via the configuration file. It is enabled by default:

node.discovery = {
  ...
  enable = true
  ...
}

Boot Nodes

Java-tron uses the Kademlia protocol to discover peers. Discovery requires boot nodes, which consist of seed nodes and actively configured peers, see Active Connection (Active Peers).

seed.node.ip.list

seed.node.ip.list is used to initialize connections. It should point to online and stable FullNodes. Each entry can use an IPv4 address, a bracketed IPv6 address, or a domain name:

seed.node = {
  ip.list = [
    "3.225.171.164:18888",
    "52.8.46.215:18888",
    ...
    "18.163.230.203:18888"
    #"seed.example.com:18888", // domain name
    #"[2a05:d014:1f2f:2600:1b15:921:d60b:4c60]:18888", // use this if support ipv6
    #"[2600:1f18:7260:f400:8947:ebf3:78a0:282b]:18888", // use this if support ipv6
  ]
}

For TRON Mainnet, you can use community public nodes as seed nodes. To get the latest seed.node.ip.list, refer to the official config file. If your network interface supports IPv6, you can uncomment the relevant lines in the list.

Domain Names in Peer Configuration

Starting with GreatVoyage-v4.8.2, seed.node.ip.list, node.active, node.passive, and node.fastForward accept domain names in hostname:port format in addition to IP addresses. IPv6 literals in these four configuration items must use [IPv6-address]:port format and must not contain leading or trailing whitespace.

node.backup.members also accepts domain names and IP addresses, but its entries must not include a port. IPv6 literals in this list are written without brackets and must not contain leading or trailing whitespace. All backup members use the port configured separately by node.backup.port. For the complete backup-node configuration and deployment example, see Master-Slave Mode for Block Production FullNodes.

At startup, java-tron resolves configured domain names to IP addresses. It first uses the operating system resolver, which honors local mappings such as /etc/hosts; if that fails or times out, it falls back to built-in public DNS resolvers. IPv4 is attempted first and IPv6 is used as a fallback. For seed.node.ip.list, node.active, node.passive, and node.fastForward, domain names in the same list are resolved in parallel and entries that cannot be resolved are skipped. In contrast, node.backup.members entries are validated one by one, and any member that cannot be resolved causes startup to fail with a parameter initialization error.

Only domains in node.backup.members are refreshed periodically, every 60 seconds; domain names in the other peer configuration items are not refreshed automatically.

Domain names in these peer configuration items use ordinary DNS A/AAAA resolution. This is separate from the DNS tree node-discovery mechanism configured through node.dns.treeUrls.

Persistent Nodes from Database

When persistence is enabled, nodes in the routing table are periodically written to the database and reused on restart:

node.discovery = {
  ...
  persist = true
  ...
}

By default, node discovery uses the User Datagram Protocol (UDP) on port 18888:

node {
  ...
  listen.port = 18888
  ...
}

Disable Node Discovery

In some cases (e.g., local testing or a fixed private network), you may disable discovery by setting:node.discovery.enable = false or by blocking UDP port 18888 via firewall.

Node Connection

Number of Node Connections

The number of peer connections is controlled by the following parameters. They are usually tuned together:

  • node.maxConnections: the maximum number of peer connections (default: 30). Passive connections from non-trusted peers are rejected once this limit is reached. A peer is considered trusted if its IP appears in node.passive, node.active, or node.fastForward (the IPs from all three are added to the trust list). Active connections bypass this check entirely: active connections to peers configured in node.active are bounded only by the size of the node.active list, while active connections to peers discovered via the discovery protocol are driven by minConnections and minActiveConnections (see below).
  • node.minConnections: the desired minimum total number of peer connections, counting both active and passive (default: 8). When the total is below this value, the node initiates active connections to discovered peers to close the gap.
  • node.minActiveConnections: the desired minimum number of active connections to discovered peers (default: 3). The node will keep initiating active connections to discovered peers until this threshold is met, even if the total connection count has already reached or exceeded minConnections.
  • node.maxConnectionsWithSameIp: the maximum number of connections allowed from the same IP address (default: 2). It mitigates abuse from a single IP.
node {
  ...
  maxConnections = 30
  minConnections = 8
  minActiveConnections = 3
  maxConnectionsWithSameIp = 2
  ...
}

Note: minConnections must not exceed maxConnections, and minActiveConnections must not exceed minConnections; otherwise the node will automatically clamp them at startup.

Active Connection (Active Peers)

Active peers come from three sources:

  • Configured active peers (high priority). These connections are made regardless of discovery settings:
node {
  ...
  active = [
    # Active establish connection in any case
    # Sample entries:
    # "192.0.2.10:18888",
    # "active.example.com:18888"
  ]
  ...
 }
  • Peers discovered via node discovery (medium priority)
  • DNS tree nodes (low priority). Rarely used and requires node.dns.treeUrls:
node {
  dns {
    # DNS URLs to get nodes, URL format tree://{pubkey}@{domain}, default empty
    treeUrls = [
      #"tree://AKMQMNAJJBL73LXWPXDI4I5ZWWIZ4AWO34DWQ636QOBBXNFXH3LQS@main.trondisco.net",
    ]
  }
}

Compared to traditional static seed node list, the DNS tree mechanism offers advantages in P2P network bootstrapping, such as dynamic node updates and resistance to attacks.

Passive Connections

  • The current node will always accept connection requests from nodes listed under node.passive
node {
  ...
  passive = [
    # Passive accept connection in any case
    # Sample entries:
    # "192.0.2.20:18888",
    # "passive.example.com:18888"
  ]
  ...
 }
  • Other nodes: While a node is discovering other nodes, it will also be discovered by other nodes, and these nodes may also initiate connections to the current node actively.

Unlike node discovery, which uses UDP, peer connections use Transmission Control Protocol (TCP) on the same port (18888 by default). However, the port number bound for passive connection is the same as that bound for node discovery. If a node does not want to accept passive connections for security reasons, it can close the TCP 18888 port through the firewall. If a node disables passive connections, the entire network topology will be as shown in the figure below:

image

Logs and Node Status Verification

View Sync Logs

TRON node logs are stored in logs/tron.log：

tail -f logs/tron.log

Example Sync Logs：

pushBlock block number:76, cost/txs:13/0 false
Success process block Num:76,ID:000000000000004c9e3899ee9952a7f0d9e4f692c7070a48390e6fea8099432f.

Example Block Production Logs (for Super Representatives):

Generate block 79336 begin
Generate block 79336 success, trxs:0, pendingCount: 0, rePushCount: 0, postponedCount: 0

Check Node Status

Use the HTTP API:

curl http://127.0.0.1:8090/wallet/getnodeinfo

Example response：

{
  "activeConnectCount": 3,
    "beginSyncNum": 42518346,
    "block": "Num:42518365,ID:000000000288c75d1967232f1efe606ff90b9dd76660d7de8cc091849be6bf10",
    "cheatWitnessInfoMap": {
        ...
    },
    "configNodeInfo": {
        ...
        "codeVersion": "4.5.1",
        "dbVersion": 2,
        "discoverEnable": true,
        "listenPort": 18888,
        ...
    },
    "currentConnectCount": 18,
    "machineInfo": {
        ...
    },
    "passiveConnectCount": 15,
    "peerList": [
        ...
    ],
    "solidityBlock": "Num:42518347,ID:000000000288c74b723398aef104c585bad1c7cbade7793c5551466bd916feee",
    "totalFlow": 8735314
}

Verify Node Synchronization

Compare your local block height with TRONSCAN ：

curl http://127.0.0.1:8090/wallet/getnowblock

If the heights match, synchronization is normal.

Troubleshooting Common Connection Issues

If your java-tron node fails to connect to peers, check the following common causes:

  • Local clock offset

    Sync system time with:

    sudo ntpdate -s time.nist.gov

  • UDP blocked by firewall

    Use node.active to specify fixed peers.

  • Not accepting inbound connections

    Configure node.passive to accept connections from trusted peers.

  • Shasta Testnet unsupported

    Use Nile Testnet instead.

Connecting to a Private Network

Developers can deploy a private instance of the TRON network.

Key Configuration:

  • Use a custom node.p2p.version to avoid conflicts with existing public networks.

Reference Guide: