æternity Documentation Hub
Aeternity.comAeternity GitHub
  • æternity Hub
  • Developer Documentation
  • Aeternity Expansions
    • PULL_REQUEST_TEMPLATE
    • AEX X
    • AEXS
      • AEX 1
      • aex-10
      • AEX 11 Fungible Token Standard
      • AEX-130: æpps Metadata Format Specification
      • aex-141
      • AEX 2
      • AEX-3
      • AEX-4
      • AEX 5
      • AEX 7
      • AEX 8
      • aex-9
    • .github
      • ISSUE_TEMPLATE
        • aexpansion
  • AeMdw - Aeternity Middleware
    • Changelog
    • docs
      • AE MDW Architecture
      • AeMdw Hyperhain Setup Documentation
      • AeMdw Docker Setup Documentation
  • Æternity <> Ethereum Bridge
    • Changelog
  • aepp-cli-js
    • CHANGELOG
    • Contributor guide
    • reference
    • user-guide
    • .github
      • ISSUE_TEMPLATE
  • Hyperchain Bridge
    • Changelog
  • æternity's JavaScript SDK
    • Installation
      • Changelog
      • Compatibility Table
      • Quick Start
      • Transaction options
      • Development
        • Releases
      • guides
        • The range of possible address length
        • AENS (æternity naming system)
        • Batch Transactions
        • How to build a wallet
        • Connect an æpp to a wallet
        • Contract Events
        • Contracts
        • Error Handling
        • JWT usage
        • Ledger Hardware Wallet
        • Low vs High level API
        • Aeternity snap for MetaMask
        • Oracles
        • PayingForTx (Meta-Transactions)
        • Typed data hashing and signing
        • Usage with TypeScript
        • migration
          • Migration to 10.0.0
          • Migration to 11.0.0
          • Migration to 12.0.0
          • Migration to 13.0.0
          • Migration to 14.0.0
          • Migration to 7.0.0
          • Migration to 9.0.0
      • tutorials
        • vuejs
          • Vue.js HelloWorld
    • Examples
      • How to connect wallet to æpp using æternity's JS SDK
        • Sample æpp for contracts
        • iframe-based wallet
        • WebExtension-based wallet
    • .github
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
  • AEproject
    • Changelog
    • docs
      • Quick Start
      • AEproject Library
      • Migration from 3.x.x to 4.x.x
      • Migration from 4.x.x to 5.x.x
      • Upcoming Version Support
      • cli
        • Local Environment
        • Project Initialization
        • Unit Testing
    • .github
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
  • aerepl
    • Changelog
  • aescan
    • Changelog
    • Contributor Covenant Code of Conduct
    • Aescan Contributing Guide
    • LICENSE
    • .github
      • pull_request_template
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
    • docs
      • BRANCHING_STRATEGY
  • Sophia Support for Visual Studio Code
    • Changelog
  • aesophia
    • Changelog
    • Contributing to Sophia
    • docs
      • aeso_aci
      • aeso_compiler
      • Introduction
      • sophia
      • Contract examples
      • Features
      • Standard library
      • Syntax
  • aesophia_cli
    • Changelog
  • aesophia_http
    • Changelog
  • Æ Studio - Formerly known as 🔥 Fire Editor ! Aeternity's easy to use editor for writing smart contr
    • ideas
  • aeternity
    • .github
      • The Æternity Code of Conduct
      • Contributing to the Aeternity node
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
    • Welcome to Aeternity node documentation
      • Summary
      • Node API
      • Introduction
      • Build from source
      • Configuration
      • CUDA Miner
      • debian_ubuntu_packaging
      • Docker
      • Fork resistance in Aeternity nodes
      • Garbage Collection
      • Hacking the Aeternity Codebase
      • Hardware Requirements
      • hyperchains
      • Installation
      • Network Monitoring
      • Operation
      • Rebar Quick Guide
      • Stratum
      • Testing
      • Update
      • release-notes
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • next-ceres
          • GH-3706-micro_block_gas_limit_used_gas
          • GH-4009-allow_contract_call_by_name
          • GH-4056-add_raw_data_pointers_to_AENS
          • GH-4080-wildcard_aens_delegation_signature
          • GH3417-tamper_protection_on_ga_meta_tx
          • aega_only_allow_attach_for_fresh_accounts
          • aens_auction_adjustments
          • aens_preclaim_optional
          • deprecate_swagger
          • fate_extensions
        • next
          • GH-3088-db_direct_access-as-default
          • GH-4087_http_endpoint_info_inner_txs
          • GH4157-control-mempool-sync-start
    • Emergency patching of OTP modules
    • rosetta
    • apps
      • aehttp
        • priv
          • rosetta_README
    • data
      • aecore
        • Token migration contract
  • Hyperchains whitepaper
    • Hyperchains: Bridging Security and Scalability Through Periodic Synchronization
    • LICENSE
    • Periodically-Syncing-HyperChains
    • generations
    • Glossary
    • Hyperchain Properties
    • staking
  • æternity protocol
    • æternity naming system
    • Gossip
    • Stratum
    • SYNC
    • Serialization formats
    • State Channels
      • Off-chain
      • On-chain
      • Authentication
      • Channel off-chain state
    • æternity consensus protocol
      • Bitcoin-NG for æternity
      • Coinbase at height
      • consensus
      • Coins locking
    • Smart Contracts
      • The æternity Ethereum virtual machine (AEVM)
      • contract_state_tree
      • Contract Transactions
      • Virtual machines on the æternity blockchain
      • contracts
      • Events
      • fate
      • The Solidity Language
      • sophia
      • sophia_stdlib
    • Generalized accounts
      • Generalized accounts - explained
      • generalized_accounts
    • Oracles
      • Oracle life cycle examples
      • Oracle state tree
      • Oracle transactions
      • oracles
    • Sync
      • P2P messages
      • Mempool/TX-pool synchronization
    • node
      • æternity node API
        • Account management - intended usage
        • Encoding scheme for API identifiers and byte arrays
        • State channel WebSocket API
        • Channels - intended usage
        • Contracts - intended usage
        • Mining - intended usage
        • Naming System - intended usage
        • Oracles - intended usage
        • Spending coins - intended usage
        • examples
          • æternity node channel WebSocket API examples
            • json-rpc
              • sc_ws_basic_open_close
              • sc_ws_basic_open_close_server
              • sc_ws_broken_open_params
              • sc_ws_close_mutual
              • sc_ws_close_solo
              • sc_ws_leave_reconnect
              • sc_ws_leave_reestablish
              • sc_ws_leave_reestablish_responder_stays
              • sc_ws_leave_reestablish_wrong_fsm_id
              • sc_ws_min_depth_is_modifiable
              • sc_ws_min_depth_not_reached_timeout
              • sc_ws_opening_ping_pong
              • sc_ws_reconnect_early
              • sc_ws_slash
              • sc_ws_snapshot_solo
              • sc_ws_timeout_open
              • sc_ws_update_with_meta
              • abort_updates
                • sc_ws_abort_deposit
                • sc_ws_abort_offchain_update
                • sc_ws_abort_settle
                • sc_ws_abort_shutdown
                • sc_ws_abort_slash
                • sc_ws_abort_snapshot_solo
                • sc_ws_abort_withdraw
                • sc_ws_can_not_abort_while_open
              • assume_min_depth
                • sc_ws_basic_open_close
              • both_sign
                • init_per_group
                • conflicts
                  • sc_ws_conflict_deposit_and_offchain_update
                  • sc_ws_conflict_two_deposits
                  • sc_ws_conflict_two_offchain_updates
                  • sc_ws_conflict_two_withdrawals
                  • sc_ws_conflict_withdrawal_and_deposit
                  • sc_ws_conflict_withdrawal_and_offchain_update
              • changeable_fee
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
                • sc_ws_set_fee_close_mutual
                • sc_ws_set_fee_close_solo
                • sc_ws_set_fee_create
                • sc_ws_set_fee_deposit
                • sc_ws_set_fee_settle
                • sc_ws_set_fee_slash
                • sc_ws_set_fee_snapshot
                • sc_ws_set_fee_withdrawal
              • changeable_fee_higher_than_gas_price
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
              • changeable_fee_lower_than_gas_price
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
              • changeable_gas_price
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
              • changeable_nonce
                • sc_ws_optional_params_fail_close_mutual
                • sc_ws_optional_params_fail_close_solo
                • sc_ws_optional_params_fail_create
                • sc_ws_optional_params_fail_deposit
                • sc_ws_optional_params_fail_force_progress
                • sc_ws_optional_params_fail_settle
                • sc_ws_optional_params_fail_slash
                • sc_ws_optional_params_fail_snapshot
                • sc_ws_optional_params_fail_withdrawal
              • continuous
                • init_per_group
                • sc_ws_deposit
                • sc_ws_failed_update
                • sc_ws_generic_messages
                • sc_ws_ping_pong
                • sc_ws_update_conflict
                • sc_ws_withdraw
              • contracts
                • init_per_group
                • sc_ws_basic_contracts
                • sc_ws_environment_contract
                • sc_ws_nameservice_contract
                • sc_ws_oracle_contract
                • sc_ws_remote_call_contract
                • sc_ws_remote_call_contract_refering_onchain_data
                • sc_ws_wrong_call_data
              • force_progress
                • sc_ws_force_progress_based_on_offchain_state
                • sc_ws_force_progress_based_on_onchain_state
              • only_one_signs
                • init_per_group
                • sc_ws_conflict_on_new_offchain
                • sc_ws_conflict_snapshot_and_offchain_update
                • conflicts
                  • sc_ws_conflict_deposit_and_offchain_update
                  • sc_ws_conflict_two_deposits
                  • sc_ws_conflict_two_offchain_updates
                  • sc_ws_conflict_two_withdrawals
                  • sc_ws_conflict_withdrawal_and_deposit
                  • sc_ws_conflict_withdrawal_and_offchain_update
              • reconnect
                • sc_ws_basic_client_reconnect_i
                • sc_ws_basic_client_reconnect_i_w_reestablish
                • sc_ws_basic_client_reconnect_r
              • with_meta
                • init_per_group
                • sc_ws_deposit
                • sc_ws_remote_call_contract
                • sc_ws_withdraw
              • generalized_accounts
                • both
                  • sc_ws_basic_open_close
                • initiator
                  • sc_ws_basic_open_close
                • responder
                  • sc_ws_basic_open_close
  • Superhero Wallet
    • Changelog
    • Contributing & Guidelines
    • docs
      • Deep link URL Schema
    • .github
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
  • aerepl-web-bridge
    • AereplApi
    • aerepl_components
Powered by GitBook
On this page
  • Introduction
  • Name management flow
  • Verify availability
  • Preclaim
  • Claim
  • Update
  • Spend to name
  • Transfer ownership
  • Revoke

Was this helpful?

Export as PDF
  1. æternity protocol
  2. node
  3. æternity node API

Naming System - intended usage

PreviousMining - intended usageNextOracles - intended usage

Last updated 1 month ago

Was this helpful?

Introduction

The way to interact with Naming System is to use HTTP API. To read about possible states and life cycle of a name please see the doc.

The following assumes that the node exposes at address 127.0.0.1 the following ports:

  • User API external HTTP endpoint: 3013

  • User API internal HTTP endpoint: 3113

Name management flow

In order to work through the example we need the (Base58Check-encoded) public-private key pair of the account with positive balance.

Verify availability

Verify that the name that your going to claim is not taken using the /names/{name} endpoint. For the purpose of this example let's consider foobar.test name:

curl http://localhost:3013/v2/names/foobar.test
{"reason":"Name not found"}

Preclaim

In order to claim a name you need to submit a preclaim transaction first, containing commitment hash.

You need to pick a random salt value, to make commitment hash unique. Commitment hash is calculated based on . For the purpose of this example name foobar.test with salt 123 is considered. In order to obtain commitment hash use the /debug/names/commitment-id endpoint:

curl http://localhost:3113/v2/debug/names/commitment-id\?name\=foobar.test\&salt\=123
{"commitment_id":"cm_2ijL6NFZ11RsBVWwFB69oZYp6gFV9JSB71xccbnqrPisEiMrji"}

To preclaim a name:

  • prepare name preclaim transaction as per specification. In order to ease the initial integration, the æternity node provides/debug/names/preclaim endpoint:

curl -X POST -H "Content-Type: application/json" http://localhost:3113/v2/debug/names/preclaim -d '{"commitment_id":"cm_2ijL6NFZ11RsBVWwFB69oZYp6gFV9JSB71xccbnqrPisEiMrji", "fee": 1, "ttl":1234, "account_id":"ak_tjnw1KcmnwfqXvhtGa9GRjanbHM3t6PmEWEWtNMM3ouvNKRu5"}'
{"tx":"..."}
  • sign the prepared transaction (e.g. by using the SDK)

  • post the signed transaction using the /transactions endpoint

Mind that preclaim and claim transactions will not be accepted in the same generation, so please check that at least one key block is mined before submitting claim transaction. To check the height of the blockchain use the /generations/current endpoint.

Claim

When a name is preclaimed, you are in a position to claim it:

  • prepare name claim transaction as per specification. In order to ease the initial integration, the æternity node provides/debug/names/claim endpoint. You must use the name with the same salt as used in commitment hash computation. Note that the name should be API encoded in the same way as a name hash.

curl -X POST -H "Content-Type: application/json" http://localhost:3113/v2/debug/names/claim -d '{"name": ""nm_3sDdKewfAc1ektVJpwuTD", "name_salt": 123, "fee": 1, "ttl":1234, "account_id":"ak_tjnw1KcmnwfqXvhtGa9GRjanbHM3t6PmEWEWtNMM3ouvNKRu5"}'
{"tx":"..."}
  • sign the prepared transaction (e.g. by using the SDK)

  • post the signed transaction using the /transactions endpoint

After claiming the name (and claim transaction being accepted) you may verify name presence using the /names/{name} endpoint.

Note that the name is claimed for the max period (50000 blocks) and relative to the current height of chain.

Update

In order to make better use of claimed name you need to specify where it should point to. To do so, specify pointers, which translates to different blockchain entities. In the initial version the following well-known pointer keys are available:

  • account_pubkey

In order to update pointers:

  • prepare name update transaction as per specification. In order to ease the initial integration, the æternity node provides/debug/names/update endpoint:

curl -X POST -H "Content-Type: application/json" http://localhost:3113/v2/debug/names/update -d '{"name_id": "nm_2S4U3A6LGh2LASvbA1RgA6WVq9FDBCfEZK6FN5uL65MPVhiVGL", "name_ttl": 10000, "client_ttl": 50, "pointers":[{"key":"account_pubkey", "id":"ak_3scLu3oJbhsdCJkDjfJ6BUPJ4M9ZZJe57CQ56deSbEXhaTSfG3Wf3i2GYZV6APX7RDDVk4Weewb7oLePte3H3QdBw4rMZw"}], "fee": 1, "ttl":1234, "account_id":"ak_tjnw1KcmnwfqXvhtGa9GRjanbHM3t6PmEWEWtNMM3ouvNKRu5"}'
{"tx":"..."}
  • sign the prepared transaction (e.g. by using the SDK)

  • post the signed transaction using the /transactions endpoint

Note that name_ttl is relative to the current height of the chain. Here we shortened the claim.

Spend to name

Now you may use account and oracle pointers interchangeably with their addresses. In order to utilize account pubkey pointer, put a name instead of an account key, e.g. in spend transaction put it in recipient_id field:

curl -X POST -H "Content-Type: application/json" -d '{"sender_id":"...", "recipient_id":"foobar.test", "amount":2, "fee":1, "ttl":1234}' http://127.0.0.1:3113/v2/debug/transactions/spend

Transfer ownership

In order to transfer a name to another user:

  • prepare name transfer transaction as per specification. In order to ease the initial integration, the æternity node provides/debug/names/transfer endpoint:

curl -X POST -H "Content-Type: application/json" http://localhost:3113/v2/debug/names/transfer -d '{name_id": "nm_2S4U3A6LGh2LASvbA1RgA6WVq9FDBCfEZK6FN5uL65MPVhiVGL", "recipient_id": "ak_3scLu3oJbhsdCJkDjfJ6BUPJ4M9ZZJe57CQ56deSbEXhaTSfG3Wf3i2GYZV6APX7RDDVk4Weewb7oLePte3H3QdBw4rMZw", "account_id":"ak_tjnw1KcmnwfqXvhtGa9GRjanbHM3t6PmEWEWtNMM3ouvNKRu5", "fee": 1, "ttl":1234}'
{"tx":"..."}
  • sign the prepared transaction (e.g. by using the SDK)

  • post the signed transaction using the /transactions endpoint

Revoke

In order to revoke a name:

  • prepare name revoke transaction as per specification. In order to ease the initial integration, the æternity node provides/debug/names/revoke endpoint:

curl -X POST -H "Content-Type: application/json" http://localhost:3113/v2/debug/names/revoke -d '{"name_id": "nm_2S4U3A6LGh2LASvbA1RgA6WVq9FDBCfEZK6FN5uL65MPVhiVGL", "fee": 1, "ttl":1234, "account_id":"ak_tjnw1KcmnwfqXvhtGa9GRjanbHM3t6PmEWEWtNMM3ouvNKRu5"}'
{"tx":"..."}
  • sign the prepared transaction (e.g. by using the SDK)

  • post the signed transaction using the /transactions endpoint

the formula