Firehose for TRON

Project Overview

The Firehose for TRON project (firetron CLI) includes the following commands:

• firetron fetch: Pulls native TRON blocks from an RPC endpoint and converts them to Firehose format, to be consumed by firecore.
• firetron fetch-evm: Pulls blocks from an RPC endpoint and converts them to an EVM-compatible Firehose block format, to be consumed by fireeth.
• firetron test-block: Used for testing block fetching.

The Firehose TRON does not handle block persistence or merging by itself.

It only implements the reader logic, fetching blocks from a TRON node and emitting a Firehose-compatible data through stdout. The firetron fetch/fetch-evm commands aren't expected to be ran standalone and instead they are expected to spin up from firecore/fireeth start .... To enable persistence (one-block files) and bundle merging (merged-blocks), you need to run firetron as the reader-node inside firecore, which provides the rest of the Firehose/Substreams pipeline:

• reader-node → Runs firetron fetch ... and writes one-blocks
• merger → Merges one-blocks into merged-blocks
• relayer → Provides a live stream of blocks for Firehose & Substreams gRPC servers
• firehose gRPC server → Provides the Firehose gRPC service
• substreams gRPC server → Provides the Substreams gRPC service

Example

1. Create firecore config with firetron as reader-node In sf-tron-mainnet.yaml:

   start:
     args:
     - reader-node
     - merger
     - relayer
     - firehose
     flags:
       # `firetron` is expected to be found in your PATH, use absolute path if it's not the case
       reader-node-path: firetron
       reader-node-arguments: |
         fetch {first-streamable-block}
         --state-dir=/data/tron/firehose/state
         --interval-between-fetch=50ms
         --tron-endpoints=http://127.0.0.1:50051
   

2. Let firecore run the full pipeline

firecore -c sf-tron-mainnet.yaml start

This successfully produced:

• one-block files
• merged-block bundles
• a working Firehose gRPC endpoint

Releasing

Releases are cut by CI, there is nothing to run locally:

1. Land a PR that moves the ## Unreleased section of CHANGELOG.md to the version being released, e.g. ## v0.3.0.

2. Tag the merge commit and push the tag:

   git tag v0.3.0 && git push origin v0.3.0

The Build, push and release (if tag) workflow then cross compiles the linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64 binaries inside Docker, pushes the multi-platform image to ghcr.io/streamingfast/firehose-tron and creates the GitHub release, using the CHANGELOG.md section matching the tag as the release notes. A tag with no matching section fails the workflow before anything is published.

Tags containing beta or rc are published as pre-releases and do not move the latest Docker tag. Every other branch push builds and pushes a linux/amd64 image only; a manual workflow_dispatch run builds the full binary matrix, which is the way to validate a release build before tagging.

References

firetron fetch 75748000 --state-dir /persistent/path --block-fetch-batch-size=1 --interval-between-fetch=0s --tron-endpoints='http://my.tron.endpoint?apiKey=xxxxxxxxx'

firetron fetch-evm 0 --tron-evm-endpoints='https://provider/jsonrpc?apiKey=xxxxxxx' --block-fetch-batch-size=1 --interval-between-fetch=1s --tron-endpoints='http://tron.grpc.endpoint:12345?apiKey=xxxxxxx' --state-dir=/persistent/path

Per-endpoint API keys

--tron-endpoints and --tron-evm-endpoints accept a per-endpoint API key, so you can configure two (or more) providers that each require a different key and get real fallback between them:

firetron fetch 0 \
  --tron-endpoints 'https://provider-a.io?apiKey=${PROVIDER_A_KEY}' \
  --tron-endpoints 'https://provider-b.io?apiKey=${PROVIDER_B_KEY}'

Endpoint URL conventions:

• --tron-api-key is deprecated (it logs a warning when used). It still works as the default key for any endpoint that does not carry its own, but prefer ?apiKey=... on each endpoint; the flag will be removed in a future release.
• http:// on an endpoint selects plaintext (no scheme defaults to https://).
• ?insecure=true on an endpoint skips TLS certificate validation.
• ${ENV} interpolation is supported in endpoint values, e.g. ${QUICKNODE_RPC_URL}?apiKey=${QUICKNODE_API_KEY}.

Note

To be wrapped by firecore/fireeth, see Example section for details.