Skip to content

README.md

Latest commit

 

History

History
324 lines (247 loc) · 25.2 KB

README.md

File metadata and controls

324 lines (247 loc) · 25.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: the AWS migration architecture, Solana Alpenglow finality handling, 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 (22 October 2026)

22 October 2026: FurlPay is moving from Vercel and Supabase to AWS. The decision is made and the work has started in code; nothing is deployed on AWS yet. The chosen architecture is in Enterprise Financial Infrastructure Architecture (2026–2027).

Status categories:

  • Production: live on furlpay.com.
  • Implemented, not deployed: written and tested, not yet released.
  • Experimental: works only against a sandbox or mock.
  • Planned: not built.
  • Blocked: waiting on an external dependency.
  • Switched off: built but disabled in production.
Area Status Today Plan
Web app and API Production Next.js 15 on Vercel (472 route handlers, 272 pages), serving furlpay.com. The latest production release shipped on 21 October 2026. Functions run in a single region across multiple availability zones. Migration decided 22 October 2026: ECS Fargate behind CloudFront and AWS WAF (architecture, runbook)
Database Production Supabase Postgres, reached through PostgREST over HTTP. Production schema migration status is being verified. Features whose tables are not yet present fail closed rather than run without them. Decided: Aurora PostgreSQL reached with the native pg driver, and S3 in place of Supabase Storage. The data layer is being rewritten in code (not merged). See the PostgreSQL migration plan
Key-value store Production, degraded Upstash Redis (REST) holds passkeys, API keys, OAuth clients, rate limits and duplicate-request protection. As of 21 October it is at its plan's capacity limit. Sign-in and money-movement endpoints that depend on it fail closed (they refuse rather than run unprotected) until capacity is raised. Raise capacity. The long-term AWS design still needs work, because ElastiCache speaks TCP, not REST.
Stablecoin payment acceptance Switched off Built, but no settlement assets are enabled in production. The background jobs for merchant payments are not operating. Enable after the database and capacity items above are resolved
Bank-network rail (Kinexys) Experimental Adapter tested only against J.P. Morgan's public mock API. Production access is disabled in code, and there is no production credential or banking relationship. —
Organizations and roles Production (fails closed) Shipped 21 October. It needs a database migration whose production status is being verified, and refuses requests until that table exists. —
Solana network Production (network) Alpenglow is live on mainnet (21 October 2026, epoch 1064). FurlPay credits Solana payments only at finalized commitment, which Alpenglow makes final in a target of about 150 ms (a consensus target, not FurlPay's end-to-end time). Consensus detection, Solana health checks and measured credit latency are built and tested on a branch (Alpenglow architecture)
AI features Production Claude Haiku 4.5 through the Anthropic API Evaluating Amazon Bedrock
AWS Planned, migration decided Account set up; no production workloads. Infrastructure-as-code exists in the application repository and has not been applied. Active relationship with AWS Startups BD (from TOKEN2049 Singapore, Oct 2026). Migration decided 22 October 2026 and started in code; see the backlog. Activate credits discussion active; see the TOKEN2049 engagement log and the resilience principles and status.
Card issuing Switched off 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 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. The decided design as of 22 October 2026, with the status of every component, is in the enterprise architecture. Figure 1 predates that decision and still shows a dedicated Solana node, which is no longer part of the plan.

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

    end

    SolanaNode["Managed Solana and EVM RPC providers<br/>ordered failover, chain identity proven per endpoint<br/>no self-operated nodes"]

    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
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

Enterprise architecture (October 2026)

The AWS migration and post-Alpenglow architecture, with an explicit status (LIVE, IMPLEMENTED, TESTED, PLANNED, RESEARCH, BLOCKED) on every component.

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 (472 route handlers and 272 pages on 21 October 2026; 314 and 219 when written); why not Amplify, Lambda or App Runner; EventBridge for the crons; the cutover and rollback plan.

  • Resilience: Principles & Status
    How FurlPay is designed to survive a zone outage without charging twice: the status of each resilience capability (production vs. planned), and the Idempotency-Key contract integrators should follow when retrying requests.

  • 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. Superseded: the model assumes self-operated Solana nodes, which the October 2026 architecture does not include.

  • 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. Superseded for node operations: since Alpenglow, mainnet requires Agave v4.3.2, and dedicated nodes are no longer planned. Contains 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, with findings and the fixes made for them. This is an internal review, not a third-party audit, and its remediation claims have not been independently verified. Report security issues to security@furlpay.com rather than relying on this document's status.
  • 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, decided 22 Oct 2026) Amazon Web Services (AWS): Route 53, CloudFront, AWS WAF, ALB, ECS Fargate, Aurora PostgreSQL 16 Serverless v2 (native pg driver), Amazon S3, ElastiCache, Amazon SQS, EventBridge, Secrets Manager, AWS KMS (Ed25519 and secp256k1 signing), CloudWatch, GuardDuty, CloudTrail, Terraform. Nitro Enclaves under research.
Blockchain access Managed RPC providers with ordered failover; each endpoint must prove it serves the right chain. No self-operated nodes are planned (Solana mainnet now requires Agave v4.3.2; see AWS Data and Event Infrastructure).
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.