keeper

package
v0.0.41 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewEVMHooks added in v0.0.13 

func NewEVMHooks(k Keeper) evmtypes.EvmHooks

NewEVMHooks creates a new instance of EVMHooks.

func NewMsgServerImpl 

func NewMsgServerImpl(keeper Keeper) types.MsgServer

NewMsgServerImpl returns an implementation of the module MsgServer interface

Types

type BallotHooks added in v0.0.40 

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

BallotHooks is the x/uexecutor implementation of x/uvalidator's BallotHooks interface. It reacts to ballot lifecycle terminal transitions (EXPIRED, PASSED, REJECTED) by maintaining the per-variant audit trail in PendingInbounds and (on terminal-failure) routing expired entries to ExpiredInbounds for the future escape-hatch flow.

Currently only INBOUND_TX ballots are handled. OUTBOUND_TX ballots are intentionally NOT handled here — outbound PendingOutbounds entries persist until validators reach consensus (existing inline removal in msg_vote_outbound.go on PASSED). Operators investigate stuck outbounds by correlating each variant's ballot_id with the uvalidator ballot status separately. See plan-pending-outbound-cleanup.md for rationale.

func NewBallotHooks added in v0.0.40 

func NewBallotHooks(k Keeper) BallotHooks

NewBallotHooks constructs the BallotHooks implementation backed by the given Keeper.

func (BallotHooks) AfterBallotTerminal added in v0.0.40 

func (h BallotHooks) AfterBallotTerminal(
	ctx sdk.Context,
	ballotID string,
	ballotType uvalidatortypes.BallotObservationType,
	status uvalidatortypes.BallotStatus,
) error

AfterBallotTerminal is invoked by x/uvalidator when a ballot reaches a terminal state. For INBOUND_TX ballots this:

  1. Marks the matching variant in the PendingInbounds entry with the terminal status that was reached.
  2. If ANY variant is still PENDING, persists the updated entry and returns — the entry continues to wait on the remaining ballot(s).
  3. If ALL variants are now terminal: a. Removes the entry from PendingInbounds. b. If any variant ended PASSED, the existing post-finalization path in VoteInbound has already produced a UniversalTx — nothing more to do. c. If ALL variants ended EXPIRED/REJECTED (no UTX was ever created), copies the entry into ExpiredInbounds preserving the full per-variant audit trail for the future escape-hatch refund flow.

Hook implementations are required to be idempotent and must not block the terminal transition by returning errors for non-fatal conditions. Decode failures and "entry already cleared" cases are warning-logged and swallowed.

type EVMHooks added in v0.0.13 

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

EVMHooks implements the EVM post-processing hooks. This hook will be invoked after every EVM transaction execution and is responsible for detecting outbound events and creating UniversalTx if needed.

func (EVMHooks) PostTxProcessing added in v0.0.13 

func (h EVMHooks) PostTxProcessing(
	ctx sdk.Context,
	sender common.Address,
	msg core.Message,
	receipt *ethtypes.Receipt,
) error

PostTxProcessing is called by the EVM module after transaction execution. It inspects the receipt and creates UniversalTx + Outbound only if UniversalTxWithdraw event is detected.

type GasFeeInfo added in v0.0.30 

type GasFeeInfo struct {
	GasToken common.Address
	GasFee   *big.Int
	GasPrice *big.Int
	GasLimit *big.Int
}

GasFeeInfo holds gas-related fields fetched from the UniversalCore contract.

type Keeper 

type Keeper struct {
	Params collections.Item[types.Params]

	// PendingInbounds tracks in-flight inbounds with full per-variant
	// audit trail (which validators voted what payload, terminal status
	// per variant). Created on first vote (RecordInboundVote), removed
	// when all variants reach a terminal state (BallotHooks impl).
	// See plan-pending-inbound-cleanup.md.
	PendingInbounds collections.Map[string, types.PendingInboundEntry]

	// ExpiredInbounds preserves the per-variant audit trail of inbounds
	// whose ballots all reached EXPIRED/REJECTED without producing a UTX.
	// Consumed by the future escape-hatch refund flow.
	ExpiredInbounds collections.Map[string, types.ExpiredInboundEntry]

	// UniversalTx collection
	UniversalTx collections.Map[string, types.UniversalTx]

	// Module account manual nonce
	ModuleAccountNonce collections.Item[uint64]

	// GasPrices — deprecated, replaced by ChainMetas. Kept for genesis backward compat.
	GasPrices collections.Map[string, types.GasPrice]

	// ChainMetas collection stores aggregated chain metadata (gas price + block height) for each chain
	ChainMetas collections.Map[string, types.ChainMeta]

	// PendingOutbounds is a secondary index of outbounds with PENDING status.
	// Key: outbound ID -> Value: PendingOutboundEntry
	PendingOutbounds collections.Map[string, types.PendingOutboundEntry]
	// contains filtered or unexported fields
}

func NewKeeper 

func NewKeeper(
	cdc codec.BinaryCodec,
	storeService storetypes.KVStoreService,
	logger log.Logger,
	authority string,
	evmKeeper types.EVMKeeper,
	feemarketKeeper types.FeeMarketKeeper,
	bankKeeper types.BankKeeper,
	accountKeeper types.AccountKeeper,
	uregistryKeeper types.UregistryKeeper,
	uvalidatorKeeper types.UValidatorKeeper,
) Keeper

NewKeeper creates a new Keeper instance

func (Keeper) AbortOutbound added in v0.0.23 

func (k Keeper) AbortOutbound(ctx context.Context, utxId string, outbound types.OutboundTx, reason string) error

AbortOutbound marks an outbound as ABORTED with a reason. This signals that automatic processing has failed and manual intervention is needed.

func (Keeper) AllExpiredInbounds added in v0.0.40 

func (k Keeper) AllExpiredInbounds(goCtx context.Context, req *types.QueryAllExpiredInboundsRequest) (*types.QueryAllExpiredInboundsResponse, error)

AllExpiredInbounds implements types.QueryServer.

Returns the full per-variant audit trail of inbounds whose ballots all reached EXPIRED/REJECTED without producing a UniversalTx. Consumed by the future escape-hatch refund flow.

func (Keeper) AllPendingInbounds 

func (k Keeper) AllPendingInbounds(goCtx context.Context, req *types.QueryAllPendingInboundsRequest) (*types.QueryAllPendingInboundsResponse, error)

AllPendingInbounds implements types.QueryServer.

Returns full per-variant audit-trail entries (which validators voted what payload, terminal status per variant). This replaces the previous "list of UTX keys" response shape — callers that previously consumed inbound_ids should switch to entries[].utx_key.

func (Keeper) AttachOutboundsToExistingUniversalTx added in v0.0.13 

func (k Keeper) AttachOutboundsToExistingUniversalTx(
	ctx sdk.Context,
	receipt *evmtypes.MsgEthereumTxResponse,
	utx types.UniversalTx,
) error

AttachOutboundsToExistingUniversalTx Used when UniversalTx already exists (e.g. inbound execution) It attaches outbounds extracted from receipt to the existing utx.

func (Keeper) AttachRescueOutboundFromReceipt added in v0.0.19 

func (k Keeper) AttachRescueOutboundFromReceipt(
	ctx sdk.Context,
	receipt *evmtypes.MsgEthereumTxResponse,
	pcTx types.PCTx,
) error

AttachRescueOutboundFromReceipt scans the receipt for RescueFundsOnSourceChain events emitted by UniversalGatewayPC and, for each one found, attaches a RESCUE_FUNDS outbound to the original UTX referenced by the event's universalTxId.

Unlike normal outbounds (which create a new UTX), rescue outbounds are appended to the already-existing UTX whose funds are stuck on the source chain.

func (Keeper) BuildOutboundsFromReceipt added in v0.0.13 

func (k Keeper) BuildOutboundsFromReceipt(
	ctx context.Context,
	utxId string,
	receipt *evmtypes.MsgEthereumTxResponse,
) ([]*types.OutboundTx, error)

func (Keeper) BuildPcUniversalTxKey added in v0.0.13 

func (k Keeper) BuildPcUniversalTxKey(ctx context.Context, pc types.PCTx) (string, error)

func (Keeper) CalculateGasCost 

func (k Keeper) CalculateGasCost(
	baseFee sdkmath.LegacyDec,
	maxFeePerGas *big.Int,
	maxPriorityFeePerGas *big.Int,
	gasUsed uint64,
) (*big.Int, error)

CalculateGasCost calculates the gas cost based on EIP-1559 fee mechanism: 1. Effective Gas Price = min(maxFeePerGas, baseFee + maxPriorityFeePerGas) 2. Total Fee = gasUsed × Effective Gas Price Parameters: - baseFee: current network base fee - maxFeePerGas: maximum total fee user is willing to pay - maxPriorityFeePerGas: maximum tip to validator - gasUsed: amount of gas consumed

func (Keeper) CallExecuteUniversalTx added in v0.0.19 

func (k Keeper) CallExecuteUniversalTx(
	ctx sdk.Context,
	recipientAddr common.Address,
	sourceChain string,
	ceaAddress []byte,
	payload []byte,
	amount *big.Int,
	prc20AssetAddr common.Address,
	txId [32]byte,
) (*evmtypes.MsgEthereumTxResponse, error)

CallExecuteUniversalTx calls executeUniversalTx on a smart-contract recipient. This is used for isCEA inbounds whose recipient is a deployed contract (not a UEA).

func (Keeper) CallFactoryGetOriginForUEA added in v0.0.16 

func (k Keeper) CallFactoryGetOriginForUEA(
	ctx sdk.Context,
	from, factoryAddr, ueaAddr common.Address,
) (*types.UniversalAccountId, bool, error)

CallFactoryGetOriginForUEA checks if a given address is a UEA Returns the UniversalAccountId and a boolean indicating if the address is a UEA

func (Keeper) CallFactoryToDeployUEA 

func (k Keeper) CallFactoryToDeployUEA(
	ctx sdk.Context,
	from, factoryAddr common.Address,
	universalAccount *types.UniversalAccountId,
) (*evmtypes.MsgEthereumTxResponse, error)

CallFactoryToDeployUEA deploys a new UEA using factory contract Returns deployment response or error if deployment fails

func (Keeper) CallFactoryToGetUEAAddressForOrigin 

func (k Keeper) CallFactoryToGetUEAAddressForOrigin(
	ctx sdk.Context,
	from, factoryAddr common.Address,
	universalAccount *types.UniversalAccountId,
) (common.Address, bool, error)

CallFactoryToGetUEAAddressForOrigin calls FactoryV1.getUEAForOrigin(...)

func (Keeper) CallPRC20Deposit 

func (k Keeper) CallPRC20Deposit(
	ctx sdk.Context,
	prc20Address, to common.Address,
	amount *big.Int,
) (*evmtypes.MsgEthereumTxResponse, error)

Calls Handler Contract to deposit prc20 tokens

func (Keeper) CallPRC20DepositAutoSwap 

func (k Keeper) CallPRC20DepositAutoSwap(
	ctx sdk.Context,
	prc20Address, to common.Address,
	amount, fee, minPCOut *big.Int,
) (*evmtypes.MsgEthereumTxResponse, error)

Calls Handler Contract to deposit prc20 tokens with auto-swap. fee and minPCOut must be pre-computed by the caller (see GetDefaultFeeTierForToken / GetSwapQuote).

func (Keeper) CallUEADomainSeparator 

func (k Keeper) CallUEADomainSeparator(
	ctx sdk.Context,
	from, ueaAddr common.Address,
) ([32]byte, error)

CallUEADomainSeparator fetches the domainSeparator from the UEA contract

func (Keeper) CallUEAExecutePayload 

func (k Keeper) CallUEAExecutePayload(
	ctx sdk.Context,
	from, ueaAddr common.Address,
	universal_payload *types.UniversalPayload,
	verificationData []byte,
) (*evmtypes.MsgEthereumTxResponse, error)

CallUEAExecutePayload executes a universal payload through UEA

func (Keeper) CallUEAMigrateUEA 

func (k Keeper) CallUEAMigrateUEA(
	ctx sdk.Context,
	from, ueaAddr common.Address,
	migration_payload *types.MigrationPayload,
	signature []byte,
) (*evmtypes.MsgEthereumTxResponse, error)

CallUEAMigrateUEA migrates UEA through existing UEA

func (Keeper) CallUniversalCoreRefundUnusedGas added in v0.0.19 

func (k Keeper) CallUniversalCoreRefundUnusedGas(
	ctx sdk.Context,
	gasToken common.Address,
	amount *big.Int,
	recipient common.Address,
	withSwap bool,
	fee *big.Int,
	minPCOut *big.Int,
) (*evmtypes.MsgEthereumTxResponse, error)

CallUniversalCoreRefundUnusedGas calls refundUnusedGas on UniversalCore to return excess gas fee to the recipient. withSwap=true swaps the gas token back to PC; withSwap=false deposits PRC20 directly.

func (Keeper) CallUniversalCoreSetChainMeta added in v0.0.19 

func (k Keeper) CallUniversalCoreSetChainMeta(
	ctx sdk.Context,
	chainNamespace string,
	price *big.Int,
	chainHeight *big.Int,
) (*evmtypes.MsgEthereumTxResponse, error)

Calls UniversalCore Contract to set chain metadata (gas price + chain height). The contract uses block.timestamp for the observed-at value.

func (Keeper) CreateUniversalTx 

func (k Keeper) CreateUniversalTx(ctx context.Context, key string, utx types.UniversalTx) error

CreateUniversalTx stores a new UniversalTx

func (Keeper) CreateUniversalTxFromPCTx added in v0.0.13 

func (k Keeper) CreateUniversalTxFromPCTx(
	ctx context.Context,
	pcTx types.PCTx,
) (*types.UniversalTx, error)

func (Keeper) CreateUniversalTxFromReceiptIfOutbound added in v0.0.13 

func (k Keeper) CreateUniversalTxFromReceiptIfOutbound(
	ctx sdk.Context,
	receipt *evmtypes.MsgEthereumTxResponse,
	pcTx types.PCTx,
) error

CreateUniversalTxFromReceiptIfOutbound Creates a UniversalTx ONLY if outbound events exist in the receipt. Safe to call from ExecutePayload, EVM hooks

func (Keeper) DeductAndBurnFees 

func (k Keeper) DeductAndBurnFees(ctx context.Context, from sdk.AccAddress, gasCost *big.Int) error

DeductAndBurnFees deducts gas fees from the user's smart account and burns them. The process happens in two steps: 1. Transfer coins from user account to module account 2. Burn coins from module account Returns error if either transfer or burn fails

func (Keeper) DeductGasFeesFromReceipt added in v0.0.27 

func (k Keeper) DeductGasFeesFromReceipt(
	ctx context.Context,
	sdkCtx sdk.Context,
	recipient common.Address,
	receipt *evmtypes.MsgEthereumTxResponse,
	universalPayload *types.UniversalPayload,
) error

DeductGasFeesFromReceipt calculates and deducts gas fees from a recipient address based on the EVM receipt and universal payload parameters. Returns nil if receipt is nil (Go-level error, no EVM tx was created). Returns error with gas details if deduction fails (insufficient balance, etc).

func (Keeper) DeployUEA 

func (k Keeper) DeployUEA(ctx context.Context, evmFrom common.Address, universalAccountId *types.UniversalAccountId) ([]byte, error)

updateParams is for updating params collections of the module

func (Keeper) DeployUEAV2 

func (k Keeper) DeployUEAV2(ctx context.Context, evmFrom common.Address, universalAccountId *types.UniversalAccountId) (*evmtypes.MsgEthereumTxResponse, error)

updateParams is for updating params collections of the module

func (Keeper) ExecuteInbound 

func (k Keeper) ExecuteInbound(ctx context.Context, utx types.UniversalTx) error

func (Keeper) ExecuteInboundFunds 

func (k Keeper) ExecuteInboundFunds(ctx context.Context, utx types.UniversalTx) error

func (Keeper) ExecuteInboundFundsAndPayload 

func (k Keeper) ExecuteInboundFundsAndPayload(ctx context.Context, utx types.UniversalTx) error

func (Keeper) ExecuteInboundGas 

func (k Keeper) ExecuteInboundGas(ctx context.Context, inbound types.Inbound) error

func (Keeper) ExecuteInboundGasAndPayload 

func (k Keeper) ExecuteInboundGasAndPayload(ctx context.Context, utx types.UniversalTx) error

func (Keeper) ExecutePayload 

func (k Keeper) ExecutePayload(ctx context.Context, evmFrom common.Address, universalAccountId *types.UniversalAccountId, universalPayload *types.UniversalPayload, verificationData string) error

updateParams is for updating params collections of the module

func (Keeper) ExecutePayloadV2 

func (k Keeper) ExecutePayloadV2(ctx context.Context, evmFrom common.Address, ueaAddr common.Address, universalPayload *types.UniversalPayload, verificationData string) (*vmtypes.MsgEthereumTxResponse, error)

ExecutePayloadV2 executes a universal payload through a UEA. The caller is responsible for resolving and validating ueaAddr before calling this function.

func (*Keeper) ExportGenesis 

func (k *Keeper) ExportGenesis(ctx context.Context) *types.GenesisState

ExportGenesis exports the module's state to a genesis state.

func (Keeper) FinalizeOutbound added in v0.0.13 

func (k Keeper) FinalizeOutbound(ctx context.Context, utxId string, outbound types.OutboundTx) error

func (Keeper) GetChainMeta added in v0.0.19 

func (k Keeper) GetChainMeta(ctx context.Context, chainID string) (types.ChainMeta, bool, error)

func (Keeper) GetDefaultFeeTierForToken added in v0.0.19 

func (k Keeper) GetDefaultFeeTierForToken(ctx sdk.Context, prc20Address common.Address) (*big.Int, error)

GetDefaultFeeTierForToken reads defaultFeeTier[prc20] from UniversalCore.

func (Keeper) GetGasFeeInfoForRevertOutbound added in v0.0.30 

func (k Keeper) GetGasFeeInfoForRevertOutbound(ctx sdk.Context, prc20Addr string) (gasToken, gasFee, gasPrice, gasLimit string, err error)

GetGasFeeInfoForRevertOutbound fetches gas info for an INBOUND_REVERT outbound using the inbound's PRC20 token address. Returns string values ready for OutboundTx fields.

func (Keeper) GetGasPriceByChain added in v0.0.28 

func (k Keeper) GetGasPriceByChain(ctx sdk.Context, chainNamespace string) (*big.Int, error)

GetGasPriceByChain reads the gas price for a chain from the UniversalCore contract.

func (Keeper) GetL1GasFeeByChain added in v0.0.33 

func (k Keeper) GetL1GasFeeByChain(ctx sdk.Context, chainNamespace string) (*big.Int, error)

GetL1GasFeeByChain reads the L1 gas fee (in gas-token units) for a chain from UniversalCore. This is the data-availability fee added on top of L2 execution for chains like Optimism/Base.

func (Keeper) GetModuleAccountNonce 

func (k Keeper) GetModuleAccountNonce(ctx sdk.Context) (uint64, error)

GetModuleAccountNonce returns the current module account nonce. If not set yet, it safely defaults to 0.

func (Keeper) GetOutboundTxGasAndFees added in v0.0.30 

func (k Keeper) GetOutboundTxGasAndFees(ctx sdk.Context, prc20 common.Address, gasLimitWithBaseLimit *big.Int) (*GasFeeInfo, error)

GetOutboundTxGasAndFees calls UniversalCore.getOutboundTxGasAndFees(prc20, gasLimitWithBaseLimit) to get gasToken, gasFee, protocolFee, gasPrice, and chainNamespace. Pass gasLimitWithBaseLimit=0 to use the contract's baseLimit.

func (Keeper) GetSwapQuote added in v0.0.19 

func (k Keeper) GetSwapQuote(
	ctx sdk.Context,
	quoterAddr, prc20Address, wpcAddress common.Address,
	fee, amount *big.Int,
) (*big.Int, error)

GetSwapQuote calls QuoterV2.quoteExactInputSingle (commit=false) to get the expected output amount for swapping prc20 → wpc.

func (Keeper) GetTssFundMigrationGasLimitByChain added in v0.0.33 

func (k Keeper) GetTssFundMigrationGasLimitByChain(ctx sdk.Context, chainNamespace string) (*big.Int, error)

GetTssFundMigrationGasLimitByChain reads the TSS fund-migration gas limit for a chain from UniversalCore.

func (*Keeper) GetUeModuleAddress 

func (k *Keeper) GetUeModuleAddress(ctx context.Context) (common.Address, string)

func (Keeper) GetUniversalCoreQuoterAddress added in v0.0.19 

func (k Keeper) GetUniversalCoreQuoterAddress(ctx sdk.Context) (common.Address, error)

GetUniversalCoreQuoterAddress reads the uniswapV3Quoter address stored in UniversalCore.

func (Keeper) GetUniversalCoreWPCAddress added in v0.0.19 

func (k Keeper) GetUniversalCoreWPCAddress(ctx sdk.Context) (common.Address, error)

GetUniversalCoreWPCAddress reads the WPC (wrapped PC) address stored in UniversalCore.

func (Keeper) GetUniversalTx 

func (k Keeper) GetUniversalTx(ctx context.Context, key string) (types.UniversalTx, bool, error)

GetUniversalTx retrieves a UniversalTx by key, returns (value, found, error). UniversalStatus is always populated on-the-fly from the actual component states so it is never stale regardless of what was written to storage.

func (Keeper) HasPendingOutboundsForChain added in v0.0.28 

func (k Keeper) HasPendingOutboundsForChain(ctx context.Context, chain string) (bool, error)

HasPendingOutboundsForChain checks if there are any pending outbounds for a given chain. It walks PendingOutbounds and joins against UniversalTx to check destination_chain. Returns true on first match. This is O(n) but only called during admin-initiated migration.

func (Keeper) HasUniversalTx 

func (k Keeper) HasUniversalTx(ctx context.Context, key string) (bool, error)

HasUniversalTx checks if a UniversalTx exists

func (Keeper) IncrementModuleAccountNonce 

func (k Keeper) IncrementModuleAccountNonce(ctx sdk.Context) (uint64, error)

IncrementModuleAccountNonce increases the nonce by 1 and stores it back.

func (*Keeper) InitGenesis 

func (k *Keeper) InitGenesis(ctx context.Context, data *types.GenesisState) error

InitGenesis initializes the module's state from a genesis state.

func (Keeper) IsPendingInbound 

func (k Keeper) IsPendingInbound(ctx context.Context, inbound types.Inbound) (bool, error)

IsPendingInbound reports whether any variant for this inbound's utx_key is still being tracked (any entry exists in PendingInbounds).

func (Keeper) Logger 

func (k Keeper) Logger() log.Logger

func (Keeper) MigrateGasPricesToChainMeta added in v0.0.19 

func (k Keeper) MigrateGasPricesToChainMeta(ctx context.Context) error

MigrateGasPricesToChainMeta seeds ChainMetas from existing GasPrices entries. Called once during the chain-meta upgrade. Existing gas price data (prices, block_nums, median_index) is carried over; StoredAts defaults to zero (treated as stale until validators re-vote).

func (Keeper) MigrateUEA 

func (k Keeper) MigrateUEA(ctx context.Context, evmFrom common.Address, universalAccountId *types.UniversalAccountId, migrationPayload *types.MigrationPayload, signature string) error

updateParams is for updating params collections of the module

func (Keeper) PruneValidatorVotes added in v0.0.23 

func (k Keeper) PruneValidatorVotes(ctx context.Context, validatorAddr string)

PruneValidatorVotes removes a validator's votes from all ChainMetas entries. Called when a validator is removed from the universal validator set to prevent stale votes from influencing the median calculations.

func (Keeper) RecordInboundVote added in v0.0.40 

func (k Keeper) RecordInboundVote(
	ctx context.Context,
	inbound types.Inbound,
	voter string,
	ballotID string,
) error

RecordInboundVote idempotently records a validator's vote on an inbound by appending to the per-utx PendingInbounds entry. Creates the entry on the first vote for a given utx_key, creates a new variant on the first vote of a given (inbound payload bytes / ballotID), and appends the voter to an existing variant on subsequent votes for the same payload (deduped).

utx_key = sha256(source_chain:tx_hash:log_index) — see GetInboundUniversalTxKey. ballotID = hex(marshal(Inbound)) — see GetInboundBallotKey.

Multiple variants exist for the same utx_key when validators marshal slightly different Inbound bytes for the same logical event (different decoded fields, formatting, etc.). Each variant tracks which validators voted for that exact byte sequence so operators can investigate divergence.

func (Keeper) RecordOutboundVote added in v0.0.40 

func (k Keeper) RecordOutboundVote(
	ctx context.Context,
	outboundID string,
	observedTx types.OutboundObservation,
	voter string,
	ballotID string,
) error

RecordOutboundVote idempotently appends a validator's observation vote to the variants list of the existing PendingOutbounds entry. Creates a new variant on the first vote of a given (observed_tx bytes / ballotID), and appends the voter to an existing variant on subsequent votes for the same observation (deduped).

outboundId is the deterministic chain-derived outbound ID. ballotID = sha256(utxId:outboundId:marshal(observedTx)) — see GetOutboundBallotKey.

PRECONDITION: PendingOutbounds[outboundId] must already exist — the entry is created chain-side at outbound creation in create_outbound.go, well before any validator vote arrives. If the entry is missing, this is a programmer error and an explicit error is returned.

Multiple variants exist for the same outboundId when validators observe different destination-chain results (different success/tx_hash/error/gas). The variant data is purely an audit trail — PendingOutbounds entries are only removed when validators reach consensus (existing inline removal in msg_vote_outbound.go on PASSED). Ballot expiry does NOT remove the entry. See plan-pending-outbound-cleanup.md for design rationale.

func (Keeper) RemovePendingInbound 

func (k Keeper) RemovePendingInbound(ctx context.Context, inbound types.Inbound) error

RemovePendingInbound removes the per-utx entry. The variant-aware design only needs this on the consensus-success path inside VoteInbound (the BallotHooks impl in ballot_hooks.go performs the same removal when ALL variants reach a terminal state). Map.Remove on absent key is a no-op.

func (Keeper) RevertStuckInbound added in v0.0.40 

func (k Keeper) RevertStuckInbound(ctx context.Context, inbound types.Inbound) (utxId, outboundId string, err error)

RevertStuckInbound creates an INBOUND_REVERT outbound for an inbound whose ballot has expired without finalizing. The revert outbound enters the normal PendingOutbounds flow; UVs sign it via TSS and broadcast it to the source chain, refunding the user.

Strict precondition: the ballot for the supplied inbound must be in EXPIRED state. Admin must run MsgRecomputeBallotQuorum first to drive a stuck ballot to EXPIRED if it isn't already (recompute auto-expires when no eligible voters remain).

Returns the new UTX ID and revert outbound ID for telemetry.

func (Keeper) SchemaBuilder 

func (k Keeper) SchemaBuilder() *collections.SchemaBuilder

func (Keeper) SetChainMeta added in v0.0.19 

func (k Keeper) SetChainMeta(ctx context.Context, chainID string, chainMeta types.ChainMeta) error

func (Keeper) SetGasPrice 

func (k Keeper) SetGasPrice(ctx context.Context, chainID string, gasPrice types.GasPrice) error

SetGasPrice — deprecated. Kept for legacy migration/test compatibility.

func (Keeper) SetModuleAccountNonce 

func (k Keeper) SetModuleAccountNonce(ctx sdk.Context, nonce uint64) error

SetModuleAccountNonce allows explicitly setting the nonce (optional, for migration or testing).

func (Keeper) UpdateOutbound added in v0.0.13 

func (k Keeper) UpdateOutbound(ctx context.Context, utxId string, outbound types.OutboundTx) error

func (Keeper) UpdateParams 

func (k Keeper) UpdateParams(ctx context.Context, params types.Params) error

updateParams is for updating params collections of the module

func (Keeper) UpdateUniversalTx 

func (k Keeper) UpdateUniversalTx(
	ctx context.Context,
	key string,
	updateFn func(*types.UniversalTx) error,
) error

UpdateUniversalTx updates an existing UniversalTx in the store. It fetches the UniversalTx, applies the update function, and saves it back. Errors are rare and indicate infrastructure-level failures:

  • IAVL store read/write failure (disk I/O error, corruption)
  • UTX not found (should not happen if CreateUniversalTx succeeded prior)
  • updateFn returns an error

func (Keeper) VoteChainMeta added in v0.0.19 

func (k Keeper) VoteChainMeta(ctx context.Context, universalValidator sdk.ValAddress, observedChainId string, price, blockNumber uint64) error

VoteChainMeta processes a universal validator's vote on chain metadata (gas price + chain height).

Rules:

  1. Each vote is stamped with the current block time (storedAt) when it is recorded and either inserted (new validator) or updated in place (existing validator).
  2. The oracle is bootstrapped on the first EVM write only after at least chainMetaMinVotesForFirstWrite fresh votes have accumulated. Earlier votes are stored but do not yet drive an on-chain update — this prevents a single validator from defining the oracle's initial values.
  3. Once bootstrapped (LastAppliedChainHeight > 0), votes whose blockNumber is not strictly greater than entry.LastAppliedChainHeight are rejected — the validator must re-vote with a newer block height.
  4. When computing medians, only votes whose storedAt is within the last chainMetaVoteStalenessSeconds seconds are considered.
  5. Price median and chain-height median are computed independently (upper median = len/2).
  6. After a successful EVM call, LastAppliedChainHeight is updated.

func (Keeper) VoteInbound 

func (k Keeper) VoteInbound(ctx context.Context, universalValidator sdk.ValAddress, inbound types.Inbound) error

VoteInbound is for uvalidators for voting on synthetic asset inbound bridging. After ballot finalization, a UniversalTx is always created on-chain regardless of whether the inbound passes execution validation. This ensures the user can always query what happened to their cross-chain tx instead of having funds silently stuck in the gateway contract.

func (Keeper) VoteOnInboundBallot 

func (k Keeper) VoteOnInboundBallot(
	ctx context.Context,
	universalValidator sdk.ValAddress,
	inbound types.Inbound,
) (isFinalized bool,
	isNew bool,
	err error)

func (Keeper) VoteOnOutboundBallot added in v0.0.13 

func (k Keeper) VoteOnOutboundBallot(
	ctx context.Context,
	universalValidator sdk.ValAddress,
	utxId string,
	outboundId string,
	observedTx types.OutboundObservation,
) (isFinalized bool,
	isNew bool,
	err error)

func (Keeper) VoteOutbound added in v0.0.13 

func (k Keeper) VoteOutbound(
	ctx context.Context,
	universalValidator sdk.ValAddress,
	utxId string,
	outboundId string,
	observedTx types.OutboundObservation,
) error

VoteOutbound is for uvalidators for voting on observed outbound tx on external chain

type Querier 

type Querier struct {
	Keeper
}

func NewQuerier 

func NewQuerier(keeper Keeper) Querier

func (Querier) AllChainMetas added in v0.0.19 

func (k Querier) AllChainMetas(goCtx context.Context, req *types.QueryAllChainMetasRequest) (*types.QueryAllChainMetasResponse, error)

AllChainMetas implements types.QueryServer. Returns paginated chain meta entries for all registered chains.

func (Querier) AllGasPrices 

func (k Querier) AllGasPrices(goCtx context.Context, req *types.QueryAllGasPricesRequest) (*types.QueryAllGasPricesResponse, error)

AllGasPrices implements types.QueryServer. Sources data from ChainMetas (the new unified store) to maintain backward compatibility. Falls back to the legacy GasPrices store for entries not yet migrated.

func (Querier) AllPendingOutbounds added in v0.0.23 

func (k Querier) AllPendingOutbounds(goCtx context.Context, req *types.QueryAllPendingOutboundsRequest) (*types.QueryAllPendingOutboundsResponse, error)

AllPendingOutbounds implements types.QueryServer. Returns all pending outbound entries with full outbound data, sorted by block height. Uses pagination.reverse for descending order (default: ascending by created_at).

func (Querier) AllUniversalTx 

func (k Querier) AllUniversalTx(goCtx context.Context, req *types.QueryAllUniversalTxRequest) (*types.QueryAllUniversalTxResponse, error)

AllUniversalTx implements types.QueryServer.

func (Querier) ChainMeta added in v0.0.19 

func (k Querier) ChainMeta(goCtx context.Context, req *types.QueryChainMetaRequest) (*types.QueryChainMetaResponse, error)

ChainMeta implements types.QueryServer. Returns the aggregated chain metadata (gas price + chain height) for a specific chain.

func (Querier) GasPrice 

func (k Querier) GasPrice(goCtx context.Context, req *types.QueryGasPriceRequest) (*types.QueryGasPriceResponse, error)

GasPrice implements types.QueryServer. Sources data from ChainMetas (the new unified store) to maintain backward compatibility.

func (Querier) GetPendingOutbound added in v0.0.23 

func (k Querier) GetPendingOutbound(goCtx context.Context, req *types.QueryGetPendingOutboundRequest) (*types.QueryGetPendingOutboundResponse, error)

GetPendingOutbound implements types.QueryServer. Returns a single pending outbound entry by ID, along with the full outbound data from the parent UTX.

func (Querier) GetUniversalTx 

func (k Querier) GetUniversalTx(goCtx context.Context, req *types.QueryGetUniversalTxRequest) (*types.QueryGetUniversalTxResponse, error)

GetUniversalTx implements types.QueryServer.

func (Querier) InboundKeys added in v0.0.40 

func (k Querier) InboundKeys(goCtx context.Context, req *types.QueryInboundKeysRequest) (*types.QueryInboundKeysResponse, error)

InboundKeys derives the canonical UTX id and inbound ballot id for the given inbound, applying the same canonicalization the vote path uses. Lets off-chain validators read the keys from the chain instead of re-implementing the rules.

func (Querier) OutboundBallotKey added in v0.0.40 

func (k Querier) OutboundBallotKey(goCtx context.Context, req *types.QueryOutboundBallotKeyRequest) (*types.QueryOutboundBallotKeyResponse, error)

OutboundBallotKey derives the canonical outbound ballot id for the given observation. The observed tx hash is canonicalized against the outbound's destination chain, which is looked up from the stored UTX/outbound so the caller can't supply the wrong chain.

func (Querier) Params 

func (k Querier) Params(c context.Context, req *types.QueryParamsRequest) (*types.QueryParamsResponse, error)

type QuerierV2 added in v0.0.16 

type QuerierV2 struct {
	Keeper
}

QuerierV2 implements the uexecutor.v2 QueryServer, returning native types.

func NewQuerierV2 added in v0.0.16 

func NewQuerierV2(keeper Keeper) QuerierV2

func (QuerierV2) GetUniversalTx added in v0.0.16 

func (k QuerierV2) GetUniversalTx(goCtx context.Context, req *typesv2.QueryGetUniversalTxRequest) (*typesv2.QueryGetUniversalTxResponse, error)

GetUniversalTx implements typesv2.QueryServer. Returns the native UniversalTx type (not legacy) for the given ID.

type UValidatorHooks added in v0.0.23 

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

UValidatorHooks implements uvalidatortypes.UValidatorHooks for the uexecutor module. It prunes removed validators' votes from GasPrices and ChainMetas.

func NewUValidatorHooks added in v0.0.23 

func NewUValidatorHooks(k Keeper) UValidatorHooks

func (UValidatorHooks) AfterValidatorAdded added in v0.0.23 

func (h UValidatorHooks) AfterValidatorAdded(ctx sdk.Context, valAddr sdk.ValAddress)

func (UValidatorHooks) AfterValidatorRemoved added in v0.0.23 

func (h UValidatorHooks) AfterValidatorRemoved(ctx sdk.Context, valAddr sdk.ValAddress)

func (UValidatorHooks) AfterValidatorStatusChanged added in v0.0.23 

func (h UValidatorHooks) AfterValidatorStatusChanged(ctx sdk.Context, valAddr sdk.ValAddress, oldStatus, newStatus uvalidatortypes.UVStatus)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.