Required reading

Village Mode vs Live Client Mode

Required reading before you turn on Twilio or any paid side effect.

Deployment environment and request execution mode are different things.

ENVIRONMENT=production means the node *may* use production infrastructure. It does not mean every request may send real SMS.

Two paths, one URL

Production deployment
│
├── Village request (Labs / Town buyer)
│   ├── X-Payment-Proof (or unpaid → HTTP 402)
│   ├── testnet / simulated settlement
│   ├── synthetic payload only
│   └── telecom always mocked
│
└── Live client request
    ├── X-PayPort-Client-Key
    ├── Idempotency-Key
    ├── real business payload
    └── Twilio only if production + configured

Why this exists

Without Dual-Mode, putting a node in production so one dental client can text patients would also let the Town buyer bot fire thousands of real texts.

Rules of thumb

  • No auth headers → 402 (Village discovery).
  • Both proof and client key → 400 ambiguous mode.
  • Invalid client key → 401.
  • Village payloads must stay synthetic (no real patient phones).
  • Live requests need idempotency so retries do not double-send SMS.

Deep dive