# HostraCore — full machine-readable specification

HostraCore is a payment settlement engine. The double-entry ledger is the source of truth.
Every money movement begins as a durable settlement intent and completes exactly once —
never zero times, never twice. The flagship product is card_to_crypto: a user pays with a
card via Stripe and receives USDT or USDC on-chain.

Website: https://hostracore.com
API: https://api.hostracore.com
Contact: support@hostracore.com
Architect: Ildar Lykmanov (Ильдар Лукманов) — https://hostracore.com/about

## 1. Architecture modules

Ledger — double-entry. Every posting is balanced across debit and credit accounts.
  Balances are derived from entries; entries are immutable.
Treasury — float and liquidity accounts per currency and per rail, reconciled against
  provider statements.
Settlement — durable settlement intents. Lifecycle: pending -> in_flight ->
  succeeded | failed | reversed. Methods: card_charge, card_push, on_chain.
Saga — composite multi-leg transactions with compensation (card_to_crypto).
Identity — human sessions (argon2id + pepper, opaque HttpOnly session cookie) and
  machine identities (API keys, prefix hstra_, verified with HMAC-SHA256).
Audit — append-only hash-chain of all state-changing operations, with a verification
  endpoint that recomputes the chain.
Notifications — transactional email (verification, password reset, API key created,
  security alert, welcome).
Webhooks — outbound events signed HMAC-SHA256, Stripe-style header (t=<unix>,v1=<hex>),
  published from a transactional outbox with retry and backoff.
Push — device token registration -> dispatch -> Expo Push API -> device. Payload is
  opaque: {"transfer_id": "..."} only, no financial data in the notification body.
Platform — Go 1.25, PostgreSQL (pgx v5), Redis (go-redis v9), RabbitMQ (amqp091-go), Docker,
  OpenTelemetry, Prometheus, Grafana, Cloudflare.

## 2. Settlement engine semantics

Settlement intent: a durable record of the intention to move money, written before any
  provider is called.
Lease: exclusive, time-bounded ownership of an intent. Exactly one worker may execute an
  intent at a time.
Fencing token: monotonic counter attached to the lease. Writes carrying a stale token are
  rejected, preventing ABA errors after a pause or partition.
Terminal CAS commit: the final state is written with compare-and-set, so a terminal state
  can never be committed twice.
Query-before-retry: before repeating a provider call, the engine queries the provider for
  the prior attempt's outcome.
Transactional outbox: events are written in the same database transaction as the state
  change, then published asynchronously. No lost events, no phantom events.
Idempotency: mutating API calls accept an Idempotency-Key header; a repeated key returns
  the original result rather than creating a second movement.

## 3. card_to_crypto saga

Flow:
  1. POST /v1/quotes — server-side quote locks rate and fee, returns quote_id with TTL.
  2. Client tokenises the card with Stripe.js, producing pm_...
  3. POST /v1/transfers with quote_id, card_pm, wallet, network, asset and an
     Idempotency-Key header. Returns transfer_id.
  4. GET /v1/transfers/{id} — poll until a terminal state, or subscribe to webhooks.

States:
  pending -> leg1_in_flight -> leg1_succeeded -> leg2_in_flight -> succeeded
  any leg failure -> compensating -> failed

Legs:
  leg1 = card_charge via Stripe (real capture).
  leg2 = on_chain disbursement via crypto custodian.
Compensation: if leg2 fails after leg1 succeeded, leg1 is reversed (refund) and the saga
  terminates as failed. The ledger records both the original and the reversing postings.

Expired quote: POST /v1/transfers with a stale quote_id returns HTTP 410. Re-quote.

## 3b. Fees and quote pricing (card_to_crypto)

platform_fee = 1.5% (150 bps) of send_amount. It is a percentage, never a flat charge.
network_fee = fixed amount per network, covering on-chain disbursement:
  tron $1.00, ethereum $15.00, polygon $0.50, bsc $0.80.
receive_amount = send_amount - platform_fee - network_fee.

Worked example, $1000.00 USD -> USDT:
  tron:     15.00 + 1.00  -> 984.00 USDT (1.60% effective)
  ethereum: 15.00 + 15.00 -> 970.00 USDT (3.00% effective)
  polygon:  15.00 + 0.50  -> 984.50 USDT (1.55% effective)
  bsc:      15.00 + 0.80  -> 984.20 USDT (1.52% effective)

Because the network fee is fixed, small tickets carry a higher effective rate
($10 on tron = $1.15, 11.50%) and large tickets a lower one ($10,000 on tron =
$151.00, 1.51%). Quotes are locked server-side for 60 seconds.

Exact call:
  POST /v1/quotes
  {"send_currency":"USD","send_amount":"1000.00","receive_asset":"USDT","receive_network":"tron"}
  -> {"quote_id","rate","platform_fee":"15.00","network_fee":"1.00","receive_amount":"984.00","expires_at"}
  POST /v1/transfers  (header Idempotency-Key)
  {"flow":"card_to_crypto","quote_id":"qt_...","card_pm":"pm_...","wallet":"T...","network":"tron","asset":"USDT"}
  -> {"id","status","legs":[...]}
  GET /v1/transfers/{id} -> poll to a terminal state.

## 4. Settlement methods and providers

Methods:
  card_charge — pull funds from a card (Stripe).
  card_push   — push funds to a card (Visa Direct OCT).
  on_chain    — transfer a digital asset through the custodian.
Providers: Stripe, Visa Direct, crypto custodian, internal loopback (test).

Networks: tron, ethereum, polygon, bsc. Arbitrum, Avalanche and Optimism are planned
(EVM-compatible, additive to the same provider surface) and not yet available.
Assets: USDT, USDC.

## 5. API surface

Base: https://api.hostracore.com/v1
Health probes (unversioned): /health, /ready, /live
OpenAPI 3.1 per bounded context: /v1/{context}/openapi.json
Swagger UI per bounded context: /v1/{context}/docs
Contexts: auth, auth/m2m, settlements, quotes, transfers, webhooks
Roughly 46 endpoints across 7 bounded contexts.

Representative routes:
  POST /v1/auth/register              — human signup, creates an owned merchant
  POST /v1/auth/login                 — session cookie hostra_session
  GET  /v1/auth/me                    — profile (email, name, merchant, verification)
  PATCH /v1/auth/me                   — update display name
  POST /v1/auth/verify-email/resend   — resend verification (session required)
  POST /v1/auth/password-reset/request— request password reset email
  POST /v1/auth/m2m/register          — machine identity, returns api_key hstra_...
  GET/POST /v1/settlements            — settlement intents
  POST /v1/quotes                     — lock rate and fee
  POST /v1/transfers                  — create a card_to_crypto saga
  GET  /v1/transfers/{id}             — saga state and both legs
  GET  /v1/audit/events               — audit hash-chain events
  GET  /v1/audit/verify               — recompute and verify the chain

Authentication modes:
  Human — opaque session cookie hostra_session (HttpOnly, Secure, SameSite=None).
  Machine — Authorization: Bearer hstra_<key>.
Errors — RFC 7807 problem+json: {type, title, status, detail, instance}.

## 6. RBAC scopes

12 scopes are evaluated per route: transfers:read, transfers:write, quotes:read,
quotes:write, settlements:read, settlements:write, settlements:reverse, audit:read,
webhooks:read, webhooks:write, devices:read, devices:write. A key can only reach what
its scopes permit.

## 7. Webhook signature

Header: Hostra-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
Signed payload: "<t>.<raw_request_body>"
Key: the merchant's webhook secret.
Verification: recompute the HMAC over the exact raw body, compare in constant time, and
reject timestamps outside a tolerance window to prevent replay.

## 8. Push pipeline

Device registers its Expo push token -> transfer.status_changed event is emitted by the
saga -> outbox delivers a signed webhook -> the notification dispatcher calls the Expo
Push API -> the device receives an opaque payload {"transfer_id": "..."} and fetches the
current state over the authenticated API.

## 9. Audit hash-chain

hash_n = H(hash_{n-1} || canonical(event_n))
Any edit or deletion of a historical event invalidates every subsequent hash.
GET /v1/audit/verify recomputes the chain, reports validity, event count and head hash.
An external party can archive the head hash and re-verify later.

## 10. Security posture

- argon2id password hashing with a server-side pepper.
- Opaque session cookies; no browser-stored tokens.
- API keys verified with HMAC-SHA256; the full key is displayed once at creation.
- PAN and CVV are never received or stored; Stripe tokenisation reduces PCI scope.
- TLS everywhere, HSTS on the web surface.
- CORS allow-list per origin with credentials; wildcard origins rejected for credentialed
  requests.
- Rate limiting per identity and per IP on authentication and mutation routes.

## 11. Glossary

settlement intent — durable record of intent to move money, created before provider calls.
lease — exclusive, time-bounded execution ownership of an intent.
terminal commit — the final, compare-and-set state write of a settlement.
fencing token — monotonic token that invalidates writes from a stale lease owner.
outbox — table written in the same transaction as state, drained by a publisher.
saga — multi-step transaction with explicit compensation instead of distributed locks.
leg — one provider-facing step of a saga; itself a settlement intent.
compensation — the reversing action for a completed leg when a later leg fails.
double-entry ledger — accounting model where every entry has equal, opposite postings.
hash-chain audit — audit log where each record embeds the hash of its predecessor.

## 12. In active development (architecture scaffolded, not generally available)

Wallet custody (hot/cold/HD); card issuance and management (virtual and physical, freeze,
limits); Apple Pay and Google Pay; KYC / KYB / AML screening; Payment Links, Invoices,
Checkout, Hosted Payments; recurring payments and subscriptions; crypto-to-fiat and crypto-to-card payout (inbound on-chain receive leg into custody, then
Visa Direct OCT card_push);
crypto-to-crypto swaps; ACH, SEPA, SWIFT and Wire; Mastercard Send; Bitcoin and Solana;
2FA and biometrics; risk engine and fraud detection.

## 13. Mobile

HostraCore for iOS and Android (Expo / React Native): buy USDT/USDC with a card, transfer
history, push notifications on status change. Currently in App Store review.

# Machine-readable API sources (live)
- https://api.hostracore.com/llms.txt
- https://api.hostracore.com/openapi.json
- https://api.hostracore.com/docs
- https://api.hostracore.com/version
- https://api.hostracore.com/health