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

  • 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

  • blockHash - String
  • 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

Get block information by block height.

Web API path

/api/blockChain/blockByHeight

Parameters

  • blockHeight - long
  • 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

  • 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

  • blockHash - String
  • offset - int
  • 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

  • withMetrics - boolean

Returns

  • List<PeerDto>
    • IpAddress - String
    • ProtocolVersion - int
    • ConnectionTime - long
    • ConnectionStatus - String
    • Inbound - boolean
    • BufferedTransactionsCount - int
    • BufferedBlocksCount - int
    • BufferedAnnouncementsCount - int
    • NodeVersion - String
    • 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

  • address - string

Returns

  • boolean

Example

client.removePeer("127.0.0.1:7001");

calculateTransactionFee

Estimate transaction fee.

Web API path

/api/blockChain/calculateTransactionFee

POST

Parameters

  • CalculateTransactionFeeInput
    • RawTrasaction - string

Returns

  • CalculateTransactionFeeOutput - The object with the following structure :
    • Success - boolean
    • TransactionFee - HashMap<String, Long>
    • ResourceFee - HashMap<String, Long>

Example

CalculateTransactionFeeOutput output = client.calculateTransactionFee(input);

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

  • privateKey - String
  • contractNameHash - byte[]

Returns

  • String

Example

client.getContractAddressByName(privateKey, contractNameHash);

GenerateTransaction

Build a transaction from the input parameters.

Parameters

  • from - String
  • to - String
  • methodName - String
  • 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

  • privateKey - String
  • address - String

Returns

  • String

Example

client.getFormattedAddress(privateKey, address);

SignTransaction

Sign a transaction using private key.

Parameters

  • privateKeyHex - String
  • transaction - Transaction

Returns

  • String

Example

client.signTransaction(privateKeyHex, transaction);

GetAddressFromPubKey

Get the account address through the public key.

Parameters

  • pubKey - String

Returns

  • String

Example

client.getAddressFromPubKey(pubKey);

GetAddressFromPrivateKey

Get the account address through the private key.

Parameters

  • 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