Skip to main content



The JSON RPC module implements the JSON RPC API layer, something that dApp developers use to interact with the blockchain.

It includes support for standard json-rpc endpoints, as well as websocket endpoints.

Blockchain Interface#

The Polygon SDK uses the blockchain interface to define all the methods that the JSON RPC module needs to use, in order to deliver its endpoints.

The blockchain interface is implemented by the Minimal server. It is the base implementation that's passed into the JSON RPC layer.

type blockchainInterface interface {
// Header returns the current header of the chain (genesis if empty)
Header() *types.Header
// GetReceiptsByHash returns the receipts for a hash
GetReceiptsByHash(hash types.Hash) ([]*types.Receipt, error)
// Subscribe subscribes for chain head events
SubscribeEvents() blockchain.Subscription
// GetHeaderByNumber returns the header by number
GetHeaderByNumber(block uint64) (*types.Header, bool)
// GetAvgGasPrice returns the average gas price
GetAvgGasPrice() *big.Int
// AddTx adds a new transaction to the tx pool
AddTx(tx *types.Transaction) error
// State returns a reference to the state
State() state.State
// BeginTxn starts a transition object
BeginTxn(parentRoot types.Hash, header *types.Header) (*state.Transition, error)
// GetBlockByHash gets a block using the provided hash
GetBlockByHash(hash types.Hash, full bool) (*types.Block, bool)
// ApplyTxn applies a transaction object to the blockchain
ApplyTxn(header *types.Header, txn *types.Transaction) ([]byte, bool, error)

ETH Endpoints#

All the standard JSON RPC endpoints are implemented in:


Filter Manager#

The Filter Manager is a service that runs alongside the JSON RPC server.

It provides support for filtering blocks on the blockchain.
Specifically, it includes both a log and a block level filter.

The Filter Manager relies heavily on Subscription Events, mentioned in the Blockchain section

type Filter struct {
id string
// block filter
block *headElem
// log cache
logs []*Log
// log filter
logFilter *LogFilter
// index of the filter in the timer array
index int
// next time to timeout
timestamp time.Time
// websocket connection
ws wsConn
type FilterManager struct {
logger hclog.Logger
store blockchainInterface
closeCh chan struct{}
subscription blockchain.Subscription
filters map[string]*Filter
lock sync.Mutex
updateCh chan struct{}
timer timeHeapImpl
timeout time.Duration
blockStream *blockStream

Filter Manager events get dispatched in the Run method:

func (f *FilterManager) Run() {
// watch for new events in the blockchain
watchCh := make(chan *blockchain.Event)
go func() {
for {
evnt := f.subscription.GetEvent()
if evnt == nil {
watchCh <- evnt
var timeoutCh <-chan time.Time
for {
// check for the next filter to be removed
filter := f.nextTimeoutFilter()
if filter == nil {
timeoutCh = nil
} else {
timeoutCh = time.After(filter.timestamp.Sub(time.Now()))
select {
case evnt := <-watchCh:
// new blockchain event
if err := f.dispatchEvent(evnt); err != nil {
f.logger.Error("failed to dispatch event", "err", err)
case <-timeoutCh:
// timeout for filter
if !f.Uninstall( {
f.logger.Error("failed to uninstall filter", "id",
case <-f.updateCh:
// there is a new filter, reset the loop to start the timeout timer
case <-f.closeCh:
// stop the filter manager

๐Ÿ“œ Resources#