Failure Modes

3.2 Failure Modes

Modulexo is designed so that invalid state transitions revert rather than partially execute.

This section describes how the system behaves under failure or edge conditions.

---

I. Asset Disabled

Condition

A user attempts to recycle a token not enabled in Registry.

Result

Transaction reverts:

ENGINE_ASSET_NOT_ENABLED

Effect

• No units consumed • No native routed • No weight minted

System state unchanged.

---

II. Insufficient Units

Condition

User attempts to recycle more native than available units allow.

Result

Revert:

ENGINE_BAD_UNITS
LEDGER_INSUFFICIENT_ALLOWANCE

Effect

• No partial consumption • No rail routing • No weight minted

Atomic rollback.

---

III. Ledger Cap Exceeded

Condition

Inventory provision exceeds registry-defined cap.

Result

Revert:

LEDGER_CAP_EXCEEDED

Effect

• No tokens burned • No units credited

Cap cannot be bypassed.

---

IV. Zero Native Payment

Condition

msg.value == 0 in recycle call.

Result

Revert:

ENGINE_NO_VALUE

Effect

No unit consumption. No ledger mutation.

---

V. Router Misconfiguration

Condition

Router address invalid or rails misconfigured.

Result

Revert:

ENGINE_ROUTER_MISMATCH
ENGINE_ROUTER_ZERO_RAIL

Effect

• No value split • No weight minted • No partial routing

This protects from unintended fee capture.

---

VI. Division by Zero

Condition

Distribution math would divide by zero (e.g., totalWeight == 0 in certain contexts).

Result

Revert:

ENGINE_DIV_BY_ZERO

Effect

Prevents corruption of:

accNativePerWeight

Ledger remains intact.

---

VII. Claim Transfer Failure

Condition

Native transfer during claim() fails.

Result

Revert:

ENGINE_CLAIM_TRANSFER_FAILED

Effect

• rewardDebt not updated • No partial settlement • User may retry

This prevents silent loss.

---

VIII. Reentrancy Attempt

Condition

Nested call attempt during recycle or claim.

Result

Revert:

ReentrancyGuardReentrantCall

Effect

Prevents:

• Double claim • Double mint • Rail duplication

---

IX. Ownership Misuse Attempt

Condition

Unauthorized call to owner-only function.

Result

Revert:

O2S_NOT_OWNER
O2S_NOT_PENDING_OWNER
O2S_ZERO_ADDRESS

Effect

No control escalation possible.

---

X. Governance Failure

Condition

Proposal fails quorum or vote threshold.

Result

Proposal cannot be queued or executed.

No state change occurs.

Timelock cannot execute without successful proposal.

---

XI. Bridge or FeeVault Failure (If Used)

Condition

Bridge transfer fails.

Result

Funds remain in FeeVault.

Recycle distribution unaffected.

Fund treasury may receive delayed inflow.

No impact on:

• weight ledger • accNativePerWeight • claimable balances

Execution layer remains isolated.

---

XII. Early System State (Low Participation)

Condition

Recycle rail distribution occurs when totalWeight is very low.

Result

Large proportional allocation to early weight holders.

This is mechanical.

No dynamic dampening unless parameterized.

Behavior is transparent and deterministic.

---

XIII. Parameter Misconfiguration

Condition

Owner sets extreme pricing parameters.

Result

Weight pricing changes accordingly.

Distribution math remains correct.

Economic consequences follow parameter logic.

No ledger corruption possible.

---

XIV. Contract Pauseless Design

Modulexo does not rely on pause flags in core distribution logic (unless implemented in deployment).

If no pause exists:

System continues operating deterministically.

If pause exists (per deployment):

Pause must be verifiable via public read function.

---

XV. Systemic Failure Containment

Failure in one layer does not propagate automatically.

Example:

• Fund governance failure does not affect recycle execution. • Registry error does not corrupt weight ledger. • Claim failure does not alter distribution math.

Each layer is modular.

---

XVI. Summary of Failure Handling

Failure Type	Behavior	State Integrity
Invalid asset	Revert	Preserved
Insufficient units	Revert	Preserved
Router error	Revert	Preserved
Claim transfer fail	Revert	Preserved
Governance fail	No execution	Preserved
Bridge delay	Funds isolated	Preserved

The system favors revert over partial mutation.