# Metodo de Indices — Composicion de Economia Real en BSC

## Arquitectura de Tres Capas

```
CAPA 3: INDICE NACIONAL
  ┌─────────────────────────────────────────────────────┐
  │  VZ_ECONOMIA  =  Σ (peso_cat × Indice_Categoria)   │
  └─────────────────────────────────────────────────────┘
          ▲            ▲            ▲            ▲
          │            │            │            │
CAPA 2: INDICES DE CATEGORIA
  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
  │ IDX_AGRI │ │ IDX_PESC │ │ IDX_MIN  │ │ IDX_ENER │ ...
  │Σ(w×inst) │ │Σ(w×inst) │ │Σ(w×inst) │ │Σ(w×inst) │
  └──────────┘ └──────────┘ └──────────┘ └──────────┘
          ▲            ▲            ▲            ▲
          │            │            │            │
CAPA 1: INSTRUMENTOS INDIVIDUALES
  MANGO_g  BOCACHICO_g  ORO_g  PETROLEO_g  POLLO_g  CASABE_g ...
```

---

## 1. Instrumento (Capa 1 — ya existe)

Cada instrumento es un `CommodityToken` (extiende `GoldTokenBase`):
- Tiene un `pricePair` (bytes32) en el Oracle
- Se mintea depositando BNB en el Vault
- Fee del 1% (o 0.05% para GOLDT) va al vault GOLDVE
- Relacion 1:1 con el bien fisico (ej: 1 MANGO_g = 100 kg mango)

**No cambia nada aqui.** Los instrumentos ya funcionan.

---

## 2. Indice de Categoria (Capa 2 — NUEVO)

### 2.1 Definicion

Un indice de categoria es un **token ERC20** (`IndexToken`) cuyo precio refleja el promedio ponderado de los precios de sus instrumentos componentes.

```
Precio_Indice_Categoria = Σ (peso_i × Precio_Instrumento_i)
```

### 2.2 Constitucion del Contrato

Cada categoria tiene un `CategoryIndex` que define:

```solidity
struct Component {
    address token;        // direccion del InstrumentToken
    bytes32 pricePair;    // par en el Oracle (ej: "MANGO/USD")
    uint256 weightBps;    // peso en basis points (10000 = 100%)
    bool active;          // se puede desactivar sin recompilar
}

struct CategoryIndex {
    string name;          // "Indice Agricola Venezolano"
    string symbol;        // "IDX_AGRI"
    bytes32 indexPair;    // par sintetico en Oracle (ej: "IDX_AGRI/USD")
    Component[] components;
    uint256 totalWeightBps;  // suma de pesos (debe ser 10000)
    uint256 rebalancePeriod; // segundos entre rebalanceos
    uint256 lastRebalance;   // timestamp del ultimo rebalanceo
}
```

### 2.3 Mecanismo de Precio

El precio del indice NO se calcula on-chain en tiempo real (gas costoso).
En cambio:

1. **Oracle Centralizado (API PHP)** calcula el valor del indice off-chain
2. **Push al Oracle on-chain**: `oracle.updatePrice("IDX_AGRI/USD", valor)`
3. **IndexToken** lee el precio del Oracle igual que cualquier CommodityToken

Esto reutiliza la infraestructura existente sin nuevos patrones.

### 2.4 Mecanismo de Minteo

El usuario deposita BNB en el `IndexToken` y recibe tokens del indice:
- El contrato lee `precio_indice` del Oracle
- Calcula `tokens_a_mintear = (BNB_depositado × (1 - fee)) / precio_indice`
- El BNB va al Vault (igual que cualquier token)
- Fee del 1% va al vault GOLDVE

**El tenedor del indice NO posee los instrumentos individuales** — posee un token que refleja el valor ponderado de la canasta. Es un derivado sintetico con respaldo en BNB.

### 2.5 Rebalanceo

Los pesos se ajustan periodicamente segun cambios en la produccion real:

```
Evento de rebalanceo:
1. Oracle API recalcula pesos basado en datos de produccion actualizados
2. Owner llama a rebalance(nuevos_pesos) en el contrato
3. El contrato actualiza weightBps de cada componente
4. Se emite evento Rebalanced(nuevos_pesos, timestamp)
```

Frecuencia sugerida: **trimestral** (cada 90 dias).

---

## 3. Indice Nacional (Capa 3 — NUEVO)

### 3.1 Definicion

El indice nacional es un `IndexToken` cuyos componentes son **indices de categoria** (no instrumentos individuales).

```
Precio_Indice_Nacional = Σ (peso_cat × Precio_Indice_Categoria)
```

### 3.2 Constitucion

```solidity
struct NationalIndex {
    string name;          // "Indice de Economia Venezolana"
    string symbol;        // "VZ_ECON"
    bytes32 indexPair;    // "VZ_ECON/USD"
    CategoryComponent[] categories;
}

struct CategoryComponent {
    address indexToken;   // direccion del IndexToken de categoria
    bytes32 categoryPair; // "IDX_AGRI/USD"
    uint256 weightBps;    // peso de la categoria en la economia nacional
    bool active;
}
```

### 3.3 Ponderacion de Categorias

Basada en la contribucion al PIB real de Venezuela (aproximada):

| Categoria | Peso (%) | Fundamento |
|---|---|---|
| Energia (petroleo, gas) | 35% | Petroleo = 95% de exportaciones historicas |
| Minería | 18% | Oro, hierro, diamantes, coltan |
| Agricultura | 15% | Produccion agrícola nacional |
| Pecuario | 7% | Carne, leche, huevos |
| Pesca | 2% | Pesca artesanal e industrial |
| Nueva Economia | 3% | Reciclaje, pirolisis, economia circular |
| Dinero (FIAT) | 12% | Liquidez, remesas, tipo de cambio |
| Tokens ecosistema | 8% | GOLDT, GOLDVE, FIAT_g (derivados propios) |

**Total: 100% (10000 bps)**

> **Principio**: El sistema solo trabaja con BNB (activo puente) y derivados
> creados por el ecosistema. Criptos externas (BTC, ETH, SOL, USDT, etc.) y
> tokens de terceros (XAUT) quedan excluidos — son ruido especulativo, no
> economia real.

Estos pesos se actualizan cuando cambian las condiciones economicas reales.

---

## 4. Calculo del Valor del Indice

### 4.1 Formula General

Para un indice con N componentes:

```
Valor_Indice = Σ(i=1..N) [ peso_i × precio_i ]

donde:
  peso_i = weightBps_i / 10000
  precio_i = Oracle.getPrice(pricePair_i).price
```

### 4.2 Ejemplo: Indice Agricola

| Componente | Peso (bps) | Precio (USD) | Aporte |
|---|---|---|---|
| Maiz | 2000 | $5.50/kg | $1.10 |
| Arroz | 1500 | $0.80/kg | $0.12 |
| Cafe | 1500 | $4.20/kg | $0.63 |
| Cacao | 1000 | $3.50/kg | $0.35 |
| Mango | 800 | $1.20/kg | $0.10 |
| Yuca | 800 | $0.40/kg | $0.03 |
| Sabila | 500 | $2.00/kg | $0.10 |
| Mani | 500 | $1.80/kg | $0.09 |
| Platano | 500 | $0.60/kg | $0.03 |
| Patilla | 300 | $0.50/kg | $0.02 |
| Melon | 300 | $0.70/kg | $0.02 |
| Algodon | 300 | $1.80/kg | $0.05 |
| **TOTAL** | **10000** | | **$2.64** |

`Precio IDX_AGRI/USD = $2.64`

### 4.3 Ejemplo: Indice Nacional

| Categoria | Peso (bps) | Precio indice | Aporte |
|---|---|---|---|
| Energia | 3500 | $75.00 | $26.25 |
| Mineria | 1800 | $1800.00 | $324.00 |
| Agricultura | 1500 | $2.64 | $0.40 |
| Pecuario | 700 | $3.20 | $0.22 |
| Pesca | 200 | $1.50 | $0.03 |
| Nueva Economia | 300 | $0.80 | $0.02 |
| Dinero | 1200 | $1.00 | $0.12 |
| Tokens ecosistema | 800 | $1.20 | $0.10 |
| **TOTAL** | **10000** | | **$351.14** |

`Precio VZ_ECON/USD = $351.14`

---

## 5. Reglas de Constitucion

### 5.1 Criterios para que un instrumento entre en un indice

1. **Debe existir como token activo** en BSC (CommodityToken desplegado)
2. **Debe tener precio en el Oracle** (pricePair registrado y valido)
3. **Debe tener volumen de produccion real** documentado
4. **No puede tener peso > 25%** del indice (diversificacion obligatoria)
5. **Minimo 3 componentes** por indice de categoria

### 5.2 Criterios para que una categoria entre en el indice nacional

1. **Debe tener su IndexToken desplegado y activo**
2. **Debe tener precio en el Oracle** (indexPair registrado)
3. **No puede tener peso > 35%** del indice nacional
4. **Minimo 3 categorias** en el indice nacional

### 5.3 Eventos que disparan rebalanceo

- Cambio significativo en volumen de produccion (>20%)
- Nuevo instrumento tokenizado que entra al indice
- Instrumento que deja de producirse o se desactiva
- Cambio en la estructura economica nacional (PIIB)
- Programado: cada 90 dias

---

## 6. Flujo de Datos

```
                    OFF-CHAIN                          ON-CHAIN
                    ─────────                          ────────

  API Oracle Centralizado (PHP)
  ├── rates.php          → precios FIAT/crypto
  ├── commodities.php    → precios commodities
  ├── indices.php (NUEVO)→ calcula valor de cada indice
  │     ├── Lee precios de componentes
  │     ├── Aplica pesos del manifest
  │     ├── Calcula valor ponderado
  │     └── Retorna JSON: { "IDX_AGRI/USD": 264, "VZ_ECON/USD": 29333 }
  │
  └── Push al Oracle on-chain
        ├── oracle.updatePrice("IDX_AGRI/USD", 264000000)  // 6 decimales
        └── oracle.updatePrice("VZ_ECON/USD", 29333000000)

  Oracle.sol (BSC)
  ├── prices["MANGO/USD"]   = 1200000    ($1.20)
  ├── prices["IDX_AGRI/USD"] = 2640000   ($2.64)
  └── prices["VZ_ECON/USD"]  = 293330000 ($293.33)

  IndexToken.sol (BSC)
  ├── Lee precio de su indexPair del Oracle
  ├── Mintea tokens proporcional al BNB depositado
  └── Fee 1% → Vault → GOLDVE
```

---

## 7. Contratos Necesarios

### 7.1 IIndex.sol (interfaz)
Define la estructura de componentes y metodos comunes.

### 7.2 IndexToken.sol (token de indice)
Extiende `GoldTokenBase`. Es un ERC20 normal cuyo `pricePair` es el par sintetico del indice. No necesita logica especial — reutiliza todo el sistema existente.

### 7.3 CategoryIndexFactory.sol
Despliega `IndexToken` para cada categoria, registrando sus componentes y pesos.

### 7.4 NationalIndexFactory.sol
Despliega el `IndexToken` nacional, registrando los indices de categoria como componentes.

### 7.5 IndexRegistry.sol (opcional)
Registro on-chain de todos los indices y sus componentes para auditoria.

---

## 8. API de Indices (NUEVO endpoint)

`/api/indices.php` — calcula y retorna el valor de todos los indices:

```json
{
  "status": "success",
  "data": [
    {
      "symbol": "IDX_AGRI",
      "name": "Indice Agricola Venezolano",
      "pair": "IDX_AGRI/USD",
      "value": 2.64,
      "components": [
        {"symbol": "MAIZ", "weight": 0.20, "price": 5.50, "contribution": 1.10},
        {"symbol": "ARROZ", "weight": 0.15, "price": 0.80, "contribution": 0.12}
      ],
      "lastRebalance": "2026-03-31"
    },
    {
      "symbol": "VZ_ECON",
      "name": "Indice de Economia Venezolana",
      "pair": "VZ_ECON/USD",
      "value": 293.33,
      "categories": [
        {"symbol": "IDX_ENER", "weight": 0.30, "value": 75.00, "contribution": 22.50},
        {"symbol": "IDX_MIN", "weight": 0.15, "value": 1800.00, "contribution": 270.00}
      ]
    }
  ]
}
```

---

## 9. Ventajas del Modelo

1. **Reutiliza infraestructura existente**: IndexToken es un GoldTokenBase mas
2. **Calculo off-chain**: el Oracle API hace el trabajo pesado, on-chain solo almacena
3. **Auditable**: los componentes y pesos estan en el contrato, verificables
4. **Rebalanceable**: el owner ajusta pesos sin recompilar
5. **Componible**: el indice nacional es un indice de indices
6. **Transparente**: cualquier puede verificar como se calcula el valor
7. **Gas eficiente**: una sola llamada al Oracle por indice

---

## 10. Roadmap de Implementacion

| Fase | Que se construye | Dependencia |
|---|---|---|
| 1 | `INDICE_MANIFEST.json` con composicion de todas las categorias | Instrumentos documentados |
| 2 | `IIndex.sol` + `IndexToken.sol` | Oracle.sol existente |
| 3 | `CategoryIndexFactory.sol` | IndexToken.sol |
| 4 | Desplegar indices de categoria en BSC testnet | Factory + Oracle |
| 5 | `NationalIndexFactory.sol` | Indices de categoria desplegados |
| 6 | `api/indices.php` (calculo off-chain) | API de rates + commodities |
| 7 | Integrar push de precios de indice al Oracle | api/indices.php |
| 8 | Desplegar en mainnet | Auditoria + testnet exitoso |

---
*Metodo v1.0 — Ecosistema Criptoinversiones*
*El indice nacional es el termometro de la economia real venezolana tokenizada.*