common

type ChainClient interface {
	// Start initializes and starts the chain client
	Start(ctx context.Context) error

	// Stop gracefully shuts down the chain client
	Stop() error

	// IsHealthy checks if the chain client is operational
	IsHealthy() bool

	// GetTxBuilder returns the TxBuilder for this chain
	// Returns an error if txBuilder is not supported for this chain (e.g., Push chain)
	GetTxBuilder() (TxBuilder, error)

	// GetReadRequestHandler returns the handler executing read requests
	// destined for this chain
	// Returns an error if reads are not available (e.g. client not started)
	GetReadRequestHandler() (ReadRequestHandler, error)
}

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

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

type EventHandler interface {
	HandleEvent(ctx context.Context, event *store.Event) error
}

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

type FundMigrationData struct {
	From     string   // Old TSS address (derived from old pubkey)
	To       string   // New TSS address (derived from current pubkey)
	GasPrice *big.Int // Gas price from the migration event
	GasLimit uint64   // Gas limit from the migration event
	L1GasFee *big.Int // Extra L1 data-availability fee (wei); 0 for non-L2 chains

	Balance *big.Int // if nil, builder queries chain
}

type InboundObservation struct {
	SourceChain         string `json:"sourceChain"`
	LogIndex            uint   `json:"logIndex"`
	Sender              string `json:"sender"`
	Recipient           string `json:"recipient"`
	Token               string `json:"bridgeToken"`
	Amount              string `json:"bridgeAmount"`         // uint256 as decimal string
	RawPayload          string `json:"rawPayload,omitempty"` // hex-encoded raw payload bytes from source chain
	VerificationData    string `json:"verificationData"`
	RevertFundRecipient string `json:"revertFundRecipient,omitempty"`
	TxType              uint   `json:"txType"`  // enum backing uint as decimal string
	FromCEA             bool   `json:"fromCEA"` // true if inbound is initiated by a CEA
}

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

type OutboundObservation struct {
	TxID          string `json:"tx_id"`                  // bytes32 hex-encoded (0x...)
	UniversalTxID string `json:"universal_tx_id"`        // bytes32 hex-encoded (0x...)
	GasFeeUsed    string `json:"gas_fee_used,omitempty"` // gas fee used in wei (decimal string)
	// PC20 export only: wrapper token address deployed/minted on the destination
	// at settlement (observed in the finalize event). Core uses it to flip the
	// PC20 deploy flag; empty for non-PC20 settlements.
	Pc20WrapperAddress string `json:"pc20_wrapper_address,omitempty"`
}

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

type ReadRequestHandler interface {
	ExecuteRead(ctx context.Context, req *ucallbacktypes.ReadRequest) (*ucallbacktypes.ReadResult, error)
}

type TxBuilder interface {
	// GetOutboundSigningRequest creates a signing request from outbound event data
	GetOutboundSigningRequest(ctx context.Context, data *uetypes.OutboundCreatedEvent, nonce uint64) (*UnsignedSigningReq, error)

	// GetNextNonce returns the next nonce for the given signer on this chain (for seeding local nonce).
	// useFinalized: for EVM, if true use finalized block nonce (aggressive/replace stuck); if false use pending. SVM ignores this.
	GetNextNonce(ctx context.Context, signerAddress string, useFinalized bool) (uint64, error)

	// BroadcastOutboundSigningRequest assembles and broadcasts a signed transaction from the signing request, event data, and signature
	BroadcastOutboundSigningRequest(ctx context.Context, req *UnsignedSigningReq, data *uetypes.OutboundCreatedEvent, signature []byte) (string, error)

	// VerifyBroadcastedTx checks the status of a broadcasted transaction on the destination chain.
	// Returns (found, blockHeight, confirmations, status, error):
	// - found=false: tx not found or not yet mined
	// - found=true: tx exists on-chain
	//   - blockHeight: the block in which the tx was mined
	//   - confirmations: number of blocks since the tx was mined (0 = just mined)
	//   - status: 0 = failed/reverted, 1 = success
	VerifyBroadcastedTx(ctx context.Context, txHash string) (found bool, blockHeight uint64, confirmations uint64, status uint8, err error)

	// IsAlreadyExecuted checks whether a transaction with the given txID has already been
	// executed on the destination chain (e.g., by another relayer).
	// For SVM: checks if the ExecutedTx PDA exists on-chain, AND returns the
	//   unix timestamp of the latest finalized block. Callers use this as the
	//   cluster's "now" to gate deadline-based give-up/REVERT decisions and to
	//   detect cluster halt or finalization stall (queryBlockTime far behind
	//   wall-clock). 0 means freshness couldn't be determined.
	// For EVM: returns (false, 0, nil). EVM uses nonce-based replay protection.
	IsAlreadyExecuted(ctx context.Context, txID string) (executed bool, queryBlockTime int64, err error)

	// GetGasFeeUsed returns the gas fee used by a transaction on the destination chain.
	// EVM: fetches receipt and returns gasUsed * effectiveGasPrice as decimal string.
	// SVM: returns "0" (gas accounting is handled via vault gasFee reimbursement).
	// Returns "0" if the transaction is not found.
	GetGasFeeUsed(ctx context.Context, txHash string) (string, error)

	// GetFundMigrationSigningRequest builds a native token transfer for fund migration,
	// transferring the maximum possible balance (balance minus gas cost).
	GetFundMigrationSigningRequest(ctx context.Context, data *FundMigrationData, nonce uint64) (*UnsignedSigningReq, error)

	// BroadcastFundMigrationTx assembles and broadcasts a signed fund migration transaction.
	BroadcastFundMigrationTx(ctx context.Context, req *UnsignedSigningReq, data *FundMigrationData, signature []byte) (string, error)
}

type UnsignedSigningReq struct {
	SigningHash []byte // Hash to be signed by TSS
	Nonce       uint64 // evm - TSS Address nonce | svm - PDA nonce

	// TSSFundMigrationAmount is the native value swept for a fund-migration tx, fixed at
	// signing time. Nil for outbound. Must be reused verbatim at broadcast — re-querying
	// balance there races with a successful sweep from another validator.
	TSSFundMigrationAmount *big.Int `json:"TSSFundMigrationAmount,omitempty"`
}

type VoteSigner interface {
	VoteInbound(ctx context.Context, inbound *uexecutortypes.Inbound) (string, error)
	VoteOutbound(ctx context.Context, txID string, utxID string, observation *uexecutortypes.OutboundObservation) (string, error)
}