dchain/docs/api/contracts.md

Contracts API

REST API для работы с WASM-контрактами: деплой, вызов, чтение state и логов.

Деплой и вызов контрактов выполняются через CLI-команды client deploy-contract и client call-contract, которые формируют и отправляют подписанные транзакции через POST /api/tx. Прямой HTTP-деплой не поддерживается.

Список контрактов

GET /api/contracts

Все задеплоенные контракты.

curl http://localhost:8081/api/contracts

{
  "count": 4,
  "contracts": [
    {
      "contract_id": "a1b2c3d4e5f60001",
      "deployer_pub": "03abcd...",
      "deployed_at": 100,
      "wasm_size": 1842,
      "abi": {
        "contract": "governance",
        "version": "1.0.0",
        "methods": [...]
      }
    },
    ...
  ]
}

---

Детали контракта

GET /api/contracts/{contractID}

curl http://localhost:8081/api/contracts/a1b2c3d4e5f60001

{
  "contract_id": "a1b2c3d4e5f60001",
  "deployer_pub": "03abcd...",
  "deployed_at": 100,
  "wasm_size": 1842,
  "abi_json": "{...}"
}

Поле	Тип	Описание
contract_id	string	16-символьный hex ID
deployer_pub	string	Pubkey деплоера
deployed_at	uint64	Высота блока деплоя
wasm_size	int	Размер WASM в байтах
abi_json	string	JSON ABI контракта

---

State контракта

GET /api/contracts/{contractID}/state/{key}

Читает значение из state контракта по ключу.

# Строковое значение
curl http://localhost:8081/api/contracts/a1b2c3d4e5f60001/state/admin

# Вложенный ключ
curl "http://localhost:8081/api/contracts/a1b2c3d4e5f60001/state/param:gas_price"

# Ключ эскроу
curl "http://localhost:8081/api/contracts/.../state/e:deal-001:b"

{
  "key": "admin",
  "value_b64": "MDNhYmNk...",
  "value_hex": "30336162636...",
  "value_u64": null
}

Поле	Тип	Описание
value_b64	string	Base64-encoded raw bytes
value_hex	string	Hex-encoded raw bytes
value_u64	uint64|null	Если значение ровно 8 байт big-endian

Примеры чтения state контрактов:

# Governance: live параметр
curl "http://localhost:8081/api/contracts/$GOV_ID/state/param:gas_price"

# Governance: pending предложение
curl "http://localhost:8081/api/contracts/$GOV_ID/state/prop:gas_price"

# Username registry: pubkey по имени
curl "http://localhost:8081/api/contracts/$REG_ID/state/name:alice"
# value_hex = hex(pubkey_bytes) → hex.DecodeString(value_hex) = pubkey

# Escrow: статус сделки
curl "http://localhost:8081/api/contracts/$ESC_ID/state/e:deal-001:x"
# value_hex: 61='a' (active), 64='d' (disputed), 72='r' (released), 66='f' (refunded)

---

Логи контракта

GET /api/contracts/{contractID}/logs?limit=N

Последние N лог-записей (по умолчанию 50, максимум 100).

curl "http://localhost:8081/api/contracts/a1b2c3d4e5f60001/logs?limit=20"

{
  "contract_id": "a1b2c3d4e5f60001",
  "count": 5,
  "logs": [
    {
      "tx_id": "tx-abc123",
      "block_index": 1024,
      "timestamp": 1710000000,
      "message": "registered: alice"
    },
    {
      "tx_id": "tx-def456",
      "block_index": 1020,
      "timestamp": 1709999800,
      "message": "initialized"
    }
  ]
}

Логи отсортированы от новейших к старейшим.

---

Деплой контракта (через CLI)

client deploy-contract \
  --key key.json \
  --wasm mycontract.wasm \
  --abi  mycontract_abi.json \
  --node http://localhost:8081

Успешный деплой печатает:

contract_id: a1b2c3d4e5f60001

В Docker:

docker exec node1 client deploy-contract \
  --key /keys/node1.json \
  --wasm /contracts/mycontract.wasm \
  --abi  /contracts/mycontract_abi.json \
  --node http://node1:8080

---

Вызов контракта (через CLI)

# Без аргументов
client call-contract \
  --contract a1b2c3d4e5f60001 \
  --method increment \
  --gas 5000 \
  --key key.json --node http://localhost:8081

# Строковый аргумент
client call-contract \
  --contract $REG_ID \
  --method register \
  --arg alice \
  --gas 30000 \
  --key key.json --node http://localhost:8081

# Числовой аргумент (uint64)
client call-contract \
  --contract $ESC_ID \
  --method create \
  --arg "deal-001" \
  --arg "$SELLER_PUB" \
  --arg64 5000000 \
  --gas 30000 \
  --key key.json --node http://localhost:8081

# Несколько аргументов в JSON
client call-contract \
  --contract $AUCTION_ID \
  --method create \
  --args '["Rare item #1", 1000000, 100]' \
  --gas 20000 \
  --key key.json --node http://localhost:8081

Флаги call-contract

Флаг	Тип	Описание
--contract	string	ID контракта (16 hex)
--method	string	Имя метода
--arg	string	Добавить строковый аргумент (повторяемый)
--arg64	uint64	Добавить числовой аргумент (повторяемый)
--args	JSON	Массив всех аргументов ["str", 42, ...]
--gas	uint64	Gas лимит
--key	path	Файл ключа
--node	URL	Node URL

---

Токены и NFT

GET /api/tokens

curl http://localhost:8081/api/tokens

{"count": 2, "tokens": [{...}]}

GET /api/tokens/{id}

curl http://localhost:8081/api/tokens/abc123

GET /api/tokens/{id}/balance/{pubkey}

curl http://localhost:8081/api/tokens/abc123/balance/03abcd...

{
  "token_id": "abc123",
  "pub_key": "03abcd...",
  "address": "DCabc...",
  "balance": 1000
}

GET /api/nfts

curl http://localhost:8081/api/nfts

GET /api/nfts/{id}

curl http://localhost:8081/api/nfts/nft-abc123

GET /api/nfts/owner/{pubkey}

curl http://localhost:8081/api/nfts/owner/03abcd...

{"count": 3, "nfts": [{...}]}