Feature: QuarkChain Multi-Native Token (MNT) Support for goshard EVM

[ping-ke]

QuarkChain Multi-Native Token (MNT) Support for goshard EVM

Summary

Port QuarkChain's multi-native token (MNT) account model and EVM extensions from goquarkchain into goshard, enabling state-root compatibility with the original pyquarkchain/goquarkchain chain. Add tooling to export and verify state trie correctness against a live pyquarkchain database.

Changes

common/

• token_codec.go — 36-base token name ↔ uint64 ID codec (TokenIDEncode / TokenIDDecode), byte-compatible with goquarkchain

core/types/

• token.go — TokenBalances type: list-format RLP encoding (0x00 prefix, ≤16 tokens); trie format (>16 tokens) unsupported with clear error
• state_account_qkc.go — StateAccount.EncodeRLP / DecodeRLP overrides implementing QKC's 6-field wire format [nonce, tokenBal, root, codeHash, fullShardKey, optional], byte-compatible with pyquarkchain
• DefaultTokenID = 35760 (TokenIDEncode("QKC"))

core/state/

• state_object_qkc.go — SetMntBalance, AddMntBalance, SubMntBalance, GetMntBalance on stateObject
• statedb_qkc.go — same set on StateDB; SubBalanceByTokenID / GetBalanceByTokenID dispatch by token ID
• journal.go — mntBalanceChange journal entry + revert
• mnt_test.go — unit tests for MNT balance state transitions

core/vm/

• contracts_qkc.go — 5 MNT precompiles at QKC system addresses:
  • 0x…514b430001 currentMntID — returns active MNT token ID
  • 0x…514b430002 transferMnt — transfer MNT between accounts
  • 0x…514b430003 deploySystemContract — deploy NonReserved / General native token contracts
  • 0x…514b430004 mintMNT — mint new MNT tokens (only callable by authorised system contract)
  • 0x…514b430005 balanceMNT — query MNT balance

core/evm.go / core/state_transition.go

• Wire MNT token ID through BlockContext and Message so precompiles and gas payment operate on the correct token

tools/

• tools/verify_trie_root/main.go — loads trie_dump.json exported from a pyquarkchain DB, feeds all trie nodes into goshard's trie package, and asserts the recomputed root matches — verified ✓ on mainnet shard-1
• tools/generatedata/dump_qkc_state_trie.py — exports the full state trie from a pyquarkchain RocksDB to JSON; handles latest-block lookup, backwards scan to find a persisted snapshot (~128-block checkpoint interval), outputs a node_store map consumable by verify_trie_root

Verification

Dump pyquarkchain trie data

python -m dump_qkc_state_trie --db-path ~/data/pyqkc/mainnet/shard-1.db --output  trie_dump.json  --limit 0
Opening DB: /root/data/pyqkc/mainnet/shard-1.db
Looking up block at height: latest
Block height:  23000709
Block hash:    b056ccff06dd44cc45a448f72fa082aeaa6c7dc7d4374dc3ca8bd48d5febb587
State root:    328e64f51560af15fe25fa4a87249fea219094769adab3fe553c0777873f05a4
Traversing trie (limit_accounts=0)...
  Nodes found:    34578
  Accounts found: 26018
  Node types:     {'branch': 8345, 'leaf': 26018, 'extension': 215}
Writing trie_dump.json...
Done. Output: trie_dump.json (47.8 MB)

Verify goshard mnt by trie root

go run ./tools/verify_state --input ./tools/dump_state/trie_dump.json
Loading ./tools/dump_state/trie_dump.json ...
State root from dump: 328e64f51560af15fe25fa4a87249fea219094769adab3fe553c0777873f05a4
Node store entries:   34578
Accounts in dump:     26018

Recomputing trie root via goshard trie package...
Expected root: 328e64f51560af15fe25fa4a87249fea219094769adab3fe553c0777873f05a4
Computed root: 0x328e64f51560af15fe25fa4a87249fea219094769adab3fe553c0777873f05a4

Out of scope / follow-up

• EVM replay test (pre-state + transactions → assert post-state root); blocked on QKCChainConfig (Constantinople-level gas rules matching goquarkchain's go-ethereum v1.8.20)
• Cross-shard transaction handling
• TokenBalances trie format (accounts with >16 MNT tokens)