Skip to content

protocol-overview.mdx

Latest commit

 

History

History
310 lines (225 loc) · 11.9 KB

protocol-overview.mdx

File metadata and controls

310 lines (225 loc) · 11.9 KB
title Protocol Overview
description Deep dive into the Paycrest protocol architecture, participants, and core components

The Paycrest protocol is a decentralized payment routing protocol designed to bridge the gap between digital assets and real-world financial systems. This overview covers the core architecture, participants, and key components.

Protocol Vision

Paycrest exists to solve the fundamental problems with cross-border payments in emerging markets:

  • High costs from legacy intermediaries and fragmented liquidity
  • Slow settlement due to closed banking networks
  • Poor user experience with complex compliance requirements
  • Limited accessibility for underbanked populations

Our solution enables near-instant fiat/stablecoin conversion via a decentralized network of liquidity provider, with zero transaction fees for senders and embedded compliance through user-friendly flows.

Mission-Driven Architecture

Our mission "To accelerate the creation of democratized payment systems of the future" is reflected in every aspect of our protocol design:

No single entity controls the flow of funds or user access. The protocol operates through a network of independent participants. Anyone can participate as a sender, provider, or developer. No gatekeepers or exclusive access requirements. All transactions are visible on-chain with complete audit trails. No hidden fees or opaque processes. Local payment solutions work seamlessly with global networks, preserving local context while enabling global reach.

This mission drives our technical decisions, from the multi-chain architecture to the developer-friendly APIs that make integration accessible to everyone.

Core Architecture

The Paycrest protocol consists of several key components working together:

1. Gateway Smart Contract

The core multi-chain contract deployed on fast EVM-compatible networks (e.g., Base, Arbitrum, Lisk). It manages:

  • Order creation and validation
  • Token escrow and conditional settlement
  • Fee distribution and protocol governance
  • Multi-chain interoperability

2. Paycrest Node

The unified protocol client that can operate in three modes:

- Listens to onchain payment order events - Indexes registered Providers - Performs matching logic - Validates KYC data offchain - Issues onchain attestations - Registers liquidity parameters - Monitors order matching - Integrates with Payment Service Providers (PSPs) - Performs last-mile fiat delivery - Submits fulfillment proofs - Operates as both Aggregator and Provider - Useful for participants with both capabilities - Optimizes for participants with full-stack operations

3. Sender API & Webhooks

Interfaces that allow businesses and apps to:

  • Create payment orders with operational settings
  • Configure refund addresses, fee addresses, and fee percentages
  • Manage API keys and authentication
  • Receive real-time updates on status transitions
  • Handle webhook notifications for order lifecycle events

4. KYC Attestation Registry

A registry of attestations for both Senders and Providers:

  • Onchain attestations for identity verification
  • Offchain verifiable credentials support
  • Encrypted KYC data stored on decentralized storage
  • Compliance integration with regulatory requirements

Protocol Participants

Sender

A KYC-verified entity that initiates either a fiat-to-stablecoin or stablecoin-to-fiat transaction. This can be:

  • Smart contracts or dApps
  • API clients integrating with the protocol
  • EIP-4337 smart accounts for advanced wallet functionality
  • Traditional applications abstracting away blockchain complexity

The sender supplies the recipient's fiat account information and initiates the payment order.

Recipient

The beneficiary of the transaction who receives:

  • Local fiat in a bank account or mobile wallet
  • Stablecoins in a crypto wallet

The recipient doesn't need to interact with the protocol directly - they simply receive the funds through their preferred method.

Provider

A KYC-verified participant that supplies fiat liquidity in exchange for stablecoins or provides stablecoins in exchange for fiat. Providers:

  • Connect to the aggregator and register rates and limits
  • Fulfill payment orders (off-ramp or on-ramp)
  • Receive corresponding assets post-validation
  • Integrate with Payment Service Providers (PSPs) for last-mile delivery

Aggregator

A KYC-verified entity that coordinates the entire order routing process:

  • Listens to payment order events from the Gateway contract
  • Matches orders with suitable Providers
  • Coordinates fulfillment and settlement
  • Performs offchain KYC verification for both Senders and Providers
  • Splits large orders across multiple Providers
  • Issues onchain attestations for compliance
  • Enforces penalties for failed delivery

Order Lifecycle

Sender creates a payment order on the Gateway contract with recipient details, amount, and rate. Aggregator indexes the order and matches it with suitable Providers based on rates, limits, and availability. One or more Providers are assigned to fulfill the order, with the order potentially split across multiple Providers. Providers execute the payment:
  • Offramp: Provider delivers fiat to the recipient via PSP integration.
  • Onramp: Provider receives fiat from the sender via local payment rails.
  • Offramp: Provision node validates fulfillment by checking the status of the fiat transfer via PSP APIs.
  • Onramp: Aggregator validates fulfillment by confirming the onchain stablecoin transfer to the recipient.
  • Offramp: Smart contract releases escrowed stablecoins to the provider after successful validation.
  • Onramp: Fulfillment, validation, and settlement occur in one step: after the provision node confirms fiat receipt, the stablecoins are released onchain to the recipient.
If the order cannot be fulfilled, funds are automatically refunded to the sender. No manual dispute process is required. Offramp: Fulfillment = Provider delivers fiat to recipient. Validation = Provision node checks fiat transfer status via PSP API. Settlement = Escrowed stablecoins released to provider.

Onramp: Fulfillment = Provider receives fiat from sender. Validation = Aggregator confirms onchain stablecoin transfer to recipient. Settlement = All three steps happen atomically after fiat receipt is confirmed.

Multi-Chain Support

Paycrest supports the following blockchain networks for fiat and stablecoin transactions:

  • Base
  • Polygon
  • BNB Smart Chain
  • Arbitrum One
  • Lisk
  • Celo

Support for additional networks is planned as the protocol evolves.

Future Expansion

  • Modular chains: App-specific rollups and Layer 3s
  • App-specific rollups: Custom chains for specific use cases
  • Cross-chain bridges: Seamless asset movement between chains

Security & Compliance

Smart Contract Security

  • Audited Gateway contracts with escrow functionality
  • Multi-signature governance for protocol upgrades
  • Timelock mechanisms for critical parameter changes
  • Emergency pause functionality for security incidents

Compliance Integration

  • KYC/KYB verification for all participants
  • Identity attestation registry onchain
  • Regulatory reporting capabilities
  • AML/CFT compliance through integrated providers

Privacy Protection

  • Encrypted recipient data stored offchain
  • Zero-knowledge proofs for compliance verification
  • Selective disclosure of sensitive information
  • GDPR compliance for user data protection

Fee Structure

The Paycrest protocol implements a zero-fee experience for senders:

  • Sender fees: Optional fees that sender businesses can charge to their users
  • Provider fees: Competitive rates based on market conditions
  • Protocol fees: Fees paid to aggregators for order routing and coordination
  • Network fees: Gas costs for blockchain transactions

Providers earn fees by:

  • Bid-ask spreads on currency pairs
  • Volume-based incentives for high-frequency providers
  • Quality bonuses for reliable fulfillment
  • Geographic premiums for underserved markets
**Fee Structure Clarification:** In the current beta phase, Paycrest operates the only aggregator, so aggregator fees are paid to Paycrest. As the protocol scales, multiple aggregators will compete for order routing, similar to how Ethereum validators earn fees for adding transactions to blocks. This creates a decentralized marketplace where aggregators earn fees for providing order routing services.

Delivery Methods

  • Bank Transfer: Direct deposit to local bank account
  • Mobile: Transfer to mobile wallet (M-Pesa, etc.) or mobile payment systems (UPI, PIX)
  • Crypto Wallet: Receive stablecoins in specified wallet

Cash pickup is not supported. All off-ramps are to fiat accounts or wallets.

Governance

Early Stage

In early stages, protocol changes are ratified by a Paycrest Core Multisig:

  • Founding contributors and technical leads
  • Multi-signature requirements for all changes
  • Transparent proposal process with community input
  • Emergency procedures for critical updates

Future Decentralization

As the protocol matures, governance will transition to:

  • Community-led structure with token-weighted voting
  • Delegate-based technical councils for specialized decisions
  • Onchain governance for parameter changes
  • Off-chain coordination for complex upgrades

Technical Specifications

Smart Contracts

  • Gateway Contract: Core order management and escrow
  • Token Contracts: Standard ERC-20 implementations
  • Governance Contracts: Multi-signature and timelock mechanisms
  • Attestation Registry: KYC and compliance verification

API Standards

  • RESTful API for all interactions
  • WebSocket support for real-time updates
  • Webhook integration for event notifications
  • Rate limiting and authentication

Network Requirements

  • High availability aggregator nodes
  • Low latency blockchain connections
  • Redundant infrastructure for reliability
  • Geographic distribution for global access

Dispute Resolution

If an order is not fulfilled, it is automatically refunded. The aggregator does not handle disputes directly. If an order is stuck, communication between senders and providers may occur via a decentralized messaging protocol (e.g., XMTP).

Integration Options

Senders can create orders via:

  • The Sender API (recommended for most users)
  • Direct contract interaction (for advanced/offramp use cases)
The Paycrest protocol is designed to be both Web3-native and accessible to traditional financial applications. The modular architecture allows for different deployment models while maintaining the core benefits of decentralization.