MNT Part 1: feat(types): add QuarkChain MNT account and token types

[ping-ke]

Summary

• Add MNT (Multi-Native Token) support to core/types, including a QKC 6-element RLP-encoded StateAccount and a TokenBalances type
• Remove the codegen file gen_account_rlp.go and replace it with hand-written EncodeRLP/DecodeRLP to support the QKC custom 6-field RLP format
• Keep this PR limited to the account types and codec layer; runtime state integration and fixture updates are handled by follow-up PRs

Background

The standard Ethereum StateAccount uses 4-element RLP (Nonce, Balance, Root, CodeHash). The QuarkChain protocol extends this with two additional fields:

• FullShardKey uint32: the shard key of the account
• MntBalances TokenBalances: a map of non-default native token balances held by the account

This change produces a different state root from standard go-ethereum, requiring the genesis hash constants to be updated accordingly.

Changed Files

File	Description
core/types/gen_account_rlp.go	Deleted and replaced by hand-written RLP encoding
core/types/state_account.go	Add FullShardKey and MntBalances fields and extend SlimAccount
core/types/state_account_qkc.go	QKC 6-element RLP encode/decode implementation
core/types/state_account_qkc_test.go	Roundtrip tests and pyquarkchain compatibility tests

PRs and Scope

PR / Branch	Scope
This PR (feature/mnt-core-types)	Add the QKC-aware account representation, TokenBalances, 6-element RLP codec, and extended SlimAccount in core/types. Snap sync wire-format support remains out of scope.
feature/mnt-state	Integrate MNT accounts into core/state, including state objects, journaling, revert/history handling, StateDB, and snapshot reader support. flatReader.Account preserves FullShardKey and decodes MntBal into MntBalances.
feature/mnt-state-test-fixtures	Update state, snapshot, pathdb, and related test fixtures and goldens for the QKC account encoding and resulting state roots.

After review, these three stacked changes will be combined into a single PR and merged.

Key Design Decisions

DefaultTokenID = 35760: Equal to TokenIDEncode("QKC"), consistent with pyquarkchain. The QKC token balance is stored in the standard Balance field, not in the MntBalances map, to preserve EIP-20 compatibility.

Test Plan

• go test ./core/types — all pass, including pyquarkchain compatibility vector tests
• go build ./... — build successful

Additional state integration and fixture/golden coverage is provided by the follow-up branches listed above.

[qzhodl]

General note: the three inline issues above were all found in a first-pass Codex 5.5 Extra High review with no additional prompt engineering beyond asking it to review this PR. Before requesting review next time, please run a self-review pass with Codex 5.5 Extra High (or an equivalent high-reasoning review mode) and address the obvious state/snapshot/generation issues it finds first.

[ping-ke]

Account RLP Compatibility with pyquarkchain

The following tables compare balance-related bytes only. The values were obtained by executing the current Go account workflow and cross-checking the resulting token-balance payloads with pyquarkchain's TokenBalances.serialize().

• TokenBal: the payload stored in the main six-field account RLP.
• SlimAccountRLP: the internal snapshot representation, shown as Balance and MntBal.
• pyquarkchain: the payload produced by TokenBalances.serialize().
• empty: empty bytes, encoded as 0x80 by the enclosing RLP field.
• 00c0: a serialized token-balance list containing no non-zero token pairs.

The examples use:

• QKC token ID: 35760 (0x8bb0)
• MNT token ID: 100 (0x64)
• Non-zero balance: 1000 (0x03e8)

New Account

A new account can be initialized with different QKC and MNT balances.

Initial values	In-memory state	EncodeRLP TokenBal	SlimAccountRLP	pyquarkchain TokenBal	Aligned
QKC=0, MNT absent	Balance=0, MntBalances=nil	empty	Balance=0, MntBal=nil	empty	Yes
QKC=0, MNT=1000	Balance=0, MntBalances={100:1000}	00c5c4648203e8	Balance=0, MntBal=00c5c4648203e8	00c5c4648203e8	Yes
QKC=1000, MNT absent	Balance=1000, MntBalances=nil	00c7c6828bb08203e8	Balance=1000, MntBal=nil	00c7c6828bb08203e8	Yes
QKC=1000, MNT=1000	Balance=1000, MntBalances={100:1000}	00ccc4648203e8c6828bb08203e8	Balance=1000, MntBal=00c5c4648203e8	00ccc4648203e8c6828bb08203e8	Yes

Decode -> Update Nonce -> Encode

Updating the nonce does not change Balance or MntBalances.

Account values before decode	Input TokenBal	State after DecodeRLP	TokenBal after EncodeRLP	SlimAccountRLP	pyquarkchain TokenBal	Aligned
QKC=0, MNT=1000	00c5c4648203e8	Balance=0, MntBalances={100:1000}	00c5c4648203e8	Balance=0, MntBal=00c5c4648203e8	00c5c4648203e8	Yes
QKC=1000, MNT absent	00c7c6828bb08203e8	Balance=1000, MntBalances=empty map	00c7c6828bb08203e8	Balance=1000, MntBal=00c0	00c7c6828bb08203e8	Yes
QKC=0, MNT absent	empty	Balance=0, MntBalances=nil	empty	Balance=0, MntBal=nil	empty	Yes

Decode -> Update Balance -> Encode

When the QKC balance changes and MntBalances == nil, the update logic changes MntBalances to a non-nil empty map to preserve QKC token-entry presence.

Balance update	Input TokenBal	State after DecodeRLP	State after update	TokenBal after EncodeRLP	SlimAccountRLP	pyquarkchain TokenBal	Aligned
QKC 1000 -> 0, MNT absent	00c7c6828bb08203e8	Balance=1000, MntBalances=empty map	Balance=0, MntBalances=empty map	00c0	Balance=0, MntBal=00c0	00c0	Yes
QKC=0, MNT 1000 -> 0	00c5c4648203e8	Balance=0, MntBalances={100:1000}	Balance=0, MntBalances={100:0} (blank)	00c0	Balance=0, MntBal=00c0	00c0	Yes
QKC 0 -> 1000, MNT absent	empty	Balance=0, MntBalances=nil	Balance=1000, MntBalances=empty map	00c7c6828bb08203e8	Balance=1000, MntBal=00c0	00c7c6828bb08203e8	Yes
QKC=0, MNT absent -> 1000	empty	Balance=0, MntBalances=nil	Balance=0, MntBalances={100:1000}	00c5c4648203e8	Balance=0, MntBal=00c5c4648203e8	00c5c4648203e8	Yes

Conclusion

DecodeRLP splits pyquarkchain's unified TokenBal into Balance for QKC and MntBalances for non-QKC tokens. EncodeRLP merges them back into the same canonical TokenBal bytes.

SlimAccountRLP stores QKC in Balance and MNT in MntBal. A non-nil empty MntBalances is encoded as MntBal=00c0 so it survives the snapshot round trip.

The final EncodeRLP output matches the payload produced by pyquarkchain for all balance states above.

[syntrust]

Checked every form in the tables against 2d589f694 and they hold up: empty, 00c7c6828bb08203e8, 00c6c5648203e8 and the MNT+QKC form all decode and re-encode to identical bytes. No disagreement on any row you listed.

There is one input form the tables don't cover, and it's the one that breaks: TokenBal = 00c0 as a decode input.

00c0 appears in the third table only as an output (the QKC 1000 -> 0 and MNT 1000 -> 0 rows). Those bytes get committed to the trie, so on the next block that touches the account they are what DecodeRLP is handed. The tables implicitly follow one in-memory state through decode → update → encode; the missing step is the state going to disk and coming back.

Filling that row in:

Input TokenBal	State after DecodeRLP	TokenBal after EncodeRLP	SlimAccountRLP	pyquarkchain TokenBal	Aligned
00c0	Balance=0, MntBalances=nil	empty	Balance=0, MntBal=nil	empty	Yes

For the state-transition path that Yes is correct and should stay: pyquarkchain rebuilds _balances from the pair list, which never carries zeros, so a reloaded account starts with an empty map and re-commits as b"" too. Reproducing 00c0 on read-back would diverge in the other direction.

The problem is the SlimAccountRLP column, which is not a state transition. Three paths use it as a pure format conversion and need full -> slim -> full to be the identity:

• triedb/pathdb/generate.go:749 — generateRange(..., types.FullAccountRLP); proveRange rebuilds a StackTrie and compares gotRoot != root (same file, 347-353). A 00c0 account re-expands as 0x80, so its range never proves and is regenerated forever.
• eth/protocols/snap/protocol.go:116 — AccountRangePacket.Unpack expands peer slim bodies before the range proof is checked against the state root.
• core/state/stateupdate.go:220,263 stores slim accountOrigin blobs that triedb/pathdb/execute.go:96 replays to reverse state history.

Measured on 2d589f694:

leaf in : f84c01 8200c0 a056e8… 8400000001 80
slim    : c50180808001                          <- MntBal field is gone entirely
leaf out: f84a01 80     a056e8… 8400000001 80

So A non-nil empty MntBalances is encoded as MntBal=00c0 so it survives the snapshot round trip only holds for accounts decoded from a leaf that carried a QKC pair or MNT entries. An account decoded from a 00c0 leaf never reaches that branch, because DecodeRLP leaves MntBalances nil — which also makes the slim.MntBal = []byte{0x00, 0xc0} marker unreachable from any trie-leaf-decode path.

Suggested split: keep the codec lossless (StateAccount faithfully represents a leaf) and move the "reload clears the map" semantics to core/state, which drops the marker when loading an account into a live state object and sets it on every balance write, including writes to zero.

Two TokenBal values in the tables look off by one byte in the MNT pair's inner list header — measured against TokenBalances.SerializeToBytes:

MNT{100:1000}          = 00c5c4648203e8                 (table: 00c6c5648203e8)
MNT+QKC, both 1000     = 00ccc4648203e8c6828bb08203e8   (table: 00ccc5648203e8c6828bb08203e8)
QKC{35760:1000}        = 00c7c6828bb08203e8             (matches)

The pair is c4 + 64 + 8203e8, so the MNT-only payload is 00c5c4648203e8. The QKC-only value is correct and matches the existing pyqkcVecNonce1QKC1000 golden.

[qzhodl]

@ping-ke Small correction: the MNT pair hex in the table looks off by one byte. For tokenID=100, balance=1000, the pair is c4 64 82 03 e8, so:

• QKC=0, MNT=1000: 00c5c4648203e8, not 00c6c5648203e8
• QKC=1000, MNT=1000: 00ccc4648203e8c6828bb08203e8, not 00ccc5648203e8c6828bb08203e8

The QKC-only value looks correct.

[qzhodl]

pyquarkchain has two distinct QKC=0 states: an absent token table ({} -> empty TokenBal) and an explicit zero QKC entry ({QKC:0} -> 00c0). So not every zero QKC balance should encode as 00c0; only the explicit zero-entry case should.

After splitting pyquarkchain's unified token table into Balance plus non-QKC MntBalances, goshard has no explicit place to store that distinction. As a result, MntBalances != nil is now implicitly used as the token-presence marker.

That feels fragile: if any caller leaves MntBalances nil while Balance == 0 is meant to represent {QKC:0}, mergeQKCTokenBalances emits empty bytes instead of 00c0. Please make this marker explicit, or document/test this invariant across state updates, snapshot, and pathdb.

[ping-ke]

pyquarkchain has two distinct QKC=0 states: an absent token table ({} -> empty TokenBal) and an explicit zero QKC entry ({QKC:0} -> 00c0). So not every zero QKC balance should encode as 00c0; only the explicit zero-entry case should.

After splitting pyquarkchain's unified token table into Balance plus non-QKC MntBalances, goshard has no explicit place to store that distinction. As a result, MntBalances != nil is now implicitly used as the token-presence marker.

That feels fragile: if any caller leaves MntBalances nil while Balance == 0 is meant to represent {QKC:0}, mergeQKCTokenBalances emits empty bytes instead of 00c0. Please make this marker explicit, or document/test this invariant across state updates, snapshot, and pathdb.

Resolved across the stacked branches.

feature/mnt-core-types (ac492153d) adds an explicit balanceUpdateCount marker to StateAccount. A zero QKC balance is encoded as 00c0 only when this marker is set; a non-nil empty MntBalances is no longer used as the QKC presence marker.

feature/mnt-state (3357d5bdc) updates the marker on actual QKC balance changes and removes the corresponding update on journal revert. Slim account round trips restore the marker explicitly for snapshot/pathdb use.

Consensus DecodeRLP(00c0) still resets the marker and re-encodes as an empty TokenBal, matching pyquarkchain.

[qzhodl]

One remaining snapshot-scope concern: if snap sync and pathdb are intentionally out of scope for this PR, that sounds fine, but snapshot database reads still seem in scope.

flatReader.Account currently rebuilds StateAccount manually from SlimAccount and copies only Nonce, Balance, Root, and CodeHash; it does not restore FullShardKey or decode MntBal back into MntBalances. Since MPTDatabase puts the flat reader before the trie reader, a snapshot cache hit can return a StateAccount missing QKC-specific fields, and a later re-commit can write corrupted account bytes back to the trie.

If this fix is intentionally deferred to the next PR, could you please make that explicit in the PR description? That would make the supported snapshot scope of this PR clear.

[syntrust]

Even if snap sync and pathdb are out of scope, the snapshot database still cannot round-trip a 00c0 leaf: SlimAccountRLP stores the marker, but FullAccountRLP drops it during proof verification and trie regeneration. Please preserve the marker for snapshot leaf reconstruction while keeping normal snapshot reads normalized, or explicitly declare these snapshot paths unsupported as well.

[ping-ke]

One remaining snapshot-scope concern: if snap sync and pathdb are intentionally out of scope for this PR, that sounds fine, but snapshot database reads still seem in scope.

flatReader.Account currently rebuilds StateAccount manually from SlimAccount and copies only Nonce, Balance, Root, and CodeHash; it does not restore FullShardKey or decode MntBal back into MntBalances. Since MPTDatabase puts the flat reader before the trie reader, a snapshot cache hit can return a StateAccount missing QKC-specific fields, and a later re-commit can write corrupted account bytes back to the trie.

If this fix is intentionally deferred to the next PR, could you please make that explicit in the PR description? That would make the supported snapshot scope of this PR clear.

The flat-reader integration is intentionally deferred to the next stacked PR (feature/mnt-state), which updates flatReader.Account to restore FullShardKey and decode MntBal into MntBalances.

This PR only introduces the QKC account codec and the extended slim-account representation. It does not by itself claim support for runtime snapshot database reads, pathdb, or snap sync.

I've added a "PRs and Scope" section to the PR description to clarify the scope of this PR and the responsibilities of the following stacked PRs.

[qzhodl]

As we discussed before, I still think this approach is more complicated and more error-prone than simply using a balance dictionary that includes both MNT and native balances.