From 5e5d9b76989f1265728f88f36863308133b2c436 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Sat, 11 Jul 2026 23:03:00 +0800 Subject: [PATCH 1/3] L1: add qkc types design doc --- L1/qkc-3-types-design.md | 76 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 L1/qkc-3-types-design.md diff --git a/L1/qkc-3-types-design.md b/L1/qkc-3-types-design.md new file mode 100644 index 0000000..767dbbb --- /dev/null +++ b/L1/qkc-3-types-design.md @@ -0,0 +1,76 @@ +# qkc-3-types design doc + +## Goal + +Add QuarkChain's basic type layer under `qkc/types`: hash/RLP helpers, token balances, logs, receipts, transactions, and root/minor blocks. + +This series only adds standalone QKC types and byte-compatible encoding/hash behavior. It does not wire these types into `core/state`, `core/types`, EVM execution, block import, or P2P/RPC. + +## Boundary + +`qkc/types` may depend on geth's general utilities such as `common`, `crypto`, `rlp`, `trie`, and isolated base types. Geth core packages should not depend on `qkc/types` in this series. + +This keeps the dependency direction clear: + +```text +qkc/types -> geth utilities +geth core/state/vm -> no qkc/types dependency in this series +``` + +If later PRs need QKC data in geth core, they should add explicit adapters or a QKC-specific integration layer instead of directly mixing package responsibilities. + +## TokenBalances note + +MNT PRs also define `TokenBalances`, but that type is for account/state-account encoding. The `qkc/types` version is used by QKC block/header wire types, especially `CoinbaseAmount`. + +They should not be blindly merged by making `qkc/types` depend on `core/types`. The balance representation should still align with modern geth/MNT (`uint256.Int` internally), while `qkc/serialize` boundaries can convert to the historical wire bytes. If we want one canonical type later, it should move to a neutral QKC package first, then both users can depend on it. + +## PR split + +All PRs are stacked; each one is based on the previous one. + +1. `qkc-3-types-01-hash-utils` + - Title: `qkc/types: add hash and rlp helpers` + - Adds `DeriveSha`, `CalculateMerkleRoot`, `serHash`, and QKC `Uint32` RLP. + - Review focus: pyquarkchain-compatible bytes/hash behavior. + +2. `qkc-3-types-02-token-balances` + - Title: `qkc/types: add token balances` + - Adds QKC token balance container and encoding for block/header usage. + - Review focus: list/trie encoding semantics, copy behavior, and boundary with MNT account-state types. + +3. `qkc-3-types-03-logs-receipts` + - Title: `qkc/types: add logs and receipts` + - Adds QKC logs, receipts, bloom, and receipt storage/wire encoding. + - Review focus: receipt status/post-state encoding and `DeriveSha(Receipts)` compatibility. + +4. `qkc-3-types-04-transactions` + - Title: `qkc/types: add transactions and signing` + - Adds EVM transactions, cross-shard transactions, signing, and ABI helpers. + - Review focus: shard fields, token IDs, tx hash/signing compatibility. + +5. `qkc-3-types-05-blocks` + - Title: `qkc/types: add root and minor blocks` + - Adds root/minor block headers, metadata, blocks, copy/hash helpers. + - Review focus: block serialization/hash and composition of tx/receipt roots. + +## Testing + +Use pyquarkchain-generated golden vectors for consensus-critical bytes and hashes whenever possible. Do not only recompute expected values with the same Go helpers under test. + +Coverage should include: + +- hash helpers, `Uint32`, `DeriveSha`, `CalculateMerkleRoot` +- token balance encoding and round trips +- log/receipt RLP, storage encoding, bloom, status handling +- transaction RLP, serialize, hash, signing/sender recovery +- root/minor block serialization, hash, seal hash, copy behavior +- invalid inputs: bad RLP prefix/length, invalid receipt status, invalid signature, nil/empty cases + +Deferred to later integration PRs: + +- state/account trie root +- receipt root from real execution receipts +- MNT account encoding with snapshot/pathdb/history +- block import and state transition +- P2P/RPC wire integration From fef33d3689be5e12ce20331153a405d78c71ffab Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Mon, 13 Jul 2026 20:10:54 +0800 Subject: [PATCH 2/3] L1: clarify qkc types scope --- L1/qkc-3-types-design.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/L1/qkc-3-types-design.md b/L1/qkc-3-types-design.md index 767dbbb..d20b9b4 100644 --- a/L1/qkc-3-types-design.md +++ b/L1/qkc-3-types-design.md @@ -6,6 +6,12 @@ Add QuarkChain's basic type layer under `qkc/types`: hash/RLP helpers, token bal This series only adds standalone QKC types and byte-compatible encoding/hash behavior. It does not wire these types into `core/state`, `core/types`, EVM execution, block import, or P2P/RPC. +## Scope + +In scope: standalone QKC wire/type definitions for hashes, token balances, logs, receipts, transactions, and root/minor blocks. The transaction PR adds transaction encoding, hashing, signing, and sender recovery as type-level behavior only. + +Out of scope: using these types in execution, state transition, account storage, block import, P2P/RPC, snapshot/pathdb/history, or MNT account integration. + ## Boundary `qkc/types` may depend on geth's general utilities such as `common`, `crypto`, `rlp`, `trie`, and isolated base types. Geth core packages should not depend on `qkc/types` in this series. From 3f67126cfca208f2d8bae58d0e46163b6afecb24 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Wed, 15 Jul 2026 11:47:14 +0800 Subject: [PATCH 3/3] L1: clarify qkc types PR split --- L1/qkc-3-types-design.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/L1/qkc-3-types-design.md b/L1/qkc-3-types-design.md index d20b9b4..c4a045f 100644 --- a/L1/qkc-3-types-design.md +++ b/L1/qkc-3-types-design.md @@ -34,31 +34,32 @@ They should not be blindly merged by making `qkc/types` depend on `core/types`. ## PR split All PRs are stacked; each one is based on the previous one. +Each PR should be reviewable on its own: why it is needed and what later PR depends on it. 1. `qkc-3-types-01-hash-utils` - Title: `qkc/types: add hash and rlp helpers` - - Adds `DeriveSha`, `CalculateMerkleRoot`, `serHash`, and QKC `Uint32` RLP. - - Review focus: pyquarkchain-compatible bytes/hash behavior. + - Why needed: later receipts, transactions, and blocks all need pyquarkchain-compatible hash/RLP helpers before their golden-vector tests can be meaningful. + - Adds: `DeriveSha`, `CalculateMerkleRoot`, `serHash`, and QKC `Uint32` RLP. 2. `qkc-3-types-02-token-balances` - Title: `qkc/types: add token balances` - - Adds QKC token balance container and encoding for block/header usage. - - Review focus: list/trie encoding semantics, copy behavior, and boundary with MNT account-state types. + - Why needed: QKC block/header wire types reference token balance bytes, especially `CoinbaseAmount`, but this PR does not model account-state storage. + - Adds: QKC token balance container and encoding for block/header usage. 3. `qkc-3-types-03-logs-receipts` - Title: `qkc/types: add logs and receipts` - - Adds QKC logs, receipts, bloom, and receipt storage/wire encoding. - - Review focus: receipt status/post-state encoding and `DeriveSha(Receipts)` compatibility. + - Why needed: minor blocks need receipt/log wire encoding, receipt roots, and header bloom values before block types can be verified. + - Adds: QKC logs, receipts, bloom integration, and receipt storage/wire encoding. 4. `qkc-3-types-04-transactions` - Title: `qkc/types: add transactions and signing` - - Adds EVM transactions, cross-shard transactions, signing, and ABI helpers. - - Review focus: shard fields, token IDs, tx hash/signing compatibility. + - Why needed: minor blocks contain QKC transactions, and block hash/root tests need transaction encoding, hashing, signing, and sender recovery to match pyquarkchain. + - Adds: EVM transactions, cross-shard transactions, signing, and ABI helpers. 5. `qkc-3-types-05-blocks` - Title: `qkc/types: add root and minor blocks` - - Adds root/minor block headers, metadata, blocks, copy/hash helpers. - - Review focus: block serialization/hash and composition of tx/receipt roots. + - Why needed: this is the first PR that composes the earlier standalone types into QKC root/minor block headers and block bodies. + - Adds: root/minor block headers, metadata, blocks, copy/hash helpers. ## Testing