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
`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

Install (prebuilt binaries)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/pearl-research-labs/pearl/master/install.sh | sh

Windows:

irm https://raw.githubusercontent.com/pearl-research-labs/pearl/master/install.ps1 | iex

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

task build              # build everything (blockchain + vLLM miner)
task build:blockchain   # pearld, prlctl, oyster, oystercli → bin/
task build:miner        # install vLLM miner Python packages
task build:pearld       # pearld only

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:

cd bin && ./oystercli

Or manually:

./bin/oyster -u rpcuser -P rpcpass --create

Follow 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

2. Start the node

./bin/pearld \
  --rpcuser=rpcuser \
  --rpcpass=rpcpass \
  --rpclisten=0.0.0.0:44107 \
  --miningaddr=<your-taproot-address> \
  --txindex

Key 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

3. Start the vLLM miner

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 start

The 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 8000

Testing

task 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)

Formatting and Linting

task fmt            # format all (Go + Rust + Python)
task lint:python    # lint Python code with ruff
task tidy           # tidy Go dependencies

Scoped variants are available: task fmt:go, task fmt:rust, task fmt:python, task lint:go, task lint:rust, task lint:python.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

Pearl is licensed under the copyfree ISC License. See LICENSE for details.

Acknowledgments

Pearl's blockchain infrastructure was originally forked from the following open-source projects:

btcd — full node implementation
btcwallet — wallet daemon
neutrino — SPV light client