1 | # [Æternity](https://aeternity.com/)'s Javascript SDK
|
2 |
|
3 | [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/aeternity/aepp-sdk-js.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/aeternity/aepp-sdk-js/context:javascript)
|
4 | [![codecov](https://codecov.io/gh/aeternity/aepp-sdk-js/branch/develop/graph/badge.svg)](https://codecov.io/gh/aeternity/aepp-sdk-js)
|
5 | [![Build Status](https://travis-ci.com/aeternity/aepp-sdk-js.svg?branch=develop)](http://travis-ci.com/aeternity/aepp-sdk-js?branch=develop)
|
6 | [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
|
7 | [![npm](https://img.shields.io/npm/v/@aeternity/aepp-sdk.svg)](https://www.npmjs.com/package/@aeternity/aepp-sdk)
|
8 | [![npm](https://img.shields.io/npm/l/@aeternity/aepp-sdk.svg)](https://www.npmjs.com/package/@aeternity/aepp-sdk)
|
9 | [![Greenkeeper badge](https://badges.greenkeeper.io/aeternity/aepp-sdk-js.svg)](https://greenkeeper.io/)
|
10 | JavaScript SDK for the revolutionary [æternity] blockchain, targeting the
|
11 | [æternity node] implementation. Aepp-sdk is [hosted on GitHub].
|
12 |
|
13 | [æternity]: https://aeternity.com/
|
14 | [æternity node]: https://github.com/aeternity/aeternity
|
15 | [hosted on GitHub]: https://github.com/aeternity/aepp-sdk-js
|
16 |
|
17 | [develop branch]: https://github.com/aeternity/aepp-sdk-js/tree/develop
|
18 |
|
19 | ## Table of content
|
20 | - [Æternity's Javascript SDK](#%C3%86ternitys-Javascript-SDK)
|
21 | - [Table of content](#Table-of-content)
|
22 | - [Quick Start](#Quick-Start)
|
23 | - [1. Install SDK](#1-Install-SDK)
|
24 | - [A) Simple Usage: with `<script>` tag](#A-Simple-Usage-with-script-tag)
|
25 | - [B) Advanced Usage: with `npm` or similar](#B-Advanced-Usage-with-npm-or-similar)
|
26 | - [2. Create an Account](#2-Create-an-Account)
|
27 | - [A) Using the Command Line](#A-Using-the-Command-Line)
|
28 | - [B) Using the SDK](#B-Using-the-SDK)
|
29 | - [3. Give yourself some _AE_ tokens](#3-Give-yourself-some-AE-tokens)
|
30 | - [4. Import (a chosen Flavor)](#4-Import-a-chosen-Flavor)
|
31 | - [5. Play with Aetenity's blockchain features](#5-Play-with-Aetenitys-blockchain-features)
|
32 | - [More: Guides & Examples](#More-Guides--Examples)
|
33 | - [CLI - Command Line Client](#CLI---Command-Line-Client)
|
34 | - [Contributing](#Contributing)
|
35 | - [Change Log](#Change-Log)
|
36 | - [License](#License)
|
37 |
|
38 | ## Quick Start
|
39 |
|
40 | ### 1. Install SDK
|
41 | #### A) Simple Usage: with `<script>` tag
|
42 | For those not using any JS bundling/complilation or compilation technique or tools like [_Codepen_](https://codepen.io/pen/) or similar online Editors, please check our [**Import SDK bundle with `<script>` tag**](docs/guides/import-script-tag.md).
|
43 |
|
44 | If you're using bundling/compilation techniques (eg. `webpack`), please continue reading.
|
45 |
|
46 | #### B) Advanced Usage: with `npm` or similar
|
47 | Add the latest `@aeternity/aepp-sdk` release from npmjs.com to your project using one of these commands
|
48 |
|
49 | ```bash
|
50 | # install using npm...or yarn or pnpm
|
51 | npm i @aeternity/aepp-sdk
|
52 | ```
|
53 |
|
54 | **Note:** To install a _Pre-Release_ (latest `beta` or `alpha` version) using on the latest Node version, you have to install the package appending the `@next` tag reference, or even use the `#` symbol and the Repo URL to install a version coming from a specific branch.
|
55 | ```bash
|
56 | # install the @next version of the SDK
|
57 | npm i @aeternity/aepp-sdk@next
|
58 |
|
59 | # install the #develop version of the SDK
|
60 | npm i https://github.com/aeternity/aepp-sdk-js#develop
|
61 | ```
|
62 |
|
63 | **Note** : If you experience errors during the installation, you might need to install build tools for your OS.
|
64 |
|
65 | Windows: Windows Build Tools
|
66 | ```
|
67 | npm install -g windows-build-tools
|
68 | ```
|
69 | Ubuntu / Debian: Build Essential
|
70 | ```
|
71 | sudo apt-get update
|
72 | sudo apt-get install build-essential
|
73 | ```
|
74 | Mac:
|
75 | Download [Xcode](https://apps.apple.com/de/app/xcode/id497799835?mt=12) from AppStore, then run
|
76 | ```
|
77 | xcode-select --install
|
78 | ```
|
79 |
|
80 | ### 2. Create an Account
|
81 | You can do many more things now, but you'll probably have to start with:
|
82 |
|
83 | #### A) Using the Command Line
|
84 | Create an account using the [💻 CLI](#cli---command-line-client)
|
85 |
|
86 | #### B) Using the SDK
|
87 |
|
88 | ```javascript
|
89 | import { Crypto } from '@aeternity/aepp-sdk/es'
|
90 | const keypair = Crypto.generateKeyPair()
|
91 | console.log(`Secret key: ${keypair.secretKey}`)
|
92 | console.log(`Public key: ${keypair.publicKey}`)
|
93 | ```
|
94 |
|
95 | ### 3. Give yourself some _AE_ tokens
|
96 | To get yourself some _AEs_ you can use the [🚰 Faucet Aepp](https://faucet.aepps.com/). Just add your publicKey, and you'll immediately get some test tokens.
|
97 |
|
98 |
|
99 | ### 4. Import (a chosen Flavor)
|
100 |
|
101 | Import the right [flavor](docs/README.md#flavors--entry-points). For this example with get the `Universal` flavor, which contains all the features of the SDK:
|
102 |
|
103 | ```js
|
104 | // Import Flavor
|
105 | import Ae from '@aeternity/aepp-sdk/es/ae/universal' // or other flavor
|
106 | ```
|
107 |
|
108 | ### 5. Play with Aetenity's blockchain features
|
109 |
|
110 | ```js
|
111 | // Use Flavor
|
112 | import Ae from '@aeternity/aepp-sdk/es/ae/universal' // or other flavor
|
113 | import MemoryAccount from '@aeternity/aepp-sdk/es/account/memory' // or other flavor
|
114 | import Node from '@aeternity/aepp-sdk/es/node' // or other flavor
|
115 | import { AE_AMOUNT_FORMATS } from '@aeternity/aepp-sdk/es/utils/amount-formatter'
|
116 |
|
117 | const NODE_URL = 'https://sdk-testnet.aepps.com'
|
118 | const COMPILER_URL = 'COMPILER_URL' // required for using Contract
|
119 | const ACCOUNT = MemoryAccount({ keypair: { secretKey: 'A_PRIV_KEY', publicKey: 'A_PUB_ADDRESS' } })
|
120 |
|
121 | (async function () {
|
122 | const nodeInstance = await Node({ url: NODE_URL })
|
123 | const sdkInstance = await Ae({
|
124 | compilerUrl: COMPILER_URL,
|
125 | nodes: [ { name: 'test-net', instance: nodeInstance } ],
|
126 | accounts: [ ACCOUNT ]
|
127 | })
|
128 |
|
129 | await sdkInstance.height() // get top block height
|
130 | console.log('Current Block Height:', height)
|
131 |
|
132 | await sdkInstance.spend(1, 'ak_asd23dasdasda...', { denomination: AE_AMOUNT_FORMATS.AE }) // spend one AE
|
133 |
|
134 | })()
|
135 | ```
|
136 |
|
137 | ## More: Guides & Examples
|
138 |
|
139 | Check out our [Guides](docs/README.md) and [Examples](examples/README.md).
|
140 |
|
141 | ## CLI - Command Line Client
|
142 |
|
143 | To quickly test _all_ of Aeternity's blockchain features from your Terminal, you can Install and use our **NodeJS [CLI](https://github.com/aeternity/aepp-cli-js)** by running:
|
144 |
|
145 | 1. `npm i -g @aeternity/aepp-cli` to globally install the CLI
|
146 | 2. `aecli --help` to get a list of possible commands
|
147 |
|
148 | _eg._ Create an Account:
|
149 |
|
150 | `aecli account create testWhateverAccountName`
|
151 |
|
152 | ## Contributing
|
153 |
|
154 | For advanced use, to get a deeper understanding of the SDK or to contribute to its development, it is advised to read the [Contributing Guidelines](docs/contrib/README.md) section.
|
155 |
|
156 | ## Change Log
|
157 |
|
158 | We keep our [Changelog](CHANGELOG.md) up to date.
|
159 |
|
160 | ## License
|
161 |
|
162 | ISC License (ISC)
|
163 | Copyright © 2018 aeternity developers
|
164 |
|
165 | Permission to use, copy, modify, and/or distribute this software for any purpose
|
166 | with or without fee is hereby granted, provided that the above copyright notice
|
167 | and this permission notice appear in all copies.
|
168 |
|
169 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
170 | REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
171 | FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
172 | INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
|
173 | OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
|
174 | TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
|
175 | THIS SOFTWARE.
|