Add KIP-999 priority fee mechanism

KIPs/kip-999.md

@@ -0,0 +1,134 @@
+---
+kip: 999
+title: Priority Fee Mechanism
+author: Ollie (@blukat29), Sawyer (@2dvorak), Aidan (@aidan-kwon)
+status: Draft
+type: Standard Track
+category : Core
+created: 2024-03-20
+---
+
+# Simple summary
+
+Priority fee mechanism for transaction type 2 (EthereumDynamicFee) in terms of transaction ordering.
+
+# Abstract
+
+Activate the priority fee mechanism as defined in the EIP-1559. The maxPriorityFeePerGas field of transaction type 2 is no longer a placeholder, now it represents the priority fee the sender is willing to pay. The transactions are ordered by descending effective gas price, which is usually in the descending priority fee order. Under congested network, high priority transactions can be included to block by declaring high priority fee.
+
+# Motivation
+
+TBU
+
+# Specification
+
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC-2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+## Block processing
+
+### Effective gas price and effective priority fee per gas
+
+```py
+def EffectiveGasPrice(block: Block, tx: Transaction):
+    if tx.type == 2:
+        maxPriorityFeePerGas = tx.maxPriorityFeePerGas
+        maxFeePerGas = tx.maxFeePerGas
+    else:
+        maxPriorityFeePerGas = tx.gasPrice
+        maxFeePerGas = tx.gasPrice
+
+    return min(block.baseFeePerGas + maxPriorityFeePerGas, maxFeePerGas)
+
+def EffectivePriorityFeePerGas(block: Block, tx: Transaction):
+    effectiveGasPrice = EffectiveGasPrice(block, tx)
+    return effectiveGasPrice - block.baseFeePerGas
+```
+
+### Transaction ordering
+
+Transactions are ordered by (1) descending effective gas price and (2) ascending arrival timestamp.
+
+TBU
+
+## JSON-RPC API
+
+### `eth_gasPrice` and `klay_gasPrice`
+
+Returns suggested value for `gasPrice` or `maxFeePerGas` fields of a transaction.
+
+- Parameters: none
+- Result: Recommended gas price in peb. The result depends on the client implementation.
+- Example
+  ```sh
+  curl $RPC_URL -X POST -H 'Content-Type: application/json' --data '
+    {"jsonrpc":"2.0","id":1,"method":"eth_gasPrice","params":[]}'
+
+  {"jsonrpc":"2.0","id":1,"result":"0xba43b7400"}
+  ```
+
+### `eth_maxPriorityFeePerGas` and `klay_maxPriorityFeePerGas`
+
+Returns suggested value for `gasPrice` or `maxFeePerGas` fields of a transaction.
+
+- Parameters: none
+- Result: Recommended priority fee per gas in peb. The result depends on the client implementation.
+- Example
+  ```sh
+  curl $RPC_URL -X POST -H 'Content-Type: application/json' --data '
+    {"jsonrpc":"2.0","id":1,"method":"eth_maxPriorityFeePerGas","params":[]}'
+
+  {"jsonrpc":"2.0","id":1,"result":"0x3b9aca00"}
+  ```
+
+### `eth_feeHistory` and `klay_feeHistory`
+
+Returns historical gas information for a range of blocks.
+
+- Parameters
+  - `blockCount` - Number of blocks in the requested range.
+  - `newestBlock` - Highest block of the requested range. Can be a number or "latest".
+  - `rewardPercentiles` - (optional) A monotonically increasing list of percentile (between 0 and 100) values. For each block in the requested range, the transactions will be sorted in ascending order by effective tip per gas and sampled at the specified percentiles.
+- Result
+  - `oldestBlock` - Lowest number block of returned range.
+  - `baseFeePerGas` - An array of block base fee per gas. This includes the next block after the newest of the returned range, because this value can be derived from the newest block. Zeroes are returned for pre-Magma blocks.
+  - `gasUsedRatio` - An array of block gas used ratios. Measures the network congestion level. These are calculated as the ratio of block gas used and [KIP-71 MAX_BLOCK_GAS_USED_FOR_BASE_FEE](https://github.com/klaytn/kips/blob/main/KIPs/kip-71.md). If the ratio is above 1, then 1.0 is returned.
+  - `reward` - A 2D array of effective priority fees per gas. `reward[n][i]` is the `rewardPercentiles[i]`-th percentile effective priority fees per gas among the transactions in the block `oldestBlock + n`.
+- Example
+  ```sh
+  curl $RPC_URL -X POST -H 'Content-Type: application/json' --data '
+    {"jsonrpc":"2.0","id":1,"method":"eth_feeHistory","params":[
+      4,
+      "latest",
+      [50.0, 90.0, 95.0]
+    ]}'
+
+  {
+    "id": "1",
+    "jsonrpc": "2.0",
+    "result": {
+      "oldestBlock": "0x8e0a025",
+      "baseFeePerGas": ["0x5d21dba00", "0x5d21dba00", "0x5d21dba00", "0x61c9f3680"],
+      "gasUsedRatio": [0.023, 0.31, 1.0, 0.88],
+      "reward": [
+        ["0x3b9aca00", "0x3b9aca00", "0x9502f900"],
+        ["0x3b9aca00", "0x3b9aca00", "0x9502f900"],
+        ["0x3b9aca00", "0x9502f900", "0x2e90edd00"],
+        ["0x3b9aca00", "0x9502f900", "0x30e4f9b40"],
+      ]
+    }
+  }
+  ```
+
+# Rationale
+
+TBU
+
+# Backward compatibility
+
+TBU
+
+# References
+
+- https://github.com/klaytn/kips/blob/main/KIPs/kip-71.md
+- https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md
+- https://github.com/ethereum/execution-apis/blob/main/src/eth/fee_market.yaml