docs: align README and PQTx comments with PQVM-native design#18
Merged
Conversation
- README: PQVM-native chain description - src/transactions.ts: EIP-1559-style fee fields (not claiming ECDSA-based signing), Shell chain ID label instead of EIP-155, removed bare EIP-1559 and EIP-155 labels Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Updates shell-sdk documentation/comments to reflect the current “PQVM-native” positioning and adjusts transaction-field wording away from strict EVM framing.
Changes:
- Updates README tagline to describe Shell Chain as “PQVM-native”.
- Refines
transactions.tsdocstrings aroundtx_type,chainId, and EIP-1559 fee fields.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Updates the project tagline to “PQVM-native” framing. |
| src/transactions.ts | Tweaks JSDoc wording for transaction type, chain ID, and fee-field descriptions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /** Options accepted by {@link buildTransaction}. */ | ||
| export interface BuildTransactionOptions { | ||
| /** EIP-155 chain ID. Devnet = 424242. */ | ||
| /** Shell chain ID. Devnet = 424242. */ |
Collaborator
Author
There was a problem hiding this comment.
Fixed in 13ce3ec. All three issues addressed: standardized chainId to EIP-155 chain ID (Shell Chain) in BuildTransactionOptions; removed -style suffix from fee-field docs for consistency with the constant declarations; added (scaffolded; not enforced by the chain) clarification to both maxFeePerGas and maxPriorityFeePerGas.
Comment on lines
61
to
66
| /** Gas limit. Defaults to {@link DEFAULT_TRANSFER_GAS_LIMIT}. */ | ||
| gasLimit?: number; | ||
| /** EIP-1559 max fee per gas in wei. Defaults to {@link DEFAULT_MAX_FEE_PER_GAS}. */ | ||
| /** EIP-1559-style max fee per gas in wei. Defaults to {@link DEFAULT_MAX_FEE_PER_GAS}. */ | ||
| maxFeePerGas?: number; | ||
| /** EIP-1559 priority fee in wei. Defaults to {@link DEFAULT_MAX_PRIORITY_FEE_PER_GAS}. */ | ||
| /** EIP-1559-style priority fee in wei. Defaults to {@link DEFAULT_MAX_PRIORITY_FEE_PER_GAS}. */ | ||
| maxPriorityFeePerGas?: number; |
Collaborator
Author
There was a problem hiding this comment.
Fixed in 13ce3ec. All three issues addressed: standardized chainId to EIP-155 chain ID (Shell Chain) in BuildTransactionOptions; removed -style suffix from fee-field docs for consistency with the constant declarations; added (scaffolded; not enforced by the chain) clarification to both maxFeePerGas and maxPriorityFeePerGas.
Comment on lines
34
to
35
| /** Default transaction type: `2` (EIP-1559-style fee fields; Shell PQTx format). */ | ||
| export const DEFAULT_TX_TYPE = 2; |
Collaborator
Author
There was a problem hiding this comment.
Fixed in 13ce3ec. All three issues addressed: standardized chainId to EIP-155 chain ID (Shell Chain) in BuildTransactionOptions; removed -style suffix from fee-field docs for consistency with the constant declarations; added (scaffolded; not enforced by the chain) clarification to both maxFeePerGas and maxPriorityFeePerGas.
…-field JSDoc - Standardize chainId description to 'EIP-155 chain ID (Shell Chain)' in BuildTransactionOptions (was 'Shell chain ID'), matching all other helpers - Remove '-style' suffix from EIP-1559 fee field docs in BuildTransactionOptions for consistency with DEFAULT_MAX_FEE_PER_GAS / DEFAULT_MAX_PRIORITY_FEE_PER_GAS - Add '(scaffolded; not enforced by the chain)' note to maxFeePerGas and maxPriorityFeePerGas fields to clarify gas fields are present in encoding but not yet active on-chain - Update DEFAULT_TX_TYPE comment to explain fee-field scaffolding intent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
LucienSong
added a commit
to LucienSong/shell-sdk
that referenced
this pull request
May 24, 2026
* spec: align address format to 0x 64-char hex 32-byte - Rewrite address.ts: BLAKE3(algo_id||pk) → 32 bytes, 0x hex display - Remove bech32m/pq1 encoding; no version byte - Rename: bytesToShellAddress, shellAddressToBytes, deriveShellAddressFromPublicKey, isShellAddress, normalizeShellAddress - Keep legacy pq* aliases (deprecated) for callers during transition - system-contracts.ts: system addresses now 32-byte big-endian (matching shell-chain) - Update all src/*.ts: imports, comments, pq1 examples → 0x - index.ts: export new Shell* names + legacy aliases Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add self-contained AGENTS.md SSoT for AI agents (ShellDAO#16) * docs: add self-contained AGENTS.md SSoT for AI agents Add an AGENTS.md (and CLAUDE.md pointer) in this repository root that serves as the single source of truth for AI coding agents working here. The file is fully self-contained (no references to files outside this submodule) and English-only (apart from one literal Chinese template string for AI-attribution). Cross-vendor: AGENTS.md is the native format for Codex, Copilot CLI; CLAUDE.md, .cursor/rules/main.mdc, and .github/copilot-instructions.md all point to AGENTS.md. 🤖 本提交由 AI Agent (Copilot) 创建 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(gitignore): ignore local AI/Agent state directories Add a standard ignore block for AI/agent local caches, configs, and scratch files (.claude/, .codex/, .cursor/, .antigravity/, .aider*, .continue/, .roo/, .windsurf/, .copilot/, AGENTS.local.md, etc.). The committed SSoT files (AGENTS.md, CLAUDE.md, docs/agents/) remain tracked — only ad-hoc local agent state is ignored. 🤖 本提交由 AI Agent (Copilot) 创建 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(readme): align with shell-chain v0.23.0 — drop pq1/Bech32m, document 32-byte 0x addresses, flag signing-hash drift (ShellDAO#17) * docs(readme): align with chain v0.23.0 — drop pq1/Bech32m examples, document 32-byte 0x address format, flag signing-hash drift Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: fix system-contracts table, address exports, and error messages Address three Copilot review comments on PR ShellDAO#17: 1. Fix malformed system-contracts table (3-column header with 2-column rows) — collapse to a clean 2-column Name/Address table with full 32-byte literal addresses. 2. Fix normalizeShellAddress error example (lines 206, 737) to match the actual thrown message: 'expected 0x + 64-char hex address, got: …' 3. Fix system-contracts module reference: remove the non-existent validatorRegistryHexAddress / accountManagerHexAddress entries; document only the actual exports (validatorRegistryAddress / accountManagerAddress) with their full 32-byte canonical values; update the isSystemContractAddress example to use a 32-byte address. Also fix stale error message in the error-handling table: 'expected 20 address bytes' → 'expected 32 address bytes' to match address.ts:37. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test: update fixtures and assertions for v0.23.0 0x address format Replace all pq1/Bech32m address references in test fixtures and assertions with valid 0x + 64-char hex Shell addresses. Update keystore fixture address fields to match BLAKE3-derived canonical addresses. Fix tampered-address test to produce a valid 64-char hex address before mutation so the keystore address-mismatch guard is exercised (not the format validator). Update rust-compat fixture pq_address and transaction hash vectors for 32-byte address encoding. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: align README and PQTx comments with PQVM-native design (ShellDAO#18) * docs: replace EVM-compatible headline; clarify PQTx fee-field comments - README: PQVM-native chain description - src/transactions.ts: EIP-1559-style fee fields (not claiming ECDSA-based signing), Shell chain ID label instead of EIP-155, removed bare EIP-1559 and EIP-155 labels Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(transactions): address review comments — standardize chainId/fee-field JSDoc - Standardize chainId description to 'EIP-155 chain ID (Shell Chain)' in BuildTransactionOptions (was 'Shell chain ID'), matching all other helpers - Remove '-style' suffix from EIP-1559 fee field docs in BuildTransactionOptions for consistency with DEFAULT_MAX_FEE_PER_GAS / DEFAULT_MAX_PRIORITY_FEE_PER_GAS - Add '(scaffolded; not enforced by the chain)' note to maxFeePerGas and maxPriorityFeePerGas fields to clarify gas fields are present in encoding but not yet active on-chain - Update DEFAULT_TX_TYPE comment to explain fee-field scaffolding intent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(sdk): scrub stale pq1 bech32m mentions from README/examples Remove stale documentation and example references that implied pq1 bech32m was a valid current render. Current v0.23.0-compatible APIs use BLAKE3-derived 32-byte Shell addresses rendered as 0x + 64 lowercase hex; deprecated Pq* aliases remain for API compatibility. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
LucienSong
added a commit
that referenced
this pull request
May 24, 2026
* spec: align address format to 0x 64-char hex 32-byte - Rewrite address.ts: BLAKE3(algo_id||pk) → 32 bytes, 0x hex display - Remove bech32m/pq1 encoding; no version byte - Rename: bytesToShellAddress, shellAddressToBytes, deriveShellAddressFromPublicKey, isShellAddress, normalizeShellAddress - Keep legacy pq* aliases (deprecated) for callers during transition - system-contracts.ts: system addresses now 32-byte big-endian (matching shell-chain) - Update all src/*.ts: imports, comments, pq1 examples → 0x - index.ts: export new Shell* names + legacy aliases * docs: add self-contained AGENTS.md SSoT for AI agents (#16) * docs: add self-contained AGENTS.md SSoT for AI agents Add an AGENTS.md (and CLAUDE.md pointer) in this repository root that serves as the single source of truth for AI coding agents working here. The file is fully self-contained (no references to files outside this submodule) and English-only (apart from one literal Chinese template string for AI-attribution). Cross-vendor: AGENTS.md is the native format for Codex, Copilot CLI; CLAUDE.md, .cursor/rules/main.mdc, and .github/copilot-instructions.md all point to AGENTS.md. 🤖 本提交由 AI Agent (Copilot) 创建 * chore(gitignore): ignore local AI/Agent state directories Add a standard ignore block for AI/agent local caches, configs, and scratch files (.claude/, .codex/, .cursor/, .antigravity/, .aider*, .continue/, .roo/, .windsurf/, .copilot/, AGENTS.local.md, etc.). The committed SSoT files (AGENTS.md, CLAUDE.md, docs/agents/) remain tracked — only ad-hoc local agent state is ignored. 🤖 本提交由 AI Agent (Copilot) 创建 --------- * docs(readme): align with shell-chain v0.23.0 — drop pq1/Bech32m, document 32-byte 0x addresses, flag signing-hash drift (#17) * docs(readme): align with chain v0.23.0 — drop pq1/Bech32m examples, document 32-byte 0x address format, flag signing-hash drift * docs: fix system-contracts table, address exports, and error messages Address three Copilot review comments on PR #17: 1. Fix malformed system-contracts table (3-column header with 2-column rows) — collapse to a clean 2-column Name/Address table with full 32-byte literal addresses. 2. Fix normalizeShellAddress error example (lines 206, 737) to match the actual thrown message: 'expected 0x + 64-char hex address, got: …' 3. Fix system-contracts module reference: remove the non-existent validatorRegistryHexAddress / accountManagerHexAddress entries; document only the actual exports (validatorRegistryAddress / accountManagerAddress) with their full 32-byte canonical values; update the isSystemContractAddress example to use a 32-byte address. Also fix stale error message in the error-handling table: 'expected 20 address bytes' → 'expected 32 address bytes' to match address.ts:37. * test: update fixtures and assertions for v0.23.0 0x address format Replace all pq1/Bech32m address references in test fixtures and assertions with valid 0x + 64-char hex Shell addresses. Update keystore fixture address fields to match BLAKE3-derived canonical addresses. Fix tampered-address test to produce a valid 64-char hex address before mutation so the keystore address-mismatch guard is exercised (not the format validator). Update rust-compat fixture pq_address and transaction hash vectors for 32-byte address encoding. --------- * docs: align README and PQTx comments with PQVM-native design (#18) * docs: replace EVM-compatible headline; clarify PQTx fee-field comments - README: PQVM-native chain description - src/transactions.ts: EIP-1559-style fee fields (not claiming ECDSA-based signing), Shell chain ID label instead of EIP-155, removed bare EIP-1559 and EIP-155 labels * docs(transactions): address review comments — standardize chainId/fee-field JSDoc - Standardize chainId description to 'EIP-155 chain ID (Shell Chain)' in BuildTransactionOptions (was 'Shell chain ID'), matching all other helpers - Remove '-style' suffix from EIP-1559 fee field docs in BuildTransactionOptions for consistency with DEFAULT_MAX_FEE_PER_GAS / DEFAULT_MAX_PRIORITY_FEE_PER_GAS - Add '(scaffolded; not enforced by the chain)' note to maxFeePerGas and maxPriorityFeePerGas fields to clarify gas fields are present in encoding but not yet active on-chain - Update DEFAULT_TX_TYPE comment to explain fee-field scaffolding intent --------- * docs(sdk): scrub stale pq1 bech32m mentions from README/examples Remove stale documentation and example references that implied pq1 bech32m was a valid current render. Current v0.23.0-compatible APIs use BLAKE3-derived 32-byte Shell addresses rendered as 0x + 64 lowercase hex; deprecated Pq* aliases remain for API compatibility. --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Align shell-sdk documentation with the current PQVM-native architecture.
Changes
EVM-compatibleheadline withPQVM-nativein READMEPQTxfee-field comments (gas fields are scaffolded, not active)Context
shell-chain v0.23.0 dropped 20-byte EVM addresses and confirmed ML-DSA-65 as the primary signing algorithm. The SDK documentation was still using the old headline; this PR brings it in sync.
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com