Official Website ⟩

Development and Testing

NockApp application developers produce sovereign applications capable of communicating with each other using Nockchain and gRPC. Most application development will not take place on the live Nockchain network to economize on $NOCK. How can application developers set up and use a fakenet to verify their code's behavior?

Local Fakenet

The simplest fakenet is provided out-of-the-box with the Nockchain binary, using the flag --fakenet. This creates an instance with its own genesis block and mining parameters. This is the simplest viable fakenet mining command, assuming a suitable PKH is provided:

nockchain --mine --fakenet --mining-pkh ${MINING_PKH} --no-default-peers

Scripts are provided for a default miner and a default node, at scripts/run_nockchain_miner_fakenet.sh and scripts/run_nockchain_node_fakenet.sh. A FAKENET_SEEDPHRASE should be provided (see Development and Testing for details and warnings) for the fakenet wallet.

The fakenet miner should be configured with appropriate wallet keys. We suggest using these standard fakenet keys (reiterated in Credentials):

FAKENET_SEEDPHRASE_0 ?= "farm step rhythm surprise math august panther pulse protect remain anger depend adjust sting enable poet describe stone essay blast click horse hair practice"
FAKENET_PKH_0 ?= "9yPePjfWAdUnzaQKyxcRXKRa5PpUzKKEwtpECBZsUYt9Jd7egSDEWoV"

A sophisticated fakenet miner command is:

nockchain --mine --fakenet --fakenet-v1-phase 1 --mining-pkh $(FAKENET_PKH₉0 --bind /ip4/0.0.0.0/udp/3005/quic-v1  --no-default-peers --fakenet-coinbase-timelock-min 0

If this works correctly, it will produce a genesis block then start to mine on it. (To clear this and restart, run rm -rf .data.nockchain.

The corresponding fakenet node command is:

nockchain --fakenet --bind-public-grpc-addr 127.0.0.1:5555 --bind /ip4/127.0.0.1/udp/3006/quic-v1

(The local gRPC server is at port 5555 by default.)

For instance, if working with the CLI wallet, the necessary import commands to work with the fakenet link to the local fakenet instance:

nockchain-wallet import-keys --seedphrase $(FAKENET_SEEDPHRASE_0) --version 1
nockchain-wallet <SUBCOMMAND> --private-grpc-server-port 5555

Other NockApp applications will need to similarly connect to the private fakenet instance to transact and observe fakenet chain state.

Parameters

A fakenet permits several configurable parameters.

  • --fakenet-pow-len <FAKENET_POW_LEN>, the size of the proof of work puzzle for mining. The livenet used 64 to start. This must be a power of 2, and defaults to 2. Currently, to use a different PoW difficulty, you must supply an appropriate genesis block with --fakenet-genesis-jam-path .)

  • --fakenet-log-difficulty <FAKENET_LOG_DIFFICULTY>, the base-2 logarithm target difficulty for mining. This defaults to 2 (thus 2² attempts on average to find a block).

  • --fakenet-v1-phase <FAKENET_V1_PHASE>, the v1 activation height. The default is 39,000, so you likely want to set this to 1. (You cannot set it to zero since the genesis block is a v0 block and will be rejected.)

  • --fakenet-genesis-jam-path <FAKENET_GENESIS_JAM_PATH>, the path to the fakenet genesis block jamfile. This is the easiest way to work with PoW difficulties other than 2.

    • Several genesis block jamfiles are supplied with the Nockchain repository in crates/nockchain/jams with names like fakenet-genesis-pow-64-bex-5.jam. This means that the genesis block corresponds to --fakenet-pow-len 64 --fakenet-log-difficulty 5, and so forth.

  • --fakenet-coinbase-timelock-min, set the timelock on newly mined coins. The default and livenet behavior is 100, but it's convenient in testing to set this much lower.

Application developers will generally prefer fakenets with short block times so that transaction confirmations can be tested efficaciously. Block time is a function of hardware and difficulty, so you may need to experiment to find something workable for your development workflow.

Notes

  • At the current time, the difficulty adjustment epoch does not work on fakenets. This happens at block height 2016, at which point the fakenet currently stops mining.

  • Default coinbase timelocks are in place (at 100 blocks), so fakenets that rely on spending should have a height greater than 100 before attempting to transact unless they have manually set a lower timelock.

Credentials

A Nockchain wallet is a pure cryptographic product, consisting of a private key, a public key and pubkey hash (pkh), a BIP39 seed phrase, and a chain code. These do not have an inherent network association. What determines the assets associated with the wallet is the node to which that wallet connects. Thus a wallet that connects to a local fakenet is transacting with that fakenet; a wallet connecting with the same keys to the livenet is transacting with Nockchain itself.

The statejam for the fakenet should be used carefully to avoid any cross-contamination of livenet and fakenet assets.

We suggest using these standard fakenet keys:

FAKENET_SEEDPHRASE_0 ?= "farm step rhythm surprise math august panther pulse protect remain anger depend adjust sting enable poet describe stone essay blast click horse hair practice"
FAKENET_PKH_0 ?= "9yPePjfWAdUnzaQKyxcRXKRa5PpUzKKEwtpECBZsUYt9Jd7egSDEWoV"

⚠️ WARNING These keys do work on the livenet, so be careful when using a wallet to interact with a fakenet and livenet.

In that case, a full command could look something like this:

nockchain --mine --fakenet --mining-pkh "9yPePjfWAdUnzaQKyxcRXKRa5PpUzKKEwtpECBZsUYt9Jd7egSDEWoV" --no-default-peers --fakenet-coinbase-timelock-min 0 --fakenet-v1-phase 1 --fakenet-genesis-jam-path crates/nockchain/jams/fakenet-genesis-pow-64-bex-5.jam --fakenet-pow-len 64 --fakenet-log-difficulty 5

Docker Fakenet Setup

The Docker Fakenet provides a containerized development environment for building and testing NockApps. This setup eliminates the need to install Rust, Cargo, or compile nockchain locally, making it easy to spin up a local test network in minutes.

Essentially, this runs a containerized fakenet that runs a miner and n nodes, with node 0 matching the miner and nodes 1–(n-1) matching the first (n-1) derived child keys from the standard fakenet pkh.

Overview

The Docker Fakenet consists of:

  • Mining Node: Produces blocks and maintains the blockchain.

  • Non-Mining Nodes: Executes queries and wallet operations without mining overhead. Intended for use with applications under development.

  • Automated Wallet Derivation: Each node receives a unique wallet derived from the standard fakenet seed phrase.

  • gRPC API Access: Full API access for NockApp development and testing.

All components are built from source in reproducible Docker containers, ensuring consistency across development environments.

Quick Start

Full documentation is available at sigilante/nockchain-fakenet-docker.

# Clone the repository
git clone https://github.com/sigilante/nockchain-fakenet-docker.git
cd nockchain-fakenet-docker

# Build and start the network (first build takes 20-40 minutes)
docker-compose build
docker-compose up -d

# Verify services are running
docker-compose ps

# Check logs
docker-compose logs -f

Once started, the network provides:

  • Mining Node: localhost:5555 (gRPC)

  • Non-Mining Node: localhost:5556 (gRPC)

    • Subsequent non-mining nodes are located at 5557, 5558, and so forth.

Both nodes use the standard fakenet credentials:

Seed Phrase: farm step rhythm surprise math august panther pulse protect remain anger depend adjust sting enable poet describe stone essay blast click horse hair practice
Master PKH: 9yPePjfWAdUnzaQKyxcRXKRa5PpUzKKEwtpECBZsUYt9Jd7egSDEWoV

Subsequent non-mining nodes use child keys derived deterministically from the master key.

Network Architecture

Node Configuration

The default setup runs two nodes:

  1. Mining Node (nockchain-fakenet-miner)

    • Mines blocks with adjustable proof-of-work difficulty

    • Receives mining rewards to the master PKH

    • Binds gRPC API to 0.0.0.0:5555

    • P2P: /ip4/0.0.0.0/udp/30303/quic-v1

  2. Non-Mining Node (nockchain-fakenet-node)

    • Synchronizes with the mining node via P2P

    • Ideal for wallet operations and NockApp queries

    • Binds gRPC API to 0.0.0.0:5555 (mapped to host port 5556)

    • Explicitly connects to miner: /dns4/nockchain-fakenet-miner/udp/30303/quic-v1

Both nodes share the same wallet by default, simplifying development workflows where a single account is sufficient.

Wallet Derivation

The setup uses Nockchain's BIP39 hierarchical deterministic wallet derivation:

  • Master Key: Used by the mining node and first non-mining node.

  • Child Keys: Additional nodes derive unique wallets using child key indices 1, 2, 3, etc.

  • Deterministic: Wallets are reproducible from the seed phrase.

Child index 0 is intentionally skipped to avoid confusion with the master key.

Accessing the Network

gRPC API

Query the network using grpcurl or any gRPC client:

# Relative references to .proto files refer to the Nockchain repo.
cd nockchain

# List available services
grpcurl -plaintext \
  -import-path crates/nockapp-grpc-proto/proto \
  -proto nockchain/public/v2/nockchain.proto \
  127.0.0.1:5555 list

# List service methods
grpcurl -plaintext \
  -import-path crates/nockapp-grpc-proto/proto \
  -proto nockchain/public/v2/nockchain.proto \
  127.0.0.1:5555 list nockchain.public.v2.NockchainService

# Describe a service
grpcurl -plaintext \
  -import-path crates/nockapp-grpc-proto/proto \
  -proto nockchain/public/v2/nockchain.proto \
  127.0.0.1:5555 describe nockchain.public.v2.NockchainService

The proto files are located in the crates/nockapp-grpc-proto/proto directory of the nockchain repository.

Wallet Operations

Execute wallet commands inside containers:

# Create a new wallet
docker exec -it nockchain-fakenet-node nockchain-wallet create --fakenet

# Import the standard fakenet keys
docker exec -it nockchain-fakenet-node nockchain-wallet import-keys \
  --seedphrase "farm step rhythm surprise math august panther pulse protect remain anger depend adjust sting enable poet describe stone essay blast click horse hair practice" \
  --version 1

# Derive a child key
docker exec -it nockchain-fakenet-node nockchain-wallet derive-child 1

Verifying Network Operation

Check that nodes are communicating correctly:

# Automated health check
./scripts/check-p2p.sh

This script verifies:

  • Container health status

  • Network connectivity between nodes

  • Peer connection establishment

  • Block synchronization

Expected output includes peer connection messages and block propagation between nodes.

Scaling the Network

Adding Nodes Automatically

Generate additional nodes with unique wallets:

# Add 3 nodes (total of 5 nodes including base setup)
./scripts/add-nodes.sh 3

# Start all services
docker-compose up -d

This creates docker-compose.override.yml with:

  • nockchain-node-2: Child key index 1, ports 5557/30305

  • nockchain-node-3: Child key index 2, ports 5558/30306

  • nockchain-node-4: Child key index 3, ports 5559/30307

Each node derives a unique wallet from the standard seed phrase.

Dynamic Node Creation

For temporary testing, spin up individual nodes without modifying configuration:

# Start a node with child key index 1
./scripts/run-node.sh 1

# Start a node with child key index 2 on custom ports
./scripts/run-node.sh 2 5558 30306

# View logs
docker logs -f nockchain-node-dynamic-1

# Cleanup
docker stop nockchain-node-dynamic-1
docker rm nockchain-node-dynamic-1

See Scaling Nodes for detailed multi-node configuration strategies.

Data Persistence

Blockchain data is stored in Docker volumes:

# List volumes
docker volume ls | grep nockchain

# Backup miner data
docker run --rm \
  -v nockchain-fakenet-docker_nockchain-miner-data:/data \
  -v $(pwd)/backup:/backup \
  ubuntu tar czf /backup/miner-data.tar.gz /data

# Fresh start (deletes all data)
docker-compose down -v
docker-compose up -d

NockApp Development Workflow

1. Start the Fakenet

docker-compose up -d

2. Develop Your NockApp

Use nockup inside a container or on your host:

# Create new NockApp project
# Copy over example manifest file and edit it.
nockup init my-nockapp

# Develop your application
# Edit my-nockapp/src/hoon/app/app.hoon

3. Build Your NockApp Application

# Build the NockApp with nockup
nockup build my-nockapp

# This generates compiled artifacts in your project directory in target/

4. Deploy to the Container

# Copy your NockApp artifacts to the container
docker cp ./my-nockapp/target nockchain-fakenet-node:~/my-nockapp

Alternatively, mount your NockApp directory as a volume in docker-compose.yml:

nockchain-fakenet-node:
  volumes:
    - ./my-nockapp:/home/nockchain/nockapp:ro

Then run from the mounted path:

docker exec -it nockchain-fakenet-node nockup run my-nockapp

5. Test and Query

# List available endpoints
grpcurl -plaintext \
  -import-path crates/nockapp-grpc-proto/proto \
  -proto nockchain/public/v2/nockchain.proto \
  127.0.0.1:5555 list

# Query your NockApp via gRPC at custom application endpoint
grpcurl -plaintext \
  -import-path crates/nockapp-grpc-proto/proto \
  -proto nockchain/public/v2/nockchain.proto \
  -d '{"your": "request"}' \
  127.0.0.1:5556 nockchain.public.v2.NockchainService/YourMethod

6. Monitor Activity

# Watch miner logs
docker-compose logs -f nockchain-fakenet-miner

# Watch node logs
docker-compose logs -f nockchain-fakenet-node

# Check P2P connectivity (in practice, seems to underreport actual connectivity)
./scripts/check-p2p.sh

Contributing

This project is maintained at: sigilante/nockchain-fakenet-docker.

PreviousArchitectureNextBuilding with Nockup

Last updated