# KrayWallet - Bitcoin Self-Custodial Wallet

**Your Keys, Your Bitcoin. Always.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Security: Local Signing](https://img.shields.io/badge/Security-Local%20Signing-green.svg)](./SECURITY.md)
[![Bitcoin: Taproot](https://img.shields.io/badge/Bitcoin-Taproot%20Native-orange.svg)](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)

A modern, secure, self-custodial Bitcoin wallet for Chrome with native support for **Taproot**, **Ordinals**, and **Runes**. Built with a security-first architecture where **your mnemonic never leaves your device**.

---

## Features

### Security First
- **100% Local Signing** - Your mnemonic, keys, and signatures never leave your device
- **Local Wallet Generation** - Mnemonic and address derivation happen entirely in-browser (v1.2.0)
- **Client-Side Cryptography** - All cryptographic operations happen locally
- **Encrypted Storage** - AES-256-GCM encryption with PBKDF2 key stretching (100,000 iterations)
- **Open Source** - Fully auditable code
- **BIP Compliant** - Follows BIP39, BIP32, BIP86, BIP340, BIP341

### Native Taproot Support
- **P2TR Addresses** - bc1p... addresses (BIP341)
- **Schnorr Signatures** - BIP340 signatures for lower fees
- **BIP86 Derivation** - m/86'/0'/0'/0/0 standard path
- **PSBT Support** - BIP174 partially signed transactions

### Ordinals & Inscriptions
- **View Inscriptions** - See your Ordinals with thumbnails
- **Send Inscriptions** - Transfer your inscriptions securely
- **Inscription Protection** - UTXO filtering prevents accidental spending
- **Content Preview** - View images, text, and other content types

### Runes Protocol
- **Runes Balance** - View all your Runes tokens
- **Runes Transfers** - Send Runes to other addresses
- **UTXO Protection** - Prevents accidental burning of Runes
- **Multiple Runes** - Support for all Runes in one wallet

### User Experience
- **Clean Interface** - Intuitive and minimal design
- **Fast** - Optimized for speed and responsiveness
- **Dark/Light Theme** - Comfortable viewing in any environment

---

## Quick Start

### Installation

#### Option 1: Direct Download

Download the latest release from [kray.space/downloads](https://kray.space/downloads/kraywallet-extension.zip), unzip, and load in Chrome (see step 2 below).

#### Option 2: Load from Source

1. **Clone the repository:**
   ```bash
   git clone https://github.com/tomkray/kraywallet-extension.git
   cd kraywallet-extension
   ```

2. **Load in Chrome:**
   - Open Chrome and go to `chrome://extensions`
   - Enable "Developer mode" (toggle in top right)
   - Click "Load unpacked"
   - Select the extension folder

3. **Create your wallet:**
   - Click the KrayWallet icon in your browser toolbar
   - Select "Create New Wallet"
   - **Write down your 12-word mnemonic on paper** (never store it digitally)
   - Set a strong password
   - You're ready to receive Bitcoin

---

## Security Architecture

### Zero-Trust Design

```
+-------------------------------------+
|     YOUR DEVICE (Trusted Zone)      |
|                                     |
|  +-------------------------------+  |
|  |   KrayWallet Extension        |  |
|  |                               |  |
|  |   [OK] Generate Mnemonic     |  |
|  |   [OK] Derive Keys           |  |
|  |   [OK] Sign Transactions     |  |
|  |   [OK] Encrypt Storage       |  |
|  |                               |  |
|  |   [NO] NEVER sends keys      |  |
|  +-------------------------------+  |
|              |                      |
|     Signed Transaction ONLY         |
+-------------------------------------+
              |
+-------------------------------------+
|     Backend (Untrusted Zone)        |
|                                     |
|   [OK] Creates unsigned PSBTs      |
|   [OK] Broadcasts transactions     |
|   [OK] Queries blockchain data     |
|   [NO] NEVER sees your keys        |
+-------------------------------------+
```

### How Your Keys Are Protected

1. **Mnemonic Generation** - Created locally using secure randomness (BIP39)
2. **Encryption at Rest** - AES-256-GCM with PBKDF2 (100,000 iterations)
3. **Local Key Derivation** - BIP32/BIP86 derivation happens in your browser
4. **Local Signing** - Schnorr signatures (BIP340) created locally with tiny-secp256k1 (WebAssembly)
5. **Memory Cleanup** - Keys cleared from memory immediately after use
6. **No Network Exposure** - Private keys are NEVER transmitted over any network

For full security documentation, threat model, and code verification steps, see [SECURITY.md](./SECURITY.md).

---

## Usage Guide

### Creating a Wallet

1. Click "Create New Wallet"
2. **Write down your 12 words on paper** - this is your only backup
3. Store them in a secure physical location (never digital)
4. Verify your backup by re-entering the words
5. Set a strong password (12+ characters recommended)

### Receiving Bitcoin

1. Click "Receive"
2. Copy your Taproot address (starts with `bc1p...`)
3. Share with the sender
4. Wait for network confirmation

### Sending Bitcoin

1. Click "Send"
2. Enter the recipient address
3. Enter the amount
4. Set the fee rate
5. Review the transaction details
6. Enter your password to sign
7. Confirm and broadcast

### Sending Inscriptions

1. Go to the "Ordinals" tab
2. Select the inscription to send
3. Enter the recipient address
4. Set fee rate
5. Review, sign with password, and confirm

### Sending Runes

1. Go to the "Runes" tab
2. Select the Rune to send
3. Enter the recipient address and amount
4. Set fee rate
5. Review, sign with password, and confirm

---

## Technical Details

### Architecture

**Frontend (Chrome Extension):**
- Manifest V3 Service Worker
- Vanilla JavaScript (no frameworks)
- Webpack-bundled Bitcoin libraries
- Local cryptography via Web Crypto API

**Backend (API):**
- Node.js + Express
- QuickNode for blockchain data
- Mempool.space for transaction broadcasting
- Zero knowledge of private keys

### Core Dependencies

| Library | Version | Purpose |
|---------|---------|---------|
| bitcoinjs-lib | 6.1.5 | Bitcoin protocol operations |
| tiny-secp256k1 | 2.2.3 | Schnorr signatures (WebAssembly) |
| bip32 | 4.0.0 | Hierarchical Deterministic key derivation |
| bip39 | 3.1.0 | Mnemonic generation and validation |

All dependencies are open source with MIT licenses.

### Network Requests

**Sent to backend (safe, public data only):**
- Public addresses
- UTXO references
- Unsigned PSBTs
- Signed transactions (for broadcast)
- Fee rate preferences

**NEVER sent to any server:**
- Mnemonic / seed phrase
- Private keys
- User password

---

## Security Best Practices

### For Users

**During Setup:**
- Use a strong, unique password (12+ characters)
- Write down your mnemonic on paper (never store it digitally)
- Store your backup in a secure physical location
- Test a restore before depositing large amounts

**During Usage:**
- Lock your wallet when not in use
- Verify recipient addresses before sending
- Review transaction details carefully
- Start with small test amounts

**Device Security:**
- Keep your OS and browser updated
- Use reputable security software
- Avoid public or untrusted WiFi for transactions
- Lock your screen when stepping away

**Phishing Protection:**
- Never share your mnemonic with anyone
- No legitimate support team will ever ask for it
- Verify URLs before entering sensitive information
- Bookmark the official site: [kray.space](https://kray.space)

---

## Contributing

We welcome contributions. To get started:

1. **Clone the repository:**
   ```bash
   git clone https://github.com/tomkray/kraywallet-extension.git
   cd kraywallet-extension
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the bundle:**
   ```bash
   npm run build
   ```

4. **Load in Chrome:**
   - Go to `chrome://extensions`
   - Enable Developer mode
   - Click "Load unpacked" and select the extension folder

5. **Make changes and test**

### Code Style

- ES6+ JavaScript
- Semicolons required
- 2-space indentation
- Descriptive variable names

---

## Bug Reports

Found a bug? Please check if it's already reported:
- [GitHub Issues](https://github.com/tomkray/kraywallet-extension/issues)

**Non-security bugs:** Open a public issue.
**Security vulnerabilities:** Report privately via [GitHub Security Advisories](https://github.com/tomkray/kraywallet-extension/security/advisories/new).

---

## License

MIT License - see the [LICENSE](./LICENSE) file for details.

### Third-Party Licenses

- bitcoinjs-lib: MIT
- tiny-secp256k1: MIT
- bip32: MIT
- bip39: MIT

---

## Acknowledgments

### Built With

- [bitcoinjs-lib](https://github.com/bitcoinjs/bitcoinjs-lib) - Bitcoin protocol library
- [tiny-secp256k1](https://github.com/bitcoinjs/tiny-secp256k1) - Schnorr signature library
- [QuickNode](https://www.quicknode.com/) - Blockchain API provider
- [Mempool.space](https://mempool.space/) - Bitcoin explorer and broadcast API

### Inspired By

- [Unisat](https://unisat.io/) - Ordinals wallet pioneer
- [Sparrow Wallet](https://sparrowwallet.com/) - PSBT implementation reference
- [Xverse](https://www.xverse.app/) - Bitcoin-native wallet design

Special thanks to the Bitcoin developer community, BIP authors, Ordinals community, Runes protocol contributors, and all open source maintainers whose work makes this project possible.

---

## Contact & Support

**Website:** [kray.space](https://kray.space)
**GitHub:** [github.com/tomkray/kraywallet-extension](https://github.com/tomkray/kraywallet-extension)

**Support:** Open an issue on [GitHub](https://github.com/tomkray/kraywallet-extension/issues)
**Security:** Report vulnerabilities via [GitHub Security Advisories](https://github.com/tomkray/kraywallet-extension/security/advisories/new)

---

## Disclaimer

**KrayWallet is provided "as is" without warranty of any kind.**

Users are responsible for:
- Backing up their mnemonic safely
- Keeping their password secure
- Verifying transactions before signing
- Following security best practices

**KrayWallet is not liable for:**
- User error (lost mnemonic, weak password)
- Device compromise (malware, theft)
- Phishing attacks
- Market volatility or regulatory changes

**Not financial advice.** KrayWallet is a tool for managing Bitcoin. It does not provide investment advice or custodial services.

---

## Roadmap

### v1.0.0 - Foundation
- Local mnemonic generation (BIP39)
- Taproot addresses (P2TR / BIP341)
- Schnorr signatures (BIP340)
- Ordinals and Runes support
- Send/receive Bitcoin
- UTXO management
- Encrypted storage (AES-256-GCM)

### v1.2.0 - Current Release
- Fully local wallet generation (`generateWalletLocal`)
- Fully local address derivation (`getAddressFromMnemonic`)
- Removed all backend dependencies for key operations
- Security hardening and code cleanup

### Future
- Hardware wallet support (Ledger, Trezor)
- Multi-signature support
- Watch-only wallet mode
- Lightning Network integration

---

## Why KrayWallet?

**Self-Custodial** - You control your keys. No one can freeze your funds. No KYC required.

**Secure** - Local signing only. Encrypted storage. Open source and fully auditable.

**Modern** - Taproot-native. Full Ordinals and Runes support. Clean, intuitive interface.

**Honest** - No hidden fees. No data collection. No tracking. Transparent development.

---

**Your keys, your Bitcoin. Always.**

---

*Last updated: January 31, 2026*
