> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# Phaser

Status: In development.

The Phaser provider extracts a chain through a Phaser bridge: a service in front of a chain's node that serves its data
as tables, over Arrow Flight, Arrow's protocol for moving tables over the network. There are bridges for Erigon, an
Ethereum node, and for the Canton Network. [Raw datasets](/datasets/raw-datasets) of kind `phaser` extract through it.
Unlike other kinds, their tables aren't fixed: they're the bridge's own, which Amp asks the bridge for when you register
the dataset.

A bridge numbers its data by position, like a block number for a blockchain, or an offset for Canton. In a `phaser`
dataset, `_block_num` is the position.

## Prerequisites

* A running Amp you can manage, like one in [Solo Mode](/running-amp/solo-mode).
* [`ampctl`](/clis/ampctl), which installs with Amp.
* A running Phaser bridge, which Amp can reach when you register the dataset, and while its job extracts. The examples
  use one at `http://127.0.0.1:8090`.

## Configure the provider

A provider's configuration is a TOML file. The smallest one names the kind, the network, and the bridge:

```toml [phaser_mainnet.toml]
kind = "phaser"
network = "mainnet"
bridge_url = "http://127.0.0.1:8090"
```

* `kind`: always `"phaser"`.
* `network`: a name for the network the bridge serves, like `mainnet`. A dataset extracts through the Phaser provider
  whose network matches its own.
* `bridge_url`: the bridge's Arrow Flight URL.

A fuller one sets how the job splits the chain:

```toml [phaser_mainnet.toml]
kind = "phaser"
network = "mainnet"
bridge_url = "http://127.0.0.1:8090"
segment_size = 100000
```

* `segment_size`: how many positions each segment covers, `500000` by default. The job extracts the chain a segment
  at a time, and starts new files at each segment's start.

:::note
The configuration also accepts `max_workers`, `batch_size`, `enable_traces`, `bridge_metadata`,
`record_batch_bytes_target`, and `segment_selection_policy`, but Amp doesn't use them yet. Set how many segments a job
extracts at once with `ampctl dataset deploy --parallelism`, and how it writes its files in the worker's
[configuration](/running-amp/configuration).
:::

The [Provider Configuration Reference](/providers/configuration-reference#phaser) lists every field.

## Create a dataset

::::steps
### Register the provider

Register it before the dataset: registering the dataset asks the provider's bridge for its tables.

```bash
ampctl provider register phaser_mainnet ./phaser_mainnet.toml
```

A provider's name holds lowercase letters, digits, and underscores, and starts with a letter or an underscore.
[Providers](/providers) covers registering and replacing providers.

### Write the manifest

`ampctl manifest generate` doesn't support Phaser, so write the [manifest](/datasets/manifests) yourself. Its `network`
names the Phaser provider to use, and its `tables` stay empty:

```json [phaser_mainnet.json]
{
  "kind": "phaser",
  "network": "mainnet",
  "tables": {}
}
```

### Register the dataset

Amp connects to the bridge, and fills `tables` with each table it serves, with its columns:

:::terminal
```bash
ampctl dataset register acme/phaser_mainnet ./phaser_mainnet.json --tag 1.0.0
```

```
✓ Dataset registered successfully
→ Namespace: acme
→ Name: phaser_mainnet
→ Version: 1.0.0
→ Hash: 7499fa8ccc1bec25857a1545b12aa9cc9720ca720ca81c02de76a3b374586783
→ Kind: phaser
→ Start block: 0
→ Finalized only: false
→ Tables: blocks, logs, transactions
```
:::

`Tables` lists the bridge's tables, so yours depend on your bridge. A table whose columns the bridge doesn't describe
is left out. `ampctl dataset manifest acme/phaser_mainnet@1.0.0` shows the manifest Amp stored.

### Deploy it

```bash
ampctl dataset deploy acme/phaser_mainnet@1.0.0 --parallelism 4
```

`--parallelism` sets how many segments the job extracts at once, `1` by default. `--end-block` sets the
last position to extract. `ampctl dataset deploy`'s `--provider`, `--verify`, and `--backfill-strategy` don't apply
to Phaser datasets.
::::

## The bridge

Amp talks to the bridge twice:

* **When you register the dataset**, Amp asks the bridge for its tables: each one's columns, the columns its rows are
  sorted by, and its segment selection policy. It stores them in the manifest, so the bridge decides the dataset's
  tables, and its hash.
* **When the job starts**, it checks that the bridge still serves every table of the manifest, with the same columns,
  then extracts each table from position 0 to the bridge's current position, or to `--end-block`.

When several Phaser providers serve the dataset's network, Amp uses the first by name, and logs a warning.

## Segment selection policy

Each table's `segment_selection_policy` says how Amp links its positions (see
[Segment selection](/datasets/raw-datasets#segment-selection)), and the bridge sets it for each table:

* `hash-linked`: by hash and parent hash, for blockchains. Amp detects [reorgs](/get-started/concepts/reorgs).
* `ordered`: by position alone, for streams without hashes, like Canton's offsets. Amp doesn't detect reorgs, so it
  only suits data that never changes once the bridge publishes it.

The provider's own `segment_selection_policy` field doesn't override the bridge's yet.

## Limitations

* **One run**: a job extracts up to the bridge's position when the job starts, then completes. It doesn't follow the
  positions the bridge adds after that.
* **From position 0**: a job always starts at position 0, whatever the manifest's `start_block`.
* **Fixed tables**: when the bridge changes a table's columns, the job fails, and you register the manifest again to
  pick up the change.

## Errors

### `PHASER_PROVIDER_NOT_FOUND: Referenced Phaser provider 'phaser:mainnet' not found`

No Phaser provider serves the manifest's network. Register one whose `network` matches the manifest's exactly, then
register the dataset again.

### `PHASER_CONNECTION_FAILED: Failed to connect to Phaser bridge at 'http://127.0.0.1:8090'`

Amp couldn't reach the provider's `bridge_url`. Check that the bridge runs, and that the machine `ampd` runs on can
reach it.

### `PHASER_NO_TABLES_DISCOVERED: No tables discovered in bridge`

The bridge serves no tables, or describes the columns of none of them. Check the bridge's configuration.

### `UNSUPPORTED_OPTION: option 'provider' is not supported for 'phaser' datasets`

You deployed a Phaser dataset with an option only other raw datasets take, here `--provider`. Deploy it without.

### `Schema mismatch for table 'blocks': …`

The bridge's table no longer has the columns Amp registered. Register the manifest again, as a new version, and
deploy that.