[ { "path": ".github/workflows/build.yml", "content": "name: build\non: pull_request\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0\n - uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 #v4.3.0\n with:\n python-version: 3.x\n - run: pip install -r requirements.txt\n - run: mkdocs build --strict\n\nenv:\n GH_TOKEN: ${{ secrets.GH_TOKEN }}\n" }, { "path": ".github/workflows/cleanup-docker-pr.yml", "content": "name: cleanup-docker-pr\non:\n pull_request:\n types: [closed]\n\nenv:\n PR_NUMBER: ${{ github.event.number }}\n OWNER: orgs/nanocurrency\n PACKAGE_NAME: nano-docs\n PER_PAGE: 100\n\njobs:\n container_cleanup:\n runs-on: ubuntu-latest\n steps:\n - name: Clean up PR specific container\n uses: actions/github-script@d556feaca394842dc55e4734bf3bb9f685482fa0 #v6.3.3\n with:\n github-token: ${{ secrets.GHCR_TOKEN }}\n script: |\n const response = await github.request(\"GET /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions\",\n { per_page: ${{ env.PER_PAGE }}\n });\n for(version of response.data) {\n if (version.metadata.container.tags[0] == \"pr-${{ env.PR_NUMBER }}\") {\n console.log(\"delete \" + version.id)\n const deleteResponse = await github.request(\"DELETE /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions/\" + version.id, { });\n console.log(\"status \" + deleteResponse.status)\n }\n }\n" }, { "path": ".github/workflows/cleanup-docker-untagged.yml", "content": "name: cleanup-docker-untagged\non:\n push:\n branches:\n - main\n\nenv:\n OWNER: orgs/nanocurrency\n PACKAGE_NAME: nano-docs\n PER_PAGE: 100\n\njobs:\n container_cleanup:\n runs-on: ubuntu-latest\n steps:\n - name: Clean up untagged containers\n uses: actions/github-script@d556feaca394842dc55e4734bf3bb9f685482fa0 #v6.3.3\n with:\n github-token: ${{ secrets.GHCR_TOKEN }}\n script: |\n const response = await github.request(\"GET /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions\",\n { per_page: ${{ env.PER_PAGE }}\n });\n for(version of response.data) {\n if ( version.metadata.container.tags.length == 0 ) {\n console.log(\"delete \" + version.id)\n const deleteResponse = await github.request(\"DELETE /${{ env.OWNER }}/packages/container/${{ env.PACKAGE_NAME }}/versions/\" + version.id, { });\n console.log(\"status \" + deleteResponse.status)\n }\n }\n" }, { "path": ".github/workflows/deploy-staging.yml", "content": "name: deploy\non:\n push:\n branches:\n - staging\njobs:\n deploy:\n runs-on: ubuntu-latest\n env:\n PRODUCTION: TRUE\n if: github.repository == 'nanocurrency/nano-docs-staging'\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-python@v5\n with:\n python-version: 3.x\n - run: pip install -r requirements.txt\n - run: mkdocs gh-deploy --force\nenv:\n GH_TOKEN: ${{ secrets.GH_TOKEN }}\n" }, { "path": ".github/workflows/deploy.yml", "content": "name: deploy\non:\n push:\n branches:\n - main\njobs:\n deploy:\n runs-on: ubuntu-latest\n env:\n PRODUCTION: TRUE\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-python@v5\n with:\n python-version: 3.x\n - run: pip install -r requirements.txt\n - run: mkdocs gh-deploy --force\nenv:\n GH_TOKEN: ${{ secrets.GH_TOKEN }}\n" }, { "path": ".github/workflows/publish-docker-master.yml", "content": "name: publish-docker-master\non:\n push:\n branches:\n - main\n\njobs:\n build_publish:\n runs-on: ubuntu-latest\n env:\n PRODUCTION: TRUE\n steps:\n - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0\n\n # Build and test Docker image\n - run: |\n echo ${{ secrets.GHCR_TOKEN }} | docker login ghcr.io -u nanocurrency --password-stdin\n docker pull squidfunk/mkdocs-material:9.4.10@sha256:01605a03397a654b74b9de3157f56915d1e075e2d3bd22fcf3fb82c443553c25\n docker build -t ghcr.io/nanocurrency/nano-docs:latest .\n docker push ghcr.io/nanocurrency/nano-docs:latest\n" }, { "path": ".github/workflows/publish-docker-pr.yml", "content": "name: publish-docker-pr\non: pull_request\n\nenv:\n PR_NUMBER: ${{ github.event.number }}\n\njobs:\n build_publish:\n runs-on: ubuntu-latest\n env:\n PRODUCTION: TRUE\n steps:\n - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0\n\n # Build and test Docker image\n - run: |\n echo ${{ secrets.GHCR_TOKEN }} | docker login ghcr.io -u nanocurrency --password-stdin\n docker pull squidfunk/mkdocs-material:9.4.10@sha256:01605a03397a654b74b9de3157f56915d1e075e2d3bd22fcf3fb82c443553c25\n docker build -t ghcr.io/nanocurrency/nano-docs:pr-${{ env.PR_NUMBER }} .\n docker push ghcr.io/nanocurrency/nano-docs:pr-${{ env.PR_NUMBER }}\n" }, { "path": ".github/workflows/push-to-staging.yml", "content": "name: push-to-staging\non:\n workflow_dispatch:\n inputs:\n branch:\n description: \"nano-docs branch to push to staging\"\n default: \"staging\"\n required: true\n\njobs:\n push:\n runs-on: ubuntu-latest\n steps:\n - name: push\n uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 #v3.1.0\n with:\n fetch-depth: 0\n ref: ${{ github.event.inputs.branch }}\n token: ${{ secrets.GH_TOKEN }}\n - run: |\n git remote add nano-docs-staging https://github.com/nanocurrency/nano-docs-staging.git\n git push nano-docs-staging ${{ github.event.inputs.branch }}:staging" }, { "path": ".gitignore", "content": "site/\n.idea\nvenv\n.cache" }, { "path": "Dockerfile", "content": "FROM squidfunk/mkdocs-material:9.4.10@sha256:01605a03397a654b74b9de3157f56915d1e075e2d3bd22fcf3fb82c443553c25\n\n# Set build directory\n#WORKDIR /docs\n\n# Copy files necessary for build\nCOPY ./ /docs\n\nRUN \\\n pip install --upgrade pip && \\\n pip install -r /docs/requirements.txt\n\n# Set working directory\nWORKDIR /docs\n\n# Expose MkDocs development server port\nEXPOSE 8000\n\n# Start development server by default\nENTRYPOINT [\"mkdocs\"]\nCMD [\"serve\", \"--dev-addr=0.0.0.0:8000\"]\n" }, { "path": "docs/CNAME", "content": "docs.nano.org" }, { "path": "docs/articles/readme.md", "content": "Please see https://github.com/nanocurrency/nano-docs/issues/555 for details the article management process and list of ideas." }, { "path": "docs/commands/command-line-interface.md", "content": "title: Command Line Interface\ndescription: Reference for the CLI commands available for the nano node\n\n# Command Line Interface\n## nano_node commands\n| Command | Description |\n|---------|-------------| \n| `--account_create --wallet=` | Insert next deterministic key into `` |\n| `--account_get --key=` | Get account number for the `` |\n| `--account_key --account=` | Get the public key for `` |\n| `--clear_send_ids` | Remove all send IDs from the database (dangerous: not intended for production use). Optional `--data_path=`|\n| `--compare_rep_weights` | Displays a summarized comparison between the hardcoded bootstrap weights and representative weights from the ledger. Full comparison is output to logs. Optional `--data_path=`. |\n| `--confirmation_height_clear` | Requires `--account` and sets the confirmation heights of the specified account to 0. Use `all` to reset all accounts. Do not use while the node is running. |\n| `--daemon` | Start node daemon. Network and path will be output. |\n| `--diagnostics` | Run internal diagnostics and validate existing config file (or create default config file if it doesn't exist). |\n| `--final_vote_clear` | Either specify a single `--root` to clear or `--all` to clear all final votes (not recommended). |\n| `--generate_config node|rpc|log` | Write configuration to stdout, populated with commented-out defaults suitable for this system. Use `--use_defaults` for uncommented values. |\n| `--help` | Print out options. |\n| `--initialize` | Initializes the data folder, if it is not already initialized. Meant for an empty data folder. |\n| `--key_create` | Generates an adhoc random keypair and prints it to stdout. |\n| `--key_expand --key=` | Derive public key and account number from ``. |\n| `--migrate_database_lmdb_to_rocksdb` | Deletes existing rocksdb subfolder if it exists and migrates the ledger from LMDB to RocksDB. Does not delete the data.ldb file afterwards. Optional `--data_path=` |\n| `--online_weight_clear` | Clear record history for long term online weight trending. Optional `--data_path=`|\n| `--peer_clear` | Clear cached peers. Optional `--data_path=`|\n| `--rebuild_database` | Rebuild LMDB database with `--vacuum` for best compaction. Requires approximately `data.ldb size * 2` free space on disk. |\n| `--snapshot` | Compact database and create snapshot, functions similar to vacuum but does not replace the existing database. Optional: `--unchecked_clear`, `--clear_send_ids`, `--online_weight_clear`, `--peer_clear`, `--confirmation_height_clear`. |\n| `--unchecked_clear` | Clear unchecked blocks. Optional `--data_path=`|\n| `--update_config`| Reads the current node configuration and updates it with missing keys and values and delete keys that are no longer used. Updated configuration is written to stdout. |\n| `--vacuum` | Compact database. If `data_path` is missing, the database in the data directory is compacted. Optional: `--unchecked_clear`, `--clear_send_ids`, `--online_weight_clear`, `--peer_clear`, `--confirmation_height_clear`, `--rebuild_database`. Requires approximately `data.ldb size * 2` free space on disk. |\n| `--validate_blocks` | Validate blocks in the ledger, includes checks for confirmation height. Optional `--threads` for multithreaded validation. |\n| `--version` | Prints out version. |\n| `--wallet_add_adhoc`
  `--wallet=`
  `--key=` | Insert `` into ``. |\n| `--wallet_create`
  `--seed=`
  `--password=` | Creates a new wallet with optional `` and optional ``, and prints the ID. |\n| `--wallet_change_seed`
  `--wallet=`
  `--seed=` | Changes seed for `` to ``. |\n| `--wallet_decrypt_unsafe`
  `--wallet=`
  `--password=` | Decrypts `` using ``.
**USE WITH CAUTION: THIS WILL PRINT YOUR PRIVATE KEY AND SEED TO STDOUT** |\n| `--wallet_destroy --wallet=` | Destroys `` and all keys it contains. |\n| `--wallet_import`
  `--file=`
  `--wallet=`
  `--password=` | Imports keys in `` using `` into ``. If the wallet id does not exist and `--force` is included, a new wallet will be created with the provided wallet id value. |\n| `--wallet_list` | Dumps wallet IDs and public keys. |\n| `--wallet_remove`
  `--wallet=`
  `--account=` | Remove `` from ``. |\n| `--wallet_representative_get`
  `--wallet=` | Prints default representative for ``. |\n| `--wallet_representative_set`
`--wallet=`
  `--account=` | Set `` as default representative for ``. |\n\n## Launch Options\nThe node is typically run like this:\n\n```bash\n./nano_node --daemon [--launch_options]\n```\n!!! note \"Intended for developer use\"\n\tThese options are only for developer use so please understand the impacts before use.\n\n| Option | Description |\n|--------|-------------|\n| `--network` | Allows selection of a different network at runtime. Values `live`, `beta` and `test` supported. |\n| `--data_path=` | Use the supplied `` as the data directory. |\n| `--config key=value` | Pass node configuration values. This takes precedence over any values in the configuration file. This option can be repeated multiple times. |\n| `--rpcconfig key=value` | Pass RPC configuration values. This takes precedence over any values in the configuration file. This option can be repeated multiple times. |\n| `--enable_pruning` | \"Enable experimental ledger pruning\" |\n| `--block_processor_batch_size` | Increase block processor transaction batch write size, default 0 (limited by config block_processor_batch_max_time), 256k for fast_bootstrap. |\n| `--block_processor_full_size` | Increase block processor allowed blocks queue size before dropping live network packets and holding bootstrap download, default 65536, 1 million for fast_bootstrap. |\n| `--block_processor_verification_size` | Increase batch signature verification size in block processor, default 0 (limited by config signature_checker_threads), unlimited for fast_bootstrap. |\n| `--fast_bootstrap` | **legacy bootstrap:** Increase bootstrap processor limits to allow more blocks before hitting full state and verify/write more per database call. Also disable deletion of processed unchecked blocks. |\n| `--allow_bootstrap_peers_duplicates` | **legacy bootstrap:** Allow multiple connections to the same peer in bootstrap attempts. |\n| `--inactive_votes_cache_size` | Increase cached votes without active elections size, default 16384. |\n| `--vote_processor_capacity` | Vote processor queue size before dropping votes, default 144k. |\n| `--disable_activate_successors` | Disables activate_successors in active_elections |\n| `--disable_add_initial_peers` | Disables the add initial peers function called on startup which reads the peers table and contacts all the peers listed in it. |\n| `--disable_ascending_bootstrap` | Disable ascending bootstrap |\n| `--disable_backup` | Turn off automatic wallet backup process. |\n| `--disable_block_processor_republishing` | Disables block republishing by disabling the local_block_broadcaster component |\n| `--disable_block_processor_unchecked_deletion` | Disable deletion of unchecked blocks after processing. |\n| `--disable_bootstrap_bulk_pull_server` | Disables the legacy bulk pull server for bootstrap operations |\n| `--disable_bootstrap_bulk_push_client` | Disables the legacy bulk push client for bootstrap operations | \n| `--disable_bootstrap_listener` | Turn off listener on the bootstrap network so incoming TCP (bootstrap) connections are rejected. Note: this does not impact TCP traffic for the live network. |\n| `--disable_lazy_bootstrap` | Turn off use of lazy bootstrap. |\n| `--disable_legacy_bootstrap` | Turn off use of legacy bootstrap. |\n| `--disable_max_peers_per_ip` | Disables the limit on the number of peer connections allowed per IP address |\n| `--disable_max_peers_per_subnetwork` | Disables the limit on the number of peer connections allowed per subnetwork |\n| `--disable_ongoing_bootstrap` | Turn off the ability for ongoing bootstraps to occur. |\n| `--disable_ongoing_telemetry_requests` | Disables ongoing telemetry requests to peers | \n| `--disable_providing_telemetry_metrics` | Do not provide any telemetry data to nodes requesting it. Responses are still made to requests, but they will have an empty payload. |\n| `--disable_rep_crawler` | Turn off the rep crawler process. |\n| `--disable_request_loop` | Turn off the request loop. |\n| `--disable_search_pending` | Disables the periodic search for pending transactions | \n| `--disable_tcp_realtime` | Turn off use of TCP live network (TCP for bootstrap will remain available). |\n| `--disable_unchecked_cleanup` | Prevent periodic cleaning of unchecked table. |\n| `--disable_unchecked_drop` | Prevent drop of all unchecked entries at node/wallet start. |\n| `--disable_wallet_bootstrap` | Turn off use of wallet-based bootstrap. |\n\n## Debug commands\n| Command | Description |\n|---------|-------------|\n| `--debug_account_count` | Display the number of accounts. |\n| `--debug_account` | Display the total counts of each version for all accounts (including unpocketed). |\n| `--debug_block_count` | Display the number of blocks. |\n| `--debug_block_dump` | Print ledger blocks - use with caution due to the potentially large amount of data this can output. |\n| `--debug_bootstrap_generate` | Generate bootstrap sequence of blocks. |\n| `--debug_cemented_block_count` | Display the number of cemented blocks (blocks which are under the confirmation height of their accounts). |\n| `--debug_dump_frontier_unchecked_dependents` | Dump frontiers which have matching unchecked keys. |\n| `--debug_dump_online_weight` | List online weights table and current online_weights value. |\n| `--debug_dump_representatives` | List representatives and weights. |\n| `--debug_generate_crash_report` | After a node crash on Linux, this command reads the dump files generated from that crash and produces a \"nano_node_crash_report.txt\" file. Requires `addr2line` to be installed on the system. |\n| `--debug_opencl` | Profile OpenCL work generation for (optional) `--device=` on `--device=` using `--threads=` count. |\n| `--debug_output_last_backtrace_dump` | Output the stacktrace stored after a node crash. |\n| `--debug_profile_bootstrap` | Profile simulated bootstrap process. |\n| `--debug_profile_frontiers_confirmation` | Profile frontiers confirmation speed. |\n| `--debug_profile_generate` | Profile work generation. Optional: `--pow_sleep_interval` which sets an amount to sleep (in nanoseconds) between batches of POW calculations when using the CPU. `--difficulty`, `--multiplier` (only the latter is used if both given) to set the work generation threshold. |\n| `--debug_profile_kdf` | Profile kdf function. |\n| `--debug_profile_sign` | Profile signature generation. |\n| `--debug_profile_validate` | Profile work validation. |\n| `--debug_profile_votes` | Profile vote verification. |\n| `--debug_rpc` | Allows running RPC commands without enabling the RPC server. Not recommended for daily usage. Example: `echo '{\"action\": \"block_count\"}' | nano_node --debug_rpc` |\n| `--debug_stacktrace` | Prints a stacktrace example, useful to verify that it includes the desired information, such as files, function names and line numbers. |\n| `--debug_sys_logging` | On *nix system this checks writing to the system log. On Windows it writes to the event viewer, a registry entry needs to exist for this to work correctly which can be created by running this command for the first time as an administrator. |\n| `--debug_unconfirmed_frontiers` | Prints the account, height, frontiers and cemented frontier for all accounts which are not fully confirmed. Sorted by height in descending order. |\n| `--debug_validate_blocks` | Alias to `--validate_blocks`. |\n| `--debug_verify_profile` | Profile signature verification. |\n| `--debug_dump_trended_weight`| Dump trended weights table |\n| `--debug_profile_process`| Profile active blocks processing (only for nano_dev_network)|\n| `--debug_random_feed`| Generates output to RNG test suites |\n| `--debug_peers`| Display peer IPv6:port connections |\n| `--debug_prune`| Prune accounts up to last confirmed blocks **EXPERIMENTAL**|\n\n## Removed\n\n| Command | Description |\n|---------|-------------|\n| `--vote_dump` | Dump most recent votes from representatives. |\n" }, { "path": "docs/commands/rpc-protocol.md", "content": "title: RPC Protocol\ndescription: Reference for the RPC commands available for the Nano node\n\n# RPC Protocol\n\nThe RPC protocol accepts JSON HTTP POST requests. The following are RPC commands along with the responses that are expected. This page is split into the following sections:\n\n| Section | Purpose |\n|---------|---------|\n| **[Node RPCs](#node-rpcs)** | For interacting with the node and ledger. |\n| **[Wallet RPCs](#wallet-rpcs)** | For interacting with the built-in, QT-based node wallet. **NOTE**: This wallet is only recommended for development and testing. |\n| **[Unit Conversion RPCs](#unit-conversion-rpcs)** | For converting different units to and from raw. |\n| **[Deprecated RPCs](#deprecated-rpcs)** | No longer recommended for use. |\n\n## Node RPCs\n\n!!! warning \"Unconfirmed blocks returned\"\n Unless otherwise specified, RPC calls can return unconfirmed blocks and related details. In the most important cases where balances or similar details may include unconfirmed amounts, additional warnings have been included. Refer to [Block confirmation procedures](/integration-guides/key-management/#block-confirmation-procedures) for details.\n\n---\n\n### account_balance \nReturns how many RAW is owned and how many have not yet been received by **account** \n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json \n{\n \"action\": \"account_balance\",\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n```\n\n**Response:**\n```json\n{\n \"balance\": \"10000\",\n \"pending\": \"10000\",\n \"receivable\": \"10000\"\n}\n```\n\n**Optional \"include_only_confirmed\"**\n_version 22.0+_ \nBoolean, true by default. Results in `balance` only including blocks on this account that have already been confirmed and `receivable` only including incoming send blocks that have already been confirmed on the sending account.\n\n---\n\n### account_block_count\nGet number of blocks for a specific **account** \n\n**Request:**\n```json\n{\n \"action\": \"account_block_count\",\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n}\n```\n\n**Response:**\n```json\n{\n \"block_count\" : \"19\"\n}\n```\n\n---\n\n### account_get\nGet account number for the **public key** \n\n**Request:**\n```json\n{\n \"action\": \"account_get\",\n \"key\": \"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039\"\n}\n```\n\n**Response:**\n```json\n{\n \"account\" : \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}\n```\n\n---\n\n### account_history \n\nReports send/receive information for an account. Returns only **send & receive** blocks by default (unless raw is set to true - see optional parameters below): change, state change & state epoch blocks are skipped, open & state open blocks will appear as receive, state receive/send blocks will appear as receive/send entries. Response will start with the latest block for the account (the frontier), and will list all blocks back to the open block of this account when \"count\" is set to \"-1\". **Note**: \"local_timestamp\" returned since version 18.0, \"height\" field returned since version 19.0 and \"confirmed\" returned since version 23.0\n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n**Request:**\n```json\n{\n \"action\": \"account_history\",\n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"count\": \"1\"\n}\n```\n\n**Response:**\n```json\n{\n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"history\": [\n {\n \"type\": \"send\",\n \"account\": \"nano_38ztgpejb7yrm7rr586nenkn597s3a1sqiy3m3uyqjicht7kzuhnihdk6zpz\",\n \"amount\": \"80000000000000000000000000000000000\",\n \"local_timestamp\": \"1551532723\",\n \"height\": \"60\",\n \"hash\": \"80392607E85E73CC3E94B4126F24488EBDFEB174944B890C97E8F36D89591DC5\",\n \"confirmed\": \"true\"\n }\n ],\n \"previous\": \"8D3AB98B301224253750D448B4BD997132400CEDD0A8432F775724F2D9821C72\"\n}\n```\n\nIf the `count` limit results in stopping before the end of the account chain, then the response will also contain a `previous` field (outside of the `history` field) which contains the block hash that would be next to process if `count` was larger.\n\n**Optional parameters:**\n\n- `raw` (bool): if set to `true` instead of the default `false`, instead of outputting a simplified send or receive explanation of blocks (intended for wallets), output all parameters of the block itself as seen in block_create or other APIs returning blocks. It still includes the \"account\" and \"amount\" properties you'd see without this option. State/universal blocks in the raw history will also have a `subtype` field indicating their equivalent \"old\" block. Unfortunately, the \"account\" parameter for open blocks is the account of the source block, not the account of the open block, to preserve similarity with the non-raw history. \n- `head` (64 hexadecimal digits string, 256 bit): instead of using the latest block for a specified account, use this block as the head of the account instead. Useful for pagination.\n- `include_linked_account` (bool): _version 28.0+._ When set to `true`, the response will include a new field `linked_account`, which returns the linked account associated with the block (or \"0\" if no linked account exists/was found e.g. due to pruning).\n- `offset` (decimal integer): skips a number of blocks starting from `head` (if given). Not often used. _Available since version 11.0_ \n- `reverse` (bool): if set to `true` instead of the default `false`, the response starts from `head` (if given, otherwise the first block of the account), and lists blocks up to the frontier (limited by \"count\"). **Note**: the field `previous` in the response changes to `next`. _Available since version 19.0_ \n- `account_filter` (array of public addresses): results will be filtered to only show sends/receives connected to the provided account(s). _Available since version 19.0_. **Note:** In v19.0, this option does not handle receive blocks; fixed in v20.0.\n\n---\n\n### account_info\nReturns frontier, open block, change representative block, balance, last modified timestamp from local database & block count for **account**. Only works for accounts that have received their first transaction and have an entry on the ledger, will return \"Account not found\" otherwise. To open an account, use [receive](#receive). \n\n--8<-- \"unconfirmed-information.md\"\n The balance is obtained from the frontier, which may be unconfirmed. As long as you follow the [guidelines](/integration-guides/key-management/#transaction-order-and-correctness), you can rely on the **balance** for the purposes of creating transactions for this account. If the frontier is never confirmed, then the blocks that proceed it will also never be confirmed.\n\n If you need only details for confirmed blocks, use the `include_confirmed` option below and referenced the `confirmed_*` fields added in to the response.\n\n**Request:**\n```json\n{\n \"action\": \"account_info\",\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n}\n```\n\n**Response:**\n```json\n{\n \"frontier\": \"FF84533A571D953A596EA401FD41743AC85D04F406E76FDE4408EAED50B473C5\",\n \"open_block\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"representative_block\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"balance\": \"235580100176034320859259343606608761791\",\n \"modified_timestamp\": \"1501793775\",\n \"block_count\": \"33\",\n \"account_version\": \"1\",\n \"confirmation_height\" : \"28\",\n \"confirmation_height_frontier\" : \"34C70FCA0952E29ADC7BEE6F20381466AE42BD1CFBA4B7DFFE8BD69DF95449EB\"\n}\n```\n\nIn response `confirmation_height` only available for _version 19.0+_ \nIn response `confirmation_height_frontier` only available for _version 21.0+_ which is the block hash at that confirmation height. \n\n**Optional \"include_confirmed\"**\n_version 22.0+_ \nBoolean, false by default. Adds new return fields with prefix of `confirmed_` for consistency:\n\n- `confirmed_balance`: balance for only blocks on this account that have already been confirmed\n- `confirmed_height`: matches `confirmation_height` value\n- `confirmed_frontier`: matches `confirmation_height_frontier` value\n- If `representative` option also `true`, `confirmed_representative` included: representative account from the confirmed frontier block\n- If `receivable` option also `true`, `confirmed_receivable` included: balance of all receivable amounts where the matching incoming send blocks have been confirmed on their account\n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json\n{\n \"action\": \"account_info\", \n \"account\": \"nano_1gyeqc6u5j3oaxbe5qy1hyz3q745a318kh8h9ocnpan7fuxnq85cxqboapu5\",\n \"representative\": \"true\",\n \"weight\": \"true\",\n \"receivable\": \"true\",\n \"include_confirmed\": \"true\"\n}\n```\n\n**Response:**\n```json\n{\n \"frontier\": \"80A6745762493FA21A22718ABFA4F635656A707B48B3324198AC7F3938DE6D4F\",\n \"open_block\": \"0E3F07F7F2B8AEDEA4A984E29BFE1E3933BA473DD3E27C662EC041F6EA3917A0\",\n \"representative_block\": \"80A6745762493FA21A22718ABFA4F635656A707B48B3324198AC7F3938DE6D4F\",\n \"balance\": \"11999999999999999918751838129509869131\",\n \"confirmed_balance\": \"11999999999999999918751838129509869131\",\n \"modified_timestamp\": \"1606934662\",\n \"block_count\": \"22966\",\n \"account_version\": \"1\",\n \"confirmed_height\": \"22966\",\n \"confirmed_frontier\": \"80A6745762493FA21A22718ABFA4F635656A707B48B3324198AC7F3938DE6D4F\",\n \"representative\": \"nano_1gyeqc6u5j3oaxbe5qy1hyz3q745a318kh8h9ocnpan7fuxnq85cxqboapu5\",\n \"confirmed_representative\": \"nano_1gyeqc6u5j3oaxbe5qy1hyz3q745a318kh8h9ocnpan7fuxnq85cxqboapu5\",\n \"weight\": \"11999999999999999918751838129509869131\",\n \"pending\": \"0\",\n \"receivable\": \"0\",\n \"confirmed_pending\": \"0\",\n \"confirmed_receivable\": \"0\"\n}\n```\n\n**Optional \"representative\", \"weight\", \"pending\"**\n_version 9.0+_ \nBooleans, false by default. Additionally returns representative, voting weight, pending/receivable balance for account \n\n**Request:**\n```json\n{\n \"action\": \"account_info\",\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\",\n \"representative\": \"true\",\n \"weight\": \"true\",\n \"pending\": \"true\"\n}\n```\n\n**Response:**\n```json\n{\n \"frontier\": \"FF84533A571D953A596EA401FD41743AC85D04F406E76FDE4408EAED50B473C5\",\n \"open_block\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"representative_block\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"balance\": \"235580100176034320859259343606608761791\",\n \"modified_timestamp\": \"1501793775\",\n \"block_count\": \"33\",\n \"account_version\": \"1\",\n \"confirmation_height\" : \"28\",\n \"confirmation_height_frontier\" : \"34C70FCA0952E29ADC7BEE6F20381466AE42BD1CFBA4B7DFFE8BD69DF95449EB\",\n \"representative\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\",\n \"weight\": \"1105577030935649664609129644855132177\",\n \"pending\": \"2309370929000000000000000000000000\",\n \"receivable\": \"2309370929000000000000000000000000\"\n}\n```\n\n---\n\n### account_key\nGet the public key for **account** \n\n**Request:**\n```json\n{\n \"action\": \"account_key\",\n \"account\" : \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}\n``` \n**Response:**\n```json\n{\n \"key\": \"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039\"\n}\n```\n\n---\n\n### account_representative \nReturns the representative for **account** \n\n**Request:**\n```json\n{\n \"action\": \"account_representative\",\n \"account\": \"nano_39a73oy5ungrhxy5z5oao1xso4zo7dmgpjd4u74xcrx3r1w6rtazuouw6qfi\"\n}\n``` \n**Response:**\n```json\n{\n \"representative\" : \"nano_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5\"\n}\n```\n\n---\n\n### account_weight \nReturns the voting weight for **account** \n\n**Request:**\n```json\n{\n \"action\": \"account_weight\",\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n``` \n**Response:**\n```json\n{\n \"weight\": \"10000\"\n}\n```\n\n---\n\n### accounts_balances \nReturns how many RAW is owned and how many have not yet been received by **accounts list** \n\n--8<-- \"unconfirmed-information.md\"\n The receivable balances are calculated from potentially unconfirmed blocks. Account balances are obtained from their frontiers. An atomic [account_info](#account_info) RPC call is recommended for the purposes of creating transactions.\n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json\n{\n \"action\": \"accounts_balances\",\n \"accounts\": [\"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\", \"nano_3i1aq1cchnmbn9x5rsbap8b15akfh7wj7pwskuzi7ahz8oq6cobd99d4r3b7\"]\n}\n``` \n**Response:**\n```json\n{\n \"balances\" : {\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": {\n \"balance\": \"325586539664609129644855132177\",\n \"pending\": \"2309372032769300000000000000000000\",\n \"receivable\": \"2309372032769300000000000000000000\"\n },\n \"nano_3i1aq1cchnmbn9x5rsbap8b15akfh7wj7pwskuzi7ahz8oq6cobd99d4r3b7\":\n {\n \"balance\": \"10000000\",\n \"pending\": \"0\",\n \"receivable\": \"0\"\n }\n }\n}\n``` \n\n**Optional \"include_only_confirmed\"**\n_version 25.0+_ \nBoolean, true by default. Results in `balance` only including blocks on the provided account that have already been confirmed and `receivable` only including incoming send blocks that have already been confirmed on the sending account.\n\n!!! info \"Error handling\"\n With _version 25.0+_, `accounts_balances` response errors come in a different entry, named as `errors`. This\n fixes the breaking change added in V24.0. Please notice that when an account is not found in the ledger, no error\n is returned anymore. It now returns a zero balance and zero as receivable.\n ```json\n {\n \"balances\": {\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": {\n \"balance\": \"325586539664609129644855132177\",\n \"pending\": \"2309370929000000000000000000000000\",\n \"receivable\": \"2309370929000000000000000000000000\"\n },\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": {\n \"balance\": \"0\",\n \"pending\": \"0\",\n \"receivable\": \"0\"\n }\n },\n \"errors\": {\n \"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\": \"Bad account number\"\n }\n }\n ```\n If all requested entries result in errors, no entry will be added in the response for `balances`. Similarly,\n if there are no errors, no entry will be added for `errors`. \n Request:\n ```json\n { \n \"action\": \"accounts_balances\", \n \"accounts\": [\"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\"] \n }\n ```\n Response:\n ```json\n {\n \"errors\": {\n \"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\": \"Bad account number\"\n }\n }\n ```\n In _version 24.0+_, `accounts_balances` response errors are returned per account entry in `balances` object.\n If an account does not exist, zero balance and zero receivables should be returned, but V24.0 has a bug: unopened\n accounts with receivables return an error instead of the receivables.\n ```json\n {\n \"balances\": {\n \"nano_3wfddg7a1paogrcwi3yhwnaerboukbr7rs3z3ino5toyq3yyhimo6f6egij6\": {\n \"balance\": \"442000000000000000000000000000\",\n \"pending\": \"0\",\n \"receivable\": \"0\"\n },\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": {\n \"error\": \"Account not found\"\n }\n }\n }\n ```\n\n\n---\n\n### accounts_frontiers \nReturns a list of pairs of account and block hash representing the head block for **accounts list** \n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n**Request:**\n```json\n{\n \"action\": \"accounts_frontiers\",\n \"accounts\": [\"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\", \"nano_3i1aq1cchnmbn9x5rsbap8b15akfh7wj7pwskuzi7ahz8oq6cobd99d4r3b7\"]\n}\n``` \n**Response:**\n```json\n{\n \"frontiers\" : {\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": \"791AF413173EEE674A6FCF633B5DFC0F3C33F397F0DA08E987D9E0741D40D81A\",\n \"nano_3i1aq1cchnmbn9x5rsbap8b15akfh7wj7pwskuzi7ahz8oq6cobd99d4r3b7\": \"6A32397F4E95AF025DE29D9BF1ACE864D5404362258E06489FABDBA9DCCC046F\"\n }\n}\n``` \n\n!!! info \"Error handling\"\n With _version 25.0+_, `accounts_frontiers` response errors come in a different entry, named `errors`.\n ```json\n {\n \"frontiers\": {\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": \"023B94B7D27B311666C8636954FE17F1FD2EAA97A8BAC27DE5084FBBD5C6B02C\"\n },\n \"errors\": {\n \"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\": \"Bad account number\",\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": \"Account not found\"\n }\n }\n ```\n If all requested entries result in errors, no entry will be added in the response for `frontiers`. Similarly,\n if there are no errors, no entry will be added for `errors`. \n Request:\n ```json\n { \n \"action\": \"accounts_frontiers\", \n \"accounts\": [\"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\"] \n }\n ```\n Response: \n ```json\n {\n \"errors\": {\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": \"Account not found\"\n }\n }\n ```\n In _version 24.0+_, `accounts_frontiers` response errors were returned per account entry in the\n `frontiers` object.\n ```json\n {\n \"frontiers\": {\n \"nano_3wfddg7a1paogrcwi3yhwnaerboukbr7rs3z3ino5toyq3yyhimo6f6egij6\": \"75BD65296241EB871918EBE3E99E9A191970A2724B3214B27F8AB205FF4FC30A\",\n \"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\": \"error: Bad account number\",\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": \"error: Account not found\"\n }\n }\n ```\n\n---\n\n### accounts_receivable \n\n_since V24.0, use [accounts_pending](#accounts_pending) for V23.3 and below_\n\nReturns a list of confirmed block hashes which have not yet been received by these **accounts** \n\n**Request:**\n```json\n{\n \"action\": \"accounts_receivable\",\n \"accounts\": [\"nano_1111111111111111111111111111111111111111111111111117353trpda\", \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"],\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": [\"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D\"],\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": [\"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74\"]\n }\n}\n``` \n**Optional \"threshold\"** \n_version 8.0+_ \nNumber (128 bit, decimal). Returns a list of receivable block hashes with amount more or equal to **threshold** \n\n**Request:**\n```json\n{\n \"action\": \"accounts_receivable\",\n \"accounts\": [\"nano_1111111111111111111111111111111111111111111111111117353trpda\", \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"],\n \"count\": \"1\",\n \"threshold\": \"1000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": {\n \"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D\": \"6000000000000000000000000000000\"\n },\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": {\n \"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74\": \"106370018000000000000000000000000\"\n }\n }\n}\n``` \n**Optional \"source\"** \n_version 9.0+_ \nBoolean, false by default. Returns a list of receivable block hashes with amount and source accounts \n\n**Request:**\n```json\n{\n \"action\": \"accounts_receivable\",\n \"accounts\": [\"nano_1111111111111111111111111111111111111111111111111117353trpda\", \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"],\n \"count\": \"1\",\n \"source\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": {\n \"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D\": {\n \"amount\": \"6000000000000000000000000000000\",\n \"source\": \"nano_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr\"\n }\n },\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": {\n \"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74\": {\n \"amount\": \"106370018000000000000000000000000\",\n \"source\": \"nano_13ezf4od79h1tgj9aiu4djzcmmguendtjfuhwfukhuucboua8cpoihmh8byo\"\n }\n }\n }\n}\n``` \n**Optional \"include_active\"**\n\n_version 15.0+_ \nBoolean, false by default. Include active (not confirmed) blocks \n\n**Request:**\n```json\n{\n \"action\": \"accounts_receivable\",\n \"accounts\": [\"nano_1111111111111111111111111111111111111111111111111117353trpda\", \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"],\n \"count\": \"1\",\n \"include_active\": \"true\"\n}\n``` \n\n**Optional \"sorting\"**\n\n_version 19.0+_ \nBoolean, false by default. Additionally sorts each account's blocks by their amounts in descending order.\n\n**Optional \"include_only_confirmed\"**\n\n_version 19.0+_ \nBoolean, true by default (_version 22.0+_), previously false by default. Only returns confirmed blocks but with the caveat that their confirmation height might not be up-to-date yet. If false, unconfirmed blocks will also be returned.\n\n---\n\n### accounts_representatives \nReturns the representatives for given **accounts** \n\n**Request:**\n```json\n{\n \"action\": \"accounts_representatives\",\n \"accounts\": [\"nano_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5\",\"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"]\n}\n``` \n**Response:**\n```json\n{\n \"representatives\" : {\n \"nano_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5\": \"nano_3hd4ezdgsp15iemx7h81in7xz5tpxi43b6b41zn3qmwiuypankocw3awes5k\",\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n }\n}\n```\n\n!!! info \"Error handling\"\n With _version 25.0+_, `accounts_representatives` response errors come in a different entry, named `errors`.\n ```json\n {\n \"representatives\": {\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n },\n \"errors\": {\n \"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\": \"Bad account number\",\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": \"Account not found\"\n }\n }\n ```\n If all requested entries result in errors, no entry will be added in the response for `representatives`. Similarly,\n if there are no errors, no entry will be added for `errors`. \n Request:\n ```json\n { \n \"action\": \"accounts_representatives\", \n \"accounts\": [\"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\"] \n }\n ```\n Response: \n ```json\n {\n \"errors\": {\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": \"Account not found\"\n }\n }\n ```\n In _version 24.0+_, `accounts_representatives` response errors were returned per account entry in the\n `representatives` object.\n ```json\n {\n \"representatives\": {\n \"nano_3wfddg7a1paogrcwi3yhwnaerboukbr7rs3z3ino5toyq3yyhimo6f6egij6\": \"nano_3wfddg7a1paogrcwi3yhwnaerboukbr7rs3z3ino5toyq3yyhimo6f6egij6\",\n \"nano_36uccgpjzhjsdbj44wm1y5hyz8gefx3wjpp1jircxt84nopxkxti5bzq1rnz\": \"error: Bad account number\",\n \"nano_1hrts7hcoozxccnffoq9hqhngnn9jz783usapejm57ejtqcyz9dpso1bibuy\": \"error: Account not found\"\n }\n }\n ```\n\n---\n\n### available_supply \nReturns how many raw are in the public supply \n\n**Request:**\n```json\n{\n \"action\": \"available_supply\"\n}\n``` \n**Response:**\n```json\n{\n \"available\": \"133248061996216572282917317807824970865\"\n}\n```\n\n---\n\n### block_account \nReturns the account containing block \n\n**Request:**\n```json\n{\n \"action\": \"block_account\",\n \"hash\": \"023B94B7D27B311666C8636954FE17F1FD2EAA97A8BAC27DE5084FBBD5C6B02C\"\n}\n``` \n**Response:**\n```json\n{\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n}\n```\n\n---\n\n### block_confirm \n_version 12.2+_ \nRequest confirmation for **block** from known online representative nodes. Check results with [confirmation history](#confirmation_history).\n\n**Request:**\n```json\n{\n \"action\": \"block_confirm\",\n \"hash\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"started\": \"1\"\n}\n```\n\n**NOTE:** Unless there was an error encountered during the command, the response will always return `\"started\": \"1\"`. This response does not indicate the block was successfully confirmed, only that an error did not occur. This response happens even if the block has already been confirmed previously and notifications will be triggered for this block (via HTTP callbacks or WebSockets) in all cases. This behavior may change in a future release.\n\n---\n\n### block_count \nReports the number of blocks in the ledger and unchecked synchronizing blocks \n\n**Request:**\n```json\n{\n \"action\": \"block_count\"\n}\n``` \n**Response:**\n```json\n{\n \"count\": \"1000\",\n \"unchecked\": \"10\",\n \"cemented\": \"25\"\n}\n```\n**Note:** If the node is running the RocksDB backend the unchecked count may only be estimate. \n\n**Optional \"include_cemented\"**\n\n_version 19.0+ (enable_control required in version 19.0, not required in version 20.0+)_ \nDefault \"true\". If \"true\", \"cemented\" in the response will contain the number of cemented blocks. (In V19.0 default was \"false\")\n\n--8<-- \"warning-enable-control.md\"\n\n---\n\n### block_create\n_enable_control required, version 9.0+_ \nCreates a json representations of new block based on input data & signed with **private key** or **account** in **wallet**. Use for offline signing. Using the optional `json_block` is recommended since v19.0. \n\n--8<-- \"warning-enable-control.md\"\n\n\n**Request sample for state block:** \n```json\n{\n \"action\": \"block_create\",\n \"json_block\": \"true\",\n \"type\": \"state\",\n \"balance\": \"1000000000000000000000\",\n \"key\": \"0000000000000000000000000000000000000000000000000000000000000002\",\n \"representative\": \"nano_1hza3f7wiiqa7ig3jczyxj5yo86yegcmqk3criaz838j91sxcckpfhbhhra1\",\n \"link\": \"19D3D919475DEED4696B5D13018151D1AF88B2BD3BCFF048B45031C1F36D1858\",\n \"previous\": \"F47B23107E5F34B2CE06F562B5C435DF72A533251CB414C51B2B62A8F63A00E4\"\n}\n``` \nParameters for state block:\n\n* `balance`: **final** balance for account after block creation, formatted in 'raw' units using a decimal integer. If balance is less than previous, block is considered as send subtype!\n* `wallet` (optional): The wallet ID that the account the block is being created for is in.\n* `account` (optional): The [account](../glossary.md#account) the block is being created for.\n* `key` (optional): Instead of using \"wallet\" & \"account\" parameters, you can directly pass in a private key.\n* `source` (optional): The block hash of the source of funds for this receive block (the send block that this receive block will pocket).\n* `destination` (optional): The [account](../glossary.md#account) that the sent funds should be accessible to.\n* `link` (optional): Instead of using \"source\" and \"destination\" parameters, you can directly pass \"link\". If the block is sending funds, set link to the public key of the destination account. If it is receiving funds, set link to the hash of the block to receive. If the block has no balance change but is updating representative only, set link to 0. See [Block format section](../integration-guides/the-basics.md#block-format) for more information\n* `representative`: The [account](../glossary.md#account) that block account will use as its representative.\n* `previous`: The block hash of the previous block on this account's block chain (\"0\" for first block).\n\n**Warning:** It is **critical** that `balance` is the balance of the account **after** created block!\n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"block\" in the response will contain a JSON subtree instead of a JSON string.\n \n**Optional \"work\"**\n\nWork value (16 hexadecimal digits string, 64 bit). Uses **work** value for block from external source \n\n**Optional \"version\"**\n\n_version 21.0+_\nWork version string. Currently \"work_1\" is the default and only valid option. Only used if optional **work** is not given.\n\n**Optional \"difficulty\"**\n\n_version 21.0+_ \nDifficulty value (16 hexadecimal digits string, 64 bit). Uses **difficulty** value to generate work. Only used if optional **work** is not given. \n\nIf difficulty and work values are both not given, RPC processor tries to calculate difficulty for work generation based on ledger data: epoch from previous block or from link for receive subtype; block subtype from previous block balance. \n\n**Examples**\n\n**Response sample for above request**: \n```json\n{\n \"hash\": \"FF0144381CFF0B2C079A115E7ADA7E96F43FD219446E7524C48D1CC9900C4F17\",\n \"difficulty\": \"ffffffe1278b3dc6\", // since V21.0\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_3qgmh14nwztqw4wmcdzy4xpqeejey68chx6nciczwn9abji7ihhum9qtpmdr\",\n \"previous\": \"F47B23107E5F34B2CE06F562B5C435DF72A533251CB414C51B2B62A8F63A00E4\",\n \"representative\": \"nano_1hza3f7wiiqa7ig3jczyxj5yo86yegcmqk3criaz838j91sxcckpfhbhhra1\",\n \"balance\": \"1000000000000000000000\",\n \"link\": \"19D3D919475DEED4696B5D13018151D1AF88B2BD3BCFF048B45031C1F36D1858\",\n \"link_as_account\": \"nano_18gmu6engqhgtjnppqam181o5nfhj4sdtgyhy36dan3jr9spt84rzwmktafc\",\n \"signature\": \"3BFBA64A775550E6D49DF1EB8EEC2136DCD74F090E2ED658FBD9E80F17CB1C9F9F7BDE2B93D95558EC2F277FFF15FD11E6E2162A1714731B743D1E941FA4560A\",\n \"work\": \"cab7404f0b5449d0\"\n }\n}\n``` \n\n---\n\n### block_hash \n_version 13.0+_ \nReturning block hash for given **block** content. Using the optional `json_block` is recommended since v19.0. \n\n**Request:**\n```json\n{ \n \"action\": \"block_hash\",\n \"json_block\": \"true\", \n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_3qgmh14nwztqw4wmcdzy4xpqeejey68chx6nciczwn9abji7ihhum9qtpmdr\",\n \"previous\": \"F47B23107E5F34B2CE06F562B5C435DF72A533251CB414C51B2B62A8F63A00E4\",\n \"representative\": \"nano_1hza3f7wiiqa7ig3jczyxj5yo86yegcmqk3criaz838j91sxcckpfhbhhra1\",\n \"balance\": \"1000000000000000000000\",\n \"link\": \"19D3D919475DEED4696B5D13018151D1AF88B2BD3BCFF048B45031C1F36D1858\",\n \"link_as_account\": \"nano_18gmu6engqhgtjnppqam181o5nfhj4sdtgyhy36dan3jr9spt84rzwmktafc\",\n \"signature\": \"3BFBA64A775550E6D49DF1EB8EEC2136DCD74F090E2ED658FBD9E80F17CB1C9F9F7BDE2B93D95558EC2F277FFF15FD11E6E2162A1714731B743D1E941FA4560A\",\n \"work\": \"cab7404f0b5449d0\"\n }\n}\n``` \n**Response:**\n```json\n{\n \"hash\": \"FF0144381CFF0B2C079A115E7ADA7E96F43FD219446E7524C48D1CC9900C4F17\"\n}\n```\n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"block\" must contain a JSON subtree instead of a JSON string.\n\n---\n\n### block_info \nRetrieves a json representation of the block in `contents` along with:\n\n* _since version 18.0_: `block_account`, transaction `amount`, block `balance`, block `height` in account chain, block local modification `timestamp`\n* _since version 19.0_: Whether block was `confirmed`, `subtype` (_for state blocks_) of `send`, `receive`, `change` or `epoch`\n* _since version 23.0_: `successor` returned\n\nUsing the optional `json_block` is recommended since v19.0. \n\n**Request:**\n```json\n{ \n \"action\": \"block_info\",\n \"json_block\": \"true\",\n \"hash\": \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\"\n}\n``` \n**Response:**\n```json\n{\n \"block_account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"amount\": \"30000000000000000000000000000000000\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"height\": \"58\",\n \"local_timestamp\": \"0\",\n \"successor\": \"8D3AB98B301224253750D448B4BD997132400CEDD0A8432F775724F2D9821C72\",\n \"confirmed\": \"true\",\n \"contents\": {\n \"type\": \"state\",\n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"previous\": \"CE898C131AAEE25E05362F247760F8A3ACF34A9796A5AE0D9204E86B0637965E\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"link\": \"5D1AA8A45F8736519D707FCB375976A7F9AF795091021D7E9C7548D6F45DD8D5\",\n \"link_as_account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"signature\": \"82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501\",\n \"work\": \"8a142e07a10996d5\"\n },\n \"subtype\": \"send\"\n}\n```\n\nNote: The `Balance` in contents is a uint128. However, it will be a hex-encoded (like `0000000C9F2C9CD04674EDEA40000000` for [1 nano](../protocol-design/distribution-and-units.md#unit-dividers)) when the block is a legacy *Send Block*. If the block is a *State-Block*, the same `Balance` will be a numeric-string (like `1000000000000000000000000000000`).\n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"contents\" will contain a JSON subtree instead of a JSON string.\n\n\n**Optional `include_linked_account`**\n\n_version 28.0+_\n(bool): When set to `true`, the response will include a new field `linked_account`, which returns the linked account associated with the block (or \"0\" if no linked account exists/was found e.g. due to pruning).\n\n\n---\n\n### blocks \nRetrieves a json representations of **blocks**. Using the optional `json_block` is recommended since v19.0. \n\n**Request:**\n```json\n{\n \"action\": \"blocks\",\n \"json_block\": \"true\",\n \"hashes\": [\"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\"]\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": {\n \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\": {\n \"type\": \"state\",\n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"previous\": \"CE898C131AAEE25E05362F247760F8A3ACF34A9796A5AE0D9204E86B0637965E\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"link\": \"5D1AA8A45F8736519D707FCB375976A7F9AF795091021D7E9C7548D6F45DD8D5\",\n \"link_as_account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"signature\": \"82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501\",\n \"work\": \"8a142e07a10996d5\"\n }\n }\n}\n```\n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"contents\" will contain a JSON subtree instead of a JSON string.\n\n---\n\n### blocks_info \nRetrieves a json representations of `blocks` in `contents` along with:\n\n* _since version 18.0_: `block_account`, transaction `amount`, block `balance`, block `height` in account chain, block local modification `timestamp`\n* _since version 19.0_: Whether block was `confirmed`, `subtype` (_for state blocks_) of `send`, `receive`, `change` or `epoch`\n* _since version 23.0_: `successor` returned\n\nUsing the optional `json_block` is recommended since v19.0. \n\n**Request:**\n```json\n{\n \"action\": \"blocks_info\",\n \"json_block\": \"true\",\n \"hashes\": [\"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\"]\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": {\n \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\": {\n \"block_account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"amount\": \"30000000000000000000000000000000000\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"height\": \"58\",\n \"local_timestamp\": \"0\",\n \"successor\": \"8D3AB98B301224253750D448B4BD997132400CEDD0A8432F775724F2D9821C72\",\n \"confirmed\": \"true\",\n \"contents\": {\n \"type\": \"state\",\n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"previous\": \"CE898C131AAEE25E05362F247760F8A3ACF34A9796A5AE0D9204E86B0637965E\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"link\": \"5D1AA8A45F8736519D707FCB375976A7F9AF795091021D7E9C7548D6F45DD8D5\",\n \"link_as_account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"signature\": \"82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501\",\n \"work\": \"8a142e07a10996d5\"\n },\n \"subtype\": \"send\"\n }\n }\n}\n```\n**Optional `include_linked_account`**\n\n_version 28.0+_\n(bool): When set to `true`, the response will include a new field `linked_account`, which returns the linked account associated with the block (or \"0\" if no linked account exists/was found e.g. due to pruning).\n \n**Optional \"pending\", \"source\"**\n\n_pending, source: version 9.0+_ \nBooleans, false by default. Additionally checks if block is pending, returns source account for receive & open blocks (0 for send & change blocks).\n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json\n{\n \"action\": \"blocks_info\",\n \"hashes\": [\"E2FB233EF4554077A7BF1AA85851D5BF0B36965D2B0FB504B2BC778AB89917D3\"],\n \"pending\": \"true\",\n \"source\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : {\n \"E2FB233EF4554077A7BF1AA85851D5BF0B36965D2B0FB504B2BC778AB89917D3\": {\n \"block_account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"amount\": \"30000000000000000000000000000000000\",\n \"contents\": {\n ...\n },\n \"pending\": \"0\",\n \"source_account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"balance\": \"40200000001000000000000000000000000\"\n }\n }\n}\n```\n**Optional \"receive_hash\"**\n\n_version 24.0+_ \nBoolean, default false. If \"true\", displays the hash of the send block's corresponding receive (if any). Returns 0 for non-send blocks, and for receivable blocks that do not yet have a corresponding receive.\n\n**Request:**\n```json\n{\n \"action\": \"blocks_info\",\n \"hashes\": [\"67D9F9F03566D22926159193BD5BDE549FBE8308807C666BCCD3CEA098FBF49D\"], \n \"receive_hash\": \"true\" \n}\n```\n\n**Response**\n```json\n{\n \"blocks\": {\n \"67D9F9F03566D22926159193BD5BDE549FBE8308807C666BCCD3CEA098FBF49D\": {\n \"block_account\": \"nano_1pnano6m6o1ix3eshr6fj9rryd4ckziyii1mf3ychqno9t3soz638dc9fj9a\",\n \"amount\": \"1240000000000000000000000000\",\n \"balance\": \"11017588042701000000000000000000\",\n \"height\": \"271199\",\n \"local_timestamp\": \"1674588370\",\n \"successor\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"confirmed\": \"true\",\n \"contents\": {\n ...\n },\n \"subtype\": \"send\",\n \"receive_hash\": \"4DCA5A5E2C732A6899292B9091B7A90CE87E8063954498DF30F469416E6DD6C0\"\n }\n }\n}\n```\n\n**Optional \"json_block\"** \n_version 19.0+_ \nDefault \"false\". If \"true\", \"contents\" will contain a JSON subtree instead of a JSON string.\n\n**Optional \"include_not_found\"** \n_version 19.0+_ \nDefault \"false\". If \"true\", an additional \"blocks_not_found\" is provided in the response, containing a list of the block hashes that were not found in the local database. Previously to this version an error would be produced if any block was not found.\n\n**Request:**\n```json\n{\n \"action\": \"blocks_info\",\n \"include_not_found\": \"true\",\n \"hashes\": [\"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\", \"0000000000000000000000000000000000000000000000000000000000000001\"]\n}\n```\n\n**Response:**\n```json\n{\n \"blocks\" : {\n \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\": {\n \"block_account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"amount\": \"30000000000000000000000000000000000\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"height\": \"58\",\n \"local_timestamp\": \"0\",\n \"confirmed\": \"false\",\n \"contents\": {\n ...\n }\n }\n },\n \"blocks_not_found\": [\n \"0000000000000000000000000000000000000000000000000000000000000001\"\n ]\n}\n```\n\n---\n\n### bootstrap \nInitialize bootstrap to specific **IP address** and **port**. Not compatible with launch flag [--disable_legacy_bootstrap](/commands/command-line-interface/#-disable_legacy_bootstrap) \n\n**Request:**\n```json\n{\n \"action\": \"bootstrap\",\n \"address\": \"::ffff:138.201.94.249\",\n \"port\": \"7075\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n```\n\n**Optional \"bypass_frontier_confirmation\"** \n_version 20.0-21.3_ \nDefault \"false\". If \"true\", frontier confirmation will not be performed for this bootstrap. Normally not to be changed.\n\n**Optional \"id\"** \n_version 21.0+_ \nString, empty by default. Set specific ID for new bootstrap attempt for better tracking.\n\n---\n\n### bootstrap_any \nInitialize multi-connection bootstrap to random peers. Not compatible with launch flag [--disable_legacy_bootstrap](/commands/command-line-interface/#-disable_legacy_bootstrap) \n\n**Request:**\n```json\n{\n \"action\": \"bootstrap_any\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n```\n**Optional \"force\"** \n_version 20.0+_ \nBoolean, false by default. Manually force closing of all current bootstraps \n\n**Optional \"id\"** \n_version 21.0+_ \nString, empty by default. Set specific ID for new bootstrap attempt for better tracking.\n\n**Optional \"account\"**\n_version 22.0+_\nString, empty by default. Public address for targeting a specific account on bootstrap attempt\n\n---\n\n### bootstrap_lazy \n_enable_control required, version 17.0+_ \nInitialize lazy bootstrap with given block **hash**. Not compatible with launch flag [--disable_lazy_bootstrap](/commands/command-line-interface/#-disable_lazy_bootstrap). As of _version 22.0_, response includes whether new election was `started` and whether a new lazy `key_inserted` was successful.\n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"bootstrap_lazy\",\n \"hash\": \"FF0144381CFF0B2C079A115E7ADA7E96F43FD219446E7524C48D1CC9900C4F17\"\n}\n``` \n**Response:**\n```json\n{\n \"started\": \"1\",\n \"key_inserted\": \"0\"\n}\n```\n**Optional \"force\"**\n\nBoolean, false by default. Manually force closing of all current bootstraps \n\n**Optional \"id\"** \n_version 21.0+_ \nString, empty by default. Set specific ID for new bootstrap attempt for better tracking.\n\n---\n\n### bootstrap_priorities \n_enable_control required, version 28.0+_ \nDumps info about priority and blocking sets to aid in debugging any potential problems\n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"bootstrap_priorities\"\n}\n``` \n\n---\n\n### bootstrap_reset \n_enable_control required, version 28.0+_ \nResets ascending bootstrap state - both priority and blocking sets are cleared.\n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"bootstrap_reset\"\n}\n``` \n\n---\n\n### bootstrap_status \n_version 17.0+_\n\n--8<-- \"warning-debug-only-command.md\"\n\nReturning status of current bootstrap attempt\n\n**Request:**\n```json\n{\n \"action\": \"bootstrap_status\"\n}\n``` \n**Response:**\n_versions 21.0+_\n```json\n{\n \"bootstrap_threads\": \"2\",\n \"running_attempts_count\": \"2\",\n \"total_attempts_count\": \"6\",\n \"connections\": {\n \"clients\": \"31\",\n \"connections\": \"45\",\n \"idle\": \"0\",\n \"target_connections\": \"64\",\n \"pulls\": \"1158514\"\n },\n \"attempts\": [\n {\n \"id\": \"EE778222D6407F94A666B8A9E03D242D\",\n \"mode\": \"legacy\",\n \"started\": \"true\",\n \"pulling\": \"1158544\",\n \"total_blocks\": \"4311\",\n \"requeued_pulls\": \"7\",\n \"frontier_pulls\": \"0\",\n \"frontiers_received\": \"true\",\n \"frontiers_confirmed\": \"false\",\n \"frontiers_confirmation_pending\": \"false\",\n \"frontiers_age\": \"4294967295\",\n \"last_account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"duration\": \"133\"\n },\n {\n \"id\": \"291D2CC32F44E004896C4215A6CDEDAFEF317F6AC802C244E8F4B4F2456175CB\",\n \"mode\": \"lazy\",\n \"started\": \"true\",\n \"pulling\": \"1\",\n \"total_blocks\": \"1878\",\n \"requeued_pulls\": \"4\",\n \"lazy_blocks\": \"1878\",\n \"lazy_state_backlog\": \"1\",\n \"lazy_balances\": \"4\",\n \"lazy_destinations\": \"0\",\n \"lazy_undefined_links\": \"0\",\n \"lazy_pulls\": \"13\",\n \"lazy_keys\": \"2\",\n \"lazy_key_1\": \"E6D0B5BD5EBDB3CEC7DBC32EDC3C2DBD5ABA17C54E34485A358BF8948039ED6A\",\n \"duration\": \"17\"\n }\n ]\n}\n```\n\n??? abstract \"Response V17.0-V20.0\"\n ```json\n {\n \"clients\": \"0\",\n \"pulls\": \"0\",\n \"pulling\": \"0\",\n \"connections\": \"31\",\n \"idle\": \"31\",\n \"target_connections\": \"16\",\n \"total_blocks\": \"13558\",\n \"runs_count\": \"0\",\n \"requeued_pulls\": \"31\",\n \"frontiers_received\": \"true\",\n \"frontiers_confirmed\": \"false\",\n \"mode\": \"legacy\",\n \"lazy_blocks\": \"0\",\n \"lazy_state_backlog\": \"0\",\n \"lazy_balances\": \"0\",\n \"lazy_destinations\": \"0\",\n \"lazy_undefined_links\": \"0\",\n \"lazy_pulls\": \"32\",\n \"lazy_keys\": \"32\",\n \"lazy_key_1\": \"36897874BDA3028DC8544C106BE1394891F23DDDF84DE100FED450F6FBC8122C\",\n \"duration\": \"29\"\n }\n ```\n\n---\n\n### chain \nReturns a consecutive list of block hashes in the account chain starting at **block** back to **count** (direction from frontier back to open block, from newer blocks to older). Will list all blocks back to the open block of this chain when count is set to \"-1\". The requested block hash is included in the answer. \n\n**Request:**\n```json\n{\n \"action\": \"chain\",\n \"block\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": [\n \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n ]\n}\n```\n**Optional \"offset\"**\n\n_version 18.0+_ \nNumber, 0 by default. Return the account chain block hashes **offset** by the specified number of blocks \n\n**Optional \"reverse\"**\n\n_version 18.0+_ \nBoolean, false by default. Returns a list of block hashes in the account chain starting at **block** up to **count** (direction from open block up to frontier, from older blocks to newer). Equal to [successors](#successors) \n\n---\n\n### confirmation_active \n_version 16.0+_ \nReturns list of active elections qualified roots (excluding stopped & aborted elections); since V21, also includes the number of unconfirmed and confirmed active elections. Find info about specific qualified root with [confirmation_info](#confirmation_info) \n\n!!! note\n The roots provided are two parts and differ between the first account block and subsequent blocks:\n\n * First account block (open): account public key + `0000000000000000000000000000000000000000000000000000000000000000`\n * Other blocks: previous hash + previous hash\n\n\n**Request:**\n```json\n{\n \"action\": \"confirmation_active\"\n}\n``` \n**Response:**\n```json\n{\n \"confirmations\": [\n \"8031B600827C5CC05FDC911C28BBAC12A0E096CCB30FA8324F56C123676281B28031B600827C5CC05FDC911C28BBAC12A0E096CCB30FA8324F56C123676281B2\"\n ],\n \"unconfirmed\": \"133\", // since V21.0\n \"confirmed\": \"5\" // since V21.0\n}\n``` \n \n**Optional \"announcements\"**\n\nNumber, 0 by default. Returns only active elections with equal or higher announcements count. Useful to find long running elections \n\n---\n\n### confirmation_history \n_version 12.0+_\n\n--8<-- \"warning-debug-only-command.md\"\n \nduration, time, confirmation_stats: version 17.0+_ \nReturns hash, tally weight, election duration (in milliseconds), election confirmation timestamp for recent elections winners; since V20.0, the confirmation request count; since V21.0, the number of blocks and voters. Also returns stats: count of elections in history (limited to 2048) & average duration time.\n\nWith version 19.0+ `confirmation_history_size` can be managed in the configuration file to adjust the number of elections to be kept in history and returned by this call. Due to timings inside the node, the default 2048 limit will return all confirmations up to traffic levels of approximately 56 confirmations/sec. To properly track levels above this, increase this value or use the confirmation subscription through the [websocket](/integration-guides/websockets) instead.\n\n**Request:**\n```json\n{\n \"action\": \"confirmation_history\"\n}\n``` \n**Response:**\n```json\n{\n \"confirmation_stats\": {\n \"count\": \"2\",\n \"average\": \"5000\"\n },\n \"confirmations\": [\n {\n \"hash\": \"EA70B32C55C193345D625F766EEA2FCA52D3F2CCE0B3A30838CC543026BB0FEA\",\n \"duration\": \"4000\",\n \"time\": \"1544819986\",\n \"tally\": \"80394786589602980996311817874549318248\",\n \"final\": \"80394786589602980996311817874549318248\", // since V22.0\n \"blocks\": \"1\", // since V21.0\n \"voters\": \"37\", // since V21.0\n \"request_count\": \"2\" // since V20.0\n },\n {\n \"hash\": \"F2F8DA6D2CA0A4D78EB043A7A29E12BDE5B4CE7DE1B99A93A5210428EE5B8667\",\n \"duration\": \"6000\",\n \"time\": \"1544819988\",\n \"tally\": \"68921714529890443063672782079965877749\",\n \"final\": \"68921714529890443063672782079965877749\", // since V22.0\n \"blocks\": \"1\", // since V21.0\n \"voters\": \"64\", // since V21.0\n \"request_count\": \"7\" // since V20.0\n }\n ]\n}\n``` \n**Optional \"hash\"**\n\nValid block hash, filters return for only the provided hash. If there is no confirmation available for that hash anymore, the following return can be expected: \n```json\n{\n \"confirmation_stats\": {\n \"count\": \"0\"\n },\n \"confirmations\": \"\"\n}\n``` \n\nIf the block is unknown on the node, the following error will be returned: \n```\"error\": \"Invalid block hash\"``` \n \n---\n\n### confirmation_info \n_version 16.0+_ \nReturns info about an unconfirmed active election by **root**. Including announcements count, last winner (initially local ledger block), total tally of voted representatives, concurrent blocks with tally & block contents for each. Using the optional `json_block` is recommended since v19.0. Updated in v28.0 to include a list of representatives_final (representatives that have voted with final votes). \n\n!!! note\n The roots provided are two parts and differ between the first account block and subsequent blocks:\n\n * First account block (open): `0000000000000000000000000000000000000000000000000000000000000000` + account public key\n * Other blocks: previous hash + previous hash\n\n\n**Request:**\n```json\n{\n \"action\": \"confirmation_info\",\n \"json_block\": \"true\",\n \"root\": \"EE125B1B1D85D3C24636B3590E1642D9F21B166C0C6CD99C9C6087A1224A0C44EE125B1B1D85D3C24636B3590E1642D9F21B166C0C6CD99C9C6087A1224A0C44\"\n}\n``` \n**Response:**\n```json\n{\n \"announcements\": \"2\",\n \"voters\": \"29\",\n \"last_winner\": \"B94C505029F04BC057A0486ADA8BD07981B4A8736AE6581F2E98C6D18498146F\",\n \"total_tally\": \"51145880360832646375807054724596663794\",\n \"final_tally\": \"51145880360832646375807054724596663794\",\n \"blocks\": {\n \"B94C505029F04BC057A0486ADA8BD07981B4A8736AE6581F2E98C6D18498146F\": {\n \"tally\": \"51145880360832646375807054724596663794\",\n \"contents\": {\n \"type\": \"state\",\n \"account\": \"nano_3fihmbtuod33s4nrbqfczhk9zy9ddqimwjshzg4c3857es8c9631i5rg6h9p\",\n \"previous\": \"EE125B1B1D85D3C24636B3590E1642D9F21B166C0C6CD99C9C6087A1224A0C44\",\n \"representative\": \"nano_3o7uzba8b9e1wqu5ziwpruteyrs3scyqr761x7ke6w1xctohxfh5du75qgaj\",\n \"balance\": \"218195000000000000000000000000\",\n \"link\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"link_as_account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"signature\": \"B1BD285235C612C5A141FA61793D7C6C762D3F104A85102DED5FBD6B4514971C4D044ACD3EC8C06A9495D8E83B6941B54F8DABA825ADF799412ED9E2C86D7A0C\",\n \"work\": \"05bb28cd8acbe71d\"\n }\n }\n }\n} \n``` \n\n**Optional \"contents\"**\n\nBoolean, true by default. Disable contents for each block \n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"contents\" will contain a JSON subtree instead of a JSON string.\n\n**Optional \"representatives\"**\n\nBoolean, false by default. Returns list of votes representatives & its weights for each block \n\n**Request:**\n```json\n{\n \"action\": \"confirmation_info\",\n \"json_block\": \"true\",\n \"root\": \"EE125B1B1D85D3C24636B3590E1642D9F21B166C0C6CD99C9C6087A1224A0C44EE125B1B1D85D3C24636B3590E1642D9F21B166C0C6CD99C9C6087A1224A0C44\",\n \"representatives\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"announcements\": \"5\",\n \"last_winner\": \"B94C505029F04BC057A0486ADA8BD07981B4A8736AE6581F2E98C6D18498146F\",\n \"total_tally\": \"51145880360792646375807054724596663794\",\n \"blocks\": {\n \"B94C505029F04BC057A0486ADA8BD07981B4A8736AE6581F2E98C6D18498146F\": {\n \"tally\": \"51145880360792646375807054724596663794\",\n \"contents\": {\n \"type\": \"state\",\n \"account\": \"nano_3fihmbtuod33s4nrbqfczhk9zy9ddqimwjshzg4c3857es8c9631i5rg6h9p\",\n \"previous\": \"EE125B1B1D85D3C24636B3590E1642D9F21B166C0C6CD99C9C6087A1224A0C44\",\n \"representative\": \"nano_3o7uzba8b9e1wqu5ziwpruteyrs3scyqr761x7ke6w1xctohxfh5du75qgaj\",\n \"balance\": \"218195000000000000000000000000\",\n \"link\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"link_as_account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"signature\": \"B1BD285235C612C5A141FA61793D7C6C762D3F104A85102DED5FBD6B4514971C4D044ACD3EC8C06A9495D8E83B6941B54F8DABA825ADF799412ED9E2C86D7A0C\",\n \"work\": \"05bb28cd8acbe71d\"\n },\n \"representatives\": {\n \"nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh\": \"12617828599372664613607727105312358589\",\n \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\": \"5953738757270291536911559258663615240\",\n ...\n \"nano_3i4n5n6c6xssapbdtkdoutm88c5zjmatc5tc77xyzdkpef8akid9errcpjnx\": \"0\"\n }\n }\n }\n}\n``` \n\n---\n\n### confirmation_quorum \n_version 16.0+_ \nReturns information about node elections settings & observed network state:\n\n- `quorum_delta`: Online weight times `online_weight_quorum_percent`\n- `online_weight_quorum_percent`: Percent of online vote weight required for confirmation\n- `online_weight_minimum`: When calculating online weight, the node is forced to assume at least this much voting weight is online, thus setting a floor for voting weight to confirm transactions at `online_weight_minimum` * `quorum_delta`\n- `online_stake_total`: Total online weight from gossip vote traffic\n- `peers_stake_total`: Total online weight from direct node connections\n- `trended_stake_total`: Median of online weight samples taken every 5 minutes over previous 2 week period\n- Removed in _version 22.0_: `peers_stake_required`\n\n**Request:**\n```json\n{ \n \"action\": \"confirmation_quorum\" \n}\n``` \n**Response:**\n```json\n{\n \"quorum_delta\": \"41469707173777717318245825935516662250\",\n \"online_weight_quorum_percent\": \"50\",\n \"online_weight_minimum\": \"60000000000000000000000000000000000000\",\n \"online_stake_total\": \"82939414347555434636491651871033324568\",\n \"peers_stake_total\": \"69026910610720098597176027400951402360\",\n \"trended_stake_total\": \"81939414347555434636491651871033324568\"\n} \n``` \n\n**Optional \"peer_details\"**\n\n_version 17.0+_ \n\nBoolean, false by default. If true, add account/ip/rep weight for each peer considered in the summation of *peers_stake_total*.\n\n**Response field \"peers_stake_required\"**\n\n_version 19.0+_\n\nThe effective stake needed from directly connected peers for quorum. Per v19, this field is computed as `max(quorum_delta, online_weight_minimum)`. If `peers_stake_total` is lower than this value, the node will not mark blocks as confirmed.\n\n---\n\n### database_txn_tracker\n_enable_control required, v19.0+_ \n\n--8<-- \"warning-debug-only-command.md\"\n \nReturns a list of open database transactions which are equal or greater than the `min_read_time` or `min_write_time` for reads and read-writes respectively. \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"database_txn_tracker\",\n \"min_read_time\" : \"1000\",\n \"min_write_time\" : \"0\"\n}\n```\n**Response on Windows/Debug:** \n```json\n{\n \"txn_tracking\": [\n {\n \"thread\": \"Blck processing\", // Which thread held the transaction\n \"time_held_open\": \"2\", // Seconds the transaction has currently been held open for\n \"write\": \"true\", // If true it is a write lock, otherwise false.\n \"stacktrace\": [\n {\n \"name\": \"nano::mdb_store::tx_begin_write\",\n \"address\": \"00007FF7142C5F86\",\n \"source_file\": \"c:\\\\users\\\\wesley\\\\documents\\\\raiblocks\\\\nano\\\\node\\\\lmdb.cpp\",\n \"source_line\": \"825\"\n },\n {\n \"name\": \"nano::block_processor::process_batch\",\n \"address\": \"00007FF714121EEA\",\n \"source_file\": \"c:\\\\users\\\\wesley\\\\documents\\\\raiblocks\\\\nano\\\\node\\\\blockprocessor.cpp\",\n \"source_line\": \"243\"\n },\n {\n \"name\": \"nano::block_processor::process_blocks\",\n \"address\": \"00007FF71411F8A6\",\n \"source_file\": \"c:\\\\users\\\\wesley\\\\documents\\\\raiblocks\\\\nano\\\\node\\\\blockprocessor.cpp\",\n \"source_line\": \"103\"\n },\n ...\n ]\n }\n ... // other threads\n ]\n}\n```\n\n---\n\n### delegators \n_version 8.0+_ \nReturns a list of pairs of delegator accounts and balances given a representative **account**\n\n**Request:**\n```json\n{\n \"action\": \"delegators\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\"\n}\n``` \n**Response:**\n```json\n{\n \"delegators\": {\n \"nano_13bqhi1cdqq8yb9szneoc38qk899d58i5rcrgdk5mkdm86hekpoez3zxw5sd\": \"500000000000000000000000000000000000\",\n \"nano_17k6ug685154an8gri9whhe5kb5z1mf5w6y39gokc1657sh95fegm8ht1zpn\": \"961647970820730000000000000000000000\"\n }\n}\n``` \n\n**Optional parameters:** \n_since V23.0_ \n\n* `threshold`: minimum required balance for a delegating account to be included in the response\n* `count`: number of delegators to return\n* `start`: account in the list you would like to start after, to allow for paging responses\n\n---\n\n### delegators_count \n_version 8.0+_ \nGet number of delegators for a specific representative **account** \n\n**Request:**\n```json\n{\n \"action\": \"delegators_count\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\"\n}\n``` \n**Response:**\n```json\n{\n \"count\": \"2\"\n}\n``` \n\n---\n\n### deterministic_key \nDerive deterministic keypair from **seed** based on **index** \n\n**Request:**\n```json\n{\n \"action\": \"deterministic_key\",\n \"seed\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"index\": \"0\"\n}\n``` \n**Response:**\n```json\n{\n \"private\": \"9F0E444C69F77A49BD0BE89DB92C38FE713E0963165CCA12FAF5712D7657120F\",\n \"public\": \"C008B814A7D269A1FA3C6528B19201A24D797912DB9996FF02A1FF356E45552B\",\n \"account\": \"nano_3i1aq1cchnmbn9x5rsbap8b15akfh7wj7pwskuzi7ahz8oq6cobd99d4r3b7\"\n}\n``` \n\n---\n\n### election_statistics \n_version 27.0+_ \n\nReturns the number of each election type, the maximum and average election age from Active Election Container (AEC).\n\nValues in `max_election_age` and `average_election_age` are in milliseconds.\n\n**Request:**\n```json\n{\n \"action\": \"election_statistics\"\n}\n``` \n**Response sample:**\n```json\n{\n \"normal\": \"152\",\n \"priority\": \"1\",\n \"hinted\": \"0\",\n \"optimistic\": \"19\",\n \"total\": \"172\",\n \"aec_utilization_percentage\": \"3.42\",\n \"max_election_age\": \"5493\",\n \"average_election_age\": \"421\"\n}\n```\n\n---\n\n### epoch_upgrade \n_enable_control required, version 20.0+_ \n\n--8<-- \"warning-debug-only-command.md\"\n\nUpgrade network to new **epoch** with epoch signer private **key**. This spawns a background task to iterate over all accounts and add the epoch block to any accounts that do not have it. It will return `{ \"started\" = \"1\" }` if the background task was spawned successfully or `{ \"started\" = \"0\" }` if the operation could not be started. Reasons for not being able to start the operations include the node being stopped and a previous being in progress. `epoch` can be set to either 1 (representing the [network upgrade to state blocks](../releases/network-upgrades.md#state-blocks)) or 2 (representing the [network upgrade for increase work difficulty](../releases/network-upgrades.md#increased-work-difficulty)).\n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"epoch_upgrade\",\n \"epoch\": \"1\",\n \"key\": \"0000000000000000000000000000000000000000000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"started\": \"1\"\n}\n``` \n**Optional \"count\"** \nNumber. Determines limit of number of accounts to upgrade.\n\n**Optional \"threads\"** \n_version 21.0+_ \nNumber. Determines limit of work threads to use for concurrent upgrade processes (useful with multiple work peers or high work peer latency).\n\n---\n\n### frontier_count \nReports the number of accounts in the ledger \n\n**Request:**\n```json\n{\n \"action\": \"frontier_count\"\n}\n``` \n**Response:**\n```json\n{\n \"count\": \"920471\"\n}\n```\n\n---\n\n### frontiers \nReturns a list of pairs of account and block hash representing the head block starting at **account** up to **count** \n\n**Request:**\n```json\n{\n \"action\": \"frontiers\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"frontiers\" : {\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n }\n}\n```\n\n---\n\n### keepalive \n_enable_control required_ \nTells the node to send a keepalive packet to **address**:**port** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"keepalive\",\n \"address\": \"::ffff:192.169.0.1\",\n \"port\": \"1024\"\n}\n``` \n**Response:**\n```json\n{\n \"started\": \"1\"\n}\n```\n\n---\n\n### key_create \nGenerates an **adhoc random keypair** \n\n**Request:**\n```json\n{\n \"action\": \"key_create\"\n}\n``` \n**Response:**\n```json\n{\n \"private\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\",\n \"public\": \"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}\n``` \n\n---\n\n### key_expand \nDerive public key and account number from **private key** \n\n**Request:**\n```json\n{\n \"action\": \"key_expand\",\n \"key\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\"\n}\n``` \n**Response:**\n```json\n{\n \"private\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\",\n \"public\": \"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}\n``` \n\n---\n\n### ledger\n_enable_control required, version 9.0+_ \nReturns frontier, open block, change representative block, balance, last modified timestamp from local database & block count starting at **account** up to **count** \n\n--8<-- \"warning-enable-control.md\"\n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n**Request:**\n```json\n{\n \"action\": \"ledger\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"accounts\": {\n \"nano_11119gbh8hb4hj1duf7fdtfyf5s75okzxdgupgpgm1bj78ex3kgy7frt3s9n\": {\n \"frontier\": \"E71AF3E9DD86BBD8B4620EFA63E065B34D358CFC091ACB4E103B965F95783321\",\n \"open_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"representative_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"balance\": \"0\",\n \"modified_timestamp\": \"1511476234\",\n \"block_count\": \"2\"\n }\n }\n}\n``` \n**Optional \"representative\", \"weight\", \"receivable\"** \nBooleans, false by default. Additionally returns representative, voting weight, receivable balance for each account \n\n**Request:**\n```json\n{\n \"action\": \"ledger\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"count\": \"1\",\n \"representative\": \"true\",\n \"weight\": \"true\",\n \"receivable\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"accounts\": {\n \"nano_11119gbh8hb4hj1duf7fdtfyf5s75okzxdgupgpgm1bj78ex3kgy7frt3s9n\": {\n \"frontier\": \"E71AF3E9DD86BBD8B4620EFA63E065B34D358CFC091ACB4E103B965F95783321\",\n \"open_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"representative_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"balance\": \"0\",\n \"modified_timestamp\": \"1511476234\",\n \"block_count\": \"2\",\n \"representative\": \"nano_1anrzcuwe64rwxzcco8dkhpyxpi8kd7zsjc1oeimpc3ppca4mrjtwnqposrs\",\n \"weight\": \"0\",\n \"pending\": \"0\",\n \"receivable\": \"0\"\n } \n } \n}\n``` \n**Optional \"modified_since\"** \n_version 11.0+_ \nUNIX timestamp (number), 0 by default. Return only accounts modified in local database after specific timestamp \n\n**Optional \"sorting\"** \nBoolean, false by default. Additional sorting accounts in descending order \nNOTE: The \"count\" option is ignored if \"sorting\" is specified\n\n**Optional \"threshold\"** \n_version 19.0+_ \nNumber (128 bit, decimal), default 0. Return only accounts with balance above **threshold**. If **receivable** is also given, the number compared with the threshold is the sum of account balance and receivable balance.\n\n---\n\n### node_id\n_enable_control required, version 17.0+_ \n\n--8<-- \"warning-debug-only-command.md\"\n \nReturns private key, public key and node ID number with checksum (similar to account representation) from the existing node ID created on startup. \"as_account\" field is **deprecated** \n_version 20.0 will generate the node_id with `node_` prefix, earlier versions will generate with `nano_` prefix_ \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"node_id\"\n}\n``` \n**Response:**\n```json\n{\n \"private\": \"2AD75C9DC20EA497E41722290C4DC966ECC4D6C75CAA4E447961F918FD73D8C7\",\n \"public\": \"78B11E1777B8E7DF9090004376C3EDE008E84680A497C0805F68CA5928626E1C\",\n \"as_account\": \"nano_1y7j5rdqhg99uyab1145gu3yur1ax35a3b6qr417yt8cd6n86uiw3d4whty3\",\n \"node_id\": \"node_1y7j5rdqhg99uyab1145gu3yur1ax35a3b6qr417yt8cd6n86uiw3d4whty3\"\n}\n``` \n\n---\n\n### peers \nReturns a list of pairs of online peer IPv6:port and its node protocol network version \n\n**Request:**\n```json\n{\n \"action\": \"peers\"\n}\n``` \n \n**Response version 8.0+:**\n```json\n{\n \"peers\": {\n \"[::ffff:172.17.0.1]:32841\": \"16\"\n }\n}\n``` \n\n**Response before version 8.0:**\n```json\n{\n \"peers\": [\n \"[::ffff:172.17.0.1]:32841\"\n ]\n}\n``` \n**Optional \"peer_details\"**\n\n_version 18.0+_ \nBoolean, false by default. Returns a list of peers IPv6:port with its node protocol network version and node ID. The node ID is random and is not a Nano address. As of Version V21+ `type` returns `tcp`, as `udp` was **deprecated** and is not longer used for peering with that node.\n\n_version 20.0 will generate the node_id with `node_` prefix, earlier versions will generate with `nano_` prefix_ \n\n**Request:**\n```json\n\n{\n \"action\": \"peers\",\n \"peer_details\": \"true\"\n}\n```\n\n**Response:**\n```json\n{\n \"peers\": {\n \"[::ffff:172.17.0.1]:7075\": {\n \"protocol_version\": \"18\",\n \"node_id\": \"node_1y7j5rdqhg99uyab1145gu3yur1ax35a3b6qr417yt8cd6n86uiw3d4whty3\",\n \"type\": \"tcp\"\n }\n }\n}\n```\n\n---\n\n### populate_backlog\n_enable_control required_ \nScans all accounts, checks for unconfirmed blocks in account chains, and then queues those blocks for confirmation via the election scheduler. Useful for local test networks, since default backlog population is normally done over longer intervals (e.g. 5 minutes).\n\n--8<-- \"warning-enable-control.md\"\n\n**Request**\n```json\n{ \n \"action\": \"populate_backlog\" \n}\n```\n**Response**\n```json\n{\n \"success\": \"\" \n}\n```\n\n---\n\n### process \nPublish **block** to the network. Using the optional `json_block` is recommended since v19.0. In v20.0-v21.3, blocks are watched for confirmation by default (see optional `watch_work`). If `enable_control` is not set to `true` on the node, then the optional `watch_work` must be set to `false`. In V22.0+ the work watcher has been removed.\n\nNote: after v25.0, it is possible that the block processing queue can internally drop a block if the queue gets full. This stat can be checked for `blockprocessor` type, and `drop` details.\n\n--8<-- \"warning-process-sub-type-recommended.md\"\n\n**Request:**\n```json\n{\n \"action\": \"process\",\n \"json_block\": \"true\",\n \"subtype\": \"send\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"previous\": \"6CDDA48608C7843A0AC1122BDD46D9E20E21190986B19EAC23E7F33F2E6A6766\",\n \"representative\": \"nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh\",\n \"balance\": \"40200000001000000000000000000000000\",\n \"link\": \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\",\n \"link_as_account\": \"nano_33t5by1653nt196hfwm5q3wq7oxtaix97r7bhox5zn8eratrzoqsny49ftsd\",\n \"signature\": \"A5DB164F6B81648F914E49CAB533900C389FAAD64FBB24F6902F9261312B29F730D07E9BCCD21D918301419B4E05B181637CF8419ED4DCBF8EF2539EB2467F07\",\n \"work\": \"000bc55b014e807d\"\n }\n}\n``` \n**Response:**\n```json\n{\n \"hash\": \"E2FB233EF4554077A7BF1AA85851D5BF0B36965D2B0FB504B2BC778AB89917D3\"\n}\n```\n**Optional \"force\"** \n_version 13.1+_ \nBoolean, false by default. Manually forcing fork resolution if processed block is not accepted as fork\n\n**Optional \"subtype\"** \n_version 18.0+_ \nString, empty by default. Additional check for state blocks subtype, i.e. prevent accidental sending to incorrect accounts instead of receiving receivable blocks. Options:\n\n* `send` - account balance is reduced\n* `receive` - account balance is increased\n* `open` - first block on account with account balance initially set higher than 0\n* `change` - account balance is unchanged, representative field value changed to valid public address\n* `epoch` - block signed with epoch signer private key (does not allow balance or representative changes)\n\n**Optional \"json_block\"** \n_version 19.0+_ \nBoolean, default \"false\". If \"true\", \"block\" must contain a JSON subtree instead of a JSON string.\n\n**Optional \"watch_work\"** \n_added in version 20.0+_ \n_removed in version 22.0_ \nBoolean, default \"true\". If \"true\", **block** will be placed on watch for confirmation, with equivalent functionality to in-wallet transactions using [send](#send), [receive](#receive) and [account_representative_set](#account_representative_set), including republishing and rework if confirmation is delayed (default is 5 seconds, set by `work_watcher_period` config entry) and if [active_difficulty](#active_difficulty) is higher than the block's PoW difficulty.\n\n**Optional \"async\"** \n_version 22.0+_ \nBoolean, default \"false\". If \"true\", requests will add the blocks to the block processor queue and `{\"started\":\"1\"}` will be immediately returned, instead of waiting for block process completion to return. To know if the block was properly processed, monitor the [WebSocket topic `new_unconfirmed_block`](../integration-guides/websockets.md#new-unconfirmed-blocks) and a notification for that successful block will be sent.\n\n---\n\n### receivable\n\n_since V23.0, use [pending](#pending) for V22.1 and below_ \nReturns a list of block hashes which have not yet been received by this account.\n\n**Request:**\n```json\n{\n \"action\": \"receivable\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": [ \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\" ]\n}\n``` \n**Optional \"count\"** \nNumber. Determines limit of number of blocks to return.\n\n**Optional \"threshold\"** \n_version 8.0+_ \nNumber (128 bit, decimal). Returns a list of receivable block hashes with amount more or equal to **threshold** \n\n**Request:**\n```json\n{\n \"action\": \"receivable\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\",\n \"count\": \"1\",\n \"threshold\": \"1000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : {\n \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\": \"6000000000000000000000000000000\"\n }\n}\n``` \n**Optional \"source\"** \n_version 9.0+_ \nBoolean, false by default. Returns a list of receivable block hashes with amount and source accounts \n\n**Request:**\n```json\n{\n \"action\": \"receivable\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\",\n \"count\": \"1\",\n \"source\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : {\n \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\": {\n \"amount\": \"6000000000000000000000000000000\",\n \"source\": \"nano_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr\"\n }\n }\n}\n``` \n**Optional \"include_active\"**\n\n_version 15.0+_ \nBoolean, false by default. Include active blocks without finished confirmations \n\n**Request:**\n```json\n{\n \"action\": \"receivable\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\",\n \"count\": \"1\",\n \"include_active\": \"true\"\n}\n``` \n\n**Optional \"min_version\"**\n\n_version 15.0+_ \nBoolean, false by default. Returns the minimum version (epoch) of a block which can pocket this receivable block.\n\n**Optional \"sorting\"**\n\nBoolean, false by default. Additionally sorts the blocks by their amounts in descending order. \n\n_version 22.0+_ \nIf used with \"count\" returns the absolute sorted values.\n\n_version 19.0+_ \nIf used with \"count\" only sorts relative to the first receivable entries found up to count so not necessarily the ones with the largest receivable balance. \n\n**Optional \"include_only_confirmed\"**\n\n_version 19.0+_ \nBoolean, true by default (_version 22.0+_), previously false by default. Only returns confirmed blocks but with the caveat that their confirmation height might not be up-to-date yet. If false, unconfirmed blocks will also be returned.\n\n---\n\n### receivable_exists\n\n_since V23.0, use [pending_exists](#pending_exists) for V22.1 and below_ \nCheck whether block is receivable by **hash** \n\n**Request:**\n```json\n{\n \"action\": \"receivable_exists\",\n \"hash\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"exists\" : \"1\"\n}\n```\n\n**Optional \"include_active\"**\n\n_version 15.0+_ \nBoolean, false by default. Include active blocks without finished confirmations \n\n**Request:**\n```json\n{\n \"action\": \"receivable_exists\",\n \"hash\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"include_active\": \"true\"\n}\n``` \n\n**Optional \"include_only_confirmed\"**\n\n_version 19.0+_ \nBoolean, true by default (_version 22.0+_), previously false by default. Only returns confirmed blocks but with the caveat that their confirmation height might not be up-to-date yet. If false, unconfirmed blocks will also be returned.\n\n---\n\n### representatives \nReturns a list of pairs of representative and its voting weight \n\n**Request:**\n```json\n{\n \"action\": \"representatives\"\n}\n``` \n**Response:**\n```json\n{\n \"representatives\": {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": \"3822372327060170000000000000000000000\",\n \"nano_1111111111111111111111111111111111111111111111111awsq94gtecn\": \"30999999999999999999999999000000\",\n \"nano_114nk4rwjctu6n6tr6g6ps61g1w3hdpjxfas4xj1tq6i8jyomc5d858xr1xi\": \"0\"\n }\n}\n```\n**Optional \"count\"**\n\n_version 9.0+_ \nNumber. Returns a list of pairs of representative and its voting weight up to **count**\n \n**Optional \"sorting\"**\n\n_version 9.0+_ \nBoolean, false by default. Additional sorting representatives in descending order \nNOTE: The \"count\" option is ignored if \"sorting\" is specified \n\n---\n\n### representatives_online \n_version 18.0+_ \nReturns a list of online representative accounts that have voted recently \n\n**Request:**\n```json\n{\n \"action\": \"representatives_online\"\n}\n``` \n**Response:**\n```json\n{\n \"representatives\": [\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\",\n \"nano_1111111111111111111111111111111111111111111111111awsq94gtecn\",\n \"nano_114nk4rwjctu6n6tr6g6ps61g1w3hdpjxfas4xj1tq6i8jyomc5d858xr1xi\"\n ]\n}\n```\n_versions 11.2–17.1_ \nReturns a list of pairs of online representative accounts that have voted recently and empty strings \n**Response:**\n```json\n{\n \"representatives\" : {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": \"\",\n \"nano_1111111111111111111111111111111111111111111111111awsq94gtecn\": \"\",\n \"nano_114nk4rwjctu6n6tr6g6ps61g1w3hdpjxfas4xj1tq6i8jyomc5d858xr1xi\": \"\"\n }\n}\n```\n**Optional \"weight\"**\n\n_version 17.0+_ \nBoolean, false by default. Returns voting weight for each representative. \n**Response:**\n```json\n{\n \"representatives\": {\n \"nano_114nk4rwjctu6n6tr6g6ps61g1w3hdpjxfas4xj1tq6i8jyomc5d858xr1xi\": {\n \"weight\": \"150462654614686936429917024683496890\"\n }\n }\n}\n```\n\n**Optional \"accounts\"** \nArray of accounts. Returned list is filtered for only these accounts.\n\n**Request:**\n```json\n{\n \"action\": \"representatives_online\",\n \"accounts\": [\"nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p\", \"nano_1111111111111111111111111111111111111111111111111117353trpda\"]\n}\n``` \n**Response:**\n```json\n{\n \"representatives\": [\n \"nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p\"\n ]\n}\n```\n\n---\n\n### republish \nRebroadcast blocks starting at **hash** to the network \n\n**Request:**\n```json\n{\n \"action\": \"republish\",\n \"hash\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\",\n \"blocks\": [\n \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"A170D51B94E00371ACE76E35AC81DC9405D5D04D4CEBC399AEACE07AE05DD293\"\n ]\n}\n``` \n\n**Optional \"sources\"**\n\n_version 8.0+_ \nBoolean, false by default. Additionally rebroadcast source chain blocks for receive/open up to **sources** depth \n\n**Request:**\n```json\n{\n \"action\": \"republish\",\n \"hash\": \"90D0C16AC92DD35814E84BFBCC739A039615D0A42A76EF44ADAEF1D99E9F8A35\",\n \"count\": \"1\",\n \"sources\": \"2\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": [\n \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"A170D51B94E00371ACE76E35AC81DC9405D5D04D4CEBC399AEACE07AE05DD293\",\n \"90D0C16AC92DD35814E84BFBCC739A039615D0A42A76EF44ADAEF1D99E9F8A35\"\n ]\n}\n``` \n\n**Optional \"destinations\"**\n\n_version 8.0+_ \nBoolean, false by default. Additionally rebroadcast destination chain blocks from receive up to **destinations** depth \n\n**Request:**\n```json\n{\n \"action\": \"republish\",\n \"hash\": \"A170D51B94E00371ACE76E35AC81DC9405D5D04D4CEBC399AEACE07AE05DD293\",\n \"count\": \"1\",\n \"destinations\": \"2\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": [\n \"A170D51B94E00371ACE76E35AC81DC9405D5D04D4CEBC399AEACE07AE05DD293\",\n \"90D0C16AC92DD35814E84BFBCC739A039615D0A42A76EF44ADAEF1D99E9F8A35\",\n \"18563C814A54535B7C12BF76A0E23291BA3769536634AB90AD0305776A533E8E\"\n ]\n}\n``` \n\n---\n\n### sign\n_version 18.0+_ \nSigning provided **block** with private **key** or key of **account** from **wallet**. Using the optional `json_block` is recommended since v19.0. \n\n**Request with private key:**\n```json\n{\n \"action\": \"sign\",\n \"json_block\": \"true\",\n \"key\": \"1D3759BB2CA187A66875D3B8497624159A576FD315E07F702B99B92BC59FC14A\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"previous\": \"6CDDA48608C7843A0AC1122BDD46D9E20E21190986B19EAC23E7F33F2E6A6766\",\n \"representative\": \"nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh\",\n \"balance\": \"40200000001000000000000000000000000\",\n \"link\": \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\",\n \"link_as_account\": \"nano_33t5by1653nt196hfwm5q3wq7oxtaix97r7bhox5zn8eratrzoqsny49ftsd\",\n \"signature\": \"A5DB164F6B81648F914E49CAB533900C389FAAD64FBB24F6902F9261312B29F730D07E9BCCD21D918301419B4E05B181637CF8419ED4DCBF8EF2539EB2467F07\",\n \"work\": \"000bc55b014e807d\"\n }\n}\n```\n\n**Request with account from wallet:**\n```json\n{\n \"action\": \"sign\",\n \"json_block\": \"true\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_18ky5chy5ws89oi46ki4zjy6x5ezpmj98zg6icwke9bmuy99nosieyqf8c1h\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"previous\": \"6CDDA48608C7843A0AC1122BDD46D9E20E21190986B19EAC23E7F33F2E6A6766\",\n \"representative\": \"nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh\",\n \"balance\": \"40200000001000000000000000000000000\",\n \"link\": \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\",\n \"link_as_account\": \"nano_33t5by1653nt196hfwm5q3wq7oxtaix97r7bhox5zn8eratrzoqsny49ftsd\",\n \"signature\": \"A5DB164F6B81648F914E49CAB533900C389FAAD64FBB24F6902F9261312B29F730D07E9BCCD21D918301419B4E05B181637CF8419ED4DCBF8EF2539EB2467F07\",\n \"work\": \"000bc55b014e807d\"\n }\n}\n```\n**Response:**\n```json\n{\n \"signature\": \"2A71F3877033F5966735F260E906BFCB7FA82CDD543BCD1224F180F85A96FC26CB3F0E4180E662332A0DFE4EE6A0F798A71C401011E635604E532383EC08C70D\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"previous\": \"6CDDA48608C7843A0AC1122BDD46D9E20E21190986B19EAC23E7F33F2E6A6766\",\n \"representative\": \"nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh\",\n \"balance\": \"40200000001000000000000000000000000\",\n \"link\": \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\",\n \"link_as_account\": \"nano_33t5by1653nt196hfwm5q3wq7oxtaix97r7bhox5zn8eratrzoqsny49ftsd\",\n \"signature\": \"2A71F3877033F5966735F260E906BFCB7FA82CDD543BCD1224F180F85A96FC26CB3F0E4180E662332A0DFE4EE6A0F798A71C401011E635604E532383EC08C70D\",\n \"work\": \"000bc55b014e807d\"\n }\n}\n```\n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", the input \"block\" must contain a JSON subtree instead of a JSON string. In addition, the response block will be a JSON subtree.\n\n\n**Optional sign block hash** \n_Requires configuration changes. Set \"rpc.enable_sign_hash\" to \"true\"_ \n\n**Request:**\n```json\n{\n \"action\": \"sign\",\n \"hash\": \"E2FB233EF4554077A7BF1AA85851D5BF0B36965D2B0FB504B2BC778AB89917D3\"\n}\n``` \n**Response:**\n```json\n{\n \"signature\": \"2A71F3877033F5966735F260E906BFCB7FA82CDD543BCD1224F180F85A96FC26CB3F0E4180E662332A0DFE4EE6A0F798A71C401011E635604E532383EC08C70D\"\n}\n``` \n\n---\n\n### stats\n_version 12.2+_ \nFor configuration and other details, please see [Statistics from RPC](/running-a-node/troubleshooting/#statistics-from-rpc)\n\n**Request counters:**\n```json\n{\n \"action\": \"stats\",\n \"type\": \"counters\"\n}\n```\n\n**Counters response:**\n```json\n{\n \"type\": \"counters\",\n \"created\": \"2018.03.29 01:46:36\",\n \"entries\": [\n {\n \"time\": \"01:46:36\",\n \"type\": \"traffic_tcp\",\n \"detail\": \"all\",\n \"dir\": \"in\",\n \"value\": \"3122792\"\n },\n {\n \"time\": \"01:46:36\",\n \"type\": \"traffic_tcp\",\n \"detail\": \"all\",\n \"dir\": \"out\",\n \"value\": \"203184\"\n }\n ...\n ]\n}\n```\n\n_version 18.0+ also returns \"stat_duration_seconds\": the number of seconds since startup or since the last \"stats_clear\" call_\n\n**Request samples:**\n```json\n{\n \"action\": \"stats\",\n \"type\": \"samples\"\n}\n```\n\n**Samples response:**\n```json\n{\n \"type\": \"samples\",\n \"created\": \"2018.03.29 01:47:08\",\n \"entries\": [\n {\n \"time\": \"01:47:04\",\n \"type\": \"traffic_tcp\",\n \"detail\": \"all\",\n \"dir\": \"in\",\n \"value\": \"59480\"\n },\n {\n \"time\": \"01:47:05\",\n \"type\": \"traffic_tcp\",\n \"detail\": \"all\",\n \"dir\": \"in\",\n \"value\": \"44496\"\n }\n ...\n ]\n}\n```\n_version 18.0+_ \nNOTE: This call is for debug purposes only and is unstable as returned objects may be frequently changed.\n\n**Request objects:**\n```json\n{\n \"action\": \"stats\",\n \"type\": \"objects\"\n}\n```\n\n**Objects response:**\n```json\n{\n \"node\": {\n \"ledger\": {\n \"bootstrap_weights\": {\n \"count\": \"125\",\n \"size\": \"7000\"\n }\n },\n \"peers\": {\n \"peers\": {\n \"count\": \"38\",\n \"size\": \"7296\"\n },\n \"attempts\": {\n \"count\": \"95\",\n \"size\": \"3800\"\n },\n },\n ...\n }\n}\n```\n\n_version 22.0+_ \nNOTE: This call is for debug purposes only and is unstable as returned objects may be frequently changed and will be different depending on the ledger backend.\n\n**Request database:**\n```json\n{\n \"action\": \"stats\",\n \"type\": \"database\"\n}\n```\n\n**Database response:** \n**LMDB:**\n```json\n{\n \"branch_pages\": \"0\",\n \"depth\": \"1\",\n \"entries\": \"11\",\n \"leaf_pages\": \"1\",\n \"overflow_pages\": \"0\",\n \"page_size\": \"4096\"\n}\n```\n**RocksDB:** \n```json\n{\n \"cur-size-all-mem-tables\": \"74063072\",\n \"size-all-mem-tables\": \"487744504\",\n \"estimate-table-readers-mem\": \"113431016\",\n \"estimate-live-data-size\": \"17756425993\",\n \"compaction-pending\": \"0\",\n \"estimate-num-keys\": \"81835964\",\n \"estimate-pending-compaction-bytes\": \"0\",\n \"total-sst-files-size\": \"20350606013\",\n \"block-cache-capacity\": \"318767104\",\n \"block-cache-usage\": \"150310696\"\n}\n```\n---\n\n### stats_clear\n_version 18.0+_\n\nClears all collected statistics. The \"stat_duration_seconds\" value in the \"stats\" action is also reset.\n\n\n**Request:**\n```json\n{\n \"action\": \"stats_clear\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n```\n\n---\n\n### stop \n_enable_control required_ \nMethod to safely shutdown node \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"stop\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n``` \n\n---\n\n### successors \nReturns a list of block hashes in the account chain starting at **block** up to **count** (direction from open block up to frontier, from older blocks to newer). Will list all blocks up to frontier (latest block) of this chain when count is set to \"-1\". The requested block hash is included in the answer. \n\n**Request:**\n```json\n{\n \"action\": \"successors\",\n \"block\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\" : [\n \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\"\n ]\n}\n```\n**Optional \"offset\"**\n\n_version 18.0+_ \nNumber, 0 by default. Return the account chain block hashes **offset** by the specified number of blocks \n\n**Optional \"reverse\"**\n\n_version 18.0+_ \nBoolean, false by default. Returns a consecutive list of block hashes in the account chain starting at **block** back to **count** (direction from frontier back to open block, from newer blocks to older). Equal to [chain](#chain) \n\n---\n\n### telemetry\n_version 21.0+_ \nReturn metrics from other nodes on the network. By default, returns a summarized view of the whole network. See below for details on obtaining local telemetry data. \n[Networking - node telemetry](/protocol-design/networking#node-telemetry) contains more detailed information on the protocol implementation of telemetry. \n**Request:**\n```json\n{\n \"action\": \"telemetry\"\n}\n```\n**Response:**\n```json\n{\n \"block_count\": \"214104509\",\n \"cemented_count\": \"214104509\",\n \"unchecked_count\": \"5161\",\n \"account_count\": \"37186909\",\n \"bandwidth_cap\": \"10485760\",\n \"peer_count\": \"176\",\n \"protocol_version\": \"21\",\n \"uptime\": \"3188200\",\n \"genesis_block\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"major_version\": \"28\",\n \"minor_version\": \"2\",\n \"patch_version\": \"0\",\n \"pre_release_version\": \"0\",\n \"maker\": \"0\",\n \"timestamp\": \"1765074100220\",\n \"active_difficulty\": \"fffffff800000000\",\n \"database_backend\": \"lmdb\",\n \"confirmation_latency_ms_p50\": \"254\",\n \"confirmation_latency_ms_p90\": \"510\",\n \"confirmation_latency_ms_p99\": \"1205\",\n \"bootstrap_status\": \"idle\",\n \"node_id\": \"node_3odec59q6i9qarh5txyrxmu3aqhfzm54mxoxgtumwpzyq6obxqktdzcxkfag\",\n \"signature\": \"067523993D0B4C07525DF4C5AA814FBCC40875F868C2A04A85AC288F75E152763196B7DCB11240921F6D8BA92E3E9F094D8F2F9D8B0970114CDAD48838372100\"\n}\n```\n\nThis contains a summarized view of the network with 10% of lower/upper bound results removed to reduce the effect of outliers. Returned values are calculated as follows:\n\n| Field Name | Response details |\n|------------|------------------------------------|\n| **block_count** | average count of blocks in ledger (including unconfirmed) |\n| **cemented_count** | average count of blocks cemented in ledger (only confirmed) |\n| **unchecked_count** | average count of unchecked blocks. This should only be considered an estimate as nodes running RocksDB may not return exact counts. |\n| **account_count** | average count of accounts in ledger |\n| **bandwidth_cap** | `0` = unlimited; the mode is chosen if there is more than 1 common result otherwise the results are averaged (excluding `0`) |\n| **peer_count** | average count of peers nodes are connected to |\n| **\\*_version** | mode (most common) of (protocol, major, minor, patch, pre_release) versions |\n| **uptime** | average number of seconds since the UTC epoch at the point where the response is sent from the peer |\n| **genesis_block** | mode (most common) of genesis block hashes |\n| **maker** | mode (most common), meant for third party node software implementing the protocol so that it can be distinguished, `0` = Nano Foundation, `1` = Nano Foundation pruned node |\n| **timestamp** | number of milliseconds since the UTC epoch at the point where the response is sent from the peer |\n| **active_difficulty** | _V22.0+_ returns minimum network difficulty due to deprecated active difficulty measurements

_up to V21.3_ returns average of the current network difficulty, see [active_difficulty](/commands/rpc-protocol/#active_difficulty) \"network_current\" |\n| **database_backend** | the database backend used by the node: `lmdb` or `rocksdb` |\n| **confirmation_latency_ms_p50** | 50th percentile (median) confirmation latency in milliseconds, based on recently confirmed elections |\n| **confirmation_latency_ms_p90** | 90th percentile confirmation latency in milliseconds, based on recently confirmed elections |\n| **confirmation_latency_ms_p99** | 99th percentile confirmation latency in milliseconds, based on recently confirmed elections |\n| **bootstrap_status** | current bootstrap status of the node: `idle` or `active` |\n| **node_id** | _V21.0+_ returns the node identifier used to sign the telemetry message. This allows receivers to verify which peer the telemetry originated from. |\n| **signature** | _V21.0+_ returns the signature of the telemetry payload, created using the node's private key. It enables verification that the data was produced by the reported `node_id` and has not been altered. |\n\nThis only returns values which have been cached by the ongoing polling of peer metric data. Each response is cached for 60 seconds on the main network and 15 seconds on beta; a few additional seconds are added on for response delays.\n\n**Optional \"raw\"** \nWhen setting raw to true metrics from all nodes are displayed. It additionally contains **address** and **port** from each peer.\n\n**Request:**\n```json\n{\n \"action\": \"telemetry\",\n \"raw\" : \"true\"\n}\n```\n\n**Response:**\n```json\n{\n \"metrics\": [\n {\n \"block_count\": \"5777903\",\n ...\n \"node_id\": \"node_1cmi8difuruopgzpnb4ybrnnj5rproxwuwe5mad7ucbsekakiwn37qqg1zo5\",\n \"signature\": \"5F8DEE5F895D53E122FDEB4B1B4118A41F9DDB818C6B299B09DF59131AF9F201BB7057769423F6B0C868B57509177B54D5D2C731405FE607527F5E2B6B2E290F\",\n \"address\": \"::ffff:152.89.106.89\",\n \"port\": \"54000\"\n },\n {\n \"block_count\": \"5777902\",\n ... \n \"node_id\": \"node_3ipxdjrha3rfg9h3spiz5jkprw8kdj7bph9fir51kf6pmryzznsyhakqznk3\",\n \"signature\": \"D691B855D9EC70EA6320DE609EB379EB706845433E034AD22721E8F91BF3A26156F40CCB2E98653F1E63D4CE5F10F530A835DE1B154D1213464E3B9BB9BE4908\",\n \"address\": \"::ffff:95.216.205.215\",\n \"port\": \"54006\"\n }\n ...\n ]\n}\n```\n\n**Optional \"address\" & \"port\"** \nGet metrics from a specific peer. It accepts both ipv4 and ipv6 addresses\n```json\n{\n \"action\": \"telemetry\",\n \"address\": \"246.125.123.456\",\n \"port\": \"7075\"\n}\n```\n\n!!!tip \"Requesting telemetry data from the local node\"\n Metrics for the local node can be requested using the peering port and any loopback address **127.0.0.1**, **::1** or **[::1]**\n\n---\n\n### validate_account_number \nCheck whether **account** is a valid account number using checksum \n\n**Request:**\n```json\n{\n \"action\": \"validate_account_number\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111117353trpda\"\n}\n``` \n**Response:**\n```json\n{\n \"valid\" : \"1\"\n}\n```\n\n---\n\n### version \nReturns version information for RPC, Store, Protocol (network), Node (Major & Minor version). \nSince _version 20.0_ also returns the Network label and identifier (hash of the genesis open block), and Build Info. Since _version 21.0_ also returns Database backend information. \n_RPC Version always returns \"1\" as of 01/11/2018_ \n\n**Request:**\n```json\n{\n \"action\": \"version\"\n}\n``` \n**Response:**\n```json\n{\n \"rpc_version\": \"1\",\n \"store_version\": \"14\",\n \"protocol_version\": \"17\",\n \"node_vendor\": \"Nano 20.0\",\n \"store_vendor\": \"LMDB 0.9.23\", // since V21.0\n \"network\": \"live\", // since v20.0\n \"network_identifier\": \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\", // since v20.0\n \"build_info\": \"Build Info \\\" version \\\" \\\"\\\" \\\"BOOST \\\" BUILT \\\"\\\"\" // since v20.0\n}\n```\n\n---\n\n### unchecked \n_version 8.0+_ \nReturns a list of pairs of unchecked block hashes and their json representation up to **count**. Using the optional `json_block` is recommended since v20.0.\n\n**Request:**\n```json\n{\n \"action\": \"unchecked\",\n \"json_block\": \"true\",\n \"count\": \"1\",\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": {\n \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\": {\n \"type\": \"state\",\n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"previous\": \"CE898C131AAEE25E05362F247760F8A3ACF34A9796A5AE0D9204E86B0637965E\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"5606157000000000000000000000000000000\",\n \"link\": \"5D1AA8A45F8736519D707FCB375976A7F9AF795091021D7E9C7548D6F45DD8D5\",\n \"link_as_account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"signature\": \"82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501\",\n \"work\": \"8a142e07a10996d5\"\n }\n }\n}\n```\n\n---\n\n### unchecked_clear \n_enable_control required, version 8.0+_ \nClear unchecked synchronizing blocks \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"unchecked_clear\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n``` \n\n---\n\n### unchecked_get \n_version 8.0+_ \nRetrieves a json representation of unchecked synchronizing block by **hash**. Using the optional `json_block` is recommended since v19.0. \n\n**Request:**\n```json\n{\n \"action\": \"unchecked_get\",\n \"json_block\": \"true\",\n \"hash\": \"19BF0C268C2D9AED1A8C02E40961B67EA56B1681DE274CD0C50F3DD972F0655C\"\n}\n``` \n**Response:**\n```json\n{\n \"modified_timestamp\": \"1565856525\",\n \"contents\": {\n \"type\": \"state\",\n \"account\": \"nano_1hmqzugsmsn4jxtzo5yrm4rsysftkh9343363hctgrjch1984d8ey9zoyqex\",\n \"previous\": \"009C587914611E83EE7F75BD9C000C430C720D0364D032E84F37678D7D012911\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"189012679592109992600249228\",\n \"link\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"link_as_account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"signature\": \"845C8660750895843C013CE33E31B80EF0A7A69E52DDAF74A5F1BDFAA9A52E4D9EA2C3BE1AB0BD5790FCC1AD9B7A3D2F4B44EECE4279A8184D414A30A1B4620F\",\n \"work\": \"0dfb32653e189699\"\n }\n}\n```\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"contents\" will contain a JSON subtree instead of a JSON string.\n\n---\n\n### unchecked_keys \n_version 8.0+_ \nRetrieves unchecked database keys, blocks hashes & a json representations of unchecked receivable blocks starting from **key** up to **count**. Using the optional `json_block` is recommended since v19.0. \n\n--8<-- \"known-issue-unchecked-keys-rpc-rocksdb.md\"\n\n**Request:**\n```json\n{\n \"action\": \"unchecked_keys\",\n \"json_block\": \"true\",\n \"key\": \"19BF0C268C2D9AED1A8C02E40961B67EA56B1681DE274CD0C50F3DD972F0655C\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"unchecked\": [\n {\n \"key\": \"19BF0C268C2D9AED1A8C02E40961B67EA56B1681DE274CD0C50F3DD972F0655C\",\n \"hash\": \"A1A8558CBABD3F7C1D70F8CB882355F2EF688E7F30F5FDBD0204CAE157885056\",\n \"modified_timestamp\": \"1565856744\",\n \"contents\": {\n \"type\": \"state\",\n \"account\": \"nano_1hmqzugsmsn4jxtzo5yrm4rsysftkh9343363hctgrjch1984d8ey9zoyqex\",\n \"previous\": \"19BF0C268C2D9AED1A8C02E40961B67EA56B1681DE274CD0C50F3DD972F0655C\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"189012679592109992600249226\",\n \"link\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"link_as_account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"signature\": \"FF5D49925AD3C8705E6EEDD993E8C4120E6107D7F1CB53B287773448DEA0B1D32918E67804248FC83609F0D93401D833DFA33127F21B6CD02F75D6E31A00450A\",\n \"work\": \"8193ddf00947e694\"\n }\n }\n ]\n}\n``` \n\n**Optional \"json_block\"**\n\n_version 19.0+_ \nDefault \"false\". If \"true\", \"contents\" will contain a JSON subtree instead of a JSON string.\n\n---\n\n### unopened \n\n_enable_control required, version 19.0+_ \n\nReturns the total receivable balance for unopened accounts in the local database, starting at **account** (optional) up to **count** (optional), sorted by account number. _**Notes:**_ By default excludes the burn account. \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"unopened\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"count\": \"1\"\n}\n``` \n\n**Response:**\n```json \n{\n \"accounts\": {\n \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\": \"207034077034226183413773082289554618448\"\n }\n}\n``` \n\n**Optional \"threshold\"** \nNumber (128 bit, decimal), default 0. Return only accounts with total receivable balance above **threshold**.\n\n---\n\n### uptime \n_version 18.0+_ \nReturn node uptime in seconds \n\n**Request:**\n```json\n{\n \"action\": \"uptime\"\n}\n``` \n**Response:**\n```json\n{\n \"seconds\": \"6000\"\n}\n``` \n\n---\n\n### work_cancel\n_enable_control required_ \nStop generating **work** for block \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_cancel\",\n \"hash\": \"718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n``` \n\n---\n\n### work_generate\n_enable_control required_ \nGenerates **work** for block. **hash** is the frontier of the account or in the case of an open block, the public key representation of the account which can be found with [account_key](#account_key). \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_generate\",\n \"hash\": \"718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2\"\n}\n``` \n**Response:**\n```json\n{\n \"work\": \"2b3d689bbcb21dca\",\n \"difficulty\": \"fffffff93c41ec94\", // of the resulting work\n \"multiplier\": \"1.182623871097636\", // since v19.0, calculated from default base difficulty\n \"hash\": \"718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2\" // since v20.0\n}\n``` \n\n**Optional \"use_peers\"**\n\n_version 14.0+_\nBoolean, false by default. If the optional `use_peers` parameter is set to `true`, then the node will query its work peers (if it has any).\nWithout this parameter, the node will only generate work locally.\n\n**Optional \"difficulty\"**\n\n!!! info \"Difficulty no longer useful\"\n With _version 22.0+_ the difficulty is no longer used for prioritization so targeting higher difficulty thresholds on work generation is not useful. However, this can still be used for targeting a lower difficulty for receive blocks. This option may be removed in a future release.\n\n_version 19.0+_ \nDifficulty value (16 hexadecimal digits string, 64 bit). Uses **difficulty** value to generate work. Defaults to the network base difficulty.\n\n**Optional \"multiplier\"**\n\n!!! info \"Multiplier no longer useful\"\n With _version 22.0+_ the difficulty is no longer used for prioritization so targeting higher multipliers on work generation is not useful. This option will be removed in a future release.\n\n_version 20.0+_ \nMultiplier from base difficulty (positive number). Uses equivalent difficulty as **multiplier** from base difficulty to generate work. \n***Note:*** overrides the `difficulty` parameter. \n\n**Optional \"account\"**\n\n_version 20.0+_ \nA valid Nano account. If provided and `use_peers` is set to `true`, this information will be relayed to work peers.\n\n**Optional \"version\"**\n\n_version 21.0+_ \nWork version string. Currently \"work_1\" is the default and only valid option.\n\n**Optional \"block\"**\n\n_version 21.0+_ \nA valid Nano block (string or JSON). Using the optional `json_block` is recommended. If provided and `difficulty` or `multiplier` are both not given, RPC processor tries to calculate the appropriate difficulty threshold based on ledger data. \n***Note:*** block should be the one where the resulting work value will be used, not the previous block.\n\n**Optional \"json_block\"**\n\n_version 21.0+_ \nDefault \"false\". If \"true\", `block` in the request should contain a JSON subtree instead of a JSON string.\n\n---\n\n### work_peer_add \n_enable_control required, version 8.0+_ \nAdd specific **IP address** and **port** as work peer for node until restart \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_peer_add\",\n \"address\": \"::ffff:172.17.0.1\",\n \"port\": \"7076\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n``` \n\n---\n\n### work_peers \n_enable_control required, version 8.0+_ \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_peers\"\n}\n``` \n**Response:**\n```json\n{\n \"work_peers\": [\n \"::ffff:172.17.0.1:7076\"\n ]\n}\n``` \n\n---\n\n### work_peers_clear \n_enable_control required, version 8.0+_ \nClear work peers node list until restart \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_peers_clear\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n``` \n\n---\n\n### work_validate \nCheck whether **work** is valid for block. Provides two values: **valid_all** is `true` if the work is valid at the current network difficulty (work can be used for any block). **valid_receive** is `true` if the work is valid for use in a receive block.\n\n**Read the details below when using this RPC in V21**.\n\n!!! warning \"Semantics change in V21.0\"\n In V21.0, when the optional **difficulty** is *not* given, **valid** is no longer included in the response.\n\n Use the new response fields **\"valid_all\"** and **\"valid_receive\"** taking into account the subtype of the block using this work value:\n\n - **valid_all** validates at the current network difficulty. As soon as the node processes the first [epoch_2 block](/releases/network-upgrades#increased-work-difficulty), this difficulty is increased.\n - **valid_receive** is completely accurate **only once the [epoch_2 upgrade](/releases/network-upgrades#increased-work-difficulty) is finished.** Until the upgrade is finished, it is only accurate if the account where this work will be used is already upgraded. The upgrade status of an account can be obtained from [account_info](#account_info). The account is upgraded if \"account_version\" is `\"2\"`.\n\n**Request:**\n```json\n{\n \"action\": \"work_validate\",\n \"work\": \"2bf29ef00786a6bc\",\n \"hash\": \"718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2\"\n}\n``` \n**Response since v21.0:**\n```json\n{\n \"valid_all\": \"1\",\n \"valid_receive\": \"1\",\n \"difficulty\": \"fffffff93c41ec94\",\n \"multiplier\": \"1.182623871097636\" // calculated from the default base difficulty\n}\n```\n\n??? abstract \"Response up to v20.0\"\n ```json\n {\n \"valid\": \"1\",\n \"difficulty\": \"fffffff93c41ec94\", // since v19.0\n \"multiplier\": \"9.4609\" // since v19.0\n }\n ```\n\n**Optional \"difficulty\"**\n\n_version 19.0+_ \nDifficulty value (16 hexadecimal digits string, 64 bit). Uses **difficulty** value to validate work. Defaults to the network base difficulty. Response includes extra field **valid** signifying validity at the given difficulty. \n\n**Request with given \"difficulty\"** \n```json\n{\n \"action\": \"work_validate\",\n \"difficulty\": \"ffffffffffffffff\",\n \"work\": \"2bf29ef00786a6bc\",\n \"hash\": \"718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2\"\n}\n```\n**Response with given \"difficulty:**\n```json\n{\n \"valid\": \"0\",\n \"valid_all\": \"1\", // since v21.0\n \"valid_receive\": \"1\", // since v21.0\n \"difficulty\": \"fffffff93c41ec94\",\n \"multiplier\": \"1.182623871097636\"\n}\n```\n\n**Optional \"multiplier\"**\n\n_version 20.0+_ \nMultiplier from base difficulty (positive number). Uses equivalent difficulty as **multiplier** from base difficulty to validate work. \n***Note:*** overrides the `difficulty` parameter. \n\n**Optional \"version\"**\n\n_version 21.0+_\nWork version string. Currently \"work_1\" is the default and only valid option.\n\n---\n\n## Wallet RPCs\n\n!!! warning \"For development and testing only\"\n Below are RPC commands that interact with the built-in, QT-based node wallet. This wallet is only recommended for development and testing. For production integrations, setting up custom [External Management](/integration-guides/key-management/#external-management) processes is required.\n\n---\n\n### account_create \n_enable_control required_ \nCreates a new account, insert next deterministic key in **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"account_create\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\n \n**Response:**\n```json\n{\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n```\n**Optional \"index\"**\n\n_version 18.0+_ \nunset by default. Indicates which index to create account for starting with 0 \n\n**Request:**\n```json\n{\n \"action\": \"account_create\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"index\": \"1\"\n}\n```\n\n**Optional \"work\"**\n\n_version 9.0+_ \nBoolean, true by default. Setting false disables work generation after creating account \n\n**Request:**\n```json\n{\n \"action\": \"account_create\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"work\": \"false\"\n}\n```\n\n---\n\n### account_list \nLists all the accounts inside **wallet** \n\n**Request:**\n```json\n{\n \"action\": \"account_list\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"accounts\": [\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n ]\n}\n```\n\n---\n\n### account_move \n_enable_control required_ \nMoves **accounts** from **source** to **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"account_move\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"source\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"accounts\": [\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n ]\n}\n``` \n**Response:**\n```json\n{\n \"moved\" : \"1\"\n}\n```\n\n---\n\n### account_remove\n_enable_control required_ \nRemove **account** from **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"account_remove\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_39a73oy5ungrhxy5z5oao1xso4zo7dmgpjd4u74xcrx3r1w6rtazuouw6qfi\"\n}\n``` \n**Response:**\n```json\n{\n \"removed\": \"1\"\n}\n```\n\n---\n\n### account_representative_set \n_enable_control required_ \nSets the representative for **account** in **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"account_representative_set\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_39a73oy5ungrhxy5z5oao1xso4zo7dmgpjd4u74xcrx3r1w6rtazuouw6qfi\",\n \"representative\": \"nano_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5\"\n}\n``` \n**Response:**\n```json\n{\n \"block\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\n**Optional \"work\"**\n\n_version 9.0+_ \nWork value (16 hexadecimal digits string, 64 bit). Uses **work** value for block from external source and disables work precaching for this account. Not using this field re-enables work precaching. \n\n---\n\n### accounts_create \n_enable_control required, version 9.0+_ \nCreates new accounts, insert next deterministic keys in **wallet** up to **count** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"accounts_create\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"2\"\n}\n``` \n**Response:**\n```json\n{\n \"accounts\": [\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3s00000000\"\n ]\n}\n```\n**Optional enabling work generation** \n_version 11.2+_ \nBoolean, false by default. Enables work generation after creating accounts \n\n**Request:**\n```json\n{\n \"action\": \"accounts_create\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"2\",\n \"work\": \"true\"\n}\n``` \n***Note:*** Before version 11.2 work generation was enabled by default, if you want to disable work generation for previous versions, use \"work\": \"false\"\n\n---\n\n### block_create (optional wallet)\nSee [block_create](#block_create) Node RPC command above\n\n---\n\n### password_change \n_enable_control required_ \nChanges the password for **wallet** to **password** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"password_change\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"password\": \"test\"\n}\n``` \n**Response:**\n```json\n{\n \"changed\" : \"1\"\n}\n```\n\n---\n\n### password_enter \nEnters the **password** in to **wallet** to unlock it \n\n**Request:**\n```json\n{\n \"action\": \"password_enter\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"password\": \"test\"\n}\n``` \n**Response:**\n```json\n{\n \"valid\": \"1\"\n}\n```\n\n---\n\n### password_valid \nChecks whether the password entered for **wallet** is valid \n\n**Request:**\n```json\n{\n \"action\": \"password_valid\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"valid\" : \"1\"\n}\n```\n\n---\n\n### receive \n_enable_control required_ \nReceive receivable **block** for **account** in **wallet**. If receiving the block opens the account, sets the account representative to a [wallet representative](#wallet_representative). Before v21, the representative is set to the account itself. \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"receive\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"block\": \"53EAA25CE28FA0E6D55EA9704B32604A736966255948594D55CBB05267CECD48\"\n}\n``` \n**Response:**\n```json\n{\n \"block\": \"EE5286AB32F580AB65FD84A69E107C69FBEB571DEC4D99297E19E3FA5529547B\"\n}\n```\n**Optional \"work\"**\n\n_version 9.0+_ \nWork value (16 hexadecimal digits string, 64 bit). Uses **work** value for block from external source and disables work precaching for this account. Not using this field re-enables work precaching. \n\n---\n\n### receive_minimum \n_enable_control required, version 8.0+_ \nReturns receive minimum for node wallet \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"receive_minimum\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1000000000000000000000000\"\n}\n```\n\n---\n\n### receive_minimum_set \n_enable_control required, version 8.0+_ \nSet **amount** as new receive minimum for node wallet until restart \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"receive_minimum_set\",\n \"amount\": \"1000000000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n```\n\n---\n\n### search_pending\n\nDeprecated in V24.0+. Replaced by [search_receivable](#search_receivable)\n\n---\n\n### search_receivable\n\n_since V24.0, use [search_pending](#search_pending) for V23.3 and below_\n\n_enable_control required_ \nTells the node to look for receivable blocks for any account in **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"search_receivable\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"started\": \"1\"\n}\n```\n---\n\n### search_pending_all\n\nDeprecated in V24.0+. Replaced by [search_receivable_all](#search_receivable_all)\n\n---\n\n### search_receivable_all \n\n_since V24.0, use [search_pending_all](#search_pending_all) for V23.3 and below_\n\n_enable_control required, version 8.0+_ \nTells the node to look for receivable blocks for any account in all available wallets \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"search_receivable_all\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\" \n}\n```\n\n---\n\n### send \n_enable_control required_ \nSend **amount** from **source** in **wallet** to **destination** \n\n--8<-- \"warning-enable-control.md\"\n\n!!! success \"Use of `id` option is highly recommended\"\n Integrations using the node wallet must ensure idempotency for transactions and this can be done externally if preferred. Using the `id` field provides this option internally and is highly recommended for all node wallet uses.\n\n**Request:**\n```json\n{\n \"action\": \"send\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"source\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"destination\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"amount\": \"1000000\",\n \"id\": \"your-unique-id\"\n}\n``` \n**Response:**\n```json\n{\n \"block\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\nProof of Work is precomputed for **one** transaction in the background when you are using the node wallet to track accounts. If it has been a while since your last transaction it will send instantly, the next one will need to wait for Proof of Work to be generated.\n\nIf the request times out, then the send may or may not have gone through. If you want to the ability to retry a failed send, all send calls must specify the id parameter as follows\n\n**Highly recommended \"id\"**\n\n_version 10.0+_ \n\nYou can (and should) specify a **unique** id for each spend to provide [idempotency](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning). That means that if you call `send` two times with the same id, the second request won't send any additional Nano, and will return the first block instead. The id can be any string. **This may be a required parameter in the future.**\n\nIf you accidentally reuse an id, the send will not go through (it will be seen as a duplicate request), so make sure your ids are unique! They must be unique per node, and are not segregated per wallet.\n\nUsing the same id for requests with different parameters (wallet, source, destination, and amount) is undefined behavior and may result in an error in the future.\n\n\n**Request:**\n```json\n{\n \"action\": \"send\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"source\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"destination\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"amount\": \"1000000\",\n \"id\": \"7081e2b8fec9146e\"\n}\n``` \n**Response:**\n```json\n{\n \"block\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\n\nSending the request again will yield the same block, and will not affect the ledger.\n\n**Optional \"work\"**\n\n_version 9.0+_ \nWork value (16 hexadecimal digits string, 64 bit). Uses **work** value for block from external source and disables work precaching for this account. Not using this field re-enables work precaching. \n\n**Request:**\n```json\n{\n \"action\": \"send\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"source\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"destination\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"amount\": \"1000000\",\n \"work\": \"2bf29ef00786a6bc\"\n}\n``` \n\n---\n\n### sign (optional wallet)\nSee [sign](#sign) Node RPC command above\n\n---\n\n### wallet_add \n_enable_control required_ \nAdd an adhoc private key **key** to **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_add\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"key\": \"34F0A37AAD20F4A260F0A5B3CB3D7FB50673212263E58A380BC10474BB039CE4\"\n}\n``` \n**Response:**\n```json\n{\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n```\n**Optional disabling work generation**\n\n_version 9.0+_ \nBoolean, false by default. Disables work generation after adding account \n\n**Request:**\n```json\n{\n \"action\": \"wallet_add\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"key\": \"34F0A37AAD20F4A260F0A5B3CB3D7FB50673212263E58A380BC10474BB039CE4\",\n \"work\": \"false\"\n}\n``` \n\n---\n\n### wallet_add_watch \n_enable_control required, version 11.0+_ \nAdd watch-only **accounts** to **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_add_watch\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"accounts\": [\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"nano_111111111111111111111111111111111111111111111111111000000000\"\n ]\n}\n``` \n**Response:**\n```json\n{\n \"success\" : \"\"\n}\n```\n\n---\n\n### wallet_balances \nReturns how many raw is owned and how many have not yet been received by all accounts in **wallet** \n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_balances\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"balances\" : {\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\": {\n \"balance\": \"10000\",\n \"pending\": \"10000\",\n \"receivable\": \"10000\"\n }\n }\n}\n```\n**Optional \"threshold\"**\n\n_version 9.0+_ \nNumber (128 bit, decimal). Returns wallet accounts balances more or equal to **threshold** \n\n---\n\n### wallet_change_seed \n_enable_control required_ \nChanges seed for **wallet** to **seed**. ***Notes:*** Clear all deterministic accounts in wallet! To restore account from new seed use RPC [accounts_create](#accounts_create). \n`last_restored_account` and `restored_count` fields in response returned since _version 19.0+_ \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_change_seed\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"seed\": \"74F2B37AAD20F4A260F0A5B3CB3D7FB51673212263E58A380BC10474BB039CEE\"\n}\n``` \n**Response:**\n```json\n{\n \"success\" : \"\",\n \"last_restored_account\": \"nano_1mhdfre3zczr86mp44jd3xft1g1jg66jwkjtjqixmh6eajfexxti7nxcot9c\",\n \"restored_count\": \"1\"\n}\n```\n\n**Optional \"count\"**\n\n_version 18.0+_ \nNumber, 0 by default. Manually set **count** of accounts to restore from seed \n\n---\n\n### wallet_contains \nCheck whether **wallet** contains **account** \n\n**Request:**\n```json\n{\n \"action\": \"wallet_contains\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n``` \n**Response:**\n```json\n{\n \"exists\": \"1\"\n}\n```\n\n---\n\n### wallet_create \n_enable_control required_ \nCreates a new random wallet id \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_create\"\n}\n``` \n**Response:**\n```json\n{\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\n**Optional \"seed\"**\n\n_version 18.0+_ \nSeed value (64 hexadecimal digits string, 256 bit). Changes seed for a new wallet to **seed**, returning last restored account from given seed & restored count \n\n---\n\n### wallet_destroy \n_enable_control required_ \nDestroys **wallet** and all contained accounts \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_destroy\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"destroyed\": \"1\"\n}\n```\n\n---\n\n### wallet_export \nReturn a json representation of **wallet** \n\n**Request:**\n```json\n{\n \"action\": \"wallet_export\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"json\" : \"{\\\"0000000000000000000000000000000000000000000000000000000000000000\\\": \\\"0000000000000000000000000000000000000000000000000000000000000001\\\"}\"\n}\n```\n\n---\n\n### wallet_frontiers \nReturns a list of pairs of account and block hash representing the head block starting for accounts from **wallet** \n\n**Request:**\n```json\n{\n \"action\": \"wallet_frontiers\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"frontiers\": {\n \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n }\n}\n```\n\n---\n\n### wallet_history \n_version 18.0+_ \nReports send/receive information for accounts in wallet. Change blocks are skipped, open blocks will appear as receive. Response will start with most recent blocks according to local ledger.\n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_history\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"history\":\n [\n {\n \"type\": \"send\",\n \"account\": \"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\",\n \"amount\": \"30000000000000000000000000000000000\",\n \"block_account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"hash\": \"87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9\",\n \"local_timestamp\": \"1527698508\"\n },\n {\n \"type\": \"send\",\n \"account\": \"nano_38ztgpejb7yrm7rr586nenkn597s3a1sqiy3m3uyqjicht7kzuhnihdk6zpz\",\n \"amount\": \"40000000000000000000000000000000000\",\n \"block_account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\",\n \"hash\": \"CE898C131AAEE25E05362F247760F8A3ACF34A9796A5AE0D9204E86B0637965E\",\n \"local_timestamp\": \"1527698492\"\n }\n ]\n}\n```\n**Optional \"modified_since\"**\n\nUNIX timestamp (number), 0 by default. Return only accounts modified in local database after specific timestamp \n\n---\n\n### wallet_info \n_version 15.0+_ \nGiven a **wallet** id, from all of the accounts in the wallet, returns:\n\n* Sum of their **balance** amounts\n* Total number of accounts as **accounts_count**\n* Number of deterministic accounts as **deterministic_count**\n* Number of adhoc (non-deterministic) accounts as **adhoc_count**\n* Index of last account derived from the walet seed as **deterministic_index** (equal to deterministic accounts number if no accounts were removed)\n* Sum of all frontier block heights as **accounts_block_count**\n* Sum of confirmed block heights as **accounts_cemented_block_count**\n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_info\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"balance\": \"10000\",\n \"pending\": \"10000\",\n \"receivable\": \"10000\",\n \"accounts_count\": \"3\",\n \"adhoc_count\": \"1\",\n \"deterministic_count\": \"2\",\n \"deterministic_index\": \"2\",\n \"accounts_block_count\": \"14\",\n \"accounts_cemented_block_count\": \"13\"\n}\n```\n\n---\n\n### wallet_ledger\n_enable_control required, version 11.0+_ \nReturns frontier, open block, change representative block, balance, last modified timestamp from local database & block count for accounts from **wallet** \n\n--8<-- \"warning-includes-unconfirmed.md\"\n\n--8<-- \"warning-enable-control.md\"\n\n--8<-- \"deprecation-info-pending.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_ledger\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"accounts\": {\n \"nano_11119gbh8hb4hj1duf7fdtfyf5s75okzxdgupgpgm1bj78ex3kgy7frt3s9n\": {\n \"frontier\": \"E71AF3E9DD86BBD8B4620EFA63E065B34D358CFC091ACB4E103B965F95783321\",\n \"open_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"representative_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"balance\": \"0\",\n \"modified_timestamp\": \"1511476234\",\n \"block_count\": \"2\"\n }\n }\n}\n``` \n**Optional \"representative\", \"weight\", \"receivable\"**\n\nBooleans, false by default. Additionally returns representative, voting weight, receivable balance for each account \n\n**Request:**\n```json\n{\n \"action\": \"wallet_ledger\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"representative\": \"true\",\n \"weight\": \"true\",\n \"receivable\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"accounts\": {\n \"nano_11119gbh8hb4hj1duf7fdtfyf5s75okzxdgupgpgm1bj78ex3kgy7frt3s9n\": {\n \"frontier\": \"E71AF3E9DD86BBD8B4620EFA63E065B34D358CFC091ACB4E103B965F95783321\",\n \"open_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"representative_block\": \"643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F\",\n \"balance\": \"0\",\n \"modified_timestamp\": \"1511476234\",\n \"block_count\": \"2\",\n \"representative\": \"nano_1anrzcuwe64rwxzcco8dkhpyxpi8kd7zsjc1oeimpc3ppca4mrjtwnqposrs\",\n \"weight\": \"0\",\n \"pending\": \"0\",\n \"receivable\": \"0\"\n }\n }\n}\n``` \n**Optional \"modified_since\"**\n\nUNIX timestamp (number), 0 by default. Return only accounts modified in local database after specific timestamp \n\n---\n\n### wallet_lock \n_enable_control required, version 9.0+_ \nLocks **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_lock\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"locked\": \"1\"\n}\n```\n\n---\n\n### wallet_locked \nChecks whether **wallet** is locked \n\n**Request:**\n```json\n{\n \"action\": \"wallet_locked\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"locked\": \"0\"\n}\n```\n---\n\n### wallet_pending\n\nDeprecated in V24.0+. Replaced by [wallet_receivable](#wallet_receivable)\n\n---\n\n### wallet_receivable\n\n_since V24.0, use [wallet_pending](#wallet_pending) for V23.3 and below_\n\n_enable_control required_ \nReturns a list of block hashes which have not yet been received by accounts in this **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_receivable\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": [\"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D\"],\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": [\"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74\"]\n }\n}\n``` \n**Optional \"threshold\"**\n\nNumber (128 bit, decimal). Returns a list of receivable block hashes with amount more or equal to **threshold** \n\n**Request:**\n```json\n{\n \"action\": \"wallet_receivable\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"1\",\n \"threshold\": \"1000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": {\n \"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D\": \"6000000000000000000000000000000\"\n },\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": {\n \"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74\": \"106370018000000000000000000000000\"\n }\n }\n}\n``` \n**Optional \"source\"**\n\n_version 9.0+_ \nBoolean, false by default. Returns a list of receivable block hashes with amount and source accounts \n\n**Request:**\n```json\n{\n \"action\": \"wallet_receivable\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"1\",\n \"source\": \"true\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": {\n \"nano_1111111111111111111111111111111111111111111111111117353trpda\": {\n \"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D\": {\n \"amount\": \"6000000000000000000000000000000\",\n \"source\": \"nano_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr\"\n }\n },\n \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\": {\n \"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74\": {\n \"amount\": \"106370018000000000000000000000000\",\n \"source\": \"nano_13ezf4od79h1tgj9aiu4djzcmmguendtjfuhwfukhuucboua8cpoihmh8byo\"\n }\n }\n }\n}\n``` \n**Optional \"include_active\"**\n\n_version 15.0+_ \nBoolean, false by default. Include active blocks without finished confirmations \n\n**Request:**\n```json\n{\n \"action\": \"wallet_receivable\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"1\",\n \"include_active\": \"true\"\n}\n``` \n\n**Optional \"min_version\"**\n\n_version 15.0+_ \nBoolean, false by default. Returns the minimum version (epoch) of a block which can pocket this receivable block.\n\n**Optional \"include_only_confirmed\"**\n\n_version 19.0+_ \nBoolean, true by default (_version 22.0+_), previously false by default. Only returns confirmed blocks but with the caveat that their confirmation height might not be up-to-date yet. If false, unconfirmed blocks will also be returned.\n\n---\n\n### wallet_representative \nReturns the default representative for **wallet** \n\n**Request:**\n```json\n{\n \"action\": \"wallet_representative\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"representative\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n```\n\n---\n\n### wallet_representative_set \n_enable_control required_ \nSets the default **representative** for **wallet** _(used only for new accounts, already existing accounts use already set representatives)_ \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_representative_set\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"representative\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n``` \n**Response:**\n```json\n{\n \"set\": \"1\"\n}\n```\n\n**Optional \"update_existing_accounts\"**\n\n_version 18.0+_ \nBoolean, false by default. Change representative for existing accounts in wallet. May require a lot of time to complete for large wallets due to work generation for change type state blocks \n\n---\n\n### wallet_republish \n_enable_control required, version 8.0+_ \nRebroadcast blocks for accounts from **wallet** starting at frontier down to **count** to the network \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_republish\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"count\": \"2\"\n}\n``` \n**Response:**\n```json\n{\n \"blocks\": [\n \"991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948\",\n \"A170D51B94E00371ACE76E35AC81DC9405D5D04D4CEBC399AEACE07AE05DD293\",\n \"90D0C16AC92DD35814E84BFBCC739A039615D0A42A76EF44ADAEF1D99E9F8A35\"\n ] \n}\n``` \n\n---\n\n### wallet_work_get\n_enable_control required, version 8.0+_ \nReturns a list of pairs of account and work from **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"wallet_work_get\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"works\": {\n \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\": \"432e5cf728c90f4f\"\n }\n}\n``` \n\n---\n\n### work_get\n_enable_control required, version 8.0+_ \nRetrieves work for **account** in **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_get\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\"\n}\n``` \n**Response:**\n```json\n{\n \"work\": \"432e5cf728c90f4f\"\n}\n``` \n\n---\n\n### work_set\n_enable_control required, version 8.0+_ \nSet **work** for **account** in **wallet** \n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"work_set\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"account\": \"nano_1111111111111111111111111111111111111111111111111111hifc8npp\",\n \"work\": \"0000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"success\": \"\"\n}\n``` \n\n---\n\n## Unit Conversion RPCs\n\n---\n\n### nano_to_raw \nConvert `nano` amount (10^30 raw) into `raw` (10^0) \n\n**Request:**\n```json\n{\n \"action\": \"nano_to_raw\",\n \"amount\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1000000000000000000000000000000\"\n}\n```\n\n### raw_to_nano \nConvert `raw` amount (10^0) into `nano` (10^30 raw)\n\n**Request:**\n```json\n{\n \"action\": \"raw_to_nano\",\n \"amount\": \"1000000000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1\"\n}\n```\n\n---\n\n## Deprecated RPCs\n\n---\n\n\n### active_difficulty\n_added in version 19.0+_ \n_deprecated in version 22.0_\n\nReturns the difficulty values (16 hexadecimal digits string, 64 bit) and related multiplier from base difficulty.\n\n| Field Name | Response Details |\n|---------------------------|------------------|\n| `multiplier` | Multiplier of the `network_current` from the base difficulty of `network_minimum` for comparison. Note that in V22.0+ this will always be 1 (see below for details). |\n| `network_minimum` | Minimum difficulty required for the network for all block types |\n| `network_current` | _V22.0+_ same minimum difficulty above due to the deprecation of active difficulty calculations used for prioritization in previous versions; _up to V21.3_ 10 second trended average of adjusted difficulty seen on prioritized transactions, refreshed every 500ms |\n| `network_receive_minimum` | Lower difficulty threshold exclusively for receive blocks |\n| `network_receive_current` | _V22.0+_ same minimum receive difficulty above due to the deprecation of active difficulty calculations used for prioritization in previous versions; _up to V21.3_ 10 second trended average of adjusted difficulty seen on prioritized receive transactions, refreshed every 500ms |\n\n!!! info \"Constant values returned\"\n Due to the deprecation of active difficulty calculations as of V22.0, this RPC call will return constant values as seen below. These values can be used as difficulty thresholds for the respective block types, but this RPC call should not be used for retrieving these values going forward.\n\n**Request:**\n```json\n{\n \"action\": \"active_difficulty\"\n}\n``` \n\n**Response:**\n```json\n{\n \"deprecated\": \"1\",\n \"network_minimum\": \"fffffff800000000\",\n \"network_receive_minimum\": \"fffffe0000000000\", // since V21.2\n \"network_current\": \"fffffff800000000\",\n \"network_receive_current\": \"fffffe0000000000\", // since V21.2\n \"multiplier\": \"1\"\n}\n```\n\n**Optional \"include_trend\"**\n\nBoolean, false by default. Also returns the trend of difficulty seen on the network as a **list of multipliers**. Sampling occurs every 500ms. The list is ordered such that the first value is the most recent sample. \nNote: Before v20, the sampling period was between 16 and 36 seconds.\n\n**Request:**\n```json\n{\n \"action\": \"active_difficulty\",\n \"include_trend\": \"true\"\n}\n```\n\n**Response:**\n```json\n{\n ...,\n \"difficulty_trend\": [\n \"1.156096135149775\",\n \"1.190133894573061\",\n \"1.135567138563921\",\n \"1.000000000000000\",\n \"...\",\n \"1.000000000000000\"\n ]\n}\n```\n\n---\n\n### accounts_pending\n\nDeprecated in V24.0+. Replaced by [accounts_receivable](#accounts_receivable)\n\n---\n\n### history \n\n**Deprecated**: please use `account_history` instead. It provides a `head` option which is identical to the history `hash` option.\n\n---\n\n### krai_from_raw \n\nDeprecated in V28.0+. For alternatives, see [Unit Conversion RPCs](#unit-conversion-rpcs)\n\nDivide a raw amount down by the krai ratio. \n\n**Request:**\n```json\n{\n \"action\": \"krai_from_raw\",\n \"amount\": \"1000000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1\"\n}\n```\n\n---\n\n### krai_to_raw \n\nDeprecated in V28.0+. For alternatives, see [Unit Conversion RPCs](#unit-conversion-rpcs)\n\nMultiply an krai amount by the krai ratio. \n\n**Request:**\n```json\n{\n \"action\": \"krai_to_raw\",\n \"amount\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1000000000000000000000000000\"\n}\n```\n\n---\n\n### mrai_from_raw \n\nDeprecated in V28.0+. For alternatives, see [Unit Conversion RPCs](#unit-conversion-rpcs)\n\nDivide a raw amount down by the Mrai ratio. \n\n**Request:**\n```json\n{\n \"action\": \"mrai_from_raw\",\n \"amount\": \"1000000000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1\"\n}\n```\n\n---\n\n### mrai_to_raw \n\nDeprecated in V28.0+. For alternatives, see [Unit Conversion RPCs](#unit-conversion-rpcs)\n\nMultiply an Mrai amount by the Mrai ratio. \n\n**Request:**\n```json\n{\n \"action\": \"mrai_to_raw\",\n \"amount\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1000000000000000000000000000000\"\n}\n```\n\n---\n\n### node_id_delete\n_enable_control required, _added in version 17.0+_ \n_deprecated in version 19.0_\n\n--8<-- \"warning-debug-only-command.md\"\n\nRemoving node ID (restart required to take effect)\n\n--8<-- \"warning-enable-control.md\"\n\n**Request:**\n```json\n{\n \"action\": \"node_id_delete\"\n}\n``` \n**Response:**\n```json\n{\n \"deprecated\": \"1\"\n}\n``` \n\n---\n\n### rai_from_raw \n\nDeprecated in V28.0+. For alternatives, see [Unit Conversion RPCs](#unit-conversion-rpcs)\n\nDivide a raw amount down by the rai ratio. \n\n**Request:**\n```json\n{\n \"action\": \"rai_from_raw\",\n \"amount\": \"1000000000000000000000000\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1\"\n}\n```\n\n---\n\n### rai_to_raw \n\nDeprecated in V28.0+. For alternatives, see [Unit Conversion RPCs](#unit-conversion-rpcs)\n\nMultiply an rai amount by the rai ratio. \n\n**Request:**\n```json\n{\n \"action\": \"rai_to_raw\",\n \"amount\": \"1\"\n}\n``` \n**Response:**\n```json\n{\n \"amount\": \"1000000000000000000000000\"\n}\n```\n\n---\n\n### pending\n\nDeprecated in V23.0+. Replaced by [receivable](#receivable)\n\n---\n\n### pending_exists\n\nDeprecated in V23.0+. Replaced by [receivable_exists](#receivable_exists)\n\n---\n\n## Removed RPCs\n\n---\n\n### confirmation_height_currently_processing\n_added in version 19.0+_ \n_removed in version 27.0_\n\n--8<-- \"warning-debug-only-command.md\"\n\nReturns the hash of the block which is having the confirmation height set for, error otherwise. When a block is being confirmed, it must confirm all blocks in the chain below and iteratively follow all receive blocks. This can take a long time, so it can be useful to find which block was the original being confirmed.\n\n**Request:**\n```json\n{\n \"action\": \"confirmation_height_currently_processing\"\n}\n``` \n**Response:**\n```json\n{\n \"hash\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\n\n---\n\n### block_count_type \nReports the number of blocks in the ledger by type (send, receive, open, change, state with version) \n\n**Request:**\n```json\n{\n \"action\": \"block_count_type\"\n}\n``` \n**Response:**\n```json\n{\n \"send\": \"5016664\",\n \"receive\": \"4081228\",\n \"open\": \"546457\",\n \"change\": \"24193\",\n \"state_v0\": \"4216537\",\n \"state_v1\": \"10653709\",\n \"state\": \"14870246\"\n}\n``` \n\n---\n\n### payment_begin \nBegin a new payment session. Searches wallet for an account that's marked as available and has a 0 balance. If one is found, the account number is returned and is marked as unavailable. If no account is found, a new account is created, placed in the wallet, and returned. \n\n**Request:**\n```json\n{\n \"action\": \"payment_begin\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"account\" : \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\"\n}\n``` \n\n---\n\n### payment_end \nEnd a payment session. Marks the account as available for use in a payment session. \n\n**Request:**\n```json\n{\n \"action\": \"payment_end\",\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"wallet\": \"FFFD1BAEC8EC20814BBB9059B393051AAA8380F9B5A2E6B2489A277D81789EEE\"\n}\n``` \n**Response:**\n```json\n{\n}\n``` \n\n---\n\n### payment_init \nMarks all accounts in wallet as available for being used as a payment session. \n\n**Request:**\n```json\n{\n \"action\": \"payment_init\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n``` \n**Response:**\n```json\n{\n \"status\": \"Ready\"\n}\n``` \n\n---\n\n### payment_wait \nWait for payment of 'amount' to arrive in 'account' or until 'timeout' milliseconds have elapsed. \n\n**Request:**\n```json\n{\n \"action\": \"payment_wait\",\n \"account\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"amount\": \"1\",\n \"timeout\": \"1000\"\n}\n``` \n**Response:**\n```json\n{\n \"deprecated\": \"1\",\n \"status\" : \"success\"\n}\n``` \n" }, { "path": "docs/core-development/code-standards.md", "content": "title: Code Standards\ndescription: Learn about the code standards expected when contributing to the nano protocol and node implementation\n\n# Code standards\n\n## Formatting\n\nclang-format is used to enforce most of the formatting rules, such as:\n\n* Tabs for indentation.\n* Open braces go on new lines.\n* Space before open parenthesis.\n* Space after comma.\n\nRunning `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.\n\nMake 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.\n\n## General guidelines\n\n* 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]\n* Handle exceptions, including IO exceptions for file and network operations.\n* 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.\n* Be liberal with `logger.always_log` or `logger.try_log` statements, except in performance critical paths.\n* Add comments to explain complex and subtle situations, but avoid comments that reiterates what the code already says.\n* Use RAII and C++11 smart pointers to manage memory and other resources.\n\n## Performance and scalabiliy considerations\n\n* When making changes, think about performance and scalability. Pick good data structures and think about algorithmic complexity. \n * 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).\n* Make sure your change doesn't conflict with the scalability characteristics described in the white paper.\n\n## Security\n\nYour code will be reviewed with security in mind, but please do your part before creating a pull request:\n\n* Familiarize yourself with best practices for writing secure C++ code. In particular:\n * Consult https://wiki.sei.cmu.edu/confluence/display/cplusplus\n * Avoid using ANSI C functions. Many of these are prone to buffer overruns.\n * Avoid using C strings and direct buffer manipulation.\n\n* 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.\n\n[^1]: https://dmitryfrank.com/articles/indent_with_tabs_align_with_spaces\n[^2]: http://www.acodersjourney.com/2016/02/c-11-auto/\n" }, { "path": "docs/core-development/collaboration-process.md", "content": "title: Collaboration Process\ndescription: Find out how the open source collaboration process works with the nano protocol and node software\n\n# Collaboration Process\n\n## Code Process\n\n**Fork and do all your work on a branch**\n\nNano 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. \n\n**Create pull requests**\n\nBefore:\n\n* Branch out of the **develop** branch. The **master** branch is only updated on new releases.\n* Review your code locally. Have you followed the [Code Standards](code-standards.md) closely?\n* 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?\n* 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\n* Run clang formatting script and resolve any raised issues: `ci/clang-format-do.sh`\n* Commit and push your fork branch\n\nAfter:\n\n* Create pull request on the upstream repository:\n * Make sure you add a description that clearly describes the purpose of the PR.\n * If the PR solves one or more issues, please reference these in the description.\n* 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.\n* Respond to comments and reviews in a timely fashion.\n\n**Resolve conflicts**\n\nIf 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.\n\nThe preferred process is to rebase your changes, resolve any conflicts, and push your changes again. [^1][^2]\n\n* Check out your branch\n* `git fetch upstream`\n* `git rebase upstream/develop`\n* Resolve conflicts in your favorite editor\n* `git add {filename}`\n* `git rebase --continue`\n* Commit and push your branch\n\n**Consider squashing or amending commits**\n\nIn the review process, you're likely to get feedback. You'll commit and push more changes, get more feedback, etc. \n\nThis can lead to a messy git history, and can make stuff like bisecting harder.\n\nOnce your PR is OK'ed, please squash the commits into a one.[^3]\n\nNote 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.\n\n## Finding issues or features to work on\n\n- Issues are available on GitHub, with the most urgent being in the latest milestone for release\n- 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\n- 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\n\n## Submitting issues and feature requests\n\nStandard 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.\n\n## Discussion channels\n\nVarious channels exist for discussing code changes with the Nano Foundation and community.\n\n**GitHub**\n\nTo 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.\n\n**Discord for chat**\n\nFor 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.\n\n**Forum**\n\nAnother 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.\n\n## Proposals\n\nThere 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.\n\n[^1]: https://help.github.com/articles/resolving-merge-conflicts-after-a-git-rebase/\n[^2]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/\n[^3]: https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit" }, { "path": "docs/core-development/developer-discussions.md", "content": "title: Developer Discussions\ndescription: Links & notes for recurring live discussions about Nano development. Includes discussion between community developers and the Nano Foundation. Technical, developer-focused.\n\n# Developer Discussions\n\nLinks & notes for recurring live discussions about Nano development. Includes discussion between community developers and the Nano Foundation. Technical, developer-focused.\n\n!!! note\n These developer discussions are best effort, live discussions, and may not contain the most accurate (or most recent) information. The intent of these discussions is to promote transparency, collaboration, & community-driven efforts, but development plans may change at any time. \n \n The below notes are also best effort, and may not be 100% accurate.\n\n## Sept 3, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1830969052820578365?t=Abqg6T-exPd5FhaQ2inY2w&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1f822rt/weekly_nano_developer_space_aug_3_2024/)\n\n## Aug 20, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1825895842437607934?t=3t1YvnV2gRsLJXoCgECw6w&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1ewzj2n/weekly_nano_developer_space_aug_20_2024/)\n\n## Aug 6, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1820822202297819143)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1elry5z/weekly_nano_developer_space_aug_6_2024/)\n\n## July 23, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1815748878320189616?t=L8QhI04wdbx87MQIJYoxug&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1eaa9i0/weekly_nano_developer_space_jul_23_2024/)\n- [YouTube](https://www.youtube.com/watch?v=cMK_Q50uWHk)\n\n## July 16, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1813204252380070206)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1e54dvm/weekly_nano_developer_space_july_16_2024/)\n- [YouTube](https://www.youtube.com/watch?v=Dx5ZEYwdbyw)\n \n## July 9, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1810675179137192279?t=hEmkKBHOxRK9RofyNnUwVg&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1dz36p3/weekly_nano_developer_space_jul_9_2024/)\n- [YouTube](https://www.youtube.com/watch?v=Z7n75b8i9sI)\n \n## July 2, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1808138726742065452?t=eqerZHL7ApiqRzFOs91V5g&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1dtmuk4/weekly_nano_developer_space_jul_2_2024/)\n- [YouTube](https://www.youtube.com/watch?v=JSEBA5HNqgE)\n\n## June 18, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1803065216919273931)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1dj46ct/weekly_nano_developer_space_june_18_2024/)\n \n## June 11, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1800528535251267598?t=b7_ZOImygrwAW8yiRw8cdw&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1ddgvyj/weekly_nano_developer_talk_june_11_2024/)\n \n## May 21, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1792897054726824333)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1cx7jqw/weekly_nano_developer_space_may_21_2024/)\n \n## May 14, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1790381641107439731?t=Ms5Dy0bBFVqx8GbkOy8lGA)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1crv7i1/weekly_nano_developer_space_may_14_2024/)\n \n## April 30, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1785308297924432315)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1ch55iu/weekly_nano_developer_space_apr_30_2024/)\n\n## April 23, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1782771656408158483)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1cbhe9x/weekly_nano_developer_space_apr_23_2024/)\n \n## April 16, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1780234655565746684?t=FGvjQKPRKAbxGRSIfCHR4A)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1c5gwux/weekly_nano_developer_space_apr_16_2024/)\n \n## April 9, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1777697905698107554)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1c0268f/weekly_nano_developer_space_apr_9_2024/)\n \n## March 26, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1772639556455567629?t=RTr-oEgf8ZoM1tEcfInxBw)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1bobrah/weekly_nano_developer_space_mar_26_2024/)\n \n## March 19, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1770091771541828085)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1bin1m6/weekly_nano_developer_space_mar_19_2024/)\n \n## March 12, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1767566192103825707)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1bd25p2/weekly_nano_developer_talk_mar_12_2024/)\n \n## March 5, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1765029691398734023?t=r6mG_OO6tKdnu32F5dhjnQ)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1b79viz/weekly_nano_developer_space_mar_5_2024/)\n \n## February 20, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1759956505606971745?t=98X_E9aTopR6qVaps1BEpw)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1avmgtd/weekly_nano_developer_space_feb_20_2024/)\n \n## February 13, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1757414995858526559)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1apv3i4/weekly_nano_developer_space_feb_13_2024/)\n \n## February 6, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1754882713926926420?t=3KncD_dJcwZeI07_JXuNdg)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1akexw7/weekly_nano_developer_space_feb_6_2024/)\n \n## January 30, 2024\n\n- [Developer call](https://x.com/gr0vity_dev/status/1752345979024490835)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/1af3o40/weekly_nano_developer_call_jan_30_2024/)\n \n## January 23, 2024\n\n- [Developer call](https://x.com/ColinLeMahieu/status/1749804269925232822)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/19dv1ca/weekly_nano_developer_call_jan_23_2024/)\n \n## January 16, 2024\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1747272701008634175)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/198wdac/weekly_nano_developer_call_jan_16_2023/)\n\n## January 9, 2024\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1744735898879811779)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/192my3t/weekly_nano_developer_space_jan_9_2024/)\n\n## December 12, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1734588963585728526)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/18gs1kr/weekly_nano_developer_space_dec_12_2023_last_one/)\n\n## December 5, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1732052255103221870)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/18bdsq8/weekly_nano_developer_talk_dec_5_2023/)\n\n## November 28, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1729515603529023585)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/185xrqi/weekly_nano_developer_call_nov_28_2023/)\n\n## November 21, 2023\n\n- [Developer call](https://twitter.com/gr0vity_dev/status/1726978836074742207)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/180p7jf/weekly_nano_developer_space_nov_21_2023/)\n\n## November 14, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1724442197179650478)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/17v5uat/weekly_nano_developer_space_november_14_2023/)\n\n## November 7, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1721905435056488743)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/17pwaa2/weekly_nano_developer_space_nov_7_2023/)\n\n## October 31, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1719368918895088121)\n\n## October 24, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1716817097408524743)\n\n## October 17, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1714280349738701183)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/17a344v/weekly_nano_developer_space_oct_17_2023/)\n\n## October 10, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1711743518576672943)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/174yxtu/weekly_nano_developer_space_oct_10_2023/)\n\n## October 3, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1709206677633782029)\n\n## September 26, 2023\n\n- [Developer call](https://twitter.com/ColinLeMahieu/status/1706669851912151247?t=YTMabUbEfkQgjIoVtGSKKg&s=19)\n- [Reddit discussion](https://www.reddit.com/r/nanocurrency/comments/16spnl2/colin_lemahieu_hosting_live_twitter_space_about/)\n" }, { "path": "docs/core-development/overview.md", "content": "title: Core Development Overview\ndescription: All you need to know to help contribute to the core development of the nano node and protocol\n\n# Core Development\n\nWelcome 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.\n\n## Getting started\n\nIt 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.\n\n- Start by reviewing the [living whitepaper](../living-whitepaper/index.md)\n- Read through (or try out) the [running a node guides](../running-a-node/overview.md)\n- Understand [the basics](../integration-guides/the-basics.md) and maybe even some [advanced details](../integration-guides/advanced.md) about integrations\n- Learn how to [build the node yourself](../integration-guides/build-options.md)\n- Participate in the community through [Discord](https://chat.nano.org)\n- Start perusing the code in the repositories below and don't be afraid to ask questions\n\n\n## Code repositories\n\nThe 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.\n\n| Name | Language | Purpose |\n|------|----------|---------|\n| [nanocurrency/nano-node](https://github.com/nanocurrency/nano-node) | C++| Primary node implementation used on the nano network |\n| [rs-nano-node](https://github.com/rsnano-node/rsnano-node) | Rust| Alternative node implementation by Gustav |\n| [nanocurrency/nano-work-server](https://github.com/nanocurrency/nano-work-server) | Rust | Standalone server for generating work values for blocks |\n| [nanocurrency/protocol](https://github.com/nanocurrency/protocol) | Kaitai Struct | Specification for nano network message protocol |\n| [nanocurrency/nanodb-specification](https://github.com/nanocurrency/nanodb-specification) | Kaitai Struct | Specification for database tables and fields used by the `nano-node` implementation |\n| [nanocurrency/nano-docs](https://github.com/nanocurrency/nano-docs) | Markdown | MKDocs based documentation this docs.nano.org site is built from |\n\nMost 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)).\n\n## Security vulnerability reporting\n\n--8<-- \"warning-security-vulnerability-reporting.md\"\n\n## Nano Foundation core developers\n\nIn 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)." }, { "path": "docs/core-development/understanding-the-code.md", "content": "title: Understanding the code\ndescription: Learn about the nano code for better development practices\n\n# Understanding the code\n\nThis guide is designed to give an overall structure of the core nano protocol codebase to help new developers get a better understanding of the different areas and how they interoperate. Due to the rapid changing nature of the protocol it’s possible some of the features are moved to different places or have changed entirely. Working on the protocol requires a very multi-disciplined and wide area of knowledge, none of it is particularly mandatory to get started but a good C++ understanding will help prevent being too overwhelmed initially: \n\nItems required include:\n\n- Windows/MacOS/Linux\n- C++20 compiler\n- Boost\n- Git\n- CMake\n\nUseful experience includes modern C++ knowledge (up to C++20) including multithreading primitives (mutex, condition variables, atomics) & templates, Boost (asio & beast), RocksDB, LMDB, FlatBuffers, JSON-RPC, IPC, networking communication (ip/tcp, message passing, broadcasting algorithms), QT, signal handling, PKI cryptography, git & cross-platform development.\n\nThe main Nano projects are located inside the `/nano` subdirectory. \n\n## Executable binaries\n\nAll executables have `nano_` prefix and projects have a `main` function inside `entry.cpp`\n\n**nano_node** – The standard way to start a node. There are 2 source files in here, `entry.cpp` and `daemon.cpp`. `nano_daemon::daemon::run()` is always called so is a good place to put a breakpoint if there are any issues during node operation (especially errors when launching initially).\n\n**nano_rpc** – This executable does not need to be run explicitly unless out of process RPC is selected. https://docs.nano.org/integration-guides/advanced/?h=+nano_rpc#running-nano-as-a-service Because this project is quite small it is all done inside the `entry.cpp` file and is probably an easier starting point template should anything else need to be moved out of process in the future.\n\n**nano_wallet** – This essentially does the same as `nano_node` but doesn’t support all CLI commands and has a graphical user interface for the wallet.\n\n---\n\n## Tests\n\nThe googletest (gtest) framework is used to validate a variety of functionality in the node, we do not currently use gmock in the codebase. \n\n### Running tests\nThe dev network is forced for locally run tests, this lowers work and other settings to make it simpler to test.\nBuild with `cmake -DNANO_TEST=ON ..`\nSee docs.nano.org for more information. There may be intermittent failures, if so add them here https://github.com/nanocurrency/nano-node/issues/1121 and fix if possible.\n\n### Executables\n\n**core\\_test** – This is where the majority of tests should go. If there is any new functionality added or something has changed, it more often than not should have a test here! Any new core areas should have their own separate test file to encapsulate the logic. \n\n**ipc\\_flatbuffers\\_test** – This actually doesn’t use the `gtest` library and has its own main file which just contains a simple example of using flatbuffers. \n\n**load_test** – This creates a dynamic number of nodes, sends blocks from 1 of the nodes (primary) and waits until all other nodes have the same number of blocks. This does not normally need to be modified but is run as part CI at the end. \n\n**rpc_test** – All RPC tests go here. There is some boilerplate to follow which creates an `ipc_server` for the node which mimics out of process rpc commands communicating with it. Care must be taken when creating write transactions as they are not allowed on io-threads (https://github.com/nanocurrency/nano-node/pull/1264). To make sure this is adhered to when calling the RPC commands, there is an RAII object `scoped_io_thread_name_change` which changes the current thread (normally the main one) to be `io`, and restores it when the object goes out of scope. For instance\n```\n...\nscoped_thread_name_io.reset ();\nnode.process (state_block);\nscoped_thread_name_io.renew ();\n```\n**slow_test** – Any core tests which are not suitable for CI because they take a long time (> a few seconds) should go here. There is a desire to make this file run once per night, but until then should be periodically run by developers.\n\n### Work/Sig verification modifying for tests\n\nA common mistake is to request work for the hash of the block to be added, but it should happen on the root (previous one). The work difficulty is different for the live/beta/dev networks and are set using the `work_thresholds` class. During any local testing, where a lot of blocks are processed, work generation and signature verification can take the majority of the time. To speed this up it can make sense to manually lower the work difficulty even further and change the sig verification to always return `true`.\n\n### Helpers\n\n**test_common** – This is a helper library which contains test specific (not node related) things which can be used by all test projects. This project should not have a `node` dependency. Anything which does should be put into `nano/node/testing.cpp`.\n\n### Fuzzer\n\nThe fuzzer uses libfuzzer which inputs arbitrary data continuously trying to find catch edge cases missed in traditional testing on specific examples. This is not currently supported on Windows. The executables are found in fuzzer_test/\\*. The node must be built with the CMake option `-DNANO_FUZZER_TEST=ON`, this does not require that `NANO_TEST` be set. Currently there are 3 executables built: fuzz_bignum, fuzz_buffer, fuzz_endpoint_parsing.\n\n**Notes:** \nThere aren’t currently tests for specific CLIs so it’s recommended to abstract the functionality so that it can be tested in `core_test`.\n\n### Testing implementation details\nSometimes it is necessary to be able to change something about a class only for a test. Rather than make this the class interface public just for tests, the specific tests can be added as friends to the class, this is done like so for a test named like so TEST (node, example);\n```\nclass my_class\n{\nprivate:\n int private_member; // the Test (node, example); test can access this member\n friend class node_example_Test;\n};\n```\nThe test itself needs to be wrapped with the nano { } namespace for this to work correctly, if the class itself is in the nano namespace which is normally the case.\n\n### Additional pre-release testing\n- Run tests with TSAN/ASAN/Valgrind. All errors should be fixed before launch unless these are determined to be test related or false positives. We currently have some errors with using coroutines. There are blacklist files for the sanitizers which remove some errors caused by lmdb & rocksdb.\n\n---\n\n## Bootstrapping\n\nWhen you first start a Nano node, it must download & validate transactions until its ledger (account & transaction history) is in sync with the other nodes on the network. This process is called bootstrapping. There are 3 bootstrapping methods, ascending, legacy, and lazy. See [here](https://github.com/nanocurrency/nano-node/issues/3837) and [here](https://medium.com/nanocurrency/nano-explainer-lazy-bootstrapping-6f091e1eae8c) for more information. \n`node/bootstrap/boostrap_attempt.hpp` contains the base class definition for bootstrap attempts.\n\n### Ascending\n\n`node/bootstrap/bootstrap.cpp`\n\nNano node versions V24 & V25 introduced ascended bootstrapping - a complete rewrite of how Nano nodes sync account & transaction history from scratch. Prior to V24, the bootstrap mechanism served transactions (blocks) in a top down format (i.e. newest to oldest / frontier to genesis), but since the blocks must be added to the local ledger from the bottom up (i.e. oldest to newest / genesis to frontier), the node spent a lot of time reordering transactions. This consumed a significant amount of disk space and disk IO (disk reads/writes), both of which contribute to long bootstrapping times (i.e. days or weeks).\n\nAscending bootstrapping sends & processes transactions from the bottom up, allowing nodes to easily trace transaction order without a complicated (and time consuming) re-ordering process. This significantly improves the speed of bootstrapping, removes complexity from the codebase, & reduces overall resource usage.\n\nFor more technical details, see [here](https://github.com/nanocurrency/nano-node/issues/3837).\n\n### Legacy\n\n`node/bootstrap/bootstrap_legacy.cpp`\n\nLegacy bootstrapping works by requesting frontiers periodically (every 5 minutes) from a random selection of peers, this is done in `nano::node::ongoing_bootstrap ()`. `bootstrap_frontier.cpp` contains the frontier req client and server. A `frontier_req` message is send from `frontier_req_client` to get a list of frontiers from a peer’s `frontier_req_server` starting at `frontier_req.start` which is done as `accounts_begin (transaction, current + 1);`. The accounts are sorted by their hash.\n\n### Lazy\n\n`node/bootstrap/bootstrap_lazy.hpp` \n\nLazy bootstrapping works by having nodes monitor the real-time network and observing live block confirmation. In combination with [optimistic elections](https://github.com/nanocurrency/nano-node/pull/4111), when a node sees confirmation for a new block, all previous blocks in the newly confirmed block's account-chain are also considered valid & confirmed, and are then inserted into node's local ledger.\n\n### Wallet lazy\n\nTODO\n\n### How messages are handled\n\n`node/bootstrap/bootstrap_server.cpp` \n\nWhen a message is received through the bootstrap server, its header is first checked inside `nano::bootstrap_server::receive_header_action ()`. The message is deserialized and added in `add_request ()` to the `std::queue> requests` collection which holds a queue of messages. `run_next ()` is then called (and will be called after the request is finished if there are more messages to process), this runs the message through a `request_response_visitor` object which creates a `tcp_message_item` and adds it to the `tcp_message_manager` to be processed. The newest set of messages added were for telemetry. If new messages need adding that can be used as a guide: https://github.com/nanocurrency/nano-node/pull/2446\n\n---\n\n## Workers (thread pool)\n\nThe class definition for `thread_pool` is defined inside `nano/lib/threading.cpp`, which allows tasks to be added to a queue for execution as well as executed at a specific time. Previously there were worker/alarm classes, which were combined in https://github.com/nanocurrency/nano-node/pull/2871. Its primary purpose was to schedule write transactions off the io threads. It is generally recommended to push other tasks onto the io threads though to avoid bottlenecking these threads.\n\n---\n\n## Database\n\nThere are 2 logical areas where a persistent file is needed: the ledger and wallets. For this 2 NoSQL databases which store binary data are used, namely LMDB & RocksDB. The ledger database is comprised of a few files:\n\n- `nano/secure/store.hpp`: database interfaces, value object conversions, visitors, and high-level implementations\n- `nano/node/lmdb/`: anything specific to LMDB goes here\n- `nano/node/rocksdb/`: anything specific to RocksDB goes here\n\nThe wallets database uses the wallets_store which only has an LMDB backend.\n\n### Database upgrades\n\n`nano::lmdb::store::do_upgrades ()` is where LMDB database upgrades are done. For instance `void nano::lmdb::store::upgrade_v21_to_v22 ()` combines all block databases into a single one. Raw mdb functions are normally required as `block_store::get ()` and other functions normally can’t be used because they are updated to the latest db spec. The RocksDB upgrades were introduced by V25.0. It follows a similar approach implemented for LMDB. There were in the past multiple upgrades during a release when a beta build went out and a subsequent upgrade was desired. Previously a ledger reset was done and the version was re-used but this was deemed too inconvenient.\n\n### write_database_queue\nThis was introduced to reduce LMDB write lock contention between the block processor and the confirmation height processor. As during bootstrapping or high TPS the block processor can hold onto the lock up to 5s (by default), before the lock is held by the blockprocessor it signals that it is about to get the LMDB lock, the confirmation height processor can make use of this information and continue processing where it would otherwise be stalled. Ongoing pruning also makes use of this.\n\n---\n\n## Block processing\n\nThere are 4 types of legacy blocks: open, receive, send & change. There are the state blocks which encompass traits from the legacy subtypes as well as support epochs. In various places an `epoch_link` is checked, this indicates that the link field is set to one of the epoch accounts (for v1 state blocks), or possibly self for v2 state blocks upgrade blocks. No new legacy blocks can be created (there are about 10million), but they still need to be handled in any algorithm which deals with blocks because users can still be bootstrap from scratch. When a node is first launched without a ledger `block_store_partial::init ()` is called, this creates the genesis block. Blocks are then bootstrapped.\n\n---\n\n## Ledger\n\n`nano/secure/ledger.cpp` is where blocks are added and deleted to the ledger database.\n\nThe ledger cache is used when it may be expensive to try and determine the count of something in the ledger. It was originally used for the cemented count, because this is determined by adding the confirmation height from all accounts. This does mean that any external write operations from LMDB (such as CLI command `--confirmation_height_clear`) will cause this number to get out of sync. This is not possible with RocksDB backend because it does not allow multi-process write transactions.\n\n---\n\n## Node initialization\n\nThe biggest bottleneck for node start-up is caused by setting up the ledger cache. This requires scanning all accounts & conf height databases. A multi-threaded process (added in https://github.com/nanocurrency/nano-node/pull/2876) splits the account space into equal partitions (as accounts should be randomly distributed) and does sequential sorted reads in each partition; this is the most efficient way to search through any of the databases. Point/Random reads are very slow in comparison.\n\n### Keeping build times low\n\n`nano/node/node.hpp` is the largest build bottleneck, it can increase build times of files by up to 10 seconds on some systems! Some boost files tend to be large too, they offer forward declaration headers such as `` & `` worth checking if they exist for any you are using in header files.\n\n### node_initialized_latch\n\nSome classes use `node_initialized_latch.wait ();` The latch was added in https://github.com/nanocurrency/nano-node/pull/2042 this is to prevent some of the issues in the node constructor initializer list where the `node` object is passed and a child constructor is wants to use a node member which is not yet initialized. This makes it resume operation once the latch is incremented at the beginning of the `node` constructor.\n\n### Initial output\nWhen the node is run it prints out some information about the database used, compiler etc. An example of appending to the output is here: https://github.com/nanocurrency/nano-node/pull/2807\n\n---\n\n## CMake \n\nCMake is used as the build system, and git submodules for any third party dependencies (except boost which must be installed separately by the developer). In `CMakeLists.txt` header files (.hpp) are above source files (.cpp), no particular reason but consistency is important.\n\n### Developer build options\n\n`-DNANO_TIMED_LOCKS=10` \n\nAdded: https://github.com/nanocurrency/nano-node/pull/2267. In `nano/lib/locks.hpp(.cpp)`, `std::mutex`, `std::condition_variable`, `std::unique_lock` & `std::lock_guard` are wrapped in custom classes (with the same interface) which adds some extra timing functionality to check if a mutex was help for a time longer than `NANO_TIMED_LOCKS` in milliseconds. This is useful to see if mutex contention is a cause of any performance loss. To pinpoint a specific mutex https://github.com/nanocurrency/nano-node/pull/2765 added `NANO_TIMED_LOCKS_FILTER=confirmation_height_processor`. The full list of mutexes is available in `nano/lib/locks.cpp` - `mutex_identifier()` .\n\n---\n\n## APIs\n\n### CLI\n\nThere are 2 places that CLI commands can be added for use with `nano_node`, `nano/node/cli.cpp` & `nano/nano_node/entry.cpp`. The `nano/node/cli.cpp` CLI commands are also shared with `nano_wallet` so this is the place to put shared logic which can be used by both. CLI commands prefixed with `debug_*` shouldn’t really be used by end users unless they are diagnosing issues. Sometimes it can be useful to compare the RPC output with CLI, and rpc results such as `block_count` will return cached results.\n\n### IPC\n\nWhen using the `nano_rpc` as a separate process (either child or manually starting it), there needs to be a way of communicating between processes. IPC supports tcp and unix domain sockets, `nano_rpc` only supports tcp as it can be run on a different computer. IPC 2.0 adds flatbuffer support (https://github.com/nanocurrency/nano-node/pull/2487) which can be used for the new RPC 2.0 (TBA).\n\n### Websockets\n\nWebsockets were introduced in https://github.com/nanocurrency/nano-node/pull/1840. Previously a HTTP callback had to be used, but websockets provides a more efficient 2 way communication protocol. Websocket events are available for various topics. For an example of adding a websocket topic look at: https://github.com/nanocurrency/nano-node/pull/2634. `observers.notify (message_a.data, endpoint);` is what ultimately invokes the websocket server to send a message which is deserialized inside `nano::websocket::message_builder`.\n\n---\n\n## Signal handling\n\nThere are 2 sets of signal handlers registered (both are only set when the `nano_node` is run as a daemon. `SIGSEGV` & `SIGABRT` are set at the beginning which will create dump files if there is a segmentation fault during program execution (added in https://github.com/nanocurrency/nano-node/pull/1921/). `SIGINT` & `SIGTERM` signals catch non-kill intentional closing of the executable, such as pressing ctrl+c (added in https://github.com/nanocurrency/nano-node/pull/2018). This shuts down the node allows any running write transactions to finish. Only async signal safe functions should be used in signal handlers, this limits it to very specific functions.\n\n---\n\n## Memory allocators\n\nA lot of our heap usage is from deserializing block/votes off the wire and ledger database. To solve this we use a memory pool allocator which reuses memory in a freelist: https://github.com/nanocurrency/nano-node/pull/2047\n\nIn `nano/lib/memory.hpp` a `nano::make_shared` function is defined which checks if the global variable `use_memory_pool` is set (initialized during node startup reading the config `node.use_memory_pools`, which defaults to true). The memory is never reclaimed, this is a performance optimization.\n\n---\n\n## Libraries and submodules\n\n### Boost\nWe use the Boost library where possible, such as coroutine, filesystem, endian converter, lexical_cast, multi_index_container etc. If there is a static/dynamic Boost library which is not used, there are generally no issues in adding it. Just make sure the build scripts and documentation are updated.\n\n**nano/boost**\nUse `nano/boost/asio` `nano/boost/beast` for includes, this wraps up various includes and prevents warnings being shown (particularly on Windows builds).\n\n### `nano/crypto_lib/`\n\nThis is a small library which has no dependency to anything in the nano core, which is needed as it is included by the ed25519 library as well. More info here: https://github.com/nanocurrency/nano-node/pull/1870\n\n### `test/common/`\n\nAny functionality which is shared between test projects and may also use gtest library. There is also `nano/node/testing.cpp` which has no gtest dependency because it is also used in CLI commands too.\n\n### `nano/lib` vs. `nano/secure`\nThe`nano/lib` library was originally intended to be used by other programs wanting some of the nano functionality, but those specific external C functions were removed and it has now become the place to put all commonly used code. As such anything which doesn’t depend on the node should go here, and the `secure` library is now mostly for ledger specific things.\n\n### git submodules\nWe have a variety of submodules https://docs.nano.org/node-implementation/contributing/?h=+submodule#about-the-code-base third party dependencies are to be kept as minimal as possible in order to keep build times lean, but if there is a suitable one it can be added a submodule.\n\n---\n\n## Assertions\n\n`debug_assert` is essentially the same as the traditional C++ assert but also outputs a stacktrace. Added in https://github.com/nanocurrency/nano-node/pull/2568. This should be used to check programmer logic.\n\n`debug_assert (!mutex.try_lock ());` When functions require that a mutex is required before being called we often check that the mutex is locked. Although this is technically undefined behaviour to be called by a thread which already owns the mutex we have been using this idiom for years and found no issues with the major compilers.\n\n`release_assert` this is an assert which is triggered in both release/debug build, it also outputs a stacktrace. This was added https://github.com/nanocurrency/nano-node/pull/1114. This should be used if some invariant doesn’t hold and there is no suitable way to recover from this. Such as reading something from the ledger which is meant to exist but doesn’t, can indicate ledger corruption.\n\n---\n\n## Voting/Consensus\n\nTo confirm a block a sufficient number of votes which are taken from `confirm_ack` messages are tallied up. If the tally is above the delta inside `nano::election::have_quorum ()` it returns true and the block is considered confirmed. `confirm_ack` messages can either contain the whole block or a hash (vote by hash). `confirm_req` message header as well as `confirm_ack` indicate what the type of the contents is in the header, either `not_a_block` which means dealing with block hashes or the block type. `nano/node/common.cpp` contains these messages (among others) and (de)serializing functions.\n\n### voting\nThe vote generator `nano::vote_generator::vote_generator` is responsible for collecting hashes that need a vote generated, combining them into a single `vote by hash` message, signing the package with the representative key and publishing the votes to the network. A maximum of `nano::network::confirm_ack_hashes_max` hashes can be combined into a single vote `confirm_ack` message, this provides a decent tradeoff between optimizing vote signatures and reducing bandwidth. While the process is running it waits for `config.vote_generator_delay` time in order to pack more hashes into a single vote message. If there are more than `config.vote_generator_threshold` after waiting then it will wait for one additional `config.vote_generator_delay` before broadcasting the message. This allows for fast vote publishing at lower rates while enabling more hashes to be combined together at higher rates.\n\n### vote_processor\nVotes are signed by the representative and the vote processor schedules checking these votes through the `signature_checker` inside `nano::vote_processor::verify_votes ()`. Once a vote signature has been verified, the hashes within the vote packet are passed to active_elections where they are either added to an active election or added to the inactive votes cache if an election does not exist.\n\n### active_transactions\nThe active transactions class handles election management and prioritization. When a block is processed and `nano::active_transactions::insert` called, a new election is started for the block hash if one does not already exist. In addition to starting elections there is a 500ms `request_loop` that handles election management. This process assists with moving elections through the different transition states as well as moving elections to a prioritized status if there is a backlog of elections. During the requst loop the current network difficulty is updated through `update_active_multiplier` which takes the top `prioritized_cutoff` number of active elections that have not been confirmed and samples their difficulty multiplier.\n\nFinally, the active transactions class also handles frontiers that have not been confirmed. Most commonly this is from bootstrapping, where the frontier of an account is added to the active elections and vote requests are sent to other nodes to confirm the frontier and thereby the rest of the account and ancestors through confirmation height processing.\n\n### confirmation_solicitor\nDuring the `request_loop` of the active transactions process, any election that is in the `active` state for more than 5 seconds will request votes from Principle Representative nodes that it has not seen a vote from yet. These requests are added to the `confirmation_solicitor` which aggregates the hashes up to `nano::network::confirm_req_hashes_max` into a single `confirm_req` message and publishes it to select PR nodes that have not voted. This helps fill any gaps in network communication failures where a vote may have been dropped which helps reach quorum on the highest priority elections.\n\n### request_aggregator\nThe request aggregator is responsible for collecting vote requests `confirm_req` messages from other nodes and finding the optimal responses. A local vote cache is used for recently generated votes, if the block hash in the request exists in the cache then a cached vote is returned, if the hash does not exist then the hash is added to the vote generator and a new vote is generated and published to the requesting node. The request aggregator also handles publishing forks if the request is for a competing fork. If the local node has a different winning hash it will publish a vote for the winning hash instead of the requested hash in addition to sending the requesting node the winning block as well.\n\n### election\nAn election is created when a new block is processed. The primary purpose of the election class is to tally the vote weight and ensure consensus between any competing forks. In order to efficiently move an election through the process it can have several states. Initially `passive` where it is waiting for votes from other nodes, then after 5 seconds if it has not been confirmed it will transition to `active` where vote requests to other nodes are made. After `active_request_count_min` rounds of requesting votes are complete if the election is still not confirmed it moves to `broadcasting` where it will publish the block to PR nodes that have not voted in an attempt to ensure the block has been propagated throughout the network. Under low load the `active` and `broadcasting` states are rarely used as all elections are complete within the `passive` window.\n\nEvery vote that is added to the election triggers a check for whether quorum has been reached on the election. Quorum requires that the winning hash has `node.online_reps.delta` more weight than any competing forks. If quorum is reached the election is marked confirmed, transitions to the `confirmed` state and is added to the confirmation height procesor which updates the ledger.\n\nAfter an election is confirmed it can stay in the active elections container up to `confirmed_duration_factor` in order to continue to process votes and republish votes to other nodes, after which is it is removed.\n\nIf an election lasts longer than 5 minutes and has not been confirmed it is transitioned to `expired_unconfirmed` and removed from the queue. This most often happens during high saturation when the active elections container reaches capacity.\n\n### continuous backlog population\n\nBacklog population is a process in which a node scans all accounts in its ledger, with or without confirmed blocks, and forwards (activates) the accounts which do not have all their blocks confirmed to the election scheduler for prioritization and eventual queuing in the proper bucket. It is necessary to do this periodically because the amount of space in each bucket is limited, and the number of accounts needing confirmations can be much higher than that (especially during bootstrap or network spam attack). \n\nContinuous backlog population changes the ledger scan interval from every 5 minutes to constant, with population rate & frequency controlled by `backlog_scan_batch_size` and `backlog_scan_frequency`.\n\nSee [here](https://github.com/nanocurrency/nano-node/pull/3999) for more details.\n\n### optimistic elections\n\nInstead of confirming every block in every account-chain one-by-one, the optimistic scheduler randomly samples accounts with unconfirmed blocks and activates an election for the account's head block (the latest _unconfirmed_ block in the account-chain). Once the head block is confirmed, all previous dependent blocks (within the account-chain _and_ in other dependent account-chains; i.e. cross-chain) are considered confirmed. The number of optimistic elections is limited, so it doesn't replace or impact the default election scheduling behavior.\n\nSee [here](https://github.com/nanocurrency/nano-node/pull/4111) for more details.\n\n### Confirmation height processor\nWhen a block is confirmed `void nano::node::process_confirmed ()` the block is added to the confirmation height processor. This begins the process of cementing it and all of its dependents, once this occurs these blocks can never be rolled back. There are 2 confirmation height algorithms bounded and unbounded. Originally only the unbounded one existed, this would store the block hash for the original block confirmed, all its previous blocks, and recurse the bottom most receive block to the source and repeat the process. If this hit something like the binance chain or (any long chain) it could use a lot of memory (unbounded amount). So this brought about the bounded confirmation height processor algorithm which starts at the very bottom of the account chains but does the same recursion when a receive block is hit. This limits the amount of block hashes needing to be stored in memory to be able to cement the bottom most blocks. Checkpoints are used if there are a lot of accounts which need to be traversed to reach which exceeds the maximum amount of memory . It does mean in certain cases the same iteration will need to be done more than once but this should be a rare case only during initial cementing. \n\nOnce the uncemented count (block count – cemented count) is less than 16K the unbounded processor is used. As mentioned above this instead starts from the top (original confirmed block) and works downwards and saves all the blocks hit (not just hash) which means they don’t need to be re-read during writing later. This does use a lot more memory though which is why this is limited to a certain number of blocks, once the unbounded cutoff is exceeded the bounded processor resumes. \n\nBoth algorithms operate with a read transaction first which reduces write lock held time as it can do a lot of iterating. This does mean that there can be some inconsistency by the time the writing is done, but this shouldn’t be an issue because once a block is confirmed by the network it will stay confirmed by `debug_assert` checks are added to catch any programming mistakes. While it is more effort to maintain 2 algorithms the unbounded one largely existed before so it made sense to re-use it, given the performance improvements in almost cemented ledgers.\n\n### Frontiers confirmation\n`nano/node/frontiers_confirmation.cpp` contains code which starts at the beginning of the accounts database (`nano::blockstore_partial::accounts_begin`) and iterates in ascending order and prioritises accounts based on the number of uncemented blocks (stores up to 100k) and requests confirmation for a limited number of these accounts. When the cemented count is above the hardcoded bootstrap weights this is limited to the number of optimistic elections which is 50 in this case so it is expected to be quite slow in this case. Accounts in wallets are also checked.\n\n---\n\n## Telemetry\nnano/node/telemetry.cpp contains the logic for telemetry processing. This sets up an ongoing telemetry request round (every 60 seconds on the live network) where a telemetry_req message is sent to every peer. There is an `alarm` timeout of about 10 seconds in which we require the response (telemetry_ack) to be received otherwise it is rejected. Any calls to get_metrics_* return a cached result. To add a new definition to the telemetry_ack message this can be used as a guide which added the `active_multiplier`: https://github.com/nanocurrency/nano-node/pull/2728\n`telemetry_ack` messages are signed and are backwards compatible with older nodes (from v22 onwards). Those nodes will verify the whole message including any extra unknown data which is appended at the end is just ignored. To prevent ddosing by `telemetry_req` messages, nodes ignore messages received within that 60second (on live) boundary. This is done in `void nano::bootstrap_server::receive_header_action ()`\n\n---\n\n## Stats\n\n### Counters\nThe `stats` object is used to keep a count of events that have happened, this is a useful idiom for checking values in tests and is aggregated in the stats->counts RPC. There are main stat types and then details for that type. A simple example of adding new details and incrementing the stats can be seen here: https://github.com/nanocurrency/nano-node/pull/2515 Adding a type for a stat is a similar procedure just using the `nano::stat::type` enumerator.\n\n### Objects\nMost classes which have a member variable of container of multiple items (map, vector, list etc..) should have a function with a prototype of:\n`std::unique_ptr collect_container_info (my_class & my_class, std::string const & name);`\nAnd then call this in an owning object which should itself be called recursively until it reaches the `node` object `collect_container_info`. They are typically not made as part of the class itself because it’s a very specialised function which is only called as part of the stats->object RPC, like so:\n`{\"action\":\"stats\",\"type\":\"objects\"}`\n\n---\n\n## Pruning\nPruning occurs periodically inside `nano::node::ongoing_ledger_pruning ()`. Pruning currently requires a full ledger to be bootstrapped and when an account frontier is confirmed it can then be pruned. The hashes of the pruned blocks are put into the pruned database so that we know to ignore any of these old blocks should the node bootstrap them again. Pending blocks cannot be pruned currently.\n\n---\n\n## Config files\nTOML config files are used, previously we used json files but TOML config files have the benefit of providing comments inside. There are no versions or upgrades done here, instead any defaults not explicitly overridden in the toml file get updated implicitly. There are few config files:\n\n### config-node.toml\nThis is actually called `daemonconfig.cpp` in the code base, but it wraps a `node_config` object.\n\n### Other config files \n`config-rpc.toml` & `config-wallet.toml` contain settings which can be modified by the user to override the defaults. The most common ones are enabling rpc/websocket & rocksdb.\n\nThe `nano/node/node_rpc_config.cpp` are the rpc settings for the node.\n\n---\n\n## Key resources\n\n**nanodb-specification & protocol repositories**\n\nThere are 2 repositories which use kaitai specifications which should be updated (normally near the end of the release) if there are any changes to the https://github.com/nanocurrency/nanodb-specification or https://github.com/nanocurrency/protocol message\n\n**nano-docs**\n\nAll RPC/CLI changes should have a documentation update specifying the version that they work. There is a documentation label in the nano-node repository which is useful as a reminder that they should be added, documentation updates are often overlooked.\n\n**nano.community**\n\nA great community built resource for developers is https://nano.community/getting-started-devs/getting-started where broad details of the design are outlined along with code-level insights.\n\n---\n \n## Other notes\n\n**All threads should have a name set**\n\nAn easy example to follow is https://github.com/nanocurrency/nano-node/pull/2987/files This is so that debuggers/viewers which show threads can pick up the name to make it easier to navigate. It’s been known not to work in the Visual Studio Concurrency visualizer.\n\n**(de)serializing**\n\nWhere possible we try and store primitives in big-endian. As most systems are little-endian this means using `boost::endian::native_to_big` on primitives when serializing and `boost::endian::big_to_native` when deserializing.\n\n**Signature checker**\n\nThis is used by both blocks/votes and creates (total threads / 2) to perform signature verification of set batches; this is the biggest compute resource. Being able to lower this would be very beneficial, such as out of process sig verification and/or via GPU.\n\n**peers**\n\nPeers are written to disk periodically. This was added in https://github.com/nanocurrency/nano-node/pull/1608 \nIf the node has not been run in a long time (1 week), the peers list is cleared and the preconfigured peers list is used, this was added in https://github.com/nanocurrency/nano-node/pull/2506\n\n\n- Do not use the `node` object or include `node.hpp` in new core source files unless necessary, instead include the dependencies that it requires. We are still in the process of removing this idiom from other files because it adds circular dependencies, potentially ordering bugs and increases the build time.\n- Take care not to have nested `tx_begin_write ()`, it is quite easy to forget about this in tests, it will just cause a deadlock. To solve it, limit the scope:\n\t- Pass `std::shared_ptr` parameters by reference where possible, https://github.com/nanocurrency/nano-node/pull/3029\n\t- Be cautious with random DB reads, they are much slower than sequential reads. This PR sped up the delegators by a factor of 100 RPC by removing the block_get call needed in the loop. https://github.com/nanocurrency/nano-node/pull/2283\n\t```\n\t{ // Limit scope\n\tauto transaction = store->tx_begin_write ();\n\tblock_put (store.tx_begin_write (), block);\n\t}\n\t…\n\tauto transaction = store->tx_begin_write ();\n\t```\n\tor if it’s a single write can create a temporary just for that use:\n\t`block_put (store.tx_begin_write (), block);`\n\tBe cautious with callback lifetimes with asynchronous callbacks, such as the worker, alarm and asio. The following issue was because of them:\n\t```\n\tint x = 4;\n\tworker.push_back ([&x]() { \n\t std::cout << x; // x might not be valid by the time this is called, should have been a copy.\n\t});\n\t```\n \n- Currently (as of V25) using C++20 with Boost 1.81.\n- There are known exceptions triggered when `consume_future` is called do not be alarmed when seeing this.\n\n## Areas of future improvement\n\n- A lot of tests still use legacy blocks, any new ones should use state blocks.\n- Minimise heap allocation. This can lead to fragmentation which affects long running processes.\n- `slow_test` is not run as part of CI\n\n## FAQs\n\n- Where are blocks added to the ledger? `nano::ledger::process ()`\n\n- Where are rpc calls handled? `nano/node/json_handler.cpp`\n\n- Where is the genesis block created? `nano::blockstore_partial::init ()` \n\n- How to stop the node effectively? `rpc->stop ();`\n\n- How to use RocksDB in tests? Set the environment variable: `TEST_USE_ROCKSDB=1`\n" }, { "path": "docs/glossary.md", "content": "title: Glossary\ndescription: A glossary of common terms used within the nano documentation and network\n\n# Glossary\n\n#### account\nRefers to an address (starts with `xrb_` or `nano_` which are interchangeable) that you control the private keys of. An address is a reinterpretation of the 256-bit public key using BASE32 encoding and a checksum. Previously supported `xrb-` or `nano-` prefixes are deprecated.\n\n#### active transaction\nA newly downloaded block to the node which enters into the voting process.\n\n#### ad hoc accounts\nAccounts not derived from a private seed which can be held in the node wallet through the wallet ID. These accounts are only recommended for use with advanced systems.\n\n#### announcement rounds\nA repeating half-second cycle on the node during which votes are collected for active transactions in attempt to reach quorum.\n\n#### Block\nA single Nano transaction. All new transactions (e.g. sends, receives, representative changes, etc) on the Nano Protocol are communicated via state blocks (since node V11). The account's entire state, including the balance after each transaction, is recorded in each block. Transaction amounts are interpreted as the difference in balance between consecutive blocks. Before V11, each transaction type (open, send, receive, change) had its own legacy block type.\n\n#### block hash\nA 64 character, uppercase hexadecimal string (0-9A-F) value representing a unique block on an account.\n\n#### Block height\nA local integer value that represents the order of a block in an account chain. For example, the 15th block in an account would have a block height of 15. Related to (but different from) [confirmation height](#confirmation-height).\n\n#### Block Lattice\nThe Block Lattice is a data-structure in which individual accounts control their own blockchain. This allows transactions to be added quickly without conflict and sent to the network for confirmation.\n\n#### Blocks Per Second (BPS)\nThe transmission rate of [unconfirmed](#confirmation) blocks (transactions) on the network. \n\n#### bootstrap network\nA sub-network established between peers via Transmission Control Protocol (TCP) for managing bulk transmission of blocks. This is used on initial bootstrapping of peers and when out-of-sync peers attempt to fill large gaps in their ledgers. This is available within all Nano networks (main, beta and test networks).\n\n#### bootstrapping\nDuring initial sync, the nano\\_node requests old transactions to independently verify and populate its local ledger database. Bootstrapping will also occur when the nano\\_node becomes out of sync with the network.\n\n#### burn\nWhen a 'burn' takes place, funds are sent to a specifc address that no one can access. Because no one can ever access funds sent to a burn address, it reduces the [circulating supply](#circulating-supply).\n\n#### circulating supply\n133,248,297.920938463463374607431768211455 Nano. This is the supply that resulted after [burns](#burn) were made from the [genesis](#genesis) account, landing account and faucet account, following original distribution. Actual circulating supply is lower due to lost keys and sends to burn accounts. The original supply minus any amounts sent to the burn account can be found using the [available_supply](/commands/rpc-protocol/#available_supply) RPC.\n\n#### Cementing\nWhen a specific node marks a [confirmed](#confirmation) transaction as locally irreversible by setting the [account's](#account) [confirmation height](#confirmation-height) (in the node database) to the now higher [block height](#block-height) of the confirmed transaction. Cementing is a node-level operation.\n\n#### Confirmation\nWhen a block (transaction) gathers enough votes from the network to pass [quorum](#quorum). Note that confirmed sends are irreversible (i.e. fully-settled), but the receiver must publish a corresponding receive block before they will be able to spend the [receivable](#receivable) funds. Confirmation is a network-level decision.\n\n#### Confirmation Height\nA number stored in the local node database that represents the highest (most recent) [confirmed](#confirmation) block in an account chain. Related to (but different from) [block height](#block-height).\n\n#### Confirmations Per Second (CPS)\nThe rate of [confirmed](#confirmation) [blocks](#blocks).\n\n#### election\n\n#### frontier\nThe most recent block added to the account chain. Also called the head block. Can be either confirmed or unconfirmed.\n\n#### genesis\nThe first [account](#account) to be created, containing the maximum amount of Nano to ever exist. From here the funds were sent to other wallets; for distribution or to be [burned](#burn).\n\n#### head block\nSee [frontier](#frontier).\n\n#### inbound send\nA block with funds being transferred to an [account](#account) owned by a [wallet](#wallet) on your node.\n\n#### legacy blocks\nBlocks on an account chain before the first v1 block (which is often the v1 epoch block but can be other types). The first v1 block and all subsequent blocks are stateful blocks.\n\n#### live network\nA sub-network established between peers via Transmission Control Protocol (TCP) for communicating newly published blocks, votes and other non-bootstrap related traffic. This is available within all Nano networks (main, beta and test networks). In versions prior to V19, this was done via User Datagram Protocol (UDP). UDP was retained as a fallback for peer connection for versions 19 and 20. In V21 it was deprecated, and in V25 it was fully removed.\n\n#### node version\nThe version used to identify a unique release build of the node. Each node version is tied to a single [protocol version](#protocol-version), but they are updated independently.\n\n#### online voting weight\nAlso called online stake, it is a trended value. The node samples online representative weights every 5 minutes across a rolling 2 week period. The online voting weight value is the median of those samples.\n\n#### peers\nNodes connected over the public internet to share Nano network data.\n\n#### pending\nSee [receivable](#receivable)\n\n#### Private Key\nSee [wallet](#wallet).\n\n#### Public Key\nA public key is derived from a [private key](#private-key) using the ED25519 elliptic curve algorithm. An address is a representation of the public key, see [account](#account) for more info.\n\n#### Open Representative Voting (ORV)\nA consensus mechanism unique to Nano which involves accounts delegating their balance as [voting weight](#voting-weight) to [Representatives](#representative). The Representatives [vote](#voting) themselves on the validity of transactions published to the network using the voting weight delegated to them. These votes are shared with their directly connected peers and they also rebroadcast votes seen from [Principal Representatives](#principal-representative). Votes are tallied and once [quorum](#quorum) is reached on a published block, it is considered confirmed by the network.\n\n#### Proof-of-Work (PoW)\nA Proof-of-Work is a piece of data which satisfies certain requirements and is difficult (costly, time-consuming) to produce, but easy for others to verify. In some systems this data is a central part of the security model used to protect against double-spends and other types of attacks, but with Nano it is only used to increase economic costs of spamming the network.\n\n#### Principal Representative\nA Nano account with >= 0.1% of the [online voting weight](#online-voting-weight) delegated to it. When configured on a node which is voting, the votes it produces will be rebroadcasted by other nodes to who receive them, helping the network reach consensus more quickly.\n\n#### protocol version\nThe version used to identify the set of protocol rules nodes are required to follow in order to properly communicate with peers. Nodes running older protocol versions are periodically de-peered on the network to keep communication efficient - see [Active Releases](/releases/node-releases/#active-releases) and [Inactive Releases](/releases/node-releases/#inactive-releases) for the latest versions allowed to peer with one another.\n\n#### qualified root\nThe concatenation of the root and previous attributes of a block. For the first block on an account, this would be is the account public key following by 32 zero bytes. For the second or higher block on an account, this would be the previous field repeated twice (root + previous, where root == previous).\n\n#### quorum\nWhen the delta between the two successive blocks of a root is > 67% of the online voting weight.\n\n#### receivable\nA transaction state where a block sending funds was published and confirmed by the network, but a matching block receiving those funds has not yet been confirmed.\n\n#### Representative\nA Nano account with > 0 voting weight, but < 0.1% of the [online voting weight](#online-voting-weight), delegated to it. Unlike [Principal Representatives](#principal-representative), when configured on a node which is voting, the votes it produces and sends to directly connected peers won't be rebroadcasted by those peers.\n\n#### root\nIf the block is the first block on the account, the root is the account public key. Otherwise it is the previous hash included in the block. The root of a block can never be zero.\n\n#### seed\nA 256-bit random value usually represented to the user as a 64 character hexidecimal (0-9 and A-F) value. Private keys are derived from a seed.\n\n#### Transactions Per Second (TPS)\nHistorically, TPS was a per-node measurement that represented a node's perception of the rate of transactions on the network ([BPS](#blocks-per-second-bps)). This measurement was found to be inaccurate due to peering and propagation differences between nodes, so [CPS](#confirmations-per-second-cps) is now the preferred term for describing overall Nano network scalability. It's also important to note that while Nano sends do not require a corresponding receive to be [confirmed](#confirmation), a receive block must be confirmed before received funds can be sent again (see [receivable](#receivable)).\n\n#### unchecked (blocks)\nBlocks (transactions) that have been downloaded but not yet processed by the Nano node. The node software downloads all blocks from other nodes as unchecked, processes them and adds to block count, confirms the [frontier](#frontier) blocks for each account, and then marks them as [cemented](#cementing).\n\n#### unopened account\nAn account address that does not have a first block on it (which must be a block to receive Nano sent from another account, cannot be a block only changing the Representative).\n\n#### unpocketed\nSee [receivable](#receivable).\n\n#### vote-by-hash\nAllows representatives to only include the hash of a block in each vote to save bandwidth. Before vote-by-hash was activated the entire block contents were required.\n\n#### voting\nEach node configured with a [Representative](#representative) votes on every block by appending their Representative signature and a sequence number to the hash. These will be sent out to directly connected peers and if the vote originates from a [Principal Representative](#principal-representative), it will subsequently be rebroadcasted by nodes to their peers.\n\n#### voting weight\nThe amount of weight delegated to a [Representative](#representative).\n\n#### wallet\nA wallet is an organizational object in a nano\\_node that holds a single seed from which multiple accounts are deterministically derived via a 32-bit unsigned integer index starting at 0. Private keys are derived from the seed and index as follows: (`||` means concatenation; `blake2b` is a [highly optimized cryptographic hash function](/protocol-design/signing-hashing-and-key-derivation/#hashing-algorithm-blake2))\n\n$$\nk_{private} = blake2b(\\text{seed} || \\text{index})\n$$\n\n#### WALLET_ID\nA 256-bit random value name/identifier for a specific wallet in the local nano\\_node database. The WALLET\\_ID **is not** stored anywhere in the network and is only used in the local nano\\_node. Even though a WALLET\\_ID looks identical to a seed, do not confuse the WALLET\\_ID with a seed; funds cannot be restored with a WALLET\\_ID. Do not backup the WALLET\\_ID as a means to backup funds.\n\n#### work peers\nNode peers which are configured to generate work for transactions at the originating nodes request.\n" }, { "path": "docs/index.md", "content": "---\r\ntitle: Home\r\ndescription: Explore the design, features, releases and other related resources for the nano protocol and node implementation.\r\nhide:\r\n - navigation\r\n - toc\r\n---\r\n\r\n# Nano Node and Protocol Documentation\r\nWelcome! 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:\r\n\r\n| Section | Details | Audience |\r\n| | | |\r\n|**[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|\r\n|**[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 |\r\n|**[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 |\r\n|**[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 |\r\n|**[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 |\r\n|**[Node Implementation](node-implementation/introduction.md)**| Details of the Nano Foundation managed node implementation of the protocol. | Developers |\r\n|**[Core Development](core-development/overview.md)**| Interested in contributing to the core Nano code or protocol? Here's how to get started. | Developers |\r\n|**[Commands](commands/rpc-protocol.md)**| Explore an exhaustive list of interaction methods for the node via RPC and CLI. | Node operators, developers |\r\n|**[Releases](releases/node-releases.md)**| Review past node releases and get details about the features coming soon in new releases. | Everyone |\r\n|**[Glossary](glossary.md)**| Commonly used terms throughout the documentation and Nano ecosystem. | Everyone |\r\n\r\n**Join the Community**\r\n\r\nIf you are looking for other details about Nano, links to wallets, discussions about the network and more, check out our community:\r\n\r\n--8<-- \"community-links.md\"\r\n\r\n[Change cookie settings](#__consent)\r\n" }, { "path": "docs/integration-guides/advanced.md", "content": "title: Advanced Integration Guide\ndescription: More advanced guides to integrating with nano including cold wallets, private key management and more\n\n# Advanced Integrations\n\n## Cold Wallets\n\nWhen security of funds is critical, it is a best practice to split your balance between multiple wallets:\n\n1. One or more **hot wallets** to handle daily user deposits/withdraws.\n2. One or more **cold wallets** to securely store Nano in an offline environment.\n\n!!! warning \"Important\"\n\tA cold wallet manages private keys that have **never** been on a network-enabled computer.\n\nThis guide extends the concepts covered in [External Private Key Management](/integration-guides/key-management/). It is advised that you read that section before continuing.\n\n!!! note\n\tOperations done on the hot, online, insecure computer will be prefaced with `(HOT)`. Operations done on the cold, offline, secure computer will be prefaced with `(COLD)`.\n\t\n\tBoth the hot and cold computers need to have the nano\\_node software installed. The hot nano\\_node needs to be synced with the network; the cold nano\\_node by definition should not be synced as it **never connects to the internet**.\n\n---\n\n!!! info \"Cold Wallet Workflow\"\n\tThe typical work flow for a cold wallet is as follows:\n\n\t1. `(HOT)` Gather account and transaction data.\n\t1. Transfer this data using an offline method (e.g. via USB stick) to the `(COLD)` secure offline computer.\n\t1. `(COLD)` Verify Head Block hash.\n\t1. `(COLD)` Generate and Sign new transaction data.\n\t1. Transfer the signed transaction back to the `(HOT)` insecure online-computer.\n\t1. `(HOT)` Publish the signed transaction to the Nano Network.\n\n\n
\n\n```mermaid\nsequenceDiagram\n participant Network\n participant HOT\n participant COLD\n HOT->>Network: Get Data\n Network->>HOT: Data Response\n HOT-->>COLD: Offline Transfer\n COLD-->>COLD: Verify\n COLD-->>COLD: Generate & Sign\n COLD-->>HOT: Return Signed\n HOT->>Network: Publish Signed\n Note over COLD,HOT: Cold/Hot Wallet transfers are done
offline using USB Stick or similar.\n```\n\n
\n\n---\n\n### Private Key Management\n\nThe process for external private key management in a cold wallet is very similar to external private key management for a hot wallet. The primary difference is that all signing commands (and thus information containing your private key) are isolated to a clean computer with no network connection.\n\n#### (HOT) Account Information\n\nGet account information by the [`account_info`](/commands/rpc-protocol#account_info) RPC Command:\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"account_info\",\n \"representative\": \"true\",\n \"account\": \"nano_3qb1qckpady6njewfotrdrcgakrgbfh7ytqfrd9r8txsx7d91b9pu6z1ixrg\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"frontier\": \"DC8EC06D1F32F97BD69BF59E3297563BD23779F72176A4FF553CFF52309C337E\",\n \"open_block\": \"2E1F5AD4BD2C840FD9DC3929ECE9EE6D0B4A8C870E45EDA11048DE91EC409165\",\n \"representative_block\": \"DC8EC06D1F32F97BD69BF59E3297563BD23779F72176A4FF553CFF52309C337E\",\n \"balance\": \"8900000000000000000000000\",\n \"modified_timestamp\": \"1524812177\",\n \"block_count\": \"105\",\n \"representative\": \"nano_3rropjiqfxpmrrkooej4qtmm1pueu36f9ghinpho4esfdor8785a455d16nf\"\n}\n```\n\n---\n\n#### (HOT) Balance Validation (Part 1)\n\nWe should always assume the `(HOT)` computer has been compromised, so cannot trust the balance returned by [`account_info`](/commands/rpc-protocol#account_info). We must obtain the headblock's transaction data and independently confirm the block's hash on our `(COLD)` offline computer. On the `(HOT)` online computer, this information can be obtained by the [`block_info`](/commands/rpc-protocol#block_info) RPC Command.\n\n##### Request Format\n\n```bash\ncurl -d '{\n \"action\": \"block_info\",\n \"hash\": \"{{HEADBLOCK}}\"\n}' http://127.0.0.1:7076\n```\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"block_info\",\n \"hash\": \"DC8EC06D1F32F97BD69BF59E3297563BD23779F72176A4FF553CFF52309C337E\"\n}' http://127.0.0.1:7076\n```\n\n###### Success Response\n\n```json\n{\n \"block_account\": \"nano_3qb1qckpady6njewfotrdrcgakrgbfh7ytqfrd9r8txsx7d91b9pu6z1ixrg\",\n \"amount\": \"100000000000000000000000\",\n \"balance\": \"8900000000000000000000000\",\n \"height\": \"105\",\n \"local_timestamp\": \"0\",\n \"contents\": \"{\\n\n \\\"type\\\": \\\"state\\\",\\n\n \\\"account\\\": \\\"nano_3qb1qckpady6njewfotrdrcgakrgbfh7ytqfrd9r8txsx7d91b9pu6z1ixrg\\\",\\n\n \\\"previous\\\": \\\"829C33C4E1F41F24F50AB6AF8D0893F484E7078F0FA05F8F56CB69223E8EEE77\\\",\\n\n \\\"representative\\\": \\\"nano_3rropjiqfxpmrrkooej4qtmm1pueu36f9ghinpho4esfdor8785a455d16nf\\\",\\n\n \\\"balance\\\": \\\"8900000000000000000000000\\\",\\n\n \\\"link\\\": \\\"616349D5A5EBA49A73324EF29044B65E13644EC182FFC1ACA4371F897EFF22AA\\\",\\n\n \\\"link_as_account\\\": \\\"nano_1rd5b9ctdtx6mbsm6mqkk34deqimej9e51qzr8pcafrzj7zhyaockuye93sk\\\",\\n\n \\\"signature\\\": \\\"5058A5A1D371CE367D88DB232D398B33DF15FF95D84206986848F4165FFD9FB009B99D9DC6E90D2A3D96C639C7772497C6D6FFB8A67143AE9BB07DC49EB72401\\\",\\n\n \\\"work\\\": \\\"5621a5a58ef8964a\\\"\\n\n }\\n\"\n}\n```\n\n!!! info\n\tBelow are a few important points to remember:\n\n\t* Contents are returned as a stringified JSON object.\n\t* The type of the block is `\"state\"`. This guide only covers on how to trustlessly process `\"state\"` blocks on an offline computer.\n\nTransfer the response over to the `(COLD)` computer.\n\n---\n\n#### (COLD) Balance Validation (Part 2)\n\nOn the `(COLD)` computer, we need to verify the block hash using the [`block_hash`](/commands/rpc-protocol#block_hash) RPC Command.. This allows us to create a safe transaction referencing the reported head block's balance.\n\n##### Request Format\n\n```bash\ncurl -d '{\n \"action\": \"block_hash\",\n \"block\": \"\"\n}' http://127.0.0.1:7076\n```\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"block_hash\", \"block\": \"{\\n\n \\\"type\\\": \\\"state\\\",\\n\n \\\"account\\\": \\\"nano_3qb1qckpady6njewfotrdrcgakrgbfh7ytqfrd9r8txsx7d91b9pu6z1ixrg\\\",\\n\n \\\"previous\\\": \\\"829C33C4E1F41F24F50AB6AF8D0893F484E7078F0FA05F8F56CB69223E8EEE77\\\",\\n\n \\\"representative\\\": \\\"nano_3rropjiqfxpmrrkooej4qtmm1pueu36f9ghinpho4esfdor8785a455d16nf\\\",\\n\n \\\"balance\\\": \\\"8900000000000000000000000\\\",\\n\n \\\"link\\\": \\\"616349D5A5EBA49A73324EF29044B65E13644EC182FFC1ACA4371F897EFF22AA\\\",\\n\n \\\"link_as_account\\\": \\\"nano_1rd5b9ctdtx6mbsm6mqkk34deqimej9e51qzr8pcafrzj7zhyaockuye93sk\\\",\\n\n \\\"signature\\\": \\\"5058A5A1D371CE367D88DB232D398B33DF15FF95D84206986848F4165FFD9FB009B99D9DC6E90D2A3D96C639C7772497C6D6FFB8A67143AE9BB07DC49EB72401\\\",\\n\n \\\"work\\\": \\\"5621a5a58ef8964a\\\"\\n\n }\\n\"\n}' http://127.0.0.1:7076\n```\n\n###### Success Response\n\n```json\n{ \n \"hash\": \"DC8EC06D1F32F97BD69BF59E3297563BD23779F72176A4FF553CFF52309C337E\"\n}\n```\n\nUsing the responded hash on the `(COLD)` computer guarentees that the transaction we are about to create on the `(COLD)` computer will have a safe, expected outcome.\n\n!!! warning \"Important\"\n\tLets consider the following scenarios where malicious software on the `(HOT)` computer modifies data:\n\n\t* You are creating a send transaction.\n\t* Malicious software alters the `balance` field of the head block to be lower than it actually is in an attempt to get you to send too much Nano to the destination address.\n\t* This alters the block's hash, but the malicious software could report the honest headblock's hash.\n\n\tBy independently computing the headblock's hash on the `(COLD)` computer, the generated transaction would be rejected by the network since the `previous` field references a non-existent block which is certainly not the headblock of your account.\n\nUse the responded hash for the `previous` field in your new transaction. When computing final account balance, compute it relative to the `balance` field of the headblock on the `(COLD)` computer. Complete the rest of the [block creation as described in section External Private Key Management](/integration-guides/key-management/#send-transaction).\n\nOnce the block is created and signed on the `(COLD)` computer, transfer the contents over to the `(HOT)` computer. From the `(HOT)` computer, run the [`process`](/commands/rpc-protocol#process) RPC command to broadcast the signed transaction to the network.\n\n---\n\n## HTTP callback\n\n!!! info \"WebSockets recommended\"\n The node supports [WebSockets](websockets.md) and these are recommended over the HTTP callbacks whenever possible.\n\nSend JSON POST requests with every confirmed block to callback server configured for the node.\n\n--8<-- \"warning-multiple-confirmation-notifications.md\"\n\n**Configuration**\n\nFor details on configuring the HTTP callback within a node, see the [HTTP callback section of Running a Node Configuration](/running-a-node/configuration#http-callback).\n\n**Example Callback**\n\n```json\n{ \n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\", \n \"hash\": \"B785D56473DE6330AC9A2071F19BD44BCAF1DE5C200A826B4BBCC85E588620FB\", \n \"block\": \"{\\n \n \\\"type\\\": \\\"state\\\",\\n\n \\\"account\\\": \\\"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\\\",\\n \n \\\"previous\\\": \\\"82D68AE43E3E04CBBF9ED150999A347C2ABBE74B38D6E506C18DF7B1994E06C2\\\",\\n \n \\\"representative\\\": \\\"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\\\",\\n \n \\\"balance\\\": \\\"5256159500000000000000000000000000000\\\",\\n \n \\\"link\\\": \\\"8B95FEB05496327471F4729F0B0919E1994F9116FD213F44C76F696B7ECD386A\\\",\\n \n \\\"link_as_account\\\": \\\"nano_34woztr7b7jkgjrzawnz3e6jmresbyajfzb39x4eguubffzetg5c96f3s16p\\\",\\n \n \\\"signature\\\": \\\"FBE5CC5491B54FE9CD8C48312A7A6D3945835FD97F4526571E9BED50E407A27ED8FB0E4AA0BF67E2831B8DB32A74E686A62BF4EC162E8FBB6E665196135C050B\\\",\\n \n \\\"work\\\": \\\"824ca671ce7067ac\\\"\\n \n }\\n\", \n \"amount\": \"2500000000000000000000000000000\" \n}\n```\n\nSend state blocks have special fields \"is_send\" & \"subtype\" \n```json\n{ \n \"account\": \"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\", \n \"hash\": \"82D68AE43E3E04CBBF9ED150999A347C2ABBE74B38D6E506C18DF7B1994E06C2\", \n \"block\": \"{\\n \n \\\"type\\\": \\\"state\\\",\\n\n \\\"account\\\": \\\"nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est\\\",\\n \n \\\"previous\\\": \\\"BE716FE4E21E0DC923ED67543601090A17547474CBA6D6F4B3FD6C113775860F\\\",\\n \n \\\"representative\\\": \\\"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\\\",\\n \n \\\"balance\\\": \\\"5256157000000000000000000000000000000\\\",\\n \n \\\"link\\\": \\\"5D1AA8A45F8736519D707FCB375976A7F9AF795091021D7E9C7548D6F45DD8D5\\\",\\n \n \\\"link_as_account\\\": \\\"nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z\\\",\\n \n \\\"signature\\\": \\\"5AF10D3DDD0E3D7A0EF18670560D194C35A519943150650BBBE0CBDB2A47A1E41817DA69112F996A9898E11F1D79EF51C041BD57C1686B81E7F9DFCCFFBAB000\\\",\\n \n \\\"work\\\": \\\"13ae0ea3e2af9004\\\"\\n \n }\\n\", \n \"amount\": \"90000000000000000000000000000000000\", \n \"is_send\": \"true\", \n \"subtype\": \"send\" \n}\n``` \n\n\n!!! warning\n It is recommended to fetch the block using the hash provided in the callback rather than trust this data is valid, and check that data instead, since a malicious 3rd party can also make a fake callback request to your endpoint.\n\n---\n\n## Running Nano as a service\n\nThere are 3 different ways to enable RPC for the node:\n\n**In process**\n\n* `rpc.enable` = **true**\n* `rpc.child_process.enable` = **false** (default, V19.0+)\n\n**Child process** \n*V19.0+ only*\n\n* `rpc.enable` = **true**\n* `rpc.child_process.enable` = **true**\n* `rpc.child_process.rpc_path` = [path to nano_rpc]\n* `ipc.tcp.enable` = **true**\n* `ipc.tcp.port` = `process.ipc_port` of `config-rpc.toml`\n\n**Out of node process** \n*V19.0+ only*\n\n* `rpc.enable` = **false**\n* `rpc.child_process.enable` = **false**\n* `node.ipc.tcp.enable` = **true**\n* `node.ipc.tcp.port` == `process.ipc_port` of `config-rpc.toml`\n\nThe choice depends on the setup and security that you want. The easiest way is to use RPC *in_process* according to [configuration](/running-a-node/configuration)\n\n**Launch nano_node in test mode** \n\n ./nano_node --daemon --network=test\n\n**Check if RPC is enabled with curl (use different terminal or session)** \n\n```bash\ncurl -d '{\n \"action\": \"block_count\"\n}' http://127.0.0.1:7076\n```\n\n--8<-- \"docker-ipv6-tip.md\"\n\n**To stop node, use** \n\n```bash\ncurl -d '{\n \"action\": \"stop\"\n}' http://127.0.0.1:7076\n```\n\n**Launch nano_node as a service with systemd** \n\n sudo touch /etc/systemd/system/nano_node.service \n sudo chmod 664 /etc/systemd/system/nano_node.service \n sudo nano /etc/systemd/system/nano_node.service \n\n**Paste your specific user, group, path settings (example)** \n \n [Unit]\n Description=Nano node service\n After=network.target\n \n [Service]\n ExecStart=/path_to_nano_node/nano_node --daemon\n Restart=on-failure\n User=username\n Group=groupname\n\n [Install]\n WantedBy=multi-user.target\n\n**Start nano_node service**\n\n sudo service nano_node start\n\n**Enable at startup** \n\n sudo systemctl enable nano_node\n \n \n!!! tip\n To manage node, use [RPC commands](/commands/rpc-protocol) or [CLI](/commands/command-line-interface)\n\n### Known issues \n\n**Error initiating bootstrap ... Too many open files**\n\nThis issue has been seen on some versions of macOS and Linux. The node will detect when the file descriptor limit is considered too low and log a warning similar to:\n\n```\nWARNING: The file descriptor limit on this system may be too low (512) \nand should be increased to at least 16384.\n```\n\nTo resolve this on Linux increase max open files limit by editing `/etc/security/limits.conf` and adding or updating: \n```\n * soft nofile 65535 \n * hard nofile 65535 \n root soft nofile 65535 \n root hard nofile 65535 \n```\nThen restart session & `nano_node` service. Check changes with `ulimit -n`.\n\nFor macOS the version impacts the steps necessary, but some people had success with the recipe in [https://superuser.com/a/1171028](https://superuser.com/a/1171028).\n\n**Increasing max open file descriptors on a Droplet w/Ubuntu**\n\nAdd `session required pam_limits.so` to these two files:\n\n```\n/etc/pam.d/common-session\n/etc/pam.d/common-session-noninteractive\n```\n\nNext, edit\n`/etc/security/limits.conf`\n\n... and add the following lines:\n\n```\n* soft nofile 20000\n* hard nofile 30000\nroot hard nofile 16384\nroot soft nofile 16384\n```\n\nThe last two lines can be skipped if you're not running the node as root.\n\nLog out and back in or reboot and see if `ulimit -n` picked it up\n\nOn some systems, you may need to change systemd files, etc.\n\n**Docker**\n\nOnce the host is updated, pass `--ulimit nofile=16384:16384`\n" }, { "path": "docs/integration-guides/block-confirmation-tracking.md", "content": "title: Block Confirmation Tracking\ndescription: Guide detailing best practices for block confirmation tracking from the nano node\n\n# Block Confirmation Tracking\n\n!!! tip \"Guide based on node V19.0\"\n\tThe 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.\n\nA 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. \n\n!!! tip \"Notifications and fallback requests both recommended\"\n\tDue 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.\n\n### Receiving notifications of confirmation\n\nThe 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.\n\n**Setup process**\n\n1. Update your [WebSocket configuration](/running-a-node/configuration/#nodewebsocket)\n1. Connect to the WebSocket at the configured endpoint\n1. Send a [subscription request for all confirmations](/integration-guides/websockets#confirmations) including the ack option and validate the subscription request was successful\n1. Listen for block confirmation notifications from the WebSocket\n\nAs 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.\n\n--8<-- \"warning-multiple-confirmation-notifications.md\"\n\n### Requesting block confirmation status\n\nIn 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.\n\nIf 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:\n\n* 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).\n* If the block is not in active elections, it will start an election which should result in confirmation and related notifications.\n* If the block is already in active elections, it will not have an effect and confirmation should eventually occur along with related notifications.\n\nOnce [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.\n\n### Account frontier confirmation status\n\nFor 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.\n\n1. Call [account_info](/commands/rpc-protocol/#account_info) RPC to get current frontier hash\n1. Call [block_info](/commands/rpc-protocol#block_info) for the frontier hash and check if `confirmed` = `true`\n\nIf 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." }, { "path": "docs/integration-guides/build-options.md", "content": "title: Build Options\ndescription: Instructions for manually building the Nano node for a variety of operating systems\n\n# Build Options\n\n--8<-- \"warning-only-official-builds-supported.md\"\n\n## Official release builds\n \nThroughout the development cycle and after releases official builds of the node for Docker, Linux, macOS and Windows are generated and published for test, beta and main networks.\n\n=== \"Main network\"\n\n --8<-- \"current-build-links-main.md\"\n\n=== \"Test network\"\n\n --8<-- \"current-build-links-test.md\"\n\n=== \"Beta network\"\n\n --8<-- \"current-build-links-beta.md\"\n\n## Nano Directory\n\n### Contents\n\n--8<-- \"directory-contents.md\"\n\n### Locations\n\n=== \"Main network\"\n\n --8<-- \"directory-locations-main.md\"\n\n=== \"Test network\"\n\n --8<-- \"directory-locations-test.md\"\n\n=== \"Beta network\"\n\n --8<-- \"directory-locations-beta.md\"\n\n??? tip \"Moving directory locations\"\n Some users desire to change the blockchain download location. A solution is available for the no gui nano_node (see https://github.com/nanocurrency/nano-node/issues/79), but no concrete solution is available for the GUI client. However, a workaround can be acheived via the use of symbolic links. Below is a short tutorial for Windows builds:\n\n 1. Rename/delete the Nano directory in your `appdata` Local directory (if you haven't run the wallet yet, skip this step). This is necessary because the command to create a symbolic link in windows will fail if the the input directory already exists.\n 1. Decide on where you want to store the blockchain and create a symbolic link. The command is (in an administrative command-prompt): `mklink /d \"C:\\Users\\\\AppData\\Local\\Nano\\\" \"E:\\Some\\Other\\Directory\"`. This command creates a symbolic link for a directory (`/d`) that 'redirects' all requests for files/directories in the `Local\\Nano` directory to the `Other\\Directory`. This means that a file created in the input directory will actually be in the output directory (on the other disk).\n 1. Verify it works. Create a file in your Nano directory in your appdata, and you should see it appear in the directory you linked it to (and vice-versa). If you have old wallets or a partially-downloaded blockchain, copy them back into the local directory. Start the wallet.\n\n---\n\n## Requirements & setup\n\n--8<-- \"warning-unsupported-configuration.md\"\n\n!!! tip \"Alternate Windows setup\"\n Some users have trouble using the command line approach below for getting setup to build on Windows. An alternative setup is available further down for [Windows 10 & Visual Studio 2019](#windows-10-visual-studio-2019). Variations on these instructions with different versions of Windows, Visual Studio, Cmake, etc. may work as well, but may require adjustments.\n\n### Boost (before V25.0)\n\nIf you are building a version before V25.0, the node build commands further down include bootstrapping Boost, but [pre-built binaries](https://sourceforge.net/projects/boost/files/boost-binaries/) can be used for Windows as well, or you can optionally build from the downloaded source instead as follows:\n\n* Download [Boost 1.81+](https://www.boost.org/users/history/version_1_81_0.html)\n* Extract to \\[boost.src\\]\n* From inside [boost.src] run:\n\n=== \"*nix\"\n ```bash\n ./bootstrap.sh --with-libraries=context,coroutine,filesystem,log,program_options,system,thread\n ./b2 --prefix=[boost] --build-dir=[boost.build] link=static install\n ```\n\n=== \"macOS\"\n ```bash\n ./bootstrap.sh --with-libraries=context,coroutine,filesystem,log,program_options,system,thread\n ./b2 --prefix=[boost] --build-dir=[boost.build] link=static install\n ```\n\n=== \"Windows\"\n ```bash\n ./bootstrap.sh --with-libraries=context,coroutine,filesystem,log,program_options,system,thread\n ./b2 --prefix=[boost] --build-dir=[boost.build] address-model=64 link=static install\n ```\n\nIf using this option, remove `bash util/build_prep/bootstrap_boost.sh -m` from the [build command](#build-commands) below.\n\n### Qt wallet\n\nIf building the Qt-based `nano_wallet`, first download [Qt 5.15.2+ open source edition](https://www.qt.io/download) and extract to [qt.src]. In [qt.build] execute:\n\n=== \"*nix\"\n ```bash\n [qt.src]/configure -shared -opensource -nomake examples -nomake tests -confirm-license -prefix [qt]\n make\n make install\n ```\n\n=== \"macOS\"\n ```bash\n [qt.src]/configure -shared -opensource -nomake examples -nomake tests -confirm-license -prefix [qt]\n make\n make install\n ```\n\n=== \"Windows\"\n ```bash\n [qt.src]/configure -shared -opensource -nomake examples -nomake tests -confirm-license -prefix [qt]\n nmake\n nmake install\n ```\n\n### Node\n\n=== \"*nix\"\n **Required build tools**\n\n * CMake >= 3.8\n * Clang >= 11 or GCC >= 11.3\n\n === \"Debian\"\n **Version**\n\n * Debian 11 Bullseye (requires Clang 11)\n\n **Install dependencies**\n\n ```bash\n sudo apt-get update && sudo apt-get upgrade\n sudo apt-get install git cmake build-essential libc++-dev libc++abi-dev clang clang++11 curl wget\n sudo apt-get install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools\n ```\n \n **Qt wallet dependencies**\n\n ```bash\n sudo apt-get install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools\n ```\n\n **Before build**\n\n ```bash\n export CC=/usr/bin/clang-11\n export CXX=/usr/bin/clang++-11\n cmake ...\n ```\n\n === \"Ubuntu\"\n **Version**\n \n * Ubuntu 22.04 LTS Server\n * Ubuntu 22.10+\n\n **Install dependencies**\n\n ```bash\n sudo apt-get update && sudo apt-get upgrade\n sudo apt-get install git cmake g++ curl wget\n ```\n\n **Qt wallet dependencies**\n\n ```bash\n sudo apt-get install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools\n ```\n\n === \"Rocky Linux\"\n **Version**\n \n * Rocky Linux 8\n\n **Install dependencies**\n\n ```bash\n sudo yum check-update\n sudo yum install git curl wget cmake\n ```\n\n **Configure repository with modern GCC**\n ```bash\n sudo yum install gcc-toolset-12\n scl enable gcc-toolset-12 bash\n ```\n\n === \"Arch Linux\"\n\n **Install dependencies**\n\n ```bash\n pacman -Syu\n pacman -S base-devel git gcc cmake curl wget\n ```\n\n=== \"macOS\"\n **Required build tools**\n \n * CMake >= 3.8\n * XCode >= 13.1\n\n=== \"Windows\"\n **Required build tools**\n\n * CMake >= 3.8\n * NSIS package builder\n * [Visual Studio 2019 Community](https://my.visualstudio.com/Downloads?q=visual%20studio%202019&wt.mc_id=o~msft~vscom~older-downloads) (or higher edition, if you have a valid license. eg. Professional or Enterprise)\n * Select **Desktop development with C++**\n * Select the latest Windows 10 SDK\n\n---\n\n## Build commands\n\n### Node\n\nThe process below will create a release build of the node for the main network. See [network options](#network-options) below for details on building for the test or beta networks.\n\n=== \"*nix\"\n ```bash\n git clone --branch V25.0 --recursive https://github.com/nanocurrency/nano-node.git nano_build\n cd nano_build\n # Boost is not required for building V25.0 or earlier versions\n # export BOOST_ROOT=`pwd`/../boost_build\n # bash util/build_prep/bootstrap_boost.sh -m\n cmake -G \"Unix Makefiles\" .\n make nano_node\n cp nano_node ../nano_node && cd .. && ./nano_node --diagnostics\n ```\n\n=== \"macOS\"\n ```bash\n git clone --branch V25.0 --recursive https://github.com/nanocurrency/nano-node.git nano_build\n cd nano_build\n # Boost is not required for building V25.0 or earlier versions\n # export BOOST_ROOT=`pwd`/../boost_build\n # bash util/build_prep/bootstrap_boost.sh -m\n cmake -G \"Unix Makefiles\" .\n make nano_node\n cp nano_node ../nano_node && cd .. && ./nano_node --diagnostics\n ```\n\n=== \"Windows\"\n\n **Setup**\n\n *Download Source*\n\n Using git_bash:\n ```bash\n git clone --branch V25.0 --recursive https://github.com/nanocurrency/nano-node\n cd nano-node\n ```\n\n *Create a `build` directory inside nano-node (makes for easier cleaning of build)*\n\n Using git_bash:\n ```bash\n mkdir build\n cd build\n ``` \n * **Note:** all subsequent commands should be run within this \"build\" directory.\n\n *Get redistributables*\n\n Using Powershell:\n ```bash\n Invoke-WebRequest -Uri https://aka.ms/vs/16/release/vc_redist.x64.exe -OutFile .\\vc_redist.x64.exe\n ```\n\n *Generate the build configuration.*\n\n Using 64 Native Tools Command Prompt:\n\n * Ensure the Qt, Boost (if < V25.0), and Windows SDK paths match your installation.\n\n ```bash\n cmake -DNANO_GUI=ON -DQt5_DIR=\"C:\\Qt\\5.15.2\\msvc2019_64\\lib\\cmake\\Qt5\" -DNANO_SIMD_OPTIMIZATIONS=TRUE -DBoost_COMPILER=\"-vc141\" -DBOOST_ROOT=\"C:/local/boost_1_70_0\" -DBOOST_LIBRARYDIR=\"C:/local/boost_1_70_0/lib64-msvc-14.1\" -G \"Visual Studio 16 2019\" -DIPHLPAPI_LIBRARY=\"C:/Program Files (x86)/Windows Kits/10/Lib/10.0.19041.0/um/x64/iphlpapi.lib\" -DWINSOCK2_LIBRARY=\"C:/Program Files (x86)/Windows Kits/10/Lib/10.0.19041.0/um/x64/WS2_32.lib\" ..\\.\n ```\n \n * If you are building V25.0 or any earlier version, you do not need to specify the Boost library.\n\n ```bash\n cmake -DNANO_GUI=ON -DQt5_DIR=\"C:\\Qt\\5.15.2\\msvc2019_64\\lib\\cmake\\Qt5\" -DNANO_SIMD_OPTIMIZATIONS=TRUE -G \"Visual Studio 16 2019\" -DIPHLPAPI_LIBRARY=\"C:/Program Files (x86)/Windows Kits/10/Lib/10.0.19041.0/um/x64/iphlpapi.lib\" -DWINSOCK2_LIBRARY=\"C:/Program Files (x86)/Windows Kits/10/Lib/10.0.19041.0/um/x64/WS2_32.lib\" ..\\.\n ```\n\n **Build**\n \t\n * Open `nano-node.sln` in Visual Studio\n * Build the configuration specified in the previous step\n * Alternative using 64 Native Tools Command Prompt:\n\n ```bash \n cmake --build . --target ALL_BUILD --config %CONFIGURATION% -- /m:%NUMBER_OF_PROCESSORS%\n ```\n\n **Package up binaries**\n\n Using 64 Native Tools Command Prompt:\n\n * Replace **%CONFIGURATION%** with the build configuration specified in previous step\n * Replace **%GENERATOR%** with NSIS (if installed) or ZIP\n\n ```bash \n cpack -G %GENERATOR% -C %CONFIGURATION%\n ```\n\n### Qt wallet\n\nThis is only required when the Qt wallet with GUI is needed.\n\n`make nano_wallet`\n\n### RPC server\n\nThis is only required for when the RPC server is being [run as a child process or outside the node process completely](advanced.md#running-nano-as-a-service).\n\n`make nano_rpc`\n\n---\n\n## Windows & Visual Studio\n\nAn alternative node building process using Windows and Visual Studio can be found below. As this uses GUI options, some of the steps and images may vary if using versions other than those indicated.\n\n**Windows**\n\nEnsure Windows 10 or Windows 11 is running and the latest updates have been completed, restart Windows.\n\n**Visual Studio**\n\nUse Visual Studio 2019 or 2022\nVisual Studio Community 2019 https://visualstudio.microsoft.com/vs/older-downloads/ \nVisual Studio Community 2022 https://visualstudio.microsoft.com/vs/community/ \nRun the installer and make sure to tick `Desktop development with C++` and leave everything else at default.\n\n![Visual Studio 2019 Install](../images/windows-10-build-instructions/visual-studio-install.jpg)\n\n**Boost** (Only needed when building versions before V25.0)\n\nInstall Boost 1.81.0 binaries for msvc 14.2. Use default settings during install \nhttps://sourceforge.net/projects/boost/files/boost-binaries/1.81.0/boost_1_81_0-msvc-14.2-64.exe/download\n\n**CMake**\n\nInstall Cmake windows installer, Latest Release\nhttps://cmake.org/download/.\n\nCheck the option `Add cmake to system path for all users`\n\n**Git**\nDownload a git tool of choice such as Github desktop https://desktop.github.com/. Clone the nano node develop branch from Github\nfrom URL https://github.com/nanocurrency/nano-node to your preferred path, such as: `C:\\Users\\YourUser\\Documents\\GitHub\\nano-node`.\n\n**Restart Windows**\n\n**Setting up the solution**\n\nRun CMake GUI\n\n- Set `Where is the source code` to your preferred path: `C:\\Users\\YourUser\\Documents\\GitHub\\nano-node`\n- Create a directory for the destination files such as: `C:\\Users\\YourUser\\Documents\\NanoSolution` and set in `Where to build the binaries`\n- Click `Configure` and select `Visual Studio 16 2019` as the generator for the project\n- Set any necessary [CMake variables](#cmake-variables) you need, such as the `ACTIVE_NETWORK` but leave `NANO_GUI` off because this requires QT to be installed\n- Click `Generate` and close Cmake\n\n![CMake Generator](../images/windows-10-build-instructions/cmake-generator.jpg)\n\n\n**Visual studio**\n\n- Open project solution file in `C:\\Users\\YourUser\\Documents\\NanoSolution\\nano-node-beta.sln`\n- At the top of the screen select the build type and architecture. `Release` and `x64` are recommended settings\n\n![Build type and architecture](../images/windows-10-build-instructions/debug-arch.jpg)\n\n- Go to the build menu and select `Build`\n- When build has finished you will find the compiled files at `C:\\Users\\YourUser\\Documents\\NanoBinaries\\` \n\n**Optional: Setup debugging**\n\nYou can setup the node to stop at code breakpoints and then inspect values during runtime.\n\nFind the nano_node project in the solution explorer on the right pane. Then right click it and select `Set as startup project`\n\n![Set as startup project](../images/windows-10-build-instructions/startup-project.jpg)\n\nRight click the nano_node project again and click `Properties`\nGo to `Configuration Properties` > `Debugging` and set the `Command Arguments` to `--daemon`, click OK\n\n![Set properties](../images/windows-10-build-instructions/set-properties.jpg)\n\nFrom Visual Studio hit `F5` to start debugging. When a breakpoint is hit, Visual Studio will halt the code and take focus.\n\n---\n\n## Additional build details\n\n### Node\n\n#### CMake variables\n\nFormat: `cmake -D VARNAME=VARVALUE`\n\n* `BOOST_ROOT=\\[boost\\]` (`/usr/local/boost/` if bootstrapped)\n* `CMAKE_BUILD_TYPE=Release` (default)\n* `ACTIVE_NETWORK=nano_live_network` (default)\n* `Qt5_DIR=[qt]lib/cmake/Qt5` (to build GUI wallet)\n* `NANO_GUI=ON` (to build GUI wallet)\n* `ENABLE_AVX2=ON`, *optional* `PERMUTE_WITH_GATHER=ON`, *optional* `PERMUTE_WITH_SHUFFLES=ON` (for CPU with AXV2 support, choose fastest method for your CPU with https://github.com/sneves/blake2-avx2/)\n* `CRYPTOPP_CUSTOM=ON` (more conservative building of Crypto++ for wider range of systems)\n* `NANO_SIMD_OPTIMIZATIONS=OFF` (Enable CPU-specific SIMD optimization: SSE/AVX or NEON, e.g.)\n* `NANO_SECURE_RPC=ON` (to build node with TLS)\n* `NANO_WARN_TO_ERR=ON` (*v20.0+* turn compiler warnings into errors on Linux/Mac) \n* `NANO_TIMED_LOCKS=50` (*v20.0+* when the number of milliseconds a mutex is held is equal or greater than this output a stacktrace, 0 disables.)\n* `NANO_STACKTRACE_BACKTRACE=ON` (*v20.0+* use a different configuration of Boost backtrace in stacktraces, attempting to display filenames, function names and line numbers. Needs `libbacktrace` to be installed. Some [workarounds](https://www.boost.org/doc/libs/develop/doc/html/stacktrace/configuration_and_build.html#stacktrace.configuration_and_build.f3) may be necessary depending on system and configuration. Use CLI [`--debug_stacktrace`](/commands/command-line-interface#-debug_stacktrace) to get an example output.)\n* `CI_BUILD=TRUE` (*v20.0+* if enabled, uses environment variable `TRAVIS_TAG` (required) to modify the locally reported node version; example `TRAVIS_TAG=\"My Nano Node v20\"`)\n* `NANO_ASIO_HANDLER_TRACKING=10` (Output asio diagnostics for any completion handlers which have taken longer than this in milliseconds. For more information see the description of the PR [#2681](https://github.com/nanocurrency/nano-node/pull/2681))\n* `NANO_FUZZER_TEST=ON` (Build the fuzz tests, not available on Windows)\n\n#### Building a package\n\n=== \"*nix\"\n `cpack -G \"TBZ2\"`\n\n=== \"macOS\"\n `cpack -G \"DragNDrop\"`\n\n=== \"Windows\"\n `cpack -G \"NSIS\"`\n\n#### Network options\n\n**Main network**\n\nThe default build network is the main network. No option needs to be specified.\n\n**Test Network**\n\n* To run a node on the test network, set CMake variable: `-DACTIVE_NETWORK=nano_test_network`\n* More information can be found on the [Test Network page](../running-a-node/test-network.md)\n\n**Beta Network**\n\n* To run a node on the beta network, set CMake variable: `-DACTIVE_NETWORK=nano_beta_network`\n* More information can be found on the [Beta Network page](../running-a-node/beta-network.md)\n\n## Testing\n\nA number of tests binaries can be built when the CMake variable `-DNANO_TEST=ON`. With this variable set, `make` will also build test files, and will produce `core_test`, `rpc_test`, `load_test` and `slow_test` binaries, which can be executed:\n\n* `core_test` - Tests the majority of protocol, node and network functionality.\n* `slow_test` - Tests which operate on a large amount of data and may take a while. Not currently tested by CI.\n* `rpc_test` - Tests all RPC commands\n* `load_test` - Launches many nodes and RPC servers, checking sending/receiving blocks with simultaneous calls. Use `./load_test --help` to see the available options\n\n### Running Tests\n\nTo run all tests in a binary just launch it:\n```bash\n./core_test\n```\n\nTo check a specific subset of tests, gtest filtering can be used (with optional wildcards):\n```bash\n./core_test --gtest_filter=confirmation_height.single\n./rpc_test --gtest_filter=rpc.*\n```\n\nTo run tests multiple times:\n```bash\n./core_test --gtest_repeat=10\n```\n\nIf running on a debugger, add the argument `--gtest_break_on_failure` break at the moment a test fails.\n\n### Environment variables to customize tests\n\n* `TEST_KEEP_TMPDIRS=1` - Setting this to anything will prevent the tests deleting any files it creates, useful for debugging log files. \n* `TEST_USE_ROCKSDB=1` - Use the RocksDB ledger backend for the tests instead of LMDB. The tests must be built with [RocksDB](/running-a-node/rocksdb-ledger-backend/#rocksdb-ledger-backend) support.\n* `TEST_BASE_PORT=26000` - The base port used in tests, the range of ports used in this case would be 26000 - 26199. This is useful if wanting to run multiple tests at once without port conflicts, the default base port used is 24000. \n* `NANO_DEFAULT_PEER=peering.nano.org` - Setting this adds its variable contents to `preconfigured_peers` from config-node.toml, & allows manually setting initial peering DNS. Setting it to an unresolvable address will prevent the node from contacting peers (after wiping peer table).\n\n### Sanitizers\n\n3 different CMake sanitizer options are supported: `NANO_ASAN_INT`, `NANO_TSAN` and `NANO_ASAN`. They cannot be used in conjunction with each other.\n\n#### Thread Sanitizer\nUse `-DNANO_TSAN=ON` as an extra CMake option. The following environment variable should also be set:\n\n`export TSAN_OPTIONS=\"suppressions=../tsan_suppressions\"`\n\n`tsan_suppressions` should be a path to the file in the root nano directory. This suppresses many errors relating to the mdb and rocksdb libraries.\n\n#### Address Sanitizer\nUse the CMake variable `-DNANO_ASAN=ON` or `-DNANO_ASAN_INT=ON` before running an executable.\n\n### Valgrind\n\nValgrind can be used to find other issues such as memory leaks. A valgrind suppressions file is provided to remove some warnings. Valgrind can be run as follows (there are many options available):\n\n```bash\nvalgrind --leak-check=full --track-origins=yes --suppressions=../valgrind.supp ./core_test\n```\n" }, { "path": "docs/integration-guides/index.md", "content": "title: Get started integrating Nano\ndescription: An introduction to the process of starting a Nano integration\n\n# Integrating with Nano\n\nIf you're looking for details about how to integrate your application or service with Nano, you've come to the right place! There are a variety of ways to do integrations and this documentation is focused on situations requiring custom development. If you are looking for a more plug-and-play option to accept Nano payments or donations, we recommend heading to https://nano.org/accept-nano for some simpler options.\n\n## What is needed to integrate?\n\nThe most basic integration with Nano will require:\n\n1. Access to make RPC calls to a Nano node\n1. A method of doing work generation for any blocks created\n1. Some form of a wallet to manage the private/public keys for your accounts\n\nBut before jumping in to setup, there are a few best practices and concepts you should be familiar with first:\n\n### How transactions work and block specs\n\nTransactions function differently in Nano compared to other blockchains due to the block lattice design. The [What is Nano?](../what-is-nano/overview.md) page gives a quick explanation on how send and receive transactions are related in Nano. As you get into your integration, it is best to be familiar with the [block specifications](the-basics.md#blocks-specifications) in order to understand how different block subtypes are built and relate to each other.\n\n### Account, Key, Seed and Wallet IDs\n\nKnowing how private and public keys are related to seeds and accounts is critical to building a safe and secure integration. With the internal node wallet, there is also a unique wallet ID that adds further security and must be considered if using that wallet for development/testing (see the wallets section below for details). Review the [Account, Key, Seed and Wallet IDs](the-basics.md#account-key-seed-and-wallet-ids) section for some additional details.\n\nIf you need to generate or manage seeds or mnemonic phrases, see the [seeds](key-management.md#seeds) section for some key information about options as they may differ from other existing projects and standards.\n\n### Units\n\nThere are two main units used: nano and raw. The ratio is:\n$$\n1 nano = 10^{30} raw\n$$\n\nAll [QR code](the-basics.md#uri-and-qr-code-standards) setups and RPC calls use raw for the amounts, while any human interaction with units is done at the Nano level.\n\n### Other concepts\n\nThe above concepts capture a minimum understanding to begin your integration journey, and although additional resources will be called out further in the various guides, don't be afraid to check out other resources throughout the documentation here.\n\n---\n\n## Accessing RPC calls\n\nMost integrations send and receive funds by making RPC calls to a Nano node. This requires either access to a public API or running your own node on one of the available networks. Depending on your goals, both are valid approaches with many options and levels of engagement.\n\n### Running your own node\n\nRunning a node involves installing, configuring and maintaining software on a server, preferably on a stable cloud service for the best performance and uptime. This approach gives you more control at the cost of additional effort.\n\nIf going this route, we encourage use of the existing test network for initial integrations. Head over to the [Running a node](../running-a-node/overview.md) guide and make your way through the overview and security pages before stepping through the node setup guide. Make sure you have \"Test network\" selected in all the example commands.\n\n!!! info \"Production integration node should be non-voting\"\n\tWhen moving to production with a node on the main network, we recommend running dedicated, non-voting node for your integration. If you are interested in running a representative node to help further decentralize the network consensus, please setup a separate node for this purpose to ensure both operate as effectively as possible. See the [Voting as a Representative guide](../running-a-node/voting-as-a-representative.md) for further details.\n\n### Public APIs\n\nAccess to public APIs for the main network is also available via third-party vendors and community members. These are only available for the main network and are great for quickly testing out a proof-of-concept or prototype using small amounts. If using for production applications caution should be taken when evaluating SLAs and uptime in general.\n\n- Community supported public APIs list available at [publicnodes.somenano.com](https://publicnodes.somenano.com/)\n- [NOWNodes](https://nownodes.io/) offers free and paid access to Nano node RPC calls (does not include work generation) with some [service quality standards](https://nownodes.io/service-quality-standards)\n\n---\n\n## Wallet\n\nIn order to manage private and public keys, accounts, seeds, etc. you will need wallet software. A few potential options are included below, with more user-focused and backend options listed at [nanowallets.guide](https://nanowallets.guide).\n\n### Node internal wallet\n\n--8<-- \"warning-node-wallet-not-for-prod-use.md\"\n\nThe official binaries, builds and Docker containers for the Nano node published by the Nano Foundation have an internal wallet available for use in development and testing. This is Qt based wallet with both a GUI and related [RPC commands](../commands/rpc-protocol.md#wallet-rpcs). The following features are available via the GUI:\n\n- Import wallet and adhoc keys\n- Export seed (automatically generated on startup)\n- Change representatives\n- Send and automatically receive\n- Automatic work generation for transactions (via CPU by default)\n- Manual options for block creation, block processing and initiation of bootstrapping\n- Various advanced options for viewing the ledger, peers, blocks, accounts and statistics\n\nThis wallet requires running the node, so after getting your [node setup](../running-a-node/node-setup.md) you can follow the [wallet setup guide](/running-a-node/wallet-setup.md) to get started. If building the node yourself, see the Qt wallet notes on the [build options guide](../integration-guides/build-options.md) for how to build the `nano_wallet` binary in addition to the node.\n\n### Pippin\n\nThis community built wallet is a production-ready, high performance developer wallet that is setup to be a drop-in replacement for the internal node wallet. Built in Python and optimized for fast response times, this is a good option to explore for any integration. With an open source license, you are encouraged to contribute to its development as well.\n\n[![Pippin](https://opengraph.githubassets.com/38565027a4d84e26310588fd4712b3cf836745cbe2b4a20ac44590225da01765/appditto/pippin_nano_wallet){width=50%}](https://github.com/appditto/pippin_nano_wallet)\n\n\n### Nault\n\nThis community built wallet is more end-user focused with a robust GUI full of various options. It can be useful in development and testing as it supports setting the custom backend to your own node and can function as a basic account/block explorer. If you use this wallet, it also has an open source license so contributions are encouraged.\n\n\n[![Nault](https://repository-images.githubusercontent.com/274627453/14c0c180-bc4a-11ea-82e9-cc23b8b5a718){width=50%}](https://github.com/Nault/Nault)\n\n---\n\n## Additional tools\n\nThere are plenty of additional libraries and tools worth exploring to help with your integration. Head over the the [Developer Tools page on nano.org](https://nano.org/tools) for a list of commonly used options. Other resources can be explored at the community built [nanolinks.info](https://nanolinks.info/) site.\n\n---\n\n## Next steps\n\nIf you've made it this far you may have a node running with a wallet setup and have started playing around on the test network. The next steps from here are understanding more about how to handle the various operations most integration require, such as:\n\n- Managing public and private keys: see [Key Management](key-management.md), sending and receiving transactions and handling work generation.\n- Creating and sending transactions:\n - External wallet (such as Pippin): see [External Management - Creating transactions](key-management.md#creating-transactions)\n - Internal node wallet: see [Internal Management](key-management.md#internal-management)\n- Tracking block confirmations: see [Block Confirmation Tracking guide](block-confirmation-tracking.md)\n- Performing efficient work generation: see [Work Generation guide](work-generation.md)\n- Optional WebSocket integration: see [WebSockets guide](websockets.md)\n\n" }, { "path": "docs/integration-guides/ipc-integration.md", "content": "title: IPC Integration Guide\ndescription: Learn how to integrate with the nano node using the Interprocess Communication (IPC) interface\n\n# IPC Integration\n\nThe node manages communications using an IPC interface with v1 introduced in V18 (see [IPC v1 Details](#ipc-v1-details)) and upgraded to v2 in V21 to include more robust options. This latest version supports the original RPC v1 endpoint and introduces RPC v2 for completion in future release, along with an authentication system for more granular control of permissioned calls.\n\n**Configuration**\n\nThese configuration options are set in the [`config-node.toml` file](../running-a-node/configuration.md#configuration-file-locations).\n\nIPC is configured in the `node.ipc.tcp` and `node.ipc.local` sections:\n\n```toml\n[node.ipc.local]\n\n# If enabled, certain unsafe RPCs can be used. Not recommended for production systems.\n# type:bool\n#allow_unsafe = false\n\n# Enable or disable IPC via local domain socket.\n# type:bool\n#enable = false\n\n# Timeout for requests.\n# type:seconds\n#io_timeout = 15\n\n# Path to the local domain socket.\n# type:string\n#path = \"/tmp/nano\"\n\n[node.ipc.tcp]\n\n# Enable or disable IPC via TCP server.\n# type:bool\n#enable = false\n\n# Timeout for requests.\n# type:seconds\n#io_timeout = 15\n\n# Server listening port.\n# type:uint16\n#port = 7077\n```\n\n## IPC request/response format\n\nA client must make requests using the following framing format:\n\n```\nREQUEST ::= HEADER PAYLOAD\nHEADER ::= u8('N') ENCODING u8(0) u8(0)\nENCODING ::= u8(1)\nPAYLOAD ::= \n```\n\nFour encodings currently exist:\n\n* 1: legacy RPC [_since v18.0_]\n* 2: legacy RPC allowing unsafe operations if node is configured so [_since v19.0_]\n* 3: flatbuffers [_since v21.0_]\n* 4: json over flatbuffers [_since v21.0_]\n\nThe encoding is followed by two reserved zero-bytes. These allow for future extensions, such as versioning and extended headers.\n\nNote that the framing format does not include a length field - this is optionally placed in the respective payloads. The reason is that some encodings might want to be \"streamy\", sending responses in chunks, or end with a sentinel.\n\n```\nLEGACY_RPC_PAYLOAD ::= be32(length) JSON request\nLEGACY_RPC_RESPONSE ::= be32(length) JSON response\n```\n\nIn short, JSON requests and responses are 32-bit big-endian length-prefixed.\n\n## RPC Gateway\n\nThe RPC gateway automatically translates between Flatbuffers and JSON messages over HTTP. The request and response is standard JSON.\n\n!!! info \"Examples require TLS support\" \n\tThe examples below assumes the node is compiled with TLS support. If not, replace https with http. If using TLS with a self-signed certificate, add --insecure to curl commands.\n\n### Making calls without a message envelope\nA message envelope is a way to tell the server which message type is sent, as well as other information such as credentials.\n\nFor HTTP clients, it's convenient to send messages _without_ an envelope. They do so by appending the message name (using uppercase CamelCase) to the path:\n\n`POST` to https://www.example.com:7076/api/v2/AccountWeight\n```\n{\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n}\n```\n\nThe RPC 1.0 `action` field is thus not necessary.\n\nThe response message is always wrapped in an envelope. JSON clients use the `message` property to access the message:\n\n```json\n{\n \"time\": 1579736914615,\n \"message_type\": \"AccountWeightResponse\",\n \"message\": {\n \"voting_weight\": \"668657804547735335568510480612620716\"\n }\n}\n```\n\nThe `message_type` is always Error if a call fails:\n\n```json\n{\n \"time\": 1579737134595,\n \"message_type\": \"Error\",\n \"message\": {\n \"code\": 3,\n \"message\": \"Access denied\"\n }\n}\n```\n\nThe `time` property is milliseconds since unix epoch when the message was produced on the server.\n\n**Relation to the WebSocket response structure**\n\nThe `message` and `time` properties of the response envelope is exactly the same as in [WebSockets](/integration-guides/websockets). Instead of `message_type`, WebSockets use `topic`. This structure should help simplify clients using both HTTP and WebSockets.\n\n**Headers**\n\nWhen calling without an envelope, credentials and a correlation id can still be set using an HTTP header:\n\n`curl --header \"Nano-Api-Key:mywalletuser\" ...`\n\nThe correlation header is Nano-Correlation-Id, which can be an arbitrary string. This is usually not useful for request/response JSON clients, but may be valuable if responses from RPCs and WebSocket subscriptions are dealt with in a common message handler on the client.\n\n### Making calls with message envelopes\n\nIf the message name is missing from the path, an envelope will be expected which tells the node about the message type.\n\n`POST` to https://www.example.com:7076/api/v2\n```json\n{ \n \"message_type\" : \"AccountWeight\", \n \"message\": {\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n }\n}\n```\n\nThe above is similar to using the \"action\" property in RPC 1.0. The main difference is that the message itself is always placed in a \"message\" property.\n\nThe envelope allows additional information to be sent, such as credentials:\n\n`POST` to https://www.example.com:7076/api/v2\n\n```json\n{ \n \"credentials\": \"mywalletuser\", \n \"message_type\" : \"AccountWeight\", \n \"message\": {\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"\n }\n}\n```\n\n**Large requests**\nWhile somewhat less convenient, the envelope approach is desirable for very large requests, because the node doesn't need to copy the message into an envelope.\n\n---\n\n### Flatbuffers mapping\n\nHere's the corresponding [message definitions](https://github.com/nanocurrency/nano-node/blob/master/api/flatbuffers/nanoapi.fbs) for the AccountWeight request and response types:\n\n```\n/** Returns the voting weight for the given account */\ntable AccountWeight {\n /** A nano_ address */\n account: string (required);\n}\n\n/** Response to AccountWeight */\ntable AccountWeightResponse {\n /** Voting weight as a decimal number*/\n voting_weight: string (required);\n}\n```\n\n---\n\n### Parsing errors\n\nAny problems with the JSON request will be reported with error details:\n\n```json\n{\n \"message_type\": \"Error\",\n \"message\": {\n \"code\": 1,\n \"message\": \"Invalid message format: 3: 2: error: required field is missing: account in AccountWeight\"\n }\n}\n```\n\n---\n\n## IPC Authorization\n\n!!! warning \"Work in progress\"\n Permission settings is a work in progress, and their exact definition and defaults will be part of RPC 2.0 in a future node release.\n\nWith IPC 2.0, the Nano node offers an authorization system.\n\nThe configuration is done in `config-access.toml` by defining users and optional roles. Permissions are then assigned to these. The node only checks for permissions, never roles. This way, you can freely structure roles and users the way that suits your situation.\n\nThere is also a default user with limited default permissions, currently only allowed to use the `AccountWeight` and `IsAlive` calls. This is used when no credentials are given. The permissions of the default user can also be changed in the configuration file.\n\nCredentials:\n\n* IPC clients set the credentials in the message envelope \n* HTTP(S) clients either use a message envelope or the HTTP Header `Nano-Api-Key`\n\n!!! tip \"Layered security highly recommended\"\n\tWhile permissions enable node operators to pick what functionality to expose to which users, it is still highly recommended that layered security is used. For instance, a wallet backend should expose only required functionality to clients. The backend can then communicate with the node with credentials for additional security.\n\n### Call example\n\n```bash\ncurl --header \"Nano-Api-Key:mywalletuser\" --insecure -d \\\n '{ \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\"}' \\\n https://www.example.com:7076/api/v2/AccountWeight\n```\nThis uses HTTPS (which the node supports through a build option), and the `--insecure` is there because the node's certificate in this example is self-signed.\n\nUsing an envelope instead of the `AccountWeight` endpoint:\n\n```json\n{ \n \"credentials\": \"mywalletuser\",\n \"message_type\" : \"AccountWeight\", \n \"message\": \n {\n \"account\": \"nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3\" \n }\n} \n```\n\n`POST` the above to https://www.example.com:7076/api/v2\n\n### Configuration examples\n\nFor testing IPC without caring about permissions, this gives access to everything:\n\n```toml\n[[user]]\nallow = \"unrestricted\"\n```\n\nA more elaborate sample:\n\n!!! warning \"Work in progress\"\n Permission settings is a work in progress, and their exact definition and defaults will be part of RPC 2.0 in a future node release.\n\n```toml\n[[role]]\nid = \"service_admin\"\nallow = \"api_service_register, api_service_stop\"\n\n[[user]]\n# User id's are typically randomly generated strings which\n# matches the credentials in API requests.\nid = \"user-2bb818ee-6424-4750-8bdb-db23bab7bc57\"\n\n# Inherit all the permissions from these roles\nroles = \"service_admin\"\n\n# Add additional permissions for this specific user\nallow = \"wallet_seed_change, api_topic_confirmation\"\n\n# A list of specific permissions can be denied as well\ndeny = \"api_account_weight\"\n\n[[user]]\nid = \"history-viewer-e3cf8a09-bd74-4ef2-9b84-e14f3db2bb4b\"\n\n# Add specific permission for this user\nallow = \"api_account_info, api_account_history\"\n\n# Do not inherit any default permissions. This is useful\n# for making users with a explicit set of minimum permissions.\n# The default user can also be set to bare. That way, a node can be\n# exposed with a limited set of default permissions.\nbare = true\n```\n\n### Reload config\n\nThe access file can be reloaded without restarting the node or wallet. For the node:\n\n`killall -SIGHUP nano_node`\n\n(actual syntax depends on OS)\n\n---\n\n## IPC V1 Details\n\nAs of v18, the Nano node exposes a low level IPC interface over which multiple future APIs can be marshalled. Currently, the IPC interface supports the legacy RPC JSON format. The HTTP based RPC server is still available. Because the only IPC encoding is currently \"legacy RPC\", RPC config options like \"enable_control\" still apply.\n\n**Transports**\n\nTCP and unix domain sockets are supported. Named pipes and shared memory may be supported in future releases.\n\n**IPC clients**\n\nA NodeJS client is available at https://github.com/meltingice/nano-ipc-js\n\nA Python client is being developed at https://github.com/guilhermelawless/nano-ipc-py\n" }, { "path": "docs/integration-guides/key-management.md", "content": "title: Key Management Guide\ndescription: Learn best practices for private key management for the nano protocol\n\n# Key Management\n\n## Seeds\n\n### Hex Seed\nNano's private key(s) have been traditionally derived from a 64 character, uppercase hexadecimal string (0-9A-F). This is currently the more popular form of seed supported by a variety of services and wallets. Additional details available in [The Basics guide](/integration-guides/the-basics/#seed).\n\n### Mnemonic Seed\nWallets that provide mnemonic seeds should use the [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) standard word list and methods for generating the seed. When BIP32 master keys are generated from the seed, the HMAC hash key variation \"ed25519 seed\" should be used due to nano using [ed25519 for the signing algorithm](../protocol-design/signing-hashing-and-key-derivation.md#signing-algorithm-ed25519) (see [SLIP-0010](https://github.com/satoshilabs/slips/blob/master/slip-0010.md)).\n\nA non-standard derivation path is used for nano in the [Ledger Nano implementation](https://github.com/LedgerHQ/app-nano), as well as other popular wallets. With a coin-type of `165'` (`0x800000a5`), this is a partial BIP44 path of `m/44'/165'/[address index]`. Only hardened paths are defined.\n\n`m/44'/165'/0'` derives the first private key, `m/44'/165'/1'` derives the second private key, and so on.\n\nThe partial derivation path is hard-coded in the common verification tool by Ian Coleman: https://iancoleman.io/bip39/ . If using this tool to verify, note that regardless of custom settings on the BIP32 or BIP44 tabs for address generation, the resulting addresses in the table at the bottom will follow `m/44'/165'/[address index]`, even if the path in that table indicates otherwise. To see accurate paths in the Derived Addresses table, on the BIP32 tab set the BIP32 Derivation Path to `m/44'/165'`.\n\n#### Demo Examples\n\n--8<-- \"warning-external-libraries.md\"\n\nhttps://github.com/roosmaa/nano-bip39-demo\n\nhttps://github.com/joltwallet/bip-mnemonic\n\n#### Implementations\n\nhttps://github.com/numsu/nanocurrency-web-js\n\n#### Test Vectors\n\n**24-Word Mnemonic**\n\n```\nedge defense waste choose enrich upon flee junk siren film clown finish luggage leader kid quick brick print evidence swap drill paddle truly occur\n```\nGiven Passphrase:\n```\nsome password\n```\nDerived BIP39 Seed:\n```\n0dc285fde768f7ff29b66ce7252d56ed92fe003b605907f7a4f683c3dc8586d34a914d3c71fc099bb38ee4a59e5b081a3497b7a323e90cc68f67b5837690310c\n```\n\n??? success \"Index 0 (`44'/165'/0'`)\"\n\n Derived Private Key:\n ```\n 3be4fc2ef3f3b7374e6fc4fb6e7bb153f8a2998b3b3dab50853eabe128024143\n ```\n Derived Public key:\n ```\n 5b65b0e8173ee0802c2c3e6c9080d1a16b06de1176c938a924f58670904e82c4\n ```\n Derived Address:\n ```\n nano_1pu7p5n3ghq1i1p4rhmek41f5add1uh34xpb94nkbxe8g4a6x1p69emk8y1d\n ```\n\n??? success \"Index 1 (`44'/165'/1'`)\"\n\n Derived Private Key:\n ```\n ce7e429e683d652446261c17a96da9ed1897aea96c8046f2b8036f6b05cb1a83\n ```\n Derived Public key:\n ```\n d9f7762e9cd4e7ed632481308cdb8f54abf0241332c0a8641f61e92e2fb03c12\n ```\n Derived Address:\n ```\n nano_3phqgrqbso99xojkb1bijmfryo7dy1k38ep1o3k3yrhb7rqu1h1k47yu78gz\n ```\n\n??? success \"Index 2 (`44'/165'/2'`)\"\n\n Derived Private Key:\n ```\n 1257df74609b9c6461a3f4e7fd6e3278f2ddcf2562694f2c3aa0515af4f09e38\n ```\n Derived Public key:\n ```\n a46da51986e25a14d82e32d765dcee69b9eeccd4405411430d91ddb61b717566\n ```\n Derived Address:\n ```\n nano_3b5fnnerfrkt4me4wepqeqggwtfsxu8fai4n473iu6gxprfq4xd8pk9gh1dg\n ```\n\n**12-Word Mnemonic**\n\n```\ncompany public remove bread fashion tortoise ahead shrimp onion prefer waste blade\n```\n\nNo Passphrase\n\nDerived BIP39 Seed:\n```\n924a962cae64448812be28a514093ebfeeed537d61a44318eb35f902961d21b2fccd30008d33c8d1d5327a34b9b73281c4b27a0a3d004c1c2e85e8dbb234cba8\n```\n\n??? success \"Index 0 (`44'/165'/0'`)\"\n\n Derived Private Key:\n ```\n 6f73d61ca0b56fcdb79d69d437f102348ad75ca971433eb92b2b003f8c99b48d\n ```\n Derived Public key:\n ```\n 134d938215f68bcaa3a0e574fde325fc4b1abad9bd3d698bfef95633b54ffb57\n ```\n Derived Address:\n ```\n nano_16tfkg33dxndscjt3sdnzqjkdz4d5cxfmhbxf87zxycp8gtnzytqmcosi3zr\n ```\n\n??? success \"Index 1 (`44'/165'/1'`)\"\n\n Derived Private Key:\n ```\n 7e104389811a0967ef574af1f3f423f23cbf7b614be17844f67fb6fd315f9a7e\n ```\n Derived Public key:\n ```\n 71e6caac915affe836c3e822be6a5b3464f40c74bd2e5459d4e74205c6a7c0df\n ```\n Derived Address:\n ```\n nano_1wh8scpb4pqzx1ue9t34qso7pf56yi89bhbgcjexbst41q5chi8zqtwb74ih\n ```\n\n??? success \"Index 2 (`44'/165'/2'`)\"\n\n Derived Private Key:\n ```\n 8b7250869207a277ac37068dbe32782c2ab9fc6a5342f0deabbfdfae1285196a\n ```\n Derived Public key:\n ```\n fcebc6554853ed01c242817abf1b5050b887002f8de8f55d00c7c6b5fe01075d\n ```\n Derived Address:\n ```\n nano_3z9drscninzf193671dtqwfo1n7riw14z5hayogi3jy8pqz143txaghe4gbk\n ```\n\n\n## External Management\n\nFor larger, more robust systems, external private key management is recommended. In this setup, the node operator generates and stores private keys in an external database and only queries the nano\\_node to:\n\n1. Find receivable blocks for an account\n2. Sign transactions given a private key. More advanced systems may choose to implement signing themselves.\n3. Broadcast the signed transaction to the network.\n\n!!! note\n [WALLET\\_IDs](/integration-guides/the-basics/#wallet-id) are not used for External Private Key Management since private keys are not stored in the nano\\_node. Much of this section builds off of the [Blocks Specifications](/integration-guides/the-basics/#blocks-specifications) documentation.\n\n---\n### External accounting systems\n\nIn order to properly implement accounting systems external to the Nano node the following best practices should be put into place, which ensure only fully confirmed blocks are used for external tracking of credits, debits, etc.\n\n!!! tip \"Confirmation and idempotency\"\n The details below expand on this, but the two most important pieces of any integration are:\n\n 1. **Always confirm blocks** - make sure to follow the block confirmation tracking recommendations so you are always taking action from confirmed blocks\n 1. **Guarantee idempotency** - whenever you take action from a block confirmation, it must be idempotent so you don't take the action again if the same block hash is seen through confirmation tracking\n\n#### Block confirmation procedures\n\nBefore crediting funds to an account internally based on a deposit on the network, the block sending the funds must be confirmed. This is done by verifying the network has reached quorum on the block. Details of the recommended verification process can be found in the [block confirmation tracking guide](/integration-guides/block-confirmation-tracking).\n\n\n#### Tracking confirmed balances\n\nExternal accounting systems that track balances arriving to the node must track hashes of blocks that have been received in order to guarantee idempotency. Once confirmation of a block has been validated, the block hash should be recorded for the account along with any credits, debits or other related information. Any attempts to credit or debit accounts external to the node should check that no previous conflicting or duplicate activity was already recorded for that same block hash.\n\n#### Transaction order and correctness\n\nIf you are creating a batch of transactions for a single account, which can be a mix of sending and receiving funds, there is no need to wait for the confirmation of blocks **in that account** to create the next transaction. As long as a transaction is valid, it will be confirmed by the network. The transactions that follow it can only be confirmed if the previous transactions are valid.\n\nHowever, you must always wait for the confirmation of **receivable blocks** before creating the corresponding receive transaction, to ensure it will be confirmed. Always wait for confirmation of transactions that you did not create yourself.\n\n---\n\n### Expanding Private Keys\n\nA Nano private key is a 256-bit piece of data produced from a cryptographically secure random number generator.\n\n!!! danger \"Secure Private Keys\" \n * Generating private keys from an insecure source may result in loss of funds.\n * Be sure to backup any generated private key; if lost the funds in the account will become inaccessible.\n\n!!! example \"Step 1: Generate secure private key\"\n The bash command below generates a valid private key from a cryptographically secure random number generator. **Always use a cryptographically secure processes for generating any private keys.**\n\n##### Command Example\n\n```bash\ncat /dev/urandom | tr -dc '0-9A-F' | head -c${1:-64}\n```\n\n##### Success Result\n\n```\n781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\n```\n\n!!! example \"Step 2: Expand private key\"\n From the private key, a public key can be derived, and the public key can be translated into a Nano Address using the [`key_expand`](/commands/rpc-protocol#key_expand) RPC command.\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"key_expand\",\n \"key\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"private\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\",\n \"public\": \"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}\n```\n\n---\n\n### Creating Transactions\n\nUsing external keys, transactions are generated in two steps: creation and broadcast. This section will be more heavy on example rather than precise specifications.\n\n#### Send Transaction\n\n!!! example \"Step 1: Get Account Info\"\n To send funds to an account, first call the [`account_info`](/commands/rpc-protocol#account_info) RPC command to gather necessary account information to craft your transaction. Setting `\"representative\": \"true\"` makes the nano\\_node also return the account's representative address, a necessary piece of data for creating a transaction.\n \n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"account_info\",\n \"representative\": \"true\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"frontier\": \"92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D\",\n \"open_block\": \"B292BFFAAE9013BE630B31144EF15205E986940080687C0441CCFE6EAB67FE53\",\n \"representative_block\": \"B292BFFAAE9013BE630B31144EF15205E986940080687C0441CCFE6EAB67FE53\",\n \"balance\": \"4618869000000000000000000000000\",\n \"modified_timestamp\": \"1524626644\",\n \"block_count\": \"4\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\"\n}\n```\n\n!!! example \"Step 2: Build `block_create` request\"\n Using details from the `account_info` call response, along with other information, we can create the [`block_create`](/commands/rpc-protocol#block_create) RPC request.\n\n For more details on values, see the [Blocks Specifications](/integration-guides/the-basics/#blocks-specifications) documentation.\n\n | Field | Value |\n | | |\n | `\"json_block\"` | always `\"true\"`, so that the output is JSON-formatted |\n | `\"type\"` | always the constant `\"state\"` |\n | `\"previous\"` | `\"frontier\"` from `account_info` response |\n | `\"account\"` | `\"account\"` address used in the `account_info` call above that the block will be created for |\n | `\"representative\"` | `\"representative\"` address returned in the `account_info` call |\n | `\"balance\"` | balance of the account in $raw$ **after** this transaction is completed (decreased if sending, increased if receiving). In this example, we will send 1 $nano$ ($10^{30} raw$) to address `nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p`. |\n | `\"link\"` | destination address the funds will move between |\n | `\"key\"` | account's private key |\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"block_create\",\n \"json_block\": \"true\",\n \"type\": \"state\",\n \"previous\": \"92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"3618869000000000000000000000000\",\n \"link\": \"nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p\",\n \"key\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"hash\": \"BB569136FA05F8CBF65CEF2EDE368475B289C4477342976556BA4C0DDF216E45\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\",\n \"previous\": \"92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"3618869000000000000000000000000\",\n \"link\": \"5C2FBB148E006A8E8BA7A75DD86C9FE00C83F5FFDBFD76EAA09531071436B6AF\",\n \"link_as_account\": \"nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p\",\n \"signature\": \"74BCC59DBA39A1E34A5F75F96D6DE9154E3477AAD7DE30EA563DFCFE501A804228008F98DDF4A15FD35705102785C50EF76732C3A74B0FEC5B0DD67B574A5900\",\n \"work\": \"fbffed7c73b61367\"\n }\n}\n```\n\n!!! info \"Additional details\"\n * The option `json_block`, available since V19.0, makes the RPC call return a non-stringified version of the block, which is easier to parse and always recommended.\n * [`block_create`](/commands/rpc-protocol#block_create) RPC commands generally take longer than other RPC commands because the nano\\_node has to generate the [Proof-of-Work](/integration-guides/the-basics/#proof-of-work) for the transaction. The response block data is already properly formatted to include in the [`process`](/commands/rpc-protocol#process) RPC command.\n * The nano\\_node creating and signing this transaction has no concept of what the transaction amount is, nor network state; all the nano\\_node knows is that it is creating a block whose previous block on the account chain has hash `92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D` results in the account having a balance of `3618869000000000000000000000000`.\n * If the account's balance at block hash `92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D` was actually `5618869000000000000000000000000`, then 2 $nano$ would have been sent to `nano_1q3hqecaw15cjt7thbtxu3pbzr1eihtzzpzxguoc37bj1wc5ffoh7w74gi6p`.\n\n!!! question \"What if I receive funds on my account and then broadcast the above crafted send? Would this result in me sending excess funds to the recipient?\"\n If you followed this guide, then the answer is \"no\". When you issued the [`account_info`](/commands/rpc-protocol#account_info) RPC command, you received the account's balance at a specific blockhash on its account-chain. In your crafted transaction, you specify that hash in the `\"previous\"` field. If funds were signed into your account, the headblock on your account-chain would change. Since your send no longer refers to the headblock on your account-chain when broadcasted, the network would reject your transaction.\n\n!!! warning\n Since only the resulting balance is recorded, the transaction amount is interpreted as the difference in balance from the previous block on the account-chain and the newly created block. For this reason, it is crucial that you obtain the current account balance and headblock in the same atomic [`account_info`](/commands/rpc-protocol#account_info) RPC command.\n\n When not following this guide closely, the following **inappropriate sequence of events could lead to erroneous amounts sent** to a recipient.\n\n 1. An account's balance, say 5 $nano$, was obtained using the [`account_balance`](/commands/rpc-protocol#account_balance). This balance is valid as of hypothetical **BLOCK_A**.\n 1. By another process you control, a receive (**BLOCK_B**) was signed and broadcasted into your account-chain (race-condition).\n * Lets say this `receive` increased the funds on the account chain by 10 $nano$, resulting in a final balance 15 $nano$.\n 1. The account's frontier block is obtained by the [`accounts_frontiers`](/commands/rpc-protocol#accounts_frontiers) RPC command, returning the hash of **BLOCK_B**. Other transaction metadata is obtained by other RPC commands.\n 1. With the collected data, if a send transaction was created for 3 $nano$, the final balance would be computed as $5 - 3$, or 2 $nano$.\n 1. When this is broadcasted, since it is referring to the current head block on the account, **BLOCK_B**, the network would accept it. But, because the balance as of **BLOCK_B** was actually 15 $nano$, this would result in 12 $nano$ being sent to the recipient.\n\n For this reason, **only populate transaction data source from a single [`account_info`](/commands/rpc-protocol#account_info) RPC call**.\n\n!!! example \"Step 3: Broadcast the transaction\"\n As a result of the command above, the nano\\_node will return a signed, but not yet broadcasted transaction. Broadcasting of the signed transaction is covered in the [Broadcasting Transactions](#broadcasting-transactions) section.\n\n---\n\n#### Receive Transaction\n\n!!! info \"Manually receiving first block\"\n The very first transaction on an account-chain, which is always a receive, is slightly special and deserves its own section [First Receive Transaction](#first-receive-transaction).\n\n!!! example \"Step 1: Get Account Info\"\n Receiving funds is very similar to sending funds outlined in the previous section, starting with calling `account_info` to get block details for the account frontier. The scenario below pretends that our previous example of a send transaction was **not** broadcast and confirmed on the network because the starting `account_info` details are identical.\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"account_info\",\n \"representative\": \"true\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"frontier\": \"92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D\",\n \"open_block\": \"B292BFFAAE9013BE630B31144EF15205E986940080687C0441CCFE6EAB67FE53\",\n \"representative_block\": \"B292BFFAAE9013BE630B31144EF15205E986940080687C0441CCFE6EAB67FE53\",\n \"balance\": \"4618869000000000000000000000000\",\n \"modified_timestamp\": \"1524626644\",\n \"block_count\": \"4\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\"\n}\n```\n\n!!! example \"Step 2: Build `block_create` request\"\n Using details from the `account_info` call response, along with other information, we can create the [`block_create`](/commands/rpc-protocol#block_create) RPC request. The two differences between the send transaction are the `\"link\"` and `\"balance\"` fields.\n\n For more details on values, see the [Blocks Specifications](/integration-guides/the-basics/#blocks-specifications) documentation.\n\n | Field | Value |\n | | |\n | `\"json_block\"` | always `\"true\"`, so that the output is JSON-formatted |\n | `\"type\"` | always the constant `\"state\"` |\n | `\"previous\"` | `\"frontier\"` from `account_info` response, or `0` if first block on new account |\n | `\"account\"` | `\"account\"` address used in the `account_info` call above that the block will be created for |\n | `\"representative\"` | `\"representative\"` address returned in the `account_info` call |\n | `\"balance\"` | balance of the account in $raw$ **after** this transaction is completed (decreased if sending, increased if receiving). In this example, we will receive 7 $nano$ ($7 \\times 10^{30} raw$) based on the assumed details of the block the `\"link\"` hash refers to (block contents not shown in this example). |\n | `\"link\"` | block hash of its paired send transaction, assumed to be a 7 $nano$ send from block hash `CBC911F57B6827649423C92C88C0C56637A4274FF019E77E24D61D12B5338783` |\n | `\"key\"` | account's private key |\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"block_create\",\n \"json_block\": \"true\",\n \"type\": \"state\",\n \"previous\": \"92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"11618869000000000000000000000000\",\n \"link\": \"CBC911F57B6827649423C92C88C0C56637A4274FF019E77E24D61D12B5338783\",\n \"key\": \"781186FB9EF17DB6E3D1056550D9FAE5D5BBADA6A6BC370E4CBB938B1DC71DA3\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"hash\": \"350D145570578A36D3D5ADE58DC7465F4CAAF257DD55BD93055FF826057E2CDD\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx\",\n \"previous\": \"92BA74A7D6DC7557F3EDA95ADC6341D51AC777A0A6FF0688A5C492AB2B2CB40D\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"11618869000000000000000000000000\",\n \"link\": \"CBC911F57B6827649423C92C88C0C56637A4274FF019E77E24D61D12B5338783\",\n \"link_as_account\": \"nano_3kyb49tqpt39ekc49kbej51ecsjqnimnzw1swxz4boix4ctm93w517umuiw8\",\n \"signature\": \"EEFFE1EFCCC8F2F6F2F1B79B80ABE855939DD9D6341323186494ADEE775DAADB3B6A6A07A85511F2185F6E739C4A54F1454436E22255A542ED879FD04FEED001\",\n \"work\": \"c5cf86de24b24419\"\n }\n}\n```\n\n!!! info \"Additional details\"\n Here the follow scenario occurs:\n\n * Previous balance was 4618869000000000000000000000000 $raw$\n * Increased our balance by 7000000000000000000000000000000 $raw$\n * Final balance becomes 11618869000000000000000000000000 $raw$\n\n!!! example \"Step 3: Broadcast the transaction\"\n As a result of the command above, the nano\\_node will return a signed, but not yet broadcasted transaction. Broadcasting of the signed transaction is covered in the [Broadcasting Transactions](#broadcasting-transactions) section.\n\n---\n\n#### First Receive Transaction\n\nThe first transaction of an account is crafted in a slightly different way. To open an account, you must have sent some funds to it with a [Send Transaction](#send-transaction) from another account. The funds will be **receivable** on the receiving account. If you already know the hash of the receivable transaction, you can skip Step 1.\n\n!!! example \"Step 1: Obtain the receivable transaction block hash\"\n\n Start with obtaining a list of receivable transactions in your unopened account. Limit the response to the highest value transaction by using a combination of `sorting` and `count`.\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"receivable\",\n \"account\": \"nano_1rawdji18mmcu9psd6h87qath4ta7iqfy8i4rqi89sfdwtbcxn57jm9k3q11\",\n \"count\": \"1\",\n \"sorting\": \"true\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"blocks\": {\n \"5B2DA492506339C0459867AA1DA1E7EDAAC4344342FAB0848F43B46D248C8E99\": \"100\"\n }\n}\n```\n\n!!! example \"Step 2: Build `block_create` request\"\n Using the block hash and raw transaction amount from the `receivable` call response, along with other information, we can create the [`block_create`](/commands/rpc-protocol#block_create) RPC request. The only difference between the normal receive transactions is the `\"previous\"` field.\n\n For more details on values, see the [Blocks Specifications](/integration-guides/the-basics/#blocks-specifications) documentation.\n\n | Field | Value |\n | | |\n | `\"json_block\"` | always `\"true\"`, so that the output is JSON-formatted |\n | `\"type\"` | always the constant `\"state\"` |\n | `\"previous\"` | always the constant \"0\" as this request is for the first block of the account |\n | `\"account\"` | `\"account\"` address used in the `account_info` call above that the block will be created for |\n | `\"representative\"` | `\"representative\"` the account address to use as [representative](/integration-guides/the-basics#representatives) for your account. Choose a reliable, trustworthy representative. |\n | `\"balance\"` | balance of the account in $raw$ **after** this transaction is completed. In this example, we will receive $100\\ raw$, based on the assumed details from the `\"receivable\"` response above. |\n | `\"link\"` | block hash of its paired send transaction, in this case assumed to be the block `5B2DA492506339C0459867AA1DA1E7EDAAC4344342FAB0848F43B46D248C8E99` |\n | `\"key\"` | account's private key |\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"block_create\",\n \"json_block\": \"true\",\n \"type\": \"state\",\n \"previous\": \"0\",\n \"account\": \"nano_1rawdji18mmcu9psd6h87qath4ta7iqfy8i4rqi89sfdwtbcxn57jm9k3q11\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"100\",\n \"link\": \"5B2DA492506339C0459867AA1DA1E7EDAAC4344342FAB0848F43B46D248C8E99\",\n \"key\": \"0ED82E6990A16E7AD2375AB5D54BEAABF6C676D09BEC74D9295FCAE35439F694\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"hash\": \"ED3BE5340CC9D62964B5A5F84375A06078CBEDC45FB5FA2926985D6E27D803BB\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1rawdji18mmcu9psd6h87qath4ta7iqfy8i4rqi89sfdwtbcxn57jm9k3q11\",\n \"previous\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"100\",\n \"link\": \"5B2DA492506339C0459867AA1DA1E7EDAAC4344342FAB0848F43B46D248C8E99\",\n \"link_as_account\": \"nano_1psfnkb71rssr34sisxc5piyhufcrit68iqtp44ayixnfnkas5nsiuy58za7\",\n \"signature\": \"903991714A55954D15C91DB75CAE2FBF1DD1A2D6DA5524AA2870F76B50A8FE8B4E3FBB53E46B9E82638104AAB3CFA71CFC36B7D676B3D6CAE84725D04E4C360F\",\n \"work\": \"08d09dc3405d9441\"\n }\n}\n```\n\n!!! example \"Step 3: Broadcast the transaction\"\n As a result of the command above, the nano\\_node will return a signed, but not yet broadcasted transaction. Broadcasting of the signed transaction is covered in the [Broadcasting Transactions](#broadcasting-transactions) section.\n\n---\n\n### Broadcasting Transactions\n\n!!! example \"Broadcast using [`process`](/commands/rpc-protocol/#process) RPC command\"\n Common to all of these transactions is the need to broadcast the completed block to the network. This is achieved by the [`process`](/commands/rpc-protocol#process) RPC command which accepts the block as stringified JSON data. If you followed the previous examples, you used the option `json_block` for RPC [`block_create`](/commands/rpc-protocol#block_create), which allows you use the non-stringified version, as long as you include the same option in this RPC call. \n A successful broadcast will return the broadcasted block's hash.\n\n--8<-- \"warning-process-sub-type-recommended.md\"\n\n##### Request Example\n```bash\ncurl -d '{\n \"action\": \"process\",\n \"json_block\": \"true\",\n \"subtype\": \"open\",\n \"block\": {\n \"type\": \"state\",\n \"account\": \"nano_1rawdji18mmcu9psd6h87qath4ta7iqfy8i4rqi89sfdwtbcxn57jm9k3q11\",\n \"previous\": \"0000000000000000000000000000000000000000000000000000000000000000\",\n \"representative\": \"nano_1stofnrxuz3cai7ze75o174bpm7scwj9jn3nxsn8ntzg784jf1gzn1jjdkou\",\n \"balance\": \"100\",\n \"link\": \"5B2DA492506339C0459867AA1DA1E7EDAAC4344342FAB0848F43B46D248C8E99\",\n \"link_as_account\": \"nano_1psfnkb71rssr34sisxc5piyhufcrit68iqtp44ayixnfnkas5nsiuy58za7\",\n \"signature\": \"903991714A55954D15C91DB75CAE2FBF1DD1A2D6DA5524AA2870F76B50A8FE8B4E3FBB53E46B9E82638104AAB3CFA71CFC36B7D676B3D6CAE84725D04E4C360F\",\n \"work\": \"08d09dc3405d9441\"\n }\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n```json\n{ \n \"hash\": \"42A723D2B60462BF7C9A003FE9A70057D3A6355CA5F1D0A57581000000000000\"\n}\n```\n\n!!! tip \"Block watching and re-work\"\n Since V20.0, blocks processed using [`process`](/commands/rpc-protocol/#process) are placed under observation by the node for re-broadcasting and re-generation of work under certain conditions. If you wish to disable this feature, add `\"watch_work\": \"false\"` to the process RPC command.\n\n * If a block is not confirmed within a certain amount of time (configuration option `work_watcher_period`, default 5 seconds), an **automatic re-generation of a higher difficulty proof-of-work** may take place.\n * Re-generation only takes place when the network is unable to confirm transactions quickly (commonly referred as the network being *saturated*) and the higher difficulty proof-of-work is used to help prioritize the block higher in the processing queue of other nodes.\n * Configuration option `max_work_generate_multiplier` can be used to limit how much effort should be spent in re-generating the proof-of-work.\n * The target proof-of-work difficulty threshold is obtained internally as the minimum between [`active_difficulty`](/commands/rpc-protocol/#active_difficulty) and `max_work_generate_multiplier` (converted to difficulty).\n * With a new, [higher difficulty](/integration-guides/the-basics/#difficulty-multiplier) proof-of-work, the block will get higher confirmation priority across the network.\n\n\n!!! info \"When a transaction does not confirm\"\n * If a transaction is taking too long to confirm, you may call the [`process`](/commands/rpc-protocol#process) RPC command with the same block data with no risk.\n * If for some reason a transaction fails to properly broadcast, subsequent transactions on the account-chain after that transaction will not be accepted by the network since the `\"previous\"` field in the transaction data refers to a non-existant block.\n * If this situation occurs, rebroadcasting the missing transaction(s) will make the subsequent blocks valid in the network's ledger.\n\n---\n\n!!! example \"Rebroadcasting blocks for an account-chain\"\n The following command rebroadcasts all hashes on an account-chain **starting** at block hash provided:\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"republish\",\n \"hash\": \"48006BF3146C18CAD3A53A957BF64EF7C57820B21FCCE373FA637559DA260358\"\n}' http://127.0.0.1:7076\n```\n\n---\n\n## Internal Management\n\nThe nano\\_node software has a built-in private-key manager that is suitable for smaller operations (<1000 accounts). [External Key Management](/integration-guides/key-management/#external-management) allows more powerful and robust systems at the cost of additional complexity. External Key Management is recommended for larger operations.\n\n### Creating a Wallet\n\nTo create an account, you first must create a wallet to hold the seed that will subsequently create the account.\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"wallet_create\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{ \n \"wallet\": \"E3E67B1B3FFA46F606240F1D0B964873D42E9C6D0B7A0BF376A2E128541CC446\"\n}\n```\n\nThe nano\\_node responds with the WALLET\\_ID. If you lose your WALLET\\_ID, it can only be recovered via a CLI command. To reiterate, the **WALLET_ID is not a seed**. The seed can be extracted for backup in [Backing Up Seed](#backing-up-seed). Many of the RPC commands in this guide require the WALLET\\_ID.\n\n---\n\n### Recovering WALLET_ID\n\nIf you lose your WALLET\\_ID, you can print out all your WALLET\\_IDs and public addresses in those wallets with the [`--wallet_list`](/commands/command-line-interface#-wallet_list) CLI command as follows:\n\n##### Command Format\n\n```bash\ndocker exec ${NANO_NAME} nano_node --wallet_list\n```\n\n##### Success Response\n\n```yaml\nWallet_ID: E3E67B1B3FFA46F606240F1D0B964873D42E9C6D0B7A0BF376A2E128541CC446\nnano_16odwi933gpzmkgdcy9tt5zef5ka3jcfubc97fwypsokg7sji4mb9n6qtbme\nWallet_ID: DB0711484E35A4C75230D898853A86BFAFE9F87FCE99C83A4C2668C39607DD4B\n```\n\nIn this example, the nano\\_node's internal private-key management system contains two wallets, each with a different 256-bit seed. The first wallet has a single account and the second wallet has zero accounts. Account creation will be covered later.\n\n---\n\n### Backing Up Seed\n\nThe following command will print the seed for a given wallet to stdout. Replace `${WALLET_ID}` with the WALLET\\_ID that you would like to display the seed of.\n\n##### Command Format\n\n```bash\ndocker exec ${NANO_NAME:-nano_node_1} nano_node --wallet_decrypt_unsafe --wallet ${WALLET_ID}\n```\n\n##### Success Response\n\n```yaml\nSeed: D56143E7561D71C1AF4D563C6AF79EECE93E82479818AD8ED88BED1AAE8BE4E5\nPub: nano_16odwi933gpzmkgdcy9tt5zef5ka3jcfubc97fwypsokg7sji4mb9n6qtbme\nPrv: 1F6FEB5D1E05C10B904E1112F430C3FA93ACC7067206B63AD155199501794E3E\n```\n\n!!! info\n The nano\\_node responds with three pieces of information:\n \n 1. The seed of the wallet (back this up).\n 1. The pairing public address\n 1. The private key (deterministically derived from seed) of accounts within the wallet.\n\n Additional notes:\n\n * If you change the seed in a wallet, future created accounts will be derived from that seed.\n * Changing seeds on a wallet that already has accounts can cause accidental loss of funds from improper seed or private key backup.\n * It is recommended to always create a new wallet when restoring a seed.\n\n##### Error Response\n\n```\nWallet doesn't exist\n```\n\n!!! warning\n If anyone has access to the seed, they can freely access funds, so keep this very secure. Since the above command prints to stdout, it is recommended to wipe stdout afterwards using:\n\n ```bash\n clear && printf '\\e[3J'\n ```\n\n---\n\n### Restoring/Changing Seed\n\n!!! warning\n Only change the seed of a wallet that contains no accounts. Changing the seed of a wallet that already has accounts may lead to a false sense of security: accounts are generated by the seed that is currently in the wallet. Generating accounts, then switching the seed and backing up the new seed does **not** backup the previously generated accounts.\n\n##### Request Format\n\n```bash\ncurl -d '{\n \"action\": \"wallet_change_seed\",\n \"wallet\": \"\",\n \"seed\": \"\"\n}' http://127.0.0.1:7076\n```\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\":\"wallet_change_seed\",\n \"wallet\":\"DB0711484E35A4C75230D898853A86BFAFE9F87FCE99C83A4C2668C39607DD4B\",\n \"seed\":\"D56143E7561D71C1AF4D563C6AF79EECE93E82479818AD8ED88BED1AAE8BE4E5\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"success\": \"\"\n}\n```\n\n##### Error Response\n\nResponse if the wallet_id isn't found in nano\\_node:\n```json\n{\n \"error\": \"Wallet not found\"\n}\n```\n\nResponse if the seed field contains non-hexidecimal values or is too long:\n```json\n{ \n \"error\": \"Bad seed\"\n}\n```\n\n!!! warning\n If the hexidecimal seed represents less than 256 bits, the seed will be 0-padded on the left to become 256 bits.\n\n---\n\n### Account Create\n\nAfter creating a wallet, it's corresponding WALLET\\_ID, and **backing up the seed (not the wallet\\_id)**, the wallet can be populated with accounts. To create a new account in a wallet use the [`account_create`](/commands/rpc-protocol#account_create) RPC command:\n\n##### Request Format\n\n```bash\ncurl -d '{\n \"action\": \"account_create\",\n \"wallet\": \"\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{ \n \"account\": \"nano_16odwi933gpzmkgdcy9tt5zef5ka3jcfubc97fwypsokg7sji4mb9n6qtbme\"\n}\n```\n\n##### Error Response\n\n```json\n{\n \"error\": \"Wallet not found\"\n}\n```\n\n---\n\n### Bulk Account Create\n\nTo generate many accounts in bulk, it is more efficient to create them all at once using the [`accounts_create`](/commands/rpc-protocol#accounts_create) RPC command:\n\n##### Request Format\n\n```bash\ncurl -d '{\n \"action\": \"accounts_create\",\n \"wallet\": \"\",\n \"count\": \"\"\n}' http://127.0.0.1:7076\n```\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"accounts_create\",\n \"wallet\": \"DB0711484E35A4C75230D898853A86BFAFE9F87FCE99C83A4C2668C39607DD4B\",\n \"count\":\"5\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"accounts\": [\n \"nano_35kgi43t5hgi64715qnppmz1yb6re1igfcrkfx4ppirkqpfmecnpd1mdmafu\",\n \"nano_3t13y6b7h93yn9hehn8p6yqx1yqzrxxs33drhzep8huhymwxamn15pba75oj\",\n \"nano_11exxzfoosai96w7gnrjrn7m6i8bodch37ib8jgxsm5k96na6e1wda8np881\",\n \"nano_3xbsso8pkemwatwdnkcyn1bfcmrb8dpcg3pit9zqxj9mkxa6ifiankff6m9x\",\n \"nano_1q5gpy46moe1csj8md8oq3x57sxqmwskk8mmr7c63q1yebnjcsxg1yib19kn\"\n ]\n}\n```\n\n---\n\n### Receiving Funds\n\nAs long as the nano\\_node is synced and the node wallet is unlocked (node wallet locking is not covered in this guide), nano\\_node automatically creates and signs receive transactions for all accounts in the wallet's internal private-key management system.\n\n!!! tip\n In the event that a receive is not automatically generated, it can be manually generated using the [`receive`](/commands/rpc-protocol#receive) RPC command.\n\n#### Semi-Manual Receiving Funds\n\nIf the nano\\_node does not automatically sign in a receivable transaction, transactions can be manually signed in. The easiest way is to explicitly command the nano\\_node to check all of the accounts in all of its wallets for receivable blocks.\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"search_receivable_all\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"success\": \"\"\n}\n```\n\n!!! note\n As the number of accounts in a nano\\_node grows, this command becomes increasingly computationally expensive.\n\n---\n\n### Sending funds\n\nThe [`send`](/commands/rpc-protocol#send) RPC command sends funds from an account in the specified wallet to a destination address.\n\n##### Request Format\n\n```bash\ncurl -d '{\n \"action\": \"send\",\n \"wallet\": \"\",\n \"source\": \"\",\n \"destination\": \"\",\n \"amount\": \"1000000\",\n \"id\": \"7081e2b8fec9146e\"\n}' http://127.0.0.1:7076\n```\n\n| Field | Description |\n| | |\n| wallet | WALLET_ID containing the source address |\n| source | Address you control starting with \"nano_\" |\n| destination | Destination address starting with \"nano_\" |\n| amount | Amount to send in raw |\n| id | Any string |\n\n---\n\n!!! warning \"Important\"\n The `\"id\"` field is a safety mechanism that prevents issuing a transaction multiple times by repeating the RPC command.\n\n * If a transaction is successful, any subsequent [`send`](/commands/rpc-protocol#send) RPC commands with the same identifier will be ignored by the nano\\_node.\n * If the request times out, then the send may or may not have gone through.\n * Most exchange \"double withdraw\" issues are caused by naive error-handling routines which re-issue the send request without the `\"id\"` parameter.\n * The `\"id\"` field is local to your nano\\_node instance and does not offer protection when sent to different instances of nano\\_node that manage the same seed.\n * As previously mentioned, having a seed loaded in multiple online nano_node is strongly discouraged.\n * If managing more than 1000 accounts, building a separate system for managing keys and accounts externally is recommended\n\n---\n\nBelow is a sample command to send 1 $nano$ from `nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000` to `nano_16odwi933gpzmkgdcy9tt5zef5ka3jcfubc97fwypsokg7sji4mb9n6qtbme`.\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"send\",\n \"wallet\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\",\n \"source\": \"nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000\",\n \"destination\": \"nano_16odwi933gpzmkgdcy9tt5zef5ka3jcfubc97fwypsokg7sji4mb9n6qtbme\",\n \"amount\": \"1000000000000000000000000000000\",\n \"id\": \"7081e2b8fec9146e\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{ \n \"block\": \"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F\"\n}\n```\n\nOn success, the nano\\_node returns the hash of the transaction's block.\n\n---\n\n### Republishing Transactions\n\nIt may take a few seconds for the transaction to appear on the Nano Network. If the transaction fails to appear, you may call the [`republish`](/commands/rpc-protocol#republish) RPC command with the oldest missing transaction's hash. Account-chains must be **continuous and unbroken**. If for some reason a transaction fails to properly broadcast, subsequent transactions on the account-chain will not be accepted by the network since the `\"previous\"` field in the transaction data refers to a block unknown to to other nodes on the network.\n\n!!! tip\n Republishing the missing transaction(s) will make all the subsequent blocks valid in the network's ledger. Republishing does not create new transactions.\n\nThe following command rebroadcasts all hashes on an acccount-chain starting at block with hash `${BLOCK_HASH}`:\n\n##### Request Example\n\n```bash\ncurl -d '{\n \"action\": \"republish\",\n \"hash\": \"AF9C1D46AAE66CC8F827904ED02D4B3D95AA98B1FF058352BA6B670BEFD40231\"\n}' http://127.0.0.1:7076\n```\n\n##### Success Response\n\n```json\n{\n \"success\": \"\",\n \"blocks\": [\n \"AF9C1D46AAE66CC8F827904ED02D4B3D95AA98B1FF058352BA6B670BEFD40231\",\n \"C9A111580A21F3E63F2283DAF6450D5178BFAC2A6C38E09B76EEA9CE37EC9CE0\"\n ]\n}\n```\nOn success, the nano\\_node returns the hashes of all republished blocks.\n" }, { "path": "docs/integration-guides/the-basics.md", "content": "title: Integration Basics Guide\ndescription: Understand some of the core details of the nano protocol including block specifications, accounts, keys, and more\n\n# The Basics\n\n## Block Lattice Design\n\nNano's ledger is built on a data-structure called a \"Block Lattice.\" Every account (private/public key pair) has their own blockchain (account-chain). Only the holder of the private key may sign and publish blocks to their own account-chain. Each block represents a transaction.\n\nAction | Description\n--------|----------\nSend | Send funds from users account to another account\nReceive | Receive funds from a given \"Send\" transaction\n\n\nThe system is akin to writing (send) and cashing (receive) a Cashier's Check. There are a few things to consider about transactions:\n\n* The receiving account does not have to be online during the Send transaction.\n* The transaction will stay as receivable indefinitely until a Receive transaction is created.\n* Once funds are sent, they cannot be revoked by the sender.\n\n---\n\n## Representatives\n\nThe Nano Network achieves consensus using the unique [Open Representative Voting (ORV)](/what-is-nano/overview/#representatives-and-voting) model. In this setup, representatives (accounts where nano\\_node with the private keys are running 24/7) vote on transactions.\n\n!!! info\n Below are some helpful things to remember about Nano's representatives and consensus:\n\n * A representative's voting power is directly proportional to the amount of funds delegated to that account by other users of the protocol.\n * An account's representative has no bearing on its transactions or nano\\_node operation.\n * Choosing a representative with good uptime that is also a unique entity (to prevent sybil attacks) helps maintain high Nano network security.\n * If an account's representative goes offline, the account's funds are no longer used to help secure the network; however, the account is unaffected.\n * Anyone that runs a full-time node may be a representative and be delegated voting weight from other users of the protocol.\n * An account can freely change its representative anytime within any transaction or explicitly by publishing [a block which only changes the representative](#change) (sends no funds), which most wallets support.\n\n---\n\n## Account, Key, Seed and Wallet IDs\n\nWhen dealing with the various IDs in the node it is important to understand the function and implication of each one.\n\n!!! danger \"Similar IDs, Different Functions\"\n There are several things that can have a similar form but may have very different functions, and mixing them up can result in loss of funds. Use caution when handling them.\n\n### Wallet ID\nThis is a series of 32 random bytes of data and is **not the seed**. It is used in several RPC actions and command line options for the node. It is a **purely local** UUID that is a reference to a block of data about a specific wallet (set of seed/private keys/info about them) in your node's local database file.\n\nThe reason this is necessary is because we want to store information about each account in a wallet: whether it's been used, what its account is so we don't have to generate it every time, its balance, etc. Also, so we can hold ad hoc accounts, which are accounts that are not derived from the seed. This identifier is only useful in conjunction with your node's database file and **it will not recover funds if that database is lost or corrupted**. \n\nThis is the value that you get back when using the `wallet_create` etc RPC commands, and what the node expects for RPC commands with a `\"wallet\"` field as input.\n\n### Seed\nThis is a series of 32 random bytes of data, usually represented as a 64 character, uppercase hexadecimal string (0-9A-F). This value is used to derive **account private keys** for accounts by combining it with an index and then putting that into the following hash function where `||` means concatenation and `i` is a 32-bit big-endian unsigned integer: `PrivK[i] = blake2b(outLen = 32, input = seed || i)`\n\nPrivate keys are derived **deterministically** from the seed, which means that as long as you put the same seed and index into the derivation function, you will get the same resulting private key every time. Therefore, knowing just the seed allows you to be able to access all the derived private keys from index 0 to $2^{32} - 1$ (because the index value is a unsigned 32-bit integer).\n\nWallet implementations will commonly start from index 0 and increment it by 1 each time you create a new account so that recovering accounts is as easy as importing the seed and then repeating this account creation process.\n\nIt should be noted that Nano reference wallet is using described Blake2b private keys derivation path. However some implementations can use BIP44 deterministic wallets and [mnemonic seed](/integration-guides/key-management/#mnemonic-seed) producing different private keys for given seed and indices. Additionally 24-word mnemonic can be derived from a Nano 64 length hex seed as entropy with clear notice for users that this is not BIP44 seed/entropy.\n\n**Code samples**\n\n=== \"Python\"\n\t\n\tGenerates a deterministic key:\n\n\t```python\n\timport hashlib\n\tseed = b\"\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x01\" # \"0000000000000000000000000000000000000000000000000000000000000001\"\n\tindex = 0x00000001.to_bytes(4, 'big') # 1\n\tblake2b_state = hashlib.blake2b(digest_size=32)\n\tblake2b_state.update(seed+index)\n\t# where `+` means concatenation, not sum: https://docs.python.org/3/library/hashlib.html#hashlib.hash.update\n\t# code line above is equal to `blake2b_state.update(seed); blake2b_state.update(index)`\n\tPrivK = blake2b_state.digest()\n\tprint(blake2b_state.hexdigest().upper()) # \"1495F2D49159CC2EAAAA97EBB42346418E1268AFF16D7FCA90E6BAD6D0965520\"\n\t```\n\n=== \"Bitcoinjs\"\n\n\tMnemonic words for Blake2b Nano seed using [Bitcoinjs](https://github.com/bitcoinjs/bip39):\n\t```js\n\tconst bip39 = require('bip39')\n\t\n\tconst mnemonic = bip39.entropyToMnemonic('0000000000000000000000000000000000000000000000000000000000000001')\n\t// => abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon diesel\n\t\n\tbip39.mnemonicToEntropy(mnemonic)\n\t// => '0000000000000000000000000000000000000000000000000000000000000001'\n\t```\n\n\n### Account private key\nThis is also a 32 byte value, usually represented as a 64 character, uppercase hexadecimal string(0-9A-F). It can either be random (an *ad-hoc key*) or derived from a seed, as described above. This is what represents control of a specific account on the ledger. If you know or can know the private key of someone's account, you can transact as if you own that account.\n\n### Account public key\nThis is also a 32 byte value, usually represented as a 64 character, uppercase hexadecimal string (0-9A-F). It is derived from an *account private key* by using the ED25519 curve using Blake2b-512 as the hash function (instead of SHA-512). Usually account public keys will not be passed around in this form, rather the below address is used.\n\n### Account public address\nThis is what you think of as someone's Nano address: it's a string that starts with `nano_` (previously `xrb_`), then has 52 characters which are the *account public key* but encoded with a specific base32 encoding algorithm to prevent human transcription errors by limiting ambiguity between different characters (no `O` and `0` for example). Then the final 8 characters are Blake2b-40 checksum of the account public key to aid in discovering typos, also encoded with the same base32 scheme (5 bytes).\n\nSo for address `nano_1anrzcuwe64rwxzcco8dkhpyxpi8kd7zsjc1oeimpc3ppca4mrjtwnqposrs`:\n\n| Prefix | Encoded Account Public Key | Checksum |\n| | | |\n| `nano_` | `1anrzcuwe64rwxzcco8dkhpyxpi8kd7zsjc1oeimpc3ppca4mrjt` | `wnqposrs` |\n\nFor basic address validation, the following regular expression can be used: `^(nano|xrb)_[13]{1}[13456789abcdefghijkmnopqrstuwxyz]{59}$`. Validation of the checksum is also recommended, depending on the integration.\n\n!!! question \"Prefixes: nano_ vs. xrb_\"\n As of V19.0 **the Nano node only returns `nano_` addresses in all actions**, but prior versions returned `xrb_` addresses. These prefixes are interchangeable — everything after the `_` remains the same. If you have an issue using one or the other prefix with any exchange or service, you can safely switch between `nano_` and `xrb_` prefixes as needed — they both represent the same account owned by your private key or seed.\n\n---\n\n## Units\n\nNano can be represented using more than one unit of measurement. While the most common unit is the $nano$, the smallest unit is the $raw$. Below is the formula for converting between $raw$ and $nano$.\n\n$$\n1 nano = 10^{30} raw\n$$\n\n!!! warning \"Important\"\n \n * All RPC commands expect units to be represented as $raw$. \n * Always keep units in integer $raw$ amounts to prevent any floating-point error or unit confusion.\n * Depending on your implementation language, you may require a big number library to perform arithmetic directly on $raw$.\n * See [Distribution and Units](/protocol-design/distribution-and-units/) page for more details on units.\n * Because final balances are recorded rather than transaction amounts, API calls must be done carefully to avoid loss of funds. Incorrect arithmetic or use of fields may change an intended receive to a send to a non-existent address.\n\n---\n\n## Blocks Specifications\n\nAll new transactions on the Nano Protocol are communicated via blocks. The account's entire state, including the balance after each transaction, is recorded in every block. Transaction amounts are interpreted as the difference in balance between consecutive blocks.\n\nIf an account balance decreases, the transaction that caused the decrease is considered a send. Similarly, if an account balance increases, the transaction that caused the increase is considered a receive.\n\n!!! warning \"Important\"\n Because final balances are recorded rather than transaction amounts, API calls must be done carefully to avoid sending erroneous amounts.\n\n### Block Format\nBecause each block contains the current state of the account, the `\"type\"` of the block is always `\"state\"`. The following table presents the anatomy of a block, along with the format used within RPC calls for building blocks, and the serialized, binary representation:\n\n| Key | RPC Format | Serialized | Description |\n| | | | |\n| type | string | - | \"state\" |\n| account | string | 32 bytes | This account's nano_ address |\n| previous | 64 hex-char string | 32 bytes | Previous head block on account; 0 if *open* block |\n| representative | string | 32 bytes | Representative nano_ address |\n| balance | decimal string | 16 bytes | Resulting balance (in [raw](#units)) |\n| link | (see link table below) | 32 bytes | Multipurpose field - see link table below |\n| signature | 128 hex-char string | 64 bytes | ED25519+Blake2b 512-bit signature |\n| work | 16 hex-char string | 8 bytes | [Proof of Work](../glossary.md#proof-of-work-pow) Nonce |\n\nDepending on the action each transaction intends to perform, the `\"link\"` field will have a different value:\n\n| Action | RPC Format | Description |\n| | | |\n| Change | decimal string | Must be \"0\" |\n| Send | 64 hex-char string | Public key for destination account |\n| Receive | 64 hex-char string | Pairing block's hash (block sending funds) |\n\n If using the [block_create](/commands/rpc-protocol#block_create) RPC command the optional fields `\"source\"` (with the block hash to be received) and `\"destination\"` (with the target `nano_` address) fields can be used instead of directly defining the `\"link\"` field.\n\n!!! note\n * Any transaction may also simultaneously change the representative. The above description of the \"Change\" action is for creating a block with an explicit representative change where no funds are transferred (balance is not changed).\n * In the completed, signed transaction json, the `\"link\"` field is **always** hexadecimal.\n * The first block on an account must be receiving funds (cannot be an explicit representative change). The first block is often referred to as \"opening the account\".\n\n### Self-Signed Blocks\n\nIf you choose to implement your own signing, the order of data (in bytes) to hash prior to signing is as follows.\n\n* All values are binary representations\n* No ASCII/UTF-8 strings.\n\nOrder of data:\n\n1. block preamble (32-Bytes, value ``0x6``)\n2. account (32-Bytes)\n3. previous (32-Bytes)\n4. representative (32-Bytes)\n5. balance (16-Bytes)\n6. link (32-Bytes)\n\n!!! question \"What is the preamble?\"\n As of v15.0 **the Nano node only supports state blocks**, but prior versions used block types to distinguish different kinds of transactions. The preamble is a relic of those blocks, and now it is a constant value since all blocks are the same `state` type.\n\nThe digital signing algorithm (which internally applies another Blake2b hashing) is applied on the resulting digest.\n\n!!! warning \"Private/public key usage\"\n Make sure that your private key uses the correct partnering public key while signing as using an incorrect public key may leak information about your private key.\n\n### Creating Blocks\n\nFor details on how to create individual blocks for sending from, receiving to, opening or changing representatives for an account, please see the [Creating Transactions](/integration-guides/key-management/#creating-transactions) section.\n\n---\n\n## URI and QR Code Standards\n\nNote: `amount` values should always be in RAW.\n\nNote: Please use `nano://` for deep links \n\n### Send to an address\n\n nano:nano_[?][amount=][&][label=