Глоссарий — System Design для TON-разработчика

// Классический подход: масштабируем сервер вертикально
// Блокчейн SD: масштабируем через шардинг контрактов

// Вместо одного контракта-монолита:
contract MonolithDEX { /* всё в одном */ }

// Проектируем систему контрактов:
contract Router { /* маршрутизация */ }
contract Pool { /* один пул ликвидности */ }
contract LPWallet { /* кошелёк LP-токенов */ }

// TON выбирает: AP (доступность + устойчивость к разделению)
// Следствие: eventual consistency между шардами

// Нельзя:
let balance = otherContract.getBalance(); // синхронный вызов

// Нужно проектировать асинхронно:
send(SendParameters{
    to: otherContract,
    body: RequestBalance{}.toCell()
});
// Ответ придёт отдельным сообщением

// Компромисс: хранение on-chain vs off-chain

// On-chain: дорого, но верифицируемо
contract OnChainNFT {
    metadata: map<Int, Cell>; // ~0.01 TON за ячейку в год
}

// Off-chain: дёшево, но требует доверия к серверу
contract OffChainNFT {
    contentUrl: String; // только ссылка on-chain
}

// Паттерн Master-Child (Factory)
// Master создаёт дочерние контракты с предсказуемыми адресами

contract JettonMaster {
    fun mint(to: Address, amount: Int) {
        let init = initOf JettonWallet(myAddress(), to);
        send(SendParameters{
            to: contractAddress(init),
            value: ton("0.05"),
            body: InternalTransfer{amount}.toCell(),
            code: init.code,
            data: init.data
        });
    }
}

// Этапы фреймворка для проектирования DEX:
// 1. Требования: swap, add/remove liquidity, fees
// 2. Архитектура: Router → Pool → LP Wallet
// 3. Потоки: пользователь → Router → Pool → Wallet
// 4. Газ: оценка цепочки из 3-5 сообщений
// 5. Безопасность: проверка bounce, replay, overflow
// 6. Деплой: порядок развёртывания контрактов

// Влияние многослойности на проектирование:

// Слой 1: Masterchain — конфигурация, валидаторы
// → Не деплоить пользовательские контракты

// Слой 2: Basechain (workchain 0) — смарт-контракты
// → Основная среда для DeFi, NFT, токенов

// Слой 3: Shardchains — автоматическое разделение
// → Проектировать контракты sharding-friendly

// Ethereum: контракты в одном шарде читают друг друга
uint price = oracle.getPrice(); // синхронно

// TON: каждый контракт — свой шард
// Нельзя синхронно прочитать состояние другого контракта
// Решение: асинхронный запрос-ответ
send(RequestPrice{pair: "TON/USD"}.toCell());
// Обработка в receive(PriceResponse)

// Финальность транзакции:
// 1. Транзакция попадает в блок шардчейна (~2-5 сек)
// 2. Хеш шардчейн-блока включается в masterchain
// 3. После этого транзакция финальна

// Для проектирования: ожидание финальности
// составляет ~6 секунд (1-2 masterchain-блока)
// Учитывать в UX платёжных систем

// Сравнение подходов к DEX:

// Ethereum (синхронная модель):
// Uniswap: Router вызывает Pool.swap() синхронно
// Всё в одной транзакции, атомарно

// TON (асинхронная модель):
// DeDust: Router отправляет сообщение Pool
// Pool обрабатывает и отправляет результат
// Цепочка из 3-5 асинхронных сообщений

// Антипаттерн: God Contract
contract BadDEX {
    pools: map<Address, PoolData>;
    balances: map<Address, Int>;
    orders: map<Int, Order>;
    // Всё в одном контракте → не масштабируется
}

// Правильно: декомпозиция
contract Router { /* маршрутизация */ }
contract Pool { /* один пул */ }
contract Vault { /* хранение средств */ }

// Каждый контракт — актор
// Принципы:
// 1. Своё изолированное состояние
// 2. Обрабатывает сообщения по одному
// 3. Может отправлять сообщения другим акторам
// 4. Может создавать новых акторов (deploy)

contract WalletActor {
    balance: Int = 0;
    
    receive(msg: Deposit) {
        self.balance += msg.amount;
        // Отправка сообщения другому актору
        send(Notification{amount: msg.amount}.toCell());
    }
}

// Поток swap в DEX (5 сообщений):
//
// User → Router: запрос swap
//   Router → Pool: transfer_notification
//     Pool → JettonWallet: transfer (выход)
//       JettonWallet → User: transfer_notification
//       JettonWallet → Pool: excesses (сдача газа)
//
// Gas budget: 0.3 TON (0.06 на каждое сообщение)

// Стратегия: откат при bounce
contract SafeTransfer {
    pendingAmount: Int = 0;
    
    // Отправка с сохранением pending
    fun transfer(to: Address, amount: Int) {
        self.pendingAmount = amount;
        self.balance -= amount;
        send(SendParameters{to, value: amount, bounce: true});
    }
    
    // Откат при bounce
    bounced(msg: Slice) {
        self.balance += self.pendingAmount;
        self.pendingAmount = 0;
    }
}

// Escrow как конечный автомат
contract Escrow {
    state: Int = 0; // 0=created, 1=funded, 2=released, 3=refunded
    
    receive(msg: Fund) {
        require(self.state == 0, "Wrong state");
        self.state = 1;
    }
    
    receive(msg: Release) {
        require(self.state == 1, "Wrong state");
        require(sender() == self.buyer, "Not buyer");
        self.state = 2;
        send(/* transfer to seller */);
    }
}

// Scatter-Gather паттерн
contract Aggregator {
    responses: Int = 0;
    expected: Int = 3;
    
    fun queryAll() {
        // Отправка параллельно в 3 оракула
        send(/* → Oracle A */);
        send(/* → Oracle B */);
        send(/* → Oracle C */);
    }
    
    receive(msg: OracleResponse) {
        self.responses += 1;
        // Действие после сбора всех ответов
        if (self.responses == self.expected) {
            self.finalize();
        }
    }
}

// Не sharding-friendly: одна точка сбора
contract CentralLedger {
    allBalances: map<Address, Int>; // все данные в одном шарде
}

// Sharding-friendly: распределённая архитектура
contract UserWallet {
    balance: Int; // каждый пользователь в своём шарде
}
contract Master {
    totalSupply: Int; // только агрегированные данные
}

// Архитектура Jetton:
// JettonMaster (1 контракт)
//   ├── JettonWallet (owner: Alice) — шард A
//   ├── JettonWallet (owner: Bob)   — шард B
//   └── JettonWallet (owner: Carol) — шард C
//
// Transfer: Wallet_A → Wallet_B (прямой, без Master)
// Mint: Master → новый Wallet
// Burn: Wallet → Master

// NFT Collection как фабрика:
// NFTCollection (контракт-фабрика)
//   ├── NFTItem #0 (index: 0, owner: Alice)
//   ├── NFTItem #1 (index: 1, owner: Bob)
//   └── NFTItem #N (index: N, owner: ...)
//
// Адрес каждого Item детерминирован:
// addr = hash(collection_addr + item_index)
// → Можно вычислить без запроса к сети

// Вычисление адреса JettonWallet до деплоя:
let walletInit = initOf JettonWallet(jettonMaster, owner);
let walletAddress = contractAddress(walletInit);

// Теперь можно отправить сообщение на walletAddress
// даже если контракт ещё не развёрнут —
// первое сообщение с StateInit создаст его
send(SendParameters{
    to: walletAddress,
    value: ton("0.05"),
    code: walletInit.code,
    data: walletInit.data,
    body: Mint{amount: 1000}.toCell()
});

// Шардинг по эпохам для системы голосования:
// VoteMain
//   ├── VoteEpoch(round: 1) — завершённый
//   ├── VoteEpoch(round: 2) — завершённый
//   └── VoteEpoch(round: 3) — активный
//       ├── VoteBallot(voter: Alice)
//       └── VoteBallot(voter: Bob)
//
// Каждый раунд — отдельный контракт
// Старые раунды не нагружают сеть

// Плоская структура (быстрый доступ, дорогое хранение):
// Root → [balance, owner, data1, data2]
// Глубина: 1, доступ: O(1)

// Глубокая структура (медленный доступ, дешёвое хранение):
// Root → [balance, ref→[owner, ref→[data1, data2]]]
// Глубина: 3, доступ: O(depth)

// Оптимальный баланс: часто читаемые данные — наверху
// Root → [balance, owner, ref→[metadata]]

// Стратегия: минимизация gas при частых операциях

// Частая операция — проверка баланса:
// Хранить balance в первых битах корневой ячейки
beginCell()
    .storeCoins(balance)    // первым — частый доступ
    .storeAddress(owner)    // вторым
    .storeRef(metadata)     // редко читаемое — в ref
    .endCell()

// TL-B схема для токен-трансфера:
// transfer#0f8a7ea5
//   query_id:uint64
//   amount:(VarUInteger 16)
//   destination:MsgAddress
//   response_destination:MsgAddress
//   custom_payload:(Maybe ^Cell)
//   forward_ton_amount:(VarUInteger 16)
//   forward_payload:(Either Cell ^Cell)
//   = InternalMsgBody;
//
// Opcode 0f8a7ea5 — уникальный идентификатор

// Проблема: словарь с 10000 записями
// Каждая запись/чтение — обход дерева O(key_bits)

// Оптимизация 1: уменьшить размер ключа
// map<Int as uint256, V>  → дорого (256 бит)
// map<Int as uint32, V>   → дёшево (32 бита)

// Оптимизация 2: шардинг словаря
// Вместо одного большого словаря:
// Master.users: map<Address, Data> // 10000 записей
// Распределить по дочерним контрактам:
// UserContract(owner).data // 1 запись на контракт

// Расчёт стоимости хранения NFT-коллекции:
// 10000 NFT × 1 KB metadata on-chain
// = 10 MB × 0.000000033 TON/бит/год
// = ~2.6 TON/год

// Альтернатива: off-chain metadata
// 10000 NFT × 32 байта (ссылка на IPFS)
// = 320 KB → ~0.08 TON/год

// Решение: гибридный подход
// Критичные данные (owner, index) — on-chain
// Медиа и описание — IPFS/TON Storage

// Gas влияет на архитектуру:

// Вариант A: один контракт, сложная логика
// Deploy: 0.05 TON
// Каждый вызов: 0.1 TON (много вычислений)
// 1000 вызовов: 100 TON

// Вариант B: система контрактов, простая логика
// Deploy: 0.2 TON (4 контракта)
// Каждый вызов: 0.03 TON (параллельно)
// 1000 вызовов: 30 TON

// Вариант B дешевле при > 200 вызовах

// Паттерн: batch-обработка вместо поштучной

// Неоптимально: 100 отдельных сообщений
for (let i = 0; i < 100; i++) {
    send(Transfer{to: recipients[i]});
}
// Gas: 100 × 0.01 = 1 TON

// Оптимально: batch через merkle-proof
send(BatchTransfer{
    merkleRoot: root,
    count: 100
});
// Gas: 0.05 TON (один вызов с proof)

// Экономическая модель DEX-пула:
// Доходы:
//   Swap fee: 0.3% от объёма
//   Ежедневный объём: 100,000 TON
//   Доход: 300 TON/день
//
// Расходы:
//   Gas на swap: 0.03 TON × 500 = 15 TON/день
//   Хранение: 0.01 TON/день
//   Итого: ~15 TON/день
//
// Прибыль: ~285 TON/день
// Breakeven при объёме: ~5000 TON/день

// Оценка gas для цепочки swap:

// Шаг 1: User → Router (compute: ~3000 gas)
// forward_fee: ~0.005 TON

// Шаг 2: Router → Pool (compute: ~5000 gas)
// forward_fee: ~0.005 TON

// Шаг 3: Pool → JettonWallet (compute: ~4000 gas)
// forward_fee: ~0.005 TON

// Итого estimate: ~0.03 TON
// Рекомендация UX: отправлять 0.05 TON
// Разница вернётся через excess-сообщение

// Проблема: слишком много вычислений в одном вызове
// gas_limit = 1,000,000 gas units

// Тяжёлая операция: пересчёт 1000 позиций
// Не влезает в один вызов!

// Решение: continuation-паттерн
contract BatchProcessor {
    processed: Int = 0;
    
    receive(msg: Process) {
        let batch = 50; // обработать порцию
        // ... обработка 50 элементов ...
        self.processed += batch;
        if (self.processed < total) {
            send(/* сообщение самому себе */)
        }
    }
}

// Архитектура DEX на TON (DeDust-стиль):
//
// Factory → создаёт Pool по параметрам
// Router  → маршрутизирует swap-запросы
// Pool    → хранит ликвидность, выполняет swap
// Vault   → хранит токены одного типа
//
// Swap flow:
// User → Jetton.transfer → Pool.swap_notification
// Pool → Vault.withdraw → User.transfer_notification
//
// В отличие от Uniswap: нет flashloan (async!)

// Push-оракул (периодическое обновление):
contract PriceOracle {
    prices: map<Int, PriceData>; // pair_id → price
    lastUpdate: Int;
    
    receive(msg: UpdatePrice) {
        require(sender() == self.updater, "Not updater");
        self.prices.set(msg.pairId, PriceData{
            price: msg.price,
            timestamp: now()
        });
    }
    
    // Контракты запрашивают цену асинхронно
    receive(msg: GetPrice) {
        let data = self.prices.get(msg.pairId);
        reply(PriceResponse{price: data.price});
    }
}

// Проектирование токеномики DAO:
//
// Эмиссия: 1,000,000 токенов (фиксированная)
// Распределение:
//   40% — community (vesting 4 года)
//   25% — team (cliff 1 год, vesting 3 года)
//   20% — treasury (управляется DAO)
//   15% — liquidity mining
//
// Governance: 1 токен = 1 голос
// Порог создания пропозала: 10,000 токенов
// Кворум: 10% supply

// Чек-лист безопасности для каждого контракта:
// □ msg_value >= required_gas + forward_fees
// □ sender() проверяется в каждом receive
// □ bounce обработан для каждого send
// □ Integer overflow невозможен
// □ Excess возвращается отправителю
// □ Replay protection (seqno или query_id)
// □ Нет зависимости от block.timestamp
// □ Код обновляемости защищён multisig

// Паттерн: Timelock-обновление
contract Upgradable {
    pendingCode: Cell? = null;
    upgradeAt: Int = 0;
    
    receive(msg: ProposeUpgrade) {
        require(sender() == self.admin, "Not admin");
        self.pendingCode = msg.newCode;
        self.upgradeAt = now() + 86400; // 24h delay
    }
    
    receive(msg: ExecuteUpgrade) {
        require(now() >= self.upgradeAt, "Too early");
        require(self.pendingCode != null, "No pending");
        nativeSetCode(self.pendingCode!!);
    }
}

// Трёхслойная архитектура Mini App:
//
// Слой 1: Telegram WebView (Mini App)
//   React + TON Connect UI
//   Показывает UI, подписывает транзакции
//
// Слой 2: Backend API
//   Кеширование on-chain данных
//   Индексация событий
//   Push-уведомления
//
// Слой 3: TON Smart Contracts
//   Бизнес-логика и хранение
//   Обработка платежей

// Жизненный цикл платёжного канала:
//
// 1. Открытие (on-chain)
//    Alice deploy ChannelContract с залогом 100 TON
//    Bob подтверждает участие с залогом 100 TON
//
// 2. Off-chain обмен (мгновенно, бесплатно)
//    State #1: Alice=90, Bob=110 (подписано обоими)
//    State #2: Alice=85, Bob=115 (подписано обоими)
//
// 3. Закрытие (on-chain)
//    Публикация финального state + challenge period
//    Распределение: Alice=85, Bob=115

// Мониторинг DEX в production:
//
// 1. Balance Monitor:
//    Проверять баланс Pool каждые 30 сек
//    Alert если < минимальной ликвидности
//
// 2. Transaction Monitor:
//    Индексировать все входящие сообщения
//    Отслеживать failed transactions
//    Alert если error rate > 5%
//
// 3. TVL Tracker:
//    Агрегировать балансы всех пулов
//    Dashboard с историей TVL
//    Alert при резком падении (> 20% за час)

// Capstone: DeFi платформа
//
// Контракты:
//   DEX (Router + Pools) — модули 04, 07
//   Token (Jetton + LP) — модуль 08
//   Governance (DAO voting) — модуль 11
//
// Frontend:
//   Telegram Mini App — модуль 09
//   TON Connect — подключение кошелька
//
// Infrastructure:
//   Indexer — отслеживание транзакций
//   Monitor — алертинг и дашборды
//   CI/CD — автодеплой контрактов

// Порядок деплоя DEX-системы:
//
// Фаза 1: Deploy базовых контрактов
//   1. JettonMaster (LP токены)
//   2. Vault контракты
//   3. Pool контракты
//
// Фаза 2: Deploy координаторов
//   4. Router (ссылается на Pool-ы)
//   5. Factory (создаёт новые Pool-ы)
//
// Фаза 3: Настройка и верификация
//   6. Инициализация ликвидности
//   7. Тестовый swap
//   8. Открытие публичного доступа