dchain/docs/contracts/governance.md

# governance

On-chain governance контракт для управления параметрами сети. Deployer становится admin. Любой может предложить изменение параметра; admin принимает или отклоняет.

## Концепция

```
Участник        Admin
    │               │
    │── propose ──▶ │   state[prop:<key>] = value
    │               │
    │               │── approve ──▶  state[param:<key>] = value (live)
    │               │                 удаляет prop:<key>
    │               │
    │               │── reject  ──▶  удаляет prop:<key>
```

После approve параметр становится **live** и читается нодой при следующем вызове контракта.

## Методы

### `init`

Инициализировать контракт, установить caller как admin.

**Аргументы:** нет

**Вызывается:** один раз после деплоя (deploy-скрипт делает это автоматически).

**Поведение:**
- Устанавливает `state[admin] = caller_pubkey`
- Идемпотентен: повторный вызов не меняет admin если уже установлен

```bash
client call-contract --method init --contract $GOV_ID \
  --key /keys/node1.json --gas 5000 --node http://node1:8080
```

---

### `propose`

Предложить новое значение параметра. Доступно всем.

**Аргументы:**
| # | Имя | Тип | Ограничение |
|---|-----|-----|------------|
| 0 | `key` | string | max 64 байта |
| 1 | `value` | string | max 256 байт |

**Поведение:**
- Сохраняет `state[prop:<key>] = value`
- Лог: `proposed: <key>=<value>`
- Если pending-предложение уже есть → перезаписывает

```bash
# Предложить новую цену газа 5 µT/gas
client call-contract --method propose \
  --arg gas_price --arg 5 \
  --contract $GOV_ID --key /keys/node1.json \
  --gas 10000 --node http://node1:8080
```

---

### `approve`

Admin принимает pending-предложение. Параметр становится live.

**Аргументы:**
| # | Имя | Тип |
|---|-----|-----|
| 0 | `key` | string |

**Права:** только admin.

**Поведение:**
- Копирует `state[prop:<key>]` → `state[param:<key>]`
- Удаляет `state[prop:<key>]`
- Лог: `approved: <key>`
- Если нет pending → лог `no pending: <key>`

```bash
client call-contract --method approve --arg gas_price \
  --contract $GOV_ID --key /keys/node1.json \
  --gas 10000 --node http://node1:8080
```

---

### `reject`

Admin отклоняет pending-предложение.

**Аргументы:**
| # | Имя | Тип |
|---|-----|-----|
| 0 | `key` | string |

**Права:** только admin.

```bash
client call-contract --method reject --arg gas_price \
  --contract $GOV_ID --key /keys/node1.json \
  --gas 5000 --node http://node1:8080
```

---

### `get`

Прочитать текущее live-значение параметра.

**Аргументы:**
| # | Имя | Тип |
|---|-----|-----|
| 0 | `key` | string |

**Лог:**
- `value: <value>` — параметр установлен
- `not set: <key>` — параметр не установлен

```bash
client call-contract --method get --arg gas_price \
  --contract $GOV_ID --key /keys/node1.json \
  --gas 3000 --node http://node1:8080
```

Через REST (без транзакции):
```bash
curl http://localhost:8081/api/contracts/$GOV_ID/state/param:gas_price
```

---

### `get_pending`

Прочитать pending-предложение.

**Аргументы:**
| # | Имя | Тип |
|---|-----|-----|
| 0 | `key` | string |

**Лог:**
- `pending: <value>`
- `no pending: <key>`

---

### `set_admin`

Передать роль admin другому адресу.

**Аргументы:**
| # | Имя | Тип |
|---|-----|-----|
| 0 | `new_admin` | string (hex pubkey) |

**Права:** только текущий admin.

```bash
client call-contract --method set_admin --arg <NEW_ADMIN_PUBKEY> \
  --contract $GOV_ID --key /keys/node1.json \
  --gas 10000 --node http://node1:8080
```

---

## Управляемые параметры

Governance хранит произвольные string-параметры. Нода читает следующие:

| Ключ | Тип | Описание | По умолчанию |
|------|-----|---------|-------------|
| `gas_price` | uint64 (строка) | µT за 1 gas unit | 1 µT |

> Нода читает `gas_price` при каждом `CALL_CONTRACT` через `chain.GetEffectiveGasPrice()`.  
> Изменение вступает в силу немедленно после `approve` — без перезапуска.

Можно хранить любые параметры приложения (messenger_entry_fee, relay_fee, etc.) и читать их из других контрактов через межконтрактные вызовы.

## State Layout

```
cstate:<contractID>:admin         →  admin pubkey (hex string bytes)
cstate:<contractID>:param:<key>   →  live value
cstate:<contractID>:prop:<key>    →  pending proposal
```

## Интеграция с нодой

После деплоя governance необходимо его **привязать** к ноде:

```bash
# Автоматически через deploy-скрипт
# Или вручную:
curl -X POST http://localhost:8081/api/governance/link \
  -H "Content-Type: application/json" \
  -d "{\"governance\": \"$GOV_ID\"}"
```

Подробнее: [Governance интеграция](../node/governance.md)