channel_v1

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

type MemoryStore interface {
	// IsAssetSupported checks if a given asset (token) is supported on the specified blockchain.
	IsAssetSupported(asset, tokenAddress string, blockchainID uint64) (bool, error)

	// GetAssetDecimals checks if an asset exists and returns its decimals in YN
	GetAssetDecimals(asset string) (uint8, error)

	// GetTokenDecimals returns the decimals for a token on a specific blockchain
	GetTokenDecimals(blockchainID uint64, tokenAddress string) (uint8, error)
}

type MockAssetStore struct {
	mock.Mock
}

type MockMemoryStore struct {
	mock.Mock
}

type MockSigValidator struct {
	mock.Mock
}

type MockStatePacker struct {
	mock.Mock
}

type MockStore struct {
	mock.Mock
}

type SigValidator interface {
	// Verify checks that the signature is valid for the given data and wallet address.
	// Returns an error if the signature is invalid or cannot be verified.
	Verify(wallet string, data, sig []byte) error
}

type SigValidatorType string

type Store interface {
	// LockUserState locks a user's balance for update, must be used within a transaction.
	// Returns the current balance.
	LockUserState(wallet, asset string) (decimal.Decimal, error)

	// GetLastUserState retrieves the most recent state for a user's asset.
	// If signed is true, only returns states with both user and node signatures.
	// Returns nil state if no matching state exists.
	GetLastUserState(wallet, asset string, signed bool) (*core.State, 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)

	// StoreUserState persists a new user state to the database.
	// applicationID is the client-declared origin tag (rpc.ApplicationIDQueryParam);
	// empty string is persisted as NULL.
	StoreUserState(state core.State, applicationID string) error

	// EnsureNoOngoingStateTransitions validates that no blockchain operations are pending
	// that would conflict with submitting a new state transition.
	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

	// ScheduleInitiateEscrowWithdrawal queues a blockchain action to initiate
	// withdrawal from an escrow channel (triggered by escrow_lock transition).
	ScheduleInitiateEscrowWithdrawal(stateID string, chainID uint64) error

	// RecordTransaction creates a transaction record linking state transitions
	// to track the history of operations (deposits, withdrawals, transfers, etc.).
	// applicationID is the client-declared origin tag (rpc.ApplicationIDQueryParam);
	// empty string is persisted as NULL.
	RecordTransaction(tx core.Transaction, applicationID string) error

	// CreateChannel creates a new channel entity in the database.
	// This is called during channel creation before the channel exists on-chain.
	// The channel starts with OnChainStateVersion=0 to indicate it's pending blockchain confirmation.
	CreateChannel(channel core.Channel) error

	// GetChannelByID retrieves a channel by its unique identifier.
	// Returns nil if the channel doesn't exist.
	GetChannelByID(channelID string) (*core.Channel, error)

	// GetActiveHomeChannel retrieves the active home channel for a user's wallet and asset.
	// Returns nil if no home channel exists for the given wallet and asset.
	GetActiveHomeChannel(wallet, asset string) (*core.Channel, error)

	// GetNotClosedHomeChannel retrieves the home channel regardless of status as long as it
	// is not Closed. Used by GetHomeChannel so the endpoint stays functional after an
	// off-chain Finalize flips the channel to Closing.
	GetNotClosedHomeChannel(wallet, asset string) (*core.Channel, error)

	// UpdateChannel persists changes to a channel's metadata (status, version, etc).
	// The channel must already exist in the database.
	UpdateChannel(channel core.Channel) error

	// HasNonClosedHomeChannel returns true if any home channel for (wallet, asset) has a
	// status other than Closed, meaning a channel lifecycle is still in progress.
	HasNonClosedHomeChannel(wallet, asset string) (bool, 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)

	// LockSessionKeyState locks the (user, session_key, kind) pointer row for the surrounding
	// transaction, returning the current version (0 if newly created) and the expires_at of
	// the matching history row (zero time when version is 0). Callers use the expires_at to
	// distinguish a reactivation (prev inactive → submitted active) from a rotation, so the
	// per-user cap can be re-checked when a revoked slot is brought back.
	LockSessionKeyState(userAddress, sessionKey string, kind database.SessionKeyKind) (latestVersion uint64, latestExpiresAt time.Time, err error)

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

	// StoreChannelSessionKeyState persists 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 non-expired latest
	// states are returned; when true, all latest states are returned regardless of expiry.
	// Results are paginated.
	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)
}

type StoreTxHandler func(Store) error

type StoreTxProvider func(StoreTxHandler) error