Titan
A distributed invoicing and payment orchestration system bridging traditional business workflows with blockchain settlement.
Supports SOL, USDC, and cNGN payments with on-chain notarization via the Ethereum Attestation Service on Base.
[DIR]: /metadata
[DIR]: /problem_statement
Traditional invoicing systems have no verifiable, tamper-proof record of payment — settlement happens off-chain, and trust is placed entirely in intermediaries or manual reconciliation. Titan bridges that gap: a business-standard invoicing workflow on the front end, blockchain settlement and attestation underneath.
The technical constraints are specific to financial software: idempotent payment creation (no duplicate charges on retry), decimal-precision arithmetic (no floating-point rounding errors in money), and support for both traditional users (email/password) and wallet-native crypto users (Sign-In With Solana) under a single auth system.
[DIR]: /architecture
Titan is a pnpm monorepo: a NestJS API (titan-api) and a Vite & React Router v7 frontend (titan-web) directly consume ts-rest contracts (@titan/api-contract) for full type safety across the client/server boundary. Prisma lives in its own package (@titan/db) to keep the ORM layer decoupled from both builds. On-chain logic runs through an Anchor program on Solana, with Codama generating a typed client from the program IDL. Invoice notarization writes attestations to Base via the Ethereum Attestation Service (EAS). UI is inspired by the Attack on Titan anime
[DIR]: /key_decisions
- Dual authentication strategy: JWT for traditional email/password users, wallet-signature verification (Sign-In With Solana) for wallet-native users — both issue the same session token so the rest of the API doesn't need to know which auth path was used.
- Idempotent invoice creation: Payment endpoints are financial-critical; a retried request must never create a duplicate invoice or double-charge. Idempotency keys enforce this at the API boundary.
- Decimal-precision arithmetic for money: Line items and totals use decimal types rather than floats — financial software can't tolerate floating-point rounding drift.
- JWT refresh rotation with Redis blacklisting: Refresh tokens rotate on use and old tokens are blacklisted in Redis, closing the replay-attack window that stateless JWT refresh normally leaves open.
[DIR]: /outcomes
- Multi-strategy authentication shipped: JWT with Redis-backed revocation plus wallet-based signature auth.
- Full invoice lifecycle implemented — creation, state transitions, payment tracking.
- Blockchain payment verification via Solana RPC polling against a treasury wallet.
- Idempotent invoice creation preventing duplicate submissions under retry.