Boing Network Documentation

Getting Started

Prerequisites

• Rust — Latest stable (1.70+). Install via rustup.
• OS — Linux, macOS, or Windows (WSL recommended on Windows).

Clone and build

From the boing.network repository:

git clone https://github.com/Boing-Network/boing.network.git
cd boing.network
cargo build --release

Directory layout after build

• target/release/boing-node — Node binary.
• target/release/boing — CLI binary.
• ~/.boing/ or ./data/ (with --data-dir) — Chain and state data.

Run a node

Full node (non-validator):

cargo run -p boing-node

RPC is available at http://127.0.0.1:8545 by default.

Validator node:

cargo run -p boing-node -- --validator --rpc-port 8545

Produces blocks when there are pending transactions.

With a custom data directory:

cargo run -p boing-node -- --data-dir ./boing-data --rpc-port 8545

Options

• --validator — Run as a block producer.
• --rpc-port <port> — RPC port (default: 8545).
• --data-dir <path> — Data directory for chain and state.

First transaction

Use the JSON-RPC API at http://<host>:8545/. See the RPC API section for boing_submitTransaction, boing_simulateTransaction, and boing_chainHeight.

Next steps

See Operations for CLI commands, monitoring, and troubleshooting; RPC API for all methods; and Tokenomics if you plan to run a validator or stake.

Network Overview

Boing is a greenfield L1 — original architecture, not a fork — with no reliance on other chains.

Design principles

• Authentic — Your own stack; not a framework clone.
• Independent — Core protocol does not depend on another L1 for consensus, execution, or identity.
• Decentralized — Permissionless validators and full nodes.
• Transparent — 100% openness in design, tokenomics, and governance.

Key parameters

• Block time — ~2 seconds (target).
• Consensus — Proof of Stake (PoS) with BFT-style consensus; validators stake BOING.
• State — Sparse Merkle tree commitments and proofs in current boing-state (see repository technical specification; Verkle remains a documented upgrade path in code comments).
• RPC port — Default 8545 (HTTP JSON-RPC).

Tokenomics

Supply model

• Total supply — Uncapped. When circulating supply reaches a defined floor, a new wave of tokens is minted to rebalance (validator incentives, treasury, staking).
• Initial supply — Set at mainnet launch (fixed amount); no infinite mint at genesis.

Fee allocation

Of transaction fees: 80% validators, 20% treasury. Burn is optional (0% in base design).

Initial supply allocation (at launch)

Staking rewards 55%, Treasury 30%, Community & grants 15%. Staking is topped up by new waves when the floor is reached, so the initial allocation leans toward treasury and community.

Floor-triggered waves

Genesis — Fixed initial supply. Ongoing — Validators and treasury earn from fees; supply may decrease slowly until the floor. Floor — When circulating supply reaches the defined floor, the protocol triggers a rebalance. New wave — A new wave of tokens is minted (size and destination set by protocol/governance) to restore balance. All parameters (floor, wave size, trigger) are on-chain and transparent.

Emission schedule (block rewards)

Declining over time: Year 1 ~8%, Year 2 ~6%, then lower; Year 10+ targets a 1% floor or 0% if fees are sufficient. Formula: emission_year_n = emission_year_1 × (decay)^(n-1) with decay ~0.85.

Staking and validator economics

• Min stake — Accessible (e.g. 10,000 BOING) for broad participation.
• Staking yield — 5–15% early, 3–8% at maturity.
• Commission — Validators typically 5–10%; delegators keep the rest.
• Unbonding — 14–21 days.

dApp incentive caps

Per-dApp cap per epoch is governance-controlled (e.g. 50,000 BOING/month). Total dApp pool is a share of fees (e.g. 5% of treasury). Prevents one dApp capturing all incentives; overflow goes to treasury.

Charts and visuals: see the landing page tokenomics.

Architecture & Features

Boing aims to deliver distinct features as protocol primitives rather than add-on contracts.

Core features

• Native Account Abstraction — Gasless txs, social recovery, session keys built into the protocol (not a contract layer).
• Adaptive Gas Model — Gas costs adapt to congestion in real time with predictable upper bounds.
• Native Cross-Chain Primitives — Protocol-level bridges and cross-chain messaging (light clients, not third-party contracts only).
• Transparent Slashing — Clear, auditable slashing conditions and appeal mechanisms; delegators see why validators were slashed.
• On-Chain Governance with Time Locks — Parameter changes go through proposal → cooling → execution so the community can react.

Additional innovations

• State rent with grace periods — Inactive accounts may pay state rent after long grace periods and clear notice.
• Verifiable delay / ordering (VDF) — Boing-native verifiable delay for fair ordering without depending on another chain.
• Native DeFi primitives — Protocol-level swap/AMM-style primitives for boing.finance integration.

RPC API

Boing nodes expose JSON-RPC 2.0 over HTTP POST to http://<host>:8545/ (default port). The authoritative reference is docs/RPC-API-SPEC.md in the repository (also RPC-API-SPEC PDF). Same listener serves GET /live, GET /ready, GET /openapi.json, GET /.well-known/boing-rpc, and GET /ws (newHeads).

Rate limiting, batch limits, and body size are node-configurable; see the spec and boing_health / boing_getNetworkInfo field rpc_surface.

Request format

{"jsonrpc":"2.0","id":1,"method":"boing_chainHeight","params":[]}

Response format

Success: {"jsonrpc":"2.0","id":1,"result":42}. Error: {"jsonrpc":"2.0","id":1,"error":{"code":-32602,"message":"Invalid params"}}.

Methods (current boing-node)

Below matches boing_rpcSupportedMethods / crates/boing-node/src/rpc.rs. Params are JSON arrays; 32-byte ids use 0x + 64 hex chars unless noted.

TypeScript client: npm package boing-sdk (createClient) implements these methods with typed results and explainBoingRpcError for QA / pool errors.

Error codes (selected)

Operations

CLI commands

Shell completions

Example (bash): boing completions bash > ~/.local/share/bash-completion/completions/boing. Similar for zsh, fish.

Monitoring and health

Chain height:

curl -s -X POST http://127.0.0.1:8545/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"boing_chainHeight","params":[]}'

Block by height: Use RPC method boing_getBlockByHeight with params [0] (or desired height).

Logs: Set RUST_LOG=info (or debug / trace) before running the node.

Incident response

For security incidents: (1) Detect — logs, alerts, reports. (2) Assess — severity: Low, Medium, High, Critical. (3) Contain — isolate systems; pause if needed. (4) Communicate — notify validators and users. (5) Remediate — apply fixes; coordinate upgrades via governance. (6) Post-mortem — document cause and prevention. See repository SECURITY-STANDARDS for contacts and bug bounty.

Troubleshooting

• Node won't start — Ensure RPC port is free; run with RUST_LOG=debug; on Windows try WSL or check firewall.
• Transaction not included — Validator mode must be on for block production; simulate with boing_simulateTransaction first; check mempool and nonce order.
• Method not found — Method names are case-sensitive; params must be a JSON array (e.g. [] not {}).
• Build fails — Try cargo clean then cargo build.

Roadmap

Phased build from first principles. Current status:

• Foundation — Complete.
• Networking — Complete.
• Verkle & VM — Complete.
• PoS & Production — In progress.
• UX & Automation — In progress.
• Cross-chain — Planned.
• Testnet & Mainnet — Planned.

See the landing page roadmap and the repository BUILD-ROADMAP for details.

Testnet

Testnet will provide a public network for validators and developers before mainnet. When available you can expect:

• Bootnodes — Public endpoints to join the testnet.
• Faucet — Test tokens for development and validation.
• Incentives — Testnet token or NFT programs for early validators and bug hunters (non-dilutive for mainnet).

Check the repository and network status for testnet announcements and configuration.

Security

Protocol level

• Consensus — BFT-style consensus; network tolerates up to 1/3 malicious validators. PoS and slashing for misbehavior.
• Cryptography — Audited primitives (e.g. Ed25519, BLAKE3).
• State — Sparse Merkle tree state roots and proofs today; aligns with open-source boing-state.

Network level

• Transport — Encrypted P2P (e.g. libp2p).
• Rate limiting — RPC and P2P rate-limited to reduce abuse and DDoS risk.

Incident response

Detect → Assess (Low/Medium/High/Critical) → Contain → Communicate → Remediate → Post-mortem. Audit reports and bug bounty details are published; see SECURITY-STANDARDS in the repository.

Governance & Transparency

Boing commits to 100% transparency. Trust is earned through verification, not promises.

Transparency commitments

• Protocol design — Open design docs, public specs, auditable code.
• Tokenomics — Emission, fee split, floor, and wave parameters on-chain and documented.
• Governance — On-chain proposals, votes, and outcomes; no backroom deals.
• Validator & staking — Clear slashing conditions, reward formulas, and distribution.
• Treasury — Public accounts, transparent allocation, governance-approved spending.
• Security & audits — Audit reports public; known risks disclosed.
• Development — Open source; roadmap and trade-offs discussed openly.

Governance process

Parameter changes use time-locked stages: proposal → cooling period → execution. This allows the community to react and exit if needed. No single party can change critical parameters unilaterally; changes require broad consensus within protocol bounds.

Responsive

The Boing Network website and documentation are built to be fully responsive across all viewports — from small phones (320px) to large desktops.

Breakpoints

Global breakpoints used across the site:

• 375px — Very small phones: reduced padding, single-column layouts where needed, smaller nav text.
• 480px — Small phones: form inputs full-width, footer and section padding reduced.
• 640px — Phones and narrow tablets: section padding, table font size, stats/pillars single column, docs sidebar stacks.
• 768px — Tablets: header padding, horizontal scroll for wide content.
• 900px+ — Desktop: hero two-column, full nav.

Main website

Landing (home), About, Community, Resources, Documentation, Developer quickstart, and all Network pages (Join Testnet, Bootnodes, Faucet, Status, Single vs multi-node, Quests) use page-wrap-inner and shared layout with responsive padding. Images use max-width: 100%. Tables and code blocks scroll horizontally on small screens when needed. Long URLs and code use word-break: break-word to avoid overflow.

Testnet portal

The testnet environment (Dashboard, Sign in, Register, Set password, hub dashboards, leaderboards) uses the same breakpoints. Portal forms, role cards, and hub content are fluid; inputs and cards never overflow the viewport.

Accessibility

Focus styles (:focus-visible), skip links, and sufficient touch targets are applied site-wide. Reduced-motion preferences disable non-essential animations.

Resources

Site pages

• Landing page — Tokenomics charts, roadmap, ecosystem, innovations.
• Developer quickstart — CLI, SDK, local dev.
• Network status — Block height, validators (when available).
• About — Design philosophy and pillars.
• Community — GitHub, governance, grants.

Repository docs (PDF)

Source: github.com/chiku524/boing.network. Download any document as PDF: