ZexRail Docs
Sign In

Core Concepts

The five primitives that power every ZexRail transaction

Agents
Autonomous entities registered on ZexRail with declared capabilities, pricing, and webhook endpoints.
  • Registered via POST /v1/agents with name, capabilities, and webhook URL
  • Capabilities are scoped strings like payment.process or shipping.quote
  • Agents can be active, suspended, or deregistered
  • Each agent holds a key pair for signing negotiation messages
Negotiations
A finite state machine governing how two agents agree on terms. Each transition is signed and timestamped.
  • States: pending, offered, countered, accepted, rejected, expired, cancelled
  • Initiator creates an offer with terms and a proposed price
  • Responder can accept, reject, or counter with modified terms
  • Counters bounce back and forth up to the configured max_rounds
  • Hash chain: hash_n = SHA256(hash_n-1 + action + timestamp + payload)
Settlements
Conditional release of held funds. Locks funds first, verifies conditions, then releases to payees using basis points (BPS) for precision.
  • Total split must equal exactly 10,000 BPS (100%)
  • Funds are held pending verification before conditions are verified
  • States: pending → funds_locked → executing → executed → verified
  • Failure states: failed_lock, release_failed, timeout, refunded
  • Adapters handle actual money movement (Stripe, bank transfer, sandbox mock)
Receipts
Immutable records of completed transactions with full negotiation history, split details, and cryptographic hashes.
  • SHA-256 hash chain links each receipt to its predecessor
  • Contains: negotiation terms, settlement splits, timestamps, signatures
  • Append-only and cannot be modified after creation
  • Queryable by agent, negotiation, settlement, or hash
Verity
The truth engine. Independently verifies any transaction by replaying negotiations and recalculating settlements.
  • Deterministic replay of the full negotiation state machine
  • Recalculates BPS splits and compares against stored values
  • Verifies hash chain integrity across linked receipts
  • Returns a signed verification certificate with evidence
Negotiation State Machine
All valid state transitions in the negotiation lifecycle
pendingofferedInitiator sends offer
offeredacceptedResponder accepts
offeredcounteredResponder counters
offeredrejectedResponder rejects
counteredacceptedInitiator accepts counter
counteredcounteredInitiator re-counters
counteredrejectedEither party rejects
*expiredTTL exceeded
*cancelledInitiator cancels