Skip to content

Commit 1a963d1

Browse files
nduchaknduchak
authored
Merge pull request #871 from aeternity/release/7.0.0-next.3
Release 7.0.0-next.3
2 parents 59b977d + 1681754 commit 1a963d1

File tree

16 files changed

+473
-124
lines changed

16 files changed

+473
-124
lines changed

‎.env

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
NODE_TAG=v5.2.0
2-
COMPILER_TAG=v4.1.0
1+
NODE_TAG=v5.4.0
2+
COMPILER_TAG=v4.2.0

‎CHANGELOG.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
# [7.0.0-next.3](https://github.com/aeternity/aepp-sdk-js/compare/6.0.1...7.0.0-next.3) (2020-01-22)
2+
3+
4+
### Features
5+
6+
* **aens:** implement aensExtendTtl function. Refactor aensUpdate ([#866](https://github.com/aeternity/aepp-sdk-js/issues/866)) ([72b073a](https://github.com/aeternity/aepp-sdk-js/commit/72b073a)), closes [#865](https://github.com/aeternity/aepp-sdk-js/issues/865)
7+
> `aensUpdate` now accept array of pointers
8+
> `aensUpdate` have new option `extendPointers=false` which retrieve pointers from the node and merge with provided
9+
* **Build:** update node to `5.4.0` and compiler to `4.2.0`
10+
* **Guide** Add guide for `AENS` usage
11+
12+
### BREAKING CHANGES
13+
14+
* **AENS:** Change AENS methods arguments
15+
> Now all of AENS module methods accept `name` as a first argument instead of `nameId`
16+
17+
18+
119
# [7.0.0-next.2](https://github.com/aeternity/aepp-sdk-js/compare/6.0.1...7.0.0-next.2) (2020-01-10)
220

321

‎docs/README.md

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,20 @@ When initialising a client, to test, you can use Aeternity's Test Nework URLs:
3434
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.
3535

3636
## Guides
37-
### Browser
38-
- [**SDK usage** Understanding low vs high level](guides/low-vs-high-usage.md)
39-
- [Import SDK bundle with **`<script>`** tag](guides/import-script-tag.md)
40-
- [Import SDK **ES Modules** (enabling Tree-Shaking)](guides/import-tree-shaking.md)
41-
- [Import SDK in **VueJS**](guides/import-vuejs.md)
42-
### NodeJS Environment
43-
- [Import SDK in **NodeJS**](guides/import-nodejs.md)
37+
### Import SDK
38+
- Browser
39+
- [Import SDK bundle with **`<script>`** tag](guides/import-script-tag.md)
40+
- [Import SDK **ES Modules** (enabling Tree-Shaking)](guides/import-tree-shaking.md)
41+
- [Import SDK in **VueJS**](guides/import-vuejs.md)
42+
- NodeJS Environment
43+
- [Import SDK in **NodeJS**](guides/import-nodejs.md)
44+
45+
### SDK basics
46+
- [**SDK usage** Understanding low vs high level](guides/low-vs-high-usage.md)
47+
48+
### Contract Usage
49+
- [Contract ACI](guides/contract-aci-usage.md)
50+
- [AENS usage](guides/aens-usage.md)
4451

4552

4653
## Examples

‎docs/api/ae/aens.md

Lines changed: 117 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ import Aens from '@aeternity/aepp-sdk/es/ae/aens'
1616
* [Aens([options])](#exp_module_@aeternity/aepp-sdk/es/ae/aens--Aens) ⇒ `Object` ⏏
1717
* _instance_
1818
* _async_
19-
* [.update(nameId, target, options)](#exp_module_@aeternity/aepp-sdk/es/ae/aens--update) ⇒ `Object` ⏏
20-
* [.transfer(nameId, account, [options])](#exp_module_@aeternity/aepp-sdk/es/ae/aens--transfer) ⇒ `Promise.&lt;Object&gt;` ⏏
19+
* [.update(name, pointers, [options])](#exp_module_@aeternity/aepp-sdk/es/ae/aens--update) ⇒ `Promise.&lt;Object&gt;` ⏏
20+
* [.transfer(name, account, [options])](#exp_module_@aeternity/aepp-sdk/es/ae/aens--transfer) ⇒ `Promise.&lt;Object&gt;` ⏏
2121
* [.query(name, opt)](#exp_module_@aeternity/aepp-sdk/es/ae/aens--query) ⇒ `Promise.&lt;Object&gt;` ⏏
2222
* [.claim(name, salt, [options])](#exp_module_@aeternity/aepp-sdk/es/ae/aens--claim) ⇒ `Promise.&lt;Object&gt;` ⏏
2323
* [.preclaim(name, [options])](#exp_module_@aeternity/aepp-sdk/es/ae/aens--preclaim) ⇒ `Promise.&lt;Object&gt;` ⏏
@@ -41,45 +41,95 @@ Aens provides name-system related methods atop
4141

4242
<a id="exp_module_@aeternity/aepp-sdk/es/ae/aens--update"></a>
4343

44-
### .update(nameId, target, options) ⇒ `Object` ⏏
45-
Update an aens entry
44+
### .update(name, pointers, [options]) ⇒ `Promise.&lt;Object&gt;` ⏏
45+
Update a name
4646

4747
**Kind**: instance method of [`@aeternity/aepp-sdk/es/ae/aens`](#module_@aeternity/aepp-sdk/es/ae/aens)
4848
**Category**: async
49+
**Throws**:
4950

50-
| Param | Description |
51-
| --- | --- |
52-
| nameId | domain hash |
53-
| target | new target |
54-
| options | |
51+
- Invalid pointer array error
5552

53+
54+
| Param | Type | Default | Description |
55+
| --- | --- | --- | --- |
56+
| name | `String` | | AENS name |
57+
| pointers | `Array.&lt;String&gt;` | | Array of name pointers. Can be oracle|account|contract|channel public key |
58+
| [options] | `Object` | <code>{}</code> | |
59+
| [options.extendPointers] | `Boolean` | <code>false</code> | extendPointers Get the pointers from the node and merge with provided one. Pointers with the same type will be overwrited |
60+
| [options.onAccount] | `String` \| `Object` | | onAccount Make operation on specific account from sdk(you pass publickKey) or using provided KeyPair(Can be keypair object or MemoryAccount) |
61+
| [options.fee] | `Number` \| `String` \| `BigNumber` | | fee |
62+
| [options.ttl] | `Number` \| `String` \| `BigNumber` | | ttl |
63+
| [options.nonce] | `Number` \| `String` \| `BigNumber` | | nonce |
64+
| [options.nameTtl] | `Number` \| `String` \| `BigNumber` | <code>50000</code> | nameTtl Name ttl represented in number of blocks (Max value is 50000 blocks) |
65+
| [options.clientTtl] | `Number` \| `String` \| `BigNumber` | <code>84600</code> | clientTtl a suggestion as to how long any clients should cache this information |
66+
67+
**Example**
68+
```js
69+
const name = 'test.chain'
70+
const pointersArray = ['ak_asd23dasdas...,' 'ct_asdf34fasdasd...']
71+
const nameObject = await sdkInstance.aensQuery(name)
72+
73+
await sdkInstance.aensUpdate(name, pointersArray, { nameTtl, ttl, fee, nonce, clientTtl })
74+
// or
75+
await nameObject.update(pointersArray, { nameTtl, ttl, fee, nonce, clientTtl })
76+
```
5677
<a id="exp_module_@aeternity/aepp-sdk/es/ae/aens--transfer"></a>
5778

58-
### .transfer(nameId, account, [options]) ⇒ `Promise.&lt;Object&gt;` ⏏
79+
### .transfer(name, account, [options]) ⇒ `Promise.&lt;Object&gt;` ⏏
5980
Transfer a domain to another account
6081

6182
**Kind**: instance method of [`@aeternity/aepp-sdk/es/ae/aens`](#module_@aeternity/aepp-sdk/es/ae/aens)
83+
**Returns**: `Promise.&lt;Object&gt;` - Transaction result
6284
**Category**: async
6385

64-
| Param | Type | Default |
65-
| --- | --- | --- |
66-
| nameId | `String` | |
67-
| account | `String` | |
68-
| [options] | `Object` | <code>{}</code> |
86+
| Param | Type | Default | Description |
87+
| --- | --- | --- | --- |
88+
| name | `String` | | AENS name |
89+
| account | `String` | | Recipient account publick key |
90+
| [options] | `Object` | <code>{}</code> | |
91+
| [options.onAccount] | `String` \| `Object` | | onAccount Make operation on specific account from sdk(you pass publickKey) or using provided KeyPair(Can be keypair object or MemoryAccount) |
92+
| [options.fee] | `Number` \| `String` \| `BigNumber` | | fee |
93+
| [options.ttl] | `Number` \| `String` \| `BigNumber` | | ttl |
94+
| [options.nonce] | `Number` \| `String` \| `BigNumber` | | nonce |
95+
96+
**Example**
97+
```js
98+
const name = 'test.chain'
99+
const recipientPub = 'ak_asd23dasdas...'
100+
const nameObject = await sdkInstance.aensQuery(name)
69101

102+
await sdkInstance.aensTransfer(name, recipientPub, { ttl, fee, nonce })
103+
// or
104+
await nameObject.transfer(recipientPub, { ttl, fee, nonce })
105+
```
70106
<a id="exp_module_@aeternity/aepp-sdk/es/ae/aens--query"></a>
71107

72108
### .query(name, opt) ⇒ `Promise.&lt;Object&gt;` ⏏
73-
Query the status of an AENS registration
109+
Query the AENS name info from the node
110+
and return the object with info and predefined functions for manipulating name
74111

75112
**Kind**: instance method of [`@aeternity/aepp-sdk/es/ae/aens`](#module_@aeternity/aepp-sdk/es/ae/aens)
76113
**Category**: async
77114

78115
| Param | Type | Description |
79116
| --- | --- | --- |
80-
| name | `string` | |
117+
| name | `String` | |
81118
| opt | `Object` | Options |
82119

120+
**Example**
121+
```js
122+
const nameObject = sdkInstance.aensQuery('test.chain')
123+
console.log(nameObject)
124+
{
125+
id, // name hash
126+
pointers, // array of pointers
127+
update, // Update name function
128+
extendTtl, // Extend Ttl name function
129+
transfer, // Transfer name function
130+
revoke // Revoke name function
131+
}
132+
```
83133
<a id="exp_module_@aeternity/aepp-sdk/es/ae/aens--claim"></a>
84134

85135
### .claim(name, salt, [options]) ⇒ `Promise.&lt;Object&gt;` ⏏
@@ -93,10 +143,22 @@ preclaim step
93143
| Param | Type | Default | Description |
94144
| --- | --- | --- | --- |
95145
| name | `String` | | |
96-
| salt | `Number` | | |
97-
| [options] | `Record` | <code>{}</code> | |
98-
| [options.nameFee] | `Number` \| `String` | | Name Fee |
146+
| salt | `Number` | | Salt from pre-claim, or 0 if it's a bid |
147+
| [options] | `Object` | <code>{}</code> | options |
148+
| [options.onAccount] | `String` \| `Object` | | onAccount Make operation on specific account from sdk(you pass publickKey) or using provided KeyPair(Can be keypair object or MemoryAccount) |
149+
| [options.fee] | `Number` \| `String` \| `BigNumber` | | fee |
150+
| [options.ttl] | `Number` \| `String` \| `BigNumber` | | ttl |
151+
| [options.nonce] | `Number` \| `String` \| `BigNumber` | | nonce |
152+
| [options.nameFee] | `Number` \| `String` | | Name Fee (By default calculated by sdk) |
153+
| [options.vsn] | `Number` \| `String` | <code>2</code> | Transaction vsn from Lima is 2 |
154+
155+
**Example**
156+
```js
157+
const name = 'test.chain'
158+
const salt = preclaimResult.salt // salt from pre-claim transaction
99159

160+
await sdkInstance.aensClaim(name, salt, { ttl, fee, nonce, nameFee })
161+
```
100162
<a id="exp_module_@aeternity/aepp-sdk/es/ae/aens--preclaim"></a>
101163

102164
### .preclaim(name, [options]) ⇒ `Promise.&lt;Object&gt;` ⏏
@@ -105,22 +167,51 @@ Preclaim a name. Sends a hash of the name and a random salt to the node
105167
**Kind**: instance method of [`@aeternity/aepp-sdk/es/ae/aens`](#module_@aeternity/aepp-sdk/es/ae/aens)
106168
**Category**: async
107169

108-
| Param | Type | Default |
109-
| --- | --- | --- |
110-
| name | `string` | |
111-
| [options] | `Record` | <code>{}</code> |
170+
| Param | Type | Default | Description |
171+
| --- | --- | --- | --- |
172+
| name | `String` | | |
173+
| [options] | `Object` | <code>{}</code> | |
174+
| [options.onAccount] | `String` \| `Object` | | onAccount Make operation on specific account from sdk(you pass publickKey) or using provided KeyPair(Can be keypair object or MemoryAccount) |
175+
| [options.fee] | `Number` \| `String` \| `BigNumber` | | fee |
176+
| [options.ttl] | `Number` \| `String` \| `BigNumber` | | ttl |
177+
| [options.nonce] | `Number` \| `String` \| `BigNumber` | | nonce |
112178

179+
**Example**
180+
```js
181+
const name = 'test.chain'
182+
const salt = preclaimResult.salt // salt from pre-claim transaction
183+
184+
await sdkInstance.aensPreclaim(name, { ttl, fee, nonce })
185+
{
186+
...transactionResult,
187+
claim, // Claim function (options={}) => claimTransactionResult
188+
salt,
189+
commitmentId
190+
}
191+
```
113192
<a id="exp_module_@aeternity/aepp-sdk/es/ae/aens--bid"></a>
114193

115194
### .bid(name, nameFee, [options]) ⇒ `Promise.&lt;Object&gt;` ⏏
116195
Bid to name auction
117196

118197
**Kind**: instance method of [`@aeternity/aepp-sdk/es/ae/aens`](#module_@aeternity/aepp-sdk/es/ae/aens)
198+
**Returns**: `Promise.&lt;Object&gt;` - Transaction result
119199
**Category**: async
120200

121201
| Param | Type | Default | Description |
122202
| --- | --- | --- | --- |
123203
| name | `String` | | Domain name |
124-
| nameFee | `String` \| `Number` | | Name fee amount |
125-
| [options] | `Record` | <code>{}</code> | |
204+
| nameFee | `String` \| `Number` | | Name fee (bid fee) |
205+
| [options] | `Object` | <code>{}</code> | |
206+
| [options.onAccount] | `String` \| `Object` | | onAccount Make operation on specific account from sdk(you pass publickKey) or using provided KeyPair(Can be keypair object or MemoryAccount) |
207+
| [options.fee] | `Number` \| `String` \| `BigNumber` | | fee |
208+
| [options.ttl] | `Number` \| `String` \| `BigNumber` | | ttl |
209+
| [options.nonce] | `Number` \| `String` \| `BigNumber` | | nonce |
126210

211+
**Example**
212+
```js
213+
const name = 'test.chain'
214+
const bidFee = computeBidFee(name, startFee, incrementPercentage)
215+
216+
await sdkInstance.aensBid(name, 213109412839123, { ttl, fee, nonce })
217+
```

‎docs/guides/aens-usage.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# AENS Usage
2+
3+
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)
4+
5+
## Main Flow
6+
7+
- Pre-claim name (broadcast `pre-claim` transaction with random `salt`)
8+
```js
9+
const sdkInstance = await Universal({ ... }) // Init Universal instance
10+
11+
const name = 'sometube.chain'
12+
13+
const preclaim = await sdkInstance.aensPreclaim(name, { ttl, fee, nonce })
14+
// {
15+
// ...transactionResult,
16+
// salt,
17+
// commitmentId
18+
// }
19+
```
20+
>After transaction is included, you have a `300` blocks to broadcast `claim` transaction with
21+
the same `salt` and it should be signed with the same private key as `pre-claim`
22+
23+
- Claim name (broadcast `claim` transaction which include the `salt` of `pre-claim`)
24+
here, we have two possible scenarios:
25+
- `Name length` <= 12: start name `auction`
26+
- `Name length` > 12: name is claimed without `auction`
27+
```js
28+
const salt = preclaim.salt // salt from pre-claim transaction
29+
const options = { ttl, fee, nonce, nameFee, onAccount } // optional: overriding default
30+
31+
// In case of starting the auction `nameFee` will be the starting bid
32+
// The minimum `nameFee` will be generated by sdk if is not provided in options
33+
const claim = await sdkInstance.aensClaim(name, salt, options)
34+
35+
36+
// In case of auction you may need to place a bid on already started auction
37+
// Currently sdk can't generate the `bid fee` automatically
38+
// as it's depend on last bid
39+
import { computeBidFee, computeAuctionEndBlock } from '@aeternity/aepp-sdk/es/tx/builder/helpers'
40+
41+
const startFee = claim.nameFee // start bid
42+
const increment = 0.05 // 5%
43+
44+
const nameFee = computeBidFee(name, startFee, increment)
45+
const bid = await sdkInstance.aensBid(name, nameFee, options)
46+
47+
console.log(`BID STARTED AT ${bid.blockHeight} WILL END AT ${computeAuctionEndBlock(name, bid.blockHeight)}`)
48+
```
49+
50+
- Update name
51+
Using `aens-update` transaction you can update the name `pointers` and extend name `ttl`
52+
```js
53+
const options = { ttl, fee, nonce, nameTtl, onAccount } // optional: overriding default
54+
const pointersArray = ['ak_asd23dasdas...,', 'ct_asdf34fasdasd...']
55+
const nameObject = await sdkInstance.aensQuery(name)
56+
57+
await sdkInstance.aensUpdate(name, pointersArray, options)
58+
// or
59+
await nameObject.update(pointersArray, options)
60+
61+
// Extend pointers of name entry
62+
// Let's assume that we have name entry with one pointers: ['ak_2314234']
63+
// Only one entry for each type is allowed
64+
// that mean that merging will overwrite pointers with the same type
65+
await sdkInstance.aensUpdate(name, pointersArray, { extendPointers: true })
66+
```
67+
68+
- Transfer
69+
Transfer the name `ownership` to another `account`
70+
```js
71+
const options = { ttl, fee, nonce, onAccount }
72+
const recipientPub = 'ak_asd23dasdas...'
73+
const nameObject = await sdkInstance.aensQuery(name)
74+
75+
await sdkInstance.aensTransfer(name, recipientPub, options)
76+
// or
77+
await nameObject.transfer(recipientPub, options)
78+
```
79+
- Revoke
80+
Revoke the name
81+
```js
82+
const options = { ttl, fee, nonce, onAccount }
83+
const nameObject = await sdkInstance.aensQuery(name)
84+
85+
await sdkInstance.aensRevoke(name, options)
86+
// or
87+
await nameObject.revoke(options)
88+
```
89+
90+
## Related links
91+
- [AENS protocol](https://github.com/aeternity/protocol/blob/master/AENS.md)
92+
- [AENS SDK API Docs](https://github.com/aeternity/aepp-sdk-js/blob/develop/docs/api/ae/aens.md)
93+

‎docs/guides/import-nodejs.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@ Promise.all([
2020
// node2
2121
],
2222
compilerUrl: 'COMPILER_URL',
23-
// instead use
2423
accounts: [
2524
acc1,
2625
// acc2

0 commit comments

Comments
 (0)