core, docs: add solidity document, close XFN-68 (#1670)

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,

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 {

docs/README.md

@@ -1,5 +1,6 @@
 # Documents
 
-- [JSONRPC API](./xdc/jsonrpc.md)
+- [JSONRPC API](xdc/jsonrpc.md)
-- [Validator Contract](./xdc/validator.md)
+- [Validator Contract](xdc/validator.md)
 - [Development environment](develop.md)
+- [Solidity](solidity.md)

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.