shadow

type ChainSnapshot struct {
	Block        json.RawMessage `json:"block"`
	BlockResults json.RawMessage `json:"blockResults"`
}

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

type CompareResult struct {
	// Height is the block height that was compared.
	Height int64 `json:"height"`

	// Timestamp is the UTC time the comparison was performed.
	Timestamp string `json:"timestamp"`

	// Match is true when all checked layers agree between shadow and canonical.
	// In migration mode an expected AppHash divergence does not clear Match.
	Match bool `json:"match"`

	// MigrationMode records that this comparison treated AppHash divergence as
	// expected (an AppHash-breaking migration shadow), keying the verdict on
	// execution-results equivalence instead.
	MigrationMode bool `json:"migrationMode,omitempty"`

	// DivergenceLayer is the first layer that detected a mismatch.
	// Nil when Match is true.
	DivergenceLayer *int `json:"divergenceLayer,omitempty"`

	// Layer0 holds the block-level hash comparison. Always populated.
	Layer0 Layer0Result `json:"layer0"`

	// Layer1 holds the transaction receipt comparison.
	// Only populated when Layer 0 detected a divergence.
	Layer1 *Layer1Result `json:"layer1,omitempty"`

	// Layer2 holds the logical state-diff comparison. Populated only when a
	// state reader and key source are configured (see WithLayer2).
	Layer2 *Layer2Result `json:"layer2,omitempty"`
}

type DivergenceReport struct {
	Height     int64         `json:"height"`
	Timestamp  string        `json:"timestamp"`
	Comparison CompareResult `json:"comparison"`
	Shadow     ChainSnapshot `json:"shadow"`
	Canonical  ChainSnapshot `json:"canonical"`
}

type FieldDivergence struct {
	Field     string `json:"field"`
	Shadow    any    `json:"shadow"`
	Canonical any    `json:"canonical"`
}

type KeySource interface {
	TouchedAccounts(ctx context.Context, height int64) ([]TouchedAccount, error)
}

type Layer0Result struct {
	AppHashMatch         bool `json:"appHashMatch"`
	LastResultsHashMatch bool `json:"lastResultsHashMatch"`
	GasUsedMatch         bool `json:"gasUsedMatch"`

	// Raw values are included when there is a mismatch, for diagnostics.
	ShadowAppHash    string `json:"shadowAppHash,omitempty"`
	CanonicalAppHash string `json:"canonicalAppHash,omitempty"`

	ShadowLastResultsHash    string `json:"shadowLastResultsHash,omitempty"`
	CanonicalLastResultsHash string `json:"canonicalLastResultsHash,omitempty"`

	ShadowGasUsed    int64 `json:"shadowGasUsed,omitempty"`
	CanonicalGasUsed int64 `json:"canonicalGasUsed,omitempty"`
}

type Layer1Result struct {
	// TotalTxs is the number of transactions in the block.
	TotalTxs int `json:"totalTxs"`

	// TxCountMatch is true when both chains have the same number of txs.
	TxCountMatch bool `json:"txCountMatch"`

	// Divergences lists the per-transaction differences found.
	Divergences []TxDivergence `json:"divergences,omitempty"`

	// Indeterminate is set when the receipt comparison could not run (RPC error).
	// In migration mode Layer 1 is a load-bearing check, so an indeterminate
	// Layer 1 forces the block to fail closed rather than pass silently.
	Indeterminate bool   `json:"indeterminate,omitempty"`
	Error         string `json:"error,omitempty"`
}

type Layer2Result struct {
	// AccountsChecked is the number of touched accounts compared.
	AccountsChecked int `json:"accountsChecked"`

	// KeysChecked is the number of individual state reads compared (storage
	// slots plus per-account balance/code/nonce checks).
	KeysChecked int `json:"keysChecked"`

	// Divergences lists the logical-state mismatches found.
	Divergences []StateDivergence `json:"divergences,omitempty"`

	// Indeterminate is set when the layer could not be evaluated (a key source
	// or state read failed). A migration shadow's load-bearing check could not
	// run, so the block must NOT be counted clean — Error carries the cause.
	Indeterminate bool   `json:"indeterminate,omitempty"`
	Error         string `json:"error,omitempty"`
}

type Option func(*Comparator)

type StateDivergence struct {
	Kind      string `json:"kind"` // storage | code | nonce
	Addr      string `json:"addr"`
	Slot      string `json:"slot,omitempty"` // set only for storage
	Shadow    string `json:"shadow"`
	Canonical string `json:"canonical"`
}

type StateReader interface {
	StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *big.Int) ([]byte, error)
	CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error)
	NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error)
	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
}

type StaticKeySource struct {
	Accounts []TouchedAccount
}

type TouchedAccount struct {
	Addr         common.Address
	Slots        []common.Hash
	CheckCode    bool
	CheckNonce   bool
	CheckBalance bool
}

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

type TxDivergence struct {
	// TxIndex is the position of the transaction within the block.
	TxIndex int `json:"txIndex"`

	// Fields lists which receipt fields diverged.
	Fields []FieldDivergence `json:"fields"`
}