BLACKCOIN / PROTOCOL V4CHANGELOG

API CHANGELOG / VERSIONED CONTRACT

What changed, and what you can rely on.

The public API is versioned. This page — and its machine-readable twin at /api/changelog.json — is how you track what moved, what's deprecated, and when a field can disappear, so a schema bump never silently breaks your client. Full contract: /openapi.json.

Current contract versions

  • OpenAPI document: 1.3.0 — The public /api/explorer + /api/v3 contract at /openapi.json.
  • Explorer envelope: schema_version 3 — available / not_found / unavailable envelope shape.
  • Chain params: blackcoin.chain-params/2 — Machine-readable identity + integration parameters at /api/chain-params.
  • MCP server: 1.1.0 — serverInfo.version reported by the /mcp initialize response.

Deprecation & versioning policy

  • Additive changes (new endpoints, new response fields) can ship in any release and never require a version bump — write forward-compatible parsers that ignore unknown fields.
  • Breaking changes (removing/renaming a field, changing a type or meaning) require a new MAJOR version of the affected surface and are announced here first.
  • Deprecated fields keep working until their stated removal, which is never earlier than the next major version of that surface.
  • Heights are authoritative over dates; amounts are exact integer-sats strings; coverage is disclosed on every response and totals under partial coverage are lower bounds.

Active deprecations

/api/supply · circulating_sats, total_sats

Deprecated since: schema_version 3

Use instead: Use the reconciled taxonomy fields (base UTXO set vs. phase-locked synthetic credit). These aliases are the spendable base-chain UTXO set only.

Removal: Retained through the current major contract. They will be removed no earlier than the next MAJOR OpenAPI version (2.0.0), and never inside a minor/patch bump.

Change log

  • Added2026-07-20 — Explorer: address UTXO listing (/api/explorer/address/{a}/utxos), mempool contents (/api/explorer/mempool), and raw serialized hex for transactions and blocks (/tx/{txid}/hex, /block/{id}/hex).
  • Added2026-07-20 — Per-transaction fee (fee_sats) is now computed for normal spends (null for coinbase/coinstake or when a prevout is unresolvable).
  • Added2026-07-20 — MCP: get_address_utxos, get_mempool, get_transaction_hex, get_block_hex, get_shadow_supply, get_network, get_network_series, get_leaderboard, get_analytics_series (17 tools total); get_transaction gained vin/vout pagination.
  • Changed2026-07-20 — Truncation is disclosed everywhere: block shadow_events_truncated / counts_partial, the unfiltered /events feed carries truncated + scan_blocks, and shadow-address activities carry confirmations.
  • Fixed2026-07-20 — Analytics /series issuance sats now come from exact RPC totals (were undercounting blocks with >2000 payouts). Unknown-parameter requests return 400 (not 404).