dchain/docs/development/tinygo.md

TinyGo SDK

Руководство по написанию DChain smart contracts на Go с использованием TinyGo.

Установка TinyGo

# macOS
brew install tinygo

# Linux (deb)
wget https://github.com/tinygo-org/tinygo/releases/download/v0.32.0/tinygo_0.32.0_amd64.deb
sudo dpkg -i tinygo_0.32.0_amd64.deb

# Windows
# Скачать installer с https://github.com/tinygo-org/tinygo/releases

# Проверка
tinygo version

Требуется TinyGo 0.30+ (поддержка //go:wasmimport + target wasip1).

Структура контракта

contracts/
  mycontract/
    main.go              # контракт
    mycontract_abi.json  # ABI
    mycontract.wasm      # собранный (gitignore или коммитим?)

Минимальный контракт:

package main

import dc "go-blockchain/contracts/sdk"

//export my_method
func myMethod() {
    dc.Log("hello from Go contract!")
}

// main обязателен для TinyGo, но не вызывается.
func main() {}

Каждая //export <name> функция становится вызываемым методом контракта.

SDK API

Импорт: import dc "go-blockchain/contracts/sdk"

Аргументы

// Строковый аргумент по индексу (maxLen — максимальная длина буфера)
name := dc.ArgStr(0, 64)    // args[0] as string
addr := dc.ArgStr(1, 128)   // args[1] as string

// Числовой аргумент (uint64)
amount := dc.ArgU64(0)      // args[0] as uint64

State

// Читать/писать произвольные байты
data := dc.GetState("key")           // []byte или nil
dc.SetState("key", []byte("value"))  // записать
dc.SetState("key", nil)              // удалить

// Удобные string обёртки
s := dc.GetStateStr("owner")         // string (пустой если нет)
dc.SetStateStr("owner", caller)      // записать string

// uint64 (хранится как 8-byte big-endian)
count := dc.GetU64("counter")        // uint64
dc.PutU64("counter", count+1)        // записать

Идентификация

caller := dc.Caller()         // hex pubkey вызывающего (64 символа)
height := dc.BlockHeight()    // uint64, текущий блок
treasury := dc.Treasury()     // hex адрес treasury контракта

Токены

// Баланс адреса в µT
bal := dc.Balance(pubkey)                  // uint64

// Перевод µT
ok := dc.Transfer(from, to, amount)        // bool: true=success

Transfer в контексте контракта: from должен быть либо caller'ом, либо dc.Treasury() — только так контракт может тратить чужие деньги.

Межконтрактные вызовы

// Вызвать метод другого контракта
ok := dc.CallContract(contractID, "method", `["arg1","arg2"]`)

// Без аргументов
ok := dc.CallContract(contractID, "get_price", "[]")

Подробнее: Межконтрактные вызовы

Логирование

dc.Log("message")               // строка видна в Explorer → Logs
dc.Log("value: " + strconv.FormatUint(v, 10))

Паттерны

Owner-только метод

//export admin_action
func adminAction() {
    owner := dc.GetStateStr("owner")
    if owner == "" {
        // первый вызов — устанавливаем owner
        dc.SetStateStr("owner", dc.Caller())
        dc.Log("initialized")
        return
    }
    if dc.Caller() != owner {
        dc.Log("unauthorized")
        return
    }
    // ... логика ...
}

Платный метод (fee в treasury)

//export register
func register() {
    name := dc.ArgStr(0, 64)
    if name == "" { return }

    const fee = 1000 // µT
    caller := dc.Caller()
    treasury := dc.Treasury()

    // Снять fee с caller и положить в treasury
    if !dc.Transfer(caller, treasury, fee) {
        dc.Log("insufficient balance")
        return
    }
    dc.SetStateStr("reg:"+name, caller)
    dc.Log("registered: " + name)
}

Эскроу с release

//export lock
func lock() {
    id := dc.ArgStr(0, 64)
    amount := dc.ArgU64(1)
    buyer := dc.Caller()
    treasury := dc.Treasury()

    if !dc.Transfer(buyer, treasury, amount) {
        dc.Log("transfer failed")
        return
    }
    dc.SetStateStr("buyer:"+id, buyer)
    dc.PutU64("amount:"+id, amount)
    dc.Log("locked: " + id)
}

//export release
func release() {
    id := dc.ArgStr(0, 64)
    buyer := dc.GetStateStr("buyer:" + id)
    if dc.Caller() != buyer {
        dc.Log("unauthorized")
        return
    }
    seller := dc.ArgStr(1, 128)
    amount := dc.GetU64("amount:" + id)
    dc.Transfer(dc.Treasury(), seller, amount)
    dc.Log("released: " + id)
}

Сборка

cd contracts/mycontract

# Собрать WASM
tinygo build -o mycontract.wasm -target wasip1 -no-debug .

# Проверить размер
ls -lh mycontract.wasm

# Опционально: wasm-strip для уменьшения размера
wasm-strip mycontract.wasm

Флаги:

• -target wasip1 — WASI Preview 1 (единственный поддерживаемый target)
• -no-debug — убрать debug info из WASM (уменьшает размер)
• -opt=2 — агрессивная оптимизация (по умолчанию в release)

Деплой

CONTRACT_ID=$(client deploy-contract \
  --key /keys/node1.json \
  --wasm mycontract.wasm \
  --abi  mycontract_abi.json \
  --node http://localhost:8081 | grep contract_id | awk '{print $2}')

echo "Contract: $CONTRACT_ID"

Проверка WASM

Перед деплоем можно проверить что модуль валиден:

// В Go тесте
ctx := context.Background()
v := vm.NewVM(ctx)
defer v.Close(ctx)

wasmBytes, _ := os.ReadFile("mycontract.wasm")
if err := v.Validate(ctx, wasmBytes); err != nil {
    log.Fatal(err)
}

Пример: hello_go

Полный пример TinyGo-контракта с комментариями находится в contracts/hello_go/main.go.

Демонстрирует:

• increment / get / reset — счётчик с owner ACL
• greet — строковые аргументы
• ping — межконтрактный вызов

# Собрать
cd contracts/hello_go
tinygo build -o hello_go.wasm -target wasip1 -no-debug .

# Задеплоить
docker exec node1 client deploy-contract \
  --key /keys/node1.json \
  --wasm hello_go.wasm \
  --abi  hello_go_abi.json \
  --node http://node1:8080

# Вызвать
docker exec node1 client call-contract \
  --key /keys/node1.json --contract $HELLO_ID \
  --method increment --gas 5000 --node http://node1:8080

docker exec node1 client call-contract \
  --key /keys/node1.json --contract $HELLO_ID \
  --method greet --arg "DChain" --gas 5000 --node http://node1:8080

Ограничения TinyGo в контекcте WASM

• Нет goroutine в WASM (нет многопоточности)
• Нет net, os, syscall — контракт изолирован
• Нет доступа к файловой системе и сети
• fmt.Println и log.Printf работают через WASI stdout — но не логируются в blockchain.
  Используйте только dc.Log() для логов видимых в Explorer.
• Размер памяти по умолчанию: 64 KB на stack + heap управляется TinyGo GC