From 956ebb2b022f4ab4fc789187bc736010758a2539 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)

---
 core/evm.go             |  1 +
 core/vm/instructions.go |  1 +
 docs/README.md          |  5 +++--
 docs/solidity.md        | 23 +++++++++++++++++++++++
 4 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 docs/solidity.md

diff --git a/core/evm.go b/core/evm.go
index 56e91c6e1f..e8493f8279 100644
--- a/core/evm.go
+++ b/core/evm.go
@@ -54,6 +54,7 @@ func NewEVMBlockContext(header *types.Header, chain ChainContext, author *common
 		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 d863c05ec0..9d9a6e9ea6 100644
--- a/core/vm/instructions.go
+++ b/core/vm/instructions.go
@@ -480,6 +480,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
index a1184823db..70b21760b5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,6 @@
 # Documents
 
-- [JSONRPC API](./xdc/jsonrpc.md)
-- [Validator Contract](./xdc/validator.md)
+- [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.