Developer Resources
Block ExplorerGitHubRun a NodeMigration GuideETN Testnet Faucet
  • Overview
  • Foundational topics
    • Intro to the Electroneum Smart Chain
    • Intro to ETN
    • Intro to dapps
    • Web2 vs Web3
    • Accounts
    • Transactions
    • Blocks
    • Electroneum Virtual Machine (EVM)
      • Opcodes
    • Gas and Fees
    • Nodes and clients
    • Networks
    • Consensus mechanisms
      • IBFT
  • Electroneum Stack
    • Intro to the stack
    • Smart contracts
    • Development networks
    • Development frameworks
    • Electroneum client APIs
      • JavaScript APIs
      • JSON-RPC
    • Storage
    • Integrated Development Environments (IDEs)
    • Metamask
  • Advanced
    • Bridges
    • Standards
      • Token standards
        • ERC-20 Fungible Tokens
        • ERC-721 NFTs
    • Oracles
    • Networking layer
      • Network addresses
    • Data structures and encoding
      • Patricia Merkle Trie
      • Recursive-length prefix (RLP)
      • Web3 secret storage definition
  • Design fundamentals
    • Intro to design and UX
  • ETN-SC Client
    • Getting started
      • Introduction
      • Hardware requirements
      • Instaling ETN-SC
    • Fundamentals
      • Command-line options
      • Security
      • Sync-modes
      • Account management
      • Databases
      • Backup & restore
      • Logs
      • Connecting to peers
      • Pruning
      • Private networks
      • Config files
      • Light client
    • Interacting with ETN-SC
      • JSON-RPC Server
        • Batch requests
        • Real-time events
      • JSON-RPC Namespaces
        • admin
        • clique
        • debug
        • eth
        • istanbul
        • les
        • miner
        • net
        • personal
        • txpool
      • JS Console
      • JS Console 2: Contracts
      • GraphQL Server
    • Developers
      • Introduction
      • Dapp developers
        • Dev mode
        • Go API
        • Go Account Management
        • Go Contract Bindings
      • EVM tracing
        • Introduction
        • Basic traces
        • Built-in tracers
        • Custom EVM tracer
        • Tutorial for JavaScript tracing
      • ETN-SC developer
        • Developer guide
        • Disclosures
        • DNS discovery setup guide
        • Code review guidelines
      • Contributing
    • Monitoring
      • Creating Dashboards
      • Understanding Dashboards
      • Ethstats
      • Metrics
    • Tools
      • Clef
        • Introduction
        • APIs
        • Rules
        • Setup
        • Datatypes
        • Tutorial
        • Clique-signing
      • abigen
      • devp2p
    • FAQs
  • Migration to Smart Chain
    • Overview
    • How to Migrate
      • ETN Online Wallets
      • Paper Wallets
      • CLI Wallet Users
      • Exchange Holders
      • Exchanges
    • Bridge Smart Contract
  • Misc. Guides
    • Set up Ledger + Metamask
  • MY.ELECTRONEUM.COM
    • Vendor API
Powered by GitBook
On this page
  • Overview
  • Go packages
  • Tutorial
  • Instantiating a client
  • Interacting with the client
  • Querying client for data
  • Querying past events
  • Sending a transaction
  • gethclient
  • Summary

Was this helpful?

  1. ETN-SC Client
  2. Developers
  3. Dapp developers

Go API

PreviousDev modeNextGo Account Management

Last updated 1 year ago

Was this helpful?

Overview

ETN-SC's reusable Go libraries focus on three main usage areas:

  • Simplified client side account management

  • Remote node interfacing via different transports

  • Contract interactions through auto-generated bindings

The libraries are updated synchronously with the ETN-SC GitHub repository. The Go libraries can be viewed in full at .

Go packages

The electroneum-sc library is distributed as a collection of standard Go packages straight from electroneum-sc's GitHub repository. The packages can be used directly via the official Go toolkit, without needing any third party tools.

The canonical import path for ETN-SC is github.com/electroneum/electroneum-sc, with all packages residing underneath. Although there are most developers will only care about a limited subset.

All the ETN-SC packages can be downloaded using:

$ go get -d github.com/electroneum/electroneum-sc/...

More Go API support for dapp developers can be found on the and pages.

Tutorial

This section includes some basic usage examples for the ethclient and gethclient packages available as part of the Go API. The ethclient package provides a client that implements the full Electroneum JSON-RPC API, whereas gethclient offers the ETN-SC-specific API.

Instantiating a client

The client is an instance of the Client struct which has associated functions that wrap requests to the Electroneum or ETN-SC RPC API endpoints.

A client is instantiated by passing a raw url or path to an ipc file to the client's Dial function. In the following code snippet the path to the ipc file for a local ETN-SC node is provided to ethclient.Dial().

// create instance of ethclient and assign to cl
cl, err := ethclient.Dial("/tmp/etn-sc.ipc")
if err != nil {
	panic(err)
}
_ = cl

Interacting with the client

Querying client for data

A simple starting point is to fetch the chain ID from the client. This e.g. is needed when signing a transaction as is to be seen in the next section.

chainid, err := cl.ChainID(context.Background())
if err != nil {
    return err
}

Unlike ChainID, many functions require arguments other than context. The Go API takes in and returns high-level types which are used in ETN-SC internals as well to simplify programming and remove the need for knowing how data needs to be formatted exactly as per the JSON-RPC API spec. For example to find out the nonce for an account at a given block the address needs to be provided as a common.Address type and the block number as a *big.Int:

addr := common.HexToAddress("0xb02A2EdA1b317FBd16760128836B0Ac59B560e9D")
nonce, err := cl.NonceAt(context.Background(), addr, big.NewInt(14000000))

Querying past events

Contracts emit events during execution which can be queried from the client. The parameters for the event one is interested in have to be filled out in the ethereum.FilterQuery object. This includes which event topics are of interest, from which contracts and during which range of blocks. The example below queries Transfer events of all ERC-20 tokens for the last 10 blocks:

blockNumber, err := cl.BlockNumber(context.Background())
if err != nil {
	fmt.Println("Failed to retrieve block number:", err)
	return
}
blockNumberBig := big.NewInt(int64(blockNumber))

eventSignatureBytes := []byte("Transfer(address,address,uint256)")
eventSignaturehash := crypto.Keccak256Hash(eventSignatureBytes)

q := ethereum.FilterQuery{
	FromBlock: new(big.Int).Sub(blockNumberBig, big.NewInt(10)),
	ToBlock:   blockNumberBig,
	Topics: [][]common.Hash{
		{eventSignaturehash},
	},
}

logs, err := cl.FilterLogs(context.Background(), q)
if err != nil {
    return err
}

Sending a transaction

Sending a transaction is achieved using the SendTransaction() function. SendTransaction takes an instance of context.Context as its leading argument and a signed transaction as its second argument. The signed transaction must be generated in advance. Building the signed transaction is a multi-stage process that requires first generating a key pair if none exists already, retrieving some chain data and defining sender and recipient addresses. Then these data can be collected into a transaction object and signed. The resulting signed transaction can then be passed to SendTransaction.

The example below assumes the following key pair has already been generated:

// SK and ADDR are the secret key and sender address
SK   = "0xaf5ead4413ff4b78bc94191a2926ae9ccbec86ce099d65aaf469e9eb1a0fa87f"
ADDR = "0x6177843db3138ae69679A54b95cf345ED759450d"

The secret key and address can be used to send a transaction. In the example below 1 ETN is sent from the address ADDR to an arbitrary recipient.

import (
	"context"
	"math/big"

	"github.com/electroneum/electroneum-sc/common"
	"github.com/electroneum/electroneum-sc/core/types"
	"github.com/electroneum/electroneum-sc/crypto"
	"github.com/electroneum/electroneum-sc/ethclient"
	"github.com/electroneum/electroneum-sc/params"
)

// sendTransaction sends a transaction with 1 ETN to a specified address.
func sendTransaction(cl *ethclient.Client) error {
	var (
		sk       = crypto.ToECDSAUnsafe(common.FromHex(SK))
		to       = common.HexToAddress("0xb02A2EdA1b317FBd16760128836B0Ac59B560e9D")
		value    = new(big.Int).Mul(big.NewInt(1), big.NewInt(params.Ether))
		sender   = common.HexToAddress(ADDR)
		gasLimit = uint64(21000)
	)
	// Retrieve the chainid (needed for signer)
	chainid, err := cl.ChainID(context.Background())
	if err != nil {
		return err
	}
	// Retrieve the pending nonce
	nonce, err := cl.PendingNonceAt(context.Background(), sender)
	if err != nil {
		return err
	}
	// Get suggested gas price
	tipCap, _ := cl.SuggestGasTipCap(context.Background())
	feeCap, _ := cl.SuggestGasPrice(context.Background())
	// Create a new transaction
	tx := types.NewTx(
		&types.DynamicFeeTx{
			ChainID:   chainid,
			Nonce:     nonce,
			GasTipCap: tipCap,
			GasFeeCap: feeCap,
			Gas:       gasLimit,
			To:        &to,
			Value:     value,
			Data:      nil,
		})
	// Sign the transaction using our keys
	signedTx, _ := types.SignTx(tx, types.NewLondonSigner(chainid), sk)
	// Send the transaction to our node
	return cl.SendTransaction(context.Background(), signedTx)
}

gethclient

An instance of gethclient can be used in exactly the same way as ethclient. However, gethclient includes ETN-SC-specific API methods. These additional methods are:

CallContract()
CreateAccessList()
GCStats()
GetNodeInfo()
GetProof()
MemStats()
SetHead()
SubscribePendingTransactions()

Note that both ethclient and gethclient have a CallContract() function - the difference is that the gethclient version includes an overrides argument.

Summary

There are a wide variety of Go APIs available for dapp developers that abstract away the complexity of interacting with Electroneum using a set of composable, reusable functions provided by ETN-SC.

The client can now be used to handle requests to the ETN-SC node using the full JSON-RPC API. For example, the function BlockNumber() wraps a call to the eth_blockNumber endpoint. The function SendTransaction wraps a call to eth_sendTransaction. The full list of client methods can be found .

Frequently, the functions take an instance of the Context type as their leading argument. This defines context about requests sent from the application such as deadlines, cancellation signals etc. More information on this can be found in the . An empty context instance can be created using Context.Background().

Details relating to these endpoints can be found at or the ETN-SC .

Go Packages
lots of them
Go Contract Bindings
Go Account Management
here
Go documentation
pkg.go.dev
GitHub