chain_container

type ChainContainer interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Pause(ctx context.Context) error
	Resume(ctx context.Context) error

	ID() eth.ChainID
	ELFinalizedHead(ctx context.Context) (eth.L2BlockRef, error)
	LocalSafeBlockAtTimestamp(ctx context.Context, ts uint64) (eth.L2BlockRef, error)
	// TimestampToBlockNumber maps an L2 unix timestamp to the L2 block number (rollup derivation).
	TimestampToBlockNumber(ctx context.Context, ts uint64) (uint64, error)
	BlockNumberToTimestamp(ctx context.Context, blocknum uint64) (uint64, error)
	// FirstSafeHeadTimestamp returns the L2 block timestamp of the first
	// entry in this chain's SafeDB. Returns ErrSafeDBNotReady when the chain
	// has not yet derived a stable first safe head.
	FirstSafeHeadTimestamp(ctx context.Context) (uint64, error)
	SyncStatus(ctx context.Context) (*eth.SyncStatus, error)
	OptimisticAt(ctx context.Context, ts uint64) (l2, l1 eth.BlockID, err error)
	// OutputRootAtL2BlockHash returns the L2 output root for the canonical
	// block at the given hash. Post-Isthmus the root is derived from the
	// header alone; pre-Isthmus it falls back to eth_getProof on state at
	// that block. Returns ethereum.NotFound if the EL no longer has the
	// block at that hash on its canonical chain.
	OutputRootAtL2BlockHash(ctx context.Context, blockHash common.Hash) (eth.Bytes32, error)
	OptimisticOutputAtTimestamp(ctx context.Context, ts uint64) (*eth.OutputV0, error)
	RegisterVerifier(v activity.VerificationActivity)
	// VerifierCurrentL1 returns the CurrentL1 of the registered verifier.
	// The bool is false when no verifier is registered.
	VerifierCurrentL1() (eth.BlockID, bool)
	// FetchReceipts fetches the receipts for a given block by hash.
	// Returns block info and receipts, or an error if the block or receipts cannot be fetched.
	FetchReceipts(ctx context.Context, blockHash eth.BlockID) (eth.BlockInfo, types.Receipts, error)
	// BlockTime returns the block time in seconds for this chain.
	BlockTime() uint64
	// PruneDeniedAtOrAfterTimestamp removes deny-list entries with DecisionTimestamp >= timestamp.
	// Returns map of removed hashes by height.
	PruneDeniedAtOrAfterTimestamp(timestamp uint64) (map[uint64][]common.Hash, error)
	// PauseAndStopVN pauses the chain container restart loop and stops the virtual node.
	// This is used to freeze a chain's VN before a multi-chain rewind begins, preventing
	// the VN from issuing forkchoice updates that race with the rewind of a peer chain.
	PauseAndStopVN(ctx context.Context) error
	// IsDenied checks if a block hash is on the deny list at the given height.
	IsDenied(height uint64, payloadHash common.Hash) (bool, error)
	// GetDeniedOutput returns the reconstructed OutputV0 for a denied block.
	// Returns nil if the block is not denied at that height.
	GetDeniedOutput(height uint64, payloadHash common.Hash) (*eth.OutputV0, error)
	// OutputV0AtBlockNumber returns the full OutputV0 for the block at the given number.
	OutputV0AtBlockNumber(ctx context.Context, l2BlockNum uint64) (*eth.OutputV0, error)
	// PayloadByHash returns the canonical execution payload envelope for the given block hash.
	// Used by interop build paths to capture canonical payloads for WAL'd rewind operations.
	PayloadByHash(ctx context.Context, hash common.Hash) (*eth.ExecutionPayloadEnvelope, error)
	// PayloadByNumber returns the canonical execution payload envelope for the given block number.
	// Used by interop build paths when the rewind target is below the verified frontier.
	PayloadByNumber(ctx context.Context, number uint64) (*eth.ExecutionPayloadEnvelope, error)
	// SetResetCallback sets a callback that is invoked when the chain resets.
	// The supernode uses this to notify activities about chain resets.
	SetResetCallback(cb ResetCallback)
}

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

type DenyRecord struct {
	PayloadHash              common.Hash `json:"payloadHash"`
	DecisionTimestamp        uint64      `json:"decisionTimestamp"`
	StateRoot                eth.Bytes32 `json:"stateRoot"`
	MessagePasserStorageRoot eth.Bytes32 `json:"messagePasserStorageRoot"`
}

type InteropChain interface {
	ChainContainer
	// HasDeniedAtOrAfterTimestamp returns true if any deny-list entry has
	// DecisionTimestamp >= timestamp, without mutating the deny list.
	HasDeniedAtOrAfterTimestamp(timestamp uint64) (bool, error)
	// RewindEngine rewinds the engine to the supplied target block. target is the canonical
	// payload at the rewind destination, loaded from durable WAL storage by the caller —
	// not re-derived from the live engine. invalidatedBlock is the block that triggered the
	// rewind and is passed to reset callbacks (it is purely informational).
	RewindEngine(ctx context.Context, target *eth.ExecutionPayloadEnvelope, invalidatedBlock eth.BlockRef) error
	// InvalidateBlock adds a block to the deny list and triggers a rewind if the chain
	// currently uses that block at the specified height. parentPayload is the canonical
	// payload at height-1 (the rewind destination) loaded from durable WAL storage —
	// callers must capture it at build time, before the rewind starts. Returns true if
	// a rewind was triggered, false otherwise.
	InvalidateBlock(ctx context.Context, height uint64, payloadHash common.Hash, decisionTimestamp uint64, stateRoot, messagePasserStorageRoot eth.Bytes32, parentPayload *eth.ExecutionPayloadEnvelope) (bool, error)
}

type RPCRouterGate interface {
	SetHandler(chainID string, h http.Handler)
	SetReadinessCheck(chainID string, fn func() bool)
	RemoveHandler(chainID string)
}

type ResetCallback func(chainID eth.ChainID, timestamp uint64, invalidatedBlock eth.BlockRef)