storage

type ChainReviewCondition struct {
	ConditionID string
	ChainID     string
	Trigger     ChainReviewTrigger
	NodeA       NodeObservation
	NodeB       NodeObservation
	OpenedAt    time.Time
	ResolvedAt  *time.Time
	Resolution  string
}

type ChainReviewRepo interface {
	Open(ctx context.Context, c ChainReviewCondition) (ChainReviewCondition, error)
	Get(ctx context.Context, conditionID string) (ChainReviewCondition, error)
	// HasOpen backs the FR-023 crediting gate.
	HasOpen(ctx context.Context, chainID string) (bool, error)
	ListOpen(ctx context.Context, chainID string) ([]ChainReviewCondition, error)
	Resolve(ctx context.Context, conditionID, resolution string, at time.Time) error
}

type ChainReviewTrigger string

type CheckpointRepo interface {
	Get(ctx context.Context, chainID string) (ScannerCheckpoint, error)
	Set(ctx context.Context, cp ScannerCheckpoint) error
}

type Classification string

type ControlFlow string

type ControlsAuditEntry struct {
	ID       int64
	ChainID  string
	Field    string
	OldValue string
	NewValue string
	Actor    string
	Reason   string
	At       time.Time
}

type ControlsRepo interface {
	// Get returns the controls row, or the all-false zero value when none
	// exists yet (controls default to running).
	Get(ctx context.Context, chainID string) (OperationalControls, error)
	// Apply performs a partial update and writes one audit entry per changed
	// field, atomically.
	Apply(ctx context.Context, chainID string, u ControlsUpdate, actor, reason string) (OperationalControls, error)
	ListAudit(ctx context.Context, chainID string, limit int) ([]ControlsAuditEntry, error)
}

type ControlsUpdate struct {
	CreditPaused          *bool
	SigningPaused         *bool
	BroadcastPaused       *bool
	SweepPaused           *bool
	ScanWithoutCredit     *bool
	ResumeFromHeight      *uint64
	ClearResumeFromHeight bool
}

type DepositRecord struct {
	ID               int64
	ChainID          string
	TxHash           string
	MessageIndex     uint32
	CoinIndex        uint32
	BlockHeight      uint64
	BlockTimestamp   time.Time
	SenderAddress    *string // nil when the input set is ambiguous (MsgMultiSend)
	RecipientAddress string
	Denom            string
	AmountBaseUnits  sdkmath.Int
	Memo             string
	TxCode           uint32
	TxLog            string
	Status           DepositStatus
	// PriorStatus is set while Status == SUSPENDED; resume returns to it.
	PriorStatus *DepositStatus
	CreditedAt  *time.Time
	SweepTxHash *string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

type DepositRepo interface {
	// Insert creates a deposit; a unique-key hit returns ErrDuplicate (the
	// caller records the DUPLICATE observation for metrics — never re-credits).
	Insert(ctx context.Context, d DepositRecord) (DepositRecord, error)
	Get(ctx context.Context, chainID, txHash string, messageIndex, coinIndex uint32, recipientAddress string) (DepositRecord, error)
	GetByID(ctx context.Context, id int64) (DepositRecord, error)
	ListByStatus(ctx context.Context, chainID string, status DepositStatus, limit int) ([]DepositRecord, error)

	// UpdateStatus moves a deposit from → to, applying set. It returns
	// ErrStatusConflict when the stored status differs from `from`,
	// ErrIllegalTransition when the (from, to) pair is not legal, including
	// resuming SUSPENDED to anything but the recorded prior status.
	UpdateStatus(ctx context.Context, id int64, from, to DepositStatus, set DepositUpdate) error
}

type DepositStatus string

type DepositUpdate struct {
	CreditedAt  *time.Time
	SweepTxHash *string
	TxLog       *string
}

type FeeFundingSpend struct {
	ID               int64
	ChainID          string
	TxHash           string
	FeeWalletAddress string
	AmountBaseUnits  sdkmath.Int
	BlockHeight      uint64
	CreatedAt        time.Time
}

type FeeOutflow struct {
	ID           int64
	ChainID      string
	TxHash       string
	PayerAddress string
	FeeBaseUnits sdkmath.Int
	TxCode       uint32
	BlockHeight  uint64
	CreatedAt    time.Time
}

type LedgerDirection string

type LedgerEntry struct {
	ID              int64
	ChainID         string
	Kind            LedgerEntryKind
	TxHash          string
	MessageIndex    uint32
	OpIndex         uint32
	BlockHeight     uint64
	EventIndex      uint32
	Direction       LedgerDirection
	Address         string
	CounterpartySet []string
	AmountBaseUnits sdkmath.Int
	Denom           string
	TxCode          uint32
	Classification  Classification
	CreatedAt       time.Time
}

type LedgerEntryKind string

type LedgerQuery struct {
	ChainID    string
	Address    string
	FromHeight uint64
	ToHeight   uint64
	AfterID    int64
	Limit      int
}

type LedgerRepo interface {
	// Append inserts one entry; a unique-key hit returns ErrDuplicate.
	Append(ctx context.Context, e LedgerEntry) (LedgerEntry, error)
	GetTxEntry(ctx context.Context, chainID, txHash string, messageIndex, opIndex uint32) (LedgerEntry, error)
	GetBlockEventEntry(ctx context.Context, chainID string, blockHeight uint64, eventIndex uint32) (LedgerEntry, error)
	List(ctx context.Context, q LedgerQuery) ([]LedgerEntry, error)

	// AppendFeeOutflow inserts one FEE_DEDUCTION record; a (chain_id, tx_hash)
	// hit returns ErrDuplicate.
	AppendFeeOutflow(ctx context.Context, f FeeOutflow) (FeeOutflow, error)
	ListFeeOutflows(ctx context.Context, chainID, payerAddress string, fromHeight, toHeight uint64) ([]FeeOutflow, error)

	// AppendFeeFundingSpend records one confirmed FEE_FUND fee-wallet spend; a
	// (chain_id, tx_hash) hit returns ErrDuplicate (a re-confirm is a no-op).
	AppendFeeFundingSpend(ctx context.Context, s FeeFundingSpend) (FeeFundingSpend, error)
	// SumFeeFundingSpend totals confirmed fee-wallet FEE_FUND spend over the
	// inclusive [fromHeight, toHeight] block window (toHeight 0 = open-ended).
	SumFeeFundingSpend(ctx context.Context, chainID, feeWalletAddress string, fromHeight, toHeight uint64) (sdkmath.Int, error)
}

type NodeObservation struct {
	Endpoint string
	Height   uint64
	Value    string // block hash or query-result digest, trigger-dependent
}

type OperationalControls struct {
	ChainID           string
	CreditPaused      bool
	SigningPaused     bool
	BroadcastPaused   bool
	SweepPaused       bool
	ScanWithoutCredit bool
	ResumeFromHeight  *uint64
	UpdatedAt         time.Time
}

type OutboxEvent struct {
	ID           int64
	ChainID      string
	Topic        string
	DedupKey     string
	Payload      []byte
	CreatedAt    time.Time
	DispatchedAt *time.Time
}

type OutboxRepo interface {
	// Enqueue inserts an event; a DedupKey hit returns ErrDuplicate.
	Enqueue(ctx context.Context, ev OutboxEvent) (OutboxEvent, error)
	ListPending(ctx context.Context, limit int) ([]OutboxEvent, error)
	MarkDispatched(ctx context.Context, id int64, at time.Time) error
}

type ReconRepo interface {
	SaveReport(ctx context.Context, r ReconciliationReport) error
	GetReport(ctx context.Context, reportID string) (ReconciliationReport, error)
	ListReports(ctx context.Context, chainID string, kind ReconciliationKind, limit int) ([]ReconciliationReport, error)
}

type ReconciliationEntry struct {
	Address                 string
	ExpectedBaseUnits       sdkmath.Int
	ObservedBaseUnits       sdkmath.Int
	Difference              sdkmath.Int
	EarliestSuspectedHeight uint64
	RelatedTxHashes         []string
	RecommendedRescanHeight uint64
}

type ReconciliationKind string

type ReconciliationReport struct {
	ReportID         string
	ChainID          string
	Kind             ReconciliationKind
	PeriodStart      time.Time
	PeriodEnd        time.Time
	GeneratedAt      time.Time
	Entries          []ReconciliationEntry
	DiscrepancyCount int
}

type ReviewItem struct {
	ID         int64
	ChainID    string
	Kind       ReviewItemKind
	RefID      string // deposit ID, withdrawal ID, or ledger-entry ID
	Reason     string
	OpenedAt   time.Time
	ResolvedAt *time.Time
	Resolution string
}

type ReviewItemKind string

type ReviewRepo interface {
	Open(ctx context.Context, item ReviewItem) (ReviewItem, error)
	Get(ctx context.Context, id int64) (ReviewItem, error)
	ListOpen(ctx context.Context, chainID string, limit int) ([]ReviewItem, error)
	// Resolve stamps ResolvedAt/Resolution; resolving an already-resolved
	// item returns ErrStatusConflict.
	Resolve(ctx context.Context, id int64, resolution string, at time.Time) error
}

type ScannerCheckpoint struct {
	ChainID                  string
	LastFullyProcessedHeight uint64
	LastObservedBlockHash    string
	UpdatedAt                time.Time
}

type SequenceRepo interface {
	// Reserve inserts a reservation in status RESERVED. A (chain, source,
	// sequence) hit on a live row returns ErrDuplicate; a hit on a RELEASED
	// row reclaims it (new WorkRef, back to RESERVED). A WorkRef hit returns
	// ErrDuplicate.
	Reserve(ctx context.Context, r SequenceReservation) (SequenceReservation, error)
	GetByWorkRef(ctx context.Context, ref WorkRef) (SequenceReservation, error)
	// ListUnconsumed returns every reservation not in a terminal status for
	// startup/mismatch reconciliation (§6 reconciliation rule).
	ListUnconsumed(ctx context.Context, chainID, sourceAddress string) ([]SequenceReservation, error)

	// UpdateStatus moves a reservation from → to; semantics as
	// DepositRepo.UpdateStatus. Note RELEASED is only reachable from
	// RESERVED or RECONCILIATION_REQUIRED — never from SIGNED/BROADCAST
	// (signed bytes may still redeem the sequence).
	UpdateStatus(ctx context.Context, id int64, from, to SequenceReservationStatus) error
}

type SequenceReservation struct {
	ID            int64
	ChainID       string
	SourceAddress string
	AccountNumber uint64
	Sequence      uint64
	WorkRef       WorkRef
	Status        SequenceReservationStatus
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type SequenceReservationStatus string

type Store interface {
	Tx

	Ledger() LedgerRepo
	Deposits() DepositRepo
	Checkpoints() CheckpointRepo
	Withdrawals() WithdrawalRepo
	Sequences() SequenceRepo
	Sweeps() SweepRepo
	Watch() WatchRepo
	Controls() ControlsRepo
	Review() ReviewRepo
	ChainReview() ChainReviewRepo
	Recon() ReconRepo
	Outbox() OutboxRepo

	Close() error
}

type SweepJob struct {
	SweepID             string
	IdempotencyKey      string
	ChainID             string
	SourceAddress       string
	HotWalletAddress    string
	Strategy            SweepStrategy
	AmountBaseUnits     sdkmath.Int
	FeeReserveBaseUnits sdkmath.Int
	DepositIDs          []int64
	SignedTxBytes       []byte
	TxHash              *string
	TxCode              *uint32
	Status              SweepStatus
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

type SweepRepo interface {
	// Create inserts a sweep in status PENDING. An existing non-terminal job
	// for (chain_id, source_address) returns ErrActiveSweepExists; an
	// idempotency-key hit returns ErrDuplicate.
	Create(ctx context.Context, j SweepJob) (SweepJob, error)
	Get(ctx context.Context, sweepID string) (SweepJob, error)
	GetByIdempotencyKey(ctx context.Context, idempotencyKey string) (SweepJob, error)
	// GetActive returns the single non-terminal job for the account, or
	// ErrNotFound.
	GetActive(ctx context.Context, chainID, sourceAddress string) (SweepJob, error)
	ListByStatus(ctx context.Context, chainID string, status SweepStatus, limit int) ([]SweepJob, error)

	// UpdateStatus moves a sweep from → to, applying set; semantics as
	// DepositRepo.UpdateStatus.
	UpdateStatus(ctx context.Context, sweepID string, from, to SweepStatus, set SweepUpdate) error
}

type SweepStatus string

type SweepStrategy string

type SweepUpdate struct {
	SignedTxBytes []byte
	TxHash        *string
	TxCode        *uint32
	DepositIDs    []int64 // non-nil replaces the covered-deposit set
}

type Tx interface {
	WithTx(ctx context.Context, fn func(ctx context.Context, s Store) error) error
}

type WatchRepo interface {
	Upsert(ctx context.Context, w WatchedAddress) error
	Get(ctx context.Context, chainID, address string) (WatchedAddress, error)
	ListActive(ctx context.Context, chainID string) ([]WatchedAddress, error)
	SetActive(ctx context.Context, chainID, address string, active bool) error
}

type WatchedAddress struct {
	ChainID      string
	Address      string
	Kind         WatchedAddressKind
	CustomerRef  string
	MemoRequired bool
	Active       bool
}

type WatchedAddressKind string

type WithdrawalRecord struct {
	WithdrawalID       string
	IdempotencyKey     string
	ChainID            string
	SourceAddress      string
	DestinationAddress string
	Denom              string
	AmountBaseUnits    sdkmath.Int
	Memo               string
	AccountNumber      *uint64
	Sequence           *uint64
	GasWanted          *uint64
	GasLimit           *uint64
	FeeAmountBaseUnits *sdkmath.Int
	SignMode           string
	SignedTxBytes      []byte
	TxHash             *string
	BlockHeight        *uint64
	TxCode             *uint32
	RawLog             string
	Status             WithdrawalStatus
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

type WithdrawalRepo interface {
	// Create inserts a withdrawal; an idempotency-key hit returns
	// ErrDuplicate (FR-033 — resolve the original via GetByIdempotencyKey).
	Create(ctx context.Context, w WithdrawalRecord) (WithdrawalRecord, error)
	Get(ctx context.Context, withdrawalID string) (WithdrawalRecord, error)
	GetByIdempotencyKey(ctx context.Context, idempotencyKey string) (WithdrawalRecord, error)
	ListByStatus(ctx context.Context, chainID string, status WithdrawalStatus, limit int) ([]WithdrawalRecord, error)

	// UpdateStatus moves a withdrawal from → to, applying set; semantics as
	// DepositRepo.UpdateStatus.
	UpdateStatus(ctx context.Context, withdrawalID string, from, to WithdrawalStatus, set WithdrawalUpdate) error

	// SumCommittedBySource reports the count and summed AmountBaseUnits of the
	// withdrawals for (chainID, sourceAddress) that currently hold a funds
	// reservation — status in {FUNDS_RESERVED, SEQUENCE_RESERVED,
	// TRANSACTION_BUILT, TRANSACTION_SIMULATED, SIGNED, BROADCAST}; REQUESTED /
	// ADDRESS_VALIDATED / COMPLIANCE_APPROVED (not yet reserved) and the
	// terminal states (CONFIRMED / FAILED / CANCELLED) are excluded. A
	// REVIEW_REQUIRED record remains committed when signed_tx_bytes is present:
	// an uncertain signed or broadcast transaction may still spend the funds.
	// Pre-sign review records do not hold a reservation. The caller adds count ×
	// its configured max-fee cap to obtain
	// the conservative reserved total; the on-chain balance must cover that
	// total plus the new withdrawal before FUNDS_RESERVED, so concurrent
	// reserves from one source cannot jointly over-commit the wallet.
	SumCommittedBySource(ctx context.Context, chainID, sourceAddress string) (count int64, sumAmount sdkmath.Int, err error)
}

type WithdrawalStatus string

type WithdrawalUpdate struct {
	AccountNumber      *uint64
	Sequence           *uint64
	GasWanted          *uint64
	GasLimit           *uint64
	FeeAmountBaseUnits *sdkmath.Int
	SignedTxBytes      []byte
	TxHash             *string
	BlockHeight        *uint64
	TxCode             *uint32
	RawLog             *string
}

type WorkKind string

type WorkRef struct {
	Kind WorkKind
	ID   string
}