-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
aens-usage: Use more semantic markup, compatible with mkdocs
- Loading branch information
Showing
1 changed file
with
91 additions
and
88 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,93 +1,96 @@ | ||
| # AENS Usage | ||
|
|
||
| This guide describes the basic operations on [AENS name](https://github.com/aeternity/protocol/blob/master/AENS.md) using [Aeternity JS SDK](https://github.com/aeternity/aepp-sdk-js) | ||
|
|
||
| This guide describes the basic operations on | ||
| [AENS name](https://github.com/aeternity/protocol/blob/master/AENS.md) using | ||
| [Aeternity JS SDK](https://github.com/aeternity/aepp-sdk-js) | ||
|
|
||
| ## Main Flow | ||
|
|
||
| - Pre-claim name (broadcast `pre-claim` transaction with random `salt`) | ||
| ```js | ||
| const sdkInstance = await Universal({ ... }) // Init Universal instance | ||
|
|
||
| const name = 'sometube.chain' | ||
|
|
||
| const preclaim = await sdkInstance.aensPreclaim(name, { ttl, fee, nonce }) | ||
| // { | ||
| // ...transactionResult, | ||
| // salt, | ||
| // commitmentId | ||
| // } | ||
| ``` | ||
| >After transaction is included, you have a `300` blocks to broadcast `claim` transaction with | ||
| the same `salt` and it should be signed with the same private key as `pre-claim` | ||
|
|
||
| - Claim name (broadcast `claim` transaction which include the `salt` of `pre-claim`) | ||
| here, we have two possible scenarios: | ||
| - `Name length` <= 12: start name `auction` | ||
| - `Name length` > 12: name is claimed without `auction` | ||
| ```js | ||
| const salt = preclaim.salt // salt from pre-claim transaction | ||
| const options = { ttl, fee, nonce, nameFee, onAccount } // optional: overriding default | ||
|
|
||
| // In case of starting the auction `nameFee` will be the starting bid | ||
| // The minimum `nameFee` will be generated by sdk if is not provided in options | ||
| const claim = await sdkInstance.aensClaim(name, salt, options) | ||
|
|
||
|
|
||
| // In case of auction you may need to place a bid on already started auction | ||
| // Currently sdk can't generate the `bid fee` automatically | ||
| // as it's depend on last bid | ||
| import { computeBidFee, computeAuctionEndBlock } from '@aeternity/aepp-sdk/es/tx/builder/helpers' | ||
|
|
||
| const startFee = claim.nameFee // start bid | ||
| const increment = 0.05 // 5% | ||
|
|
||
| const nameFee = computeBidFee(name, startFee, increment) | ||
| const bid = await sdkInstance.aensBid(name, nameFee, options) | ||
|
|
||
| console.log(`BID STARTED AT ${bid.blockHeight} WILL END AT ${computeAuctionEndBlock(name, bid.blockHeight)}`) | ||
| ``` | ||
|
|
||
| - Update name | ||
| Using `aens-update` transaction you can update the name `pointers` and extend name `ttl` | ||
| ```js | ||
| const options = { ttl, fee, nonce, nameTtl, onAccount } // optional: overriding default | ||
| const pointersArray = ['ak_asd23dasdas...,', 'ct_asdf34fasdasd...'] | ||
| const nameObject = await sdkInstance.aensQuery(name) | ||
| await sdkInstance.aensUpdate(name, pointersArray, options) | ||
| // or | ||
| await nameObject.update(pointersArray, options) | ||
| // Extend pointers of name entry | ||
| // Let's assume that we have name entry with one pointers: ['ak_2314234'] | ||
| // Only one entry for each type is allowed | ||
| // that mean that merging will overwrite pointers with the same type | ||
| await sdkInstance.aensUpdate(name, pointersArray, { extendPointers: true }) | ||
| ``` | ||
|
|
||
| - Transfer | ||
| Transfer the name `ownership` to another `account` | ||
| ```js | ||
| const options = { ttl, fee, nonce, onAccount } | ||
| const recipientPub = 'ak_asd23dasdas...' | ||
| const nameObject = await sdkInstance.aensQuery(name) | ||
| await sdkInstance.aensTransfer(name, recipientPub, options) | ||
| // or | ||
| await nameObject.transfer(recipientPub, options) | ||
| ``` | ||
| - Revoke | ||
| Revoke the name | ||
| ```js | ||
| const options = { ttl, fee, nonce, onAccount } | ||
| const nameObject = await sdkInstance.aensQuery(name) | ||
| await sdkInstance.aensRevoke(name, options) | ||
| // or | ||
| await nameObject.revoke(options) | ||
| ``` | ||
|
|
||
| ### Pre-claim name | ||
| Broadcast `pre-claim` transaction with random `salt`. | ||
| ```js | ||
| const sdkInstance = await Universal({ ... }) // Init Universal instance | ||
|
|
||
| const name = 'sometube.chain' | ||
|
|
||
| const preclaim = await sdkInstance.aensPreclaim(name, { ttl, fee, nonce }) | ||
| // { | ||
| // ...transactionResult, | ||
| // salt, | ||
| // commitmentId | ||
| // } | ||
| ``` | ||
| After transaction is included, you have `300` blocks to broadcast `claim` transaction with | ||
| the same `salt` and it should be signed with the same private key as `pre-claim`. | ||
|
|
||
| ### Claim name | ||
| Broadcast `claim` transaction which include the `salt` of `pre-claim`. | ||
| Here, we have two possible scenarios: | ||
| - `Name length` <= 12: start name `auction` | ||
| - `Name length` > 12: name is claimed without `auction` | ||
| ```js | ||
| const salt = preclaim.salt // salt from pre-claim transaction | ||
| const options = { ttl, fee, nonce, nameFee, onAccount } // optional: overriding default | ||
|
|
||
| // In case of starting the auction `nameFee` will be the starting bid | ||
| // The minimum `nameFee` will be generated by sdk if is not provided in options | ||
| const claim = await sdkInstance.aensClaim(name, salt, options) | ||
|
|
||
|
|
||
| // In case of auction you may need to place a bid on already started auction | ||
| // Currently sdk can't generate the `bid fee` automatically | ||
| // as it's depend on last bid | ||
| import { computeBidFee, computeAuctionEndBlock } from '@aeternity/aepp-sdk/es/tx/builder/helpers' | ||
|
|
||
| const startFee = claim.nameFee // start bid | ||
| const increment = 0.05 // 5% | ||
|
|
||
| const nameFee = computeBidFee(name, startFee, increment) | ||
| const bid = await sdkInstance.aensBid(name, nameFee, options) | ||
|
|
||
| console.log(`BID STARTED AT ${bid.blockHeight} WILL END AT ${computeAuctionEndBlock(name, bid.blockHeight)}`) | ||
| ``` | ||
|
|
||
| ### Update name | ||
| Using `aens-update` transaction you can update the name `pointers` and extend name `ttl`. | ||
| ```js | ||
| const options = { ttl, fee, nonce, nameTtl, onAccount } // optional: overriding default | ||
| const pointersArray = ['ak_asd23dasdas...,', 'ct_asdf34fasdasd...'] | ||
| const nameObject = await sdkInstance.aensQuery(name) | ||
|
|
||
| await sdkInstance.aensUpdate(name, pointersArray, options) | ||
| // or | ||
| await nameObject.update(pointersArray, options) | ||
|
|
||
| // Extend pointers of name entry | ||
| // Let's assume that we have name entry with one pointers: ['ak_2314234'] | ||
| // Only one entry for each type is allowed | ||
| // that mean that merging will overwrite pointers with the same type | ||
| await sdkInstance.aensUpdate(name, pointersArray, { extendPointers: true }) | ||
| ``` | ||
|
|
||
| ### Transfer | ||
| Transfer the name `ownership` to another `account`. | ||
| ```js | ||
| const options = { ttl, fee, nonce, onAccount } | ||
| const recipientPub = 'ak_asd23dasdas...' | ||
| const nameObject = await sdkInstance.aensQuery(name) | ||
|
|
||
| await sdkInstance.aensTransfer(name, recipientPub, options) | ||
| // or | ||
| await nameObject.transfer(recipientPub, options) | ||
| ``` | ||
|
|
||
| ### Revoke name | ||
| ```js | ||
| const options = { ttl, fee, nonce, onAccount } | ||
| const nameObject = await sdkInstance.aensQuery(name) | ||
|
|
||
| await sdkInstance.aensRevoke(name, options) | ||
| // or | ||
| await nameObject.revoke(options) | ||
| ``` | ||
|
|
||
| ## Related links | ||
| - [AENS protocol](https://github.com/aeternity/protocol/blob/master/AENS.md) | ||
| - [AENS SDK API Docs](https://github.com/aeternity/aepp-sdk-js/blob/develop/docs/api/ae/aens.md) | ||
|
|
||
| - [AENS protocol](https://github.com/aeternity/protocol/blob/master/AENS.md) | ||
| - [AENS SDK API Docs](https://github.com/aeternity/aepp-sdk-js/blob/develop/docs/api/ae/aens.md) |