shell-sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [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/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,6 +1,6 @@
-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";

package/dist/index.js

@@ -1,6 +1,6 @@
-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";

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

@@ -113,7 +113,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>;
@@ -279,7 +279,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) {
@@ -294,7 +294,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;

package/package.json

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