bridgesync

package
v0.7.2 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2025 License: Apache-2.0, MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidPageSize indicates that the page size is invalid
	ErrInvalidPageSize = errors.New("page size must be greater than 0")

	// ErrInvalidPageNumber indicates that the page number is invalid
	ErrInvalidPageNumber = errors.New("page number must be greater than 0")
)

Functions

func DecodeGlobalIndex

func DecodeGlobalIndex(globalIndex *big.Int) (mainnetFlag bool,
	rollupIndex uint32, localExitRootIndex uint32, err error)

Decodes global index to its three parts: 1. mainnetFlag - first byte 2. rollupIndex - next 4 bytes 3. localExitRootIndex - last 4 bytes NOTE - mainnet flag is not in the global index bytes if it is false NOTE - rollup index is 0 if mainnet flag is true NOTE - rollup index is not in the global index bytes if mainnet flag is false and rollup index is 0

func GenerateGlobalIndex

func GenerateGlobalIndex(mainnetFlag bool, rollupIndex uint32, depositCount uint32) *big.Int

GenerateGlobalIndex encodes a unique "global index" used for identifying bridges and claims. The index is constructed as a big integer from three components: - mainnetFlag: indicates if the origin network is mainnet (true) or a rollup (false).

  • If true, the first 4-byte segment is set to `0x01` and the next 4 bytes are zero.
  • If false, the first 4-byte segment is the rollupIndex (networkID - 1).

- rollupIndex: only used if mainnetFlag is false; represents (networkID - 1). - depositCount: always appended as the final 4-byte segment.

Encoding layout (big-endian concatenation of 4-byte chunks):

[ mainnetFlag ] [ rollupIndex ] [ depositCount ]

Examples:

mainnetFlag=true,  depositCount=3  → 0x0100000000000003
mainnetFlag=false, rollupIndex=1, depositCount=3 → 0x0000000100000003

The result is returned as a *big.Int that can be used consistently across mainnet and rollup networks.

func GenerateGlobalIndexForNetworkID added in v0.7.0

func GenerateGlobalIndexForNetworkID(networkID uint32, depositCount uint32) *big.Int

GenerateGlobalIndexForNetworkID builds the "global index" used to identify bridges and claims.

Types

type BackfillTxnSender added in v0.7.0

type BackfillTxnSender struct {
	// contains filtered or unexported fields
}

BackfillTxnSender handles the backfilling of txn_sender field for bridge records

func NewBackfillTxnSender added in v0.7.0

func NewBackfillTxnSender(
	dbPath string,
	client types.EthClienter,
	bridgeAddr common.Address,
	logger *log.Logger,
) (*BackfillTxnSender, error)

NewBackfillTxnSender creates a new instance of BackfillTxnSender

func (*BackfillTxnSender) BackfillAll added in v0.7.0

func (b *BackfillTxnSender) BackfillAll(ctx context.Context) error

BackfillAll processes bridge table to backfill txn_sender field

func (*BackfillTxnSender) Close added in v0.7.0

func (b *BackfillTxnSender) Close() error

Close closes the database connection

type Bridge

type Bridge struct {
	BlockNum           uint64         `meddler:"block_num"`
	BlockPos           uint64         `meddler:"block_pos"`
	FromAddress        common.Address `meddler:"from_address,address"`
	TxHash             common.Hash    `meddler:"tx_hash,hash"`
	BlockTimestamp     uint64         `meddler:"block_timestamp"`
	LeafType           uint8          `meddler:"leaf_type"`
	OriginNetwork      uint32         `meddler:"origin_network"`
	OriginAddress      common.Address `meddler:"origin_address"`
	DestinationNetwork uint32         `meddler:"destination_network"`
	DestinationAddress common.Address `meddler:"destination_address"`
	Amount             *big.Int       `meddler:"amount,bigint"`
	Metadata           []byte         `meddler:"metadata"`
	DepositCount       uint32         `meddler:"deposit_count"`
	TxnSender          common.Address `meddler:"txn_sender,address"`
}

Bridge is the representation of a bridge event

func (*Bridge) Hash

func (b *Bridge) Hash() common.Hash

Hash returns the hash of the bridge event as expected by the exit tree Note: can't change the Hash() here after adding BlockTimestamp and TxHash. Might affect previous versions

type BridgeSync

type BridgeSync struct {
	// contains filtered or unexported fields
}

BridgeSync manages the state of the exit tree for the bridge contract by processing Ethereum blockchain events.

func NewL1

func NewL1(
	ctx context.Context,
	cfg Config,
	rd ReorgDetector,
	ethClient aggkittypes.EthClienter,
	originNetwork uint32,
	syncFullClaims bool,
) (*BridgeSync, error)

NewL1 creates a bridge syncer that synchronizes the mainnet exit tree

func NewL2

func NewL2(
	ctx context.Context,
	cfg Config,
	rd ReorgDetector,
	ethClient aggkittypes.EthClienter,
	originNetwork uint32,
	syncFullClaims bool,
) (*BridgeSync, error)

NewL2 creates a bridge syncer that synchronizes the local exit tree

func NewL2ReadOnly added in v0.7.0

func NewL2ReadOnly(
	ctx context.Context,
	dbPath string,
	originNetwork uint32,
	dbQueryTimeout time.Duration,
) (*BridgeSync, error)

func (*BridgeSync) GetBlockByLER

func (s *BridgeSync) GetBlockByLER(ctx context.Context, ler common.Hash) (uint64, error)

func (*BridgeSync) GetBridges

func (s *BridgeSync) GetBridges(ctx context.Context, fromBlock, toBlock uint64) ([]Bridge, error)

func (*BridgeSync) GetBridgesPaged added in v0.5.0

func (s *BridgeSync) GetBridgesPaged(
	ctx context.Context,
	page, pageSize uint32,
	depositCount *uint64, networkIDs []uint32, fromAddress string) ([]*Bridge, int, error)

func (*BridgeSync) GetClaims

func (s *BridgeSync) GetClaims(ctx context.Context, fromBlock, toBlock uint64) ([]Claim, error)

func (*BridgeSync) GetClaimsByGlobalIndex added in v0.7.0

func (s *BridgeSync) GetClaimsByGlobalIndex(ctx context.Context, globalIndex *big.Int) ([]Claim, error)

func (*BridgeSync) GetClaimsPaged added in v0.5.0

func (s *BridgeSync) GetClaimsPaged(
	ctx context.Context,
	page, pageSize uint32, networkIDs []uint32, fromAddress string, globalIndex *big.Int) ([]*Claim, int, error)

func (*BridgeSync) GetContractDepositCount added in v0.5.0

func (s *BridgeSync) GetContractDepositCount(ctx context.Context) (uint32, error)

GetContractDepositCount returns the last deposit count from the bridge contract

func (*BridgeSync) GetExitRootByHash added in v0.7.0

func (s *BridgeSync) GetExitRootByHash(ctx context.Context, root common.Hash) (*tree.Root, error)

func (*BridgeSync) GetExitRootByIndex

func (s *BridgeSync) GetExitRootByIndex(ctx context.Context, index uint32) (tree.Root, error)

GetExitRootByIndex returns the root of the exit tree at the moment the leaf with the given index was added

func (*BridgeSync) GetLastProcessedBlock

func (s *BridgeSync) GetLastProcessedBlock(ctx context.Context) (uint64, error)

func (*BridgeSync) GetLastReorgEvent added in v0.5.0

func (s *BridgeSync) GetLastReorgEvent(ctx context.Context) (*LastReorg, error)

func (*BridgeSync) GetLastRoot added in v0.5.0

func (s *BridgeSync) GetLastRoot(ctx context.Context) (*tree.Root, error)

func (*BridgeSync) GetLatestNetworkBlock added in v0.7.0

func (s *BridgeSync) GetLatestNetworkBlock(ctx context.Context) (uint64, error)

GetLatestNetworkBlock returns the latest block number from the network

func (*BridgeSync) GetLegacyTokenMigrations added in v0.5.0

func (s *BridgeSync) GetLegacyTokenMigrations(
	ctx context.Context, pageNumber, pageSize uint32) ([]*LegacyTokenMigration, int, error)

func (*BridgeSync) GetProof

func (s *BridgeSync) GetProof(ctx context.Context, depositCount uint32, localExitRoot common.Hash) (tree.Proof, error)

func (*BridgeSync) GetRootByLER

func (s *BridgeSync) GetRootByLER(ctx context.Context, ler common.Hash) (*tree.Root, error)

func (*BridgeSync) GetTokenMappings added in v0.5.0

func (s *BridgeSync) GetTokenMappings(ctx context.Context, pageNumber, pageSize uint32, originTokenAddress string,
) ([]*TokenMapping, int, error)

func (*BridgeSync) IsActive added in v0.7.0

func (s *BridgeSync) IsActive(ctx context.Context) bool

IsActive returns true if the syncer is active (not halted)

func (*BridgeSync) OriginNetwork

func (s *BridgeSync) OriginNetwork() uint32

OriginNetwork returns the network ID of the origin chain

func (*BridgeSync) Start

func (s *BridgeSync) Start(ctx context.Context)

Start starts the synchronization process

type BridgeSyncRuntimeData added in v0.5.0

type BridgeSyncRuntimeData struct {
	// This fields are coming from legacy sync.RuntimeData
	ChainID   uint64
	Addresses []common.Address
	// DBVersion tracks the database schema version for compatibility validation
	DBVersion *int
}

BridgeSyncRuntimeData contains runtime environment data used for database compatibility checks. It includes chain ID, contract addresses, and database version information.

func (BridgeSyncRuntimeData) IsCompatible added in v0.5.0

func (b BridgeSyncRuntimeData) IsCompatible(storage BridgeSyncRuntimeData) error

func (BridgeSyncRuntimeData) String added in v0.5.0

func (b BridgeSyncRuntimeData) String() string

type BridgeSyncerType added in v0.5.0

type BridgeSyncerType int

BridgeSyncerType represents the type of bridge syncer

const (
	L1BridgeSyncer BridgeSyncerType = iota
	L2BridgeSyncer

	// CurrentDBVersion represents the current version of the bridge syncer's database schema.
	// It is used to ensure the database is reset if an upgrade requires a full resync.
	// Increment this value whenever the database schema changes in a way that is not backward-compatible.
	CurrentDBVersion = 1
)

func (BridgeSyncerType) String added in v0.5.0

func (b BridgeSyncerType) String() string

type Claim

type Claim struct {
	BlockNum            uint64         `meddler:"block_num"`
	BlockPos            uint64         `meddler:"block_pos"`
	FromAddress         common.Address `meddler:"from_address,address"`
	TxHash              common.Hash    `meddler:"tx_hash,hash"`
	GlobalIndex         *big.Int       `meddler:"global_index,bigint"`
	OriginNetwork       uint32         `meddler:"origin_network"`
	OriginAddress       common.Address `meddler:"origin_address"`
	DestinationAddress  common.Address `meddler:"destination_address"`
	Amount              *big.Int       `meddler:"amount,bigint"`
	ProofLocalExitRoot  types.Proof    `meddler:"proof_local_exit_root,merkleproof"`
	ProofRollupExitRoot types.Proof    `meddler:"proof_rollup_exit_root,merkleproof"`
	MainnetExitRoot     common.Hash    `meddler:"mainnet_exit_root,hash"`
	RollupExitRoot      common.Hash    `meddler:"rollup_exit_root,hash"`
	GlobalExitRoot      common.Hash    `meddler:"global_exit_root,hash"`
	DestinationNetwork  uint32         `meddler:"destination_network"`
	Metadata            []byte         `meddler:"metadata"`
	IsMessage           bool           `meddler:"is_message"`
	BlockTimestamp      uint64         `meddler:"block_timestamp"`
}

Claim representation of a claim event

type Config

type Config struct {
	// DBPath path of the DB
	DBPath string `mapstructure:"DBPath"`
	// BlockFinality indicates the status of the blocks that will be queried in order to sync
	BlockFinality aggkittypes.BlockNumberFinality `` //nolint:lll
	/* 134-byte string literal not displayed */
	// InitialBlockNum is the first block that will be queried when starting the synchronization from scratch.
	// It should be a number equal or bellow the creation of the bridge contract
	InitialBlockNum uint64 `mapstructure:"InitialBlockNum"`
	// BridgeAddr is the address of the bridge smart contract
	BridgeAddr common.Address `mapstructure:"BridgeAddr"`
	// SyncBlockChunkSize is the amount of blocks that will be queried to the client on each request
	SyncBlockChunkSize uint64 `mapstructure:"SyncBlockChunkSize"`
	// RetryAfterErrorPeriod is the time that will be waited when an unexpected error happens before retry
	RetryAfterErrorPeriod types.Duration `mapstructure:"RetryAfterErrorPeriod"`
	// MaxRetryAttemptsAfterError is the maximum number of consecutive attempts that will happen before panicing.
	// Any number smaller than zero will be considered as unlimited retries
	MaxRetryAttemptsAfterError int `mapstructure:"MaxRetryAttemptsAfterError"`
	// WaitForNewBlocksPeriod time that will be waited when the synchronizer has reached the latest block
	WaitForNewBlocksPeriod types.Duration `mapstructure:"WaitForNewBlocksPeriod"`
	// RequireStorageContentCompatibility is true it's mandatory that data stored in the database
	// is compatible with the running environment
	RequireStorageContentCompatibility bool `mapstructure:"RequireStorageContentCompatibility"`
	// DBQueryTimeout is the timeout for database operations (queries, transactions)
	// This is separate from HTTP timeouts to allow database operations more time when needed
	DBQueryTimeout types.Duration `mapstructure:"DBQueryTimeout"`
}

type Event

type Event struct {
	Bridge               *Bridge
	Claim                *Claim
	TokenMapping         *TokenMapping
	LegacyTokenMigration *LegacyTokenMigration
	RemoveLegacyToken    *RemoveLegacyToken
}

Event combination of bridge, claim, token mapping and legacy token migration events

type LastReorg added in v0.5.0

type LastReorg struct {
	DetectedAt int64  `json:"detected_at"`
	FromBlock  uint64 `json:"from_block"`
	ToBlock    uint64 `json:"to_block"`
}

type LegacyTokenMigration added in v0.5.0

type LegacyTokenMigration struct {
	BlockNum            uint64         `meddler:"block_num"`
	BlockPos            uint64         `meddler:"block_pos"`
	BlockTimestamp      uint64         `meddler:"block_timestamp"`
	TxHash              common.Hash    `meddler:"tx_hash,hash"`
	Sender              common.Address `meddler:"sender,address"`
	LegacyTokenAddress  common.Address `meddler:"legacy_token_address,address"`
	UpdatedTokenAddress common.Address `meddler:"updated_token_address,address"`
	Amount              *big.Int       `meddler:"amount,bigint"`
}

LegacyTokenMigration representation of a MigrateLegacyToken event, that is emitted by the sovereign chain bridge contract.

type RecordToBackfill added in v0.7.0

type RecordToBackfill struct {
	BlockNum  uint64
	BlockPos  uint64
	TxHash    common.Hash
	TxnSender common.Address
}

RecordToBackfill represents a record that needs txn_sender backfilling

type RecordUpdate added in v0.7.0

type RecordUpdate struct {
	BlockNum  uint64
	BlockPos  uint64
	TxnSender common.Address
}

RecordUpdate represents a record update with txn_sender data

type RemoveLegacyToken added in v0.5.0

type RemoveLegacyToken struct {
	BlockNum           uint64         `meddler:"block_num"`
	BlockPos           uint64         `meddler:"block_pos"`
	BlockTimestamp     uint64         `meddler:"block_timestamp"`
	TxHash             common.Hash    `meddler:"tx_hash,hash"`
	LegacyTokenAddress common.Address `meddler:"legacy_token_address,address"`
}

RemoveLegacyToken representation of a RemoveLegacySovereignTokenAddress event, that is emitted by the sovereign chain bridge contract.

type ReorgDetector

type ReorgDetector interface {
	sync.ReorgDetector
	GetLastReorgEvent(ctx context.Context) (reorgdetector.ReorgEvent, error)
}

type TokenMapping added in v0.5.0

type TokenMapping struct {
	BlockNum            uint64                       `meddler:"block_num"`
	BlockPos            uint64                       `meddler:"block_pos"`
	BlockTimestamp      uint64                       `meddler:"block_timestamp"`
	TxHash              common.Hash                  `meddler:"tx_hash,hash"`
	OriginNetwork       uint32                       `meddler:"origin_network"`
	OriginTokenAddress  common.Address               `meddler:"origin_token_address,address"`
	WrappedTokenAddress common.Address               `meddler:"wrapped_token_address,address"`
	Metadata            []byte                       `meddler:"metadata"`
	IsNotMintable       bool                         `meddler:"is_not_mintable"`
	Type                bridgetypes.TokenMappingType `meddler:"token_type"`
}

TokenMapping representation of a NewWrappedToken event, that is emitted by the bridge contract

type Transaction added in v0.7.0

type Transaction struct {
	From             string `json:"from"`
	To               string `json:"to"`
	Hash             string `json:"hash"`
	Value            string `json:"value"`
	Gas              string `json:"gas"`
	GasPrice         string `json:"gasPrice"`
	Nonce            string `json:"nonce"`
	Input            string `json:"input"`
	BlockHash        string `json:"blockHash"`
	BlockNumber      string `json:"blockNumber"`
	TransactionIndex string `json:"transactionIndex"`
}

Transaction represents the structure of a transaction returned by eth_getTransactionByHash

type TxnSenderJob added in v0.7.0

type TxnSenderJob struct {
	Record RecordToBackfill
}

TxnSenderJob represents a job for extracting transaction sender

type TxnSenderResult added in v0.7.0

type TxnSenderResult struct {
	Update RecordUpdate
	Error  error
}

TxnSenderResult represents the result of extracting transaction sender

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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