etherscan

Documentation

Overview

Package etherscan provides a client for interacting with Etherscan's API, enabling the retrieval of blockchain data and supporting rate-limited API key rotation.

Index

• type Contract
  • func (c Contract) MarshalBinary() ([]byte, error)
  • func (c Contract) UnmarshalBinary(data []byte) error
• type ContractCreation
  • func (c *ContractCreation) GetTransactionHash() common.Hash
  • func (c *ContractCreation) MarshalBinary() ([]byte, error)
  • func (c *ContractCreation) UnmarshalBinary(data []byte) error
• type ContractCreationResponse
• type ContractResponse
• type ErrorResponse
• type Options
  • func (o *Options) Validate() error
• type Provider
  • func NewProvider(ctx context.Context, cache *redis.Client, opts *Options) (*Provider, error)
  • func (e *Provider) CacheKey(method string, path string) string
  • func (e *Provider) GetNextKey() string
  • func (e *Provider) GetRateLimiter() *utils.RateLimiter
  • func (e *Provider) ProviderName() string
  • func (e *Provider) QueryContractCreationTx(ctx context.Context, addr common.Address) (*ContractCreation, error)
  • func (e *Provider) ScanContract(ctx context.Context, addr common.Address) (*Contract, error)
• type ProviderType
  • func (p ProviderType) String() string

Types

type Contract

type Contract struct {
	SourceCode           interface{} `json:"SourceCode"`           // The source code of the contract. Can be a plain string or a structured metadata object.
	ABI                  string      `json:"ABI"`                  // The ABI (Application Binary Interface) of the contract in JSON format.
	Name                 string      `json:"ContractName"`         // The name of the contract.
	CompilerVersion      string      `json:"CompilerVersion"`      // The version of the Solidity compiler used to compile the contract.
	OptimizationUsed     string      `json:"OptimizationUsed"`     // Indicates if optimization was used during compilation.
	Runs                 string      `json:"Runs"`                 // The number of runs specified for the optimizer.
	ConstructorArguments string      `json:"ConstructorArguments"` // The constructor arguments used when deploying the contract.
	EVMVersion           string      `json:"EVMVersion"`           // The version of the Ethereum Virtual Machine (EVM) for which the contract was compiled.
	Library              string      `json:"Library"`              // Specifies any library used in the contract.
	LicenseType          string      `json:"LicenseType"`          // The license type under which the contract source code is provided.
	Proxy                string      `json:"Proxy"`                // Indicates if the contract is a proxy contract.
	Implementation       string      `json:"Implementation"`       // The address of the implementation contract, if this is a proxy contract.
	SwarmSource          string      `json:"SwarmSource"`          // The Swarm source of the contract's metadata.
}

Contract represents the detailed information of a smart contract including its source code, ABI, and other metadata as returned by the Etherscan API.

func (Contract) MarshalBinary

func (c Contract) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface for Contract. It returns the JSON encoding of the contract.

func (Contract) UnmarshalBinary

func (c Contract) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface for Contract. It parses a JSON-encoded contract and stores the result in the Contract.

type ContractCreation

type ContractCreation struct {
	Address         string `json:"contractAddress"` // The smart contract address.
	CreatorAddress  string `json:"contractCreator"` // The address of the creator of the contract.
	TransactionHash string `json:"txHash"`          // The hash of the transaction that created the contract.
}

ContractCreation represents the creation details of a smart contract, including its address, creator's address, and the transaction hash of the creation transaction.

func (*ContractCreation) GetTransactionHash

func (c *ContractCreation) GetTransactionHash() common.Hash

GetTransactionHash returns the Ethereum transaction hash of the contract creation as a common.Hash.

func (*ContractCreation) MarshalBinary

func (c *ContractCreation) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler to provide binary encoding for a ContractCreation.

func (*ContractCreation) UnmarshalBinary

func (c *ContractCreation) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler to provide binary decoding for a ContractCreation.

type ContractCreationResponse

type ContractCreationResponse struct {
	Status  string              `json:"status"`  // The response status.
	Message string              `json:"message"` // A descriptive message of the response.
	Result  []*ContractCreation `json:"result"`  // The contract creation details.
}

ContractCreationResponse encapsulates the API response for a contract creation query, containing the status, message, and the result of the query.

type ContractResponse

type ContractResponse struct {
	Status  string     `json:"status"`  // The status of the API response, "1" for success and "0" for failure.
	Message string     `json:"message"` // A message accompanying the status, often indicating the nature of any error.
	Result  []Contract `json:"result"`  // The contracts returned by the query, typically containing a single contract.
}

ContractResponse encapsulates the response structure for contract queries made to the Etherscan API.

type ErrorResponse

type ErrorResponse struct {
	Status  string `json:"status"`  // The status code of the response.
	Message string `json:"message"` // A message describing the error.
	Result  string `json:"result"`  // The result field, typically empty in error responses.
}

ErrorResponse represents the standard error response format returned by Etherscan's API.

type Options

type Options struct {
	// Provider specifies the blockchain explorer service (e.g., Etherscan, BscScan) to be used.
	Provider ProviderType `json:"provider" yaml:"provider" mapstructure:"provider"`

	// Endpoint is the base URL of the blockchain explorer API.
	// It determines where the client sends its requests.
	Endpoint string `json:"endpoint" yaml:"endpoint" mapstructure:"endpoint"`

	// RateLimit specifies the maximum number of requests that the client is allowed to make to the
	// blockchain explorer API within a fixed time window. Consult Etherscan documentation.
	RateLimit int `json:"rateLimit" yaml:"rateLimit" mapstructure:"rateLimit"`

	// Keys contains a list of API keys used for authenticating requests to the blockchain explorer API.
	// The client can rotate through these keys to manage rate limits.
	Keys []string `json:"keys" yaml:"keys" mapstructure:"keys"`
}

Options holds the configuration settings for an etherscan client. These settings define how the client interacts with the blockchain explorer APIs.

func (*Options) Validate

func (o *Options) Validate() error

Validate checks the integrity and completeness of the Options settings. It ensures that all necessary configurations are properly set and valid, including non-empty Endpoint, at least one API key, and a supported Provider.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider encapsulates the logic for interacting with the Etherscan API, including handling API keys and caching responses.

func NewProvider

func NewProvider(ctx context.Context, cache *redis.Client, opts *Options) (*Provider, error)

NewProvider initializes a new EtherScanProvider with specified options and cache. It returns an error if the provided options are invalid or incomplete.

func (*Provider) CacheKey

func (e *Provider) CacheKey(method string, path string) string

CacheKey generates a unique cache key for storing and retrieving API responses. The key is composed using the API method and path.

func (*Provider) GetNextKey

func (e *Provider) GetNextKey() string

GetNextKey selects the next API key to use for a request in a round-robin fashion. This method ensures even distribution of request load across all configured API keys.

func (*Provider) GetRateLimiter

func (e *Provider) GetRateLimiter() *utils.RateLimiter

GetRateLimiter returns the instantiated rate limiter

func (*Provider) ProviderName

func (e *Provider) ProviderName() string

ProviderName returns the name of the provider as specified in the options.

func (*Provider) QueryContractCreationTx

func (e *Provider) QueryContractCreationTx(ctx context.Context, addr common.Address) (*ContractCreation, error)

QueryContractCreationTx queries the blockchain for contract creation details given a contract address. It first checks for cached responses; if none are found, it queries the Etherscan API directly.

This function returns a ContractCreation if found, or an error if the query fails, the response is not satisfactory, or the result cannot be properly unmarshaled.

func (*Provider) ScanContract

func (e *Provider) ScanContract(ctx context.Context, addr common.Address) (*Contract, error)

ScanContract retrieves the source code and other related details of a smart contract from the Ethereum blockchain using the Etherscan API. It attempts to retrieve the data from a local cache first; if not available, it fetches it from the API. The address of the contract (addr) must be provided. On success, a Contract instance containing the source code and related metadata is returned. Various errors encountered during the data retrieval and parsing process, including API and network errors, are propagated.

type ProviderType

type ProviderType string

ProviderType defines a type for different blockchain explorer services supported by the etherscan package.

const (
	// EtherScan represents the Etherscan service for the Ethereum blockchain.
	EtherScan ProviderType = "etherscan"

	// BscScan represents the BSCScan service for the Binance Smart Chain.
	BscScan ProviderType = "bscscan"
)

func (ProviderType) String

func (p ProviderType) String() string

String returns the string representation of the ProviderType.