Skip to content
cofreadminwallet
app
Public

About

self-custodial web3 personal finance.

cofreadmin.gfin.app

Topics

expense-trackinggamified-smart-vaultsglobal-payment-appnative-usdcpersonal-financesavingsself-custodial

Resources

Readme
License
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

CofreAdmin 🔐

Self-Custodial Web3 Personal Finance
USDC Vault Manager on Base Network
Docs: Resources & Documentation
Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

📖 Overview

CofreAdmin is an open-source, self-custodial personal finance web application and digital dollar wallet built on the Base network (Ethereum Layer 2).

Designed with the familiarity and responsiveness of modern consumer banking apps, CofreAdmin eliminates Web3 friction: users can save in digital dollar vaults, send and receive payments, and organize their finances with human-friendly transaction memos—all while retaining 100% cryptographic self-custody over their private keys.

✨ Key Features

  • 🛡️ True Self-Custody (BIP-39 + Versioned WebCrypto Vault): Wallets are generated locally using BIP-39 12-word mnemonics (generateMnemonic + mnemonicToAccount HD derivation) and encrypted at rest with AES-GCM 256-bit powered by a non-extractable (extractable: false) IndexedDB CryptoKey (v3 envelope) or PBKDF2 100k iterations (v2 envelope). Servers and cloud databases never see or store your private keys or mnemonics.
  • 🔄 Continuous Crypto-Agility & Multi-Generation Account Upgrade Engine: Built with a forward-compatible, versioned wallet architecture (v1 → v2 → v3+) that automatically detects balances from previous wallet generations on Base L2, guides a 1-click on-chain sweep to the latest cryptographic standard, and enforces mandatory recovery backup—ensuring zero fund loss across current and future security upgrades.
  • 💵 Digital Dollar Savings (USDC on Base): Create themed savings vaults with custom target amounts and deadlines to separate spendable funds from savings.
  • ⛽ Zero-ETH Gasless Experience: Pay transaction fees directly with your USDC balance using Circle Paymaster and EIP-3009 (TransferWithAuthorization) meta-transaction rails—no native ETH required.
  • ⚡ Instant Pay & Receive: Scan QR codes with your device camera or share high-contrast branded receive cards with EIP-55 checksum validation.
  • 🏷️ Smart Ledger & Human Memos: Transform raw, cryptic blockchain hashes (0x3f...) into human-readable named entries (e.g., "Groceries", "Freelance invoice") with customizable categories.
  • 📊 Financial Insights & PDF Export: Track daily spending pace, review category breakdowns, and export clean, accountant-ready PDF and CSV reports in one click.
  • 📱 Progressive Web App (PWA): Installs directly to iOS and Android home screens as a native-feeling standalone app with offline caching and zero app store middlemen.

🛠️ Tech Stack

  • Language & Runtime: TypeScript (~5.8), Node.js (>=20)
  • Frontend: React 19, Vite 6, Tailwind CSS 4, Motion
  • Web3 & Blockchain: Viem 2 (EVM / Base Network L2, BIP-39 HD Accounts, EIP-3009)
  • Backend & Bundler: Express 4, esbuild
  • Hosting & Cloud: (Deployable to any cloud provider; preconfigured for Firebase App Hosting)

📋 Prerequisites

Before installing, ensure your environment meets these requirements:

  • Node.js: v20.0.0 or higher (v22.x recommended)
  • npm: v10.0.0 or higher
  • Git

🚀 Installation & Local Development

Follow these steps to run a fully functional independent instance locally:

1. Clone the Repository

git clone https://github.com/cofreadminwallet/app.git
cd app

2. Install Dependencies

npm install

3. Create Environment Configuration

Copy the template .env.example file to create your local .env:

cp .env.example .env

4. Start the Development Server

npm run dev

The app will start at http://localhost:3000 with hot-reloading enabled.

5. Build for Production Locally

npm run build
npm run start

⚙️ Environment Variables & Configuration (.env)

All configuration is isolated in environment variables. Open your .env file to customize the following settings:

A. Firebase Setup (Cloud Database & Google Authentication)

Firebase powers cloud database synchronization and Google Social Login. (Guest / Offline mode works 100% locally without Firebase).

💡 Enabling Google Sign-In: In your Firebase Console, navigate to Authentication > Sign-in method, click Add new provider, and enable Google. No additional GOOGLE_CLIENT_ID environment variable is needed—Firebase manages the authentication handshake automatically via the Firebase config variables below.

Variable Description Where to find
VITE_FIREBASE_API_KEY Firebase Web API Key Firebase Console > Project Settings > Web App
VITE_FIREBASE_AUTH_DOMAIN Firebase Auth domain (e.g. your-app.firebaseapp.com) Firebase Console > Project Settings > Web App
VITE_FIREBASE_PROJECT_ID Google Cloud / Firebase Project ID Firebase Console > Project Settings
VITE_FIREBASE_STORAGE_BUCKET Firebase Storage Bucket URL Firebase Console > Project Settings
VITE_FIREBASE_MESSAGING_SENDER_ID Cloud Messaging Sender ID Firebase Console > Project Settings
VITE_FIREBASE_APP_ID Firebase Web Application ID Firebase Console > Project Settings
VITE_FIREBASE_DATABASE_ID (Optional) Named Firestore Database ID Leave empty to use (default)

B. Web3 & Base Network Settings

Variable Description Default / Example
DEV_FEE_RECIPIENT_ADDRESS Public EVM address to receive protocol fees (0.2% fee, $0.05 min) 0xD4875cCF...
VITE_DEV_FEE_RECIPIENT_ADDRESS Client-side mirror of the fee recipient address 0xD4875cCF...
EXPECTED_GAS_RELAYER Public EVM address of designated gas relayer 0x31b7BafB...
VITE_EXPECTED_GAS_RELAYER Client-side mirror of the gas relayer address 0x31b7BafB...
CIRCLE_API_KEY (Optional) Circle developer key for paymaster operations Leave empty for permissionless mode
RELAYER_PRIVATE_KEY (Optional / Server-only) Private key if running a custom relayer Never commit to Git

💡 Modifying the Protocol Fee Rate: By default, outgoing transfers route a 0.2% fee (with a $0.05 USDC floor) to the DEV_FEE_RECIPIENT_ADDRESS. To change this percentage or adjust the minimum floor, update DEV_PROTOCOL_FEE_PERCENT and DEV_PROTOCOL_FEE_MIN_USD in src/services/cryptoTransferService.ts.

💡 Zero-Cost RPCs & Native USDC: Out of the box, the app connects directly to Base's official public RPC endpoint (https://mainnet.base.org) and interacts with official native Circle USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), requiring zero paid third-party infrastructure keys.

C. Discord Social Login (Optional)

Enable Discord authentication under Discord Developer Portal > OAuth2:

Variable Description
DISCORD_CLIENT_ID Discord Application Client ID
DISCORD_CLIENT_SECRET Discord Application Client Secret

Redirect URI to configure in Discord: https://<your-domain>/api/auth/discord/callback

🎨 Customizing Branding, Support & Contacts in the App

If you are self-hosting or rebranding the application, you can customize the contact channels and support links either via environment variables or directly in the code:

1. Via Environment Variables (.env)

Variable Default Value What it Changes in the App
VITE_SUPPORT_EMAIL cofreadminwallet@gmail.com Changes the support email linked in Settings and diagnostic mailto links
VITE_FEEDBACK_URL https://forms.gle/MBpyniv5zf795wi97 Changes the destination of the Feedback button in Settings

2. Via Source Files

If you wish to update hardcoded default fallbacks directly in source files:

☁️ Production Deployment

Option 1: Firebase App Hosting (Preconfigured)

This project is 100% preconfigured for continuous deployment via Firebase App Hosting:

  1. Link your GitHub repository in the Firebase Console under App Hosting.
  2. In App Hosting > Environment settings, add the variables defined in your .env.
  3. The included apphosting.yaml file automatically handles:
    • Build command: npm run build
    • Run command: npm run start (serves the bundled backend on port 8080/3000)
  4. Every push to your main branch triggers an automated zero-downtime build and deployment.

Option 2: Any Other Cloud Provider, Container, or VPS (Cloud-Agnostic)

Because CofreAdmin compiles into a standard standalone Node.js / Express bundle (dist/server.cjs), you are not locked into Firebase. You can host it on any cloud provider, container service, or Linux VPS (Docker, Render, Railway, Fly.io, AWS, Google Cloud Run, DigitalOcean, etc.):

  • Build Command: npm run build
  • Run Command: npm run start (automatically binds to the system PORT environment variable)

🛡️ Security & Cryptographic Self-Custody

  • Strict BIP-39 HD Key Generation: All modern wallets generate a cryptographically random 12-word recovery phrase (generateMnemonic(english)) and strictly derive the exact corresponding private key and EVM address (mnemonicToAccount). Deterministic seed derivation and disconnected fallback keys are strictly prohibited.
  • Versioned Dual-Mode AES-GCM 256-bit Cryptographic Vault (cryptoVault.ts):
    • Device-Bound Non-Extractable CryptoKey (enc:aes-gcm:idb:v3:): By default, private keys and mnemonics are encrypted with AES-GCM 256-bit (random 12-byte IV) using a master CryptoKey generated with extractable: false and stored in the browser's IndexedDB (cofreadmin_keystore_db). This ensures seamless persistence across page reloads (F5) and browser restarts while making raw key material impossible to export via exportKey() or steal from localStorage.
    • PBKDF2 Passphrase Protection (enc:aes-gcm:v2:): When a custom security passphrase is supplied, keys are encrypted via PBKDF2 (100,000 iterations, SHA-256, random 16-byte salt + 12-byte IV).
    • Forward-Compatible Envelope Versioning (v1 → v2 → v3 → vN): Every encrypted payload carries an explicit version prefix, allowing the vault to transparently decrypt older envelopes and upgrade key storage to future cryptographic standards (v4+) without breaking user access.
  • Zero-Overwrite & Anti-Ghost Wallet Guarantees:
    • If an encrypted key is locked or fails decryption, connectGoogleWallet immediately halts (CARTEIRA_BLOQUEADA) and never generates or overwrites existing keys.
    • On cloud restore or new device login, the app always verifies local private key ownership so the displayed deposit address strictly matches a key controlled on the current device.
    • Wallet resets (resetWallet) verify on-chain Base USDC/ETH balances first and block accidental resets when funds are present.
  • Continuous Crypto-Agility & Multi-Generation Account Upgrade Engine: Designed for long-term protocol evolution (v1 → v2 → v3+), the app automatically scans previous account generations on Base L2. Whenever funds are detected on an older wallet standard, the Security Upgrade & Key Rotation modal guides a 1-click on-chain sweep (dynamically computing exact 0.2% / $0.05 protocol and $0.02 gas fees for any balance size) to the latest BIP-39 HD wallet, persists the new encrypted credentials across all profile keys, and triggers mandatory recovery phrase backup.
  • Strict Cloud & Storage Sanitization: Both StorageService.saveUser and CloudSyncService.saveToCloud explicitly strip walletPrivateKey, walletMnemonic, and securityPinHash prior to serialization—sensitive key material never touches plain JSON user objects or Firestore.
  • Client-Side Allowlist, Input Validation & Fee Guard: Outgoing meta-transactions (EIP-3009 TransferWithAuthorization) validate recipient checksums (isAddress, non-zero burn guard), positive finite amounts, total balance coverage (amount + protocolFee + gasFee <= usdcBalance), and verify the Relayer and fee recipient against an immutable client-side allowlist (capping gas fees at $0.10 USDC and protocol fees at max(0.2%, $0.05 USDC) prior to signing).
  • Cryptographic EIP-3009 Nonces: All transaction authorization nonces are generated with crypto.getRandomValues(32) to eliminate predictable nonce collision attacks.
  • Zero Secrets in Code & Strict .gitignore: Zero API keys, database passwords, or private keys are hardcoded in the repository. Files matching .env*, *.key, bun.lock*, service-account*.json, and private metadata are strictly excluded from commits.
  • Web Security Hardening: The Express backend implements OWASP defense headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, strict-origin-when-cross-origin).

📬 Contact

In compliance with the AGPL-3.0-or-later terms:

📜 License (AGPL-3.0-or-later)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See the LICENSE.md file for full details.

💖 Donate Support the development:

About

self-custodial web3 personal finance.

cofreadmin.gfin.app

Topics

expense-trackinggamified-smart-vaultsglobal-payment-appnative-usdcpersonal-financesavingsself-custodial

Resources

Readme
License
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Sponsor this project

Packages

Contributors

Languages