types

package
v0.11.0-rc8 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: Apache-2.0, MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// WSTypeStatus is a TrackingData snapshot (initial or on every change); its BridgeStatus
	// field is nil until the tracker resolves the bridge
	WSTypeStatus = "status"
	// WSTypeError is an ErrorData sent only for invalid request parameters (bad network_id/
	// tx_hash); the server closes the connection after sending it. Once a bridge is
	// registered, every outcome — including giving up trying to resolve it — is a
	// WSTypeStatus message instead (see TrackingData.Error)
	WSTypeError = "error"
)

WebSocket message types carried in the WSMessage envelope

View Source 
const HealthStatusOK = "ok"

HealthStatusOK is the value of HealthResponse.Status: the endpoint always returns 200, so the status is always "ok"

Variables

This section is empty.

Functions

This section is empty.

Types

type ActivityFilter 

type ActivityFilter int

ActivityFilter selects which bridges GetActivity (see domain.ActivityQuerier) returns for a from_address, based on ClaimStatus, and doubles as a hint to skip fetching data the caller does not want: requesting ActivityFilterPending or ActivityFilterError skips the destination bridge service's claim record for a bridge found to be claimed, since it would be filtered out of the result anyway — that bridge's cache entry simply stays unsettled and is fetched normally the next time a filter that needs it is used (see bridgetracker.ActivityCache.refresh) 

const (
	// ActivityFilterAll returns every bridge found, regardless of claim state (the default)
	ActivityFilterAll ActivityFilter = iota
	// ActivityFilterClaimed returns only bridges confirmed claimed
	ActivityFilterClaimed
	// ActivityFilterPending returns only bridges confirmed still unclaimed (ClaimStatusUnclaimed)
	// — a bridge whose claim state could not be checked is not "pending", see ActivityFilterError
	ActivityFilterPending
	// ActivityFilterError returns only bridges whose isClaimed() check itself failed
	// (ClaimStatusError): their claim state is unknown, neither claimed nor confirmed pending
	ActivityFilterError
)

func ParseActivityFilter 

func ParseActivityFilter(s string) (ActivityFilter, error)

ParseActivityFilter parses the filterBridges query parameter: "" (unset) and "all" both mean ActivityFilterAll. Returns an error for any other value.

func (ActivityFilter) String 

func (f ActivityFilter) String() string

String representation of the enum: "all", "claimed", "pending" or "error"

type BridgeLeafType 

type BridgeLeafType int

BridgeLeafType identifies the kind of leaf the bridge created (asset or message) 

const (
	// BridgeLeafTypeAsset the bridge was created with bridgeAsset (leaf_type=0)
	BridgeLeafTypeAsset BridgeLeafType = iota
	// BridgeLeafTypeMessage the bridge was created with bridgeMessage (leaf_type=1)
	BridgeLeafTypeMessage
)

func (BridgeLeafType) String 

func (b BridgeLeafType) String() string

String representation of the enum

type BridgeRequest 

type BridgeRequest struct {
	// NetworkID is the network where the bridge transaction was sent (0 -> Mainnet)
	NetworkID uint32 `json:"network_id"`
	// TxHash is the hash of the transaction that created the bridge (bridgeAsset)
	TxHash common.Hash `json:"tx_hash"`
}

BridgeRequest is the request of GET /tracker/v1/network/{network_id}/tx/{tx_hash}. Both values come from the URL path, so they are mandatory

type BridgeStep 

type BridgeStep int

BridgeStep identifies each step a bridge goes through, from its creation with bridgeAsset until it is claimed on the destination network 

const (
	// StepWaitingGERUpdate the bridge has been created (BridgeEvent emitted) on an L1
	// origin, but the Global Exit Root has not been updated yet (e.g.
	// forceUpdateGlobalExitRoot=false)
	StepWaitingGERUpdate BridgeStep = iota
	// StepWaitingLERUpdate the bridge has been created (BridgeEvent emitted) on an L2
	// origin, but its Local Exit Root has not been updated yet
	StepWaitingLERUpdate
	// StepPendingInclusion the bridge is not yet part of any certificate
	StepPendingInclusion
	// StepCertificatePending the bridge is included in a certificate sent to the Agglayer;
	// covers every status the certificate goes through (Pending, Proven, Candidate, InError)
	// until it settles — those intermediate statuses do not change the step, only the
	// certificate data carried in its Result (see BridgeStepPath.Result)
	StepCertificatePending
	// StepWaitL1SettledGER the certificate has settled, but its settlement tx has not been
	// confirmed on L1 yet: the tracker waits for that tx to reach the configured L1 finality
	// and its receipt to carry both VerifyBatchesTrustedAggregator and UpdateL1InfoTree
	// (UpdateL1InfoTreeV2 is captured too, if present, but is not required). Only reached by
	// L2-originated bridges (L2->L1 and L2->L2), right after StepCertificatePending
	StepWaitL1SettledGER
	// StepWaitingGERInjection the certificate is settled but the Global Exit Root has
	// not been injected on the destination network yet
	StepWaitingGERInjection
	// StepWaitingClaim the Global Exit Root that includes the bridge has been injected
	// on the destination network, so the bridge is ready to be claimed
	StepWaitingClaim
	// StepClaimed the bridge has been claimed on the destination network
	StepClaimed
)

func (BridgeStep) String 

func (s BridgeStep) String() string

String representation of the enum

type BridgeType 

type BridgeType int

BridgeType identifies the direction of a bridge 

const (
	// BridgeTypeL1ToL2 is a bridge from mainnet to a rollup
	BridgeTypeL1ToL2 BridgeType = iota
	// BridgeTypeL2ToL1 is a bridge from a rollup to mainnet
	BridgeTypeL2ToL1
	// BridgeTypeL2ToL2 is a bridge between two rollups
	BridgeTypeL2ToL2
)

func (BridgeType) String 

func (b BridgeType) String() string

String representation of the enum

type CertificateData 

type CertificateData struct {
	CertificateID common.Hash                     `json:"certificate_id"`
	Status        agglayertypes.CertificateStatus `json:"status"`
	// StatusString is the string representation of Status, auto-populated on JSON marshaling
	StatusString string `json:"status_string"`
	// Error is only set if the certificate carries an error message (relevant for InError certs)
	Error            string       `json:"error,omitempty"`
	SettlementTxHash *common.Hash `json:"settlement_tx_hash,omitempty"`
	// BlockNumber/BlockTimestamp locate SettlementTxHash on L1, once its receipt is visible
	// there. Only ever set once Status.IsSettled(): even then, both stay nil for a transient
	// tick (the settlement tx's own receipt can lag a step behind the certificate turning
	// Settled — see CertificatePendingResolver), so nil is not necessarily permanent
	BlockNumber    *uint64 `json:"block_number,omitempty"`
	BlockTimestamp *uint64 `json:"block_timestamp,omitempty"`
}

CertificateData holds the Agglayer certificate information related to a bridge

func (CertificateData) MarshalJSON 

func (c CertificateData) MarshalJSON() ([]byte, error)

MarshalJSON is the implementation of the json.Marshaler interface. It populates the string representation of the numeric enum fields

type CertificateInclusionData 

type CertificateInclusionData struct {
	CertificateData
	// PreviousLocalExitRoot is the LER right before this certificate, nil for a network's first
	// certificate
	PreviousLocalExitRoot *common.Hash
	// NewLocalExitRoot is the LER this certificate advances to, the one that covers the bridge
	NewLocalExitRoot common.Hash
}

CertificateInclusionData is the data CertificateSource.CertificateFor resolves for the certificate that covers (or may come to cover) a bridge: its status (CertificateData, also StepCertificatePending's own Result type) plus the LER transition it produced, which only PendingInclusionResolver needs

type ClaimResult 

type ClaimResult struct {
	ClaimTx        common.Hash `json:"claim_tx"`
	BlockNumber    uint64      `json:"block_number"`
	BlockTimestamp uint64      `json:"block_timestamp"`
}

ClaimResult is the result of StepClaimed once it completes: the claim transaction on the destination network and the block it was mined in

type ClaimStatus 

type ClaimStatus int

ClaimStatus is the tri-state result of checking a bridge's on-chain claim state (see domain.ActivityEntry / the GET /activity/from/{from_address} endpoint): unlike a plain bool, it distinguishes "confirmed unclaimed" from "the check itself failed" (e.g. no bridge contract address configured for the destination network, or an RPC failure) — a caller must not read ClaimStatusError as "not claimed". 

const (
	// ClaimStatusUnclaimed the destination bridge contract's isClaimed() call succeeded and
	// reported the bridge as not yet claimed
	ClaimStatusUnclaimed ClaimStatus = iota
	// ClaimStatusClaimed the destination bridge contract's isClaimed() call succeeded and
	// reported the bridge as claimed
	ClaimStatusClaimed
	// ClaimStatusError the isClaimed() check itself failed; the claim state is unknown and
	// will be retried on the next call
	ClaimStatusError
)

func (ClaimStatus) String 

func (s ClaimStatus) String() string

String representation of the enum: "false", "true" or "error"

type Duration 

type Duration struct {
	time.Duration
}

Duration is a time.Duration that marshals to/from a human-readable string (e.g. "5m0s") instead of nanoseconds

func NewDuration 

func NewDuration(d time.Duration) *Duration

NewDuration returns a Duration wrapper

func (Duration) MarshalJSON 

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON is the implementation of the json.Marshaler interface

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON is the implementation of the json.Unmarshaler interface

type ErrorData 

type ErrorData struct {
	// Code is an HTTP-like error code (e.g. 400 invalid params, 404 bridge tx not found)
	Code int `json:"code"`
	// Message is a human-readable description of the error
	Message string `json:"message"`
}

ErrorData is the error structure shared by the REST error responses and the WebSocket "error" messages

type ErrorStep 

type ErrorStep struct {
	ErrorType StepErrorType `json:"error_type"`
	// ErrorTypeString is the string representation of ErrorType, auto-populated on JSON marshaling
	ErrorTypeString string `json:"error_type_string"`
	// RetryCount is the number of retries attempted so far for this step
	RetryCount int `json:"retry_count"`
	// Description holds the human-readable description of the error; one entry per occurrence
	Description []string `json:"description"`
}

ErrorStep carries the details of a step that is in StepStatusError

func (ErrorStep) MarshalJSON 

func (e ErrorStep) MarshalJSON() ([]byte, error)

MarshalJSON is the implementation of the json.Marshaler interface. It populates the string representation of the numeric enum fields

type GERData 

type GERData struct {
	// NetworkID is the network the GER belongs to (0 -> Mainnet)
	NetworkID uint32 `json:"network_id"`
	// GER is the Global Exit Root
	GER *common.Hash `json:"ger,omitempty"`
	// MER is the Mainnet Exit Root
	MER *common.Hash `json:"mer,omitempty"`
	// RER is the Rollup Exit Root
	RER *common.Hash `json:"rer,omitempty"`
	// LER is the Local Exit Root
	LER *common.Hash `json:"ler,omitempty"`
	// LERType identifies which exit tree the LER belongs to
	LERType LERType `json:"ler_type"`
	// LERTypeString is the string representation of LERType, auto-populated on JSON marshaling
	LERTypeString string `json:"ler_type_string"`
	// BlockNumber is the block where the GER update happened. Populated when resolving the
	// origin GER of an L1-originated bridge, and the GER injected on a bridge's destination
	// network (see StepWaitingGERInjection's InjectedGERResult, which carries it on the wire).
	// Internal only otherwise: GERData is not serialized on any tracker response, it is the
	// domain layer's currency to decide GER coverage
	BlockNumber *uint64 `json:"-"`
	// BlockTimestamp is BlockNumber's block timestamp. Populated (and carried on the wire) under
	// the same conditions as BlockNumber
	BlockTimestamp *uint64 `json:"-"`
	// L2BlockNumber/L2BlockTimestamp are the actual L2 block/timestamp the GER was injected at on
	// the destination network. Only set by InjectedGERAtIndex, and only when the destination's
	// bridge-service instance reports it (see bridgeservice/types.L1InfoTreeLeafResponse's
	// InjectedL2BlockNumber/InjectedL2BlockTimestamp). Unlike BlockNumber/BlockTimestamp above —
	// always the L1 event, even here — these stay nil while unknown instead of being backfilled
	// with the L1 block, which is exactly the #1818 bug this pair exists to avoid repeating
	L2BlockNumber *uint64 `json:"-"`
	// L2BlockTimestamp is L2BlockNumber's timestamp; may lag L2BlockNumber briefly if resolving
	// it from the L2 RPC failed (see l2gersync.L2GERSync.GetFirstGERAfterL1InfoTreeIndex)
	L2BlockTimestamp *uint64 `json:"-"`
}

GERData holds the exit roots of a Global Exit Root update relevant to a bridge

func (GERData) MarshalJSON 

func (g GERData) MarshalJSON() ([]byte, error)

MarshalJSON is the implementation of the json.Marshaler interface. It populates the string representation of the numeric enum fields

type GERUpdateResult 

type GERUpdateResult struct {
	// L1InfoTreeIndex is the leaf index the update landed at, resolved from the contract's own
	// leaf count (1-based) as of the update's block: index = count - 1
	L1InfoTreeIndex uint32      `json:"l1_info_tree_index"`
	GER             common.Hash `json:"ger"`
	MainnetExitRoot common.Hash `json:"mer"`
	RollupExitRoot  common.Hash `json:"rer"`
	BlockNumber     uint64      `json:"block_number"`
	BlockTimestamp  uint64      `json:"block_timestamp"`
	LogIndex        uint        `json:"log_index"`
}

GERUpdateResult is the result of StepWaitingGERUpdate once it completes: the GER produced by the update on the origin network (L1) and the block it was updated in

type HealthResponse 

type HealthResponse struct {
	// Status is always "ok"
	Status string `json:"status"`
	// InstanceID is a UUID generated at startup; it changes on every execution, so two
	// responses with different InstanceID come from different instances (or the same
	// instance after a restart)
	InstanceID string `json:"instance_id"`
	// ConfigSHA1 is the sha1sum (hex) of the configuration the instance was started with;
	// it allows checking that all instances behind a proxy run the same configuration
	ConfigSHA1 string `json:"config_sha1"`
	// Version is the build/version information of the running instance
	Version VersionInfo `json:"version"`
}

HealthResponse is the body of GET /tracker/v1/health

type InjectedGERL1Leaf 

type InjectedGERL1Leaf struct {
	GER            common.Hash `json:"ger"`
	BlockNumber    uint64      `json:"block_number"`
	BlockTimestamp uint64      `json:"block_timestamp"`
}

InjectedGERL1Leaf is the L1 Info Tree leaf covering the bridge: its GER and the L1 block/ timestamp of the UpdateL1InfoTree/UpdateL1InfoTreeV2 event that produced it

type InjectedGERResult 

type InjectedGERResult struct {
	L1InfoTreeLeaf InjectedGERL1Leaf   `json:"l1_info_tree_leaf"`
	L2InjectedGER  *InjectedL2GERBlock `json:"l2_injected_ger,omitempty"`
}

InjectedGERResult is the result of StepWaitingGERInjection once it completes: the GER covering the bridge, resolved to its L1 Info Tree leaf (L1InfoTreeLeaf, always known once the step completes) and, once actually injected on the destination network, that injection's own L2 block/timestamp (L2InjectedGER). L2InjectedGER is nil when the destination's bridge-service instance does not report it yet (predates injected_l2_block_num/injected_l2_block_timestamp on GET /bridge/v1/injected-l1-info-leaf, see bridgeservice/types.L1InfoTreeLeafResponse) — in that case L1InfoTreeLeaf's own BlockNumber/BlockTimestamp are the L1 event that produced the leaf, not the L2 injection block, and must not be mistaken for it (this conflation was #1818)

type InjectedL2GERBlock 

type InjectedL2GERBlock struct {
	BlockNumber    uint64  `json:"block_number"`
	BlockTimestamp *uint64 `json:"block_timestamp,omitempty"`
}

InjectedL2GERBlock is the L2 block the GER was actually injected at on the destination network. BlockTimestamp is only known once resolved from the destination's L2 RPC (see l2gersync.L2GERSync.GetFirstGERAfterL1InfoTreeIndex), so it may briefly be absent right after upgrading a bridge-service instance that only just started reporting BlockNumber, resolving on a later request

type L1SettledGERResult 

type L1SettledGERResult struct {
	TxHash                            common.Hash `json:"tx_hash"`
	SettlementBlockNumber             uint64      `json:"settlement_block_number"`
	SettlementBlockTimestamp          uint64      `json:"settlement_block_timestamp"`
	SettlementLogIndex                uint        `json:"settlement_log_index"`
	GER                               common.Hash `json:"ger"`
	GERBlockNumber                    uint64      `json:"ger_block_number"`
	GERBlockTimestamp                 uint64      `json:"ger_block_timestamp"`
	GERLogIndex                       uint        `json:"ger_log_index"`
	L1InfoTreeIndex                   *uint32     `json:"l1_info_tree_index,omitempty"`
	HasVerifyBatchesTrustedAggregator bool        `json:"has_verify_batches_trusted_aggregator"`
	HasUpdateL1InfoTree               bool        `json:"has_update_l1_info_tree"`
	HasUpdateL1InfoTreeV2             bool        `json:"has_update_l1_info_tree_v2"`
}

L1SettledGERResult is the result of StepWaitL1SettledGER once it completes: the evidence, read off the certificate's settlement tx receipt on L1, that the settlement propagated to the L1 Global Exit Root. HasVerifyBatchesTrustedAggregator and HasUpdateL1InfoTree are both required for the step to complete; HasUpdateL1InfoTreeV2 is only informational. SettlementBlockNumber/SettlementBlockTimestamp/SettlementLogIndex locate the settlement tx's own VerifyBatchesTrustedAggregator log — the event that confirms this tx is a genuine certificate settlement. GER is the Global Exit Root produced by the settlement (computed from UpdateL1InfoTree's mainnet/rollup exit roots), used by StepWaitingGERInjection to check whether it has reached the destination. GERBlockNumber/GERBlockTimestamp/GERLogIndex locate the UpdateL1InfoTree event GER was computed from: normally the same block as the settlement (HasUpdateL1InfoTree true), but when the settlement tx's own receipt does not carry the event (the settlement did not move the GER itself), they instead point to the closest earlier one on L1 (see sources.SettlementSource.findEventUpdateL1InfoTreeBackwards), whose GER is still the one this settlement propagated. L1InfoTreeIndex is the leaf index GER landed at: populated straight from UpdateL1InfoTreeV2's LeafCount when that (optional) event fires, otherwise resolved by the step itself with one extra lookup (GER -> leaf) before it can complete — either way, by the time this step is Done, L1InfoTreeIndex is never nil

type LERType 

type LERType int

LERType identifies which exit tree the Local Exit Root belongs to 

const (
	// LERTypeNA the Local Exit Root is not available / not applicable
	LERTypeNA LERType = iota
	// LERTypeMainnet the Local Exit Root belongs to the mainnet exit tree
	LERTypeMainnet
	// LERTypeLocal the Local Exit Root belongs to a rollup local exit tree
	LERTypeLocal
)

func (LERType) String 

func (l LERType) String() string

String representation of the enum

type LERUpdateResult 

type LERUpdateResult struct {
	NetworkID   uint32      `json:"network_id"`
	LER         common.Hash `json:"ler"`
	BlockNumber uint64      `json:"block_number"`
}

LERUpdateResult is the result of StepWaitingLERUpdate once it completes: the LER produced by the update on the origin L2 network and the block it was updated in

type PendingInclusionResult 

type PendingInclusionResult struct {
	CertificateID common.Hash  `json:"certificate_id"`
	NewLER        common.Hash  `json:"new_ler"`
	PreviousLER   *common.Hash `json:"previous_ler,omitempty"`
}

PendingInclusionResult is the result of StepPendingInclusion once it completes: the certificate that first includes the bridge and the LER transition it produced

type StepErrorType 

type StepErrorType int

StepErrorType classifies a step error by whether it is expected to clear on retry 

const (
	// StepErrorTransient the error is expected to be resolved by retrying the step
	StepErrorTransient StepErrorType = iota
	// StepErrorPermanent the error will not resolve by retrying and requires intervention
	StepErrorPermanent
	// StepErrorExhausted the error was transient but retries have been given up on
	StepErrorExhausted
)

func (StepErrorType) String 

func (e StepErrorType) String() string

String representation of the enum

type StepStatus 

type StepStatus int

StepStatus is the status of a single step within the bridge path 

const (
	// StepStatusPending the step has not started yet
	StepStatusPending StepStatus = iota
	// StepStatusInProgress the step is the one currently in progress
	StepStatusInProgress
	// StepStatusDone the step has been completed
	StepStatusDone
	// StepStatusError the step failed; details are carried in BridgeStepPath.Error
	StepStatusError
)

func (StepStatus) String 

func (s StepStatus) String() string

String representation of the enum

type TrackingStatus 

type TrackingStatus int

TrackingStatus is the full lifecycle of a supervised bridge, from registration to settlement: Registered while BridgeStatus is still nil, then Running/Error/Finished from the same signal TrackingData.StepIndex points at once it resolves (see the TrackingData envelope in bridgetracker/api, the only package that constructs it) 

const (
	// TrackingStatusRegistered the bridge has been added to the supervised list but the
	// tracker has no information about it yet (BridgeStatus is nil)
	TrackingStatusRegistered TrackingStatus = iota
	// TrackingStatusRunning the bridge is resolved and alive: still being polled/updated
	TrackingStatusRunning
	// TrackingStatusError the bridge is resolved and stopped: one of its steps reached an error
	TrackingStatusError
	// TrackingStatusFinished the bridge is resolved and reached its terminal step (Claimed)
	TrackingStatusFinished
)

func (TrackingStatus) String 

func (t TrackingStatus) String() string

String representation of the enum

type VersionInfo 

type VersionInfo struct {
	// Version is the semantic version (e.g. "v0.1.0")
	Version string `json:"version"`
	// GitRev is the git revision the binary was built from
	GitRev string `json:"git_rev"`
	// GitBranch is the git branch the binary was built from
	GitBranch string `json:"git_branch"`
	// BuildDate is the build timestamp
	BuildDate string `json:"build_date"`
	// GoVersion is the Go runtime version (e.g. "go1.24.0")
	GoVersion string `json:"go_version"`
	// OS is the target operating system (e.g. "linux")
	OS string `json:"os"`
	// Arch is the target architecture (e.g. "amd64")
	Arch string `json:"arch"`
}

VersionInfo is the build/version information of the running instance, populated from aggkit.GetVersion()

func NewVersionInfo 

func NewVersionInfo() VersionInfo

NewVersionInfo builds a VersionInfo from the build-time version data

type WSMessage 

type WSMessage struct {
	// Type is one of WSTypeStatus or WSTypeError
	Type string `json:"type"`
	// Data is a TrackingData for "status" and an ErrorData for "error"
	Data any `json:"data"`
}

WSMessage is the envelope of every message the WebSocket endpoint sends

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.