# 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.