From 838751e3789b34d35a21b0bbaf910a9e98f00692 Mon Sep 17 00:00:00 2001
From: Daniel Liu <139250065@qq.com>
Date: Fri, 14 Nov 2025 18:55:42 +0800
Subject: [PATCH] core, docs: add solidity document, close XFN-68 (#1670)

---
 commits                 | 18 ++++++++++++++++++
 core/evm.go             |  1 +
 core/vm/instructions.go |  1 +
 docs/README.md          |  6 ++++++
 docs/solidity.md        | 23 +++++++++++++++++++++++
 5 files changed, 49 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/solidity.md

diff --git a/commits b/commits
index d886a75ba1..e202ef08cf 100644
--- a/commits
+++ b/commits
@@ -1,5 +1,7 @@
 I found 50 commits containing the keyword "XFN" in the last 200 commits. Here they are with dates: November 2025:
 
+
+
 845137849 - Wanwiset Peerapatanapokin - consensus: change os.Exit to return error (#1653)
 b49f6cb0f - Wanwiset Peerapatanapokin - consensus: verify header hash is same as input hash in getEpochSwitchInfo (#1627)
 e0c987f45 - Wanwiset Peerapatanapokin - impose size limit for DecodeBytesExtraFields (#1637)
@@ -10,6 +12,22 @@ c95d25805 - Wanwiset Peerapatanapokin - separate fullVerifies array into v1fullV
 25a70e877 - Wanwiset Peerapatanapokin - consensus: skip gas limit verification for genesis block (#1646)
 da92ad7cc - Wanwiset Peerapatanapokin - update package version: (#1612)
 
+2025-11-18 - 627d77ae2 - eth/hook: fix parameter mame mismatch in `HookPenalties()`, close XFN-141 (#1741)
+2025-11-18 - f8553d587 - core, miner: fix inconsistent tx blacklist enforcement, close XFN-98 (#1674)
+2025-11-16 - 73061af2c - core/types: fix immutability guarantees in Block #27844, close XFN-82 (#1727)
+2025-11-15 - 07e2609c2 - common: improve variable names for `ExtractAddressFromBytes()`, close XFN-27 (#1726)
+2025-11-15 - 650047c81 - consensus/XDPoS, params: fix some comments, close XFN-125 (#1733)
+2025-11-15 - f24e68b01 - consensus/XDPoS, eth: fix potential rpc.BlockNumber overflow, close XFN-69 (#1735)
+2025-11-15 - 60868c904 - engines/engine_v2: refactor verifyQC by errgroup, close XFN-09 (#1740)
+2025-11-15 - 8cbbc1e83 - consensus, params: remove `SkipV2Validation`, close XFN-151 (#1730)
+2025-11-15 - 7a3ac998a - eth: quick canceling block inserting when debug_setHead is invoked #32067, close XFN-142 (#1728)
+2025-11-14 - eef5242fa - all: pre-allocate memory for slices and maps, close XFN-148 (#1714)
+2025-11-14 - 782a7ff5c - all: fix typos, close XFN-23 (#1725)
+2025-11-14 - bd3d30919 - XDPoS/utils: get pool size by key, close XFN-21 (#1666)
+2025-11-14 - d5a03ab9e - core, eth: fix overuse Of `log.Crit`, close XFN-102 (#1648)
+2025-11-14 - 2c40021f7 - core/state, internal/ethapi: GetAccountInfo handle error properly, close XFN-79 (#1663)
+2025-11-14 - 39b8184f5 - XDPoS/utils: must use `NewPool()` to create Pool, close XFN-13 (#1667)
+2025-11-14 - 956ebb2b0 - core, docs: add solidity document, close XFN-68 (#1670)
 
 2025-11-12 - 4bb925258 - params: fix type V2 not equal bug, close XFN-45 (#1737)
 2025-11-10 - 366c99ece - consensus: use signer pubkey to check for unique signatures, close XFN-03 (#1643)
diff --git a/core/evm.go b/core/evm.go
index 9847a8d790..7b188c8b91 100644
--- a/core/evm.go
+++ b/core/evm.go
@@ -43,6 +43,7 @@ func NewEVMBlockContext(header *types.Header, chain consensus.ChainContext, auth
 		baseFee = new(big.Int).Set(header.BaseFee)
 	}
 	// since xdpos chain do not use difficulty and mixdigest, we use hash of the block number as random
+	// NOTE: random is predictable, do not use it in real business
 	random = crypto.Keccak256Hash(header.Number.Bytes())
 	return vm.BlockContext{
 		CanTransfer: CanTransfer,
diff --git a/core/vm/instructions.go b/core/vm/instructions.go
index 79f1913078..de119d74a9 100644
--- a/core/vm/instructions.go
+++ b/core/vm/instructions.go
@@ -482,6 +482,7 @@ func opDifficulty(pc *uint64, interpreter *EVMInterpreter, scope *ScopeContext)
 	return nil, nil
 }
 
+// NOTE: Random is predictable in current implemention, do not use it in real business
 func opRandom(pc *uint64, interpreter *EVMInterpreter, scope *ScopeContext) ([]byte, error) {
 	var v *uint256.Int
 	if interpreter.evm.Context.Random != nil {
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..70b21760b5
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,6 @@
+# Documents
+
+- [JSONRPC API](xdc/jsonrpc.md)
+- [Validator Contract](xdc/validator.md)
+- [Development environment](develop.md)
+- [Solidity](solidity.md)
diff --git a/docs/solidity.md b/docs/solidity.md
new file mode 100644
index 0000000000..7bd5c769b9
--- /dev/null
+++ b/docs/solidity.md
@@ -0,0 +1,23 @@
+# Solidity
+
+## Compatibility
+
+- mainnet: v0.8.23
+- testnet: v0.8.28
+- devnet: v0.8.28
+
+## Special variables
+
+### block.prevrandao
+
+The value of `block.prevrandao` is `keccak256(block.number)` in our current implemention. It is predictable and unsafe.
+
+**NOTICE: do not use it in real business.**
+
+### block.basefee
+
+The value of `block.basefee` is always 12.5 GWei in our EIP-1559 implemention.
+
+### block.blobbasefee
+
+The value of `block.blobbasefee` is always 0 in our EIP-7516 implemention.