DOCSEARCHbyAlgolia
Submit Docs

Nano Protocol Documentation

repository·main·Indexed 41 days ago

https://github.com/nanocurrency/nano-docs

Technical reference for the Nano protocol, designed for advanced users, node operators, and developers. Includes comprehensive guides on the nano_node command-line interface, daemon configuration, debug flags, and the JSON-RPC protocol for node and wallet interaction.

Tokens
78.5K
Snippets
250
Records
390
Agent score
50%

What's inside Nano

  1. Explore Nano Node and Protocol Documentation

    main

    The Nano documentation is organized into several key areas depending on your goal:

    • High-level Overview: Use What is Nano? to understand Nano's suitability as a global digital currency.
    • Node Operation: Use Running a Node to learn how to set up a node to manage the ledger, publish blocks, and participate in consensus.
    • Building Services: Use Integration Guides for practical instructions on building wallets, payment systems, and other network services.
    • Deep Technical Specs:
    • Interaction & Control: Use Commands to find the exhaustive list of RPC and CLI methods for interacting with the node.
    • Development & Contributions: Use Core Development to learn how to contribute to the core code or protocol.
    • Reference: Use the Glossary for ecosystem terms and Releases for version history and upcoming features.

  3. Use the Nano RPC Protocol

    main

    The Nano RPC protocol allows interaction with a Nano node using JSON-RPC over HTTP. All requests must be sent as HTTP POST requests containing a JSON payload.

    RPC commands are categorized into several functional groups:

    • Node RPCs: Used for interacting directly with the node and the ledger.
    • Wallet RPCs: Used for interacting with the built-in node wallet (Note: This wallet is recommended for development and testing only).
    • Unit Conversion RPCs: Used for converting between different denominations and raw.
    • Deprecated RPCs: Commands that are no longer recommended for use.
    // Example structure of an RPC request
{
  "command": "account_balance",
  "account": "nano_1abc..."
}

  4. Nano community discussion channels

    main

    Use the following channels to discuss code changes, protocol design, and ideas:

    • GitHub: Best for persisting technical discussions related to specific issues or Pull Requests.
    • Discord: For live chat. Join at https://chat.nano.org and use the #protocol and #development channels.
    • Forum: For high-level technical discussions and exploring ideas before implementation. Use the Protocol Design and Development categories at https://forum.nano.org.

    Proposing New Ideas

    There is currently no formal proposal process. To propose a new idea:

    1. Discuss it on the Forum first to gather community feedback.
    2. Once the concept is validated, submit it via GitHub Issues.

  6. Understand Nano attack vectors and mitigations

    main

    The Nano protocol (formerly RaiBlocks) implements several mechanisms to defend against common decentralized network attacks:

    • Block Gap Synchronization (Network Amplification): To prevent DoS attacks where malicious blocks trigger unnecessary resyncs, nodes wait for a threshold of votes before initiating a connection to a bootstrap node. If a block lacks sufficient votes, it is treated as junk.
    • Transaction Flooding: While the lack of fees could allow network saturation, the required Proof-of-Work (PoW) for each transaction limits the rate of attack. Additionally, non-historical nodes can prune old transactions to manage storage.
    • Sybil Attack: Since voting weight is tied to account balance rather than node count, creating multiple nodes on a single machine provides no advantage to an attacker.
    • Penny-Spend Attack: To prevent storage exhaustion from infinitesimal transactions, nodes can prune accounts based on statistical metrics. The protocol is optimized for minimal storage (approx. 128B per account including indexing).
    • Precomputed PoW Attack: Attackers may pre-calculate sequential blocks to flood the network. Mitigation involves transaction rate-limiting.
    • >50% Attack: An attacker gaining >50% voting strength could disrupt consensus. Defenses include:
      • Economic Incentive: Voting weight is tied to balance; attacking the system destroys the attacker's own investment.
      • Representative Voting: Users can name representatives to vote on their behalf, increasing network resiliency through diversity.
      • Fork Policy: Nodes can implement policies on how to interact with forked blocks to avoid being caught in an attack.
    • Bootstrap Poisoning: To prevent attackers from feeding old, manipulated network states to new nodes, nodes can be paired with an initial database of known-good block heads.

  7. Implement External Private Key Management

    main

    For robust systems, manage private keys externally rather than storing them in the nano_node. In this architecture, the node operator manages a private database of keys and uses the nano_node only to:

    1. Find receivable blocks for an account.
    2. Sign transactions (or implement signing locally).
    3. Broadcast signed transactions to the network.

    Note: WALLET_IDs are not used in this setup because keys are not stored in the node.

  8. The Election lifecycle and states

    main

    An election is created when a block is processed to tally vote weight and ensure consensus.

    States:

    1. passive: Waiting for votes.
    2. active: Entered after 5 seconds if unconfirmed; triggers vote requests to nodes.
    3. broadcasting: Entered after active_request_count_min rounds of requests if still unconfirmed; publishes the block to PR nodes to ensure propagation.
    4. confirmed: Reached when the winning hash has node.online_reps.delta more weight than any competing fork. The election is then passed to the confirmation height processor.
    5. expired_unconfirmed: If an election lasts longer than 5 minutes without confirmation, it is removed.

    Post-Confirmation: An election can remain in the active container for up to confirmed_duration_factor to continue processing and republishing votes before being removed.

  9. Understand Transaction States: Receivable and Confirmed

    main

    Understanding the lifecycle of a transaction is critical for developers:

    • Confirmation: A network-level decision occurring when a block gathers enough votes to pass quorum. Confirmed sends are irreversible (fully-settled).
    • Receivable: A state where a block sending funds has been confirmed by the network, but the recipient has not yet published a corresponding receive block.
    • Note: While a 'send' is confirmed immediately, the receiver must publish a 'receive' block before they can spend those funds again.

  11. How the block-lattice ledger structure works

    main

    Unlike traditional blockchains where all transactions are bundled into a single chain, RaiBlocks uses a block-lattice data structure. In this model, every account maintains its own independent chain of blocks.

    This converts the distributed ledger from a single shared data structure into a collection of non-shared ones, where consensus is achieved through balance-weighted votes on conflicting transactions rather than a single global chain.

  12. Understand ledger pruning behavior

    main

    Pruning is handled periodically by nano::node::ongoing_ledger_pruning ().

    Requirements and Behavior:

    • Requires a full ledger to be bootstrapped first.
    • An account frontier must be confirmed before it can be pruned.
    • Hashes of pruned blocks are stored in the pruned database to prevent the node from attempting to bootstrap those old blocks again.
    • Note: Pending blocks cannot currently be pruned.