aelf-sdk.js - AELF JavaScript API
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.
If you need more information you can check out the repo : aelf-sdk.js
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.
// in brower use: <script src="https://unpkg.com/aelf-sdk@lastest/dist/aelf.umd.js"></script>
// in node.js use: const AElf = require('aelf-sdk');
const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:8000'));
Examples
You can also see full examples in ./examples
;
Create instance
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
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
Get a system contract address, take AElf.ContractNames.Token
as an
example
const 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
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;});
Use contract instance
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
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'));
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’
parameters and returns based on the URL:
https://aelf-public-node.aelf.io/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';
// 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'));
1.getChainStatus
Get the current status of the block chain.
Web API path
/api/blockChain/chainStatus
GET
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);
})
2.getContractFileDescriptorSet
Get the protobuf definitions related to a contract
Web API path
/api/blockChain/contractFileDescriptorSet
GET
Parameters
contractAddress - String
address of a contract
Returns
String
Example
aelf.chain.getContractFileDescriptorSet(contractAddress)
.then(res => {
console.log(res);
})
3.getBlockHeight
Get current best height of the chain.
Web API path
/api/blockChain/blockHeight
GET
Parameters
Empty
Returns
Number
Example
aelf.chain.getBlockHeight()
.then(res => {
console.log(res);
})
4.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 blockfalse
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);
})
5.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 blockfalse
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);
})
6.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);
})
7.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);
})
8.getTransactionPoolStatus
Get the transaction pool status.
Web API path
/api/blockChain/transactionPoolStatus
Parameters
Empty
9.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:
10.sendTransactions
Broadcast multiple transactions
POST
Parameters
Object
- The object with the following structure :RawTransaction - String
11.callReadOnly
Call a read-only method on a contract.
POST
Parameters
Object
- The object with the following structure :RawTransaction - String
12.getPeers
Get peer info about the connected network nodes
GET
Parameters
withMetrics - Boolean
:true
with metricsfalse
without metrics
13.addPeer
Attempts to add a node to the connected network nodes
POST
Parameters
Object
- The object with the following structure :Address - String
14.removePeer
Attempts to remove a node from the connected network nodes
DELETE
Parameters
address - String
15.calculateTransactionFee
Estimate transaction fee
Web API path
/api/blockChain/calculateTransactionFee
POST
Parameters
CalculateTransactionFeeInput - Object
- The object with the following structure :RawTransaction - String
Returns
CalculateTransactionFeeOutput - Object
- The object with the following structure :Success - Bool
TransactionFee - Array
ResourceFee - Array
Example
aelf.chain.calculateTransactionFee(rawTransaction)
.then(res => {
console.log(res);
})
16.networkInfo
Get information about the node’s connection to the network
GET
Parameters
Empty
AElf.wallet
AElf.wallet
is a static property of AElf
.
Use the api to see detailed results
1.createNewWallet
Returns
Object
mnemonic - String
: mnemonicBIP44Path - String
: m/purpose’/coin_type’/account’/change/address_indexchildWallet - Object
: HD WalletkeyPair - String
: The EC key pair generated by ellipticprivateKey - String
: private Keyaddress - String
: address
Example
import AElf from 'aelf-sdk';
const wallet = AElf.wallet.createNewWallet();
2.getWalletByMnemonic
Parameters
mnemonic - String
: wallet’s mnemonic
Returns
Object
: Complete wallet object.
Example
const wallet = AElf.wallet.getWalletByMnemonic(mnemonic);
3.getWalletByPrivateKey
Parameters
privateKey: String
: wallet’s private key
Returns
Object
: Complete wallet object, with empty mnemonic
Example
const wallet = AElf.wallet.getWalletByPrivateKey(privateKey);
4.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);
5.AESEncrypt
Encrypt a string by aes algorithm
Parameters
input - String
password - String
Returns
String
6.AESDecrypt
Decrypt by aes algorithm
Parameters
input - String
password - String
Returns
String
AElf.pbjs
The reference to protobuf.js, read the documentation to see how to use.
AElf.pbUtils
Some basic format methods of aelf.
For more information, please see the code in src/utils/proto.js
. It
is simple and easy to understand.
AElf.utils
Some methods for aelf.
For more information, please see the code in src/utils/utils.js
. It
is simple and easy to understand.
Check address
const AElf = require('aelf-sdk');
const {base58} = AElf.utils;
base58.decode('$addresss'); // throw error if invalid
AElf.version
import AElf from 'aelf-sdk';
AElf.version // eg. 3.2.23
Requirements
Support
About contributing
Read out [contributing guide]