Obex Alpha — Public Testnet (Spec‑First, Byte‑Precise)

Overview

• Rust workspace under obex-alpha/ implements α‑I/α‑II/α‑III/α‑T primitives, an HTTP node, and tooling.
• Consensus‑critical crates forbid unsafe and deny warnings; golden vectors verify byte‑for‑byte behavior.
• The node is header‑first and deterministic; GET endpoints are idempotent and cacheable.

Quickstart

Native

cargo build --release -p obex_node -p obex_tool
./obex-alpha/target/release/obex_node \
  --listen 0.0.0.0:8081 \
  --data-dir data/obex-node \
  --network-id obex-alpha-testnet

Docker (example)

docker build -t obex-node:alpha obex-alpha/
docker run --rm -p 8081:8081 -v $(pwd)/data:/data obex-node:alpha \
  --listen 0.0.0.0:8081 --data-dir /data --network-id obex-alpha-testnet

Security profiles

• --security-profile sets sensible defaults:
  • balanced (default): GET open; generous faucet/tx caps; orchestrator writes require token/IP; CORS allows GET/POST/OPTIONS with Content-Type/Authorization.
  • open: higher caps and broader CORS for demos; orchestrator writes still protected.
  • locked: strict CORS allowlist; lower caps for public gateways.
• Orchestrator protection (required for public):
  • --orchestrator-token <TOKEN> and --orchestrator-allow-ips <ip1,ip2,...>; local‑only mode per profile.
• CORS:
  • --cors-origins https://app.example,https://explorer.example to allow browser apps.

What the node provides (HTTP + SSE)

• Health & metrics: GET /healthz, /readyz, /livez, /metrics (Prometheus text)
• Chain/headers/slots:
  • GET /v1/info (chain_id, genesis_hash, version, slots_per_sec, head)
  • GET /v1/head
  • GET /v1/headers (paginated)
  • GET /v1/slot/{slot} (summary + counts)
  • GET /header/{slot} (legacy DTO) — also used by tool for binds
• Tickets (α‑III) and proofs:
  • GET /v1/alpha_iii/{slot} (decoded ticket leaves, paginated)
  • GET /v1/ticket/{txid} (resolve + inclusion proof)
  • GET /v1/proof/ticket/{slot}/{txid} (Merkle proof)
• Participation (α‑I):
  • GET /v1/alpha_i_index/{slot} (participants)
  • GET /v1/proof/participant/{slot}/{pk} (proof)
• Wallets and txs:
  • GET /v1/account/{pk-no-0x} → {spendable_u,reserved_u,next_nonce}
  • POST /v1/tx → submit signed tx (Ed25519; canonical bytes)
  • GET /v1/tx/{txid} → pending|admitted|rejected (+slot)
  • POST /v1/faucet → test credits (profile‑based daily caps)
  • GET /v1/fees → fee rule (flat‑or‑1percent)
• Search, peers, stats:
  • GET /v1/search, /v1/peers
  • GET /v1/stats/network (slots, txs_total, wallets_total, spendable_total_u)
  • GET /v1/stats/supply (O(1) incremental)
  • GET /v1/stats/participation, /v1/stats/fees
• Pending (for operators/UX):
  • GET /v1/pending?limit= returns pending txs (body shape matches /v1/tx input)
• Streaming (SSE):
  • GET /v1/subscribe — events newHead and ticketAdmitted, 15s keep‑alive pings
• Orchestrator‑only (protected):
  • POST /alpha_iii/{slot} → ingest concatenated 216‑byte ticket leaves
  • POST /header → validate and accept next header
  • POST /advance → deterministically build next header from store (utility)

Minimal executor (server‑side)

• On ticket ingestion/admission, the node validates binds, nonce, fees, and funds using the original TxBodyV1 kept in pending_txs and updates balances/nonces atomically.
• Valid: mark admitted, increment sender nonce, debit sender (amount+fee), credit recipient (amount), move total to reserved.
• Invalid: mark rejected and do not mutate balances.

CLI: obex_tool

• gen-key — generate Ed25519 keypair (sk/pk)
• faucet --node --pk 0x<pk> --amount-u N — request test tokens
• send-tx --node --sk 0x<sk> --recipient 0x<pk> --amount-u N [--memo 0x] — build, sign, submit
• status --node [--pk <64hex-no-0x>] — health, head, peers, optional account
• peers --node — list peers
• net-stats --node — network stats
• history --node --pk 0x<pk> [--back-slots N] — incoming/outgoing scan
• orchestrate --node --max-txs N --interval-ms M — single‑proposer loop (requires token/IP when enforced)
• install-node [--dest <path>], run-node [--public --port --data-dir --seeds-file --network-id --listen --background]

Defaults & flags (node)

• Listen: --listen 127.0.0.1:8081 (default)
• Data dir: --data-dir data/obex-node
• Networking: --peers <csv>, --seeds-file <path>, per‑peer concurrency/backoff/ban
• Security/CORS: --security-profile, --cors-origins <csv>, --trust-forward-headers
• Orchestrator: --orchestrator-token, --orchestrator-allow-ips

Developer ergonomics

• JSON over HTTP; 32‑byte fields as 0x‑hex; big integers as decimal strings.
• Cursor+limit pagination on list endpoints; ETag/If‑None‑Match for caching where applicable.
• Each response includes x-request-id for tracing; logs emit a structured request_end record.

Current testnet status

• Single trusted proposer (centralized) builds blocks via /alpha_iii + /header.
• Transactions are admitted with proofs; balances and nonces update on admission.
• Alpha‑I lottery/VRF and mempool/relay are not yet public; planned as next milestones.

Docs

• OpenAPI: Production_Documentations/API_OPENAPI_v1.yaml
• Operator/user guides: Obex_Node_Guide.md, Obex_Tool_Guide.md
• Roadmaps and analytics plan: 40Hours.md, Plan_To_WorldClass_Analytics.md