logo

Go SDK

aelf-sdk.go - aelf Go API Introduction#

This document provides information on how to use the aelf Go SDK (aelf-sdk.go) to interact with an aelf node. The SDK allows you to communicate with a local or remote aelf node using HTTP. Here you will find instructions for setting up the SDK, examples of how to use it, and a brief description of its main functions.

For additional information, please visit the repository: aelf-sdk.go

Installation#

To install the aelf-sdk.go package, run the following command:

1
go get -u github.com/AElfProject/aelf-sdk.go

Examples#

Create instance#

Create a new instance of AElfClient and set the URL of an AElf chain node:

1
import ("github.com/AElfProject/aelf-sdk.go/client")
2


3
var aelf = client.AElfClient{
4
    Host:       "http://127.0.0.1:8000",
5
    Version:    "1.0",
6
    PrivateKey: "cd86ab6347d8e52bbbe8532141fc59ce596268143a308d1d40fedf385528b458",
7
}

Initiating a Transfer Transaction#

Here is an example of how to initiate a transfer transaction using the aelf Go SDK:

1
// Get token contract address.
2
tokenContractAddress, _ := aelf.GetContractAddressByName("AElf.ContractNames.Token")
3
fromAddress := aelf.GetAddressFromPrivateKey(aelf.PrivateKey)
4
methodName := "Transfer"
5
toAddress, _ := util.Base58StringToAddress("7s4XoUHfPuqoZAwnTV7pHWZAaivMiL8aZrDSnY9brE1woa8vz")
6


7
params := &pb.TransferInput{
8
    To:     toAddress,
9
    Symbol: "ELF",
10
    Amount: 1000000000,
11
    Memo:   "transfer in demo",
12
}
13
paramsByte, _ := proto.Marshal(params)
14


15
// Generate a transfer transaction.
16
transaction, _ := aelf.CreateTransaction(fromAddress, tokenContractAddress, methodName, paramsByte)
17
signature, _ := aelf.SignTransaction(aelf.PrivateKey, transaction)
18
transaction.Signature = signature
19


20
// Send the transfer transaction to aelf chain node.
21
transactionByets, _ := proto.Marshal(transaction)
22
sendResult, _ := aelf.SendTransaction(hex.EncodeToString(transactionByets))
23


24
time.Sleep(time.Duration(4) * time.Second)
25
transactionResult, _ := aelf.GetTransactionResult(sendResult.TransactionID)
26
fmt.Println(transactionResult)
27


28
// Query account balance.
29
ownerAddress, _ := util.Base58StringToAddress(fromAddress)
30
getBalanceInput := &pb.GetBalanceInput{
31
    Symbol: "ELF",
32
    Owner:  ownerAddress,
33
}
34
getBalanceInputByte, _ := proto.Marshal(getBalanceInput)
35


36
getBalanceTransaction, _ := aelf.CreateTransaction(fromAddress, tokenContractAddress, "GetBalance", getBalanceInputByte)
37
getBalanceTransaction.Params = getBalanceInputByte
38
getBalanceSignature, _ := aelf.SignTransaction(aelf.PrivateKey, getBalanceTransaction)
39
getBalanceTransaction.Signature = getBalanceSignature
40


41
getBalanceTransactionByets, _ := proto.Marshal(getBalanceTransaction)
42
getBalanceResult, _ := aelf.ExecuteTransaction(hex.EncodeToString(getBalanceTransactionByets))
43
balance := &pb.GetBalanceOutput{}
44
getBalanceResultBytes, _ := hex.DecodeString(getBalanceResult)
45
proto.Unmarshal(getBalanceResultBytes, balance)
46
fmt.Println(balance)

Web API#

You can see how the Web API of the node works at {chainAddress}/swagger/index.html. For example, on a local address: http://127.0.0.1:1235/swagger/index.html.

The usage of these methods is based on the AElfClient instance. If you don’t have one, please create it:

1
import ("github.com/AElfProject/aelf-sdk.go/client")
2


3
var aelf = client.AElfClient{
4
    Host:       "http://127.0.0.1:8000",
5
    Version:    "1.0",
6
    PrivateKey: "680afd630d82ae5c97942c4141d60b8a9fedfa5b2864fca84072c17ee1f72d9d",
7
}

GetChainStatus#

  • Web API path: /api/blockChain/chainStatus
  • Parameters : None
  • Returns:

    • Example:

    1
    chainStatus, err := aelf.GetChainStatus()

    GetContractFileDescriptorSet#

    Get the protobuf definitions related to a contract.

  • Web API path: /api/blockChain/contractFileDescriptorSet
  • Parameters :
  • Returns: []byte

    • Example:

    1
    contractFile, err := aelf.GetContractFileDescriptorSet("pykr77ft9UUKJZLVq15wCH8PinBSjVRQ12sD1Ayq92mKFsJ1i")

    GetBlockHeight#

    Get the current best height of the chain.

  • Web API path: /api/blockChain/blockHeight
  • Parameters : None
  • Returns: float64

    • Example:

    1
    height, err := aelf.GetBlockHeight()

    GetBlock#

    Get block information by block hash.

  • Web API path: /api/blockChain/block
  • Parameters :
  • Returns:

    • Example:

    1
    block, err := aelf.GetBlockByHash(blockHash, true)

    GetBlockByHeight#

  • Web API path: /api/blockChain/blockByHeight
  • Parameters :
  • Returns:

    • Example:

    1
    block, err := aelf.GetBlockByHeight(100, true)

    GetTransactionResult#

  • Web API path: /api/blockChain/transactionResult
  • Parameters :
  • Returns:

    • Example:

    1
    transactionResult, err := aelf.GetTransactionResult(transactionID)

    GetTransactionResults#

    Get multiple transaction results in a block.

  • Web API path: /api/blockChain/transactionResults
  • Parameters :
  • Returns: []TransactionResultDto

    • Example:

    1
    transactionResults, err := aelf.GetTransactionResults(blockHash, 0, 10)

    GetTransactionPoolStatus#

  • Web API path: /api/blockChain/transactionPoolStatus
  • Parameters : None
  • Returns: TransactionPoolStatusOutput

    • Example:

    1
    poolStatus, err := aelf.GetTransactionPoolStatus();

    SendTransaction#

  • Web API path: /api/blockChain/sendTransaction (POST)
  • Parameters :
  • Returns:

    • Example:

    1
    sendResult, err := aelf.SendTransaction(input)

    SendRawTransaction#

  • Web API path: /api/blockChain/sendTransaction (POST)
  • Parameters :
  • Returns:

    • Example:

    1
    sendRawResult, err := aelf.SendRawTransaction(input)

    SendTransactions#

  • Web API path: /api/blockChain/sendTransactions (POST)
  • Parameters :
  • Returns: []interface{}

    • Example:

    1
    results, err := aelf.SendTransactions(transactions)

    CreateRawTransaction#

    Creates an unsigned serialized transaction.

  • Web API path: /api/blockChain/rawTransaction (POST)
  • Parameters :
  • Returns:

    • Example:

    1
    result, err := aelf.CreateRawTransaction(input)

    ExecuteTransaction#

    Call a read-only method on a contract.

  • Web API path: /api/blockChain/executeTransaction (POST)
  • Parameters :
  • Returns: string

    • Example:

    1
    executeresult, err := aelf.ExecuteTransaction(rawTransaction)

    ExecuteRawTransaction#

    Call a read-only method on a contract.

  • Web API path: /api/blockChain/executeRawTransaction (POST)
  • Parameters :
  • Returns: string

    • Example:

    1
    executeRawresult, err := aelf.ExecuteRawTransaction(executeRawinput)

    GetPeers#

    Get peer info about the connected network nodes.

  • Web API path: /api/net/peers
  • Parameters :
  • Returns:

    • Example:

    1
    peers, err := aelf.GetPeers(false)

    AddPeer#

    Attempts to add a node to the connected network nodes.

  • Web API path: /api/net/peer (POST)
  • Parameters :
  • Returns: bool

    • Example:

    1
    addResult, err := aelf.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 :
  • Returns: bool

    • Example:

    1
    removeResult, err := aelf.RemovePeer("127.0.0.1:7001")

    CalculateTransactionFee#

    Estimate transaction fee.

  • Web API path: /api/blockChain/calculateTransactionFee (POST)
  • Parameters :
  • Returns:

    • Example:

    1
    calculateTransactionFee, err := aelf.CalculateTransactionFee(transactionFeeInput)

    GetNetworkInfo#

    Get the network information of the node.

  • Web API path: /api/net/networkInfo
  • Parameters : Empty
  • Returns:

    • Example:

    1
    networkInfo, err := aelf.GetNetworkInfo()

    aelf Client#

    IsConnected#

    Check if the SDK is successfully connected to the blockchain.

  • Parameters: None
  • Returns :

    • Example:

    1
    isConnected := aelf.IsConnected()

    GetGenesisContractAddress#

  • Parameters: None
  • Returns :

    • Example:

    1
    contractAddress, err := aelf.GetGenesisContractAddress()

    GetContractAddressByName#

    Get the address of a contract by its name hash.

  • Parameters:
  • Returns :

    • Example:

    1
    contractAddress, err := aelf.GetContractAddressByName("AElf.ContractNames.Token")

    CreateTransaction#

    Build a transaction with the provided parameters.

  • Parameters:
  • Returns :

    • Example:

    1
    transaction, err := aelf.CreateTransaction(fromAddress, toAddress, methodName, param)

    GetFormattedAddress#

    Convert an address to a displayable string format: symbol_base58-string_base58-string-chain-id.

  • Parameters:
  • Returns :

    • Example:

    1
    formattedAddress, err := aelf.GetFormattedAddress(address)

    SignTransaction#

    Sign a transaction using a private key.

  • Parameters:
  • Returns :

    • Example:

    1
    signature, err := aelf.SignTransaction(privateKey, transaction)

    GetAddressFromPubKey#

  • Parameters:
  • Returns :

    • Example:

    1
    address := aelf.GetAddressFromPubKey(pubKey)

    GetAddressFromPrivateKey#

  • Parameters:
  • Returns :

    • Example:

    1
    address := aelf.GetAddressFromPrivateKey(privateKey)

    GenerateKeyPairInfo#

  • Parameters: None
  • Returns :

    • Example:

    1
    keyPair := aelf.GenerateKeyPairInfo()

    Supported Go Version#

  • Go 1.13

    • Edited on: 15 July 2024 05:49:28 GMT+0