uniswapv3

package module
v0.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 10, 2026 License: MIT Imports: 13 Imported by: 0

README

uniswapv3

CI Go Reference

uniswapv3 is a Go library for indexing and interacting with Uniswap V3.

It provides event decoding, on-chain state tracking, swap path encoding, pool address computation, and tick/liquidity math utilities. It is designed to work with ethindexer for robust backfill and live indexing.

Install

go get github.com/LeTamanoir/uniswapv3

Usage

See examples/ for a complete indexing example.

handler := uniswapv3.NewFactoryHandler()

idx, err := ethindexer.OpenContext(ctx, ethindexer.Options{
    Client:  httpClient,
    Handler: handler,
    Store:   store,
    LogFunc: slog.Info,
})

After processing, handler.Pools contains the tracked state for every indexed pool:

  • Slot0 — current sqrtPriceX96, tick, and protocol fee
  • Liquidity — current global liquidity
  • Ticks — initialized ticks with gross/net liquidity
  • TickBitmap — initialized tick bitmap

What it provides

Event decoding

Decodes PoolCreated, Mint, Burn, and Swap logs into typed structs:

event, err := uniswapv3.UnpackSwapEvent(log)

State tracking

FactoryHandler implements ethindexer.Handler and maintains pool state by applying mints, burns, and swaps:

  • Tracks tick liquidity and flips the tick bitmap when ticks are initialized or cleared
  • Updates global liquidity when the current tick crosses position boundaries
  • Updates Slot0 on every swap

Swap paths

Encode and decode Uniswap V3 multi-hop swap paths:

path := uniswapv3.NewPathBuilder().
    From(tokenA).
    Fee(3000).
    Hop(tokenB).
    Fee(500).
    To(tokenC)

Pool keys and addresses

Compute canonical pool keys and deterministic CREATE2 pool addresses:

key := uniswapv3.NewPoolKey(token0, token1, fee)
addr := uniswapv3.ComputePoolAddress(key)

Utilities

  • uint24/int24 helpers (ReadUint24, WriteUint24, ReadInt24)
  • Tick bitmap position and flip operations
  • Liquidity add/sub with overflow checks

Development

just check
go test ./...

License

MIT

Documentation

Index

Constants

View Source
const (
	// Uint24Max is the maximum value representable as a uint24.
	Uint24Max = 0xFFFFFF

	// Uint24Size is the byte length of a uint24.
	Uint24Size = 3
)
View Source
const (
	// FactoryCreationBlock is the Uniswap V3 factory deployment block on Ethereum mainnet.
	FactoryCreationBlock = 12369621
)

Variables

View Source
var (
	// PoolCreatedEventID is the Uniswap V3 Factory PoolCreated event ID.
	//
	//	PoolCreated(address,address,uint24,int24,address)
	PoolCreatedEventID = crypto.Keccak256Hash([]byte("PoolCreated(address,address,uint24,int24,address)"))

	// MintEventID is the Uniswap V3 Pool Mint event ID.
	//
	//	Mint(address,address,int24,int24,uint128,uint256,uint256)
	MintEventID = crypto.Keccak256Hash([]byte("Mint(address,address,int24,int24,uint128,uint256,uint256)"))

	// SwapEventID is the Uniswap V3 Pool Swap event ID.
	//
	//	Swap(address,address,int256,int256,uint160,uint128,int24)
	SwapEventID = crypto.Keccak256Hash([]byte("Swap(address,address,int256,int256,uint160,uint128,int24)"))

	// BurnEventID is the Uniswap V3 Pool Burn event ID.
	//
	//	Burn(address,int24,int24,uint128,uint256,uint256)
	BurnEventID = crypto.Keccak256Hash([]byte("Burn(address,int24,int24,uint128,uint256,uint256)"))
)
View Source
var (
	// FactoryAddress is the Uniswap V3 factory address on Ethereum mainnet.
	FactoryAddress = common.HexToAddress("0x1F98431c8aD98523631AE4a59f267346ea31F984")
)
View Source
var (
	// PoolInitCodeHash is the Uniswap V3 pool init code hash.
	PoolInitCodeHash = common.HexToHash("0xe34f199b19b2b4f47f68442619d555527d244f78a3297ea89325f843f87b8b54")
)

Functions

func AppendUint24

func AppendUint24(b []byte, v uint32) []byte

AppendUint24 appends v as a big-endian uint24.

func ComputePoolAddress

func ComputePoolAddress(key PoolKey) common.Address

ComputePoolAddress returns the deterministic Uniswap V3 pool address for key.

func ReadInt24 added in v0.1.5

func ReadInt24(b []byte) int32

ReadInt24 reads a big-endian int24 and sign-extends it to int32.

func ReadUint24

func ReadUint24(b []byte) uint32

ReadUint24 reads a big-endian uint24.

func WriteUint24

func WriteUint24(dst []byte, v uint32)

WriteUint24 writes v as a big-endian uint24.

Types

type BurnEvent added in v0.1.5

type BurnEvent struct {
	// The owner of the position for which liquidity is removed
	Owner common.Address
	// The lower tick of the position
	TickLower int32 // int24
	// The upper tick of the position
	TickUpper int32 // int24
	// The amount of liquidity to remove
	Amount uint256.Int // uint128
	// The amount of token0 withdrawn
	Amount0 uint256.Int // uint256
	// The amount of token1 withdrawn
	Amount1 uint256.Int // uint256
}

BurnEvent is a decoded Uniswap V3 Pool Burn event.

func UnpackBurnEvent added in v0.1.5

func UnpackBurnEvent(log types.Log) (*BurnEvent, error)

UnpackBurnEvent decodes a Uniswap V3 Pool Burn event.

type FactoryHandler added in v0.1.5

type FactoryHandler struct {
	Pools map[common.Address]*PoolState
}

func NewFactoryHandler added in v0.1.5

func NewFactoryHandler() *FactoryHandler

func (*FactoryHandler) Filter added in v0.1.5

func (f *FactoryHandler) Filter() ethindexer.Filter

func (*FactoryHandler) Process added in v0.1.5

func (f *FactoryHandler) Process(ctx context.Context, logs []types.Log) error

func (*FactoryHandler) Restore added in v0.1.5

func (f *FactoryHandler) Restore(_ context.Context, data []byte) error

func (*FactoryHandler) Snapshot added in v0.1.5

func (f *FactoryHandler) Snapshot(_ context.Context) ([]byte, error)

type MintEvent added in v0.1.5

type MintEvent struct {
	// The address that minted the liquidity
	Sender common.Address
	// The owner of the position and recipient of any minted liquidity
	Owner common.Address
	// The lower tick of the position
	TickLower int32 // int24
	// The upper tick of the position
	TickUpper int32 // int24
	// The amount of liquidity minted to the position range
	Amount uint256.Int // uint128
	// How much token0 was required for the minted liquidity
	Amount0 uint256.Int // uint256
	// How much token1 was required for the minted liquidity
	Amount1 uint256.Int // uint256
}

MintEvent is a decoded Uniswap V3 Pool Mint event.

func UnpackMintEvent added in v0.1.5

func UnpackMintEvent(log types.Log) (*MintEvent, error)

UnpackMintEvent decodes a Uniswap V3 Pool Mint event.

type Path added in v0.1.4

type Path []byte

Path is an encoded Uniswap V3 swap path.

func (Path) DecodeFirstPool added in v0.1.4

func (p Path) DecodeFirstPool() (tokenIn common.Address, tokenOut common.Address, fee uint32)

DecodeFirstPool returns the first pool encoded in the path.

func (Path) FeeAt added in v0.1.4

func (p Path) FeeAt(pos int) uint32

FeeAt returns the pool fee at position pos.

from [--fee--> hop]... --fee--> to
        0        1..n-1          n

func (Path) HasMultiplePools added in v0.1.4

func (p Path) HasMultiplePools() bool

HasMultiplePools reports whether the path contains more than one pool.

func (Path) NumPools added in v0.1.4

func (p Path) NumPools() int

NumPools returns the number of pools encoded in the path.

func (Path) Pools added in v0.1.4

func (p Path) Pools() []PoolKey

Pools returns the pools encoded in the path, in swap order.

func (Path) SkipToken added in v0.1.4

func (p Path) SkipToken() Path

SkipToken returns the path without its first token and fee.

func (Path) String added in v0.1.4

func (p Path) String() string

func (Path) TokenAt added in v0.1.4

func (p Path) TokenAt(pos int) common.Address

TokenAt returns the token at position pos.

from [--fee--> hop]... --fee--> to
  0           1..n              n+1

type PathBuilder added in v0.1.4

type PathBuilder interface {
	// From sets the input token.
	From(common.Address) PathBuilderSetFee
}

PathBuilder builds a swap path from the input token.

func NewPathBuilder

func NewPathBuilder() PathBuilder

NewPathBuilder returns a new swap path builder.

type PathBuilderSetFee added in v0.1.4

type PathBuilderSetFee interface {
	// Fee appends the fee for the next pool.
	Fee(uint32) PathBuilderSetNext
}

PathBuilderSetFee continues a swap path by setting the next pool fee.

type PathBuilderSetNext added in v0.1.4

type PathBuilderSetNext interface {
	// Hop appends an intermediate token.
	Hop(common.Address) PathBuilderSetFee

	// To appends the output token and returns the encoded path.
	To(common.Address) Path
}

PathBuilderSetNext continues or completes a swap path.

type PoolCreatedEvent added in v0.1.5

type PoolCreatedEvent struct {
	// The first token of the pool by address sort order
	Token0 common.Address
	// The second token of the pool by address sort order
	Token1 common.Address
	// The fee collected upon every swap in the pool, denominated in hundredths of a bip
	Fee uint32 // uint24
	// The minimum number of ticks between initialized ticks
	TickSpacing int32 // int24
	// The address of the created pool
	Pool common.Address
}

PoolCreatedEvent is a decoded Uniswap V3 Factory PoolCreated event.

func UnpackPoolCreatedEvent added in v0.1.5

func UnpackPoolCreatedEvent(log types.Log) (*PoolCreatedEvent, error)

UnpackPoolCreatedEvent decodes a Uniswap V3 Factory PoolCreated event.

type PoolKey

type PoolKey [common.AddressLength*2 + Uint24Size]byte

PoolKey identifies a Uniswap V3 pool by its sorted token pair and fee.

func NewPoolKey

func NewPoolKey(token0, token1 common.Address, fee uint32) PoolKey

NewPoolKey returns the canonical key for token0, token1, and fee.

func (PoolKey) Fee

func (p PoolKey) Fee() uint32

Fee returns the pool fee.

func (PoolKey) String

func (p PoolKey) String() string

func (PoolKey) Token0

func (p PoolKey) Token0() common.Address

Token0 returns the lower-sorted token address.

func (PoolKey) Token1

func (p PoolKey) Token1() common.Address

Token1 returns the higher-sorted token address.

type PoolState added in v0.1.5

type PoolState struct {
	Slot0       Slot0
	Liquidity   uint256.Int // uint128
	TickSpacing int32       // in24
	TickBitmap  map[int16]uint256.Int
	Ticks       map[int32]tick_Info
}

func (*PoolState) Initialized added in v0.1.6

func (p *PoolState) Initialized() bool

type Slot0 added in v0.1.5

type Slot0 struct {
	// The current price
	SqrtPriceX96 uint256.Int // uint160
	// The current tick
	Tick int32 // int24
}

type SwapEvent added in v0.1.5

type SwapEvent struct {
	// The address that initiated the swap call, and that received the callback
	Sender common.Address
	// The address that received the output of the swap
	Recipient common.Address
	// The delta of the token0 balance of the pool
	Amount0 uint256.Int // int256
	// The delta of the token1 balance of the pool
	Amount1 uint256.Int // int256
	// The sqrt(price) of the pool after the swap, as a Q64.96
	SqrtPriceX96 uint256.Int // uint160
	// The liquidity of the pool after the swap
	Liquidity uint256.Int // uint128
	// The log base 1.0001 of price of the pool after the swap
	Tick int32 // int24
}

SwapEvent is a decoded Uniswap V3 Pool Swap event.

func UnpackSwapEvent added in v0.1.5

func UnpackSwapEvent(log types.Log) (*SwapEvent, error)

UnpackSwapEvent decodes a Uniswap V3 Pool Swap event.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL