Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

106 Commits

Folders and files

Repository files navigation

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. The binaries are attached both bare and as the firehose-tron_<os>_<arch>.tar.gz archives the Homebrew formula installs from, and the workflow opens a formula bump PR on streamingfast/homebrew-tap, which must be merged by hand. Without the HOMEBREW_TAP_TOKEN secret the bump is skipped with a warning.

Tags containing alpha, beta or rc are published as pre-releases, do not update the Homebrew formula 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}'

Endpoints are tried in the order they are declared. A failing endpoint moves polling to the next one, and --providers-failback-interval (default 10m) controls how long polling stays there: on every interval the declared order is re-preferred, so a transient failure does not keep you on a fallback provider for the lifetime of the process. Set it to 0 to stay on the fallback until the process is restarted.

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.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages