interfaces.go

// Copyright 2016 The go-ethereum Authors
// This file is part of the go-ethereum library.
//
// The go-ethereum library is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// The go-ethereum library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.

// Package ethereum defines interfaces for interacting with Ethereum.
// 이더리움 패키지는 이더리움과 통신하는 인터페이스를 정의한다
package ethereum

import (
	"context"
	"errors"
	"math/big"

	"github.com/ethereum/go-ethereum/common"
	"github.com/ethereum/go-ethereum/core/types"
)

// NotFound is returned by API methods if the requested item does not exist.
var NotFound = errors.New("not found")

// TODO: move subscription to package event

// Subscription represents an event subscription where events are
// delivered on a data channel.
// Subscription 인터페이스는 데이터 채널위에서 전송되는 이벤트를 구독한다.
type Subscription interface {
	// Unsubscribe cancels the sending of events to the data channel
	// and closes the error channel.
	Unsubscribe()
	// Err returns the subscription error channel. The error channel receives
	// a value if there is an issue with the subscription (e.g. the network connection
	// delivering the events has been closed). Only one value will ever be sent.
	// The error channel is closed by Unsubscribe.
	Err() <-chan error
}

// ChainReader provides access to the blockchain. The methods in this interface access raw
// data from either the canonical chain (when requesting by block number) or any
// blockchain fork that was previously downloaded and processed by the node. The block
// number argument can be nil to select the latest canonical block. Reading block headers
// should be preferred over full blocks whenever possible.
//
// The returned error is NotFound if the requested item does not exist.
// 체인리더 인터페이스는 블록체인에 대한 접근을 제공한다.
// 이 인터페이스 내부의 함수들은 캐노니컬 체인(블록넘버로 접근했을때)과 
// 기존에 이 노드에 다운받았거나 처리되었던 다른 포크체인의 저수준 데이터를 접근한다.
// 블록 번호 인자는 마지막 캐노니컬 블록을 선택하기 위해 nil일수 있다.
// 블록헤더를 읽는것은 풀불록이 가능한 상태에서 읽는것이 선호된다.
type ChainReader interface {
	BlockByHash(ctx context.Context, hash common.Hash) (*types.Block, error)
	BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error)
	HeaderByHash(ctx context.Context, hash common.Hash) (*types.Header, error)
	HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error)
	TransactionCount(ctx context.Context, blockHash common.Hash) (uint, error)
	TransactionInBlock(ctx context.Context, blockHash common.Hash, index uint) (*types.Transaction, error)

	// This method subscribes to notifications about changes of the head block of
	// the canonical chain.
	// 이 함수는 캐노니컬 체인의 헤드블록의 변경에 대한 노티를 구독한다
	SubscribeNewHead(ctx context.Context, ch chan<- *types.Header) (Subscription, error)
}

// TransactionReader provides access to past transactions and their receipts.
// Implementations may impose arbitrary restrictions on the transactions and receipts that
// can be retrieved. Historic transactions may not be available.
//
// Avoid relying on this interface if possible. Contract logs (through the LogFilterer
// interface) are more reliable and usually safer in the presence of chain
// reorganisations.
//
// The returned error is NotFound if the requested item does not exist.
// 트렌젝션리더 인터페이스는 지난 트렌젝션들과 그들의 영수증에 대한 접근을 제공한다.
// 구현들은 아마도 반환 가능한 트렌젝션과 영수증에 대해 임의의 제약을 부과할것이다.
// historic한 트렌젝션들은 가능하지 않을 수도 있다.
// 가능하다면 이함수를 신뢰하는 것을 회피하라. 체인 재구성에 직면한 상황에서
// 로그필터러 인터페이스를 통해 얻는 계약 로그가 보다 더 신뢰가능하고 안전하다 

type TransactionReader interface {
	// TransactionByHash checks the pool of pending transactions in addition to the
	// blockchain. The isPending return value indicates whether the transaction has been
	// mined yet. Note that the transaction may not be part of the canonical chain even if
	// it's not pending.
	// TransactionByHash 함수는 블록체인에 추가할 대기 트렌젝션 풀을 체크한다.
	// isPending의 반환값은 아직 마이닝되지 않은 트렌젝션을 가리킨다.
	// 그 트렌젝션은 대기중이 아니라도 캐노니컬 체인의 부분이 아닐수 있다는 것을 기억하라. 
	TransactionByHash(ctx context.Context, txHash common.Hash) (tx *types.Transaction, isPending bool, err error)
	// TransactionReceipt returns the receipt of a mined transaction. Note that the
	// transaction may not be included in the current canonical chain even if a receipt
	// exists.
	// Transaction Receipt 함수는 채굴된 트렌젝션의 영수증을 반환한다.
	// 영수증이 존재하더라도 그 트렌젝션은 현재 캐노니컬 체인에 포함되지 않을수 있다.
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error)
}

// ChainStateReader wraps access to the state trie of the canonical blockchain. Note that
// implementations of the interface may be unable to return state values for old blocks.
// In many cases, using CallContract can be preferable to reading raw contract storage.
// 체인상태리더 인터페이스는 캐노니컬 블록체인의 상태트라이에 대한 접근을 포함한다.
// 인터페이스의 구현들은 오래된 블럭에 대한 상태 값을 반환하는 것이 
// 불가능할수도 있다는 것을 기억하라
// 대부분의 상황에서, 저수준 계약 저장소를 읽는 것은 
// CallContract 함수를 사용하는 것이 선호된다
type ChainStateReader interface {
	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
	StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *big.Int) ([]byte, error)
	CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error)
	NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error)
}

// SyncProgress gives progress indications when the node is synchronising with
// the Ethereum network.
// SyncProgress 구조체는 노드가 이더리움 네트워크가 싱크중일때 진행상황을 알려준다
type SyncProgress struct {
	StartingBlock uint64 // Block number where sync began
	CurrentBlock  uint64 // Current block number where sync is at
	HighestBlock  uint64 // Highest alleged block number in the chain
	PulledStates  uint64 // Number of state trie entries already downloaded
	KnownStates   uint64 // Total number of state trie entries known about
}

// ChainSyncReader wraps access to the node's current sync status. If there's no
// sync currently running, it returns nil.
// 체인싱크리더 인터페이스는 노드의 현재 동기화 상태에 접근을 포함한다.
// 만약 현재 싱크중이지 않다면 nil을 리턴한다
type ChainSyncReader interface {
	SyncProgress(ctx context.Context) (*SyncProgress, error)
}

// CallMsg contains parameters for contract calls.
// CallMsg 구조체는 계약 호출을 위한 파라미터를 포함한다
type CallMsg struct {
	From     common.Address  // the sender of the 'transaction'
	To       *common.Address // the destination contract (nil for contract creation)
	Gas      uint64          // if 0, the call executes with near-infinite gas
	GasPrice *big.Int        // wei <-> gas exchange ratio
	Value    *big.Int        // amount of wei sent along with the call
	Data     []byte          // input data, usually an ABI-encoded contract method invocation
}

// A ContractCaller provides contract calls, essentially transactions that are executed by
// the EVM but not mined into the blockchain. ContractCall is a low-level method to
// execute such calls. For applications which are structured around specific contracts,
// the abigen tool provides a nicer, properly typed way to perform calls.
// 계약호출 인터페이스는블록체인에 채굴되어 포함되지 않았지만
// EVM에 의해 실행될 필수 트렌젝션들에 대한 계약 호출을 제공한다
// 이 인터페이스는 위와같은 호출을 실행시키는 저수준 함수이다.
// 특정계약을 구성하는 프로그램들을 위해 abigen tool 인터페이스는 
// 호출을 수행하기 위한 보다 좋고 적합한 방법을 제공한다
type ContractCaller interface {
	CallContract(ctx context.Context, call CallMsg, blockNumber *big.Int) ([]byte, error)
}

// FilterQuery contains options for contract log filtering.
// 필터쿼리 구조체는 계약 로그 필터링을 위한 옵션을 포함한다
type FilterQuery struct {
	FromBlock *big.Int         // beginning of the queried range, nil means genesis block
	ToBlock   *big.Int         // end of the range, nil means latest block
	Addresses []common.Address // restricts matches to events created by specific contracts

	// The Topic list restricts matches to particular event topics. Each event has a list
	// of topics. Topics matches a prefix of that list. An empty element slice matches any
	// topic. Non-empty elements represent an alternative that matches any of the
	// contained topics.
	//
	// Examples:
	// {} or nil          matches any topic list
	// {{A}}              matches topic A in first position
	// {{}, {B}}          matches any topic in first position, B in second position
	// {{A}}, {B}}        matches topic A in first position, B in second position
	// {{A, B}}, {C, D}}  matches topic (A OR B) in first position, (C OR D) in second position
	Topics [][]common.Hash
}

// LogFilterer provides access to contract log events using a one-off query or continuous
// event subscription.
//
// Logs received through a streaming query subscription may have Removed set to true,
// indicating that the log was reverted due to a chain reorganisation.
// 로그 필터러 인터페이스는 한번의 쿼리나 연속적인 이벤트 구독을 이용하는
// 계약 로그 이벤트에 대한 접근을 제공한다 
type LogFilterer interface {
	FilterLogs(ctx context.Context, q FilterQuery) ([]types.Log, error)
	SubscribeFilterLogs(ctx context.Context, q FilterQuery, ch chan<- types.Log) (Subscription, error)
}

// TransactionSender wraps transaction sending. The SendTransaction method injects a
// signed transaction into the pending transaction pool for execution. If the transaction
// was a contract creation, the TransactionReceipt method can be used to retrieve the
// contract address after the transaction has been mined.
//
// The transaction must be signed and have a valid nonce to be included. Consumers of the
// API can use package accounts to maintain local private keys and need can retrieve the
// next available nonce using PendingNonceAt.
// TransactionSender 인터페이스는 trasanction 전송을 포함한다. 
// SendTransaction 함수는 사인된 트렌젝션을 실행하기 위해 대기 트렌젝션 풀에 주입한다.
// 만약 트렌젝션이 계약의 생성이였다면, 트렌젝션이 마이닝 된후 계약 주소를 반환받기 위해
// TransactionReceipt 함수가 사용될 수 있다.
type TransactionSender interface {
	SendTransaction(ctx context.Context, tx *types.Transaction) error
}

// GasPricer wraps the gas price oracle, which monitors the blockchain to determine the
// optimal gas price given current fee market conditions.
// GasPricer 인터페이스는 블록체인이 주어진 현재 마켓의 수수료 상태에서
// 최적의 가스가격을 결정하도록 모니터링 하는 GasPriceOracle을 포함한다
type GasPricer interface {
	SuggestGasPrice(ctx context.Context) (*big.Int, error)
}

// A PendingStateReader provides access to the pending state, which is the result of all
// known executable transactions which have not yet been included in the blockchain. It is
// commonly used to display the result of ’unconfirmed’ actions (e.g. wallet value
// transfers) initiated by the user. The PendingNonceAt operation is a good way to
// retrieve the next available transaction nonce for a specific account.
// PendingStateReader 인터페이스는 아직 블록체인에 포함되지 않은 
// 모든 알려진 실행가능한 트렌젝션의 대기상태로의 접근을 지원한다
type PendingStateReader interface {
	PendingBalanceAt(ctx context.Context, account common.Address) (*big.Int, error)
	PendingStorageAt(ctx context.Context, account common.Address, key common.Hash) ([]byte, error)
	PendingCodeAt(ctx context.Context, account common.Address) ([]byte, error)
	PendingNonceAt(ctx context.Context, account common.Address) (uint64, error)
	PendingTransactionCount(ctx context.Context) (uint, error)
}

// PendingContractCaller can be used to perform calls against the pending state.
// PendingContractCaller 인터페이스는 대기상태에 대한 수행 호출을 위해 사용될수 있다
type PendingContractCaller interface {
	PendingCallContract(ctx context.Context, call CallMsg) ([]byte, error)
}

// GasEstimator wraps EstimateGas, which tries to estimate the gas needed to execute a
// specific transaction based on the pending state. There is no guarantee that this is the
// true gas limit requirement as other transactions may be added or removed by miners, but
// it should provide a basis for setting a reasonable default.
// GasEstimator 인터페이스는 대기상태에 따른 특정 트렌젝션을 실행하기 위한
// 가스를 예측하기 위한 EstimateGas 함수를 포함한다.
type GasEstimator interface {
	EstimateGas(ctx context.Context, call CallMsg) (uint64, error)
}

// A PendingStateEventer provides access to real time notifications about changes to the
// pending state.
// PendingStateEventer 인터페이스는 대기상태의 변화에 대한 실시간 알람을 제공한다
type PendingStateEventer interface {
	SubscribePendingTransactions(ctx context.Context, ch chan<- *types.Transaction) (Subscription, error)
}