Nexus is a high performance Application Framework that provides a Peer to Peer electronic cash system with support for real-time smart contracts powered with a 64-bit register virtual machine. Nexus technology is developed to improve the overall security, scalability, and usability of Internet driven Applications.
We use a very strict branching logic for our development. The branch 'merging' is the main development branch, which contains the most up-to-date code. The branch 'master' is the stable branch, that contains releases. If you are compiling from source, ensure you use the 'master' branch or pull from a release tag. The branch 'staging' is for pre-releases, so if you would like to test out new features before full release, but want to ensure they are mostly stable, use 'staging'.
We use Make to build our project to multiple platforms. Please read out build documentation for instructions and options.
For deterministic local/Codespaces/Copilot dependency bootstrap on Ubuntu, run:
sudo bash contrib/devtools/install-build-deps.shRISC-V - Native and cross-compilation for RV64GC/RV64GCV platforms
Nexus supports both private solo mining and decentralized public mining pools using the enhanced Falcon Handshake protocol.
The LLL-TAO node implements a secure, post-quantum Falcon handshake for miner authentication with the following features:
- Post-Quantum Signatures: Utilizes Falcon-512/1024 signature schemes for quantum-resistant authentication
- ChaCha20 Encryption: Optional ChaCha20 encryption for Falcon public key exchange (mandatory for public nodes, optional for localhost)
- Session Key Generation: Dynamic session keys tied to Tritium GenesisHash ownership
- Replay Protection: Timestamp-based validation prevents replay attacks
- Cache Limit: Hardcoded 500 entry maximum for DDOS protection
- Keep-Alive Ping: Miners must ping every 24 hours (or more frequently)
- Purge Routine: Inactive miners removed after 7 days (remote) or 30 days (localhost)
- Localhost Exception: Extended cache persistence for local solo miners
Private Solo Mining (Localhost)
- Simplified validation with extended cache timeout
- ChaCha20 encryption optional (plaintext allowed)
- Direct reward payout to configured Tritium account
Public Pool Mining (Internet)
- Mandatory TLS 1.3 with ChaCha20-Poly1305-SHA256 cipher suite
- Required Falcon public key encryption during handshake
- Rewards tied to Tritium GenesisHash for stateful validation
- Session-based authentication with automatic purging
The minimum required settings to run a Nexus node as a mining pool server (~/.Nexus/nexus.conf):
# --- Autologin (required for unattended node operation) ---
autologin=1
username=YOUR_USERNAME
password=YOUR_PASSWORD
pin=YOUR_PIN
# --- API Authentication ---
apiuser=YOUR_API_USERNAME
apipassword=YOUR_STRONG_API_PASSWORD
# --- Servers ---
server=1
# --- Enable Mining (starts BOTH servers simultaneously) ---
mining=1
miningport=9323 # Stateless mining server (PORT 9323)
legacyminingport=8323 # Legacy mining server (PORT 8323, auto-starts)
# --- Network ---
listen=1
maxconnections=99
llpallowip=127.0.0.1 # Localhost testing
#llpallowip=0.0.0.0 # Public internet pool
# --- Post-Quantum Authentication ---
falcon=1
Localhost Testing: Use
llpallowip=127.0.0.1— miners on the same machine connect to127.0.0.1:9323
Public Internet: Switch tollpallowip=0.0.0.0— miners point to your public IP on port9323
Security:chmod 600 ~/.Nexus/nexus.confto protect your credentials
The node runs two mining servers simultaneously:
| Server | Port | Protocol | Miners |
|---|---|---|---|
| Stateless | 9323 |
16-bit framing (Phase 2) | NexusMiner (stateless config) |
| Legacy | 8323 |
8-bit framing (Phase 1) | Backward-compatible miners |
Linux Epoll Optimization: On Linux, mining DataThreads use a dedicated
epollevent loop with 1 ms timeout for sub-millisecond I/O responsiveness. Non-Linux platforms fall back topoll()with a 10 ms timeout. Production mining nodes should run on Linux for optimal performance. See Linux Epoll Mining Architecture for details.
For a complete reference see nexus.conf Reference.
Developing on Nexus has been designed to be powerful, yet simple to use. Tritium++ packages features from SQL Queries, filters, sorting, statistical operators, functions, variables, and much more. The API uses a RESTFul HTTP-JSON protocol, so that you can access the power of Smart Contracts on Nexus from very basic web experience to advanced capabilities. The API is always expanding, so if you find any bugs or wish to suggest improvements, please use the Issues tracker and submit your feedback.
If you are new to this repository, start with the codebase shape rather than the project story:
src/LLP/- networking, mining, session management, sync edge handlingsrc/TAO/- ledger, consensus, contracts, registers, and API logicsrc/LLD/- storage and database accesssrc/Legacy/- backward-compatible legacy wallet and RPC surfacetests/{unit,smoke,live,bench}- validation layers for different development stagesmakefile.cli- the active build entrypoint used in this branch
For local onboarding, use the deterministic bootstrap path already wired into the repo:
sudo bash contrib/devtools/install-build-deps.sh
make -f makefile.cli -j"$(nproc)"
make -f makefile.cli UNIT_TESTS=1 -j"$(nproc)"The highest-value reading path for a new coder is:
README.mddocs/onboarding/ai-assisted-onboarding.mdsrc/LLP/mining/session codesrc/TAO/Ledger/consensus/sync code
Nexus is released under the terms of the MIT license. See LICENSE for more information or see https://opensource.org/licenses/MIT.
Architecture diagrams, protocol visualizations, and onboarding guides:
- Diagram Templates & Architecture Diagrams - 15+ Mermaid and ASCII diagrams
- Linux Epoll Mining Architecture - Why Linux-only epoll for mining I/O
- Recent Mining Changes (PRs #502–#545) - Change log for future developers
- Canonical Session Handling - Live vs inactive registry flow, lane handoff, and reactivation diagrams
- Known Risks & Limitations - Current risks and escalation triggers
- AI-Assisted Developer Onboarding - Learning pathways with AI guidance
- New Coder Repo Guide - Repo shape, architectural risks, workflow guidance, and AEP/dynAEP assessment
- AI-Human Advancement Thesis - Collaboration philosophy
- Mining Debug Cheat Sheet
- Consensus Debug Cheat Sheet
- Performance Tuning
If you would like to contribute as always submit a pull request. All code contributions should follow the comments and style guides. See COMMENTS or STYLEGUIDE for more information.
See Coding Agent Best Practices for guidelines on creating effective PR descriptions that work within the 3,000 character limit.
Quick reference: Cheat Sheet