From e92bef4414c8d21d22454a6c479f9fa2988fce47 Mon Sep 17 00:00:00 2001
From: tgmichel <telmo@purestake.com>
Date: Wed, 22 Jul 2020 16:31:47 +0200
Subject: [PATCH] Document EthereumRuntimeApi and README update (#81)

* Document EthereumRuntimeApi

* Update readme

* Styling fixes
---
 README.md                 | 19 +++++++++++++++++++
 rpc/primitives/src/lib.rs | 27 +++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/README.md b/README.md
index c7fb75997..1a9c738f8 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,25 @@ It consists of the following components:
 
 Frontier is still work-in-progress. Below are some notes about the development.
 
+### Runtime
+
+A few notes on the EthereumRuntimeApi's runtime implementation requirements:
+
+- For supporting author rpc call, the FindAuthor trait must be implemented in an
+arbitrary struct. This implementation must call the authorities accessor in either
+Aura or Babe and convert the authority id response to H160 using
+pallet_evm::HashTruncateConvertAccountId::convert_account_id.
+
+The struct implementing FindAuthor is passed as the FindAuthor associated type's 
+value for pallet_ethereum.
+
+An Aura example for this is available in the template's runtime (EthereumFindAuthor).
+
+- For supporting chain_id rpc call, a u64 ChainId constant must be defined.
+
+- For supporting gas_price rpc call, FeeCalculator trait must be implemented in an
+arbitrary struct. An example FixedGasPrice is available in the template's runtime.
+
 ### Vendor folder
 
 The vendor folder contains dependencies that contains changes that has not yet
diff --git a/rpc/primitives/src/lib.rs b/rpc/primitives/src/lib.rs
index a9d020558..f9b60b95b 100644
--- a/rpc/primitives/src/lib.rs
+++ b/rpc/primitives/src/lib.rs
@@ -53,12 +53,19 @@ impl Default for TransactionStatus {
 sp_api::decl_runtime_apis! {
 	/// API necessary for Ethereum-compatibility layer.
 	pub trait EthereumRuntimeApi {
+		/// Returns runtime defined pallet_evm::ChainId.
 		fn chain_id() -> u64;
+		/// Returns pallet_evm::Accounts by address.
 		fn account_basic(address: H160) -> pallet_evm::Account;
+		/// Returns FixedGasPrice::min_gas_price
 		fn gas_price() -> U256;
+		/// For a given account address, returns pallet_evm::AccountCodes.
 		fn account_code_at(address: H160) -> Vec<u8>;
+		/// Returns the converted FindAuthor::find_author authority id.
 		fn author() -> H160;
+		/// For a given account address and index, returns pallet_evm::AccountStorages.
 		fn storage_at(address: H160, index: U256) -> H256;
+		/// Returns a pallet_evm::execute_call response.
 		fn call(
 			from: H160,
 			to: H160,
@@ -68,17 +75,32 @@ sp_api::decl_runtime_apis! {
 			gas_price: U256,
 			nonce: Option<U256>,
 		) -> Option<(Vec<u8>, U256)>;
+		/// For a given block number, returns an ethereum::Block and all its TransactionStatus.
 		fn block_by_number(number: u32) -> (Option<EthereumBlock>, Vec<Option<TransactionStatus>>);
+		/// For a given block number, returns the number of transactions.
 		fn block_transaction_count_by_number(number: u32) -> Option<U256>;
+		/// For a given block hash, returns an ethereum::Block.
 		fn block_by_hash(hash: H256) -> Option<EthereumBlock>;
+		/// For a given block hash, returns an ethereum::Block and all its TransactionStatus.
 		fn block_by_hash_with_statuses(hash: H256) -> (Option<EthereumBlock>, Vec<Option<TransactionStatus>>);
+		/// For a given block hash, returns the number of transactions in a given block hash.
 		fn block_transaction_count_by_hash(hash: H256) -> Option<U256>;
+		/// For a given transaction hash, returns data necessary to build an Transaction rpc type response.
+		/// - EthereumTransaction: transaction as stored in pallet-ethereum.
+		/// - EthereumBlock: block as stored in pallet-ethereum .
+		/// - TransactionStatus: transaction execution metadata.
+		/// - EthereumReceipt: transaction receipt.
 		fn transaction_by_hash(hash: H256) -> Option<(
 			EthereumTransaction,
 			EthereumBlock,
 			TransactionStatus,
 			Vec<EthereumReceipt>
 		)>;
+		/// For a given block hash and transaction index, returns data necessary to build an Transaction rpc
+		/// type response.
+		/// - EthereumTransaction: transaction as stored in pallet-ethereum.
+		/// - EthereumBlock: block as stored in pallet-ethereum .
+		/// - TransactionStatus: transaction execution metadata.
 		fn transaction_by_block_hash_and_index(
 			hash: H256,
 			index: u32
@@ -87,6 +109,11 @@ sp_api::decl_runtime_apis! {
 			EthereumBlock,
 			TransactionStatus
 		)>;
+		/// For a given block number and transaction index, returns data necessary to build an Transaction rpc
+		/// type response.
+		/// - EthereumTransaction: transaction as stored in pallet-ethereum.
+		/// - EthereumBlock: block as stored in pallet-ethereum .
+		/// - TransactionStatus: transaction execution metadata.
 		fn transaction_by_block_number_and_index(
 			number: u32,
 			index: u32