A production-oriented, security-first, self-custody cryptocurrency wallet platform built as a TypeScript monorepo with multi-chain and multi-platform support.
Crypto Wallet is a self-custody-first wallet platform designed around strong security boundaries, client-side signing authority, provider-neutral blockchain integrations, and reproducible free-resource infrastructure.
The platform supports:
- EVM
- Solana
- Bitcoin
Supported application platforms:
- Web
- Mobile
- Desktop
- Browser Extension
The architecture keeps wallet key material within the client trust boundary. Seed phrases and private keys are never intended to be stored in backend services, databases, CI systems, analytics, crash reports, or application logs.
- TypeScript-heavy pnpm monorepo
- Turborepo workspace
- PostgreSQL as the authoritative application and ledger database
- Redis/Valkey for ephemeral coordination and caching
- Durable event infrastructure
- Provider-neutral blockchain adapters
- Client-side transaction signing
- Secure local wallet storage
- Explicit transaction approval
- Least-privilege security boundaries
- Self-custody as the primary trust domain
- Separate custody/exchange trust domain for future capabilities
- Free, local, and self-hosted infrastructure for the current implementation
- Network configuration and chain-ID validation
- Native asset balances
- ERC-20 asset discovery
- Transaction construction
- Fee estimation
- Transaction signing
- Provider abstraction and failover
- Anti-RPC-misdirection protections
- Solana address and key handling
- SOL/SPL asset support
- Transaction construction
- Recent blockhash handling
- Transaction signing and submission
- Confirmation/finality tracking
- Normalized transaction errors
- Bitcoin account and address derivation
- UTXO discovery
- Fee estimation
- PSBT-oriented transaction construction
- Transaction signing
- Confirmation tracking
- Reorganization-aware state handling
- Esplora provider integration
The wallet foundation includes:
- Wallet creation
- Wallet recovery
- BIP-39 mnemonic handling
- BIP-32 key derivation
- secp256k1 signing
- Secure local wallet storage
- Wallet session management
- Lock and unlock
- Receive address generation
- QR-based receive flow
- Transaction construction
- Explicit transaction approval
- Client-side signing
- Transaction submission
- Transaction tracking
- Confirmation handling
- Transaction history
- Failure and recovery handling
The web wallet provides a responsive self-custody wallet experience including:
- Wallet creation and recovery
- Secure unlock and locking
- Portfolio and asset views
- Receive and send flows
- Explicit transaction approval
- Transaction tracking
- Transaction history
- Explorer links
The mobile application foundation provides:
- React Native application shell
- Wallet onboarding
- Secure unlock
- Dashboard
- Send and receive flows
- Activity
- Native secure-storage integration
- Biometric unlock support
The desktop application uses an Electron-based architecture with security-sensitive functionality separated from the renderer.
The browser extension uses a Manifest V3 architecture with:
- Minimal permissions
- Minimal host permissions
- Origin validation
- Explicit approval
- Scoped dApp connectivity
- Connect approval
- Sign approval
- Transaction approval
- Anti-phishing and origin-binding considerations
Security is a core architectural boundary of the project.
Private wallet material remains within the client-side trust boundary.
The project does not intentionally store:
- Seed phrases in backend services
- Private keys in backend services
- Seed phrases in databases
- Private keys in databases
- Wallet secrets in CI variables
- Wallet secrets in analytics
- Wallet secrets in crash reports
- Wallet secrets in application logs
- Wallet secrets in support channels
Transaction signing requires explicit user approval.
The transaction flow is designed around:
Identity
↓
Wallet / Key Material
↓
Chain Adapter
↓
Transaction Construction
↓
Explicit User Approval
↓
Client-Side Signing
↓
Transaction Submission
↓
Confirmation / Tracking
The project follows a security-first architecture based on the following principles:
- Self-custody first
- Security boundaries before convenience
- Client-side signing authority
- Least privilege
- Explicit transaction authorization
- Secure local secret storage
- Secret redaction
- Provider abstraction
- Provider failover
- Origin validation
- Session security
- Rate limiting and abuse controls
- Separation of trust domains
- Defense in depth
- No wallet secrets in backend systems
- No wallet secrets in databases
- No wallet secrets in CI
- No wallet secrets in logs
- No wallet secrets in analytics
- No wallet secrets in crash reports
PostgreSQL remains the authoritative database, while Redis/Valkey is limited to ephemeral coordination and caching.
Exchange and custody functionality is intentionally separated from the self-custody wallet trust domain.
The repository includes architecture for future capabilities such as:
- Custody
- Key management
- Ledger
- Compliance
- Risk management
- Event-driven exchange workflows
- Deposits
- Withdrawals
- Trades
- Fees
- Reconciliation
- Treasury controls
These components do not change the self-custody security boundary.
The current implementation does not claim to provide a production custodial exchange.
Production custody capabilities such as:
- Managed KMS
- CloudHSM
- MPC
- Multisig infrastructure
- Cold storage
- Managed disaster recovery
remain future production capabilities rather than claims of the current free-resource implementation.
The current implementation uses free, local, and self-hosted infrastructure where appropriate.
Core infrastructure includes:
- PostgreSQL
- Valkey
- Redpanda
- Temporal
- MinIO
- Prometheus
- Grafana
- Loki
- Alloy
- Docker Compose
The infrastructure architecture remains provider-neutral so that stronger managed production capabilities can be introduced later without changing the core application trust boundaries.
PostgreSQL is the authoritative application and ledger database.
It is responsible for durable application state and authoritative persistence.
Valkey is used for ephemeral infrastructure concerns such as:
- Cache
- Rate limiting
- Locks
- Ephemeral coordination
Valkey is never treated as the authoritative source of truth.
Redpanda provides durable event infrastructure for asynchronous processing and event-driven workflows.
Temporal provides durable workflow orchestration for long-running and failure-sensitive workflows.
MinIO provides local/self-hosted object storage for appropriate non-sensitive artifacts.
Prometheus provides metrics collection and monitoring.
Grafana provides dashboards and operational visibility.
Loki provides centralized log aggregation.
Alloy provides telemetry collection and forwarding.
Docker Compose provides reproducible local infrastructure for development, integration testing, observability, and operational validation.
.
├── apps
│ ├── api
│ ├── desktop
│ ├── extension
│ ├── hardware-wallet
│ ├── mobile
│ └── web
│
├── packages
│ ├── chain-core
│ ├── compliance-core
│ ├── crypto
│ ├── custody-core
│ ├── dapp-core
│ ├── ledger-core
│ ├── secure-storage
│ ├── shared-types
│ ├── storage
│ ├── telemetry
│ ├── ui
│ └── wallet-core
│
├── infra
│ └── local
│
├── docs
│
├── .github
│ └── workflows
│
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
└── README.md
Cryptographic primitives and wallet key operations including:
- BIP-39 mnemonic handling
- BIP-32 derivation
- secp256k1 signing
- Deterministic wallet cryptography
Secure local wallet storage abstractions and encryption boundaries.
Wallet lifecycle, wallet sessions, creation, recovery, locking, unlocking, and wallet-domain behavior.
Shared TypeScript domain types and contracts.
Provider-neutral blockchain abstractions and chain adapters for:
- EVM
- Solana
- Bitcoin
Persistence abstractions and storage-related functionality.
Ledger and exchange-domain architecture boundaries.
Provider-neutral custody and key-management architecture boundaries.
dApp connectivity and approval architecture.
Compliance and risk architecture boundaries.
Application telemetry and observability abstractions.
Shared UI primitives and components.
The API application provides the backend boundary for application services while maintaining separation between:
- Identity
- Wallet/key material
- Blockchain adapters
- Transaction authority
- Application state
The API architecture includes:
- Authentication and session security
- API contracts
- Rate limiting
- Abuse controls
- Correlation IDs
- Standardized errors
- Idempotency
- Database access
- Event-driven workflows
- Operational health checks
Backend services do not receive or persist wallet seed phrases or private keys.
The project includes a local/self-hosted observability stack.
Observability covers:
- Application errors
- RPC latency
- Transaction failures
- Security events
- Service health
- Infrastructure health
- Operational metrics
- Structured logs
Sensitive fields are redacted from application logs.
Protected sensitive fields include, where applicable:
- Authorization headers
- Passwords
- Mnemonics
- Private keys
- Other wallet-secret material
The observability architecture is designed to provide operational visibility without exposing wallet secrets.
The repository uses GitHub Actions for automated validation.
The CI pipeline includes:
- Ubuntu runner
- Node.js 22
- pnpm
- Frozen-lockfile installation
- PostgreSQL service
- Valkey service
- Redpanda service
- Dependency auditing
- Gitleaks secret scanning
- Formatting validation
- Linting
- Type checking
- Database migrations
- Automated tests
- Build validation
Local validation includes:
pnpm run format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
git diff --checkThe local infrastructure stack can be run through Docker Compose.
Validated services include:
- Alloy
- Grafana
- Loki
- MinIO
- PostgreSQL
- Prometheus
- Redpanda
- Temporal
- Valkey
Validated infrastructure and application checks include:
- PostgreSQL connectivity
- Redpanda cluster health
- MinIO health endpoint
- Prometheus health endpoint
- API health endpoint
- Application health endpoint
- Docker Compose service availability
- Valkey authentication and connectivity
The local environment is intended for development, validation, controlled beta work, and architecture verification.
It should not be interpreted as equivalent to managed production infrastructure with enterprise availability, disaster recovery, security assurance, or service-level guarantees.
Project documentation includes:
- Security architecture
- Threat model
- Security boundaries
- Security principles
- Incident response
- Operations runbooks
- Infrastructure documentation
- Privacy disclosure
- Controlled beta documentation
- Production-readiness documentation
- Future engineering roadmap
Important documentation is maintained under:
docs/
Key documentation includes:
docs/PRIVACY.md
docs/CONTROLLED_BETA.md
docs/NEXT_90_DAYS.md
The project includes a controlled free-resource beta boundary for the self-custody wallet foundation.
Validation areas include:
- Wallet creation
- Wallet restoration
- Lock and unlock
- Receive flow
- Transaction construction
- Explicit transaction approval
- Transaction signing
- Send flow
- Transaction tracking
- Confirmation
- Transaction history
- Failure and recovery behavior
- Web validation
- Mobile validation
- Desktop validation
- Browser extension validation
Operational data collection is limited to information necessary for the controlled beta.
Sensitive wallet material must not appear in:
- Logs
- Analytics
- Crash reports
- CI artifacts
- Support channels
The browser extension follows minimal permission and host-permission principles with origin validation and explicit approval.
The controlled beta is intended for trusted testers and does not represent a public regulated exchange launch.
The current free-resource implementation intentionally documents several production limitations.
These include:
- Production TLS termination is not represented by the local repository.
- Production HTTP security headers are not currently configured in the repository.
- Production CSP deployment configuration remains future deployment work.
- Production reverse-proxy and deployment security configuration remains future work.
- Local custody infrastructure is not equivalent to production KMS, CloudHSM, MPC, multisig, cold storage, or managed disaster recovery.
- Independent security review is outside the current free-resource implementation.
- Free/local infrastructure does not provide the same guarantees as managed production services.
- Controlled beta validation does not constitute a public production launch.
These limitations are explicitly documented rather than presenting local/free infrastructure as equivalent to stronger paid production capabilities.
The project follows these engineering principles:
- Self-custody first.
- Security boundaries before convenience.
- Client-side signing authority.
- Never store wallet secrets in backend systems.
- Never store wallet secrets in databases.
- Never expose wallet secrets through CI.
- Never expose wallet secrets through logs, analytics, crash reports, or support channels.
- PostgreSQL remains authoritative for application and ledger state.
- Valkey remains ephemeral.
- Blockchain providers remain replaceable.
- Durable event semantics are preserved.
- Explicit transaction approval is mandatory.
- Least privilege is preferred throughout the architecture.
- Free-resource implementation must not pretend to provide paid production guarantees.
- Custody and exchange remain separate trust domains.
- Future production capabilities must preserve the established security boundaries.
- Architectural limitations must be documented rather than hidden.
The architecture leaves room for future capabilities including:
- Additional blockchain networks
- Advanced dApp support
- Swap infrastructure
- Expanded transaction infrastructure
- Custody architecture
- Exchange infrastructure
- Fiat integration
- Institutional capabilities
- Production key-management infrastructure
- Stronger disaster recovery
- Independent security review
- Additional security validation
- Improved transaction lifecycle capabilities
- Expanded observability
- Wallet and user-experience improvements
Future capabilities must preserve the existing self-custody and security boundaries.
The future engineering direction is documented separately in:
docs/NEXT_90_DAYS.md
The current project represents a controlled, free-resource self-custody wallet foundation with:
- Multi-platform architecture
- EVM support
- Solana support
- Bitcoin support
- Secure local key storage
- Wallet lifecycle management
- Transaction lifecycle management
- Provider-neutral blockchain infrastructure
- Observability
- Security controls
- Automated quality gates
- Production-readiness documentation
- Controlled beta documentation
The project is not a claim that a regulated public cryptocurrency exchange can safely launch without:
- Additional production infrastructure
- Legal and compliance work
- Independent security review
- Stronger custody controls
- Appropriate operational controls
- Stronger disaster recovery
- Production-grade managed security services where required
The free-resource implementation deliberately preserves architecture and interfaces for future production capabilities instead of claiming that local infrastructure provides equivalent assurance.
Production-readiness documentation and controlled-beta boundaries are established.
The implementation baseline has been completed and the final production-readiness documentation has been integrated into the master branch.
The repository currently provides a security-first self-custody wallet foundation with:
- Multi-chain support
- Multi-platform architecture
- Secure wallet storage
- Transaction lifecycle management
- Provider-neutral blockchain integrations
- Local observability
- Security-focused CI gates
- Operational documentation
- Privacy documentation
- Controlled beta documentation
- Future engineering roadmap
The project is positioned for continued stabilization, controlled validation, security and correctness improvements, and future capability development while preserving the established architecture and trust boundaries.
See the repository license for the applicable terms.