aelf-sdk.js - AELF JavaScript API

Branch	Tests	Coverage
master

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')
    })
  ]
});

For Node.js usage and use commonjs module system

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;

1. 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'));

2. 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 ...');

3. 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));
   })();

4. 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;
   });

5. 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"
      }
    */
   })();

6. 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'

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'));

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

Web API path

/api/blockChain/contractFileDescriptorSet

Parameters

1. contractAddress - String address of a contract

Returns

String

Example

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

1. blockHash - String
2. 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

1. blockHeight - Number
2. 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

1. 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

1. blockHash - String
2. offset - Number
3. 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

calculateTransactionFee

Estimate transaction fee

Web API path

/api/blockChain/calculateTransactionFee

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';
const wallet = AElf.wallet.createNewWallet();

getWalletByMnemonic

Parameters

1. mnemonic - String : wallet's mnemonic

Returns

Object: Complete wallet object.

Example

const wallet = AElf.wallet.getWalletByMnemonic(mnemonic);

getWalletByPrivateKey

Parameters

1. 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

1. rawTxn - String
2. 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

1. input - String
2. password - String

Returns

String

AESDecrypt

Decrypt by aes algorithm

Parameters

1. input - String
2. 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';
AElf.version; // eg. 3.2.23

3.8 Requirements

• Node.js
• NPM

3.9 Support

4. Building

• Node.js
• npm

sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install npm

4.1 Building (webpack)

Build the web3.js package:

yarn run build

4.2 Testing (jest)

yarn run test

Commit code will run test and lint automatically, and show the test result in readme.md, please make sure all test cases passed.

4.3 About contributing

Read out contributing guide

5. About Version

https://semver.org/