Go Consensus

This repository contains a consensus-compatible reimplementation of a P2Pool internals for Monero P2Pool decentralized pool.

As part of this work, several libraries to work with Monero and its cryptography are also maintained.

You may be looking for P2Pool Observer instead.

Reporting issues

You can give feedback or report / discuss issues or provide changes on:

• The issue tracker on git.gammaspectra.live/P2Pool/consensus
• Via IRC on #p2pool-observer@libera.chat [WebIRC] or general Monero channels
• Via Matrix on #p2pool-observer:monero.social or general Monero channels, or @DataHoarder:monero.social

Security issues

Reporting potential security issues must be done privately. If you are unsure, feel free to reach out.

This can be done on:

• Via Matrix private message to @DataHoarder:monero.social
• Email to weebdatahoarder [at] protonmail.com.

Note: If sending mail, it's recommended to send an advisory private message to Matrix.

You must disclose usage of automated tools (fuzzers, static checkers) or AI-driven tools if used on your findings.

Reports will be reviewed and answered to. There are no bug bounties at this time, but may provide one personally to extraordinary issues.

Libraries in this package

Path	Status	Documentation	Description
merge_mining	🛠️ In development		Implements the Merge Mining format and API.
monero/address	✅ Supported		Implements Monero Cryptonote address decoding/encoding, and generation of Transaction Proofs
monero/address/carrot	🛠️ In development		Implements Carrot addressing protocol.
monero/address/cryptonote	🛠️ In development		Implements legacy CryptoNote subaddress protocol.
monero/address/wallet	Semi-Internal		Implements generic View Wallet and Spend Wallet for Legacy Cryptonote and Carrot addressing protocols. Includes Tx match helpers for wallets, tx keys or tx proofs.
monero/block	✅ Supported		Supports decoding/encoding Monero Blocks with V2 Coinbase Transactions, calculating RandomX proof of work, calculating rewards.
monero/client	✅ Supported		High level Monero Daemon RPC client wrapper.
monero/client/rpc	✅ Supported		Monero Daemon RPC client.
monero/client/zmq	✅ Supported		Monero Daemon ZMQ-Pub client.
monero/client/levin	❌ Unsupported		Monero Portable Storage and Levin partial implementation.
monero/crypto	✅ Supported		General Monero cryptography data types, generators and hashers, passing all upstream tests. Keccak256, Blake2b, merkle trees, signatures, hash to point and key images.
monero/crypto/curve	🛠️ In development		Generic Field, Scalar and Point definitions and operations to work on Ed25519/Helios/Selene and others that define common interfaces.
monero/crypto/curve25519	✅ Supported		Specialized Ed25519/X25519 implementation for Monero, with performant constant and variable time implementations.
monero/crypto/ringct	✅ Supported		RingCT general data types, Pedersen commitments and original ring signatures.
monero/crypto/ringct/borromean	✅ Supported port		Borromean range proofs. Only verification supported.
monero/crypto/ringct/bulletproofs	✅ Supported port		Bulletproofs and Bulletproofs+ range proofs.
monero/crypto/ringct/clsag	✅ Supported port		Implements CLSAG RingCT ring signature scheme.
monero/crypto/ringct/mlsag	✅ Supported port		Implements MLSAG RingCT ring signature scheme.
monero/crypto/ringct/generalized-bulletproofs	⏳ Planned		Implements Generalized Bulletproofs.
monero/crypto/ringct/fcmp-plus-plus	🛠️ In development		Implements FCMP++ proofs.
monero/crypto/multiexp	🛠️ In development		Wrapper utilities for fast multiexponentiation in constant or variable time.
monero/proofs	✅ Supported		Implements Monero proofs, for generating and verifying Transaction proofs, Spend proofs.
monero/randomx	✅ Supported		Implements RandomX proof of work, with pure Go implementation and optional C library.
monero/cryptonight	✅ Supported		Implements CryptoNight proof of work, with variants v0, v1, v2, R supported, with pure Go. Aimed for verification (not mining) purposes.
monero/transaction	✅ Supported		Allows decoding/encoding and verifying transactions from binary, along its proofs on V1 and V2 transactions for all supported ring signatures and range proofs. Supports pruning.
p2pool/mempool	✅ Supported		Mempool selection algorithm for P2Pool.
p2pool/p2p	✅ Supported		P2Pool Consensus P2P implementation. For go-p2pool.
p2pool/sidechain	✅ Supported		P2Pool Consensus SideChain, compatible across all P2Pool versions and hard forks. Passes all upstream tests. For go-p2pool and Observer.
p2pool/stratum	✅ Supported		P2Pool Stratum implementation, supporting multiple addresses. For go-p2pool.
types	✅ Supported		General data types to work with 256-bit hashes or other fixed bytes, proof of work checking and 128-bit network difficulty.
utils	Semi-Internal		Utilities to decode or work with specialized Monero types.

Support Status Description

• ✅ Supported: Fully supported, maintained, and regularly/automatically tested. They are built for external consumption. Will follow the semver of the main package.
• ✅ Supported port: Fully supported, maintained, and regularly/automatically tested. They are built for external consumption. Will follow the semver of the main package. These were ported from monero-oxide, unless specified.
• Semi-Internal: Supported, when used along with other parts of this package. Not supported when used independently.
• Internal: Not supported when used externally. Supported within the package.
• 🛠️ In Development: Currently in development or not finished. It is not guaranteed to not break, even across minor patches. Use at your own discretion.
• ⏳ Planned: Planned to be developed.
• ❌ Unsupported: Not supported. Package may be deprecated or not currently developed.

Note: Project is automatically tested under Linux for amd64 and arm64 architectures, with normal, purego, and cgo flavors. Other platforms are tested manually. 32-bit platforms should work but are not supported, but may receive fixes as needed.

Other maintained external libraries

Package	Status	Description
go-p2pool	✅ Supported	Alternative P2Pool daemon implementation in Go. Supports full consensus and mining, with similar arguments. Able to run P2Pool seed nodes.
go-randomx	✅ Supported	Implements pure Go RandomX, with JIT for amd64 and native support for more architectures, and purego implementation for WASM. Achieves ~90% speed of equivalent full mode under amd64, aimed for verification (not mining) purposes.
edwards25519	✅ Supported	Implements the edwards25519 elliptic curve, with extensions to support Monero operations efficiently. Builds on top of FiloSottile/edwards25519 as a fork.
helioselene	🛠️ In Development	Implements Helio-Selene, Elliptic curve tower-cycle for Curve25519. Efficient purego implementation using formally proven field element operations.
monero-base58	✅ Supported	Efficient Monero's Base58 encoder/decoder.

SemVer and usage in other projects

This package follows SemVer v2 from v5.x.x onwards, with the following additions or exceptions:

• MINOR version of 0 indicates an in-development version. In this case, PATCH indicates API changes, additions, or breakage. Once MINOR version is increased to one or above, normal SemVer resumes.
• Untagged or development branches are not covered by SemVer versions.
• Security releases MAY break backwards compatibility.
• ❌ Unsupported, 🛠️ In Development, Semi-Internal or Internal subpackages are not covered by the SemVer version.

Donations

This project is provided for everyone to use, for free. Any support is appreciated.

Donate to support this project, its development, and running the Observer Instances on 4AeEwC2Uik2Zv4uooAUWjQb2ZvcLDBmLXN4rzSn3wjBoY8EKfNkSUqeg5PxcnWTwB1b2V39PDwU9gaNE5SnxSQPYQyoQtr7

You can also use the OpenAlias p2pool.observer directly on the GUI.

Development notes

Running tests

cd path/to/project/consensus
MONEROD_RPC_URL=http://127.0.0.1:18081
MONEROD_ZMQ_URL=tcp://127.0.0.1:18083
go test -v ./...

Initialize test data

Several test data is provided outside the repository tree, but is verified with saved hashes. Monero crypto tests and P2Pool crypto and sidechain tests will be downloaded. Requires curl and sha256sum installed.

Note: This only needs to be run once, or when new test data is added.

cd path/to/project/consensus
./testdata/setup.sh

Running linters

Install golangci-lint

The config is available in-tree at .golangci.yml

cd path/to/project/consensus
golangci-lint run ./...
go vet ./...

Requirements

Go 1.26

By default, CGO is not necessary, so CGO_ENABLED=0 is recommended. You may use the purego build flag to disable any assembly or architecture specific optimizations.

This library supports both go-RandomX library and the C++ RandomX reference counterpart.

By default, the Golang library will be used, without special requirements.

You can enable the C++ library if by using CGO and the Go compile tag enable_randomx_library and use CGO_ENABLED=1. You must have the library installed or done via the command below:

$ git clone --depth 1 --branch v2.0.1 https://github.com/tevador/RandomX.git /tmp/RandomX && cd /tmp/RandomX && \
    mkdir build && cd build && \
    cmake .. -DCMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX:PATH=/usr && \
    make -j$(nproc) && \
    sudo make install && \
    cd ../ && \
    rm -rf /tmp/RandomX