# WarpCoin (WARP)

A fast, mineable, peer-to-peer cryptocurrency built from scratch in Go.

WarpCoin is a complete proof-of-work blockchain designed for everyday P2P
payments: 30-second target block times, a simple account-based ledger that is
cheap to validate, and a SHA-256d proof of work that **anyone can mine on a CPU
or a GPU**. The entire system is a single dependency-free Go binary — run a full
node, manage a wallet, send coins, and mine, all from one command.

---

## Highlights

- **Fast P2P payments** — 30s target block time, account/nonce ledger, fee market.
- **Mineable by everyone** — SHA-256d proof of work with automatic difficulty
  retargeting. Built-in multicore CPU miner, plus a `getwork`/`submitwork` JSON
  API so external CPU **and GPU** miners can connect.
- **Real networking** — TCP gossip protocol with peer discovery, transaction and
  block propagation, and sequential chain sync between nodes.
- **Self-contained** — pure Go standard library, no external dependencies. One
  static binary is a full node, wallet, and miner.
- **Secure by construction** — ECDSA signatures (P-256), Base58Check addresses,
  double-SHA256 hashing, Merkle-committed blocks, and most-work fork choice with
  reorg support.

## Network parameters

| Parameter            | Value                                            |
|----------------------|--------------------------------------------------|
| Coin / ticker        | WarpCoin / WARP                                  |
| Smallest unit        | 1 WARP = 100,000,000 flux (8 decimals)           |
| Target block time    | 30 seconds                                       |
| Difficulty retarget  | every 60 blocks                                  |
| Initial block reward  | 50 WARP                                          |
| Halving interval     | every 2,100,000 blocks (~2 years)                |
| Proof of work        | double SHA-256 over the block header             |
| Address format       | Base58Check, version `0x49` (addresses start `W`)|
| Genesis premine      | 20,000,000 WARP to founding holders              |

## Genesis premine

The genesis block grants substantial founding reserves on-chain (committed via
the genesis Merkle root). These balances exist in the ledger from height 0:

| Holder                 | Address                              | Amount          |
|------------------------|--------------------------------------|-----------------|
| Treasury Reserve       | `WhgToZN7oNwPWan29uCt8YExAw6hnFex4y` | 10,000,000 WARP |
| Development Fund       | `WdpepcweJReNG4cPU9RQBaJ6VaiXzCUi96` | 5,000,000 WARP  |
| Ecosystem & Community  | `WZKvgQeJUdWFmu5LZKXRZrs1owzR9QPhMk` | 5,000,000 WARP  |

> **Security note.** The private keys controlling these reserves are in
> [`genesis_founders.json`](./genesis_founders.json) so the founding holder can
> claim and move them. **Before any public launch, move these funds to fresh,
> offline-generated keys and remove the committed keys.** Anyone with a key
> controls the corresponding reserve.

## Build

```sh
make build      # produces ./bin/warpcoin
# or:
go build -o bin/warpcoin ./cmd/warpcoin
```

Requires Go 1.24+. There are no third-party dependencies.

## Quick start

### 1. Create a wallet

```sh
warpcoin wallet new
# → address : Wf...   (saved to ~/.warpcoin/wallet.json)
```

### 2. Run a mining node

```sh
warpcoin node --mine --miner-address $(warpcoin wallet address)
```

This starts a full node (P2P on `:8338`, RPC on `127.0.0.1:8339`) and mines to
your wallet. Watch the balance grow:

```sh
warpcoin balance
warpcoin status
```

### 3. Send a P2P payment

```sh
warpcoin send --to WkUdxUS2QFuxTGF6GZdJFvW7qkz9KsorVu --amount 12.5
```

The transaction is signed locally, broadcast to peers, and confirmed when a
miner includes it in a block.

### 4. Join the network

Point a second node at a peer to sync the chain:

```sh
warpcoin node --datadir ~/.warpcoin/node2 --p2p :8340 \
  --rpc 127.0.0.1:8341 --seeds 127.0.0.1:8338
```

## Mining on CPU or GPU

WarpCoin's proof of work is plain double-SHA256 over an 88-byte header, so the
same nonce search runs on a CPU, a GPU, or dedicated hardware.

**Built-in CPU miner** (inside the node):

```sh
warpcoin node --mine --miner-address <addr> --cpus 8
```

**Standalone miner** against any node's RPC — this is the integration point a
GPU miner targets:

```sh
warpcoin miner --rpc http://127.0.0.1:8339 --address <addr> --cpus 8
```

It repeatedly calls `GET /getwork?address=<addr>` to fetch a candidate block and
its target, searches for a nonce whose `SHA256d(header) <= target`, and submits
the solved block to `POST /submitwork`. A GPU miner implements the identical
loop with a CUDA/OpenCL SHA-256d kernel; see [docs/MINING.md](./docs/MINING.md).

## Desktop app (Windows & macOS)

Prefer a GUI? The [`desktop/`](./desktop) directory contains a cross-platform
Electron app that runs a full node, wallet, and miner with a one-click
dashboard. It bundles the compiled `warpcoin` binary as a managed sidecar, so the
GUI runs the exact same consensus and wallet code as the CLI.

```sh
cd desktop
npm install
npm start            # builds the node binary and launches the app

npm run dist:win     # build a Windows installer (on Windows)
npm run dist:mac     # build a macOS .dmg     (on macOS)
```

The GitHub Actions workflow `.github/workflows/desktop.yml` builds signed-ready
Windows and macOS installers on native runners. See [desktop/README.md](./desktop/README.md).

## Server deployment & node roles

The [`deploy/`](./deploy) directory packages WarpCoin for servers. One Docker
image (and a shared role entrypoint) runs any node role, selected with
`WARP_ROLE`:

| Role | Purpose |
|------|---------|
| `full` | Validating full node |
| `seed` | High-peer-count bootstrap node |
| `dnsseed` | Peer-routing **DNS seeder** — answers `A` queries for a seed domain with live peer IPs |
| `verifier` | Non-mining node exposing `POST /verify` to pre-flight transactions |
| `explorer` | Full node serving the **block explorer + supply API** |
| `market` | **Market data service** — CoinGecko/CMC ticker + orderbook API |
| `miner` | Full node that mines to `WARP_MINER_ADDRESS` |

Bring up a complete local network (seed + dnsseed + verifier + full + miner):

```sh
cp deploy/.env.example deploy/.env   # set MINER_ADDRESS
docker compose -f deploy/docker-compose.yml up --build
```

Bare-metal via systemd: `sudo deploy/install.sh` then
`systemctl enable --now warpcoin@seed`. Kubernetes manifests live in
`deploy/k8s/`. Full details in [deploy/README.md](./deploy/README.md).

## Block explorer & exchange listing

WarpCoin ships a public **block explorer** with a supply API suitable for
listing trackers like CoinGecko:

```sh
warpcoin explorer --http 0.0.0.0:8340
```

- Browseable pages: overview, blocks, transactions, addresses, and a rich list.
- JSON API: `/api/stats`, `/api/block/{id}`, `/api/tx/{id}`, `/api/address/{addr}`, `/api/richlist`.
- **Supply API** (plain-number endpoints CoinGecko consumes):
  `/api/supply/circulating`, `/api/supply/total`, `/api/supply/max`, plus
  `/api/supply` (JSON).

Supply is derived on-chain: **total** = premine + mined subsidy, **circulating**
= total minus the genesis reserve balances still held, **max** ≈ 229,999,999.77
WARP. Branding assets and machine-readable metadata live in
[`branding/`](./branding), and a step-by-step listing checklist is in
[docs/LISTING.md](./docs/LISTING.md).

## Market data API (exchange ticker)

WarpCoin ships a reference market service: an in-memory order book with a
price-time-priority matching engine, exposing ticker/orderbook/trade endpoints
in the **CoinGecko** and **CoinMarketCap** exchange-integration formats, plus a
small order API so the book produces real data.

```sh
warpcoin market --http 0.0.0.0:8341 --pairs WARP_USDT,WARP_BTC
```

- CoinGecko: `/api/v1/pairs`, `/api/v1/tickers`, `/api/v1/orderbook`, `/api/v1/historical_trades`
- CoinMarketCap: `/summary`, `/assets`, `/ticker`, `/orderbook/{pair}`, `/trades/{pair}`
- Orders: `POST /api/v1/orders` `{pair, side, price, amount}`

It's market infrastructure, not a custodial exchange — it matches orders and
records tickers/trades but does not hold funds or settle on-chain. Full details
in [docs/API.md](./docs/API.md).

## Website, whitepaper & docs

- **Website**: the public site is a Next.js app maintained on the dedicated
  `claude/warpcoin-site-vercel` branch (space-themed, deployed via Vercel). That
  branch contains only the site and documentation — no core code or keys.
- **Whitepaper**: [docs/WHITEPAPER.md](./docs/WHITEPAPER.md).
- **Documentation hub**: [docs/README.md](./docs/README.md) — getting started,
  API reference, design, mining, deployment, and listing.

## JSON-RPC API

The node exposes a small HTTP/JSON API (default `127.0.0.1:8339`):

| Endpoint               | Method | Purpose                                  |
|------------------------|--------|------------------------------------------|
| `/status`              | GET    | chain height, tip, difficulty, peers     |
| `/balance?address=`    | GET    | balance (flux + WARP) and nonce          |
| `/account?address=`    | GET    | raw `{balance, nonce}`                    |
| `/tx` (or `/send`)     | POST   | submit a signed transaction              |
| `/block?height=` / `?hash=` | GET | fetch a block (tip if no args)         |
| `/mempool`             | GET    | pending transactions                     |
| `/getwork?address=`    | GET    | candidate block + target for miners      |
| `/submitwork`          | POST   | submit a solved block                    |
| `/verify`              | POST   | pre-flight a transaction without broadcasting |
| `/peers`               | GET    | connected and known peer addresses       |
| `/healthz`             | GET    | liveness/readiness probe                 |
| `/supply`              | GET    | max / total / circulating supply (JSON)  |

A richer public **block explorer** with browseable pages and a supply API for
listing trackers runs separately — see below.

### Wallet-platform services

The node also exposes first-class, supported endpoints for the WarpCoin wallet
platform — the same features delivered by the [WarpWallet](https://github.com/kevinsegal/warpwallet)
web app, mirrored here in node code so any client can use them against a real
node. Privileged actions are authorized by a **wallet signature** over a
canonical action string (double-SHA256 digest, same scheme as transactions), and
the WarpScript compiler is **byte-compatible** with the web app — an identical
spec yields an identical `W…` contract address on both sides.

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/tag/resolve?tag=` | GET | resolve a warp#tag → address |
| `/tag/reverse?address=` | GET | reverse-lookup an address → warp#tag |
| `/tag/register` | POST | claim a warp#tag (signed action) |
| `/escrow/create` | POST | open a buyer/seller/arbiter escrow |
| `/escrow/list?address=` | GET | escrows where the address is a party |
| `/escrow/get?id=` | GET | fetch an escrow |
| `/escrow/action` | POST | `fund` / `release` / `refund` / `dispute` (signed action) |
| `/merchant/register` | POST | register a business, mint an API key |
| `/merchant/invoice/create` | POST | create an invoice (`Authorization: Bearer <apiKey>`) |
| `/merchant/invoice/get?id=` | GET | fetch an invoice (hosted checkout) |
| `/merchant/invoice/pay` | POST | pay an invoice with a signed transfer (broadcast + confirm) |
| `/merchant/invoices?merchantId=` | GET | list a merchant's invoices |
| `/contract/compile` | POST | compile a WarpScript spec → artifact (no deploy) |
| `/contract/deploy` | POST | deploy a content-addressed contract artifact |
| `/contract/get?id=` / `/contract/list?author=` | GET | fetch / list contracts |
| `/contract/templates` / `/contract/palette` | GET | studio building blocks |
| `/lighttime?from=&to=` | GET | inter-planetary one-way / round-trip light time |
| `/lighttime/bodies` | GET | selectable Solar System bodies |

> Escrow is a signature-authorized **coordination** layer (state + approvals);
> on an account/nonce chain, on-chain custody and WarpScript execution arrive
> with WarpVM. Set `WARP_WEBHOOK_SECRET` to HMAC-sign merchant webhooks.

## CLI reference

```
warpcoin node      Run a full node (flags: --mine --miner-address --cpus --seeds --maxpeers --datadir --p2p --rpc --verbose)
warpcoin dnsseed   Run a DNS-seed / peer-routing node (flags: --domain --dns --ttl --seeds --datadir --p2p --rpc)
warpcoin explorer  Run a full node with the block explorer + supply API (flags: --http --seeds --datadir --p2p --rpc)
warpcoin market    Run the market data service (CoinGecko/CMC ticker + orderbook API) (flags: --http --pairs --seed)
warpcoin wallet    new | address | import --key <hex>   (--keystore <path>)
warpcoin balance   [address]                            (--rpc, --keystore)
warpcoin send      --to <addr> --amount <WARP> [--fee <WARP>]
warpcoin status    Show a node's chain status
warpcoin miner     Mine to a node via getwork/submitwork (--address --cpus --rpc)
warpcoin info      Print network parameters and the genesis premine
```

## Architecture

```
cmd/warpcoin/        CLI entrypoint and subcommands
internal/wallet/     ECDSA keys, Base58Check addresses, signing, keystore
internal/core/       transactions, blocks, PoW/difficulty, state, blockchain, mempool
internal/p2p/        TCP gossip protocol, peer discovery, block/tx sync
internal/node/       node orchestration, JSON-RPC, built-in miner
internal/rpcclient/  HTTP client used by the wallet/miner commands
internal/authsig/    signature-based authorization for service actions
internal/nameservice/ warp#tag registry (name → address)
internal/escrow/     escrow coordination + signed state transitions
internal/merchant/   merchant gateway: invoices, payments, webhooks
internal/warpscript/ no-code contract model + deterministic compiler
internal/contracts/  deployed-contract registry
internal/interplanetary/ inter-planetary light-time estimation
```

See [docs/DESIGN.md](./docs/DESIGN.md) for consensus rules and design rationale.

## Development

```sh
make test     # run the test suite
make vet      # go vet
make build    # build the binary
./scripts/demo.sh   # spin up nodes locally and run an end-to-end demo
```

## Security

WarpCoin includes consensus, networking, and key-storage hardening — overflow-
safe accounting, duplicate-transaction/Merkle (CVE-2012-2459) protection, low-S
non-malleable signatures, size-capped P2P framing with deadlines, hardened HTTP
servers with optional bearer-token RPC auth (`--rpc-token` / `WARP_RPC_TOKEN`),
and **passphrase-encrypted keystores** (PBKDF2-SHA256 + AES-256-GCM; automatic
in the desktop app via the OS keychain). See **[docs/SECURITY.md](./docs/SECURITY.md)**
for the full model.

Create an encrypted wallet:

```sh
warpcoin wallet new                       # prompts for a passphrase
# or non-interactively:
WARP_WALLET_PASSPHRASE=… warpcoin wallet new
```

## Status & roadmap

WarpCoin is a fully functional reference implementation: nodes sync, miners
produce blocks, and signed transactions settle. Next steps for a public launch:

- Coinbase maturity enforcement at spend time (the depth is defined but not yet
  enforced per-output).
- Optional encrypted P2P transport and a crypto-agility layer with hybrid
  post-quantum signatures.
- Transaction expiry, richer mempool eviction, and per-peer rate limiting.
- A native GPU (CUDA/OpenCL) miner binary.
- DNS seed nodes and NAT traversal for the public network.

## License

MIT — see [LICENSE](./LICENSE).
