FPSF-SS-002 — Overview
Layer: Overview · Audience: wallet developers, Processor operators, technical evaluators For normative requirements, see the Formal Specification.
What the wallet-gateway Is
The wallet-gateway is the single network entry point for wallet client applications in the Stablecoin Stack. It is where a wallet connects, queries data, submits payments, and receives real-time status updates.
Wallet developers do not interact with the payment network directly. They interact with the wallet-gateway. This boundary is intentional: it delegates all network-layer complexity to the Processor's infrastructure and gives wallet implementers a clean, well-defined interface.
What It Does
The wallet-gateway provides five categories of service:
Data retrieval. Current token balances, transfer history, permit nonces, and fee breakdowns are available on demand. Fee queries return the full breakdown: operatorFee, acquiringFee, and totalWithFees — all computed per-token by the Settlement Contract.
Payment submission. The wallet submits a fully signed payment payload. The gateway accepts it, routes it to the broadcast-service, and delivers status updates as the operation progresses through to network confirmation.
Acquirer registration submission. The same asynchronous submission model applies to Acquirer registration requests.
Real-time notifications. A wallet may subscribe to receive push notifications for balance changes and new confirmed transfers on any subset of supported tokens.
Wallet initialisation. On a wallet's first connection, the gateway transparently collects the complete transfer history and initial balance snapshot, making this data immediately available for subsequent queries.
What It Is Not
The wallet-gateway is not an execution engine. It does not broadcast transactions or interact with the Settlement Contract. When a wallet submits a payment, the gateway enqueues it with the broadcast-service and relays status updates.
It is not a custodian. It holds no token balances. A gateway compromise does not expose user funds — cryptographic integrity is enforced by the Settlement Contract independently.
It is not a source of truth for settlement. A SUCCESS submission status means the transaction was accepted by the network without error. Final settlement is determined by transfer-history after sufficient block confirmations, and is delivered as a TRANSFER_NOTIFICATION push notification.
Connection Model
The gateway uses WebSocket exclusively. All operations — data queries, payment submissions, and real-time notifications — share the same connection. This is by design: payment confirmation is inherently asynchronous, spanning multiple block intervals, and WebSocket allows the gateway to push status updates to the client as they arrive.
Every message the wallet sends is signed with its private key. There are no sessions, API keys, or cookies. Authentication is per-message and cryptographic.
Relationship to FPSF-SS-001
This specification is a companion to FPSF-SS-001. All data structures — TransferRequest, BuyAcquiringPackRequest, PayWithPermitParams — are defined in FPSF-SS-001 and referenced here by section number. Key changes from the base spec that this gateway interface reflects:
GET_FEESreturns aBrokenDownAmountwithoperatorFee,acquiringFee, andtotalWithFeesseparately (reflecting the per-token, two-component Operator Fee model of FPSF-SS-001 Section 13).SUBMIT_PAYMENTacceptsPayWithPermitParamswithorderReferenceandacquirerIdas separatebytes16fields — not concatenated.SUBMIT_ACQUIRINGacceptsBuyAcquiringPackPermitParamswith theacquiringFeeBps_field.
Document Map
| Layer | Document | Purpose |
|---|---|---|
| Formal Specification | SPEC.md | Normative definitions |
| Overview | this document | What it is and why it exists |
| Core Concepts | Connection model, authentication, subscriptions | |
| Guides | Connect, submit payments, handle notifications | |
| Governance | Versioning, changelog | |
| Reference | Message type index, error codes, glossary |
FPSF-SS-002 v1.0.0 · Draft · Fabric Payment Standards Foundation · Apache-2.0