Nockchain is a lightweight blockchain for heavyweight verifiable applications.
We believe the future of blockchains is lightweight trustless settlement of heavyweight verifiable computation. The only way to get there is by replacing verifiability-via-public-replication with verifiability-via-private-proving. Proving happens off-chain; verification is on-chain.
Nockchain is entirely experimental and many parts are unaudited. We make no representations or guarantees as to the behavior of this software.
Install rustup by following their instructions at: https://rustup.rs/
Ensure you have these dependencies installed if running on Debian/Ubuntu:
sudo apt update
sudo apt install clang llvm-dev libclang-dev
Copy the example environment file and rename it to .env:
cp .env_example .env
Install hoonc, the Hoon compiler:
make install-hoonc
export PATH="$HOME/.cargo/bin:$PATH"
To build the Nockchain and the wallet binaries and their required assets:
make build
After you've run the setup and build commands, install the wallet:
make install-nockchain-wallet
export PATH="$HOME/.cargo/bin:$PATH"
See the nockchain-wallet README for more information.
After you've run the setup and build commands, install Nockchain:
make install-nockchain
export PATH="$HOME/.cargo/bin:$PATH"
To generate a new key pair:
nockchain-wallet keygen
This will print a new public/private key pair + chain code to the console, as well as the seed phrase for the private key.
Now, copy the public key to the .env file:
MINING_PUBKEY=<public-key>
To backup your keys, run:
nockchain-wallet export-keys
This will save your keys to a file called keys.export in the current directory.
They can be imported later with:
nockchain-wallet import-keys --input keys.export
Make sure your current directory is nockchain.
To run a Nockchain node without mining.
sh ./scripts/run_nockchain_node.sh
To run a Nockchain node and mine to a pubkey:
sh ./scripts/run_nockchain_miner.sh
For launch, make sure you run in a fresh working directory that does not include a .data.nockchain file from testing.
Yes, you can use the same pubkey if running multiple miners.
Run nockchain-wallet keygen to generate a new key pair.
If you are using the Makefile workflow, copy the public key to the .env file.
To run multiple instances on the same machine, you need to:
- Create separate working directories for each instance
- Use different ports for each instance
Here's how to set it up:
Inside of the nockchain directory:
# Create directories for each instance
mkdir node1 node2
# Copy .env to each directory
cp .env node1/
cp .env node2/
# Run each instance in its own directory with .env loaded
cd node1 && sh ../scripts/run_nockchain_miner.sh
cd node2 && sh ../scripts/run_nockchain_miner.shNockchain requires:
- Internet.
- If you are behind a firewall, you need to specify the p2p ports to use and open them..
- Example:
nockchain --bind /ip4/0.0.0.0/udp/$PEER_PORT/quic-v1
- Example:
- NAT Configuration (if you are behind one):
- If behind NAT, configure port forwarding for the peer port
- Use
--bindto specify your public IP/domain - Example:
nockchain --bind /ip4/1.2.3.4/udp/$PEER_PORT/quic-v1
Common reasons for peer connection failures:
-
Network Issues:
- Firewall blocking P2P port
- NAT not properly configured
- Incorrect bind address
-
Configuration Issues:
- Invalid peer IDs
-
Debug Steps:
- Check logs for connection errors
- Verify port forwarding
Outgoing connection failures can occur due to:
-
Network Issues:
- Peer is offline
- Firewall blocking connection
- NAT traversal failure
-
Peer Issues:
- Peer has reached connection limit
- Peer is blocking your IP
-
Debug Steps:
- Check peer's status
- Verify network connectivity
- Check logs for specific error messages
No way to manually check mining status yet. We're working on it.
In the meantime, you can check the logs for mining activity.
If you see a line that looks like:
[%mining-on 12.040.301.481.503.404.506 17.412.404.101.022.637.021 1.154.757.196.846.835.552 12.582.351.418.886.020.622 6.726.267.510.179.724.279]No way to manually check block height yet. We're working on it.
In the meantime, you can check the logs for a line like:
block Vo3d2Qjy1YHMoaHJBeuQMgi4Dvi3Z2GrcHNxvNYAncgzwnQYLWnGVE added to validated blocks at 2That last number is the block height.
Common errors and their solutions:
- Connection Errors:
Failed to dial peer: Network connectivity issues, you may still be connected though.Handshake with the remote timed out: Peer might be offline, not a fatal issue.
To check your wallet balance:
# List all notes (UTXOs) that your node has seen
nockchain-wallet --nockchain-socket ./nockchain.sock list-notes
# List all notes by pubkey
nockchain-wallet --nockchain-socket ./nockchain.sock list-notes-by-pubkey <your-pubkey>To reduce logging verbosity, you can set the RUST_LOG environment variable before running nockchain:
# Show only info and above
RUST_LOG=info nockchain
# Show only errors
RUST_LOG=error nockchain
# Show specific module logs (e.g. only p2p events)
RUST_LOG=nockchain_libp2p_io=info nockchain
# Multiple modules with different levels
RUST_LOG=nockchain_libp2p_io=info,nockchain=warn nockchainCommon log levels from most to least verbose:
trace: Very detailed debugging informationdebug: Debugging informationinfo: General operational informationwarn: Warning messageserror: Error messages
You can also add this to your .env file if you're running with the Makefile:
RUST_LOG=info
-
Node Won't Start:
- Check port availability
- Verify .env configuration
- Check for existing .data.nockchain file
- Ensure proper permissions
-
No Peers Connecting:
- Verify port forwarding
- Check firewall settings
-
Mining Not Working:
- Verify mining pubkey
- Check --mine flag
- Ensure peers are connected
- Check system resources
-
Wallet Issues:
- Verify key import/export
- Check socket connection
- Ensure proper permissions