types

type Address string

type BigIntString string

type BridgeResponse struct {
	// Block number where the bridge event was recorded
	BlockNum uint64 `json:"block_num" example:"1234"`

	// Position of the bridge event within the block
	BlockPos uint64 `json:"block_pos" example:"1"`

	// Address that initiated the transaction on bridge contract. It can be intermediary contract or EOA.
	// May be null if bridge was synced with SyncFromInBridges=false
	FromAddress *Address `json:"from_address,omitempty" example:"0xabc1234567890abcdef1234567890abcdef1234"`

	// Hash of the transaction that included the bridge event
	TxHash Hash `json:"tx_hash" example:"0xdef4567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"`

	// Global index of the bridge event (consisted of mainnet flag, rollup id and deposit count)
	GlobalIndex BigIntString `json:"global_index" example:"4294967296"`

	// Timestamp of the block containing the bridge event
	BlockTimestamp uint64 `json:"block_timestamp" example:"1684500000"`

	// Type of leaf (bridge event type) used in the tree structure
	LeafType uint8 `json:"leaf_type" example:"1"`

	// ID of the network where the bridge transaction originated
	OriginNetwork uint32 `json:"origin_network" example:"10"`

	// Address of the token sender on the origin network
	OriginAddress Address `json:"origin_address" example:"0xabc1234567890abcdef1234567890abcdef1234"`

	// ID of the network where the bridge transaction is destined
	DestinationNetwork uint32 `json:"destination_network" example:"42161"`

	// Address of the token receiver on the destination network
	DestinationAddress Address `json:"destination_address" example:"0xdef4567890abcdef1234567890abcdef12345678"`

	// Amount of tokens being bridged
	Amount BigIntString `json:"amount" example:"1000000000000000000"`

	// Optional metadata attached to the bridge event
	Metadata string `json:"metadata" example:"0xdeadbeef"`

	// Count of total deposits processed so far for the given token/address
	DepositCount uint32 `json:"deposit_count" example:"10"`

	// Unique hash representing the bridge event, often used as an identifier
	BridgeHash Hash `json:"bridge_hash" example:"0xabc1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd"`

	// Address of the transaction sender who initiated the bridge transaction
	TxnSender Address `json:"txn_sender" example:"0xabc1234567890abcdef1234567890abcdef12345"`

	// Address of the contract that was the recipient of the transaction. This may differ from the bridge contract address.
	ToAddress Address `json:"to_address" example:"0xF9D64d54D32EE2BDceAAbFA60C4C438E224427d0"`
}

type BridgesByContentResult struct {
	// List of bridges matching the content query
	Bridges []*BridgeResponse `json:"bridges"`

	// Total number of matching bridges
	Count int `json:"count" example:"2"`
}

type BridgesResult struct {
	// List of bridge events
	Bridges []*BridgeResponse `json:"bridges"`

	// Total number of bridge events
	Count int `json:"count" example:"42"`
}

type ClaimProof struct {
	// Merkle proof for the local exit root
	ProofLocalExitRoot Proof `json:"proof_local_exit_root" example:"[0x1, 0x2, 0x3...]"`

	// Merkle proof for the rollup exit root
	ProofRollupExitRoot Proof `json:"proof_rollup_exit_root" example:"[0x4, 0x5, 0x6...]"`

	// L1 info tree leaf data associated with the claim
	L1InfoTreeLeaf L1InfoTreeLeafResponse `json:"l1_info_tree_leaf"`
}

type ClaimResponse struct {
	// Block number where the claim was processed
	BlockNum uint64 `json:"block_num" example:"1234"`

	// Timestamp of the block containing the claim
	BlockTimestamp uint64 `json:"block_timestamp" example:"1684500000"`

	// Transaction hash associated with the claim
	TxHash Hash `json:"tx_hash" example:"0xdef4567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"`

	// Global index of the claim
	GlobalIndex BigIntString `json:"global_index" example:"1000000000000000000"`

	// Address initiating the claim on the origin network
	OriginAddress Address `json:"origin_address" example:"0xabc1234567890abcdef1234567890abcdef1234"`

	// Origin network ID where the claim was initiated
	OriginNetwork uint32 `json:"origin_network" example:"10"`

	// Address receiving the claim on the destination network
	DestinationAddress Address `json:"destination_address" example:"0xdef4567890abcdef1234567890abcdef12345678"`

	// Destination network ID where the claim was processed
	DestinationNetwork uint32 `json:"destination_network" example:"42161"`

	// Amount claimed
	Amount BigIntString `json:"amount" example:"1000000000000000000"`

	// Address from which the claim originated
	FromAddress Address `json:"from_address" example:"0xabc1234567890abcdef1234567890abcdef1234"`

	// Mainnet exit root associated with the claim
	MainnetExitRoot Hash `json:"mainnet_exit_root" example:"0x27ae5ba08d7291c96c8cbddcc148bf48a6d68c7974b94356f53754ef6171d757"` //nolint:lll

	// Rollup exit root associated with the claim
	RollupExitRoot Hash `json:"rollup_exit_root" example:"0x27ae5ba08d7291c96c8cbddcc148bf48a6d68c7974b94356f53754ef6171d757"` //nolint:lll

	// Global exit root associated with the claim
	GlobalExitRoot Hash `json:"global_exit_root" example:"0x27ae5ba08d7291c96c8cbddcc148bf48a6d68c7974b94356f53754ef6171d757"` //nolint:lll

	// Proof local exit root associated with the claim (optional)
	ProofLocalExitRoot *Proof `json:"proof_local_exit_root,omitempty" example:"[0x1, 0x2, 0x3...]"`

	// Proof rollup exit root associated with the claim (optional)
	ProofRollupExitRoot *Proof `json:"proof_rollup_exit_root,omitempty" example:"[0x4, 0x5, 0x6...]"`

	// Metadata associated with the claim
	Metadata string `json:"metadata" example:"0xdeadbeef"`

	// IsMessage indicates whether this is a message claim (leaf type 1) rather than an asset claim (leaf type 0)
	IsMessage bool `json:"is_message" example:"false"`
}

type ClaimsByGERResult struct {
	// List of claims matching the global exit root
	Claims []*ClaimResponse `json:"claims"`

	// Total number of matching claims
	Count int `json:"count" example:"3"`
}

type ClaimsResult struct {
	// List of claims matching the query
	Claims []*ClaimResponse `json:"claims"`

	// Total number of matching claims
	Count int `json:"count" example:"42"`
}

type ComponentHealth struct {
	IsActive bool `json:"is_active" example:"true"`

	// IsSynced is omitted for a component with no meaningful notion of "caught up" today
	// (e.g. l2gersync, which currently exposes no is_synced signal -- see docs/bridge_service.md).
	IsSynced *bool `json:"is_synced,omitempty" example:"true"`

	// IsHalted mirrors the matching /bridge/v1/sync-status entry's is_halted.
	IsHalted bool `json:"is_halted" example:"false"`

	// Error is set when this component's sync status could not be computed; same text as the
	// matching /bridge/v1/sync-status entry's error.
	Error string `json:"error,omitempty" example:"failed to get deposit count from L1 bridge contract: dial tcp: timeout"` //nolint:lll
}

type ErrorResponse struct {
	Error string `json:"error" example:"Error message"`
}

type Hash string

type HealthCheckDetails struct {
	L1         *ComponentHealth `json:"l1,omitempty"`
	L2         *ComponentHealth `json:"l2,omitempty"`
	L2GER      *ComponentHealth `json:"l2_ger,omitempty"`
	L1InfoTree *ComponentHealth `json:"l1_info_tree,omitempty"`
	ClaimL1    *ComponentHealth `json:"claim_l1,omitempty"`
	ClaimL2    *ComponentHealth `json:"claim_l2,omitempty"`
}

type HealthCheckResponse struct {
	Status  string    `json:"status"`
	Time    time.Time `json:"time"`
	Version string    `json:"version"`

	// SyncStatus summarizes bridge synchronization health as one of "done", "pending" or
	// "error". It never affects the HTTP status code of this endpoint (always 200) so that
	// liveness/routing probes never evict a healthy-but-lagging instance -- see
	// bridgeservicefinder/health.go and docs/bridge_service.md's health check section.
	SyncStatus HealthSyncStatus `json:"sync_status"`

	// Details gives a compact per-component breakdown backing SyncStatus. It intentionally
	// does not duplicate the full SyncStatus (deposit counts, block numbers) payload -- callers
	// wanting that detail should use GET /bridge/v1/sync-status.
	Details HealthCheckDetails `json:"details"`
}

type HealthSyncStatus string

type L1ContractsConfig struct {
	// GlobalExitRootAddr is the address of the GlobalExitRoot manager contract on L1
	GlobalExitRootAddr Address `json:"GlobalExitRootAddr" example:"0xabcdef1234567890abcdef1234567890abcdef12"`
	// RollupManagerAddr is the address of the RollupManager/AgglayerManager contract
	RollupManagerAddr Address `json:"RollupManagerAddr" example:"0xabcdef1234567890abcdef1234567890abcdef12"`
	// BridgeAddr is the address of the bridge smart contract on L1
	BridgeAddr Address `json:"BridgeAddr" example:"0xabcdef1234567890abcdef1234567890abcdef12"`
}

type L1InfoTreeLeafResponse struct {
	// Block number where the leaf was recorded
	BlockNumber uint64 `json:"block_num" example:"123456"`

	// Position of the leaf in the block (used for ordering)
	BlockPosition uint64 `json:"block_pos" example:"5"`

	// Index of this leaf in the L1 info tree
	L1InfoTreeIndex uint32 `json:"l1_info_tree_index" example:"42"`

	// Hash of the previous block in the tree
	PreviousBlockHash Hash `json:"previous_block_hash" example:"0xabc1...bcd"`

	// Timestamp of the block in seconds since the Unix epoch
	Timestamp uint64 `json:"timestamp" example:"1684500000"`

	// Mainnet exit root at this leaf
	MainnetExitRoot Hash `json:"mainnet_exit_root" example:"0xdefc...789"`

	// Rollup exit root at this leaf
	RollupExitRoot Hash `json:"rollup_exit_root" example:"0x7890...123"`

	// Global exit root computed from mainnet and rollup roots
	// @example "0x4567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef123"
	GlobalExitRoot Hash `json:"global_exit_root"`

	// Unique hash identifying this leaf node
	Hash Hash `json:"hash" example:"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"`

	// Block number on the destination (L2) network where this Global Exit Root was injected.
	// Only set by the injected-l1-info-leaf endpoint when network_id is the L2's own; nil for an
	// L1 (network_id=0) lookup, where BlockNumber above already is the relevant block.
	// Approximate (the current polling head, not necessarily the real injection block) for L2
	// chains synced by l2gersync in Legacy mode
	InjectedL2BlockNumber *uint64 `json:"injected_l2_block_num,omitempty" example:"654321"`

	// Timestamp of the L2 block above, in seconds since the Unix epoch. Only set alongside
	// InjectedL2BlockNumber; may briefly be nil for a row written before l2gersync persisted
	// timestamps if backfilling it from the L2 RPC failed (transient), in which case it resolves
	// on a later request. Always nil for L2 chains synced by l2gersync in Legacy mode, where
	// InjectedL2BlockNumber is only approximate and no accurate timestamp can be derived from it
	InjectedL2BlockTimestamp *uint64 `json:"injected_l2_block_timestamp,omitempty" example:"1684500123"`
}

type L2ContractsConfig struct {
	// GlobalExitRootAddr is the address of the GER smart contract on L2
	GlobalExitRootAddr Address `json:"GlobalExitRootAddr" example:"0xabcdef1234567890abcdef1234567890abcdef12"`
	// BridgeAddr is the address of the bridge smart contract on L2
	BridgeAddr Address `json:"BridgeAddr" example:"0xabcdef1234567890abcdef1234567890abcdef12"`
}

type L2GERSyncComponentConfig struct {
	SyncComponentConfig
	// SyncMode is the GER manager mode detected on L2 at startup: "Legacy" or "SovereignChain".
	// Not configuration — auto-detected by probing the L2 GER contract — but useful operational
	// information. Empty when this instance isn't running the L2GERSync component.
	SyncMode string `json:"sync_mode,omitempty" example:"SovereignChain"`
}

type L2GERSyncInfo struct {
	IsActive           bool   `json:"is_active" example:"true" description:"True if the l2gersync syncer is available"`                     //nolint:lll
	LastProcessedBlock uint64 `json:"last_processed_block,omitempty" example:"12345678" description:"Last L2 block processed by l2gersync"` //nolint:lll
	IsHalted           bool   `json:"is_halted" example:"false" description:"Always false: l2gersync has no halt state"`                    //nolint:lll
	Error              string ``                                                                                                            //nolint:lll
	/* 167-byte string literal not displayed */
}

type LegacyTokenMigrationResponse struct {
	// Block number where the migration occurred
	BlockNum uint64 `json:"block_num" example:"1234"`

	// Position of the transaction in the block
	BlockPos uint64 `json:"block_pos" example:"1"`

	// Timestamp of the block
	BlockTimestamp uint64 `json:"block_timestamp" example:"1684500000"`

	// Transaction hash of the migration event
	TxHash Hash `json:"tx_hash" example:"0xabc123..."`

	// Address of the sender initiating the migration
	Sender Address `json:"sender" example:"0xabc123..."`

	// Legacy token address being migrated
	LegacyTokenAddress Address `json:"legacy_token_address" example:"0xdef456..."`

	// New updated token address after migration
	UpdatedTokenAddress Address `json:"updated_token_address" example:"0xfeed789..."`

	// Amount of tokens migrated
	Amount BigIntString `json:"amount" example:"1000000000000000000"`
}

type LegacyTokenMigrationsResult struct {
	// List of legacy token migration events
	TokenMigrations []*LegacyTokenMigrationResponse `json:"legacy_token_migrations"`

	// Total number of legacy token migration events
	Count int `json:"count" example:"12"`
}

type NetworkSyncInfo struct {
	ContractDepositCount     uint32 `json:"contract_deposit_count" example:"676797" description:"Bridge deposits in contract"`     //nolint:lll
	SynchronizedDepositCount uint32 `json:"synchronized_deposit_count" example:"676797" description:"Bridge deposits in database"` //nolint:lll
	IsSynced                 bool   `json:"is_synced" example:"true" description:"True if counts match (sync up-to-date)"`
	IsActive                 bool   `json:"is_active" example:"true" description:"True if bridge syncer is running"`
	LastProcessedBlock       uint64 `json:"last_processed_block,omitempty" example:"12345678" description:"Last block processed"` //nolint:lll
	NetworkBlock             uint64 `json:"network_block,omitempty" example:"12350000" description:"Current latest block"`
	IsHalted                 bool   `json:"is_halted" example:"false" description:"True if the bridge syncer is configured but halted (e.g. resolving a reorg)"` //nolint:lll
	Error                    string ``                                                                                                                           //nolint:lll
	/* 177-byte string literal not displayed */
}

type Proof [tree.DefaultHeight]Hash

type PublicComponentsConfig struct {
	L1InfoTreeSync *SyncComponentConfig      `json:"L1InfoTreeSync,omitempty"`
	BridgeL1Sync   *SyncComponentConfig      `json:"BridgeL1Sync,omitempty"`
	BridgeL2Sync   *SyncComponentConfig      `json:"BridgeL2Sync,omitempty"`
	L2GERSync      *L2GERSyncComponentConfig `json:"L2GERSync,omitempty"`
}

type PublicConfigResponse struct {
	// NetworkID is the rollup/network ID this bridge service instance's bridge/claim syncers are
	// listening on (the destination network for L2, mainnet=0 for L1).
	NetworkID uint32 `json:"network_id" example:"10"`
	// Components holds the public parameters of each syncer component
	Components PublicComponentsConfig `json:"components"`
	// Contracts holds the smart contract addresses used by this instance, deduplicated by network
	Contracts PublicContractsConfig `json:"contracts"`
	// InternalConfigChecksum is a hex-encoded FNV-1a checksum of this instance's fully-resolved
	// configuration (public and private). It changes whenever any configuration value changes,
	// even one that isn't exposed on this endpoint. Not cryptographically secure — just a fast
	// fingerprint to detect incidental change, never to detect tampering.
	InternalConfigChecksum string `json:"internal_config_checksum" example:"af63bd4c8601b7df"`
	// PublicConfigChecksum is a hex-encoded FNV-1a checksum of only the fields published in this
	// response (NetworkID, Components, Contracts). Lets a caller (e.g. a proxy) detect when the
	// public-facing configuration it depends on has changed, without reacting to unrelated internal
	// configuration changes that also move InternalConfigChecksum.
	PublicConfigChecksum string `json:"public_config_checksum" example:"af63bd4c8601b7df"`
}

type PublicContractsConfig struct {
	L1 L1ContractsConfig `json:"L1"`
	L2 L2ContractsConfig `json:"L2"`
}

type RemoveGEREventResponse struct {
	// Global Exit Root hash that was removed
	GlobalExitRoot Hash `json:"global_exit_root" example:"0x27ae5ba08d7291c96c8cbddcc148bf48a6d68c7974b94356f53754ef6171d757"` //nolint:lll

	// Block number where the GER was removed
	BlockNum uint64 `json:"block_num" example:"1234"`

	// Position of the event within the block
	BlockPos uint64 `json:"block_pos" example:"0"`

	// Timestamp when the remove event was recorded in database
	CreatedAt uint64 `json:"created_at" example:"1684500000"`
}

type RemoveGEREventsResult struct {
	// List of remove GER events
	RemoveGEREvents []*RemoveGEREventResponse `json:"remove_ger_events"`

	// Total number of remove GER events
	Count int `json:"count" example:"10"`
}

type RootByLERResponse struct {
	// Index is the deposit count at which this root became the local exit root (0-based)
	Index uint32 `json:"index" example:"42"`

	// BlockNum is the block in which the leaf that produced this root was added
	BlockNum uint64 `json:"block_num" example:"123456"`

	// BlockPosition orders same-block roots (multiple deposits in one block)
	BlockPosition uint64 `json:"block_position" example:"0"`
}

type SetClaimResponse struct {
	// Block number where the set claim was processed
	BlockNum uint64 `json:"block_num" example:"1234"`

	// Position of the set claim event within the block
	BlockPos uint64 `json:"block_pos" example:"2"`

	// Transaction hash associated with the set claim
	TxHash Hash `json:"tx_hash" example:"0xdef4567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"`

	// Global index of the claim that was set
	GlobalIndex BigIntString `json:"global_index" example:"1000000000000000000"`

	// Timestamp when the set claim was created
	CreatedAt uint64 `json:"created_at" example:"1684500000"`
}

type SetClaimsResult struct {
	// List of set claim events
	SetClaims []*SetClaimResponse `json:"set_claims"`

	// Total number of set claim events
	Count int `json:"count" example:"20"`
}

type SettlementResponse struct {
	// L1 transaction that settled this certificate. Omitted for settlements synced before this
	// field was tracked (#1817); it is never backfilled for those.
	TxHash *Hash `json:"tx_hash,omitempty" example:"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd"` //nolint:lll

	// Local exit root this settlement produced.
	NewLocalExitRoot Hash `json:"new_local_exit_root" example:"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678"` //nolint:lll

	// L1 block this settlement was mined in.
	BlockNumber uint64 `json:"block_number" example:"123456"`

	// L1 block's timestamp, in seconds since the Unix epoch. Omitted for the same reason as
	// TxHash.
	BlockTimestamp *uint64 `json:"block_timestamp,omitempty" example:"1684500000"`

	// L1 block's hash, when available (nil if the block table has no recorded hash for it).
	BlockHash *Hash `json:"block_hash,omitempty" example:"0xabc1234567890abcdef1234567890abcdef1234567890abcdef1234567890a"` //nolint:lll
}

type SettlementsResult struct {
	// List of settlements, most recent first
	Settlements []*SettlementResponse `json:"settlements"`

	// Total number of settlements for this network
	Count int `json:"count" example:"10"`
}

type SyncComponentConfig struct {
	// BlockFinality is the block finality used by this syncer when querying the chain
	BlockFinality string `json:"block_finality" example:"FinalizedBlock"`
	// InitialBlock is the first block that was queried when starting the sync from scratch
	InitialBlock uint64 `json:"initial_block" example:"12345"`
	// SyncBlockChunkSize is the amount of blocks queried per request
	SyncBlockChunkSize uint64 `json:"sync_block_chunk_size" example:"100"`
}

type SyncStatus struct {
	L1Info         *NetworkSyncInfo `json:"l1_info" description:"L1 network bridge sync status"`
	L2Info         *NetworkSyncInfo `json:"l2_info" description:"L2 network bridge sync status"`
	L2GERInfo      *L2GERSyncInfo   `json:"l2_ger_info,omitempty" description:"l2gersync (injected-GER) sync status"`
	L1InfoTreeInfo *SyncerSyncInfo  `json:"l1_info_tree_info,omitempty" description:"l1infotreesync sync status"`
	ClaimL1Info    *SyncerSyncInfo  `json:"claim_l1_info,omitempty" description:"L1 claimsync sync status"`
	ClaimL2Info    *SyncerSyncInfo  `json:"claim_l2_info,omitempty" description:"L2 claimsync sync status"`
}

type SyncerSyncInfo struct {
	IsActive           bool   `json:"is_active" example:"true" description:"True if the syncer is running and not halted"`                        //nolint:lll
	IsHalted           bool   `json:"is_halted" example:"false" description:"True if the syncer is halted (always false for claimsync)"`          //nolint:lll
	LastProcessedBlock uint64 `json:"last_processed_block,omitempty" example:"12345678" description:"Last block processed (omitted if none yet)"` //nolint:lll
	Error              string ``                                                                                                                  //nolint:lll
	/* 170-byte string literal not displayed */
}

type TokenMappingResponse struct {
	// Block number where the token mapping was recorded
	BlockNum uint64 `json:"block_num" example:"123456"`

	// Position of the mapping event within the block
	BlockPos uint64 `json:"block_pos" example:"2"`

	// Timestamp of the block containing the mapping event
	BlockTimestamp uint64 `json:"block_timestamp" example:"1684501234"`

	// Transaction hash associated with the mapping event
	TxHash Hash `json:"tx_hash" example:"0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd"`

	// ID of the origin network where the original token resides
	OriginNetwork uint32 `json:"origin_network" example:"1"`

	// Address of the token on the origin network
	OriginTokenAddress Address `json:"origin_token_address" example:"0x1234567890abcdef1234567890abcdef12345678"`

	// Address of the wrapped token on the destination network
	WrappedTokenAddress Address `json:"wrapped_token_address" example:"0xabcdef1234567890abcdef1234567890abcdef12"`

	// Optional metadata associated with the token mapping
	Metadata string `json:"metadata" example:"0xdeadbeef"`

	// Indicates whether the wrapped token is not mintable (true = not mintable)
	IsNotMintable bool `json:"is_not_mintable" example:"false"`

	// Type of the token mapping: 0 = WrappedToken, 1 = SovereignToken
	Type TokenMappingType `json:"token_type" example:"0"`
}

type TokenMappingType uint8

type TokenMappingsResult struct {
	// List of token mapping entries
	TokenMappings []*TokenMappingResponse `json:"token_mappings"`

	// Total number of token mapping records
	Count int `json:"count" example:"27"`
}

type UnsetClaimResponse struct {
	// Block number where the unset claim was processed
	BlockNum uint64 `json:"block_num" example:"1234"`

	// Position of the unset claim event within the block
	BlockPos uint64 `json:"block_pos" example:"2"`

	// Transaction hash associated with the unset claim
	TxHash Hash `json:"tx_hash" example:"0xdef4567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"`

	// Global index of the claim that was unset
	GlobalIndex BigIntString `json:"global_index" example:"1000000000000000000"`

	// Hash chain value for unset global indexes
	UnsetGlobalIndexHashChain Hash `json:"unset_global_index_hash_chain" example:"0x1234567890abcdef"`

	// Timestamp when the unset claim was created
	CreatedAt uint64 `json:"created_at" example:"1684500000"`
}

type UnsetClaimsResult struct {
	// List of unset claim events
	UnsetClaims []*UnsetClaimResponse `json:"unset_claims"`

	// Total number of unset claim events
	Count int `json:"count" example:"15"`
}