core

type Asset struct {
	Name                  string  `json:"name"`                    // Asset name
	Decimals              uint8   `json:"decimals"`                // Number of decimal places at YN
	Symbol                string  `json:"symbol"`                  // Asset symbol
	SuggestedBlockchainID uint64  `json:"suggested_blockchain_id"` // Suggested blockchain network ID for this asset
	Tokens                []Token `json:"tokens"`                  // Supported tokens for the asset
}

type AssetStore interface {
	// 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 BalanceEntry struct {
	Asset    string          `json:"asset"`    // Asset symbol
	Balance  decimal.Decimal `json:"balance"`  // Balance amount
	Enforced decimal.Decimal `json:"enforced"` // On-chain enforced balance
}

type Blockchain struct {
	Name                  string `json:"name"`                    // Blockchain name
	ID                    uint64 `json:"id"`                      // Blockchain network ID
	ChannelHubAddress     string `json:"channel_hub_address"`     // Address of the ChannelHub contract on this blockchain
	BlockStep             uint64 `json:"block_step"`              // Number of blocks between each channel update
	ConfirmationDelaySecs uint32 `json:"confirmation_delay_secs"` // Seconds to wait before processing an event (0 = immediate)
}

type BlockchainClient interface {
	// Getters - Token Balance & Approval
	GetTokenBalance(asset string, walletAddress string) (decimal.Decimal, error)
	Approve(asset string, amount decimal.Decimal) (string, error)

	// Getters - ChannelsHub
	GetNodeBalance(token string) (decimal.Decimal, error)
	GetOpenChannels(user string) ([]string, error)
	GetHomeChannelData(homeChannelID string) (HomeChannelDataResponse, error)
	GetEscrowDepositData(escrowChannelID string) (EscrowDepositDataResponse, error)
	GetEscrowWithdrawalData(escrowChannelID string) (EscrowWithdrawalDataResponse, error)

	// Node vault functions
	Deposit(token string, amount decimal.Decimal) (string, error)
	Withdraw(to, token string, amount decimal.Decimal) (string, error)

	// Node lifecycle
	EnsureSigValidatorRegistered(validatorID uint8, validatorAddress string, checkOnly bool) error

	// Channel lifecycle
	Create(def ChannelDefinition, initCCS State) (string, error)
	MigrateChannelHere(def ChannelDefinition, candidate State) (string, error)
	Checkpoint(candidate State) (string, error)
	Challenge(candidate State, challengerSig []byte, challengerIdx ChannelParticipant) (string, error)
	Close(candidate State) (string, error)

	// Escrow deposit
	InitiateEscrowDeposit(def ChannelDefinition, initCCS State) (string, error)
	ChallengeEscrowDeposit(candidate State, challengerSig []byte, challengerIdx ChannelParticipant) (string, error)
	FinalizeEscrowDeposit(candidate State) (string, error)

	// Escrow withdrawal
	InitiateEscrowWithdrawal(def ChannelDefinition, initCCS State) (string, error)
	ChallengeEscrowWithdrawal(candidate State, challengerSig []byte, challengerIdx ChannelParticipant) (string, error)
	FinalizeEscrowWithdrawal(candidate State) (string, error)
}

type BlockchainEvent struct {
	ContractAddress string `json:"contract_address"`
	BlockchainID    uint64 `json:"blockchain_id"`
	Name            string `json:"name"`
	BlockNumber     uint64 `json:"block_number"`
	TransactionHash string `json:"transaction_hash"`
	LogIndex        uint32 `json:"log_index"`
	BlockHash       string `json:"block_hash"`
}

type Channel struct {
	ChannelID             string        `json:"channel_id"`                     // Unique identifier for the channel
	UserWallet            string        `json:"user_wallet"`                    // User wallet address
	Asset                 string        `json:"asset"`                          // Asset symbol (e.g. USDC, ETH)
	Type                  ChannelType   `json:"type"`                           // Type of the channel (home, escrow)
	BlockchainID          uint64        `json:"blockchain_id"`                  // Unique identifier for the blockchain
	TokenAddress          string        `json:"token_address"`                  // Address of the token used in the channel
	ChallengeDuration     uint32        `json:"challenge_duration"`             // Challenge period for the channel in seconds
	ChallengeExpiresAt    *time.Time    `json:"challenge_expires_at,omitempty"` // Timestamp when the challenge period elapses
	Nonce                 uint64        `json:"nonce"`                          // Nonce for the channel
	ApprovedSigValidators string        `json:"approved_sig_validators"`        // Bitmask representing approved signature validators for the channel
	Status                ChannelStatus `json:"status"`                         // Current status of the channel (void, open, challenged, closed)
	StateVersion          uint64        `json:"state_version"`                  // On-chain state version of the channel
}

type ChannelDefaultSigner struct {
	sign.Signer
}

type ChannelDefinition struct {
	Nonce                 uint64 `json:"nonce"`                   // A unique number to prevent replay attacks
	Challenge             uint32 `json:"challenge"`               // Challenge period for the channel in seconds
	ApprovedSigValidators string `json:"approved_sig_validators"` // Bitmask representing approved signature validators for the channel
}

type ChannelHubEventHandler interface {
	HandleNodeBalanceUpdated(context.Context, ChannelHubEventHandlerStore, *NodeBalanceUpdatedEvent) error
	HandleHomeChannelCreated(context.Context, ChannelHubEventHandlerStore, *HomeChannelCreatedEvent) error
	HandleHomeChannelMigrated(context.Context, ChannelHubEventHandlerStore, *HomeChannelMigratedEvent) error
	HandleHomeChannelCheckpointed(ctx context.Context, tx ChannelHubEventHandlerStore, hub ReadOnlyChannelHub, event *HomeChannelCheckpointedEvent) error
	HandleHomeChannelChallenged(ctx context.Context, tx ChannelHubEventHandlerStore, hub ReadOnlyChannelHub, event *HomeChannelChallengedEvent) error
	HandleHomeChannelClosed(ctx context.Context, tx ChannelHubEventHandlerStore, hub ReadOnlyChannelHub, event *HomeChannelClosedEvent) error
	HandleEscrowDepositInitiated(context.Context, ChannelHubEventHandlerStore, *EscrowDepositInitiatedEvent) error
	HandleEscrowDepositChallenged(context.Context, ChannelHubEventHandlerStore, *EscrowDepositChallengedEvent) error
	HandleEscrowDepositFinalized(context.Context, ChannelHubEventHandlerStore, *EscrowDepositFinalizedEvent) error
	HandleEscrowDepositsPurged(context.Context, ChannelHubEventHandlerStore, *EscrowDepositsPurgedEvent) error
	HandleEscrowWithdrawalInitiated(context.Context, ChannelHubEventHandlerStore, *EscrowWithdrawalInitiatedEvent) error
	HandleEscrowWithdrawalChallenged(context.Context, ChannelHubEventHandlerStore, *EscrowWithdrawalChallengedEvent) error
	HandleEscrowWithdrawalFinalized(context.Context, ChannelHubEventHandlerStore, *EscrowWithdrawalFinalizedEvent) error
}

type ChannelHubEventHandlerStore interface {
	// GetLastStateByChannelID retrieves the most recent state for a given channel.
	// If signed is true, only returns states with both user and node signatures.
	// Returns nil if no matching state exists.
	GetLastStateByChannelID(channelID string, signed bool) (*State, error)

	// GetLastUserState retrieves the most recent state for a user's asset across all
	// channels and detached chain entries (HomeChannelID nil). Returns nil if no
	// matching state exists. If signed is true, only fully co-signed states are returned.
	GetLastUserState(wallet, asset string, signed bool) (*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) (*State, error)

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

	// GetChannelByID retrieves a channel by its unique identifier.
	// Returns nil if the channel does not exist.
	GetChannelByID(channelID string) (*Channel, 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

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

	// ScheduleFinalizeEscrowDeposit schedules a finalize 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

	// 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

	// LockUserState acquires SELECT ... FOR UPDATE on the user's balance row so the
	// caller's transaction serializes against concurrent RPC paths that already lock
	// the same row before issuing receiver states. Postgres-only; SQLite is a no-op
	// in tests.
	LockUserState(wallet, asset string) (decimal.Decimal, error)

	// LockUserStateForHomeChannel locks the balance row of the user owning channelID. On
	// postgres it derives the lock key from the channel in SQL and returns the channel read
	// under that lock; on non-postgres (sqlite in tests) the snapshot is taken before the lock
	// for test compatibility. Event handlers must use this instead of a GetChannelByID +
	// LockUserState pair, which reads channel status before the lock and races a concurrent
	// submit_state finalization. Returns nil if the channel is absent.
	LockUserStateForHomeChannel(channelID string) (*Channel, error)

	// UpdateStateSigsIfMissing backfills the user and/or node signatures for a stored state
	// when the corresponding column is currently NULL. Used to repair the local record after
	// an on-chain event proves the state was enforced. Either signature may be empty to skip
	// that side; existing values are never overwritten and the call is idempotent on event replay.
	UpdateStateSigsIfMissing(channelID string, version uint64, userSig, nodeSig string) error

	// HasSignedFinalize reports whether a node-signed Finalize state exists for the given
	// home channel. Used to detect the post-Finalize lifecycle when the channel status
	// 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)

	// StoreUserState persists a user state row. Used by the event handler to record a
	// ChallengeRescue squash state derived from a closed challenged channel.
	StoreUserState(state State, applicationID string) error

	// RecordTransaction creates a transaction row linking state transitions. Used by the
	// event handler to record the ChallengeRescue transaction associated with the squash.
	RecordTransaction(tx Transaction, applicationID string) error
}

type ChannelParticipant uint8

type ChannelSessionKeySignerV1 struct {
	sign.Signer
	// contains filtered or unexported fields
}

type ChannelSessionKeyStateV1 struct {
	// ID Hash(user_address + session_key + version)
	UserAddress   string    `json:"user_address"`    // UserAddress is the user wallet address
	SessionKey    string    `json:"session_key"`     // SessionKey is the session key address for delegation
	Version       uint64    `json:"version"`         // Version is the version of the session key format
	Assets        []string  `json:"assets"`          // Assets associated with this session key
	ExpiresAt     time.Time `json:"expires_at"`      // Expiration time as unix timestamp of this session key
	UserSig       string    `json:"user_sig"`        // UserSig is the user's signature over the session key metadata to authorize the registration/update of the session key
	SessionKeySig string    `json:"session_key_sig"` // SessionKeySig is the session-key holder's signature proving possession of the key being registered.
}

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

type ChannelSigner interface {
	sign.Signer
	Type() ChannelSignerType
}

type ChannelSignerType uint8

type ChannelStatus uint8

type ChannelType uint8

type EscrowDepositChallengedEvent channelChallengedEvent

type EscrowDepositDataResponse struct {
	EscrowChannelID string `json:"escrow_channel_id"`
	Node            string `json:"node"`
	LastState       State  `json:"last_state"`
	UnlockExpiry    uint64 `json:"unlock_expiry"`
	ChallengeExpiry uint64 `json:"challenge_expiry"`
}

type EscrowDepositFinalizedEvent channelEvent

type EscrowDepositInitiatedEvent channelEvent

type EscrowDepositsPurgedEvent struct {
	// EscrowIDs holds the hex-encoded escrow IDs (== channel_id in the channels table) that were purged.
	EscrowIDs []string `json:"escrow_ids"`
}

type EscrowWithdrawalChallengedEvent channelChallengedEvent

type EscrowWithdrawalDataResponse struct {
	EscrowChannelID string `json:"escrow_channel_id"`
	Node            string `json:"node"`
	LastState       State  `json:"last_state"`
}

type EscrowWithdrawalFinalizedEvent channelEvent

type EscrowWithdrawalInitiatedEvent channelEvent

type HomeChannelChallengedEvent channelChallengedEvent

type HomeChannelCheckpointedEvent channelEvent

type HomeChannelClosedEvent channelEvent

type HomeChannelCreatedEvent channelEvent

type HomeChannelDataResponse struct {
	Definition      ChannelDefinition `json:"definition"`
	Node            string            `json:"node"`
	LastState       State             `json:"last_state"`
	ChallengeExpiry uint64            `json:"challenge_expiry"`
}

type HomeChannelMigratedEvent channelEvent

type Ledger struct {
	TokenAddress string          `json:"token_address"` // Address of the token used in this channel
	BlockchainID uint64          `json:"blockchain_id"` // Unique identifier for the blockchain
	UserBalance  decimal.Decimal `json:"user_balance"`  // User balance in the channel
	UserNetFlow  decimal.Decimal `json:"user_net_flow"` // User net flow in the channel
	NodeBalance  decimal.Decimal `json:"node_balance"`  // Node balance in the channel
	NodeNetFlow  decimal.Decimal `json:"node_net_flow"` // Node net flow in the channel
}

type NodeBalanceUpdatedEvent struct {
	BlockchainID uint64          `json:"blockchain_id"`
	Asset        string          `json:"asset"`
	Balance      decimal.Decimal `json:"balance"`
}

type NodeConfig struct {
	// NodeAddress is the Ethereum address of the nitronode operator
	NodeAddress string

	// NodeVersion is the software version of the nitronode instance
	NodeVersion string

	// SupportedSigValidators is the list of supported signature validator types
	SupportedSigValidators []ChannelSignerType

	// Blockchains is the list of supported blockchain networks
	Blockchains []Blockchain
}

type OnChainChannelSnapshot struct {
	Status             ChannelStatus // mapped from on-chain ChannelStatus enum
	StateVersion       uint64        // from ChannelMeta.lastState.version
	ChallengeExpiresAt *time.Time    // nil if no active challenge (on-chain expiry is zero)
	LastStateUserSig   string        // hex-encoded user signature for UpdateStateSigsIfMissing backfill; empty when chain has no sig populated
}

type PaginationMetadata struct {
	Page       uint32 `json:"page"`        // Current page number
	PerPage    uint32 `json:"per_page"`    // Number of items per page
	TotalCount uint32 `json:"total_count"` // Total number of items
	PageCount  uint32 `json:"page_count"`  // Total number of pages
}

type PaginationParams struct {
	Offset *uint32
	Limit  *uint32
	Sort   *string
}

type ReadOnlyChannelHub interface {
	// FetchChannel reads the authoritative on-chain channel snapshot for channelID
	// and returns an OnChainChannelSnapshot ready to overwrite the Node's local
	// row. The snapshot reflects on-chain state at RPC-read time, not
	// event-emit time.
	FetchChannel(ctx context.Context, channelID string) (*OnChainChannelSnapshot, error)
}

type State struct {
	ID              string     `json:"id"`                          // Deterministic ID (hash) of the state
	Transition      Transition `json:"transition"`                  // The transition that led to this state
	Asset           string     `json:"asset"`                       // Asset type of the state
	UserWallet      string     `json:"user_wallet"`                 // User wallet address
	Epoch           uint64     `json:"epoch"`                       // User Epoch Index
	Version         uint64     `json:"version"`                     // Version of the state
	HomeChannelID   *string    `json:"home_channel_id,omitempty"`   // Identifier for the home Channel ID
	EscrowChannelID *string    `json:"escrow_channel_id,omitempty"` // Identifier for the escrow Channel ID
	HomeLedger      Ledger     `json:"home_ledger"`                 // User and node balances for the home channel
	EscrowLedger    *Ledger    `json:"escrow_ledger,omitempty"`     // User and node balances for the escrow channel
	UserSig         *string    `json:"user_sig,omitempty"`          // User signature for the state
	NodeSig         *string    `json:"node_sig,omitempty"`          // Node signature for the state
}

type StateAdvancer interface {
	ValidateAdvancement(currentState, proposedState State) error
}

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

type StatePacker interface {
	PackState(state State) ([]byte, error)
}

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

type Token struct {
	Name         string `json:"name"`          // Token name
	Symbol       string `json:"symbol"`        // Token symbol
	Address      string `json:"address"`       // Token contract address
	BlockchainID uint64 `json:"blockchain_id"` // Blockchain network ID
	Decimals     uint8  `json:"decimals"`      // Number of decimal places
}

type Transaction struct {
	ID                 string          `json:"id"`                              // Unique transaction reference
	Asset              string          `json:"asset"`                           // Asset symbol
	TxType             TransactionType `json:"tx_type"`                         // Transaction type
	FromAccount        string          `json:"from_account"`                    // The account that sent the funds
	ToAccount          string          `json:"to_account"`                      // The account that received the funds
	SenderNewStateID   *string         `json:"sender_new_state_id,omitempty"`   // The ID of the new sender's channel state
	ReceiverNewStateID *string         `json:"receiver_new_state_id,omitempty"` // The ID of the new receiver's channel state
	Amount             decimal.Decimal `json:"amount"`                          // Transaction amount
	CreatedAt          time.Time       `json:"created_at"`                      // When the transaction was created
}

type TransactionType uint8

type Transition struct {
	Type      TransitionType  `json:"type"`       // Type of state transition
	TxID      string          `json:"tx_id"`      // Transaction ID associated with the transition
	AccountID string          `json:"account_id"` // Account identifier (varies based on transition type)
	Amount    decimal.Decimal `json:"amount"`     // Amount involved in the transition
}

type TransitionType uint8

type ValidatorRegisteredEvent struct {
	BlockchainID uint64 `json:"blockchain_id"`
	ValidatorID  uint8  `json:"validator_id"`
	// Validator is the EIP-55 checksummed hex address of the registered validator contract.
	// Always compare using strings.EqualFold or common.HexToAddress(ev.Validator).Hex()
	// to avoid silent mismatches against lowercase or non-checksummed config values.
	Validator   string `json:"validator"`
	BlockNumber uint64 `json:"block_number"` // block where the event was emitted; use as fromBlock on reconnect
}

type VerifyChannelSessionKePermissionsV1 func(walletAddr, sessionKeyAddr, metadataHash string) (bool, error)