database

type ActionLogEntryV1 struct {
	ID          uuid.UUID `gorm:"type:char(36);primaryKey"`
	UserWallet  string    `gorm:"column:user_wallet;not null"`
	GatedAction uint8     `gorm:"column:gated_action;not null"`
	CreatedAt   time.Time
}

type ActiveCountByLabel struct {
	Label string `gorm:"column:label"`
	Count uint64 `gorm:"column:count"`
}

type AppLedgerEntryV1 struct {
	ID          uuid.UUID       `gorm:"type:char(36);primaryKey"`
	AccountID   string          `gorm:"column:account_id;not null;index:idx_account_asset_symbol;index:idx_account_wallet"`
	AssetSymbol string          `gorm:"column:asset_symbol;not null;index:idx_account_asset_symbol"`
	Wallet      string          `gorm:"column:wallet;not null;index:idx_account_wallet"`
	Credit      decimal.Decimal `gorm:"column:credit;type:varchar(78);not null"`
	Debit       decimal.Decimal `gorm:"column:debit;type:varchar(78);not null"`
	CreatedAt   time.Time
}

type AppParticipantV1 struct {
	AppSessionID    string `gorm:"column:app_session_id;not null;primaryKey;priority:1"`
	WalletAddress   string `gorm:"column:wallet_address;not null;primaryKey;priority:2"`
	SignatureWeight uint8  `gorm:"column:signature_weight;not null"`
}

type AppSessionCount struct {
	Application string               `gorm:"column:application_id"`
	Status      app.AppSessionStatus `gorm:"column:status"`
	Count       uint64               `gorm:"column:count"`
}

type AppSessionKeyAppSessionIDV1 struct {
	SessionKeyStateID string `gorm:"column:session_key_state_id;not null;primaryKey;priority:1"`
	AppSessionID      string `gorm:"column:app_session_id;not null;primaryKey;priority:2;index"`
}

type AppSessionKeyApplicationV1 struct {
	SessionKeyStateID string `gorm:"column:session_key_state_id;not null;primaryKey;priority:1"`
	ApplicationID     string `gorm:"column:application_id;not null;primaryKey;priority:2;index"`
}

type AppSessionKeyStateV1 struct {
	ID             string                        `gorm:"column:id;primaryKey"`
	UserAddress    string                        `gorm:"column:user_address;not null;uniqueIndex:idx_session_key_states_v1_user_key_ver,priority:1"`
	SessionKey     string                        `gorm:"column:session_key;not null;uniqueIndex:idx_session_key_states_v1_user_key_ver,priority:2"`
	Version        uint64                        `gorm:"column:version;not null;uniqueIndex:idx_session_key_states_v1_user_key_ver,priority:3"`
	ApplicationIDs []AppSessionKeyApplicationV1  `gorm:"foreignKey:SessionKeyStateID;references:ID"`
	AppSessionIDs  []AppSessionKeyAppSessionIDV1 `gorm:"foreignKey:SessionKeyStateID;references:ID"`
	ExpiresAt      time.Time                     `gorm:"column:expires_at;not null"`
	UserSig        string                        `gorm:"column:user_sig;not null"`
	SessionKeySig  string                        `gorm:"column:session_key_sig"`
	CreatedAt      time.Time
}

type AppSessionV1 struct {
	ID            string               `gorm:"primaryKey"`
	ApplicationID string               `gorm:"column:application_id;not null"`
	Nonce         uint64               `gorm:"column:nonce;not null"`
	Participants  []AppParticipantV1   `gorm:"foreignKey:AppSessionID;references:ID"`
	SessionData   string               `gorm:"column:session_data;type:text;not null"`
	Quorum        uint8                `gorm:"column:quorum;default:100"`
	Version       uint64               `gorm:"column:version;default:1"`
	Status        app.AppSessionStatus `gorm:"column:status;not null"`
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type AppV1 struct {
	ID                          string `gorm:"primaryKey"`
	OwnerWallet                 string `gorm:"column:owner_wallet;not null"`
	Metadata                    string `gorm:"column:metadata;type:text;not null"`
	Version                     uint64 `gorm:"column:version;default:1"`
	CreationApprovalNotRequired bool   `gorm:"column:creation_approval_not_required"`
	CreatedAt                   time.Time
	UpdatedAt                   time.Time
}

type BlockchainAction struct {
	ID           int64                  `gorm:"primary_key"`
	Type         BlockchainActionType   `gorm:"column:action_type;not null"`
	StateID      string                 `gorm:"column:state_id;size:66"`
	BlockchainID uint64                 `gorm:"column:blockchain_id;not null"`
	Data         datatypes.JSON         `gorm:"column:action_data;type:text"`
	Status       BlockchainActionStatus `gorm:"column:status;not null"`
	Retries      uint8                  `gorm:"column:retry_count;default:0"`
	Error        string                 `gorm:"column:last_error;type:text"`
	TxHash       string                 `gorm:"column:transaction_hash;size:66"`
	CreatedAt    time.Time              `gorm:"column:created_at"`
	UpdatedAt    time.Time              `gorm:"column:updated_at"`
}

type BlockchainActionStatus uint8

type BlockchainActionType uint8

type Channel struct {
	ChannelID             string             `gorm:"column:channel_id;primaryKey;"`
	UserWallet            string             `gorm:"column:user_wallet;not null"`
	Asset                 string             `gorm:"column:asset;not null"`
	Type                  core.ChannelType   `gorm:"column:type;not null"`
	BlockchainID          uint64             `gorm:"column:blockchain_id;not null"`
	Token                 string             `gorm:"column:token;not null"`
	ChallengeDuration     uint32             `gorm:"column:challenge_duration;not null"`
	ChallengeExpiresAt    *time.Time         `gorm:"column:challenge_expires_at;default:null"`
	Nonce                 uint64             `gorm:"column:nonce;not null;"`
	ApprovedSigValidators string             `gorm:"column:approved_sig_validators;not null;"`
	Status                core.ChannelStatus `gorm:"column:status;not null;"`
	StateVersion          uint64             `gorm:"column:state_version;not null;"`
	CreatedAt             time.Time
	UpdatedAt             time.Time
}

type ChannelCount struct {
	Asset  string             `gorm:"column:asset"`
	Status core.ChannelStatus `gorm:"column:status"`
	Count  uint64             `gorm:"column:count"`
}

type ChannelSessionKeyAssetV1 struct {
	SessionKeyStateID string `gorm:"column:session_key_state_id;not null;primaryKey;priority:1"`
	Asset             string `gorm:"column:asset;not null;primaryKey;priority:2;index"`
}

type ChannelSessionKeyStateV1 struct {
	ID            string                     `gorm:"column:id;primaryKey"`
	UserAddress   string                     `gorm:"column:user_address;not null;uniqueIndex:idx_channel_session_key_states_v1_user_key_ver,priority:1"`
	SessionKey    string                     `gorm:"column:session_key;not null;uniqueIndex:idx_channel_session_key_states_v1_user_key_ver,priority:2"`
	Version       uint64                     `gorm:"column:version;not null;uniqueIndex:idx_channel_session_key_states_v1_user_key_ver,priority:3"`
	Assets        []ChannelSessionKeyAssetV1 `gorm:"foreignKey:SessionKeyStateID;references:ID"`
	MetadataHash  string                     `gorm:"column:metadata_hash;type:char(66);not null"`
	ExpiresAt     time.Time                  `gorm:"column:expires_at;not null"`
	UserSig       string                     `gorm:"column:user_sig;not null"`
	SessionKeySig string                     `gorm:"column:session_key_sig"`
	CreatedAt     time.Time
}

type ContractEvent struct {
	ID              int64     `gorm:"primary_key;column:id"`
	ContractAddress string    `gorm:"column:contract_address"`
	BlockchainID    uint64    `gorm:"column:blockchain_id"`
	Name            string    `gorm:"column:name"`
	BlockNumber     uint64    `gorm:"column:block_number"`
	TransactionHash string    `gorm:"column:transaction_hash"`
	LogIndex        uint32    `gorm:"column:log_index"`
	CreatedAt       time.Time `gorm:"column:created_at"`
}

type CurrentSessionKeyStateV1 struct {
	UserAddress string         `gorm:"column:user_address;primaryKey;size:42"`
	SessionKey  string         `gorm:"column:session_key;primaryKey;size:42;uniqueIndex:current_session_key_states_v1_key_kind_uniq,priority:1"`
	Kind        SessionKeyKind `gorm:"column:kind;primaryKey;type:smallint;uniqueIndex:current_session_key_states_v1_key_kind_uniq,priority:2"`
	Version     uint64         `gorm:"column:version;not null"`
	UpdatedAt   time.Time      `gorm:"column:updated_at"`
}

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

type DatabaseConfig struct {
	URL      string `env:"NITRONODE_DATABASE_URL" env-default:""`
	Name     string `env:"NITRONODE_DATABASE_NAME" env-default:""`
	Schema   string `env:"NITRONODE_DATABASE_SCHEMA" env-default:""`
	Driver   string `env:"NITRONODE_DATABASE_DRIVER" env-default:"postgres"`
	Username string `env:"NITRONODE_DATABASE_USERNAME"  env-default:"postgres"`
	Password string `env:"NITRONODE_DATABASE_PASSWORD" env-default:"your-super-secret-and-long-postgres-password"`
	Host     string `env:"NITRONODE_DATABASE_HOST" env-default:"localhost"`
	Port     string `env:"NITRONODE_DATABASE_PORT" env-default:"5432"`
	SSLMode  string `env:"NITRONODE_DATABASE_SSLMODE" env-default:"require"`
	Retries  int    `env:"NITRONODE_DATABASE_RETRIES" env-default:"5"`

	// Connection pool settings
	MaxOpenConns    int `env:"NITRONODE_DATABASE_MAX_OPEN_CONNS" env-default:"100"`
	MaxIdleConns    int `env:"NITRONODE_DATABASE_MAX_IDLE_CONNS" env-default:"25"`
	ConnMaxLifetime int `env:"NITRONODE_DATABASE_CONN_MAX_LIFETIME_SEC" env-default:"300"`
	ConnMaxIdleTime int `env:"NITRONODE_DATABASE_CONN_MAX_IDLE_TIME_SEC" env-default:"60"`
}

type DatabaseStore interface {
	// ExecuteInTransaction runs the provided handler within a database transaction.
	// If the handler returns an error, the transaction is rolled back.
	// If the handler completes successfully, the transaction is committed.
	ExecuteInTransaction(handler StoreTxHandler) error

	// GetUserBalances retrieves the balances for a user's wallet.
	GetUserBalances(wallet string) ([]core.BalanceEntry, error)

	// LockUserState locks a user's balance row for update (postgres only, must be used within a transaction).
	// Uses INSERT ... ON CONFLICT DO NOTHING to ensure the row exists, then SELECT ... FOR UPDATE to lock it.
	// Returns the current balance or zero if the row was just inserted.
	LockUserState(wallet, asset string) (decimal.Decimal, error)

	// GetUserTransactions retrieves transaction history for a user with optional filters.
	GetUserTransactions(wallet string, asset *string, txType *core.TransactionType, fromTime *uint64, toTime *uint64, paginate *core.PaginationParams) ([]core.Transaction, core.PaginationMetadata, error)

	// RecordTransaction creates a transaction record linking state transitions.
	// applicationID is the self-declared origin tag of the client that caused
	// the transaction (see rpc.ApplicationIDQueryParam); empty string means no
	// app_id was supplied and the column is persisted as NULL.
	RecordTransaction(tx core.Transaction, applicationID string) error

	// CreateChannel creates a new channel entity in the database.
	CreateChannel(channel core.Channel) error

	// GetChannelByID retrieves a channel by its unique identifier.
	GetChannelByID(channelID string) (*core.Channel, error)

	// GetActiveHomeChannel retrieves the active home channel for a user's wallet and asset.
	// "Active" includes both Void (DB-only) and Open (materialized onchain).
	GetActiveHomeChannel(wallet, asset string) (*core.Channel, error)

	// GetNotClosedHomeChannel retrieves the home channel for a user's wallet and asset
	// regardless of status, as long as it has not reached ChannelStatusClosed. Intended
	// for read paths (e.g. GetHomeChannel RPC) that must remain functional after an
	// off-chain Finalize flips the channel to Closing.
	GetNotClosedHomeChannel(wallet, asset string) (*core.Channel, error)

	// CheckActiveChannel verifies if a user has an active home channel for the given asset
	// and returns its approved signature validators and current status. A nil status means
	// no active channel exists. "Active" includes Void (DB-only, awaiting onchain confirmation)
	// and Open (materialized onchain); callers needing onchain materialization must additionally
	// require Status == core.ChannelStatusOpen.
	CheckActiveChannel(wallet, asset string) (string, *core.ChannelStatus, error)

	// HasNonClosedHomeChannel returns true if any home channel for (wallet, asset) exists
	// with a status other than Closed, indicating an in-progress channel lifecycle.
	HasNonClosedHomeChannel(wallet, asset string) (bool, error)

	// UpdateChannel persists changes to a channel's metadata (status, version, etc).
	UpdateChannel(channel core.Channel) error

	// GetUserChannels retrieves all channels for a user with optional status, asset, and type filters.
	GetUserChannels(wallet string, status *core.ChannelStatus, asset *string, channelType *core.ChannelType, limit, offset uint32) ([]core.Channel, uint32, error)

	// GetLastStateByChannelID retrieves the most recent state for a given channel.
	// If signed is true, only returns states with both user and node signatures.
	GetLastStateByChannelID(channelID string, signed bool) (*core.State, error)

	// GetStateByChannelIDAndVersion retrieves a specific state version for a channel.
	// Returns nil if the state with the specified version does not exist.
	GetStateByChannelIDAndVersion(channelID string, version uint64) (*core.State, error)

	// GetLastUserState retrieves the most recent state for a user's asset.
	GetLastUserState(wallet, asset string, signed bool) (*core.State, error)

	// StoreUserState persists a new user state to the database.
	// applicationID is the self-declared origin tag of the client that caused
	// the transition (see rpc.ApplicationIDQueryParam); empty string means no
	// app_id was supplied and the column is persisted as NULL.
	StoreUserState(state core.State, applicationID string) error

	// EnsureNoOngoingStateTransitions validates that no conflicting blockchain operations are pending.
	EnsureNoOngoingStateTransitions(wallet, asset string) error

	// EnsureNoOngoingEscrowOperation validates that the user has no in-flight escrow
	// operation (escrow_lock, mutual_lock, or unfinalized escrow_deposit/escrow_withdraw)
	// that would prevent issuing a receiver-side state.
	EnsureNoOngoingEscrowOperation(wallet, asset string) error

	// UpdateStateSigsIfMissing backfills the user and/or node signatures for a stored
	// state when the corresponding column is currently NULL. Either signature may be
	// empty to skip that side.
	UpdateStateSigsIfMissing(channelID string, version uint64, userSig, nodeSig string) error

	// HasSignedFinalize reports whether a node-signed Finalize state exists for the given
	// home channel. Used by event handlers to detect the post-Finalize lifecycle when the
	// channel status field has been temporarily overwritten by an on-chain challenge.
	HasSignedFinalize(channelID string) (bool, error)

	// SumNetTransitionAmountAfterVersion returns the net effect on the user's
	// home-channel balance of transitions stored against channelID strictly above
	// minVersion. Receiver credits (TransferReceive, Release) contribute positively;
	// sender debits (TransferSend, Commit) contribute negatively. Other transition
	// kinds are excluded. Used to compute the ChallengeRescue amount when a
	// challenged channel is closed.
	SumNetTransitionAmountAfterVersion(channelID string, minVersion uint64) (decimal.Decimal, error)

	// ScheduleInitiateEscrowWithdrawal queues a blockchain action to initiate withdrawal.
	// This queues the state to be submitted on-chain to initiate an escrow withdrawal.
	ScheduleInitiateEscrowWithdrawal(stateID string, chainID uint64) error

	// ScheduleCheckpoint schedules a checkpoint operation for a home channel state.
	// This queues the state to be submitted on-chain to update the channel's on-chain state.
	ScheduleCheckpoint(stateID string, chainID uint64) error

	// ScheduleChallenge schedules a challengeChannel(...) submission on the channel's home
	// blockchain using the provided state and a node-produced challenger signature.
	ScheduleChallenge(stateID string, chainID uint64) error

	// ScheduleFinalizeEscrowDeposit schedules a checkpoint for an escrow deposit operation.
	// This queues the state to be submitted on-chain to finalize an escrow deposit.
	ScheduleFinalizeEscrowDeposit(stateID string, chainID uint64) error

	// ScheduleFinalizeEscrowWithdrawal schedules a checkpoint for an escrow withdrawal operation.
	// This queues the state to be submitted on-chain to finalize an escrow withdrawal.
	ScheduleFinalizeEscrowWithdrawal(stateID string, chainID uint64) error

	// ScheduleInitiateEscrowDeposit schedules a checkpoint for an escrow deposit operation.
	// This queues the state to be submitted on-chain for an escrow deposit on home chain.
	ScheduleInitiateEscrowDeposit(stateID string, chainID uint64) error

	// Fail marks a blockchain action as failed and increments the retry counter.
	Fail(actionID int64, err string) error

	// FailNoRetry marks a blockchain action as failed without incrementing the retry counter.
	FailNoRetry(actionID int64, err string) error

	// RecordAttempt records a failed attempt for a blockchain action and increments the retry counter.
	// The action remains in pending status.
	RecordAttempt(actionID int64, err string) error

	// Complete marks a blockchain action as completed with the given transaction hash.
	Complete(actionID int64, txHash string) error

	// GetActions retrieves pending blockchain actions, optionally limited by count.
	GetActions(limit uint8, chainID uint64) ([]BlockchainAction, error)

	// GetStateByID retrieves a state by its deterministic ID.
	GetStateByID(stateID string) (*core.State, error)

	// CreateApp registers a new application. Returns an error if the app ID already exists.
	CreateApp(entry app.AppV1) error

	// GetApp retrieves a single application by ID. Returns nil if not found.
	GetApp(appID string) (*app.AppInfoV1, error)

	// GetApps retrieves applications with optional filtering by app ID, owner wallet, and pagination.
	GetApps(appID *string, ownerWallet *string, pagination *core.PaginationParams) ([]app.AppInfoV1, core.PaginationMetadata, error)

	// GetAppCount returns the total number of applications owned by a specific wallet.
	GetAppCount(ownerWallet string) (uint64, error)

	// CreateAppSession initializes a new application session.
	CreateAppSession(session app.AppSessionV1) error

	// GetAppSession retrieves a specific session by ID.
	GetAppSession(sessionID string) (*app.AppSessionV1, error)

	// GetAppSessions retrieves filtered sessions with pagination.
	GetAppSessions(appSessionID *string, participant *string, status app.AppSessionStatus, pagination *core.PaginationParams) ([]app.AppSessionV1, core.PaginationMetadata, error)

	// UpdateAppSession updates existing session data.
	UpdateAppSession(session app.AppSessionV1) error

	// GetAppSessionBalances retrieves the total balances associated with a session.
	GetAppSessionBalances(sessionID string) (map[string]decimal.Decimal, error)

	// GetParticipantAllocations retrieves specific asset allocations per participant.
	GetParticipantAllocations(sessionID string) (map[string]map[string]decimal.Decimal, error)

	// RecordLedgerEntry logs a movement of funds within the internal ledger.
	RecordLedgerEntry(userWallet, accountID, asset string, amount decimal.Decimal) error

	// LockSessionKeyState seeds the pointer row for (user, session_key, kind) if absent and
	// locks the (session_key, kind) row for the surrounding transaction. Returns the latest
	// stored version for the caller's row and the latestExpiresAt of that version (zero time
	// when the latest version is 0, i.e. no history row exists yet). Returns
	// ErrSessionKeyNotAllowed if the key is bound to a different wallet for this kind.
	// The latestExpiresAt return lets submit handlers distinguish a reactivation
	// (prev inactive → submitted active) from a rotation (prev already active) so the
	// per-user cap can be re-checked when a revoked slot is brought back.
	LockSessionKeyState(userAddress, sessionKey string, kind SessionKeyKind) (latestVersion uint64, latestExpiresAt time.Time, err error)

	// CountSessionKeysForUser returns the number of distinct session keys recorded for the
	// wallet across both kinds. Used to enforce the per-user cap at submit time.
	CountSessionKeysForUser(userAddress string) (uint32, error)

	// StoreAppSessionKeyState stores or updates a session key state.
	StoreAppSessionKeyState(state app.AppSessionKeyStateV1) error

	GetAppSessionKeyOwner(sessionKey, appSessionId, applicationId string) (string, error)

	// SessionKeyStateExists returns the latest version of a non-expired session key state for a user.
	// Returns 0 if no state exists.
	GetLastAppSessionKeyVersion(wallet, sessionKey string) (uint64, error)

	// GetLatestSessionKeyState retrieves the latest version of a specific session key for a user.
	// Returns nil if no state exists.
	GetLastAppSessionKeyState(wallet, sessionKey string) (*app.AppSessionKeyStateV1, error)

	// GetLastAppSessionKeyStates retrieves the latest session key states for a user with optional
	// filtering. When includeInactive is false, only states whose expires_at is in the future are
	// returned; when true, all latest states are returned regardless of expiry. Results are
	// paginated; totalCount is the unpaginated total matching the filter.
	GetLastAppSessionKeyStates(wallet string, sessionKey *string, includeInactive bool, limit, offset uint32) ([]app.AppSessionKeyStateV1, uint32, error)

	// StoreChannelSessionKeyState stores or updates a channel session key state.
	StoreChannelSessionKeyState(state core.ChannelSessionKeyStateV1) error

	// GetLastChannelSessionKeyVersion returns the latest version for a (wallet, sessionKey) pair.
	// Returns 0 if no state exists.
	GetLastChannelSessionKeyVersion(wallet, sessionKey string) (uint64, error)

	// GetLastChannelSessionKeyStates retrieves the latest channel session key states for a user,
	// optionally filtered by session key. When includeInactive is false, only states whose
	// expires_at is in the future are returned; when true, all latest states are returned
	// regardless of expiry. Results are paginated; totalCount is the unpaginated total matching
	// the filter.
	GetLastChannelSessionKeyStates(wallet string, sessionKey *string, includeInactive bool, limit, offset uint32) ([]core.ChannelSessionKeyStateV1, uint32, error)

	// ValidateChannelSessionKeyForAsset checks that a valid, non-expired session key state
	// exists at its latest version for the (wallet, sessionKey) pair, includes the given asset,
	// and matches the metadata hash.
	ValidateChannelSessionKeyForAsset(wallet, sessionKey, asset, metadataHash string) (bool, error)

	// CountActiveUsers returns distinct user counts per asset within the given window.
	CountActiveUsers(window time.Duration) ([]ActiveCountByLabel, error)

	// CountActiveAppSessions returns app session counts per application within the given window.
	CountActiveAppSessions(window time.Duration) ([]ActiveCountByLabel, error)

	// GetLifetimeMetricLastTimestamp returns the most recent last_timestamp among all metrics with the given name.
	GetLifetimeMetricLastTimestamp(name string) (time.Time, error)

	// GetAppSessionsCountByLabels computes app session count deltas, upserts as lifespan metrics, and returns updated totals.
	GetAppSessionsCountByLabels() ([]AppSessionCount, error)

	// GetChannelsCountByLabels computes channel count deltas, upserts as lifespan metrics, and returns updated totals.
	GetChannelsCountByLabels() ([]ChannelCount, error)

	// GetTotalValueLocked computes TVL deltas by domain (channels, app_sessions) and asset, upserts as lifespan metrics, and returns updated totals.
	GetTotalValueLocked() ([]TotalValueLocked, error)

	// SetNodeBalance upserts the on-chain liquidity for a given blockchain and asset.
	SetNodeBalance(blockchainID uint64, asset string, value decimal.Decimal) error

	// RefreshUserEnforcedBalance recomputes the locked balance from the user's open home channel on-chain state.
	RefreshUserEnforcedBalance(wallet, asset string) error

	// GetNodeBalance returns the on-chain liquidity per blockchain and asset.
	GetNodeBalance() ([]NodeBalance, error)

	// GetUserBalanceSummary returns the off-chain liquidity requirement per blockchain and asset.
	GetUserBalanceSummary() ([]UserBalanceSummary, error)

	// UpdateUserStaked upserts the staked amount for a user on a specific blockchain.
	UpdateUserStaked(wallet string, blockchainID uint64, amount decimal.Decimal) error

	// GetTotalUserStaked returns the total staked amount for a user across all blockchains.
	GetTotalUserStaked(wallet string) (decimal.Decimal, error)

	// RecordAction inserts a new action log entry for a user.
	RecordAction(wallet string, gatedAction core.GatedAction) error

	// GetUserActionCount returns the number of actions matching the given wallet, method, and path
	// within the specified time window.
	GetUserActionCount(wallet string, gatedAction core.GatedAction, window time.Duration) (uint64, error)

	// GetUserActionCounts returns a map of gated actions to their respective counts for a user within the specified time window.
	GetUserActionCounts(userWallet string, window time.Duration) (map[core.GatedAction]uint64, error)

	// StoreContractEvent stores a blockchain event to prevent duplicate processing.
	StoreContractEvent(ev core.BlockchainEvent) error

	// GetLatestContractEventBlockNumber returns the highest block number for a given contract.
	GetLatestContractEventBlockNumber(contractAddress string, blockchainID uint64) (lastBlock uint64, err error)

	// IsContractEventPresent checks if a specific contract event has already been stored.
	IsContractEventPresent(blockchainID, blockNumber uint64, txHash string, logIndex uint32) (isPresent bool, err error)
}

type LifespanMetric struct {
	ID            string          `gorm:"column:id;primaryKey;size:66"`
	Name          string          `gorm:"column:name;not null"`
	Labels        datatypes.JSON  `gorm:"column:labels;type:text"`
	Value         decimal.Decimal `gorm:"column:value;type:varchar(78);not null"`
	LastTimestamp time.Time       `gorm:"column:last_timestamp;not null"`
	UpdatedAt     time.Time
}

type ListOptions struct {
	Offset uint32    `json:"offset,omitempty"`
	Limit  uint32    `json:"limit,omitempty"`
	Sort   *SortType `json:"sort,omitempty"` // Optional sort type (asc/desc)
}

type NodeBalance struct {
	BlockchainID string          `gorm:"column:blockchain_id"`
	Asset        string          `gorm:"column:asset"`
	Value        decimal.Decimal `gorm:"column:value"`
	LastUpdated  time.Time       `gorm:"column:last_updated"`
}

type QueryDurationObserver interface {
	ObserveDBQueryDuration(queryKind string, duration time.Duration)
}

type SessionKeyKind uint8

type SortType string

type State struct {
	// ID is a 64-character deterministic hash
	ID         string `gorm:"column:id;primaryKey;size:64"`
	Asset      string `gorm:"column:asset;not null"`
	UserWallet string `gorm:"column:user_wallet;not null"`
	Epoch      uint64 `gorm:"column:epoch;not null"`
	Version    uint64 `gorm:"column:version;not null"`

	// Transition
	TransitionType      uint8           `gorm:"column:transition_type;not null"`
	TransitionTxID      string          `gorm:"column:transition_tx_id;size:66;not null"`
	TransitionAccountID string          `gorm:"column:transition_account_id;size:66;not null"`
	TransitionAmount    decimal.Decimal `gorm:"column:transition_amount;type:varchar(78);not null"`

	// Optional channel references
	HomeChannelID   *string `gorm:"column:home_channel_id"`
	EscrowChannelID *string `gorm:"column:escrow_channel_id"`

	// Home Channel balances and flows
	// Using decimal.Decimal for int256 values and int64 for flow values
	HomeUserBalance decimal.Decimal `gorm:"column:home_user_balance;type:varchar(78)"`
	HomeUserNetFlow decimal.Decimal `gorm:"column:home_user_net_flow;default:0"`
	HomeNodeBalance decimal.Decimal `gorm:"column:home_node_balance;type:varchar(78)"`
	HomeNodeNetFlow decimal.Decimal `gorm:"column:home_node_net_flow;default:0"`

	// Escrow Channel balances and flows
	EscrowUserBalance decimal.Decimal `gorm:"column:escrow_user_balance;type:varchar(78)"`
	EscrowUserNetFlow decimal.Decimal `gorm:"column:escrow_user_net_flow;default:0"`
	EscrowNodeBalance decimal.Decimal `gorm:"column:escrow_node_balance;type:varchar(78)"`
	EscrowNodeNetFlow decimal.Decimal `gorm:"column:escrow_node_net_flow;default:0"`

	UserSig *string `gorm:"column:user_sig;type:text"`
	NodeSig *string `gorm:"column:node_sig;type:text"`

	// ApplicationID is the self-declared origin tag of the client that caused
	// this state transition (see rpc.ApplicationIDQueryParam). Advisory only.
	ApplicationID *string `gorm:"column:application_id;size:66;index:idx_channel_states_app_id"`

	// Read-only fields populated from JOINs with channels table
	HomeBlockchainID   *uint64 `gorm:"->;column:home_blockchain_id"`
	HomeTokenAddress   *string `gorm:"->;column:home_token_address"`
	EscrowBlockchainID *uint64 `gorm:"->;column:escrow_blockchain_id"`
	EscrowTokenAddress *string `gorm:"->;column:escrow_token_address"`

	CreatedAt time.Time
}

type StoreTxHandler func(DatabaseStore) error

type TotalValueLocked struct {
	Asset       string          `gorm:"column:asset"`
	Domain      string          `gorm:"column:domain"`
	Value       decimal.Decimal `gorm:"column:value"`
	LastUpdated time.Time       `gorm:"column:last_updated"`
}

type Transaction struct {
	// ID is a 64-character deterministic hash
	ID                 string               `gorm:"column:id;primaryKey;size:64"`
	Type               core.TransactionType `gorm:"column:tx_type;not null;index:idx_type;index:idx_from_to_account"`
	AssetSymbol        string               `gorm:"column:asset_symbol;not null"`
	FromAccount        string               `gorm:"column:from_account;not null;index:idx_from_account;index:idx_from_to_account"`
	ToAccount          string               `gorm:"column:to_account;not null;index:idx_to_account;index:idx_from_to_account"`
	SenderNewStateID   *string              `gorm:"column:sender_new_state_id;size:64"`
	ReceiverNewStateID *string              `gorm:"column:receiver_new_state_id;size:64"`
	Amount             decimal.Decimal      `gorm:"column:amount;type:decimal(38,18);not null"`
	CreatedAt          time.Time

	// ApplicationID is the self-declared origin tag of the client that caused
	// this transaction (see rpc.ApplicationIDQueryParam). Advisory only.
	ApplicationID *string `gorm:"column:application_id;size:66;index:idx_transactions_app_id"`
}

type UserBalance struct {
	UserWallet       string          `gorm:"column:user_wallet;primaryKey;size:42"`
	Asset            string          `gorm:"column:asset;primaryKey;size:20"`
	Balance          decimal.Decimal `gorm:"column:balance;type:varchar(78);not null"`
	Enforced         decimal.Decimal `gorm:"column:enforced;type:varchar(78);not null;default:0"`
	HomeBlockchainID uint64          `gorm:"column:home_blockchain_id;not null;default:0"`
	CreatedAt        time.Time       `gorm:"column:created_at"`
	UpdatedAt        time.Time       `gorm:"column:updated_at"`
}

type UserBalanceSummary struct {
	BlockchainID string          `gorm:"column:home_blockchain_id"`
	Asset        string          `gorm:"column:asset"`
	Total        decimal.Decimal `gorm:"column:total"`
	Underfunded  decimal.Decimal `gorm:"column:underfunded"`
	Releasable   decimal.Decimal `gorm:"column:releasable"`
}

type UserStakedV1 struct {
	UserWallet   string          `gorm:"column:user_wallet;primaryKey;not null"`
	BlockchainID uint64          `gorm:"column:blockchain_id;primaryKey;not null"`
	Amount       decimal.Decimal `gorm:"column:amount;type:varchar(78);not null"`
	CreatedAt    time.Time
	UpdatedAt    time.Time
}