# Pearl developer guide

https://www.learnpearl.org/developers/ · Checked October 20, 2026 · Advanced

Pearl’s public monorepo holds the blockchain, wallet, light client, miner and proof systems. Start by choosing one layer rather than building the whole stack blind.

## Key takeaways

- The node (Go, from btcd) and the proof system (Rust, Plonky2) are separate layers; pick one.
- Build with the repository’s Task targets: they set the `xmss` and `zkpow` tags the real verifier needs.
- Develop on testnet, testnet2, regtest or simnet; mainnet carries real value.
- Bitcoin libraries look compatible and aren’t quite: Pearl changes addresses and outputs, and its fee-rate fields are easy to misread.

## Repository map

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

## Build prerequisites

- 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](https://taskfile.dev) as the build runner.
- The NVIDIA CUDA toolkit for the GPU miner.

Build and test:

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

## Choose a network before writing code

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

## Gotchas for Bitcoin developers

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.

> **Read at a specific version.** These were read from the code at v1.4.1 and spot-checked at v1.5.2. Check the tag you build against: details move between releases.

## How to contribute well

1. **Reproduce the issue.** Record the release, operating system, processor, network, logs and the smallest steps that trigger it.
2. **Search existing issues.** Avoid duplicates; add evidence to an open issue when it fits.
3. **Make the smallest coherent change.** Keep consensus, wallet and interface changes apart where you can.
4. **Run the relevant tests.** Use the Go and Python suites, and note anything your environment had to skip.
5. **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](https://github.com/pearl-research-labs/pips).

## Sources

- [Pearl monorepo on GitHub](https://github.com/pearl-research-labs/pearl) (Pearl Research Labs, primary)
- [Official Pearl releases](https://github.com/pearl-research-labs/pearl/releases) (Pearl Research Labs, primary)
- [Pearl v1.5.2 release notes](https://github.com/pearl-research-labs/pearl/releases/tag/v1.5.2) (Pearl Research Labs, primary)
- [Pearl INT whitepaper (the scheme mainnet runs)](https://pearlresearch.ai/research/int-whitepaper) (Pearl Research Labs, primary)