18779ea6bcrpcclient.New rejected "testnet2" (its chain-name switch predates the network), breaking oystercli --testnet2 before dialing. Add the missing case, plus --testnet2 in the tools that never got it (sweepaccount, addblock, findcheckpoint, dbtool, rpctest harness), and document the option in both sample configs. Also stop marking the testnet/testnet2 DNS seeds as service-bit filtering: SPV clients queried x49.<seed> subdomains the deployed seeders do not serve, so fresh SPV wallets discovered zero peers. pearld was unaffected (SFNodeNetwork uses the unfiltered path), and neutrino still checks advertised services after connecting. |
||
|---|---|---|
| .github | ||
| .vscode | ||
| apps | ||
| coredns-dnsseed | ||
| dnsseeder | ||
| docs | ||
| miner | ||
| node | ||
| pearl-blake3 | ||
| plonky2 | ||
| proxy | ||
| py-pearl-mining | ||
| spv | ||
| tools | ||
| version | ||
| wallet | ||
| xmss | ||
| zk-pow | ||
| .clang-format | ||
| .coderabbit.yaml | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .gitmodules | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| go.mod | ||
| go.sum | ||
| install.ps1 | ||
| install.sh | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| ruff.toml | ||
| SECURITY.md | ||
| Taskfile.yml | ||
| uv.lock | ||
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: