Naming System - intended usage
Last updated
Was this helpful?
Last updated
Was this helpful?
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
In order to work through the example we need the (Base58Check-encoded) public-private key pair of the account with positive balance.
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:
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:
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:
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.
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.
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.
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:
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.
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:
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:
sign the prepared transaction (e.g. by using the SDK)
post the signed transaction using the /transactions endpoint
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:
sign the prepared transaction (e.g. by using the SDK)
post the signed transaction using the /transactions endpoint