Pearl developer guide

node/

pearld

Reference full node (Go)

wallet/

Oyster

HD wallet daemon, JSON-RPC and gRPC, plus oystercli

spv/

Light client

Privacy-preserving, compact block filters

zk-pow/

Proof system

Proof-of-work circuit and verifier (Rust, Plonky2)

miner/

vLLM miner

GPU mining (Python and CUDA)

xmss/

XMSS

Post-quantum signatures (C with Go bindings)

py-pearl-mining/

Mining bindings

Python bindings (Rust/PyO3)

coredns-dnsseed/

DNS seeder

Production peer discovery

apps/

Applications

Desktop wallet and shared UI packages

docs/

Upgrade guides

What operators do at each hard fork

• Go 1.26 or newer for the blockchain components.
• A Rust toolchain and a C compiler for the proof, hashing and signature libraries.
• Python 3.12 and uv for the vLLM miner packages.
• Task (opens in a new tab) as the build runner.
• The NVIDIA CUDA toolkit for the GPU miner.

task build:blockchain   # pearld, prlctl, oyster, oystercli → bin/
task build:miner        # vLLM miner Python packages
task test               # Go and Python test suites

Mainnet carries real value. Testnet and testnet2 are shared test networks for integration work; regtest and simnet are private, controllable networks for deterministic development.

Mainnet

prl1… · 44108

RPC 44107, wallet 44207

Testnet

tprl1… · 44110

RPC 44109, wallet 44209

Testnet2

tprl1… · 44112

RPC 44111, wallet 44211

Pearl inherited much of the Bitcoin stack, so Bitcoin libraries often seem to work. These differences, read from the code, are where they quietly break:

• Outputs are a closed list. Consensus accepts only Taproot (witness v1), P2MR (witness v2) and data-only outputs. Legacy P2PKH, P2SH and multisig outputs are invalid, not merely non-standard.
• Addresses are Bech32m only. Witness version 0 isn’t supported at all. Testnet and testnet2 share the tprl prefix, and regtest and simnet share rprl, so a prefix doesn’t identify a test network.
• Decoding doesn’t check the network. DecodeAddress takes network parameters but doesn’t compare them; call IsForNet yourself before building an output.
• Derivation is BIP-86. The mainnet path is m/86'/808276'/account'/branch/index with coin type 808276. The wallet README still mentions BIP-44; the code uses BIP-86.
• Extended keys borrow zpub/vpub. No standard prefix exists for BIP-86, so Pearl reuses BIP-84’s, with a TODO in its wallet code to revisit.
• Fee rates are per 1,000 virtual bytes. The FeePerKB field counts grains per 1,000 vbytes; reading it as grains per vbyte is off by 1,000×.
• Headers are heavy. Each header travels with a certificate of up to 65,000 bytes, so a batch of 100 headers can exceed 6.5 MB.
• Build tags change validation. Without -tags xmss,zkpow, stub verifiers are compiled in: the node can’t verify certificates and rejects every XMSS spend.

1. 01

   Reproduce the issue

   Record the release, operating system, processor, network, logs and the smallest steps that trigger it.

2. 02

   Search existing issues

   Avoid duplicates; add evidence to an open issue when it fits.

3. 03

   Make the smallest coherent change

   Keep consensus, wallet and interface changes apart where you can.

4. 04

   Run the relevant tests

   Use the Go and Python suites, and note anything your environment had to skip.

5. 05

   Explain the security impact

   Changes to consensus, keys, networking or proofs need explicit reasoning about attacks. Report vulnerabilities privately through GitHub security advisories.

Protocol-level ideas are written up as Pearl Improvement Proposals in the pips repository (opens in a new tab).