Matchids CeloHT

Web3 payment integration for Matchids. CeloHT is a dapp that lets people send and receive CELO and USDm on the Celo blockchain — this repo makes CeloHT usable as a Matchids payment method, for both premium book purchases and Give Back donations.

What's here

src/
  types.ts             PaymentProvider contract (mirrors @matchids/payments)
  CeloHTProvider.ts     The provider implementation — see below
  wallet.ts              Wallet connection / balance integration points
  index.ts                Public exports
tests/                  Vitest tests — assert the provider fails safely when unconfigured
docs/
  INTEGRATION.md         Exactly what to fill in once CeloHT's API details are available

What is real vs. a placeholder

Nothing invented anywhere in this repo: no contract address, ABI, RPC endpoint, CeloHT API route, wallet address, or private key. CeloHTProvider.isConfigured() checks for CELOHT_API_BASE_URL and CELOHT_API_KEY (see .env.example) — until both are real, createIntent() throws a clear error and verifyTransaction() always returns verified: false. Matchids' checkout is expected to read isConfigured() and show CeloHT as "coming soon" rather than offering a payment method that can't work.

Integration with matchids-payments

This package implements the same PaymentProvider interface exported by @matchids/payments, duplicated locally in src/types.ts so this repo typechecks and tests on its own. When wiring the real system together, matchids-backend registers this provider with the shared service:

import { PaymentService } from "@matchids/payments";
import { CeloHTProvider } from "@matchids/celoht";

const paymentService = new PaymentService([new CeloHTProvider()]);

Security

• Transaction verification always runs server-side. A payment or donation is never marked confirmed because the frontend says a transaction succeeded — see verifyTransaction().
• No private key is ever read, stored, or logged by this package. Wallet signing happens in the user's own wallet (Valora, etc.), never here.

Local setup

npm install
cp .env.example .env   # leave CeloHT values blank until you have real ones
npm test

See docs/INTEGRATION.md for the exact checklist to activate the real integration once CeloHT shares API details.