shell-sdk 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [0.7.1] — 2026-05-06
+
+### Added
+- Typed Shell RPC reward metadata for address-history and transaction-summary
+  responses, including block gas rewards, STARK rewards, reward layers,
+  source hashes, and compression accounting fields.
+
+### Changed
+- Preserve pq1-only compatibility from `0.7.0` while aligning the SDK type
+  surface with `shell-chain v0.21.1`.
+
+## [0.7.0] — 2026-04-30 ⚠️ BREAKING
+
+### Breaking Changes — F-PQ1-ONLY (pq1 bech32m addresses everywhere)
+
+This is a **breaking release**. All `0x` hex address support has been removed.
+
+#### Removed
+- `hexAddress()` / `hexAddressFromPubkey()` exports deleted — use `pq1Address()` instead.
+- `normalizePqAddress()` no longer accepts `0x...` hex strings — only `pq1...` bech32m.
+- Keystore `address` field: `encryptKeystore()` now always emits `pq1...` bech32m (was `0x...` hex).
+- `decryptKeystore()` rejects keystores with `0x` address fields (use `shell-node key migrate` first).
+
+#### Added
+- `pq1Address(pubkey, sigType)` — canonical address derivation returning `pq1...` bech32m string.
+- SK-only keystore format: `encryptKeystore` stores only the secret key in ciphertext (no pk concatenation), matching `shell-node key generate` output for full cross-language compatibility.
+- Full cross-format compatibility: SDK keystores are now byte-for-byte compatible with Rust CLI keystores.
+
+#### Updated
+- All SDK test fixtures regenerated with `pq1` addresses.
+- `SIGNATURE_TYPE_IDS.MlDsa65 = 1` (was incorrectly aliased to `0` in v0.6.x).
+- ML-DSA-65 (FIPS 204) via `@noble/post-quantum` — real implementation, not a Dilithium3 alias.
+
+### Migration Guide
+```js
+// Before (0.6.x)
+import { hexAddress } from 'shell-sdk';
+const addr = hexAddress(pubkey, sigType); // "0x..."
+
+// After (0.7.0)
+import { pq1Address } from 'shell-sdk';
+const addr = pq1Address(pubkey, sigType); // "pq1..."
+```
+
+For existing keystores with `0x` addresses: run `shell-node key migrate <keystore.json>` to upgrade to pq1 format.
+
+### Compatibility
+- Requires `shell-chain v0.21.0+` (pq1-only RPC).
+- Not backwards-compatible with SDK `0.6.x` address handling.
+
+## [0.6.0] — 2026-04-27
+
+### Added — ML-DSA-65 (FIPS 204) + Keystore SK-only format
+
+#### Crypto (`keystore.ts`, `address.ts`)
+- **`MlDsa65Adapter`**: real FIPS 204 ML-DSA-65 implementation via `@noble/post-quantum`.
+- **`SIGNATURE_TYPE_IDS.MlDsa65 = 1`**: ML-DSA-65 is now a distinct algorithm (was aliased to Dilithium3=0).
+- **SK-only keystore**: `encryptKeystore` stores only secret key bytes in ciphertext, matching `shell-node` CLI format. Cross-language compatible.
+- **`decryptCliKeystore`** helper removed — standard `decryptKeystore` now handles CLI keystores.
+
+#### Compatibility
+- Fully cross-language compatible: Rust CLI keystores decryptable by SDK and vice versa.
+- `shell-chain v0.20.0+` required for ML-DSA-65 transaction signing.
+
 ## [0.5.0] — 2026-04-26
 
 ### Added — AA Phase 2 (matches `shell-chain v0.19.0`)

package/README.md

@@ -40,6 +40,7 @@
 - **Native account abstraction** — key rotation and custom validation code via system contracts
 - **viem integration** — standard Ethereum JSON-RPC methods via a typed `PublicClient`
 - **Shell-specific RPC** — `shell_getPqPubkey`, `shell_sendTransaction`, `shell_getTransactionsByAddress`, `shell_getNodeInfo`, `shell_getWitness`
+- **Reward-aware history types** — block/address transaction summaries expose readable `shellType`, `rewardKind`, and STARK reward metadata (`rewardLayer`, `rewardSourceHash`, `originalSize`, `compressedSize`)
 - **Node introspection** — `getNodeInfo()` returns version, block height, peer count, and storage profile; `getWitness()` fetches raw PQ signatures for any block
 - **Encrypted keystore** — argon2id KDF + xchacha20-poly1305 cipher; compatible with the Shell CLI
 
@@ -78,7 +79,7 @@ const signer  = new ShellSigner("MlDsa65", adapter);
 const from    = signer.getAddress(); // pq1…
 
 const provider = createShellProvider();
-const nonce    = await provider.client.getTransactionCount({ address: signer.getHexAddress() });
+const nonce    = await provider.client.getTransactionCount({ address: from });
 
 const tx       = buildTransferTransaction({ chainId: 424242, nonce, to: "pq1recipient…", value: parseEther("1") });
 const txHash   = hashTransaction(tx);
@@ -107,7 +108,7 @@ blake3( version(1) || algo_id(1) || public_key )[0..20]
 
 Algorithm IDs: `Dilithium3=0`, `MlDsa65=1`, `SphincsSha2256f=2`.
 
-Internally the chain also recognises the hex representation (`0x…`) of the same 20 bytes, so both forms are interchangeable in SDK APIs.
+Shell Chain v0.21.0+ accepts `pq1…` addresses at user-facing RPC and SDK boundaries. Legacy `0x…` address inputs are rejected.
 
 ### Native account abstraction (AA)
 
@@ -147,7 +148,9 @@ Defined in `src/types.ts`. All types are re-exported from the package root.
 | `ShellSignature` | `{ sig_type, data: number[] }` |
 | `SignedShellTransaction` | Complete signed transaction ready to broadcast |
 | `ShellAccessListItem` | EIP-2930 access list entry |
-| `ShellTxByAddressPage` | Paginated address history response |
+| `ShellKnownRpcTxType` | Literal union of known Shell RPC transaction kinds |
+| `ShellRpcTransactionSummary` | Lightweight transaction summary with Shell reward metadata |
+| `ShellTxByAddressPage` | Paginated address history response with effective `fromBlock`/`toBlock` range |
 | `ShellKdfParams` | argon2id parameters inside a keystore |
 | `ShellCipherParams` | xchacha20-poly1305 nonce inside a keystore |
 | `ShellEncryptedKey` | Full encrypted keystore file structure |
@@ -173,10 +176,7 @@ Defined in `src/types.ts`. All types are re-exported from the package root.
 | `bytesToPqAddress` | `(bytes: Uint8Array, version?) → string` | Encode 20 raw bytes as a `pq1…` bech32m address |
 | `pqAddressToBytes` | `(address: string) → Uint8Array` | Decode a `pq1…` address to its 20 raw bytes |
 | `pqAddressVersion` | `(address: string) → number` | Extract the version byte from a `pq1…` address |
-| `hexAddressToBytes` | `(address: string) → Uint8Array` | Parse a `0x…` address to 20 bytes |
-| `bytesToHexAddress` | `(bytes: Uint8Array) → HexString` | Encode 20 bytes as a `0x…` hex address |
-| `normalizePqAddress` | `(address: string) → string` | Accept either pq1 or 0x form, always return pq1 |
-| `normalizeHexAddress` | `(address: string) → HexString` | Accept either pq1 or 0x form, always return 0x |
+| `normalizePqAddress` | `(address: string) → string` | Validate and return a `pq1…` address |
 | `derivePqAddressFromPublicKey` | `(pk, algoId, version?) → string` | Derive pq1 address from a raw public key |
 | `isPqAddress` | `(address: string) → boolean` | Return `true` if the string is a valid pq1 address |
 
@@ -194,9 +194,9 @@ const address = derivePqAddressFromPublicKey(publicKey, 1 /* MlDsa65 */);
 
 console.log(isPqAddress(address)); // true
 
-// Round-trip normalisation
-normalizePqAddress("0xabcdef…"); // → "pq1…"
+// Validation / normalisation
 normalizePqAddress("pq1qx3f…");  // → "pq1qx3f…" (unchanged)
+normalizePqAddress("0xabcdef…"); // throws: expected a pq1… bech32m address
 ```
 
 ---
@@ -236,8 +236,8 @@ import { shellDevnet } from "shell-sdk/provider";
 | `.rpcHttpUrl` | HTTP RPC URL in use |
 | `getPqPubkey(address)` | `shell_getPqPubkey` → hex public key or `null` |
 | `sendTransaction(signed)` | `shell_sendTransaction` → tx hash string |
-| `getTransactionsByAddress(address, opts)` | `shell_getTransactionsByAddress` with optional `fromBlock/toBlock/page/limit` |
-| `getBlockReceipts(block)` | `eth_getBlockReceipts` → array of receipts |
+| `getTransactionsByAddress(address, opts)` | `shell_getTransactionsByAddress` with optional `fromBlock/toBlock/page/limit`; pin `toBlock` from page 0 for stable full-history pagination |
+| `getBlockReceipts(block)` | `eth_getBlockReceipts` → `ShellRpcReceipt[]` |
 | `getNodeInfo()` | `shell_getNodeInfo` → `ShellNodeInfo` (version, block height, peer count, storage profile) |
 | `getWitness(blockNumberOrHash)` | `shell_getWitness` → `ShellWitnessBundle` or `null` if pruned |
 | `getStorageProfile()` | Convenience wrapper around `getNodeInfo()` → `ShellStorageProfile \| undefined` |
@@ -258,6 +258,11 @@ const pubkeyHex = await provider.getPqPubkey("pq1…");
 const txHash    = await provider.sendTransaction(signedTx);
 
 const history = await provider.getTransactionsByAddress("pq1…", { page: 0, limit: 20 });
+const older = await provider.getTransactionsByAddress("pq1…", {
+  page: 1,
+  limit: 20,
+  toBlock: history.toBlock ?? history.to_block,
+});
 ```
 
 **Custom endpoint:**
@@ -334,7 +339,6 @@ const signer = new ShellSigner("MlDsa65", MlDsa65Adapter.generate());
 | `algorithmId` | Numeric algorithm ID (`0`, `1`, or `2`) |
 | `getPublicKey()` | Raw public key bytes |
 | `getAddress()` | `pq1…` bech32m address |
-| `getHexAddress()` | `0x…` hex address |
 | `sign(message)` | Sign an arbitrary byte message → signature bytes |
 | `buildSignedTransaction(options)` | Sign `txHash` and assemble a `SignedShellTransaction` |
 
@@ -568,7 +572,6 @@ import { buildTransferTransaction, hashTransaction } from "shell-sdk/transaction
 const adapter = MlDsa65Adapter.generate();
 const signer  = new ShellSigner("MlDsa65", adapter);
 const from    = signer.getAddress();      // pq1…
-const fromHex = signer.getHexAddress();   // 0x…
 
 console.log("Address:", from);
 
@@ -576,7 +579,7 @@ console.log("Address:", from);
 const provider = createShellProvider(); // defaults to http://127.0.0.1:8545
 
 // 3. Get current nonce
-const nonce = await provider.client.getTransactionCount({ address: fromHex });
+const nonce = await provider.client.getTransactionCount({ address: from });
 
 // 4. Build the transaction
 const tx = buildTransferTransaction({
@@ -614,7 +617,7 @@ import { parseEther } from "viem";
 
 const signer   = await decryptKeystore(readFileSync("./key.json", "utf8"), process.env.PASSPHRASE!);
 const provider = createShellProvider();
-const nonce    = await provider.client.getTransactionCount({ address: signer.getHexAddress() });
+const nonce    = await provider.client.getTransactionCount({ address: signer.getAddress() });
 
 const tx = buildTransferTransaction({
   chainId: 424242,
@@ -639,13 +642,13 @@ This is the recommended shape for a Chrome extension background worker: keep the
 import { createShellProvider, buildTransferTransaction, hashTransaction } from "shell-sdk";
 
 async function submitTransfer({ signer, to, value, rpcHttpUrl }: {
-  signer: { getHexAddress(): `0x${string}`; buildSignedTransaction(args: { tx: unknown; txHash: Uint8Array; includePublicKey?: boolean }): Promise<unknown> };
+  signer: { getAddress(): string; buildSignedTransaction(args: { tx: unknown; txHash: Uint8Array; includePublicKey?: boolean }): Promise<unknown> };
   to: string;
   value: bigint;
   rpcHttpUrl: string;
 }) {
   const provider = createShellProvider({ rpcHttpUrl });
-  const nonce = await provider.client.getTransactionCount({ address: signer.getHexAddress() });
+  const nonce = await provider.client.getTransactionCount({ address: signer.getAddress() });
 
   const tx = buildTransferTransaction({
     chainId: 424242,
@@ -671,7 +674,7 @@ const provider = createShellProvider({
   rpcHttpUrl: "https://rpc.testnet.shell.network",
 });
 
-const account = normalizePqAddress("0x1234...abcd");
+const account = normalizePqAddress("pq1qx3f...");
 const history = await provider.getTransactionsByAddress(account, { page: 1, limit: 10 });
 
 console.log("recent txs:", history.transactions);
@@ -699,7 +702,7 @@ const currentSigner = await decryptKeystore(readFileSync("old-key.json", "utf8")
 const newAdapter = MlDsa65Adapter.generate();
 const newSigner  = new ShellSigner("MlDsa65", newAdapter);
 
-const nonce = await provider.client.getTransactionCount({ address: currentSigner.getHexAddress() });
+const nonce = await provider.client.getTransactionCount({ address: currentSigner.getAddress() });
 
 // Build the rotateKey system transaction
 const tx = buildRotateKeyTransaction({
@@ -728,7 +731,6 @@ All SDK functions throw standard `Error` instances. Common error messages:
 |---|---|
 | `expected 20 address bytes, got N` | Wrong-length bytes passed to address helpers |
 | `expected pq address prefix, got X` | bech32m prefix is not `pq` |
-| `invalid hex address` | String does not start with `0x` |
 | `invalid bech32m address` | String is not a valid bech32m address |
 | `unsupported key type: X` | Keystore `key_type` not recognised |
 | `unsupported kdf: X` | Only `argon2id` is supported |

package/dist/adapters.d.ts

@@ -4,12 +4,10 @@
  * `@noble/post-quantum` provides ML-DSA-65 and SLH-DSA-SHA2-256f via
  * WebAssembly-accelerated pure-JS implementations.
  *
- * **Dilithium3 compatibility note**: `pqcrypto-dilithium` v0.5 (used by
- * shell-chain) implements ML-DSA-65 (FIPS 204) under the `dilithium3` name.
- * `@noble/post-quantum` `ml_dsa65` produces byte-identical keys and
- * signatures (pk=1952, sk=4032, sig=3309), so `MlDsa65Adapter` is fully
- * wire-compatible with the chain's Dilithium3 verifier. Both `"Dilithium3"`
- * and `"MlDsa65"` algorithm names route to the same adapter.
+ * **Algorithm distinction**: `"Dilithium3"` (type_id=0) and `"ML-DSA-65"` /
+ * `"MlDsa65"` (type_id=1) are now separate algorithms on chain with distinct
+ * address derivation. `MlDsa65Adapter` and `DilithiumAdapter` both use the
+ * same underlying `ml_dsa65` crypto (FIPS 204), but produce different addresses.
  *
  * @module adapters
  */

package/dist/adapters.js

@@ -4,12 +4,10 @@
  * `@noble/post-quantum` provides ML-DSA-65 and SLH-DSA-SHA2-256f via
  * WebAssembly-accelerated pure-JS implementations.
  *
- * **Dilithium3 compatibility note**: `pqcrypto-dilithium` v0.5 (used by
- * shell-chain) implements ML-DSA-65 (FIPS 204) under the `dilithium3` name.
- * `@noble/post-quantum` `ml_dsa65` produces byte-identical keys and
- * signatures (pk=1952, sk=4032, sig=3309), so `MlDsa65Adapter` is fully
- * wire-compatible with the chain's Dilithium3 verifier. Both `"Dilithium3"`
- * and `"MlDsa65"` algorithm names route to the same adapter.
+ * **Algorithm distinction**: `"Dilithium3"` (type_id=0) and `"ML-DSA-65"` /
+ * `"MlDsa65"` (type_id=1) are now separate algorithms on chain with distinct
+ * address derivation. `MlDsa65Adapter` and `DilithiumAdapter` both use the
+ * same underlying `ml_dsa65` crypto (FIPS 204), but produce different addresses.
  *
  * @module adapters
  */

package/dist/address.d.ts

@@ -4,7 +4,6 @@ export declare const PQ_ADDRESS_HRP = "pq";
 export declare const PQ_ADDRESS_LENGTH = 20;
 /** Version byte for V1 Shell addresses (`0x01`). */
 export declare const PQ_ADDRESS_VERSION_V1 = 1;
-type HexAddress = `0x${string}`;
 /**
  * Encode 20 raw address bytes as a `pq1…` bech32m address.
  *
@@ -45,40 +44,15 @@ export declare function pqAddressToBytes(address: string): Uint8Array;
  */
 export declare function pqAddressVersion(address: string): number;
 /**
- * Parse a `0x…` hex address string into its raw 20 bytes.
+ * Normalise an address: validates it is a `pq1…` bech32m address and returns it.
  *
- * @param address - A `0x`-prefixed 40-character hex address.
- * @returns The 20-byte address payload.
- * @throws {Error} If the string does not start with `"0x"` or is not exactly 20 bytes.
- */
-export declare function hexAddressToBytes(address: string): Uint8Array;
-/**
- * Encode 20 raw address bytes as a `0x…` hex address.
- *
- * @param bytes - Exactly 20 address bytes.
- * @returns A `0x`-prefixed 40-character hex string.
- * @throws {Error} If `bytes.length !== 20`.
- */
-export declare function bytesToHexAddress(bytes: Uint8Array): HexAddress;
-/**
- * Normalise an address to `pq1…` bech32m form.
+ * Hex (`0x…`) addresses are no longer accepted. Use `pq1…` format everywhere.
  *
- * Accepts either a `pq1…` or `0x…` address and always returns the canonical
- * bech32m form.
- *
- * @param address - A `pq1…` or `0x…` address.
- * @returns The `pq1…` bech32m address.
+ * @param address - A `pq1…` bech32m address.
+ * @returns The same `pq1…` address (validated).
+ * @throws {Error} If the address is not a valid `pq1…` bech32m address.
  */
 export declare function normalizePqAddress(address: string): string;
-/**
- * Normalise an address to `0x…` hex form.
- *
- * Accepts either a `pq1…` or `0x…` address and always returns the hex form.
- *
- * @param address - A `pq1…` or `0x…` address.
- * @returns The `0x`-prefixed hex address.
- */
-export declare function normalizeHexAddress(address: string): HexAddress;
 /**
  * Derive a `pq1…` address from a raw post-quantum public key.
  *
@@ -116,4 +90,3 @@ export declare function derivePqAddressFromPublicKey(publicKey: Uint8Array, algo
  * ```
  */
 export declare function isPqAddress(address: string): boolean;
-export {};

package/dist/address.js

@@ -1,9 +1,9 @@
 /**
  * PQ address utilities for Shell Chain.
  *
- * Shell Chain uses **bech32m**-encoded addresses (prefix `"pq"`) instead of
- * Ethereum's checksummed hex format. Each address encodes a version byte and
- * 20 address bytes derived from the account's post-quantum public key:
+ * Shell Chain uses **bech32m**-encoded addresses (prefix `"pq"`) exclusively.
+ * Each address encodes a version byte and 20 address bytes derived from the
+ * account's post-quantum public key:
  *
  * ```
  * address_bytes = blake3(version || algo_id || public_key)[0..20]
@@ -12,14 +12,10 @@
  *
  * Algorithm IDs: Dilithium3=0, MlDsa65=1, SphincsSha2256f=2.
  *
- * Both pq1… and 0x… representations refer to the same underlying 20 bytes;
- * the SDK accepts either form in most places via the `AddressLike` type.
- *
  * @module address
  */
 import { blake3 } from "@noble/hashes/blake3";
 import { bech32m } from "@scure/base";
-import { bytesToHex, hexToBytes } from "viem";
 /** Human-readable part (HRP) used in Shell bech32m addresses. */
 export const PQ_ADDRESS_HRP = "pq";
 /** Number of raw address bytes (excluding the version byte). */
@@ -31,11 +27,6 @@ function assertBech32Address(value) {
         throw new Error("invalid bech32m address");
     }
 }
-function assertHexAddress(value) {
-    if (!value.startsWith("0x")) {
-        throw new Error("invalid hex address");
-    }
-}
 /**
  * Encode 20 raw address bytes as a `pq1…` bech32m address.
  *
@@ -106,61 +97,18 @@ export function pqAddressVersion(address) {
     return bytes[0];
 }
 /**
- * Parse a `0x…` hex address string into its raw 20 bytes.
+ * Normalise an address: validates it is a `pq1…` bech32m address and returns it.
  *
- * @param address - A `0x`-prefixed 40-character hex address.
- * @returns The 20-byte address payload.
- * @throws {Error} If the string does not start with `"0x"` or is not exactly 20 bytes.
- */
-export function hexAddressToBytes(address) {
-    assertHexAddress(address);
-    const bytes = hexToBytes(address);
-    if (bytes.length !== PQ_ADDRESS_LENGTH) {
-        throw new Error(`expected ${PQ_ADDRESS_LENGTH} address bytes, got ${bytes.length}`);
-    }
-    return bytes;
-}
-/**
- * Encode 20 raw address bytes as a `0x…` hex address.
+ * Hex (`0x…`) addresses are no longer accepted. Use `pq1…` format everywhere.
  *
- * @param bytes - Exactly 20 address bytes.
- * @returns A `0x`-prefixed 40-character hex string.
- * @throws {Error} If `bytes.length !== 20`.
- */
-export function bytesToHexAddress(bytes) {
-    if (bytes.length !== PQ_ADDRESS_LENGTH) {
-        throw new Error(`expected ${PQ_ADDRESS_LENGTH} address bytes, got ${bytes.length}`);
-    }
-    return bytesToHex(bytes);
-}
-/**
- * Normalise an address to `pq1…` bech32m form.
- *
- * Accepts either a `pq1…` or `0x…` address and always returns the canonical
- * bech32m form.
- *
- * @param address - A `pq1…` or `0x…` address.
- * @returns The `pq1…` bech32m address.
+ * @param address - A `pq1…` bech32m address.
+ * @returns The same `pq1…` address (validated).
+ * @throws {Error} If the address is not a valid `pq1…` bech32m address.
  */
 export function normalizePqAddress(address) {
-    if (isPqAddress(address)) {
-        return address;
-    }
-    return bytesToPqAddress(hexAddressToBytes(address));
-}
-/**
- * Normalise an address to `0x…` hex form.
- *
- * Accepts either a `pq1…` or `0x…` address and always returns the hex form.
- *
- * @param address - A `pq1…` or `0x…` address.
- * @returns The `0x`-prefixed hex address.
- */
-export function normalizeHexAddress(address) {
-    if (isPqAddress(address)) {
-        return bytesToHexAddress(pqAddressToBytes(address));
+    if (!isPqAddress(address)) {
+        throw new Error(`expected a pq1… bech32m address, got: "${address.slice(0, 10)}…"`);
     }
-    assertHexAddress(address);
     return address;
 }
 /**

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
+export { PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
 export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, type CreateShellPublicClientOptions, } from "./provider.js";
-export { accountManagerAddress, accountManagerHexAddress, cancelRecoverySelector, clearValidationCodeSelector, encodeCancelRecoveryCalldata, encodeClearValidationCodeCalldata, encodeExecuteRecoveryCalldata, encodeRotateKeyCalldata, encodeSetGuardiansCalldata, encodeSetValidationCodeCalldata, encodeSubmitRecoveryCalldata, executeRecoverySelector, isSystemContractAddress, rotateKeySelector, setGuardiansSelector, setValidationCodeSelector, submitRecoverySelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
+export { accountManagerAddress, cancelRecoverySelector, clearValidationCodeSelector, encodeCancelRecoveryCalldata, encodeClearValidationCodeCalldata, encodeExecuteRecoveryCalldata, encodeRotateKeyCalldata, encodeSetGuardiansCalldata, encodeSetValidationCodeCalldata, encodeSubmitRecoveryCalldata, executeRecoverySelector, isSystemContractAddress, rotateKeySelector, setGuardiansSelector, setValidationCodeSelector, submitRecoverySelector, validatorRegistryAddress, } from "./system-contracts.js";
 export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS, buildBatchTransaction, buildClearValidationCodeTransaction, buildContractPaymasterTransaction, buildInnerCall, buildInnerTransfer, buildRotateKeyTransaction, buildSessionKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSponsoredTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_AA_GAS_LIMIT, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashBatchTransaction, hashTransaction, type BuildBatchTransactionOptions, type BuildContractPaymasterTransactionOptions, type BuildSessionKeyTransactionOptions, type BuildSponsoredTransactionOptions, } from "./transactions.js";
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, type ParsedShellKeystore, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, type MlDsa65KeyPair, type SlhDsaKeyPair, } from "./adapters.js";
 export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, type SignerAdapter, } from "./signer.js";
 export { AA_MAX_PAYMASTER_CONTEXT, AA_SESSION_KEY_GAS_SURCHARGE } from "./types.js";
-export type { AaBundle, AaInnerCall, AddressLike, GuardianConfig, HexString, RecoveryProposal, SessionAuth, ShellAccessListItem, ShellBatchInnerCallRequest, ShellBatchInnerGas, ShellCipherParams, ShellEncryptedKey, ShellEstimateBatchRequest, ShellEstimateBatchResult, ShellIsSponsoredResult, ShellKdfParams, ShellNodeInfo, ShellPaymasterPolicy, ShellSendTransactionParams, ShellSignature, ShellStorageProfile, ShellTransactionRequest, ShellTxByAddressPage, ShellTxWitness, ShellWitnessBundle, ShellWitnessRootResult, SignedShellTransaction, SignatureTypeName, } from "./types.js";
+export { formatShellRpcTxType } from "./types.js";
+export type { AaBundle, AaInnerCall, AddressLike, GuardianConfig, HexString, RecoveryProposal, SessionAuth, ShellAccessListItem, ShellBatchInnerCallRequest, ShellBatchInnerGas, ShellCipherParams, ShellEncryptedKey, ShellEstimateBatchRequest, ShellEstimateBatchResult, ShellKnownRpcTxType, ShellIsSponsoredResult, ShellKdfParams, ShellNodeInfo, ShellPaymasterPolicy, ShellReadableTxType, ShellRewardKind, ShellRpcReceipt, ShellRpcTransaction, ShellRpcTransactionSummary, ShellRpcTxType, ShellSendTransactionParams, ShellSignature, ShellStorageProfile, ShellTransactionRequest, ShellTxByAddressPage, ShellTxWitness, ShellWitnessBundle, ShellWitnessRootResult, SignedShellTransaction, SignatureTypeName, } from "./types.js";

package/dist/index.js

@@ -1,8 +1,9 @@
-export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
+export { PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
 export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, } from "./provider.js";
-export { accountManagerAddress, accountManagerHexAddress, cancelRecoverySelector, clearValidationCodeSelector, encodeCancelRecoveryCalldata, encodeClearValidationCodeCalldata, encodeExecuteRecoveryCalldata, encodeRotateKeyCalldata, encodeSetGuardiansCalldata, encodeSetValidationCodeCalldata, encodeSubmitRecoveryCalldata, executeRecoverySelector, isSystemContractAddress, rotateKeySelector, setGuardiansSelector, setValidationCodeSelector, submitRecoverySelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
+export { accountManagerAddress, cancelRecoverySelector, clearValidationCodeSelector, encodeCancelRecoveryCalldata, encodeClearValidationCodeCalldata, encodeExecuteRecoveryCalldata, encodeRotateKeyCalldata, encodeSetGuardiansCalldata, encodeSetValidationCodeCalldata, encodeSubmitRecoveryCalldata, executeRecoverySelector, isSystemContractAddress, rotateKeySelector, setGuardiansSelector, setValidationCodeSelector, submitRecoverySelector, validatorRegistryAddress, } from "./system-contracts.js";
 export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS, buildBatchTransaction, buildClearValidationCodeTransaction, buildContractPaymasterTransaction, buildInnerCall, buildInnerTransfer, buildRotateKeyTransaction, buildSessionKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSponsoredTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_AA_GAS_LIMIT, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashBatchTransaction, hashTransaction, } from "./transactions.js";
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, } from "./adapters.js";
 export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, } from "./signer.js";
 export { AA_MAX_PAYMASTER_CONTEXT, AA_SESSION_KEY_GAS_SURCHARGE } from "./types.js";
+export { formatShellRpcTxType } from "./types.js";

package/dist/keystore.d.ts

@@ -16,8 +16,6 @@ export interface ParsedShellKeystore {
     publicKey: Uint8Array;
     /** Canonical `pq1…` address derived from `publicKey`. */
     canonicalAddress: string;
-    /** `0x`-prefixed hex representation of the same address. */
-    hexAddress: string;
 }
 /**
  * Parse a Shell keystore file (string or object) and extract public metadata.
@@ -33,7 +31,7 @@ export interface ParsedShellKeystore {
  * ```typescript
  * const parsed = parseEncryptedKey(readFileSync("key.json", "utf8"));
  * console.log(parsed.canonicalAddress); // pq1…
- * console.log(parsed.signatureType);    // "MlDsa65"
+ * console.log(parsed.signatureType);    // "ML-DSA-65"
  * ```
  */
 export declare function parseEncryptedKey(input: string | ShellEncryptedKey): ParsedShellKeystore;
@@ -77,17 +75,14 @@ export declare function assertSignerMatchesKeystore(signer: ShellSigner, keystor
  *
  * **KDF**: argon2id (parameters from `kdf_params`)
  * **Cipher**: xchacha20-poly1305 (24-byte nonce from `cipher_params`)
- * **Plaintext layout**: `[secret_key_bytes][public_key_bytes]`
- *
- * The decrypted public key is compared against `raw.public_key` to detect
- * wrong passwords or corrupt files before returning the signer.
+ * **Plaintext layout (v1)**: secret key bytes only (sk-only format).
+ * The public key is read from the `public_key` JSON field directly.
  *
  * @param input - Keystore JSON string or object.
  * @param password - The passphrase used to encrypt the key.
  * @returns A fully configured `ShellSigner` ready for signing transactions.
  * @throws {Error} If the KDF or cipher is unsupported.
  * @throws {Error} If decryption fails (wrong password or corrupt ciphertext).
- * @throws {Error} If the decrypted public key does not match the stored one.
  *
  * @example
  * ```typescript

package/dist/keystore.js

@@ -6,19 +6,23 @@
  * - **KDF**: argon2id (memory-hard password derivation)
  * - **Cipher**: xchacha20-poly1305 (authenticated encryption)
  *
- * They are generated by the Shell CLI (`shell key generate`) and are
- * compatible with the SDK's `decryptKeystore` function.
+ * ## Keystore format (v1 — canonical)
  *
- * Plaintext layout after decryption: `[secret_key_bytes][public_key_bytes]`.
+ * The **ciphertext** contains **only the secret key bytes** (sk-only format).
+ * The public key is stored separately in the `public_key` field as plain hex.
+ * This matches the format produced by `shell-node key generate`.
+ *
+ * Previous SDK versions expected `sk || pk` in the ciphertext. That format
+ * is no longer produced or accepted; all new keystores use sk-only.
  *
  * @module keystore
  */
 import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
 import { argon2id } from "hash-wasm";
-import { derivePqAddressFromPublicKey, normalizeHexAddress, normalizePqAddress } from "./address.js";
+import { derivePqAddressFromPublicKey, normalizePqAddress } from "./address.js";
 import { adapterFromKeyPair } from "./adapters.js";
-import { ShellSigner, publicKeyFromHex, signatureTypeFromKeyType } from "./signer.js";
-const SIG_IDS = { "ML-DSA-65": 0, Dilithium3: 0, MlDsa65: 0, SphincsSha2256f: 2 };
+import { ShellSigner, canonicalSignatureType, publicKeyFromHex, signatureTypeFromKeyType, } from "./signer.js";
+const SIG_IDS = { "ML-DSA-65": 1, Dilithium3: 0, MlDsa65: 1, SphincsSha2256f: 2 };
 /**
  * Parse a Shell keystore file (string or object) and extract public metadata.
  *
@@ -33,7 +37,7 @@ const SIG_IDS = { "ML-DSA-65": 0, Dilithium3: 0, MlDsa65: 0, SphincsSha2256f: 2
  * ```typescript
  * const parsed = parseEncryptedKey(readFileSync("key.json", "utf8"));
  * console.log(parsed.canonicalAddress); // pq1…
- * console.log(parsed.signatureType);    // "MlDsa65"
+ * console.log(parsed.signatureType);    // "ML-DSA-65"
  * ```
  */
 export function parseEncryptedKey(input) {
@@ -42,8 +46,7 @@ export function parseEncryptedKey(input) {
     const algorithmId = SIG_IDS[signatureType];
     const publicKey = publicKeyFromHex(raw.public_key);
     const canonicalAddress = derivePqAddressFromPublicKey(publicKey, algorithmId);
-    const hexAddress = normalizeHexAddress(canonicalAddress);
-    return { raw, signatureType, algorithmId, publicKey, canonicalAddress, hexAddress };
+    return { raw, signatureType, algorithmId, publicKey, canonicalAddress };
 }
 /**
  * Parse a keystore and verify that the declared address matches the public key.
@@ -89,7 +92,7 @@ export function exportEncryptedKeyJson(input) {
  * ```
  */
 export function assertSignerMatchesKeystore(signer, keystore) {
-    if (signer.signatureType !== keystore.signatureType) {
+    if (canonicalSignatureType(signer.signatureType) !== keystore.signatureType) {
         throw new Error("algorithm mismatch: signer=" + signer.signatureType + " keystore=" + keystore.signatureType);
     }
     const addr = signer.getAddress();
@@ -110,17 +113,14 @@ function hexToBytes(hex) {
  *
  * **KDF**: argon2id (parameters from `kdf_params`)
  * **Cipher**: xchacha20-poly1305 (24-byte nonce from `cipher_params`)
- * **Plaintext layout**: `[secret_key_bytes][public_key_bytes]`
- *
- * The decrypted public key is compared against `raw.public_key` to detect
- * wrong passwords or corrupt files before returning the signer.
+ * **Plaintext layout (v1)**: secret key bytes only (sk-only format).
+ * The public key is read from the `public_key` JSON field directly.
  *
  * @param input - Keystore JSON string or object.
  * @param password - The passphrase used to encrypt the key.
  * @returns A fully configured `ShellSigner` ready for signing transactions.
  * @throws {Error} If the KDF or cipher is unsupported.
  * @throws {Error} If decryption fails (wrong password or corrupt ciphertext).
- * @throws {Error} If the decrypted public key does not match the stored one.
  *
  * @example
  * ```typescript
@@ -150,17 +150,8 @@ export async function decryptKeystore(input, password) {
     });
     const derivedKey = hexToBytes(derivedKeyHex);
     const chacha = xchacha20poly1305(derivedKey, nonce);
-    const plaintext = chacha.decrypt(ciphertext);
-    const pubkeyLen = parsed.publicKey.length;
-    const skLen = plaintext.length - pubkeyLen;
-    if (skLen <= 0) {
-        throw new Error("payload too short: " + plaintext.length + " bytes");
-    }
-    const secretKey = plaintext.slice(0, skLen);
-    const derivedPubkey = plaintext.slice(skLen);
-    if (!derivedPubkey.every((b, i) => b === parsed.publicKey[i])) {
-        throw new Error("decrypted public key mismatch");
-    }
+    // Plaintext is sk-only; public key comes from the JSON `public_key` field.
+    const secretKey = chacha.decrypt(ciphertext);
     const adapter = adapterFromKeyPair(parsed.signatureType, parsed.publicKey, secretKey);
     return new ShellSigner(parsed.signatureType, adapter);
 }

package/dist/provider.d.ts

@@ -16,7 +16,7 @@
  * @module provider
  */
 import { type Chain, type PublicClient } from "viem";
-import type { ShellEstimateBatchRequest, ShellEstimateBatchResult, ShellIsSponsoredResult, ShellNodeInfo, ShellPaymasterPolicy, ShellStorageProfile, ShellWitnessBundle, ShellWitnessRootResult, SignedShellTransaction } from "./types.js";
+import type { ShellEstimateBatchRequest, ShellEstimateBatchResult, ShellIsSponsoredResult, ShellNodeInfo, ShellPaymasterPolicy, ShellRpcReceipt, ShellStorageProfile, ShellTxByAddressPage, ShellWitnessBundle, ShellWitnessRootResult, SignedShellTransaction } from "./types.js";
 /**
  * Pre-configured viem chain definition for Shell Devnet.
  *
@@ -90,6 +90,7 @@ export interface CreateShellPublicClientOptions {
 }
 /** A typed alias for a viem `PublicClient`. */
 export type ShellPublicClient = PublicClient;
+export type ShellBlockRangeBound = number | `0x${string}`;
 /**
  * RPC client for Shell Chain.
  *
@@ -113,7 +114,7 @@ export declare class ShellProvider {
      * Calls `shell_getPqPubkey`. Returns `null` if the address has not yet
      * submitted a transaction (public key is only recorded on first send).
      *
-     * @param address - A `pq1…` or `0x…` address.
+     * @param address - A `pq1…` bech32m address.
      * @returns Hex-encoded public key string, or `null` if unknown.
      */
     getPqPubkey(address: string): Promise<string | null>;
@@ -138,14 +139,16 @@ export declare class ShellProvider {
      * @param options.toBlock - End of block range (inclusive).
      * @param options.page - Zero-based page index.
      * @param options.limit - Maximum number of results per page.
-     * @returns Raw paginated response from the node.
+     * @returns Paginated response from the node. `fromBlock`/`toBlock` in the
+     * response is the effective inclusive range; clients that paginate under
+     * live load should pin `toBlock` from the first page.
      */
     getTransactionsByAddress(address: string, options?: {
-        fromBlock?: number;
-        toBlock?: number;
+        fromBlock?: ShellBlockRangeBound;
+        toBlock?: ShellBlockRangeBound;
         page?: number;
         limit?: number;
-    }): Promise<unknown>;
+    }): Promise<ShellTxByAddressPage>;
     /**
      * Fetch all transaction receipts for a block.
      *
@@ -154,7 +157,7 @@ export declare class ShellProvider {
      * @param block - Block identifier: `"latest"`, `"earliest"`, or a hex block number.
      * @returns Array of transaction receipt objects.
      */
-    getBlockReceipts(block: string): Promise<unknown[]>;
+    getBlockReceipts(block: string): Promise<ShellRpcReceipt[]>;
     /**
      * Fetch metadata about the connected Shell Chain node.
      *
@@ -279,7 +282,7 @@ export declare function createShellWsClient(options?: CreateShellPublicClientOpt
  * @example
  * ```typescript
  * const provider = createShellProvider();
- * const balance  = await provider.client.getBalance({ address: signer.getHexAddress() });
+ * const balance  = await provider.getBalance(signer.getAddress());
  * const hash     = await provider.sendTransaction(signedTx);
  * ```
  */

package/dist/provider.js

@@ -86,7 +86,7 @@ export class ShellProvider {
      * Calls `shell_getPqPubkey`. Returns `null` if the address has not yet
      * submitted a transaction (public key is only recorded on first send).
      *
-     * @param address - A `pq1…` or `0x…` address.
+     * @param address - A `pq1…` bech32m address.
      * @returns Hex-encoded public key string, or `null` if unknown.
      */
     async getPqPubkey(address) {
@@ -115,7 +115,9 @@ export class ShellProvider {
      * @param options.toBlock - End of block range (inclusive).
      * @param options.page - Zero-based page index.
      * @param options.limit - Maximum number of results per page.
-     * @returns Raw paginated response from the node.
+     * @returns Paginated response from the node. `fromBlock`/`toBlock` in the
+     * response is the effective inclusive range; clients that paginate under
+     * live load should pin `toBlock` from the first page.
      */
     async getTransactionsByAddress(address, options = {}) {
         return this.request("shell_getTransactionsByAddress", [
@@ -294,7 +296,7 @@ export function createShellWsClient(options = {}) {
  * @example
  * ```typescript
  * const provider = createShellProvider();
- * const balance  = await provider.client.getBalance({ address: signer.getHexAddress() });
+ * const balance  = await provider.getBalance(signer.getAddress());
  * const hash     = await provider.sendTransaction(signedTx);
  * ```
  */

package/dist/signer.d.ts

@@ -4,9 +4,8 @@ import type { SignedShellTransaction, SignatureTypeName } from "./types.js";
  * Maps each {@link SignatureTypeName} to its numeric algorithm ID used in
  * address derivation and on-chain records.
  *
- * - `"ML-DSA-65"` → `0` (canonical FIPS 204 name)
- * - `"Dilithium3"` → `0` (legacy alias, same algorithm)
- * - `"MlDsa65"` → `0` (camelCase alias, same algorithm)
+ * - `"Dilithium3"` → `0` (Round 3 Dilithium, legacy compat)
+ * - `"ML-DSA-65"` / `"MlDsa65"` → `1` (FIPS 204 ML-DSA-65, canonical)
  * - `"SphincsSha2256f"` → `2`
  */
 export declare const SIGNATURE_TYPE_IDS: Record<SignatureTypeName, number>;
@@ -15,9 +14,9 @@ export declare const SIGNATURE_TYPE_IDS: Record<SignatureTypeName, number>;
  * corresponding {@link SignatureTypeName}.
  *
  * Keys are lowercase; matching is done after calling `.toLowerCase()`.
- * Always returns the FIPS 204 canonical name `"ML-DSA-65"` for ML-DSA-65 variants.
  */
 export declare const KEY_TYPE_TO_SIGNATURE_TYPE: Record<string, SignatureTypeName>;
+export declare function canonicalSignatureType(signatureType: SignatureTypeName): SignatureTypeName;
 /**
  * Minimal interface that any post-quantum signing implementation must satisfy
  * to be used with {@link ShellSigner}.
@@ -55,8 +54,7 @@ export interface SignerAdapter {
  * const adapter = MlDsa65Adapter.generate();
  * const signer  = new ShellSigner("MlDsa65", adapter);
  *
- * console.log(signer.getAddress());    // pq1…
- * console.log(signer.getHexAddress()); // 0x…
+ * console.log(signer.getAddress()); // pq1…
  * ```
  */
 export declare class ShellSigner {
@@ -83,12 +81,6 @@ export declare class ShellSigner {
      * The address is computed deterministically from the public key and algorithm ID.
      */
     getAddress(): string;
-    /**
-     * Return the `0x…` hex representation of this signer's address.
-     *
-     * Equivalent to `normalizeHexAddress(signer.getAddress())`.
-     */
-    getHexAddress(): `0x${string}`;
     /**
      * Sign a raw byte message with the underlying adapter.
      *
@@ -132,7 +124,7 @@ export declare class ShellSigner {
  *
  * @example
  * ```typescript
- * signatureTypeFromKeyType("mldsa65");          // "MlDsa65"
+ * signatureTypeFromKeyType("mldsa65");          // "ML-DSA-65"
  * signatureTypeFromKeyType("sphincs-sha2-256f"); // "SphincsSha2256f"
  * ```
  */

package/dist/signer.js

@@ -10,21 +10,20 @@
  * @module signer
  */
 import { hexToBytes } from "viem";
-import { derivePqAddressFromPublicKey, normalizeHexAddress, normalizePqAddress } from "./address.js";
+import { derivePqAddressFromPublicKey, normalizePqAddress } from "./address.js";
 import { buildSignature, buildSignedTransaction, } from "./transactions.js";
 /**
  * Maps each {@link SignatureTypeName} to its numeric algorithm ID used in
  * address derivation and on-chain records.
  *
- * - `"ML-DSA-65"` → `0` (canonical FIPS 204 name)
- * - `"Dilithium3"` → `0` (legacy alias, same algorithm)
- * - `"MlDsa65"` → `0` (camelCase alias, same algorithm)
+ * - `"Dilithium3"` → `0` (Round 3 Dilithium, legacy compat)
+ * - `"ML-DSA-65"` / `"MlDsa65"` → `1` (FIPS 204 ML-DSA-65, canonical)
  * - `"SphincsSha2256f"` → `2`
  */
 export const SIGNATURE_TYPE_IDS = {
-    "ML-DSA-65": 0,
+    "ML-DSA-65": 1,
     Dilithium3: 0,
-    MlDsa65: 0,
+    MlDsa65: 1,
     SphincsSha2256f: 2,
 };
 /**
@@ -32,14 +31,16 @@ export const SIGNATURE_TYPE_IDS = {
  * corresponding {@link SignatureTypeName}.
  *
  * Keys are lowercase; matching is done after calling `.toLowerCase()`.
- * Always returns the FIPS 204 canonical name `"ML-DSA-65"` for ML-DSA-65 variants.
  */
 export const KEY_TYPE_TO_SIGNATURE_TYPE = {
     "ml-dsa-65": "ML-DSA-65",
     mldsa65: "ML-DSA-65",
-    dilithium3: "ML-DSA-65",
+    dilithium3: "Dilithium3",
     "sphincs-sha2-256f": "SphincsSha2256f",
 };
+export function canonicalSignatureType(signatureType) {
+    return signatureType === "MlDsa65" ? "ML-DSA-65" : signatureType;
+}
 /**
  * High-level Shell Chain signer.
  *
@@ -54,8 +55,7 @@ export const KEY_TYPE_TO_SIGNATURE_TYPE = {
  * const adapter = MlDsa65Adapter.generate();
  * const signer  = new ShellSigner("MlDsa65", adapter);
  *
- * console.log(signer.getAddress());    // pq1…
- * console.log(signer.getHexAddress()); // 0x…
+ * console.log(signer.getAddress()); // pq1…
  * ```
  */
 export class ShellSigner {
@@ -68,7 +68,7 @@ export class ShellSigner {
      * @param adapter - An adapter providing `sign` and `getPublicKey`.
      */
     constructor(signatureType, adapter) {
-        this.signatureType = signatureType;
+        this.signatureType = canonicalSignatureType(signatureType);
         this.adapter = adapter;
     }
     /**
@@ -91,14 +91,6 @@ export class ShellSigner {
     getAddress() {
         return derivePqAddressFromPublicKey(this.getPublicKey(), this.algorithmId);
     }
-    /**
-     * Return the `0x…` hex representation of this signer's address.
-     *
-     * Equivalent to `normalizeHexAddress(signer.getAddress())`.
-     */
-    getHexAddress() {
-        return normalizeHexAddress(this.getAddress());
-    }
     /**
      * Sign a raw byte message with the underlying adapter.
      *
@@ -150,7 +142,7 @@ export class ShellSigner {
  *
  * @example
  * ```typescript
- * signatureTypeFromKeyType("mldsa65");          // "MlDsa65"
+ * signatureTypeFromKeyType("mldsa65");          // "ML-DSA-65"
  * signatureTypeFromKeyType("sphincs-sha2-256f"); // "SphincsSha2256f"
  * ```
  */

package/dist/system-contracts.d.ts

@@ -1,8 +1,4 @@
 import type { AddressLike, HexString } from "./types.js";
-/** Hex address of the ValidatorRegistry system contract (`0x…0001`). */
-export declare const validatorRegistryHexAddress = "0x0000000000000000000000000000000000000001";
-/** Hex address of the AccountManager system contract (`0x…0002`). */
-export declare const accountManagerHexAddress = "0x0000000000000000000000000000000000000002";
 /** `pq1…` bech32m address of the ValidatorRegistry system contract. */
 export declare const validatorRegistryAddress: string;
 /** `pq1…` bech32m address of the AccountManager system contract. */
@@ -57,17 +53,13 @@ export declare function encodeClearValidationCodeCalldata(): HexString;
 /**
  * Return `true` if `address` refers to one of the Shell system contracts.
  *
- * Accepts both `pq1…` and `0x…` forms for the AccountManager and
- * ValidatorRegistry addresses.
- *
- * @param address - Address to test (any format accepted by `AddressLike`).
+ * @param address - `pq1…` address to test.
  * @returns `true` if the address matches AccountManager or ValidatorRegistry.
  *
  * @example
  * ```typescript
- * isSystemContractAddress("0x0000000000000000000000000000000000000002"); // true
- * isSystemContractAddress(accountManagerAddress);                        // true
- * isSystemContractAddress("pq1someuser…");                               // false
+ * isSystemContractAddress(accountManagerAddress);  // true
+ * isSystemContractAddress("pq1someuser…");         // false
  * ```
  */
 export declare function isSystemContractAddress(address: AddressLike): boolean;
@@ -78,7 +70,7 @@ export declare function isSystemContractAddress(address: AddressLike): boolean;
  * account owner can call this (the call must be made as an inner call from
  * the owner's AA bundle, or as a direct transaction).
  *
- * @param guardians - Array of guardian addresses (1..5). May be hex or `pq1…` form.
+ * @param guardians - Array of guardian addresses (1..5). Must be `pq1…` bech32m form.
  * @param threshold - k-of-n required votes (1 ≤ threshold ≤ guardians.length).
  * @param timelock - Minimum blocks between threshold-reach and execution (≥ 100).
  * @returns `HexString` with the 4-byte selector prepended.
@@ -86,7 +78,7 @@ export declare function isSystemContractAddress(address: AddressLike): boolean;
  * @example
  * ```typescript
  * const data = encodeSetGuardiansCalldata(
- *   ["0xGuardian1…", "0xGuardian2…", "0xGuardian3…"],
+ *   ["pq1guardian1…", "pq1guardian2…", "pq1guardian3…"],
  *   2,   // 2-of-3 threshold
  *   100, // 100-block timelock
  * );
@@ -100,7 +92,7 @@ export declare function encodeSetGuardiansCalldata(guardians: AddressLike[], thr
  * When k-of-n threshold is reached, the proposal becomes executable after
  * `timelock` blocks.
  *
- * @param account - Account being recovered (0x hex or `pq1…` form).
+ * @param account - Account being recovered (`pq1…` bech32m form).
  * @param newPubkey - Raw bytes of the new PQ public key.
  * @param newAlgo - Algorithm ID for the new key (ML-DSA-65 = 0, etc.).
  * @returns `HexString` with the 4-byte selector prepended.
@@ -108,7 +100,7 @@ export declare function encodeSetGuardiansCalldata(guardians: AddressLike[], thr
  * @example
  * ```typescript
  * const data = encodeSubmitRecoveryCalldata(
- *   "0xAccountAddress…",
+ *   "pq1accountaddress…",
  *   newPubkeyBytes,
  *   0, // ML-DSA-65
  * );

package/dist/system-contracts.js

@@ -18,7 +18,7 @@
  * @module system-contracts
  */
 import { bytesToHex, encodeAbiParameters, keccak256, toBytes } from "viem";
-import { bytesToPqAddress } from "./address.js";
+import { bytesToPqAddress, pqAddressToBytes } from "./address.js";
 const SYSTEM_ADDRESS_LENGTH = 20;
 function systemAddress(lastByte) {
     const bytes = new Uint8Array(SYSTEM_ADDRESS_LENGTH);
@@ -28,10 +28,6 @@ function systemAddress(lastByte) {
 function selector(signature) {
     return keccak256(toBytes(signature)).slice(0, 10);
 }
-/** Hex address of the ValidatorRegistry system contract (`0x…0001`). */
-export const validatorRegistryHexAddress = "0x0000000000000000000000000000000000000001";
-/** Hex address of the AccountManager system contract (`0x…0002`). */
-export const accountManagerHexAddress = "0x0000000000000000000000000000000000000002";
 /** `pq1…` bech32m address of the ValidatorRegistry system contract. */
 export const validatorRegistryAddress = bytesToPqAddress(systemAddress(1));
 /** `pq1…` bech32m address of the AccountManager system contract. */
@@ -100,24 +96,17 @@ export function encodeClearValidationCodeCalldata() {
 /**
  * Return `true` if `address` refers to one of the Shell system contracts.
  *
- * Accepts both `pq1…` and `0x…` forms for the AccountManager and
- * ValidatorRegistry addresses.
- *
- * @param address - Address to test (any format accepted by `AddressLike`).
+ * @param address - `pq1…` address to test.
  * @returns `true` if the address matches AccountManager or ValidatorRegistry.
  *
  * @example
  * ```typescript
- * isSystemContractAddress("0x0000000000000000000000000000000000000002"); // true
- * isSystemContractAddress(accountManagerAddress);                        // true
- * isSystemContractAddress("pq1someuser…");                               // false
+ * isSystemContractAddress(accountManagerAddress);  // true
+ * isSystemContractAddress("pq1someuser…");         // false
  * ```
  */
 export function isSystemContractAddress(address) {
-    return (address === accountManagerAddress ||
-        address === validatorRegistryAddress ||
-        address === accountManagerHexAddress ||
-        address === validatorRegistryHexAddress);
+    return address === accountManagerAddress || address === validatorRegistryAddress;
 }
 // ---------------------------------------------------------------------------
 // AA Phase 2 — Guardian Recovery calldata encoders (v0.19.0-dev)
@@ -129,7 +118,7 @@ export function isSystemContractAddress(address) {
  * account owner can call this (the call must be made as an inner call from
  * the owner's AA bundle, or as a direct transaction).
  *
- * @param guardians - Array of guardian addresses (1..5). May be hex or `pq1…` form.
+ * @param guardians - Array of guardian addresses (1..5). Must be `pq1…` bech32m form.
  * @param threshold - k-of-n required votes (1 ≤ threshold ≤ guardians.length).
  * @param timelock - Minimum blocks between threshold-reach and execution (≥ 100).
  * @returns `HexString` with the 4-byte selector prepended.
@@ -137,18 +126,15 @@ export function isSystemContractAddress(address) {
  * @example
  * ```typescript
  * const data = encodeSetGuardiansCalldata(
- *   ["0xGuardian1…", "0xGuardian2…", "0xGuardian3…"],
+ *   ["pq1guardian1…", "pq1guardian2…", "pq1guardian3…"],
  *   2,   // 2-of-3 threshold
  *   100, // 100-block timelock
  * );
  * ```
  */
 export function encodeSetGuardiansCalldata(guardians, threshold, timelock) {
-    // Normalise to 0x… form; encodeAbiParameters expects `0x${string}` addresses.
-    const hexGuardians = guardians.map((g) => {
-        const s = typeof g === "string" ? g : bytesToHex(g);
-        return (s.startsWith("0x") ? s : `0x${s}`);
-    });
+    // Decode pq1… addresses to raw 20 bytes, then to 0x-hex for ABI encoding.
+    const hexGuardians = guardians.map((g) => bytesToHex(pqAddressToBytes(g)));
     const encoded = encodeAbiParameters([{ type: "address[]" }, { type: "uint8" }, { type: "uint64" }], [hexGuardians, threshold, BigInt(timelock)]);
     return `${setGuardiansSelector}${encoded.slice(2)}`;
 }
@@ -159,7 +145,7 @@ export function encodeSetGuardiansCalldata(guardians, threshold, timelock) {
  * When k-of-n threshold is reached, the proposal becomes executable after
  * `timelock` blocks.
  *
- * @param account - Account being recovered (0x hex or `pq1…` form).
+ * @param account - Account being recovered (`pq1…` bech32m form).
  * @param newPubkey - Raw bytes of the new PQ public key.
  * @param newAlgo - Algorithm ID for the new key (ML-DSA-65 = 0, etc.).
  * @returns `HexString` with the 4-byte selector prepended.
@@ -167,7 +153,7 @@ export function encodeSetGuardiansCalldata(guardians, threshold, timelock) {
  * @example
  * ```typescript
  * const data = encodeSubmitRecoveryCalldata(
- *   "0xAccountAddress…",
+ *   "pq1accountaddress…",
  *   newPubkeyBytes,
  *   0, // ML-DSA-65
  * );
@@ -209,9 +195,7 @@ export function encodeCancelRecoveryCalldata(account) {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
+/** Convert a pq1… address to a 0x-hex form for EVM ABI encoding. */
 function normaliseToHex(address) {
-    if (typeof address !== "string") {
-        return bytesToHex(address);
-    }
-    return (address.startsWith("0x") ? address : `0x${address}`);
+    return bytesToHex(pqAddressToBytes(address));
 }

package/dist/transactions.js

@@ -11,7 +11,7 @@ import { bytesToHex, keccak256, toRlp, hexToBytes } from "viem";
 import { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS } from "./types.js";
 export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS };
 import { accountManagerAddress, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, } from "./system-contracts.js";
-import { normalizeHexAddress } from "./address.js";
+import { pqAddressToBytes } from "./address.js";
 /** Default transaction type: `2` (EIP-1559). */
 export const DEFAULT_TX_TYPE = 2;
 /** Default gas limit for simple SHELL token transfers (`21_000`). */
@@ -40,7 +40,7 @@ function toRlpAccessList(accessList) {
         return [];
     }
     return accessList.map((item) => [
-        normalizeHexAddress(item.address),
+        bytesToHex(pqAddressToBytes(item.address)),
         item.storage_keys.map((key) => key),
     ]);
 }
@@ -249,7 +249,7 @@ export function hashTransaction(tx) {
     const fields = [
         toRlpUint(tx.chain_id),
         toRlpUint(tx.nonce),
-        tx.to ? normalizeHexAddress(tx.to) : "0x",
+        tx.to ? bytesToHex(pqAddressToBytes(tx.to)) : "0x",
         toRlpUint(tx.value),
         tx.data,
         toRlpUint(tx.gas_limit),
@@ -368,14 +368,14 @@ export function hashBatchTransaction(tx, bundle) {
     }
     // Encode inner calls for signing (matches chain's encode_for_signing).
     const innerCallsRlp = bundle.inner_calls.map((call) => [
-        call.to ? normalizeHexAddress(call.to) : "0x",
+        call.to ? bytesToHex(pqAddressToBytes(call.to)) : "0x",
         toRlpUint(call.value),
         call.data,
         toRlpUint(call.gas_limit),
     ]);
     // Paymaster: 20-byte address or empty bytes.
     const paymasterField = bundle.paymaster
-        ? normalizeHexAddress(bundle.paymaster)
+        ? bytesToHex(pqAddressToBytes(bundle.paymaster))
         : "0x";
     // paymaster_context: raw bytes or empty.
     const paymasterContextField = bundle.paymaster_context && bundle.paymaster_context.length > 0
@@ -384,7 +384,7 @@ export function hashBatchTransaction(tx, bundle) {
     const txFields = [
         toRlpUint(tx.chain_id),
         toRlpUint(tx.nonce),
-        tx.to ? normalizeHexAddress(tx.to) : "0x",
+        tx.to ? bytesToHex(pqAddressToBytes(tx.to)) : "0x",
         toRlpUint(tx.value),
         tx.data,
         toRlpUint(tx.gas_limit),

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /** A `0x`-prefixed hex string, e.g. `"0xdeadbeef"`. */
 export type HexString = `0x${string}`;
-/** Any string accepted as an address — either a `pq1…` bech32m address or a `0x…` hex address. */
+/** A `pq1…` bech32m address string (Shell Chain canonical address format). */
 export type AddressLike = string;
 /** A single entry in an EIP-2930 access list. */
 export interface ShellAccessListItem {
@@ -18,7 +18,7 @@ export interface ShellTransactionRequest {
     chain_id: number;
     /** Sender account nonce. */
     nonce: number;
-    /** Recipient address (pq1… or 0x…), or `null` for contract deployment. */
+    /** Recipient address (`pq1…` bech32m format), or `null` for contract deployment. */
     to: AddressLike | null;
     /** Transfer value as a hex-encoded bigint string, e.g. `"0xde0b6b3a7640000"`. */
     value: string;
@@ -237,6 +237,83 @@ export interface SignedShellTransaction {
      */
     aa_bundle?: AaBundle | null;
 }
+/** Product-level transaction kind emitted by Shell Chain RPC. */
+export type ShellKnownRpcTxType = "transfer" | "contractCreate" | "contractCall" | "aaBatch" | "blockGasReward" | "starkReward";
+export type ShellRpcTxType = ShellKnownRpcTxType | (string & {});
+/** Reward kind emitted for first-class system reward transactions. */
+export type ShellRewardKind = "blockGasReward" | "starkReward";
+/** Human-readable transaction label for wallets, explorers, and apps. */
+export type ShellReadableTxType = "Transfer" | "Contract Create" | "Contract Call" | "AA Batch" | "Block Reward" | "STARK Reward" | "System" | "Transaction";
+/** Shell Chain `eth_getTransactionByHash` transaction shape. */
+export interface ShellRpcTransaction {
+    hash: HexString;
+    blockHash?: HexString | null;
+    blockNumber?: HexString | null;
+    transactionIndex?: HexString | null;
+    from: AddressLike;
+    to?: AddressLike | null;
+    value: HexString;
+    gas: HexString;
+    gasPrice: HexString;
+    maxFeePerGas?: HexString;
+    maxPriorityFeePerGas?: HexString;
+    nonce: HexString;
+    input: HexString;
+    chainId: HexString;
+    type: HexString;
+    shellType?: ShellRpcTxType | null;
+    rewardKind?: ShellRewardKind | null;
+    rewardLayer?: HexString | null;
+    rewardSourceHash?: HexString | null;
+    originalSize?: HexString | null;
+    compressedSize?: HexString | null;
+}
+/** Shell Chain transaction summary returned in block/address transaction lists. */
+export interface ShellRpcTransactionSummary {
+    hash: HexString;
+    blockHash?: HexString | null;
+    blockNumber?: HexString | null;
+    transactionIndex?: HexString | null;
+    from?: AddressLike;
+    to?: AddressLike | null;
+    value?: HexString;
+    type?: HexString;
+    hasInput?: boolean;
+    shellType?: ShellRpcTxType | null;
+    rewardKind?: ShellRewardKind | null;
+    rewardLayer?: HexString | null;
+    rewardSourceHash?: HexString | null;
+    originalSize?: HexString | null;
+    compressedSize?: HexString | null;
+}
+/** Shell Chain transaction receipt shape, including system reward metadata. */
+export interface ShellRpcReceipt {
+    transactionHash: HexString;
+    blockHash: HexString;
+    blockNumber: HexString;
+    transactionIndex: HexString;
+    from: AddressLike;
+    to?: AddressLike | null;
+    status: HexString;
+    gasUsed: HexString;
+    cumulativeGasUsed: HexString;
+    effectiveGasPrice: HexString;
+    contractAddress?: AddressLike | null;
+    logs: unknown[];
+    logsBloom: HexString;
+    type: HexString;
+    shellType?: ShellRpcTxType | null;
+    rewardKind?: ShellRewardKind | null;
+}
+/** Return a user-facing transaction type label without leaking EIP wire labels. */
+export declare function formatShellRpcTxType(tx: {
+    type?: string | null;
+    to?: AddressLike | null;
+    hasInput?: boolean;
+    input?: string | null;
+    shellType?: ShellRpcTxType | null;
+    rewardKind?: ShellRewardKind | null;
+}): ShellReadableTxType;
 /**
  * A single inner call entry in a `shell_estimateBatch` request.
  */
@@ -399,10 +476,18 @@ export interface ShellWitnessBundle {
 /** Paginated response from `shell_getTransactionsByAddress`. */
 export interface ShellTxByAddressPage {
     address: AddressLike;
+    /** Inclusive lower block bound used for the query, hex-encoded. */
+    from_block?: HexString;
+    /** Inclusive upper block snapshot used for the query, hex-encoded. */
+    to_block?: HexString;
+    /** Inclusive lower block bound used for the query, hex-encoded. */
+    fromBlock?: HexString;
+    /** Inclusive upper block snapshot used for the query, hex-encoded. */
+    toBlock?: HexString;
     page: number;
     limit: number;
     total: number;
-    transactions: unknown[];
+    transactions: ShellRpcTransactionSummary[];
 }
 /** Parameters for `shell_sendTransaction`. */
 export interface ShellSendTransactionParams {

package/dist/types.js

@@ -23,3 +23,36 @@ export const AA_MAX_PAYMASTER_CONTEXT = 256;
  * Added to intrinsic gas when a session key is used.
  */
 export const AA_SESSION_KEY_GAS_SURCHARGE = 20_000;
+/** Return a user-facing transaction type label without leaking EIP wire labels. */
+export function formatShellRpcTxType(tx) {
+    const shellType = tx.shellType ?? tx.rewardKind;
+    if (shellType === "blockGasReward")
+        return "Block Reward";
+    if (shellType === "starkReward")
+        return "STARK Reward";
+    if (shellType === "aaBatch")
+        return "AA Batch";
+    if (shellType === "contractCreate")
+        return "Contract Create";
+    if (shellType === "contractCall")
+        return "Contract Call";
+    if (shellType === "transfer")
+        return "Transfer";
+    if (shellType)
+        return "System";
+    if (tx.type === "0x7e")
+        return "AA Batch";
+    if (tx.to === null)
+        return "Contract Create";
+    if (tx.hasInput || (tx.input && tx.input !== "0x"))
+        return "Contract Call";
+    if (tx.type === "0x80")
+        return "System";
+    if (tx.type == null &&
+        tx.to === undefined &&
+        tx.hasInput === undefined &&
+        tx.input === undefined) {
+        return "Transaction";
+    }
+    return "Transfer";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shell-sdk",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "TypeScript SDK for Shell Chain — build quantum-safe dApps before Q-Day.",
   "license": "MIT",
   "type": "module",