Companion to EXPLORER_API.md, which documents the endpoints, the
finality model, and the signing contract. This file covers what a listing team and a
withdrawal engineer need that the endpoint reference does not: asset identity, the
scheduled consensus activations, the failure modes that cost money, and the operational
shape of running a node.
| Field | Value |
|---|---|
| Asset name | alphanumeric |
| Ticker | ALPHA |
| Display glyph | ♦ |
| Decimals | 8 |
| Smallest unit | 1 ALPHA = 100,000,000 units |
| Address format | 40 lowercase hex characters, SHA256(public_key)[..20] |
| Network id | 66b401a212ee9cddab38ff73176a3eeca1733ac81a912376b63aa11afdd1e78c |
| Signature scheme | ML-DSA-87 (post-quantum), signature 4,627 B, public key 2,592 B |
| Target block time | 5 s (measured ~5.4 s) |
| Finality margin | 64 blocks (~6 min) |
network_id is the launch genesis hash and is served by /explorer/status. Verify it on
connect: it is the only field that distinguishes this chain from a fork or a testnet that
shares the same address and transaction format.
Amounts appear twice in every response: a decimal string (amount) and an exact integer
(amount_units). Reconcile on *_units only. The decimal form exists for display.
Both are compiled into the binary. There is nothing to configure; you need the right release before the height arrives.
| Height | ~Date | Change | Minimum release |
|---|---|---|---|
| 517,583 | 2026-08-10 | Fee accounting arms: block-level net-issuance cap | v7.9.3 |
| 569,423 | 2026-08-13 | Reward curve V2: a block carrying transactions no longer pays less than an empty one | v7.9.4 |
A node older than the required release computes a different coinbase from that height and
stops following the chain. Build from the release tag, not from main.
Between 517,583 and 569,423 the fee-accounting baseline uses a compatibility envelope, so
blocks carrying many minimum-fee transactions can be rejected with
FeeAccountingLimitExceeded. This affects miners building templates, not exchanges
submitting transactions.
Transaction identity is sender:recipient:amount:fee:timestamp with the timestamp at
one-second granularity. There is no nonce or sequence number.
So two genuinely separate withdrawals with the same sender, recipient, amount and fee, signed within the same second, are the same transaction. The second is absorbed as a duplicate and only one payment happens.
The node tells you, but not with an error:
200 {"ok": true, "status": "already_pending",
"hint": "identical transaction already pending; a distinct payment must differ in timestamp, amount, or fee"}A worker that checks only the HTTP status and ok will record two successful payouts
and send one. Branch on status:
status |
Meaning |
|---|---|
accepted |
new transaction admitted |
already_pending |
either your own retry, or a distinct payment that collided |
already_confirmed |
already mined |
already_pending means the node already holds a transaction with your exact five identity
fields. It cannot tell you whether that is your own retry or a colliding second payment,
and comparing the returned tx_id does not help: get_tx_id is a pure function of the five
fields you just posted, so the returned id always equals the one you submitted — and a
collision is by definition two payments whose five fields are identical, which is precisely
when the ids match.
The defence has to be client-side. Reserve the 5-tuple (sender, recipient, amount, fee,
timestamp) in your own store before signing, and refuse to issue a second withdrawal that
reuses one. If already_pending comes back for a 5-tuple you have not previously submitted,
treat it as a COLLISION: do not mark the withdrawal paid — re-sign with a different
timestamp (wait one second) or vary the fee by one unit. Serialising withdrawals to one per
second per (recipient, amount) pair is the simplest correct policy.
The client-side defense above still works and is unchanged. But the node can now do the detection for you if you give it the one thing only your system has — a unique id per withdrawal.
Use the protected endpoints and attach an idempotency_key (your own withdrawal id) to every
submission:
POST /explorer/v2/submit-txPOST /explorer/v2/submit-tx-batch
The rule is one line:
Generate one unique, unguessable key per withdrawal. Send it with the transaction. Reuse the same key only when retrying that exact withdrawal.
Single submission:
POST /explorer/v2/submit-tx
{
"idempotency_key": "d2c0ef48-849a-4ce8-b67c-04fd7fc8e017",
"transaction": {
"sender": "<40-char hex>", "recipient": "<40-char hex>",
"amount": 10, "fee": 0.0001, "timestamp": 1786752000,
"signature": "<hex>", "pub_key": "<hex>", "sig_hash": "<hex>"
}
}Batch — every item carries its own key:
POST /explorer/v2/submit-tx-batch
{
"version": 1,
"transactions": [
{ "idempotency_key": "<uuid-1>", "transaction": { … } },
{ "idempotency_key": "<uuid-2>", "transaction": { … } }
]
}The node evaluates four cases and answers unambiguously:
| Your submission | status |
Meaning |
|---|---|---|
| new key, transaction absent before v2 reservation | accepted |
admitted and attributed to this key |
| same key, same recent transaction | already_pending/already_confirmed, idempotent_replay: true |
safe retry — canonically reconciled, never a second payment |
| same key, cached confirmation older than the canonical replay window | historical_outcome_unavailable (HTTP 409) |
the node will not trust stale cached state — reconcile from your withdrawal database |
| same key, different transaction | idempotency_conflict (HTTP 409) |
you reused a withdrawal id for a different transaction — refused |
| different key, identical transaction | transaction_collision (HTTP 409) |
two of your withdrawals produced identical bytes and collided |
| new key, transaction already present outside v2 | existing_transaction_unattributed (HTTP 409) |
the node cannot safely attribute the pre-existing payment to this withdrawal |
The last row is the case you could not previously detect: two byte-identical transactions carrying
two different withdrawal ids are two distinct payments, and without the two ids the node cannot tell
them from one transaction submitted twice. On transaction_collision, re-sign the colliding
withdrawal (advance its timestamp by one second or change the fee by one unit) and resubmit it under
its own key. The rejected collision attempt does not claim that key, so this corrected resubmission is
allowed. On any 409, do not mark the withdrawal paid until you resolve it.
existing_transaction_unattributed is deliberately conservative. It occurs when the identical
transaction reached this node through the legacy endpoint, P2P, or another path before the protected
endpoint could durably associate it with your key. It may be your earlier submission, or it may be a
distinct colliding withdrawal. Do not re-sign blindly (both transactions could then confirm); compare
the transaction with your durable withdrawal history and resolve the attribution first. For the full
guarantee, send a withdrawal through v2 on its first submission and retry that same node/key/tx.
The node fsyncs the key-to-transaction reservation before canonical admission. A reservation failure
returns 503 ledger_unavailable without admitting a new transaction. Replays are reconciled with
the node's current confirmed and durable/in-memory pending state while those canonical indexes retain
the transaction; old cached confirmations fail closed as described below. If an admission error
cannot be reconciled, the node returns
503 submission_outcome_unknown; retry only the exact same key and signed transaction and never
re-sign until the outcome is known.
The node ledger is a bounded safety layer, not your permanent withdrawal database. Terminal bindings
are retained for seven days and can be pruned earlier under the hard 100,000-entry / 256 MiB live-state
limits; reserved, pending, and ambiguous payments are never evicted to make room, and new protected
submissions fail closed if capacity is exhausted by non-terminal operations. Keep the withdrawal id,
key, signed transaction, and final outcome in your own durable store and never reuse a key. Once a
terminal binding is pruned, the node no longer provides idempotency history for it. Separately, the
canonical replay index retains only the transaction-validity window; if the ledger remembers an older
confirmation that the index can no longer prove, the endpoint returns
historical_outcome_unavailable for manual reconciliation instead of trusting stale cached state.
A transaction that was definitively not admitted does not retain a binding, so a corrected
transaction (including a higher-fee rebuild after mempool_full) may reuse that withdrawal's key.
Once a key has a live, confirmed, or ambiguous binding, a different transaction under it is an
idempotency_conflict.
Security — keys must be unguessable. The submission endpoint may be reachable by more than your
backend. A predictable key such as withdrawal-1234 lets someone else claim it first and make your
real withdrawal fail with idempotency_conflict. Use a UUIDv4 (or another high-entropy value), or
scope keys to an authenticated API client. Keys must be 16–128 printable-ASCII characters; the node
rejects shorter or malformed ones.
Migration is deliberate; existing integrations are untouched. The legacy submit-tx and
submit-tx-batch endpoints are unchanged, so upgrading the node breaks nothing. You gain this
protection when you point your withdrawal worker at the /v2/ endpoints and start sending a key —
not merely by upgrading. That participation is unavoidable: the withdrawal id is information only
your system has, so the node cannot supply it for you.
If you instead sign with the reference wallet (create/send), you already get collision-free
timestamps automatically — the ledger allocates a distinct timestamp per identical payment — so the
protected endpoints are specifically for integrations that sign in their own service and POST the
finished transaction.
A minimal reference client (Python):
import uuid, requests
def submit_withdrawal(node_url, signed_tx, withdrawal_id=None):
# Persist `key` next to the withdrawal row BEFORE submitting; reuse it verbatim on retry.
key = withdrawal_id or str(uuid.uuid4())
body = requests.post(f"{node_url}/explorer/v2/submit-tx",
json={"idempotency_key": key, "transaction": signed_tx}).json()
status = body.get("status")
if status in ("accepted", "already_pending"):
return "submitted", key, body # safe association; wait for normal confirmation policy
if status == "already_confirmed":
return "confirmed", key, body
if status == "transaction_collision":
return "rebuild", key, body # re-sign with a new timestamp, resubmit under the same id
if status == "idempotency_conflict":
return "conflict", key, body # you reused an id for a different tx — investigate
if status in ("existing_transaction_unattributed", "historical_outcome_unavailable",
"submission_outcome_unknown"):
return "manual_reconcile", key, body # never re-sign while the original may be live
return "retry_or_reject", key, body # backpressure (retry) or terminal rejection — inspect body- 100 concurrently pending transactions per sender address (
MEMPOOL_MAX_PER_ADDRESS). A hot wallet is one address, so a burst of more than 100 queued withdrawals fails at the 101st. Cap in-flight submissions below 100, or shard across several hot wallets. - 2,000 submissions per 60 s per sender address — ~33 tx/s sustained. (Raised from 100 in this release: a pool paying its miners in one payout round no longer trips it.)
- The submit endpoint is additionally fronted by a node-wide token bucket: 5
submissions/s sustained, burst 20, shared across every sender regardless of the
per-sender limit. Exceeding it returns
429 {"error": "rate_limited"}. This, not the per-sender limit, is the ceiling on sustained submission throughput against one node. - No server-side way to query current mempool depth for your address. Track in-flight count client-side.
Admission backpressure — the per-address pending cap, the per-sender rate, and a full mempool — is returned as HTTP 429 with a machine-readable body, so you branch on a field instead of a string:
429 {"error": "rate_limited", "reason": "per_address_pending_cap", "retryable": true, "retry_same_transaction": true, "detail": "…"}reason |
retryable / retry_same_transaction |
Action |
|---|---|---|
per_address_pending_cap |
yes | at the pending-per-address cap; back off, resend the same signed transaction (slots drain as blocks land) |
per_sender_rate |
yes | per-sender submission rate; back off, resend the same signed transaction |
mempool_full |
no | re-sign at a higher fee — eviction is fee-ordered and all-or-nothing, so resubmitting the identical transaction can never win a slot |
retryable mirrors retry_same_transaction, so a worker can branch on the top-level flag
alone: it is false for mempool_full because only a re-sign at a higher fee — a different
transaction — can clear it. A separate node-wide token bucket (5/s sustained, burst 20,
shared across all senders) also returns 429 {"error": "rate_limited"} with no reason; it
is always retryable.
A 400 {"error": "transaction rejected: …"} is terminal — Insufficient funds,
signature is invalid or missing, fee below the relay floor, amount is invalid or negative — alert on it.
Malformed requests are rejected by the HTTP layer before the handler runs and return PLAIN
TEXT, not JSON: 400 for a JSON syntax error, 415 for a missing/wrong Content-Type,
422 for well-formed JSON that is not a transaction. Key off Content-Type — only a 400
whose body parses as {"error": "transaction rejected: …"} came from validation.
Minimum relay fee is 10,000 units (0.0001 ALPHA). Minimum transfer is 564 units. Use
/explorer/fee-estimate rather than hardcoding.
Some historical fee values carry an encoding meaning in the reference wallet. Use the fee
returned by /explorer/fee-estimate, or the relay floor, and avoid choosing large
arbitrary fee values for ordinary withdrawals.
/explorer/address/{addr} returns confirmed ledger state.
This release returns these fields: address, balance, balance_units, spendable,
spendable_units, history_available, index_ready, index_height, summary,
transactions, next.
balance_units is the raw confirmed ledger total. It includes mining rewards that are
still immature (coinbase maturity is 100 blocks) and does not subtract in-flight mempool
debits, so it can exceed what the address can actually spend. For a deposit address that
never mines and that you never spend from concurrently, it is safe to credit against. For
any address you also withdraw from, use spendable_units (below) or subtract your own
in-flight debits client-side.
spendable / spendable_units is the precomputed spendable amount — confirmed minus
pending debits minus still-immature mining rewards — or null when it cannot be computed.
Prefer it over subtracting your own in-flight debits from balance_units.
Check history_available before trusting transactions. The history is served off the
address index, which can be unbuilt or mid-rebuild after a bootstrap or re-index. When it is
not ready, history_available is false and transactions is served as null (not an
empty array), so "index not ready" and "no deposits" cannot be confused — a scanner must
refuse to conclude anything about deposits while history_available is false. Retry until
it is true, and also confirm freshness via /explorer/status (blocks_behind).
GET endpoints can return 503 under chain-lock contention during heavy sync/indexing
({"error":"chain busy, retry shortly"}) or when storage/index data cannot be read
({"error":"storage_unavailable"}). A deposit scanner must treat either response as
"retry/alert", never as "no data", or it can skip deposits or accept a false zero.
Credit rules and reorg handling are covered in
EXPLORER_API.md.
The node deliberately terminates itself and must run under a supervisor. Several
recovery paths call exit(3) (and exit(4) when the storage engine reports an
unrecoverable I/O state such as a full disk) expecting an external supervisor to restart the process, for
example when the local chain has fallen too far behind to catch up incrementally and needs
to re-bootstrap. Under nohup or a bare container with no restart policy, the node stays
down. Use systemd, Docker restart: always, launchd KeepAlive, or equivalent.
Storage notes:
- The database never shrinks. Deleted data is not reclaimed, and a re-bootstrapped database carries permanent import overhead.
- There is no prune mode and no compaction command. Provision for monotonic growth and re-bootstrap from a snapshot if a node's database becomes unwieldy.
- Bootstrap downloads a signed snapshot; check
https://alphanumeric.blue/api/bootstrap/manifestfor the current size before provisioning.
Bind the API to loopback and put your own auth in front of it. It has no authentication of its own.
| Capability | Status |
|---|---|
| Memo / destination tag | None. Use one deposit address per user; there is no shared-address tagging. |
| Batch withdrawal (one transaction, many recipients) | None. Send N separate transactions; the miner template drains many transactions per sender per block, so this works, subject to the 250-pending-per-address cap. |
| Fee bump / RBF | None, and no replacement either. A pending transaction cannot be cancelled or superseded: if you sign a second payment for the same withdrawal, BOTH are valid and both can confirm. Treat a submitted transaction as spent until it confirms or the node reports it gone (pending rows expire after the node's TTL, 2 h by default, and are never mineable past 6 h from their timestamp). Resubmit the SAME signed transaction, never a re-signed copy. |
| Mempool acceptance query | None. Submission response is the acceptance signal. |
| Block or deposit webhooks | No per-address webhooks and no outbound HTTP from the node. There IS a tip push: ALPHANUMERIC_BLOCKNOTIFY="/path/to/script %s %h" runs your command on every new tip (%s hash, %h height) — Bitcoin Core's -blocknotify contract. When a program path or argument contains spaces, use structured argv, for example ALPHANUMERIC_BLOCKNOTIFY_ARGV='["C:\\Program Files\\Pool\\notify.exe","%s","%h"]'; it takes precedence over the legacy variable and still executes directly without a shell. Built for pools, but it suits a deposit scanner just as well: trigger a block-walk on the hook instead of polling /explorer/tip. Single-flight, coalesces under load, killed after 10 s. |
| HD derivation standard | None published. Post-quantum keys do not use BIP32-style derivation. |
| Multisig | None. |