Skip to content

README.md

Latest commit

 

History

History
281 lines (212 loc) · 19.2 KB

README.md

File metadata and controls

281 lines (212 loc) · 19.2 KB
Raw

FurlPay Documentation & Architecture Blueprints

FurlPay Banner

Digital-Dollar Payment Infrastructure: Documentation & Blueprints

Solana AWS Circle Next.js 15 TypeScript React Native Kotlin Swift Rust PostgreSQL Redis Docker Terraform Linux

Enterprise-grade technical documentation, AWS cloud migration roadmaps, dedicated Agave v2.x Solana RPC specifications, Circle CCTP v2 cross-chain rails, Rain JIT virtual-card rail blueprints, and internal security reviews. Documents marked Blueprint or Plan describe the target architecture, not what runs today.

Current status (15 October 2026)

Area Today Plan
Web app and API Next.js 15 on Vercel (446 route handlers, 269 pages), serving furlpay.com ECS Fargate behind CloudFront (runbook)
Database Supabase Postgres, reached through PostgREST over HTTP Aurora PostgreSQL is not a drop-in replacement; see the engagement brief
Key-value store Upstash Redis (REST), which holds passkeys, API keys and OAuth clients Needs a durable AWS design; ElastiCache speaks TCP, not REST
AI features Claude Haiku 4.5 through the Anthropic API Evaluating Amazon Bedrock
AWS Account set up; no production workloads. Active relationship with AWS Startups BD (from TOKEN2049 Singapore, Oct 2026). Migration planned, not started. Activate credits discussion active; see TOKEN2049 engagement log.
Card issuing Designed, switched off. No card issuer is contracted Issuer selection pending
Banking, on-ramp and off-ramp Switched off; no provider contracted Partner selection pending
iOS app Blocked on an Apple Developer account iOS runbook
Security audits Reports under audit/ are internal reviews; no third-party audit yet —

What FurlPay can state publicly, and with which qualifiers, is governed by the verified-claims register. If a claim is not in its green table, it does not go in an email, a deck or a grant application.

Target Architecture (AWS migration blueprint)

The diagrams below show the planned AWS architecture. None of it is deployed yet.

FurlPay target AWS architecture (planned)

Figure 1: Target AWS architecture (planned, not deployed): multi-AZ private VPC, dedicated Solana RPC nodes, ECS Fargate Next.js 15 backend, Nitro Enclave key isolation and settlement rails.

flowchart TD
    subgraph Clients["Client Applications & Edge Devices"]
        Android["Android Native Mobile App<br/>React Native / AndroidKeyStore / BiometricPrompt"]
        WearOS["Wear OS Companion App<br/>Jetpack Compose / Wearable Data Layer"]
        iOS["iOS Native Mobile App & SDK<br/>Swift / Secure Enclave / PassKit"]
    end

    subgraph Ingress["AWS Global Ingress & Protection"]
        CloudFront["AWS CloudFront Global CDN<br/>Edge TLS 1.3 Termination"]
        WAF["AWS WAF v2<br/>DDoS Shield, Bot Control, Rate Limiting"]
    end

    subgraph PrivateVPC["AWS Private Multi-AZ VPC (10.100.0.0/16)"]
        ALB["Application Load Balancer (ALB)<br/>Dual-Stack Multi-AZ Ingress"]
        
        subgraph ComputeCluster["Application Cluster (Amazon ECS Fargate)"]
            ECS["Next.js 15 App Router Backend Cluster<br/>- Gasless Relayers (EIP-3009)<br/>- Solana Actions & Blinks<br/>- Card authorization webhooks (designed)"]
        end

        subgraph DataTier["State, Caching & Relational Storage"]
            Valkey[("Amazon ElastiCache for Valkey<br/>Atomic Nonce Claims (kvSetNx)<br/>Card JIT balance locks (designed)")]
            Aurora[("Amazon Aurora PostgreSQL Serverless v2<br/>Double-Entry Ledger & Idempotency Storage<br/>Multi-AZ AWS KMS CMK Encryption")]
        end

        subgraph KeyIsolation["Hardware-Isolated Cryptography"]
            Enclave["AWS Nitro Enclaves (Isolated vsock)<br/>KMS Attestation Key Decryption<br/>Relayer & Circle CCTP Mint Signing"]
        end

        subgraph BlockchainTier["Dedicated Blockchain Node Subnet"]
            SolanaNode["Dedicated Solana RPC Node (EC2 i4i.8xlarge)<br/>Agave v2.2 Validator Engine<br/>3.75TB NVMe RAID-0 + 180GB tmpfs AccountsDB<br/>Yellowstone Dragon's Mouth gRPC Geyser"]
        end
    end

    subgraph Rails["Institutional Settlement & Card Networks"]
        Circle["Circle USDC & CCTP v2<br/>TokenMessengerMinterV2 & MessageTransmitterV2<br/>Circle Iris Attestation & Fast Transfers<br/>Circle Mint Fedwire / ACH Clearing"]
        Rain["Card issuer (design target: Rain)<br/>Not contracted · switched off<br/>Just-in-time funding design"]
    end

    Android --> CloudFront
    WearOS --> Android
    iOS --> CloudFront
    CloudFront --> WAF
    WAF --> ALB
    ALB --> ECS
    ECS --> Valkey
    ECS --> Aurora
    ECS --> Enclave
    ECS --> SolanaNode
    ECS --> Circle
    ECS --> Rain
    SolanaNode -.->|gRPC Slot Stream| ECS
Loading

FurlPay payment rails and settlement architecture (design)

Figure 2: Stablecoin payment rails, hardware key signing and the designed card-authorization path (design; card issuing is not live).

Master Documentation Index

0. Deployment & Environments (deploy/)

Operational runbooks for shipping each surface, and the environment contract they all share. Start here if you are moving the platform onto AWS.

  • Environments — development, staging, production
    What an environment is in this codebase: the FURLPAY_ENV financial-mode switch, the Vercel-injected variables that stop existing on AWS (including the one that silently breaks passkeys), the five scheduled jobs, and the managed-service decisions the migration forces.

  • AWS Security Baseline
    The controls that gate a go-live: multi-account topology with SCP boundaries, IAM Identity Center with no IAM users, Secrets Manager, KMS and Nitro Enclave key custody, detection, supply chain, and a go-live checklist.

  • Web — Vercel → AWS
    ECS Fargate behind CloudFront for the app (446 route handlers and 269 pages on 15 October 2026; 314 and 219 when written); why not Amplify, Lambda or App Runner; EventBridge for the crons; the cutover and rollback plan.

  • Android Release Runbook · Play Store Signing
    EAS builds, keystore custody, and the Play App Signing step.

  • iOS Release Runbook
    Currently blocked on an Apple Developer account. Covers the SDK floor, the watchOS and widget targets, and what App Store review asks a financial app.

  • Wear OS Release Runbook
    Why the watch app shares the phone's applicationId, same-key signing, and the fingerprint registration that passkeys depend on.

1. Engineering Blog & Technical Articles (blog/)

2. AWS Cloud & Dedicated Infrastructure Blueprints (aws/)

Everything in this section is a blueprint: planned, not deployed.

  • AWS Engagement Brief: current state, pain points and asks
    Where FurlPay runs today, the nine problems the migration has to solve, and what we are asking AWS for. Start here if you are from AWS.

  • Virtual Card JIT Rails Plan
    How FurlPay virtual cards will work with Rain: real-time authorization against the user's USDC balance, atomic holds, clearing and reversals, funding and daily reconciliation, travel-card merchant locks, failure handling, the AWS layout and a phased rollout. Plan; no issuer contracted yet.

  • Cross-Platform USDC Payment Engine & AWS Architecture (2026–2027)
    End-to-end USDC payment flow across Android Native (native-app), Wear OS (guardian), iOS (furlpay-swift), and AWS dedicated infrastructure. Covers hardware Keystore/Secure Enclave signing, EIP-3009 gasless transfers, Solana v0 transactions, a designed card-authorization path, Circle CCTP v2 burn-and-mint and AWS Nitro Enclaves.

  • 1-Year Master Infrastructure & AWS Migration Blueprint (2026–2027)
    Complete 12-month engineering roadmap moving FurlPay from Vercel edge functions and managed RPC providers (Helius/QuickNode) to a private Multi-AZ VPC on Amazon Web Services (AWS).

  • AWS Infrastructure Cost Model & FinOps Report
    Modeled cost of the planned architecture, cut from $44,040/year to $21,480/year (51.2%) by replacing io2 Block Express IOPS with local Nitro NVMe SSDs (i4i.8xlarge), adopting ElastiCache for Valkey and optimizing standby RPC failover. These model a future bill; FurlPay has not incurred this spend.

  • Credits Funding Plan & Solana Node Specification
    A plan to fund the planned infrastructure with AWS Activate credits and Solana Foundation grants; those credits and grants have not been secured. Contains official Agave v2.2 validator arguments, Linux sysctl tuning (21-agave-validator.conf), dual NVMe RAID-0 storage scripts, tmpfs AccountsDB setup, Yellowstone Dragon's Mouth gRPC configuration, and automated slot health monitoring.

  • AWS Enterprise Security, Compliance & Infrastructure Blueprint (2026–2027)
    Advanced defense-in-depth architecture covering AWS Organizations multi-account governance, KMS envelope encryption with Nitro Enclave PCR attestation, production Terraform IaC modules (VPC, ECS Fargate, WAF v2), a control mapping towards PCI DSS v4.0 and SOC 2 Type II (FurlPay holds neither certification), multi-region disaster recovery runbooks, and SRE alerting matrices.

  • TOKEN2049 AWS Engagement Log
    Timeline of the AWS Startups relationship established at TOKEN2049 Singapore (October 2026), Activate credits discussion status, competitor comparable analysis, and call-preparation notes.

3. Security Reviews & Vulnerability Assessments (audit/)

These are internal reviews. FurlPay has not had a third-party security audit.

  • Monorepo Security Review (internal)
    Internal code review across Solana Anchor programs, Next.js API routes, Android/Wear OS native applications, and client SDKs. Uncovers and remediates critical vulnerabilities including the Solana escrow token drain in auto_release.rs, merchant wallet fallback to 1111...1111, WooCommerce/Magento HMAC bypass, Swift timing side-channel leaks, and Android SQLite encryption.
  • Mobile Security Audit & Hardening Guide
    Analysis of Android and iOS cryptographic boundaries, reverse engineering protections, anti-hooking checks, and biometric authentication gates.
  • x402 Micropayment Attack Vectors & Mitigation
    Facilitator-layer hardening for HTTP 402 AI agent payment rails, closing cross-resource substitution (F1) and duplicate settlement race conditions (F2).
  • Transaction Security Standards
    The unified authorization boundary: transaction simulation and app attestation built as one control, implemented end to end and covered by 148 tests.

4. Mobile, Wearable & Client Protocols (docs/)

5. Protocols, Settlement & Custody Models (docs/)

6. Expansion Blueprints & Strategy (reports/)

Technology Stack Breakdown

Layer Technologies & Protocols
Hosting & data (current) Vercel (Next.js), Supabase Postgres via PostgREST, Upstash Redis (REST), Anthropic API (Claude Haiku 4.5).
Cloud & Infrastructure (target) Amazon Web Services (AWS), planned: EC2 i4i.8xlarge, ECS Fargate, CloudFront, ALB, Aurora PostgreSQL Serverless v2, ElastiCache for Valkey, AWS Nitro Enclaves, AWS KMS, Amazon SNS, CloudWatch, Terraform.
Dedicated Blockchain Node (target) Agave v2.2.x (Solana Validator Engine), Yellowstone Dragon's Mouth gRPC Geyser, Ubuntu 24.04 LTS, Nitro NVMe RAID-0, Linux tmpfs AccountsDB.
Cross-Chain & Stablecoins Circle USDC, Circle CCTP v2 (MessageTransmitterV2, TokenMessengerMinterV2), Circle Iris Attestation API, Circle Mint API, Circle Programmable Wallets, Circle Arc.
Card Issuing: Rain JIT rails (plan) Rain virtual cards with just-in-time authorization against USDC balances, atomic holds and daily reconciliation (plan). No issuer is contracted; card issuing is switched off.
Backend Application Next.js 15 (App Router), Node.js 22, TypeScript 5.5, Zod, Viem, @solana/web3.js, EIP-3009 Gasless Relay Engine, EIP-712 Typed Signing.
Mobile Applications React Native / Expo (Android & iOS), Kotlin 2.1 (Android & Wear OS Compose), Swift 6.0 (iOS / Apple Watch), Google Play Integrity API, AndroidKeyStore, Apple Secure Enclave.
Security & Cryptography Hardware-backed Biometric Authentication (Class 3 / Strong), Ed25519, Secp256k1, AES-256-GCM, Constant-Time HMAC-SHA256, Zeroization.

Community & Support

Copyright © 2026 FurlPay Inc. All rights reserved. Sovereign financial rails for the next billion users.