Docs/adjust guides (#861)

* docs(RPC): Adjust index section of guides(Add link to contract usage guide) Fix and adjust basic SDK usage gudie * fix(example): Fix extension sdk path * docs(guide): AENS guide draft Return `nameFee` in `aensClaim` * docs(guide): AENS guide: Update AENS * docs(guide): Add AENS `transfer` and `revoke` * chore(PR): Fix PR comments * docs(guide): Add AENS links to index guide section Co-authored-by: Shubhendu Shekhar <[email protected]>
aeternity · Jan 21, 2020 · 8feec4d · 8feec4d
1 parent 445e15c
commit 8feec4d
Show file tree

Hide file tree

Showing 6 changed files with 128 additions and 29 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -34,13 +34,20 @@ When initialising a client, to test, you can use Aeternity's Test Nework URLs:
 You can use this URL with any releasee on [npmjs](https://www.npmjs.com/package/@aeternity/aepp-sdk). It offers the last stable version of [Node](https://github.com/aeternity/aeternity), used by all of of Aeternity's Dev Tools.
 
 ## Guides
-### Browser
-  - [**SDK usage** Understanding low vs high level](guides/low-vs-high-usage.md)
-  - [Import SDK bundle with **`<script>`** tag](guides/import-script-tag.md)
-  - [Import SDK **ES Modules** (enabling Tree-Shaking)](guides/import-tree-shaking.md)
-  - [Import SDK in **VueJS**](guides/import-vuejs.md)
-### NodeJS Environment
-  - [Import SDK in **NodeJS**](guides/import-nodejs.md)
+### Import SDK
+  - Browser
+    - [Import SDK bundle with **`<script>`** tag](guides/import-script-tag.md)
+    - [Import SDK **ES Modules** (enabling Tree-Shaking)](guides/import-tree-shaking.md)
+    - [Import SDK in **VueJS**](guides/import-vuejs.md)
+  - NodeJS Environment
+    - [Import SDK in **NodeJS**](guides/import-nodejs.md)
+
+### SDK basics
+   - [**SDK usage** Understanding low vs high level](guides/low-vs-high-usage.md)
+
+### Contract Usage
+ - [Contract ACI](guides/contract-aci-usage.md)
+ - [AENS usage](guides/aens-usage.md)
 
 
 ## Examples

diff --git a/docs/guides/aens-usage.md b/docs/guides/aens-usage.md
@@ -0,0 +1,93 @@
+# 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)
+
+## 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)
+     ```
+
+## 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)
+
diff --git a/docs/guides/import-nodejs.md b/docs/guides/import-nodejs.md
@@ -20,7 +20,6 @@ Promise.all([
         // node2
       ],
       compilerUrl: 'COMPILER_URL',
-      // instead use
       accounts: [
         acc1,
         // acc2

diff --git a/docs/guides/low-vs-high-usage.md b/docs/guides/low-vs-high-usage.md
@@ -21,25 +21,22 @@ Promises framework makes this somewhat easy:
 Example spend function, using aeternity's SDK abstraction
 ```js
   // Import necessary Modules by simply importing the Wallet module
-  import Wallet from '@aeternity/aepp-sdk/es/ae/wallet' // import from SDK es-modules
+  import Universal from '@aeternity/aepp-sdk/es/ae/wallet' // import from SDK es-modules
   import Node from '@aeternity/aepp-sdk/es/node' // import from SDK es-modules
 
-  // const node1 = await Node({ url, internalUrl })
-
-  Wallet({
-    nodes: [
-        // { name: 'someNode', instance: node1 },
-        // mode2
-    ],    
-    compilerUrl: 'COMPILER_URL_HERE',
-    accounts: [MemoryAccount({keypair: {secretKey: 'PRIV_KEY_HERE', publicKey: 'PUB_KEY_HERE'}, networkId: 'NETWORK_ID_HERE'})],
-    address: 'PUB_KEY_HERE',
-    onTx: confirm, // guard returning boolean
-    onChain: confirm, // guard returning boolean
-    onAccount: confirm, // guard returning boolean
-    onContract: confirm, // guard returning boolean
-    networkId: 'ae_uat' // or any other networkId your client should connect to
-  }).then(ae => ae.spend(parseInt(amount), receiver_pub_key))
+  async function init () {
+    const node = await Node({ url, internalUrl })
+
+    const sdkInstance = await Universal({
+        nodes: [{ name: 'test-net-node', instance: node }],    
+        compilerUrl: 'COMPILER_URL_HERE',
+        accounts: [MemoryAccount({keypair: {secretKey: 'PRIV_KEY_HERE', publicKey: 'PUB_KEY_HERE'}})],
+        address: 'SELECTED_ACCOUNT_PUB_KEY_HERE',
+      })
+   // Spend transaction info 
+   console.log(await sdkInstance.spend(parseInt(amount), 'RECEIVER_PUB_KEY'))
+  }
+
 ```
 
 ### Low-level SDK usage (use [API](https://github.com/aeternity/protocol/tree/master/node/api) endpoints directly)
@@ -49,11 +46,14 @@ Example spend function, using the SDK, talking directly to the [**API**](https:/
   import Tx from '@aeternity/aepp-sdk/es/tx/tx.js'
   import Chain from '@aeternity/aepp-sdk/es/chain/node.js'
   import Account from '@aeternity/aepp-sdk/es/account/memory.js'
+  import Node from '@aeternity/aepp-sdk/es/node' // import from SDK es-modules
 
   async function spend (amount, receiver_pub_key) {
+    const node = await Node({ url, internalUrl })
+    const nodes = [{ name: 'testnet-node', instance: node }]
 
-    const tx = await Tx({url: 'HOST_URL_HERE', internalUrl: 'HOST_URL_HERE'})
-    const chain = await Chain({url: 'HOST_URL_HERE', internalUrl: 'HOST_URL_HERE'})
+    const tx = await Tx({ nodes })
+    const chain = await Chain({ nodes })
     const account = Account({keypair: {secretKey: 'PRIV_KEY_HERE', publicKey: 'PUB_KEY_HERE'}, networkId: 'NETWORK_ID_HERE'})
     const spendTx = await tx.spendTx({ sender: 'PUB_KEY_HERE', receiver_pub_key, amount })
 

diff --git a/es/ae/aens.js b/es/ae/aens.js
@@ -253,7 +253,7 @@ async function claim (name, salt, options = { vsn: 2 }) {
     const nameInter = opt.waitMined ? await this.aensQuery(name, opt) : {}
     return Object.assign(result, nameInter)
   }
-  return result
+  return { ...result, nameFee: opt.nameFee }
 }
 
 /**

diff --git a/examples/browser/extension/package.json b/examples/browser/extension/package.json
@@ -21,6 +21,6 @@
     "write-file-webpack-plugin": "4.5.0"
   },
   "dependencies": {
-    "@aeternity/aepp-sdk": "https://github.com/aeternity/aepp-sdk-js#feat/switch-to-post-message-for-extension"
+    "@aeternity/aepp-sdk": "7.0.0-next.2"
   }
 }