aelf-sdk.java - AELF Java API

This Java library helps in the communication with an AElf node. You can find out more here.

Introduction

aelf-sdk.java 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.java, as well as providing a API reference documentation with examples.

If you need more information you can check out the repo : aelf-sdk.java

Adding aelf-sdk.java package

First you need to get elf-sdk.java package into your project: MvnRepository

Maven:

<!-- https://mvnrepository.com/artifact/io.aelf/aelf-sdk -->
<dependency>
    <groupId>io.aelf</groupId>
    <artifactId>aelf-sdk</artifactId>
    <version>0.X.X</version>
</dependency>

Examples

Create instance

Create a new instance of AElfClient, and set url of an AElf chain node.

using AElf.Client.Service;

// create a new instance of AElf, change the URL if needed
AElfClient client = new AElfClient("http://127.0.0.1:1235");

Test connection

Check that the AElf chain node is connectable.

boolean isConnected = client.isConnected();

Initiate a transfer transaction

// Get token contract address.
String tokenContractAddress = client.getContractAddressByName(privateKey, Sha256.getBytesSha256("AElf.ContractNames.Token"));

Client.Address.Builder to = Client.Address.newBuilder();
to.setValue(ByteString.copyFrom(Base58.decodeChecked("7s4XoUHfPuqoZAwnTV7pHWZAaivMiL8aZrDSnY9brE1woa8vz")));
Client.Address toObj = to.build();

TokenContract.TransferInput.Builder paramTransfer = TokenContract.TransferInput.newBuilder();
paramTransfer.setTo(toObj);
paramTransfer.setSymbol("ELF");
paramTransfer.setAmount(1000000000);
paramTransfer.setMemo("transfer in demo");
TokenContract.TransferInput paramTransferObj = paramTransfer.build();

String ownerAddress = client.getAddressFromPrivateKey(privateKey);

Transaction.Builder transactionTransfer = client.generateTransaction(ownerAddress, tokenContractAddress, "Transfer", paramTransferObj.toByteArray());
Transaction transactionTransferObj = transactionTransfer.build();
transactionTransfer.setSignature(ByteString.copyFrom(ByteArrayHelper.hexToByteArray(client.signTransaction(privateKey, transactionTransferObj))));
transactionTransferObj = transactionTransfer.build();

// Send the transfer transaction to AElf chain node.
SendTransactionInput sendTransactionInputObj = new SendTransactionInput();
sendTransactionInputObj.setRawTransaction(Hex.toHexString(transactionTransferObj.toByteArray()));
SendTransactionOutput sendResult = client.sendTransaction(sendTransactionInputObj);

Thread.sleep(4000);
// After the transaction is mined, query the execution results.
TransactionResultDto transactionResult = client.getTransactionResult(sendResult.getTransactionId());
System.out.println(transactionResult.getStatus());

// Query account balance.
Client.Address.Builder owner = Client.Address.newBuilder();
owner.setValue(ByteString.copyFrom(Base58.decodeChecked(ownerAddress)));
Client.Address ownerObj = owner.build();

TokenContract.GetBalanceInput.Builder paramGetBalance = TokenContract.GetBalanceInput.newBuilder();
paramGetBalance.setSymbol("ELF");
paramGetBalance.setOwner(ownerObj);
TokenContract.GetBalanceInput paramGetBalanceObj = paramGetBalance.build();

Transaction.Builder transactionGetBalance = client.generateTransaction(ownerAddress, tokenContractAddress, "GetBalance", paramGetBalanceObj.toByteArray());
Transaction transactionGetBalanceObj = transactionGetBalance.build();
String signature = client.signTransaction(privateKey, transactionGetBalanceObj);
transactionGetBalance.setSignature(ByteString.copyFrom(ByteArrayHelper.hexToByteArray(signature)));
transactionGetBalanceObj = transactionGetBalance.build();

ExecuteTransactionDto executeTransactionDto = new ExecuteTransactionDto();
executeTransactionDto.setRawTransaction(Hex.toHexString(transactionGetBalanceObj.toByteArray()));
String transactionGetBalanceResult = client.executeTransaction(executeTransactionDto);

TokenContract.GetBalanceOutput balance = TokenContract.GetBalanceOutput.getDefaultInstance().parseFrom(ByteArrayHelper.hexToByteArray(transactionGetBalanceResult));
System.out.println(balance.getBalance());

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 AElfClient instance, so if you don’t have one please create it:

using AElf.Client.Service;

// create a new instance of AElf, change the URL if needed
AElfClient client = new AElfClient("http://127.0.0.1:1235");

GetChainStatus

Get the current status of the block chain.

Web API path

/api/blockChain/chainStatus

Parameters

Empty

Returns

ChainStatusDto

  • ChainId - String
  • Branches - HashMap<String, Long>
  • NotLinkedBlocks - ashMap<String, String>
  • LongestChainHeight - long
  • LongestChainHash - String
  • GenesisBlockHash - String
  • GenesisContractAddress - String
  • LastIrreversibleBlockHash - String
  • LastIrreversibleBlockHeight - long
  • BestChainHash - String
  • BestChainHeight - long

Example

client.getChainStatus();

GetContractFileDescriptorSet

Get the protobuf definitions related to a contract.

Web API path

/api/blockChain/contractFileDescriptorSet

Parameters

  1. contractAddress - String address of a contract

Returns

byte[]

Example

client.getContractFileDescriptorSet(address);

GetBlockHeight

Get current best height of the chain.

Web API path

/api/blockChain/blockHeight

Parameters

Empty

Returns

long

Example

client.getBlockHeight();

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

BlockDto

  • BlockHash - String
  • Header - BlockHeaderDto
    • PreviousBlockHash - String
    • MerkleTreeRootOfTransactions - String
    • MerkleTreeRootOfWorldState - String
    • Extra - String
    • Height - long
    • Time - Date
    • ChainId - String
    • Bloom - String
    • SignerPubkey - String
  • Body - BlockBodyDto
    • TransactionsCount - int
    • Transactions - List<String>

Example

client.getBlockByHash(blockHash);

GetBlockByHeight

Web API path

/api/blockChain/blockByHeight

Get block information by block height.

Parameters

  1. blockHeight - long
  2. includeTransactions - boolean :
  • true require transaction ids list in the block
  • false Doesn’t require transaction ids list in the block

Returns

BlockDto

  • BlockHash - String
  • Header - BlockHeaderDto
    • PreviousBlockHash - String
    • MerkleTreeRootOfTransactions - String
    • MerkleTreeRootOfWorldState - String
    • Extra - String
    • Height - long
    • Time - Date
    • ChainId - String
    • Bloom - String
    • SignerPubkey - String
  • Body - BlockBodyDto
    • TransactionsCount - int
    • Transactions - List<String>

Example

client.getBlockByHeight(height);

GetTransactionResult

Get the result of a transaction.

Web API path

/api/blockChain/transactionResult

Parameters

  1. transactionId - String

Returns

TransactionResultDto

  • TransactionId - String
  • Status - String
  • Logs - ist<LogEventDto>
    • Address - String
    • Name - String
    • Indexed - List<String>
    • NonIndexed - String
  • Bloom - String
  • BlockNumber - long
  • Transaction - TransactionDto
    • From - String
    • To - String
    • RefBlockNumber - long
    • RefBlockPrefix - String
    • MethodName - String
    • Params - String
    • Signature - String
  • Error - String

Example

client.getTransactionResult(transactionId);

GetTransactionResults

Get multiple transaction results in a block.

Web API path

/api/blockChain/transactionResults

Parameters

  1. blockHash - String
  2. offset - int
  3. limit - int

Returns

List<TransactionResultDto> - The array of transaction result:

  • the transaction result object

Example

client.getTransactionResults(blockHash, 0, 10);

GetTransactionPoolStatus

Get the transaction pool status.

Web API path

/api/blockChain/transactionPoolStatus

Parameters

Empty

Returns

TransactionPoolStatusOutput

  • Queued - int
  • Validated - int

Example

client.getTransactionPoolStatus();

SendTransaction

Broadcast a transaction.

Web API path

/api/blockChain/sendTransaction

POST

Parameters

SendTransactionInput - Serialization of data into protobuf data:

  • RawTransaction - String

Returns

SendTransactionOutput

  • TransactionId - String

Example

client.sendTransaction(input);

SendRawTransaction

Broadcast a transaction.

Web API path

/api/blockChain/sendTransaction

POST

Parameters

SendRawTransactionInput - Serialization of data into protobuf data:

  • Transaction - String
  • Signature - String
  • ReturnTransaction - boolean

Returns

SendRawTransactionOutput

  • TransactionId - String
  • Transaction - TransactionDto

Example

client.sendRawTransaction(input);

SendTransactions

Broadcast multiple transactions.

Web API path

/api/blockChain/sendTransactions

POST

Parameters

SendTransactionsInput - Serialization of data into protobuf data:

  • RawTransactions - String

Returns

List<String>

Example

client.sendTransactions(input);

CreateRawTransaction

Creates an unsigned serialized transaction.

Web API path

/api/blockChain/rawTransaction

POST

Parameters

CreateRawTransactionInput

  • From - String
  • To - String
  • RefBlockNumber - long
  • RefBlockHash - String
  • MethodName - String
  • Params - String

Returns

CreateRawTransactionOutput- Serialization of data into protobuf data:

  • RawTransaction - String

Example

client.createRawTransaction(input);

ExecuteTransaction

Call a read-only method on a contract.

Web API path

/api/blockChain/executeTransaction

POST

Parameters

ExecuteTransactionDto - Serialization of data into protobuf data:

  • RawTransaction - String

Returns

String

Example

client.executeTransaction(input);

ExecuteRawTransaction

Call a read-only method on a contract.

Web API path

/api/blockChain/executeRawTransaction

POST

Parameters

ExecuteRawTransactionDto - Serialization of data into protobuf data:

  • RawTransaction - String
  • Signature - String

Returns

String

Example

client.executeRawTransaction(input);

GetPeers

Get peer info about the connected network nodes.

Web API path

/api/net/peers

Parameters

  1. withMetrics - boolean

Returns

List<PeerDto>

  • IpAddress - String
  • ProtocolVersion - int
  • ConnectionTime - long
  • ConnectionStatus - String
  • Inbound - boolean
  • BufferedTransactionsCount - int
  • BufferedBlocksCount - int
  • BufferedAnnouncementsCount - int
  • RequestMetrics - List<RequestMetric>
    • RoundTripTime - long
    • MethodName - String
    • Info - String
    • RequestTime - String

Example

client.getPeers(false);

AddPeer

Attempts to add a node to the connected network nodes.

Web API path

/api/net/peer

POST

Parameters

AddPeerInput

  • Address - String

Returns

boolean

Example

client.addPeer("127.0.0.1:7001");

RemovePeer

Attempts to remove a node from the connected network nodes.

Web API path

/api/net/peer

DELETE

Parameters

  1. address - String

Returns

boolean

Example

client.removePeer("127.0.0.1:7001");

GetNetworkInfo

Get the network information of the node.

Web API path

/api/net/networkInfo

Parameters

Empty

Returns

NetworkInfoOutput

  • Version - String
  • ProtocolVersion - int
  • Connections - int

Example

client.getNetworkInfo();

AElf Client

IsConnected

Verify whether this sdk successfully connects the chain.

Parameters

Empty

Returns

boolean

Example

client.isConnected();

GetGenesisContractAddress

Get the address of genesis contract.

Parameters

Empty

Returns

String

Example

client.getGenesisContractAddress();

GetContractAddressByName

Get address of a contract by given contractNameHash.

Parameters

  1. privateKey - String
  2. contractNameHash - byte[]

Returns

String

Example

client.getContractAddressByName(privateKey, contractNameHash);

GenerateTransaction

Build a transaction from the input parameters.

Parameters

  1. from - String
  2. to - String
  3. methodName - String
  4. input - byte[]

Returns

Transaction

Example

client.generateTransaction(from, to, methodName, input);

GetFormattedAddress

Convert the Address to the displayed string：symbol_base58-string_base58-String-chain-id.

Parameters

  1. privateKey - String
  2. address - String

Returns

String

Example

client.getFormattedAddress(privateKey, address);

SignTransaction

Sign a transaction using private key.

Parameters

  1. privateKeyHex - String
  2. transaction - Transaction

Returns

String

Example

client.signTransaction(privateKeyHex, transaction);

GetAddressFromPubKey

Get the account address through the public key.

Parameters

  1. pubKey - String

Returns

String

Example

client.getAddressFromPubKey(pubKey);

GetAddressFromPrivateKey

Get the account address through the private key.

Parameters

  1. privateKey - String

Returns

String

Example

client.getAddressFromPrivateKey(privateKey);

GenerateKeyPairInfo

Generate a new account key pair.

Parameters

Empty

Returns

KeyPairInfo

  • PrivateKey - String
  • PublicKey - String
  • Address - String

Example

client.generateKeyPairInfo();

Supports

  • JDK1.8+
  • Log4j2.6.2