461 lines
17 KiB
Markdown
461 lines
17 KiB
Markdown
# Montana Contracts — Техническая Спецификация
|
||
|
||
**Версия:** 1.0
|
||
**Дата:** 2026-01-21
|
||
**Автор:** Alejandro Montana
|
||
|
||
---
|
||
|
||
## Обзор
|
||
|
||
Montana Contracts — система умных контрактов с человеческим арбитражем. В отличие от автоматических смарт-контрактов блокчейна, Montana Contracts используют AI-арбитра (Юнона) для валидации условий и разрешения споров.
|
||
|
||
**Ключевое отличие:** Юнона понимает естественный язык и может оценить выполнимость условий, в то время как классические смарт-контракты слепо исполняют код.
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ КОНТРАКТНАЯ КОМНАТА │
|
||
│ (Telegram группа) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Сторона А ──────► КОНТРАКТ ◄────── Сторона Б │
|
||
│ (creator) │ │ (target) │
|
||
│ │ │ │
|
||
│ ▼ ▼ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ СВИДЕТЕЛИ │ │
|
||
│ │ (witnesses) │ │
|
||
│ │ голосуют >50% │ │
|
||
│ └────────┬─────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ ЮНОНА │ │
|
||
│ │ (AI-арбитр) │ │
|
||
│ │ ПОСЛЕДНЕЕ СЛОВО │ │
|
||
│ └────────┬─────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ ESCROW │ │
|
||
│ │ (заморозка Ɉ) │ │
|
||
│ └──────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Жизненный цикл контракта
|
||
|
||
### Статусы
|
||
|
||
| Статус | Описание |
|
||
|--------|----------|
|
||
| `DRAFT` | Черновик. Собирает голоса участников |
|
||
| `PENDING` | Одобрен Юноной. Ждёт подтверждения Стороны Б |
|
||
| `ACCEPTED` | Принят. Условия исполняются |
|
||
| `COMPLETION_VOTING` | Голосование за завершение. Свидетели подтверждают исполнение |
|
||
| `COMPLETED` | Исполнен. Escrow переведён Стороне Б |
|
||
| `CANCELLED` | Отменён. Escrow возвращён Стороне А |
|
||
| `REJECTED` | Отклонён Юноной или большинством |
|
||
|
||
### Диаграмма переходов
|
||
|
||
```
|
||
создание
|
||
│
|
||
▼
|
||
┌─────────┐
|
||
│ DRAFT │◄──────────────┐
|
||
└────┬────┘ │
|
||
│ │
|
||
голосование │ >50% ЗА │ изменения
|
||
▼ │
|
||
┌───────────┐ │
|
||
│ ЮНОНА │──────────────┘
|
||
│ проверяет │ отклонение
|
||
└─────┬─────┘
|
||
│ одобрение
|
||
▼
|
||
┌───────────┐
|
||
│ PENDING │
|
||
└─────┬─────┘
|
||
│ Сторона Б принимает
|
||
▼
|
||
┌───────────┐
|
||
│ ACCEPTED │
|
||
└─────┬─────┘
|
||
│ /contract done
|
||
▼
|
||
┌───────────────────┐
|
||
│ COMPLETION_VOTING │
|
||
│ (Bitcoin Pizza) │
|
||
└─────┬─────────────┘
|
||
│ кворум + Юнона
|
||
┌───────────┴───────────┐
|
||
│ │
|
||
▼ ▼
|
||
┌───────────┐ ┌───────────┐
|
||
│ COMPLETED │ │ CANCELLED │
|
||
│ (escrow→Б)│ │ (escrow→А)│
|
||
└───────────┘ └───────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Механизм консенсуса
|
||
|
||
### Кворум
|
||
|
||
Контракт требует одобрения **большинства** участников комнаты (>50%).
|
||
|
||
```python
|
||
def has_quorum(votes_approve, total_witnesses):
|
||
return len(votes_approve) > total_witnesses / 2
|
||
```
|
||
|
||
**Пример:**
|
||
- 5 участников → нужно 3+ голоса ЗА
|
||
- 12 участников → нужно 7+ голосов ЗА
|
||
|
||
### Последнее слово Юноны
|
||
|
||
Даже при достижении кворума, Юнона может **отклонить** контракт если:
|
||
|
||
1. Условия невыполнимы или размыты
|
||
2. Нет объективных критериев исполнения
|
||
3. Условия противоречат протоколу Montana
|
||
4. Обнаружены признаки мошенничества
|
||
|
||
```python
|
||
def junona_decision(contract, approve, reason=None):
|
||
"""
|
||
ПОСЛЕДНЕЕ СЛОВО: Юнона может отклонить даже с кворумом
|
||
"""
|
||
if not contract.has_quorum():
|
||
return False, "Нет кворума"
|
||
|
||
contract.junona_approved = approve
|
||
contract.junona_reason = reason
|
||
|
||
if approve:
|
||
contract.status = PENDING
|
||
else:
|
||
contract.status = REJECTED
|
||
release_escrow_to_creator(contract)
|
||
|
||
return True, "Решение принято"
|
||
```
|
||
|
||
---
|
||
|
||
## Escrow механизм
|
||
|
||
### Заморозка средств
|
||
|
||
При создании контракта средства Стороны А **замораживаются** на специальном escrow-адресе:
|
||
|
||
```
|
||
escrow:{contract_id}
|
||
```
|
||
|
||
**Пример:** `escrow:PIZZA-001`
|
||
|
||
### Движение средств
|
||
|
||
```
|
||
СОЗДАНИЕ: Сторона А ──[amount]──► escrow:CONTRACT-ID
|
||
ИСПОЛНЕНИЕ: escrow:CONTRACT-ID ──[amount]──► Сторона Б
|
||
ОТМЕНА: escrow:CONTRACT-ID ──[amount]──► Сторона А
|
||
```
|
||
|
||
### Безопасность
|
||
|
||
- Escrow-адрес не контролируется ни одной стороной
|
||
- Перевод возможен только при смене статуса контракта
|
||
- Все операции подписаны ML-DSA-65
|
||
|
||
---
|
||
|
||
## Голосование за завершение (Bitcoin Pizza Style)
|
||
|
||
### Концепция
|
||
|
||
Как в истории с Bitcoin Pizza — свидетели должны подтвердить что сделка выполнена. Не только стороны А и Б, но ВСЕ участники группы голосуют за валидность исполнения.
|
||
|
||
### Веса голосов
|
||
|
||
| Участник | Вес голоса |
|
||
|----------|------------|
|
||
| **Юнона** | 2 голоса |
|
||
| **Свидетель** | 1 голос |
|
||
|
||
### Процесс завершения
|
||
|
||
1. Сторона А выполняет условия контракта
|
||
2. Стороны предоставляют доказательства в группу (фото, видео, документы)
|
||
3. Команда `/contract done ID` запускает голосование
|
||
4. Свидетели голосуют `/contract verify ID` (за) или `/contract reject ID` (против)
|
||
5. Юнона анализирует и голосует (2 голоса)
|
||
6. При кворуме (>50%) + одобрении Юноны → COMPLETED
|
||
|
||
### Кворум для завершения
|
||
|
||
```python
|
||
total_weight = len(witnesses) * 1 + 2 # Свидетели + Юнона
|
||
approve_weight = len(votes_approve) * 1 + (2 if junona_approved else 0)
|
||
has_quorum = approve_weight > total_weight / 2
|
||
ready_to_complete = has_quorum and junona_approved
|
||
```
|
||
|
||
### Доказательства
|
||
|
||
Для подтверждения исполнения участники могут использовать:
|
||
- Фото чека/товара/результата
|
||
- Видео кружки (Telegram video circles)
|
||
- Документы (PDF, контракты)
|
||
- Скриншоты
|
||
- Любые другие медиа
|
||
|
||
Свидетели видят доказательства и голосуют исходя из увиденного.
|
||
|
||
### API
|
||
|
||
```python
|
||
# Запуск голосования за завершение
|
||
contract.start_completion_voting()
|
||
|
||
# Голосование свидетеля
|
||
contract.vote_completion(user_id="123", approve=True)
|
||
|
||
# Голос Юноны (2 голоса)
|
||
contract.vote_completion(user_id="JUNONA", approve=True, is_junona=True)
|
||
|
||
# Проверка кворума
|
||
quorum = contract.get_completion_quorum_status()
|
||
# {
|
||
# "total_weight": 7,
|
||
# "approve_weight": 5,
|
||
# "has_quorum": True,
|
||
# "junona_approved": True,
|
||
# "ready_to_complete": True
|
||
# }
|
||
```
|
||
|
||
---
|
||
|
||
## Контрактная комната
|
||
|
||
### Ограничения
|
||
|
||
| Параметр | Значение |
|
||
|----------|----------|
|
||
| Максимум участников | 12 |
|
||
| Минимум для контракта | 2 (стороны А и Б) |
|
||
| Минимум для голосования | 1 голос (при 2 участниках) |
|
||
|
||
### Верификация участников
|
||
|
||
Только реальные участники Telegram-группы могут:
|
||
- Голосовать за/против контракта
|
||
- Быть стороной контракта
|
||
|
||
```python
|
||
def validate_witnesses(group_members, claimed_witnesses):
|
||
"""
|
||
DISNEY-SAFE: Нельзя указать произвольные ID как свидетелей
|
||
"""
|
||
valid = []
|
||
for wid in claimed_witnesses:
|
||
if wid in group_members:
|
||
valid.append(wid)
|
||
return valid
|
||
```
|
||
|
||
---
|
||
|
||
## Валидация условий
|
||
|
||
Юнона анализирует описание контракта по критериям:
|
||
|
||
### Критерии выполнимости
|
||
|
||
1. **Конкретность** — есть ли чёткие критерии?
|
||
2. **Измеримость** — можно ли объективно проверить?
|
||
3. **Достижимость** — реалистично ли условие?
|
||
4. **Временные рамки** — указан ли срок?
|
||
|
||
### ExecutabilityResult
|
||
|
||
```python
|
||
@dataclass
|
||
class ExecutabilityResult:
|
||
executable: bool # Выполнимо ли условие
|
||
confidence: float # Уверенность (0.0-1.0)
|
||
concerns: List[str] # Проблемы
|
||
suggestions: List[str] # Рекомендации
|
||
```
|
||
|
||
**Порог одобрения:** `confidence >= 0.6`
|
||
|
||
---
|
||
|
||
## API
|
||
|
||
### Создание контракта
|
||
|
||
```python
|
||
db.create_contract(
|
||
contract_id="PIZZA-001",
|
||
creator_id="123456789",
|
||
target_id="987654321",
|
||
amount=500,
|
||
description="Доставка пиццы до 18:00",
|
||
chat_id="-100123456789",
|
||
witnesses=["123456789", "987654321", "111222333"],
|
||
freeze_escrow=True
|
||
)
|
||
```
|
||
|
||
### Голосование
|
||
|
||
```python
|
||
contract.vote(user_id="111222333", approve=True)
|
||
# Returns: (True, "Голос принят")
|
||
```
|
||
|
||
### Решение Юноны
|
||
|
||
```python
|
||
contract.junona_decision(approve=True, reason=None)
|
||
# Returns: (True, "Контракт одобрен")
|
||
```
|
||
|
||
### Завершение
|
||
|
||
```python
|
||
db.complete_contract_escrow(contract_id="PIZZA-001")
|
||
# Returns: (True, "Контракт исполнен! 500 Ɉ переведено.")
|
||
```
|
||
|
||
---
|
||
|
||
## База данных
|
||
|
||
### Таблица contracts
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS contracts (
|
||
contract_id TEXT PRIMARY KEY,
|
||
creator_id TEXT NOT NULL,
|
||
target_id TEXT NOT NULL,
|
||
amount INTEGER NOT NULL,
|
||
description TEXT,
|
||
chat_id TEXT,
|
||
witnesses TEXT, -- JSON array
|
||
status TEXT DEFAULT 'draft',
|
||
created_at TEXT,
|
||
accepted_at TEXT,
|
||
completed_at TEXT,
|
||
cancelled_at TEXT,
|
||
escrow_tx_id TEXT,
|
||
votes_approve TEXT, -- JSON array
|
||
votes_reject TEXT, -- JSON array
|
||
junona_approved INTEGER, -- 0/1/NULL
|
||
junona_reason TEXT
|
||
);
|
||
```
|
||
|
||
### Индексы
|
||
|
||
```sql
|
||
CREATE INDEX idx_contracts_creator ON contracts(creator_id);
|
||
CREATE INDEX idx_contracts_target ON contracts(target_id);
|
||
CREATE INDEX idx_contracts_status ON contracts(status);
|
||
```
|
||
|
||
---
|
||
|
||
## Безопасность
|
||
|
||
### Защита от атак
|
||
|
||
| Атака | Защита |
|
||
|-------|--------|
|
||
| Fake witnesses | Верификация через Telegram API |
|
||
| Double-spend escrow | Атомарные транзакции |
|
||
| Сговор большинства | Право вето Юноны |
|
||
| Размытые условия | Валидация ExecutabilityResult |
|
||
| Escrow theft | ML-DSA-65 подписи |
|
||
|
||
### Криптография
|
||
|
||
- Все транзакции подписаны **ML-DSA-65** (FIPS 204)
|
||
- Постквантовая устойчивость
|
||
- Размер подписи: 3309 байт
|
||
|
||
---
|
||
|
||
## Команды бота
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `/contract` | Начать диалог о контракте |
|
||
| `/contract @user 100 условие` | Создать контракт |
|
||
| `/contract accept ID` | Принять (Сторона Б) |
|
||
| `/contract complete ID` | Завершить (Сторона А) |
|
||
| `/contract cancel ID` | Отменить |
|
||
| `/contract yes ID` | Голосовать ЗА |
|
||
| `/contract no ID` | Голосовать ПРОТИВ |
|
||
|
||
---
|
||
|
||
## Примеры использования
|
||
|
||
### Доставка еды
|
||
|
||
```
|
||
/contract @delivery 500 Доставка пиццы Маргарита до 18:00 по адресу ул. Ленина 15
|
||
```
|
||
|
||
### Фриланс
|
||
|
||
```
|
||
/contract @designer 5000 Дизайн логотипа в 3 вариантах, исходники в Figma, срок 7 дней
|
||
```
|
||
|
||
### Аренда
|
||
|
||
```
|
||
/contract @landlord 50000 Аренда квартиры на ул. Пушкина 10 на январь 2026
|
||
```
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
### v1.0 (текущая)
|
||
- [x] Создание контрактов в группах
|
||
- [x] Голосование участников
|
||
- [x] Escrow механизм
|
||
- [x] Решение Юноны
|
||
|
||
### v1.1 (планируется)
|
||
- [ ] Многоэтапные контракты
|
||
- [ ] Автоматические триггеры (время, события)
|
||
- [ ] Интеграция с внешними оракулами
|
||
|
||
### v2.0 (будущее)
|
||
- [ ] Кросс-чейн escrow
|
||
- [ ] Шаблоны контрактов
|
||
- [ ] Репутационная система сторон
|
||
|
||
---
|
||
|
||
**Montana Protocol — Time is the only real currency.**
|