Boing Network Documentation
Overview
Boing Network is an independent Layer 1 built from first principles, where quality is enforced by the protocol. It is independent of other chains and designed for sustainable value, uncapped supply with floor-triggered rebalancing, and 100% transparent governance and tokenomics.
Pick your path
- 👋 Everyday users — Create a wallet at Boing Express, request testnet BOING at the faucet, then look up your account on Boing Observer. Move liquidity with Boing Finance using Boing Express on Boing L1.
- 🛠️ Developers — Public RPC
https://testnet-rpc.boing.network/. Addresses are 32-byte hex (64 characters), Ed25519 + BLAKE3, not EVM. Start with Getting Started and RPC API. TypeScript:npm install @boing-network/boing-sdk(source under repoboing-sdk/). - 🛰️ Operators — Bootnodes, Fly cluster, and the Worker gateway are documented in the repository
docs/TESTNET.mdanddocs/FLY-IO.md. Upgrading a laptop node does not change the public explorer.
The six pillars
In order: 🔐 Security → ⚡ Scalability → 🌍 Decentralization → 🧬 Authenticity → 🔎 Transparency → ✅ True quality assurance. Protocol + product narrative: Whitepaper (PDF). The written pillars are the SIX-PILLARS PDF (also on /about). Plain-language overview: BOING-NETWORK-ESSENTIALS (PDF). Technical companion: BOING-NETWORK-TECHNICAL-ESSENTIALS (PDF). QA detail: QUALITY-ASSURANCE-NETWORK (PDF).
Recent enhancements & optimizations
Network-wide improvements include: re-insert of failed txs into mempool, RPC methods boing_qaCheck and QA error codes, boing_getBalance / boing_getAccount, native DEX discovery on-chain (boing_listDexPools, boing_listDexTokens, boing_getDexToken; capability names also appear under boing_getNetworkInfo.developer.dex_discovery_methods), unsigned boing_simulateContractCall for calldata dry-runs, six-pillars and essentials documentation, Protocol QA phase in the roadmap. QA pillar enhancements (pre-flight checks, structured errors, public metrics, versioned rule sets, appeal path) are documented in QUALITY-ASSURANCE-NETWORK (PDF). For the full list of implemented and planned enhancements, see DEVELOPMENT-AND-ENHANCEMENTS (PDF).
What this documentation covers
Getting Started — Prerequisites, build, run a node (full or validator), first transaction. Network Overview — Block time, consensus, key facts. Tokenomics — Supply model, fees, staking, waves. Architecture & Features — Native AA, adaptive gas, cross-chain, slashing, governance. RPC API — All JSON-RPC methods, params, and error codes. Operations — CLI, monitoring, troubleshooting, incident response. Roadmap — Phased build status. Testnet — Join the live testnet (bootnodes, faucet, portal). Security — Protocol, network, and operational security. Governance & Transparency — How decisions and parameters are visible and verifiable. Resources — Links to repo, landing page, and other pages.
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
- Independent — Your own stack, built from first principles; 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 when transactions are pending. Blocks are produced only when transactions are present, so a quiet network can sit on the same tip for hours.
- 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
Plain-language overview (allocation, fees, quest/bounty pots, testnet ≠ mainnet claim): BOING-TOKENOMICS-AND-INCENTIVIZED-TESTNET (PDF). Draft tables with Proposed vs Undecided: BOING-INITIAL-TOKENOMICS (PDF). No TGE date is asserted.
Supply model
- Locked (BN-155) — 1 billion BOING genesis / initial supply (
INITIAL_SUPPLY); supply ceiling after genesis is uncapped (not a 1B hard cap). - Decimals — 18 (1 BOING = 1018 base units).
- Emissions — Block rewards continue past 1B under the declining schedule + floor; shipping code does not clamp minting at 1B. Code mints ~70% of each block emission to the proposer.
- Design narrative — Uncapped supply with floor-triggered rebalancing remains the long-form sustainability model in the design plan. No TGE / mainnet calendar date is asserted. Testnet ≠ mainnet claim.
Fee allocation
Proposed design target: 80% validators, 20% treasury (burn optional 0%). Current public testnet runtime: protocol gas defaults to 100% treasury; tips and block emission go to the proposer.
Initial supply allocation (at launch)
Proposed genesis pie (not final — exact buckets still Undecided): Staking 50% · Treasury 20% · Community & Grants 15% · Team & ops 15%. Older marketing charts used ~55 / 30 / 15 without a Team line; see initial tokenomics draft. Staking is topped up by ongoing block emissions (uncapped after the 1B genesis).
Floor-triggered waves
Genesis — 1B initial supply. Ongoing — Validators and treasury earn from fees; emissions continue uncapped under the declining schedule. Floor — When circulating supply reaches the defined floor, the protocol can trigger a rebalance. New wave — A new wave of tokens may be minted (size and destination set by protocol/governance) to restore balance. All parameters (floor, wave size, trigger) are intended to be on-chain and transparent.
Emission schedule (block rewards)
Proposed: Year 1 ~8% of the 1B base, then decay ≈ 0.85 per year; Year 10+ targets a 1% floor (or 0% if fees suffice). Formula: emission_year_n = emission_year_1 × (decay)^(n-1). Shipping mint path credits ~70% of the year-N emission to the round proposer.
FAQ — Why uncapped max supply?
Uncapped ≠ free print. Genesis is fixed at 1B BOING; growth after that follows a documented decaying emission schedule (~8% Y1 → ~1% floor; ~70% proposer share in shipping code). Hard caps can starve long-run validator security when fees stay intentionally low (Solana-like small base gas). Raising a hard cap later is usually a messy crisis hard-fork—an open schedule is the more honest security budget. Markets price circulating supply and the inflation path (order of ~1.3B by Y10 under the Proposed sketch), not a marketing max.
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 fields rpc_surface and developer.dex_discovery_methods (stable names for the L1 DEX directory RPC trio).
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.
| Method | Params (summary) | Notes |
|---|---|---|
boing_chainHeight | [] | Committed tip height (u64). |
boing_clientVersion | [] | e.g. boing-node/0.1.0 |
boing_rpcSupportedMethods | [] | Sorted list of boing_* names. |
boing_health | [] | Liveness, head_height, optional chain_id, rpc_surface, rpc_metrics. |
boing_getSyncState | [] | head_height, finalized_height, latest_block_hash. |
boing_getNetworkInfo | [] | Chain metadata, chain_native, developer, end_user, rpc.not_available, … |
boing_getRpcMethodCatalog | [] | Embedded catalog for tooling. |
boing_getRpcOpenApi | [] | OpenAPI 3.1 for HTTP surface. |
boing_getBalance | [hex_account_id] | Result: balance (u128 decimal string). |
boing_getAccount | [hex_account_id] | balance, nonce, stake. |
boing_getBlockByHeight | [height] or [height, include_receipts] | Block or null. |
boing_getBlockByHash | [hex_hash] or [hex_hash, include_receipts] | Block or null. |
boing_getTransactionReceipt | [hex_tx_id] | Receipt or null. |
boing_getLogs | [filter] | Bounded block range + optional address / topics. |
boing_getAccountProof | [hex_account_id] | proof, root, value_hash. |
boing_verifyAccountProof | [hex_proof, hex_state_root] | Result: valid boolean. |
boing_getContractStorage | [hex_contract, hex_key] | Single 32-byte storage word. |
boing_listDexPools | [object] | Paginated CP pools from the on-chain pair directory + reserves (needs factory via env or factory field). See spec. |
boing_listDexTokens | [object] | Paginated tokens derived from registered pools + optional deploy metadata scans. |
boing_getDexToken | [object] | Single token row by id, or null. |
boing_getTokenMetadata | [id] or [object] | Name, symbol, decimals, total supply for any token contract (not only DEX pools); fields the chain does not hold are null. |
boing_listTokens | [object] | Cursor-paginated directory of every known token, ordered by id. |
boing_simulateTransaction | [hex_signed_tx] | Gas, success, suggested_access_list, … |
boing_simulateContractCall | [hex_contract, hex_calldata, sender?, at_block?] | Unsigned calldata dry-run; same result shape as simulate (see spec). |
boing_submitTransaction | [hex_signed_tx] | Success: tx_hash field — current node uses literal "ok" when accepted; track inclusion via receipt / nonce (see spec). |
boing_registerDappMetrics | [hex_contract, hex_owner] | dApp incentive registration. |
boing_submitIntent | [hex_signed_intent] | Returns intent_id. |
boing_qaCheck | [hex_bytecode, …] | Optional: purpose_category, description_hash, asset_name, asset_symbol. |
boing_qaPoolList | [] | Pending QA pool items. |
boing_qaPoolConfig | [] | Pool governance + depth. |
boing_getQaRegistry | [] | Effective QA rule registry. |
boing_qaPoolVote | [tx_hash, voter, vote] | Admin-only votes need the X-Boing-Operator header matching the node's BOING_OPERATOR_RPC_TOKEN; -32057 if missing or unset. |
boing_operatorApplyQaPolicy | [registry_json, pool_json] | Operator-only when token set. |
boing_faucetRequest | [hex_account_id] | Only if node started with faucet enabled (testnet). |
TypeScript client: npm package @boing-network/boing-sdk (createClient; see npm for the latest release) implements these methods with typed results and explainBoingRpcError for QA / pool errors. Do not install unscoped boing-sdk.
Error codes (selected)
| Code | Meaning |
|---|---|
| -32600 | Invalid Request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error (e.g. boing_getLogs result cap) |
| -32000 | Server / transport error |
| -32016 | Rate limit exceeded |
| -32050 | QA: deployment rejected (data.rule_id, data.message) |
| -32051 | QA: pending pool (data.tx_hash) |
| -32052 … -32056 | QA pool state / caps (see spec) |
| -32057 | Operator RPC auth required |
Operations
CLI commands
| Command | Description |
|---|---|
boing init [name] | Scaffold a new dApp project |
boing dev [--port 8545] | Start local dev chain |
boing deploy [path] | Deploy contract or config |
boing metrics register --contract <hex> --owner <hex> | Register contract for dApp incentives |
boing token | Native fungible token: deploy, mint, transfer, balance, approve, allowance |
boing pool | Native constant-product AMM pool: create, add/remove liquidity, swap, quote, reserves, route |
boing validator | Open validator set: register, deregister, unjail, claim-unbond, status |
boing name | Name registry (label.boing): resolve, reverse, check, claim, renew, transfer |
boing iface | Interface registry: deploy, hash, publish and fetch contract interface JSON |
boing qa apply | Operator-only: apply a QA registry / pool config to a node (needs the operator token) |
boing completions <shell> | Shell completions (bash, zsh, fish, powershell, elvish) |
Run boing --help or boing <command> --help for every subcommand and flag.
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_simulateTransactionfirst; check mempool and nonce order. - Method not found — Method names are case-sensitive; most methods expect
paramsas a JSON array (e.g.[]not{}). Exception:boing_listDexPools,boing_listDexTokens,boing_getDexToken,boing_getTokenMetadata, andboing_listTokensaccept a single JSON object or[object]— seedocs/RPC-API-SPEC.md. - Build fails — Try
cargo cleanthencargo 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 — Live (see Join Testnet; iterate toward mainnet).
- Mainnet — Planned.
See the landing page roadmap and the repository BUILD-ROADMAP for details.
Testnet
The public Boing testnet is live for validators and developers ahead of mainnet. Use this site’s Join Testnet, Bootnodes, Faucet, and portal for onboarding; detailed operator flows and release artifacts are in the repository docs/TESTNET.md.
- Bootnodes — Public endpoints to peer with the network.
- Faucet — Test BOING for gas and experimentation (rate-limited per account).
- Incentives - The incentivized testnet is not currently running. We hope to run one in the future; announcements will be posted on our official channels. Portal quests and operator dashboards track participation only.
Monitor network status and repository release tags when upgrading boing-node.
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 — Public RPC, explorer, and operator smoke commands.
- About — Design philosophy and pillars.
- Community — GitHub, governance, grants.
Repository docs (PDF)
Source: github.com/Boing-Network/boing.network. Download any document as PDF:
- WHITEPAPER Protocol and product whitepaper for public testnet (chain 6913). PDF
- SIX-PILLARS Written six pillars — the PDF used on /about. PDF
- BOING-NETWORK-ESSENTIALS Plain-language overview of products and honest testnet limits. PDF
- BOING-NETWORK-TECHNICAL-ESSENTIALS Technical companion: chain id, activations, VM, fees, RPC, DEX, blobs. PDF
- TOKENOMICS & INCENTIVIZED TESTNET Allocation, community pots, and testnet ≠ mainnet claim. PDF
- BOING-INITIAL-TOKENOMICS Draft allocation / emissions / fees — Proposed vs Undecided. PDF
- FEATURES Product and protocol features with activation heights and status. PDF
- QUALITY-ASSURANCE-NETWORK Protocol QA rules, automation, community pool, meme leniency. PDF
- DEVELOPMENT-AND-ENHANCEMENTS SDK, automation, dApp incentives; network-wide enhancements. PDF
- BOING-BLOCKCHAIN-DESIGN-PLAN Design philosophy, tokenomics, decentralization, innovations. PDF
- RUNBOOK Node setup, RPC, CLI, monitoring, incident response. PDF
- RPC-API-SPEC Full JSON-RPC methods, boing_qaCheck, boing_getBalance, errors. PDF
- SECURITY-STANDARDS Protocol, network, operational security; audit and bug bounty. PDF
- BUILD-ROADMAP Build and release roadmap. PDF