# Track API Contracts

Complete API contract definitions for all 4 tracks of SolaceScanScout Explorer.

## Track 1: Public Meta Explorer (No Auth Required)

### Base URL
```
/api/v1/track1
```

### Rate Limits
- **Anonymous**: 10 req/s, 100 req/min per IP
- **Caching**: 10-30s TTL via Redis

### Endpoints

#### GET /api/v1/track1/blocks/latest
Get latest blocks.

**Query Parameters:**
- `limit` (optional, default: 10, max: 50): Number of blocks to return
- `page` (optional, default: 1): Page number

**Response:**
```json
{
  "data": [
    {
      "number": 12345,
      "hash": "0x...",
      "timestamp": "2024-01-20T10:30:00Z",
      "transaction_count": 42,
      "gas_used": "15000000",
      "gas_limit": "30000000"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1000
  }
}
```

**Error Responses:**
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: RPC error

---

#### GET /api/v1/track1/txs/latest
Get latest transactions.

**Query Parameters:**
- `limit` (optional, default: 10, max: 50): Number of transactions to return
- `page` (optional, default: 1): Page number

**Response:**
```json
{
  "data": [
    {
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "block_number": 12345,
      "timestamp": "2024-01-20T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5000
  }
}
```

---

#### GET /api/v1/track1/block/:number
Get block by number.

**Path Parameters:**
- `number` (required): Block number (integer)

**Response:**
```json
{
  "data": {
    "number": 12345,
    "hash": "0x...",
    "parent_hash": "0x...",
    "timestamp": "2024-01-20T10:30:00Z",
    "transaction_count": 42,
    "gas_used": "15000000",
    "gas_limit": "30000000",
    "base_fee_per_gas": "20000000000",
    "miner": "0x...",
    "difficulty": "0"
  }
}
```

**Error Responses:**
- `404 Not Found`: Block not found
- `400 Bad Request`: Invalid block number

---

#### GET /api/v1/track1/tx/:hash
Get transaction by hash.

**Path Parameters:**
- `hash` (required): Transaction hash (0x...)

**Response:**
```json
{
  "data": {
    "hash": "0x...",
    "from": "0x...",
    "to": "0x...",
    "value": "1000000000000000000",
    "gas": "21000",
    "gas_price": "20000000000",
    "block_number": 12345,
    "block_hash": "0x...",
    "transaction_index": 0,
    "status": "success",
    "timestamp": "2024-01-20T10:30:00Z"
  }
}
```

**Error Responses:**
- `404 Not Found`: Transaction not found
- `400 Bad Request`: Invalid hash format

---

#### GET /api/v1/track1/address/:addr/balance
Get address ETH balance.

**Path Parameters:**
- `addr` (required): Ethereum address (0x...)

**Response:**
```json
{
  "data": {
    "address": "0x...",
    "balance": "1000000000000000000",
    "balance_wei": "1000000000000000000",
    "balance_ether": "1.0"
  }
}
```

**Error Responses:**
- `400 Bad Request`: Invalid address format

---

#### GET /api/v1/track1/bridge/status
Get bridge monitoring status.

**Response:**
```json
{
  "data": {
    "status": "operational",
    "chains": {
      "138": {
        "name": "Defi Oracle Meta Mainnet",
        "status": "operational",
        "last_sync": "2024-01-20T10:30:00Z"
      },
      "1": {
        "name": "Ethereum Mainnet",
        "status": "operational",
        "last_sync": "2024-01-20T10:29:00Z"
      }
    },
    "total_transfers_24h": 150,
    "total_volume_24h": "5000000000000000000000"
  }
}
```

---

## Track 2: Full Indexed Explorer (Track 2 Required)

### Base URL
```
/api/v1/track2
```

### Authentication
- **Required**: JWT token with `track: 2` claim
- **Header**: `Authorization: Bearer <token>`

### Rate Limits
- **Track 2**: 100 req/s, 1000 req/min per user

### Endpoints

#### GET /api/v1/track2/address/:addr/txs
Get address transaction history (paginated).

**Path Parameters:**
- `addr` (required): Ethereum address (0x...)

**Query Parameters:**
- `page` (optional, default: 1): Page number
- `limit` (optional, default: 20, max: 100): Items per page
- `type` (optional): Filter by type (`sent`, `received`, `all`)

**Response:**
```json
{
  "data": [
    {
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "block_number": 12345,
      "timestamp": "2024-01-20T10:30:00Z",
      "status": "success",
      "direction": "sent"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 500,
    "total_pages": 25
  }
}
```

**Error Responses:**
- `401 Unauthorized`: Missing or invalid token
- `403 Forbidden`: Insufficient track level
- `400 Bad Request`: Invalid address format

---

#### GET /api/v1/track2/address/:addr/tokens
Get address token balances (ERC-20).

**Path Parameters:**
- `addr` (required): Ethereum address (0x...)

**Response:**
```json
{
  "data": {
    "address": "0x...",
    "tokens": [
      {
        "contract": "0x...",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "balance": "1000000",
        "balance_formatted": "1.0",
        "price_usd": "1.00",
        "value_usd": "1.00"
      }
    ],
    "total_tokens": 5,
    "total_value_usd": "1500.00"
  }
}
```

---

#### GET /api/v1/track2/token/:contract
Get token information and stats.

**Path Parameters:**
- `contract` (required): Token contract address (0x...)

**Response:**
```json
{
  "data": {
    "contract": "0x...",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "total_supply": "1000000000000000",
    "holders": 5000,
    "transfers_24h": 1500,
    "volume_24h": "5000000000000"
  }
}
```

---

#### GET /api/v1/track2/search?q=
Unified search endpoint.

**Query Parameters:**
- `q` (required): Search query (address, tx hash, or block number)

**Response:**
```json
{
  "data": {
    "type": "address",
    "result": {
      "address": "0x...",
      "balance": "1000000000000000000",
      "tx_count": 500
    }
  }
}
```

**Search Types:**
- `address`: Returns address data
- `transaction`: Returns transaction data
- `block`: Returns block data

---

#### GET /api/v1/track2/address/:addr/internal-txs
Get internal transactions for an address.

**Path Parameters:**
- `addr` (required): Ethereum address (0x...)

**Query Parameters:**
- `page` (optional, default: 1): Page number
- `limit` (optional, default: 20, max: 100): Items per page

**Response:**
```json
{
  "data": [
    {
      "transaction_hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "block_number": 12345,
      "timestamp": "2024-01-20T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
```

---

## Track 3: Analytics & Forensics (Track 3 Required)

### Base URL
```
/api/v1/track3
```

### Authentication
- **Required**: JWT token with `track: 3` claim
- **Header**: `Authorization: Bearer <token>`

### Rate Limits
- **Track 3**: 50 req/s, 500 req/min per user (lower due to complexity)

### Endpoints

#### GET /api/v1/track3/analytics/flows
Get flow tracking data (address → address).

**Query Parameters:**
- `from` (optional): Source address
- `to` (optional): Destination address
- `token` (optional): Token contract address
- `start_date` (optional): Start date (ISO 8601)
- `end_date` (optional): End date (ISO 8601)
- `limit` (optional, default: 50, max: 200): Number of flows

**Response:**
```json
{
  "data": {
    "flows": [
      {
        "from": "0x...",
        "to": "0x...",
        "token": "0x...",
        "amount": "1000000000000000000",
        "count": 5,
        "first_seen": "2024-01-20T10:00:00Z",
        "last_seen": "2024-01-20T10:30:00Z"
      }
    ],
    "total_flows": 100,
    "total_volume": "5000000000000000000000"
  }
}
```

---

#### GET /api/v1/track3/analytics/bridge
Get bridge analytics and flow history.

**Query Parameters:**
- `chain_from` (optional): Source chain ID
- `chain_to` (optional): Destination chain ID
- `start_date` (optional): Start date (ISO 8601)
- `end_date` (optional): End date (ISO 8601)

**Response:**
```json
{
  "data": {
    "transfers_24h": 150,
    "volume_24h": "5000000000000000000000",
    "chains": {
      "138": {
        "outbound": 75,
        "inbound": 75,
        "volume_out": "2500000000000000000000",
        "volume_in": "2500000000000000000000"
      }
    },
    "top_tokens": [
      {
        "token": "0x...",
        "symbol": "USDC",
        "transfers": 50,
        "volume": "2000000000000000000000"
      }
    ]
  }
}
```

---

#### GET /api/v1/track3/analytics/token-distribution
Get token concentration and distribution analysis.

**Path Parameters:**
- `contract` (required): Token contract address (0x...)

**Query Parameters:**
- `top_n` (optional, default: 100): Number of top holders

**Response:**
```json
{
  "data": {
    "contract": "0x...",
    "symbol": "USDC",
    "total_supply": "1000000000000000",
    "holders": 5000,
    "distribution": {
      "top_10_percent": "60.5",
      "top_1_percent": "25.0",
      "gini_coefficient": "0.75"
    },
    "top_holders": [
      {
        "address": "0x...",
        "balance": "100000000000000",
        "percentage": "10.0"
      }
    ]
  }
}
```

---

#### GET /api/v1/track3/analytics/address-risk
Get address risk analysis.

**Path Parameters:**
- `addr` (required): Ethereum address (0x...)

**Response:**
```json
{
  "data": {
    "address": "0x...",
    "risk_score": 0.25,
    "risk_level": "low",
    "factors": {
      "suspicious_activity": false,
      "known_scam": false,
      "high_volume": true,
      "token_concentration": "medium"
    },
    "flags": []
  }
}
```

---

## Track 4: Operator Tools (Track 4 Required)

### Base URL
```
/api/v1/track4
```

### Authentication
- **Required**: JWT token with `track: 4` claim
- **Additional**: Wallet signature verification
- **Header**: `Authorization: Bearer <token>`
- **Header**: `X-Wallet-Signature: <signature>`

### Security
- **IP Whitelist**: Required
- **Role Allow-list**: Required
- **Audit Logging**: All requests logged immutably

### Rate Limits
- **Track 4**: 20 req/s, 200 req/min per user (strict limits)

### Endpoints

#### GET /api/v1/track4/operator/bridge/events
Get bridge operator events and control state.

**Query Parameters:**
- `chain_id` (optional): Filter by chain ID
- `event_type` (optional): Filter by event type
- `start_date` (optional): Start date (ISO 8601)
- `end_date` (optional): End date (ISO 8601)

**Response:**
```json
{
  "data": {
    "events": [
      {
        "id": "evt_123",
        "chain_id": 138,
        "event_type": "transfer",
        "timestamp": "2024-01-20T10:30:00Z",
        "status": "completed",
        "details": {}
      }
    ],
    "control_state": {
      "paused": false,
      "maintenance_mode": false,
      "last_update": "2024-01-20T10:30:00Z"
    }
  }
}
```

**Error Responses:**
- `401 Unauthorized`: Missing or invalid token
- `403 Forbidden`: Insufficient track level or not on IP whitelist
- `403 Forbidden`: Invalid wallet signature

---

#### GET /api/v1/track4/operator/validators
Get validator/sequencer status and information.

**Response:**
```json
{
  "data": {
    "validators": [
      {
        "address": "0x...",
        "status": "active",
        "stake": "1000000000000000000000",
        "uptime": "99.5",
        "last_block": 12345,
        "last_seen": "2024-01-20T10:30:00Z"
      }
    ],
    "total_validators": 10,
    "active_validators": 9
  }
}
```

---

#### GET /api/v1/track4/operator/contracts
Get contract registry and status.

**Query Parameters:**
- `chain_id` (optional): Filter by chain ID
- `type` (optional): Filter by contract type

**Response:**
```json
{
  "data": {
    "contracts": [
      {
        "address": "0x...",
        "chain_id": 138,
        "type": "bridge",
        "name": "CCIP Router",
        "status": "active",
        "version": "1.0.0",
        "last_verified": "2024-01-20T10:00:00Z"
      }
    ]
  }
}
```

---

#### GET /api/v1/track4/operator/protocol-state
Get protocol configuration and state.

**Response:**
```json
{
  "data": {
    "protocol_version": "1.0.0",
    "chain_id": 138,
    "config": {
      "bridge_enabled": true,
      "max_transfer_amount": "1000000000000000000000000",
      "fee_structure": {}
    },
    "state": {
      "total_locked": "50000000000000000000000000",
      "total_bridged": "10000000000000000000000000",
      "active_bridges": 2
    },
    "last_updated": "2024-01-20T10:30:00Z"
  }
}
```

---

## Common Error Responses

All endpoints may return these common errors:

### 400 Bad Request
```json
{
  "error": "bad_request",
  "message": "Invalid request parameters",
  "details": {}
}
```

### 401 Unauthorized
```json
{
  "error": "unauthorized",
  "message": "Authentication required"
}
```

### 403 Forbidden
```json
{
  "error": "forbidden",
  "message": "Insufficient permissions",
  "required_track": 2
}
```

### 404 Not Found
```json
{
  "error": "not_found",
  "message": "Resource not found"
}
```

### 429 Too Many Requests
```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "retry_after": 60
}
```

### 500 Internal Server Error
```json
{
  "error": "internal_error",
  "message": "An internal error occurred",
  "request_id": "req_123"
}
```

---

## Authentication Flow

### Wallet Authentication (Tracks 2-4)

1. **Request Nonce**
   ```
   POST /api/v1/auth/nonce
   Body: { "address": "0x..." }
   Response: { "nonce": "random_string", "expires_at": "..." }
   ```

2. **Sign and Authenticate**
   ```
   POST /api/v1/auth/wallet
   Body: {
     "address": "0x...",
     "signature": "0x...",
     "nonce": "random_string"
   }
   Response: {
     "token": "jwt_token",
     "expires_at": "...",
     "track": 2,
     "permissions": [...]
   }
   ```

3. **Use Token**
   ```
   Authorization: Bearer <jwt_token>
   ```

---

## Rate Limit Headers

All responses include rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

---

## Pagination

Paginated endpoints use consistent pagination:

**Query Parameters:**
- `page`: Page number (1-indexed)
- `limit`: Items per page

**Response:**
```json
{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 500,
    "total_pages": 25,
    "has_next": true,
    "has_prev": false
  }
}
```