aelf-sdk.js - AELF JavaScript API
1. Introduction
aelf-sdk.js for aelf is like web.js for ethereum.
aelf-sdk.js is a collection of libraries which allow you to interact with a local or remote aelf node, using a HTTP connection.
The following documentation will guide you through installing and running aelf-sdk.js, as well as providing a API reference documentation with examples.
You can get some codes in the ./examples directory
2. Getting Started
2.1 Adding aelf-sdk.js
First you need to get aelf-sdk.js into your project. This can be done using the following methods:
npm: npm install aelf-sdk
pure js: link dist/aelf.umd.js
After that you need to create a aelf instance and set a provider.
// 1.In node.js use: const AElf = require('aelf-sdk');
// 2.FrontEnd freshman, add following tag in html
// <script src="https://unpkg.com/aelf-sdk@lastest/dist/aelf.umd.js"></script>
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000'));
2.2 Detail information for library files
You can skip 2.2 as 2.1 is enough now.
In our dist directory, we supply two kinds of packages for different platforms, such as Node and Browser.
packages | usage |
---|---|
dist/aelf.cjs.js | built for node, remove node built-in modules such as crypto. |
dist/aelf.umd.js | built for browser, add some node built-in modules by webpack |
You can choose any packages based on your need, for examples:
if you are new to FrontEnd, you can use AElf-sdk
by add a script tag in your html files.
<!-- minified version with UMD module -->
<script src="https://unpkg.com/aelf-sdk@lastest/dist/aelf.umd.js"></script>
if you want to use a bundle system such as webpack or rollup, and build your applications for Node.js and Browsers, just import the specified version of package files.
For browser usage and use UMD
Webpack:
module.exports = {
// ...
resolve: {
alias: {
'aelf-sdk$': 'aelf-sdk/dist/aelf.umd.js'
}
}
}
Rollup:
const alias = require('rollup-plugin-alias');
rollup({
// ...
plugins: [
alias({
'aelf-sdk': require.resolve('aelf-sdk/dist/aelf.umd.js')
})
]
})
<<<<<<< HEAD
For Node.js usage and use commonjs module system
=======
For Node.js usage and use commonjs module system
release/v3.2.55
Webpack:
module.exports = {
// ...
resolve: {
alias: {
'aelf-sdk$': 'aelf-sdk/dist/aelf.cjs.js'
}
}
}
Rollup:
const alias = require('rollup-plugin-alias');
rollup({
// ...
plugins: [
alias({
'aelf-sdk': require.resolve('aelf-sdk/dist/aelf.cjs.js')
})
]
})
3. Basic usage
3.1 Examples
You can also see full examples in ./examples;
-
Create a new instance of AElf, connect to an AELF chain node.
import AElf from 'aelf-sdk'; // create a new instance of AElf const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:1235'));
-
Create or load a wallet with
AElf.wallet
// create a new wallet const newWallet = AElf.wallet.createNewWallet(); // load a wallet by private key const priviteKeyWallet = AElf.wallet.getWalletByPrivateKey('xxxxxxx'); // load a wallet by mnemonic const mnemonicWallet = AElf.wallet.getWalletByMnemonic('set kite ...');
-
Get a system contract address, take
AElf.ContractNames.Token
as an exampleconst tokenContractName = 'AElf.ContractNames.Token'; let tokenContractAddress; (async () => { // get chain status const chainStatus = await aelf.chain.getChainStatus(); // get genesis contract address const GenesisContractAddress = chainStatus.GenesisContractAddress; // get genesis contract instance const zeroContract = await aelf.chain.contractAt(GenesisContractAddress, newWallet); // Get contract address by the read only method `GetContractAddressByName` of genesis contract tokenContractAddress = await zeroContract.GetContractAddressByName.call(AElf.utils.sha256(tokenContractName)); })()
-
Get a contract instance by contract address
const wallet = AElf.wallet.createNewWallet(); let tokenContract; // Use token contract for examples to demonstrate how to get a contract instance in different ways // in async function (async () => { tokenContract = await aelf.chain.contractAt(tokenContractAddress, wallet) })(); // promise way aelf.chain.contractAt(tokenContractAddress, wallet) .then(result => { tokenContract = result; }); // callback way aelf.chain.contractAt(tokenContractAddress, wallet, (error, result) => {if (error) throw error; tokenContract = result;});
-
How to use contract instance
A contract instance consists of several contract methods and methods can be called in two ways: read-only and send transaction.
(async () => { // get the balance of an address, this would not send a transaction, // or store any data on the chain, or required any transaction fee, only get the balance // with `.call` method, `aelf-sdk` will only call read-only method const result = await tokenContract.GetBalance.call({ symbol: "ELF", owner: "7s4XoUHfPuqoZAwnTV7pHWZAaivMiL8aZrDSnY9brE1woa8vz" }); console.log(result); /** { "symbol": "ELF", "owner": "2661mQaaPnzLCoqXPeys3Vzf2wtGM1kSrqVBgNY4JUaGBxEsX8", "balance": "1000000000000" }*/ // with no `.call`, `aelf-sdk` will sign and send a transaction to the chain, and return a transaction id. // make sure you have enough transaction fee `ELF` in your wallet const transactionId = await tokenContract.Transfer({ symbol: "ELF", to: "7s4XoUHfPuqoZAwnTV7pHWZAaivMiL8aZrDSnY9brE1woa8vz", amount: "1000000000", memo: "transfer in demo" }); console.log(transactionId); /** { "TransactionId": "123123" } */ })()
-
Change the node endpoint by using
aelf.setProvider
import AElf from 'aelf-sdk'; const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:1235')); aelf.setProvider(new AElf.providers.HttpProvider('http://127.0.0.1:8000'));
3.2 Web API
You can see how the Web Api of the node works in {chainAddress}/swagger/index.html
tip: for an example, my local address: 'http://127.0.0.1:1235/swagger/index.html'
The usage of these methods is based on the AElf instance, so if you don't have one please create it:
import AElf from 'aelf-sdk';
<<<<<<< HEAD
// create a new instance of AElf, change the URL if needed
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:1235'));
getChainStatus
Get the current status of the block chain.
Web API path
/api/blockChain/chainStatus
Parameters
Empty
Returns
Object
ChainId - String
Branches - Object
NotLinkedBlocks - Object
LongestChainHeight - Number
LongestChainHash - String
GenesisBlockHash - String
GenesisContractAddress - String
LastIrreversibleBlockHash - String
LastIrreversibleBlockHeight - Number
BestChainHash - String
BestChainHeight - Number
Example
aelf.chain.getChainStatus()
.then(res => {
console.log(res);
})
getContractFileDescriptorSet
Get the protobuf definitions related to a contract
// only pass a host parameter const aelfInstance = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000'));
// host, timeout, user, password, headers const aelf = new AElf( new AElf.providers.HttpProvider( host, // https://127.0.0.1:8000 timeout, // 300 user, // username password, // passowrd // header [{ name: 'x-csrf-token', value: document.cookie.match(/csrfToken=[^;]*/)[0].replace('csrfToken=', '') }] ) );
init contract and call contract methods
```js
// contractAddress = xxx; wallet = xxx;
// We use token contract for example.
aelf.chain.contractAt(contractAddress, wallet, (err, result) => {
const contractoktMethods = result;
// contractMethods.methodName(param01, ..., paramN, callback);
// contractMethods.methodName.call(param01, ..., paramN, callback);
contractoktMethods.Transfer({
symbol: 'ELF',
to: '58h3RwTfaE8RDpRNMAMiMv8jUjanCeYHBzKuQfHbrfSFTCn',
amount: '1000'
}, (err, result) => {
});
>>>>>>> release/v3.2.55
_Web API path_
`/api/blockChain/contractFileDescriptorSet`
_Parameters_
1. `contractAddress - String` address of a contract
_Returns_
`String`
_Example_
```javascript
aelf.chain.getContractFileDescriptorSet(contractAddress)
.then(res => {
console.log(res);
})
getBlockHeight
Get current best height of the chain.
Web API path
/api/blockChain/blockHeight
Parameters
Empty
Returns
Number
Example
aelf.chain.getBlockHeight()
.then(res => {
console.log(res);
})
getBlock
Get block information by block hash.
Web API path
/api/blockChain/block
Parameters
blockHash - String
-
includeTransactions - Boolean
:
-
true
require transaction ids list in the block -
false
Doesn't require transaction ids list in the block
Returns
Object
BlockHash - String
-
Header - Object
PreviousBlockHash - String
MerkleTreeRootOfTransactions - String
MerkleTreeRootOfWorldState - String
Extra - Array
Height - Number
Time - google.protobuf.Timestamp
ChainId - String
Bloom - String
SignerPubkey - String
-
Body - Object
TransactionsCount - Number
-
Transactions - Array
transactionId - String
Example
aelf.chain.getBlock(blockHash, false)
.then(res => {
console.log(res);
})
getBlockByHeight
Web API path
/api/blockChain/blockByHeight
Get block information by block height.
Parameters
blockHeight - Number
-
includeTransactions - Boolean
:
-
true
require transaction ids list in the block -
false
Doesn't require transaction ids list in the block
Returns
Object
BlockHash - String
-
Header - Object
PreviousBlockHash - String
MerkleTreeRootOfTransactions - String
MerkleTreeRootOfWorldState - String
Extra - Array
Height - Number
Time - google.protobuf.Timestamp
ChainId - String
Bloom - String
SignerPubkey - String
-
Body - Object
TransactionsCount - Number
-
Transactions - Array
transactionId - String
Example
aelf.chain.getBlockByHeight(12, false)
.then(res => {
console.log(res);
})
getTxResult
Get the result of a transaction
Web API path
/api/blockChain/transactionResult
Parameters
transactionId - String
Returns
Object
TransactionId - String
Status - String
-
Logs - Array
Address - String
Name - String
Indexed - Array
NonIndexed - String
Bloom - String
BlockNumber - Number
-
Transaction - Object
From - String
To - String
RefBlockNumber - Number
RefBlockPrefix - String
MethodName - String
Params - Object
Signature - String
ReadableReturnValue - Object
Error - String
Example
aelf.chain.getTxResult(transactionId)
.then(res => {
console.log(res);
})
getTxResults
Get multiple transaction results in a block
Web API path
/api/blockChain/transactionResults
Parameters
blockHash - String
offset - Number
limit - Number
Returns
Array
- The array of method descriptions:
- the transaction result object
Example
aelf.chain.getTxResults(blockHash, 0, 2)
.then(res => {
console.log(res);
})
getTransactionPoolStatus
Get the transaction pool status.
Web API path
/api/blockChain/transactionPoolStatus
Parameters
Empty
sendTransaction
Broadcast a transaction
Web API path
/api/blockChain/sendTransaction
POST
Parameters
Object
- Serialization of data into protobuf data, The object with the following structure :
-
RawTransaction - String
:
usually developers don't need to use this function directly, just get a contract method and send transaction by call contract method:
sendTransactions
Broadcast multiple transactions
POST
Parameters
Object
- The object with the following structure :
RawTransaction - String
callReadOnly
Call a read-only method on a contract.
POST
Parameters
Object
- The object with the following structure :
RawTransaction - String
getPeers
Get peer info about the connected network nodes
addPeer
Attempts to add a node to the connected network nodes
you need to create a aelf authorization instance and set a provider
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000', 8000, { "Authorization": AElf.utils.getAuthorization('UseName', 'Password') }));
Example
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000', 8000, { "Authorization": AElf.utils.getAuthorization('aelf', '12345678') }));
aelf.chain.addPeer('192.168.11.140:6801').then(res => {
console.log(res);
})
removePeer
Attempts to remove a node from the connected network nodes
you need to create a aelf authorization instance and set a provider
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000', 8000, { "Authorization": AElf.utils.getAuthorization('UseName', 'Password') }));
Example
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000', 8000, { "Authorization": AElf.utils.getAuthorization('aelf', '12345678') }));
aelf.chain.removePeer('192.168.11.140:6801').then(res => {
console.log(res);
})
networkInfo
Get information about the node’s connection to the network
3.3 AElf.wallet
AElf.wallet
is a static property of AElf
.
Use the api to see detailed results
createNewWallet
Returns
Object
-
mnemonic - String
: mnemonic -
BIP44Path - String
: m/purpose'/coin_type'/account'/change/address_index -
childWallet - Object
: HD Wallet -
keyPair - String
: The EC key pair generated by elliptic -
privateKey - String
: private Key -
address - String
: address
Example
import AElf from 'aelf-sdk';
<<<<<<< HEAD
const wallet = AElf.wallet.createNewWallet();
=======
const aelf = new AElf(new AElf.providers.HttpProvider('https://127.0.0.1:8000'));
aelf.setProvider(new AElf.providers.HttpProvider('https://127.0.0.1:8010'));
>>>>>>> release/v3.2.55
getWalletByMnemonic
Parameters
<<<<<<< HEAD
-
mnemonic - String
: wallet's mnemonic
Returns
Object
: Complete wallet object.
Example
const wallet = AElf.wallet.getWalletByMnemonic(mnemonic);
=======
```js
import AElf from 'aelf-sdk';
AElf.wallet.createNewWallet();
// wallet.AESDecrypto wallet.AESEncrypto wallet.bip39
// wallet.createNewWallet wallet.getWalletByMnemonic wallet.getWalletByPrivateKey
// wallet.sign wallet.signTransaction
>>>>>>> release/v3.2.55
getWalletByPrivateKey
Parameters
-
privateKey: String
: wallet's private key
Returns
Object
: Complete wallet object, with empty mnemonic
Example
const wallet = AElf.wallet.getWalletByPrivateKey(privateKey);
signTransaction
Use wallet keypair
to sign a transaction
Parameters
rawTxn - String
keyPair - String
Returns
Object
: The object with the following structure :
Example
const result = AElf.wallet.signTransaction(rawTxn, keyPair);
AESEncrypt
Encrypt a string by aes algorithm
Parameters
input - String
password - String
Returns
String
AESDecrypt
Decrypt by aes algorithm
Parameters
input - String
password - String
Returns
String
3.4 AElf.pbjs
Simple example in how to use aelf.pbjs;
The reference to protobuf.js, read the documentation to see how to use.
3.5 AElf.pbUtils
Some basic format methods about proto for aelf.
For more information, please see the code in src/util/proto.js. It is simple and easy to understand.
3.6 AElf.utils
Some methods for aelf.
For more information, please see the code in src/util/utils.js. It is simple and easy to understand.
3.6.1 Check address
const AElf = require('aelf-sdk');
const {base58} = AElf.utils;
base58.decode('$addresss'); // throw error if invalid
3.7 AElf.version
import AElf from 'aelf-sdk';
<<<<<<< HEAD
AElf.version // eg. 3.2.23
3.8 Requirements
======= AElf.version // eg. 3.2.13
## Contributing
- All contributions have to go into the dev branch
- Please follow the code style of `eslint-config-airbnb-base`
### Requirements
>>>>>>> release/v3.2.55
- [Node.js](https://nodejs.org)
- [NPM](http://npmjs.com/)
### 3.9 Support
![browsers](https://img.shields.io/badge/browsers-latest%202%20versions-brightgreen.svg)
<<<<<<< HEAD
![node](https://img.shields.io/badge/node->=10-green.svg)
=======
![node](https://img.shields.io/badge/node->=10.9.0-green.svg)
>>>>>>> release/v3.2.55
## 4. About contributing
Read out [contributing guide](./.github/CONTRIBUTING.md)
## 5. About Version
https://semver.org/