├── docs ├── CNAME ├── images │ ├── favicon.png │ ├── epoch-blocks.png │ ├── nano-docs-open-graph.png │ ├── whitepaper │ │ └── balance-lru-prio.png │ ├── nano-prometheus-exporter-architecture.png │ ├── windows-10-build-instructions │ │ ├── debug-arch.jpg │ │ ├── cmake-generator.jpg │ │ ├── set-properties.jpg │ │ ├── startup-project.jpg │ │ └── visual-studio-install.jpg │ ├── nano-logo.svg │ └── mailing-list.svg ├── articles │ └── readme.md ├── snippets │ ├── docker-ipv6-tip.md │ ├── current-build-links-beta.md │ ├── warning-debug-only-command.md │ ├── warning-node-wallet-not-for-prod-use.md │ ├── unconfirmed-information.md │ ├── contributing-code.md │ ├── warning-includes-unconfirmed.md │ ├── current-build-links-all.md │ ├── directory-locations-all.md │ ├── enable-voting.md │ ├── deprecation-info-pending.md │ ├── known-issue-windows-logging-stable.md │ ├── config-node-option-rpc-enable-true.md │ ├── release-details-v28-0.md │ ├── warning-process-sub-type-recommended.md │ ├── warning-external-libraries.md │ ├── directory-locations-main.md │ ├── directory-locations-beta.md │ ├── directory-locations-test.md │ ├── warning-alternative-work-generation-setup-preferred.md │ ├── warning-telemetry-can-be-forged.md │ ├── known-issue-unchecked-keys-rpc-rocksdb.md │ ├── release-details-v18-0.md │ ├── warning-multiple-confirmation-notifications.md │ ├── dedicated-representative-nodes.md │ ├── release-details-v27-1.md │ ├── known-issue-unable-to-find-libboost.md │ ├── config-node-option-rpc-enable-control-false.md │ ├── terms-block-transaction-transfer.md │ ├── warning-only-official-builds-supported.md │ ├── release-details-v23-3.md │ ├── release-details-v22-1.md │ ├── docker-run-command-main.md │ ├── release-details-v25-1.md │ ├── release-details-v27-0.md │ ├── setup-beta-test-testing.md │ ├── docker-run-command-beta.md │ ├── docker-run-command-test.md │ ├── release-details-v26-1.md │ ├── community-links.md │ ├── config-node-option-node-enable-voting-true.md │ ├── release-details-v19-0.md │ ├── release-details-v23-0.md │ ├── release-details-v23-1.md │ ├── warning-docker-limitations.md │ ├── release-details-v21-2.md │ ├── release-details-v21-3.md │ ├── release-details-v24-0.md │ ├── warning-enable-control.md │ ├── warning-unsupported-configuration.md │ ├── release-details-v25-0.md │ ├── release-details-v26-0.md │ ├── release-details-v20-0.md │ ├── toml-config-commands.md │ ├── release-details-v22-0.md │ ├── release-details-v21-1.md │ ├── release-details-v21-0.md │ ├── config-node-option-rpc-enable-control-true.md │ ├── warning-multiple-node-setups.md │ ├── directory-contents.md │ ├── known-issue-macos-too-many-open-files.md │ ├── wip-living-whitepaper.md │ ├── network-details-simple-main.md │ ├── network-details-simple-beta.md │ ├── network-details-simple-test.md │ ├── join-technical-mailing-list.md │ ├── known-issue-peers-stake-reporting.md │ ├── current-build-links-test.md │ ├── security-vulnerability-reporting.md │ ├── warning-security-vulnerability-reporting.md │ ├── hardware-recommendations.md │ ├── network-details.md │ └── current-build-links-main.md ├── javascript │ └── mermaid-loose-security.js ├── releases │ ├── release-v26-0.md │ ├── release-v26-1.md │ ├── release-v21-1.md │ ├── release-v21-2.md │ ├── roadmap.md │ ├── release-v21-3.md │ ├── release-v25-1.md │ ├── release-v22-1.md │ ├── release-v23-1.md │ ├── release-v27-1.md │ ├── release-v23-3.md │ ├── release-v27-0.md │ ├── release-v25-0.md │ └── release-v23-0.md ├── node-implementation │ ├── work.md │ ├── components.md │ ├── database.md │ ├── networking.md │ ├── introduction.md │ ├── blocks.md │ └── voting.md ├── protocol-design │ ├── resource-usage.md │ ├── signing-hashing-and-key-derivation.md │ ├── networking.md │ ├── distribution-and-units.md │ ├── ledger.md │ └── orv-consensus.md ├── running-a-node │ ├── beyond-the-node.md │ ├── test-network.md │ ├── overview.md │ ├── advanced-monitoring.md │ ├── security.md │ ├── voting-as-a-representative.md │ ├── beta-network.md │ └── logging-tracing.md ├── index.md ├── core-development │ ├── overview.md │ ├── code-standards.md │ └── collaboration-process.md ├── living-whitepaper │ └── index.md ├── integration-guides │ └── block-confirmation-tracking.md ├── what-is-nano │ └── overview.md └── stylesheets │ └── extras.css ├── theme-overrides ├── .icons │ └── .svg ├── main.html └── partials │ └── footer.html ├── .gitignore ├── deploy-key.enc ├── requirements.txt ├── .github └── workflows │ ├── build.yml │ ├── deploy.yml │ ├── publish-docker-master.yml │ ├── push-to-staging.yml │ ├── deploy-staging.yml │ ├── publish-docker-pr.yml │ ├── cleanup-docker-untagged.yml │ └── cleanup-docker-pr.yml ├── Dockerfile └── readme.md /docs/CNAME: -------------------------------------------------------------------------------- 1 | docs.nano.org -------------------------------------------------------------------------------- /theme-overrides/.icons/.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site/ 2 | .idea 3 | venv 4 | .cache -------------------------------------------------------------------------------- /deploy-key.enc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/deploy-key.enc -------------------------------------------------------------------------------- /docs/images/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/favicon.png -------------------------------------------------------------------------------- /docs/images/epoch-blocks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/epoch-blocks.png -------------------------------------------------------------------------------- /docs/images/nano-docs-open-graph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/nano-docs-open-graph.png -------------------------------------------------------------------------------- /docs/articles/readme.md: -------------------------------------------------------------------------------- 1 | Please see https://github.com/nanocurrency/nano-docs/issues/555 for details the article management process and list of ideas. -------------------------------------------------------------------------------- /docs/images/whitepaper/balance-lru-prio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/whitepaper/balance-lru-prio.png -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | # Direct dependencies 2 | mkdocs>=1.5 3 | mkdocs-material[imaging]>=9.4 4 | mkdocs-material-extensions>=1.3 5 | mkdocs-redirects>=1.2 6 | -------------------------------------------------------------------------------- /docs/snippets/docker-ipv6-tip.md: -------------------------------------------------------------------------------- 1 | !!! tip 2 | On some systems it may be necessary to replace `127.0.0.1` with IPv6 equivalent of `[::1]` when mapping Docker ports -------------------------------------------------------------------------------- /docs/images/nano-prometheus-exporter-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/nano-prometheus-exporter-architecture.png -------------------------------------------------------------------------------- /docs/javascript/mermaid-loose-security.js: -------------------------------------------------------------------------------- 1 | var mermaid_config = { 2 | startOnLoad:true, 3 | securityLevel:'loose', 4 | }; 5 | 6 | mermaid.initialize(mermaid_config); -------------------------------------------------------------------------------- /docs/images/windows-10-build-instructions/debug-arch.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/windows-10-build-instructions/debug-arch.jpg -------------------------------------------------------------------------------- /docs/snippets/current-build-links-beta.md: -------------------------------------------------------------------------------- 1 | Join the [nano Discord server](https://chat.nano.org) and head to the `#beta-announcements` channel for the latest build details. -------------------------------------------------------------------------------- /docs/images/windows-10-build-instructions/cmake-generator.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/windows-10-build-instructions/cmake-generator.jpg -------------------------------------------------------------------------------- /docs/images/windows-10-build-instructions/set-properties.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/windows-10-build-instructions/set-properties.jpg -------------------------------------------------------------------------------- /docs/images/windows-10-build-instructions/startup-project.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/windows-10-build-instructions/startup-project.jpg -------------------------------------------------------------------------------- /docs/images/windows-10-build-instructions/visual-studio-install.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/nano-docs/HEAD/docs/images/windows-10-build-instructions/visual-studio-install.jpg -------------------------------------------------------------------------------- /docs/snippets/warning-debug-only-command.md: -------------------------------------------------------------------------------- 1 | !!! warning "Debug purposes only" 2 | This call is for internal diagnostics/debug purposes only. Do not rely on this interface being stable and do not use in a production system. -------------------------------------------------------------------------------- /docs/snippets/warning-node-wallet-not-for-prod-use.md: -------------------------------------------------------------------------------- 1 | !!! warning "Node wallet not for production use" 2 | The node wallet is not supported for use in production environments. Use third-party or custom key management for production applications. -------------------------------------------------------------------------------- /docs/snippets/unconfirmed-information.md: -------------------------------------------------------------------------------- 1 | !!! info "Unconfirmed information" 2 | This call returns information that may be based on unconfirmed blocks. These details should not be relied on for any process or integration that requires confirmed blocks. -------------------------------------------------------------------------------- /docs/releases/release-v26-0.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V26.0 nano node 2 | description: Details of the V26.0 nano node release. 3 | 4 | # V26.0 5 | 6 | --8<-- "release-details-v26-0.md" 7 | 8 | --- 9 | 10 | --8<-- "current-build-links-main.md" 11 | -------------------------------------------------------------------------------- /docs/snippets/contributing-code.md: -------------------------------------------------------------------------------- 1 | !!! tip "Contributing to the code" 2 | If you are interested in helping develop the C++ based Nano node we will help you out! Check out our details on [contributing code to the Nano node](/node-implementation/contributing) to get started. -------------------------------------------------------------------------------- /docs/snippets/warning-includes-unconfirmed.md: -------------------------------------------------------------------------------- 1 | !!! warning "Includes unconfirmed blocks" 2 | This call may return results that include unconfirmed blocks, so it should not be used in any processes or integrations requiring only details from blocks confirmed by the network. -------------------------------------------------------------------------------- /docs/snippets/current-build-links-all.md: -------------------------------------------------------------------------------- 1 | === "Test network" 2 | 3 | --8<-- "current-build-links-test.md" 4 | 5 | === "Main network" 6 | 7 | --8<-- "current-build-links-main.md" 8 | 9 | === "Beta network" 10 | 11 | --8<-- "current-build-links-beta.md" -------------------------------------------------------------------------------- /docs/snippets/directory-locations-all.md: -------------------------------------------------------------------------------- 1 | === "Test network" 2 | 3 | --8<-- "directory-locations-test.md" 4 | 5 | === "Main network" 6 | 7 | --8<-- "directory-locations-main.md" 8 | 9 | === "Beta network" 10 | 11 | --8<-- "directory-locations-beta.md" -------------------------------------------------------------------------------- /docs/releases/release-v26-1.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V26.1 nano node 2 | description: Details of the V26.1 nano node. 3 | 4 | # V26.1 5 | 6 | --8<-- "release-details-v26-1.md" 7 | 8 | --- 9 | 10 | ## Builds and commands 11 | 12 | --8<-- "current-build-links-main.md" 13 | -------------------------------------------------------------------------------- /docs/snippets/enable-voting.md: -------------------------------------------------------------------------------- 1 | !!! tip "Enable Voting" 2 | When setting up a new node, voting is disabled by default in the configuration file and must be manually enabled in order to participate in consensus. See [enable_voting configuration option](/running-a-node/configuration/#nodeenable_voting) for more details. -------------------------------------------------------------------------------- /docs/snippets/deprecation-info-pending.md: -------------------------------------------------------------------------------- 1 | !!! info "" 2 | The term `pending` was deprecated in favor of [`receivable`](/glossary/#receivable). For compatibility reasons both terms are still available for many calls and in responses. For more details see: https://docs.nano.org/releases/release-v24-0/#pendingreceivable-term-rpc-updates. -------------------------------------------------------------------------------- /docs/snippets/known-issue-windows-logging-stable.md: -------------------------------------------------------------------------------- 1 | ??? warning "Known Issue Windows V21: Crash when using config `node.logging.stable_log_filename`" 2 | Setting `node.logging.stable_log_filename` configuration option to `true` results in a node crash on Windows in V21.0 and V21.1, after a node restart. This must be set to `false`. 3 | -------------------------------------------------------------------------------- /docs/snippets/config-node-option-rpc-enable-true.md: -------------------------------------------------------------------------------- 1 | #### rpc.enable 2 | To enable communication via RPC, set this configuration option in the [`config-node.toml`](../running-a-node/configuration.md#configuration-file-locations) file. 3 | 4 | ```toml 5 | [rpc] 6 | 7 | # Enable or disable RPC 8 | # type:bool 9 | enable = true 10 | ``` -------------------------------------------------------------------------------- /docs/snippets/release-details-v28-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 28.0 | TBD | TBD | TBD | | Release - [Milestone](https://github.com/nanocurrency/nano-node/milestone/34) - Changelog | 4 | -------------------------------------------------------------------------------- /docs/snippets/warning-process-sub-type-recommended.md: -------------------------------------------------------------------------------- 1 | !!! warning "Including `subtype` in `process` RPC calls highly recommended" 2 | In order to avoid potential incorrect sends **including the optional `subtype` parameter on all [`process`](/commands/rpc-protocol/#process) RPC calls is highly recommended**. In the next version of the RPC this parameter will be required. -------------------------------------------------------------------------------- /docs/snippets/warning-external-libraries.md: -------------------------------------------------------------------------------- 1 | !!! warning "External libraries, review before using" 2 | The linked resources below contain code dealing with private key management and/or execution of transactions. The Nano Foundation does not control this code, does not endorse it and is not responsible for its use. Use of this code requires review and is at your own discretion. -------------------------------------------------------------------------------- /docs/snippets/directory-locations-main.md: -------------------------------------------------------------------------------- 1 | | **OS/Build** | **Location** | 2 | |----------------|--------------| 3 | | Windows | `C:\Users\\AppData\Local\Nano\` | 4 | | macOS | `/Users//Library/Nano/ ` | 5 | | Linux | `/home//Nano/ ` | 6 | | Docker | As defined by the `-v` flag in the `docker run` command | 7 | | .deb/rpm | `/var/nanocurrency/Nano` | 8 | -------------------------------------------------------------------------------- /docs/releases/release-v21-1.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V21.1 nano node 2 | description: Details of the V21.1 nano node release including upgrade notices, major features, API changes and more 3 | 4 | # V21.1 5 | 6 | --8<-- "release-details-v21-1.md" 7 | 8 | !!! success "No special upgrade considerations" 9 | V21.1 is a service release which doesn't require any special upgrade considerations when upgrading from V21.0. -------------------------------------------------------------------------------- /docs/releases/release-v21-2.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V21.2 nano node 2 | description: Details of the V21.2 nano node release including upgrade notices, major features, API changes and more 3 | 4 | # V21.2 5 | 6 | --8<-- "release-details-v21-2.md" 7 | 8 | !!! success "No special upgrade considerations" 9 | V21.2 is a service release which doesn't require any special upgrade considerations when upgrading from V21.0. -------------------------------------------------------------------------------- /docs/snippets/directory-locations-beta.md: -------------------------------------------------------------------------------- 1 | | **OS** | **Location** | 2 | |----------------|--------------| 3 | | Windows | `C:\Users\\AppData\Local\NanoBeta\` | 4 | | macOS | `/Users//Library/NanoBeta/ ` | 5 | | Linux | `/home//NanoBeta/ ` | 6 | | Docker | As defined by the `-v` flag in the `docker run` command | 7 | | .deb/rpm | `/var/nanocurrency/NanoBeta` | -------------------------------------------------------------------------------- /docs/snippets/directory-locations-test.md: -------------------------------------------------------------------------------- 1 | | **OS** | **Location** | 2 | |----------------|--------------| 3 | | Windows | `C:\Users\\AppData\Local\NanoTest\` | 4 | | macOS | `/Users//Library/NanoTest/ ` | 5 | | Linux | `/home//NanoTest/ ` | 6 | | Docker | As defined by the `-v` flag in the `docker run` command | 7 | | .deb/rpm | `/var/nanocurrency/NanoTest` | -------------------------------------------------------------------------------- /docs/snippets/warning-alternative-work-generation-setup-preferred.md: -------------------------------------------------------------------------------- 1 | !!! warning "Alternative work generation setup preferred" 2 | Due to potential performance impacts to nodes participating on the network (voting, staying in sync, etc.), when possible this option should be updated to a value of `0` to turn off local work generation. Please see the [Work Generation guide](/integration-guides/work-generation) for best practices. -------------------------------------------------------------------------------- /docs/snippets/warning-telemetry-can-be-forged.md: -------------------------------------------------------------------------------- 1 | !!! warning "Telemetry can be forged" 2 | Although the telemetry messages are signed by nodes, the data provided by other peers can be forged by malicious nodes so they cannot be guaranteed as accurate. All details in these messages should be used as rough indicators of peer and broad network situations, but not exclusively relied on for any key integration or network activities. -------------------------------------------------------------------------------- /docs/snippets/known-issue-unchecked-keys-rpc-rocksdb.md: -------------------------------------------------------------------------------- 1 | ???info "Known issue with RocksDB: RPC `unchecked_keys` not working properly" 2 | **Issue:** The RPC `unchecked_keys` is returning `0` for all calls when used with the RocksDB backend. This known issue will be resolved in a future release. 3 | 4 | **Solution:** Until the issue is resolved any integrations using this command should remain on the existing LMDB backend -------------------------------------------------------------------------------- /docs/snippets/release-details-v18-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 18.0 | 16 | 13 | 2019-02-21 || [Release](https://github.com/nanocurrency/nano-node/releases/tag/V18.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/7) - [Changelog](https://github.com/nanocurrency/nano-node/compare/V17.1...V18.0) | -------------------------------------------------------------------------------- /docs/snippets/warning-multiple-confirmation-notifications.md: -------------------------------------------------------------------------------- 1 | !!! warning "Multiple notifications for blocks" 2 | Depending on the node setup and sync status, multiple confirmation notifications for the same block hash may be sent by a single tracking mechanism. **In order to prevent potential issues, integrations must track these block hashes externally to the node and prevent any unwanted actions based on multiple notifications.** -------------------------------------------------------------------------------- /docs/snippets/dedicated-representative-nodes.md: -------------------------------------------------------------------------------- 1 | !!! tip "Dedicated Representative nodes recommended" 2 | Due to the resources needed to participate in the voting process, it is recommended that **any node setup as a Representative should be dedicated to generating consensus**. If the resources of the Representative are used for other activities, such as application integrations, it reduces the potential benefit that node brings to the network. 3 | -------------------------------------------------------------------------------- /docs/images/nano-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /docs/releases/roadmap.md: -------------------------------------------------------------------------------- 1 | title: Roadmap 2 | description: The Nano roadmap which is aimed at achieving the mission of allowing Nano to become a global currency. 3 | 4 | # Roadmap 5 | 6 | !!! info "Nano Roadmap moved to GitHub" 7 | Head over to the new [Nano Roadmap GitHub Project](https://github.com/orgs/nanocurrency/projects/27) for a more dynamic and updated view of the upcoming features under research and implementation on the Nano node and protocol. 8 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v27-1.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 27.1 | 21 | 24 | TBD | [V27.1](../releases/release-v27-1.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V27.1) - Milestone - [Changelog](https://github.com/nanocurrency/nano-node/compare/V27.0...V27.1) | 4 | -------------------------------------------------------------------------------- /docs/snippets/known-issue-unable-to-find-libboost.md: -------------------------------------------------------------------------------- 1 | ??? warning "Known Issue Linux V21: 'unable to find libboost'" 2 | If you are on Linux and unable to get V21.0 to start, `unable to find libboost...` https://github.com/nanocurrency/nano-node/releases/download/V21.0/nano-node-V21.0.1-Linux.tar.bz2 has been added to the release artifacts with the correct lib rpath. Please use this if you do not wish to move the lib folder into the bin folder after extraction. -------------------------------------------------------------------------------- /docs/snippets/config-node-option-rpc-enable-control-false.md: -------------------------------------------------------------------------------- 1 | In the [`config-rpc.toml`](../running-a-node/configuration.md#configuration-file-locations) file, you can disable the control commands again by setting `enable_control` back to false. 2 | 3 | ```toml 4 | # Enable or disable control-level requests. 5 | # WARNING: Enabling this gives anyone with RPC access the ability to stop the node and access wallet funds. 6 | # type:bool 7 | enable_control = false 8 | ``` -------------------------------------------------------------------------------- /docs/snippets/terms-block-transaction-transfer.md: -------------------------------------------------------------------------------- 1 | * **block** is the digital encoding of the transaction details. 2 | 3 | * **transaction** is the action of creating and publishing a block to the network. Depending on the type of transaction, the block will have different requirements. 4 | 5 | * **transfer** is the completion of both a send transaction and the corresponding receive transaction, representing the movement of funds which can be sent again by the recipient. -------------------------------------------------------------------------------- /docs/snippets/warning-only-official-builds-supported.md: -------------------------------------------------------------------------------- 1 | !!! warning "Only Official Builds Supported" 2 | * The fastest and most recommended method of installation is through [Docker management](/running-a-node/node-setup) 3 | * Only [official release builds](/integration-guides/build-options#official-release-builds) are recommended and supported for use on the main network 4 | * Builds created from git should be done using the available release tags (`V21.2` etc.) 5 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v23-3.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 23.3 | 18 | 21 | 2022-06-13 | [V23.3](../releases/release-v23-3.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V23.3) - [Changelog](https://github.com/nanocurrency/nano-node/compare/fef94e3601410542a971f945b0f8c238829c3c96...33422f46e3fb46c3086278e2bdc411220133f3e2) | 4 | 5 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v22-1.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 22.1 | 18 | 21 | 2021-06-11 | [V22.1](../releases/release-v22-1.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V22.1) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/24) - [Changelog](https://github.com/nanocurrency/nano-node/compare/853398af...ade6f224) | 4 | 5 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: build 2 | on: pull_request 3 | 4 | jobs: 5 | build: 6 | runs-on: ubuntu-latest 7 | steps: 8 | - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0 9 | - uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 #v4.3.0 10 | with: 11 | python-version: 3.x 12 | - run: pip install -r requirements.txt 13 | - run: mkdocs build --strict 14 | 15 | env: 16 | GH_TOKEN: ${{ secrets.GH_TOKEN }} 17 | -------------------------------------------------------------------------------- /docs/snippets/docker-run-command-main.md: -------------------------------------------------------------------------------- 1 | ``` { .bash .annotate } 2 | docker run --restart=unless-stopped -d \ 3 | -p 7075:7075 \ 4 | -p 127.0.0.1:7076:7076 \ # (1) 5 | -p 127.0.0.1:7078:7078 \ # (2) 6 | -v ${NANO_HOST_DIR}:/root \ 7 | --name ${NANO_NAME} \ 8 | nanocurrency/nano:${NANO_TAG} 9 | ``` 10 | 11 | 1. Port 7076 is optional, but recommended, for querying via [RPC](../commands/rpc-protocol.md) 12 | 2. Port 7078 is optional for connecting via [WebSockets](../integration-guides/websockets.md) -------------------------------------------------------------------------------- /docs/snippets/release-details-v25-1.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 25.1 | 19 | 22 | 2023-06-02 | [V25.1](../releases/release-v25-1.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V25.1) - [Changelog](https://github.com/nanocurrency/nano-node/compare/8dad120507b78f725ccb5ad6147f2ac1631953b4...d710e2934792bf29c44e62edb8c4a6ef372456ba) | 4 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v27-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 27.0 | 21 | 24 | TBD | [V27.0](../releases/release-v27-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V27.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/33) - [Changelog](https://github.com/nanocurrency/nano-node/compare/V26.1...V27.0) | 4 | -------------------------------------------------------------------------------- /docs/snippets/setup-beta-test-testing.md: -------------------------------------------------------------------------------- 1 | !!! info "Setup for testing on beta or test network" 2 | If you are looking to test the latest version of the node ahead of release, check out the [Beta Network](../running-a-node/beta-network.md) and [Test Network](../running-a-node/test-network.md) pages for more details about how to get setup on the appropriate network. Typically general integration and node upgrades are tested on the public test network, while new feature and load testing are conducted on the beta network. -------------------------------------------------------------------------------- /docs/snippets/docker-run-command-beta.md: -------------------------------------------------------------------------------- 1 | ``` { .bash .annotate } 2 | docker run --restart=unless-stopped -d \ 3 | -p 54000:54000 \ 4 | -p 127.0.0.1:55000:55000 \ # (1) 5 | -p 127.0.0.1:57000:57000 \ # (2) 6 | -v ${NANO_HOST_DIR}:/root \ 7 | --name ${NANO_NAME} \ 8 | nanocurrency/nano-beta:${NANO_TAG} 9 | ``` 10 | 11 | 1. Port 55000 is optional, but recommended, for querying via [RPC](../commands/rpc-protocol.md) 12 | 2. Port 57000 is optional for connecting via [WebSockets](../integration-guides/websockets.md) -------------------------------------------------------------------------------- /docs/snippets/docker-run-command-test.md: -------------------------------------------------------------------------------- 1 | ``` { .bash .annotate } 2 | docker run --restart=unless-stopped -d \ 3 | -p 17075:17075 \ 4 | -p 127.0.0.1:17076:17076 \ # (1) 5 | -p 127.0.0.1:17078:17078 \ # (2) 6 | -v ${NANO_HOST_DIR}:/root \ 7 | --name ${NANO_NAME} \ 8 | nanocurrency/nano-test:${NANO_TAG} 9 | ``` 10 | 11 | 1. Port 17076 is optional, but recommended, for querying via [RPC](../commands/rpc-protocol.md) 12 | 2. Port 17078 is optional for connecting via [WebSockets](../integration-guides/websockets.md) -------------------------------------------------------------------------------- /docs/snippets/release-details-v26-1.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 26.1 | 20 | 22 | 2024-02-26 | [V26.1](../releases/release-v26-1.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V26.1) - Milestone - [Changelog](https://github.com/nanocurrency/nano-node/compare/bbbfe92cffe6ba861085c7eb3d21193bc141aaba...66d74ffd86b4beea3c8df3b918e4f1e8e31f2800) | 4 | -------------------------------------------------------------------------------- /docs/snippets/community-links.md: -------------------------------------------------------------------------------- 1 | !!! note "" 2 | [Nano.org](https://nano.org) | [Forum](https://forum.nano.org) | [GitHub](https://github.com/nanocurrency) | [Twitter](https://twitter.com/nano) | [Discord](https://chat.nano.org) | [Reddit](https://reddit.com/r/nanocurrency) | [Medium](https://medium.com/nanocurrency) 3 | 4 | [Facebook](https://facebook.com/nanofoundation) | [LinkedIn](https://www.linkedin.com/company/nano-foundation/) | [YouTube](https://youtube.com/nanocurrency) | [Instagram](https://www.instagram.com/nanocurrency/) -------------------------------------------------------------------------------- /docs/snippets/config-node-option-node-enable-voting-true.md: -------------------------------------------------------------------------------- 1 | #### node.enable_voting 2 | Newly setup nodes have voting disabled by default. In order to participate in network consensus, this value must be updated in the [`config-node.toml`](../running-a-node/configuration.md#configuration-file-locations) file. 3 | 4 | ```toml 5 | [node] 6 | 7 | # Enable or disable voting. Enabling this option requires additional system resources, namely increased CPU, bandwidth and disk usage. 8 | # type:bool 9 | enable_voting = true 10 | ``` -------------------------------------------------------------------------------- /docs/snippets/release-details-v19-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 19.0 | 17 | 14 | 2019-07-11 | [V19.0](../releases/release-v19-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V19.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/9) - [Changelog](https://github.com/nanocurrency/nano-node/compare/V18.0...V19.0) | 4 | 5 | --8<-- "known-issue-macos-too-many-open-files.md" -------------------------------------------------------------------------------- /docs/snippets/release-details-v23-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 23.0 | 18 | 21 | 2022-01-17 | [V23.0](../releases/release-v23-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V23.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/20) - [Changelog](https://github.com/nanocurrency/nano-node/compare/e2232dd7ab961278557d0c41e95278ac85ca7157...a7a44f9e8a23672f66e15804e79560f004995859) | 4 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v23-1.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 23.1 | 18 | 21 | 2022-05-19 | [V23.1](../releases/release-v23-1.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V23.1) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/26) - [Changelog](https://github.com/nanocurrency/nano-node/compare/a7a44f9e8a23672f66e15804e79560f004995859...fef94e3601410542a971f945b0f8c238829c3c96) | 4 | 5 | -------------------------------------------------------------------------------- /docs/snippets/warning-docker-limitations.md: -------------------------------------------------------------------------------- 1 | !!! warning "Docker Limitations" 2 | Although Docker is a great choice for many setups, it is not recommended to run a \*nix container, such as the officially provided one, on a Windows host - there are known issues with handling ports which prevent proper communication with peers. 3 | 4 | If planning to use `ufw` with Docker, note that you may need to [prevent Docker from manipulating iptables](https://docs.docker.com/network/iptables/#prevent-docker-from-manipulating-iptables) to properly manage firewall settings. 5 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM squidfunk/mkdocs-material:9.4.10@sha256:01605a03397a654b74b9de3157f56915d1e075e2d3bd22fcf3fb82c443553c25 2 | 3 | # Set build directory 4 | #WORKDIR /docs 5 | 6 | # Copy files necessary for build 7 | COPY ./ /docs 8 | 9 | RUN \ 10 | pip install --upgrade pip && \ 11 | pip install -r /docs/requirements.txt 12 | 13 | # Set working directory 14 | WORKDIR /docs 15 | 16 | # Expose MkDocs development server port 17 | EXPOSE 8000 18 | 19 | # Start development server by default 20 | ENTRYPOINT ["mkdocs"] 21 | CMD ["serve", "--dev-addr=0.0.0.0:8000"] 22 | -------------------------------------------------------------------------------- /docs/releases/release-v21-3.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V21.3 nano node 2 | description: Details of the V21.3 nano node release including upgrade notices, major features, API changes and more 3 | 4 | # V21.3 5 | 6 | 7 | --8<-- "release-details-v21-3.md" 8 | 9 | !!! success "No special upgrade considerations" 10 | V21.3 is a service release which doesn't require any special upgrade considerations when upgrading from V21.0 or higher. If upgrading from V20.0 or lower, please review the [V21.0 Release Notes](release-v21-0.md) for upgrade notices and other considerations.** -------------------------------------------------------------------------------- /docs/snippets/release-details-v21-2.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 21.2 | 18 | 18 | 2020-09-03 | [V21.2](../releases/release-v21-2.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V21.2) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/21) - [Changelog](https://github.com/nanocurrency/nano-node/compare/9e65cf68664a3bcbe2734fed0b1cb6df264bce58...V21.2) | 4 | 5 | --8<-- "known-issue-macos-too-many-open-files.md" -------------------------------------------------------------------------------- /docs/snippets/release-details-v21-3.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 21.3 | 18 | 18 | 2021-03-18 | [V21.3](../releases/release-v21-3.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V21.3) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/23) - [Changelog](https://github.com/nanocurrency/nano-node/compare/51600739a828d9d43cbefd077bb9f2fde460f1fb...V21.3) | 4 | 5 | --8<-- "known-issue-macos-too-many-open-files.md" -------------------------------------------------------------------------------- /docs/snippets/release-details-v24-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 24.0 | 19 | 21 | 2023-01-19 | [V24.0](../releases/release-v24-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V24.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/25) - [Changelog](https://github.com/nanocurrency/nano-node/compare/941331bdb3ee1314a26dd95df058beb4e22f155a...3d8d7cbe0e719aa26fcbe07a6d169f8979a0562e) | 4 | -------------------------------------------------------------------------------- /docs/snippets/warning-enable-control.md: -------------------------------------------------------------------------------- 1 | !!! danger "Dangerous RPC calls controlled by `enable_control`" 2 | This RPC command/option requires `enable_control` to be enabled within the RPC config file. Enabling this means that anyone with access to the RPC port could potentially [access wallet funds](/commands/rpc-protocol#send), [stop](/commands/rpc-protocol#stop) the node from running and take other dangerous actions. **Use caution when enabling this option, especially with external RPC access available.** For more details see the [Node Security page](/running-a-node/security). -------------------------------------------------------------------------------- /docs/snippets/warning-unsupported-configuration.md: -------------------------------------------------------------------------------- 1 | !!! warning "Unsupported configuration" 2 | * This documentation is intended only for developers of the Nano Node software, and will not result in a supported configuration. End-users are advised to use releases. 3 | * The fastest and most recommended method of installation is through [Docker](/running-a-node/node-setup). 4 | * [Running node as a service](/integration-guides/advanced/#running-nano-as-a-service). 5 | * To manage a node, use [RPC commands](/commands/rpc-protocol/) or the [CLI](/commands/command-line-interface). -------------------------------------------------------------------------------- /docs/snippets/release-details-v25-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 25.0 | 19 | 22 | 2023-05-24 | [V25.0](../releases/release-v25-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V25.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/27) - [Changelog](https://github.com/nanocurrency/nano-node/compare/927d1b9ae2da0c03bdee2403fdff3680c88c6030...8dad120507b78f725ccb5ad6147f2ac1631953b4) | 4 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v26-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 26.0 | 20 | 22 | 2024-01-16 | [V26.0](../releases/release-v26-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V26.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/32) - [Changelog](https://github.com/nanocurrency/nano-node/compare/27820f92647e15149f05a138d6885e93c9c23165...bbbfe92cffe6ba861085c7eb3d21193bc141aaba) | 4 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v20-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 20.0 | 17 | 15 | 2019-11-12 | [V20.0](../releases/release-v20-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V20.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/10) - [Changelog](https://github.com/nanocurrency/nano-node/compare/V19.0...V20.0) | 4 | 5 | --8<-- "known-issue-macos-too-many-open-files.md" 6 | 7 | --8<-- "known-issue-peers-stake-reporting.md" -------------------------------------------------------------------------------- /docs/snippets/toml-config-commands.md: -------------------------------------------------------------------------------- 1 | | **Name** | **Description** | **Generated with** | 2 | |---------|--------------|--------------| 3 | | `config-node.toml` | Node configuration | `nano_node --generate_config node` | 4 | | `config-rpc.toml` | RPC configuration | `nano_node --generate_config rpc` | 5 | | `config-log.toml` | Log configuration | `nano_node --generate_config log` | 6 | | `config-nano-pow-server.toml` | Proof of work server configuration | `nano_pow_server --generate_config` | 7 | | `config-qtwallet.toml` | Qt developer wallet configuration | This file is maintained by the Qt wallet | -------------------------------------------------------------------------------- /docs/snippets/release-details-v22-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 22.0 | 18 | 21 | 2021-05-14 | [V22.0](../releases/release-v22-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V22.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/19) - [Changelog](https://github.com/nanocurrency/nano-node/compare/adc904d8514c1f147b164dabdaf7375ff0c5c729...ef09e55c74cf74d40c95ec11639d85fa2233ad94) | 4 | 5 | --8<-- "known-issue-unchecked-keys-rpc-rocksdb.md" 6 | -------------------------------------------------------------------------------- /docs/snippets/release-details-v21-1.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 21.1 | 18 | 18 | 2020-07-14 | [V21.1](../releases/release-v21-1.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V21.1) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/21) - [Changelog](https://github.com/nanocurrency/nano-node/compare/4631c10c0eb67b0c62328a7ed8cef5f3169633f9...V21.1) | 4 | 5 | --8<-- "known-issue-macos-too-many-open-files.md" 6 | 7 | --8<-- "known-issue-windows-logging-stable.md" -------------------------------------------------------------------------------- /docs/snippets/release-details-v21-0.md: -------------------------------------------------------------------------------- 1 | | Node | Protocol | Database | Release Date | Release Notes | GitHub Links | 2 | | | | | | | | 3 | | 21.0 | 18 | 18 | 2020-06-16 | [V21.0](../releases/release-v21-0.md) | [Release](https://github.com/nanocurrency/nano-node/releases/tag/V21.0) - [Milestone](https://github.com/nanocurrency/nano-node/milestone/18) - [Changelog](https://github.com/nanocurrency/nano-node/compare/V20.0...V21.0) | 4 | 5 | --8<-- "known-issue-macos-too-many-open-files.md" 6 | 7 | --8<-- "known-issue-unable-to-find-libboost.md" 8 | 9 | --8<-- "known-issue-windows-logging-stable.md" -------------------------------------------------------------------------------- /docs/node-implementation/work.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Work 2 | description: Explore how work generation and management has been implemented in the nano node implementation 3 | 4 | # Node Implementation - Work 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## OpenCL implementation 9 | 10 | --- 11 | 12 | ## Prioritization 13 | 14 | --- 15 | 16 | ## Work re-generation 17 | 18 | --- 19 | 20 | 21 | Existing whitepaper sections related to this page: 22 | 23 | * [Implementation](../whitepaper/english.md#implementation) 24 | 25 | Other content related to this page: 26 | 27 | * [Work Generation guide](../integration-guides/work-generation.md) -------------------------------------------------------------------------------- /docs/snippets/config-node-option-rpc-enable-control-true.md: -------------------------------------------------------------------------------- 1 | This configuration option, which is needed for certain sensitive RPC calls such as those for creating wallets and accounts, is set in the [`config-rpc.toml`](../running-a-node/configuration.md#configuration-file-locations) file. Please make sure you are aware of the sensitive RPC calls opened up by enabling this option (detailed in the [configuration guide](../running-a-node/configuration.md#enable_control)). 2 | 3 | ```toml 4 | # Enable or disable control-level requests. 5 | # WARNING: Enabling this gives anyone with RPC access the ability to stop the node and access wallet funds. 6 | # type:bool 7 | enable_control = true 8 | ``` -------------------------------------------------------------------------------- /docs/node-implementation/components.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Components 2 | description: A breakdown of the various components making up the nano node implementation 3 | 4 | # Node Implementation - Components 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Overview (diagram) 9 | 10 | --- 11 | 12 | ## Node 13 | 14 | ### Ledger 15 | 16 | --- 17 | 18 | ## Node wallet (dev only) 19 | 20 | --- 21 | 22 | ## Work generation 23 | 24 | --- 25 | 26 | ## Communications 27 | 28 | ### RPC server 29 | 30 | ### IPC 31 | 32 | ### CLI 33 | 34 | ### WebSockets 35 | 36 | --- 37 | 38 | Existing whitepaper sections related to this page: 39 | 40 | * [Implementation](/whitepaper/english/#implementation) -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy 2 | on: 3 | push: 4 | branches: 5 | - main 6 | jobs: 7 | deploy: 8 | runs-on: ubuntu-latest 9 | env: 10 | PRODUCTION: TRUE 11 | steps: 12 | - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0 13 | - uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 #v4.3.0 14 | with: 15 | python-version: 3.x 16 | - uses: actions/cache@9b0c1fce7a93df8e3bb8926b0d6e9d89e92f20a7 #v3 17 | with: 18 | key: ${{ github.ref }} 19 | path: .cache 20 | - run: pip install -r requirements.txt 21 | - run: mkdocs gh-deploy --force 22 | env: 23 | GH_TOKEN: ${{ secrets.GH_TOKEN }} 24 | -------------------------------------------------------------------------------- /docs/snippets/warning-multiple-node-setups.md: -------------------------------------------------------------------------------- 1 | !!! warning "Warning - Multiple Node Setups" 2 | **Never** use the same seed on multiple running nano node instances at the same time. 3 | 4 | * Multiple nano nodes using the same seed can result in network race conditions that degrade performance for your personal accounts. 5 | * In addition, publishing transactions from two nodes with the same account at the same time may cause an account fork which requires a slower representative voting process. 6 | * Similarly, if you are running a representative account on multiple nodes, they may publish conflicting votes, causing your representative to be ignored by the network. 7 | * Performance degradation in enterprise environments may be significant. -------------------------------------------------------------------------------- /.github/workflows/publish-docker-master.yml: -------------------------------------------------------------------------------- 1 | name: publish-docker-master 2 | on: 3 | push: 4 | branches: 5 | - main 6 | 7 | jobs: 8 | build_publish: 9 | runs-on: ubuntu-latest 10 | env: 11 | PRODUCTION: TRUE 12 | steps: 13 | - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0 14 | 15 | # Build and test Docker image 16 | - run: | 17 | echo ${{ secrets.GHCR_TOKEN }} | docker login ghcr.io -u nanocurrency --password-stdin 18 | docker pull squidfunk/mkdocs-material:9.4.10@sha256:01605a03397a654b74b9de3157f56915d1e075e2d3bd22fcf3fb82c443553c25 19 | docker build -t ghcr.io/nanocurrency/nano-docs:latest . 20 | docker push ghcr.io/nanocurrency/nano-docs:latest 21 | -------------------------------------------------------------------------------- /.github/workflows/push-to-staging.yml: -------------------------------------------------------------------------------- 1 | name: push-to-staging 2 | on: 3 | workflow_dispatch: 4 | inputs: 5 | branch: 6 | description: "nano-docs branch to push to staging" 7 | default: "staging" 8 | required: true 9 | 10 | jobs: 11 | push: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - name: push 15 | uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0 16 | with: 17 | fetch-depth: 0 18 | ref: ${{ github.event.inputs.branch }} 19 | token: ${{ secrets.GH_TOKEN }} 20 | - run: | 21 | git remote add nano-docs-staging https://github.com/nanocurrency/nano-docs-staging.git 22 | git push nano-docs-staging ${{ github.event.inputs.branch }}:staging -------------------------------------------------------------------------------- /docs/node-implementation/database.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Database 2 | description: Learn how the ledger is managed in the various tables and backend database options on the nano node 3 | 4 | # Node Implementation - Database 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Ledger 9 | 10 | ### Blocks 11 | 12 | ### Pending blocks 13 | 14 | ### Accounts 15 | 16 | ### Caching 17 | 18 | --- 19 | 20 | ## Block cementing 21 | 22 | --- 23 | 24 | ## Database backends 25 | 26 | ### LMDB 27 | 28 | ### RocksDB 29 | 30 | --- 31 | 32 | Existing whitepaper sections related to this page: 33 | 34 | * [Implementation](/whitepaper/english/#implementation) 35 | 36 | Other content related to this page: 37 | 38 | * [Ledger Management guide](../running-a-node/ledger-management.md) -------------------------------------------------------------------------------- /docs/node-implementation/networking.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Networking 2 | description: Details of networking setup design for the nano node 3 | 4 | # Node Implementation - Networking 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Peering process 9 | 10 | Initial peering pulls the IP addresses and domains from the `node.preconfigured_peers` setting in `config-node.toml` file. The default domain of `peering.nano.org` is included, which contains a list of known nodes of high trust, availability and performance - mostly nodes maintained by the Nano Foundation. Due to the [peering process defined by the protocol](../protocol-design/networking.md#peering-process), this initial list is quickly expanded to discovery of the full network via random peer IP sharing on keepalives. -------------------------------------------------------------------------------- /docs/snippets/directory-contents.md: -------------------------------------------------------------------------------- 1 | The Nano directory contains: 2 | 3 | - Node wallet files (`wallets.ldb`, `wallets.ldb-lock`) 4 | - [Configuration files](../running-a-node/configuration.md#configuration-file-locations) 5 | - [Log files](/running-a-node/troubleshooting/#log-files) 6 | - Ledger files (`data.ldb` and `data.ldb-lock` for default LMDB, or `rocksdb` directory with files for optional [RocksDB backend](../running-a-node/ledger-management.md#rocksdb-ledger-backend)) 7 | - Directory for wallet backups (`backup`) 8 | 9 | !!! warning "Protect wallet and backup files" 10 | The built-in node wallet is for use in development and testing only. Those using it should take care in protecting access to the `wallets.ldb` file and backup files, whether encrypted or not, for added security. 11 | -------------------------------------------------------------------------------- /docs/snippets/known-issue-macos-too-many-open-files.md: -------------------------------------------------------------------------------- 1 | ??? info "Known Issue V19+: 'Too many open files'" 2 | 3 | * **Issue:** The following error, or a similar one, can be seen when attempting to run a full node on some versions of macOS, Linux and possibly other operating systems. This is most common when using the built-in Qt wallet or other GUI-based wallets: "Exception while running wallet: open: Too many open files" or other errors containing "Too many open files". This is due to some systems having a very low default file descriptor limit and V19.0+ uses more of them after the move to TCP. 4 | 5 | * **Solution:** Increasing the file limits is needed to resolve this. See [this known issue](../integration-guides/advanced.md#known-issues) for more details on resolution. 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /.github/workflows/deploy-staging.yml: -------------------------------------------------------------------------------- 1 | name: deploy 2 | on: 3 | push: 4 | branches: 5 | - staging 6 | jobs: 7 | deploy: 8 | runs-on: ubuntu-latest 9 | env: 10 | PRODUCTION: TRUE 11 | if: github.repository == 'nanocurrency/nano-docs-staging' 12 | steps: 13 | - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0 14 | - uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 #v4.3.0 15 | with: 16 | python-version: 3.x 17 | - uses: actions/cache@9b0c1fce7a93df8e3bb8926b0d6e9d89e92f20a7 #v3 18 | with: 19 | key: ${{ github.ref }} 20 | path: .cache 21 | - run: pip install -r requirements.txt 22 | - run: mkdocs gh-deploy --force 23 | env: 24 | GH_TOKEN: ${{ secrets.GH_TOKEN }} 25 | -------------------------------------------------------------------------------- /.github/workflows/publish-docker-pr.yml: -------------------------------------------------------------------------------- 1 | name: publish-docker-pr 2 | on: pull_request 3 | 4 | env: 5 | PR_NUMBER: ${{ github.event.number }} 6 | 7 | jobs: 8 | build_publish: 9 | runs-on: ubuntu-latest 10 | env: 11 | PRODUCTION: TRUE 12 | steps: 13 | - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0 14 | 15 | # Build and test Docker image 16 | - run: | 17 | echo ${{ secrets.GHCR_TOKEN }} | docker login ghcr.io -u nanocurrency --password-stdin 18 | docker pull squidfunk/mkdocs-material:9.4.10@sha256:01605a03397a654b74b9de3157f56915d1e075e2d3bd22fcf3fb82c443553c25 19 | docker build -t ghcr.io/nanocurrency/nano-docs:pr-${{ env.PR_NUMBER }} . 20 | docker push ghcr.io/nanocurrency/nano-docs:pr-${{ env.PR_NUMBER }} 21 | -------------------------------------------------------------------------------- /docs/snippets/wip-living-whitepaper.md: -------------------------------------------------------------------------------- 1 | ??? info "Part of work in progress Living Whitepaper" 2 | This page is part of the Living Whitepaper revisions currently underway to replace the original static whitepaper. These efforts include the [Protocol Design](/protocol-design/introduction) and [Node Implementation](/node-implementation/introduction) sections of the docs, which will cover and expand on details and topics covered in the [original whitepaper](/whitepaper/english). 3 | 4 | See the bottom of the page for related whitepaper sections and other related details. Some of the sections and headers on this page may be in draft form or just suggestions/framework for later consideration. If you are interested in helping with revisions please connect with us on the `#documentation` channel on our [Discord server](https://chat.nano.org). -------------------------------------------------------------------------------- /docs/releases/release-v25-1.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V25.1 nano node 2 | description: Details of the V25.1 nano node release including upgrade notices. 3 | 4 | # V25.1 5 | 6 | --8<-- "release-details-v25-1.md" 7 | 8 | ## Upgrade notices 9 | 10 | If you are coming from V25.0, there are no special considerations when upgrading to V25.1. If you are upgrading from previous versions, please check for the possible RPC breaking changes on [V25.0](release-v25-0.md#minor-rpc-breaking-changes). 11 | 12 | All nodes are encouraged to upgrade to V25.1, including exchanges. 13 | 14 | ## Fixes 15 | 16 | * Fixes builds for Windows and RedHat Linux variants. 17 | * Fixes an issue with the “process” RPC which could hang in some circumstances. 18 | 19 | --- 20 | 21 | ## Builds and commands 22 | 23 | --8<-- "current-build-links-main.md" 24 | -------------------------------------------------------------------------------- /docs/snippets/network-details-simple-main.md: -------------------------------------------------------------------------------- 1 | | Port | Protocol | Required? | Purpose | 2 | |-------------|----------|------------------|---------| 3 | | 7075 | TCP | Yes, open to all traffic | For [live network](/glossary#live-network) activity and [bootstrap network](/glossary#bootstrap-network) activity. | 4 | | 7076 | TCP | No, recommended | For communication with RPC server. **Do not expose this outside of your production environment. Anyone with access to this port can control your node's RPC.** | 5 | | 7077 | TCP | No, optional | For communication via IPC (advanced). See [IPC integration guide](../integration-guides/ipc-integration.md) for more details. | 6 | | 7078 | TCP | No, optional | For communication with [websocket server](/integration-guides/websockets). Depending on configuration, data throughput can be very high. | -------------------------------------------------------------------------------- /docs/snippets/network-details-simple-beta.md: -------------------------------------------------------------------------------- 1 | | Port | Protocol | Required? | Purpose | 2 | |-------------|----------|------------------|---------| 3 | | 54000 | TCP | Yes, open to all traffic | For [live network](/glossary#live-network) activity and [bootstrap network](/glossary#bootstrap-network) activity. | 4 | | 55000 | TCP | No, recommended | For communication with RPC server. **Do not expose this outside of your production environment. Anyone with access to this port can control your node's RPC.** | 5 | | 56000 | TCP | No, optional | For communication via IPC (advanced). See [IPC integration guide](../integration-guides/ipc-integration.md) for more details. | 6 | | 57000 | TCP | No, optional | For communication with [websocket server](/integration-guides/websockets). Depending on configuration, data throughput can be very high. | -------------------------------------------------------------------------------- /docs/snippets/network-details-simple-test.md: -------------------------------------------------------------------------------- 1 | | Port | Protocol | Required? | Purpose | 2 | |-------------|----------|------------------|---------| 3 | | 17075 | TCP | Yes, open to all traffic | For [live network](/glossary#live-network) activity and [bootstrap network](/glossary#bootstrap-network) activity. | 4 | | 17076 | TCP | No, recommended | For communication with RPC server. **Do not expose this outside of your production environment. Anyone with access to this port can control your node's RPC.** | 5 | | 17077 | TCP | No, optional | For communication via IPC (advanced). See [IPC integration guide](../integration-guides/ipc-integration.md) for more details. | 6 | | 17078 | TCP | No, optional | For communication with [websocket server](/integration-guides/websockets). Depending on configuration, data throughput can be very high. | -------------------------------------------------------------------------------- /docs/snippets/join-technical-mailing-list.md: -------------------------------------------------------------------------------- 1 | !!! info "" 2 |
3 |
4 |

Technical Update Mailing List

 5 |
Sign up for email updates on the latest protocol/node releases and other technical details including network upgrades.
6 | Join Mailing List 7 |
8 |
9 |
10 | Join Technical Updates Mailing List 11 |
12 |
13 |
14 | -------------------------------------------------------------------------------- /docs/snippets/known-issue-peers-stake-reporting.md: -------------------------------------------------------------------------------- 1 | ??? warning "Known Issue V20: Peers stake reporting inaccurate (Windows only)" 2 | 3 | * **Issue:** For Windows builds only, when calling [confirmation_quorum RPC](/commands/rpc-protocol/#confirmation_quorum) the `peers_stake_total` amount returned may be inaccurate, returning a range from the correct full peer stake amount down to 0. 4 | 5 | * **Solution:** A solution to the issue has been found and as this is a reporting issue only, the fix will be included in the next released version. For those manually building the node, patching the [fix pull request](https://github.com/nanocurrency/nano-node/pull/2405) onto the [V20.0 tag](https://github.com/nanocurrency/nano-node/tree/V20.0) can resolve the issue now. Or alternatively, building on the V20.0 tag with `RelWithDebInfo` option, see [Build Instructions for Windows](/integration-guides/build-options/#setup). 6 | -------------------------------------------------------------------------------- /docs/snippets/current-build-links-test.md: -------------------------------------------------------------------------------- 1 | | OS | Download link/command | 2 | |---------------------|------------------------------------------------------------------| 3 | | Universal Linux | https://repo.nano.org/test/binaries/nano-node-V27.1-Linux.tar.bz2 | 4 | | Debian | https://repo.nano.org/test/binaries/nano-node-V27.1-Linux.deb | 5 | | macOS | https://repo.nano.org/test/binaries/nano-node-V27.1-Darwin.dmg | 6 | | Windows (exe) | https://repo.nano.org/test/binaries/nano-node-V27.1-win64.exe | 7 | | Windows (zip) | https://repo.nano.org/test/binaries/nano-node-V27.1-win64.zip | 8 | | Docker | `docker pull nanocurrency/nano-test:V27.1` | 9 | | RHEL/RockyLinux rpm | Not available anymore. Please check [Build Options](#build-options) for build instructions. | 10 | -------------------------------------------------------------------------------- /docs/releases/release-v22-1.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V22.1 nano node 2 | description: Details of the V22.1 nano node release including upgrade notices and major features. 3 | 4 | # V22.1 5 | 6 | --8<-- "release-details-v22-1.md" 7 | 8 | ## Upgrade notices 9 | There are no special considerations when upgrading from V22.0 to V22.1. There are no database upgrades or API changes. 10 | 11 | 12 | ## Major updates 13 | 14 | * Fixes an issue where UPnP leases might be lost and port mappings might cease 15 | * Fixes an issue where manually started or hinted elections would be quickly removed from the election scheduler 16 | * Fixes an issue where new connections might not be able to be accepted 17 | * Doubles the length of the connection backlog 18 | 19 | ## Developer/debug options 20 | 21 | * Elections dropped due to timeout/overflow have been separated in node statistics. 22 | 23 | --- 24 | 25 | ## Builds and commands 26 | 27 | --8<-- "current-build-links-main.md" 28 | -------------------------------------------------------------------------------- /docs/snippets/security-vulnerability-reporting.md: -------------------------------------------------------------------------------- 1 | !!! warning "Submit vulnerabilities privately" 2 | **Do NOT discuss potential security vulnerabilities on the issue tracker, public forums or open discussion channels. Submit sensitive issues privately to the Nano Foundation for review.** 3 | 4 | If you discover a bug you believe to pose a security risk to the Nano network, please contact security@nano.org with a proof of concept with full details of the bug including: 5 | 6 | * Repository of the bug 7 | * High-level summary 8 | * Detailed description 9 | * Steps to reproduce 10 | * Supporting material/references 11 | * The potential security impact of the bug 12 | 13 | It is strongly recommended to encrypt the email using GPG and the pubkeys for this purpose can be found on the [SECURITY file](https://github.com/nanocurrency/nano-node/blob/develop/SECURITY.md) in the node repository. The Nano Foundation will work to determine potential impacts and coordinate resolution in a node release. -------------------------------------------------------------------------------- /docs/snippets/warning-security-vulnerability-reporting.md: -------------------------------------------------------------------------------- 1 | !!! warning "Submit vulnerabilities privately" 2 | **Do NOT discuss potential security vulnerabilities on the issue tracker, public forums or open discussion channels. Submit sensitive issues privately to the Nano Foundation for review.** 3 | 4 | If you discover a bug you believe to pose a security risk to the Nano network, please contact security@nano.org with a proof of concept with full details of the bug including: 5 | 6 | * Repository of the bug 7 | * High-level summary 8 | * Detailed description 9 | * Steps to reproduce 10 | * Supporting material/references 11 | * The potential security impact of the bug 12 | 13 | It is strongly recommended to encrypt the email using GPG and the pubkeys for this purpose can be found on the [SECURITY file](https://github.com/nanocurrency/nano-node/blob/develop/SECURITY.md) in the node repository. The Nano Foundation will work to determine potential impacts and coordinate resolution in a node release. -------------------------------------------------------------------------------- /docs/protocol-design/resource-usage.md: -------------------------------------------------------------------------------- 1 | title: Protocol Design - Resource Usage 2 | description: Find out the expected resource usage for the nano procotol across network, disk, compute and memory resources 3 | 4 | # Protocol Design - Resource Usage 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Network 9 | 10 | ### Principal Representatives (Voting) 11 | 12 | ### Representatives (Voting) 13 | 14 | ### Observer (Non-voting) 15 | 16 | --- 17 | 18 | ## Disk I/O 19 | 20 | --- 21 | 22 | ## Disk Capacity 23 | 24 | ### Historical 25 | 26 | ### Pruned 27 | 28 | --- 29 | 30 | ## CPU/GPU 31 | 32 | ### Work Generation 33 | 34 | ### Principal Representative 35 | 36 | ### Representative 37 | 38 | ### Observer 39 | 40 | --- 41 | 42 | Existing whitepaper sectionsrelated to this page: 43 | 44 | * [Resource Usage](/whitepaper/english/#resource-usage) 45 | 46 | Existing content related to this page: 47 | 48 | * [Representatives and voting](/what-is-nano/overview/#representatives-and-voting) 49 | * [Representatives](/integration-guides/the-basics/#representatives) -------------------------------------------------------------------------------- /docs/releases/release-v23-1.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V23.1 nano node 2 | description: Details of the V23.1 nano node release including upgrade notices and major features. 3 | 4 | # V23.1 5 | 6 | --8<-- "release-details-v23-1.md" 7 | 8 | ## Upgrade notices 9 | There are no special considerations when upgrading from V22.X or V23.0 to V23.1. There are no database upgrades or API changes. 10 | 11 | ## Fixes 12 | 13 | * Remove a message that is always logged during block processing that could be abused to fill log files 14 | * Clean up the node_id_handshake message handler which in some circumstances can fill memory 15 | * Bound the unchecked table size to ensure it cannot be abused to use up all available disk space 16 | * Limit entries into the unchecked table to two items per dependency 17 | * Add persistent node IDs to provide a method for removing spoof telemetry messages 18 | * Default to turn off inactive votes cache to avoid excessive vote relaying 19 | * Disable a vote processor flushing in the request loop which can block during heavy load 20 | 21 | --- 22 | 23 | ## Builds and commands 24 | 25 | --8<-- "current-build-links-main.md" 26 | -------------------------------------------------------------------------------- /.github/workflows/cleanup-docker-untagged.yml: -------------------------------------------------------------------------------- 1 | name: cleanup-docker-untagged 2 | on: 3 | push: 4 | branches: 5 | - main 6 | 7 | env: 8 | OWNER: orgs/nanocurrency 9 | PACKAGE_NAME: nano-docs 10 | PER_PAGE: 100 11 | 12 | jobs: 13 | container_cleanup: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Clean up untagged containers 17 | uses: actions/github-script@d556feaca394842dc55e4734bf3bb9f685482fa0 #v6.3.3 18 | with: 19 | github-token: ${{ secrets.GHCR_TOKEN }} 20 | script: | 21 | const response = await github.request("GET /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions", 22 | { per_page: ${{ env.PER_PAGE }} 23 | }); 24 | for(version of response.data) { 25 | if ( version.metadata.container.tags.length == 0 ) { 26 | console.log("delete " + version.id) 27 | const deleteResponse = await github.request("DELETE /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions/" + version.id, { }); 28 | console.log("status " + deleteResponse.status) 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /theme-overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block extrahead %} 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | {% if page and page.meta and page.meta.robots %} 13 | 14 | {% else %} 15 | 16 | {% endif %} 17 | 18 | 19 | 20 | {% endblock %} 21 | 22 | {% block announce %} 23 | 24 | 25 | Nano node V27.1 now available! We highly recommend upgrading to 26 | this version for improved network operation: efficiency and security. ⭢ 27 | 28 | 29 | {% endblock %} 30 | -------------------------------------------------------------------------------- /.github/workflows/cleanup-docker-pr.yml: -------------------------------------------------------------------------------- 1 | name: cleanup-docker-pr 2 | on: 3 | pull_request: 4 | types: [closed] 5 | 6 | env: 7 | PR_NUMBER: ${{ github.event.number }} 8 | OWNER: orgs/nanocurrency 9 | PACKAGE_NAME: nano-docs 10 | PER_PAGE: 100 11 | 12 | jobs: 13 | container_cleanup: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Clean up PR specific container 17 | uses: actions/github-script@d556feaca394842dc55e4734bf3bb9f685482fa0 #v6.3.3 18 | with: 19 | github-token: ${{ secrets.GHCR_TOKEN }} 20 | script: | 21 | const response = await github.request("GET /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions", 22 | { per_page: ${{ env.PER_PAGE }} 23 | }); 24 | for(version of response.data) { 25 | if (version.metadata.container.tags[0] == "pr-${{ env.PR_NUMBER }}") { 26 | console.log("delete " + version.id) 27 | const deleteResponse = await github.request("DELETE /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions/" + version.id, { }); 28 | console.log("status " + deleteResponse.status) 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /docs/running-a-node/beyond-the-node.md: -------------------------------------------------------------------------------- 1 | title: Beyond the node 2 | description: Explore other tools, services, education and inspiration available after getting your nano node up and running 3 | 4 | # Beyond the Node 5 | 6 | ## Building tools and services 7 | 8 | Congrats! Now that you understand more about how Nano works and setup your own node to participate on the network, the next step is building tools and services on the node. Our [Integration Guides](/integration-guides/the-basics/) are a great starting point to help you understand how you can leverage your node to create amazing applications that utilize the unique value transfer features of Nano. 9 | 10 | ## Need some inspiration? 11 | 12 | A big part of the Nano community is [the Nano Center](https://nanocenter.org/). Run by a group of Nano enthusiasts, their website helps manage requests for assistance and funding for Nano-related projects. Check out the in progress and past funded projects for some great ideas and opportunities to join in building on top of Nano! 13 | 14 | For even more details about the many projects that help make our ecosystem robust, head over to [Nano.org](https://nano.org) for examples of wallets, services and more that have integrated Nano. 15 | 16 | ## Keep learning 17 | 18 | If you're ready to keep building with Nano, head over to [The Basics](/integration-guides/the-basics/) of our Integration Guides. -------------------------------------------------------------------------------- /docs/node-implementation/introduction.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Introduction 2 | description: An overview of the nano node implementation being developed by the Nano Foundation and broader Nano community 3 | 4 | # Node Implementation - Introduction 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | Methods and mechanisms built into the current node software that aren't required for compliance with protocol rules, but help provide better efficiency and performance for nodes running on the network. These details could be ignored or implemented in different ways by other versions of node software. 9 | 10 | ## Context and scope 11 | 12 | --- 13 | 14 | ## Efficiency and security 15 | 16 | --- 17 | 18 | ## Determinism 19 | 20 | --- 21 | 22 | ## Choice of language and framework 23 | 24 | --- 25 | 26 | ## Github links 27 | 28 | ### Contributing 29 | 30 | --- 31 | 32 | | Section | Description | 33 | |---------|-------------| 34 | | [Components](components.md) | Breakdown of separate functional areas of the node | 35 | | [Database](database.md) | Storage and cementing mechanisms, backend database options | 36 | | [Voting](voting.md) | Vote handling and voting weight management | 37 | | [Work](work.md) | Kernel designs, prioritization processes and rework mechanisms | 38 | | [Contributing](/node-implementation/contributing/) | How to contribute to the Nano protocol directly | 39 | 40 | --- 41 | 42 | Existing whitepaper sections related to this page: 43 | 44 | * [Implementation](/whitepaper/english/#implementation) -------------------------------------------------------------------------------- /docs/node-implementation/blocks.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Blocks 2 | description: Review of block handling in the current nano node implementation 3 | 4 | # Node Implementation - Blocks 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Block publishing and propagation 9 | Nodes use a modified gossip protocol for message distribution that enables quick distribution of blocks and votes across the network while distributing the load required to propagate messages across multiple nodes rather than each node having to respond to requests from every other node. Prioritization of messages are focused on the Principal Representative nodes that make up the core consensus mechanism where they receive blocks and votes directly from other nodes and then messages are spread to the rest of the network via gossiping. 10 | 11 | Blocks are initially broadcast and propagated across the network to different types of nodes based on the blocks status. Some basic rules are listed below: 12 | 13 | - Nodes initially publish new blocks on the live network to **all Principal Representatives they can connect to** and a subset of Non Principal Representative nodes. 14 | - When a node processes a new block that is not a known fork, or is a known fork and the block becomes the new winner on an election, nodes will republish that block to `sqrt(peers)`. 15 | 16 | On average, this gossiping results in blocks arriving multiple times at each node. To help reduce node resource usage, there are duplicate block filters in place to prevent reprocessing of the same blocks. 17 | -------------------------------------------------------------------------------- /docs/snippets/hardware-recommendations.md: -------------------------------------------------------------------------------- 1 | ### Principal Representative Nodes 2 | The following are minimum recommended specifications for nodes with more than 0.1% of the online voting weight ([Principal Representatives](../glossary.md#principal-representative)): 3 | 4 | * 16GB RAM 5 | * Quad-Core or higher CPU 6 | * 500 Mbps bandwidth (8TB or more of available monthly bandwidth) 7 | * SSD-based hard drive with 400GB+ of free space 8 | 9 | ### Non-voting and Representative Nodes 10 | The following are minimum recommended specifications for non-voting nodes and Representative nodes with less than 0.1% of the online voting weight (regular [Representatives](../glossary.md#representative)): 11 | 12 | * 8GB RAM 13 | * Quad-Core CPU 14 | * 250 Mbps bandwidth (4TB or more of available monthly bandwidth) 15 | * SSD-based hard drive with 400GB+ of free space 16 | 17 | These lower specifications are also valid for any type of node run on the [Beta network](../running-a-node/beta-network.md) and [Test network](../running-a-node/test-network.md). 18 | 19 | !!! warning "Varied resource usage" 20 | Various factors affect resource usage including how often RPC calls are made, other applications running on the machine, etc. These recommendations should be evaluated along with other considerations. 21 | 22 | !!! tip "Work Generation guide" 23 | For nodes being used with services requiring regular or high volume sending and receiving of transactions, special considerations must be made for handling Proof-of-Work generation activities. Find details on configuring a GPU, external work services and more for the perfect setup in the [Work Generation guide](../integration-guides/work-generation.md). 24 | -------------------------------------------------------------------------------- /docs/releases/release-v27-1.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V27.1 nano node 2 | description: Details of the V27.1 nano node release. 3 | 4 | # V27.1 5 | 6 | --8<-- "release-details-v27-1.md" 7 | 8 | --- 9 | 10 | ## Upgrade notices 11 | 12 | All nodes are encouraged to upgrade to V27.1, including exchanges. 13 | 14 | In general, exchanges, services and integrations are encouraged to join [the test network](../running-a-node/test-network.md) for performing integration testing. This network mimics the live network in work requirements but has a smaller number of nodes and a lower block count for easier setup. 15 | 16 | ### Database upgrade 17 | 18 | If you are upgrading from previous versions (e.g. V26), V27 includes a one-way database upgrade that takes a few minutes to run. 19 | 20 | If you are upgrading from V27.0, there is no additional database upgrade. 21 | 22 | ### gcc-12 users 23 | 24 | If your system uses gcc-12 there is a known bug in the compiler optimiser that has problems compiling c++20 code. 25 | 26 | If you get a compiler error related to -Wrestrict, it's recomended to either downgrade to gcc-11 or upgrade to gcc-13 to compile the node. See more [detail here](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105329). Debian 12 (bookworm) ships with gcc-12 by default, but has a package for gcc-11. 27 | 28 | --- 29 | 30 | ## Major updates 31 | 32 | See the [V27.0 release notes](release-v27-0.md#major-updates) for the major updates list. 33 | 34 | --- 35 | 36 | ## Fixes 37 | 38 | * [Bounding the growth of the election_winner_details set](https://github.com/nanocurrency/nano-node/pull/4720) 39 | * [Cementing fixes](https://github.com/nanocurrency/nano-node/pull/4722) 40 | 41 | --- 42 | 43 | ## Builds and commands 44 | 45 | --8<-- "current-build-links-main.md" 46 | -------------------------------------------------------------------------------- /docs/releases/release-v23-3.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V23.3 nano node 2 | description: Details of the V23.3 nano node release including upgrade notices and major features. 3 | 4 | # V23.3 5 | 6 | --8<-- "release-details-v23-3.md" 7 | 8 | ## Upgrade notices 9 | There are no special considerations when upgrading from V22.X or V23.X to V23.3. There are no database upgrades or API changes. 10 | 11 | ## Fixes 12 | 13 | * Correctly check for the magic bytes and the network in the message header 14 | * Remove a debug assert that crashes the node on receipt of zero node ID 15 | * Improve the vote processor class and limit its flush operation, so it does not block for too long 16 | * Disable migrating of unchecked table from LMDB to RocksDB as this upgrade is not really needed 17 | * Convert functions on unchecked_map class that return iterators to use for_each with a functor to execute on each result 18 | * Reimplement nano::unchecked_store::get in terms of unchecked_store::for_each and remove backend-specific variants 19 | * Add a memory container for blocks once the initial bootstrap threshold is reached having the blocks pruned in FIFO order 20 | * Vote hinting re-enabled 21 | * Fix nano::json_handler::unchecked_get which did not get translated properly with the for_each conversion 22 | * Merge identical code branches for convenience at nano::unchecked_store_partial::put 23 | * Change the unchecked blocks to be put in to a memory container instead of disk when the initial bootstrap threshold is reached having the blocks removed from the container in FIFO order once the maximum of 256,000 blocks are reached 24 | * Change the active_transactions::cleanup_election to use shared pointer instead of an object reference 25 | 26 | --- 27 | 28 | ## Builds and commands 29 | 30 | --8<-- "current-build-links-main.md" 31 | -------------------------------------------------------------------------------- /docs/protocol-design/signing-hashing-and-key-derivation.md: -------------------------------------------------------------------------------- 1 | title: Protocol Design - Signing, Hashing and Key Derivation 2 | description: All about the methods for signing messages, hashing data and deriving keys on the nano protocol 3 | 4 | # Protocol Design - Signing, Hashing and Key Derivation 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ### Signing algorithm: ED25519 9 | 10 | ED25519 is an elliptic curve algorithm developed in an academic setting with a focus on security from side channel attack, performance, and fixing a lot of the little annoyances in most elliptic curve systems[^1]. However, it should be noted that instead of using SHA-512 in the key derivation function, Nano uses Blake2b-512. 11 | 12 | !!! failure "Incorrect, SHA-512 has been used" 13 | ``` 14 | 0000000000000000000000000000000000000000000000000000000000000000 -> 15 | 3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29 16 | ``` 17 | 18 | !!! success "Correct, Blake2b-512 digested the seed" 19 | ``` 20 | 0000000000000000000000000000000000000000000000000000000000000000 -> 21 | 19D3D919475DEED4696B5D13018151D1AF88B2BD3BCFF048B45031C1F36D1858 22 | ``` 23 | 24 | ### Hashing algorithm: Blake2 25 | 26 | Compared to existing cryptocurrencies, the hash algorithm chosen is much less important since it's not being used in a [Proof-of-Work](/glossary#proof-of-work-pow) context. In Nano hashing is used purely as a digest algorithm against block contents. Blake2b-256 is a highly optimized cryptographic hash function whose predecessor was a SHA3 finalist.[^2] 27 | 28 | ### Key derivation function: Argon2 29 | 30 | The key derivation function of Argon2d version 1.0 is used for securing the account keys in the reference wallet. [^3] 31 | 32 | [^1]:http://ed25519.cr.yp.to/ 33 | [^2]:https://blake2.net/ 34 | [^3]:https://en.wikipedia.org/wiki/Argon2 -------------------------------------------------------------------------------- /docs/snippets/network-details.md: -------------------------------------------------------------------------------- 1 | ## Network Details 2 | 3 | | Port | Type | Default | Details | 4 | | | | | | 5 | | 7075 | TCP | Enabled |
  • Node bootstrapping server
  • Share port configuration in `config-node.toml`, option `node.peering_port`
  • Binds to all adapters; unicast
  • Contents: Raw nano protocol stream
  • Transmits the ledger to new nodes in bulk
  • If blocked other nodes will not be able retrieve the ledger from this node
| 6 | | 7076 | TCP | Disabled |
  • RPC server
  • Port configurable in `config-rpc.toml`, option `rpc.port`
  • Enable in `config-node.toml`, option `rpc.enable` or by starting `nano_rpc` manually
  • Binds to localhost by default for security reasons, configurable in `config-rpc.toml`, option `rpc.address`; unicast
  • Contents: Unencrypted HTTP requests containing JSON object bodies
  • Allows the node to be queried or controlled through HTTP requests
  • If blocked the node will not be able to be queried or controlled by HTTP
  • **WARNING: Exposing this port externally while setting `enable_control` option to `true` in configs could expose your wallet, allow the node to be stopped remotely and open your node up to other dangerous activity.** See the [Node Security page](/running-a-node/security) for more details.
| 7 | | 7078 | TCP | Disabled |
  • Websocket server
  • Port configurable in `config-node.toml`, option `node.websocket.port`
  • Enable in `config-node.toml`, option `node.websocket.enable`
  • Binds to localhost by default due to data throughput potentially being very high; producer-subscriber broadcast
  • Contents: Standard websocket frames containing JSON-encoded objects
  • See [WebSocket Support](/integration-guides/websockets) for details on configuration
| 8 | -------------------------------------------------------------------------------- /docs/snippets/current-build-links-main.md: -------------------------------------------------------------------------------- 1 | | OS | Download link/command | Verification | 2 | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| 3 | | Universal Linux | https://repo.nano.org/live/binaries/nano-node-V27.1-Linux.tar.bz2 | [SHA256 Checksum](https://repo.nano.org/live/binaries/nano-node-V27.1-Linux.tar.bz2.sha256) | 4 | | Debian | https://repo.nano.org/live/binaries/nano-node-V27.1-Linux.deb | [SHA256 Checksum](https://repo.nano.org/live/binaries/nano-node-V27.1-Linux.deb.sha256) | 5 | | macOS | https://repo.nano.org/live/binaries/nano-node-V27.1-Darwin.dmg | [SHA256 Checksum](https://repo.nano.org/live/binaries/nano-node-V27.1-Darwin.dmg.sha256) | 6 | | Windows (exe) | https://repo.nano.org/live/binaries/nano-node-V27.1-win64.exe | [SHA256 Checksum](https://repo.nano.org/live/binaries/nano-node-V27.1-win64.exe.sha256) | 7 | | Windows (zip) | https://repo.nano.org/live/binaries/nano-node-V27.1-win64.zip | [SHA256 Checksum](https://repo.nano.org/live/binaries/nano-node-V27.1-win64.zip.sha256) | 8 | | Docker | `docker pull nanocurrency/nano:V27.1`
See [Pulling the Docker Image](/running-a-node/node-setup/#pulling-the-docker-image) for more details. | | 9 | | RHEL/RockyLinux rpm | Not available anymore. Please check [Build Options](#build-options) for build instructions. | | 10 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Home 3 | description: Explore the design, features, releases and other related resources for the nano protocol and node implementation. 4 | hide: 5 | - navigation 6 | - toc 7 | --- 8 | 9 | # Nano Node and Protocol Documentation 10 | Welcome! This documentation is focused on helping developers understand Nano, including setup, maintenance, and building on top of the Nano node. Details of how this documentation has been arranged are below: 11 | 12 | | Section | Details | Audience | 13 | | | | | 14 | |**[What is Nano?](what-is-nano/overview.md)**|Take a high-level tour - this is a great place to learn about how Nano is uniquely suited to being a global digital currency.|Everyone| 15 | |**[Running a Node](running-a-node/overview.md)**| Set up a Nano node to manage the ledger, create and publish blocks and participate in consensus. | Node operators, developers | 16 | |**[Integration Guides](integration-guides/the-basics.md)**| Learn practical concepts, structures and features for building wallets, payment systems and other services on the Nano network. | Developers | 17 | |**[Living Whitepaper](living-whitepaper/index.md)**| Dive into the details of why Nano was created & how it's designed. Split into two sub-sections: [Protocol Design](protocol-design/introduction.md) & [Node Implementation](node-implementation/introduction.md). | Developers | 18 | |**[Protocol Design](protocol-design/introduction.md)**| Dig deeper into the design and behaviors driving the protocol, including the election process, peering mechanics and more. | Developers | 19 | |**[Node Implementation](node-implementation/introduction.md)**| Details of the Nano Foundation managed node implementation of the protocol. | Developers | 20 | |**[Core Development](core-development/overview.md)**| Interested in contributing to the core Nano code or protocol? Here's how to get started. | Developers | 21 | |**[Commands](commands/rpc-protocol.md)**| Explore an exhaustive list of interaction methods for the node via RPC and CLI. | Node operators, developers | 22 | |**[Releases](releases/node-releases.md)**| Review past node releases and get details about the features coming soon in new releases. | Everyone | 23 | |**[Glossary](glossary.md)**| Commonly used terms throughout the documentation and Nano ecosystem. | Everyone | 24 | 25 | **Join the Community** 26 | 27 | If you are looking for other details about Nano, links to wallets, discussions about the network and more, check out our community: 28 | 29 | --8<-- "community-links.md" 30 | 31 | [Change cookie settings](#__consent) 32 | -------------------------------------------------------------------------------- /theme-overrides/partials/footer.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /docs/core-development/overview.md: -------------------------------------------------------------------------------- 1 | title: Core Development Overview 2 | description: All you need to know to help contribute to the core development of the nano node and protocol 3 | 4 | # Core Development 5 | 6 | Welcome and thanks for your interest in core development of the nano! The following resources contain information and guides for getting involved with the development of the node and protocol. 7 | 8 | ## Getting started 9 | 10 | It is recommended to have an understanding of how the nano protocol is designed to work so the code can be more easily read and evaluated. 11 | 12 | - Start by reviewing the [living whitepaper](../living-whitepaper/index.md) 13 | - Read through (or try out) the [running a node guides](../running-a-node/overview.md) 14 | - Understand [the basics](../integration-guides/the-basics.md) and maybe even some [advanced details](../integration-guides/advanced.md) about integrations 15 | - Learn how to [build the node yourself](../integration-guides/build-options.md) 16 | - Participate in the community through [Discord](https://chat.nano.org) and the [Forum](https://forum.nano.org) 17 | - Start perusing the code in the repositories below and don't be afraid to ask questions 18 | 19 | 20 | ## Code repositories 21 | 22 | The Nano Foundation manages the [`nanocurrency`](https://github.com/nanocurrency) GitHub Organization account which includes various repositories for nano tools and implementations. Below is a partial list of the most common repositories referenced. 23 | 24 | | Name | Language | Purpose | 25 | |------|----------|---------| 26 | | [nanocurrency/nano-node](https://github.com/nanocurrency/nano-node) | C++| Primary node implementation used on the nano network | 27 | | [nanocurrency/nano-work-server](https://github.com/nanocurrency/nano-work-server) | Rust | Standalone server for generating work values for blocks | 28 | | [nanocurrency/protocol](https://github.com/nanocurrency/protocol) | Kaitai Struct | Specification for nano network message protocol | 29 | | [nanocurrency/nanodb-specification](https://github.com/nanocurrency/nanodb-specification) | Kaitai Struct | Specification for database tables and fields used by the `nano-node` implementation | 30 | | [nanocurrency/nano-docs](https://github.com/nanocurrency/nano-docs) | Markdown | MKDocs based documentation this docs.nano.org site is built from | 31 | 32 | Most of the content in the following documentation is focused around the [nanocurrency/nano-node](https://github.com/nanocurrency/nano-node) repository, as that is where most development activity occurs. But there are tons of related projects creating useful tools, libraries, services and more for the nano ecosystem (see some options in [GitHub](https://github.com/search?q=nanocurrency&type=discussions)). 33 | 34 | ## Security vulnerability reporting 35 | 36 | --8<-- "warning-security-vulnerability-reporting.md" 37 | 38 | ## Nano Foundation core developers 39 | 40 | In addition to contributions from the wider nano community, the [Nano Foundation](https://nano.org/foundation) manages a team of core developers who contribute to the protocol and primary node implementation. For a list of code contributors, see the [GitHub Insights page](https://github.com/nanocurrency/nano-node/graphs/contributors). -------------------------------------------------------------------------------- /docs/protocol-design/networking.md: -------------------------------------------------------------------------------- 1 | title: Protocol Design - Networking 2 | description: Details of networking setup design for nano protocol 3 | 4 | # Protocol Design - Networking 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## TCP messages 9 | TCP is used for traffic on the [live network](/glossary#live-network) and for bulk data transfer on the [bootstrap network](/glossary#bootstrap-network). 10 | 11 | --8<-- "network-details.md" 12 | 13 | ## IPV4/IPV6 addressing 14 | The system is built to only operate on IPv6 and uses IPv4-mapped IPv6 addresses to connect to IPv4 hosts. 15 | 16 | ## Node telemetry 17 | In _v21_ node telemetry was added to node. This allows peers to communicate telemetry metrics to each other. For specific details on the message format see `telemetry_ack` in the [protocol specification](https://github.com/nanocurrency/protocol/tree/master/reference). 18 | 19 | The nodes are designed to reply to `telemetry_req` messages. They avoid replying if messages are received from the same peer in quick succession; the minimum time until another reply is 60 seconds on the main network, 15 seconds on beta. This is done to reduce bandwidth. 20 | 21 | Telemetry messages bypass the node's bandwidth limiter so that services monitoring the network can still do so during when the network is heavily used. Sending `telemetry_req` frequently within this exclusion zone could see your ip blacklisted by other peers. The node safely handles this for you by doing ongoing requests periodically and only sent when valid to do so. 22 | 23 | ### Signing 24 | `Telemetry_ack` messages are signed using [ED25519](/protocol-design/signing-hashing-and-key-derivation/#signing-algorithm-ed25519) as follows: 25 | 26 | ``` 27 | ED25519(key = node id public key, message = "node id || block count || cemented count|| unchecked count || account count || bandwidth capacity || peer count || protocol version || uptime || genesis block hash || major version || minor version || patch version || pre-release version || maker || timestamp since UTC epoch || active difficulty") 28 | ``` 29 | 30 | The node id used in the initial handshake is used for signing. The genesis block hash should be in big endian. 31 | The data is signed so that it cannot be forged by a Man In The Middle (MITM) attack. 32 | 33 | !!! warning "Peer disconnections" 34 | Sending incorrectly signed telemetry data to peers will result in being blacklisted as it is seen as malicious, make sure the signing is correct! Verify signatures against known signing done by node by testing [local telemetry](../commands/rpc-protocol.md#telemetry). Nodes with a different genesis block hash will also be disconnected. 35 | 36 | ## Peering process 37 | 38 | Initial identification of peers is a [node implementation detail](../node-implementation/networking.md#peering-process), but once a node successfully connects with another using the protocol handshake, the keepalive messages each node sends will include a random selection of the IP addresses of 8 of their peers. Any new IP addresses will be included in the list of potential peers the node will attempt to connect with during bootstrapping, vote request, telemetry and other activities. 39 | 40 | --- 41 | 42 | ## Live traffic 43 | 44 | --- 45 | 46 | ## Bootstrap traffic 47 | 48 | --- 49 | 50 | Existing whitepaper sections related to this page: 51 | 52 | * [Networking](/protocol-design/networking/) 53 | -------------------------------------------------------------------------------- /docs/living-whitepaper/index.md: -------------------------------------------------------------------------------- 1 | title: Living Whitepaper 2 | description: Overview of the living whitepaper on the Nano protocol and existing node implementation 3 | 4 | # Nano - Digital money for the modern world 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | --8<-- "contributing-code.md" 9 | 10 | The original whitepaper for Nano was last updated in November 2017, and since then, many improvements to the protocol have been made. The current node implementation has received updates every few months on average since 2018.[^1] As these updates continue to make the network stronger over time, the static nature of a traditional whitepaper required too much effort to continually update and publish. To ensure information about Nano is kept as up-to-date as possible, a new "Living Whitepaper" is being managed through the existing documentation website, which is easier to update and is open source.[^2] 11 | 12 | ## Protocol vs. Node 13 | 14 | The two main sections of the Living Whitepaper are the [Protocol Design](../protocol-design/introduction.md) and [Node Implementation](../node-implementation/introduction.md). Although they were structured to split the required elements to conform to the protocol (Protocol Design) away from optional improvements built into the current node (Node Implementation), there is some overlap between them. Where possible, these overlaps have been highlighted; however, those interested in [contributing to the development of the protocol](../core-development/overview.md) or building another node implementation should analyze more closely the differences between these to ensure the necessary rules are followed. 15 | 16 | ### [Protocol Design](../protocol-design/introduction.md) 17 | 18 | This section contains details of the different messages shared between nodes and common data structures, which allow data to be stored and communicated consistently across the network. Because Nano is decentralized and uses network-wide consensus to validate transactions, participating on the network requires following the message and data designs, otherwise attempts at transacting will be ignored or not properly confirmed by the network. 19 | 20 | Many changes done to elements outlined here require a change in the [protocol version](../glossary.md#protocol-version) in addition to the [node version](../glossary.md#node-version). 21 | 22 | ### [Node Implementation](../node-implementation/introduction.md) 23 | 24 | This section expands into methods and mechanisms built into the current node software that aren't required for compliance with protocol rules, but help provide better efficiency and performance for nodes running on the network. These details could be ignored or implemented in different ways by different types or versions of node software, while still maintaining compatibility with other nodes. 25 | 26 | --- 27 | 28 | Existing whitepaper sections related to this page: 29 | 30 | * [Introduction](../whitepaper/english.md#introduction) 31 | * [Background](../whitepaper/english.md#background) 32 | 33 | Other existing content related to this page: 34 | 35 | * [Nano Overview](../what-is-nano/overview.md) 36 | * [Representatives and Voting](../what-is-nano/overview.md#representatives-and-voting) 37 | * [Incentives to run a node](https://medium.com/nanocurrency/the-incentives-to-run-a-node-ccc3510c2562) 38 | 39 | [^1]: Node Releases: https://docs.nano.org/releases/node-releases/ 40 | [^2]: Nano Documentation Repository: https://github.com/nanocurrency/nano-docs/ 41 | -------------------------------------------------------------------------------- /docs/core-development/code-standards.md: -------------------------------------------------------------------------------- 1 | title: Code Standards 2 | description: Learn about the code standards expected when contributing to the nano protocol and node implementation 3 | 4 | # Code standards 5 | 6 | ## Formatting 7 | 8 | clang-format is used to enforce most of the formatting rules, such as: 9 | 10 | * Tabs for indentation. 11 | * Open braces go on new lines. 12 | * Space before open parenthesis. 13 | * Space after comma. 14 | 15 | Running `ci/clang-format-do.sh` on \*nix systems is required before pushing your code to ensure that the formatting is good. If you want to do formatting from the IDE, chances are there's a plugin available. Visual Studio for instance provides a way to automatically format on saving. The definition file `.clang-format` is located in the project root directory. For CMake changes, running `cmake-format-do.sh` is required as well. 16 | 17 | Make sure you set up your editor to use tabs. Use tabs for indentation, and spaces for alignment [^1]. That way, you can use any tab size you want in your favorite editor, but the code will still look good for people with different settings. 18 | 19 | ## General guidelines 20 | 21 | * Use `auto` type inference for local variables if it's clear from the context what the type will be. Use your best judgement, sometimes adding explicit types can increase readability [^2] 22 | * Handle exceptions, including IO exceptions for file and network operations. 23 | * Be liberal with `debug_assert`. Use asserts to check invariants, not potential runtime errors, which should be handled gracefully. `debug_assert` has an advantage over normal `assert` as it will always print out the stacktrace of the current thread when it hits. Debug asserts are for detecting bugs, not error handling. There is also `release_assert` which is similar to `debug_assert` but also hits in a release build. When there is unexpected behaviour and no suitable way to recover it can be used to halt program execution. 24 | * Be liberal with `logger.always_log` or `logger.try_log` statements, except in performance critical paths. 25 | * Add comments to explain complex and subtle situations, but avoid comments that reiterates what the code already says. 26 | * Use RAII and C++11 smart pointers to manage memory and other resources. 27 | 28 | ## Performance and scalabiliy considerations 29 | 30 | * When making changes, think about performance and scalability. Pick good data structures and think about algorithmic complexity. 31 | * Nested loops yield quadratic behavior - is there an alternative? A typical example is removing an inner lookup loop with an unordered set/map to improve lookup performance to O(1). 32 | * Make sure your change doesn't conflict with the scalability characteristics described in the white paper. 33 | 34 | ## Security 35 | 36 | Your code will be reviewed with security in mind, but please do your part before creating a pull request: 37 | 38 | * Familiarize yourself with best practices for writing secure C++ code. In particular: 39 | * Consult https://wiki.sei.cmu.edu/confluence/display/cplusplus 40 | * Avoid using ANSI C functions. Many of these are prone to buffer overruns. 41 | * Avoid using C strings and direct buffer manipulation. 42 | 43 | * Use static and dynamic analysis tools, such as valgrind, XCode instrumentation, linters and sanitizers. These tools are also great for debugging crashes and performance problems. 44 | 45 | [^1]: https://dmitryfrank.com/articles/indent_with_tabs_align_with_spaces 46 | [^2]: http://www.acodersjourney.com/2016/02/c-11-auto/ 47 | -------------------------------------------------------------------------------- /docs/running-a-node/test-network.md: -------------------------------------------------------------------------------- 1 | title: Test Network 2 | description: Find out how to get a nano node setup on the test network for general integration and node upgrade testing 3 | 4 | # Test network 5 | 6 | The test network exists primarily for the purpose of conducting general integration and node upgrade testing in light volumes. By providing a network with similar parameters to the main network (work difficulty, etc.) this is the best environment for connecting test or staging versions of services and applications to for small scale tests. In order to keep the network as stable as possible, the Nano Foundation will maintain nodes on this network on the latest Release Candidate (RC) or release version, it will not be updated with beta or development features. 7 | 8 | For load testing and new node releases and features testing, head over to the [beta network](beta-network.md) page where details on how to conduct those types of network-wide testing exist. 9 | 10 | ## Running a test node 11 | 12 | Setting up a node on the test network is similar to the beta network. To start you should [install docker](/running-a-node/node-setup/#installing-docker) and be familiar with the general setup and [Docker management](/running-a-node/docker-management/) processes. 13 | 14 | ### Network ports 15 | 16 | --8<-- "network-details-simple-test.md" 17 | 18 | ___ 19 | 20 | ### Directory locations 21 | 22 | --8<-- "directory-locations-test.md" 23 | 24 | --- 25 | 26 | 27 | ### Binaries 28 | 29 | In addition to the Docker details above, the latest binary builds of the node for the test network can be found below. These will only change when Release Candidates (RC) builds are ready, or when final releases are done. However, the first build available today is actually a development build since the changes to enable this network were recently introduced. 30 | 31 | --8<-- "current-build-links-test.md" 32 | 33 | 34 | If manual builds are needed, see the [build options](../integration-guides/build-options.md) page for details. 35 | 36 | 37 | ### Pulling the Docker image 38 | [![Docker Pulls](https://img.shields.io/docker/pulls/nanocurrency/nano.svg)](https://hub.docker.com/r/nanocurrency/nano-test) 39 | 40 | Pulls the latest test release of the nano Node: 41 | ```bash 42 | docker pull nanocurrency/nano-test 43 | ``` 44 | 45 | Pulls a specific test version of the nano node: 46 | ```bash 47 | docker pull nanocurrency/nano-test: 48 | ``` 49 | 50 | A list of test tags can be found at the official [Nano Currency Docker Hub](https://hub.docker.com/r/nanocurrency/nano-test/tags) 51 | 52 | ### Starting the Docker container 53 | 54 | --8<-- "docker-run-command-test.md" 55 | 56 | !!! tip 57 | * For an explanation of the options included in the Docker `run` command, see [Starting the Container](/running-a-node/docker-management/#starting) details for the main network. 58 | * See [Docker management](/running-a-node/docker-management/) for other related commands 59 | 60 | !!! warning "Separate host directories" 61 | Be sure to use a different host directory for main network, beta network and test network Docker node setups. Attempting to use the same directory will result in issues. 62 | 63 | ## Getting test funds 64 | 65 | One you have a node up and running the ledger should bootstrap from the network quickly, and then you just need some test network specific Nano funds. We are currently working on a faucet setup to enable self-service options, but for now please reach out to `ThiagoSFS#1554` on [Discord](https://chat.nano.org) or email [infrastructure@nano.org](mailto:integrations@nano.org) with the account number you would like funds distributed to for the test network. 66 | -------------------------------------------------------------------------------- /docs/protocol-design/distribution-and-units.md: -------------------------------------------------------------------------------- 1 | title: Protocol Design - Distribution and Units 2 | description: Review the breakdown of divisibility, distribution and units within the nano protocol 3 | 4 | # Protocol Design - Distribution and Units 5 | 6 | !!! warning "Page may be migrating" 7 | This page may be migrated into another page or section - TBD. 8 | 9 | --8<-- "wip-living-whitepaper.md" 10 | 11 | ## Divisibility 12 | There are three important aspects of divisibility of the supply which are satisfied by the final distributed amount: 13 | 14 | - The supply needs to be able to be divided up amongst a large number of users with users possibly wanting several accounts. 15 | - Each account needs to be able to represent an adequate dynamic range of value. 16 | - The supply should be able to deal with deflation over time as accounts are abandoned. 17 | 18 | ## Distribution 19 | The distribution of Nano (formerly RaiBlocks) was performed through solving manual captchas starting in late 2015 and ending in October 2017. Distribution stopped after \~39% of the [Genesis](/glossary#genesis) amount was distributed and the rest of the supply was burnt.[^1] 20 | 21 | !!! info "Distribution Accounts" 22 | * **Genesis**: `nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3` 23 | * **Landing**: `nano_13ezf4od79h1tgj9aiu4djzcmmguendtjfuhwfukhuucboua8cpoihmh8byo` 24 | * **Faucet**: `nano_35jjmmmh81kydepzeuf9oec8hzkay7msr6yxagzxpcht7thwa5bus5tomgz9` 25 | * **Burn**: `nano_1111111111111111111111111111111111111111111111111111hifc8npp` 26 | 27 | During distribution the Genesis seed was kept in cold storage and funds were moved to the Landing account once per week to minimize the number of live, undistributed blocks. These were subsequently moved into the Faucet account for distribution until the faucet was closed and remaining funds sent to the Burn account. 28 | 29 | !!! info "Total Supply" 30 | With $2^{128} - 1$ raw (i.e. `FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF` HEX raw) in the original Genesis account, upon closing of the faucet and burning of the remaining funds, the total supply which is 100% in circulation ended at **~133,248,297 nano** (or more precisely 133248297920938463463374607431768211455 raw). Since then, additional funds have been sent to the known burn address slightly lowering the amount in circulation as a result. This amount can be found using the [available_supply](/commands/rpc-protocol/#available_supply) RPC. 31 | 32 | ## Unit Dividers 33 | A 128 bit integer is used to represent account balances. The reference wallet uses nano as a divider. 34 | 35 | | Name | Integer | Power | Previous | 36 | |-------------------|------------------------------------|----------|-----------------------| 37 | | nano (NANO/Nano) | 1000000000000000000000000000000 | $10^{30}$| Mnano | 38 | | raw | 1 | $10^{0}$ | raw | 39 | 40 | 41 | **NOTE:** 1 raw is the smallest possible division and is used in QR codes as `amount`, while nano is the current standard division used for human readable elements in most wallets, on exchanges, etc. 42 | 43 | A set of SI prefixes[^2] from the base nano has been previously used to make the numbers more accessible and avoid confusion in certain scenarios, but this approach is not common (e.g., micronano or μnano for $10^{24}$). 44 | 45 | [^1]:https://medium.com/nanocurrency/the-nano-faucet-c99e18ae1202 46 | [^2]:The SI prefixes are metric prefixes that were standardized for use in the International System of Units (SI) by the International Bureau of Weights and Measures (BIPM). https://www.bipm.org/en/measurement-units/si-prefixes 47 | -------------------------------------------------------------------------------- /docs/node-implementation/voting.md: -------------------------------------------------------------------------------- 1 | title: Node Implementation - Voting 2 | description: Review the various aspects of voting and vote management in the nano node implementation 3 | 4 | # Node Implementation - Voting 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Vote rebroadcasting 9 | 10 | When a block is processed, Principal Representatives evaluate whether they can generate a vote for the block (dependent blocks already confirmed, etc.). If they can, they generate the vote and publish to all other PRs they are aware of in addition to `2*sqrt(peers)` of non-PR nodes. To reduce the load on PRs nodes, they do not republish incoming votes - only Non-PR nodes republish other votes to `1/2*sqrt(peers)` to ensure enough coverage across the rest of the network. 11 | 12 | Due to the direct 1:1 relationship between PR nodes, their latency is mostly geographic/network based. For Non-PRs, there is some gossiping via the random distribution, so the number of hops required is what makes up a majority of the latency and the geographic and network latency is less of a factor. 13 | 14 | --- 15 | 16 | ## Final votes 17 | 18 | Nodes will treat votes differently depending on the value of their timestamp field, which results in two phases of voting. These votes can be considered non-final votes and final votes. 19 | 20 | Non-final votes are generated when a node is ready to vote on a block and it has not seen enough vote weight to reach quorum. This non-final vote will have the current Unix time stamp in seconds in the timestamp field. 21 | 22 | Once quorum is reached from votes received, the node will then generate a new final vote for the same block where the timestamps field contains the maximum value possible: `18446744073709551615`. 23 | 24 | In the above cases when evaluating quorum for generating a final vote, both non-final votes and final votes can be included. But a node will only consider a block confirmed when quorum is reached with all final votes. At that point the triggering of confirmation notifications, updating of confirmation heights, etc. occurs. 25 | 26 | --- 27 | 28 | ## Rep crawler 29 | 30 | The rep crawler is a repeating process to help track the online (actively voting) status of representatives. Although typical network activity highly propagates votes to many nodes on the network, there is no guarantee that a given node will receive a recent vote from a particular representative. 31 | 32 | To help fill these potential gaps in online status, the rep crawler pulls a set of random representatives from its peers list - either 15 entries if the weight of peers is higher than quorum delta, otherwise 50 entries - and sends confirmation requests to them for a randomly chosen block in the local ledger. 33 | 34 | If the confirmation acknowledgement is returned for those peers they will be considered online and actively voting. This ongoing crawl happens every 7 seconds on the live, beta and test networks, and every 0.1 seconds on the dev network for unit test purposes. 35 | 36 | --- 37 | 38 | ## Online weight calculator 39 | 40 | Whenever a vote signed by a particular representative is processed by the node, it will consider that representative to be online and included in the online weight calculations. This online status will remain for a period of 5 minutes after the vote processing and the clock will reset back to 5 minutess when additional voting is seen. 41 | 42 | This online status is counted regardless of where the vote originated from - the [rep crawler](#rep-crawler), live voting activity, etc. 43 | 44 | --- 45 | 46 | ## Active transactions loop 47 | 48 | --- 49 | 50 | Existing whitepaper sections related to this page: 51 | 52 | * [Implementation](/whitepaper/english/#implementation) 53 | 54 | Other content related to this page: 55 | 56 | * [Voting as a Representative guide](../running-a-node/voting-as-a-representative.md) 57 | -------------------------------------------------------------------------------- /docs/releases/release-v27-0.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V27.0 nano node 2 | description: Details of the V27.0 nano node release. 3 | 4 | # V27.0 5 | 6 | --8<-- "release-details-v27-0.md" 7 | 8 | --- 9 | 10 | ## Upgrade notices 11 | 12 | All nodes are encouraged to upgrade to V27.0, including exchanges. 13 | 14 | In general, exchanges, services and integrations are encouraged to join [the test network](../running-a-node/test-network.md) for performing integration testing. This network mimics the live network in work requirements but has a smaller number of nodes and a lower block count for easier setup. 15 | 16 | ### Database upgrade 17 | 18 | V27 includes a one-way database upgrade that takes a few minutes to run. 19 | 20 | ### gcc-12 users 21 | 22 | If your system uses gcc-12 there is a known bug in the compiler optimiser that has problems compiling c++20 code. 23 | 24 | If you get a compiler error related to -Wrestrict, it's recomended to either downgrade to gcc-11 or upgrade to gcc-13 to compile the node. See more [detail here](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105329). Debian 12 (bookworm) ships with gcc-12 by default, but has a package for gcc-11. 25 | 26 | ### RPC changes 27 | 28 | V27 RPC changes are minor and non-breaking. 29 | 30 | --- 31 | 32 | ## Major updates 33 | 34 | ### Fair Queueing Enhancements 35 | Designed by Piotr Wójcik, the fair queue has been integrated into the nano node, ensuring equal processing time for each network peer. The fair queue orders requests in a fair, round-robin fashion, which is needed by several components in the node, including block, network message, bootstrap request, and vote request processing. These fair queues help ensure that higher priority transactions are seen and prioritized more consistently, even during network congestion. 36 | 37 | ### Network Handling Rewrite 38 | Significant portions of the networking stack have been rewritten and simplified. Legacy code that handled half-duplex TCP channels has been removed and all TCP connections now operate full-duplex. Asynchronous callback-style code has been replaced with coroutines in several places simplifying code flow. 39 | 40 | ### Network Flow Control Improvements 41 | This suite of features optimises transaction processing, guards against spam and denial-of-service attacks, and ensures equitable resource distribution. 42 | 43 | ### Up to 255 votes per message 44 | V27 allows voting messages to contain up to 255 votes per message, an increase from the previous limit of 12. This enhancement reduces voting traffic and network congestion, improving consensus efficiency and robustness. Note that this change de-peers nodes older than V26.0. 45 | 46 | ### Additional prioritization bucket 47 | An additional prioritization bucket for amounts between Ӿ0.000001 and Ӿ0.0003 has been added, for a total of 63. More precisely, amounts above Ӿ0.0000006 (2^79 raw) and below Ӿ0.000309 (2^88 raw) will fall in this new bucket. All existing buckets remain unchanged to minimize the impact of bucket reallocation. Many Nano faucets send amounts in this range to new users trying out nano for the first time, and many wallets use Ӿ0.000001 as the minimum amount for automatic receives. More details on buckets and bucket ranges [here](../protocol-design/spam-work-and-prioritization.md/#prioritization-details). 48 | 49 | ### Configurable Logging 50 | A new, highly configurable logging system allows node operators to tailor logging levels and outputs, enhancing debugging and health monitoring without excessive disk space use. 51 | 52 | ### Bug fixes 53 | Several bugs were fixed, including race conditions, missing notifications, & dependency issues. 54 | 55 | --- 56 | 57 | ## Official V27 Blog Post 58 | See [here](https://nano.org/en/blog/v27-denarius-preview--eb8bceac) for the official V27 blog post. 59 | 60 | --- 61 | 62 | --8<-- "current-build-links-main.md" 63 | -------------------------------------------------------------------------------- /docs/integration-guides/block-confirmation-tracking.md: -------------------------------------------------------------------------------- 1 | title: Block Confirmation Tracking 2 | description: Guide detailing best practices for block confirmation tracking from the nano node 3 | 4 | # Block Confirmation Tracking 5 | 6 | !!! tip "Guide based on node V19.0" 7 | The recommendations below are based on node V19.0 and node versions earlier may not have all these options available. All integrations should upgrade their nodes to make use of easier block confirmation procedures detailed here. 8 | 9 | A primary function of any integration is to track confirmation of blocks on the network and the node provides both proactive notifications and options to request confirmation status on individual blocks. This combination allows building of robust systems for monitoring the status of any blocks of interest. 10 | 11 | !!! tip "Notifications and fallback requests both recommended" 12 | Due to notification methods not guaranteeing delivery of every block confirmed, it is recommended that manual requests for confirmation status be implemented as a fallback option. Both these types of methods are outlined below. 13 | 14 | ### Receiving notifications of confirmation 15 | 16 | The recommended method for receiving notifications is via [WebSockets](/integration-guides/websockets) through the confirmation `topic`. This method involves sending a subscribe command to start receiving notifications every time a block is confirmed by the network. It is recommended that the `confirmation_type` filtering options are not used for this purpose, to make it less likely to miss a notification. 17 | 18 | **Setup process** 19 | 20 | 1. Update your [WebSocket configuration](/running-a-node/configuration/#nodewebsocket) 21 | 1. Connect to the WebSocket at the configured endpoint 22 | 1. Send a [subscription request for all confirmations](/integration-guides/websockets#confirmations) including the ack option and validate the subscription request was successful 23 | 1. Listen for block confirmation notifications from the WebSocket 24 | 25 | As confirmations are received they can be parsed and handled as necessary. All operations handling notifications from the node on block confirmation should be idempotent as multiple notifications for the same block hash can occur. 26 | 27 | --8<-- "warning-multiple-confirmation-notifications.md" 28 | 29 | ### Requesting block confirmation status 30 | 31 | In the event confirmation notifications are not received from the WebSocket in an expected timeframe, the [block_info](/commands/rpc-protocol#block_info) RPC can be called on a specific block hash. The `confirmed` field will indicate whether the block has been confirmed. Typical confirmation times on the main network during low-traffic periods are within a few seconds, so a delay of 5 seconds before requesting block information is recommended. 32 | 33 | If confirmation has still not been seen on the block, the [block_confirm](/commands/rpc-protocol#block_confirm) RPC can be called. This will cause the following: 34 | 35 | * If the block is confirmed, it will trigger a notification through the WebSocket and HTTP Callbacks, and the block hash will also appear in the [confirmation_history](/commands/rpc-protocol/#confirmation_history) RPC (recommended for debug purposes only). 36 | * If the block is not in active elections, it will start an election which should result in confirmation and related notifications. 37 | * If the block is already in active elections, it will not have an effect and confirmation should eventually occur along with related notifications. 38 | 39 | Once [block_confirm](/commands/rpc-protocol#block_confirm) is called, a notification of confirmation through the WebSocket should be expected and if not received, then calling [block_info](/commands/rpc-protocol#block_info) RPC to check for confirmation again can be done. Escalation of potential delays in confirmation can be done after this point in external systems as necessary. 40 | 41 | ### Account frontier confirmation status 42 | 43 | For some systems the starting point for checking block status may be the account, such as when a user views their account. The following process is recommended when the account is known and the confirmation status of the frontier block is desired. 44 | 45 | 1. Call [account_info](/commands/rpc-protocol/#account_info) RPC to get current frontier hash 46 | 1. Call [block_info](/commands/rpc-protocol#block_info) for the frontier hash and check if `confirmed` = `true` 47 | 48 | If the block is not confirmed, you can follow a similar process outlined in the [Requesting block confirmation status](#requesting-block-confirmation-status) section above for requesting block confirmation and re-checking confirmation status before escalating in external systems. -------------------------------------------------------------------------------- /docs/running-a-node/overview.md: -------------------------------------------------------------------------------- 1 | title: Running a Node Overview 2 | description: Understand the purpose for running a nano node, the different types of nodes available and what type of maintenance should be expected 3 | 4 | # Running a Node Overview 5 | 6 | Running a node is a key way to help decentralize the network and provide a network access point for systems built on top of nano. Before setting up a node we recommend reviewing the following details in order to understand more about the motivations for running, required upkeep, types and recommended specifications for nodes. 7 | 8 | ## Why run a node? 9 | By design, the incentives for running a nano node are not built into the network itself, but instead are external. This is an important difference compared to nearly all other cryptocurrency networks and allows nano to operate securely without transaction fees.[^1][^2] These indirect, external incentives include the following and more: 10 | 11 | * Advertising exposure from their representative showing up on curated representative lists 12 | * Transaction fee savings for businesses and organizations accepting nano as payment 13 | * Helping support and further decentralize a global payment network 14 | * Having a trusted access point for building additional software on the network 15 | 16 | Regardless of the motivation for running a node, it will only benefit the network if proper care is taken to ensure it is run on correctly provisioned machines and ongoing maintenance of the node, OS and any supporting systems are routinely done. 17 | 18 | ## Node types 19 | 20 | --8<-- "dedicated-representative-nodes.md" 21 | 22 | !!! tip "Review Node security guide" 23 | Regardless of the type of node you are planning to run, make sure to review the [Node security guide](security.md) to ensure best practice with configuration, firewalls and more. 24 | 25 | ### Non-voting nodes 26 | When first setting up a node it will not be configured to participate in consensus by voting on traffic. This type of node is common and is recommended for all integrations. If your goal in setting up a node is to learn how to integrate and use nano for payments, this is the best starting point. If you want to dedicate resources to help secure consensus on the network, then a Representative node should be explored. 27 | 28 | !!! info "Representatives and voting" 29 | For a very brief overview of how representatives and voting works in the nano network, see the [What is nano? page](../what-is-nano/overview.md#representatives-and-voting). If you're looking to dig deeper, the [ORV consensus section of the living whitepaper](../protocol-design/orv-consensus.md) helps explain further how consensus works. 30 | 31 | ### Representative nodes 32 | If a node is setup with a Representative account, is configured to vote and has **less than 0.1% of [online voting weight](/glossary#online-voting-weight)** delegated to them, they are a considered Representative node. These nodes will validate and vote on transactions seen on the network. Their votes will be directly sent to a subset of their peers, but other nodes on the network will not rebroadcast their votes. 33 | 34 | ### Principal Representative nodes 35 | Representative nodes with **at least 0.1% of the [online voting weight](/glossary#online-voting-weight)** delegated to them participate more broadly in network consensus because votes they send to their peers are then rebroadcasted by those nodes as well. These "PR" nodes have the most impact to the security and availability of the network so [keeping them secure](security.md) and following [maintenance recommendations](#maintenance) should be taken seriously. 36 | 37 | !!! success "Becoming a Principal Representative" 38 | With the ability for any user on the network to redelegate their voting weight, even an account with no weight today can become a Principal Representative over time. 39 | 40 | ## Hardware recommendations 41 | 42 | Nodes consume CPU, RAM, disk IO and bandwidth IO resources, all of which come at a cost. In order to keep the node participating and in-sync, the recommended specifications for machines based on node type below should be followed. 43 | 44 | --8<-- "hardware-recommendations.md" 45 | 46 | ## Maintenance 47 | 48 | --8<-- "join-technical-mailing-list.md" 49 | 50 | With any system, ongoing maintenance must be taken into account to avoid issues. The following are a few examples of regular activities that should be committed to, especially when running a [Representative](#representative-nodes) or [Principal Representative](#principal-representative-nodes) node: 51 | 52 | - Performing OS-level updates and security patches regularly applied 53 | - Upgrading to the [latest node versions](../releases/node-releases.md) as they are available 54 | - Following best practices for securing passwords or other sensitive data related to the node 55 | 56 | Without taking care of the security and maintenance of systems hosting the node, any benefit to the network could be lost. Continue learning about how best to keep the node secure in our [Node security guide](security.md). 57 | 58 | [^1]: https://medium.com/nanocurrency/the-incentives-to-run-a-node-ccc3510c2562 59 | [^2]: https://medium.com/@clemahieu/emergent-centralization-due-to-economies-of-scale-83cc85a7cbef 60 | -------------------------------------------------------------------------------- /docs/what-is-nano/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: What is nano? 3 | description: A broad introduction to nano - the instant, fee-less and eco-friendly digital money available across the world 4 | hide: 5 | - navigation 6 | - toc 7 | --- 8 | 9 | # What is nano? 10 | 11 | Nano is a digital payment protocol designed to be accessible and lightweight, with a focus on removing inefficiencies present in other cryptocurrencies. With ultrafast transactions and zero fees on a secure, green and decentralized network, this makes Nano ideal for everyday transactions. 12 | 13 | ### How do transactions work? 14 | 15 | Nano utilizes the [Block Lattice](/glossary#block-lattice), a data-structure in which individual accounts control their own blockchain. This allows blocks to be added quickly without conflict and sent to the network for confirmation. 16 | 17 | Transactions occur between accounts with two separate actions: 18 | 19 | 1. The sender publishes a block debiting their own account for the amount to be sent to the receiving account 20 | 1. The receiver publishes a matching block crediting their own account for the amount sent 21 | 22 | Once a block sending funds is confirmed by the network, the transaction goes into a [receivable](/glossary#receivable) state and cannot be reversed. The receiver can be offline and safely leave the funds in this state until they are ready to publish a matching block receiving the funds to their account. 23 | 24 | ### Lightweight, stateful blocks 25 | 26 | Nano uses a structure for each block which contains all the information about an account at that point in time: account number, balance, representative. 27 | 28 | Every block must also contain a small, user-generated [Proof-of-Work](/glossary#proof-of-work-pow) value which is a Quality-of-Service prioritization mechanism allowing occasional, average user transactions to process quickly and consistently. The PoW computation for a transaction typically takes a few seconds on a modern desktop CPU. 29 | 30 | For more details, see the [Blocks](/integration-guides/the-basics/#blocks-specifications) and [Proof-of-Work specifications](/integration-guides/the-basics/#proof-of-work) in our [Integration Guides](/integration-guides/the-basics/). 31 | 32 | ### Representatives and Voting 33 | Nano has a unique consensus mechanism called [Open Representative Voting (ORV)](/glossary/#open-representative-voting-orv). Every account can freely choose a [Representative](/glossary#representative) at any time to vote on their behalf, even when the delegating account itself is offline. These Representative accounts are configured on nodes that remain online and vote on the validity of transactions they see on the network. Their voting weight is the sum of balances for accounts delegating to them, and if they have enough voting weight they become a [Principal Representative](/glossary/#principal-representative). The votes these Principal Representatives send out will subsequently be rebroadcasted by other nodes. 34 | 35 | As these votes are shared and rebroadcasted between nodes, they are tallied up and compared against the online voting weight available. Once a node sees a block get enough votes to reach [quorum](/glossary/#quorum), that block is confirmed. Due to the lightweight nature of blocks and votes, the network is able to reach confirmation for transaction ultrafast, often in under a couple seconds. Also note that delegation of voting weight does not mean staking of any funds - the account delegating can still spend all their available funds at any time without restrictions. 36 | 37 | Because Nano accounts can freely delegate their voting weight to representatives at any time, the users have more control over who has power with consensus and how decentralized the network is. This is a key advantage to the design of [Open Representative Voting (ORV)](/glossary/#open-representative-voting-orv). With no direct monetary incentive for nodes, this removes emergent centralization forces for longer-term trending toward decentralization of the network.[^1] 38 | 39 | ### Design Advantages 40 | Nano was designed with new data structures, consensus mechanisms and other features to gain some key advantages over competing digital currencies: 41 | 42 | * Minimal block size allows for lightweight communication resulting in ultrafast transaction confirmation times 43 | * Without traditional Proof-of-Work and mining, nodes use significantly less energy per transaction than other popular networks 44 | * Emergent centralization forces for node operators are reduced due to the near zero marginal cost of producing consensus in Nano [^1] 45 | 46 | --- 47 | 48 | ### Exploring More 49 | 50 | * Looking for technical details of the protocol and node design? Check out the [Living Whitepaper](../living-whitepaper/index.md) 51 | * Ready to participate on the network? Try [running a node](/running-a-node/overview), [review integration options](/integration-guides/the-basics) or find commands via [RPC](/commands/rpc-protocol) and [CLI](/commands/command-line-interface) 52 | * Want to know the future of Nano? See the [upcoming features](/releases/upcoming-features/) for the node or help shape the future by [contributing to the development of the protocol](/node-implementation/contributing) if you can! 53 | * Want to explore less technical aspects of Nano or join our community? Head over to [Nano.org](https://nano.org) 54 | 55 | [^1]: https://medium.com/@clemahieu/emergent-centralization-due-to-economies-of-scale-83cc85a7cbef 56 | -------------------------------------------------------------------------------- /docs/running-a-node/advanced-monitoring.md: -------------------------------------------------------------------------------- 1 | title: Advanced Monitoring 2 | description: Learn how to install advanced monitoring to keep an eye on your nano node using a Prometheus-based agent 3 | 4 | # Advanced Monitoring 5 | 6 | For keeping a closer watch on node performance a Prometheus-based exporter monitoring solution is available. It provides an easy way to automatically gather and export a multitude of stats and metrics from the node RPC, as well as from the machine running the exporter. For added security, the exporter doesn't require opening any additional inbound ports as the metrics are pushed out to a Prometheus push gateway, which can be hosted externally. 7 | 8 | Prometheus is an open-source systems monitoring and alerting toolkit. For a brief overview of everything it offers, see [What is Prometheus?](https://prometheus.io/docs/introduction/overview/) 9 | 10 | !!! tip "Basic monitoring option" 11 | For a simpler monitoring setup that is maintained by the Nano community and provides a public website to view details on, see the [monitoring details on the Voting as a Representative page](voting-as-a-representative.md#setup-monitoring). 12 | 13 | ## Recommended architecture 14 | 15 | The diagram below illustrates a recommended architecture of components: 16 | 17 | ![Nano node Prometheus exporter architecture](../images/nano-prometheus-exporter-architecture.png) 18 | 19 | This configuration was recommended as it splits the concerns across two servers: one hosting the node and exporter, with another hosting the push gateway, Prometheus server and graphing/visualization tools. However, there are a variety of configuration options to allow separation of each component onto different servers, depending on the needs. 20 | 21 | ## Installation 22 | 23 | The following provides the basic details for installing and connecting the components outlined above. 24 | 25 | ### Step 1: Setup and configure Nano node 26 | 27 | These configuration options are set in the [`config-node.toml` file](../running-a-node/configuration.md#configuration-file-locations). 28 | 29 | * Get a [Nano node setup](node-setup.md) with Docker or binaries 30 | * Update config `node.rpc.enable` = `true` 31 | * If you want to gather [`nano_stats_objects*` metrics](https://github.com/nanocurrency/nano_prom_exporter#stats-exposed), update config `rpc.enable_control` = `true` 32 | * Restart the node for settings to take effect 33 | 34 | ### Step 2: Install Prometheus push gateway 35 | 36 | For the best security, it is recommended to run this on a separate server. By default this will need to accept incoming connections from the exporter on TCP port `9091`. 37 | 38 | * Requires [python 3.7+](https://www.python.org/) 39 | * Download and run the [prometheus-pushgateway](https://github.com/prometheus/pushgateway/blob/master/README.md#run-it) 40 | * Accept incoming TCP port `9091` connections from the node/exporter server 41 | 42 | ### Step 3: Install and run the Nano node exporter 43 | 44 | Typical configurations will have the exporter running on the same server as the node. If so, `--rpchost` is local as noted below. 45 | 46 | **Install via pip** 47 | 48 | `pip install nano-prom-exporter` 49 | 50 | **Example run command** 51 | 52 | ```shell 53 | nano-prom -h --rpchost ::1 \ 54 | --rpcport 7076 \ 55 | --datapath ~/Nano/Nano \ 56 | --pushgateway your-exporter-and-node.server.org:9091 \ 57 | --hostname MyNanoMetrics 58 | ``` 59 | 60 | See the [README](https://github.com/nanocurrency/nano_prom_exporter) for more details on usage. 61 | 62 | ### Step 4: View your metrics 63 | 64 | To validate data is available from the exporter, the `/targets` endpoint on port `9090` at the URL of the push gateway will show job health: `http://your-new.monitor.org:9090/targets`. The endpoint pushing the data should have `State` = `UP` if everything is working well. 65 | 66 | There is also a `/graph` endpoint to do some manual querying of available data: `http://your-new.monitor.org:9090/graph` 67 | 68 | ### Step 5: Install Grafana 69 | 70 | Once you've verified metrics are properly being captured, you can setup visualization amd analysis solutions. One popular option is Grafana, which can be installed from here: https://grafana.com/grafana/download. 71 | 72 | If Grafana is being installed on a different server from the Promethus push gateway TCP port `9090` will need to be opened as well. 73 | 74 | Once running, a sample file can be used from our repository to kickstart your dashboard setup: https://github.com/nanocurrency/nano_prom_exporter/blob/master/sample-grafana-dashboard.json. 75 | 76 | Other options can be explored in the [Visualization](https://prometheus.io/docs/visualization/browser/) section of the Prometheus site. 77 | 78 | ## Connecting to other push gateways 79 | 80 | The exporter supports sending metrics to multiple push gateways using a `config.ini` file and the `--config_path` option in the command to accept the location. Within this file the authentication can be managed between different endpoints and support for selecting specific metrics per push gateway will added soon. See the [README](https://github.com/nanocurrency/nano_prom_exporter) for more details on usage. 81 | 82 | Although no public push gateways for node monitoring are available at this time, there may be opportunities in the future to share your node metrics with the community or other monitoring setups to provide a better view of network performance. Check back here and keep an eye out for these public gateways to become available. 83 | 84 | And if you know of any public push gateways available to send this useful node data to, [please let us know](https://nano.org/connect). 85 | -------------------------------------------------------------------------------- /docs/core-development/collaboration-process.md: -------------------------------------------------------------------------------- 1 | title: Collaboration Process 2 | description: Find out how the open source collaboration process works with the nano protocol and node software 3 | 4 | # Collaboration Process 5 | 6 | ## Code Process 7 | 8 | **Fork and do all your work on a branch** 9 | 10 | Nano prefers the standard GitHub workflow. You create a fork of the nanocurrency/nano-node repository (or other repositories as needed), make changes on new branches for features/fixes, and push these up to be added as Pull Requests. 11 | 12 | **Create pull requests** 13 | 14 | Before: 15 | 16 | * Branch out of the **develop** branch. The **master** branch is only updated on new releases. 17 | * Review your code locally. Have you followed the [Code Standards](code-standards.md) closely? 18 | * Run tests: `core_test`,`qt_test`,`rpc_test` (see [running tests](understanding-the-code.md#tests) for more details). Did you consider adding a test case for your feature? 19 | * Run [ASAN](../integration-guides/build-options.md#address-sanitizer), [TSAN](../integration-guides/build-options.md#thread-sanitizer) and [Valgrind](../integration-guides/build-options.md#valgrind) to detect memory, threading or other bugs 20 | * Run clang formatting script and resolve any raised issues: `ci/clang-format-do.sh` 21 | * Commit and push your fork branch 22 | 23 | After: 24 | 25 | * Create pull request on the upstream repository: 26 | * Make sure you add a description that clearly describes the purpose of the PR. 27 | * If the PR solves one or more issues, please reference these in the description. 28 | * Check that CI completes successfully - this can take up to a few hours depending on current CI queues. If any failures exist, fix the problem and push an update. 29 | * Respond to comments and reviews in a timely fashion. 30 | 31 | **Resolve conflicts** 32 | 33 | If time passes between your pull request (PR) submission and the team accepting it, merge conflicts may occur due to activity on develop, such as merging other PR's before yours. In order for your PR to be accepted, you must resolve these conflicts. 34 | 35 | The preferred process is to rebase your changes, resolve any conflicts, and push your changes again. [^1][^2] 36 | 37 | * Check out your branch 38 | * `git fetch upstream` 39 | * `git rebase upstream/develop` 40 | * Resolve conflicts in your favorite editor 41 | * `git add {filename}` 42 | * `git rebase --continue` 43 | * Commit and push your branch 44 | 45 | **Consider squashing or amending commits** 46 | 47 | In the review process, you're likely to get feedback. You'll commit and push more changes, get more feedback, etc. 48 | 49 | This can lead to a messy git history, and can make stuff like bisecting harder. 50 | 51 | Once your PR is OK'ed, please squash the commits into a one.[^3] 52 | 53 | Note that you can also update the last commit with `git commit --amend`. Say your last commit had a typo. Instead of committing and having to squash it later, simply commit with amend and push the branch. 54 | 55 | ## Finding issues or features to work on 56 | 57 | - Issues are available on GitHub, with the most urgent being in the latest milestone for release 58 | - Start with issues labeled as [`good first issue`](https://github.com/nanocurrency/nano-node/labels/good%20first%20issue) or connect with the NF core developers on [Discord](https://chat.nano.org) or the [forum](https://forum.nano.org) for ideas on how to help 59 | - If you find an issue you'd like to help with, comment and tag a [Nano Foundation team member](https://github.com/orgs/nanocurrency/people) who can evaluate and assign it to you 60 | 61 | ## Submitting issues and feature requests 62 | 63 | Standard GitHub templates exist for submitting any found issues or feature requests. If you plan on working on a bug or feature that doesn't already have a GitHub Issue associated with it, please submit it first so the team is aware. See https://github.com/nanocurrency/nano-node/issues/new/choose for templates. 64 | 65 | ## Discussion channels 66 | 67 | Various channels exist for discussing code changes with the Nano Foundation and community. 68 | 69 | **GitHub** 70 | 71 | To help persist useful information about a particular issue or feature, it is best to discuss within the related GitHub Issue or Pull Request. Members of the nano community and Nano Foundation actively follow and will engage when available. 72 | 73 | **Discord for chat** 74 | 75 | For live chat, join the server at https://chat.nano.org and check out the `#protocol` and `#development` channels. The various channels under the `TESTING` section can also be helpful to follow. 76 | 77 | **Forum** 78 | 79 | Another area for technical and code related discussions is the [forum](https://forum.nano.org). There are categories for `Protocol Design` and `Development` that are useful in discussing ideas. This can be a great place for getting feedback on ideas and exploring further before finalizing fixes and features in GitHub. 80 | 81 | ## Proposals 82 | 83 | There currently is no formal process for proposals on the nano network. This is an area actively being investigated and if requirements for submissions change, this area will be updated. For now, if you wish to propose an new idea, it is recommended to discuss on the [forum](https://forum.nano.org) first to gather feedback and use the [GitHub Issues](https://github.com/nanocurrency/nano-node/issues/new/choose) on the concept is solidifed/validated. 84 | 85 | [^1]: https://help.github.com/articles/resolving-merge-conflicts-after-a-git-rebase/ 86 | [^2]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ 87 | [^3]: https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit -------------------------------------------------------------------------------- /docs/running-a-node/security.md: -------------------------------------------------------------------------------- 1 | title: Node Security 2 | description: Information about how to properly secure your nano node when getting setup on the network 3 | 4 | # Node Security 5 | 6 | There are [many reasons to run a Nano node](/running-a-node/overview/#why-run-a-node) on the network. Nodes are the participants that help vote on transaction validity, assist other nodes with bootstrapping blocks in the ledger and providing an access point to all accounts. But those who choose to run them should be making a long-term commitment to [run them on proper hardware](/running-a-node/node-setup/#hardware-recommendations), keep them updated with the [latest release](/releases/node-releases/) and, most importantly, keep their setup as secure as possible. 7 | 8 | --8<-- "join-technical-mailing-list.md" 9 | 10 | The details below are guidelines on things to watch out for when setting up and securing your Nano node. As the node can be run on many different operating systems, some of these guidelines have been kept more general. There are plenty of resources online for learning how to apply these guidelines to more specific setups and additional details will be included in the docs here as they are appropriate. 11 | 12 | ## Node configuration 13 | 14 | ### Enabling control 15 | 16 | Various RPC calls are marked as requiring the `enable_control` option to be turned on before they can be called. This extra level of permission to use these RPCs was put in place because the calls can be dangerous in a couple ways: 17 | 18 | * They can potentially allow access to wallet funds 19 | * They can consume extra node resources compared to other calls, such as using more disk space or requiring additional computation to complete 20 | 21 | By turning `enable_control` on, anyone with access to your RPC can run these potentially dangerous commands, so it is only recommended with [port configurations](#port-configuration) where RPC access is restricted to local and loopback addresses only. If your RPC is exposed to external or non-loopback addresses, the node will print out warnings to `stdout` and your logs to help make you aware of potential exposure. 22 | 23 | ### Port configuration 24 | 25 | Opening default port `7075` on TCP is required for the node to participate on the main network and this should be done unrestricted. The default port for RPC access is `7076` and should only be available to those you wish to have control of the node. Verifying the configuration in `config-rpc.toml` file for `address` and `enable_control` should be done on all nodes, alonside other access verifications outlined below. 26 | 27 | !!! danger "Opening RPC port externally and enabling control is potentially dangerous" 28 | As mentioned above, enabling control allows anyone with RPC access to make potentially dangerous calls to your node. If turning on `enable_control`, you must carefully review any access granted to the RPC port (default `7076`) to ensure it is as secure as possible. 29 | 30 | ## Firewalls 31 | 32 | There are various firewall options available across operating systems. IPTables, PeerBlock, Windows Firewall and others allow you to better control access to your host machine and thus your node. By having a firewall in place you can completely block unused and unnecessary ports, as well as whitelist other ports for access only from trusted IP addresses. Using this in combination with good [server access](#server-access) and [port configuration](#port-configuration) practices helps harden your node setup even further. 33 | 34 | ## Server access 35 | 36 | Due to the node currently processing all transactions, keeping them running and online as much as possible is recommended, so many operators use dedicated servers or shared servers, often in data centers or cloud providers. When running node on a remote machine, access to that machine should be tightened up in various ways. Some common tips are included below which may or may not apply to your specific system: 37 | 38 | * Use private/public key pairs exclusively for authentication over SSH, which involves disabling password-based authentication 39 | * Disable root login entirely 40 | * Disable remote logins for accounts with an empty password 41 | * Change default SSH port 42 | * Use a [firewall](#firewalls) to whitelist IP access to SSH connections 43 | * Set timeouts for idle SSH connections 44 | * Get setup to block SSH brute force attempts automatically with tools like Fail2ban 45 | * Limit the maximimum authentication attempts allowed 46 | * Setup alerts and monitoring for SSH connections 47 | 48 | Using a variety of these control measures for server access can increase your resistance to unauthorized access to your host machine and help protect your node from interference. 49 | 50 | ## Maintenance 51 | 52 | As always the machine hosting the node should have regular maintenance done such as security patches, updates, etc. See [Maintenance](overview.md#maintenance) for more details. 53 | 54 | ## Docker considerations 55 | 56 | When running a node in Docker there is an extra layer of port controls between the node in the Docker container and the host machine. The default node configuration provided with Docker images in [Docker hub](https://hub.docker.com/r/nanocurrency/nano), along with examples in our documentation [for commands such as `docker run`](/running-a-node/docker-management/#starting), result in allowing RPC access only to the machine hosting the container. This is the recommended setup for most nodes. 57 | 58 | To make sure Docker security is understood by any node operator and the setup used is as secure as possible, we recommend reading up on general best practices for using Docker, consider [running Docker with non-root USER](/running-a-node/docker-management/#docker-user-support) and verifying external access to RPC calls are controlled sufficiently by the Docker host machine. 59 | -------------------------------------------------------------------------------- /docs/releases/release-v25-0.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V25.0 nano node 2 | description: Details of the V25.0 nano node release including upgrade notices, major features, API changes and more 3 | 4 | # V25.0 5 | 6 | --8<-- "release-details-v25-0.md" 7 | 8 | ## Upgrade notices 9 | 10 | All nodes are encouraged to upgrade to V25.0 including exchanges. 11 | 12 | In general, exchanges, services and integrations are encouraged to join [the test network](../running-a-node/test-network.md) for performing integration testing. This network mimics the live network in work requirements but has a smaller number of nodes and a lower block count for easier setup. 13 | 14 | ### Database upgrade 15 | 16 | This version no longer stores unchecked data in the database. The data is now held in memory, resulting in reduced storage access and mitigated database growth. As a result of this change, an upgrade will be performed on the database to eliminate the unchecked table. This upgrade is applicable to both database types, LMDB and RocksDB. 17 | 18 | ### Minor RPC breaking changes 19 | The following RPC calls have undergone minor breaking changes: `accounts_balances`, `accounts_frontiers`, and `accounts_representatives`. These changes address the issue where an error is returned for the entire response when at least one of the requested accounts results in an error. 20 | 21 | The fix was initially introduced in [V24.0](release-v24-0.md#rpc-updates), but it inadvertently disrupted the `accounts_balances` RPC by breaking the default zero balance and zero receivable response when the account is not found in the ledger. Additionally, the absence of the error message within a specific entry disrupts the established JSON format. 22 | 23 | If your integrations use these RPC calls, we strongly recommend carefully reviewing the additional details on these changes included in the [RPC Updates](#rpc-updates) section below. Please note that another disruption may occur: if all the requested account keys result in errors, there will be only the entry `errors`. 24 | 25 | ### Minor breaking change for PoW 26 | 27 | The Proof-of-Work (PoW) server is no longer bundled within the docker artifact. 28 | 29 | --- 30 | 31 | ## Major updates 32 | 33 | ### Adding the ascending bootstrap client 34 | In [V24](release-v24-0.md#ascending-bootstrap) the server components and network messages were added. In V25, the bootstrap client is added, enabling it to finally work on the nano node software. This leads to several improvements which reduce socket usage, lighten the burden on the unchecked table by pulling blocks in an ascending manner instead of descending, allows the unchecked table to exist entirely in memory, reduces bandwidth and isolates the bootstrapping logic from the rest of the node. 35 | 36 | The client also uses a priority-weighted tracing algorithm to pull successive iterations of blocks from peers, which further improves the efficiency of the syncing process. Overall, these improvements significantly reduce the time it takes for a new node to sync with the rest of the network. 37 | 38 | ### Optimistic elections 39 | This is a major change that improves the efficiency and speed of the election process. When a node is starting up, it needs to confirm a large number of blocks, and this process can take a long time. Currently, the node confirms blocks one by one. The new feature randomly selects an account with unconfirmed blocks and confirms the latest unconfirmed block in the account chain, which speeds up the process. This feature is limited to 500 elections and does not replace the current method. It's a simple algorithm but makes a big difference in the efficiency of the process. This should significantly increase the speed of node syncing. 40 | 41 | ### Complete removal of UDP channel implementation 42 | The nano protocol was originally written using UDP and later transitioned to TCP. In the V24 release, most of the UDP protocol code was already removed. In V25, the remaining of it has been removed from the network channels, leaving the only implemented transport layer to be the TCP protocol. It enabled some other removals like the message buffer class and other code that was already unuseful since the UDP deprecation. 43 | 44 | ### Bug fixes 45 | Several bugs were fixed, including issues with counting successes/failures, updating token buckets, and race conditions. 46 | 47 | ### Enhancements 48 | Several enhancements were made to the Nano node software, including improved stat counters, refactoring of the election vote process, and cleaning up of stat counters for active transactions. 49 | 50 | ### Build, Text, Automate, Cleanup & Chores 51 | The V25 version of the Nano node software includes several updates related to build, test, automation, cleanup, and chores. These updates include improvements to the unit test chains setup, fixing sign comparison mismatches, removing unnecessary "usings," disambiguating implemented locks, and more. Additionally, the minimum required OSX version has been increased to 10.15, and the IPv6 socket is now specified for IPv4 communication. 52 | 53 | --- 54 | 55 | ## RPC updates 56 | 57 | * The RPCs [`account_balances`](https://docs.nano.org/commands/rpc-protocol/#accounts_balances), [`accounts_frontiers`](https://docs.nano.org/commands/rpc-protocol/#accounts_frontiers), and [`accounts_representatives`](https://docs.nano.org/commands/rpc-protocol/#accounts_representatives) have been fixed to return errors within an `errors` entry. Additionally, the `accounts_balances` RPC has been updated to return zero balance and zero receivable when an account is not found in the ledger. 58 | 59 | --- 60 | 61 | ## Deprecations/Removals 62 | 63 | * JSON serializing of config files are not supported anymore 64 | * Removed some stat types related to UDP 65 | * Removed live updating bandwidth limits: this change was made to fix a thread safety issue. It may be reverted if config reloading gets fully implemented 66 | 67 | --- 68 | 69 | ## Ledger & Database 70 | * The unchecked table was removed from LMDB and RocksDB 71 | * RocksDB now supports database upgrades 72 | * RocksDB was updated to version 7.8.3 73 | 74 | --- 75 | 76 | ## Builds and commands 77 | 78 | --8<-- "current-build-links-main.md" 79 | -------------------------------------------------------------------------------- /docs/running-a-node/voting-as-a-representative.md: -------------------------------------------------------------------------------- 1 | title: Voting as a Representative 2 | description: A comprehensive guide for getting your nano node to participate in consensus on the network by voting as a representative 3 | 4 | # Voting as a Representative 5 | 6 | The default [node setup](node-setup.md) guide provides instructions for getting a non-voting node setup, but if you're looking to run a [Representative node](overview.md#representative-nodes), and perhaps hoping to become a [Principal Representative](overview.md#principal-representative-nodes), the node will need to be configured to vote and be setup with a Representative account. 7 | 8 | --8<-- "join-technical-mailing-list.md" 9 | 10 | Before getting into the setup instructions, there are a few important considerations: 11 | 12 | ## Commitment, security and maintenance 13 | Running a Nano Representative is a commitment to helping secure the network. This can only be done if the operation of the node is taken seriously. 14 | 15 | * Prepare for the necessary [maintenance](overview.md#maintenance) on the node and host machine 16 | * Carefully review the [security guide](security.md) and follow general security best practices at all times 17 | * Ensure you are prepared for the time and cost commitments of maintaining the node over the long term to help maximize the benefits 18 | 19 | ## Hardware recommendations 20 | 21 | --8<-- "hardware-recommendations.md" 22 | 23 | ## Synced ledger 24 | In order to open a new account to become a representative, the local node ledger must be in sync with the rest of the network. If you are starting a fresh node and bootstrapping, this process can take days to complete, depending on the network conditions, hardware specifications, etc. To speed this up, a [downloaded ledger](ledger-management.md#downloaded-ledger-files) can be used if necessary. 25 | 26 | --- 27 | 28 | ## Step 1: Enable voting 29 | For the node to start voting, the following [configuration](configuration.md) options need to be updated: 30 | 31 | --8<-- "config-node-option-node-enable-voting-true.md" 32 | 33 | --8<-- "config-node-option-rpc-enable-true.md" 34 | 35 | #### enable_control 36 | 37 | --8<-- "config-node-option-rpc-enable-control-true.md" 38 | 39 | --- 40 | 41 | ## Step 2: Setup Representative account 42 | 43 | Add a representative account to a wallet: 44 | 45 | 1. Use [wallet_create](../commands/rpc-protocol.md#wallet_create) RPC, optionally with `seed` if you already know your representative account’s seed 46 | 1. One of the following: 47 | - [wallet_add](../commands/rpc-protocol.md#wallet_add) RPC, if you have a private key and didn’t have a seed before 48 | - [account_create](../commands/rpc-protocol.md#account_create) RPC if you had a seed or are creating a new representative account 49 | 1. Verify the account is in the wallet with [account_list](../commands/rpc-protocol.md#account_list) 50 | 51 | 52 | Open the account - until you do [account_info](../commands/rpc-protocol.md#account_info) and others will fail: 53 | 54 | 1. Send some funds to the account, at least 0.01 Nano 55 | 1. Use [search_pending](../commands/rpc-protocol.md#search_pending) to make the wallet open the account automatically 56 | 1. Use [account_info](../commands/rpc-protocol.md#account_info) to verify the state of the account 57 | - If the account is still not open, use [receive](../commands/rpc-protocol.md#receive) as a backup 58 | 59 | --- 60 | 61 | ## Step 3: Restart the node and check voting 62 | 63 | Before the node will vote, the representative account configured above must have at least 1000 Nano delegated to it. This is done by changing the representative of other accounts in your wallet with [account_representative_set](../commands/rpc-protocol.md#account_representative_set). If you do not control over 1000 Nano, you will need to have others delegate their weight to your representative. 64 | 65 | Once you have enough weight, after a few minutes you can search for your representative account on [BlockLattice.io](https://blocklattice.io/), [Nano.community](https://nano.community/), or [NanoCharts.info](https://nanocharts.info/) to verify it is voting. 66 | 67 | --8<-- "warning-multiple-node-setups.md" 68 | 69 | ## Step 4 (Optional): Disable RPC control commands for more security 70 | 71 | `enable_control` was only needed to create the account which the Representative uses to vote. It is not actually needed for voting. Therefore there is no need to actually keep it active after the node is prepared for voting. 72 | 73 | --8<-- "config-node-option-rpc-enable-control-false.md" 74 | 75 | ## Step 5: Monitoring and more 76 | 77 | Congratulations on getting your representative setup! If you are able to do a good job maintaining the node and keeping it performing well, you may have a chance at becoming a [Principal Representative](overview.md#principal-representative-nodes). To reach this higher level of participation in consensus, you must get at least 0.1% of [online voting weight](/glossary#online-voting-weight) delegated to your node. After that any votes you send for transactions will be rebroadcast by other nodes to help with consensus even more. 78 | 79 | Once you are comfortable with your node setup and want to connect it to the broader Nano ecosystem, there are a few recommended options: 80 | 81 | ### Setup monitoring 82 | 83 | Details for setting up a popular monitoring service for the node can be found at https://github.com/NanoTools/nanoNodeMonitor. Not only can this provide a website for viewing the status and promoting your representative, but it also provides metrics to popular services in the ecosystem who help monitor the broader network status and performance, such as [BlockLattice.io](https://blocklattice.io/), [Nano.community](https://nano.community/), and [NanoCharts.info](https://nanocharts.info/). 84 | 85 | ### Connect with community services 86 | 87 | At nano.community [[1]](https://github.com/mistakia/nano-community/blob/main/data/nano-reps.csv)[[2]](https://nano.community/cli) you can also verify your representative and share additional details about your social accounts. Many community members use this service to evaluate representatives which can help you get additional weight if your setup is reliable and well maintained. 88 | 89 | ### Ongoing maintenance and support 90 | 91 | As you continue maintaining your representative there are great community resources available for support: 92 | 93 | * Ask questions in the [Node and Representative Management](https://forum.nano.org/c/node-and-rep/8) category of the Nano Forum 94 | * Connect on the [Nano Discord server](https://chat.nano.org) for discussion around node maintenance 95 | * Join our [Technical Updates Mailing List](http://eepurl.com/gZucL1) to stay updated on releases, network upgrade details and more 96 | -------------------------------------------------------------------------------- /docs/stylesheets/extras.css: -------------------------------------------------------------------------------- 1 | 2 | [data-md-color-scheme="nano"] { 3 | --md-primary-fg-color: #4a90e2; 4 | --md-primary-fg-color--light: #F4FAFF; 5 | --md-primary-fg-color--dark: #000034; 6 | 7 | --md-footer-bg-color: #000034; 8 | 9 | } 10 | 11 | [data-md-color-scheme="slate"] { 12 | --md-primary-fg-color: #000034; 13 | --md-primary-fg-color--light: #F4FAFF; 14 | --md-primary-fg-color--dark: #000034; 15 | 16 | --md-footer-bg-color: #000034; 17 | 18 | --md-hue: 240; 19 | 20 | --md-typeset-a-color: #4a90e2; 21 | 22 | --md-code-bg-color: #2E2E3E; 23 | 24 | } 25 | 26 | .md-annotation__index { 27 | background-color: #4a90e2; 28 | } 29 | 30 | [data-md-color-scheme="slate"] .md-tooltip { 31 | 32 | background-color: var(--md-primary-fg-color); 33 | 34 | } 35 | 36 | [data-md-color-scheme="slate"] .mermaid-wrapper { 37 | background-color: var(--md-default-fg-color--light); 38 | } 39 | 40 | [data-md-color-scheme="slate"] .mermaid-wrapper a { 41 | color: var(--md-primary-fg-color); 42 | } 43 | 44 | [data-md-color-scheme="slate"] .md-tabs { 45 | width: 100%; 46 | overflow: auto; 47 | color: var(--md-primary-bg-color); 48 | background-color: rgb(0 0 52 / 30%); 49 | transition: background 250ms; 50 | } 51 | 52 | [data-md-color-scheme="slate"] .md-header { 53 | position: -webkit-sticky; 54 | position: sticky; 55 | top: 0; 56 | right: 0; 57 | left: 0; 58 | z-index: 2; 59 | height: 2.4rem; 60 | color: var(--md-primary-bg-color); 61 | background-color: rgb(0 0 52 / 1.0); 62 | box-shadow: 0 0 0.2rem rgba(0,0,0,0), 0 0.2rem 0.4rem rgba(0,0,0,0); 63 | transition: color 250ms,background-color 250ms; 64 | } 65 | 66 | 67 | [data-md-color-scheme="slate"] .md-announce { 68 | background-color: rgb(0 0 52 / 1.0); 69 | } 70 | 71 | [data-md-color-scheme="slate"] .md-typeset a { 72 | color: hsl(212 72% 62% / 1); 73 | word-break: break-word; 74 | } 75 | 76 | [data-md-color-scheme="slate"] .md-typeset a:focus, .md-typeset a:hover { 77 | color: hsl(212 66% 67% / 1); 78 | } 79 | 80 | [data-md-color-scheme="slate"] .md-main { 81 | flex-grow: 1; 82 | background-color: #1e1f2d; 83 | } 84 | 85 | [data-md-color-scheme="slate"] .md-typeset h1 { 86 | margin: 0 0 1.25em; 87 | color: hsl(0 0% 100% / 0.95); 88 | font-weight: 300; 89 | font-size: 2em; 90 | line-height: 1.3; 91 | letter-spacing: -0.01em; 92 | } 93 | 94 | [data-md-color-scheme="slate"] .md-typeset h5 { 95 | color: rgb(233, 233, 252); 96 | font-size: 0.6rem; 97 | } 98 | 99 | [data-md-color-scheme="slate"] .md-typeset table:not([class]) th { 100 | min-width: 5rem; 101 | padding: .9375em 1.25em; 102 | color: hsl(0 0% 87% / 1); 103 | vertical-align: top; 104 | background-color: hsl(238deg 12% 39%); 105 | } 106 | 107 | [data-md-color-scheme="slate"] .md-footer-nav { 108 | background-color: #1f213c; 109 | } 110 | 111 | [data-md-color-scheme="slate"] .md-footer-meta { 112 | background-color: hsl(232deg 22% 15%); 113 | } 114 | 115 | .md-announce__inner a { 116 | color: #F4FAFF !important; 117 | } 118 | 119 | /*.md-container { 120 | background-color: white; 121 | }*/ 122 | 123 | .md-header-nav__button.md-logo img { 124 | display: block; 125 | height: 48px; 126 | width: 120px; 127 | } 128 | 129 | .md-header-nav__button.md-logo { 130 | margin: 0rem; 131 | padding: 0rem; 132 | } 133 | 134 | .md-nav--primary .md-nav__title, .md-nav--secondary .md-nav__title { 135 | background: none; 136 | box-shadow: none; 137 | } 138 | 139 | .md-nav__button img { 140 | width: 50px; 141 | height: 50px; 142 | } 143 | 144 | .md-header-nav__title { 145 | padding-left: 0.6rem; 146 | } 147 | 148 | .md-header__title { 149 | margin-left: 0rem; 150 | } 151 | 152 | /* 153 | .md-header, 154 | .md-footer-nav, 155 | .md-footer-meta { 156 | background-color: #4a90e2; 157 | } 158 | */ 159 | 160 | /* Highlight current page in nav menu */ 161 | .md-nav__link--active { 162 | /*color : #4a90e2;*/ 163 | font-weight: bold; 164 | } 165 | 166 | .md-footer-social { 167 | font-size: 24px; 168 | } 169 | /* 170 | .md-typeset .codehilite pre { 171 | background-color: #EDEFF1; 172 | } 173 | 174 | .md-typeset pre>code { 175 | border-radius: 5px; 176 | background-color: #f2f2f2; 177 | } 178 | */ 179 | 180 | /*tighten up table padding*/ 181 | .md-typeset table:not([class]) td { 182 | padding: 0.6rem 0.6rem; 183 | } 184 | 185 | .md-typeset table:not([class]) th { 186 | padding: 0.6rem 0.6rem; 187 | min-width: 50px; 188 | } 189 | 190 | .md-typeset { 191 | font-size: 0.7rem; 192 | line-height: 1.8; 193 | } 194 | /* 195 | .md-typeset details summary { 196 | font-size: 14px; 197 | } 198 | .md-typeset .admonition-title{ 199 | font-size: 14px; 200 | } 201 | .md-typeset .admonition p{ 202 | font-size: 14px; 203 | } 204 | .md-typeset .admonition ul{ 205 | font-size: 14px; 206 | } 207 | */ 208 | @media (min-width: 768px) { 209 | .md-typeset code { 210 | white-space: pre; 211 | } 212 | } 213 | 214 | .no-break { 215 | white-space: pre; 216 | } 217 | 218 | 219 | .codehilite { 220 | color: #131121; 221 | } 222 | 223 | .codehilite .c1 { 224 | color: #7e7c8e; 225 | } 226 | 227 | /*.md-typeset h1 { 228 | color: #131121; 229 | }*/ 230 | 231 | 232 | .h4-no-toc { 233 | margin: .8rem 0; 234 | font-weight: 700; 235 | letter-spacing: -.01em; 236 | font-size: .8rem; 237 | display: block; 238 | margin-block-start: 1.33em; 239 | margin-block-end: 1.33em; 240 | margin-inline-start: 0px; 241 | margin-inline-end: 0px; 242 | line-height: 1.8; 243 | } 244 | 245 | .md-footer-copyright { 246 | padding: 0.6rem 0 0 0; 247 | } 248 | 249 | .md-footer-disclaimer { 250 | text-align: center; 251 | max-width: 100%; 252 | float:none; 253 | border-top: 1px solid hsla(0,0%,100%,.3); 254 | padding: 0.6rem 0; 255 | } 256 | 257 | .md-grid-disclaimer { 258 | margin-left: 0; 259 | margin-right: 0; 260 | max-width: 100%; 261 | } 262 | 263 | .md-footer-social { 264 | padding: 0; 265 | float:right; 266 | } 267 | 268 | .md-footer-social__link svg { 269 | max-height: 1.2rem; 270 | } 271 | 272 | .md-header__button.md-logo img { 273 | height: 0.9rem; 274 | width: unset; 275 | } 276 | 277 | .md-announce { 278 | background-color: #000034; 279 | } 280 | 281 | @media only screen and (min-width: 45em) { 282 | .md-footer-social { 283 | padding: 0; 284 | } 285 | .md-footer-disclaimer { 286 | width: 100%; 287 | } 288 | } 289 | 290 | @media (min-width: 1600px) { 291 | .md-header-nav__button.md-logo svg { 292 | height: 52px; 293 | } 294 | } -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Nano Protocol Documentation 2 | 3 | `nano-docs` is the source code for the Nano protocol documentation and is built using [MkDocs](https://www.mkdocs.org/) with the [MkDocs Material theme](https://squidfunk.github.io/mkdocs-material/). 4 | 5 | ### Purpose 6 | This documentation focuses on various users within the technical community: advanced users, node operators, developers integrating Nano, and those interested in details around how the protocol works. All efforts to help update the documentation should keep in mind these goals as submissions that fall outside of this scope are likely to be rejected. 7 | 8 | ### Contributing 9 | For users wishing to contribute to this documentation, we recommend you join the Discord (https://chat.nano.org) #documentation channel to keep up to date on the latest activity. GitHub issues will be used to manage requests for changes. It is recommended any navigational changes or larger updates be discussed on the Discord #nano-docs channel or within a GitHub issue before completing work - this will help avoid wasted work that does not align with the documentation goals. 10 | 11 | To submit changes, please fork the repository and create a branch to make changes. Submit a Pull Request back to the source repository when ready for review ahead of possible inclusion. 12 | 13 | ## Development 14 | The recommended local setup is to use Docker with a pre-built image for MkDocs and Material theme. With Docker installed, from the cloned nano-docs directory run: 15 | 16 | ```bash 17 | docker pull ghcr.io/nanocurrency/nano-docs:latest 18 | docker run --rm -it -p 8000:8000 ghcr.io/nanocurrency/nano-docs:latest 19 | ``` 20 | 21 | You can also install MkDocs with Python 3 to serve using the following: 22 | 23 | ```bash 24 | pip3 install -r requirements.txt 25 | mkdocs serve 26 | ``` 27 | 28 | If only reviewing pull requests is required, using a pre-packaged container with all custom theme modifications can be done with the following commands: 29 | ```bash 30 | docker pull ghcr.io/nanocurrency/nano-docs:pr- 31 | docker run --rm -it -p 8000:8000 ghcr.io/nanocurrency/nano-docs:pr- 32 | ``` 33 | 34 | Note that because a local volume isn't being mounted this pull request review approach is only good for validating changes and not for development purposes. These PR-specific containers will be deleted once the related pull request is either closed or merged. If an offline version of the docs are needed, the container tag `latest` is also available and updated on each change to the `master` branch. 35 | 36 | Access the site at http://localhost:8000. This supports automatic rebuilding, so anytime changes are saved to the documentation or configuration, it will be rebuilt and refresh the page. Some search indexing may remain cache between builds. 37 | 38 | ## Formatting and Organization Tips 39 | 40 | ## Title and description 41 | At the top of every page (not snippets) two fields should be added `title: ` and `description: ` which will be converted to values of `` and `<meta>` tags in the header to better inform search engines, social scraping tools and more. 42 | 43 | ### Headers 44 | Pages automatically have a `<h1>` title setup for them based on the page name, so headers `##` (`<h2>`) and higher should only be used to organize the content. 45 | 46 | ### Table of Contents 47 | Currently, the ToC on the right side is limited to a depth of 4, so `##`, `###`, and `####` will be included there. Higher header levels can be used on the page to better organize content but will not be in the ToC. 48 | 49 | ### Links 50 | MkDocs has a link checker built in that can be run using the `--strict` flag on `mkdocs serve`, or `mkdocs build` command. This flag is included in the build pipeline. For it to work, links must be referencing the relative file path with the file extension included and no trailing slashes. Anchors are not included in this check. Although relative URLs will function if used, they will not be verified by the link checker. 51 | 52 | For example, linking from a page in the`running-a-node` folder to `integration-guides` would be: 53 | 54 | * Gets checked: `../integration-guides/the-basics.md`. 55 | * Doesn't get checked: `/integration-guides/the-basics` 56 | 57 | ### Snippets 58 | The `snippets` directory contains reusable pieces of content which can be inserted as follows: 59 | 60 | `--8<-- "snippet-file-name.md"` 61 | 62 | This should be used for simple, duplicated content only and is not a complex templating setup. 63 | 64 | ### Comments 65 | The StripHTML extension is used so that HTML-style comments can be included in the markdown docs. However, for best compatibility, keep them at the top level, not within indented areas/rendered admonition blocks, etc. as much as possible. 66 | 67 | `<!-- this is a valid comment that will not get rendered to the browser -->` 68 | 69 | ### Admonition Extension Quick Reference 70 | Admonition is an extension for MkDocs that provides easy block-styled side content (including collapsible blocks). More details on use can be found here: https://squidfunk.github.io/mkdocs-material/extensions/admonition/. Below is a quick reference for this functionality: 71 | 72 | For an always expanded option: 73 | `!!! note "This is the title" 74 | This is the text` 75 | 76 | For a collapsible option: 77 | 78 | `??? question "Is this collapsed by default?" 79 | Yes, it is` 80 | 81 | `???+ question "Is this expanded by default?" 82 | Yes, it is` 83 | 84 | Types include: 85 | 86 | - note 87 | - abstract 88 | - info 89 | - tip 90 | - success 91 | - question 92 | - warning 93 | - failure 94 | - danger 95 | - bug 96 | - example 97 | - quote 98 | 99 | ### Diagrams 100 | Usage of Draw.io is encouraged for generating diagrams: 101 | 102 | * Folder `/docs/diagrams` contains the `.svg` files that are the preferred format for diagrams 103 | * Diagrams can be edited using the Draw.io and similar applications: 104 | * Web: https://nanocurrency.github.io/drawio/src/main/webapp/index.html or https://app.diagrams.net 105 | * Desktop: https://github.com/jgraph/drawio-desktop/releases/latest 106 | * Embedding diagrams uses markdown format: `![account-chains](/diagrams/account-chains.svg)` 107 | 108 | There is also support for Mermaid Sequence Diagrams, and documentation can be found here: https://mermaidjs.github.io/#/sequenceDiagram, however given the desire to have consistency in the diagrams and the limitations of Mermaid, generating Draw.io type diagrams is preferred. 109 | 110 | ### Octicon icons 111 | The scripts for using Github's Octicons are included in the header. Details for available icons can be found here: https://primer.style/octicons/. Usage should be limited. Example currently available in announcement block: 112 | 113 | `<span class="iconify" data-icon="octicon-tag-16" data-inline="false"></span>` 114 | -------------------------------------------------------------------------------- /docs/releases/release-v23-0.md: -------------------------------------------------------------------------------- 1 | title: Release notes - V23.0 nano node 2 | description: Details of the V23.0 nano node release including upgrade notices, major features, API changes and more 3 | 4 | # V23.0 5 | 6 | --8<-- "release-details-v23-0.md" 7 | 8 | ## Upgrade notices 9 | 10 | There are no upgrade impacts to be considered with V23.0. However all exchanges, services and integrations are encouraged to test their implementations on the [test network](../running-a-node/test-network.md) (excluding load testing). 11 | 12 | --- 13 | 14 | ## Major updates 15 | 16 | ### Refactoring and cleanup 17 | 18 | Many of the more than 150 pull requests closed for this release were part of efforts to refactor and cleanup many areas of the code. These updates are helping provide a foundation for better improvements in subsequent releases. More details can be found in the [V23.0 Follis — Development Update](https://blog.nano.org/v23-0-follis-development-update-55ef8c41cbb). 19 | 20 | ### Unit tests and bug fixes 21 | 22 | Another focus area was improving and cleaning up the unit tests, along with various minor bugs and fixes. Test runs are now more consistent and reliable with V23, and will continue to be improved on in the coming releases. 23 | 24 | ### Naming conventions 25 | 26 | Recent updates to naming conventions are noteworthy: 27 | 28 | #### Receivable instead of pending 29 | 30 | After community discussions, a change from the term `pending` to `receivable`/`ready to be received` and similar was decided on and partially implemented in V23.0. These changes can be seen in various areas of the node wallet as well as across many RPC calls. 31 | 32 | !!! success "" 33 | _There are no breaking changes with this update, but switching to `receivable` terms is advised._ 34 | 35 | To keep backwards compatibility: 36 | 37 | - The `pending` RPC call name is deprecated in favor of `receivable` (additional RPC call name changes to be completed in the next release) 38 | - All RPC responses containing a key of `pending` still include the key as deprecated, and an additional `receivable` key with the same value was added as the preferred option 39 | - Any RPC examples in the documentation have been updated to favor `receivable` 40 | 41 | The aim of this change is to help reduce the confusion around send blocks that are confirmed, but a matching receive block has not yet been published for them. See [RPC updates](#pendingreceivable-term-rpc-updates) below for a list of impacted RPC calls. 42 | 43 | #### Unit name simplifications 44 | 45 | Updates to simplify the unit names used within the node wallet and unit conversion RPCs were completed. This means previous unit conversion RPCs are now deprecated (see [Deprecations/removals](#deprecationsremovals) below) and the wallet uses the only remaining standard units of `raw` (10^0) and `nano` (10^30). 46 | 47 | --- 48 | 49 | ## RPC updates 50 | 51 | * [`account_history`](../commands/rpc-protocol.md#account_history) RPC now includes whether the block was `confirmed` in the response, allowing more efficient confirmation validation in some cases. 52 | * **NEW** [`accounts_representatives`](../commands/rpc-protocol.md#accounts_representatives) RPC allows requesting representatives from multiple accounts in a single call. 53 | * [`block_info`](../commands/rpc-protocol.md#block_info) and [`blocks_info`](../commands/rpc-protocol.md#blocks_info) RPCs now include the `successor` block hash in responses for easier ledger walking. 54 | * [`delegators`](../commands/rpc-protocol.md#delegators) now allows for optional parameters `count` (to limit number of returned accounts), `threshold` (to require a minimum balance for returned delegators) and `start` (to allow paging by providing account to start after). 55 | * [`wallet_info`](../commands/rpc-protocol.md#wallet_info) RPC return includes count of all blocks and confirmed blocks from all accounts in the given wallet. 56 | 57 | ### Pending/Receivable term RPC updates 58 | 59 | There are various changes related to the switch from `pending` to `receivable` in RPC calls as noted above. **Although all changes are backwards compatible, switching to the term `receivable` in these cases is advised**. 60 | 61 | There are two main types of changes: RPC call name changes and updates to keys in the call requests and responses. 62 | 63 | **RPC call name changes** 64 | 65 | * [`pending`](../commands/rpc-protocol.md#pending) replaced by [`receivable`](../commands/rpc-protocol.md#receivable) 66 | * [`pending_exists`](../commands/rpc-protocol.md#pending_exists) replaced by [`receivable_exists`](../commands/rpc-protocol.md#receivable_exists) 67 | 68 | **Response/request key changes only** 69 | 70 | * [`account_balance`](../commands/rpc-protocol.md#account_balance) 71 | * [`account_info`](../commands/rpc-protocol.md#account_info) 72 | * [`accounts_balances`](../commands/rpc-protocol.md#accounts_balances) 73 | * [`blocks_info`](../commands/rpc-protocol.md#blocks_info) 74 | * [`ledger`](../commands/rpc-protocol.md#ledger) 75 | * [`wallet_balances`](../commands/rpc-protocol.md#wallet_balances) 76 | * [`wallet_info`](../commands/rpc-protocol.md#wallet_info) 77 | * [`wallet_ledger`](../commands/rpc-protocol.md#wallet_ledger) 78 | 79 | !!! success "" 80 | _There are no breaking changes with this update, but switching to `receivable` terms is advised._ 81 | 82 | --- 83 | 84 | ## WebSocket updates 85 | 86 | Support added for `wss://` to allow secure WebSocket connections alongside existing TLS support for RPC. Further details and documentation is pending, with initial pull request available here: https://github.com/nanocurrency/nano-node/pull/3032. 87 | 88 | --- 89 | 90 | ## Developer/debug options 91 | 92 | * **NEW CONFIGURATION OPTION** `node.rep_crawler_weight_minimum` allows configuration of the minimum vote weight a node needs to qualify for the [rep crawler](../node-implementation/voting.md#rep-crawler) to solicit confirmations from them. By default the rep crawler only tracks Principal Representatives (all previous versions behave this way) but a lower value for this option can provide broader tracking for debugging purposes. 93 | * **NEW CLI COMMANDS** 94 | * [`--disable_add_initial_peers`](../commands/command-line-interface.md#-disable_add_initial_peers) 95 | * [`--debug_block_dump`](../commands/command-line-interface.md#-debug_block_dump) 96 | * [`--initialize`](../commands/command-line-interface.md#-initialize) 97 | * [`--disable_ongoing_bootstrap`](../commands/command-line-interface.md#-disable_ongoing_bootstrap) 98 | * [`--disable_rep_crawler`](../commands/command-line-interface.md#-disable_rep_crawler) 99 | * [`--disable_request_loop`](../commands/command-line-interface.md#-disable_request_loop) 100 | 101 | --- 102 | 103 | ## Deprecations/removals 104 | 105 | * Most unit conversion RPCs were deprecated, including `krai_from_raw`, `krai_to_raw`, `mrai_from_raw`, `mrai_to_raw`, `rai_from_raw`, `rai_to_raw` 106 | 107 | --- 108 | 109 | ## Builds and commands 110 | 111 | --8<-- "current-build-links-main.md" 112 | -------------------------------------------------------------------------------- /docs/running-a-node/beta-network.md: -------------------------------------------------------------------------------- 1 | title: Beta Network 2 | description: Find out how to join the nano community in testing the latest nano node and protocol features on the beta network 3 | 4 | # Joining the beta network 5 | 6 | The beta network exists for the purpose of conducting certain network-wide activites including load testing and [new node releases and features testing](#node-release-testing). These activities can cause the network to become unstable or inaccessible at times due to heavy traffic, occasional resetting of the genesis/ledger or the introduction of bugs due to new features. As a result, an alternative [test network](test-network.md) is also available which will be more stable and is a better fit for learning node setup and management, and testing out upgrades and other activities for Nano before moving to production. 7 | 8 | With those things in consideration, if you are interested in helping with testing on the beta network we are excited to help you out - so keep reading! 9 | 10 | 11 | ## Node release testing 12 | The Nano Foundation maintains a few beta nodes on the network and various community members also setup nodes to help provide an environment more similar to the main network. During each development cycle Development Builds (DB) are prepared and shared in the Discord Beta Testing section of channels where early testing is coordinated. Once features are stabilized and included, release builds are published as Release Candidates (RC). Starting with RC1 and incrementing with each published build if needed (RC2, RC3, etc.). Final release of a version typically follows quickly once the RC is observed to be stable. 13 | 14 | !!! warning 15 | Development Builds (DBs) are only recommended for use on the beta network, and Release Candidate builds (RCs) are only recommended for use on the test and beta networks 16 | 17 | ## Running a beta node 18 | 19 | Setting up a node on the beta network is similar to the main network. To start you should [install docker](/running-a-node/node-setup/#installing-docker) and be familiar with the general setup and [Docker management](/running-a-node/docker-management/) processes. 20 | 21 | ### Network ports 22 | 23 | --8<-- "network-details-simple-beta.md" 24 | 25 | ___ 26 | 27 | ### Directory locations 28 | 29 | --8<-- "directory-locations-beta.md" 30 | 31 | --- 32 | 33 | ### Pulling the Docker image 34 | [![Docker Pulls](https://img.shields.io/docker/pulls/nanocurrency/nano.svg)](https://hub.docker.com/r/nanocurrency/nano-beta) 35 | 36 | Pulls the latest release of the Nano Node: 37 | ```bash 38 | docker pull nanocurrency/nano-beta 39 | ``` 40 | 41 | Pulls a specific version of the Nano node: 42 | ```bash 43 | docker pull nanocurrency/nano-beta:<tag> 44 | ``` 45 | 46 | A list of beta tags can be found at the official [Nano Currency Docker Hub](https://hub.docker.com/r/nanocurrency/nano-beta/tags) 47 | 48 | ### Starting the Docker container 49 | 50 | --8<-- "docker-run-command-beta.md" 51 | 52 | !!! tip 53 | * For an explanation of the options included in the Docker `run` command, see [Starting the Container](/running-a-node/docker-management/#starting) details for the main network. 54 | * See [Docker management](/running-a-node/docker-management/) for other related commands 55 | 56 | !!! warning "Separate host directories" 57 | Be sure to use a different host directory for main network and beta network Docker node setups. Attempting to use the same directory will result in issues. 58 | 59 | ## Additional beta resources 60 | 61 | | URL | Description | 62 | | | | 63 | | https://beta.nanobrowse.com | Beta Explorer | 64 | | https://nanoticker.bnano.info/ | Beta node details and stats | 65 | 66 | ## Differences from the main network 67 | 68 | | Parameter | Main Network | Beta Network | Comment | 69 | |-----------|--------------|--------------|---------| 70 | | Epoch 1 difficulty threshold | `ffffffc000000000` | `fffff00000000000` | 64 times lower on the beta network | 71 | | Epoch 2 send/change threshold | `fffffff800000000` | `fffff00000000000` | Same as epoch 1 on the beta network | 72 | | Epoch 2 receive threshold | `fffffe0000000000` | `ffffe00000000000` | 2 times lower than epoch 1 | 73 | 74 | <span id="release-candidate-builds"></span> 75 | <span id="development-builds"></span> 76 | <span id="latest-beta-builds"></span> 77 | ## Testing Builds 78 | 79 | Most of the resources needed to participate on the beta network can be found within the `#beta-xxxxxxx` channels on our [Discord server](https://chat.nano.org). As much of the discussion, planning and engagement happens here, all participants are highly encouraged to join there. 80 | 81 | ### Binaries 82 | 83 | In addition to the Docker details above, the latest binary builds of the node for the beta network are shared in the `#beta-announcements` channel on our [Discord server](https://chat.nano.org). These assets are also available on the [GitHub repository Releases page](https://github.com/nanocurrency/nano-node/releases) under `RC#` and `DB#` tags, which can also be used to manually build if necessary. 84 | 85 | ### Beta fund distribution 86 | 87 | The funds used for testing transactions on the beta network are generated from a new genesis block and distributed in bulk to various testers running nodes on the network. For small amounts suitable for most basic integration, you can get beta Nano from the `#beta-faucet` channel on Discord. If you plan to consistently run a node on beta and want to participate in consensus as a Representative, please connect with `ThiagoSFS#1554` in the `#beta-net` channel on our [Discord server](https://chat.nano.org). 88 | 89 | ### Beta ledger file 90 | 91 | To help get beta nodes in sync more quickly it is recommended that an updated ledger file is downloaded and placed into the data directory. Often referred to as a "fast sync", more details around this approach can be found in the [Ledger Management guide](ledger-management.md#downloaded-ledger-files). Since the beta network contains no value, validating the blocks, voting weights and confirmation heights isn't necessary. 92 | 93 | The following command will download and unzip a recent ledger snapshot. Any existing ledger files should be backed up elswhere as this will override them. From within the [data directory](#directory-locations) run: 94 | 95 | ``` 96 | curl -O https://s3.us-east-2.amazonaws.com/beta-snapshot.nano.org/data.tar.gz; tar -xzvf data.tar.gz; rm -fr data.tar.gz 97 | ``` 98 | <span id="ongoing-test-cases"></span> 99 | ### Build contents and test cases 100 | With each DB a GitHub Project board will be created in the [Nano GitHub Organization](https://github.com/orgs/nanocurrency/projects) containing all the Pull Requests newly added in the DB, changes from previous DBs that still need network testing, and issues with the various test cases that are targeted to be run with that build. For those looking to assist with these tests, we encourage connecting with the other beta network participants in the `#beta-net` channel on our [Discord server](https://chat.nano.org). 101 | -------------------------------------------------------------------------------- /docs/running-a-node/logging-tracing.md: -------------------------------------------------------------------------------- 1 | # Nano Node Logging Documentation 2 | 3 | ## Introduction 4 | 5 | This documentation covers the logging facilities of the Nano Node, including configuration options, environment variables, and usage of tracing and stats logging. 6 | 7 | ## Overview - V27 and later 8 | 9 | ### Log Levels 10 | 11 | Log levels are used to control the verbosity of log output. The available log levels are: 12 | 13 | ```toml 14 | - trace 15 | - debug 16 | - info 17 | - warn 18 | - error 19 | - critical 20 | - off 21 | ``` 22 | 23 | For users, log levels up to debug are useful. Tracing and stats logging are primarily for developers debugging the node. 24 | 25 | ### Configuration - V27 and later 26 | 27 | There are two ways to configure the logger: 28 | 29 | * The first is to use a **config file** `config-log.toml`, which is located in the data directory alongside other configuration files. 30 | 31 | * The second is to use `NANO_LOG` and `NANO_LOG_LEVELS` **environment variables**. The environment variables take precedence over the configuration file. 32 | 33 | 34 | #### Config File (config-log.toml) 35 | 36 | During normal node operation, the configuration file is loaded from the data directory. 37 | When running test suites, the configuration is loaded from the current working directory. 38 | 39 | ##### Example config-log.toml 40 | ``` 41 | [log] 42 | default_level = "info" 43 | 44 | [log.console] 45 | #colors = true 46 | enable = true 47 | #to_cerr = false 48 | 49 | [log.file] 50 | enable = true 51 | #max_size = 33554432 52 | #rotation_count = 4 53 | 54 | [log.levels] 55 | #active_transactions = "info" 56 | #all = "info" 57 | #blockprocessor = "info" 58 | #bootstrap = "info" 59 | #bootstrap_lazy = "info" 60 | #... 61 | #log_type = "log_level" 62 | ``` 63 | 64 | The full list of `log_types` can be found [here](https://github.com/nanocurrency/nano-node/blob/develop/nano/lib/logging_enums.hpp#L24-L95) 65 | 66 | 67 | #### Environment Variables 68 | 69 | Environment variables override the configuration file. This is useful when running test suites. 70 | 71 | ##### Set default log level 72 | ``` 73 | NANO_LOG = [trace|debug|info|warn|error|critical|off] 74 | ``` 75 | 76 | ##### Set log level for individual loggers 77 | ``` 78 | NANO_LOG_LEVELS = log_type_1=level_1[,log_type_2=level_2,...] 79 | ``` 80 | 81 | Example: 82 | ``` 83 | export NANO_LOG=warn 84 | export NANO_LOG_LEVELS=active_transactions=debug,bootstrap=debug 85 | ``` 86 | 87 | 88 | ### Unit Tests 89 | 90 | By default, the logger is disabled when running unit tests to keep the output clean. To enable it, set the `NANO_LOG` environment variable to a desired log level. 91 | Alternatively a configuration file inside the current working directory will be loaded by the test suites. 92 | 93 | In test suite mode, each log line additionally contains the identifier of the node that produced the log line (first 10 characters of its node ID). This makes it easier to follow the flow of events and will become much more useful once full tracing is implemented. 94 | 95 | 96 | ### Tracing 97 | 98 | The goal of tracing is to introduce a framework for tracing events in the node. This is meant to be used for debugging and profiling purposes, e.g., by visualizing the flow of votes through the network or analyzing the delay between receiving a block and confirming it. 99 | 100 | #### Tracing Usage 101 | To use tracing, it must be enabled **at compile time** by passing the `-DNANO_TRACING=ON` flag to CMake. By default, it is disabled for release builds and enabled for debug builds. 102 | 103 | After that, tracing can be enabled by setting the logging verbosity level to `trace`: 104 | ``` 105 | NANO_LOG=trace 106 | ``` 107 | 108 | Since the amount of logs when setting the logging level to `trace` is very large, it is recommended to use the trace level only for specific components. This can be done by setting the `NANO_LOG_LEVELS` environment variable to a comma-separated list of components to trace. For example, to trace only `active_transactions` and `vote_processor`, set: 109 | ``` 110 | NANO_LOG_LEVELS="active_transactions=trace,vote_processor=trace" 111 | ``` 112 | 113 | Alternatively, this can also be done by modifying the `config-log.toml` file. 114 | 115 | 116 | ### Tracing Formats 117 | 118 | It is possible to specify the format of tracing output at runtime. This is done by setting the `NANO_TRACE_FORMAT` environment variable to one of the following: `standard` or `json`. 119 | 120 | #### Standard Tracing 121 | Standard tracing is enabled by default. It is a simple key: { value } format with indentation that should be easy to read. 122 | 123 | #### JSON Tracing 124 | JSON tracing is meant to be parsed by external tools. There is no indentation or newlines, so each log output line can be treated as a separate event, which simplifies parsing. 125 | 126 | ##### Sample JSON Tracing output: 127 | ``` 128 | [2024-01-30 17:56:53.312] [vote_processor::vote_processed] [trace] "event":"vote_processor::vote_processed","time":1706633813312751,"vote":{"account":"FD16B0FE0102F68C2D9482348AE7211E3CBF86681364E53D8793A5E551167A6C","final":true,"timestamp":18446744073709551615,"hashes":["7DEF4D1F5EB222BC5DE2123293EE5A8CE58E283176AB65DF3373DA009FD99E86"]},"result":"indeterminate" 129 | ``` 130 | 131 | 132 | ### Stats Logging 133 | 134 | This allows logging individual stat counter increments. This is useful for debugging tests. This functionality can be enabled by setting the `NANO_LOG_STATS=[1,true,on]` environment variable. 135 | 136 | #### Example output: 137 | ``` 138 | [2024-05-02 18:43:27.939] [node_16gzg] [stats] [debug] Stat: bootstrap_server::request::in += 1 139 | [2024-05-02 18:43:27.939] [node_16gzg] [stats] [debug] Stat: bootstrap_server_request::blocks::in += 1 140 | [2024-05-02 18:43:27.939] [node_3e5x4] [stats] [debug] Stat: traffic_tcp::all::out += 51 141 | [2024-05-02 18:43:27.939] [node_3e5x4] [stats] [debug] Stat: bootstrap_ascending::track::in += 1 142 | [2024-05-02 18:43:27.939] [node_3e5x4] [stats] [debug] Sample: bootstrap_tag_duration -> 1 143 | ``` 144 | 145 | 146 | 147 | ## Overview - V26 and prior 148 | 149 | V26 and prior version use a different method to enable logs. 150 | 151 | ### Configuration - V26 and prior 152 | 153 | ```toml 154 | [node.logging] 155 | 156 | # Append to log/node.log without a timestamp in the filename. 157 | # The file is not emptied on startup if it exists, but appended to. 158 | # type:bool 159 | stable_log_filename = true 160 | ``` 161 | 162 | This configuration option is set in the [`config-node.toml` file](../running-a-node/configuration.md#configuration-file-locations). 163 | 164 | To generate a config file with all logging options, run `nano_node --generate_config node` 165 | 166 | #### logging.stable_log_filename 167 | 168 | --8<-- "known-issue-windows-logging-stable.md" 169 | 170 | By default this option is set to `false` which results in all log files having a timestamp appended to them, even the currently active file. If set to `true` the currently active log file will have a static name at `log/node.log` for easier management. 171 | 172 | 173 | #### logging.log_rpc 174 | This configuration option is set in the [`config-rpc.toml`](../running-a-node/configuration.md#configuration-file-locations) file. 175 | 176 | By default, all RPC calls and the time spent handling each one are [logged](../running-a-node/troubleshooting.md#log-files). This can be optionally turned off by switching option `logging.log_rpc` to `false` 177 | 178 | ```toml 179 | [logging] 180 | 181 | # Whether to log RPC calls. 182 | # type:bool 183 | log_rpc = true 184 | ``` -------------------------------------------------------------------------------- /docs/protocol-design/ledger.md: -------------------------------------------------------------------------------- 1 | title: Protocol Design - Ledger 2 | description: Explore the structure of the ledger in nano including accounts, blocks and how they can be managed 3 | 4 | # Protocol Design - Ledger 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | ## Ledger design 9 | 10 | The Nano ledger is the global set of accounts where each account has its own chain of transactions (<a href="#account-chains-diagram">Figure 1</a>). This is a key design component that falls under the category of replacing a run-time agreement with a design-time agreement - everyone agrees via signature checking that only an account owner can modify the balance and representative on their own chain. This converts a seemingly shared data structure (a global blockchain) into a set of non-shared ones (individual account-chains). 11 | 12 | Each Nano node determines for itself whether or not to add a valid transaction to its local ledger. This means that there is no waiting for leader-selection as there is in single-blockchain cryptocurrencies like Bitcoin, where a single miner or staker extends the global blockchain with a new block (group of transactions) after solving a Proof-of-Work or being chosen through random selection. The block lattice ledger design removes this bottleneck, drastically decreasing transaction latency, improving decentralization, and simplifying transaction validation. Nano has no concept of block sizes or block times that arbitrarily limit the number of transactions that can be processed - the network will confirm as many transactions as current network conditions allow. 13 | 14 | <span id="account-chains-diagram"></span> 15 | 16 | ![account-chains](/diagrams/account-chains.svg) 17 | 18 | *Figure 1. Each account has its own blockchain containing the account’s balance history. Block 1 must be a receive transaction with it's `previous` field as constant `0`.* 19 | 20 | ### Accounts 21 | 22 | An account is the public-key portion of a digital signature key-pair. The public-key, also referred to as the address, is shared with other network participants while the private-key is kept secret. A digitally signed packet of data ensures that the contents were approved by the private-key holder. One user may control many accounts, but only one public address may exist per account. 23 | 24 | Although a special private key can be used to publish epoch transactions to all accounts, the only changes allowed for this special type of transaction are related to upgrading the account version. This means that account owners are the only ones who can modify the balance and representative on their own account chains and thus contention only happens on a per-account basis or in relation to epoch distributions[^1]. 25 | 26 | For example, if account A attempts a double spend that must be resolved by the network, account B can still make transactions as normal. Transactions are processed independently and asynchronously. 27 | 28 | ### Blocks 29 | 30 | In traditional blockchain-based cryptocurrencies like Bitcoin, a block is a group of transactions. In Nano, a block contains the details of a single transaction. There are four different transaction types in Nano (send, receive, change representative and epoch) and in order to transfer funds, two transactions are required - a send transaction and a receive transaction. 31 | 32 | This difference in transaction structures means the terminology used can have different meanings, so it is worth defining these more explicitly: 33 | 34 | * **block** is the digital encoding of the transaction details ([Figure 2](#block-diagram)). 35 | 36 | * **transaction** is the action of creating and publishing a block to the network. Depending on the type of transaction, the block will have different requirements. 37 | 38 | * **transfer** is the completion of both a send transaction and the corresponding receive transaction, representing the movement of funds which can be sent again by the recipient. 39 | 40 | <span id="block-diagram"></span> 41 | 42 | ``` 43 | "block": { 44 | "type": "state", 45 | "account": "nano_3qgmh14nwztqw4wmcdzy4xpqeejey68chx6nciczwn9abji7ihhum9qtpmdr", 46 | "previous": "F47B23107E5F34B2CE06F562B5C435DF72A533251CB414C51B2B62A8F63A00E4", 47 | "representative": "nano_1hza3f7wiiqa7ig3jczyxj5yo86yegcmqk3criaz838j91sxcckpfhbhhra1", 48 | "balance": "1000000000000000000000", 49 | "link": "19D3D919475DEED4696B5D13018151D1AF88B2BD3BCFF048B45031C1F36D1858", 50 | "link_as_account": "nano_18gmu6engqhgtjnppqam181o5nfhj4sdtgyhy36dan3jr9spt84rzwmktafc", 51 | "signature": "3BFBA64A775550E6D49DF1EB8EEC2136DCD74F090E2ED658FBD9E80F17CB1C9F9F7BDE2B93D95558EC2F277FFF15FD11E6E2162A1714731B743D1E941FA4560A", 52 | "work": "cab7404f0b5449d0" 53 | } 54 | ``` 55 | _Figure 2 - An example Nano block with all required fields_ 56 | 57 | Note that there is an open [proposal](https://github.com/nanocurrency/nano-node/issues/2864) to update the state block with version, block height, and subtype fields. 58 | 59 | #### Why require two transactions to transfer 60 | 61 | Although send transactions confirmed by the network are irreversible, in order for the recipient to send those funds again they first must complete a receive transaction on their account. This receiving requirement to complete a transfer of funds provides a few benefits: 62 | 63 | * Sending of funds can be performed while the receiver is offline 64 | * Account owners are the only ones who are allowed to modify the balance and representative on their accounts 65 | * Allows account owners to ignore transactions, which prevents continuous sending of tiny amounts in an attempt to prevent use of the account 66 | 67 | ### Block lattice 68 | 69 | The lattice structure of the ledger arises from blocks connecting across account-chains. All block types use the `previous` field to vertically extend the account-chain. In addition, send and receive blocks also use the `link` field to connect across account-chains. [Figure 3](#block-lattice-diagram) below illustrates the lattice structure at a high level with additional details about blocks available on the [blocks](blocks.md) page. 70 | 71 | <span id="block-lattice-diagram"></span> 72 | 73 | ![block-lattice](/diagrams/block-lattice.svg) 74 | 75 | As illustrated above, the ledger was initiated with a genesis account containing the genesis balance. The genesis balance was a fixed quantity and can never be increased. The genesis balance was divided across various accounts via send transactions registered on the genesis account-chain. The sum of the balances of all accounts in the ledger will never exceed the initial genesis balance, which gives the system an upper bound on quantity and no ability to increase it. 76 | 77 | --- 78 | 79 | ## Ledger pruning 80 | 81 | Since every transaction in Nano includes a block with the complete current state of an account, the ledger can be significantly pruned. While there are a few exceptions (e.g. pending transactions), Nano's ledger design could be pruned down to one block per account (plus pending), regardless of how many transactions the account has sent or received. Note that pruning is not implemented yet, and exact implementation details are still being tested and discussed. 82 | 83 | See the official [forum](https://forum.nano.org/t/ledger-pruning/114) or [GitHub](https://github.com/nanocurrency/nano-node/issues/1094) discussions for more detail. 84 | 85 | --- 86 | 87 | Existing whitepaper sections related to this page: 88 | 89 | * [Nano Components](/whitepaper/english/#raiblocks-components) 90 | 91 | Other existing content related to this page: 92 | 93 | * [Block Lattice design](/integration-guides/the-basics/#block-lattice-design) 94 | * [Accounts, Keys, Seeds, etc.](/integration-guides/the-basics/#account-key-seed-and-wallet-ids) 95 | * [Looking up to Confirmation Height](https://medium.com/nanocurrency/looking-up-to-confirmation-height-69f0cd2a85bc) 96 | * [Ledger Management guide](../running-a-node/ledger-management.md) 97 | 98 | [^1]: Epoch blocks details, Network Upgrades documentation: https://docs.nano.org/releases/network-upgrades/#epoch-blocks 99 | -------------------------------------------------------------------------------- /docs/images/mailing-list.svg: -------------------------------------------------------------------------------- 1 | <svg xmlns="http://www.w3.org/2000/svg" width="245" height="256" viewBox="0 0 245 256" fill="none"> 2 | <path d="M0 16C0 7.16344 7.16344 0 16 0H229C237.837 0 245 7.16344 245 16V256H0V16Z" fill="white"></path> 3 | <path d="M29 214.125H39.3125V221H29V214.125ZM39 214.125H49.3125V221H39V214.125ZM49 214.125H59.3125V221H49V214.125ZM59 214.125H69.3125V221H59V214.125ZM69 214.125H79.3125V221H69V214.125ZM99.0625 214.125H109.375V221H99.0625V214.125ZM109.062 214.125H119.375V221H109.062V214.125ZM139.125 214.125H149.438V221H139.125V214.125ZM149.125 214.125H159.438V221H149.125V214.125ZM159.125 214.125H169.438V221H159.125V214.125ZM169.125 214.125H179.438V221H169.125V214.125ZM29 224.125H39.3125V231H29V224.125ZM39 224.125H49.3125V231H39V224.125ZM49 224.125H59.3125V231H49V224.125ZM59 224.125H69.3125V231H59V224.125ZM69 224.125H79.3125V231H69V224.125ZM99.0625 224.125H109.375V231H99.0625V224.125ZM109.062 224.125H119.375V231H109.062V224.125ZM119.062 224.125H129.375V231H119.062V224.125ZM129.062 224.125H139.375V231H129.062V224.125ZM139.062 224.125H149.375V231H139.062V224.125ZM169.125 224.125H179.438V231H169.125V224.125ZM179.125 224.125H189.438V231H179.125V224.125Z" fill="#DCE9F9" fill-opacity="0.66"></path> 4 | <path d="M29 72.125H39.3125V79H29V72.125ZM39 72.125H49.3125V79H39V72.125ZM49 72.125H59.3125V79H49V72.125ZM79.0625 72.125H89.375V79H79.0625V72.125ZM89.0625 72.125H99.375V79H89.0625V72.125ZM99.0625 72.125H109.375V79H99.0625V72.125ZM109.062 72.125H119.375V79H109.062V72.125ZM119.062 72.125H129.375V79H119.062V72.125ZM129.062 72.125H139.375V79H129.062V72.125ZM139.062 72.125H149.375V79H139.062V72.125ZM149.062 72.125H159.375V79H149.062V72.125ZM159.062 72.125H169.375V79H159.062V72.125Z" fill="#DCE9F9"></path> 5 | <path d="M29 96.125H39.3125V103H29V96.125ZM39 96.125H49.3125V103H39V96.125ZM49 96.125H59.3125V103H49V96.125ZM59 96.125H69.3125V103H59V96.125ZM69 96.125H79.3125V103H69V96.125ZM99.0625 96.125H109.375V103H99.0625V96.125ZM109.062 96.125H119.375V103H109.062V96.125ZM119.062 96.125H129.375V103H119.062V96.125ZM129.062 96.125H139.375V103H129.062V96.125ZM139.062 96.125H149.375V103H139.062V96.125ZM29 106.125H39.3125V113H29V106.125ZM39 106.125H49.3125V113H39V106.125ZM49 106.125H59.3125V113H49V106.125ZM59 106.125H69.3125V113H59V106.125ZM69 106.125H79.3125V113H69V106.125ZM99.0625 106.125H109.375V113H99.0625V106.125ZM109.062 106.125H119.375V113H109.062V106.125ZM139.125 106.125H149.438V113H139.125V106.125ZM149.125 106.125H159.438V113H149.125V106.125ZM159.125 106.125H169.438V113H159.125V106.125ZM169.125 106.125H179.438V113H169.125V106.125ZM29 116.125H39.3125V123H29V116.125ZM39 116.125H49.3125V123H39V116.125ZM49 116.125H59.3125V123H49V116.125ZM59 116.125H69.3125V123H59V116.125ZM69 116.125H79.3125V123H69V116.125ZM99.0625 116.125H109.375V123H99.0625V116.125ZM109.062 116.125H119.375V123H109.062V116.125ZM119.062 116.125H129.375V123H119.062V116.125ZM129.062 116.125H139.375V123H129.062V116.125ZM139.062 116.125H149.375V123H139.062V116.125ZM169.125 116.125H179.438V123H169.125V116.125ZM179.125 116.125H189.438V123H179.125V116.125ZM29 126.125H39.3125V133H29V126.125ZM39 126.125H49.3125V133H39V126.125ZM49 126.125H59.3125V133H49V126.125ZM59 126.125H69.3125V133H59V126.125ZM89.0625 126.125H99.375V133H89.0625V126.125ZM99.0625 126.125H109.375V133H99.0625V126.125ZM109.062 126.125H119.375V133H109.062V126.125ZM119.062 126.125H129.375V133H119.062V126.125ZM129.062 126.125H139.375V133H129.062V126.125ZM159.125 126.125H169.438V133H159.125V126.125ZM169.125 126.125H179.438V133H169.125V126.125ZM29 136.125H39.3125V143H29V136.125ZM39 136.125H49.3125V143H39V136.125ZM49 136.125H59.3125V143H49V136.125ZM59 136.125H69.3125V143H59V136.125ZM69 136.125H79.3125V143H69V136.125ZM99.0625 136.125H109.375V143H99.0625V136.125ZM109.062 136.125H119.375V143H109.062V136.125ZM119.062 136.125H129.375V143H119.062V136.125ZM129.062 136.125H139.375V143H129.062V136.125ZM159.125 136.125H169.438V143H159.125V136.125ZM169.125 136.125H179.438V143H169.125V136.125ZM29 146.125H39.3125V153H29V146.125ZM39 146.125H49.3125V153H39V146.125ZM49 146.125H59.3125V153H49V146.125ZM59 146.125H69.3125V153H59V146.125ZM69 146.125H79.3125V153H69V146.125Z" fill="#DCE9F9" fill-opacity="0.66"></path> 6 | <rect x="29" y="168" width="187" height="35" rx="6" fill="#DCE9F9"></rect> 7 | <path d="M117.663 36.2694C117.513 36.2694 117.387 36.3207 117.293 36.4297C117.199 36.5386 117.155 36.6732 117.155 36.8399V47.0693L109.524 36.5386C109.405 36.3592 109.254 36.2694 109.072 36.2694C108.897 36.2694 108.759 36.3207 108.659 36.4297C108.558 36.5386 108.508 36.6732 108.508 36.8399V48.4666C108.508 48.646 108.546 48.787 108.627 48.8896C108.709 48.9921 108.834 49.0434 109.01 49.0434C109.16 49.0434 109.286 48.9921 109.38 48.8832C109.474 48.7742 109.518 48.6396 109.518 48.473V38.2179L117.168 48.7742C117.306 48.9537 117.462 49.0434 117.638 49.0434C117.801 49.0434 117.926 48.9921 118.02 48.8832C118.114 48.7742 118.158 48.6396 118.158 48.473V36.8399C118.158 36.6604 118.114 36.5194 118.027 36.4232C117.951 36.3207 117.826 36.2694 117.663 36.2694ZM157.763 36.1797C154.289 36.1797 151.467 39.0639 151.467 42.6148C151.467 46.1656 154.289 49.0498 157.763 49.0498C161.237 49.0498 164.058 46.1656 164.058 42.6148C164.058 39.0639 161.23 36.1797 157.763 36.1797ZM157.763 47.9987C154.859 47.9987 152.496 45.5823 152.496 42.6148C152.496 39.6472 154.859 37.2308 157.763 37.2308C160.666 37.2308 163.03 39.6472 163.03 42.6148C163.03 45.5823 160.666 47.9987 157.763 47.9987ZM128.743 36.6476C128.699 36.5258 128.618 36.4361 128.505 36.3592C128.392 36.2886 128.273 36.2502 128.147 36.2502C127.865 36.2502 127.677 36.3784 127.57 36.6412L122.466 48.3576C122.441 48.4025 122.429 48.473 122.429 48.5563C122.429 48.6973 122.479 48.8127 122.579 48.9024C122.679 48.9921 122.799 49.037 122.936 49.037C123.156 49.037 123.319 48.9216 123.426 48.6973L124.774 45.5887H131.552L132.881 48.6973C132.925 48.8063 132.994 48.8896 133.082 48.9473C133.17 49.005 133.258 49.037 133.352 49.037C133.49 49.037 133.615 48.9921 133.722 48.9024C133.828 48.8127 133.878 48.7037 133.878 48.5755C133.878 48.505 133.86 48.4345 133.828 48.364L128.743 36.6476ZM125.175 44.6273L128.16 37.718L131.132 44.6273H125.175ZM147.278 36.2694C147.128 36.2694 147.003 36.3207 146.915 36.4297C146.821 36.5386 146.777 36.6732 146.777 36.8399V47.0693L139.139 36.5322C139.02 36.3527 138.87 36.263 138.688 36.263C138.512 36.263 138.374 36.3143 138.274 36.4232C138.174 36.5322 138.124 36.6668 138.124 36.8334V48.4602C138.124 48.6396 138.161 48.7806 138.243 48.8832C138.324 48.9857 138.45 49.037 138.625 49.037C138.776 49.037 138.901 48.9857 138.995 48.8768C139.089 48.7678 139.133 48.6332 139.133 48.4666V38.2179L146.783 48.7742C146.921 48.9537 147.078 49.0434 147.253 49.0434C147.416 49.0434 147.542 48.9921 147.636 48.8832C147.73 48.7742 147.774 48.6396 147.774 48.473V36.8399C147.774 36.6604 147.73 36.5194 147.642 36.4232C147.567 36.3207 147.442 36.2694 147.278 36.2694Z" fill="#000034"></path> 8 | <path d="M86.5301 42.6143C86.5301 43.7936 85.5958 44.7422 84.4483 44.7422C83.3008 44.7422 82.3665 43.7872 82.3665 42.6143C82.3665 41.0183 81.8461 40.4863 80.2847 40.4863C78.7234 40.4863 78.2029 41.0183 78.2029 42.6143C78.2029 43.7936 77.2686 44.7422 76.1211 44.7422C74.9736 44.7422 74.0393 43.7872 74.0393 42.6143C74.0393 41.4349 74.9736 40.4863 76.1211 40.4863C77.6825 40.4863 78.2029 39.9544 78.2029 38.3584C78.2029 37.1791 79.1372 36.2305 80.2847 36.2305C81.4322 36.2305 82.3665 37.1855 82.3665 38.3584C82.3665 39.9544 82.8869 40.4863 84.4483 40.4863C85.6021 40.4863 86.5301 41.4349 86.5301 42.6143Z" fill="#4A90E2"></path> 9 | <path d="M71.945 49.0039C73.0947 49.0039 74.0268 48.0512 74.0268 46.876C74.0268 45.7008 73.0947 44.748 71.945 44.748C70.7952 44.748 69.8632 45.7008 69.8632 46.876C69.8632 48.0512 70.7952 49.0039 71.945 49.0039Z" fill="#4A90E2"></path> 10 | <path d="M99.0397 38.3516C99.0397 39.5309 98.1054 40.4795 96.9579 40.4795C95.3965 40.4795 94.8761 41.0115 94.8761 42.6074C94.8761 43.7868 93.9418 44.7354 92.7943 44.7354C91.2329 44.7354 90.7125 45.2673 90.7125 46.8633C90.7125 48.0426 89.7782 48.9912 88.6307 48.9912C87.4832 48.9912 86.5489 48.0362 86.5489 46.8633C86.5489 45.684 87.4832 44.7354 88.6307 44.7354C90.192 44.7354 90.7125 44.2034 90.7125 42.6074C90.7125 41.4281 91.6468 40.4795 92.7943 40.4795C94.3556 40.4795 94.8761 39.9475 94.8761 38.3516C94.8761 37.1722 95.8104 36.2236 96.9579 36.2236C98.1054 36.2236 99.0397 37.1786 99.0397 38.3516Z" fill="#4A90E2"></path> 11 | </svg> -------------------------------------------------------------------------------- /docs/protocol-design/orv-consensus.md: -------------------------------------------------------------------------------- 1 | title: Protocol Design - ORV Consensus 2 | description: Take a deep dive into the unique, gossip-based algorithm used by nano to generate global consensus across all nodes on the network 3 | 4 | # Protocol Design - ORV Consensus 5 | 6 | --8<-- "wip-living-whitepaper.md" 7 | 8 | Existing whitepaper sections: [System Overview](/whitepaper/english/#system-overview), [Implementation](/whitepaper/english/#implementation) 9 | 10 | Existing content: 11 | 12 | * [Representatives and voting](/what-is-nano/overview/#representatives-and-voting) 13 | * [Representatives](/integration-guides/the-basics/#representatives) 14 | * [PoW for Receive block](https://github.com/nanocurrency/nano-node/issues/464#issuecomment-356467448) 15 | 16 | --- 17 | 18 | ## Overview 19 | 20 | In order to protect against [double spending](attack-vectors.md#50-attack) and [Sybil attacks](attack-vectors.md#sybil-attack-to-change-ledger-entries), Nano uses a unique consensus mechanism called Open Representative Voting (ORV). In ORV, user-selected representative nodes vote on each transaction, and every node (representative or not) independently [cements](../glossary.md#cementing) each transaction after seeing enough representative votes to achieve [quorum](#quorum). Since Nano transactions are processed individually and asynchronously, deterministic finality (irreversible, full-settlement) is achieved in a short period of time, typically less than 1 second [^1]. 21 | 22 | Due to Nano's [block-lattice ledger design](ledger.md), only account owners have the ability to sign blocks into their account-chains, so all forks must be the result of poor programming or malicious intent (double-spend) by the account owner, which means that nodes can easily make policy decisions on how to handle forks without affecting legitimate transactions. 23 | 24 | Because Nano accounts can freely delegate their voting weight to representatives at any time, the users have more control over who has power with consensus and how decentralized the network is. Also note that delegation of voting weight does not mean staking of any funds - the account delegating can still spend all their available funds at any time without restrictions. This is a key advantage to the design of [Open Representative Voting (ORV)](/glossary/#open-representative-voting-orv). With no direct monetary incentive for nodes, this removes emergent centralization forces for longer-term trending toward decentralization of the network.[^2] 25 | 26 | ### Open Representative Voting (ORV) vs Proof of Stake (PoS) 27 | 28 | While Nano uses a weighted-voting system ([ORV](/protocol-design#orv-consensus)) that can be compared to PoS, it differs from traditional PoS because: 29 | 30 | - There is not one monolithic blockchain that requires leader selection (i.e. a staker or a miner) to extend 31 | 32 | - Representatives do not create or produce shared blocks (groups of transactions) 33 | 34 | - Each Nano account has its own blockchain that only the owner can modify (representatives can only modify their own blockchain) 35 | 36 | - In Nano, a block is a single transaction (not a group of transactions). Transactions are evaluated individually and asynchronously 37 | 38 | - Users can remotely re-delegate their voting weight to anyone at any time 39 | 40 | - Anyone can be a representative 41 | 42 | - No funds are staked or locked up 43 | 44 | - Representatives do not earn transaction fees 45 | 46 | - Representatives cannot reverse transactions that nodes have locally confirmed (due to [block cementing](/glossary#cementing)). 47 | 48 | ### Confirmation Speed 49 | 50 | Nano's <1 second average transaction confirmation time often leads to questions about how finality can be achieved so quickly vs alternatives like Bitcoin. There are a few factors that contribute to this difference: 51 | 52 | - The block-lattice ledger design replaces a run-time agreement with a design-time agreement 53 | 54 | - A Nano block is a single transaction that can be processed individually and asynchronously vs other transactions 55 | 56 | - Lightweight Open Representative voting (ORV) and contention minimization 57 | 58 | Only account owners have the ability to sign blocks into their account-chains, so all forks must be the result of poor programming or malicious intent (double-spend) by the account owner, which means that nodes can easily make policy decisions on how to handle forks without affecting legitimate transactions. 59 | 60 | A Bitcoin block is a group of transactions (~1 Megabyte per block) that has to be propagated and processed together, while a Nano [block](blocks.md) is a single transaction (~200 bytes) that is almost 5000 times smaller than a Bitcoin block. To make a Nano transaction, a node publishes a block to all the Nano [Principal Representatives (PRs)](#principal-representatives-vs-non-principal-representatives) [^3] at the speed of internet latency (20-100ms typically, depending on location), and those PRs then generate their vote (another small network packet) and publish it to each other and a subset of non-PR peers (who then publish to a subset of their peers). This pattern of communication is known as gossip-about-gossip. 61 | 62 | Once a node sees enough PR vote responses to cross its local vote weight threshold for confirmation (>67% of online vote weight by default), it considers the transaction to be confirmed and then cements it as irreversible. Since the vast majority of transactions are not forks (no extra voting for fork resolution required), average Nano confirmation times are comparable to typical request-response internet latency. 63 | 64 | ### Principal Representatives vs Non-Principal Representatives 65 | 66 | There are two types of representatives in Nano: Principal Representatives (PR) and non-principal ones. To become a Principal Representative (PR), a Nano account must have at least 0.1% of [online voting weight](../glossary.md#online-voting-weight) delegated to it, but the only operational difference between the two representative types is that PR votes are rebroadcasted by other nodes who receive the votes, helping the network reach consensus more quickly. 67 | 68 | This implementation decision was made in part because of the exponential bandwidth cost of allowing every Nano node (potentially thousands) to send a vote to every other Nano node. Outside of PRs, the vast majority of nodes would not be able to meaningfully contribute to consensus due to their low vote weight delegation. The delegated vote weight for most nodes might only be a millionth of a percent vs total online vote weight, while >67% online vote weight is required for a transaction to achieve confirmation. A 0.1% minimum was thus chosen as a compromise. 69 | 70 | --- 71 | 72 | ## Incentives for participating in consensus 73 | [Incentives to run a node](https://medium.com/nanocurrency/the-incentives-to-run-a-node-ccc3510c2562) 74 | 75 | --- 76 | 77 | ## Block validation 78 | 79 | --- 80 | 81 | ## Voting 82 | 83 | ### Vote contents 84 | 85 | ### Vote-by-hash 86 | 87 | --- 88 | 89 | ## Fork handling 90 | 91 | ### Fork resolution 92 | 93 | #### Simple 94 | 95 | #### Complex 96 | 97 | ### Why PoW for receive blocks 98 | 99 | --- 100 | 101 | ## Quorum 102 | 103 | [^1]: "Block Confirmation Times", 2021. [Online]. Available: https://nanoticker.info 104 | [^2]: C. LeMahieu, "Emergent centralization due to economies of scale", 2020. [Online]. Available: https://medium.com/@clemahieu/emergent-centralization-due-to-economies-of-scale-83cc85a7cbef 105 | [^3]: Srayman, "Community Blog: Proposal for Nano Node Network Optimizations", 2020. [Online]. Available: https://medium.com/nanocurrency/proposal-for-nano-node-network-optimizations-21003e79cdba 106 | 107 | --- 108 | 109 | Existing whitepaper sections related to this page: 110 | 111 | * [System Overview](/whitepaper/english/#system-overview) 112 | * [Implementation](/whitepaper/english/#implementation) 113 | 114 | Existing content related to this page: 115 | 116 | * [Representatives and voting](/what-is-nano/overview/#representatives-and-voting) 117 | * [Representatives](/integration-guides/the-basics/#representatives) 118 | * [PoW for Receive block](https://github.com/nanocurrency/nano-node/issues/464#issuecomment-356467448) 119 | --------------------------------------------------------------------------------