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.
| Directory | Description |
|---|---|
node/ |
pearld — reference implementation of the Pearl Protocol (full node) |
wallet/ |
Oyster — HD wallet daemon with JSON-RPC and gRPC interfaces |
spv/ |
Pearl light client — privacy-preserving SPV client using compact block filters |
dnsseeder/ |
DNS seeder for the Pearl network |
coredns-dnsseed/ |
CoreDNS plugin — production DNS seeder |
proxy/ |
Caddy reverse-proxy sidecar for RPC TLS termination and rate limiting |
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 |
- 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)
task build # build everything (blockchain + vLLM miner)
task build:blockchain # pearld, prlctl, oyster → bin/
task build:miner # install vLLM miner Python packages
task build:pearld # pearld onlyThe setup flow: build > create wallet > start node > start vLLM miner.
./bin/oyster -u rpcuser -P rpcpass --createFollow the prompts to set a passphrase and record your seed. Then start the wallet and generate a Taproot mining address:
./bin/oyster -u rpcuser -P rpcpass &
./bin/prlctl -u rpcuser -P rpcpass -s https://localhost:44207 getnewaddress./bin/pearld \
--rpcuser=rpcuser \
--rpcpass=rpcpass \
--rpclisten=0.0.0.0:44107 \
--miningaddr=<your-taproot-address> \
--txindexKey flags: --testnet / --simnet for non-mainnet, --notls to disable TLS,
--debuglevel=debug for verbose logs. See node/sample-pearld.conf for all
options.
| Network | RPC | P2P | Wallet Server |
|---|---|---|---|
| Mainnet | 44107 | 44108 | 44207 |
| Testnet | 44109 | 44110 | 44209 |
| Testnet2 | 44111 | 44112 | 44211 |
| Simnet | 18556 | 18555 | 18554 |
| Regtest | 18334 | 18444 | 18332 |
The vLLM miner has two components: pearl-gateway (bridge to the node) and vllm-miner (GPU mining via vLLM).
export PEARLD_RPC_URL="http://localhost:44107"
export PEARLD_RPC_USER="rpcuser"
export PEARLD_RPC_PASSWORD="rpcpass"
export PEARLD_MINING_ADDRESS="<your-taproot-address>"
pearl-gateway startThe gateway connects to pearld over JSON-RPC and exposes a mining interface
on /tmp/pearlgw.sock (UDS) or port 8337 (TCP, set MINER_RPC_TRANSPORT=tcp).
To run the full stack with Docker:
docker buildx build -t vllm_miner . -f miner/vllm-miner/Dockerfile
docker run --rm -it --gpus all --network host \
-e PEARLD_RPC_URL=http://localhost:44107 \
-e PEARLD_RPC_USER=rpcuser \
-e PEARLD_RPC_PASSWORD=rpcpass \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--shm-size 8g \
vllm_miner:latest \
pearl-ai/Llama-3.3-70B-Instruct-pearl \
--host 0.0.0.0 --port 8000task test # run all tests (Go + Python)
task test:go # Go tests with race detector
task test:python # full Python test suite
task test:python:basic # Python tests (excludes integration/perf/slow)task fmt # format all (Go + Rust + Python)
task lint:python # lint Python code with ruff
task tidy # tidy Go dependenciesScoped variants are available: task fmt:go, task fmt:rust, task fmt:python,
task lint:go, task lint:rust, task lint:python.
See CONTRIBUTING.md.
See SECURITY.md.
Pearl is licensed under the copyfree ISC License. See LICENSE for details.
Pearl's blockchain infrastructure was originally forked from the following open-source projects: