Technical Design

I. Account Model

The wM contract uses a sophisticated account model to efficiently track balances and yield information:

struct Account {
    bool isEarning;         // Whether the account is in earning mode
    uint240 balance;        // Current token balance (excluding yield)
    uint112 earningPrincipal; // Principal amount for earning accounts
    bool hasClaimRecipient; // Whether a custom recipient is set
    bool hasEarnerDetails;  // Whether admin fee settings exist
}

This structure packs related data together to minimize storage costs while maintaining all necessary information for the dual-mode system.

II. Principal-Based Accounting

A key aspect of wM's design is its principal-based accounting system for earning accounts:

Principal Conversions

When an account starts earning, its balance is converted to a principal amount:

principal = balance ÷ currentIndex (rounded down)

This principal remains constant while the account is earning, while its value in tokens grows with the index.

Present Value Calculation

The current token value of a principal is:

presentValue = principal × currentIndex

This calculation is used when checking balances and claiming yield.

Rounding Strategy

The contract employs consistent rounding rules:

• When converting from tokens to principal (adding to earning), principal is rounded DOWN
• When calculating present value (for balance displays), the value is exact
• When subtracting from earning accounts, principal is rounded UP

These rules slightly favor the protocol, creating a small buffer of excess tokens that enhances stability.

III. Supply Tracking

The contract maintains precise tracking of token supply:

• totalNonEarningSupply: Sum of all non-earning account balances
• totalEarningSupply: Sum of all earning account balances (excluding accrued yield)
• totalEarningPrincipal: Sum of all earning account principals
• Total supply = totalNonEarningSupply + totalEarningSupply
• projectedEarningSupply: The total earning supply if all accrued yield was claimed

These values are used for various calculations, including excess determination.

IV. Transfer Mechanics

The transfer system handles different scenarios based on account earning status:

Same Status Transfers

• Between earning accounts: Converts the amount to principal using the current index
• Between non-earning accounts: Simple balance transfers without conversion

Cross-Status Transfers

• From earning to non-earning: Converts from principal to tokens
• From non-earning to earning: Converts from tokens to principal
• Affects total earning and non-earning supply tracking

Each transfer type ensures that exact token amounts move between accounts while maintaining proper accounting in the appropriate mode.

V. Fee Mechanism

When enabled by an admin through the EarnerManager, fees can be taken from yield:

• Fees are a percentage (in basis points, max 10,000) of claimed yield
• Fee amounts are transferred to the admin who approved the account
• If an admin is removed from the admin list, their fee settings become invalid
• Fees are processed during the claim operation

This creates an incentive for admins to onboard and manage accounts in the system.

VI. Excess Mechanism

The WrappedMToken (wM) contract is designed to naturally accumulate "excess" $M tokens over time. This excess represents the $M tokens held by the contract above and beyond what is required to fully back all circulating wM tokens and their accrued yield entitlements. This mechanism enhances system stability and creates a value capture opportunity for the protocol.

The fundamental driver of excess accumulation stems from a mismatch in yield earning:

1. wM Contract Earns M Yield: As confirmed by its status as a major M holder and its requirement to be an approved M earner (enableEarning requires _isThisApprovedEarner), the entire balance of $M tokens held within the WrappedMToken contract continuously earns yield according to the M token's native rebasing mechanism.
2. Not All wM Holders Earn wM Yield: However, only wM holders whose accounts are explicitly set to Earning Mode (via Governance or EarnerManager approval) accrue a corresponding claimable wM yield entitlement based on their principal. Holders in Non-Earning Mode do not accrue wM yield.

The excess M balance primarily grows from:

1. Yield on M Backing Non-Earning wM (Primary Source): The M yield generated by the portion of $M tokens backing the wM held by users in Non-Earning Mode directly contributes to the excess. Since these users aren't entitled to wM yield, the M yield earned on their underlying share remains within the contract as surplus.

2. Rounding Effects during Principal Conversions (Secondary Source & Potential Deficit): The contract utilizes principal-based accounting for earners, requiring conversions between token amounts and principal values whenever balances change (e.g., wrap, unwrap, startEarningFor, stopEarningFor, cross-status transfers). This process involves rounding:

   • Tokens to Principal (e.g., starting to earn): Principal is rounded DOWN (getPrincipalAmountRoundedDown).
   • Subtracting Principal (e.g., stopping earning, transfers out): The principal equivalent of the token amount removed is rounded UP (getPrincipalAmountRoundedUp) before being deducted.
   • Yield Calculation (_getAccruedYield): The potential yield payout is based on a present value calculation rounded DOWN (getPresentAmountRoundedDown).
   • Calculating Liabilities (projectedEarningSupply): The present value of earning principals is rounded UP.

   While some rounding directions favor the protocol (contributing positively to excess over time), others (like subtracting principal rounded up during transfers/unwraps) can slightly disadvantage the protocol.

   The combination of wM's internal rounding necessities with the behavior of the underlying M token during external transfers (wrapping/unwrapping M) can lead to temporary discrepancies. Specifically, if the M token's transfer mechanism results in the wM contract sending slightly more M or receiving slightly less M than the nominal amount due to M's own rebasing logic, the wM contract might temporarily hold slightly less M than strictly required by its wM liabilities (a potential negative excess). The system is designed such that the primary sources of excess M (like yield on M backing non-earning wM and wM's own favorable internal rounding) act as a substantial buffer to cover these minor external interaction effects over time, ensuring long-term solvency.

3. Direct M Transfers: Any $M tokens sent directly to the WrappedMToken contract address (outside the wrap function) also become part of the excess.

4. Cross-Status Transfers: While involving rounding (covered above), the mechanics of transfers between earning and non-earning accounts can also contribute minor gains due to the specific rounding applied during the principal conversions involved.

The contract calculates the available excess using the excess() view function, which basically can be computed like this:

This calculation ensures that excess only represents $M tokens available after accounting for all obligations to wM holders (both earning and non-earning).

The accumulated excess $M tokens can be claimed and transferred out of the contract via the claimExcess() function.

The excessDestination is set during deployment and typically points to the Distribution Vault, creating a revenue stream for the broader protocol ecosystem, ultimately benefiting Zero token holders.

Crucially, the ability for a wM holder to be in Earning Mode depends on the same approval mechanisms (Governance list or EarnerManager admin approval) used by the M token system itself. An account must be approved in the EarnerManager (or globally via Governance) to call startEarningFor and begin accruing wM yield. This shared approval layer is fundamental to the excess mechanism, as it governs who receives wM yield, directly influencing how much of the M yield generated by the wM contract contributes to the excess pool versus being earmarked for wM earners.