# 05: N-Dimensional Ellipsoidal Bonding Surface

## Source
- **Novel construction** extending Gyroscope E-CLP (2D) and 3-CLP (3D)
- **Foundation**: E-CLP A-matrix pattern, 3-CLP cubic invariant approach
- **Math**: Standard N-dimensional ellipsoid geometry

## Rationale for MYCO

This is the **core innovation** of the MYCO bonding surface. While Gyroscope demonstrated:
- 2-CLP: Concentrated LP for 2 tokens (quadratic)
- 3-CLP: Concentrated LP for 3 tokens (cubic, symmetric price bounds)
- E-CLP: Elliptical concentration for 2 tokens

Nobody has deployed an **N-asset ellipsoidal bonding surface** for token issuance. This primitive generalizes all three into a single framework where:

1. Each reserve asset occupies one dimension
2. The ellipsoid geometry controls pricing and concentration
3. Per-axis stretch factors ($\lambda_i$) give independent concentration control per asset
4. The rotation matrix $Q$ controls correlation structure between assets
5. $MYCO supply maps to the invariant $r$ (radius of the ellipsoid)

## Invariant

$$|A(\vec{v} - \vec{\text{offset}})|^2 = r^2$$

where:
- $\vec{v} = (b_1, \ldots, b_N)$ — reserve balances
- $\vec{\text{offset}} = (a_1, \ldots, a_N)$ — virtual offsets (functions of $r$)
- $A = \text{diag}(1/\lambda_i) \cdot Q^T$ — N×N transformation matrix
- $Q$ — N×N orthogonal rotation matrix
- $\lambda_i$ — per-axis stretch factors
- $r$ — scalar invariant (bonding surface "radius")

**Key property — homogeneous degree 1:**
$$r(k \cdot \vec{v}) = k \cdot r(\vec{v})$$

This ensures BPT/LP-token math works: minting is proportional to invariant increase.

## Parameters

| Parameter | Dimension | Range | Effect |
|-----------|-----------|-------|--------|
| $\lambda_i$ | N | [1, ∞) | Per-axis concentration. Higher = tighter pricing for that asset |
| $Q$ | N×N | Orthogonal | Rotation encoding correlations. Identity = axis-aligned |
| $\alpha_i$ | N | (0, 1) | Lower price bounds per asset |
| $\beta_i$ | N | (1, ∞) | Upper price bounds per asset |

**Degrees of freedom:**
- N stretch factors
- N(N-1)/2 rotation angles (via Givens rotations)
- 2N price bounds
- Total: N² + N/2 parameters — rich enough to model complex reserve structures

## Swap Math

Given a swap of token $k$ in for token $j$ out:

1. Set $b_k \leftarrow b_k + \Delta_k$
2. Solve $|A(\vec{v}' - \vec{\text{offset}})|^2 = r^2$ for $b_j'$
3. This is a **quadratic in $b_j$** (isolate terms involving $b_j$ from the norm)
4. $\Delta_j = b_j - b_j'$

The quadratic structure means swaps are computed in O(N) time (matrix-vector multiply + scalar quadratic solve).

## Minting / Bonding

Depositing reserves into the surface:

1. User deposits amounts $\Delta_1, \ldots, \Delta_N$
2. New invariant $r' = r(\vec{v} + \vec{\Delta})$
3. $\text{MYCO\_minted} = \text{supply} \cdot (r'/r - 1)$

The invariant increase depends on the **geometry** of the deposit relative to the surface. Deposits aligned with the ellipsoid's minor axes (high $\lambda$ directions) increase the invariant more per unit deposited — this is by design, as those are the "more needed" reserves.

## Geometric Interpretation

The iso-invariant surface in N-D space is an **N-dimensional ellipsoid** (offset from the origin by the virtual reserves). Trading moves along this ellipsoid. Minting expands it (larger $r$). Redeeming shrinks it.

The stretch factors $\lambda_i$ control the **eccentricity** along each axis:
- $\lambda_i = 1$ for all $i$: hypersphere (isotropic, like weighted product)
- $\lambda_i \gg 1$ for asset $i$: very concentrated in that dimension (tight pricing)
- Mixed $\lambda$: some assets tightly priced, others loosely (risk tranching effect)

The rotation matrix $Q$ controls **correlations**:
- $Q = I$: axis-aligned, no cross-asset correlation in concentration
- Non-trivial $Q$: Correlated assets share concentration (e.g., ETH and stETH)

## Properties

- **Convexity**: Ellipsoids are convex — swap paths are well-defined
- **Homogeneous degree 1**: Required for LP math
- **O(N) swaps**: Quadratic solve per swap (after O(N) matrix multiply)
- **Degenerates to E-CLP**: When N=2, recovers the Gyroscope E-CLP exactly
- **Degenerates to hypersphere**: When all $\lambda_i = 1$ and $Q = I$

## MYCO Application

This is the **primary pricing surface** for financial reserve deposits. When a user deposits ETH, USDC, DAI, or any accepted reserve token, the ellipsoid geometry determines how much $MYCO they receive.

Governance controls the surface shape:
- Increasing $\lambda_i$ for a scarce reserve makes deposits of that asset more valuable
- Rotating the surface via $Q$ can encode expected correlations
- Price bounds prevent minting at absurd ratios

## Implementation

See `src/primitives/n_dimensional_surface.py`