Overview

An existing e-commerce platform wanted to add blockchain payments alongside traditional payment methods.
The system needed to support:

  • one-time purchases
  • subscriptions and recurring payments
  • refunds, reversals, cancellations
  • revenue splits between sellers, nonprofits, and the platform
  • rewards and points recorded on-chain

This required a hybrid on-chain/off-chain system with reliable reconciliation and clear sources of truth.

My role

  • Designed end-to-end payment flows
  • Implemented:
    • backend integrations
    • smart contract interaction logic
    • indexing and subgraph polling
    • fund management and settlement workflows
  • Worked closely with the smart contract developer to finalize integration flows
  • Owned the off-chain system correctness and state synchronization

Architecture Overview

  • Users initiated payments via their wallet to an intermediary smart contract
  • Funds were held on-chain until settlement
  • An admin-triggered settlement distributed funds:
    • seller payouts
    • nonprofit allocations
    • platform fees
  • Rewards, points, and accounting events were recorded on-chain
  • A subgraph indexed all payment-related events
  • A subgraph backend polled indexed events and forwarded them to the main backend
  • The main backend:
    • updated balances
    • managed rewards and points
    • exposed user-visible state
  • Users could withdraw funds:
    • on-chain transfer occurred
    • fiat payout executed off-chain using platform tokens

Polling was used to guarantee reliability across restarts and failures.

Indexed On-Chain events

  • The system indexed and processed a wide range of events, including:
    • ProductSold
    • DonationReceived
    • UserWithdrawInitiate / Complete / Reverted
    • NonprofitFundsSettled / Received
    • TokenStatusUpdated
    • RecurringDonationDeactivated
    • Vault deployment and settlement events
  • All backend state was derived from confirmed on-chain events.

Trust and Consistency Model

  • On-chain events were the ultimate source of truth
  • Subgraph indexing ensured ordered, block-based synchronization
  • Backend sync logic:
    • tracked block numbers
    • replayed missing ranges on startup
  • Event ordering was enforced to handle:
    • delayed confirmations
    • multi-step payment flows
    • future events arriving before intermediate states

Key Challenges

  • Fund locking & sequencing: ensuring multiple dependent events completed before confirmation
  • State synchronization: keeping blockchain state and backend state aligned at all times
  • Price volatility: prices were fetched at transaction start and frozen for the entire payment lifecycle
  • Operational complexity
    • multiple user types
    • multiple settlement paths
    • lack of unified product pricing abstractions

What I’d Improve If Rebuilding Today

  • Add strong idempotency guarantees
  • Formalize queues earlier for all state transitions
  • Decouple pricing logic via explicit dependencies instead of DB lookups
  • Improve internal abstractions for products and user roles
  • Keep polling for subgraph reliability, but harden event delivery between backends