Struct PixGlobalConfig 

pub struct PixGlobalConfig {
    pub num_ssa_parts: usize,
    pub ssa_part_size: usize,
    pub additional_shares: Option<usize>,
    pub max_ssas_per_request: usize,
    pub reconstructor: PixReconstructorConfig,
}

Global configuration for the Protocol for Incentivization of eXits (PIX).

Fields

num_ssa_parts: usize

Number of parts an SSA is split into.

This scales will with the CPU parallelism.

Defaults to DEFAULT_PIX_POLYS_PER_SSA, which is also what IncomingSessionPixConfig::quota_range is derived from — changing this without widening the peer Exit’s quota_range accordingly will get the Session rejected.

The range below bounds this field alone. What actually costs is the product with ssa_part_size, which validation bounds separately at 4× the profiled operating point — see validate_pix_dimension_product.

ssa_part_size: usize

Number of shares required to reconstruct an SSA part.

This does not scale well with CPU parallelism.

Defaults to DEFAULT_PIX_SHARES_PER_POLY. See num_ssa_parts for the interaction with the Exit’s accepted quota range, and validate_pix_dimension_product for the bound on the two together. Capped at 255 because the threshold is one byte of the negotiated PixParams word — see MAX_POLY_THRESHOLD.

additional_shares: Option<usize>

Number of shares sent in addition to ssa_part_size to reconstruct an SSA part.

This is used to account for potential packet loss but makes it take longer for the other side to reconstruct the entire SSA from all its parts. This is because if no packet loss is present, the other side can reconstruct the SSA from fewer shares.

Leave unset unless you have measured your return-path loss. None derives the surplus from ssa_part_size via default_surplus_for, which sizes it to absorb 20 % of a polynomial’s shares going missing. Read surplus_shares for the resolved value.

It is a ratio because the physics is a ratio: a polynomial reconstructs from the first ssa_part_size distinct shares to arrive out of ssa_part_size + surplus emitted, so surviving loss rate p needs surplus >= ssa_part_size · p/(1−p). Setting an absolute count therefore means a different loss tolerance at every threshold — a flat 20 covers 24 % at ssa_part_size 64 but 56 % at 16, where it exceeds the shares it insures and is rejected.

The factor is what matters, because it is what this costs. A polynomial leaves the generator’s queue at ssa_part_size + surplus shares whether or not any were lost, so this is service the Exit performs in every case — and since the surplus travels to the peer as part of the negotiated PixParams, the per-SSA quota counts it and the deposit pays for it. It buys loss tolerance, and it is charged for like any other insurance: on purchase, not on claim.

Raising it therefore costs money rather than earning free service, which is the way round it should be. It used to be the other way: the surplus was excluded from the quota, so the rational Entry raised this dial to take traffic it was not billed for.

Capped at 255 because it is the other byte of that word, and at ssa_part_size because insurance costing more than the payload is a misconfiguration rather than a preference.

max_ssas_per_request: usize

Maximum number of SSA commitments this node, acting as an Entry, accepts in a single SsaRequest from an Exit.

This is a protection against a misbehaving Exit rather than a preference: each accepted entry costs a full client commitment, its own burst of SsaCommit packets and its own on-chain deposit, so an uncapped request would let one inbound packet amplify into minutes of CPU and as many simultaneous deposits as the wire format admits (27). An over-cap request is rejected in full before any of that work starts.

Must be at least the ssas_per_request of every Exit this node uses. The batch size is not negotiated — the Exit cannot learn this value — so an Exit batching above it has every request rejected, and every such Session is lost. The refusal is reported to the Exit as an UnacceptablePixParams SessionError so it fails in about a round trip rather than as a deposit timeout minutes later, but raising the Exit side still requires raising this in step.

Unlike its neighbours this is not a dimension, so validate_pix_dimension_product ignores it.

Defaults to 2, minimum 1, maximum 20 (MAX_SSA_BATCH_SIZE).

reconstructor: PixReconstructorConfig

Exit-side SSA reconstructor configuration.

Nested rather than flattened so the whole PIX surface stays under one key, and so that Exit-side capacity does not intermix with the Entry-side dimensions above.

Implementations

impl PixGlobalConfig

pub fn surplus_shares(&self) -> usize

Surplus shares per polynomial: the operator’s value if set, otherwise derived from ssa_part_size.

Every reader must go through this rather than the field. The field is Option precisely because serde cannot express “default to a function of a sibling”, so the field alone is not the configuration — reading it directly is how the unset case would silently become zero surplus, i.e. no loss tolerance at all.

Trait Implementations

impl Clone for PixGlobalConfig

fn clone(&self) -> PixGlobalConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for PixGlobalConfig

impl Debug for PixGlobalConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PixGlobalConfig

fn default() -> Self

Return PixGlobalConfig { num_ssa_parts: DEFAULT_PIX_POLYS_PER_SSA as usize, ssa_part_size: DEFAULT_PIX_SHARES_PER_POLY as usize, additional_shares: Default::default(), max_ssas_per_request: DEFAULT_MAX_SSAS_PER_SSA_REQUEST, reconstructor: Default::default() }

impl PartialEq for PixGlobalConfig

fn eq(&self, other: &PixGlobalConfig) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PixGlobalConfig

impl Validate for PixGlobalConfig

fn validate(&self) -> Result<(), ValidationErrors>

impl<'v_a> ValidateArgs<'v_a> for PixGlobalConfig

type Args = ()

fn validate_with_args(&self, args: Self::Args) -> Result<(), ValidationErrors>