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

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

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 metrics
    • false 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: 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();

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

browsers node

About contributing

Read out [contributing guide]

About Version

https://semver.org/