pearl-research-labs / pearl

# Pearl
Pearl is an L1 blockchain based on the **Proof-of-Useful-Work** protocol, where mining is done as a by-product of arbitrary matrix multiplication, as proposed in this paper.
This monorepo contains the full node, wallet, SPV light client, ZK proving
system, vLLM miner, and supporting tools.
## Repository Layout
| Directory | Description |
|-----------|-------------|
| `node/` | **pearld** — reference implementation of the Pearl Protocol (full node) |
| `wallet/` | **Oyster** — HD wallet daemon with JSON-RPC and gRPC interfaces, plus **oystercli**, an interactive terminal client for it |
| `spv/` | **Pearl light client** — privacy-preserving SPV client using compact block filters |
| `coredns-dnsseed/` | CoreDNS plugin — production DNS seeder |
| `xmss/` | XMSS post-quantum signature scheme (C + Go FFI) |
| `zk-pow/` | ZK proof-of-work circuit and verifier (Rust, Plonky2/STARKy) |
| `pearl-blake3/` | Blake3 hashing utilities (Rust) |
| `plonky2/` | Plonky2 SNARK proving system (Rust, vendored) |
| `miner/` | vLLM miner — GPU mining infrastructure (Python/CUDA, uv workspace) |
| `py-pearl-mining/` | Python bindings for Pearl mining (Rust/PyO3) |
| `apps/` | Frontend applications (website, desktop wallet — pnpm/Turborepo) |
| `tools/` | Go development tool dependencies |
## Install (prebuilt binaries)
macOS / Linux:
 [code] 
Windows:
 [code] 
Installs `pearld`, `prlctl`, `oyster`, and `oystercli` with localhost-only mainnet defaults and
shared RPC credentials (oyster uses SPV by default). Binaries go to
`${XDG_BIN_HOME:-$HOME/.local/bin}` on macOS/Linux, or `%LOCALAPPDATA%\Pearl\bin`
on Windows.
| Tool | Linux | macOS | Windows |
|------|-------|-------|---------|
| pearld | `~/.pearld/pearld.conf` | `~/Library/Application Support/Pearld/pearld.conf` | `%LOCALAPPDATA%\Pearld\pearld.conf` |
| oyster | `~/.oyster/oyster.conf` | `~/Library/Application Support/Oyster/oyster.conf` | `%LOCALAPPDATA%\Oyster\oyster.conf` |
| prlctl | `~/.prlctl/prlctl.conf` | `~/Library/Application Support/Prlctl/prlctl.conf` | `%LOCALAPPDATA%\Prlctl\prlctl.conf` |
Pin a version or install directory with `--version` / `--bin-dir` (or `-Version` /
`-BinDir` on Windows). See node/docs/installation.md
for upgrade, removal, and other details. To build from source, see **Building** below.
## Prerequisites
- Go 1.26 or newer
- Rust toolchain (for ZK and hashing crates)
- C compiler (for XMSS library)
- Python 3.12 and uv (for vLLM miner packages)
- Task runner
- CUDA toolkit (for vLLM miner)
## Building
 [code] 
## Running a Node and vLLM Miner
The setup flow: **build** > **create wallet** > **start node** > **start vLLM miner**.
### 1. Create a wallet and get a mining address
The interactive way — `oystercli` configures oyster
automatically and walks you through wallet creation, starting the daemon, and
generating an address (Receive menu). With the release installer it is already
on your PATH (`oystercli`); from a source build:
 [code] 
Or manually:
 [code] 
Follow the p