# Substreams

This page documents the configuration flags for the Substreams Tier 1 and Tier 2 components. For architectural concepts and how Substreams works, see [Substreams Architecture](/firehose/architecture/components/substreams.md).

## Substreams Tier 1

The Tier 1 component serves the Substreams API and handles live block processing.

### Starting Tier 1

```bash
firecore start substreams-tier1 [flags]
```

### Core Configuration

| Flag                                     | Description                                             | Default  |
| ---------------------------------------- | ------------------------------------------------------- | -------- |
| `--substreams-tier1-grpc-listen-addr`    | gRPC listening address (append `*` for TLS)             | `:10016` |
| `--substreams-tier1-block-type`          | Protobuf block type (e.g., `sf.ethereum.type.v2.Block`) |          |
| `--substreams-tier1-enforce-compression` | Require gzip or zstd encoding                           | `true`   |

### Tier 2 Connection

| Flag                                       | Description                       | Default  |
| ------------------------------------------ | --------------------------------- | -------- |
| `--substreams-tier1-subrequests-endpoint`  | Address to reach tier2 workers    | `:10017` |
| `--substreams-tier1-subrequests-plaintext` | Use plaintext connection to tier2 | `true`   |
| `--substreams-tier1-subrequests-insecure`  | Skip tier2 TLS validation         | `false`  |
| `--substreams-tier1-max-subrequests`       | Parallel subrequests per request  | `4`      |

### Request Limits

| Flag                                                          | Description                                       | Default    |
| ------------------------------------------------------------- | ------------------------------------------------- | ---------- |
| `--substreams-tier1-active-requests-soft-limit`               | Soft limit for active requests (triggers unready) | `0` (none) |
| `--substreams-tier1-active-requests-hard-limit`               | Hard limit (rejects requests)                     | `0` (none) |
| `--substreams-tier1-default-max-request-per-user`             | Default max requests per user                     | `3`        |
| `--substreams-tier1-default-minimal-request-life-time-second` | Minimum request lifetime                          | `180`      |

### State Storage

| Flag                                   | Description                     | Default                   |
| -------------------------------------- | ------------------------------- | ------------------------- |
| `--substreams-state-store-url`         | URL for Substreams state data   | `{sf-data-dir}/localdata` |
| `--substreams-state-store-default-tag` | Tag appended to state store URL |                           |
| `--substreams-state-bundle-size`       | Blocks between store snapshots  | `1000`                    |
| `--substreams-block-execution-timeout` | Max block execution time        | `3m`                      |
| `--substreams-tier1-quicksave-store`   | Store for quicksave on shutdown |                           |

### Discovery & Pools

| Flag                                                      | Description                      | Default |
| --------------------------------------------------------- | -------------------------------- | ------- |
| `--substreams-tier1-discovery-service-url`                | Discovery service for tier2      |         |
| `--substreams-tier1-global-worker-pool-address`           | Global worker pool address       |         |
| `--substreams-tier1-global-worker-pool-keep-alive-delay`  | Worker pool keep-alive interval  | `25s`   |
| `--substreams-tier1-global-request-pool-address`          | Global request pool address      |         |
| `--substreams-tier1-global-request-pool-keep-alive-delay` | Request pool keep-alive interval | `25s`   |
| `--substreams-tier1-foundational-stores-config-path`      | Foundational stores config file  |         |

## Substreams Tier 2

The Tier 2 component provides workers for historical block processing.

### Starting Tier 2

```bash
firecore start substreams-tier2 [flags]
```

### Configuration

| Flag                                           | Description                                 | Default  |
| ---------------------------------------------- | ------------------------------------------- | -------- |
| `--substreams-tier2-grpc-listen-addr`          | gRPC listening address (append `*` for TLS) | `:10017` |
| `--substreams-tier2-max-concurrent-requests`   | Max concurrent requests (0 = no limit)      | `0`      |
| `--substreams-tier2-segment-execution-timeout` | Max segment execution time                  | `1h`     |
| `--substreams-tier2-discovery-service-url`     | Discovery service to advertise presence     |          |

## Example Usage

### Basic Tier 1 Setup

```bash
firecore start substreams-tier1 \
  --substreams-tier1-grpc-listen-addr=":10016" \
  --substreams-tier1-block-type="sf.ethereum.type.v2.Block" \
  --substreams-tier1-subrequests-endpoint="localhost:10017"
```

### Basic Tier 2 Setup

```bash
firecore start substreams-tier2 \
  --substreams-tier2-grpc-listen-addr=":10017"
```

### With Cloud Storage

```bash
firecore start substreams-tier1 \
  --substreams-tier1-grpc-listen-addr=":10016" \
  --substreams-state-store-url="s3://my-bucket/substreams-state" \
  --common-merged-blocks-store-url="s3://my-bucket/merged-blocks"
```

### With Request Limits

```bash
firecore start substreams-tier1 \
  --substreams-tier1-grpc-listen-addr=":10016" \
  --substreams-tier1-active-requests-soft-limit=50 \
  --substreams-tier1-active-requests-hard-limit=100 \
  --substreams-tier1-default-max-request-per-user=5
```

### Multiple Tier 2 Workers

Run multiple Tier 2 instances for parallel historical processing:

```bash
# Worker 1
firecore start substreams-tier2 --substreams-tier2-grpc-listen-addr=":10017"

# Worker 2
firecore start substreams-tier2 --substreams-tier2-grpc-listen-addr=":10018"

# Worker 3
firecore start substreams-tier2 --substreams-tier2-grpc-listen-addr=":10019"
```

Configure Tier 1 to use multiple workers via discovery service or manual endpoint configuration.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://firehose.streamingfast.io/references/cli-reference/substreams.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.