Crate hypercall_settlement 

Pure settlement arithmetic for Hypercall options.

This crate computes option settlement payouts at expiry. It has no IO, no state, and no async – just deterministic arithmetic over [Decimal] values. This makes it auditable, formally verifiable, and safe to call from any context.

Invariants (verified by Kani bounded model checking)

• Non-negative intrinsic value: intrinsic_value() >= 0 for all inputs.
• Call-put parity: call_iv - put_iv = spot - strike.
• Zero-sum: for any matched long/short pair with the same parameters, long.net_pnl + short.net_pnl = 0. Settlement cannot create or destroy value.
• No panics: settle_position does not panic on any valid Decimal input.

Usage

use hypercall_settlement::{OptionType, SettlementInput, settle_position};
use rust_decimal_macros::dec;

let output = settle_position(&SettlementInput {
    option_type: OptionType::Call,
    strike: dec!(80000),
    reference_price: dec!(85000),
    position_size: dec!(1),
    entry_price: dec!(3000),
});

assert_eq!(output.intrinsic_value, dec!(5000));
assert_eq!(output.settlement_value, dec!(5000));
assert_eq!(output.cost_basis, dec!(3000));
assert_eq!(output.net_pnl, dec!(2000));

Settlement math

For a position with size s, strike K, spot at expiry S, and entry price e:

intrinsic_value = max(S - K, 0)  for calls
                  max(K - S, 0)  for puts

settlement_value = intrinsic_value * s
cost_basis       = s * e
net_pnl          = settlement_value - cost_basis

All intermediate results are quantized to 8 decimal places (MidpointAwayFromZero rounding).

Modules

api 🔒

error 🔒

events 🔒

persistence 🔒

planning 🔒

symbol 🔒

Structs

ParsedSettlementSymbol

Parsed components of an option symbol used by settlement.

PositionExpiredMessage

Canonical position-expired event payload.

SettlementEconomics

Optional economics fields that must be all present or all absent.

SettlementError

Settlement validation failure.

SettlementInput

Inputs required to settle a single option position at expiry.

SettlementInstrument

Instrument metadata needed to settle a symbol.

SettlementOutput

Settlement result for a single position.

SettlementPayoutView

Settlement payout view used by API adapters.

SettlementPersistenceIntent

Database-neutral settlement persistence intent.

SettlementPosition

Engine position selected for settlement.

Enums

OptionType

Option type: European-style call or put.

Constants

SCALE_DP 🔒

Functions

build_position_expired_message

Build the canonical position-expired event for a settlement output.

intrinsic_value

Compute the intrinsic value of an option at expiry.

normalize_payout_ids

Normalize settlement payout IDs supplied to the seen-payout API.

plan_position_settlements

Build settlement outputs for all non-zero positions in one instrument.

quantize 🔒

settle_batch

Settle a batch of positions and return per-position outputs plus total PnL.

settle_position

Settle a single option position at expiry.

settlement_cash_delta_for_margin_mode

Calculate the cash delta that settlement should apply for a margin mode.

validate_settlement_economics

Validate that optional settlement economics are either complete or absent.

validate_settlement_value

Validate that settlement cashflow matches size times intrinsic settlement price.