Справочник RPC

Публичный API — это JSON-over-HTTP фасад перед нодой. На testnet он доступен по адресу https://test.noxycore.io. Самостоятельно поднятый noxy-public-api по умолчанию слушает 0.0.0.0:8080 и ходит в локальные RPC-порты ноды: чтение (:9360) и отправка (:9350).

Все ответы — JSON. Нативные ID аккаунтов и активов — 64-символьный строчный hex; верхний регистр отвергается с 400. EVM-адреса (0x + 40 hex) принимаются в любом регистре и возвращаются строчными.

Ошибки

Все не-EVM эндпоинты используют один конверт ошибки:

{ "error": "account not found", "variant": "not_found" }

variant — стабильная машиночитаемая строка. Чаще всего встречаются: bad_request, hash, limit, cursor, asset, level, not_found, rate_limit, upstream_busy, unavailable, upstream, internal, preverify, auth, insufficient, nonce_mismatch.

Rate limiting считается по IP клиента: token bucket с пополнением 20 запросов/с и burst 50, плюс глобальный лимит одновременных запросов. Превышение — 429 с variant: rate_limit, заголовок Retry-After не отправляется. Отдельный случай — 429 с variant: upstream_busy: это backpressure самой ноды.

Health и идентичность

curl https://test.noxycore.io/v0/health
# { "status": "ok" }

curl https://test.noxycore.io/v0/node/identity

{
  "chain_id": "veylith-testnet-10",
  "genesis_hash_hex": "…",
  "native_asset_id_hex": "…",
  "protocol_version": 4,
  "release_version": "0.1.x",
  "commit_sha": "…",
  "node_role": "…"
}

/v0/health всегда отвечает 200 и не обращается к ноде — он говорит только о том, что фасад жив. /v0/economics/summary сейчас возвращает только { "native_asset_id_hex": "…" }.

Статистика сети

curl https://test.noxycore.io/v0/network/stats

{
  "chain_id": "veylith-testnet-10",
  "genesis_hash_hex": "…",
  "protocol_version": 4,
  "node_role": "…",
  "release_version": "0.1.x",
  "checkpoint": {
    "height": 84,
    "ordered_sequence_end": 12040,
    "state_root_hex": "…",
    "ordered_log_root_hex": "…"
  },
  "validators": { "count": 4, "fault_bound": 1, "quorum": 3 },
  "evm": {
    "chain_id_numeric": 20057,
    "window_gas_ceiling": 30000000,
    "base_fee_wei": "1000000000",
    "time_anchor_unix_secs": 1785173149,
    "millis_per_round": 250
  }
}

checkpoint равен null до первого durable-чекпоинта. evm равен null в сети без EVM lane; на testnet он содержит chain_id_numeric, window_gas_ceiling, base_fee_wei (десятичная строка), time_anchor_unix_secs и millis_per_round. Объект indexed с activity_rows появляется, когда к ноде подключена read-model.

Аккаунты

# Запись аккаунта — "account" равен null, если аккаунта нет (никогда не 404)
curl https://test.noxycore.io/v0/account/{id_hex}
# { "account": { "account_id_hex": "…", "account_type": "User",
#                "status": "Active", "sequence_nonce": 7,
#                "primary_key_id_hex": "…" } }

# Следующий nonce — 404, если аккаунт неизвестен
curl https://test.noxycore.io/v0/account/{id_hex}/nonce
# { "nonce": 7 }

# Баланс одного актива — "0", если актива нет
curl https://test.noxycore.io/v0/account/{id_hex}/balance/{asset_id_hex}
# { "amount_decimal": "100000000000" }

Баланс — десятичная строка в базовых единицах. Сеть сегодня одноактивная: любой asset ID, кроме нативного, возвращает 400 с variant: asset.

Тот же маршрут /v0/account/{id} обслуживает и EVM-сторону дуальности аккаунтов. Передайте адрес 0x + 40 hex, и ответ станет таким:

{
  "account": {
    "domain": "evm",
    "address_hex": "0x…",
    "balance_wei": "0",
    "nonce": 0,
    "is_contract": false,
    "code_hash_hex": "…"
  }
}

Ни разу не встречавшийся EVM-адрес возвращает нулевой аккаунт, а не 404. Подмаршруты /nonce и /balance принимают только нативные ID.

Активность

curl 'https://test.noxycore.io/v0/account/{id_hex}/activity?limit=25'

{
  "account_id_hex": "…",
  "limit": 25,
  "next_cursor": "…",
  "activities": [
    {
      "cursor": "…",
      "tx_hash_hex": "…",
      "block_height": 84,
      "tx_index": 0,
      "tx_type": "Transfer",
      "account_role": "sender",
      "accepted": true,
      "fee_charged_decimal": "1200",
      "state_version": 12040,
      "events_count": 2,
      "transfers": [
        {
          "direction": "sent",
          "counterparty_account_id_hex": "…",
          "asset_id_hex": "…",
          "amount_decimal": "1000000000"
        }
      ]
    }
  ]
}

limit — от 1 до 100 (по умолчанию 25). Для пагинации передайте next_cursor обратно как ?cursor=; на последней странице next_cursor равен null. Нода без read-model отвечает 200 с пустым activities, а не ошибкой.

Отправка транзакции

curl -X POST https://test.noxycore.io/v0/tx/submit \
  -H 'content-type: application/json' \
  -d '{"envelope_bytes_base64":"<base64 канонического TransactionEnvelope>"}'

Успех — 202:

{ "tx_hash_hex": "9f2c…", "relay_status": "queued" }

Ошибки и их коды:

| Код | variant | Причина | |---|---|---| | 400 | preverify | битый base64, слишком большой envelope или envelope, который нода считает некорректным | | 401 | auth | не прошла проверка подписи | | 402 | insufficient | баланс меньше комиссии или суммы перевода | | 409 | nonce_mismatch | nonce в envelope ≠ sequence nonce аккаунта | | 429 | upstream_busy | нода применяет backpressure | | 413 | — | тело больше лимита маршрута в 256 KiB |

Статус транзакции

curl https://test.noxycore.io/v0/tx/{hash_hex}

{
  "status": "done",
  "receipt": {
    "tx_hash_hex": "9f2c…",
    "stage": "…",
    "outcome": "…",
    "finality": "…",
    "display": {
      "display_label": "…",
      "help_line": "…",
      "progress_step": "…",
      "is_terminal": true,
      "can_user_act": false,
      "funds_effect": "…"
    },
    "dictionary_version": 2
  }
}

status — одно из sending, processing, done, failed, unknown. Неизвестный хеш отвечает 200 с { "status": "unknown", "receipt": null }, а не 404. Объект display — готовая строка статуса для кошельков; failure_reason_class и user_next_action появляются только когда уместны.

Доказательства транзакций

Любую закоммиченную транзакцию можно доказать против цепочки одним GET:

curl 'https://test.noxycore.io/v0/tx/{hash_hex}/proof?level=finality'

level — inclusion, finality (по умолчанию) или checkpoint. Ответ содержит дайджест и индекс транзакции, Merkle-пути батча и окна (tx_proof_hex, list_proof_hex) и упорядоченную ссылку (ordered_ref_hex). На уровне finality и выше добавляются чекпоинт и его сертификат (checkpoint_hex, checkpoint_cert_hex) — доказательство доводится до чекпоинта, подписанного валидаторами.

Транзакция без durable-доказательства возвращает 404 not_found; транзакция старше bootstrap-базы ноды — 404 post_base_only.

EVM lane: eth JSON-RPC

POST /v0/evm говорит на стандартном eth JSON-RPC 2.0 и работает на testnet (EVM chain id 20057), поэтому EVM-кошельки и тулинг подключаются напрямую. Поддерживаемые методы:

eth_chainId, net_version, eth_blockNumber, eth_gasPrice, eth_maxPriorityFeePerGas, eth_getBlockByNumber, eth_getBlockByHash, eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt, eth_call, eth_estimateGas, eth_feeHistory, eth_sendRawTransaction, eth_getTransactionByHash, eth_getTransactionReceipt, eth_getLogs

Батчи поддерживаются до 20 запросов. Диапазон eth_getLogs ограничен 100 блоками. Ошибки всегда приходят JSON-RPC-объектами поверх HTTP 200 (-32601 для неподдерживаемых методов, -32005 для превышенных лимитов, 3 для execution revert).

Имена аккаунтов

Записи имён живут ончейн в StateNamespace::AccountNameRecord. Резолв работает через состояние: нормализуйте метки, выведите хеш имени и прочитайте запись — TypeScript SDK и кошелёк делают это за вас. Отдельный публичный HTTP-эндпоинт резолва запланирован, но пока не открыт; структура записи и семантика аренды — в разделе Аккаунты.