Skip to content

Latest commit

 

History

History
343 lines (273 loc) · 19.5 KB

EXCHANGE_INTEGRATION.md

File metadata and controls

343 lines (273 loc) · 19.5 KB

Exchange integration

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.

Asset identity

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.

Scheduled consensus activations

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.

Withdrawals

Two distinct payments can silently become one

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.

Protected submission (recommended): let the node detect collisions for you

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-tx
  • POST /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

Queue limits

  • 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.

Classifying failures

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.

Fee band caution

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.

Deposits

/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.

Running a node

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/manifest for 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.

Capabilities this chain does not have

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.