uniswap-v4-substreams

StreamingFast

v0.1.1/13 downloads/Repository

Package ref

uniswap-v4-substreams@v0.1.1

Download .spkg

Run package

CLI

Run map_events from the command line.

substreams run uniswap-v4-substreams@v0.1.1 map_events -e mainnet --start-block -1

Authenticate by running substreams auth or directly on thegraph.market (see docs).

README

Uniswap v4 Substreams

sg2ss conversion of Uniswap/v4-subgraph, running on every chain where Uniswap v4 is deployed.

Layer	Role
Substreams	Decode PoolManager + PositionManager events (address-gated)
ClickHouse	Event tables + HOL views (`api_pools`, `api_swaps`, …)
Hasura	GraphQL over public `api_*` views

No Substreams stores for Tier A+B — v4 pool events all come from a single PoolManager per chain.

Source: streamingfast/substreams-chain-modules · dex/uniswap-v4-substreams

Showcase: substreams.dev/showcases/uniswap-v4

See DESIGN.md.

Networks

The chain is selected with --network; the manifest carries the matching contract addresses (as map_events params) and initialBlock for each one.

Chain	`--network`	PoolManager	PositionManager	initialBlock
Ethereum	`mainnet`	`0x000000000004444c5dc75cB358380D2e3dE08A90`	`0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e`	21688329
Base	`base`	`0x498581fF718922c3f8e6A244956aF099B2652b2b`	`0x7C5f5A4bBd8fD63184577525326123B519429bDc`	25350988
Arbitrum One	`arbitrum-one`	`0x360E68faCcca8cA495c1B759Fd9EEe466db9FB32`	`0xd88F38F930b7952f2DB2432Cb002E7abbF3dD869`	297842872
OP Mainnet	`optimism`	`0x9a13F98Cb987694C9F086b1F5eB990EeA8264Ec3`	`0x3C3Ea4B57a46241e54610e5f022E5c45859A1017`	130947675
Polygon	`matic`	`0x67366782805870060151383F4BbFF9daB53e5cD6`	`0x1Ec2eBf4F37E7363FDfe3551602425af0B3ceef9`	66980384
BNB Smart Chain	`bsc`	`0x28e2Ea090877bF75740558f6BFB36A5ffeE9e9dF`	`0x7A4a5c919aE2541AeD11041A1AEeE68f1287f95b`	45970610
Avalanche	`avalanche`	`0x06380C0e0912312B5150364B9DC4542BA0DbBc85`	`0xB74b1F14d2754AcfcbBe1a221023a5cf50Ab8ACD`	56195376
Unichain	`unichain`	`0x1F98400000000000000000000000000000000004`	`0x4529A01c7A0410167c5740C487A8DE60232617bf`	25500
World Chain	`worldchain`	`0xb1860D529182ac3BC1F51Fa2ABd56662b7D13f33`	`0xC585E0f504613b5fBf874F21Af14c65260fB41fA`	9111872
Blast	`blast-mainnet`	`0x1631559198A9e474033433b2958daBC135ab6446`	`0x4AD2F4CcA2682cBB5B950d660dD458a1D3f1bAaD`	14377311
Zora	`zora`	`0x0575338e4C17006aE181B47900A84404247CA30f`	`0xf66C7b99e2040f0D9b326B3b7c152E9663543D63`	25434534
Soneium	`soneium`	`0x360e68faccca8ca495c1b759fd9eee466db9fb32`	`0x1b35d13a2e2528f192637f14b05f0dc0e7deb566`	2473300
Ink	`ink`	`0x360e68faccca8ca495c1b759fd9eee466db9fb32`	`0x1b35d13a2e2528f192637f14b05f0dc0e7deb566`	4580556
Celo	`celo`	`0x288dc841A52FCA2707c6947B3A777c5E56cd87BC`	`0xf7965f3981e4D5BC383BfBCb61501763e9068CA9`	43985160
Linea	`linea`	`0x248083fb965359d82b06c1f5322480dcfc1ad857`	`0xddcad5775b2816a87495f207731b3571d7ee3c76`	28974969
Monad	`monad`	`0x188d586Ddcf52439676Ca21A244753fA19F9Ea8e`	`0x5b7eC4a94fF9beDb700fb82aB09d5846972F4016`	29255895
X Layer	`xlayer-mainnet`	`0x360E68faCcca8cA495c1B759Fd9EEe466db9FB32`	`0xcF1EAFC6928dC385A342E7C6491d371d2871458b`	46106401
MegaETH	`megaeth`	`0xacb7e78fa05d562e0a5d3089ec896d57d057d38e`	`0x9ae0921e981aaa7308f176f8d4f9129b9247c89d`	7009653
Tempo	`tempo`	`0x33620f62c5b9b2086dd6b62f4a297a9f30347029`	`0x3fc79444f8eacc1894775493ff3fa41f1e35ce11`	6606180
Robinhood Chain	`robinhood`	`0x8366a39cc670b4001a1121b8f6a443a643e40951`	`0x58daec3116aae6d93017baaea7749052e8a04fa7`	9070

Testnets:

Chain	`--network`	PoolManager	PositionManager	initialBlock
Ethereum Sepolia	`sepolia`	`0xE03A1074c86CFeDd5C142C4F04F1a1536e203543`	`0x429ba70129df741B2Ca2a85BC3A2a3328e5c09b4`	7258946
Base Sepolia	`base-sepolia`	`0x05E73354cFDd6745C338b50BcFDfA3Aa6fA03408`	`0x4b2c77d209d3405f41a037ec6c77f7f5b8e2ca80`	19088197
Arbitrum Sepolia	`arbitrum-sepolia`	`0xFB3e0C6F74eB1a21CC1Da29aeC80D2Dfe6C9a317`	`0xAc631556d3d4019C95769033B5E719dD77124BAc`	105909222
Unichain Sepolia	`unichain-testnet`	`0x00b036b58a818b1bc34d502d3fe730db729e62ac`	`0xf969aee60879c54baaed9f3ed26147db216fd664`	7092034

Addresses come from networks.json in the upstream subgraph; initialBlock is the earlier of the two deployment blocks.

Uniswap v4 is also deployed on Arc, which has no Substreams endpoint yet.

To point the module at contracts not listed here, override the params directly:

substreams run ./substreams.yaml map_events \
  --network base

Prerequisites

Install the Substreams CLI (includes substreams sink clickhouse — migration guide). Docker for the local ClickHouse + Hasura stack.

Build

From the monorepo root (workspace member):

cd substreams-chain-modules
cargo build -p uniswap_v4_substreams --release --target wasm32-unknown-unknown
# or:
cd dex/uniswap-v4-substreams && substreams build
# → uniswap-v4-substreams-v0.1.0.spkg

Sink to Postgres (without views and docker helpers)

(You need a postgresql instance accessible with DSN)

DSN="psql://user:$PASSWORD@host:port/dbname?schemaName=..."
substreams sink postgres uniswap-v4-substreams map_events  --dsn "$DSN" --spool-dir=/path/to/tmpdir --spool-max-size=8GiB --network=base

Sink To Clickhouse

git clone https://github.com/streamingfast/substreams-chain-modules.git
cd substreams-chain-modules/dex/uniswap-v4-substreams

docker compose up -d                    # ClickHouse + Hasura + connector
# substreams auth                       # once

substreams sink clickhouse ./substreams.yaml map_events \
  --dsn "clickhouse://default:SecureMe!@127.0.0.1:9000/uniswap_v4" \
  --network base \
  --bytes-encoding hex \
  --cursor-file-path ./cursor.txt \
  --sink-info-folder ./ch-sink-info

# after event tables exist:
./scripts/apply_views.sh
./scripts/hasura_connect_clickhouse.sh

Then open the Console or hit GraphQL:

Service	URL
GraphQL	http://localhost:8080/v1/graphql · header `x-hasura-admin-secret: SecureMe!`
Console	http://localhost:8080/console
ClickHouse	http://127.0.0.1:8123 · DB `uniswap_v4`

curl -s http://localhost:8080/v1/graphql \
  -H 'content-type: application/json' \
  -H 'x-hasura-admin-secret: SecureMe!' \
  -d '{"query":"{ uniswap_v4_api_pools(limit: 5) { pool_id token0 token1 fee tick liquidity swap_count } }"}'

More examples: sql/hasura/examples.graphql

Hosted option: StreamingFast can host the sink against your warehouse — hosted sinks · Portal.

API views

View	Meaning
`api_pools`	Pool id HOL: tokens, fee, latest price/tick/liquidity
`api_swaps`	Swap events
`api_modify_liquidity`	Liquidity modifications
`api_positions`	Position NFT latest owner
`api_tokens`	Currency addresses seen (no symbol/decimals eth_call yet)

Out of core (for now)

USD volumes / Bundle pricing
Tick entities, day/hour aggregates as full subgraph parity
Hook factory extras (Arrakis/Euler)
Token metadata eth_call

Modules

Execution graph

1 modules

mapMain

map_events

from #21688329

Output

uniswap.v4.Events

Inputs

paramssf.ethereum.type.v2.Block

Protobuf

uniswap.v4

Eventsmain

uniswap.v4.Events

InitializeEvent[]initialize_events = 1

SwapEvent[]swap_events = 2

ModifyLiquidityEvent[]modify_liquidity_events = 3

PositionTransferEvent[]position_transfer_events = 4

PositionSubscriptionEvent[]position_subscription_events = 5

PositionUnsubscriptionEvent[]position_unsubscription_events = 6

InitializeEvent

uniswap.v4.InitializeEvent

stringid = 1

uint64block_number = 2

uint64block_timestamp = 3

stringtransaction_hash = 4

uint32log_index = 5

stringcontract = 6

stringevent_name = 7

stringpool_id = 8

stringcurrency0 = 9

stringcurrency1 = 10

stringfee = 11

stringtick_spacing = 12

stringhooks = 13

stringsqrt_price_x96 = 14

stringtick = 15

ModifyLiquidityEvent

uniswap.v4.ModifyLiquidityEvent

stringid = 1

uint64block_number = 2

uint64block_timestamp = 3

stringtransaction_hash = 4

uint32log_index = 5

stringcontract = 6

stringevent_name = 7

stringpool_id = 8

stringsender = 9

stringtick_lower = 10

stringtick_upper = 11

stringliquidity_delta = 12

stringsalt = 13

PositionSubscriptionEvent

uniswap.v4.PositionSubscriptionEvent

stringid = 1

uint64block_number = 2

uint64block_timestamp = 3

stringtransaction_hash = 4

uint32log_index = 5

stringcontract = 6

stringevent_name = 7

stringtoken_id = 8

stringsubscriber = 9

PositionTransferEvent

uniswap.v4.PositionTransferEvent

stringid = 1

uint64block_number = 2

uint64block_timestamp = 3

stringtransaction_hash = 4

uint32log_index = 5

stringcontract = 6

stringevent_name = 7

stringfrom_address = 8

stringto_address = 9

stringtoken_id = 10

PositionUnsubscriptionEvent

uniswap.v4.PositionUnsubscriptionEvent

stringid = 1

uint64block_number = 2

uint64block_timestamp = 3

stringtransaction_hash = 4

uint32log_index = 5

stringcontract = 6

stringevent_name = 7

stringtoken_id = 8

stringsubscriber = 9

SwapEvent

uniswap.v4.SwapEvent

stringid = 1

uint64block_number = 2

uint64block_timestamp = 3

stringtransaction_hash = 4

uint32log_index = 5

stringcontract = 6

stringevent_name = 7

stringpool_id = 8

stringsender = 9

stringamount0 = 10

stringamount1 = 11

stringsqrt_price_x96 = 12

stringliquidity = 13

stringtick = 14

stringfee = 15

Show 27 dependencies

schema

ClickhouseIndexField

schema.ClickhouseIndexField

ClickhouseIndexField defines a secondary index for improved query performance. Secondary indexes help ClickHouse skip irrelevant data blocks during query execution.

stringname = 1

The name of the index (must be unique within the table)

stringfield_name = 2

The field name on which to create the index

IndexTypetype = 3

The type of index to create (e.g., minmax, bloom_filter, set)

uint32granularity = 4

The granularity parameter that controls index density (higher = less memory, lower precision)

Functionfunction = 5

Optional function to apply to the field value before indexing

ClickhouseOrderByField

schema.ClickhouseOrderByField

ClickhouseOrderByField defines a field used in the ClickHouse table ORDER BY clause. ORDER BY determines the physical storage order of data for optimal compression and query performance.

stringname = 1

The name of the field to include in the ORDER BY clause

booldescending = 2

Whether to sort this field in descending order (default is ascending)

Functionfunction = 3

Optional function to apply to the field value before ordering (e.g., toDate for timestamps)

ClickhousePartitionByField

schema.ClickhousePartitionByField

ClickhousePartitionByField defines a field used for ClickHouse table partitioning. Partitioning splits data into separate parts based on the specified field values.

stringname = 1

The name of the field to use for partitioning

Functionfunction = 2

Optional function to apply to the field value before partitioning (e.g., toYYYYMM for dates)

ClickhouseTableOptions

schema.ClickhouseTableOptions

ClickhouseTableOptions defines ClickHouse-specific table configuration options. These options are used to configure ClickHouse table engines and optimize query performance.

ClickhouseOrderByField[]order_by_fields = 1

Fields to use for the ORDER BY clause in ClickHouse table definition. ORDER BY determines the physical ordering of data on disk for better compression and query performance.

ClickhousePartitionByField[]partition_fields = 2

Fields to use for table partitioning in ClickHouse. Partitioning helps with query performance and data management by splitting data into logical parts.

ClickhouseIndexField[]index_fields = 4

Secondary indexes to create for improved query performance on specific columns. These are data skipping indexes that help ClickHouse skip irrelevant data blocks during queries.

Column

schema.Column

Column defines metadata for mapping a protobuf field to a database column. This message is used with the (field) extension on protobuf fields.

stringname = 1

Custom column name. If not specified, the field name is used.

stringforeign_key = 2

Foreign key reference to another table's column in the format "table.column". Used to establish referential integrity constraints in relational databases.

boolunique = 3

Whether this column should have a unique constraint. Ensures no duplicate values exist for this column.

boolprimary_key = 4

Whether this column is part of the primary key. Primary key columns are automatically non-null and unique.

StringConvertionconvertTo = 5

Specifies how to convert string fields to specific numeric types. Only applies to string fields that contain numeric data. Leave unset for no conversion (store as string).

boolinline = 6

Decimal128

schema.Decimal128

Decimal128 represents a 128-bit decimal type for string conversion. Used in StringConvertion to specify that a string field should be converted to Decimal128.

int32scale = 1

The number of digits after the decimal point for this decimal type.

Decimal256

schema.Decimal256

Decimal256 represents a 256-bit decimal type for string conversion. Used in StringConvertion to specify that a string field should be converted to Decimal256.

int32scale = 1

The number of digits after the decimal point for this decimal type.

Int128

schema.Int128

Int128 represents a 128-bit signed integer type for string conversion. Used in StringConvertion to specify that a string field should be converted to Int128.

No fields.

Int256

schema.Int256

Int256 represents a 256-bit signed integer type for string conversion. Used in StringConvertion to specify that a string field should be converted to Int256.

No fields.

StringConvertion

schema.StringConvertion

StringConvertion defines how string fields should be converted to specific numeric types. This is used when protobuf string fields contain numeric data that should be stored as native numeric types in the database for better performance and storage efficiency. Usage: Set this in Column.convertTo field to specify the target numeric type.

Int128int128 = 2oneof convertion

Convert string to 128-bit signed integer

UInt128uint128 = 3oneof convertion

Convert string to 128-bit unsigned integer

Int256int256 = 4oneof convertion

Convert string to 256-bit signed integer

UInt256uint256 = 6oneof convertion

Convert string to 256-bit unsigned integer

Decimal128decimal128 = 50oneof convertion

Convert string to 128-bit decimal with specified scale

Decimal256decimal256 = 51oneof convertion

Convert string to 256-bit decimal with specified scale

Table

schema.Table

Table defines metadata for mapping a protobuf message to a database table. This message is used with the (table) extension on protobuf messages.

stringname = 1

The name of the database table. If not specified, the message name is used.

stringchild_of = 2

Optional field to specify a parent table for establishing table relationships. Used for creating foreign key relationships in relational databases.

ClickhouseTableOptionsclickhouse_table_options = 200

ClickHouse-specific table options for configuring table engine parameters. Only applicable when using ClickHouse as the target database.

UInt128

schema.UInt128

UInt128 represents a 128-bit unsigned integer type for string conversion. Used in StringConvertion to specify that a string field should be converted to UInt128.

No fields.

UInt256

schema.UInt256

UInt256 represents a 256-bit unsigned integer type for string conversion. Used in StringConvertion to specify that a string field should be converted to UInt256.

No fields.

Functionenum

schema.Function

unset = 0

No function applied (use raw field value)

toYYYYMM = 1

Convert date/timestamp to YYYYMM format (useful for monthly partitioning)

toYYYYDD = 2

Convert date/timestamp to YYYYDD format (useful for daily partitioning)

toYear = 3

Extract year from date/timestamp (useful for yearly partitioning)

toMonth = 4

Extract month from date/timestamp (useful for monthly grouping)

toDate = 5

Convert timestamp to date (removes time component)

toStartOfMonth = 6

Convert date to first day of the month (useful for monthly aggregations)

IndexTypeenum

schema.IndexType

minmax = 0

MinMax index stores minimum and maximum values for each granule (fastest, least memory)

set = 1

Set index stores unique values for each granule (good for low cardinality fields)

ngrambf_v1 = 2

N-gram Bloom filter index for substring searches (good for text search)

tokenbf_v1 = 3

Token Bloom filter index for full-word searches (good for tokenized text)

bloom_filter = 4

Bloom filter index for equality checks (good for high cardinality fields)

sf.firehose.v2

BlockMetadata

sf.firehose.v2.BlockMetadata

uint64num = 1

Num is the block number of this response's block.

stringid = 2

ID is the block ID of this response's block. The ID actual representation is chain specific.

Antelope & Ethereum uses hex.
NEAR & Solana uses base58.

Refer to the chain documentation for more details.

uint64parent_num = 3

ParentNum is the block number of the parent of this response's block

stringparent_id = 4

ParentID is the block ID of the parent of this response's block. If this response is the genesis block, this field is empty.

The ID actual representation is chain specific.

Antelope & Ethereum uses hex.
NEAR & Solana uses base58.

Refer to the chain documentation for more details.

uint64lib_num = 5

LibNum is the block number of the last irreversible block (a.k.a last finalized block) at the time of this response' block. It determines the finality of the block.

Timestamptime = 6

Time is the time at which the block was produced.

InfoRequest

sf.firehose.v2.InfoRequest

No fields.

InfoResponse

sf.firehose.v2.InfoResponse

stringchain_name = 1

Canonical chain name from https://thegraph.com/docs/en/developing/supported-networks/ (ex: matic, mainnet ...)

string[]chain_name_aliases = 2

Alternate names for the chain.

uint64first_streamable_block_num = 3

First block that is served by this endpoint. This should usually be the genesis block, but some providers may have truncated history.

stringfirst_streamable_block_id = 4

InfoResponse.BlockIdEncodingblock_id_encoding = 5

This informs the client on how to decode the block_id field inside the "Clock" message as well as the first_streamable_block_id above.

string[]block_features = 10

features describes the blocks. Popular values for EVM chains include base, extended or hybrid.

Request

sf.firehose.v2.Request

int64start_block_num = 1

Controls where the stream of blocks will start.

The stream will start inclusively at the requested block num.

When not provided, starts at first streamable block of the chain. Not all chain starts at the same block number, so you might get an higher block than requested when using default value of 0.

Can be negative, will be resolved relative to the chain head block, assuming a chain at head block #100, then using -50 as the value will start at block #50. If it resolves before first streamable block of chain, we assume start of chain.

If start_cursor is given, this value is ignored and the stream instead starts immediately after the Block pointed by the opaque start_cursor value.

stringcursor = 2

Controls where the stream of blocks will start which will be immediately after the Block pointed by this opaque cursor.

Obtain this value from a previously received Response.cursor.

This value takes precedence over start_block_num.

uint64stop_block_num = 3

When non-zero, controls where the stream of blocks will stop.

The stream will close after that block has passed so the boundary is inclusive.

boolfinal_blocks_only = 4

With final_block_only, you only receive blocks with STEP_FINAL Default behavior will send blocks as STEP_NEW, with occasional STEP_UNDO

Any[]transforms = 10

Response

sf.firehose.v2.Response

Anyblock = 1

Chain specific block payload, ex:

sf.eosio.type.v1.Block
sf.ethereum.type.v1.Block
sf.near.type.v1.Block

ForkStepstep = 6

stringcursor = 10

BlockMetadatametadata = 12

Metadata about the block, added in some Firehose version, so consumer should be ready to handle the absence of this field.

SingleBlockRequest

sf.firehose.v2.SingleBlockRequest

SingleBlockRequest.BlockNumberblock_number = 3oneof reference

SingleBlockRequest.BlockHashAndNumberblock_hash_and_number = 4oneof reference

SingleBlockRequest.Cursorcursor = 5oneof reference

Any[]transforms = 6

BlockHashAndNumber

sf.firehose.v2.SingleBlockRequest.BlockHashAndNumber

Get the current block with specific hash and number

uint64num = 1

stringhash = 2

BlockNumber

sf.firehose.v2.SingleBlockRequest.BlockNumber

Get the current known canonical version of a block at with this number

uint64num = 1

Cursor

sf.firehose.v2.SingleBlockRequest.Cursor

Get the block that generated a specific cursor

stringcursor = 1

SingleBlockResponse

sf.firehose.v2.SingleBlockResponse

Anyblock = 1

BlockMetadatametadata = 2

Metadata about the block, added in some Firehose version, so consumer should be ready to handle the absence of this field.

ForkStepenum

sf.firehose.v2.ForkStep

STEP_UNSET = 0

STEP_NEW = 1

Incoming block

STEP_UNDO = 2

A reorg caused this specific block to be excluded from the chain

STEP_FINAL = 3

Block is now final and can be committed (finality is chain specific, see chain documentation for more details)

BlockIdEncodingenum

sf.firehose.v2.InfoResponse.BlockIdEncoding

BLOCK_ID_ENCODING_UNSET = 0

BLOCK_ID_ENCODING_HEX = 1

BLOCK_ID_ENCODING_0X_HEX = 2

BLOCK_ID_ENCODING_BASE58 = 3

BLOCK_ID_ENCODING_BASE64 = 4

BLOCK_ID_ENCODING_BASE64URL = 5