# MYCO Bonding Surface

Multi-asset bonding surface for **$MYCO** token issuance, combining N-dimensional ellipsoidal pricing with commitment-based minting channels and Gyroscope-inspired reserve management.

## Architecture

```
                    ┌─────────────────────┐
                    │   $MYCO Token Mint   │
                    └─────────┬───────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
    ┌─────────────┐  ┌──────────────┐  ┌────────────┐
    │  Financial   │  │ Commitment   │  │  Staking   │
    │  Reserves    │  │  Channels    │  │  Lockups   │
    │ (N assets)   │  │ (labor/sub)  │  │ (duration) │
    └──────┬──────┘  └──────┬───────┘  └─────┬──────┘
           │                │                │
    ┌──────▼──────┐  ┌──────▼───────┐  ┌─────▼──────┐
    │ Ellipsoid   │  │ Contribution │  │ Time-weight │
    │ Bonding     │  │ Oracle /     │  │ Multiplier  │
    │ Surface     │  │ Attestation  │  │ Curve       │
    │ (N-CLP)     │  │              │  │             │
    └──────┬──────┘  └──────┬───────┘  └─────┬──────┘
           │                │                │
           ▼                ▼                ▼
    ┌─────────────────────────────────────────────┐
    │           Reserve Tranching Layer            │
    │  (target weights, safety checks, rebalance)  │
    └──────────────────┬──────────────────────────┘
                       │
              ┌────────▼────────┐
              │  P-AMM Redemption│
              │  Curve + Flow    │
              │  Dampening       │
              └─────────────────┘
```

## What This Is

A research/simulation repo exploring advanced token issuance mechanics drawn from:

- **[Balancer](https://github.com/balancer)** — Weighted constant product, StableSwap, concentrated liquidity, GradualValueChange, StableSurge fees
- **[Gyroscope](https://github.com/gyrostable)** — E-CLP elliptical curves, P-AMM redemption, reserve tranching, flow dampening

The system extends these DeFi primitives into an **N-dimensional bonding surface** where $MYCO can be minted via:

1. **Financial deposits** (ETH, USDC, DAI, ...) priced on an ellipsoidal invariant surface
2. **Labor contributions** — proof-of-contribution attestations converted to tokens at governed rates
3. **Subscriptions** — recurring pledges with loyalty multipliers
4. **Staking lockups** — time-weighted bonus minting with concave (sqrt) reward curves

## Primitives

| # | Primitive | Source | Purpose |
|---|-----------|--------|---------|
| 1 | Weighted Product | Balancer | N-asset constant product invariant |
| 2 | StableSwap | Curve/Balancer | Stable-pegged invariant (Newton solver) |
| 3 | Concentrated 2-CLP | Gyroscope | Virtual-reserve concentrated liquidity |
| 4 | Elliptical CLP | Gyroscope | A-matrix elliptical pricing |
| 5 | **N-D Ellipsoid Surface** | Novel | Generalized N-asset bonding surface |
| 6 | Reserve Tranching | Gyroscope GYD | Multi-vault weight targets + safety |
| 7 | P-AMM Redemption | Gyroscope | Backing-ratio-dependent redemption pricing |
| 8 | Dynamic Weights | Balancer/QuantAMM | Time-varying parameters + oracle multipliers |
| 9 | Flow Dampening | Gyroscope | Anti-bank-run exponential outflow memory |
| 10 | Imbalance Fees | Balancer StableSurge | Median-based surge fees |
| 11 | Commitment Issuance | Novel | Labor, subscription, staking channels |

Each primitive has a math spec in `docs/` and a Python simulation in `src/primitives/` or `src/commitments/`.

## Quick Start

```bash
# Install
pip install -e ".[dev]"

# Run tests (128 tests)
pytest tests/

# Run a simulation
python -c "
from src.composed.simulator import scenario_token_launch
result = scenario_token_launch(n_assets=3, n_depositors=50, duration=90)
print(f'Final supply: {result.supply[-1]:.2f}')
print(f'Final reserve: {result.reserve_value[-1]:.2f}')
print(f'Backing ratio: {result.backing_ratio[-1]:.4f}')
"
```

## Project Structure

```
myco-bonding-curve/
├── docs/                    # Math specifications (00–12)
├── src/
│   ├── primitives/          # Core invariants and mechanisms
│   ├── commitments/         # Labor, subscription, staking channels
│   ├── composed/            # Full MycoSystem + simulator
│   └── utils/               # Fixed-point, Newton solver, linear algebra
├── notebooks/               # Interactive exploration
├── reference/               # Existing Solidity contracts (read-only)
└── tests/                   # 128 property-based tests
```

## Key Invariants

1. `supply >= 0` — never negative supply
2. `reserve_value >= 0` — never negative reserves
3. `redemption_amount <= reserve_value` — never return more than exists
4. `sum(vault_weights) == 1.0` — weights always normalized
5. `flow_tracker.current_flow >= 0` — flow tracking non-negative
6. `commitment_minted <= cap * supply` — commitment channels capped

## Relationship to payment-infra

This repo sits alongside `payment-infra` (which has the existing polynomial bonding curve + USDC reserve). This is the research/advanced design track exploring multi-asset surfaces and commitment-based issuance. Both repos coexist.

## Dependencies

- Python >= 3.11
- numpy, scipy, matplotlib, sympy
- pytest, jupyter (dev)