ExecutionPricing

Git Source

Inherits: AccessControl, IExecutionPricing

Title: ExecutionPricing

Bounded, directional order-book pricing with persistent admission accounting.

Non-upgradeable module. Governance configures it on a paused vault after publishing depth. Reporter acknowledgments attest completed hedges; publishing alone never releases exposure.

Constants

SCALE

uint256 private constant SCALE = 1e30

BPS

uint256 private constant BPS = 10_000

MAX_LEVELS

Maximum number of executable price levels on each side.

uint256 public constant MAX_LEVELS = 20

WRITER_ROLE

Role authorized to publish observed Hyperliquid depth.

bytes32 public constant WRITER_ROLE = keccak256("WRITER_ROLE")

REPORTER_ROLE

Role authorized to acknowledge hedged exposure and margin capacity.

bytes32 public constant REPORTER_ROLE = keccak256("REPORTER_ROLE")

vault

Vault authorized to consume liquidity.

address public immutable override vault

venueOracle

Hyperliquid oracle required in the router's active market slot.

address public immutable venueOracle

reserveRecipient

Recipient of execution spread reserves.

address public immutable reserveRecipient

State Variables

maxAge

Maximum book and capacity observation age in seconds.

uint256 public maxAge

maxImpactBps

Maximum per-level deviation from the reference price in basis points.

uint256 public maxImpactBps

bufferBps

Venue fee and timing allowance incorporated into each execution rate.

uint256 public bufferBps

maxOutstanding

Governance ceiling on admitted unacknowledged EUR exposure.

uint256 public maxOutstanding

riskLimitsUpdatedAt

Governance-update timestamp; subsequent reports must be observed after this time.

uint256 public riskLimitsUpdatedAt

asks

Level[] private asks

bids

Level[] private bids

observedAt

Original source observation time; never replaced by publication time.

uint256 public observedAt

sequence

Monotonic accepted snapshot revision.

uint256 public sequence

usedBuy

Buy-side quantity consumed from the current admission epoch.

uint256 public usedBuy

usedSell

Sell-side quantity consumed from the current admission epoch.

uint256 public usedSell

admittedBuy

Lifetime admitted quantities, used as replay-safe acknowledgment cursors.

uint256 public admittedBuy

admittedSell

uint256 public admittedSell

acknowledgedBuy

Lifetime hedge-acknowledged quantities.

uint256 public acknowledgedBuy

acknowledgedSell

uint256 public acknowledgedSell

acknowledgedAt

Time of the last complete hedge acknowledgment.

uint256 public acknowledgedAt

lastConsumptionBlock

Last block in which exposure was consumed.

uint256 public lastConsumptionBlock

marginCapacity

Reporter-certified additional margin capacity in EUR and its observation time.

uint256 public marginCapacity

capacityObservedAt

uint256 public capacityObservedAt

Functions

constructor

Deploy a vault-bound pricing module with explicit initial risk ceilings.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Explicit role separation; no default economic limits are inferred.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: Applies the effects described above.

• events: Emits the events described above when applicable.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: Vault settlement is nonReentrant; publisher and reporter methods have no external state-changing callbacks.

• access: Deployment only; explicit role recipients are required.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

constructor(address[6] memory addresses, uint256[4] memory limits) ;

Parameters

version

Implementation semantic version.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Public read access.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function version() external pure returns (string memory);

Returns

updateRiskLimits

Update pricing limits on a paused vault after all admitted hedges are acknowledged.

Invalidates depth and capacity so subsequent quotes require newly observed reports.

Notes:

• security: Governance only; cannot change the terms of pending admission.

• validation: Requires paused settlement, zero outstanding admission and bounded limits.

• state-changes: Updates limits, invalidates reports and clears consumed depth.

• events: RiskLimitsUpdated.

• errors: InvalidCondition for unsettled/unpaused vault; InvalidParameter for invalid limits.

• reentrancy: Only a read-only call to the immutable vault.

• access: DEFAULT_ADMIN_ROLE.

• oracle: Fresh reports observed after the change are required before quoting.

function updateRiskLimits(uint256 age, uint256 impact, uint256 buffer, uint256 outstandingLimit)
    external
    onlyRole(DEFAULT_ADMIN_ROLE);

Parameters

_validateRiskLimits

Validate pricing risk limits.

Applies the same bounds during deployment and governance updates.

Notes:

• security: Caps source age and per-level impact.

• validation: Age 1–300, impact 1–500, buffer at most impact, positive exposure limit.

• state-changes: None.

• events: None.

• errors: InvalidParameter.

• reentrancy: None.

• access: Internal.

• oracle: None.

function _validateRiskLimits(uint256 age, uint256 impact, uint256 buffer, uint256 outstandingLimit) private pure;

Parameters

publish

Publish strictly ordered book levels with the original exchange timestamp.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: A newer observation cannot clear outstanding exposure or reset used depth prematurely.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: Applies the effects described above.

• events: Emits the events described above when applicable.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: Vault settlement is nonReentrant; publisher and reporter methods have no external state-changing callbacks.

• access: WRITER_ROLE only.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function publish(uint256 sourceTime, Level[] calldata buy, Level[] calldata sell) external onlyRole(WRITER_ROLE);

Parameters

acknowledge

Acknowledge all currently admitted exposure after canonical fills are reconciled.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Trusted reporter must reconcile fills and Base finality before calling; timestamps alone are not evidence.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: Applies the effects described above.

• events: Emits the events described above when applicable.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: Vault settlement is nonReentrant; publisher and reporter methods have no external state-changing callbacks.

• access: REPORTER_ROLE only.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function acknowledge(uint256 buy, uint256 sell, uint256 capacity, uint256 sourceTime)
    external
    onlyRole(REPORTER_ROLE);

Parameters

outstanding

Unacknowledged exposure across both directions, without speculative netting.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Public read access.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function outstanding() public view override returns (uint256);

Returns

availableCapacity

Remaining executable EUR capacity on each side, including outstanding exposure limits.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Public read access.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function availableCapacity() external view returns (uint256 buy, uint256 sell);

Returns

previewMint

Exact-USDC-input mint preview, after the vault's protocol fee.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Public read access.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function previewMint(uint256 usdcInput) external view returns (Quote memory quote);

Parameters

Returns

previewRedeem

Exact-QEURO-input normal-redemption preview, after the reference-valued protocol fee.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Public read access.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function previewRedeem(uint256 qeuroInput) external view returns (Quote memory quote);

Parameters

Returns

consumeMint

Consume buy liquidity and return minted quantity and reference backing.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: Updates consumed liquidity counters.

• events: LiquidityConsumed.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: Vault settlement is nonReentrant; publisher and reporter methods have no external state-changing callbacks.

• access: Configured vault only.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function consumeMint(uint256 netUsdc, uint256 ref) external override returns (uint256 q, uint256 backing);

Parameters

Returns

consumeRedeem

Consume sell liquidity and return the execution-valued payout.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: Updates consumed liquidity counters.

• events: LiquidityConsumed.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: Vault settlement is nonReentrant; publisher and reporter methods have no external state-changing callbacks.

• access: Configured vault only.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function consumeRedeem(uint256 q, uint256 ref) external override returns (uint256 payout);

Parameters

Returns

withdrawReserve

Transfer collected execution spreads to the immutable hedge reserve recipient.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Governance cannot redirect the reserve to an arbitrary recipient.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: Applies the effects described above.

• events: Emits the events described above when applicable.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: Vault settlement is nonReentrant; publisher and reporter methods have no external state-changing callbacks.

• access: DEFAULT_ADMIN_ROLE only.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function withdrawReserve(uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE);

Parameters

_checkLevels

Validate nonzero strictly ordered executable book levels.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _checkLevels(Level[] calldata levels, bool buy) private pure;

Parameters

_reference

Read a valid reference price for execution previews.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _reference() private view returns (uint256 ref);

Returns

_validate

Validate reference coherence, venue and observation freshness.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _validate(uint256 ref) private view;

Parameters

_rate

Calculate a conservative per-level execution rate.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _rate(uint256 price, bool buy, uint256 ref) private view returns (uint256);

Parameters

Returns

_capacity

Calculate remaining admitted capacity at the configured price limit.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _capacity(bool buy, uint256 ref) private view returns (uint256 capacity);

Parameters

Returns

_mint

Invert cumulative buy cost for an exact USDC input.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _mint(uint256 budget, uint256 ref) private view returns (uint256 q, uint256 backing);

Parameters

Returns

_redeem

Calculate cumulative sell proceeds for a QEURO input.

Uses the documented units and preserves reference-price accounting.

Notes:

• security: Uses explicit contract access boundaries and checked arithmetic.

• validation: Validates the documented preconditions; view interface reads delegate to the target contract.

• state-changes: None.

• events: None.

• errors: Propagates invalid input, freshness, capacity or downstream contract errors as applicable.

• reentrancy: No state changes.

• access: Private helper.

• oracle: Reference EUR/USD and observed venue depth where required; no oracle dependency for role and version reads.

function _redeem(uint256 q, uint256 ref) private view returns (uint256 payout);

Parameters

Returns

Events

BookPublished

event BookPublished(uint256 indexed sequence, uint256 observedAt, uint256 usedBuy, uint256 usedSell);

LiquidityConsumed

event LiquidityConsumed(
    bool indexed mint,
    uint256 quantity,
    uint256 referencePrice,
    uint256 executionUsdc,
    uint256 admittedBuy,
    uint256 admittedSell
);

HedgeAcknowledged

event HedgeAcknowledged(uint256 admittedBuy, uint256 admittedSell, uint256 capacity, uint256 observedAt);

ReserveWithdrawn

event ReserveWithdrawn(address indexed recipient, uint256 amount);

RiskLimitsUpdated

event RiskLimitsUpdated(uint256 maxAge, uint256 maxImpactBps, uint256 bufferBps, uint256 maxOutstanding);

Structs

Level

A price level with USD/EUR price and EUR quantity, both in 18 decimals.

struct Level {
    uint128 price;
    uint128 quantity;
}

Quote

Contract preview, including user output after protocol fees.

struct Quote {
    uint256 amountOut;
    uint256 executionRate;
    uint256 referenceRate;
    uint256 capacityQeuro;
    uint256 observedAt;
    uint256 sequence;
}