shell-sdk 0.1.0

package/dist/adapters.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Concrete SignerAdapter implementations for each PQ algorithm.
+ *
+ * @noble/post-quantum provides ML-DSA-65 and SLH-DSA-SHA2-256f.
+ * Dilithium3 (pre-FIPS Round-3) uses {@link MlDsa65Adapter} as a stand-in.
+ *
+ * @module adapters
+ */
+import type { SignerAdapter } from "./signer.js";
+import type { SignatureTypeName } from "./types.js";
+/** Key pair produced by {@link generateMlDsa65KeyPair}. */
+export interface MlDsa65KeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/** Key pair produced by {@link generateSlhDsaKeyPair}. */
+export interface SlhDsaKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/**
+ * Generate a fresh ML-DSA-65 key pair.
+ *
+ * @param seed - Optional 32-byte deterministic seed. A random seed is used when omitted.
+ * @returns `{ publicKey, secretKey }` — public key is 1952 bytes, secret key is 4032 bytes.
+ *
+ * @example
+ * ```typescript
+ * const { publicKey, secretKey } = generateMlDsa65KeyPair();
+ * ```
+ */
+export declare function generateMlDsa65KeyPair(seed?: Uint8Array): MlDsa65KeyPair;
+/**
+ * Generate a fresh SLH-DSA-SHA2-256f key pair.
+ *
+ * @param seed - Optional 96-byte deterministic seed. A random seed is used when omitted.
+ * @returns `{ publicKey, secretKey }` — public key is 64 bytes, secret key is 128 bytes.
+ *
+ * @example
+ * ```typescript
+ * const { publicKey, secretKey } = generateSlhDsaKeyPair();
+ * ```
+ */
+export declare function generateSlhDsaKeyPair(seed?: Uint8Array): SlhDsaKeyPair;
+/**
+ * {@link SignerAdapter} for ML-DSA-65 (NIST FIPS 204).
+ *
+ * Also used as the implementation for `"Dilithium3"` (the pre-standardisation
+ * Round-3 variant) since the wire format is compatible.
+ *
+ * @example
+ * ```typescript
+ * // Generate a fresh key pair
+ * const adapter = MlDsa65Adapter.generate();
+ *
+ * // Load an existing key pair (e.g. from a keystore)
+ * const adapter = MlDsa65Adapter.fromKeyPair(publicKey, secretKey);
+ * ```
+ */
+export declare class MlDsa65Adapter implements SignerAdapter {
+    private readonly _publicKey;
+    private readonly _secretKey;
+    constructor(_publicKey: Uint8Array, _secretKey: Uint8Array);
+    /**
+     * Generate a fresh ML-DSA-65 key pair and wrap it in an adapter.
+     *
+     * @param seed - Optional 32-byte deterministic seed.
+     */
+    static generate(seed?: Uint8Array): MlDsa65Adapter;
+    /**
+     * Wrap an existing ML-DSA-65 key pair in an adapter.
+     *
+     * @param pk - Raw public key bytes (1952 bytes).
+     * @param sk - Raw secret key bytes (4032 bytes).
+     */
+    static fromKeyPair(pk: Uint8Array, sk: Uint8Array): MlDsa65Adapter;
+    /** Return the raw ML-DSA-65 public key bytes (1952 bytes). */
+    getPublicKey(): Uint8Array;
+    /**
+     * Sign `message` with ML-DSA-65 and return the raw signature bytes.
+     *
+     * @param message - The bytes to sign (typically an RLP-encoded tx hash).
+     */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * {@link SignerAdapter} for SLH-DSA-SHA2-256f (NIST FIPS 205).
+ *
+ * Corresponds to the `"SphincsSha2256f"` signature type. Produces much larger
+ * signatures (~49 KB) than ML-DSA-65 but offers stronger security assumptions.
+ *
+ * @example
+ * ```typescript
+ * const adapter = SlhDsaAdapter.generate();
+ * const adapter = SlhDsaAdapter.fromKeyPair(publicKey, secretKey);
+ * ```
+ */
+export declare class SlhDsaAdapter implements SignerAdapter {
+    private readonly _publicKey;
+    private readonly _secretKey;
+    constructor(_publicKey: Uint8Array, _secretKey: Uint8Array);
+    /**
+     * Generate a fresh SLH-DSA-SHA2-256f key pair and wrap it in an adapter.
+     *
+     * @param seed - Optional 96-byte deterministic seed.
+     */
+    static generate(seed?: Uint8Array): SlhDsaAdapter;
+    /**
+     * Wrap an existing SLH-DSA-SHA2-256f key pair in an adapter.
+     *
+     * @param pk - Raw public key bytes (64 bytes).
+     * @param sk - Raw secret key bytes (128 bytes).
+     */
+    static fromKeyPair(pk: Uint8Array, sk: Uint8Array): SlhDsaAdapter;
+    /** Return the raw SLH-DSA public key bytes (64 bytes). */
+    getPublicKey(): Uint8Array;
+    /**
+     * Sign `message` with SLH-DSA-SHA2-256f and return the raw signature bytes.
+     *
+     * @param message - The bytes to sign (typically an RLP-encoded tx hash).
+     */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Generate a fresh {@link SignerAdapter} for the given algorithm.
+ *
+ * A convenience factory that dispatches to the correct adapter class.
+ *
+ * @param algorithm - The PQ algorithm to use.
+ * @param seed - Optional deterministic seed (32 bytes for ML-DSA-65, 96 bytes for SLH-DSA).
+ * @returns A ready-to-use `SignerAdapter`.
+ * @throws {Error} If `algorithm` is not one of the supported values.
+ *
+ * @example
+ * ```typescript
+ * const adapter = generateAdapter("MlDsa65");
+ * const adapter = generateAdapter("SphincsSha2256f", mySeed);
+ * ```
+ */
+export declare function generateAdapter(algorithm: SignatureTypeName, seed?: Uint8Array): SignerAdapter;
+/**
+ * Build a {@link SignerAdapter} from an existing key pair (e.g. loaded from a keystore).
+ *
+ * @param algorithm - The PQ algorithm.
+ * @param publicKey - Raw public key bytes.
+ * @param secretKey - Raw secret key bytes.
+ * @returns A `SignerAdapter` backed by the provided key pair.
+ * @throws {Error} If `algorithm` is not one of the supported values.
+ *
+ * @example
+ * ```typescript
+ * const adapter = adapterFromKeyPair("MlDsa65", publicKey, secretKey);
+ * ```
+ */
+export declare function adapterFromKeyPair(algorithm: SignatureTypeName, publicKey: Uint8Array, secretKey: Uint8Array): SignerAdapter;

package/dist/adapters.js

@@ -0,0 +1,191 @@
+/**
+ * Concrete SignerAdapter implementations for each PQ algorithm.
+ *
+ * @noble/post-quantum provides ML-DSA-65 and SLH-DSA-SHA2-256f.
+ * Dilithium3 (pre-FIPS Round-3) uses {@link MlDsa65Adapter} as a stand-in.
+ *
+ * @module adapters
+ */
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { slh_dsa_sha2_256f } from "@noble/post-quantum/slh-dsa.js";
+/**
+ * Generate a fresh ML-DSA-65 key pair.
+ *
+ * @param seed - Optional 32-byte deterministic seed. A random seed is used when omitted.
+ * @returns `{ publicKey, secretKey }` — public key is 1952 bytes, secret key is 4032 bytes.
+ *
+ * @example
+ * ```typescript
+ * const { publicKey, secretKey } = generateMlDsa65KeyPair();
+ * ```
+ */
+export function generateMlDsa65KeyPair(seed) {
+    const s = seed ?? crypto.getRandomValues(new Uint8Array(32));
+    return ml_dsa65.keygen(s);
+}
+/**
+ * Generate a fresh SLH-DSA-SHA2-256f key pair.
+ *
+ * @param seed - Optional 96-byte deterministic seed. A random seed is used when omitted.
+ * @returns `{ publicKey, secretKey }` — public key is 64 bytes, secret key is 128 bytes.
+ *
+ * @example
+ * ```typescript
+ * const { publicKey, secretKey } = generateSlhDsaKeyPair();
+ * ```
+ */
+export function generateSlhDsaKeyPair(seed) {
+    const s = seed ?? crypto.getRandomValues(new Uint8Array(96));
+    return slh_dsa_sha2_256f.keygen(s);
+}
+/**
+ * {@link SignerAdapter} for ML-DSA-65 (NIST FIPS 204).
+ *
+ * Also used as the implementation for `"Dilithium3"` (the pre-standardisation
+ * Round-3 variant) since the wire format is compatible.
+ *
+ * @example
+ * ```typescript
+ * // Generate a fresh key pair
+ * const adapter = MlDsa65Adapter.generate();
+ *
+ * // Load an existing key pair (e.g. from a keystore)
+ * const adapter = MlDsa65Adapter.fromKeyPair(publicKey, secretKey);
+ * ```
+ */
+export class MlDsa65Adapter {
+    _publicKey;
+    _secretKey;
+    constructor(_publicKey, _secretKey) {
+        this._publicKey = _publicKey;
+        this._secretKey = _secretKey;
+    }
+    /**
+     * Generate a fresh ML-DSA-65 key pair and wrap it in an adapter.
+     *
+     * @param seed - Optional 32-byte deterministic seed.
+     */
+    static generate(seed) {
+        const kp = generateMlDsa65KeyPair(seed);
+        return new MlDsa65Adapter(kp.publicKey, kp.secretKey);
+    }
+    /**
+     * Wrap an existing ML-DSA-65 key pair in an adapter.
+     *
+     * @param pk - Raw public key bytes (1952 bytes).
+     * @param sk - Raw secret key bytes (4032 bytes).
+     */
+    static fromKeyPair(pk, sk) {
+        return new MlDsa65Adapter(pk, sk);
+    }
+    /** Return the raw ML-DSA-65 public key bytes (1952 bytes). */
+    getPublicKey() { return this._publicKey; }
+    /**
+     * Sign `message` with ML-DSA-65 and return the raw signature bytes.
+     *
+     * @param message - The bytes to sign (typically an RLP-encoded tx hash).
+     */
+    async sign(message) {
+        return ml_dsa65.sign(this._secretKey, message);
+    }
+}
+/**
+ * {@link SignerAdapter} for SLH-DSA-SHA2-256f (NIST FIPS 205).
+ *
+ * Corresponds to the `"SphincsSha2256f"` signature type. Produces much larger
+ * signatures (~49 KB) than ML-DSA-65 but offers stronger security assumptions.
+ *
+ * @example
+ * ```typescript
+ * const adapter = SlhDsaAdapter.generate();
+ * const adapter = SlhDsaAdapter.fromKeyPair(publicKey, secretKey);
+ * ```
+ */
+export class SlhDsaAdapter {
+    _publicKey;
+    _secretKey;
+    constructor(_publicKey, _secretKey) {
+        this._publicKey = _publicKey;
+        this._secretKey = _secretKey;
+    }
+    /**
+     * Generate a fresh SLH-DSA-SHA2-256f key pair and wrap it in an adapter.
+     *
+     * @param seed - Optional 96-byte deterministic seed.
+     */
+    static generate(seed) {
+        const kp = generateSlhDsaKeyPair(seed);
+        return new SlhDsaAdapter(kp.publicKey, kp.secretKey);
+    }
+    /**
+     * Wrap an existing SLH-DSA-SHA2-256f key pair in an adapter.
+     *
+     * @param pk - Raw public key bytes (64 bytes).
+     * @param sk - Raw secret key bytes (128 bytes).
+     */
+    static fromKeyPair(pk, sk) {
+        return new SlhDsaAdapter(pk, sk);
+    }
+    /** Return the raw SLH-DSA public key bytes (64 bytes). */
+    getPublicKey() { return this._publicKey; }
+    /**
+     * Sign `message` with SLH-DSA-SHA2-256f and return the raw signature bytes.
+     *
+     * @param message - The bytes to sign (typically an RLP-encoded tx hash).
+     */
+    async sign(message) {
+        return slh_dsa_sha2_256f.sign(this._secretKey, message);
+    }
+}
+/**
+ * Generate a fresh {@link SignerAdapter} for the given algorithm.
+ *
+ * A convenience factory that dispatches to the correct adapter class.
+ *
+ * @param algorithm - The PQ algorithm to use.
+ * @param seed - Optional deterministic seed (32 bytes for ML-DSA-65, 96 bytes for SLH-DSA).
+ * @returns A ready-to-use `SignerAdapter`.
+ * @throws {Error} If `algorithm` is not one of the supported values.
+ *
+ * @example
+ * ```typescript
+ * const adapter = generateAdapter("MlDsa65");
+ * const adapter = generateAdapter("SphincsSha2256f", mySeed);
+ * ```
+ */
+export function generateAdapter(algorithm, seed) {
+    switch (algorithm) {
+        case "Dilithium3":
+        case "MlDsa65":
+            return MlDsa65Adapter.generate(seed);
+        case "SphincsSha2256f":
+            return SlhDsaAdapter.generate(seed ? seed.slice(0, 96) : undefined);
+        default:
+            throw new Error("unsupported algorithm: " + algorithm);
+    }
+}
+/**
+ * Build a {@link SignerAdapter} from an existing key pair (e.g. loaded from a keystore).
+ *
+ * @param algorithm - The PQ algorithm.
+ * @param publicKey - Raw public key bytes.
+ * @param secretKey - Raw secret key bytes.
+ * @returns A `SignerAdapter` backed by the provided key pair.
+ * @throws {Error} If `algorithm` is not one of the supported values.
+ *
+ * @example
+ * ```typescript
+ * const adapter = adapterFromKeyPair("MlDsa65", publicKey, secretKey);
+ * ```
+ */
+export function adapterFromKeyPair(algorithm, publicKey, secretKey) {
+    switch (algorithm) {
+        case "Dilithium3":
+        case "MlDsa65":
+            return MlDsa65Adapter.fromKeyPair(publicKey, secretKey);
+        case "SphincsSha2256f":
+            return SlhDsaAdapter.fromKeyPair(publicKey, secretKey);
+        default:
+            throw new Error("unsupported algorithm: " + algorithm);
+    }
+}

package/dist/address.d.ts

@@ -0,0 +1,119 @@
+/** Human-readable part (HRP) used in Shell bech32m addresses. */
+export declare const PQ_ADDRESS_HRP = "pq";
+/** Number of raw address bytes (excluding the version byte). */
+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.
+ *
+ * @param bytes - Exactly 20 address bytes (the 20-byte hash derived from a public key).
+ * @param version - Address version byte; defaults to {@link PQ_ADDRESS_VERSION_V1} (`0x01`).
+ * @returns The bech32m-encoded address string, e.g. `"pq1qx3f…"`.
+ * @throws {Error} If `bytes.length !== 20` or `version` is out of the 0–255 range.
+ *
+ * @example
+ * ```typescript
+ * const addr = bytesToPqAddress(hashBytes);
+ * // → "pq1qx3f…"
+ * ```
+ */
+export declare function bytesToPqAddress(bytes: Uint8Array, version?: number): string;
+/**
+ * Decode a `pq1…` bech32m address to its raw 20 address bytes.
+ *
+ * The version byte is stripped; use {@link pqAddressVersion} to retrieve it.
+ *
+ * @param address - A valid `pq1…` bech32m address.
+ * @returns The 20-byte address payload (version byte excluded).
+ * @throws {Error} If the prefix is not `"pq"` or the payload length is wrong.
+ *
+ * @example
+ * ```typescript
+ * const bytes = pqAddressToBytes("pq1qx3f…");
+ * // bytes.length === 20
+ * ```
+ */
+export declare function pqAddressToBytes(address: string): Uint8Array;
+/**
+ * Extract the version byte from a `pq1…` bech32m address.
+ *
+ * @param address - A valid `pq1…` bech32m address.
+ * @returns The version byte (e.g. `1` for V1 addresses).
+ * @throws {Error} If the address is malformed.
+ */
+export declare function pqAddressVersion(address: string): number;
+/**
+ * Parse a `0x…` hex address string into its raw 20 bytes.
+ *
+ * @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.
+ *
+ * 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.
+ */
+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.
+ *
+ * The derivation is:
+ * ```
+ * address_bytes = blake3(version || algo_id || public_key)[0..20]
+ * ```
+ *
+ * @param publicKey - Raw public key bytes (length depends on algorithm).
+ * @param algorithmId - Numeric algorithm ID: Dilithium3=0, MlDsa65=1, SphincsSha2256f=2.
+ * @param version - Address version byte; defaults to {@link PQ_ADDRESS_VERSION_V1}.
+ * @returns The derived `pq1…` bech32m address.
+ * @throws {Error} If `algorithmId` is outside 0–255.
+ *
+ * @example
+ * ```typescript
+ * const address = derivePqAddressFromPublicKey(publicKey, 1 /* MlDsa65 *\/);
+ * // → "pq1qx3f…"
+ * ```
+ */
+export declare function derivePqAddressFromPublicKey(publicKey: Uint8Array, algorithmId: number, version?: number): string;
+/**
+ * Return `true` if `address` is a structurally valid `pq1…` bech32m address.
+ *
+ * Does **not** check whether the address exists on-chain.
+ *
+ * @param address - Any string to test.
+ * @returns `true` if the string is a valid Shell bech32m address.
+ *
+ * @example
+ * ```typescript
+ * isPqAddress("pq1qx3f…"); // true
+ * isPqAddress("0xabc…");   // false
+ * isPqAddress("garbage");   // false
+ * ```
+ */
+export declare function isPqAddress(address: string): boolean;
+export {};

package/dist/address.js

@@ -0,0 +1,220 @@
+/**
+ * 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:
+ *
+ * ```
+ * address_bytes = blake3(version || algo_id || public_key)[0..20]
+ * bech32m_address = bech32m_encode("pq", [version, ...address_bytes])
+ * ```
+ *
+ * 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). */
+export const PQ_ADDRESS_LENGTH = 20;
+/** Version byte for V1 Shell addresses (`0x01`). */
+export const PQ_ADDRESS_VERSION_V1 = 0x01;
+function assertBech32Address(value) {
+    if (!value.includes("1")) {
+        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.
+ *
+ * @param bytes - Exactly 20 address bytes (the 20-byte hash derived from a public key).
+ * @param version - Address version byte; defaults to {@link PQ_ADDRESS_VERSION_V1} (`0x01`).
+ * @returns The bech32m-encoded address string, e.g. `"pq1qx3f…"`.
+ * @throws {Error} If `bytes.length !== 20` or `version` is out of the 0–255 range.
+ *
+ * @example
+ * ```typescript
+ * const addr = bytesToPqAddress(hashBytes);
+ * // → "pq1qx3f…"
+ * ```
+ */
+export function bytesToPqAddress(bytes, version = PQ_ADDRESS_VERSION_V1) {
+    if (bytes.length !== PQ_ADDRESS_LENGTH) {
+        throw new Error(`expected ${PQ_ADDRESS_LENGTH} address bytes, got ${bytes.length}`);
+    }
+    if (version < 0 || version > 255) {
+        throw new Error(`invalid address version: ${version}`);
+    }
+    const payload = new Uint8Array(1 + PQ_ADDRESS_LENGTH);
+    payload[0] = version;
+    payload.set(bytes, 1);
+    return bech32m.encode(PQ_ADDRESS_HRP, bech32m.toWords(payload));
+}
+/**
+ * Decode a `pq1…` bech32m address to its raw 20 address bytes.
+ *
+ * The version byte is stripped; use {@link pqAddressVersion} to retrieve it.
+ *
+ * @param address - A valid `pq1…` bech32m address.
+ * @returns The 20-byte address payload (version byte excluded).
+ * @throws {Error} If the prefix is not `"pq"` or the payload length is wrong.
+ *
+ * @example
+ * ```typescript
+ * const bytes = pqAddressToBytes("pq1qx3f…");
+ * // bytes.length === 20
+ * ```
+ */
+export function pqAddressToBytes(address) {
+    assertBech32Address(address);
+    const { prefix, words } = bech32m.decode(address);
+    if (prefix !== PQ_ADDRESS_HRP) {
+        throw new Error(`expected ${PQ_ADDRESS_HRP} address prefix, got ${prefix}`);
+    }
+    const bytes = Uint8Array.from(bech32m.fromWords(words));
+    if (bytes.length !== 1 + PQ_ADDRESS_LENGTH) {
+        throw new Error(`expected ${1 + PQ_ADDRESS_LENGTH} address bytes, got ${bytes.length}`);
+    }
+    return bytes.slice(1);
+}
+/**
+ * Extract the version byte from a `pq1…` bech32m address.
+ *
+ * @param address - A valid `pq1…` bech32m address.
+ * @returns The version byte (e.g. `1` for V1 addresses).
+ * @throws {Error} If the address is malformed.
+ */
+export function pqAddressVersion(address) {
+    assertBech32Address(address);
+    const { words } = bech32m.decode(address);
+    const bytes = Uint8Array.from(bech32m.fromWords(words));
+    if (bytes.length !== 1 + PQ_ADDRESS_LENGTH) {
+        throw new Error(`expected ${1 + PQ_ADDRESS_LENGTH} address bytes, got ${bytes.length}`);
+    }
+    return bytes[0];
+}
+/**
+ * Parse a `0x…` hex address string into its raw 20 bytes.
+ *
+ * @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.
+ *
+ * @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.
+ */
+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));
+    }
+    assertHexAddress(address);
+    return address;
+}
+/**
+ * Derive a `pq1…` address from a raw post-quantum public key.
+ *
+ * The derivation is:
+ * ```
+ * address_bytes = blake3(version || algo_id || public_key)[0..20]
+ * ```
+ *
+ * @param publicKey - Raw public key bytes (length depends on algorithm).
+ * @param algorithmId - Numeric algorithm ID: Dilithium3=0, MlDsa65=1, SphincsSha2256f=2.
+ * @param version - Address version byte; defaults to {@link PQ_ADDRESS_VERSION_V1}.
+ * @returns The derived `pq1…` bech32m address.
+ * @throws {Error} If `algorithmId` is outside 0–255.
+ *
+ * @example
+ * ```typescript
+ * const address = derivePqAddressFromPublicKey(publicKey, 1 /* MlDsa65 *\/);
+ * // → "pq1qx3f…"
+ * ```
+ */
+export function derivePqAddressFromPublicKey(publicKey, algorithmId, version = PQ_ADDRESS_VERSION_V1) {
+    if (algorithmId < 0 || algorithmId > 255) {
+        throw new Error(`invalid algorithm id: ${algorithmId}`);
+    }
+    const input = new Uint8Array(2 + publicKey.length);
+    input[0] = version;
+    input[1] = algorithmId;
+    input.set(publicKey, 2);
+    const hash = blake3(input);
+    return bytesToPqAddress(hash.slice(0, PQ_ADDRESS_LENGTH), version);
+}
+/**
+ * Return `true` if `address` is a structurally valid `pq1…` bech32m address.
+ *
+ * Does **not** check whether the address exists on-chain.
+ *
+ * @param address - Any string to test.
+ * @returns `true` if the string is a valid Shell bech32m address.
+ *
+ * @example
+ * ```typescript
+ * isPqAddress("pq1qx3f…"); // true
+ * isPqAddress("0xabc…");   // false
+ * isPqAddress("garbage");   // false
+ * ```
+ */
+export function isPqAddress(address) {
+    try {
+        pqAddressToBytes(address);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
+export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, type CreateShellPublicClientOptions, } from "./provider.js";
+export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
+export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, hexBytes, } 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, KEY_TYPE_TO_SIGNATURE_TYPE, publicKeyFromHex, ShellSigner, SIGNATURE_TYPE_IDS, signatureTypeFromKeyType, type SignerAdapter, } from "./signer.js";
+export type { AddressLike, HexString, ShellAccessListItem, ShellCipherParams, ShellEncryptedKey, ShellSendTransactionParams, ShellKdfParams, ShellSignature, ShellTransactionRequest, ShellTxByAddressPage, SignedShellTransaction, SignatureTypeName, } from "./types.js";