logo

Java SDK

aelf-sdk.java - aelf Java API

Introduction#

aelf-sdk.java is a set of libraries that allow interaction with a local or remote aelf node using an HTTP connection. This documentation guides you through installing and running aelf-sdk.java, along with providing API reference documentation and examples.

For more information, you can check out the repository.

Adding aelf-sdk.java Package#

To add the aelf-sdk.java package to your project, use the following Maven dependency:

1
<!-- https://mvnrepository.com/artifact/io.aelf/aelf-sdk -->
2
<dependency>
3
    <groupId>io.aelf</groupId>
4
    <artifactId>aelf-sdk</artifactId>
5
    <version>0.X.X</version>
6
</dependency>

Examples#

Create Instance#

Create a new instance of AElfClient, and set the URL of an aelf chain node.

1
import AElf.Client.Service;
2


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

Test Connection#

Check if the aelf chain node is connectable.

1
boolean isConnected = client.isConnected();

Initiate a Transfer Transaction#

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


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


8
TokenContract.TransferInput.Builder paramTransfer = TokenContract.TransferInput.newBuilder();
9
paramTransfer.setTo(toObj);
10
paramTransfer.setSymbol("ELF");
11
paramTransfer.setAmount(1000000000);
12
paramTransfer.setMemo("transfer in demo");
13
TokenContract.TransferInput paramTransferObj = paramTransfer.build();
14


15
String ownerAddress = client.getAddressFromPrivateKey(privateKey);
16


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


22
// Send the transfer transaction to aelf chain node.
23
SendTransactionInput sendTransactionInputObj = new SendTransactionInput();
24
sendTransactionInputObj.setRawTransaction(Hex.toHexString(transactionTransferObj.toByteArray()));
25
SendTransactionOutput sendResult = client.sendTransaction(sendTransactionInputObj);
26


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


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


37
TokenContract.GetBalanceInput.Builder paramGetBalance = TokenContract.GetBalanceInput.newBuilder();
38
paramGetBalance.setSymbol("ELF");
39
paramGetBalance.setOwner(ownerObj);
40
TokenContract.GetBalanceInput paramGetBalanceObj = paramGetBalance.build();
41


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


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


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

This guide provides basic steps to interact with an aelf node using the aelf-sdk.java library. For more detailed information and advanced usage, please refer to the repository documentation.

Web API#

You can see how the Web API of the node works at {chainAddress}/swagger/index.html. For example, if you are using a local address, it would be: 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:

1
import AElf.Client.Service;
2


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

GetChainStatus#

Get the current status of the blockchain.

Web API path: /api/blockChain/chainStatus

Parameters: None

Returns: ChainStatusDto

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

    • Example:

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

    1
    client.getContractFileDescriptorSet(address);

    GetBlockHeight#

    Get the current best height of the chain.

    Web API path: /api/blockChain/blockHeight

    Parameters:: None

    Returns: long

    Example:

    1
    client.getBlockHeight();

    GetBlock#

    Get block information by block hash.

    Web API path: /api/blockChain/block

    Parameters:

  • blockHash - String
  • includeTransactions - boolean (true to include transaction ids list in the block, false otherwise)

    • Returns:

  • BlockDto

    • Example:

    1
    client.getBlockByHash(blockHash);

    GetBlockByHeight#

    Web API path: /api/blockChain/blockByHeight

    Parameters:

  • blockHeight - long
  • includeTransactions - boolean (true to include transaction ids list in the block, false otherwise)

    • Returns:

  • BlockDto

    • Example:

    1
    client.getBlockByHeight(height);

    GetTransactionResult#

    Web API path: /api/blockChain/transactionResult

    Parameters:

  • transactionId - String

    • Returns: TransactionResultDto

  • json

    • Example:

    1
    client.getTransactionResult(transactionId);

    GetTransactionResults#

    Web API path: /api/blockChain/transactionResults

    Parameters:

  • blockHash - String
  • offset - int
  • limit - int

    • Returns: List<TransactionResultDto> - The array of transaction results

    Example:

    1
    client.getTransactionResults(blockHash, 0, 10);

    GetTransactionPoolStatus#

    Web API path: /api/blockChain/transactionPoolStatus

    Parameters:: None

    Returns:

  • TransactionPoolStatusOutput

    • Example:

    1
    client.getTransactionPoolStatus();

    SendTransaction#

    Web API path: /api/blockChain/sendTransaction

    Method: POST

    Parameters:

  • SendTransactionInput - Serialization of data into protobuf format:

    • Returns:

  • SendTransactionOutput

    • Example:

    1
    client.sendTransaction(input);

    SendRawTransaction#

    Web API path: /api/blockChain/sendTransaction

    Method: POST

    Parameters:

  • SendRawTransactionInput - Serialization of data into protobuf format:

    • Returns:

  • SendRawTransactionOutput

    • Example:

    1
    client.sendRawTransaction(input);

    SendTransactions#

    Broadcast multiple transactions.

    Web API path: /api/blockChain/sendTransactions

    Method: POST

    Parameters:

  • SendTransactionsInput - Serialization of data into protobuf format:

    • Returns: List<String>

    Example:

    1
    client.sendTransactions(input);

    CreateRawTransaction#

    Create an unsigned serialized transaction.

    Web API path: /api/blockChain/rawTransaction

    Method: POST

    Parameters:

  • CreateRawTransactionInput

    • Returns:

  • CreateRawTransactionOutput - Serialization of data into protobuf format:

    • Example:

    1
    client.createRawTransaction(input);

    ExecuteTransaction#

    Web API path: /api/blockChain/executeTransaction

    Method: POST

    Parameters:

  • ExecuteTransactionDto - Serialization of data into protobuf format:

    • Returns: String

    Example:

    1
    client.executeTransaction(input);

    ExecuteRawTransaction#

    Web API path: /api/blockChain/executeRawTransaction

    Method: POST

    Parameters:

  • ExecuteRawTransactionDto - Serialization of data into protobuf format:

    • Returns: String

    Example:

    1
    client.executeRawTransaction(input);

    GetPeers#

    Get peer information about the connected network nodes.

    Web API path: /api/net/peers

    Parameters:

  • withMetrics - boolean

    • Returns:

  • List<PeerDto>

    • Example:

    1
    client.getPeers(false);

    AddPeer#

    Attempts to add a node to the connected network nodes.

    Web API path: /api/net/peer

    Method: POST

    Parameters:

  • AddPeerInput

    • Returns: boolean

    Example:

    1
    client.addPeer("127.0.0.1:7001");

    RemovePeer#

    Attempts to remove a node from the connected network nodes.

    Web API path: /api/net/peer

    Method: DELETE

    Parameters:

  • Address - String

    • Returns: boolean

    Example:

    1
    client.removePeer("127.0.0.1:7001");

    CalculateTransactionFee#

    Estimate transaction fee.

    Web API path: /api/blockChain/calculateTransactionFee

    Method: POST

    Parameters:

  • CalculateTransactionFeeInput

    • Returns:

  • CalculateTransactionFeeOutput

    • Example:

    1
    CalculateTransactionFeeOutput output = client.calculateTransactionFee(input);

    GetNetworkInfo#

    Web API path: /api/net/networkInfo

    Parameters: None

    Returns:

  • NetworkInfoOutput

    • Example:

    1
    client.getNetworkInfo();

    AElf Client#

    IsConnected#

    Verify whether this SDK successfully connects to the chain.

    Parameters: None

    Returns: boolean

    Example:

    1
    client.isConnected();

    GetGenesisContractAddress#

    Parameters: None

    Returns: String

    Example:

    1
    client.getGenesisContractAddress();

    GetContractAddressByName#

    Get the address of a contract by the given contract name hash.

    Parameters::

  • privateKey - String
  • contractNameHash - byte[]

    • Returns: String

    Example:

    1
    client.getContractAddressByName(privateKey, contractNameHash);

    GenerateTransaction#

    Build a transaction from the input parameters.

    Parameters:

  • from - String
  • to - String
  • methodName - String
  • input - byte[]

    • Returns: Transaction

    Example:

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

    1
    client.getFormattedAddress(privateKey, address);

    SignTransaction#

    Parameters:

  • privateKeyHex - String
  • transaction - Transaction

    • Returns: String

    Example:

    1
    client.signTransaction(privateKeyHex, transaction);

    GetAddressFromPubKey#

    Parameters:

  • pubKey - String

    • Returns: String

    Example:

    1
    client.getAddressFromPubKey(pubKey);

    GetAddressFromPrivateKey#

    Parameters:

  • privateKey - String

    • Returns: String

    Example:

    1
    client.getAddressFromPrivateKey(privateKey);

    GenerateKeyPairInfo#

    Parameters: None

    Returns:

  • KeyPairInfo

    • Example:

    1
    client.generateKeyPairInfo();

    Supports#

  • JDK1.8+
  • Log4j2.6.2

    • Edited on: 16 July 2024 04:44:34 GMT+0