Developer Guide

This page is for developers, testers, and integrators who want to work directly with the xPrivFi protocol. It focuses on practical usage: building from source, running a node, trying RPC calls, and experimenting on a local test environment. For a deeper protocol description, see Docs and Specs.

1. Requirements

To build and run the node you will need:

• A 64-bit OS (Linux, macOS, or Windows WSL recommended).
• Go toolchain (recent stable version).
• Git (or other access method to the source repository).
• Basic command-line familiarity.

The node is intentionally small and should run comfortably on a modest VPS or laptop.

2. Build From Source

Clone the official xPrivFi node repository and build it with Go. Commands below are an example — adjust paths and module names to your actual repo layout.

# 1. Clone repository
git clone <XPF_NODE_REPOSITORY_URL>
cd <xpf-node-repository>

# 2. Fetch Go modules
go mod tidy

# 3. Build the node binary
go build -o xpfnode ./cmd/xpfnode

# after this, you should have an executable named "xpfnode"
      

Keep the build steps simple. Any major changes to the Go toolchain or directory structure should be documented alongside the code.

3. Running a Node

Once the binary is built, you can start a node. Example:

# run the node with a default data directory
./xpfnode

# or explicitly specify data dir / rpc port (example flags)
./xpfnode \
  --datadir /var/lib/xpfnode \
  --rpcaddr 127.0.0.1:8080
      

On startup, the node will:

• load or initialize the local chain database,
• initialize state (balances, nonces, remaining mineable supply),
• connect to peers (when P2P is configured),
• expose the JSON-RPC interface on the configured address/port.

Logs should show the current tip height, difficulty, and sync progress.

4. Basic JSON-RPC Usage

By default, the node exposes a JSON-RPC service over HTTP (example: http://127.0.0.1:8080). All methods follow the standard JSON-RPC 2.0 format:

POST /rpc
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_balance",
  "params": {
    "address": "XPF1..."
  }
}
      

4.1 Example: Get Balance

curl -X POST http://127.0.0.1:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"get_balance",
    "params":{"address":"XPF1EXAMPLEADDRESS"}
  }'
      

4.2 Example: Get Sync Status

curl -X POST http://127.0.0.1:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"get_sync_status",
    "params":{}
  }'
      

4.3 Example: Submit a Transaction

Transactions are constructed and signed client-side. Once you have a signed transaction in your wallet or tool, broadcast it via submit_tx:

curl -X POST http://127.0.0.1:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"submit_tx",
    "params":{"tx":"<SIGNED_TX_PAYLOAD>"}
  }'
      

See Docs for exact field definitions and transaction format.

5. Local Testnet / Devnet

For development and testing, it is recommended to run a local devnet: a single node with its own data directory, separate from any future public network.

# use a dedicated data dir for your local devnet
./xpfnode --datadir ./devnet-data
      

A typical local dev loop:

1. Start the node with a fresh devnet data directory.
2. Use a local wallet or script to generate test addresses.
3. Mine or pre-allocate some funds to a dev address (depending on your build).
4. Call submit_tx to test transactions and fees.
5. Watch state changes via get_balance and get_sync_status.

When a dedicated public testnet is launched, it will be documented here with specific flags (e.g. --testnet) and bootstrap peers.

6. HexGrid Layer-2 Integration

HexGrid is the browser-based mining game that implements the 6-minute, 200–890-participant mining rounds. It runs entirely off-chain and uses the JSON-RPC API to:

• read sync status and basic chain data,
• verify that the node is on the expected tip,
• submit reward transactions for the selected winner each round.

The base protocol does not know anything about HexGrid rules. From the chain’s perspective, HexGrid reward payouts are just normal transactions.

When integrating your own tools, follow the same pattern: perform coordination and game logic off-chain, then commit results to Layer-1 via standard signed transactions.

7. Project Layout (High-Level)

Exact directories depend on the repository, but a typical xPrivFi node layout looks like:

• /cmd/xpfnode — main entrypoint for the node binary.
• /core or /consensus — block/tx validation, rewards, difficulty.
• /state — balances, nonces, remaining supply, persistence.
• /rpc — JSON-RPC server and method handlers.
• /p2p — peer management and gossip (as it evolves).
• /wallet (optional) — CLI wallet helpers and key management.

Keep consensus-critical code small and reviewable. Application logic, experiments, and tools should live around it, not inside it.

8. Best Practices & Contributions

• Do not modify consensus logic on nodes that should follow the canonical chain (unless you are deliberately running a fork or devnet).
• Use a separate data directory for each environment (devnet, testnet, mainnet).
• Inspect logs when debugging — most validation errors are clearly reported.
• Keep your Go toolchain and dependencies up to date.
• Open issues and propose changes in small, reviewable units.

The Layer-1 node is intended to remain MIT-licensed and independently implementable. HexGrid and certain Layer-2 components are proprietary and documented at a higher level only.