Constraints & Limits

3.1 Constraints & Limits

The Modulexo system enforces explicit constraints at contract level.

These constraints are designed to:

• Prevent misuse • Enforce accounting integrity • Block invalid state transitions • Protect deterministic distribution

All constraints are implemented through revert conditions and bounded parameter logic.

---

I. Asset Enablement Constraint

Recycle execution requires asset registration.

If a token is not enabled in the Registry:

ENGINE_ASSET_NOT_ENABLED

The transaction reverts.

There is no fallback path.

---

II. Unit Availability Constraint

Recycle execution requires sufficient accounting units.

If insufficient units are available:

ENGINE_BAD_UNITS
LEDGER_INSUFFICIENT_ALLOWANCE

The transaction reverts.

Units cannot go negative.

---

III. Cap Enforcement (Ledger)

If a registry-defined cap exists:

Ledger enforces:

LEDGER_CAP_EXCEEDED

This prevents excessive allocation per beneficiary or per token.

Cap logic is enforced before state mutation.

---

IV. Self-Sponsor Restriction

The Ledger prevents:

LEDGER_SELF_SPONSOR_FORBIDDEN

This ensures providers cannot artificially create circular inventory relationships.

---

V. Engine-Only Consumption

Ledger consumption is restricted:

LEDGER_ONLY_ENGINE

Only RecyclingEngine may consume units.

Users cannot directly manipulate unit balances.

---

VI. Native Value Constraint

Recycle execution requires non-zero native payment.

If msg.value == 0:

ENGINE_NO_VALUE

Execution reverts.

---

VII. Router Safety Checks

Before routing native rails:

Engine verifies:

• Router address valid • Rail values non-zero

If invalid:

ENGINE_ROUTER_MISMATCH
ENGINE_ROUTER_ZERO_RAIL

Execution reverts.

No partial rail allocation occurs.

---

VIII. Division Safety

If distribution math would divide by zero:

ENGINE_DIV_BY_ZERO

Execution reverts.

This protects:

accNativePerWeight

from invalid calculation.

---

IX. Claim Safety

During claim:

If native transfer fails:

ENGINE_CLAIM_TRANSFER_FAILED

The entire transaction reverts.

No partial debt update.

No inconsistent state.

---

X. Parameter Bounds

RecyclingEngine parameters:

baseWeightPriceWei
decayPerDayPPM
linearGrowthSlopeWeiPerDay

May be subject to bounded validation (if implemented).

Out-of-bounds input reverts:

ENGINE_PARAM_OOB

Parameter updates emit:

ParamsSet(...)

No silent changes.

---

XI. Ownership Safeguards

Ownership transfer requires:

transferOwnership()
acceptOwnership()

Incorrect caller reverts:

O2S_NOT_OWNER
O2S_NOT_PENDING_OWNER
O2S_ZERO_ADDRESS

Ownership cannot be hijacked.

---

XII. Reentrancy Protection

RecyclingEngine includes:

ReentrancyGuardReentrantCall

Prevents nested execution during recycle or claim.

This protects distribution math and rail routing.

---

XIII. Atomicity Constraint

All recycle operations execute atomically.

If any of the following fails:

• Unit consumption • Rail routing • Weight minting • Distribution update

The entire transaction reverts.

There is no partial execution path.

---

XIV. No Negative Ledger States

The following invariants are enforced:

• recyclableBalance ≥ 0 • weightOf ≥ 0 • totalWeight ≥ 0 • rewardDebt ≤ accrued entitlement

State cannot drift negative.

---

XV. Separation Constraints

Recycle contracts cannot:

• Modify Fund share balances • Override governance • Access treasury directly

Fund contracts cannot:

• Modify recycle ledger • Alter distribution math

These boundaries prevent systemic coupling.

---

XVI. Constraint Summary

Constraint	Enforced By	Failure Result
Asset enabled	Engine	Revert
Unit availability	Ledger	Revert
Cap limit	Ledger	Revert
Non-zero native	Engine	Revert
Router integrity	Engine	Revert
Division safety	Engine	Revert
Claim transfer	Engine	Revert
Ownership rules	O2S	Revert
Reentrancy	Guard	Revert

No silent failure modes exist.