https://github.com/carlosrabelo/karoo
Karoo Stratum Proxy
https://github.com/carlosrabelo/karoo
blockchain cryptocurrency golang mining-proxy multi-protocol nerdminer observability stratum tcp-server vardiff
Last synced: 7 months ago
JSON representation
Karoo Stratum Proxy
- Host: GitHub
- URL: https://github.com/carlosrabelo/karoo
- Owner: carlosrabelo
- License: gpl-2.0
- Created: 2025-09-21T20:36:41.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-09-21T21:00:44.000Z (7 months ago)
- Last Synced: 2025-09-21T23:18:09.441Z (7 months ago)
- Topics: blockchain, cryptocurrency, golang, mining-proxy, multi-protocol, nerdminer, observability, stratum, tcp-server, vardiff
- Language: Go
- Homepage:
- Size: 18.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Karoo Stratum Proxy
> Author: Carlos Rabelo - contato@carlosrabelo.com.br
Karoo started as a weekend experiment: a lightweight Stratum proxy so a rack of Nerdminers could share a single upstream connection. The idea quickly grew into a general-purpose, multi-protocol Stratum front-end that keeps upstream pools happy while CPU, GPU, or embedded rigs hammer away behind it.
## Features
- **Upstream on demand** – automatically dials the configured pool only when miners are connected and backs off with jittered retries on failures.
- **Protocol aware fan-out** – normalises `mining.subscribe`, `mining.authorize`, and `mining.submit` flows while preserving client IDs and minimizing extranonce collisions.
- **Share accounting & reporting** – detailed logs per worker (latency, spacing between accepted shares) plus periodic aggregate reports and HTTP `/status` / `/healthz` endpoints.
- **VarDiff scaffold** – optional, per-worker difficulty adjustments with room to grow into a full moving-average controller.
- **Flexible transport** – TCP today, with plumbing designed to extend to TLS or additional wire protocols.
## Getting Started
```bash
make build # compile to build/karoo
make build-static # compile to build/karoo-static (CGO disabled)
make run # run with ./config.json
```
The default configuration listens on `:3334` for Stratum clients and connects to the upstream pool defined in `config.json`. HTTP status endpoints are exposed at `:8080` by default.
### Configuration Highlights
- `proxy.listen` – downstream address the miners connect to.
- `upstream.{host,port,user,pass}` – upstream Stratum pool credentials.
- `proxy.client_idle_ms` – disconnect idle miners after the specified timeout.
- `compat.strict_broadcast` – when `false`, forwards unfamiliar `mining.*` messages unchanged.
- `vardiff.enabled` – toggle simple per-worker VarDiff adjustments.
See the commented sample at the bottom of `main.go` for a full reference.
## Development Workflow
- Build with `make build` (outputs `build/karoo`).
- Run unit-style checks by executing `go test ./...` (once tests are added).
- Format code with `gofmt` (the Makefile target already does this before building).
- Publish binaries by pushing a tag like `v1.0.0` or running the GitHub Actions workflow manually.
## Roadmap
- Expand the VarDiff loop into a moving average controller with bucketed share statistics.
- Add downstream protocol adapters (e.g., WebSockets) and upstream failover lists.
- Ship structured metrics (Prometheus/OpenTelemetry) to complement the existing logs.
## License
Karoo is released under the GNU General Public License, version 2. See [LICENSE](LICENSE) for the full text.
## Donations
If Karoo is useful to you, consider supporting development:
- **BTC**: `bc1qw2raw7urfuu2032uyyx9k5pryan5gu6gmz6exm`
- **DOGE**: `DTAkhF6oHiK9HmcsSk3RPZp5XqR2bvCaHK`
- **ETH**: `0xdb4d2517C81bE4FE110E223376dD9B23ca3C762E`
- **LTC**: `LSQFLPM89gABNEGutwWMFA4ma24qDVwy8m`
- **TRX**: `TTznF3FeDCqLmL5gx8GingeahUyLsJJ68A`