# Jason RPC

### Overview <a href="#overview" id="overview"></a>

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**](https://eth.wiki/json-rpc/API), as well as websocket endpoints.

### Blockchain Interface <a href="#blockchain-interface" id="blockchain-interface"></a>

The xBuildApp 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**](https://dominicluu.gitbook.io/blockchaindocs/architecture/modules/minimal) server. It is the base implementation that's passed into the JSON RPC layer.

Copy

```
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)

	stateHelperInterface
}
```

### ETH Endpoints <a href="#eth-endpoints" id="eth-endpoints"></a>

All the standard JSON RPC endpoints are implemented in:

Copy

```
jsonrpc/eth_endpoint.go
```

### Filter Manager <a href="#filter-manager" id="filter-manager"></a>

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](https://github.com/ZChain-168168/zchain-docs/blob/main/docs/architecture/modules/blockchain/README.md#blockchain-subscriptions) section

Copy

```
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:

Copy

```
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 {
				return
			}
			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(filter.id) {
				f.logger.Error("failed to uninstall filter", "id", 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
			return
		}
	}
}
```

### 📜 Resources <a href="#resources" id="resources"></a>

* [**Ethereum JSON-RPC**](https://eth.wiki/json-rpc/API)