fix comment

qkc/cluster/wire/messages.go

@@ -43,18 +43,18 @@
 // Primitive Type Mapping (Python → Go)
 // -----------------------------------------------------------------------------
 //
-//	uint8        → uint8        (1 byte)
+//	uint8        → uint8              (1 byte)
-//	uint16       → uint16       (2 bytes BE)
+//	uint16       → uint16             (2 bytes BE)
-//	uint32       → uint32       (4 bytes BE)
+//	uint32       → uint32             (4 bytes BE)
-//	uint64       → uint64       (8 bytes BE)
+//	uint64       → uint64             (8 bytes BE)
-//	uint128      → [16]byte     (16 bytes BE)
+//	uint128      → [16]byte           (16 bytes BE)
-//	uint256      → *big.Int     (1-byte length + big-endian bytes)
+//	uint256      → serialize.Uint256   (32 bytes big-endian)
-//	biguint      → *big.Int     (same as uint256)
+//	biguint      → serialize.BigUint   (1-byte length + big-endian bytes)
-//	hash256      → [32]byte     (32 bytes)
+//	hash256      → [32]byte           (32 bytes)
-//	Branch       → uint32       (4 bytes)
+//	Branch       → uint32             (4 bytes)
-//	Address      → [20]byte     (20 bytes)
+//	Address      → account.Address     (24 bytes: 20B recipient + 4B full_shard_key)
-//	signature65  → [65]byte     (65 bytes)
+//	signature65  → [65]byte           (65 bytes)
-//	boolean      → bool         (0x00 / 0x01)
+//	boolean      → bool               (0x00 / 0x01)
 //
 // -----------------------------------------------------------------------------
 // Layout Organization
@@ -87,17 +87,15 @@
 package wire
 
 import (
-	"math/big"
+	"github.com/ethereum/go-ethereum/qkc/account"
+	"github.com/ethereum/go-ethereum/qkc/serialize"
 )
 
 // =============================================================================
-// Wire-level address / branch / hash constants
+// Wire-level constants
 // =============================================================================
 //
-// These match quarkchain/core.py:Constant and Python Branch/Address types.
+// These match quarkchain/core.py:Constant and Python built-in type sizes.
-
-// AddressLength is the byte length of an Address (20 bytes).
-const AddressLength = 20
 
 // HashLength is the byte length of a hash256.
 const HashLength = 32
@@ -261,9 +259,9 @@ type AddRootBlockResponse struct {
 type EcoInfo struct {
 	Branch                           uint32
 	Height                           uint64
-	CoinbaseAmount                   *big.Int // uint256
+	CoinbaseAmount                   serialize.Uint256
-	Difficulty                       *big.Int // biguint
+	Difficulty                       serialize.BigUint
-	UnconfirmedHeadersCoinbaseAmount *big.Int // uint256
+	UnconfirmedHeadersCoinbaseAmount serialize.Uint256
 }
 
 // GetEcoInfoListRequest (ClusterOp.GET_ECO_INFO_LIST_REQUEST, 0x87) — empty body.
@@ -284,7 +282,7 @@ type GetEcoInfoListResponse struct {
 //	]
 type GetNextBlockToMineRequest struct {
 	Branch             uint32
-	Address            [AddressLength]byte
+	Address            account.Address
 	ArtificialTxConfig ArtificialTxConfig
 }
 
@@ -343,7 +341,7 @@ type GetUnconfirmedHeadersResponse struct {
 //	]
 type AccountBranchData struct {
 	Branch           uint32
-	TransactionCount *big.Int // uint256
+	TransactionCount serialize.Uint256
 	// TODO: Replace with *TokenBalanceMap once core.TokenBalanceMap is ported.
 	TokenBalances      *RawBytes
 	IsContract         bool
@@ -353,7 +351,7 @@ type AccountBranchData struct {
 
 // GetAccountDataRequest (ClusterOp.GET_ACCOUNT_DATA_REQUEST, 0x8D).
 type GetAccountDataRequest struct {
-	Address     [AddressLength]byte
+	Address     account.Address
 	BlockHeight *uint64 `ser:"nil"` // Optional uint64
 }
 
@@ -391,8 +389,8 @@ type AddTransactionResponse struct {
 type ShardStats struct {
 	Branch             uint32
 	Height             uint64
-	Difficulty         *big.Int // biguint
+	Difficulty         serialize.BigUint
-	CoinbaseAddress    [AddressLength]byte
+	CoinbaseAddress    account.Address
 	Timestamp          uint64
 	TxCount60s         uint32
 	PendingTxCount     uint32
@@ -467,7 +465,7 @@ type SyncMinorBlockListResponse struct {
 
 // MinorBlockExtraInfo — used by GetMinorBlockResponse.
 type MinorBlockExtraInfo struct {
-	EffectiveDifficulty *big.Int // biguint
+	EffectiveDifficulty serialize.BigUint
 	PoswMineableBlocks  uint16
 	PoswMinedBlocks     uint16
 }
@@ -506,7 +504,7 @@ type GetTransactionResponse struct {
 type ExecuteTransactionRequest struct {
 	// TODO: Replace with *TypedTransaction once core.TypedTransaction is ported.
 	Tx          *RawBytes
-	FromAddress [AddressLength]byte
+	FromAddress account.Address
 	BlockHeight *uint64 `ser:"nil"`
 }
 
@@ -537,9 +535,9 @@ type GetTransactionReceiptResponse struct {
 type TransactionDetail struct {
 	TxHash          [HashLength]byte
 	Nonce           uint64
-	FromAddress     [AddressLength]byte
+	FromAddress     account.Address
-	ToAddress       *[AddressLength]byte `ser:"nil"` // Optional Address
+	ToAddress       *account.Address `ser:"nil"` // Optional Address
-	Value           *big.Int             // uint256
+	Value           serialize.Uint256
 	BlockHeight     uint64
 	Timestamp       uint64
 	Success         bool
@@ -550,7 +548,7 @@ type TransactionDetail struct {
 
 // GetTransactionListByAddressRequest (ClusterOp.GET_TRANSACTION_LIST_BY_ADDRESS_REQUEST, 0xAB).
 type GetTransactionListByAddressRequest struct {
-	Address         [AddressLength]byte
+	Address         account.Address
 	TransferTokenID *uint64 `ser:"nil"`
 	Start           []byte  `bytesizeofslicelen:"4"`
 	Limit           uint32
@@ -588,7 +586,7 @@ type GetAllTransactionsResponse struct {
 //	]
 type GetLogRequest struct {
 	Branch     uint32
-	Addresses  [][AddressLength]byte    `bytesizeofslicelen:"4"`
+	Addresses  []account.Address        `bytesizeofslicelen:"4"`
 	Topics     []PrependedSizeHashList4 `bytesizeofslicelen:"4"`
 	StartBlock uint64
 	EndBlock   uint64
@@ -604,7 +602,7 @@ type GetLogResponse struct {
 type EstimateGasRequest struct {
 	// TODO: Replace with *TypedTransaction once core.TypedTransaction is ported.
 	Tx          *RawBytes
-	FromAddress [AddressLength]byte
+	FromAddress account.Address
 }
 
 // EstimateGasResponse (ClusterOp.ESTIMATE_GAS_RESPONSE, 0xB0).
@@ -615,9 +613,9 @@ type EstimateGasResponse struct {
 
 // GetStorageRequest (ClusterOp.GET_STORAGE_REQUEST, 0xB1).
 type GetStorageRequest struct {
-	Address     [AddressLength]byte
+	Address     account.Address
-	Key         *big.Int // uint256
+	Key         serialize.Uint256
-	BlockHeight *uint64  `ser:"nil"`
+	BlockHeight *uint64 `ser:"nil"`
 }
 
 // GetStorageResponse (ClusterOp.GET_STORAGE_RESPONSE, 0xB2).
@@ -628,7 +626,7 @@ type GetStorageResponse struct {
 
 // GetCodeRequest (ClusterOp.GET_CODE_REQUEST, 0xB3).
 type GetCodeRequest struct {
-	Address     [AddressLength]byte
+	Address     account.Address
 	BlockHeight *uint64 `ser:"nil"`
 }
 
@@ -653,7 +651,7 @@ type GasPriceResponse struct {
 // GetWorkRequest (ClusterOp.GET_WORK_REQUEST, 0xB7).
 type GetWorkRequest struct {
 	Branch       uint32
-	CoinbaseAddr *[AddressLength]byte `ser:"nil"` // Optional Address
+	CoinbaseAddr *account.Address `ser:"nil"` // Optional Address
 }
 
 // GetWorkResponse (ClusterOp.GET_WORK_RESPONSE, 0xB8).
@@ -661,7 +659,7 @@ type GetWorkResponse struct {
 	ErrorCode  uint32
 	HeaderHash [HashLength]byte
 	Height     uint64
-	Difficulty *big.Int // biguint
+	Difficulty serialize.BigUint
 }
 
 // SubmitWorkRequest (ClusterOp.SUBMIT_WORK_REQUEST, 0xB9).
@@ -685,15 +683,15 @@ type SubmitWorkResponse struct {
 
 // GetRootChainStakesRequest (ClusterOp.GET_ROOT_CHAIN_STAKES_REQUEST, 0xC1).
 type GetRootChainStakesRequest struct {
-	Address        [AddressLength]byte
+	Address        account.Address
 	MinorBlockHash [HashLength]byte
 }
 
 // GetRootChainStakesResponse (ClusterOp.GET_ROOT_CHAIN_STAKES_RESPONSE, 0xC2).
 type GetRootChainStakesResponse struct {
 	ErrorCode uint32
-	Stakes    *big.Int // biguint
+	Stakes    serialize.BigUint
-	Signer    [AddressLength]byte
+	Signer    [20]byte
 }
 
 // GetTotalBalanceRequest (ClusterOp.GET_TOTAL_BALANCE_REQUEST, 0xC3).
@@ -709,8 +707,8 @@ type GetTotalBalanceRequest struct {
 // GetTotalBalanceResponse (ClusterOp.GET_TOTAL_BALANCE_RESPONSE, 0xC4).
 type GetTotalBalanceResponse struct {
 	ErrorCode    uint32
-	TotalBalance *big.Int // biguint
+	TotalBalance serialize.BigUint
-	Next         []byte   `bytesizeofslicelen:"4"`
+	Next         []byte `bytesizeofslicelen:"4"`
 }
 
 // =============================================================================

qkc/cluster/wire/rawbytes_placeholder.go

@@ -4,133 +4,108 @@
 // WIRE MIGRATION SHIM (NOT PART OF PROTOCOL SPEC)
 // =============================================================================
 //
-// This file exists solely to support incremental migration from Python
+// This file provides temporary placeholder types used during the migration
-// QuarkChain Serializable types to Go native structs.
+// from Python QuarkChain Serializable types to native Go structs.
 //
-// It is an IMPLEMENTATION-ONLY COMPATIBILITY LAYER.
+// This is an IMPLEMENTATION-ONLY migration aid.
+// It is NOT part of the wire protocol specification.
 //
 // -----------------------------------------------------------------------------
 // IMPORTANT DISTINCTION
 // -----------------------------------------------------------------------------
 //
-// This file is NOT part of the wire protocol specification.
+// The wire protocol is defined by the concrete message structs in package wire.
 //
-// The actual protocol contract is defined in package wire message structs.
+// RawBytes does NOT implement the original serialization logic of the Python
-// RawBytes is only a temporary bridge for unported complex types.
+// Serializable type it replaces. It only exists to allow incremental migration
+// by temporarily representing unported complex types.
 //
 // -----------------------------------------------------------------------------
 // Migration Strategy
 // -----------------------------------------------------------------------------
 //
-// Many Python-side Serializable types (e.g. RootBlock, MinorBlockHeader,
+// Some Python Serializable types (for example:
-// TypedTransaction, CrossShardTransactionList, TokenBalanceMap, etc.)
-// have not yet been ported to Go.
 //
-// During migration, these types are represented as:
+//   - RootBlock
+//   - MinorBlockHeader
+//   - TypedTransaction
+//   - CrossShardTransactionList
+//   - TokenBalanceMap
 //
-//	*RawBytes
+// ) may not yet have corresponding Go implementations.
+//
+// During migration, these types may temporarily be represented as:
+//
+//     *RawBytes
 //
 // This allows:
-//   - wire format to remain stable
+//   - message structs to be migrated incrementally
-//   - incremental type replacement
+//   - Go code to compile before all dependent types are ported
-//   - independent migration of each message type
+//   - each complex type to be replaced independently
+//
+// RawBytes is expected to be removed once the corresponding native Go type
+// has been implemented.
 //
 // -----------------------------------------------------------------------------
 // RawBytes Semantics
 // -----------------------------------------------------------------------------
 //
-// RawBytes is a bounded-length passthrough placeholder.
+// RawBytes is an opaque placeholder containing serialized bytes of an
+// unported Python Serializable object.
 //
-// It represents an opaque byte segment whose internal structure is defined
+// It does NOT:
-// by the Python FIELDS schema but is not yet implemented in Go.
+//   - decode the contained data
+//   - inspect the contained data
+//   - reproduce the original Python serialization format
+//   - define any protocol-level wire encoding rules
 //
-// Wire behavior:
+// Serialization behavior is inherited from the generic serialization framework
-//   - Serialize: writes 4-byte length prefix + raw bytes (matches Python PrependedSizeBytesSerializer(4))
+// for byte slices. The resulting wire format may differ from the original
-//   - Deserialize: reads 4-byte length prefix + corresponding bytes
+// Python Serializable encoding.
 //
-// This design allows RawBytes to be used in ANY struct position (not just last field).
+// Any required wire compatibility must be achieved by replacing RawBytes with
+// the correct concrete Go type.
 //
 // -----------------------------------------------------------------------------
 // SAFETY CONSTRAINTS
 // -----------------------------------------------------------------------------
 //
-// RawBytes MUST obey the following rules:
+// RawBytes MUST:
 //
-//  1. MUST NOT be partially decoded or inspected
+//   1. remain opaque and must not be partially decoded
-//  2. MUST NOT be used in stable protocol definitions
+//   2. not be used as a permanent protocol type
-//  3. MUST be removed once real Go types are introduced
+//   3. be replaced by the corresponding concrete Go implementation
 //
-// Any violation of these rules results in undefined wire behavior.
+// Using RawBytes as a final protocol representation may result in wire format
+// incompatibility.
 //
 // -----------------------------------------------------------------------------
 // Lifecycle
 // -----------------------------------------------------------------------------
 //
-// This file is TEMPORARY and will be removed after full migration.
+// Migration completion:
 //
-// Migration completion steps:
+//   1. Implement the corresponding native Go struct
-//  1. Replace all *RawBytes fields with concrete types
+//   2. Replace all *RawBytes fields with concrete types
-//  2. Verify wire compatibility via round-trip tests
+//   3. Verify compatibility through Python/Go wire compatibility tests
-//  3. Delete this file entirely
+//   4. Remove this migration shim
 //
 // -----------------------------------------------------------------------------
 // WARNING
 // -----------------------------------------------------------------------------
 //
-// This file is NOT production protocol logic.
+// This file contains temporary migration helpers only.
-// It is a migration tool and must be treated as unstable internal code.
+// It must not become part of the production protocol implementation.
+//
+
 package wire
 
-import (
+// RawBytes is an opaque placeholder for Python Serializable types that have
-	"encoding/binary"
+// not yet been migrated to native Go structs.
-	"fmt"
-
-	"github.com/ethereum/go-ethereum/qkc/serialize"
-)
-
-// RawBytes is a transparent byte passthrough placeholder for unported complex types.
-type RawBytes []byte
-
-func (r RawBytes) Serialize(w *[]byte) error {
-	const maxRawBytesSize = 100 * 1024 * 1024 // 100 MB
-	if len(r) > maxRawBytesSize {
-		return fmt.Errorf("RawBytes.Serialize: size %d exceeds max %d", len(r), maxRawBytesSize)
-	}
-
-	// Write 4-byte length prefix (matches Python PrependedSizeBytesSerializer(4))
-	lenBuf := make([]byte, 4)
-	binary.BigEndian.PutUint32(lenBuf, uint32(len(r)))
-	*w = append(*w, lenBuf...)
-	*w = append(*w, r...)
-	return nil
-}
-
-// Deserialize reads 4-byte length prefix and corresponding bytes.
 //
-// TEMPORARY: Delete this placeholder once real types (RootBlock, MinorBlockHeader) are ported.
+// RawBytes does not define custom wire behavior. It follows the default
-func (r *RawBytes) Deserialize(bb *serialize.ByteBuffer) error {
+// serialization behavior of the underlying byte slice type.
-	const maxRawBytesSize = 100 * 1024 * 1024 // 100 MB, matches Serialize
+//
-
+// It must be replaced by the corresponding concrete Go type once migration
-	// Read 4-byte length prefix
+// is complete.
-	length, err := bb.GetUInt32()
+type RawBytes []byte
-	if err != nil {
-		return err
-	}
-
-	if length > maxRawBytesSize {
-		return fmt.Errorf("RawBytes.Deserialize: length %d exceeds max %d", length, maxRawBytesSize)
-	}
-
-	// Read the actual bytes
-	bytes, err := bb.ReadBytes(int(length))
-	if err != nil {
-		return err
-	}
-
-	*r = RawBytes(bytes)
-	return nil
-}
-
-// Compile-time check: RawBytes implements Serializable (required by serialize package).
-// This ensures serialize.Serialize(&buf, &struct{Field *RawBytes}) works.
-var _ serialize.Serializable = (*RawBytes)(nil)