Firehose Acme

StreamingFast Firehose template for new chain integrations

Instrumenting a new chain requires the blockchain node to output Firehose Protocol messages — a simple, unified protocol consisting of FIRE INIT and FIRE BLOCK messages. Any chain that implements this protocol automatically benefits from the entire Firehose ecosystem.

The Firehose Protocol is chain-agnostic: the node outputs block data as base64-encoded protobuf, and firehose-core handles the rest. The chain-specific parts are:

1. Node instrumentation: Modify your blockchain node to output FIRE INIT and FIRE BLOCK messages

2. Protobuf schema: Define your chain's block data model

That's it — most chains only need these two pieces. No custom binary required.

Implement Node Instrumentation

The key integration work is implementing the Firehose Protocol in your blockchain node. The node must output:

1. FIRE INIT once at startup with the protocol version and protobuf block type

2. FIRE BLOCK for each block with metadata and base64-encoded protobuf payload

Block Hash Format: Pay careful attention to the block hash representation requirements. The parent_hash of each block must exactly match the block_hash of the previous block. For new chains, use lowercase hexadecimal without the 0x prefix.

See the dummy-blockchain tracer for a reference implementation.

Define Protobuf Types

Create protobuf definitions that model your chain's block data structure. The block type name must match what your instrumented node outputs in the FIRE INIT message.

Publish your protobuf definitions to the Buf registry to use firecore directly, or keep them local if building a custom binary.

Using firecore Directly

If your protobuf block definitions are published to the Buf registry, you can use firecore directly without building any chain-specific binary:

firecore start reader-node \
  --reader-node-path=/path/to/your/instrumented-node \
  --reader-node-proto-type=buf.build/myorg/mychain:sf.mychain.type.v1.Block

This is the simplest integration path and works for most chains.

Optional: Custom firehose-<chain> Binary

For chains that need custom CLI commands, specialized tooling, or prefer not to use the Buf registry, you can create a firehose-<chain> wrapper around firehose-core.

We provide a template project firehose-acme as a starting point. It includes scaffolding code and a dummy-blockchain example.

Copy the template:

git clone [email protected]:streamingfast/firehose-acme firehose-mychain
cd firehose-mychain

Rename to Your Chain

Rename all references from "acme" to your chain's name. Choose two names:

• Long form: Full chain name (e.g., arweave, solana, ethereum)

• Short form: 3-4 letter abbreviation (e.g., arw, sol, eth)

Perform the following replacements:

• Rename cmd/fireacme → cmd/fire<short> (e.g., cmd/firearw)

• Search and replace fireacme → fire<short>

• Search and replace acme → <long> (case-sensitive for acme, ACME, Acme)

Update the proto file path sf/acme/type/v1/type.proto and regenerate Go structs:

./types/pb/generate.sh

Development & Testing

The template includes a development script that starts Firehose with the dummy-blockchain:

./devel/standard/start.sh

This uses the configuration in devel/standard/standard.yaml. Modify start.flags.reader-node-path to point to your instrumented node binary.

Run the test suite:

go test ./...

You can reach out to the StreamingFast team on Discord. We usually maintain these Go-side integrations and can help with the initial setup.

Register Your Chain

Once your integration is working, register your chain in The Graph's networks registry to make it discoverable by the ecosystem.

The Graph Networks Registry

Add your chain to The Graph Networks Registry by following their adding/updating a chain guide.

The registry entry includes metadata about your chain such as:

• Chain ID and name

• Firehose and Substreams endpoints

• Block type information

Update Well-Known Protobuf Descriptors

After your chain is registered, update firehose-core to include your chain's protobuf descriptors in the well-known types. This enables better tooling support across the ecosystem.

1. Run the registry generator to regenerate the well-known descriptors

2. Open a PR to firehose-core with the updated descriptors

The StreamingFast team can help with this step — reach out on Discord after your chain is registered.