Web3 payment rails: the reference architecture

"Payment rail" is borrowed language, and it flatters most crypto payment products. A rail implies a network with rules, membership and dispute handling. What Web3 payment companies actually build is an orchestration layer: software that connects a public blockchain on one side to regulated financial institutions on the other, and keeps a coherent record across both. That is a narrower claim and a much more useful design brief.

The components

1. Wallet layer

The user's key stays with the user. This layer connects to wallets, requests signatures for transactions the backend has built, and surfaces the connected address for verification. It should never handle key material, and it should refuse to display or accept a seed phrase in any context. Practically: adapters for the wallets your users actually have, a clear connected state, and an explicit indication of which address will receive any output.

2. Quoting and routing

Given an input asset and amount, this layer determines the route to the settlement asset and the expected output. On Solana, routing across liquidity venues is handled by aggregation infrastructure such as Jupiter; the orchestrator's job is to request a quote, apply its own limits and slippage policy, attach its fee transparently, and set an expiry. A quote without an expiry is a liability.

3. Transaction construction and submission

Build unsigned transactions server-side, where validation rules live and cannot be bypassed. Send them to the client for signature, accept the signed payload back, and submit it. This split keeps guards enforceable: allowed mints, amount ceilings and floors, and a destination restricted to the connected wallet. Any request carrying an unexpected destination field should be rejected outright rather than sanitised.

4. On-chain verification

A separate component that answers one question authoritatively: did this payment arrive, in the expected asset, in the expected amount, at the expected address, finally? It talks to RPC infrastructure, is cluster-aware, and is the only component permitted to move a payment into a state that triggers downstream money movement.

5. The state machine

This is the heart of the system, and the component most often deferred. Every payment is a row with an explicit status, a monotonic event log, and defined legal transitions. Everything else — user-facing status, receipts, admin tooling, reconciliation, analytics, support — reads from it.

• One authoritative status field, with transitions enforced in code rather than by convention.
• An append-only event table: what happened, when, triggered by what, with the external identifier involved.
• Idempotency keys on every mutating operation, so retries and duplicate webhooks collapse into one effect.
• A recorded reason on every terminal state, in language a support agent can read to a customer.

6. Payout partner integration

The boundary to the regulated world. This layer creates customer records, submits payout instructions, and receives asynchronous status updates. Three rules keep it manageable: treat the partner's identifiers as foreign keys rather than your primary state, verify every inbound webhook signature before acting on it, and never let partner downtime corrupt your own state — queue and retry instead.

7. Operations and observability

A rail you cannot observe is a rail you cannot operate. The minimum is structured logs keyed by payment identifier across every leg, an admin view that shows a payment's full event history, alerting on stuck states rather than only on errors, and a daily reconciliation between on-chain facts, partner-reported payouts and your own ledger.

The seam that defines the design

Two of these components are verifiable by anyone — construction and on-chain verification. Two are entirely dependent on a counterparty — payout integration and the identity checks around it. The architecture's main job is to keep that seam visible instead of blurring it.

Ledger discipline

Once value crosses a boundary, a status field is not enough. Double-entry ledger entries — every movement recorded twice, against named accounts — are what make it possible to answer "where is the money" and "do our books balance" without reading application code. The accounts worth modelling early are the user's deposit, the platform's settlement balance, fee income, partner-held balance, and payout in flight. Retrofitting this after launch is significantly more painful than adding it before.

Security posture

The attack surface of a Web3 payment rail is unusual: one side is a public network where mistakes are irreversible, the other holds identity data. A short list that catches most of it:

• All third-party credentials server-side, never in a client bundle, never in a public environment variable.
• Input validation on every endpoint with a schema, rejecting unknown fields rather than ignoring them.
• Row-level access control on every table holding customer or transaction data.
• Authorisation on operator endpoints, separate from end-user authentication, with an audit log for privileged actions.
• Webhook signature verification before any state change.
• Rate limiting on quoting and creation endpoints, which are the cheapest to abuse.

A realistic build order

1. 1Wallet connection and on-chain verification — the components you can prove without any partner.
2. 2Quoting and conversion into the settlement asset, with strict limits while it is young.
3. 3State machine, event log and idempotency.
4. 4Ledger entries and reconciliation.
5. 5Admin tooling and structured logging.
6. 6Deposit monitoring and automated status progression.
7. 7Identity verification provider.
8. 8Regulated payout partner and live fiat legs.
9. 9Limit increases behind risk controls, then broader corridor coverage.

The ordering is deliberate: everything above step seven can be built, tested and demonstrated without a regulatory dependency, and each step makes the next one safer. LamportPay follows this sequence — the wallet, conversion and verification components run live under tight limits, the state and admin layers exist for the demonstrated flow, and the identity and fiat payout legs are labelled simulations pending a regulated payout infrastructure partner.