dchain/docs/api/chain.md

# Chain API

Эндпоинты для чтения блокчейна: блоки, транзакции, балансы, идентичности, валидаторы.

## Статистика сети

### `GET /api/netstats`

Агрегированная статистика сети.

```bash
curl http://localhost:8081/api/netstats
```

```json
{
  "total_blocks": 1024,
  "total_txs": 4821,
  "validator_count": 3,
  "relay_count": 1,
  "total_supply_ut": 10000000000
}
```

---

## Блоки

### `GET /api/blocks?limit=N`

Последние `N` блоков (по умолчанию 20).

```bash
curl "http://localhost:8081/api/blocks?limit=10"
```

```json
[
  {
    "index": 1024,
    "hash": "a1b2c3...",
    "prev_hash": "...",
    "timestamp": 1710000000,
    "validator": "03abcd...",
    "tx_count": 3,
    "total_fees_ut": 15000
  },
  ...
]
```

---

### `GET /api/block/{index}`

Детали блока по высоте.

```bash
curl http://localhost:8081/api/block/1024
```

```json
{
  "index": 1024,
  "hash": "a1b2c3...",
  "prev_hash": "...",
  "timestamp": 1710000000,
  "validator": "03abcd...",
  "transactions": [
    {
      "id": "tx-abc123",
      "type": "TRANSFER",
      "from": "03...",
      "to": "04...",
      "amount_ut": 1000000,
      "fee_ut": 1000
    }
  ]
}
```

---

## Транзакции

### `GET /api/txs/recent?limit=N`

Последние транзакции (по умолчанию 20).

```bash
curl "http://localhost:8081/api/txs/recent?limit=5"
```

---

### `GET /api/tx/{txid}`

Транзакция по ID.

```bash
curl http://localhost:8081/api/tx/tx-abc123def456
```

```json
{
  "id": "tx-abc123",
  "block_index": 1024,
  "type": "CALL_CONTRACT",
  "from": "03abcd...",
  "timestamp": 1710000000,
  "payload": { ... },
  "signature": "..."
}
```

---

### `POST /api/tx`

Отправить подписанную транзакцию.

```bash
curl -X POST http://localhost:8081/api/tx \
  -H "Content-Type: application/json" \
  -d '{"type":"TRANSFER","from":"03...","payload":{...},"signature":"..."}'
```

```json
{"id": "tx-abc123", "status": "accepted"}
```

---

## Chain API v2

Расширенный API для работы с транзакциями.

### `GET /v2/chain/transactions/{tx_id}`

```bash
curl http://localhost:8081/v2/chain/transactions/tx-abc123
```

```json
{
  "id": "tx-abc123",
  "block_index": 1024,
  "payload": { ... },
  "payload_hex": "...",
  "signature_hex": "..."
}
```

---

### `GET /v2/chain/accounts/{account_id}/transactions`

Транзакции для аккаунта с пагинацией.

**Query параметры:**
| Параметр | По умолчанию | Описание |
|---------|------------|---------|
| `limit` | 100 | Максимум (max 1000) |
| `after_block` | — | Только блоки после N |
| `before_block` | — | Только блоки до N |
| `order` | `desc` | `asc` или `desc` |

```bash
curl "http://localhost:8081/v2/chain/accounts/03abcd.../transactions?limit=20&order=desc"
```

---

### `POST /v2/chain/transactions/draft`

Создать черновик транзакции для подписания.

```bash
curl -X POST http://localhost:8081/v2/chain/transactions/draft \
  -H "Content-Type: application/json" \
  -d '{"from":"03...","to":"04...","amount_ut":1000000}'
```

```json
{
  "tx": { ... },
  "sign_bytes_hex": "...",
  "sign_bytes_base64": "..."
}
```

---

### `POST /v2/chain/transactions`

Отправить подписанную транзакцию (расширенный формат).

```bash
curl -X POST http://localhost:8081/v2/chain/transactions \
  -H "Content-Type: application/json" \
  -d '{"tx":{...},"signature":"..."}'
```

---

## Адреса

### `GET /api/address/{addr}?limit=N&offset=N`

Информация об адресе (DC-адрес или hex pubkey).

```bash
curl "http://localhost:8081/api/address/DCabc123?limit=20&offset=0"
```

```json
{
  "address": "DCabc123...",
  "pub_key": "03abcd...",
  "balance_ut": 9500000,
  "tx_count": 12,
  "transactions": [...],
  "has_more": false
}
```

---

## Идентичности и валидаторы

### `GET /api/identity/{pubkey|addr}`

Информация об идентичности.

```bash
curl http://localhost:8081/api/identity/03abcd...
```

```json
{
  "pub_key": "03abcd...",
  "address": "DCabc123...",
  "nick": "alice",
  "x25519_pub": "...",
  "registered_at": 100,
  "stake_ut": 1000000000
}
```

---

### `GET /api/validators`

Список активных валидаторов.

```bash
curl http://localhost:8081/api/validators
```

```json
[
  {"pub_key": "03...", "stake_ut": 1000000000},
  {"pub_key": "04...", "stake_ut": 1000000000}
]
```

---

### `GET /api/node/{pubkey|addr}?window=N`

Информация об узле (статистика, репутация).

```bash
curl http://localhost:8081/api/node/03abcd...
```

---

### `GET /api/relays`

Зарегистрированные relay-провайдеры.

```bash
curl http://localhost:8081/api/relays
```

```json
[
  {
    "pub_key": "03...",
    "relay_pub": "...",
    "fee_ut": 100,
    "endpoint": ""
  }
]
```

---

## Live Events

### `GET /api/events`

Server-Sent Events поток новых блоков и транзакций.

```bash
curl -N http://localhost:8081/api/events
```

```
data: {"type":"block","index":1025,"hash":"...","tx_count":2}

data: {"type":"tx","id":"tx-abc","block":1025,"from":"03..."}
```