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 blockfalse
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 blockfalse
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
- intValidated
- 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